omkit 0.4.8 → 0.8.1

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;

package/dist/core/om.js

@@ -1,22 +1,41 @@
 import { ExecutionTree } from "./ExecutionTree.js";
-import { callerSite } from "../foundation/callsite.js";
-/**
- * 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).
- */
-export function om(name, body) {
+import { callerSite, siteFile } from "../foundation/callsite.js";
+import { describeSchema, isDiscovering, reportOm } from "./discovery-mode.js";
+import { activeSupervisor } from "./interaction.js";
+import { jsonAnswerComplete, resolveArgs } from "./args.js";
+import { OPAQUE } from "./schema-hint.js";
+function assertName(name) {
     if (typeof name !== "string" || name.trim() === "") {
-        throw new Error("om(name, body) requires a non-empty name — it identifies the run in logs/");
+        throw new Error("om(name) requires a non-empty name — it identifies the run in logs/");
+    }
+}
+/** Start the run: build the tree with the captured site and drive the body as the root. */
+function launch(name, site, description, exposure, body, schema) {
+    // Discovery: report what this om declares and start nothing.
+    //
+    // The guard belongs *here*, at the single choke point both `run()` methods funnel
+    // through, for two reasons. `OmBuilderArgs.run` resolves args inside the run body, so a
+    // guard one level up would reach `resolveArgs` first and prompt into a child nobody can
+    // answer (or throw MissingArgsError) — neither is a discovery outcome. And
+    // `new ExecutionTree(...)` creates the run's log folder in its constructor, so the
+    // guard has to precede it or discovery litters `logs/` with empty runs.
+    if (isDiscovering()) {
+        const { inputSchema, schemaError } = describeSchema(schema);
+        reportOm({
+            kind: "om-registration",
+            name,
+            file: siteFile(site),
+            description,
+            mcp: exposure,
+            inputSchema,
+            schemaError,
+        });
+        return Promise.resolve();
     }
     if (ExecutionTree.current) {
         throw new Error("an om() run is already active in this process");
     }
-    const tree = new ExecutionTree(name, callerSite()); // callerSite: where om() was called — the run's script
+    const tree = new ExecutionTree(name, site, description, exposure);
     ExecutionTree.current = tree;
     const rootBody = (ctx) => body({
         signal: ctx.signal,
@@ -25,7 +44,157 @@ export function om(name, body) {
         cancel: () => tree.cancel(),
         assert: ctx.assert,
         snapshot: ctx.snapshot,
+        artifact: ctx.artifact,
         artifactsFolder: ctx.artifactsFolder,
     });
     return tree.runRoot(rootBody);
 }
+class Builder {
+    name;
+    site;
+    /** Carried into `ArgsBuilder` by `.args()`, which otherwise rebuilds the builder. */
+    description;
+    /** Carried the same way, for the same reason — `.args()` returns a new object. */
+    exposure;
+    constructor(name, 
+    /** Captured in `om()`, not here — the defining file must be the caller's, not om.ts. */
+    site) {
+        this.name = name;
+        this.site = site;
+    }
+    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;
+    }
+    args(schema) {
+        return new ArgsBuilder(this.name, this.site, schema, this.description, this.exposure);
+    }
+    run(body) {
+        // Carried onto the run for `omkit ls` and the MCP server; not read by the runtime yet.
+        return launch(this.name, this.site, this.description, this.exposure, body);
+    }
+}
+/**
+ * The builder after `.args(schema)`. Unlike an action's, the schema here is live: `.run`
+ * resolves it before calling the body, so an om declares what it needs and omkit fills it
+ * in. The site is the one `om()` captured — threaded through, never re-taken.
+ */
+class ArgsBuilder {
+    name;
+    site;
+    schema;
+    description;
+    exposure;
+    constructor(name, site, schema, description, exposure) {
+        this.name = name;
+        this.site = site;
+        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) {
+        // Resolution happens inside the run, not before it: prompting is async, and the run
+        // must already exist for the prompt and its answer to land on the timeline. A failure
+        // to resolve is therefore an ordinary failure of the root node — logged, and the run
+        // is marked failed — rather than a throw out of `om(...)`.
+        return launch(this.name, this.site, this.description, this.exposure, async (ctx) => {
+            const args = (await resolveArgs(this.schema, {
+                supplied: parseSuppliedArgs(),
+                interactive: isInteractive(),
+                ask: askForArg,
+            }));
+            ExecutionTree.current?.setRootArgs(args);
+            await body(ctx, args);
+        }, 
+        // Handed to `launch` for discovery only: in a real run the schema is resolved above,
+        // inside the body. Discovery never reaches that body, so it converts the schema here.
+        this.schema);
+    }
+}
+/** `OMKIT_ARGS` carries JSON — the only channel readable synchronously at `.run()`. */
+function parseSuppliedArgs() {
+    const raw = process.env.OMKIT_ARGS;
+    // Read it once, then clear it from the environment so any subprocess this run spawns
+    // (`command("npx omkit run other-om")`, a nested npm script, …) does not inherit this
+    // run's args and resolve them against a completely different schema. Whoever launches an
+    // omkit child sets that child's args explicitly.
+    delete process.env.OMKIT_ARGS;
+    if (!raw)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error("OMKIT_ARGS is not valid JSON");
+    }
+}
+/**
+ * Supervised, or a real terminal. Otherwise nobody can answer a prompt and resolution must
+ * fail fast instead of blocking on a question no one will see.
+ */
+function isInteractive() {
+    return activeSupervisor() !== null || process.stdin.isTTY === true;
+}
+/**
+ * Ask the user for one arg, via the `prompt` battery.
+ *
+ * The import is dynamic so that `import { om }` does not pull readline in, and because
+ * `core` is otherwise not allowed to import `actions`. Be clear about what that costs: this
+ * is a **deliberate, unenforced** runtime edge, not a permitted one. ESLint's
+ * `no-restricted-imports` has no `ImportExpression` visitor, so a dynamic import is
+ * *invisible* to the rule rather than allowed by it — the linter will not catch the next one
+ * either, and nothing but this comment stands between here and a real dependency cycle.
+ */
+async function askForArg(spec) {
+    const { prompt } = await import("../actions/prompt.js");
+    if (spec.kind === "json") {
+        return prompt({
+            kind: "multiline",
+            message: `${spec.path} — JSON`,
+            // No sketch means `shapeHint` could not express the shape; a placeholder would tell
+            // the user nothing about what to type, so the schema itself goes in its place.
+            hint: spec.hint ?? JSON.stringify(spec.jsonSchema),
+            // Not `"json"`: a JSON-kind arg may also be answered with the path to a JSON file, and
+            // a path is not JSON, so a JSON-only terminator would never end the read. At a bare
+            // terminal there is no EOF to fall back on, so the user would wait out the timeout —
+            // three times. This is the same rule `coerce` reads the answer back with.
+            until: jsonAnswerComplete,
+            timeoutMs: 120_000,
+        }).result;
+    }
+    // One line has no room for a raw schema, so an unsketchable scalar shows the placeholder.
+    return prompt({ message: `${spec.path} (${spec.hint ?? OPAQUE})`, timeoutMs: 120_000 }).result;
+}
+/**
+ * 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 function om(name) {
+    assertName(name);
+    // The removed two-argument form: JS callers would otherwise silently lose their body
+    // to a builder nobody runs. TypeScript callers get a compile error before this.
+    if (arguments.length > 1) {
+        throw new Error("om(name, body) was removed — use om(name).run(body). See the omkit CHANGELOG.");
+    }
+    return new Builder(name, callerSite()); // the om() call site — the run's defining script
+}

package/dist/core/schema-hint.d.ts

@@ -0,0 +1,20 @@
+import type { JsonSchema } from "./schema-json.ts";
+/**
+ * Placeholder text for a schema that cannot be sketched, for the one-line prompts where
+ * printing the raw JSON Schema instead would not fit. Callers do **not** detect degradation
+ * by comparing against it — {@link shapeHint} returns `undefined` for that.
+ */
+export declare const OPAQUE = "see schema";
+/**
+ * Render a JSON Schema as a one-line type sketch for a prompt — `{ host: string,
+ * port?: number }` — or `undefined` when it cannot express the shape (deep unions,
+ * tuples, recursion).
+ *
+ * Deliberately partial, and **all-or-nothing**: an unsketchable type anywhere in the tree
+ * degrades the whole sketch rather than leaving a placeholder inside an otherwise-valid
+ * one. `{ mode: see schema }` reads as a field whose type is the string "see schema", which
+ * is exactly the misleading output this is supposed to refuse to print. Degradation is
+ * signalled by the return type so a caller cannot miss it by string-matching the wrong
+ * shape of sentinel.
+ */
+export declare function shapeHint(schema: JsonSchema): string | undefined;

