Skip to content

Commit d17dc69

Browse files
committed
📝 docs(spec): state the command and compiler contracts
The spec listed the new entrypoint files without saying what they promise. Both contracts are observable and neither was written down. §4.2 now states compiler ownership: execute() neither detects the runtime nor installs a compiler; a document without eval blocks needs none; one with them requires the caller to install API.Compiler middleware, and gets an explicit failure rather than a guess when it has not; a caller's compiler is used rather than shadowed. The section no longer presents the data: URI as the only mechanism, since two implementations ship and neither is bound to the runtime its name once suggested. §9.6 now states the command contract: the complete invocation with arguments appended in the position that host needs, no inferred default, an absolute entry path from import.meta.url, and resolution deferred until <TestAgent> provisions a provider. Corrects the claim that cli.ts "detects nothing about the host". It makes no decision about re-invocation, compiler choice, or runtime detection — but it still reaches process.stdout and node:fs/promises directly, which is #156. Tier CB covers the compiler boundary: no eval blocks and no compiler, an eval block with no compiler, and a caller-installed compiler surviving execute().
1 parent 8b1adc6 commit d17dc69

3 files changed

Lines changed: 147 additions & 12 deletions

File tree

‎packages/cli/src/cli.ts‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -574,9 +574,16 @@ export interface XmdOptions {
574574
}
575575

