Skip to content

Commit 83db18a

Browse files
committed
✨ feat: add a scoped TempDir component
A test that needs a filesystem it can dirty had to write an eval block to get one. `<TempDir>` makes it a component, built into core: no search directory, no file to install, and it survives `deno compile`. Written with content it is a working directory. Its canonical path becomes the contextual `Env.cwd`, so nested components, code blocks, processes and agents all run there without being handed a path, and the directory is removed when the content finishes, fails, or is cancelled. Because the directory is the invocation's own resource, anything the content started stops before it goes. Written self-closing it is an allocation: it renders the path and retains the directory at the invocation site, for the siblings that follow. The path is canonical because macOS reports the temporary root as a symlink while a subprocess reports it resolved — otherwise the rendered path, the `Env.cwd` descendants observe, and a subprocess's own directory would be three spellings of one place, and no document could compare them. `mkdtemp` names and creates in one step, so the directory cannot be one an earlier run left behind. Resuming from a partial journal is refused. Every run creates a new directory while a recorded effect is matched by its description, so replaying one would return a path already removed and skip the filesystem work it stands for. An effect consumed from the journal inside the content raises `StaleInputError`, which ends the execution rather than settling under the ambient error policy — `fatalCause` gives the engine one rule for errors expansion must not convert, and looks through teardown aggregates that would otherwise launder them. Re-executing recorded effects inside a freshly established environment is #218. Registration is the smallest thing that works: a module-private map import consults, producing no `import_component` entry because there is no path and no read. Whether a repository file may shadow a built-in name stays unspecified and belongs to #202.
1 parent 0ff35ca commit 83db18a

12 files changed