package/dist/core/schema-hint.js

@@ -0,0 +1,73 @@
+/**
+ * Placeholder text for a schema that cannot be sketched, for the one-line prompts where
+ * printing the raw JSON Schema instead would not fit. Callers do **not** detect degradation
+ * by comparing against it — {@link shapeHint} returns `undefined` for that.
+ */
+export const OPAQUE = "see schema";
+/**
+ * Render a JSON Schema as a one-line type sketch for a prompt — `{ host: string,
+ * port?: number }` — or `undefined` when it cannot express the shape (deep unions,
+ * tuples, recursion).
+ *
+ * Deliberately partial, and **all-or-nothing**: an unsketchable type anywhere in the tree
+ * degrades the whole sketch rather than leaving a placeholder inside an otherwise-valid
+ * one. `{ mode: see schema }` reads as a field whose type is the string "see schema", which
+ * is exactly the misleading output this is supposed to refuse to print. Degradation is
+ * signalled by the return type so a caller cannot miss it by string-matching the wrong
+ * shape of sentinel.
+ */
+export function shapeHint(schema) {
+    return render(schema);
+}
+function render(node) {
+    if (typeof node !== "object" || node === null)
+        return undefined;
+    const s = node;
+    const enumValues = s.enum;
+    if (Array.isArray(enumValues) && enumValues.length > 0) {
+        return enumValues.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    switch (s.type) {
+        case "string":
+        case "number":
+        case "integer":
+        case "boolean":
+        case "null":
+            return String(s.type);
+        case "array":
+            return renderArray(s);
+        case "object":
+            return renderObject(s);
+        default:
+            return undefined;
+    }
+}
+/**
+ * A tuple's `items` is absent (it uses `prefixItems`), and an opaque element type renders
+ * to nothing — either way there is no element sketch, so there is no array sketch.
+ * Propagating `undefined` here is what stops `see schema[]` being printed.
+ */
+function renderArray(s) {
+    const items = render(s.items);
+    return items === undefined ? undefined : `${items}[]`;
+}
+function renderObject(s) {
+    const properties = s.properties;
+    if (typeof properties !== "object" || properties === null)
+        return undefined;
+    const required = new Set(Array.isArray(s.required) ? s.required : []);
+    const entries = Object.entries(properties);
+    if (entries.length === 0)
+        return undefined;
+    const fields = [];
+    for (const [key, value] of entries) {
+        const rendered = render(value);
+        // One field we cannot sketch makes the whole line untrustworthy: the reader has no way
+        // to tell the interpolated placeholder from a real type. Degrade the object instead, so
+        // the caller falls back to printing the schema the user actually has to satisfy.
+        if (rendered === undefined)
+            return undefined;
+        fields.push(`${key}${required.has(key) ? "" : "?"}: ${rendered}`);
+    }
+    return `{ ${fields.join(", ")} }`;
+}