omkit 0.4.7 → 0.8.0

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");
+}

package/dist/core/discovery-mode.d.ts

@@ -0,0 +1,37 @@
+import type { DescribedArgs, OmDescription, ResolvedMcpExposure } from "./types.ts";
+/**
+ * What an om reports in discovery mode, posted the moment `.run(...)` is reached.
+ *
+ * Sent over the fork's IPC channel rather than collected in a module variable: a user's
+ * file resolves `"omkit"` to the installed package while the discovery child runs omkit's
+ * own module graph, so the two can hold different copies of omkit — and a shared variable
+ * would be written in one and read in the other, coming back empty with no error and no
+ * clue why. `process.send` is copy-independent.
+ */
+export interface OmRegistrationMessage {
+    readonly kind: "om-registration";
+    readonly name: string;
+    /** The defining file — the same input the run's identity hashes. No `:line`. */
+    readonly file: string | undefined;
+    readonly description: OmDescription | undefined;
+    readonly mcp: ResolvedMcpExposure | undefined;
+    /** The declared args as JSON Schema; undefined when the om declares none. */
+    readonly inputSchema: DescribedArgs["inputSchema"];
+    /** Set when `.args(schema)` would not convert — the entry lists as unavailable. */
+    readonly schemaError: DescribedArgs["schemaError"];
+}
+export declare function isDiscovering(): boolean;
+/** Test seam: enter or leave discovery mode without forking a child. */
+export declare function setDiscovering(on: boolean): void;
+/** Where a registration goes. */
+export type RegistrationSink = (registration: OmRegistrationMessage) => void;
+/** Test seam: collect registrations in-process. Pass `null` to restore the IPC sink. */
+export declare function setRegistrationSink(next: RegistrationSink | null): void;
+export declare function reportOm(registration: OmRegistrationMessage): void;
+/**
+ * Convert a declared schema, never throwing. `z.toJSONSchema` rejects schemas it cannot
+ * represent (`z.date()`, `z.custom()`, anything built on them), and one such entry must
+ * not take the whole tool list down with it — so the failure is carried as data on that
+ * entry alone. `undefined` in (no `.args()`) means nothing to report either way.
+ */
+export declare function describeSchema(schema: unknown): DescribedArgs;

package/dist/core/discovery-mode.js

@@ -0,0 +1,54 @@
+import { toJsonSchema } from "./schema-json.js";
+/**
+ * Discovery mode. The child forked by `discoverRegistrations()` sets `OMKIT_DISCOVER=1`
+ * and imports om files purely to read what they declare. In that mode `launch()` posts a
+ * registration and returns: no ExecutionTree, no log folder, no body.
+ *
+ * The flag is read once at import and then deleted from the environment, so a subprocess
+ * an om happens to spawn does not inherit it — the same discipline `OMKIT_SUPERVISED` and
+ * `OMKIT_ARGS` already follow.
+ */
+function detect() {
+    const discovering = process.env.OMKIT_DISCOVER === "1";
+    delete process.env.OMKIT_DISCOVER;
+    return discovering;
+}
+let discovering = detect();
+export function isDiscovering() {
+    return discovering;
+}
+/** Test seam: enter or leave discovery mode without forking a child. */
+export function setDiscovering(on) {
+    discovering = on;
+}
+/** The real sink: straight up the fork's IPC channel. A no-op with no channel. */
+const ipcSink = (registration) => {
+    process.send?.(registration);
+};
+let sink = ipcSink;
+/** Test seam: collect registrations in-process. Pass `null` to restore the IPC sink. */
+export function setRegistrationSink(next) {
+    sink = next ?? ipcSink;
+}
+export function reportOm(registration) {
+    sink(registration);
+}
+/**
+ * Convert a declared schema, never throwing. `z.toJSONSchema` rejects schemas it cannot
+ * represent (`z.date()`, `z.custom()`, anything built on them), and one such entry must
+ * not take the whole tool list down with it — so the failure is carried as data on that
+ * entry alone. `undefined` in (no `.args()`) means nothing to report either way.
+ */
+export function describeSchema(schema) {
+    if (schema === undefined)
+        return { inputSchema: undefined, schemaError: undefined };
+    try {
+        return { inputSchema: toJsonSchema(schema), schemaError: undefined };
+    }
+    catch (e) {
+        return {
+            inputSchema: undefined,
+            schemaError: e instanceof Error ? e.message : String(e),
+        };
+    }
+}

package/dist/core/interaction.d.ts

@@ -5,13 +5,15 @@ import type { LogEntry } from "../foundation/LogEntry.ts";
  * so there is no core→actions import cycle).
  */
 export interface PromptSpec {
-    kind: "input" | "choice";
+    kind: "input" | "choice" | "multiline";
     message: string;
     default: string;
     choices?: {
         label: string;
         value: string;
     }[];
+    /** A one-line type sketch shown with the message — set for `multiline` JSON prompts. */
+    hint?: string;
 }
 export type ChildMessage = {
     kind: "prompt";

package/dist/core/om.d.ts

@@ -1,11 +1,13 @@
-import type { Awaitable, OmContext } from "./types.ts";
+import type { OmBuilder } from "./types.ts";
 /**
- * Runs a linear orchestration as the root of a fresh {@link ExecutionTree}. The
- * required `name` plus the absolute path of the file calling `om()` form the run's
- * identity — its log folder is `logs/<name>-<hash8>/…`, so same-named oms defined
- * in different files never share a folder. The body runs inside the root node's
- * ambient scope, so any action call / `step(...)` / `console.*` it reaches
- * attributes correctly. Resolves once the run has torn down and produced its
- * artifacts; never rejects (failures are recorded in the tree and set the exit code).
+ * Define a run. `om(name)` returns a builder — chain `.describe(…)` and/or `.args(schema)`
+ * and finish with `.run(body)`, which launches it as the root of a fresh
+ * {@link ExecutionTree}. The name plus the absolute path of the calling file identify the
+ * run; its log folder is `logs/<name>-<hash8>/…`, so same-named oms in different files
+ * never share a folder.
+ *
+ * The call site is captured **here**, not in `.run()` (nor in `.args()`): `om(name)` is
+ * where a run is defined, so a builder handed to (and run from) another file still hashes
+ * to the file that defined it — see the run-folder-identity constraint doc.
  */
-export declare function om(name: string, body: (ctx: OmContext) => Awaitable<void>): Promise<void>;
+export declare function om(name: string): OmBuilder;