From e42fe45e2b7b3668f53e6f1996533cfd5068616a Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 20:47:39 -0500 Subject: [PATCH 1/8] Add byte-preserving File.Copy --- packages/cli/src/repl/file-recorder.ts | 65 ++++++ .../cli/src/repl/repositories/deno/files.ts | 45 ++-- .../cli/src/repl/repositories/deno/local.ts | 17 +- packages/cli/src/repl/repositories/records.ts | 31 ++- .../src/repl/workspace-mount-installation.ts | 54 +++-- .../file-copy/FileCopy.test.md | 52 +++++ packages/cli/tests/repl-repositories.test.ts | 101 +++++++- .../cli/tests/retained-repository-git.test.ts | 2 + .../tests/retained-repository-history.test.ts | 3 + .../retained-repository-lifecycle.test.ts | 2 + .../tests/retained-repository-local.test.ts | 162 +++++++++++++ .../retained-repository-pull-request.test.ts | 2 + .../tests/retained-repository-push.test.ts | 2 + .../retained-repository-selection.test.ts | 2 + packages/cli/tests/syntax-cli.test.ts | 18 ++ packages/core/src/components/FileCopy.ts | 31 +++ packages/core/src/components/components.md | 16 ++ .../core/src/components/fs-error-phrases.ts | 1 + packages/core/src/components/registry.ts | 12 + packages/core/src/files.ts | 5 + packages/core/tests/support/fragment-files.ts | 7 + packages/runtime/files-api.ts | 1 + packages/runtime/files.ts | 16 ++ packages/runtime/host-files.ts | 102 +++++++- packages/runtime/mod.ts | 1 + packages/runtime/tests/host-files.test.ts | 147 +++++++++++- packages/workflow/src/deno/workspace/files.ts | 75 ++++++ .../workflow/src/deno/workspace/filesystem.ts | 11 +- packages/workflow/src/deno/workspace/guard.ts | 4 +- .../tests/generated-agent-component.test.ts | 42 ++++ .../workflow/tests/workspace-files.test.ts | 219 ++++++++++++++++-- scripts/bench-repl-file-dir.ts | 2 + scripts/files-contract-probe.ts | 20 +- scripts/lib/markdown-suites.ts | 1 + scripts/tests/test-file-discovery.test.ts | 1 + specs/executable-mdx-spec.md | 33 +++ specs/repl-spec.md | 20 +- specs/testing-spec.md | 1 + specs/workflow-workspace-spec.md | 18 ++ 39 files changed, 1266 insertions(+), 78 deletions(-) create mode 100644 packages/cli/tests/document-suites/file-copy/FileCopy.test.md create mode 100644 packages/core/src/components/FileCopy.ts diff --git a/packages/cli/src/repl/file-recorder.ts b/packages/cli/src/repl/file-recorder.ts index 8412f90b5..358d5e47b 100644 --- a/packages/cli/src/repl/file-recorder.ts +++ b/packages/cli/src/repl/file-recorder.ts @@ -1,6 +1,9 @@ import { Err, Ok } from "effection"; import type { Operation, Result } from "effection"; import { + API, + Permissions, + hostFileAccessReason, FilesInvariantError, filesFailure, fileWriteFailure, @@ -9,6 +12,7 @@ import { parseFileWriteSuccess, } from "@executablemd/runtime"; import type { + HostFilesAccess, FilesHandler, FilesOperation, FilesPhase, @@ -16,6 +20,7 @@ import type { FileWriteSuccess, } from "@executablemd/runtime"; import { registerFileRecorder, assembleFileCall } from "@executablemd/runtime/files-host"; +import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path"; import type { Around } from "@effectionx/context-api"; import type { AuthoredFileOperation } from "@executablemd/core/host"; import type { @@ -71,6 +76,14 @@ function recordingBody(route: FileRecordingRoute) { const result = yield* route("file-write", { ...input }, () => writeOutcome(next(input))); return result.ok ? Ok(expectWritten(result.value)) : result; }, + *copyFile([input], next) { + const result = yield* route( + "file-copy", + { cwd: input.cwd, source: input.source, path: input.destination }, + () => unitOutcome(next(input), { operation: "copy", phase: "access" }), + ); + return result.ok ? Ok(undefined) : result; + }, *deleteFile([input], next) { const result = yield* route("file-delete", { ...input }, () => unitOutcome(next(input), { operation: "delete", phase: "access" }), @@ -93,6 +106,58 @@ export function* useEntryFileRecorder(route: FileRecordingRoute): Operation ensure(input), authored), }); } +export function* liveCopyTargets( + request: ReplLocalRequest, + access: HostFilesAccess | undefined, +): Operation> { + const { cwd, source, path } = request; + if (source === undefined) { + throw new FilesInvariantError("protocol"); + } + for (const operand of [source, path]) { + const suffix = relative(cwd, resolve(cwd, operand)); + const reason = + operand === "" + ? "empty-path" + : isAbsolute(operand) + ? "absolute-path" + : suffix === ".." || suffix.startsWith(".." + sep) || isAbsolute(suffix) + ? "lexical-escape" + : undefined; + if (reason !== undefined) { + return Err(filesFailure({ operation: "copy", phase: "lexical", reason })); + } + } + if ( + !(yield* Permissions.operations.files("read")) || + !(yield* Permissions.operations.files("write")) + ) { + return Err( + filesFailure({ operation: "copy", phase: "resolution", reason: "permission-denied" }), + ); + } + const reason = + (yield* hostFileAccessReason(access, "read", { cwd, path: source })) ?? + (yield* hostFileAccessReason(access, "delete", { cwd, path })); + if (reason !== undefined) { + return Err(filesFailure({ operation: "copy", phase: "resolution", reason })); + } + + const from = resolve(cwd, source); + const to = resolve(cwd, path); + const parent = dirname(to); + // The final destination entry can itself be a link. Its parent owns the copy. + try { + return Ok({ + source: (yield* API.Fs.operations.realpath(from)) ?? from, + destination: resolve((yield* API.Fs.operations.realpath(parent)) ?? parent, basename(to)), + }); + } catch { + // The performing provider reports resolution failures in the Files vocabulary. + return Ok({ source: from, destination: to }); + } +} + function* writeOutcome(call: Operation>): Operation> { const produced: unknown = yield* call; const settled = settlement(produced); diff --git a/packages/cli/src/repl/repositories/deno/files.ts b/packages/cli/src/repl/repositories/deno/files.ts index e90347f82..d77ba8498 100644 --- a/packages/cli/src/repl/repositories/deno/files.ts +++ b/packages/cli/src/repl/repositories/deno/files.ts @@ -1,7 +1,7 @@ import { hostFileAccessReason, fileWriteFailure } from "@executablemd/runtime"; import type { HostFilesAccess } from "@executablemd/runtime"; import type { AwaitedMountPolicy } from "../../mount-files.ts"; -import { useEntryFileRecorder } from "../../file-recorder.ts"; +import { liveCopyTargets, useEntryFileRecorder } from "../../file-recorder.ts"; import type { MountFileEntry } from "../../workspace-mount-installation.ts"; import type { WorkspaceMountTable } from "../../../workspace-mounts.ts"; import type { AuthoredFileOperation } from "@executablemd/core/host"; @@ -143,10 +143,15 @@ function* routed( return yield* replay; } } - if (yield* retainedResultAhead(name)) { + if (yield* retainedResultAhead(name, operation)) { return yield* recordedLocalOperation({ operation, request, perform }); } + const copy = operation === "file-copy" ? yield* liveCopyTargets(request, access) : undefined; + if (copy !== undefined && !copy.ok) { + return copy; + } + if ( operation === "dir-ensure" && isAbsolute(request.path) && @@ -162,17 +167,20 @@ function* routed( ); } - const reason = yield* hostFileAccessReason( - access, - operation === "file-read" - ? "read" - : operation === "file-write" - ? "write" - : operation === "file-delete" - ? "delete" - : "ensure-directory", - request, - ); + const reason = + copy === undefined + ? yield* hostFileAccessReason( + access, + operation === "file-read" + ? "read" + : operation === "file-write" + ? "write" + : operation === "file-delete" + ? "delete" + : "ensure-directory", + request, + ) + : undefined; if (reason !== undefined) { return Err( operation === "file-write" @@ -194,8 +202,15 @@ function* routed( authored === undefined || mounts === undefined ? recordedLocalOperation({ operation, request, perform }) : mounts.record(authored, request, perform, coverage); - const target = yield* targetOf(request); - const managed = covering(recorder.placements(), target); + const target = copy?.value.destination ?? (yield* targetOf(request)); + const placements = recorder.placements(); + const managed = covering(placements, target); + if (copy !== undefined) { + const source = covering(placements, copy.value.source); + if (source !== undefined && source !== managed) { + yield* source.own(); + } + } if (managed !== undefined) { // Placement ownership first, and for a read as much as for a write: what it // answers is that one entry at a time owns this managed checkout, which an diff --git a/packages/cli/src/repl/repositories/deno/local.ts b/packages/cli/src/repl/repositories/deno/local.ts index e785d7730..edcce4236 100644 --- a/packages/cli/src/repl/repositories/deno/local.ts +++ b/packages/cli/src/repl/repositories/deno/local.ts @@ -136,8 +136,21 @@ export function retainedSelectionAhead(): Operation { } /** Whether this operation's own saved result stands at the cursor. */ -export function retainedResultAhead(name: string): Operation { - return retainedRecordAhead(REPL_REPOSITORY_LOCAL, name); +export function* retainedResultAhead( + name: string, + operation?: ReplLocalOperation, +): Operation { + if (operation !== "file-copy") { + return yield* retainedRecordAhead(REPL_REPOSITORY_LOCAL, name); + } + const context = yield* DurableContext.expect(); + const description = context.replayIndex.peekYield(context.coroutineId)?.description; + const prefix = replLocalRecordName({ operation, fingerprint: "" }).slice(0, -2); + return ( + description?.type === REPL_REPOSITORY_LOCAL && + typeof description.name === "string" && + description.name.startsWith(prefix) + ); } /** diff --git a/packages/cli/src/repl/repositories/records.ts b/packages/cli/src/repl/repositories/records.ts index e9f328074..56da5d850 100644 --- a/packages/cli/src/repl/repositories/records.ts +++ b/packages/cli/src/repl/repositories/records.ts @@ -75,11 +75,17 @@ export const REPL_REPOSITORY_SELECTION = "repl_repository_selection"; export const RECORD_PREFIX = "executablemd.git.repl-repository"; /** Which local operation a record describes. */ -export type ReplLocalOperation = "file-read" | "file-write" | "file-delete" | "dir-ensure"; +export type ReplLocalOperation = + | "file-read" + | "file-write" + | "file-copy" + | "file-delete" + | "dir-ensure"; const LOCAL_OPERATIONS: readonly ReplLocalOperation[] = [ "file-read", "file-write", + "file-copy", "file-delete", "dir-ensure", ]; @@ -100,6 +106,7 @@ export interface ReplLocalRequest { readonly path: string; /** The exact expanded content a write asked for; absent for the other three. */ readonly content?: string; + readonly source?: string; } /** The routing facts the entry's ambient discovery found, or their absence. */ @@ -247,7 +254,12 @@ export function parseReplLocalRecord(value: unknown): ReplLocalRecord | undefine refusal === undefined ? parseSuccess(read["success"], operation) : parseRefusal(read["refusal"]); - if (outcome === undefined) { + if ( + outcome === undefined || + (operation === "file-copy" && + !outcome.ok && + parseFilesFailure(outcome.error)?.operation !== "copy") + ) { return undefined; } return Object.freeze({ @@ -314,6 +326,18 @@ function parseReplLocalRequest( value: unknown, operation: ReplLocalOperation, ): ReplLocalRequest | undefined { + if (operation === "file-copy") { + const read = members(value, ["cwd", "source", "destination"]); + if (read === undefined) { + return undefined; + } + const cwd = string(read.cwd); + const source = anyString(read.source); + const path = anyString(read.destination); + return cwd === undefined || source === undefined || path === undefined + ? undefined + : Object.freeze({ cwd, source, path }); + } const read = operation === "file-write" ? members(value, ["cwd", "path", "content"]) @@ -406,6 +430,9 @@ function carried(data: unknown): Error { } function requestJson(request: ReplLocalRequest): Json { + if (request.source !== undefined) { + return { cwd: request.cwd, source: request.source, destination: request.path }; + } return request.content === undefined ? { cwd: request.cwd, path: request.path } : { cwd: request.cwd, path: request.path, content: request.content }; diff --git a/packages/cli/src/repl/workspace-mount-installation.ts b/packages/cli/src/repl/workspace-mount-installation.ts index 4fce5a378..2919ad326 100644 --- a/packages/cli/src/repl/workspace-mount-installation.ts +++ b/packages/cli/src/repl/workspace-mount-installation.ts @@ -7,7 +7,7 @@ import type { Operation, Result } from "effection"; import type { ExecutionInstallation } from "@executablemd/core/host"; import type { DurableEvent } from "@executablemd/durable-streams"; import type { WorkspaceMountTable } from "../workspace-mounts.ts"; -import { useEntryFileRecorder } from "./file-recorder.ts"; +import { liveCopyTargets, useEntryFileRecorder } from "./file-recorder.ts"; import type { EntryFileCalls } from "./file-recorder.ts"; import { createMountPolicy } from "./mount-files.ts"; import type { AwaitedMountPolicy } from "./mount-files.ts"; @@ -59,13 +59,18 @@ export function workspaceMountInstallation( } } const name = yield* localRecordName({ operation, request }); - if (yield* retainedResultAhead(name)) { + if (yield* retainedResultAhead(name, operation)) { return yield* recordedLocalOperation({ operation, request, perform }); } const roots = [ ...(ownedDirectory === undefined ? [] : [ownedDirectory]), ...(limits === undefined ? [] : [limits.project, limits.assets, limits.components]), ]; + const copy = + operation === "file-copy" ? yield* liveCopyTargets(request, limits) : undefined; + if (copy !== undefined && !copy.ok) { + return copy; + } const permitted = roots.length === 0 || ((yield* Permissions.operations.files( @@ -74,19 +79,22 @@ export function workspaceMountInstallation( (operation !== "dir-ensure" || !isAbsolute(request.path) || (yield* Permissions.operations.files("absolute")))); - const reason = permitted - ? yield* hostFileAccessReason( - limits, - operation === "file-read" - ? "read" - : operation === "file-write" - ? "write" - : operation === "file-delete" - ? "delete" - : "ensure-directory", - request, - ) - : "permission-denied"; + const reason = + copy !== undefined + ? undefined + : permitted + ? yield* hostFileAccessReason( + limits, + operation === "file-read" + ? "read" + : operation === "file-write" + ? "write" + : operation === "file-delete" + ? "delete" + : "ensure-directory", + request, + ) + : "permission-denied"; if (reason !== undefined) { return Err( operation === "file-write" @@ -105,13 +113,15 @@ export function workspaceMountInstallation( } if (roots.length > 0) { const directory = (yield* API.Fs.operations.realpath(request.cwd)) ?? request.cwd; - const target = isAbsolute(request.path) - ? resolve( - (yield* API.Fs.operations.realpath(dirname(request.path))) ?? - dirname(request.path), - basename(request.path), - ) - : resolve(directory, request.path); + const target = + copy?.value.destination ?? + (isAbsolute(request.path) + ? resolve( + (yield* API.Fs.operations.realpath(dirname(request.path))) ?? + dirname(request.path), + basename(request.path), + ) + : resolve(directory, request.path)); for (const directory of roots) { const root = (yield* API.Fs.operations.realpath(directory)) ?? resolve(directory); const suffix = relative(root, target); diff --git a/packages/cli/tests/document-suites/file-copy/FileCopy.test.md b/packages/cli/tests/document-suites/file-copy/FileCopy.test.md new file mode 100644 index 000000000..b7d9ae4e6 --- /dev/null +++ b/packages/cli/tests/document-suites/file-copy/FileCopy.test.md @@ -0,0 +1,52 @@ +# File.Copy + + + + + +Generate the binary fixture in the test directory. + +```ts eval +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { until } from "effection"; +yield* (function* () { + const fixture = new Uint8Array(8 * 1024 * 1024 + 1); + fixture[fixture.length - 1] = 0xff; + yield* until(writeFile(join(directory, "source.bin"), fixture)); +})(); +``` + + + +```ts eval +import { readFile, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { until } from "effection"; +const verified = yield* (function* () { + const fixture = new Uint8Array(8 * 1024 * 1024 + 1); + fixture[fixture.length - 1] = 0xff; + const source = join(directory, "source.bin"); + const destination = join(directory, "destination.bin"); + const original = (yield* until(readFile(source))).equals(fixture); + const copy = (yield* until(readFile(destination))).equals(fixture); + yield* until(writeFile(destination, Uint8Array.of(42))); + return { original, copy, independent: (yield* until(readFile(source))).equals(fixture) }; +})(); +``` + + + + + + + +source +\n\nran\n\n\n'} as="child"> + + + + + + + diff --git a/packages/cli/tests/repl-repositories.test.ts b/packages/cli/tests/repl-repositories.test.ts index c1c9fab10..08be6d4ba 100644 --- a/packages/cli/tests/repl-repositories.test.ts +++ b/packages/cli/tests/repl-repositories.test.ts @@ -21,7 +21,7 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; import { ensure, resource, scoped, until } from "effection"; import type { Operation, Result } from "effection"; -import { exists, readTextFile, rm } from "@effectionx/fs"; +import { ensureDir, exists, readTextFile, rm } from "@effectionx/fs"; import { mkdtemp, realpath, writeFile } from "node:fs/promises"; import { appendFile, open } from "node:fs/promises"; import { tmpdir } from "node:os"; @@ -39,6 +39,11 @@ import { REPL_REPOSITORY_PLACEMENT, } from "../src/repl/repositories/placement-records.ts"; import { Execution } from "@executablemd/core/api"; +import { collect, inlineSource } from "@executablemd/core"; +import { executeInstalled } from "@executablemd/core/host"; +import { useCompositionComponents } from "@executablemd/git"; +import { useReplFileRecorder } from "../src/repl/repositories/deno/files.ts"; +import { workspaceMountInstallation } from "../src/repl/workspace-mount-installation.ts"; import type { Json } from "@executablemd/core"; import type { ExecutionInstallation } from "@executablemd/core/host"; import { ordinaryGeneratedSelection } from "../src/evaluation-profile.ts"; @@ -455,6 +460,100 @@ describe("how a REPL entry gets its repository behavior", () => { expect(yield* exists(join(fixture.checkout, "made"))).toBe(false); }); + it("retains an authored byte copy in a managed Repository", function* () { + const fixture = yield* useFixture(); + const origin = yield* useOrigin(fixture); + const source = [ + ``, + 'original', + '', + "", + ].join("\n"); + const events = yield* submit(fixture, source, execution(), { initialized: 0 }); + const copies = recordsOf(events, REPL_REPOSITORY_LOCAL).flatMap((event) => { + const record = parseReplLocalRecord( + event.type === "yield" && event.result.status === "ok" ? event.result.value : undefined, + ); + return record?.operation === "file-copy" ? [record] : []; + }); + expect(copies).toHaveLength(1); + expect(copies[0]?.outcome).toEqual({ ok: true, value: undefined }); + const directory = copies[0]?.request.cwd; + if (directory === undefined) { + throw new Error("No managed copy directory"); + } + expect(yield* readTextFile(join(directory, "copy.md"))).toBe("original"); + }); + + it("uses both placement slots and only the destination mutation hold from a mounted cwd", function* () { + const fixture = yield* useFixture(); + const destination = join(fixture.root, "destination"); + yield* ensureDir(destination); + const sourceCommon = join(fixture.checkout, ".git"); + const destinationCommon = join(destination, ".git"); + const calls: string[] = []; + yield* useHostFiles(); + yield* useCompositionComponents(); + yield* useWorkingDirectory(fixture.root); + yield* Permissions.around({ + files: ([op], next) => (op === "absolute" ? true : next(op)), + }); + const mounts = [{ source: fixture.root, target: "/reference" }]; + const files = yield* useReplFileRecorder( + { + *selection() { + return undefined; + }, + *hold(common) { + calls.push(`hold ${common}`); + }, + placements() { + return [ + { + checkoutRoot: fixture.checkout, + commonDirectory: sourceCommon, + *own() { + calls.push("source slot"); + }, + }, + { + checkoutRoot: destination, + commonDirectory: destinationCommon, + *own() { + calls.push("destination slot"); + }, + }, + ]; + }, + }, + fixture.root, + mounts, + fixture.root, + ); + const stream = new InMemoryStream(); + const source = [ + '', + '', + "", + ].join("\n"); + yield* collect( + yield* executeInstalled({ ...inlineSource(source), stream }, [ + workspaceMountInstallation(mounts, () => files), + ]), + ); + expect(calls).toEqual(["source slot", "destination slot", `hold ${destinationCommon}`]); + const records = recordsOf(yield* stream.readAll(), REPL_REPOSITORY_LOCAL); + const copy = records.flatMap((event) => { + const parsed = parseReplLocalRecord( + event.type === "yield" && event.result.status === "ok" ? event.result.value : undefined, + ); + return parsed?.operation === "file-copy" ? [parsed] : []; + }); + expect(copy).toHaveLength(1); + expect(copy[0]?.request.cwd).toBe(fixture.root); + expect(yield* readTextFile(join(destination, "copied.md"))).toBe("seed\n"); + }); + it("E7: keeps two entries' equal records in their own segments", function* () { const fixture = yield* useFixture(); const counted: Counted = { initialized: 0 }; diff --git a/packages/cli/tests/retained-repository-git.test.ts b/packages/cli/tests/retained-repository-git.test.ts index 081510eee..39d244807 100644 --- a/packages/cli/tests/retained-repository-git.test.ts +++ b/packages/cli/tests/retained-repository-git.test.ts @@ -163,6 +163,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -350,6 +351,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-history.test.ts b/packages/cli/tests/retained-repository-history.test.ts index 0258e6e59..9151ddc07 100644 --- a/packages/cli/tests/retained-repository-history.test.ts +++ b/packages/cli/tests/retained-repository-history.test.ts @@ -212,6 +212,9 @@ function invocationFiles(temporary: string): InvocationFiles { const resolved = (input: FilePathInput): string => input.path.startsWith("/") ? input.path : join(input.cwd, input.path); const handler: FilesHandler = { + *copyFile() { + throw new Error("Unexpected copy"); + }, // deno-lint-ignore require-yield *checkFilePath(): Operation> { return Ok(undefined); diff --git a/packages/cli/tests/retained-repository-lifecycle.test.ts b/packages/cli/tests/retained-repository-lifecycle.test.ts index 2b7d7e115..6dd29b0f7 100644 --- a/packages/cli/tests/retained-repository-lifecycle.test.ts +++ b/packages/cli/tests/retained-repository-lifecycle.test.ts @@ -167,6 +167,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -247,6 +248,7 @@ function entry( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-local.test.ts b/packages/cli/tests/retained-repository-local.test.ts index a23a44106..b003cd290 100644 --- a/packages/cli/tests/retained-repository-local.test.ts +++ b/packages/cli/tests/retained-repository-local.test.ts @@ -124,6 +124,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -210,6 +211,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, @@ -1451,3 +1453,163 @@ describe("marked workspace mount initialization", () => { ]); }); }); + +describe("retained File.Copy", () => { + const source = ''; + + it("replays success and occupied refusal before current permissions and routing", function* () { + for (const occupied of [false, true]) { + const fixture = yield* useFixture(); + const target = join(fixture.checkout, "copy.md"); + if (occupied) { + yield* writeTextFile(target, "occupied"); + } + const first = yield* run(fixture, source, new InMemoryStream(), counters()); + expect( + localRecords(first.events).map((record) => [record.operation, record.outcome.ok]), + ).toEqual([["file-copy", !occupied]]); + yield* writeTextFile(target, "external"); + const checked = counters(); + const asked: string[] = []; + const resumed = yield* run(fixture, source, unfinished(first.events), checked, { + *between() { + yield* Permissions.around({ + files: ([op]) => { + asked.push(op); + return false; + }, + }); + yield* API.Fs.around({ + *realpath([path], next) { + if (path.includes("seed.md") || path === fixture.checkout) { + checked.resolved++; + } + return yield* next(path); + }, + }); + }, + }); + expect(resumed.refusal).toBe(undefined); + expect(resumed.output).toBe(first.output); + expect(asked).toEqual([]); + expect(checked.discoveries).toEqual([]); + expect(checked.resolved).toBe(0); + expect(yield* readTextFile(target)).toBe("external"); + } + }); + + it("rejects either changed operand before routing and leaves uncovered copy live", function* () { + const fixture = yield* useFixture(); + const doc = ''; + const placement = { cwd: fixture.root, projectCwd: fixture.checkout }; + const first = yield* run(fixture, doc, new InMemoryStream(), counters(), placement); + expect(localRecords(first.events).map((record) => record.operation)).toEqual(["file-copy"]); + for (const change of [{ source: "checkout/other.md" }, { destination: "outside.md" }]) { + const checked = counters(); + const asked: string[] = []; + const resumed = yield* run(fixture, doc, unfinished(first.events), checked, { + ...placement, + *between() { + yield* API.Files.around({ copyFile: ([input], next) => next({ ...input, ...change }) }); + yield* Permissions.around({ + files: ([op]) => { + asked.push(op); + return true; + }, + }); + }, + }); + expect(resumed.refusal).toContain("file-copy"); + expect(asked).toEqual([]); + expect(checked.discoveries).toEqual([]); + expect(localRecords(resumed.events)).toEqual(localRecords(first.events)); + } + const outside = join(fixture.root, "outside.md"); + expect(yield* exists(outside)).toBe(false); + const uncovered = yield* run( + fixture, + doc.replace("checkout/copy.md", "outside.md"), + new InMemoryStream(), + counters(), + placement, + ); + expect(uncovered.refusal).toBe(undefined); + expect(localRecords(uncovered.events)).toEqual([]); + expect(yield* readTextFile(outside)).toBe("seed\n"); + }); + + it("refuses occupancy after a native copy whose acknowledgement was halted", function* () { + const fixture = yield* useFixture(); + const events: DurableEvent[] = []; + const reached = withResolvers(); + const barrier: DurableStream = { + *readAll(): Operation { + return [...events]; + }, + *append(event: DurableEvent): Operation { + if (event.type === "yield" && event.description.type === REPL_REPOSITORY_LOCAL) { + reached.resolve(); + yield* suspend(); + } + events.push(event); + }, + }; + yield* scoped(function* () { + const task = yield* spawn(() => run(fixture, source, barrier, counters())); + yield* reached.operation; + yield* task.halt(); + }); + expect(localRecords(events)).toEqual([]); + const target = join(fixture.checkout, "copy.md"); + const copied = yield* readTextFile(target); + expect(copied).toBe(yield* readTextFile(join(fixture.checkout, "seed.md"))); + const resumed = yield* run(fixture, source, new InMemoryStream(events), counters()); + expect(resumed.output).toContain("already exists"); + expect(localRecords(resumed.events).map((record) => record.outcome.ok)).toEqual([false]); + expect(yield* readTextFile(target)).toBe(copied); + }); + + it("records copies in the mount installation fallback and restores without live copy", function* () { + const fixture = yield* useFixture(); + const owned = join(fixture.root, "owned"); + yield* ensureDir(owned); + yield* writeTextFile(join(owned, "seed.md"), "owned seed"); + const first = yield* scoped(function* () { + yield* API.Env.around({ + *cwd() { + return owned; + }, + }); + const host = hostFilesHandler(); + yield* API.Files.around({ copyFile: ([input]) => host.copyFile(input) }, { at: "min" }); + const stream = new InMemoryStream(); + yield* collect( + yield* executeInstalled({ ...inlineSource(source), stream }, [ + workspaceMountInstallation([], undefined, undefined, owned), + ]), + ); + return yield* stream.readAll(); + }); + expect(localRecords(first).map((record) => record.operation)).toEqual(["file-copy"]); + expect(recordsOf(first, REPL_REPOSITORY_SELECTION)).toEqual([]); + yield* writeTextFile(join(owned, "copy.md"), "changed"); + yield* scoped(function* () { + yield* API.Env.around({ + *cwd() { + return owned; + }, + }); + yield* Permissions.around({ + files: () => { + throw new Error("live policy"); + }, + }); + yield* collect( + yield* executeInstalled({ ...inlineSource(source), stream: unfinished(first) }, [ + workspaceMountInstallation([], undefined, undefined, owned), + ]), + ); + }); + expect(yield* readTextFile(join(owned, "copy.md"))).toBe("changed"); + }); +}); diff --git a/packages/cli/tests/retained-repository-pull-request.test.ts b/packages/cli/tests/retained-repository-pull-request.test.ts index d5c213ed8..06b073793 100644 --- a/packages/cli/tests/retained-repository-pull-request.test.ts +++ b/packages/cli/tests/retained-repository-pull-request.test.ts @@ -627,6 +627,7 @@ function hostFiles(): FilesHandler { globFiles: (input) => host.globFiles(input), temporaryDirectory: () => host.temporaryDirectory(), writeTextFile: (input: FileWriteInput) => host.writeTextFile(input), + copyFile: (input) => host.copyFile(input), deleteFile: (input) => host.deleteFile(input), ensureDirectory: (input) => host.ensureDirectory(input), }; @@ -829,6 +830,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-push.test.ts b/packages/cli/tests/retained-repository-push.test.ts index e3ff3316b..1b88bb781 100644 --- a/packages/cli/tests/retained-repository-push.test.ts +++ b/packages/cli/tests/retained-repository-push.test.ts @@ -173,6 +173,7 @@ function hostFiles(): FilesHandler { globFiles: (input) => host.globFiles(input), temporaryDirectory: () => host.temporaryDirectory(), writeTextFile: (input: FileWriteInput) => host.writeTextFile(input), + copyFile: (input) => host.copyFile(input), deleteFile: (input) => host.deleteFile(input), ensureDirectory: (input) => host.ensureDirectory(input), }; @@ -303,6 +304,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/retained-repository-selection.test.ts b/packages/cli/tests/retained-repository-selection.test.ts index fbdbb9d3b..7a3cac74e 100644 --- a/packages/cli/tests/retained-repository-selection.test.ts +++ b/packages/cli/tests/retained-repository-selection.test.ts @@ -164,6 +164,7 @@ function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { checkFilePath: (input) => host.checkFilePath(input), + copyFile: (input) => host.copyFile(input), *readTextFile(input: FilePathInput) { counted.reads.push(input.path); return yield* host.readTextFile(input); @@ -306,6 +307,7 @@ function run( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/packages/cli/tests/syntax-cli.test.ts b/packages/cli/tests/syntax-cli.test.ts index 5c6f339f5..25cd1f03b 100644 --- a/packages/cli/tests/syntax-cli.test.ts +++ b/packages/cli/tests/syntax-cli.test.ts @@ -563,6 +563,24 @@ describe("Tier SX — the command line", { sanitizeOps: false, sanitizeResources expect(unknown.stdout).toBe(""); }); + it("SX16: named File.Copy describes the two paths and replay", function* () { + const named = yield* runCli(["syntax", "File.Copy"], { cwd: "." }).expect(); + for (const text of [ + "**Forms:** ``", + "| `source` | `string` | yes |", + "| `destination` | `string` | yes |", + "An occupied destination is preserved.", + "Ordinary hosts and Markdown tests copy live", + "partial host replay", + "Workflow Workspace replay restores a published", + "Retained REPL replay restores an acknowledged", + "Unrecorded copies run live.", + ]) { + expect(named.stdout).toContain(text); + } + expect(named.stdout).not.toContain(""); + }); + it("SX16: engine and selected installed structural names match canonical component references", function* () { const plugin = new URL("./fixtures/plugins/structural-reference.mjs", import.meta.url).pathname; for (const name of ["If", "All", "Banner", "BannerLine"]) { diff --git a/packages/core/src/components/FileCopy.ts b/packages/core/src/components/FileCopy.ts new file mode 100644 index 000000000..7f7bfd66c --- /dev/null +++ b/packages/core/src/components/FileCopy.ts @@ -0,0 +1,31 @@ +import { cwd, parseFilesFailure } from "@executablemd/runtime"; +import { printErrors } from "../component-failures.ts"; +import { copyFile } from "../files.ts"; +import type { FormDeclaration } from "../invocation-identity.ts"; +import { reason } from "./fs-error-phrases.ts"; + +export const props = { + type: "object", + properties: { + source: { type: "string", minLength: 1 }, + destination: { type: "string", minLength: 1 }, + }, + required: ["source", "destination"], + additionalProperties: false, +}; + +export const form: FormDeclaration = { + forms: "self-closing", + refuse: () => new Error(" requires a self-closing invocation."), + fn: printErrors(function* (props) { + const result = yield* copyFile({ + cwd: yield* cwd(), + source: String(props.source), + destination: String(props.destination), + }); + if (!result.ok) { + throw new Error(`Cannot copy file: ${reason(parseFilesFailure(result.error)?.reason)}.`); + } + return ""; + }), +}; diff --git a/packages/core/src/components/components.md b/packages/core/src/components/components.md index ea2879324..6d9021ad9 100644 --- a/packages/core/src/components/components.md +++ b/packages/core/src/components/components.md @@ -177,6 +177,22 @@ read rather than re-reading a file that has since changed. A read of a path that does not exist fails. The write form creates the file and the directories above it as needed. +## File.Copy + +Copy a regular file byte for byte. + +```mdx + +``` + +Both paths are relative to the working directory. The destination directory +must already exist. An occupied destination is preserved. + +Ordinary hosts and Markdown tests copy live, including partial host replay +that reaches the copy. Workflow Workspace replay restores a published result. +Retained REPL replay restores an acknowledged result in covered storage. +Unrecorded copies run live. + ## File.Delete Deletes a file, relative to the working directory. diff --git a/packages/core/src/components/fs-error-phrases.ts b/packages/core/src/components/fs-error-phrases.ts index 4a1506f79..1ea2b79ac 100644 --- a/packages/core/src/components/fs-error-phrases.ts +++ b/packages/core/src/components/fs-error-phrases.ts @@ -28,6 +28,7 @@ import type { FilesReason } from "@executablemd/runtime"; * directory or a special file, and a pattern that cannot be compiled. */ const PHRASES: ReadonlyMap = new Map([ + ["occupied", "the destination already exists"], ["missing", "no such file or directory"], ["not-directory", "a component of the path is not a directory"], ["directory", "it is a directory"], diff --git a/packages/core/src/components/registry.ts b/packages/core/src/components/registry.ts index b14aced37..7e93ca351 100644 --- a/packages/core/src/components/registry.ts +++ b/packages/core/src/components/registry.ts @@ -32,6 +32,7 @@ import Cwd, { props as cwdProps, generated as cwdGenerated } from "./Cwd.ts"; import TempDir, { props as tempDirProps } from "./TempDir.ts"; import { form as failForm, props as failProps } from "./Fail.ts"; import Fetch, { generated as fetchGenerated, props as fetchProps } from "./Fetch.ts"; +import { form as fileCopyForm, props as fileCopyProps } from "./FileCopy.ts"; import Glob, { generated as globGenerated, props as globProps, @@ -232,6 +233,17 @@ export const CORE_REGISTRY: ComponentRegistry = new Map([ generated: fetchGenerated, }, ), + core("File.Copy", fileCopyForm, parseJsonObject(fileCopyProps), { + description: + 'Copy a regular file byte for byte. `` ' + + "requires an existing destination directory. " + + "Both paths are relative to the working directory. An occupied destination is preserved. " + + "Ordinary hosts and Markdown tests copy live, as does partial host replay that reaches the copy. " + + "Workflow Workspace replay restores a published copy result. Retained REPL replay restores " + + "an acknowledged copy in covered storage. Unrecorded copies run live.", + as: null, + context: null, + }), core( "Glob", Glob, diff --git a/packages/core/src/files.ts b/packages/core/src/files.ts index 830106edc..97361ac6d 100644 --- a/packages/core/src/files.ts +++ b/packages/core/src/files.ts @@ -31,6 +31,7 @@ import { parseFilesFailure, } from "@executablemd/runtime"; import type { + FileCopyInput, FilePathInput, FilesOperation, FilesPhase, @@ -322,6 +323,10 @@ export function deleteFile(input: FilePathInput): Operation> { return unit(Files.operations.deleteFile(input), { operation: "delete", phase: "access" }); } +export function copyFile(input: FileCopyInput): Operation> { + return unit(Files.operations.copyFile(input), { operation: "copy", phase: "access" }); +} + /** * Make this authored path name a directory, with nothing coming back. * diff --git a/packages/core/tests/support/fragment-files.ts b/packages/core/tests/support/fragment-files.ts index ab6a280cf..572b1ae5d 100644 --- a/packages/core/tests/support/fragment-files.ts +++ b/packages/core/tests/support/fragment-files.ts @@ -132,6 +132,10 @@ export function recordedFiles( entries.set(input.path, input.content); return Ok(fileWriteSuccess("host-committed")); }, + *copyFile() { + performed.push("copy"); + throw new Error("Unexpected copy"); + }, *deleteFile(input: FilePathInput): Operation> { if (!(yield* Permissions.operations.files("write"))) { return Err( @@ -200,6 +204,9 @@ export function* useRecordedFiles(files: RecordedFiles): Operation { *writeTextFile([input]) { return yield* files.writeTextFile(input); }, + *copyFile([input]) { + return yield* files.copyFile(input); + }, *deleteFile([input]) { return yield* files.deleteFile(input); }, diff --git a/packages/runtime/files-api.ts b/packages/runtime/files-api.ts index 90c0e8d23..c5eea3a3a 100644 --- a/packages/runtime/files-api.ts +++ b/packages/runtime/files-api.ts @@ -123,6 +123,7 @@ export function createFilesApi(terminal: FilesHandler): FilesApi { checkFilePath: call(terminal.checkFilePath, (layer) => layer.checkFilePath), readTextFile: call(terminal.readTextFile, (layer) => layer.readTextFile), writeTextFile: call(terminal.writeTextFile, (layer) => layer.writeTextFile), + copyFile: call(terminal.copyFile, (layer) => layer.copyFile), deleteFile: call(terminal.deleteFile, (layer) => layer.deleteFile), ensureDirectory: call(terminal.ensureDirectory, (layer) => layer.ensureDirectory), globFiles: call(terminal.globFiles, (layer) => layer.globFiles), diff --git a/packages/runtime/files.ts b/packages/runtime/files.ts index 74edbba29..73228db76 100644 --- a/packages/runtime/files.ts +++ b/packages/runtime/files.ts @@ -96,6 +96,7 @@ export type FilesReason = | "absolute-path" | "lexical-escape" | "resolved-escape" + | "occupied" | "missing" | "directory" | "special-file" @@ -118,6 +119,7 @@ const REASONS: readonly FilesReason[] = [ "absolute-path", "lexical-escape", "resolved-escape", + "occupied", "missing", "directory", "special-file", @@ -140,6 +142,7 @@ const REASONS: readonly FilesReason[] = [ export type FilesOperation = | "check-file-path" | "read" + | "copy" | "delete" | "ensure-directory" | "glob" @@ -148,6 +151,7 @@ export type FilesOperation = const OPERATIONS: readonly FilesOperation[] = [ "check-file-path", "read", + "copy", "delete", "ensure-directory", "glob", @@ -243,6 +247,12 @@ export interface FilePathInput { readonly path: string; } +export interface FileCopyInput { + readonly cwd: string; + readonly source: string; + readonly destination: string; +} + export interface FileWriteInput extends FilePathInput { readonly content: string; } @@ -261,6 +271,8 @@ export interface FilesHandler { checkFilePath(input: FilePathInput): Operation>; readTextFile(input: FilePathInput): Operation>; writeTextFile(input: FileWriteInput): Operation>; + /** Copy a regular file to a vacant destination with an existing parent. */ + copyFile(input: FileCopyInput): Operation>; /** * Remove one entry this path names, and answer with nothing. * @@ -871,6 +883,10 @@ const composedFiles: FilesApi = createFilesApi({ throw new FilesProviderUnavailableError(); }, // deno-lint-ignore require-yield + *copyFile(_input: FileCopyInput): Operation> { + throw new FilesProviderUnavailableError(); + }, + // deno-lint-ignore require-yield *deleteFile(_input: FilePathInput): Operation> { throw new FilesProviderUnavailableError(); }, diff --git a/packages/runtime/host-files.ts b/packages/runtime/host-files.ts index e3b4a95f2..614e07502 100644 --- a/packages/runtime/host-files.ts +++ b/packages/runtime/host-files.ts @@ -92,7 +92,7 @@ import type { Operation, Result } from "effection"; import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { randomUUID } from "node:crypto"; import { mkdtempSync } from "node:fs"; -import { realpath, rmdir } from "node:fs/promises"; +import { constants, copyFile as nativeCopyFile, realpath, rmdir } from "node:fs/promises"; import { fileURLToPath } from "node:url"; import { tmpdir } from "node:os"; import { FsApi, rm } from "@effectionx/fs"; @@ -100,6 +100,7 @@ import { API } from "./apis.ts"; import { fileWriteFailure, fileWriteSuccess, filesFailure, FilesInvariantError } from "./files.ts"; import { Permissions } from "./permissions.ts"; import type { + FileCopyInput, FilePathInput, FilesHandler, FilesOperation, @@ -121,7 +122,7 @@ import type { * observable rather than merely stated. */ export interface HostFilesEvent { - readonly operation: "read" | "write" | "delete" | "ensure-directory" | "glob"; + readonly operation: "copy" | "read" | "write" | "delete" | "ensure-directory" | "glob"; readonly phase: "target" | "access" | "parents" | "temporary" | "commit" | "cleanup" | "read-dir"; } @@ -130,6 +131,8 @@ export type HostFilesObserver = (event: HostFilesEvent) => void; export interface HostFilesOptions { readonly observe?: HostFilesObserver; + /** Test boundary for the native copy and its settlement. */ + readonly nativeCopy?: typeof nativeCopyFile; readonly access?: HostFilesAccess; /** * The directory temporary directories are minted under, defaulting to the @@ -199,7 +202,7 @@ export function* hostFileAccessReason( } const resolved = operation === "delete" - ? yield* removalDestination(input) + ? yield* entryDestination(input) : operation === "ensure-directory" ? yield* directoryDestination(input) : yield* destination(input); @@ -352,12 +355,10 @@ function* destination(input: FilePathInput): Operation { } /** - * The path a removal would act on, with the final segment left alone. + * The path whose final directory entry a removal or copy addresses. * - * Deletion is the one operation whose target must *not* be resolved. A final - * symbolic link is the entry the document named, and following it would remove - * something the document never mentioned — possibly outside the working - * directory entirely. So only the parent prefix is resolved, and the authored + * A final symbolic link is the entry the document named. Only the parent + * prefix is resolved, and the authored * last segment is put back onto it unresolved. Resolving the parent is what * still catches a directory link leading out; leaving the last segment is what * keeps a link a link. @@ -368,7 +369,7 @@ function* destination(input: FilePathInput): Operation { * an escape. It is classified directly instead, and target classification then * refuses it for what it is. */ -function* removalDestination(input: FilePathInput): Operation { +function* entryDestination(input: FilePathInput): Operation { try { const base = (yield* API.Fs.operations.realpath(input.cwd)) ?? input.cwd; const named = resolve(input.cwd, input.path); @@ -627,6 +628,83 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler { return Ok(fileWriteSuccess("host-committed")); } + function* copyFile(input: FileCopyInput): Operation> { + const source = { cwd: input.cwd, path: input.source }; + const target = { cwd: input.cwd, path: input.destination }; + const lexical = inadmissible(source) ?? inadmissible(target); + if (lexical !== undefined) { + return nonWriteFailure("copy", "lexical", lexical); + } + if ( + !(yield* Permissions.operations.files("read")) || + !(yield* Permissions.operations.files("write")) + ) { + return nonWriteFailure("copy", "resolution", "permission-denied"); + } + + const from = yield* destination(source); + if ("reason" in from) { + return nonWriteFailure("copy", "resolution", from.reason); + } + const to = yield* entryDestination(target); + if ("reason" in to) { + return nonWriteFailure("copy", "resolution", to.reason); + } + if ( + options.access !== undefined && + (!permits(options.access, from.path, false) || !permits(options.access, to.path, true)) + ) { + return nonWriteFailure("copy", "resolution", "resolved-escape"); + } + + notify(observe, { operation: "copy", phase: "target" }); + try { + const info = yield* API.Fs.operations.stat(from.path); + if (!info.exists) { + return nonWriteFailure("copy", "target", "missing"); + } + if (!info.isFile) { + return nonWriteFailure("copy", "target", info.isDirectory ? "directory" : "special-file"); + } + const parent = yield* API.Fs.operations.stat(dirname(to.path)); + if (!parent.exists || !parent.isDirectory) { + return nonWriteFailure("copy", "target", parent.exists ? "not-directory" : "missing"); + } + // Some runtimes follow a dangling final link even with COPYFILE_EXCL. + if ((yield* API.Fs.operations.lstat(to.path)).exists) { + return nonWriteFailure("copy", "target", "occupied"); + } + } catch (error) { + return nonWriteFailure("copy", "target", reasonOf(error)); + } + + notify(observe, { operation: "copy", phase: "access" }); + try { + yield* scoped(function* () { + let pending: Promise | undefined; + yield* ensure(function* () { + if (pending !== undefined) { + yield* until(pending); + } + }); + const operation = options.nativeCopy ?? nativeCopyFile; + const copy = operation(from.path, to.path, constants.COPYFILE_EXCL); + pending = copy.then( + () => undefined, + () => undefined, + ); + yield* until(copy); + }); + return Ok(undefined); + } catch (error) { + return nonWriteFailure( + "copy", + "access", + errorCode(error) === "EEXIST" ? "occupied" : reasonOf(error), + ); + } + } + /** * Remove one regular file or one final symbolic link. * @@ -653,7 +731,7 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler { return nonWriteFailure("delete", "resolution", "permission-denied"); } - const target = yield* removalDestination(input); + const target = yield* entryDestination(input); if ("reason" in target) { return nonWriteFailure("delete", "resolution", target.reason); } @@ -901,6 +979,7 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler { checkFilePath, readTextFile, writeTextFile, + copyFile, deleteFile, ensureDirectory, globFiles, @@ -983,6 +1062,9 @@ export function useHostFiles(options: HostFilesOptions = {}): Operation { *writeTextFile([input]) { return yield* handler.writeTextFile(input); }, + *copyFile([input]) { + return yield* handler.copyFile(input); + }, *deleteFile([input]) { return yield* handler.deleteFile(input); }, diff --git a/packages/runtime/mod.ts b/packages/runtime/mod.ts index 5ece5ca5c..46daef97a 100644 --- a/packages/runtime/mod.ts +++ b/packages/runtime/mod.ts @@ -115,6 +115,7 @@ export { parseFilesFatal, } from "./files.ts"; export type { + FileCopyInput, FilePathInput, FilesDeniableOperation, FilesErrorData, diff --git a/packages/runtime/tests/host-files.test.ts b/packages/runtime/tests/host-files.test.ts index 6b4d044d4..3511e8395 100644 --- a/packages/runtime/tests/host-files.test.ts +++ b/packages/runtime/tests/host-files.test.ts @@ -33,7 +33,16 @@ import { } from "effection"; import type { Operation, Result } from "effection"; import { exists, readTextFile, rm, writeTextFile } from "@effectionx/fs"; -import { lstat, mkdir, mkdtemp, readdir, realpath, symlink } from "node:fs/promises"; +import { + lstat, + mkdir, + mkdtemp, + readFile, + readdir, + realpath, + symlink, + writeFile, +} from "node:fs/promises"; import { renameSync, symlinkSync, unlinkSync } from "node:fs"; import { tmpdir } from "node:os"; import { join, sep } from "node:path"; @@ -1405,6 +1414,26 @@ describe("host Files — permission", () => { }); } + it("copy authorizes both paths before target I/O", function* () { + const fixture = yield* useFixture(); + yield* useHostFiles(); + yield* writeTextFile(join(fixture.workspace, "source"), "fixture"); + const touched: string[] = []; + yield* census(touched); + const request = { cwd: fixture.workspace, source: "source", destination: "destination" }; + for (const denied of ["read", "write"]) { + yield* scoped(function* () { + yield* Permissions.around({ + files: ([operation], next) => (operation === denied ? false : next(operation)), + }); + const result = yield* Files.operations.copyFile(request); + expect(parseFilesFailure(failed(result))?.reason).toBe("permission-denied"); + }); + } + expect(touched).toEqual([]); + expect(yield* exists(join(fixture.workspace, request.destination))).toBe(false); + }); + it("HF absolute: default and explicit denial reach no target; opt-in intersects read/write", function* () { const fixture = yield* useFixture(); const files = handler(); @@ -1747,3 +1776,119 @@ describe("1113: outward session roots", () => { expect(yield* entries(fixture.outside)).toEqual(["canary"]); }); }); + +describe("host Files copy", () => { + it("preserves occupied entries and refuses missing or escaped paths", function* () { + const { workspace, outside } = yield* useFixture(); + yield* useHostFiles(); + const binary = new Uint8Array(8 * 1024 * 1024 + 1); + binary[binary.length - 1] = 0xff; + yield* until(writeFile(join(workspace, "source"), binary)); + yield* writeTextFile(join(workspace, "occupied"), "keep"); + yield* writeTextFile(join(outside, "outside.txt"), "keep outside"); + yield* linkDirectory(outside, join(workspace, "escape")); + yield* until(symlink(join(workspace, "missing"), join(workspace, "dangling"), "file")); + const copy = (source: string, destination: string) => + Files.operations.copyFile({ cwd: workspace, source, destination }); + + for (const [from, to, reason] of [ + ["source", "occupied", "occupied"], + ["source", "dangling", "occupied"], + ["source", "absent/target", "missing"], + ["source", "escape/target", "resolved-escape"], + ["escape/outside.txt", "target", "resolved-escape"], + ]) { + expect(parseFilesFailure(failed(yield* copy(from, to)))?.reason).toBe(reason); + } + expect(yield* readTextFile(join(workspace, "occupied"))).toBe("keep"); + expect((yield* until(lstat(join(workspace, "dangling")))).isSymbolicLink()).toBe(true); + for (const absent of [ + join(workspace, "missing"), + join(workspace, "absent"), + join(workspace, "target"), + join(outside, "target"), + ]) { + expect(yield* exists(absent)).toBe(false); + } + + expect(yield* copy("source", "copy")).toEqual({ ok: true, value: undefined }); + expect((yield* until(readFile(join(workspace, "copy")))).equals(binary)).toBe(true); + expect((yield* until(readFile(join(workspace, "source")))).equals(binary)).toBe(true); + }); + + it("joins a started native copy during halt without returning a Files result", function* () { + const { workspace } = yield* useFixture(); + yield* writeTextFile(join(workspace, "source"), "fixture"); + const started = withResolvers(); + let finish = () => {}; + const pending = new Promise((resolve) => { + finish = resolve; + }); + yield* useHostFiles({ + nativeCopy() { + started.resolve(undefined); + return pending; + }, + }); + let result: Result | undefined; + const task = yield* spawn(function* () { + result = yield* Files.operations.copyFile({ + cwd: workspace, + source: "source", + destination: "destination", + }); + }); + yield* started.operation; + const halted = task.halt(); + try { + const early = yield* race([ + (function* () { + yield* halted; + return true; + })(), + (function* () { + yield* sleep(0); + return false; + })(), + ]); + expect(early).toBe(false); + } finally { + finish(); + } + yield* halted; + expect(result).toBe(undefined); + }); + + it("applies captured roots to both effective copy operands", function* () { + const { root, workspace, outside } = yield* useFixture(); + const access = yield* captureHostFilesAccess({ + project: workspace, + private: join(workspace, "session"), + assets: join(workspace, "session", "assets"), + components: join(workspace, "session", "components"), + }); + yield* until(mkdir(access.assets, { recursive: true })); + yield* writeTextFile(join(access.assets, "source"), "asset"); + yield* writeTextFile(join(outside, "source"), "outside"); + const touched: HostFilesEvent[] = []; + yield* useHostFiles({ access, observe: (event) => touched.push(event) }); + const request = { + cwd: root, + source: "workspace/session/assets/source", + destination: "workspace/copy", + }; + for (const change of [ + { source: "outside/source" }, + { destination: "workspace/session/assets/copy" }, + ]) { + yield* scoped(function* () { + yield* API.Files.around({ copyFile: ([input], next) => next({ ...input, ...change }) }); + const result = yield* Files.operations.copyFile(request); + expect(parseFilesFailure(failed(result))?.reason).toBe("resolved-escape"); + }); + } + expect(touched).toEqual([]); + expect(yield* exists(join(workspace, "copy"))).toBe(false); + expect(yield* exists(join(access.assets, "copy"))).toBe(false); + }); +}); diff --git a/packages/workflow/src/deno/workspace/files.ts b/packages/workflow/src/deno/workspace/files.ts index 7e4377fa6..26dd5ea9e 100644 --- a/packages/workflow/src/deno/workspace/files.ts +++ b/packages/workflow/src/deno/workspace/files.ts @@ -32,6 +32,7 @@ import { parseFileWritePhase, } from "@executablemd/runtime"; import type { + FileCopyInput, FilePathInput, FilesPhase, FilesReason, @@ -121,6 +122,7 @@ function lexicalReason(error: Error): FilesReason { type FileEffectOutcome = | { readonly kind: "content"; readonly content: string } | { readonly kind: "written" } + | { readonly kind: "copied" } | { readonly kind: "deleted" } | { readonly kind: "ensured" } | { readonly kind: "paths"; readonly paths: string[] } @@ -145,6 +147,7 @@ function refused( const OUTCOME_MEMBERS: ReadonlyMap = new Map([ ["content", ["kind", "content"]], ["written", ["kind"]], + ["copied", ["kind"]], ["deleted", ["kind"]], ["ensured", ["kind"]], ["paths", ["kind", "paths"]], @@ -206,6 +209,9 @@ function parseOutcome( if (kind === "written") { return { kind: "written" }; } + if (kind === "copied") { + return { kind: "copied" }; + } if (kind === "deleted") { return { kind: "deleted" }; } @@ -451,6 +457,37 @@ function* writeOutcome( return { kind: "written" }; } +function* copyOutcome( + filesystem: DenoWorkspaceFilesystem, + source: string, + destination: string, +): Operation> { + if ( + !(yield* Permissions.operations.files("read")) || + !(yield* Permissions.operations.files("write")) + ) { + return refused("resolution", "permission-denied"); + } + const info = yield* statPath(filesystem, source); + if (!info.ok) { + return refused("resolution", refusalReason(info.error)); + } + if (info.value.kind !== "file") { + return refused("target", "directory"); + } + try { + const bytes = yield* filesystem.readFile(source); + // The exclusive writer resolves the parent and classifies the final entry + // by dirent before writing, with the same parent inode for both. + yield* savepoint(filesystem.writeFile(destination, bytes, undefined, true)); + return { kind: "copied" }; + } catch (error) { + const reason = + journalableWorkspaceCode(error) === "EEXIST" ? "occupied" : refusalReason(asRefusal(error)); + return refused("access", reason); + } +} + /** * Remove one file, or find that there is nothing to remove. * @@ -633,6 +670,7 @@ export interface WorkflowFilesHandler { checkFilePath(input: FilePathInput): Operation>; readTextFile(input: FilePathInput): Operation>; writeTextFile(input: FileWriteInput): Operation>; + copyFile(input: FileCopyInput): Operation>; deleteFile(input: FilePathInput): Operation>; ensureDirectory(input: FilePathInput): Operation>; globFiles(input: GlobInput): Operation>; @@ -706,6 +744,40 @@ export function workflowFilesHandler(database: WorkflowRunDatabase): WorkflowFil return Ok(fileWriteSuccess("transaction-staged")); }, + *copyFile(input: FileCopyInput): Operation> { + const source = resolveLogicalPath(input.cwd, input.source); + const destination = resolveLogicalPath(input.cwd, input.destination); + const invalid = !source.ok ? source : !destination.ok ? destination : undefined; + if (!source.ok || !destination.ok) { + return Err( + filesFailure({ + operation: "copy", + phase: "lexical", + reason: invalid === undefined ? "operation-failed" : lexicalReason(invalid.error), + }), + ); + } + const outcome = yield* performed( + database, + yield* describeFileEffect("copy", JSON.stringify([source.value, destination.value]), { + cwd: input.cwd, + source: input.source, + destination: input.destination, + }), + parseFilesPhase, + (filesystem) => copyOutcome(filesystem, source.value, destination.value), + ); + if (outcome.kind === "refused") { + return Err( + filesFailure({ operation: "copy", phase: outcome.phase, reason: outcome.reason }), + ); + } + if (outcome.kind !== "copied") { + throw new FilesInvariantError("protocol"); + } + return Ok(undefined); + }, + *deleteFile(input: FilePathInput): Operation> { const resolved = resolveLogicalPath(input.cwd, input.path); if (!resolved.ok) { @@ -824,6 +896,9 @@ export function useWorkflowFiles(database: WorkflowRunDatabase): Operation *writeTextFile([input]) { return yield* handler.writeTextFile(input); }, + *copyFile([input]) { + return yield* handler.copyFile(input); + }, *deleteFile([input]) { return yield* handler.deleteFile(input); }, diff --git a/packages/workflow/src/deno/workspace/filesystem.ts b/packages/workflow/src/deno/workspace/filesystem.ts index 1ae4087a1..d9fa958b7 100644 --- a/packages/workflow/src/deno/workspace/filesystem.ts +++ b/packages/workflow/src/deno/workspace/filesystem.ts @@ -36,7 +36,12 @@ export interface DenoWorkspaceFilesystem { lstat(path: string): Operation; readlink(path: string): Operation; readdir(path: string): Operation; - writeFile(path: string, content: string | Uint8Array, mode?: number): Operation; + writeFile( + path: string, + content: string | Uint8Array, + mode?: number, + exclusive?: boolean, + ): Operation; mkdir(path: string, options?: { recursive?: boolean; mode?: number }): Operation; remove(path: string, options?: { recursive?: boolean; force?: boolean }): Operation; rename(from: string, to: string): Operation; @@ -120,14 +125,14 @@ export function createDenoWorkspaceFilesystem( })); }, - *writeFile(path, content, mode): Operation { + *writeFile(path, content, mode, exclusive): Operation { const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content; execute(() => // The write belongs to the caller's savepoint on the same synchronous // SQLite connection; suspending inside it would let another operation // commit between the rows this single write is meant to place together. // oxlint-disable-next-line local/no-sync-filesystem - writeFileSync(dofs, path, bytes, mode === undefined ? {} : { mode }, filesystem.now), + writeFileSync(dofs, path, bytes, { mode, exclusive }, filesystem.now), ); }, diff --git a/packages/workflow/src/deno/workspace/guard.ts b/packages/workflow/src/deno/workspace/guard.ts index b42786b4a..40911196d 100644 --- a/packages/workflow/src/deno/workspace/guard.ts +++ b/packages/workflow/src/deno/workspace/guard.ts @@ -94,8 +94,8 @@ export function guardedWorkflowWorkspaceFilesystem( ): DenoWorkspaceFilesystem { return { ...guardedWorkflowWorkspaceReads(filesystem, held), - writeFile: (path, content, mode) => - gatedOperation(held, () => filesystem.writeFile(path, content, mode)), + writeFile: (path, content, mode, exclusive) => + gatedOperation(held, () => filesystem.writeFile(path, content, mode, exclusive)), mkdir: (path, options) => gatedOperation(held, () => filesystem.mkdir(path, options)), remove: (path, options) => gatedOperation(held, () => filesystem.remove(path, options)), rename: (from, to) => gatedOperation(held, () => filesystem.rename(from, to)), diff --git a/packages/workflow/tests/generated-agent-component.test.ts b/packages/workflow/tests/generated-agent-component.test.ts index 28be4fedb..399e4d33a 100644 --- a/packages/workflow/tests/generated-agent-component.test.ts +++ b/packages/workflow/tests/generated-agent-component.test.ts @@ -1317,6 +1317,48 @@ describe("Tier WGAC — the standard write table", () => { }); }); + it("WGAC15: an unoffered File.Copy stops an earlier admitted deletion", function* () { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + yield* plant(database, "obsolete.md", "sentinel"); + const reached: string[] = []; + const attempt = yield* scoped(function* () { + yield* API.Files.around({ + *deleteFile([input], next) { + reached.push("delete"); + return yield* next(input); + }, + *copyFile([input], next) { + reached.push("copy"); + return yield* next(input); + }, + }); + return yield* runDocument( + database, + evaluates( + '\n\n', + ["write"], + ), + ); + }); + expect(reported(attempt)).toBe( + "a generated fragment names a component this host did not admit.", + ); + expect(reached).toEqual([]); + expect( + attempt.events.filter( + (event) => + event.type === "yield" && + event.description.type === "workspace_file" && + /^(delete|copy):/.test(event.description.name), + ), + ).toEqual([]); + expect(yield* stored(database, "/obsolete.md")).toBe("sentinel"); + expect(yield* stored(database, "/copy.md")).toBe(undefined); + }); + }); + it("WGAC10: a self-closing File is not admitted by the write table", function* () { const root = yield* useStorageRoot(); yield* withStorage(root, function* () { diff --git a/packages/workflow/tests/workspace-files.test.ts b/packages/workflow/tests/workspace-files.test.ts index ef75a9cd3..c69c343e5 100644 --- a/packages/workflow/tests/workspace-files.test.ts +++ b/packages/workflow/tests/workspace-files.test.ts @@ -243,13 +243,13 @@ function refusingWrite( ): (filesystem: DenoWorkspaceFilesystem) => DenoWorkspaceFilesystem { return (filesystem) => ({ ...filesystem, - *writeFile(path, content, mode) { + *writeFile(path, content, mode, exclusive) { if (path === target) { throwWorkspaceFilesystemFailure( Object.assign(new Error("planted"), { name: "WorkspaceFsError", code: "EACCES" }), ); } - yield* filesystem.writeFile(path, content, mode); + yield* filesystem.writeFile(path, content, mode, exclusive); }, }); } @@ -279,9 +279,9 @@ function countingWrites( ): (filesystem: DenoWorkspaceFilesystem) => DenoWorkspaceFilesystem { return (filesystem) => ({ ...filesystem, - *writeFile(path, content, mode) { + *writeFile(path, content, mode, exclusive) { written.push(path); - yield* filesystem.writeFile(path, content, mode); + yield* filesystem.writeFile(path, content, mode, exclusive); }, }); } @@ -356,8 +356,8 @@ function suspendingWrite( ): (filesystem: DenoWorkspaceFilesystem) => DenoWorkspaceFilesystem { return (filesystem) => ({ ...filesystem, - *writeFile(path, content, mode) { - yield* filesystem.writeFile(path, content, mode); + *writeFile(path, content, mode, exclusive) { + yield* filesystem.writeFile(path, content, mode, exclusive); if (path === target) { reached.resolve(); yield* suspend(); @@ -1763,17 +1763,17 @@ describe("Tier WF — the run's own directories", () => { * to win. What these assert is that current policy decides new work and says * nothing about work the journal already holds. */ -describe("workflow document filesystem — permission", () => { - /** Refuse one class of operation, recording every question asked. */ - function restricted(asked: string[], refuse: "read" | "write"): Operation { - return Permissions.around({ - files: ([operation], next) => { - asked.push(operation); - return operation === refuse ? false : next(operation); - }, - }); - } +/** Refuse one class of operation, recording every question asked. */ +function restricted(asked: string[], refuse: "read" | "write"): Operation { + return Permissions.around({ + files: ([operation], next) => { + asked.push(operation); + return operation === refuse ? false : next(operation); + }, + }); +} +describe("workflow document filesystem — permission", () => { it("WF27: a denied write is published as an ordinary refusal and keeps the root", function* () { const root = yield* useStorageRoot(); yield* withStorage(root, function* () { @@ -1918,3 +1918,190 @@ describe("workflow document filesystem — permission", () => { ); }); }); + +describe("Workspace file copy", () => { + const doc = ''; + const target = JSON.stringify(["/source.bin", "/destination.bin"]); + const bytes = Uint8Array.of(0, 255, 128); + + function* seed(database: WorkflowRunDatabase): Operation { + yield* mutateWorkspace(database, function* (workspace) { + yield* workspace.filesystem.writeFile("/source.bin", bytes); + }); + } + + function read(database: WorkflowRunDatabase, path: string) { + return transactWorkspaceRoots(database, (workspace) => workspace.filesystem.readFile(path)); + } + + it("publishes exact independent bytes, Unit, and the resulting root", function* () { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + expect(yield* read(database, "/destination.bin")).toEqual({ ok: true, value: bytes }); + expect((yield* recordedFileEffects(database)).map((effect) => effect.result)).toEqual([ + { status: "ok", value: { kind: "copied" } }, + ]); + expect(committedEffects(path, "copy", target)).toBe(1); + expect(committedRoot(path)).toEqual(rootOfLastEvent(path)); + yield* mutateWorkspace(database, function* (workspace) { + yield* workspace.filesystem.writeFile("/destination.bin", "changed"); + }); + expect(yield* read(database, "/source.bin")).toEqual({ ok: true, value: bytes }); + }); + }); + + it("publishes ordinary refusals without changing the frontier", function* () { + for (const denied of ["read", "write", "occupied"]) { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + if (denied === "occupied") { + yield* mutateWorkspace(database, function* (workspace) { + yield* workspace.filesystem.writeFile("/destination.bin", "keep"); + }); + } + const before = committedRoot(path); + yield* scoped(function* () { + if (denied === "read" || denied === "write") { + yield* restricted([], denied); + } + yield* runDocument(database, doc); + }); + const reason = denied === "occupied" ? "occupied" : "permission-denied"; + expect((yield* recordedFileEffects(database))[0]?.result).toEqual({ + status: "ok", + value: { + kind: "refused", + phase: denied === "occupied" ? "access" : "resolution", + reason, + }, + }); + expect(committedRoot(path)).toBe(before); + if (denied === "occupied") { + expect(yield* workspaceText(database, "/destination.bin")).toBe("keep"); + } else { + expect((yield* read(database, "/destination.bin")).ok).toBe(false); + } + }); + } + }); + + it("rolls back an unpublished copy and performs it once on continuation", function* () { + const root = yield* useStorageRoot(); + let fail = true; + let copied = 0; + yield* withStorage( + root, + function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + const before = committedRoot(path); + expect(yield* raised(runDocument(database, doc))).toBeInstanceOf(Error); + expect(committedRoot(path)).toBe(before); + expect((yield* read(database, "/destination.bin")).ok).toBe(false); + expect(yield* recordedFileEffects(database)).toEqual([]); + expect(copied).toBe(1); + + fail = false; + yield* replayDocument(database, doc); + expect(copied).toBe(2); + expect(committedEffects(path, "copy", target)).toBe(1); + expect(yield* read(database, "/destination.bin")).toEqual({ ok: true, value: bytes }); + }, + { + decorateFilesystem: (filesystem) => ({ + ...filesystem, + *writeFile(path, content, mode, exclusive) { + yield* filesystem.writeFile(path, content, mode, exclusive); + if (exclusive) { + copied += 1; + if (fail) { + throw new Error("planted failure after the copy"); + } + } + }, + }), + }, + ); + }); + + it("restores an acknowledged copy without live access or a second publication", function* () { + const root = yield* useStorageRoot(); + const writes: string[] = []; + yield* withStorage( + root, + function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + const frontier = committedRoot(path); + dropRootClose(path); + const asked: string[] = []; + yield* scoped(function* () { + yield* restricted(asked, "write"); + yield* replayDocument(database, doc); + }); + expect(asked).toEqual([]); + expect(writes).toEqual(["/source.bin", "/destination.bin"]); + expect(committedRoot(path)).toBe(frontier); + expect(committedEffects(path, "copy", target)).toBe(1); + }, + { decorateFilesystem: countingWrites(writes) }, + ); + }); + + it("rejects a changed source or destination before the live copy", function* () { + for (const change of [{ source: "changed.bin" }, { destination: "changed.bin" }]) { + const root = yield* useStorageRoot(); + const writes: string[] = []; + yield* withStorage( + root, + function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + const frontier = committedRoot(path); + dropRootClose(path); + const failure = yield* scoped(function* () { + yield* API.Files.around({ + copyFile: ([input], next) => next({ ...input, ...change }), + }); + return yield* raised(replayDocument(database, doc)); + }); + expect(String(failure)).toContain("changed.bin"); + expect(writes).toEqual(["/source.bin", "/destination.bin"]); + expect(committedRoot(path)).toBe(frontier); + expect(committedEffects(path, "copy", target)).toBe(1); + }, + { decorateFilesystem: countingWrites(writes) }, + ); + } + }); + + it("refuses a malformed retained copy success", function* () { + const root = yield* useStorageRoot(); + yield* withStorage(root, function* () { + const database = yield* createRun(); + const path = runPath(root, database.record.runId); + yield* seed(database); + yield* runDocument(database, doc); + dropRootClose(path); + plantOutcome(path, "copy", target, { kind: "copied", path: "/destination.bin" }); + const failure = yield* raised(replayDocument(database, doc)); + expect(parseFilesFatal(fatalOf(failure))).toEqual({ + type: FILES_FATAL, + kind: "invariant", + category: "protocol", + }); + }); + }); +}); diff --git a/scripts/bench-repl-file-dir.ts b/scripts/bench-repl-file-dir.ts index a7f245fda..c1c799051 100644 --- a/scripts/bench-repl-file-dir.ts +++ b/scripts/bench-repl-file-dir.ts @@ -171,6 +171,7 @@ function counters(): Counters { function countingFiles(counted: Counters): FilesHandler { const host = hostFilesHandler(); return { + copyFile: (input) => host.copyFile(input), *checkFilePath(input: FilePathInput) { counted.checks += 1; return yield* host.checkFilePath(input); @@ -380,6 +381,7 @@ function measure( globFiles: ([input]) => files.globFiles(input), temporaryDirectory: () => files.temporaryDirectory(), writeTextFile: ([input]) => files.writeTextFile(input), + copyFile: ([input]) => files.copyFile(input), deleteFile: ([input]) => files.deleteFile(input), ensureDirectory: ([input]) => files.ensureDirectory(input), }, diff --git a/scripts/files-contract-probe.ts b/scripts/files-contract-probe.ts index 2f3e13d82..0ac77b7dc 100644 --- a/scripts/files-contract-probe.ts +++ b/scripts/files-contract-probe.ts @@ -19,7 +19,7 @@ import { ensureDir, exists, readTextFile, writeTextFile } from "@effectionx/fs"; import { exit, main, scoped, until } from "effection"; import type { Result } from "effection"; -import { lstat, realpath, symlink } from "node:fs/promises"; +import { lstat, readFile, realpath, symlink, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { useTempDirectory } from "./lib/temp-directory.ts"; import process from "node:process"; @@ -87,6 +87,24 @@ await main(function* () { yield* useHostFiles(); + const binary = Uint8Array.of(0, 255, 128); + const copy = { cwd: workspace, source: "source.bin", destination: "destination.bin" }; + yield* until(writeFile(join(workspace, copy.source), binary)); + check("native copy returns Unit", (yield* Files.operations.copyFile(copy)).ok); + check( + "native copy preserves bytes", + (yield* until(readFile(join(workspace, copy.destination)))).equals(binary), + ); + yield* until(writeFile(join(workspace, copy.destination), Uint8Array.of(42))); + check( + "native copy refuses occupancy", + reasonOf(yield* Files.operations.copyFile(copy)) === "occupied", + ); + check( + "native copy preserves an occupied destination", + (yield* until(readFile(join(workspace, copy.destination)))).equals(Uint8Array.of(42)), + ); + check( "an empty path is refused lexically", reasonOf(yield* Files.operations.checkFilePath({ cwd: workspace, path: "" })) === "empty-path", diff --git a/scripts/lib/markdown-suites.ts b/scripts/lib/markdown-suites.ts index 83e796c46..957aeb217 100644 --- a/scripts/lib/markdown-suites.ts +++ b/scripts/lib/markdown-suites.ts @@ -7,6 +7,7 @@ interface DocumentSuite { /** The documents whose TypeScript launchers used the ordinary CLI profile. */ export const DOCUMENT_SUITES: ReadonlyMap = new Map([ ["packages/cli/tests/document-suites/evaluate/Evaluate.test.md", {}], + ["packages/cli/tests/document-suites/file-copy/FileCopy.test.md", {}], ["packages/cli/tests/document-suites/inline/Inline.test.md", {}], ["packages/cli/tests/document-suites/plan/Plan.test.md", { worker: true }], ["packages/cli/tests/document-suites/props/Props.test.md", {}], diff --git a/scripts/tests/test-file-discovery.test.ts b/scripts/tests/test-file-discovery.test.ts index 5c3e78428..a69fb0287 100644 --- a/scripts/tests/test-file-discovery.test.ts +++ b/scripts/tests/test-file-discovery.test.ts @@ -126,6 +126,7 @@ describe("the Markdown suites", () => { ), ).toEqual([ "packages/cli/tests/document-suites/evaluate/Evaluate.test.md", + "packages/cli/tests/document-suites/file-copy/FileCopy.test.md", "packages/cli/tests/document-suites/inline/Inline.test.md", "packages/cli/tests/document-suites/plan/Plan.test.md", "packages/cli/tests/document-suites/props/Props.test.md", diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index d42a61034..ebde99849 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -9878,6 +9878,39 @@ semantics belong to the provider: `specs/workflow-workspace-spec.md` §§6.3 and --- +### 6.13.3 Copying a file: `` + +```mdx + +``` + +Core supplies `File.Copy` as an ordinary default. The canonical dispatcher +requires self-closing form and refuses paired form before expanding its +content. Both props are required nonempty strings. The component calls +`API.Files.copyFile({ cwd, source, destination })` once with the contextual +working directory. Success is Unit and renders nothing. Ordinary filesystem +refusals use the Files reporting rules in §6.13. + +The performing provider authorizes read access to the effective source and +write access to the effective destination after middleware and before target +I/O. Each path is relative and subject to the provider's lexical and resolved +containment. The source must be a regular file. The destination requires an +existing directory and a vacant final entry. A dangling final link counts as +occupied. A successful copy preserves every source byte in an independent file. +A refusal for occupancy preserves the existing entry. + +Ordinary runs and host-backed Markdown tests use native exclusive copy under +the stable pathname namespace contract. The host checks the final entry +without following it and joins a started copy during cancellation. +An ordinary run starts fresh. Low-level partial host replay that reaches copy +performs it live. Completed-root replay returns the saved outcome without +expansion. [Workflow Workspace](workflow-workspace-spec.md#101-workspace-local-effects) +restores a published effect. [Retained REPL](repl-spec.md#the-files-an-entry-wrote-in-the-checkout-you-are-standing-in) +restores an acknowledged result within covered storage. + +Named `xmd syntax File.Copy` describes the props, form, and provider behavior. +Generated XMD requires a separate trusted offer for the name and form. + ### 6.14 Finding files: `` A document decides what to work on by looking at what is there. `` is diff --git a/specs/repl-spec.md b/specs/repl-spec.md index d7b8cda15..27cd10864 100644 --- a/specs/repl-spec.md +++ b/specs/repl-spec.md @@ -2286,14 +2286,28 @@ uncertain append establishes no saved value or Unit. Start the REPL inside a Git checkout and an entry's file work is retained too, under the ordinary physical records. The prospective mapped class above uses its -closed association record. Four operations are -kept: a self-closing `` text read; a paired +closed association record. The physical records keep a self-closing `` text read; a paired `…` write, after its content has expanded; a self-closing -``; and the directory a paired `…` +``; a self-closing ``; and the directory a paired `…` ensures, before its content is entered. The reads, writes and deletions an admitted `` fragment performs are kept on the same terms, because a fragment's operations go to the same document filesystem an authored one does. +A copy uses the physical record even when its working directory came from a +mount. Its identity binds the received working directory and both ordered +operands. Acknowledged Unit and ordinary refusals restore before permissions, +path observations, discovery, placement slots or mutation holds. A changed +operand at that retained position diverges before live routing, including when +the new destination lies outside coverage. + +For a live copy, the resolved destination parent determines coverage and the +final entry stays intact for classification. Covered managed operands use +their placement slots. The destination alone determines the checkout mutation +hold. Owned-root coverage requires no Git lease. Outside coverage the copy is +live and unrecorded. If native copy completed before an unacknowledged append, +a continuation attempts the operation live. An occupied destination then +produces an ordinary refusal with its bytes intact. + What that buys is the one thing experimentation needs: leave an entry at a question, come back to the printed location, and the work it already did is not done again. The question is offered again, and the write after it happens for diff --git a/specs/testing-spec.md b/specs/testing-spec.md index bffc6eb6b..14c137497 100644 --- a/specs/testing-spec.md +++ b/specs/testing-spec.md @@ -819,6 +819,7 @@ A Markdown suite is a regular `*.test.md` file directly inside these registered paths: - `packages/cli/tests/document-suites/evaluate/Evaluate.test.md` +- `packages/cli/tests/document-suites/file-copy/FileCopy.test.md` - `packages/cli/tests/document-suites/inline/Inline.test.md` - `packages/cli/tests/document-suites/plan/Plan.test.md` - `packages/cli/tests/document-suites/props/Props.test.md` diff --git a/specs/workflow-workspace-spec.md b/specs/workflow-workspace-spec.md index 034219b07..14f10bdcf 100644 --- a/specs/workflow-workspace-spec.md +++ b/specs/workflow-workspace-spec.md @@ -2369,6 +2369,10 @@ current sandbox. ### 8.4 Generated XMD +Authored `File.Copy` is available in Core. The standard generated selection +does not offer it. Preflight refuses its use in that selection before any +earlier admitted operation performs an effect. + A Prompt may return an XMD fragment rather than an ad hoc file-operation schema. The fragment is untrusted input: it carries data, never authorization. Only the trusted workflow host offers the vocabulary, and it does so through the ordinary @@ -3078,6 +3082,20 @@ cwd scope: later content failure or cancellation restores the enclosing cwd but does not remove the directory. `` neither reads nor changes the Repository selection in scope. +**Document copy** uses one `workspace_file` effect whose name binds the +expansion, the copy operation, and the ordered pair of resolved logical paths. +The live performer checks source read and destination write permission before +filesystem lookup. It reads the regular source as bytes and uses the logical +filesystem's exclusive writer to require an existing parent and a vacant +final entry. The writer uses the same parent inode for classification and +insertion and creates an independent file. + +A completed copy retains exactly `{ kind: "copied" }`. An ordinary refusal +retains `{ kind: "refused", phase, reason }`. Mutation, resulting root and +filtered result use the transaction described above. Replay restores a +published outcome before current permission or filesystem access. A copy +without a published outcome runs against the retained frontier. + **Document deletion** is one of them. `` (executable-mdx-spec §6.13.1) removes one file from the run's Workspace, resolving its path inside the logical filesystem so no host path is ever produced. One regular file or one From 3c9c5ecf62a300bd5965a3fb3834aba0918b5185 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 21:20:16 -0500 Subject: [PATCH 2/8] Correct retained File.Copy routing and replay --- packages/cli/src/repl/file-recorder.ts | 177 +++++++++++------- .../cli/src/repl/repositories/admission.ts | 19 +- .../cli/src/repl/repositories/deno/files.ts | 107 +++++++---- .../cli/src/repl/repositories/deno/local.ts | 72 ++++--- packages/cli/src/repl/repositories/records.ts | 42 ++++- .../src/repl/workspace-mount-installation.ts | 77 ++++---- packages/cli/tests/repl-repositories.test.ts | 137 +++++++++----- .../tests/retained-repository-local.test.ts | 137 +++++++++++++- .../tests/retained-repository-records.test.ts | 47 ++++- packages/runtime/files-host.ts | 17 ++ packages/runtime/host-files.ts | 2 + specs/repl-spec.md | 33 ++-- 12 files changed, 636 insertions(+), 231 deletions(-) diff --git a/packages/cli/src/repl/file-recorder.ts b/packages/cli/src/repl/file-recorder.ts index 358d5e47b..f73000e5b 100644 --- a/packages/cli/src/repl/file-recorder.ts +++ b/packages/cli/src/repl/file-recorder.ts @@ -1,9 +1,6 @@ -import { Err, Ok } from "effection"; +import { createContext, Err, Ok, scoped, useScope } from "effection"; import type { Operation, Result } from "effection"; import { - API, - Permissions, - hostFileAccessReason, FilesInvariantError, filesFailure, fileWriteFailure, @@ -12,15 +9,28 @@ import { parseFileWriteSuccess, } from "@executablemd/runtime"; import type { - HostFilesAccess, + FileCopyInput, FilesHandler, FilesOperation, FilesPhase, FilePathInput, FileWriteSuccess, } from "@executablemd/runtime"; -import { registerFileRecorder, assembleFileCall } from "@executablemd/runtime/files-host"; -import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path"; +import { + registerFileRecorder, + assembleFileCall, + withHostCopyRoute, +} from "@executablemd/runtime/files-host"; +import { + checkCopyPublication, + copyReplayContext, + recordedLocalOperation, + retainedCopyAhead, + ReplLocalRecordError, + retainedSelectionAhead, + failCopy, +} from "./repositories/deno/local.ts"; +import type { LocalOperation } from "./repositories/deno/local.ts"; import type { Around } from "@effectionx/context-api"; import type { AuthoredFileOperation } from "@executablemd/core/host"; import type { @@ -39,7 +49,80 @@ export interface EntryFileCalls { read(authored: AuthoredFileOperation, input: FilePathInput): Operation>; ensure(authored: AuthoredFileOperation, input: FilePathInput): Operation>; } -function recordingBody(route: FileRecordingRoute) { +interface CopyRouting { + guard(): Operation; + restoreSelection?(): Operation; + route(source: string, destination: string): Operation | undefined>; +} + +function copyRecorder(routing: CopyRouting) { + const nextOrdinal = new Map(); + return function* ( + input: FileCopyInput, + perform: () => Operation>, + ): Operation> { + const context = yield* copyReplayContext(); + const ordinal = nextOrdinal.get(context.coroutineId) ?? 0; + nextOrdinal.set(context.coroutineId, ordinal + 1); + const identity: Pick = { + operation: "file-copy", + ordinal, + request: { cwd: input.cwd, source: input.source, path: input.destination }, + }; + yield* routing.guard(); + if (routing.restoreSelection !== undefined && (yield* retainedSelectionAhead())) { + yield* routing.restoreSelection(); + } + if (yield* retainedCopyAhead(ordinal)) { + const result = yield* recordedLocalOperation({ + ...identity, + *perform() { + throw new ReplLocalRecordError("Cannot perform a retained file-copy occurrence live."); + }, + }); + return result.ok ? Ok(undefined) : result; + } + + let covered = false; + let result: Result; + try { + result = yield* scoped(() => + withHostCopyRoute( + function* (source, destination) { + yield* copyReplayContext(); + const hold = yield* routing.route(source, destination); + if (hold !== undefined) { + yield* checkCopyPublication(); + yield* hold; + covered = true; + } + yield* copyReplayContext(); + }, + (function* () { + return yield* unitOutcome(perform(), { operation: "copy", phase: "access" }); + })(), + ), + ); + } catch (error) { + throw yield* failCopy(error); + } + yield* copyReplayContext(); + if (covered) { + result = yield* recordedLocalOperation({ + ...identity, + perform: function* () { + return result; + }, + }); + } + return result.ok ? Ok(undefined) : result; + }; +} + +function recordingBody( + route: FileRecordingRoute, + copy: ReturnType | undefined, +) { return { *read( input: FilePathInput, @@ -76,14 +159,11 @@ function recordingBody(route: FileRecordingRoute) { const result = yield* route("file-write", { ...input }, () => writeOutcome(next(input))); return result.ok ? Ok(expectWritten(result.value)) : result; }, - *copyFile([input], next) { - const result = yield* route( - "file-copy", - { cwd: input.cwd, source: input.source, path: input.destination }, - () => unitOutcome(next(input), { operation: "copy", phase: "access" }), - ); - return result.ok ? Ok(undefined) : result; - }, + ...(copy === undefined + ? {} + : { + copyFile: ([input], next) => copy(input, () => next(input)), + }), *deleteFile([input], next) { const result = yield* route("file-delete", { ...input }, () => unitOutcome(next(input), { operation: "delete", phase: "access" }), @@ -94,8 +174,17 @@ function recordingBody(route: FileRecordingRoute) { }, }; } -export function* useEntryFileRecorder(route: FileRecordingRoute): Operation { - const body = recordingBody(route); +const entryCopyInstalled = createContext("executablemd.repl.entry-copy-installed"); + +export function* useEntryFileRecorder( + route: FileRecordingRoute, + copy: CopyRouting, +): Operation { + // Repository initialization can precede mount fallback in the same execution. + const scope = yield* useScope(); + const alreadyInstalled = scope.hasOwn(entryCopyInstalled); + scope.set(entryCopyInstalled, true); + const body = recordingBody(route, alreadyInstalled ? undefined : copyRecorder(copy)); const handle = yield* registerFileRecorder(body.boundary()); const read = assembleFileCall(handle, "readTextFile"); const ensure = assembleFileCall(handle, "ensureDirectory"); @@ -106,58 +195,6 @@ export function* useEntryFileRecorder(route: FileRecordingRoute): Operation ensure(input), authored), }); } -export function* liveCopyTargets( - request: ReplLocalRequest, - access: HostFilesAccess | undefined, -): Operation> { - const { cwd, source, path } = request; - if (source === undefined) { - throw new FilesInvariantError("protocol"); - } - for (const operand of [source, path]) { - const suffix = relative(cwd, resolve(cwd, operand)); - const reason = - operand === "" - ? "empty-path" - : isAbsolute(operand) - ? "absolute-path" - : suffix === ".." || suffix.startsWith(".." + sep) || isAbsolute(suffix) - ? "lexical-escape" - : undefined; - if (reason !== undefined) { - return Err(filesFailure({ operation: "copy", phase: "lexical", reason })); - } - } - if ( - !(yield* Permissions.operations.files("read")) || - !(yield* Permissions.operations.files("write")) - ) { - return Err( - filesFailure({ operation: "copy", phase: "resolution", reason: "permission-denied" }), - ); - } - const reason = - (yield* hostFileAccessReason(access, "read", { cwd, path: source })) ?? - (yield* hostFileAccessReason(access, "delete", { cwd, path })); - if (reason !== undefined) { - return Err(filesFailure({ operation: "copy", phase: "resolution", reason })); - } - - const from = resolve(cwd, source); - const to = resolve(cwd, path); - const parent = dirname(to); - // The final destination entry can itself be a link. Its parent owns the copy. - try { - return Ok({ - source: (yield* API.Fs.operations.realpath(from)) ?? from, - destination: resolve((yield* API.Fs.operations.realpath(parent)) ?? parent, basename(to)), - }); - } catch { - // The performing provider reports resolution failures in the Files vocabulary. - return Ok({ source: from, destination: to }); - } -} - function* writeOutcome(call: Operation>): Operation> { const produced: unknown = yield* call; const settled = settlement(produced); diff --git a/packages/cli/src/repl/repositories/admission.ts b/packages/cli/src/repl/repositories/admission.ts index 641d13982..d3f5a6b1e 100644 --- a/packages/cli/src/repl/repositories/admission.ts +++ b/packages/cli/src/repl/repositories/admission.ts @@ -115,6 +115,7 @@ export function* admitReplRepositoryHistory(retained: readonly DurableEvent[]): // checkout it read, and nothing outside this snapshot may authorize one: the // route has to be a placement a preceding record in the same history made. const placements: ReplPlacement[] = []; + const lastCopy = new Map(); for (const event of retained) { if (event.type !== "yield") { continue; @@ -162,7 +163,13 @@ export function* admitReplRepositoryHistory(retained: readonly DurableEvent[]): yield* admitObservation(payload, event.description.name, placements); continue; } - yield* admitLocal(payload, event.description.name); + const ordinal = yield* admitLocal(payload, event.description.name); + if (ordinal !== undefined) { + if (ordinal <= (lastCopy.get(event.coroutineId) ?? -1)) { + throw malformed(REPL_REPOSITORY_LOCAL); + } + lastCopy.set(event.coroutineId, ordinal); + } } } @@ -244,21 +251,19 @@ function* admitObservation( } } -function* admitLocal(payload: unknown, name: string): Operation { +function* admitLocal(payload: unknown, name: string): Operation { const record = parseReplLocalRecord(payload); if (record === undefined) { throw malformed(REPL_REPOSITORY_LOCAL); } - const fingerprint = yield* replLocalFingerprint({ - operation: record.operation, - request: record.request, - }); + const fingerprint = yield* replLocalFingerprint(record); if (record.fingerprint !== fingerprint) { throw changed(REPL_REPOSITORY_LOCAL); } - if (name !== replLocalRecordName({ operation: record.operation, fingerprint })) { + if (name !== replLocalRecordName(record)) { throw misnamed(REPL_REPOSITORY_LOCAL); } + return record.ordinal; } /** diff --git a/packages/cli/src/repl/repositories/deno/files.ts b/packages/cli/src/repl/repositories/deno/files.ts index d77ba8498..a91186a23 100644 --- a/packages/cli/src/repl/repositories/deno/files.ts +++ b/packages/cli/src/repl/repositories/deno/files.ts @@ -1,7 +1,7 @@ import { hostFileAccessReason, fileWriteFailure } from "@executablemd/runtime"; import type { HostFilesAccess } from "@executablemd/runtime"; import type { AwaitedMountPolicy } from "../../mount-files.ts"; -import { liveCopyTargets, useEntryFileRecorder } from "../../file-recorder.ts"; +import { useEntryFileRecorder } from "../../file-recorder.ts"; import type { MountFileEntry } from "../../workspace-mount-installation.ts"; import type { WorkspaceMountTable } from "../../../workspace-mounts.ts"; import type { AuthoredFileOperation } from "@executablemd/core/host"; @@ -49,7 +49,7 @@ import { createMountPolicy } from "../../mount-files.ts"; */ import type { Operation, Result } from "effection"; -import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"; +import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { realpath } from "node:fs/promises"; import { Err, until } from "effection"; import { filesFailure, Permissions } from "@executablemd/runtime"; @@ -143,15 +143,10 @@ function* routed( return yield* replay; } } - if (yield* retainedResultAhead(name, operation)) { + if (yield* retainedResultAhead(name)) { return yield* recordedLocalOperation({ operation, request, perform }); } - const copy = operation === "file-copy" ? yield* liveCopyTargets(request, access) : undefined; - if (copy !== undefined && !copy.ok) { - return copy; - } - if ( operation === "dir-ensure" && isAbsolute(request.path) && @@ -167,20 +162,17 @@ function* routed( ); } - const reason = - copy === undefined - ? yield* hostFileAccessReason( - access, - operation === "file-read" - ? "read" - : operation === "file-write" - ? "write" - : operation === "file-delete" - ? "delete" - : "ensure-directory", - request, - ) - : undefined; + const reason = yield* hostFileAccessReason( + access, + operation === "file-read" + ? "read" + : operation === "file-write" + ? "write" + : operation === "file-delete" + ? "delete" + : "ensure-directory", + request, + ); if (reason !== undefined) { return Err( operation === "file-write" @@ -202,15 +194,8 @@ function* routed( authored === undefined || mounts === undefined ? recordedLocalOperation({ operation, request, perform }) : mounts.record(authored, request, perform, coverage); - const target = copy?.value.destination ?? (yield* targetOf(request)); - const placements = recorder.placements(); - const managed = covering(placements, target); - if (copy !== undefined) { - const source = covering(placements, copy.value.source); - if (source !== undefined && source !== managed) { - yield* source.own(); - } - } + const target = yield* targetOf(request); + const managed = covering(recorder.placements(), target); if (managed !== undefined) { // Placement ownership first, and for a read as much as for a write: what it // answers is that one entry at a time owns this managed checkout, which an @@ -331,7 +316,51 @@ function* canonical(directory: string): Operation { */ function inside(checkoutRoot: string, target: string): boolean { const at = relative(checkoutRoot, target); - return at !== "" && !at.startsWith("..") && !isAbsolute(at); + return at !== "" && at !== ".." && !at.startsWith(".." + sep) && !isAbsolute(at); +} + +function* copyRoute( + recorder: ReplLocalRecorder, + source: string, + destination: string, + roots: readonly string[], +): Operation | undefined> { + const placements = recorder.placements(); + const read = covering(placements, source); + const write = covering(placements, destination); + const checkout = write === undefined ? yield* recorder.selection() : undefined; + const hold = + write?.commonDirectory ?? + (checkout !== undefined && inside(checkout.checkoutRoot, destination) + ? checkout.commonDirectory + : undefined); + let owned = false; + if (hold === undefined) { + for (const directory of roots) { + const root = yield* canonical(directory); + if (root === destination || inside(root, destination)) { + owned = true; + break; + } + } + } + if (hold === undefined && !owned) { + if (read !== undefined) { + yield* read.own(); + } + return undefined; + } + return (function* () { + if (read !== undefined && read !== write) { + yield* read.own(); + } + if (write !== undefined) { + yield* write.own(); + } + if (hold !== undefined) { + yield* recorder.hold(hold); + } + })(); } export function* useReplFileRecorder( @@ -342,8 +371,18 @@ export function* useReplFileRecorder( access?: HostFilesAccess, ): Operation { const policy = yield* createMountPolicy(mounts, directory); - const files = yield* useEntryFileRecorder((operation, request, perform, authored) => - routed(recorder, operation, request, perform, workspace, authored, policy, access), + const roots = [ + ...(workspace === undefined ? [] : [workspace]), + ...(access === undefined ? [] : [access.project, access.assets, access.components]), + ]; + const files = yield* useEntryFileRecorder( + (operation, request, perform, authored) => + routed(recorder, operation, request, perform, workspace, authored, policy, access), + { + guard: () => policy.guard(), + restoreSelection: () => recorder.selection(), + route: (source, destination) => copyRoute(recorder, source, destination, roots), + }, ); return { files, policy }; } diff --git a/packages/cli/src/repl/repositories/deno/local.ts b/packages/cli/src/repl/repositories/deno/local.ts index edcce4236..bdabf3b7f 100644 --- a/packages/cli/src/repl/repositories/deno/local.ts +++ b/packages/cli/src/repl/repositories/deno/local.ts @@ -42,6 +42,7 @@ import type { import { StaleInputError } from "@executablemd/durable-streams"; import { asFilesFatal, FilesInvariantError } from "@executablemd/runtime"; import { + copyOrdinalFromName, parseReplLocalRecord, parseReplSelectionRecord, replLocalFingerprint, @@ -77,6 +78,7 @@ export interface LocalOperation { readonly operation: ReplLocalOperation; /** What the document asked for. Names the record; never live state. */ readonly request: ReplLocalRequest; + readonly ordinal?: number; /** The ordinary composed call, run only when no result is saved. */ perform(): Operation>; } @@ -136,21 +138,49 @@ export function retainedSelectionAhead(): Operation { } /** Whether this operation's own saved result stands at the cursor. */ -export function* retainedResultAhead( - name: string, - operation?: ReplLocalOperation, -): Operation { - if (operation !== "file-copy") { - return yield* retainedRecordAhead(REPL_REPOSITORY_LOCAL, name); - } +export function retainedResultAhead(name: string): Operation { + return retainedRecordAhead(REPL_REPOSITORY_LOCAL, name); +} + +export function* copyReplayContext(): Operation { const context = yield* DurableContext.expect(); + const failure = context.durability?.failure; + if (failure !== undefined) { + throw failure; + } + if (context.replayIndex.abandonedHistory(context.coroutineId)) { + throw new ReplLocalRecordError("Cannot continue File.Copy after abandoning retained history."); + } + return context; +} + +export function* retainedCopyAhead(ordinal: number): Operation { + const context = yield* copyReplayContext(); const description = context.replayIndex.peekYield(context.coroutineId)?.description; - const prefix = replLocalRecordName({ operation, fingerprint: "" }).slice(0, -2); - return ( - description?.type === REPL_REPOSITORY_LOCAL && - typeof description.name === "string" && - description.name.startsWith(prefix) - ); + const retained = + description?.type === REPL_REPOSITORY_LOCAL ? copyOrdinalFromName(description.name) : undefined; + if (retained !== undefined && retained < ordinal) { + throw yield* failCopy( + new ReplLocalRecordError("A retained file-copy occurrence was passed over."), + ); + } + return retained === ordinal; +} + +export function* failCopy(error: unknown): Operation { + const context = yield* DurableContext.expect(); + const state = (context.durability ??= {}); + return (state.failure ??= classify(error)); +} + +export function* checkCopyPublication(): Operation { + const context = yield* copyReplayContext(); + if ( + context.replayIndex.peekYield(context.coroutineId) !== undefined || + context.replayIndex.hasClose(context.coroutineId) + ) { + throw new ReplLocalRecordError("A new file-copy outcome would precede retained history."); + } } /** @@ -202,11 +232,8 @@ export function recordedLocalOperation( } function* recording(operation: LocalOperation): Operation> { - const fingerprint = yield* replLocalFingerprint({ - operation: operation.operation, - request: operation.request, - }); - const name = replLocalRecordName({ operation: operation.operation, fingerprint }); + const fingerprint = yield* replLocalFingerprint(operation); + const name = replLocalRecordName({ ...operation, fingerprint }); // Whatever comes back is journal data on a replay, so it is handed on as the // unknown it is and parsed below rather than trusted as this code's own. @@ -220,9 +247,8 @@ function* recording(operation: LocalOperation): Operation throw outcome.error; } return replLocalRecordJson({ - operation: operation.operation, + ...operation, fingerprint, - request: operation.request, outcome, }); }, @@ -236,7 +262,11 @@ function* recording(operation: LocalOperation): Operation "says about work already done is unknown.", ); } - if (parsed.operation !== operation.operation || parsed.fingerprint !== fingerprint) { + if ( + parsed.operation !== operation.operation || + parsed.fingerprint !== fingerprint || + parsed.ordinal !== operation.ordinal + ) { throw new ReplLocalRecordError( `the saved result standing where "${operation.operation}" belongs describes another ` + "operation, so this history does not say what happened here.", diff --git a/packages/cli/src/repl/repositories/records.ts b/packages/cli/src/repl/repositories/records.ts index 56da5d850..973e3bbaa 100644 --- a/packages/cli/src/repl/repositories/records.ts +++ b/packages/cli/src/repl/repositories/records.ts @@ -121,6 +121,7 @@ export interface ReplAmbientCheckout { export interface ReplLocalRecord { readonly version: typeof REPL_REPOSITORY_VERSION; readonly operation: ReplLocalOperation; + readonly ordinal?: number; /** The digest of the version, operation kind and authored request. */ readonly fingerprint: string; readonly request: ReplLocalRequest; @@ -148,16 +149,41 @@ export interface ReplSelectionRecord { export function replLocalRecordName(record: { readonly operation: ReplLocalOperation; readonly fingerprint: string; + readonly ordinal?: number; }): string { return canonicalJson([ RECORD_PREFIX, "local", REPL_REPOSITORY_VERSION, record.operation, + ...(record.ordinal === undefined ? [] : [record.ordinal]), record.fingerprint, ]); } +export function copyOrdinalFromName(name: string): number | undefined { + try { + const fields: unknown = JSON.parse(name); + if ( + Array.isArray(fields) && + fields.length === 6 && + fields[0] === RECORD_PREFIX && + fields[1] === "local" && + fields[2] === REPL_REPOSITORY_VERSION && + fields[3] === "file-copy" && + typeof fields[5] === "string" + ) { + return copyOrdinal(fields[4]); + } + } catch { + return undefined; + } +} + +function copyOrdinal(value: unknown): number | undefined { + return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined; +} + /** The stable name the entry's ambient routing record is journaled under. */ export function replSelectionRecordName(record: { readonly fingerprint: string }): string { return canonicalJson([RECORD_PREFIX, "selection", REPL_REPOSITORY_VERSION, record.fingerprint]); @@ -167,11 +193,13 @@ export function replSelectionRecordName(record: { readonly fingerprint: string } export function replLocalFingerprint(input: { readonly operation: ReplLocalOperation; readonly request: ReplLocalRequest; + readonly ordinal?: number; }): Operation { return digest({ version: REPL_REPOSITORY_VERSION, operation: input.operation, request: requestJson(input.request), + ...(input.ordinal === undefined ? {} : { ordinal: input.ordinal }), }); } @@ -186,11 +214,13 @@ export function replLocalRecordJson(input: { readonly fingerprint: string; readonly request: ReplLocalRequest; readonly outcome: Result; + readonly ordinal?: number; }): Json { const stated = { version: REPL_REPOSITORY_VERSION, operation: input.operation, fingerprint: input.fingerprint, + ...(input.ordinal === undefined ? {} : { ordinal: input.ordinal }), request: requestJson(input.request), }; if (input.outcome.ok) { @@ -229,10 +259,13 @@ export function replSelectionRecordJson(input: { * happened and may not. The caller refuses rather than guessing. */ export function parseReplLocalRecord(value: unknown): ReplLocalRecord | undefined { - const refusal = members(value, ["version", "operation", "fingerprint", "request", "refusal"]); + const fields = ["version", "operation", "fingerprint", "request"]; + const refusal = + members(value, [...fields, "refusal"]) ?? members(value, [...fields, "ordinal", "refusal"]); const success = refusal === undefined - ? members(value, ["version", "operation", "fingerprint", "request", "success"]) + ? (members(value, [...fields, "success"]) ?? + members(value, [...fields, "ordinal", "success"])) : undefined; const read = refusal ?? success; if (read === undefined) { @@ -246,6 +279,10 @@ export function parseReplLocalRecord(value: unknown): ReplLocalRecord | undefine if (fingerprint === undefined || operation === undefined) { return undefined; } + const ordinal = copyOrdinal(read.ordinal); + if (operation === "file-copy" ? ordinal === undefined : Object.hasOwn(read, "ordinal")) { + return undefined; + } const request = parseReplLocalRequest(read["request"], operation); if (request === undefined) { return undefined; @@ -266,6 +303,7 @@ export function parseReplLocalRecord(value: unknown): ReplLocalRecord | undefine version: REPL_REPOSITORY_VERSION, operation, fingerprint, + ...(ordinal === undefined ? {} : { ordinal }), request, outcome, }); diff --git a/packages/cli/src/repl/workspace-mount-installation.ts b/packages/cli/src/repl/workspace-mount-installation.ts index 2919ad326..b881d06ed 100644 --- a/packages/cli/src/repl/workspace-mount-installation.ts +++ b/packages/cli/src/repl/workspace-mount-installation.ts @@ -1,13 +1,13 @@ import { hostFileAccessReason, filesFailure, fileWriteFailure } from "@executablemd/runtime"; import type { HostFilesAccess } from "@executablemd/runtime"; -import { Err } from "effection"; +import { Err, lift } from "effection"; import { admitReplRepositoryHistory } from "./repositories/admission.ts"; import { cwd } from "@executablemd/runtime"; import type { Operation, Result } from "effection"; import type { ExecutionInstallation } from "@executablemd/core/host"; import type { DurableEvent } from "@executablemd/durable-streams"; import type { WorkspaceMountTable } from "../workspace-mounts.ts"; -import { liveCopyTargets, useEntryFileRecorder } from "./file-recorder.ts"; +import { useEntryFileRecorder } from "./file-recorder.ts"; import type { EntryFileCalls } from "./file-recorder.ts"; import { createMountPolicy } from "./mount-files.ts"; import type { AwaitedMountPolicy } from "./mount-files.ts"; @@ -49,6 +49,10 @@ export function workspaceMountInstallation( } else { const directory = yield* cwd(); const policy = yield* createMountPolicy(mounts, directory); + const roots = [ + ...(ownedDirectory === undefined ? [] : [ownedDirectory]), + ...(limits === undefined ? [] : [limits.project, limits.assets, limits.components]), + ]; const files = yield* useEntryFileRecorder( function* (operation, request, perform, authored): Operation> { yield* policy.guard(); @@ -59,18 +63,9 @@ export function workspaceMountInstallation( } } const name = yield* localRecordName({ operation, request }); - if (yield* retainedResultAhead(name, operation)) { + if (yield* retainedResultAhead(name)) { return yield* recordedLocalOperation({ operation, request, perform }); } - const roots = [ - ...(ownedDirectory === undefined ? [] : [ownedDirectory]), - ...(limits === undefined ? [] : [limits.project, limits.assets, limits.components]), - ]; - const copy = - operation === "file-copy" ? yield* liveCopyTargets(request, limits) : undefined; - if (copy !== undefined && !copy.ok) { - return copy; - } const permitted = roots.length === 0 || ((yield* Permissions.operations.files( @@ -79,22 +74,19 @@ export function workspaceMountInstallation( (operation !== "dir-ensure" || !isAbsolute(request.path) || (yield* Permissions.operations.files("absolute")))); - const reason = - copy !== undefined - ? undefined - : permitted - ? yield* hostFileAccessReason( - limits, - operation === "file-read" - ? "read" - : operation === "file-write" - ? "write" - : operation === "file-delete" - ? "delete" - : "ensure-directory", - request, - ) - : "permission-denied"; + const reason = permitted + ? yield* hostFileAccessReason( + limits, + operation === "file-read" + ? "read" + : operation === "file-write" + ? "write" + : operation === "file-delete" + ? "delete" + : "ensure-directory", + request, + ) + : "permission-denied"; if (reason !== undefined) { return Err( operation === "file-write" @@ -113,15 +105,13 @@ export function workspaceMountInstallation( } if (roots.length > 0) { const directory = (yield* API.Fs.operations.realpath(request.cwd)) ?? request.cwd; - const target = - copy?.value.destination ?? - (isAbsolute(request.path) - ? resolve( - (yield* API.Fs.operations.realpath(dirname(request.path))) ?? - dirname(request.path), - basename(request.path), - ) - : resolve(directory, request.path)); + const target = isAbsolute(request.path) + ? resolve( + (yield* API.Fs.operations.realpath(dirname(request.path))) ?? + dirname(request.path), + basename(request.path), + ) + : resolve(directory, request.path); for (const directory of roots) { const root = (yield* API.Fs.operations.realpath(directory)) ?? resolve(directory); const suffix = relative(root, target); @@ -147,6 +137,19 @@ export function workspaceMountInstallation( } return yield* perform(); }, + { + guard: () => policy.guard(), + *route(_source, destination) { + for (const directory of roots) { + const root = (yield* API.Fs.operations.realpath(directory)) ?? resolve(directory); + const at = relative(root, destination); + if (at !== ".." && !at.startsWith(".." + sep) && !isAbsolute(at)) { + return lift(() => undefined)(); + } + } + return undefined; + }, + }, ); entry = { files, policy }; } diff --git a/packages/cli/tests/repl-repositories.test.ts b/packages/cli/tests/repl-repositories.test.ts index 08be6d4ba..35e6b3a9f 100644 --- a/packages/cli/tests/repl-repositories.test.ts +++ b/packages/cli/tests/repl-repositories.test.ts @@ -19,14 +19,14 @@ import { describe, it } from "@executablemd/test-support/bdd"; import { expect } from "@executablemd/test-support/expect"; -import { ensure, resource, scoped, until } from "effection"; +import { ensure, Err, resource, scoped, until } from "effection"; import type { Operation, Result } from "effection"; import { ensureDir, exists, readTextFile, rm } from "@effectionx/fs"; import { mkdtemp, realpath, writeFile } from "node:fs/promises"; import { appendFile, open } from "node:fs/promises"; import { tmpdir } from "node:os"; import { dirname, isAbsolute, join, relative } from "node:path"; -import { API, Permissions, useHostFiles } from "@executablemd/runtime"; +import { API, filesFailure, Permissions, useHostFiles } from "@executablemd/runtime"; import { InMemoryStream } from "@executablemd/durable-streams"; import type { DurableEvent } from "@executablemd/durable-streams"; import { @@ -477,6 +477,7 @@ describe("how a REPL entry gets its repository behavior", () => { return record?.operation === "file-copy" ? [record] : []; }); expect(copies).toHaveLength(1); + expect(copies).toHaveLength(1); expect(copies[0]?.outcome).toEqual({ ok: true, value: undefined }); const directory = copies[0]?.request.cwd; if (directory === undefined) { @@ -492,56 +493,94 @@ describe("how a REPL entry gets its repository behavior", () => { const sourceCommon = join(fixture.checkout, ".git"); const destinationCommon = join(destination, ".git"); const calls: string[] = []; - yield* useHostFiles(); + yield* useHostFiles({ + observe(event) { + if (event.operation === "copy") { + calls.push(event.phase); + } + }, + }); + let delegated = 0; + yield* API.Files.around( + { + *copyFile([input], next) { + if (input.destination !== "uncovered.md") { + return yield* next(input); + } + delegated++; + const copied = yield* next({ ...input, destination: "destination/rewritten.md" }); + expect(copied.ok).toBe(true); + return Err(filesFailure({ operation: "copy", phase: "target", reason: "occupied" })); + }, + }, + { at: "min" }, + ); yield* useCompositionComponents(); yield* useWorkingDirectory(fixture.root); yield* Permissions.around({ files: ([op], next) => (op === "absolute" ? true : next(op)), }); const mounts = [{ source: fixture.root, target: "/reference" }]; - const files = yield* useReplFileRecorder( - { - *selection() { - return undefined; - }, - *hold(common) { - calls.push(`hold ${common}`); - }, - placements() { - return [ - { - checkoutRoot: fixture.checkout, - commonDirectory: sourceCommon, - *own() { - calls.push("source slot"); + function* runCopy(stream: InMemoryStream) { + const files = yield* useReplFileRecorder( + { + *selection() { + return undefined; + }, + *hold(common) { + calls.push(`hold ${common}`); + }, + placements() { + return [ + { + checkoutRoot: fixture.checkout, + commonDirectory: sourceCommon, + *own() { + calls.push("source slot"); + }, }, - }, - { - checkoutRoot: destination, - commonDirectory: destinationCommon, - *own() { - calls.push("destination slot"); + { + checkoutRoot: destination, + commonDirectory: destinationCommon, + *own() { + calls.push("destination slot"); + }, }, - }, - ]; + ]; + }, }, - }, - fixture.root, - mounts, - fixture.root, - ); + undefined, + mounts, + fixture.root, + ); + const source = [ + '', + '', + "", + '', + ].join("\n"); + return String( + yield* collect( + yield* executeInstalled({ ...inlineSource(source), stream }, [ + workspaceMountInstallation(mounts, () => files), + ]), + ), + ); + } const stream = new InMemoryStream(); - const source = [ - '', - '', - "", - ].join("\n"); - yield* collect( - yield* executeInstalled({ ...inlineSource(source), stream }, [ - workspaceMountInstallation(mounts, () => files), - ]), - ); - expect(calls).toEqual(["source slot", "destination slot", `hold ${destinationCommon}`]); + const first = yield* scoped(() => runCopy(stream)); + expect(calls).toEqual([ + "source slot", + "destination slot", + `hold ${destinationCommon}`, + "target", + "access", + "source slot", + "destination slot", + `hold ${destinationCommon}`, + "target", + "access", + ]); const records = recordsOf(yield* stream.readAll(), REPL_REPOSITORY_LOCAL); const copy = records.flatMap((event) => { const parsed = parseReplLocalRecord( @@ -549,9 +588,19 @@ describe("how a REPL entry gets its repository behavior", () => { ); return parsed?.operation === "file-copy" ? [parsed] : []; }); - expect(copy).toHaveLength(1); + expect(copy).toHaveLength(2); expect(copy[0]?.request.cwd).toBe(fixture.root); - expect(yield* readTextFile(join(destination, "copied.md"))).toBe("seed\n"); + expect(copy[1]?.request.path).toBe("uncovered.md"); + expect(copy[1]?.outcome.ok).toBe(false); + expect(first).toContain("already exists"); + expect(yield* readTextFile(join(destination, "..notes.md"))).toBe("seed\n"); + expect(yield* readTextFile(join(destination, "rewritten.md"))).toBe("seed\n"); + const prefix = (yield* stream.readAll()).filter((event) => event.type !== "close"); + calls.length = 0; + const restored = yield* scoped(() => runCopy(new InMemoryStream(prefix))); + expect(restored).toBe(first); + expect(calls).toEqual([]); + expect(delegated).toBe(1); }); it("E7: keeps two entries' equal records in their own segments", function* () { diff --git a/packages/cli/tests/retained-repository-local.test.ts b/packages/cli/tests/retained-repository-local.test.ts index b003cd290..c6dd52dc3 100644 --- a/packages/cli/tests/retained-repository-local.test.ts +++ b/packages/cli/tests/retained-repository-local.test.ts @@ -46,6 +46,7 @@ import { fileWriteSuccess, filesFailure, hostFilesHandler, + parseFilesFailure, Permissions, } from "@executablemd/runtime"; import type { FilePathInput, FilesHandler, FileWriteInput } from "@executablemd/runtime"; @@ -53,7 +54,13 @@ import { InMemoryStream, StaleInputError } from "@executablemd/durable-streams"; import type { DurableEvent, DurableStream, Json } from "@executablemd/durable-streams"; import { Execution } from "@executablemd/core/api"; import { executeInstalled } from "@executablemd/core/host"; -import { collect, Elicitation, inlineSource, useNormalizedOutput } from "@executablemd/core"; +import { + collect, + Elicitation, + inlineSource, + registerComponents, + useNormalizedOutput, +} from "@executablemd/core"; import { useDenoRepositoryOperations } from "@executablemd/git/deno"; import type { DenoRepositoryOperations } from "@executablemd/git/deno"; import { denoReplEntry } from "../src/deno-repositories.ts"; @@ -1538,6 +1545,130 @@ describe("retained File.Copy", () => { expect(yield* readTextFile(outside)).toBe("seed\n"); }); + it("keeps an uncovered or synthetic direct call separate from a later retained copy", function* () { + const fixture = yield* useFixture(); + const placement = { cwd: fixture.root, projectCwd: fixture.checkout }; + const a = "outside.md"; + const b = "checkout/copy.md"; + const doc = ""; + type Mode = "live" | "replay" | "insert" | "synthetic"; + const observed: string[] = []; + function install(mode: Mode) { + return (function* () { + yield* registerComponents([ + { + name: "CopyPair", + origin: "test", + props: { type: "object", properties: {} }, + *fn() { + for (const destination of [a, b]) { + const outcome = yield* API.Files.operations.copyFile({ + cwd: fixture.root, + source: "checkout/seed.md", + destination, + }); + observed.push( + outcome.ok ? "ok" : (parseFilesFailure(outcome.error)?.reason ?? "failed"), + ); + } + return ""; + }, + }, + ]); + yield* API.Files.around( + { + *copyFile([input], next) { + observed.push(input.destination); + if (input.destination === a && mode === "synthetic") { + return Ok(undefined); + } + return yield* next( + input.destination === a && mode === "insert" + ? { ...input, destination: "checkout/insert.md" } + : input, + ); + }, + }, + { at: "min" }, + ); + yield* API.Fs.around({ + *lstat([path], next) { + if (path.endsWith("/" + a) || path.endsWith("/" + b) || path.endsWith("/insert.md")) { + observed.push("observe " + path); + } + return yield* next(path); + }, + }); + })(); + } + + const fresh = yield* run(fixture, doc, new InMemoryStream(), counters(), { + ...placement, + between: () => install("live"), + }); + expect(fresh.refusal).toBe(undefined); + expect(localRecords(fresh.events).map((record) => record.ordinal)).toEqual([1]); + expect(recordsOf(fresh.events, REPL_REPOSITORY_SELECTION)).toHaveLength(1); + yield* writeTextFile(join(fixture.checkout, "copy.md"), "historical edit"); + + observed.length = 0; + const replayed = counters(); + const resumed = yield* run(fixture, doc, unfinished(fresh.events), replayed, { + ...placement, + between: () => install("replay"), + }); + expect(resumed.refusal).toBe(undefined); + expect(observed).toEqual([a, "observe " + join(fixture.root, a), "occupied", "ok"]); + expect(replayed.discoveries).toEqual([]); + expect(yield* readTextFile(join(fixture.root, a))).toBe("seed\n"); + expect(yield* readTextFile(join(fixture.root, b))).toBe("historical edit"); + + observed.length = 0; + const inserted = yield* run(fixture, doc, unfinished(fresh.events), counters(), { + ...placement, + between: () => install("insert"), + }); + expect(inserted.refusal).toContain("precede retained history"); + expect(observed).toEqual([a]); + expect(yield* exists(join(fixture.checkout, "insert.md"))).toBe(false); + expect(localRecords(inserted.events)).toEqual(localRecords(fresh.events)); + + yield* rm(join(fixture.root, a)); + yield* rm(join(fixture.root, b)); + observed.length = 0; + const synthetic = yield* run(fixture, doc, new InMemoryStream(), counters(), { + ...placement, + between: () => install("synthetic"), + }); + expect(synthetic.refusal).toBe(undefined); + expect(localRecords(synthetic.events).map((record) => record.ordinal)).toEqual([1]); + expect(yield* exists(join(fixture.root, a))).toBe(false); + }); + + it("distinguishes equal received pairs in one coroutine and starts each child at zero", function* () { + const fixture = yield* useFixture(); + const one = ''; + const doc = [ + one, + one, + "", + '', + '', + "", + ].join("\n"); + const first = yield* run(fixture, doc, new InMemoryStream(), counters()); + expect(first.refusal).toBe(undefined); + expect( + localRecords(first.events) + .map((record) => record.ordinal) + .sort(), + ).toEqual([0, 0, 0, 1]); + const names = recordNames(first.events); + expect(new Set(names).size).toBe(4); + const resumed = yield* run(fixture, doc, unfinished(first.events), counters()); + expect(resumed.refusal).toBe(undefined); + }); + it("refuses occupancy after a native copy whose acknowledgement was halted", function* () { const fixture = yield* useFixture(); const events: DurableEvent[] = []; @@ -1590,7 +1721,9 @@ describe("retained File.Copy", () => { ); return yield* stream.readAll(); }); - expect(localRecords(first).map((record) => record.operation)).toEqual(["file-copy"]); + expect(localRecords(first).map((record) => [record.operation, record.ordinal])).toEqual([ + ["file-copy", 0], + ]); expect(recordsOf(first, REPL_REPOSITORY_SELECTION)).toEqual([]); yield* writeTextFile(join(owned, "copy.md"), "changed"); yield* scoped(function* () { diff --git a/packages/cli/tests/retained-repository-records.test.ts b/packages/cli/tests/retained-repository-records.test.ts index ba5e87022..0b1e6d23a 100644 --- a/packages/cli/tests/retained-repository-records.test.ts +++ b/packages/cli/tests/retained-repository-records.test.ts @@ -140,18 +140,19 @@ function* localEvent( request: ReplLocalRequest, outcome = Ok(operation === "file-write" ? fileWriteSuccess("host-committed") : undefined), name?: string, + ordinal?: number, ): Operation { - const fingerprint = yield* replLocalFingerprint({ operation, request }); + const fingerprint = yield* replLocalFingerprint({ operation, request, ordinal }); return { type: "yield", coroutineId: "root", description: { type: REPL_REPOSITORY_LOCAL, - name: name ?? replLocalRecordName({ operation, fingerprint }), + name: name ?? replLocalRecordName({ operation, fingerprint, ordinal }), }, result: { status: "ok", - value: replLocalRecordJson({ operation, fingerprint, request, outcome }), + value: replLocalRecordJson({ operation, fingerprint, request, outcome, ordinal }), }, }; } @@ -534,6 +535,46 @@ describe("which histories one entry will continue", () => { ).toBe(undefined); }); + it("admits ordered physical copies with gaps and refuses malformed occurrences", function* () { + const pair = { cwd: "/work", source: "seed", path: "copy" }; + const first = yield* localEvent("file-copy", pair, undefined, undefined, 0); + const later = yield* localEvent( + "file-copy", + pair, + Err( + filesFailure({ + operation: "copy", + phase: "target", + reason: "occupied", + }), + ), + undefined, + 3, + ); + expect(yield* refusalOf([first, { ...first, coroutineId: "root.0" }, later])).toBe(undefined); + expect((yield* refusalOf([first, first]))?.reason).toBe("malformed-record"); + expect((yield* refusalOf([later, first]))?.reason).toBe("malformed-record"); + for (const ordinal of [undefined, -1, 1.5, Number.MAX_SAFE_INTEGER + 1]) { + const invalid = yield* localEvent("file-copy", pair, undefined, undefined, ordinal); + expect((yield* refusalOf([invalid]))?.reason).toBe("malformed-record"); + } + const wrongName = yield* localEvent("file-copy", pair, undefined, "invalid name", 0); + expect((yield* refusalOf([wrongName]))?.reason).toBe("request-fingerprint"); + for (const extra of [{ extra: true }, { fingerprint: "tampered" }]) { + expect( + yield* refusalOf([ + { + ...first, + result: { + status: "ok", + value: { ...Object(saved(first)), ...extra }, + }, + }, + ]), + ).toBeDefined(); + } + }); + it("refuses a record whose request no longer produces its name", function* () { const event = yield* localEvent("file-write", WRITE); // The request is changed after the work was saved, which is the one way a diff --git a/packages/runtime/files-host.ts b/packages/runtime/files-host.ts index f66da9c72..7ef4e936f 100644 --- a/packages/runtime/files-host.ts +++ b/packages/runtime/files-host.ts @@ -1,3 +1,5 @@ +import { createContext } from "effection"; +import type { Operation } from "effection"; import { registerFileRecorder } from "./files.ts"; import type { FilesHandler } from "./files.ts"; import type { FileRecorderHandle } from "./files-api.ts"; @@ -7,3 +9,18 @@ export const assembleFileCall = ( handle: FileRecorderHandle, method: K, ): FilesHandler[K] => handle.assemble(method); + +export type HostCopyRoute = (source: string, destination: string) => Operation; + +const HostCopyRouting = createContext("executablemd.runtime.host-copy-routing"); + +export function withHostCopyRoute(route: HostCopyRoute, operation: Operation): Operation { + return HostCopyRouting.with(route, () => operation); +} + +export function* routeHostCopy(source: string, destination: string): Operation { + const route = yield* HostCopyRouting.get(); + if (route !== undefined) { + yield* route(source, destination); + } +} diff --git a/packages/runtime/host-files.ts b/packages/runtime/host-files.ts index 614e07502..d5aafde8b 100644 --- a/packages/runtime/host-files.ts +++ b/packages/runtime/host-files.ts @@ -98,6 +98,7 @@ import { tmpdir } from "node:os"; import { FsApi, rm } from "@effectionx/fs"; import { API } from "./apis.ts"; import { fileWriteFailure, fileWriteSuccess, filesFailure, FilesInvariantError } from "./files.ts"; +import { routeHostCopy } from "./files-host.ts"; import { Permissions } from "./permissions.ts"; import type { FileCopyInput, @@ -657,6 +658,7 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler { return nonWriteFailure("copy", "resolution", "resolved-escape"); } + yield* routeHostCopy(from.path, to.path); notify(observe, { operation: "copy", phase: "target" }); try { const info = yield* API.Fs.operations.stat(from.path); diff --git a/specs/repl-spec.md b/specs/repl-spec.md index 27cd10864..c70ecabf0 100644 --- a/specs/repl-spec.md +++ b/specs/repl-spec.md @@ -2294,17 +2294,28 @@ admitted `` fragment performs are kept on the same terms, because a fragment's operations go to the same document filesystem an authored one does. A copy uses the physical record even when its working directory came from a -mount. Its identity binds the received working directory and both ordered -operands. Acknowledged Unit and ordinary refusals restore before permissions, -path observations, discovery, placement slots or mutation holds. A changed -operand at that retained position diverges before live routing, including when -the new destination lies outside coverage. - -For a live copy, the resolved destination parent determines coverage and the -final entry stays intact for classification. Covered managed operands use -their placement slots. The destination alone determines the checkout mutation -hold. Owned-root coverage requires no Git lease. Outside coverage the copy is -live and unrecorded. If native copy completed before an unacknowledged append, +mount. Each entry numbers received copy calls from zero within each durable +coroutine, counting uncovered, refused and synthetic calls. The copy record +and name carry this ordinal. Its fingerprint binds the ordinal, the received +working directory and both ordered operands. Admission requires strictly +increasing nonnegative safe integer ordinals per coroutine and accepts gaps. +A copy record requires an ordinal. + +After restoring any pending ambient selection, an equal ordinal offers the +current fingerprint to the durable matcher before live work. A changed operand +at that occurrence diverges, including when the new destination is uncovered. +A lower retained ordinal fails before live work. A higher ordinal stays +pending while the current call takes the live path. Acknowledged Unit and +ordinary refusals restore before Files composition or target observations. + +The host routes each live delegation by its effective resolved operands after +authorization and containment. The destination's resolved parent and final +entry determine coverage. Both managed operand slots precede the destination +checkout's mutation hold. Owned-root coverage requires no Git lease. +A covered dispatch cannot insert an outcome ahead of retained history. +The outer recorder publishes the final composed answer after settlement when +at least one dispatch reached covered storage. Uncovered and purely synthetic +calls have no copy result. If native copy completed before an unacknowledged append, a continuation attempts the operation live. An occupied destination then produces an ordinary refusal with its bytes intact. From 4222dcd1d994a53fc0c2c9156739def71645d97d Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 21:28:32 -0500 Subject: [PATCH 3/8] Preserve fatal File.Copy routing failures --- packages/cli/src/repl/file-recorder.ts | 19 +++++---- .../tests/retained-repository-local.test.ts | 42 ++++++++++++++++++- 2 files changed, 53 insertions(+), 8 deletions(-) diff --git a/packages/cli/src/repl/file-recorder.ts b/packages/cli/src/repl/file-recorder.ts index f73000e5b..035e2f5ab 100644 --- a/packages/cli/src/repl/file-recorder.ts +++ b/packages/cli/src/repl/file-recorder.ts @@ -89,14 +89,19 @@ function copyRecorder(routing: CopyRouting) { result = yield* scoped(() => withHostCopyRoute( function* (source, destination) { - yield* copyReplayContext(); - const hold = yield* routing.route(source, destination); - if (hold !== undefined) { - yield* checkCopyPublication(); - yield* hold; - covered = true; + try { + yield* copyReplayContext(); + const hold = yield* routing.route(source, destination); + if (hold !== undefined) { + yield* checkCopyPublication(); + yield* hold; + covered = true; + } + yield* copyReplayContext(); + } catch (error) { + // A delegating layer may recover before the composed call settles. + throw yield* failCopy(error); } - yield* copyReplayContext(); }, (function* () { return yield* unitOutcome(perform(), { operation: "copy", phase: "access" }); diff --git a/packages/cli/tests/retained-repository-local.test.ts b/packages/cli/tests/retained-repository-local.test.ts index c6dd52dc3..b20fb8f2f 100644 --- a/packages/cli/tests/retained-repository-local.test.ts +++ b/packages/cli/tests/retained-repository-local.test.ts @@ -1551,8 +1551,9 @@ describe("retained File.Copy", () => { const a = "outside.md"; const b = "checkout/copy.md"; const doc = ""; - type Mode = "live" | "replay" | "insert" | "synthetic"; + type Mode = "live" | "replay" | "insert" | "catch-insert" | "synthetic"; const observed: string[] = []; + const caught: unknown[] = []; function install(mode: Mode) { return (function* () { yield* registerComponents([ @@ -1582,6 +1583,19 @@ describe("retained File.Copy", () => { if (input.destination === a && mode === "synthetic") { return Ok(undefined); } + if (input.destination === a && mode === "catch-insert") { + try { + yield* next({ ...input, destination: "checkout/insert.md" }); + } catch (error) { + caught.push(error); + } + try { + yield* next({ ...input, destination: "retry-outside.md" }); + } catch (error) { + caught.push(error); + } + return Ok(undefined); + } return yield* next( input.destination === a && mode === "insert" ? { ...input, destination: "checkout/insert.md" } @@ -1592,6 +1606,12 @@ describe("retained File.Copy", () => { { at: "min" }, ); yield* API.Fs.around({ + *stat([path], next) { + if (mode === "catch-insert" && path === join(fixture.checkout, "seed.md")) { + observed.push("classify " + path); + } + return yield* next(path); + }, *lstat([path], next) { if (path.endsWith("/" + a) || path.endsWith("/" + b) || path.endsWith("/insert.md")) { observed.push("observe " + path); @@ -1633,6 +1653,26 @@ describe("retained File.Copy", () => { expect(yield* exists(join(fixture.checkout, "insert.md"))).toBe(false); expect(localRecords(inserted.events)).toEqual(localRecords(fresh.events)); + observed.length = 0; + const recovered = yield* run(fixture, doc, unfinished(fresh.events), counters(), { + ...placement, + between: () => install("catch-insert"), + }); + expect(recovered.refusal).toBe(inserted.refusal); + expect(caught).toHaveLength(2); + expect(caught[1]).toBe(caught[0]); + expect(observed).toEqual([a]); + expect(yield* exists(join(fixture.checkout, "insert.md"))).toBe(false); + expect(yield* exists(join(fixture.root, "retry-outside.md"))).toBe(false); + expect(localRecords(recovered.events)).toEqual(localRecords(fresh.events)); + expect( + recovered.events.some( + (event) => + event.type === "close" && event.coroutineId === "root" && event.result.status === "ok", + ), + ).toBe(false); + expect(yield* readTextFile(join(fixture.root, b))).toBe("historical edit"); + yield* rm(join(fixture.root, a)); yield* rm(join(fixture.root, b)); observed.length = 0; From 86cb56bbfbf6a4aecae2c24daabb84a9ae282922 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 21:44:18 -0500 Subject: [PATCH 4/8] Trim File.Copy syntax help --- packages/cli/tests/syntax-cli.test.ts | 15 +++++++-------- packages/core/src/components/components.md | 14 -------------- packages/core/src/components/registry.ts | 7 +------ specs/executable-mdx-spec.md | 2 +- 4 files changed, 9 insertions(+), 29 deletions(-) diff --git a/packages/cli/tests/syntax-cli.test.ts b/packages/cli/tests/syntax-cli.test.ts index 25cd1f03b..06d4c66f1 100644 --- a/packages/cli/tests/syntax-cli.test.ts +++ b/packages/cli/tests/syntax-cli.test.ts @@ -563,22 +563,21 @@ describe("Tier SX — the command line", { sanitizeOps: false, sanitizeResources expect(unknown.stdout).toBe(""); }); - it("SX16: named File.Copy describes the two paths and replay", function* () { + it("SX16: named File.Copy shows concise usage and two required paths", function* () { const named = yield* runCli(["syntax", "File.Copy"], { cwd: "." }).expect(); for (const text of [ "**Forms:** ``", "| `source` | `string` | yes |", "| `destination` | `string` | yes |", - "An occupied destination is preserved.", - "Ordinary hosts and Markdown tests copy live", - "partial host replay", - "Workflow Workspace replay restores a published", - "Retained REPL replay restores an acknowledged", - "Unrecorded copies run live.", + "Copy a file into an existing directory.", + '', ]) { expect(named.stdout).toContain(text); } - expect(named.stdout).not.toContain(""); + expect(named.stdout.match(/Copy a file into an existing directory\./g)).toHaveLength(1); + expect(named.stdout).not.toMatch( + /replay|working directory|occupied destination|<\/File.Copy>/i, + ); }); it("SX16: engine and selected installed structural names match canonical component references", function* () { diff --git a/packages/core/src/components/components.md b/packages/core/src/components/components.md index 6d9021ad9..963761698 100644 --- a/packages/core/src/components/components.md +++ b/packages/core/src/components/components.md @@ -179,20 +179,6 @@ the directories above it as needed. ## File.Copy -Copy a regular file byte for byte. - -```mdx - -``` - -Both paths are relative to the working directory. The destination directory -must already exist. An occupied destination is preserved. - -Ordinary hosts and Markdown tests copy live, including partial host replay -that reaches the copy. Workflow Workspace replay restores a published result. -Retained REPL replay restores an acknowledged result in covered storage. -Unrecorded copies run live. - ## File.Delete Deletes a file, relative to the working directory. diff --git a/packages/core/src/components/registry.ts b/packages/core/src/components/registry.ts index 7e93ca351..a0a50dcab 100644 --- a/packages/core/src/components/registry.ts +++ b/packages/core/src/components/registry.ts @@ -235,12 +235,7 @@ export const CORE_REGISTRY: ComponentRegistry = new Map([ ), core("File.Copy", fileCopyForm, parseJsonObject(fileCopyProps), { description: - 'Copy a regular file byte for byte. `` ' + - "requires an existing destination directory. " + - "Both paths are relative to the working directory. An occupied destination is preserved. " + - "Ordinary hosts and Markdown tests copy live, as does partial host replay that reaches the copy. " + - "Workflow Workspace replay restores a published copy result. Retained REPL replay restores " + - "an acknowledged copy in covered storage. Unrecorded copies run live.", + 'Copy a file into an existing directory. ``', as: null, context: null, }), diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index ebde99849..03108722f 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -9908,7 +9908,7 @@ expansion. [Workflow Workspace](workflow-workspace-spec.md#101-workspace-local-e restores a published effect. [Retained REPL](repl-spec.md#the-files-an-entry-wrote-in-the-checkout-you-are-standing-in) restores an acknowledged result within covered storage. -Named `xmd syntax File.Copy` describes the props, form, and provider behavior. +Named `xmd syntax File.Copy` shows the invocation and required props. Generated XMD requires a separate trusted offer for the name and form. ### 6.14 Finding files: `` From 3a6d135fe6a0060dc3605bf9bd3dd20eb06f4de2 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 22:01:12 -0500 Subject: [PATCH 5/8] Use from and to for File.Copy syntax --- .../tests/document-suites/file-copy/FileCopy.test.md | 4 ++-- packages/cli/tests/repl-repositories.test.ts | 6 +++--- packages/cli/tests/retained-repository-local.test.ts | 10 +++++----- packages/cli/tests/syntax-cli.test.ts | 6 +++--- packages/core/src/components/FileCopy.ts | 10 +++++----- packages/core/src/components/registry.ts | 2 +- .../workflow/tests/generated-agent-component.test.ts | 2 +- packages/workflow/tests/workspace-files.test.ts | 2 +- specs/executable-mdx-spec.md | 11 ++++++----- specs/repl-spec.md | 2 +- 10 files changed, 28 insertions(+), 27 deletions(-) diff --git a/packages/cli/tests/document-suites/file-copy/FileCopy.test.md b/packages/cli/tests/document-suites/file-copy/FileCopy.test.md index b7d9ae4e6..035a75e95 100644 --- a/packages/cli/tests/document-suites/file-copy/FileCopy.test.md +++ b/packages/cli/tests/document-suites/file-copy/FileCopy.test.md @@ -17,7 +17,7 @@ yield* (function* () { })(); ``` - + ```ts eval import { readFile, writeFile } from "node:fs/promises"; @@ -42,7 +42,7 @@ const verified = yield* (function* () { source -\n\nran\n\n\n'} as="child"> +\n\nran\n\n\n'} as="child"> diff --git a/packages/cli/tests/repl-repositories.test.ts b/packages/cli/tests/repl-repositories.test.ts index 35e6b3a9f..c819e9d74 100644 --- a/packages/cli/tests/repl-repositories.test.ts +++ b/packages/cli/tests/repl-repositories.test.ts @@ -466,7 +466,7 @@ describe("how a REPL entry gets its repository behavior", () => { const source = [ ``, 'original', - '', + '', "", ].join("\n"); const events = yield* submit(fixture, source, execution(), { initialized: 0 }); @@ -555,9 +555,9 @@ describe("how a REPL entry gets its repository behavior", () => { ); const source = [ '', - '', + '', "", - '', + '', ].join("\n"); return String( yield* collect( diff --git a/packages/cli/tests/retained-repository-local.test.ts b/packages/cli/tests/retained-repository-local.test.ts index b20fb8f2f..b73a86d85 100644 --- a/packages/cli/tests/retained-repository-local.test.ts +++ b/packages/cli/tests/retained-repository-local.test.ts @@ -1462,7 +1462,7 @@ describe("marked workspace mount initialization", () => { }); describe("retained File.Copy", () => { - const source = ''; + const source = ''; it("replays success and occupied refusal before current permissions and routing", function* () { for (const occupied of [false, true]) { @@ -1507,7 +1507,7 @@ describe("retained File.Copy", () => { it("rejects either changed operand before routing and leaves uncovered copy live", function* () { const fixture = yield* useFixture(); - const doc = ''; + const doc = ''; const placement = { cwd: fixture.root, projectCwd: fixture.checkout }; const first = yield* run(fixture, doc, new InMemoryStream(), counters(), placement); expect(localRecords(first.events).map((record) => record.operation)).toEqual(["file-copy"]); @@ -1687,13 +1687,13 @@ describe("retained File.Copy", () => { it("distinguishes equal received pairs in one coroutine and starts each child at zero", function* () { const fixture = yield* useFixture(); - const one = ''; + const one = ''; const doc = [ one, one, "", - '', - '', + '', + '', "", ].join("\n"); const first = yield* run(fixture, doc, new InMemoryStream(), counters()); diff --git a/packages/cli/tests/syntax-cli.test.ts b/packages/cli/tests/syntax-cli.test.ts index 06d4c66f1..4de7ea4b6 100644 --- a/packages/cli/tests/syntax-cli.test.ts +++ b/packages/cli/tests/syntax-cli.test.ts @@ -567,10 +567,10 @@ describe("Tier SX — the command line", { sanitizeOps: false, sanitizeResources const named = yield* runCli(["syntax", "File.Copy"], { cwd: "." }).expect(); for (const text of [ "**Forms:** ``", - "| `source` | `string` | yes |", - "| `destination` | `string` | yes |", + "| `from` | `string` | yes |", + "| `to` | `string` | yes |", "Copy a file into an existing directory.", - '', + '', ]) { expect(named.stdout).toContain(text); } diff --git a/packages/core/src/components/FileCopy.ts b/packages/core/src/components/FileCopy.ts index 7f7bfd66c..be698634d 100644 --- a/packages/core/src/components/FileCopy.ts +++ b/packages/core/src/components/FileCopy.ts @@ -7,10 +7,10 @@ import { reason } from "./fs-error-phrases.ts"; export const props = { type: "object", properties: { - source: { type: "string", minLength: 1 }, - destination: { type: "string", minLength: 1 }, + from: { type: "string", minLength: 1 }, + to: { type: "string", minLength: 1 }, }, - required: ["source", "destination"], + required: ["from", "to"], additionalProperties: false, }; @@ -20,8 +20,8 @@ export const form: FormDeclaration = { fn: printErrors(function* (props) { const result = yield* copyFile({ cwd: yield* cwd(), - source: String(props.source), - destination: String(props.destination), + source: String(props.from), + destination: String(props.to), }); if (!result.ok) { throw new Error(`Cannot copy file: ${reason(parseFilesFailure(result.error)?.reason)}.`); diff --git a/packages/core/src/components/registry.ts b/packages/core/src/components/registry.ts index a0a50dcab..a1b598da5 100644 --- a/packages/core/src/components/registry.ts +++ b/packages/core/src/components/registry.ts @@ -235,7 +235,7 @@ export const CORE_REGISTRY: ComponentRegistry = new Map([ ), core("File.Copy", fileCopyForm, parseJsonObject(fileCopyProps), { description: - 'Copy a file into an existing directory. ``', + 'Copy a file into an existing directory. ``', as: null, context: null, }), diff --git a/packages/workflow/tests/generated-agent-component.test.ts b/packages/workflow/tests/generated-agent-component.test.ts index 399e4d33a..dd3ed2dce 100644 --- a/packages/workflow/tests/generated-agent-component.test.ts +++ b/packages/workflow/tests/generated-agent-component.test.ts @@ -1337,7 +1337,7 @@ describe("Tier WGAC — the standard write table", () => { return yield* runDocument( database, evaluates( - '\n\n', + '\n\n', ["write"], ), ); diff --git a/packages/workflow/tests/workspace-files.test.ts b/packages/workflow/tests/workspace-files.test.ts index c69c343e5..b9441d151 100644 --- a/packages/workflow/tests/workspace-files.test.ts +++ b/packages/workflow/tests/workspace-files.test.ts @@ -1920,7 +1920,7 @@ describe("workflow document filesystem — permission", () => { }); describe("Workspace file copy", () => { - const doc = ''; + const doc = ''; const target = JSON.stringify(["/source.bin", "/destination.bin"]); const bytes = Uint8Array.of(0, 255, 128); diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index 03108722f..72f95d15f 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -9881,15 +9881,16 @@ semantics belong to the provider: `specs/workflow-workspace-spec.md` §§6.3 and ### 6.13.3 Copying a file: `` ```mdx - + ``` Core supplies `File.Copy` as an ordinary default. The canonical dispatcher requires self-closing form and refuses paired form before expanding its -content. Both props are required nonempty strings. The component calls -`API.Files.copyFile({ cwd, source, destination })` once with the contextual -working directory. Success is Unit and renders nothing. Ordinary filesystem -refusals use the Files reporting rules in §6.13. +content. The `from` and `to` props are required nonempty strings. +The component passes `from` as `source` and `to` as `destination` in one call +to `API.Files.copyFile` with the contextual working directory. Success is Unit +and renders nothing. Ordinary filesystem refusals use the Files reporting +rules in §6.13. The performing provider authorizes read access to the effective source and write access to the effective destination after middleware and before target diff --git a/specs/repl-spec.md b/specs/repl-spec.md index c70ecabf0..bc8ad5339 100644 --- a/specs/repl-spec.md +++ b/specs/repl-spec.md @@ -2288,7 +2288,7 @@ Start the REPL inside a Git checkout and an entry's file work is retained too, under the ordinary physical records. The prospective mapped class above uses its closed association record. The physical records keep a self-closing `` text read; a paired `…` write, after its content has expanded; a self-closing -``; a self-closing ``; and the directory a paired `…` +``; a self-closing ``; and the directory a paired `…` ensures, before its content is entered. The reads, writes and deletions an admitted `` fragment performs are kept on the same terms, because a fragment's operations go to the same document filesystem an authored one does. From 11085e02a9380b33e99dc43e41d7678c4a5a4451 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 22:08:04 -0500 Subject: [PATCH 6/8] Link File.Copy to its specification --- packages/core/src/components/components.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/core/src/components/components.md b/packages/core/src/components/components.md index 963761698..51784919f 100644 --- a/packages/core/src/components/components.md +++ b/packages/core/src/components/components.md @@ -179,6 +179,8 @@ the directories above it as needed. ## File.Copy +Read the [File.Copy specification](https://github.com/taras/executable.md/blob/main/specs/executable-mdx-spec.md#6133-copying-a-file-filecopy). + ## File.Delete Deletes a file, relative to the working directory. From ccf9f1b7d24106291af420b528d9eb1724da8e7d Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 22:18:51 -0500 Subject: [PATCH 7/8] Use the Markdown reference for File.Copy help --- packages/cli/tests/syntax-cli.test.ts | 34 +++++++++++++++---- packages/core/src/components/components.md | 17 +++++----- packages/core/src/components/documentation.ts | 16 +++------ packages/core/src/components/registry.ts | 8 ++--- packages/core/tests/syntax-catalog.test.ts | 18 ++++++---- specs/executable-mdx-spec.md | 12 ++++--- 6 files changed, 64 insertions(+), 41 deletions(-) diff --git a/packages/cli/tests/syntax-cli.test.ts b/packages/cli/tests/syntax-cli.test.ts index 4de7ea4b6..3258ec8be 100644 --- a/packages/cli/tests/syntax-cli.test.ts +++ b/packages/cli/tests/syntax-cli.test.ts @@ -25,9 +25,19 @@ import { randomUUID } from "node:crypto"; import { platform, tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { API } from "@executablemd/runtime"; -import { CORE_COMPONENT_NAMES } from "@executablemd/core"; +import { + capturedDocumentation, + CORE_COMPONENT_NAMES, + documentationIndexFor, +} from "@executablemd/core"; +import { Syntax } from "@executablemd/core/api"; import type { PropsSchema, SyntaxSymbols } from "@executablemd/core"; -import { renderSyntaxJson, renderSyntaxMarkdown, syntaxSymbols } from "../src/syntax.ts"; +import { + renderSyntaxJson, + renderSyntaxMarkdown, + syntaxSymbols, + useCommandSyntax, +} from "../src/syntax.ts"; import { installPlugins } from "../src/plugin-host.ts"; import { BUNDLED_PLUGIN } from "../src/run-profile.ts"; @@ -283,9 +293,16 @@ describe("Tier SX — the run profile the command describes", () => { }); it("SX2: documents every complete built-in in the profile", function* () { - const catalog = yield* syntaxSymbols([]); + const { catalog, docs } = yield* scoped(function* () { + yield* useCommandSyntax([]); + return { + catalog: yield* Syntax.operations.symbols, + docs: documentationIndexFor(yield* capturedDocumentation()), + }; + }); const undocumented = catalog.categories[1].entries.filter( - (entry) => entry.description === undefined || entry.description.trim().length === 0, + (entry) => + !entry.description?.trim() && !docs.documentationFor(entry.name, entry.origin)?.trim(), ); expect(names(undocumented)).toEqual([]); @@ -569,8 +586,13 @@ describe("Tier SX — the command line", { sanitizeOps: false, sanitizeResources "**Forms:** ``", "| `from` | `string` | yes |", "| `to` | `string` | yes |", - "Copy a file into an existing directory.", - '', + [ + "Copy a file into an existing directory.", + "", + "```mdx", + '', + "```", + ].join("\n"), ]) { expect(named.stdout).toContain(text); } diff --git a/packages/core/src/components/components.md b/packages/core/src/components/components.md index 51784919f..0df256ae9 100644 --- a/packages/core/src/components/components.md +++ b/packages/core/src/components/components.md @@ -2,9 +2,8 @@ Long-form documentation for the components canonical core owns. Each level-two heading below is the exact name of one component. The compact list of symbols — `xmd syntax`, or a bare `` — names every component -with its forms, props and one-line description. This file holds the part that -does not belong in a list: when to reach for a component, what it does at run -time, and what it will refuse. +with its forms, props and any description from its registration. Named help +adds the usage from this file. Every component this package supplies has a section here. A build in which one does not refuses rather than serving a reference with a silent hole in it: a @@ -22,10 +21,8 @@ is written. ``` The bare form lists the symbols available here: every name a document may write -at that site, with its forms, props and description. It is the same text -`xmd syntax` prints, built by the same code, so an operator reading a terminal -and an agent reading a document are never told different things about one -profile. +at that site, with its forms, props and any registered description. It prints +the same text as `xmd syntax` for that profile. ```mdx @@ -179,7 +176,11 @@ the directories above it as needed. ## File.Copy -Read the [File.Copy specification](https://github.com/taras/executable.md/blob/main/specs/executable-mdx-spec.md#6133-copying-a-file-filecopy). +Copy a file into an existing directory. + +```mdx + +``` ## File.Delete diff --git a/packages/core/src/components/documentation.ts b/packages/core/src/components/documentation.ts index a33144dde..78c05b98d 100644 --- a/packages/core/src/components/documentation.ts +++ b/packages/core/src/components/documentation.ts @@ -20,18 +20,12 @@ export interface ComponentDocumentation { /** * The same prose, as a first-party declaration is required to state it. * - * `as` and `context` are `string | null` rather than optional, so a first-party - * declaration decides whether each one applies instead of leaving an omitted - * field to mean either "not applicable" or "forgotten". `null` is the explicit - * "this component takes no binding" / "this component reads no content", and it - * contributes no field to the public catalog. - * - * The public registration contract stays the optional strings above: this is - * the discipline first-party packages hold themselves to, not a rule imposed on - * anybody who registers a component. + * Each field is explicit. Use `null` for a description supplied by the package's + * `components.md`, for a component with no binding to describe, or for one that + * reads no content. A null field is omitted from the public catalog. */ export interface FirstPartyDocumentation { - readonly description: string; + readonly description: string | null; readonly as: string | null; readonly context: string | null; } @@ -40,7 +34,7 @@ export interface FirstPartyDocumentation { export function documented(documentation: FirstPartyDocumentation): ComponentDocumentation { const { description, as, context } = documentation; return { - description, + ...(description === null ? {} : { description }), ...(as === null ? {} : { as }), ...(context === null ? {} : { context }), }; diff --git a/packages/core/src/components/registry.ts b/packages/core/src/components/registry.ts index a1b598da5..ce7fa7342 100644 --- a/packages/core/src/components/registry.ts +++ b/packages/core/src/components/registry.ts @@ -103,9 +103,8 @@ interface CoreOptions { * * The accepted forms are read off that same declaration rather than restated, * so ``'s and ``'s one accepted form each is documented by the - * value that dispatches it. Documentation is a parameter rather than an option - * because a core default states what it is for, and says explicitly whether - * `as` and content apply to it. + * value that dispatches it. Each registration specifies which prose it + * contributes to the catalog. */ function core( name: string, @@ -234,8 +233,7 @@ export const CORE_REGISTRY: ComponentRegistry = new Map([ }, ), core("File.Copy", fileCopyForm, parseJsonObject(fileCopyProps), { - description: - 'Copy a file into an existing directory. ``', + description: null, as: null, context: null, }), diff --git a/packages/core/tests/syntax-catalog.test.ts b/packages/core/tests/syntax-catalog.test.ts index c43ceea81..23b93dd24 100644 --- a/packages/core/tests/syntax-catalog.test.ts +++ b/packages/core/tests/syntax-catalog.test.ts @@ -26,7 +26,9 @@ import { API } from "@executablemd/runtime"; import type { DirectoryEntry, LinkStatResult, StatResult } from "@executablemd/runtime"; import { repositoryComponentName } from "../src/components/candidates.ts"; import { + capturedDocumentation, CORE_COMPONENT_NAMES, + documentationIndexFor, inspectComponent, inspectSyntax, PROTECTED_COMPONENT_NAMES, @@ -35,7 +37,7 @@ import { RESERVED_STRUCTURAL, STRUCTURAL_DECLARATIONS, } from "../mod.ts"; -import { AGENT_REGISTRATIONS, agentIdentityComponents } from "@executablemd/agent/host"; +import { agentIdentityComponents, useAgentComponents } from "@executablemd/agent/host"; import type { CompleteComponentSyntaxEntry, InstalledStructuralSyntaxEntry, @@ -1387,15 +1389,19 @@ describe("Tier SY: inspection is observation, never execution", () => { }); describe("Tier SY: first-party documentation", () => { - it("SY28: gives every core and Agent default a description", function* () { - const catalog = yield* scoped(function* () { + it("SY28: documents every core and Agent default", function* () { + const { catalog, docs } = yield* scoped(function* () { yield* useTree({}); - yield* registerComponents(AGENT_REGISTRATIONS); - return yield* inspectSyntax({ includes: [], components: agentIdentityComponents() }); + yield* useAgentComponents(); + return { + catalog: yield* inspectSyntax({ includes: [], components: agentIdentityComponents() }), + docs: documentationIndexFor(yield* capturedDocumentation()), + }; }); const undocumented = builtIn(catalog).filter( - (entry) => entry.description === undefined || entry.description.length === 0, + (entry) => + !entry.description?.trim() && !docs.documentationFor(entry.name, entry.origin)?.trim(), ); expect(names(undocumented)).toEqual([]); for (const name of [...CORE_COMPONENT_NAMES, "Agent", "Prompt", "Session"]) { diff --git a/specs/executable-mdx-spec.md b/specs/executable-mdx-spec.md index 72f95d15f..5647381b8 100644 --- a/specs/executable-mdx-spec.md +++ b/specs/executable-mdx-spec.md @@ -3617,9 +3617,11 @@ yield* registrar.around(function* (request, next) { A registration may also carry `description`, `as` and `context` — the same three descriptive fields Markdown frontmatter carries, with the same meaning and the -same absence of behavior. Every component a first-party package registers -declares a description, and decides explicitly whether `as` and `context` apply -to it rather than leaving an omitted field to mean either. +same absence of behavior. A first-party component supplies its description in +the registration or in its section of the package's `components.md` (§5.3.1). +The compact catalog includes descriptions from registrations. Named help also +includes the matching Markdown sections. First-party registrations specify +whether `as` and `context` apply. **A return binds by reference.** `as` binds the value the component returned — the object itself, not a rendering of it — so a component can hand its caller @@ -13565,7 +13567,7 @@ so the include-boundary rows are the same on every host. Defined in §5.3. | SY24/SY25 | Complete contracts | ``'s two forms, ``'s one, ``'s one and its capture, and text and value return modes; declaration order of captures and forms survives, each canonical forms spelling is accepted, and every other one is refused | | SY7/SY7c/SY18 | Owned names keep their origin | A flat dotted candidate, an unreachable subtree and a link behind a prefix leave `` reported with canonical core's own origin rather than a registration's | | SY26–SY27 | Declared components | One is described without its factory being called and a repository file still overrides it; two declarations of one name are refused before either factory; and a declaration inspection refuses is refused identically by registration | -| SY28 | First-party documentation | Every complete built-in in the core and Agent profile states a description | +| SY28 | First-party documentation | Every complete built-in in the core and Agent profile has a registration description or a nonempty package documentation section | | SY29 | Determinism | Two inspections of one environment are equal, and entries are sorted within each category | ### Tier DV — Document validation @@ -13779,7 +13781,7 @@ would bind differently — belongs to `EP`, where profile capture is tested. | # | Test | Verify | |---|------|--------| | SX1–SX3 | The run profile | Core, Agent, testing and web defaults and `` are described from the declarations the runtime installers register, with no execution claimant minted | -| SX2 | Documentation completeness | Every complete built-in in the profile states a description, and the testing contracts read as they are: `` requires `message` and binds the caught error segment, an ordinary assertion binds its diagnostic report, and an assertion that refuses expected children reports one form | +| SX2 | Documentation completeness | Every complete built-in has a registration description or a nonempty package documentation section, and the testing contracts read as they are: `` requires `message` and binds the caught error segment, an ordinary assertion binds its diagnostic report, and an assertion that refuses expected children reports one form | | SX4–SX6 | Renderers take a value | Both formats render from a supplied symbols with the filesystem refusing every call, twice with identical bytes, under the fixed category headings; every table cell is escaped, a prop name holding a pipe included | | SX7/SX8 | Includes | Repeated values select in caller order and replace the defaults; absent, the defaults apply | | SX9 | Failure | An unusable include exits 1, reports on stderr and prints no symbols | From e148ffe69a2dd1cf2a5a8c9be6e598c1d2b59942 Mon Sep 17 00:00:00 2001 From: Taras Mankovski Date: Mon, 16 Nov 2026 22:45:30 -0500 Subject: [PATCH 8/8] Refresh generated syntax artifacts for File.Copy --- .../core/tests/fixtures/syntax-generated-base.json | 10 +++++----- specs/construct-inventory.md | 1 + 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/packages/core/tests/fixtures/syntax-generated-base.json b/packages/core/tests/fixtures/syntax-generated-base.json index 3e6e806d7..6cb9bf1c5 100644 --- a/packages/core/tests/fixtures/syntax-generated-base.json +++ b/packages/core/tests/fixtures/syntax-generated-base.json @@ -1,10 +1,10 @@ { "fragment-base.txt": "## Built-in structural syntax\n\nNo structural constructs are reserved.\n\n## Built-in components\n\nNo components are registered in this profile.\n\n## User-provided components\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n", "root-base.txt": "## Built-in structural syntax\n\nNo structural constructs are reserved.\n\n## Built-in components\n\nNo components are registered in this profile.\n\n## User-provided components\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `test://provider` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n", - "canonical-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", - "catalog-base.json": "{\"version\":1,\"categories\":[{\"kind\":\"structural\",\"entries\":[{\"kind\":\"structural\",\"name\":\"All\",\"origin\":{\"kind\":\"structural\",\"construct\":\"All\"},\"syntax\":[\"……\"],\"description\":\"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\"context\":\"The `` children this runs at the same time.\"},{\"kind\":\"structural\",\"name\":\"Answer\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answer\"},\"syntax\":[\"\",\"…\"],\"description\":\"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\"context\":\"A multiline template, in place of the single-line `template` prop.\"},{\"kind\":\"structural\",\"name\":\"Answers\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answers\"},\"syntax\":[\"…\"],\"description\":\"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\"context\":\"`` matchers, and the body they answer for.\"},{\"kind\":\"structural\",\"name\":\"Break\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Break\"},\"syntax\":[\"\"],\"description\":\"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"},{\"kind\":\"structural\",\"name\":\"Case\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Case\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\"context\":\"Markdown expanded when this case is selected.\"},{\"kind\":\"structural\",\"name\":\"Catch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Catch\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\"as\":\"Optional. Binds the ordinary Error by reference in this branch.\",\"context\":\"Recovery content.\"},{\"kind\":\"structural\",\"name\":\"Content\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Content\"},\"syntax\":[\"\",\"\"],\"description\":\"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"},{\"kind\":\"structural\",\"name\":\"Each\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Each\"},\"syntax\":[\"…\"],\"description\":\"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\"as\":\"Optional. Captures the whole rendered loop instead of emitting it.\",\"context\":\"Markdown rendered once per element.\"},{\"kind\":\"structural\",\"name\":\"Else\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Else\"},\"syntax\":[\"…\"],\"description\":\"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\"context\":\"The branch taken when the enclosing condition does not hold.\"},{\"kind\":\"structural\",\"name\":\"Finally\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Finally\"},\"syntax\":[\"…\"],\"description\":\"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\"context\":\"Completion content using the surrounding bindings.\"},{\"kind\":\"structural\",\"name\":\"If\",\"origin\":{\"kind\":\"structural\",\"construct\":\"If\"},\"syntax\":[\"…\"],\"description\":\"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\"context\":\"The branch taken when the condition holds, up to an ``.\"},{\"kind\":\"structural\",\"name\":\"Let\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Let\"},\"syntax\":[\"…\",\"\"],\"description\":\"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\"as\":\"Required. The binding name the value is available under.\",\"context\":\"Markdown whose rendered text becomes the binding, in the paired form.\"},{\"kind\":\"structural\",\"name\":\"Loop\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Loop\"},\"syntax\":[\"…\"],\"description\":\"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\"context\":\"Markdown expanded once per iteration.\"},{\"kind\":\"structural\",\"name\":\"Output\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Output\"},\"syntax\":[\"…\"],\"description\":\"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\"context\":\"The rendered output the run presents.\"},{\"kind\":\"structural\",\"name\":\"PrintErrors\",\"origin\":{\"kind\":\"structural\",\"construct\":\"PrintErrors\"},\"syntax\":[\"…\"],\"description\":\"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\"context\":\"The region whose failures are printed rather than raised.\"},{\"kind\":\"structural\",\"name\":\"Return\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Return\"},\"syntax\":[\"\"],\"description\":\"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"},{\"kind\":\"structural\",\"name\":\"Spawn\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Spawn\"},\"syntax\":[\"…\"],\"description\":\"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\"context\":\"Markdown expanded in its own child, beside its siblings.\"},{\"kind\":\"structural\",\"name\":\"Switch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Switch\"},\"syntax\":[\"…\"],\"description\":\"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\"context\":\"Direct `` branches considered in source order.\"},{\"kind\":\"structural\",\"name\":\"Try\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Try\"},\"syntax\":[\"………\"],\"description\":\"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\"context\":\"Attempted content followed by direct Catch and Finally branches.\"}]},{\"kind\":\"built-in\",\"entries\":[{\"kind\":\"component\",\"name\":\"CodeBlock\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{\"type\":\"string\"},\"language\":{\"type\":\"string\",\"pattern\":\"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"}},\"required\":[\"value\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\"as\":\"Optional. Captures the exact fenced Markdown instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Cwd\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read the working directory. `` renders its path without adding a newline.\",\"as\":\"Optional. Captures the directory path instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Dir\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Create or use a directory. `…` changes the working directory for its content.\",\"context\":\"The Markdown expanded in that directory.\"},{\"kind\":\"component\",\"name\":\"Elicit\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Ask a person a structured question. `…` shows the content as the request.\",\"as\":\"Required. The validated answer, as a structured value.\",\"context\":\"The request message the person is shown.\"},{\"kind\":\"component\",\"name\":\"Evaluate\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"text\":{\"type\":\"string\",\"description\":\"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"},\"allow\":{\"type\":\"array\",\"minItems\":1,\"uniqueItems\":true,\"items\":{\"enum\":[\"read\",\"write\"]},\"description\":\"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Evaluate program text. `` runs it.\",\"as\":\"Optional. Captures the fragment's rendered output instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Fail\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"message\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"message\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Stop authored work with an actionable failure. `` raises the message where it is written.\"},{\"kind\":\"component\",\"name\":\"Fetch\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"url\":{\"type\":\"string\"},\"method\":{\"type\":\"string\"},\"headers\":{\"type\":\"object\",\"additionalProperties\":{\"type\":\"string\"}},\"timeout\":{\"type\":\"string\"}},\"required\":[\"url\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\"as\":\"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"},{\"kind\":\"component\",\"name\":\"File\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\"as\":\"Optional. Captures the file's text instead of emitting it, in the reading form.\",\"context\":\"The text to write, in the writing form.\"},{\"kind\":\"component\",\"name\":\"File.Delete\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\"as\":\"Optional. Captures the empty string this renders, as for any text component.\"},{\"kind\":\"component\",\"name\":\"Glob\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"include\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1},\"exclude\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"default\":[]}},\"required\":[\"include\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"description\":\"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\"as\":\"Required. The matched paths, as a string array.\"},{\"kind\":\"component\",\"name\":\"Json\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as JSON text. `` writes the JSON where you put it.\",\"as\":\"Optional. Captures the JSON text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Parse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\"as\":\"Required. The validated value.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Query\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{},\"yq\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"value\",\"yq\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\"as\":\"Optional. Binds the selected value as data instead of writing it as JSON.\"},{\"kind\":\"component\",\"name\":\"SafeParse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"oneOf\":[{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":true},\"value\":{}},\"required\":[\"ok\",\"value\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":false},\"input\":{\"type\":\"string\"},\"errors\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"instancePath\":{\"type\":\"string\"},\"schemaPath\":{\"type\":\"string\"},\"keyword\":{\"type\":\"string\"},\"params\":{},\"message\":{\"type\":\"string\"}},\"required\":[\"instancePath\",\"schemaPath\",\"keyword\",\"params\",\"message\"],\"additionalProperties\":false}}},\"required\":[\"ok\",\"input\",\"errors\"],\"additionalProperties\":false}]},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\"as\":\"Required. The result: either the validated value or the issues that rejected it.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Slice\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"offset\":{\"type\":\"integer\",\"default\":0},\"length\":{\"type\":\"integer\",\"minimum\":1,\"default\":4096}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\"as\":\"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\"context\":\"The content whose completed rendering the window is taken from.\"},{\"kind\":\"component\",\"name\":\"Syntax\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"names\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1,\"uniqueItems\":true,\"description\":\"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\"as\":\"Optional. Captures the rendered text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"TempDir\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\"as\":\"Optional. Captures the rendered directory path instead of emitting it.\",\"context\":\"Markdown expanded with the temporary directory as its working directory.\"},{\"kind\":\"component\",\"name\":\"Test\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"timeout\":{\"type\":\"string\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\"context\":\"The body of the test: its assertions and the work they judge.\"},{\"kind\":\"component\",\"name\":\"Yaml\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as YAML text. `` writes the YAML where you put it.\",\"as\":\"Optional. Captures the YAML text instead of emitting it.\"}]},{\"kind\":\"user-provided\",\"entries\":[]}]}", - "ordinary-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `AGENTS.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | yes | Workspace package directory, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package directory, e.g. packages/workflow\"\n }\n },\n \"required\": [\n \"package\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `components/BootstrapNpmPackage.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | no | Workspace package to reserve on npm, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package to reserve on npm, e.g. packages/workflow\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `README.md`\n", - "cli-bare-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nSet the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches use this agent.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSet the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `defaultAgent` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown expanded with this provider installed.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nApprove every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are approved.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAsk about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are asked about.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAssert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `message` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\n\n**Body context:** The Markdown expected to fail.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCapture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The journal snapshot.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCapture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The child's accumulated output.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGive a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `host` | `string` | yes | |\n| `target` | `string` | no | |\n| `source` | `string` | no | |\n| `action` | `string` | no | |\n| `props` | `object` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\n\n**Body context:** The declarations for the child, then the assertions about it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStage paths for commit. `` resolves Git pathspecs from the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `paths` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCompare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, each change's path, status and previous path, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCommit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | no | |\n| `ref` | `string` | no | |\n| `verify` | `boolean` | no | |\n| `yq` | `string` | no | |\n| `maxBytes` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\n\n**Body context:** The message body, expanded before the commit is made. A ref read takes none.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a comparison's patch. `` reads a window of the unified diff text.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a committed file. `` reads the text that commit holds, not the working copy.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `commit` | `string` | yes | |\n| `path` | `string` | yes | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `prefix` | `string` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The tracked paths, and the arguments of the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nPublish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSwitch or create a branch. `` starts a missing branch at the specified base.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | no | |\n| `title` | `string` | no | |\n| `tags` | `array` | no | |\n| `assignee` | `string` | no | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\n\n**Body context:** The issue's description, for the form that files one.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect an issue tracker. `…` expands its content with the specified tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown whose issues are filed there.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGenerate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\n\n**Body context:** The complete prompt, expanded once before authorship.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli/Plan.md` (declared Markdown)\n\n### ``\n\nSend a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n| `timeout` | `string` | no | |\n| `throwOnError` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the reply instead of emitting it.\n\n**Body context:** The prompt text, in the paired form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nOpen or update a pull request. `…` uses its content as the body after ``.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `number` | `integer` | no | |\n| `title` | `string` | yes | |\n| `base` | `string` | no | |\n| `draft` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The pull request's repository, number, url, state and head and base commits.\n\n**Body context:** The pull request's body.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request checks. `` reads check runs and commit statuses for its head.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each check's kind, name, head commit and outcome.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request comments. `` reads both conversation and review comments.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request reviews. `` reads reviews from the specified pull request.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each review's author, state, body, submission time, commit and url.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nClone or use a repository. `…` expands its content in the specified checkout.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `url` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the selected checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nConfigure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `model` | `string` | no | |\n| `effort` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches run in this session.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nLaunch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The instructions the native session starts from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nTurn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in testing mode.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nExpand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli` (registered default)\n\n### ``\n\nAsk a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n| `uiSchema` | JSON Schema | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated response.\n\n**Body context:** The Markdown shown above the form.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{}\n```\n\n**Origin:** `@executablemd/web` (registered default)\n\n### ``\n\nScope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The workflow-hosted executions this scope owns.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a worktree. `…` expands its content in the worktree.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the linked checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", - "cli-json-base.txt": "{\n \"version\": 1,\n \"categories\": [\n {\n \"kind\": \"structural\",\n \"entries\": [\n {\n \"kind\": \"structural\",\n \"name\": \"All\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"All\"\n },\n \"syntax\": [\n \"……\"\n ],\n \"description\": \"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\n \"context\": \"The `` children this runs at the same time.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answer\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answer\"\n },\n \"syntax\": [\n \"\",\n \"…\"\n ],\n \"description\": \"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\n \"context\": \"A multiline template, in place of the single-line `template` prop.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answers\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answers\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\n \"context\": \"`` matchers, and the body they answer for.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Break\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Break\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Case\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Case\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\n \"context\": \"Markdown expanded when this case is selected.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Catch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Catch\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\n \"as\": \"Optional. Binds the ordinary Error by reference in this branch.\",\n \"context\": \"Recovery content.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Content\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Content\"\n },\n \"syntax\": [\n \"\",\n \"\"\n ],\n \"description\": \"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Each\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Each\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\n \"as\": \"Optional. Captures the whole rendered loop instead of emitting it.\",\n \"context\": \"Markdown rendered once per element.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Else\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Else\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\n \"context\": \"The branch taken when the enclosing condition does not hold.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Finally\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Finally\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\n \"context\": \"Completion content using the surrounding bindings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"If\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"If\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\n \"context\": \"The branch taken when the condition holds, up to an ``.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Let\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Let\"\n },\n \"syntax\": [\n \"…\",\n \"\"\n ],\n \"description\": \"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\n \"as\": \"Required. The binding name the value is available under.\",\n \"context\": \"Markdown whose rendered text becomes the binding, in the paired form.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Loop\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Loop\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\n \"context\": \"Markdown expanded once per iteration.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Output\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Output\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\n \"context\": \"The rendered output the run presents.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"PrintErrors\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"PrintErrors\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\n \"context\": \"The region whose failures are printed rather than raised.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Return\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Return\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Spawn\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Spawn\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\n \"context\": \"Markdown expanded in its own child, beside its siblings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Switch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Switch\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\n \"context\": \"Direct `` branches considered in source order.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Try\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Try\"\n },\n \"syntax\": [\n \"………\"\n ],\n \"description\": \"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\n \"context\": \"Attempted content followed by direct Catch and Finally branches.\"\n }\n ]\n },\n {\n \"kind\": \"built-in\",\n \"entries\": [\n {\n \"kind\": \"component\",\n \"name\": \"Agent\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\",\n \"context\": \"Markdown whose prompts and launches use this agent.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AgentProvider\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\",\n \"context\": \"Markdown expanded with this provider installed.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"ApproveAll\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Approve every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\",\n \"context\": \"Markdown whose permission requests are approved.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AskPermission\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Ask about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\",\n \"context\": \"Markdown whose permission requests are asked about.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Assert\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertExists\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertFalse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreater\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreaterOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLess\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLessOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStringIncludes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertThrows\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"message\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\",\n \"as\": \"Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\",\n \"context\": \"The Markdown expected to fail.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CodeBlock\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\n \"as\": \"Optional. Captures the exact fenced Markdown instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\",\n \"as\": \"Required. The journal snapshot.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectOutput\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\",\n \"as\": \"Required. The child's accumulated output.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Cwd\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read the working directory. `` renders its path without adding a newline.\",\n \"as\": \"Optional. Captures the directory path instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"DiagnosticJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Give a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Dir\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a directory. `…` changes the working directory for its content.\",\n \"context\": \"The Markdown expanded in that directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Elicit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Ask a person a structured question. `…` shows the content as the request.\",\n \"as\": \"Required. The validated answer, as a structured value.\",\n \"context\": \"The request message the person is shown.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Evaluate\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Evaluate program text. `` runs it.\",\n \"as\": \"Optional. Captures the fragment's rendered output instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Execution\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\",\n \"as\": \"Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\",\n \"context\": \"The declarations for the child, then the assertions about it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fail\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stop authored work with an actionable failure. `` raises the message where it is written.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fetch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\n \"as\": \"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\n \"as\": \"Optional. Captures the file's text instead of emitting it, in the reading form.\",\n \"context\": \"The text to write, in the writing form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File.Delete\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\n \"as\": \"Optional. Captures the empty string this renders, as for any text component.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Add\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stage paths for commit. `` resolves Git pathspecs from the working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Changes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Compare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\",\n \"as\": \"Required. The comparison, each change's path, status and previous path, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Commit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Commit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\",\n \"as\": \"Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\",\n \"context\": \"The message body, expanded before the commit is made. A ref read takes none.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Diff\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a comparison's patch. `` reads a window of the unified diff text.\",\n \"as\": \"Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.File\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a committed file. `` reads the text that commit holds, not the working copy.\",\n \"as\": \"Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Files\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"List tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\",\n \"as\": \"Required. The tracked paths, and the arguments of the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Push\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Publish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Switch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Switch or create a branch. `` starts a missing branch at the specified base.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Glob\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"description\": \"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\n \"as\": \"Required. The matched paths, as a string array.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Issue\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Read or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\",\n \"as\": \"Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\",\n \"context\": \"The issue's description, for the form that files one.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"IssueTracker\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select an issue tracker. `…` expands its content with the specified tracker in scope.\",\n \"context\": \"The Markdown whose issues are filed there.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Json\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as JSON text. `` writes the JSON where you put it.\",\n \"as\": \"Optional. Captures the JSON text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Parse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\n \"as\": \"Required. The validated value.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Plan\",\n \"origin\": {\n \"kind\": \"declared-markdown\",\n \"origin\": \"@executablemd/cli/Plan.md\",\n \"digest\": \"d97953c7f65cde0a2858761245d94e06cd31aaba6feb15622256d4dddcaafec2\"\n },\n \"sourceKind\": \"declared-markdown\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Generate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\",\n \"as\": \"Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\",\n \"context\": \"The complete prompt, expanded once before authorship.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Prompt\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Send a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\",\n \"as\": \"Optional. Captures the reply instead of emitting it.\",\n \"context\": \"The prompt text, in the paired form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Open or update a pull request. `…` uses its content as the body after ``.\",\n \"as\": \"Optional. The pull request's repository, number, url, state and head and base commits.\",\n \"context\": \"The pull request's body.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Checks\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request checks. `` reads check runs and commit statuses for its head.\",\n \"as\": \"Required. Each check's kind, name, head commit and outcome.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Comments\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request comments. `` reads both conversation and review comments.\",\n \"as\": \"Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Reviews\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n },\n \"description\": \"Read pull request reviews. `` reads reviews from the specified pull request.\",\n \"as\": \"Required. Each review's author, state, body, submission time, commit and url.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Query\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\n \"as\": \"Optional. Binds the selected value as data instead of writing it as JSON.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Repository\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Clone or use a repository. `…` expands its content in the specified checkout.\",\n \"as\": \"Optional. The path of the selected checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"SafeParse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\n \"as\": \"Required. The result: either the validated value or the issues that rejected it.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Configure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\",\n \"context\": \"Markdown whose prompts and launches run in this session.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session.Launch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Launch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\",\n \"context\": \"The instructions the native session starts from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Slice\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\n \"as\": \"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\n \"context\": \"The content whose completed rendering the window is taken from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Syntax\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\n \"as\": \"Optional. Captures the rendered text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"TempDir\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\n \"as\": \"Optional. Captures the rendered directory path instead of emitting it.\",\n \"context\": \"Markdown expanded with the temporary directory as its working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Test\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\n \"context\": \"The body of the test: its assertions and the work they judge.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Testing\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Turn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\",\n \"context\": \"The Markdown expanded in testing mode.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Verbose\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/cli\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Expand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\",\n \"as\": \"Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WebForm\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/web\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {},\n \"description\": \"Ask a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\",\n \"as\": \"Required. The validated response.\",\n \"context\": \"The Markdown shown above the form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WorkflowRun\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Scope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\",\n \"context\": \"The workflow-hosted executions this scope owns.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Worktree\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a worktree. `…` expands its content in the worktree.\",\n \"as\": \"Optional. The path of the linked checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Yaml\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as YAML text. `` writes the YAML where you put it.\",\n \"as\": \"Optional. Captures the YAML text instead of emitting it.\"\n }\n ]\n },\n {\n \"kind\": \"user-provided\",\n \"entries\": []\n }\n ]\n}\n", + "canonical-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `from` | `string` | yes | |\n| `to` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", + "catalog-base.json": "{\"version\":1,\"categories\":[{\"kind\":\"structural\",\"entries\":[{\"kind\":\"structural\",\"name\":\"All\",\"origin\":{\"kind\":\"structural\",\"construct\":\"All\"},\"syntax\":[\"……\"],\"description\":\"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\"context\":\"The `` children this runs at the same time.\"},{\"kind\":\"structural\",\"name\":\"Answer\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answer\"},\"syntax\":[\"\",\"…\"],\"description\":\"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\"context\":\"A multiline template, in place of the single-line `template` prop.\"},{\"kind\":\"structural\",\"name\":\"Answers\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Answers\"},\"syntax\":[\"…\"],\"description\":\"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\"context\":\"`` matchers, and the body they answer for.\"},{\"kind\":\"structural\",\"name\":\"Break\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Break\"},\"syntax\":[\"\"],\"description\":\"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"},{\"kind\":\"structural\",\"name\":\"Case\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Case\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\"context\":\"Markdown expanded when this case is selected.\"},{\"kind\":\"structural\",\"name\":\"Catch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Catch\"},\"syntax\":[\"…\",\"…\"],\"description\":\"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\"as\":\"Optional. Binds the ordinary Error by reference in this branch.\",\"context\":\"Recovery content.\"},{\"kind\":\"structural\",\"name\":\"Content\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Content\"},\"syntax\":[\"\",\"\"],\"description\":\"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"},{\"kind\":\"structural\",\"name\":\"Each\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Each\"},\"syntax\":[\"…\"],\"description\":\"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\"as\":\"Optional. Captures the whole rendered loop instead of emitting it.\",\"context\":\"Markdown rendered once per element.\"},{\"kind\":\"structural\",\"name\":\"Else\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Else\"},\"syntax\":[\"…\"],\"description\":\"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\"context\":\"The branch taken when the enclosing condition does not hold.\"},{\"kind\":\"structural\",\"name\":\"Finally\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Finally\"},\"syntax\":[\"…\"],\"description\":\"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\"context\":\"Completion content using the surrounding bindings.\"},{\"kind\":\"structural\",\"name\":\"If\",\"origin\":{\"kind\":\"structural\",\"construct\":\"If\"},\"syntax\":[\"…\"],\"description\":\"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\"context\":\"The branch taken when the condition holds, up to an ``.\"},{\"kind\":\"structural\",\"name\":\"Let\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Let\"},\"syntax\":[\"…\",\"\"],\"description\":\"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\"as\":\"Required. The binding name the value is available under.\",\"context\":\"Markdown whose rendered text becomes the binding, in the paired form.\"},{\"kind\":\"structural\",\"name\":\"Loop\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Loop\"},\"syntax\":[\"…\"],\"description\":\"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\"context\":\"Markdown expanded once per iteration.\"},{\"kind\":\"structural\",\"name\":\"Output\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Output\"},\"syntax\":[\"…\"],\"description\":\"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\"context\":\"The rendered output the run presents.\"},{\"kind\":\"structural\",\"name\":\"PrintErrors\",\"origin\":{\"kind\":\"structural\",\"construct\":\"PrintErrors\"},\"syntax\":[\"…\"],\"description\":\"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\"context\":\"The region whose failures are printed rather than raised.\"},{\"kind\":\"structural\",\"name\":\"Return\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Return\"},\"syntax\":[\"\"],\"description\":\"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"},{\"kind\":\"structural\",\"name\":\"Spawn\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Spawn\"},\"syntax\":[\"…\"],\"description\":\"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\"context\":\"Markdown expanded in its own child, beside its siblings.\"},{\"kind\":\"structural\",\"name\":\"Switch\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Switch\"},\"syntax\":[\"…\"],\"description\":\"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\"context\":\"Direct `` branches considered in source order.\"},{\"kind\":\"structural\",\"name\":\"Try\",\"origin\":{\"kind\":\"structural\",\"construct\":\"Try\"},\"syntax\":[\"………\"],\"description\":\"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\"context\":\"Attempted content followed by direct Catch and Finally branches.\"}]},{\"kind\":\"built-in\",\"entries\":[{\"kind\":\"component\",\"name\":\"CodeBlock\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{\"type\":\"string\"},\"language\":{\"type\":\"string\",\"pattern\":\"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"}},\"required\":[\"value\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\"as\":\"Optional. Captures the exact fenced Markdown instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Cwd\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read the working directory. `` renders its path without adding a newline.\",\"as\":\"Optional. Captures the directory path instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Dir\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Create or use a directory. `…` changes the working directory for its content.\",\"context\":\"The Markdown expanded in that directory.\"},{\"kind\":\"component\",\"name\":\"Elicit\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Ask a person a structured question. `…` shows the content as the request.\",\"as\":\"Required. The validated answer, as a structured value.\",\"context\":\"The request message the person is shown.\"},{\"kind\":\"component\",\"name\":\"Evaluate\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"text\":{\"type\":\"string\",\"description\":\"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"},\"allow\":{\"type\":\"array\",\"minItems\":1,\"uniqueItems\":true,\"items\":{\"enum\":[\"read\",\"write\"]},\"description\":\"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Evaluate program text. `` runs it.\",\"as\":\"Optional. Captures the fragment's rendered output instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Fail\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"message\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"message\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Stop authored work with an actionable failure. `` raises the message where it is written.\"},{\"kind\":\"component\",\"name\":\"Fetch\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"url\":{\"type\":\"string\"},\"method\":{\"type\":\"string\"},\"headers\":{\"type\":\"object\",\"additionalProperties\":{\"type\":\"string\"}},\"timeout\":{\"type\":\"string\"}},\"required\":[\"url\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\"as\":\"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"},{\"kind\":\"component\",\"name\":\"File\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\"as\":\"Optional. Captures the file's text instead of emitting it, in the reading form.\",\"context\":\"The text to write, in the writing form.\"},{\"kind\":\"component\",\"name\":\"File.Copy\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"from\":{\"type\":\"string\",\"minLength\":1},\"to\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"from\",\"to\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"}},{\"kind\":\"component\",\"name\":\"File.Delete\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"path\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\"as\":\"Optional. Captures the empty string this renders, as for any text component.\"},{\"kind\":\"component\",\"name\":\"Glob\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"include\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1},\"exclude\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"default\":[]}},\"required\":[\"include\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"description\":\"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\"as\":\"Required. The matched paths, as a string array.\"},{\"kind\":\"component\",\"name\":\"Json\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as JSON text. `` writes the JSON where you put it.\",\"as\":\"Optional. Captures the JSON text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"Parse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\"},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\"as\":\"Required. The validated value.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Query\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"value\":{},\"yq\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"value\",\"yq\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\"as\":\"Optional. Binds the selected value as data instead of writing it as JSON.\"},{\"kind\":\"component\",\"name\":\"SafeParse\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"schema\":{}},\"required\":[\"schema\"],\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"value\",\"returns\":{\"$schema\":\"http://json-schema.org/draft-07/schema#\",\"oneOf\":[{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":true},\"value\":{}},\"required\":[\"ok\",\"value\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"ok\":{\"const\":false},\"input\":{\"type\":\"string\"},\"errors\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"instancePath\":{\"type\":\"string\"},\"schemaPath\":{\"type\":\"string\"},\"keyword\":{\"type\":\"string\"},\"params\":{},\"message\":{\"type\":\"string\"}},\"required\":[\"instancePath\",\"schemaPath\",\"keyword\",\"params\",\"message\"],\"additionalProperties\":false}}},\"required\":[\"ok\",\"input\",\"errors\"],\"additionalProperties\":false}]},\"description\":\"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\"as\":\"Required. The result: either the validated value or the issues that rejected it.\",\"context\":\"The JSON text to parse.\"},{\"kind\":\"component\",\"name\":\"Slice\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"offset\":{\"type\":\"integer\",\"default\":0},\"length\":{\"type\":\"integer\",\"minimum\":1,\"default\":4096}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\"as\":\"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\"context\":\"The content whose completed rendering the window is taken from.\"},{\"kind\":\"component\",\"name\":\"Syntax\",\"origin\":{\"kind\":\"protected\",\"origin\":\"@executablemd/core\"},\"sourceKind\":\"protected\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{\"names\":{\"type\":\"array\",\"items\":{\"type\":\"string\"},\"minItems\":1,\"uniqueItems\":true,\"description\":\"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\"as\":\"Optional. Captures the rendered text instead of emitting it.\"},{\"kind\":\"component\",\"name\":\"TempDir\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\"as\":\"Optional. Captures the rendered directory path instead of emitting it.\",\"context\":\"Markdown expanded with the temporary directory as its working directory.\"},{\"kind\":\"component\",\"name\":\"Test\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\",\"paired\"],\"props\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"timeout\":{\"type\":\"string\"}},\"additionalProperties\":false},\"captures\":[],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\"context\":\"The body of the test: its assertions and the work they judge.\"},{\"kind\":\"component\",\"name\":\"Yaml\",\"origin\":{\"kind\":\"registered\",\"origin\":\"@executablemd/core\",\"reserved\":false},\"sourceKind\":\"registered\",\"inspectability\":\"complete\",\"forms\":[\"self-closing\"],\"props\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"captures\":[\"value\"],\"returnMode\":\"text\",\"returns\":{\"type\":\"string\"},\"description\":\"Render a value as YAML text. `` writes the YAML where you put it.\",\"as\":\"Optional. Captures the YAML text instead of emitting it.\"}]},{\"kind\":\"user-provided\",\"entries\":[]}]}", + "ordinary-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `from` | `string` | yes | |\n| `to` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `AGENTS.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | yes | Workspace package directory, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package directory, e.g. packages/workflow\"\n }\n },\n \"required\": [\n \"package\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `components/BootstrapNpmPackage.md`\n\n### ``\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `package` | `string` | no | Workspace package to reserve on npm, e.g. packages/workflow |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"package\": {\n \"type\": \"string\",\n \"pattern\": \"^packages/[a-z0-9][a-z0-9._-]*$\",\n \"description\": \"Workspace package to reserve on npm, e.g. packages/workflow\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `README.md`\n", + "cli-bare-base.txt": "## Built-in structural syntax\n\n### ``\n\nRun tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\n\n**Syntax:**\n\n```md\n……\n```\n\n**Body context:** The `` children this runs at the same time.\n\n### ``\n\nSupply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\n\n**Syntax:**\n\n```md\n\n…\n```\n\n**Body context:** A multiline template, in place of the single-line `template` prop.\n\n### ``\n\nAnswer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** `` matchers, and the body they answer for.\n\n### ``\n\nExit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nDefine one branch of a ``. `…` matches with `===`; `…` is the final fallback.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**Body context:** Markdown expanded when this case is selected.\n\n### ``\n\nHandle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\n\n**Syntax:**\n\n```md\n…\n…\n```\n\n**`as`:** Optional. Binds the ordinary Error by reference in this branch.\n\n**Body context:** Recovery content.\n\n### ``\n\nRender what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\"footer\"`.\n\n**Syntax:**\n\n```md\n\n\n```\n\n### ``\n\nRepeat content for each item in an array. `…` binds each one to `item` inside.\n\n**Syntax:**\n\n```md\n…\n```\n\n**`as`:** Optional. Captures the whole rendered loop instead of emitting it.\n\n**Body context:** Markdown rendered once per element.\n\n### ``\n\nThe branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the enclosing condition does not hold.\n\n### ``\n\nFinish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Completion content using the surrounding bindings.\n\n### ``\n\nExpand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The branch taken when the condition holds, up to an ``.\n\n### ``\n\nBind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\n\n**Syntax:**\n\n```md\n…\n\n```\n\n**`as`:** Required. The binding name the value is available under.\n\n**Body context:** Markdown whose rendered text becomes the binding, in the paired form.\n\n### ``\n\nRepeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded once per iteration.\n\n### ``\n\nRestrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The rendered output the run presents.\n\n### ``\n\nConvert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** The region whose failures are printed rather than raised.\n\n### ``\n\nReturn a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\n\n**Syntax:**\n\n```md\n\n```\n\n### ``\n\nRun a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Markdown expanded in its own child, beside its siblings.\n\n### ``\n\nChoose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\n\n**Syntax:**\n\n```md\n…\n```\n\n**Body context:** Direct `` branches considered in source order.\n\n### ``\n\nRecover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\n\n**Syntax:**\n\n```md\n………\n```\n\n**Body context:** Attempted content followed by direct Catch and Finally branches.\n\n## Built-in components\n\n### ``\n\nSet the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches use this agent.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nSet the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `defaultAgent` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown expanded with this provider installed.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nApprove every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are approved.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAsk about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose permission requests are asked about.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nAssert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `expr` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `msg` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `actual`, `expected` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\n\n**Body context:** The expected value, in place of the `expected` prop.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nAssert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `message` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\n\n**Body context:** The Markdown expected to fail.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nShow arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | `string` | yes | |\n| `language` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the exact fenced Markdown instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nCapture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The journal snapshot.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCapture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The child's accumulated output.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the directory path instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGive a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a directory. `…` changes the working directory for its content.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in that directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nAsk a person a structured question. `…` shows the content as the request.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated answer, as a structured value.\n\n**Body context:** The request message the person is shown.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nEvaluate program text. `` runs it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | The program to evaluate, for the self-closing form. Written instead of content, never beside it. |\n| `allow` | `array` | no | Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the fragment's rendered output instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `host` | `string` | yes | |\n| `target` | `string` | no | |\n| `source` | `string` | no | |\n| `action` | `string` | no | |\n| `props` | `object` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\n\n**Body context:** The declarations for the child, then the assertions about it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nStop authored work with an actionable failure. `` raises the message where it is written.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nFetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `method` | `string` | no | |\n| `headers` | `object` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the file's text instead of emitting it, in the reading form.\n\n**Body context:** The text to write, in the writing form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `from` | `string` | yes | |\n| `to` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDelete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the empty string this renders, as for any text component.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nStage paths for commit. `` resolves Git pathspecs from the working directory.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `paths` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCompare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, each change's path, status and previous path, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nCommit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `message` | `string` | no | |\n| `ref` | `string` | no | |\n| `verify` | `boolean` | no | |\n| `yq` | `string` | no | |\n| `maxBytes` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\n\n**Body context:** The message body, expanded before the commit is made. A ref read takes none.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a comparison's patch. `` reads a window of the unified diff text.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `compare` | JSON Schema | yes | |\n| `base` | `string` | no | |\n| `head` | `string` | no | |\n| `paths` | `array` | no | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead a committed file. `` reads the text that commit holds, not the working copy.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `commit` | `string` | yes | |\n| `path` | `string` | yes | |\n| `offset` | `integer` | no | |\n| `limit` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `prefix` | `string` | no | |\n| `limit` | `integer` | no | |\n| `cursor` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The tracked paths, and the arguments of the next page or null.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nPublish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSwitch or create a branch. `` starts a missing branch at the specified base.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The matched paths, as a string array.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | no | |\n| `title` | `string` | no | |\n| `tags` | `array` | no | |\n| `assignee` | `string` | no | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\n\n**Body context:** The issue's description, for the form that files one.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect an issue tracker. `…` expands its content with the specified tracker in scope.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown whose issues are filed there.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the JSON text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Errors on invalid content.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated value.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nGenerate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\n\n**Forms:** `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\n\n**Body context:** The complete prompt, expanded once before authorship.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli/Plan.md` (declared Markdown)\n\n### ``\n\nSend a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `text` | `string` | no | |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n| `timeout` | `string` | no | |\n| `throwOnError` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the reply instead of emitting it.\n\n**Body context:** The prompt text, in the paired form.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nOpen or update a pull request. `…` uses its content as the body after ``.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `number` | `integer` | no | |\n| `title` | `string` | yes | |\n| `base` | `string` | no | |\n| `draft` | `boolean` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The pull request's repository, number, url, state and head and base commits.\n\n**Body context:** The pull request's body.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request checks. `` reads check runs and commit statuses for its head.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each check's kind, name, head commit and outcome.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request comments. `` reads both conversation and review comments.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRead pull request reviews. `` reads reviews from the specified pull request.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `url` | `string` | yes | |\n| `provider` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. Each review's author, state, body, submission time, commit and url.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nSelect part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `value` | JSON Schema | yes | |\n| `yq` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Binds the selected value as data instead of writing it as JSON.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nClone or use a repository. `…` expands its content in the specified checkout.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `url` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the selected checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nParse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The result: either the validated value or the issues that rejected it.\n\n**Body context:** The JSON text to parse.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nConfigure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `model` | `string` | no | |\n| `effort` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** Markdown whose prompts and launches run in this session.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nLaunch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `agent` | `string` | no | |\n| `session` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The instructions the native session starts from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nShow a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `offset` | `integer` | no | |\n| `length` | `integer` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the resulting text, including any range note, instead of emitting it.\n\n**Body context:** The content whose completed rendering the window is taken from.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nRun work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered directory path instead of emitting it.\n\n**Body context:** Markdown expanded with the temporary directory as its working directory.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nDefine a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | no | |\n| `timeout` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The body of the test: its assertions and the work they judge.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nTurn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The Markdown expanded in testing mode.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nExpand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\n\n**Forms:** ``, `…`\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/cli` (registered default)\n\n### ``\n\nAsk a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `schema` | JSON Schema | yes | |\n| `uiSchema` | JSON Schema | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Required. The validated response.\n\n**Body context:** The Markdown shown above the form.\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{}\n```\n\n**Origin:** `@executablemd/web` (registered default)\n\n### ``\n\nScope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Body context:** The workflow-hosted executions this scope owns.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/testing` (registered default)\n\n### ``\n\nCreate or use a worktree. `…` expands its content in the worktree.\n\n**Forms:** ``, `…`\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `name` | `string` | yes | |\n| `branch` | `string` | yes | |\n| `base` | `string` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**`as`:** Optional. The path of the linked checkout.\n\n**Body context:** The Markdown expanded in that checkout.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/workflow/composition` (registered default)\n\n### ``\n\nRender a value as YAML text. `` writes the YAML where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**`as`:** Optional. Captures the YAML text instead of emitting it.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n## User-provided components\n\nNo components were found in the configured includes.\n", + "cli-json-base.txt": "{\n \"version\": 1,\n \"categories\": [\n {\n \"kind\": \"structural\",\n \"entries\": [\n {\n \"kind\": \"structural\",\n \"name\": \"All\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"All\"\n },\n \"syntax\": [\n \"……\"\n ],\n \"description\": \"Run tasks in parallel. `firstsecond` expands every task at the same time, waits for them all to succeed, and preserves their Markdown order. Write at least two `` children directly inside it; if one fails, unfinished tasks are cancelled and `` produces no output.\",\n \"context\": \"The `` children this runs at the same time.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answer\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answer\"\n },\n \"syntax\": [\n \"\",\n \"…\"\n ],\n \"description\": \"Supply one answer inside ``. `` answers any elicitation its template matches — `{?name}` matches any text. The first matching `` wins.\",\n \"context\": \"A multiline template, in place of the single-line `template` prop.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Answers\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Answers\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Answer any `` in its content without asking a person. `…` replies from the `` matchers declared inside it, reaching elicitations from nested components too. `delegate` passes an unmatched one outward instead of failing.\",\n \"context\": \"`` matchers, and the body they answer for.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Break\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Break\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Exit the nearest enclosing ``. `` stops the current iteration where it is; nothing after it in that iteration runs.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Case\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Case\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Define one branch of a ``. `…` matches with `===`; `…` is the final fallback.\",\n \"context\": \"Markdown expanded when this case is selected.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Catch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Catch\"\n },\n \"syntax\": [\n \"…\",\n \"…\"\n ],\n \"description\": \"Handle a failure in the preceding Try body. `{error.message}` runs after clean release; its bindings stay local. Cancellation skips this branch.\",\n \"as\": \"Optional. Binds the ordinary Error by reference in this branch.\",\n \"context\": \"Recovery content.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Content\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Content\"\n },\n \"syntax\": [\n \"\",\n \"\"\n ],\n \"description\": \"Render what the caller wrote inside this component. `` renders all of it; `` renders just the part the caller marked `slot=\\\"footer\\\"`.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Each\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Each\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content for each item in an array. `…` binds each one to `item` inside.\",\n \"as\": \"Optional. Captures the whole rendered loop instead of emitting it.\",\n \"context\": \"Markdown rendered once per element.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Else\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Else\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"The branch `` takes when its condition is false. `…` is written directly inside an ``, and is an error anywhere else.\",\n \"context\": \"The branch taken when the enclosing condition does not hold.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Finally\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Finally\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Finish a Try after its attempted body and recovery. `Cleanup.` also runs and joins on terminal Stop. Resumable Exit leaves an unentered branch pending; failed release and infrastructure failure prevent new entry.\",\n \"context\": \"Completion content using the surrounding bindings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"If\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"If\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Expand content only when a condition is true. `…` expands its content, or the `` branch instead. The branch not taken never runs.\",\n \"context\": \"The branch taken when the condition holds, up to an ``.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Let\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Let\"\n },\n \"syntax\": [\n \"…\",\n \"\"\n ],\n \"description\": \"Bind a name for the rest of the region. `…` binds what its content rendered; `` binds the value. `select` narrows the rendered content to one CSS selection.\",\n \"as\": \"Required. The binding name the value is available under.\",\n \"context\": \"Markdown whose rendered text becomes the binding, in the paired form.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Loop\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Loop\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Repeat content up to `max` times. `…` expands its content again and again until a `` inside it, or until `max` is reached. `max` is required.\",\n \"context\": \"Markdown expanded once per iteration.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Output\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Output\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Restrict what a document or component renders. `…` becomes its entire output; anything outside the region is not rendered.\",\n \"context\": \"The rendered output the run presents.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"PrintErrors\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"PrintErrors\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Convert thrown errors into output without failing. `…` renders any failure inside it as part of the output.\",\n \"context\": \"The region whose failures are printed rather than raised.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Return\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Return\"\n },\n \"syntax\": [\n \"\"\n ],\n \"description\": \"Return a value instead of rendered markdown. `` hands the value to the caller, checked against the component's declared `returns` schema.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Spawn\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Spawn\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Run a task in parallel inside of ``. Write `…` directly inside ``; bindings made in its content stay with that task, and `` or `` cannot affect work outside it.\",\n \"context\": \"Markdown expanded in its own child, beside its siblings.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Switch\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Switch\"\n },\n \"syntax\": [\n \"…\"\n ],\n \"description\": \"Choose one branch by comparing a value with `===`. `……` expands the first matching case, or the final default when none matches.\",\n \"context\": \"Direct `` branches considered in source order.\"\n },\n {\n \"kind\": \"structural\",\n \"name\": \"Try\",\n \"origin\": {\n \"kind\": \"structural\",\n \"construct\": \"Try\"\n },\n \"syntax\": [\n \"………\"\n ],\n \"description\": \"Recover an ordinary failure after its resources close. `…fallback` keeps the rendered prefix and stops the attempted body at failure. Write Catch, Finally, or both. Failed release and infrastructure failures end execution.\",\n \"context\": \"Attempted content followed by direct Catch and Finally branches.\"\n }\n ]\n },\n {\n \"kind\": \"built-in\",\n \"entries\": [\n {\n \"kind\": \"component\",\n \"name\": \"Agent\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent for every prompt in its content. `…` reaches prompts sent from nested components too. `` checks the agent is available.\",\n \"context\": \"Markdown whose prompts and launches use this agent.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AgentProvider\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"defaultAgent\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"name\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Set the agent provider for its content. `…` applies to everything inside, where `defaultAgent` sets the agent to use when none is named and `timeout` bounds each prompt. An unknown provider fails before the content runs.\",\n \"context\": \"Markdown expanded with this provider installed.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"ApproveAll\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Approve every permission request in its content. `…` answers for the agent so it never stops to ask you; requests offering no allow option are denied.\",\n \"context\": \"Markdown whose permission requests are approved.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AskPermission\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Ask about every permission request in its content. `…` puts each request to you; with no interactive terminal, or no valid answer, it denies.\",\n \"context\": \"Markdown whose permission requests are asked about.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Assert\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is truthy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertExists\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is neither null nor undefined — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertFalse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"expr\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a value is falsy — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreater\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertGreaterOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is greater than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLess\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertLessOrEqual\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that one number is less than or equal to another — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string matches a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not deeply equal — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotMatch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string does not match a pattern — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertNotStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are not the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStrictEquals\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that two values are the same, compared with `===` — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertStringIncludes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"msg\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [\n \"actual\",\n \"expected\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that a string contains a substring — ``. The optional `msg` prop replaces the reported failure message.\",\n \"as\": \"Optional. The diagnostic report this assertion rendered, as text — a passing assertion renders one only while testing or verbose output is on, so the binding is empty otherwise. A failing assertion does not return.\",\n \"context\": \"The expected value, in place of the `expected` prop.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"AssertThrows\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"message\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Assert that its content fails. `…` passes only if the content fails with a matching message. `message` is required and takes a string or a regular expression.\",\n \"as\": \"Optional. The complete caught error segment, bound by reference — its `message`, `source` and structured `cause` as they were raised, not a description of them.\",\n \"context\": \"The Markdown expected to fail.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CodeBlock\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"string\"\n },\n \"language\": {\n \"type\": \"string\",\n \"pattern\": \"^[A-Za-z0-9][A-Za-z0-9._+#-]*$\"\n }\n },\n \"required\": [\n \"value\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show arbitrary text as a fenced Markdown code block. `` chooses a fence the value cannot close.\",\n \"as\": \"Optional. Captures the exact fenced Markdown instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's journal so a test can assert on it. `` goes inside ``, beside ``. It reads a journal the run already has — pair it with `` to create one.\",\n \"as\": \"Required. The journal snapshot.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"CollectOutput\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Capture a child execution's output so a test can assert on it. `` goes inside ``, before the assertions, and is invalid anywhere else. It changes nothing about the run, and a child that fails partway still leaves what it printed.\",\n \"as\": \"Required. The child's accumulated output.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Cwd\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read the working directory. `` renders its path without adding a newline.\",\n \"as\": \"Optional. Captures the directory path instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"DiagnosticJournal\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Give a child execution a journal of its own. `` goes inside ``, before the assertions, and is invalid anywhere else. Without it the child keeps no journal you can collect — with it, `` has one to read.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Dir\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a directory. `…` changes the working directory for its content.\",\n \"context\": \"The Markdown expanded in that directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Elicit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Ask a person a structured question. `…` shows the content as the request.\",\n \"as\": \"Required. The validated answer, as a structured value.\",\n \"context\": \"The request message the person is shown.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Evaluate\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\",\n \"description\": \"The program to evaluate, for the self-closing form. Written instead of content, never beside it.\"\n },\n \"allow\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"items\": {\n \"enum\": [\n \"read\",\n \"write\"\n ]\n },\n \"description\": \"Optional. Which effect classes the program may draw on, narrowing what this host already installed. Omitted asks for `read`.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Evaluate program text. `` runs it.\",\n \"as\": \"Optional. Captures the fragment's rendered output instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Execution\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"host\": {\n \"type\": \"string\"\n },\n \"target\": {\n \"type\": \"string\"\n },\n \"source\": {\n \"type\": \"string\"\n },\n \"action\": {\n \"type\": \"string\"\n },\n \"props\": {\n \"type\": \"object\"\n }\n },\n \"required\": [\n \"host\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run another document from inside a test, and assert on how it finished. `…` runs it for real, with its own journal and output. Pass `source` instead of `target` to supply the markdown directly, and `props` for the document's properties.\",\n \"as\": \"Optional. The child's outcome: a settled result, or a suspension. Without it a settled failure fails the owning test rather than passing vacuously.\",\n \"context\": \"The declarations for the child, then the assertions about it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fail\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"message\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stop authored work with an actionable failure. `` raises the message where it is written.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Fetch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\"\n },\n \"method\": {\n \"type\": \"string\"\n },\n \"headers\": {\n \"type\": \"object\",\n \"additionalProperties\": {\n \"type\": \"string\"\n }\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Fetch a URL. `` binds the response, and any status is data you can branch on. Without `as`, a non-2xx status fails. Only GET and HEAD methods currently supported.\",\n \"as\": \"Optional. Captures the response, which is what makes a non-2xx status data instead of a failure.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Read or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\",\n \"as\": \"Optional. Captures the file's text instead of emitting it, in the reading form.\",\n \"context\": \"The text to write, in the writing form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"File.Copy\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"from\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"to\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"from\",\n \"to\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n }\n },\n {\n \"kind\": \"component\",\n \"name\": \"File.Delete\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Delete a file. `` removes it. It does not error if the file doesn't exist, and produces no output.\",\n \"as\": \"Optional. Captures the empty string this renders, as for any text component.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Add\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"minLength\": 1\n },\n {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n ]\n }\n },\n \"required\": [\n \"paths\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Stage paths for commit. `` resolves Git pathspecs from the working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Changes\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"changes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"A\",\n \"M\",\n \"D\",\n \"R\",\n \"T\",\n \"U\"\n ]\n },\n \"previousPath\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"path\",\n \"status\",\n \"previousPath\"\n ],\n \"additionalProperties\": false\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"changes\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Compare what changed. `` reports each changed path and its status for unstaged, staged or two commits.\",\n \"as\": \"Required. The comparison, each change's path, status and previous path, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Commit\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"message\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"ref\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"verify\": {\n \"type\": \"boolean\"\n },\n \"yq\": {\n \"type\": \"string\"\n },\n \"maxBytes\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"anyOf\": [\n {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"next\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"prev\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"last\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"value\",\n \"next\",\n \"prev\",\n \"last\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Commit staged changes, or read an existing commit. `Prepare 1.4` uses its expanded content as the commit message. `` reads that commit's metadata and runs the checkout's configured signature verifier; your Markdown decides what the result permits.\",\n \"as\": \"Required. Creating binds the full object id of the new commit. A ref read binds value, next, prev and last: the yq selection and the queries that read its neighbouring pages.\",\n \"context\": \"The message body, expanded before the commit is made. A ref read takes none.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Diff\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"head\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"comparison\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"unstaged\"\n }\n },\n \"required\": [\n \"compare\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"staged\"\n },\n \"base\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"compare\",\n \"base\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"compare\": {\n \"const\": \"commits\"\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"compare\",\n \"base\",\n \"head\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"compare\": {\n \"enum\": [\n \"unstaged\",\n \"staged\",\n \"commits\"\n ]\n },\n \"base\": {\n \"type\": \"string\"\n },\n \"head\": {\n \"type\": \"string\"\n },\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"compare\",\n \"offset\",\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"comparison\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a comparison's patch. `` reads a window of the unified diff text.\",\n \"as\": \"Required. The comparison, the patch window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.File\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"path\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"text\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"commit\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"offset\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"offset\",\n \"limit\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"commit\",\n \"path\",\n \"text\",\n \"offset\",\n \"length\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Read a committed file. `` reads the text that commit holds, not the working copy.\",\n \"as\": \"Required. The resolved commit, the path, the text window, its offset, the whole length, and the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Files\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"paths\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"next\": {\n \"type\": [\n \"object\",\n \"null\"\n ],\n \"properties\": {\n \"prefix\": {\n \"type\": \"string\"\n },\n \"limit\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"cursor\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"limit\",\n \"cursor\"\n ],\n \"additionalProperties\": false\n }\n },\n \"required\": [\n \"paths\",\n \"next\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"List tracked files. `` lists the selected repository's tracked paths, bounded and continuable.\",\n \"as\": \"Required. The tracked paths, and the arguments of the next page or null.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Push\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Publish the current branch. `` pushes its current commit to the same branch on `origin` without forcing.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Git.Switch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Switch or create a branch. `` starts a missing branch at the specified base.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Glob\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n },\n \"description\": \"List files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\",\n \"as\": \"Required. The matched paths, as a string array.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Issue\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"description\": {\n \"type\": \"string\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"assignee\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"url\",\n \"title\",\n \"description\",\n \"tags\",\n \"assignee\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Read or file an issue. `` reads one. `…` files its content in the issue tracker in scope.\",\n \"as\": \"Required for a read, which binds url, title, description, tags and assignee. A file binds the url alone.\",\n \"context\": \"The issue's description, for the form that files one.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"IssueTracker\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select an issue tracker. `…` expands its content with the specified tracker in scope.\",\n \"context\": \"The Markdown whose issues are filed there.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Json\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as JSON text. `` writes the JSON where you put it.\",\n \"as\": \"Optional. Captures the JSON text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Parse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\"\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Errors on invalid content.\",\n \"as\": \"Required. The validated value.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Plan\",\n \"origin\": {\n \"kind\": \"declared-markdown\",\n \"origin\": \"@executablemd/cli/Plan.md\",\n \"digest\": \"d97953c7f65cde0a2858761245d94e06cd31aaba6feb15622256d4dddcaafec2\"\n },\n \"sourceKind\": \"declared-markdown\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"session\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Generate program text from a prompt. `Ask for the user's age.` emits the approved program text; `` runs it.\",\n \"as\": \"Binds the exact approved program source and emits nothing. Omitted, that source is emitted where the component is written.\",\n \"context\": \"The complete prompt, expanded once before authorship.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Prompt\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"text\": {\n \"type\": \"string\"\n },\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n },\n \"throwOnError\": {\n \"type\": \"boolean\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Send a prompt and render the reply. `…` sends its content; `` sends the prop. `agent`, `session` and `timeout` override the surrounding scope. A failed prompt renders what it got and the document continues — `throwOnError` stops it instead.\",\n \"as\": \"Optional. Captures the reply instead of emitting it.\",\n \"context\": \"The prompt text, in the paired form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"title\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"draft\": {\n \"type\": \"boolean\",\n \"default\": false\n }\n },\n \"required\": [\n \"title\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"object\",\n \"properties\": {\n \"repository\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"locatorFingerprint\": {\n \"type\": \"string\",\n \"pattern\": \"^[0-9a-f]{64}$\"\n },\n \"requestedBase\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"creationCommit\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"primaryBranch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"objectFormat\": {\n \"enum\": [\n \"sha1\",\n \"sha256\"\n ]\n }\n },\n \"required\": [\n \"name\",\n \"locatorFingerprint\",\n \"requestedBase\",\n \"creationCommit\",\n \"primaryBranch\",\n \"objectFormat\"\n ],\n \"additionalProperties\": false\n },\n \"providerId\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"number\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"state\": {\n \"const\": \"open\"\n },\n \"headSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n },\n \"baseSha\": {\n \"type\": \"string\",\n \"pattern\": \"^([0-9a-f]{40}|[0-9a-f]{64})$\"\n }\n },\n \"required\": [\n \"repository\",\n \"providerId\",\n \"number\",\n \"url\",\n \"state\",\n \"headSha\",\n \"baseSha\"\n ],\n \"additionalProperties\": false\n },\n \"description\": \"Open or update a pull request. `…` uses its content as the body after ``.\",\n \"as\": \"Optional. The pull request's repository, number, url, state and head and base commits.\",\n \"context\": \"The pull request's body.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Checks\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"check-run\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"status\": {\n \"enum\": [\n \"queued\",\n \"in_progress\",\n \"completed\",\n \"waiting\",\n \"requested\",\n \"pending\"\n ]\n },\n \"conclusion\": {\n \"enum\": [\n \"success\",\n \"failure\",\n \"neutral\",\n \"cancelled\",\n \"skipped\",\n \"timed_out\",\n \"action_required\",\n null\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"startedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"completedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"title\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"summary\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"text\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"status\",\n \"conclusion\",\n \"url\",\n \"startedAt\",\n \"completedAt\",\n \"title\",\n \"summary\",\n \"text\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"commit-status\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"headSha\": {\n \"type\": \"string\"\n },\n \"name\": {\n \"type\": \"string\"\n },\n \"state\": {\n \"enum\": [\n \"error\",\n \"failure\",\n \"pending\",\n \"success\"\n ]\n },\n \"description\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"headSha\",\n \"name\",\n \"state\",\n \"description\",\n \"url\",\n \"createdAt\",\n \"updatedAt\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request checks. `` reads check runs and commit statuses for its head.\",\n \"as\": \"Required. Each check's kind, name, head commit and outcome.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Comments\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"conversation\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"kind\": {\n \"const\": \"review\"\n },\n \"id\": {\n \"type\": \"string\"\n },\n \"reviewId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"createdAt\": {\n \"type\": \"string\"\n },\n \"updatedAt\": {\n \"type\": \"string\"\n },\n \"url\": {\n \"type\": \"string\"\n },\n \"path\": {\n \"type\": \"string\"\n },\n \"diffHunk\": {\n \"type\": \"string\"\n },\n \"commitSha\": {\n \"type\": \"string\"\n },\n \"originalCommitSha\": {\n \"type\": \"string\"\n },\n \"line\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"side\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"startLine\": {\n \"type\": [\n \"integer\",\n \"null\"\n ]\n },\n \"startSide\": {\n \"enum\": [\n \"left\",\n \"right\",\n null\n ]\n },\n \"inReplyToId\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n }\n },\n \"required\": [\n \"kind\",\n \"id\",\n \"reviewId\",\n \"author\",\n \"body\",\n \"createdAt\",\n \"updatedAt\",\n \"url\",\n \"path\",\n \"diffHunk\",\n \"commitSha\",\n \"originalCommitSha\",\n \"line\",\n \"side\",\n \"startLine\",\n \"startSide\",\n \"inReplyToId\"\n ],\n \"additionalProperties\": false\n }\n ]\n }\n },\n \"description\": \"Read pull request comments. `` reads both conversation and review comments.\",\n \"as\": \"Required. Each comment's kind, author, body, timestamps and url, and a review comment's file, hunk and line.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"PullRequest.Reviews\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"provider\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n },\n \"author\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"state\": {\n \"enum\": [\n \"approved\",\n \"changes-requested\",\n \"commented\",\n \"dismissed\",\n \"pending\"\n ]\n },\n \"body\": {\n \"type\": \"string\"\n },\n \"submittedAt\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"commitSha\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"url\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"id\",\n \"author\",\n \"state\",\n \"body\",\n \"submittedAt\",\n \"commitSha\",\n \"url\"\n ],\n \"additionalProperties\": false\n }\n },\n \"description\": \"Read pull request reviews. `` reads reviews from the specified pull request.\",\n \"as\": \"Required. Each review's author, state, body, submission time, commit and url.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Query\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {},\n \"yq\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"value\",\n \"yq\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Select part of a value with a yq expression. `` binds the scripts object; the same element without `as` writes the selected value as JSON. Text is decoded only where the expression says `from_json` or `from_yaml`, and an expression that selects nothing or several values says to collect them with `[ … ]`.\",\n \"as\": \"Optional. Binds the selected value as data instead of writing it as JSON.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Repository\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"url\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"url\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Clone or use a repository. `…` expands its content in the specified checkout.\",\n \"as\": \"Optional. The path of the selected checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"SafeParse\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"oneOf\": [\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": true\n },\n \"value\": {}\n },\n \"required\": [\n \"ok\",\n \"value\"\n ],\n \"additionalProperties\": false\n },\n {\n \"type\": \"object\",\n \"properties\": {\n \"ok\": {\n \"const\": false\n },\n \"input\": {\n \"type\": \"string\"\n },\n \"errors\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"instancePath\": {\n \"type\": \"string\"\n },\n \"schemaPath\": {\n \"type\": \"string\"\n },\n \"keyword\": {\n \"type\": \"string\"\n },\n \"params\": {},\n \"message\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"instancePath\",\n \"schemaPath\",\n \"keyword\",\n \"params\",\n \"message\"\n ],\n \"additionalProperties\": false\n }\n }\n },\n \"required\": [\n \"ok\",\n \"input\",\n \"errors\"\n ],\n \"additionalProperties\": false\n }\n ]\n },\n \"description\": \"Parse a value using a JSON schema. `…` parses its content. Binds a result object instead of erroring.\",\n \"as\": \"Required. The result: either the validated value or the issues that rejected it.\",\n \"context\": \"The JSON text to parse.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"model\": {\n \"type\": \"string\"\n },\n \"effort\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Configure one Agent conversation for its content. `…` uses that exact session and configuration for prompts and native launches from nested components. A self-closing Session places or validates the conversation without sending a prompt.\",\n \"context\": \"Markdown whose prompts and launches run in this session.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Session.Launch\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"agent\": {\n \"type\": \"string\"\n },\n \"session\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Launch a coding agent with prepared context. `…` makes its content the agent's starting context, hands the agent's own interface the terminal, and continues when you exit it.\",\n \"context\": \"The instructions the native session starts from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Slice\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"offset\": {\n \"type\": \"integer\",\n \"default\": 0\n },\n \"length\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"default\": 4096\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Show a window of rendered text. `…` counts Unicode code points and labels partial excerpts.\",\n \"as\": \"Optional. Captures the resulting text, including any range note, instead of emitting it.\",\n \"context\": \"The content whose completed rendering the window is taken from.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Syntax\",\n \"origin\": {\n \"kind\": \"protected\",\n \"origin\": \"@executablemd/core\"\n },\n \"sourceKind\": \"protected\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Inspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\",\n \"as\": \"Optional. Captures the rendered text instead of emitting it.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"TempDir\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Run work in a temporary working directory. `…` expands its content with the temporary directory as the working directory, so `` and commands inside write there rather than in the current one. `` renders the path instead.\",\n \"as\": \"Optional. Captures the rendered directory path instead of emitting it.\",\n \"context\": \"Markdown expanded with the temporary directory as its working directory.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Test\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"timeout\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Define a test. `…` runs under `xmd test`, or inside a `` region; elsewhere it is skipped. A failing command or assertion inside fails the test rather than the document.\",\n \"context\": \"The body of the test: its assertions and the work they judge.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Testing\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Turn on testing for its content. `…` runs the `` elements inside and reports them; a failing test fails the document, and so does finding no tests at all.\",\n \"context\": \"The Markdown expanded in testing mode.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Verbose\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/cli\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Expand content when run verbosity is enabled. `--verbose` enables it for the run; a component may override verbosity for its content.\",\n \"as\": \"Optional. Captures the rendered verbose text, or an empty string when verbosity is off.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WebForm\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/web\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"schema\": {},\n \"uiSchema\": {}\n },\n \"required\": [\n \"schema\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"value\",\n \"returns\": {},\n \"description\": \"Ask a person a question in a browser form. `…` builds the form from the schema and shows its content above it. `uiSchema` sets presentation options. `` asks the same question without choosing the browser.\",\n \"as\": \"Required. The validated response.\",\n \"context\": \"The Markdown shown above the form.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"WorkflowRun\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/testing\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Scope a workflow-hosted execution. `…` holds `` children, and refuses unless the host supplies a workflow profile.\",\n \"context\": \"The workflow-hosted executions this scope owns.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Worktree\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/workflow/composition\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\",\n \"paired\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"branch\": {\n \"type\": \"string\",\n \"minLength\": 1\n },\n \"base\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n },\n \"required\": [\n \"name\",\n \"branch\"\n ],\n \"additionalProperties\": false\n },\n \"captures\": [],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Create or use a worktree. `…` expands its content in the worktree.\",\n \"as\": \"Optional. The path of the linked checkout.\",\n \"context\": \"The Markdown expanded in that checkout.\"\n },\n {\n \"kind\": \"component\",\n \"name\": \"Yaml\",\n \"origin\": {\n \"kind\": \"registered\",\n \"origin\": \"@executablemd/core\",\n \"reserved\": false\n },\n \"sourceKind\": \"registered\",\n \"inspectability\": \"complete\",\n \"forms\": [\n \"self-closing\"\n ],\n \"props\": {\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n },\n \"captures\": [\n \"value\"\n ],\n \"returnMode\": \"text\",\n \"returns\": {\n \"type\": \"string\"\n },\n \"description\": \"Render a value as YAML text. `` writes the YAML where you put it.\",\n \"as\": \"Optional. Captures the YAML text instead of emitting it.\"\n }\n ]\n },\n {\n \"kind\": \"user-provided\",\n \"entries\": []\n }\n ]\n}\n", "cli-fragment-base.txt": "## Built-in structural syntax\n\nNo structural constructs are reserved.\n\n## Built-in components\n\nNo components are registered in this profile.\n\n## User-provided components\n\n### ``\n\nRender a value as JSON text. `` writes the JSON where you put it.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Captures:** `value` — evaluated by the component itself, so these props are deliberately absent from the schema above.\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead the working directory. `` renders its path without adding a newline.\n\n**Forms:** ``\n\n#### Props\n\nThis component declares no individual props.\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nRead or write a file. `` reads the content; `…` writes the content. The path is relative to the working directory.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `path` | `string` | yes | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"path\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"path\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n\n### ``\n\nList files by pattern. `` matches paths relative to the working directory. The list is sorted. Directories and symbolic links are never results.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `include` | `array` | yes | |\n| `exclude` | `array` | no | |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"include\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1\n },\n \"exclude\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"default\": []\n }\n },\n \"required\": [\n \"include\"\n ],\n \"additionalProperties\": false\n}\n```\n\n**Returns:** a value — it renders nothing, and `as` binds what it returns.\n\n```json\n{\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n }\n}\n```\n\n**Origin:** `@executablemd/core` (registered default)\n\n### ``\n\nInspect available components and control-flow constructs. `` lists the symbols available here; `` renders selected documentation.\n\n**Forms:** ``\n\n#### Props\n\n| Prop | Type | Required | Description |\n| --- | --- | --- | --- |\n| `names` | `array` | no | Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order. |\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"names\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\"\n },\n \"minItems\": 1,\n \"uniqueItems\": true,\n \"description\": \"Optional. Render complete references for these structural or component names instead of the list of available symbols. Entries render once each, in symbol order.\"\n }\n },\n \"additionalProperties\": false\n}\n```\n\n**Returns:** text — the markdown this component renders.\n\n```json\n{\n \"type\": \"string\"\n}\n```\n\n**Origin:** `@executablemd/core` (protected component)\n" } diff --git a/specs/construct-inventory.md b/specs/construct-inventory.md index ba8c19045..42142b2cf 100644 --- a/specs/construct-inventory.md +++ b/specs/construct-inventory.md @@ -61,6 +61,7 @@ A non-normative table of the selected public vocabulary. In props, `?` marks an | Elicit | default component | @executablemd/core | schema: schema | value: schema | | Fail | default component | @executablemd/core | message: string | text: string | | Fetch | default component | @executablemd/core | url: string; method?: string; headers?: object; timeout?: string | text: string | +| File.Copy | default component | @executablemd/core | from: string; to: string | text: string | | Glob | default component | @executablemd/core | include: array; exclude?: array | value: array | | Json | default component | @executablemd/core | value: capture | text: string | | Parse | default component | @executablemd/core | schema: schema | value: schema |