Lines changed: 1036 additions & 11 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,11 @@ jobs:
7777
--component-dir packages/core/components \
7878
--raw
7979
80+
# A built-in component resolves from the module graph rather than a
81+
# search path. Only the compiled binary proves it survives `deno compile`.
82+
- name: Smoke test a built-in component with no search path
83+
run: ./dist/xmd test packages/core/src/components/TempDir.test.md --raw
84+
8085
# The guide documents this command and its output; running it keeps the
8186
# value-root contract executable rather than described.
8287
- name: Smoke test a value root's JSON result
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# TempDir
2+
3+
`<TempDir>` gives its content an isolated working directory and removes it
4+
afterwards. Everything expanded inside observes it — including the shell —
5+
so the story below is told entirely by commands reporting where they ran.
6+
7+
Outside any `<TempDir>`, a command runs where the document was invoked from,
8+
so it sees no temporary directory at all.
9+
10+
<Test name="Execution starts in the ordinary working directory">
11+
<Capture as="before">
12+
```sh exec
13+
pwd
14+
```
15+
</Capture>
16+
<AssertNotMatch actual={before} expected={/xmd-tempdir-/} />
17+
</Test>
18+
19+
Inside, the same command reports a directory belonging to that invocation,
20+
and that directory is there while the command runs.
21+
22+
<Test name="Inside TempDir a command runs in a live temporary directory">
23+
<Capture as="inside">
24+
<TempDir>
25+
```sh exec
26+
pwd
27+
test -d "$PWD" && echo LIVE
28+
```
29+
</TempDir>
30+
</Capture>
31+
<AssertMatch actual={inside} expected={/xmd-tempdir-/} />
32+
<AssertStringIncludes actual={inside} expected={"LIVE"} />
33+
</Test>
34+
35+
Once the component finishes, its directory is gone and the ordinary working
36+
directory is back. The path is carried out of the block by capturing it, then
37+
tested from outside.
38+
39+
<Test name="After TempDir the directory is gone and the old cwd is restored">
40+
<Capture as="path">
41+
<TempDir>
42+
```sh exec
43+
pwd
44+
```
45+
</TempDir>
46+
</Capture>
47+
<Capture as="after">
48+
```sh exec
49+
test -d {path} || echo REMOVED
50+
pwd
51+
```
52+
</Capture>
53+
<AssertStringIncludes actual={after} expected={"REMOVED"} />
54+
<AssertNotMatch actual={after} expected={/xmd-tempdir-/} />
55+
</Test>
56+
57+
A self-closing `<TempDir />` has no content to wrap. It renders its path and
58+
keeps the directory, so a later sibling can still use it.
59+
60+
<Test name="A captured TempDir stays live for a following sibling">
61+
<TempDir as="workspace" />
62+
<Capture as="present">
63+
```sh exec
64+
test -d {workspace} && echo PRESENT
65+
```
66+
</Capture>
67+
<AssertMatch actual={workspace} expected={/xmd-tempdir-/} />
68+
<AssertStringIncludes actual={present} expected={"PRESENT"} />
69+
</Test>
70+
71+
Without `as` the same form simply renders the path.
72+
73+
<Test name="A bare TempDir renders its path">
74+
<Capture as="rendered"><TempDir /></Capture>
75+
<AssertMatch actual={rendered} expected={/xmd-tempdir-/} />
76+
</Test>
Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
/**
2+
* `<TempDir>` — an isolated temporary directory (specs/executable-mdx-spec.md §6.11).
3+
*
4+
* Written with content it is a working directory: everything expanded inside
5+
* observes it as the contextual `Env.cwd`, and it is removed when the content
6+
* finishes, fails, or is cancelled. Written self-closing it is an allocation:
7+
* the directory is retained at the invocation site so a later sibling can use
8+
* the path it renders, and removed with that scope.
9+
*/
10+
11+
import { ensure, resource, until } from "effection";
12+
import type { Operation } from "effection";
13+
import { rm } from "@effectionx/fs";
14+
import { API } from "@executablemd/runtime";
15+
import { ReplayGuard, StaleInputError } from "@executablemd/durable-streams";
16+
import { mkdtemp, realpath } from "node:fs/promises";
17+
import { tmpdir } from "node:os";
18+
import { join } from "node:path";
19+
import { retain } from "../component-api.ts";
20+
import { hasContent, useContent } from "../content-context.ts";
21+
22+
export const props = {
23+
type: "object",
24+
properties: {},
25+
additionalProperties: false,
26+
};
27+
28+
/**
29+
* A directory this call created, named by its canonical path.
30+
*
31+
* `mkdtemp` creates and names in one step, so the directory cannot already
32+
* exist and cannot be claimed between the two — which generating a name and
33+
* then creating it does not rule out.
34+
*
35+
* The path is then canonicalized: on macOS `tmpdir()` is a symlink
36+
* (`/var/folders/…`) while a child process resolves it (`/private/var/…`).
37+
* Canonicalizing is what makes the rendered path, `Env.cwd`, and a
38+
* subprocess's own `cwd` the same string, so a document can compare them.
39+
*
40+
* `@effectionx/fs` has neither operation, so both come from Node.
41+
*/
42+
function useTemporaryDirectory(): Operation<string> {
43+
return resource(function* (provide) {
44+
const created = yield* until(mkdtemp(join(tmpdir(), "xmd-tempdir-")));
45+
yield* ensure(() => rm(created, { recursive: true, force: true }));
46+
yield* provide(yield* until(realpath(created)));
47+
});
48+
}
49+
50+
/**
51+
* Refuse to replay a recorded effect inside this directory.
52+
*
53+
* Every run creates a *new* directory, but a journaled effect is matched by
54+
* description alone. Replaying one recorded under an earlier run would hand
55+
* the document output naming a directory that no longer exists, and the
56+
* filesystem work the effect stands for would never happen in the directory
57+
* this run created. Neither is detectable downstream, so the effect is refused
58+
* where it is recognised.
59+
*
60+
* Re-executing recorded effects inside a freshly established environment is a
61+
* durability design of its own (#218); until then a document that resumes from
62+
* a partial journal stops here rather than continuing on stale results.
63+
*/
64+
function refuseReplayInside(directory: string): Operation<void> {
65+
return ReplayGuard.around({
66+
decide([event], _next) {
67+
return {
68+
outcome: "error",
69+
// A StaleInputError, so expansion propagates it instead of rendering
70+
// it: the ambient error policy must not be able to downgrade a
71+
// durability failure to a comment and let later siblings run.
72+
error: new StaleInputError(
73+
`<TempDir> cannot replay the recorded ${event.description.type} effect ` +
74+
`"${event.description.name}": this run created ${directory}, and the recorded ` +
75+
"result belongs to a directory an earlier run created and removed. Re-run the " +
76+
"document from the start rather than resuming from a partial journal.",
77+
{ coroutineId: event.coroutineId, description: event.description },
78+
),
79+
};
80+
},
81+
});
82+
}
83+
84+
export default function* (): Operation<string> {
85+
if (yield* hasContent()) {
86+
const directory = yield* useTemporaryDirectory();
87+
yield* API.Env.around(
88+
{
89+
// deno-lint-ignore require-yield
90+
*cwd() {
91+
return directory;
92+
},
93+
},
94+
{ at: "min" },
95+
);
96+
yield* refuseReplayInside(directory);
97+
return yield* useContent();
98+
}
99+
return yield* retain(useTemporaryDirectory);
100+
}
Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/**
2+
* Components core owns (specs/executable-mdx-spec.md §5.3).
3+
*
4+
* A built-in resolves no source file: it is already in the module graph, so it
5+
* ships in the compiled binary and every published package without a search
6+
* path or a bundling step. Import consults this map and returns the definition
7+
* directly.
8+
*
9+
* Deliberately module-private — not exported from `mod.ts`. What is contracted
10+
* is only that a built-in resolves with no path and no search directory; where
11+
* this lookup sits relative to filesystem resolution is incidental and may
12+
* change. What a host may add, what happens when a repository file shares one
13+
* of these names, and how inspection reports the choice are #202's to settle.
14+
*/
15+
16+
import type { FunctionComponentDefinition } from "../types.ts";
17+
import TempDir, { props as tempDirProps } from "./TempDir.ts";
18+
import { parseJsonObject } from "../json.ts";
19+
20+
const BUILT_IN: ReadonlyMap<string, FunctionComponentDefinition> = new Map<
21+
string,
22+
FunctionComponentDefinition
23+
>([
24+
[
25+
"TempDir",
26+
{
27+
kind: "function",
28+
name: "TempDir",
29+
path: "<built-in>/TempDir",
30+
props: parseJsonObject(tempDirProps),
31+
fn: TempDir,
32+
},
33+
],
34+
]);
35+
36+
export function builtInComponent(name: string): FunctionComponentDefinition | undefined {
37+
return BUILT_IN.get(name);
38+
}