576576
/**
577-
* Run the CLI. Every host-specific decision — how this xmd is invoked and
578-
* which compiler suits the runtime — is supplied by the entrypoint that calls
579-
* this, so nothing here inspects the host.
577+
* Run the CLI.
578+
*
579+
* Three host-specific decisions are supplied by the entrypoint that calls
580+
* this: how this xmd is re-invoked, which compiler suits the runtime, and
581+
* therefore whether the runtime needs detecting at all. None of them is made
582+
* here.
583+
*
584+
* This module still reaches the host directly for terminal and journal I/O —
585+
* `process.stdout` and `node:fs/promises`. Routing those through contextual
586+
* APIs is #156.
580587
*/
581588
export function* runXmd(args: string[], options: XmdOptions): Operation<void> {
582589
const helpRequest = takeHelpFlag(args);
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
/**
2+
* Tier CB — who owns compiler installation (spec §4.2).
3+
*
4+
* `execute()` neither detects the runtime nor installs a compiler. These
5+
* assertions pin the three consequences: a document with no eval blocks needs
6+
* no compiler, one with eval blocks says so plainly when none is installed,
7+
* and a compiler the caller installed is the one that runs.
8+
*/
9+
import { describe, it } from "@effectionx/bdd/node";
10+
import { expect } from "@effectionx/bdd/expect";
11+
import type { Operation } from "effection";
12+
import { InMemoryStream } from "@executablemd/durable-streams";
13+
import { useStubFs } from "@executablemd/runtime/test";
14+
import { API } from "@executablemd/runtime";
15+
import { execute } from "../src/execute.ts";
16+
import { collect } from "../src/collect.ts";
17+
18+
function* runDoc(source: string): Operation<string> {
19+
yield* useStubFs({ "doc.md": source });
20+
return yield* collect(yield* execute({ path: "doc.md", stream: new InMemoryStream() }));
21+
}
22+
23+
describe("Tier CB — compiler boundary", () => {
24+
it("CB1: a document without eval blocks runs with no compiler installed", function* () {
25+
const output = yield* runDoc("# Plain\n\nJust prose, no fences.\n");
26+
expect(output).toContain("Just prose, no fences.");
27+
expect(output).not.toContain("ERROR");
28+
});
29+
30+
it("CB2: an eval block without compiler middleware reports that explicitly", function* () {
31+
const output = yield* runDoc(["# Doc", "", "```js eval", "env.x = 1;", "```", ""].join("\n"));
32+
expect(output).toContain("compiler not installed");
33+
expect(output).toContain("API.Compiler.around()");
34+
});
35+
36+
it("CB3: execute() uses the caller's compiler rather than shadowing it", function* () {
37+
const compiled: string[] = [];
38+
yield* API.Compiler.around({
39+
*compile([source], next) {
40+
void next; // terminal middleware — does not delegate
41+
compiled.push(source);
42+
return function* () {
43+
return undefined;
44+
};
45+
},
46+
});
47+
48+
const output = yield* runDoc(["# Doc", "", "```js eval", "env.x = 1;", "```", ""].join("\n"));
49+
expect(output).not.toContain("compiler not installed");
50+
expect(compiled).toHaveLength(1);
51+
expect(compiled[0]).toContain("env.x = 1;");
52+
});
53+
});

‎specs/executable-mdx-spec.md‎

Lines changed: 84 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -983,12 +983,40 @@ function serializeExports(
983983
}
984984
```
985985

986-
### 4.2 Module compilation via data: URI
986+
### 4.2 Module compilation
987987

988-
Eval blocks are compiled into `data:` URI TypeScript modules and
989-
dynamically imported (`compileBlock` in `src/eval-context.ts`,
990-
delegating to the platform compiler middleware). Eval blocks can use
991-
standard `import` statements, resolved through Deno's import map.
988+
Eval blocks are compiled into TypeScript modules and dynamically imported
989+
(`compileBlock` in `src/eval-context.ts`, delegating to the compiler
990+
middleware installed on `API.Compiler`). Eval blocks can use standard
991+
`import` statements, resolved through the host's module resolution.
992+
993+
#### Who installs a compiler
994+
995+
Compilation is a capability the caller provides. `execute()` neither detects
996+
the runtime nor installs a compiler, and installing one from inside its
997+
spawned task would shadow whatever the caller installed outside it.
998+
999+
- A document with **no eval blocks** never reaches `API.Compiler`, and runs
1000+
with no compiler middleware installed.
1001+
- A document **with eval blocks** requires the caller to have installed
1002+
middleware via `API.Compiler.around()`. With none installed, the default
1003+
handler fails with `compiler not installed — install platform-specific
1004+
middleware via API.Compiler.around()`. It does not guess.
1005+
- A compiler the caller installs is the one used. `execute()` does not
1006+
replace or wrap it.
1007+
1008+
The CLI satisfies this from its runtime-named entrypoints (§9.6). Two
1009+
implementations ship, and neither is locked to the runtime its name once
1010+
suggested:
1011+
1012+
| Middleware | Mechanism | Hosts |
1013+
| --- | --- | --- |
1014+
| `useDataUriCompiler()` | imports a `data:` URI; touches no disk | Deno, Bun, the compiled binary |
1015+
| `useTempFileCompiler()` | writes `.xmd-eval/<uuid>.ts` and imports `file://` | any host, and the only one Node's tsx loader accepts |
1016+
1017+
An entrypoint installs whichever its host can load. Where the two disagree —
1018+
Node's tsx loader rejects `data:` URI imports — that is a property of the
1019+
loader, not of the eval block.
9921020

9931021
#### Standard imports
9941022

@@ -1188,7 +1216,7 @@ run but are absent from the diagnostic trace.
11881216
|---|---|
11891217
| `src/eval-transform.ts` | `transformBlock()`, `serializeExports()`, `isJson()`, `TransformResult` |
11901218
| `src/component-api.ts` | `Component` Api + `ComponentApi` interface and the direct operations (`importComponent`, `applyModifiers`, `raise`, `env`, `evalScope`, `codeBlock`, `persistent`, `content`) — §5.5 |
1191-
| `src/eval-context.ts` | `compileBlock()` (data: URI) |
1219+
| `src/eval-context.ts` | `compileBlock()` — delegates to the installed `API.Compiler` middleware |
11921220
| `src/data-uri-compiler.ts` | `useDataUriCompiler()` — data: URI compiler middleware for Deno/Bun; owns `STANDARD_IMPORTS` |
11931221
| `src/temp-file-compiler.ts` | `useTempFileCompiler()` — temp-file compiler middleware for Node/Bun; owns `STANDARD_IMPORTS` |
11941222
| `src/content-context.ts` | `useContent()` — content slot access for function components |
@@ -3354,9 +3382,48 @@ export function* useTerminalOutput(): Operation<void> {
33543382

33553383
**File:** `packages/cli/src/cli.ts` (separate `cli` workspace package)
33563384

3357-
`cli.ts` detects nothing about the host. A runtime-named entrypoint
3358-
(`deno.ts`, `node.ts`, `bun.ts`, `compiled.ts`) installs the `API.Env.command`
3359-
adapter and the compiler middleware, then calls `runXmd`.
3385+
`cli.ts` makes no host-specific decision about **how this xmd is re-invoked,
3386+
which compiler to install, or which runtime it is on**. A runtime-named
3387+
entrypoint — `deno.ts`, `node.ts`, `bun.ts`, `compiled.ts` — supplies all
3388+
three and then calls `runXmd`. `cli.ts` still reaches the host directly for
3389+
terminal and journal I/O (`process.stdout`, `node:fs/promises`); routing those
3390+
through contextual APIs is separate work.
3391+
3392+
#### The xmd command (`API.Env.command`)
3393+
3394+
```typescript
3395+
command(args?: string[]): Operation<string[]>
3396+
```
3397+
3398+
Returns the **complete invocation** of the currently running xmd, with `args`
3399+
appended — something directly executable, not a prefix for the caller to
3400+
extend. `command()` with no arguments returns the base invocation.
3401+
3402+
Argument placement belongs to the adapter, because it differs per host:
3403+
3404+
| Entrypoint | `command(args)` |
3405+
| --- | --- |
3406+
| `deno.ts` | `[execPath, "run", "--allow-all", entry, ...args]` |
3407+
| `node.ts` | `[execPath, ...execArgv-minus-inspect, entry, ...args]` |
3408+
| `bun.ts` | `[execPath, entry, ...args]` |
3409+
| `compiled.ts` | `[execPath, ...args]` |
3410+
3411+
**There is no inferred default.** With no adapter installed the operation
3412+
fails with `xmd command not installed — a runtime-named entrypoint must
3413+
install it via API.Env.around()`. It cannot be derived: `process.execPath`
3414+
names the executable but not how it was launched — `deno run --allow-all
3415+
<entry>` is not recoverable from `deno` — and a compiled binary has no entry
3416+
script at all.
3417+
3418+
`entry` is absolute, taken from each entry module's own `import.meta.url`
3419+
rather than `process.argv[1]`. A relaunched worker is spawned with the
3420+
document's working directory, not the CLI's, so a relative path would not
3421+
resolve there.
3422+
3423+
**Resolution is lazy.** `command` is requested when `<TestAgent>` provisions a
3424+
provider — once per isolation boundary — and never when the components are
3425+
installed. A document that does not use `<TestAgent>` therefore runs to
3426+
completion even where no adapter has been installed at all.
33603427

33613428
The CLI installs output middleware (transforms only — no channel wiring
33623429
needed), calls `execute` to get a `DocumentExecution`, consumes
@@ -3878,6 +3945,14 @@ visible warning blocks, collect into a separate error report).
38783945
| H7 | `data:` URI encoding | Module source with special characters is correctly URI-encoded |
38793946
| H8 | User imports hoisted | User `import` declarations from eval block source appear in generated module |
38803947

3948+
### Tier CB — Compiler boundary (`compiler-boundary`)
3949+
3950+
| # | Test | Verify |
3951+
|---|------|--------|
3952+
| CB1 | No eval blocks, no compiler | A document with no eval blocks executes with no `API.Compiler` middleware installed |
3953+
| CB2 | Eval block, no compiler | An eval block with no middleware installed fails with `compiler not installed — install platform-specific middleware via API.Compiler.around()` |
3954+
| CB3 | Caller's compiler wins | A compiler installed before `execute()` receives the block source; `execute()` neither replaces nor shadows it |
3955+
38813956
### Tier I — Middleware conformance (eval modifiers)
38823957

38833958
| # | Test | Verify |

0 commit comments

Comments
 (0)