omkit 0.4.8 → 0.8.0

package/dist/core/ActionRun.d.ts

@@ -2,6 +2,7 @@ import { type EventHandler } from "../foundation/events.ts";
 import type { ActionRef } from "../foundation/ActionRef.ts";
 import type { LogStore } from "../output/log/LogStore.ts";
 import type { SnapshotStore } from "../output/snapshot/SnapshotStore.ts";
+import type { ArtifactStore } from "../output/artifact/ArtifactStore.ts";
 import type { Activity, Exec, InstanceEvents, NodeStatus } from "./types.ts";
 /** Everything a node needs to exist, minus its behavior. */
 export interface NodeInit {
@@ -19,6 +20,8 @@ export interface NodeInit {
     readonly parentSignal: AbortSignal | null;
     /** The run's snapshot store — backs `ctx.snapshot`. */
     readonly snapshots: SnapshotStore;
+    /** The run's artifact registry — backs `ctx.artifact`. */
+    readonly artifacts: ArtifactStore;
     /** Absolute path to the run's output folder — backs `ctx.artifactsFolder`. */
     readonly artifactsFolder: string;
     /** Report an assertion outcome to the run verdict. */
@@ -54,6 +57,7 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     duration: number;
     private readonly store;
     private readonly snapshots;
+    private readonly artifacts;
     private readonly artifactsFolder;
     private readonly onAssert;
     private readonly onUnhandledFailure;
@@ -101,6 +105,7 @@ export declare class ActionRun<Result = unknown, Events extends object = object,
     private context;
     private assertInvariant;
     private captureSnapshot;
+    private registerArtifact;
     private attach;
     private succeed;
     private fail;

package/dist/core/ActionRun.js

@@ -30,6 +30,7 @@ export class ActionRun {
     duration = 0;
     store;
     snapshots;
+    artifacts;
     artifactsFolder;
     onAssert;
     onUnhandledFailure;
@@ -59,6 +60,7 @@ export class ActionRun {
         this.parentId = init.parentId;
         this.store = init.store;
         this.snapshots = init.snapshots;
+        this.artifacts = init.artifacts;
         this.artifactsFolder = init.artifactsFolder;
         this.onAssert = init.onAssert;
         this.onUnhandledFailure = init.onUnhandledFailure;
@@ -228,6 +230,7 @@ export class ActionRun {
             tag: (name) => void this.tag(name),
             assert: (condition, message) => this.assertInvariant(condition, message),
             snapshot: (name, value) => this.captureSnapshot(name, value),
+            artifact: (name, file, opts) => this.registerArtifact(name, file, opts),
             artifactsFolder: this.artifactsFolder,
             proc: createProc((source, level, message) => this.store.append({ nodeId: this.id, path: this.path, level, source, message }), this.signal),
         };
@@ -244,6 +247,12 @@ export class ActionRun {
         this.bubble(`📸 ${name} → ${file}`);
         return file;
     }
+    registerArtifact(name, file, opts) {
+        const record = this.artifacts.register(name, file, this.id, opts);
+        this.log("artifact", "artifact", `${name} → ${record.file}`);
+        this.bubble(`📎 ${name} → ${record.file}`);
+        return record.file;
+    }
     attach(handle) {
         if (this.attached)
             return;

package/dist/core/ExecutionTree.d.ts

@@ -1,8 +1,10 @@
 import { LogStore } from "../output/log/LogStore.ts";
 import { RunFolder } from "../output/folder/RunFolder.ts";
+import { type ArtifactRecord } from "../output/artifact/ArtifactStore.ts";
 import type { RunView } from "../output/writers/views.ts";
 import { ActionRun } from "./ActionRun.ts";
-import type { Exec, LaunchSpec } from "./types.ts";
+import type { Exec, LaunchSpec, OmDescription, ResolvedMcpExposure } from "./types.ts";
+import type { LogEntry } from "../foundation/LogEntry.ts";
 /**
  * The run: a module singleton that owns the log store, the run folder, the node
  * registry, and the process-wide teardown. `launch` creates a child node under the
@@ -20,9 +22,22 @@ export declare class ExecutionTree {
     readonly store: LogStore;
     readonly folder: RunFolder;
     readonly root: ActionRun;
+    /**
+     * The om's `.describe(…)` summary, carried here from the builder so it survives the
+     * terminal `.run(...)` call. Stored so it is retrievable; nothing reads it yet.
+     */
+    readonly description: OmDescription | undefined;
+    /**
+     * The om's `.mcp(…)` exposure, carried here from the builder for the same reason
+     * `description` is: `.run(...)` is the terminal call, and an om has no definition object
+     * to hang it on. The MCP server reads its own copy from the discovery fork, not from
+     * here — this is what makes the carry observable, and therefore testable, at all.
+     */
+    readonly mcp: ResolvedMcpExposure | undefined;
     private readonly rawStream;
     private readonly consoleCapture;
     private readonly snapshotStore;
+    private readonly artifactStore;
     private readonly registry;
     private readonly unsettled;
     private readonly originalLog;
@@ -31,6 +46,7 @@ export declare class ExecutionTree {
     private forwarding;
     private assertionsPassed;
     private assertionsFailed;
+    private rootArgs;
     private readonly faults;
     static graceMs: number;
     private phase;
@@ -40,7 +56,9 @@ export declare class ExecutionTree {
     private readonly onSigint;
     private readonly onUncaught;
     private readonly onUnhandled;
-    constructor(name: string, definedAt?: string);
+    constructor(name: string, definedAt?: string, description?: OmDescription, mcp?: ResolvedMcpExposure);
+    /** Record the run's resolved args, so the root's log header reports them. */
+    setRootArgs(args: unknown): void;
     /** Launch an instance under the ambient current node (or the root). */
     launch(spec: LaunchSpec): ActionRun;
     private append;
@@ -83,7 +101,27 @@ export declare class ExecutionTree {
     private nodeView;
     /** Test seam: the projected run view (same object written to result.json). */
     runViewForTest(): RunView;
+    /** Test seam: the run's curated artifacts. */
+    artifactsForTest(): readonly ArtifactRecord[];
+    /** Test seam: every log entry recorded for this run. */
+    entriesForTest(): readonly LogEntry[];
     private runView;
+    /**
+     * The run's curated artifacts, keyed by `(nodeId, name)`: one action re-registering
+     * a name (e.g. re-labelling the same file after regenerating it) updates that entry
+     * in place rather than appending a second one, so `result.json` always reflects the
+     * latest registration per name. Keying on the pair — not `name` alone — matters
+     * because two *different* actions can independently choose the same name (two
+     * screenshot steps both calling `ctx.artifact("screenshot", …)`); those describe two
+     * distinct files and both must survive into `result.json`, not collapse into one.
+     * Position follows first registration; `artifacts.log` (a chronological rollup, like
+     * `events.log`/`asserts.log`) is unaffected either way and still lists every call.
+     *
+     * The pair is joined with `\0` — the same separator `omHash` uses, and for the same
+     * reason: a step name may legitimately contain colons (`TSKB:root:watch:docs`) and an
+     * artifact name is free-form, so any printable separator can be forged inside a key.
+     */
+    private curatedArtifacts;
     /**
      * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
      * prefix. Each id segment is sanitized so names with filesystem-illegal characters

package/dist/core/ExecutionTree.js

@@ -7,6 +7,7 @@ import { LogStore } from "../output/log/LogStore.js";
 import { RunFolder } from "../output/folder/RunFolder.js";
 import { RawStream } from "../output/log/RawStream.js";
 import { SnapshotStore } from "../output/snapshot/SnapshotStore.js";
+import { ArtifactStore } from "../output/artifact/ArtifactStore.js";
 import { ConsoleCapture } from "../output/console/ConsoleCapture.js";
 import { LiveRenderer } from "../output/LiveRenderer.js";
 import { writeNodeLogs } from "../output/writers/NodeLogWriter.js";
@@ -40,9 +41,22 @@ export class ExecutionTree {
     store = new LogStore();
     folder;
     root;
+    /**
+     * The om's `.describe(…)` summary, carried here from the builder so it survives the
+     * terminal `.run(...)` call. Stored so it is retrievable; nothing reads it yet.
+     */
+    description;
+    /**
+     * The om's `.mcp(…)` exposure, carried here from the builder for the same reason
+     * `description` is: `.run(...)` is the terminal call, and an om has no definition object
+     * to hang it on. The MCP server reads its own copy from the discovery fork, not from
+     * here — this is what makes the carry observable, and therefore testable, at all.
+     */
+    mcp;
     rawStream;
     consoleCapture;
     snapshotStore;
+    artifactStore = new ArtifactStore();
     registry = [];
     unsettled = new Set();
     originalLog = console.log.bind(console);
@@ -51,6 +65,10 @@ export class ExecutionTree {
     forwarding;
     assertionsPassed = 0;
     assertionsFailed = 0;
+    // The root's args are resolved *inside* its body (prompting is async), so unlike a
+    // child node's they cannot be handed to `run()` up front — they are recorded here
+    // instead and projected onto the root by `nodeView`.
+    rootArgs = [];
     faults = [];
     static graceMs = 5000; // teardown waits this long for nodes to settle, then finalizes anyway
     phase = "open";
@@ -65,7 +83,9 @@ export class ExecutionTree {
     // Process hooks — installed at run start, removed at finalize (they must not outlive the run).
     onUncaught = (e) => this.onFatal("uncaughtException", e);
     onUnhandled = (e) => this.onFatal("unhandledRejection", e);
-    constructor(name, definedAt) {
+    constructor(name, definedAt, description, mcp) {
+        this.description = description;
+        this.mcp = mcp;
         // The run's identity: its name + where om() is written (not how it was launched),
         // so same-named oms in different files get distinct log folders.
         this.folder = new RunFolder(name, omHash(name, siteFile(definedAt)));
@@ -87,6 +107,10 @@ export class ExecutionTree {
         this.consoleCapture = new ConsoleCapture(this.store, () => (currentNode.getStore() ?? this.root).toRef());
         ExecutionTree.last = this;
     }
+    /** Record the run's resolved args, so the root's log header reports them. */
+    setRootArgs(args) {
+        this.rootArgs = [args];
+    }
     /** Launch an instance under the ambient current node (or the root). */
     launch(spec) {
         if (this.phase !== "open") {
@@ -137,6 +161,7 @@ export class ExecutionTree {
         return {
             store: this.store,
             snapshots: this.snapshotStore,
+            artifacts: this.artifactStore,
             artifactsFolder: this.folder.path(),
             onAssert: (pass, actionPath, message) => this.recordAssert(pass, actionPath, message),
             onUnhandledFailure: (actionPath, error) => {
@@ -276,6 +301,7 @@ export class ExecutionTree {
         await writeRollup(at("events.log"), flat, entries, (e) => e.level === "event");
         await writeRollup(at("asserts.log"), flat, entries, (e) => e.level === "assert", assertSummary);
         await writeRollup(at("snapshots.log"), flat, entries, (e) => e.level === "snapshot");
+        await writeRollup(at("artifacts.log"), flat, entries, (e) => e.level === "artifact");
         await writeResult(at("result.json"), this.runView());
         // Only now let go of the process hooks — a Ctrl+C during the writes must still be
         // caught (as a no-op) so it can't fall through to Node's kill-without-log default.
@@ -306,6 +332,7 @@ export class ExecutionTree {
             `  events    → ${at("events.log")}`,
             `  asserts   → ${at("asserts.log")}   ${assertSummary}`,
             `  snapshots → ${at("snapshots.log")}`,
+            `  artifacts → ${at("artifacts.log")}`,
         ];
     }
     /** The recap to the terminal (files are already written). */
@@ -327,7 +354,8 @@ export class ExecutionTree {
             path: node.path,
             parentId: node.parentId,
             tags: [...node.tags],
-            args: [...node.args],
+            // The root never has args passed to `run()`; its own are resolved mid-body.
+            args: [...(node.parentId === null ? this.rootArgs : node.args)],
             status: node.status,
             startedAt: node.startedAt,
             endedAt: node.endedAt,
@@ -340,6 +368,14 @@ export class ExecutionTree {
     runViewForTest() {
         return this.runView();
     }
+    /** Test seam: the run's curated artifacts. */
+    artifactsForTest() {
+        return this.artifactStore.all();
+    }
+    /** Test seam: every log entry recorded for this run. */
+    entriesForTest() {
+        return this.store.entries();
+    }
     runView() {
         return {
             ok: this.faults.length === 0,
@@ -350,8 +386,36 @@ export class ExecutionTree {
             duration: this.root.duration,
             rawStream: this.rawStreamPath(),
             root: this.nodeView(this.root),
+            artifacts: this.curatedArtifacts(),
         };
     }
+    /**
+     * The run's curated artifacts, keyed by `(nodeId, name)`: one action re-registering
+     * a name (e.g. re-labelling the same file after regenerating it) updates that entry
+     * in place rather than appending a second one, so `result.json` always reflects the
+     * latest registration per name. Keying on the pair — not `name` alone — matters
+     * because two *different* actions can independently choose the same name (two
+     * screenshot steps both calling `ctx.artifact("screenshot", …)`); those describe two
+     * distinct files and both must survive into `result.json`, not collapse into one.
+     * Position follows first registration; `artifacts.log` (a chronological rollup, like
+     * `events.log`/`asserts.log`) is unaffected either way and still lists every call.
+     *
+     * The pair is joined with `\0` — the same separator `omHash` uses, and for the same
+     * reason: a step name may legitimately contain colons (`TSKB:root:watch:docs`) and an
+     * artifact name is free-form, so any printable separator can be forged inside a key.
+     */
+    curatedArtifacts() {
+        const byKey = new Map();
+        for (const { name, file, description, mime, nodeId } of this.artifactStore.all()) {
+            byKey.set(`${nodeId}\0${name}`, {
+                name,
+                file,
+                mime,
+                ...(description === undefined ? {} : { description }),
+            });
+        }
+        return [...byKey.values()];
+    }
     /**
      * Absolute `.log` path for a node — root is `main.log`, children drop the `main/`
      * prefix. Each id segment is sanitized so names with filesystem-illegal characters

package/dist/core/action.d.ts

@@ -1,7 +1,8 @@
 import type { ActionBuilderEvents, NoEvents } from "./types.ts";
 /**
  * Define an action. Provide the impl via `.run(…)`, optionally after declaring
- * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`). Call the result
+ * metadata (`.describe(…)`), events (`.emits<…>()`), an imperative handle
+ * (`.ref<…>()`), and/or pinning the args type (`.args(schema)`). Call the result
  * to launch it.
  */
 export declare function action(name: string): ActionBuilderEvents<NoEvents, void>;

package/dist/core/action.js

@@ -1,36 +1,120 @@
 import { ExecutionTree } from "./ExecutionTree.js";
 import { callerSite } from "../foundation/callsite.js";
+import { describeSchema } from "./discovery-mode.js";
 /**
- * The builder returned by `action(name)`: declare events (`.emits<…>()`) and/or an
- * imperative handle (`.ref<…>()`), then bind the impl with `.run(…)`. `.run` returns a
- * callable {@link Action} — **invoking it launches** the action under the ambient current
- * node and returns the live {@link Activity}, on which `withCache`/`tag`/… chain.
+ * The builder returned by `action(name)`: declare metadata (`.describe(…)`), events
+ * (`.emits<…>()`), an imperative handle (`.ref<…>()`), and/or pin the args type
+ * (`.args(schema)`), then bind the impl with `.run(…)`. `.run` returns a callable
+ * {@link Action} — **invoking it launches** the action under the ambient current node
+ * and returns the live {@link Activity}, on which `withCache`/`tag`/… chain.
  */
 class Builder {
     name;
-    constructor(name) {
+    description;
+    exposure;
+    constructor(name, 
+    /** Carried across `.emits()`/`.ref()`, which otherwise rebuild the builder. */
+    description = undefined, 
+    /** Carried the same way, for the same reason. */
+    exposure = undefined) {
         this.name = name;
+        this.description = description;
+        this.exposure = exposure;
+    }
+    describe(description) {
+        this.description = description;
+        return this;
+    }
+    mcp(exposure = {}) {
+        // The default is filled here, not at the reader, so every consumer sees one shape.
+        this.exposure = { mode: exposure.mode ?? "settling" };
+        return this;
     }
     emits() {
-        return new Builder(this.name);
+        return new Builder(this.name, this.description, this.exposure);
     }
     ref() {
-        return new Builder(this.name);
+        return new Builder(this.name, this.description, this.exposure);
+    }
+    args(schema) {
+        return new ArgsBuilder(this.name, schema, this.description, this.exposure);
     }
     run(body) {
         const name = this.name;
+        // Carried onto the definition for `omkit ls` and the MCP server; not read by the runtime.
+        const description = this.description;
+        const mcp = this.exposure;
         const definedAt = callerSite(); // the `.run(...)` call site — where this action lives
+        // No `.args()` on this path, so there is nothing to describe.
+        const describeArgs = () => describeSchema(undefined);
+        const exec = body;
+        const create = (...args) => {
+            const spec = { name, args, tags: [], body: exec, definedAt };
+            return ExecutionTree.require().launch(spec);
+        };
+        return Object.assign(create, {
+            actionName: name,
+            definedAt,
+            description,
+            mcp,
+            describeArgs,
+        });
+    }
+}
+/**
+ * The builder after `.args(schema)`. The schema pins `.run`'s parameter type; it is not
+ * validated here — an action invoked from an om body is passed its args directly in code.
+ * (Spec B's MCP server validates before it ever reaches this point.)
+ */
+class ArgsBuilder {
+    name;
+    schema;
+    description;
+    exposure;
+    constructor(name, 
+    /** Type-level only: `S` pins `.run`'s parameter. Nothing reads the value at runtime. */
+    schema, description, exposure) {
+        this.name = name;
+        this.schema = schema;
+        this.description = description;
+        this.exposure = exposure;
+    }
+    describe(description) {
+        this.description = description;
+        return this;
+    }
+    mcp(exposure = {}) {
+        this.exposure = { mode: exposure.mode ?? "settling" };
+        return this;
+    }
+    run(body) {
+        const name = this.name;
+        // Carried onto the definition for `omkit ls` and the MCP server; not read by the runtime.
+        const description = this.description;
+        const mcp = this.exposure;
+        const definedAt = callerSite();
+        // The schema is captured so the conversion happens in *this* copy of omkit — the one
+        // that built it — rather than in whichever copy the discovery child is running.
+        const schema = this.schema;
+        const describeArgs = () => describeSchema(schema);
         const exec = body;
         const create = (...args) => {
             const spec = { name, args, tags: [], body: exec, definedAt };
             return ExecutionTree.require().launch(spec);
         };
-        return Object.assign(create, { actionName: name, definedAt });
+        return Object.assign(create, {
+            actionName: name,
+            definedAt,
+            description,
+            mcp,
+            describeArgs,
+        });
     }
 }
 /**
  * Define an action. Provide the impl via `.run(…)`, optionally after declaring
- * events (`.emits<…>()`) and/or an imperative handle (`.ref<…>()`). Call the result
+ * metadata (`.describe(…)`), events (`.emits<…>()`), an imperative handle
+ * (`.ref<…>()`), and/or pinning the args type (`.args(schema)`). Call the result
  * to launch it.
  */
 export function action(name) {

package/dist/core/args.d.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+import { type JsonSchema } from "./schema-json.ts";
+/** Thrown when args cannot be resolved and nobody can be asked. */
+export declare class MissingArgsError extends Error {
+    readonly fields: string[];
+    /**
+     * @param fields  Top-level field names that blocked resolution.
+     * @param detail  Why, when at least one of them *was* supplied — a value that is present
+     *   but wrong is not missing, and must not be reported as though it were absent.
+     */
+    constructor(fields: string[], detail?: string);
+}
+/** What the caller must render to get one value from the user. */
+export interface AskSpec {
+    /** Dotted path of the field, e.g. `rows` or `config`. */
+    readonly path: string;
+    readonly kind: "scalar" | "json";
+    /** One-line type sketch for the prompt, or `undefined` when the shape cannot be sketched. */
+    readonly hint: string | undefined;
+    /** The field's JSON Schema, for printing when there is no hint. */
+    readonly jsonSchema: JsonSchema;
+}
+export interface ResolveOptions {
+    /** Values already supplied (from `OMKIT_ARGS`). */
+    readonly supplied: unknown;
+    /** False when there is no supervisor and stdin is not a TTY. */
+    readonly interactive: boolean;
+    readonly ask: (spec: AskSpec) => Promise<string>;
+}
+/**
+ * Fill a schema's shape from supplied values, then defaults, then prompting — and fail if
+ * that is not enough. Defaults need no work of their own: `safeParse` applies them, so a
+ * defaulted field is never blocking and is never asked about.
+ *
+ * Interactivity is checked **before any prompting**: if nobody can be asked, every blocking
+ * field is collected into a single error rather than asking for one and then discovering
+ * the second is unanswerable.
+ */
+export declare function resolveArgs(schema: z.ZodType, opts: ResolveOptions): Promise<unknown>;
+/**
+ * True once a JSON-kind answer is finished. A `{`/`[` opener is a pasted blob and is done
+ * when it parses; anything else is a path to a JSON file, and one line is the whole answer.
+ *
+ * Exported because the prompt that *collects* the answer has to stop on exactly the inputs
+ * {@link coerce} knows how to read — `om.ts` passes this as the multiline prompt's `until`.
+ * Let the two rules drift apart and the documented file-path answer becomes untypable: a
+ * bare path is not JSON, so a JSON-only terminator keeps reading, and a real terminal never
+ * reaches the EOF that would otherwise end it.
+ */
+export declare function jsonAnswerComplete(text: string): boolean;

package/dist/core/args.js

@@ -0,0 +1,166 @@
+import { readFileSync } from "node:fs";
+import { toJsonSchema } from "./schema-json.js";
+import { shapeHint } from "./schema-hint.js";
+/** Thrown when args cannot be resolved and nobody can be asked. */
+export class MissingArgsError extends Error {
+    fields;
+    /**
+     * @param fields  Top-level field names that blocked resolution.
+     * @param detail  Why, when at least one of them *was* supplied — a value that is present
+     *   but wrong is not missing, and must not be reported as though it were absent.
+     */
+    constructor(fields, detail) {
+        super(`could not resolve arg${fields.length === 1 ? "" : "s"}: ${fields.join(", ")} — ` +
+            `pass them via OMKIT_ARGS, or run interactively` +
+            (detail ? ` (${detail})` : ""));
+        this.fields = fields;
+        this.name = "MissingArgsError";
+    }
+}
+/** How many rounds of asking before resolution gives up. */
+const MAX_ATTEMPTS = 3;
+/**
+ * Fill a schema's shape from supplied values, then defaults, then prompting — and fail if
+ * that is not enough. Defaults need no work of their own: `safeParse` applies them, so a
+ * defaulted field is never blocking and is never asked about.
+ *
+ * Interactivity is checked **before any prompting**: if nobody can be asked, every blocking
+ * field is collected into a single error rather than asking for one and then discovering
+ * the second is unanswerable.
+ */
+export async function resolveArgs(schema, opts) {
+    // Converted lazily, and only once something actually has to be asked. `toJSONSchema`
+    // throws for types it cannot represent (`z.date()`, and anything built on it), and only
+    // the prompt needs the conversion — a run whose args all arrived supplied or defaulted
+    // must not be failed by work it never required.
+    let converted;
+    const root = () => (converted ??= toJsonSchema(schema));
+    let current = asRecord(opts.supplied);
+    for (let attempt = 0;; attempt++) {
+        const parsed = schema.safeParse(current);
+        if (parsed.success)
+            return parsed.data;
+        const blocking = blockingFields(parsed.error);
+        // Nothing nameable to ask for — the schema rejected the object as a whole (a top-level
+        // refinement, or a schema that isn't an object at all). No question would make progress,
+        // so fail now with the real reason instead of looping silently to the attempt cap.
+        if (blocking.length === 0)
+            throw new Error(`could not resolve args: ${message(parsed.error)}`);
+        if (!opts.interactive) {
+            const anySupplied = blocking.some((field) => current[field] !== undefined);
+            throw new MissingArgsError(blocking, anySupplied ? message(parsed.error) : undefined);
+        }
+        if (attempt >= MAX_ATTEMPTS) {
+            throw new Error(`could not resolve args after ${MAX_ATTEMPTS} attempts: ${message(parsed.error)}`);
+        }
+        for (const field of blocking) {
+            const fieldSchema = propertySchema(root(), field);
+            const kind = isComplex(fieldSchema) ? "json" : "scalar";
+            const answer = await opts.ask({
+                path: field,
+                kind,
+                hint: shapeHint(fieldSchema),
+                jsonSchema: fieldSchema,
+            });
+            // An empty answer is *no answer*, not a value. The prompt battery resolves an empty
+            // line (and a timeout) to its default (""), and `Number("")` is 0 — so coercing here
+            // would silently turn a bare Enter on a required number into a real zero. Leave the
+            // field as it was and let the loop re-ask.
+            if (answer.trim() === "")
+                continue;
+            current = { ...current, [field]: coerce(answer, fieldSchema, kind) };
+        }
+    }
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? { ...value } : {};
+}
+/**
+ * The top-level field names the error blames, first-seen order, deduplicated. Both an
+ * absent field and a present-but-wrong one block resolution and are asked about the same
+ * way, so they are one list — whether a field was supplied is read off `current`, which
+ * is the direct observation, rather than inferred from zod's issue shape.
+ */
+function blockingFields(error) {
+    const names = error.issues.map((i) => String(i.path[0] ?? "")).filter((n) => n !== "");
+    return [...new Set(names)];
+}
+function message(error) {
+    return error.issues.map((i) => `${i.path.join(".") || "(root)"} — ${i.message}`).join("; ");
+}
+function propertySchema(root, field) {
+    const properties = root.properties;
+    if (typeof properties === "object" && properties !== null) {
+        const found = properties[field];
+        if (typeof found === "object" && found !== null)
+            return found;
+    }
+    return {};
+}
+function isComplex(schema) {
+    return schema.type === "object" || schema.type === "array";
+}
+/**
+ * True once a JSON-kind answer is finished. A `{`/`[` opener is a pasted blob and is done
+ * when it parses; anything else is a path to a JSON file, and one line is the whole answer.
+ *
+ * Exported because the prompt that *collects* the answer has to stop on exactly the inputs
+ * {@link coerce} knows how to read — `om.ts` passes this as the multiline prompt's `until`.
+ * Let the two rules drift apart and the documented file-path answer becomes untypable: a
+ * bare path is not JSON, so a JSON-only terminator keeps reading, and a real terminal never
+ * reaches the EOF that would otherwise end it.
+ */
+export function jsonAnswerComplete(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return false; // a bare Enter is not an answer — keep reading
+    return isJsonBlob(trimmed) ? parsesAsJson(trimmed) : true;
+}
+/** Whether an answer is a pasted JSON blob rather than a path to one. */
+function isJsonBlob(text) {
+    return text.startsWith("{") || text.startsWith("[");
+}
+function parsesAsJson(text) {
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Turn a prompt answer into a value the schema can accept. Scalars coerce from their
+ * string form; complex fields parse as JSON, or are read from a file path when the answer
+ * does not start with `{` or `[` — pointing at a file beats pasting a large config.
+ */
+function coerce(answer, schema, kind) {
+    const text = answer.trim();
+    if (kind === "json") {
+        try {
+            return JSON.parse(isJsonBlob(text) ? text : readFileArg(text));
+        }
+        catch {
+            // Unparseable JSON *or* an unreadable path: hand the raw text back so the schema
+            // rejects it and the loop re-asks, naming the field. A mistyped filename must not
+            // escape as an ENOENT and take the whole run down.
+            return text;
+        }
+    }
+    if (schema.type === "number" || schema.type === "integer") {
+        const n = Number(text);
+        return Number.isNaN(n) ? text : n;
+    }
+    if (schema.type === "boolean") {
+        if (/^(true|yes|y|1)$/i.test(text))
+            return true;
+        if (/^(false|no|n|0)$/i.test(text))
+            return false;
+        return text;
+    }
+    return text;
+}
+/** Read a JSON file named by an answer; a leading `@` is optional sugar. */
+function readFileArg(pathish) {
+    return readFileSync(pathish.replace(/^@/, ""), "utf8");
+}