‎packages/core/src/errors.ts‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
import { createContext } from "effection";
22
import type { Context, Operation } from "effection";
3+
import { StaleInputError } from "@executablemd/durable-streams";
4+
import { InvocationTeardownError } from "./invocation.ts";
35
import type { ErrorSegment } from "./types.ts";
46

57
/**
@@ -44,3 +46,67 @@ export class DocumentationError extends Error {
4446
this.segment = segment;
4547
}
4648
}
49+
50+
/**
51+
* The error that ends the execution, if this failure carries one.
52+
*
53+
* Expansion turns a failure into a diagnostic the document can render, which
54+
* is right for anything the document itself got wrong. Two kinds are not that,
55+
* and every generic catch in the engine rethrows them:
56+
*
57+
* - `DocumentationError` — the ambient policy has already decided this
58+
* execution fails (§6.9); collecting it would undo that decision.
59+
* - `StaleInputError` — a journal entry no longer describes the world it was
60+
* recorded in (§6.11). The document is not wrong and there is nothing useful
61+
* to render: continuing would run later siblings on top of work that never
62+
* happened. Rendering it as a comment would let the ambient policy downgrade
63+
* a durability failure to a note.
64+
*
65+
* A fatal error stays fatal however it is wrapped, so this looks through the
66+
* three ways the engine and the platform aggregate failures: an
67+
* `InvocationTeardownError`'s causes (§4.4), an `AggregateError`'s members,
68+
* and an ordinary `cause`. It returns the fatal error itself rather than the
69+
* wrapper, which is the one worth reporting.
70+
*
71+
* Cause graphs are arbitrary — nothing stops `error.cause` from pointing back
72+
* at `error` — so traversal remembers what it has seen. Recursing forever would
73+
* turn an ordinary diagnostic into a stack overflow, which is exactly the
74+
* failure this function exists to prevent.
75+
*/
76+
export function fatalCause(error: unknown): DocumentationError | StaleInputError | undefined {
77+
return findFatal(error, new Set());
78+
}
79+
80+
function findFatal(
81+
error: unknown,
82+
seen: Set<unknown>,
83+
): DocumentationError | StaleInputError | undefined {
84+
if (error instanceof DocumentationError || error instanceof StaleInputError) {
85+
return error;
86+
}
87+
if (typeof error !== "object" || error === null || seen.has(error)) {
88+
return undefined;
89+
}
90+
seen.add(error);
91+
for (const cause of causesOf(error)) {
92+
const fatal = findFatal(cause, seen);
93+
if (fatal !== undefined) {
94+
return fatal;
95+
}
96+
}
97+
return undefined;
98+
}
99+
100+
/** The wrapper contracts a failure can aggregate other failures through. */
101+
function causesOf(error: object): unknown[] {
102+
if (error instanceof InvocationTeardownError) {
103+
return error.causes;
104+
}
105+
if (error instanceof AggregateError) {
106+
return error.errors;
107+
}
108+
if (error instanceof Error && error.cause !== undefined) {
109+
return [error.cause];
110+
}
111+
return [];
112+
}

‎packages/core/src/execute.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ import { evalFactory } from "./eval-handler.ts";
6060
import { persistFactory } from "./modifiers/persist.ts";
6161
import { timeoutFactory } from "./modifiers/timeout.ts";
6262
import { daemonFactory } from "./modifiers/daemon.ts";
63+
import { builtInComponent } from "./components/registry.ts";
6364
import type { EvalEnv } from "./types.ts";
6465
import { useEvalScope } from "@effectionx/scope-eval";
6566
import { Stdio } from "@effectionx/process";
@@ -86,6 +87,14 @@ function* durableImportComponent(
8687
rootDocPath: string | undefined,
8788
searchPaths: string[],
8889
): Workflow<ComponentDefinition | FunctionComponentDefinition> {
90+
// A built-in resolves no path and reads no file, so there is nothing to
91+
// journal and nothing a replay could restore differently: it is already in
92+
// the module graph and is created fresh on every execution.
93+
const builtIn = builtInComponent(name);
94+
if (builtIn) {
95+
return builtIn;
96+
}
97+
8998
const result = (yield createDurableOperation<ImportResult>(
9099
{ type: "import_component", name },
91100
function* (): Operation<ImportResult> {

‎packages/core/src/expand.ts‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ import {
4040
importComponent,
4141
raise,
4242
} from "./component-api.ts";
43-
import { AmbientErrorPolicy, DocumentationError } from "./errors.ts";
43+
import { AmbientErrorPolicy, fatalCause } from "./errors.ts";
4444
import type { ErrorPolicy } from "./errors.ts";
4545
import { withInvocation } from "./invocation.ts";
4646
import type { Invocation } from "./invocation.ts";
@@ -589,10 +589,9 @@ export function* expandSegments(
589589
}
590590
// If output is empty and exit code is 0, nothing added (e.g., silent)
591591
} catch (error) {
592-
// A DocumentationError from nested expansion (e.g. renderChildren
593-
// inside an eval block) is our own fail-fast — never swallow it.
594-
if (error instanceof DocumentationError) {
595-
throw error;
592+
const fatal = fatalCause(error);
593+
if (fatal !== undefined) {
594+
throw fatal;
596595
}
597596
result.push(
598597
yield* raise({
@@ -852,6 +851,12 @@ function* expandComponent(
852851
try {
853852
imported = yield* importComponent(name);
854853
} catch (error) {
854+
// Import is a durable effect, so it is the other place a stale journal
855+
// entry can surface.
856+
const fatal = fatalCause(error);
857+
if (fatal !== undefined) {
858+
throw fatal;
859+
}
855860
return [
856861
yield* raise({
857862
type: "error",
@@ -1068,8 +1073,9 @@ function* expandComponent(
10681073
} catch (error) {
10691074
// Body fail-fast propagates unchanged; a return-value failure is the
10701075
// component's own diagnostic and follows the caller's policy.
1071-
if (error instanceof DocumentationError) {
1072-
throw error;
1076+
const fatal = fatalCause(error);
1077+
if (fatal !== undefined) {
1078+
throw fatal;
10731079
}
10741080
return [yield* raise(schemaValidationErrorSegment(error, name))];
10751081
}
@@ -1292,10 +1298,9 @@ function* expandFunctionComponent(
12921298
}
12931299
return [{ type: "text", content: asText(output) }];
12941300
} catch (error) {
1295-
// A DocumentationError from a content-rendering path (useContent) is
1296-
// fail-fast — propagate it unchanged.
1297-
if (error instanceof DocumentationError) {
1298-
throw error;
1301+
const fatal = fatalCause(error);
1302+
if (fatal !== undefined) {
1303+
throw fatal;
12991304
}
13001305
// A return that failed its schema already names the component and carries
13011306
// its issues; wrapping it would bury both.

0 commit comments

Comments
 (0)