instagui 0.1.0

package/dist/core/compose.js

@@ -0,0 +1,66 @@
+/** Pick the canonical flag token from a help-style flag field, e.g.
+ *  "-c, --codec" → "-c", "--output" → "--output", "-c/--codec" → "-c". First listed wins
+ *  (that is what the tool's help shows first). */
+export function firstFlag(flag) {
+    const tokens = flag.split(/[\s,|/]+/).filter((t) => t.length > 0);
+    const dashed = tokens.find((t) => t.startsWith('-'));
+    return dashed ?? tokens[0] ?? flag;
+}
+/** Non-empty string value → contributes an argument. Empty string / undefined / null → not.
+ *  (Booleans are handled separately.) */
+function asValue(v) {
+    if (v === undefined || v === null || typeof v === 'boolean')
+        return null;
+    const s = typeof v === 'string' ? v : String(v);
+    return s.length === 0 ? null : s;
+}
+function pushOption(args, o, raw) {
+    if (o.type === 'boolean') {
+        // A checked box contributes the bare flag; unchecked/absent contributes nothing.
+        if (raw === true || raw === 'true')
+            args.push(firstFlag(o.flag));
+        return;
+    }
+    const value = asValue(raw);
+    if (value === null)
+        return; // empty/default → no argument
+    args.push(firstFlag(o.flag), value);
+}
+/**
+ * Compose the argument array (excluding the tool name) from `state`, honoring Schema order:
+ * options first, then positionals. Empty/default fields contribute nothing.
+ */
+export function composeArgs(schema, state) {
+    const args = [];
+    const options = state.options ?? {};
+    const positionals = state.positionals ?? {};
+    for (const o of schema.options) {
+        pushOption(args, o, options[o.name]);
+    }
+    for (const p of schema.positionals) {
+        const value = asValue(positionals[p.name]);
+        if (value !== null)
+            args.push(value);
+    }
+    return args;
+}
+/** Wrap an argument for display only when it contains characters that would be ambiguous
+ *  unquoted. POSIX single-quote style; purely illustrative (Run uses the array, not this). */
+function quoteForDisplay(arg) {
+    if (arg === '')
+        return "''";
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(arg))
+        return arg;
+    return "'" + arg.replace(/'/g, "'\\''") + "'";
+}
+/** Render the composed command as a readable string: `tool arg1 arg2 …`. Derived from the
+ *  SAME array `composeArgs` returns, so preview never drifts from execution. */
+export function previewString(tool, args) {
+    return [tool, ...args.map(quoteForDisplay)].join(' ');
+}
+/** Convenience: the arg array and its preview string in one call, from one composition. */
+export function compose(schema, state) {
+    const args = composeArgs(schema, state);
+    return { args, preview: previewString(schema.tool, args) };
+}
+//# sourceMappingURL=compose.js.map

package/dist/core/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/core/compose.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.js

@@ -0,0 +1,40 @@
+// Exit-code contract (spine): 0 ok · 2 known precondition failure (distinct messages) ·
+// 1 unexpected. Core throws typed errors; the CLI maps them to process exit codes so the
+// core stays testable and free of process.exit.
+/** A known, user-facing precondition failure → exit code 2. Message is safe to print
+ *  as-is (no stack trace). */
+export class PreconditionError extends Error {
+    exitCode = 2;
+    /** Path to a written debug artifact, when the failure produced one. */
+    debugFile;
+    constructor(message, debugFile) {
+        super(message);
+        this.name = 'PreconditionError';
+        this.debugFile = debugFile;
+    }
+}
+// Capture failures — distinct types so Story 1.3 can route distinct messages/exit codes.
+// All are precondition failures (exit 2); messages here are serviceable and refined in 1.3.
+/** The named tool is not found on PATH. */
+export class ToolNotFoundError extends PreconditionError {
+    tool;
+    constructor(tool) {
+        super(`Tool not found: "${tool}" is not on your PATH. Check the name and that it is installed.`);
+        this.tool = tool;
+        this.name = 'ToolNotFoundError';
+    }
+}
+/** The tool ran but produced no usable help text through any fallback. */
+export class NoHelpError extends PreconditionError {
+    tool;
+    detail;
+    constructor(tool, detail) {
+        super(`No help output: "${tool}" produced no usable help via --help, -h, help, or man` +
+            (detail ? ` (${detail})` : '') +
+            `. Pass --help-file <path> or pipe help text on stdin.`);
+        this.tool = tool;
+        this.detail = detail;
+        this.name = 'NoHelpError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,yFAAyF;AACzF,gDAAgD;AAEhD;8BAC8B;AAC9B,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,QAAQ,GAAG,CAAC,CAAC;IACtB,uEAAuE;IAC9D,SAAS,CAAU;IAE5B,YAAY,OAAe,EAAE,SAAkB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED,yFAAyF;AACzF,4FAA4F;AAE5F,2CAA2C;AAC3C,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IAC1B;IAA5B,YAA4B,IAAY;QACtC,KAAK,CAAC,oBAAoB,IAAI,iEAAiE,CAAC,CAAC;QADvE,SAAI,GAAJ,IAAI,CAAQ;QAEtC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,WAAY,SAAQ,iBAAiB;IAE9B;IACA;IAFlB,YACkB,IAAY,EACZ,MAAe;QAE/B,KAAK,CACH,oBAAoB,IAAI,wDAAwD;YAC9E,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9B,uDAAuD,CAC1D,CAAC;QAPc,SAAI,GAAJ,IAAI,CAAQ;QACZ,WAAM,GAAN,MAAM,CAAS;QAO/B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}

package/dist/core/extract.js

@@ -0,0 +1,78 @@
+// core/extract.ts — the AI bet, isolated. Help text in → validated Schema out.
+// Flow: build prompt → ask Claude for JSON matching the Schema → Schema.parse().
+// On malformed output: exactly one retry, then write the raw output to a debug file and
+// fail with a clear precondition error (exit 2). No server, no UI here.
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { Schema } from './schema.js';
+import { PreconditionError } from './errors.js';
+import { resolveComplete } from '../shared/engine.js';
+/** Locked decision: extraction model. */
+export const DEFAULT_MODEL = 'claude-haiku-4-5';
+const SYSTEM_PROMPT = `You extract a machine-usable description of a command-line tool's interface from its --help text, matching the provided JSON schema exactly.
+
+Rules — follow all of them:
+1. GROUND EVERY FLAG IN THE HELP. Only include options whose flag appears verbatim in the help text. Never invent, guess, complete, or "improve" a flag. If you are unsure a flag exists, omit it. A hallucinated flag is worse than a missing one.
+2. THE TOOL IS FLAT — no subcommands. If the help lists sub-commands, verbs, or usage examples (e.g. "tool build", "tool run"), do NOT model them as a tree and do NOT invent per-subcommand options. Extract only the tool's own top-level options and positional arguments.
+3. SHORT-ONLY FLAGS COUNT. If an option has only a short form (e.g. "-x" with no long form), capture it exactly. Never drop an option for lacking a "--long" form. Put the flag text exactly as written in "flag" (include every form shown, e.g. "-c, --codec").
+4. HUGE HELP: if the tool exposes hundreds of options (codec/format dumps, etc.), extract the generally useful options a person would set from the main option sections. You may omit exhaustive rare entries. Coverage of the common, task-relevant options matters more than completeness.
+5. POSITIONALS ARE FIRST-CLASS. Capture positional arguments (input/output files, etc.) in "positionals", not as flags. Infer "required" and "variadic" from the usage line ("<output>" is required; "[file...]" is variadic and optional).
+6. TYPES: use "boolean" for switches that take no value; "enum" when the help lists a fixed set of allowed values (put them in "enumValues"); "number" for numeric values; "path" for file/directory/path values; "string" otherwise. "enumValues" is [] unless the type is "enum".
+7. "group" is the help section header the option sits under (e.g. "Video options"); "" if none. "description" is a concise one-line description from the help, or "" if none.
+8. "tool" must echo the tool name given by the user exactly. "summary" is a one-line description of the tool if the help states one, else "".`;
+export function buildUserPrompt(helpText, tool) {
+    return `Tool: ${tool}\n\nHelp text:\n"""\n${helpText}\n"""`;
+}
+/**
+ * Extract a validated Schema from help text. Exactly one retry on malformed output; on a
+ * second failure the raw model output is written to a debug file (path carried on the
+ * thrown PreconditionError) and never discarded.
+ */
+export async function extractSchema(helpText, tool, opts = {}) {
+    const completeFn = opts.complete ?? resolveComplete();
+    const req = {
+        model: opts.model ?? DEFAULT_MODEL,
+        system: SYSTEM_PROMPT,
+        user: buildUserPrompt(helpText, tool),
+        outputSchema: Schema,
+        maxTokens: opts.maxTokens,
+    };
+    const maxAttempts = 2; // initial + exactly one retry
+    let lastRaw = '';
+    let lastReason = '';
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        lastRaw = await completeFn(req, opts.client);
+        const outcome = validate(lastRaw);
+        if (outcome.ok) {
+            return { schema: outcome.schema, attempts: attempt };
+        }
+        lastReason = outcome.reason;
+    }
+    // Both attempts failed — persist the invalid output for prompt tuning, then fail clearly.
+    const debugFile = writeDebugFile(lastRaw, tool, lastReason, opts);
+    throw new PreconditionError(`Extraction failed: the model did not return a valid Schema for "${tool}" after one retry (${lastReason}). ` +
+        `The invalid output was saved to ${debugFile} for inspection.`, debugFile);
+}
+function validate(raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (e) {
+        return { ok: false, reason: `response was not valid JSON: ${e.message}` };
+    }
+    const parsed = Schema.safeParse(json);
+    if (!parsed.success) {
+        return { ok: false, reason: `response did not match the Schema shape: ${parsed.error.message}` };
+    }
+    return { ok: true, schema: parsed.data };
+}
+function writeDebugFile(raw, tool, reason, opts) {
+    const dir = opts.debugDir ?? process.cwd();
+    const ts = opts.now ?? Date.now();
+    const file = path.join(dir, `instagui-debug-${tool.replace(/[^\w.-]/g, '_')}-${ts}.json`);
+    const body = JSON.stringify({ tool, reason, rawOutput: raw }, null, 2);
+    writeFileSync(file, body, 'utf8');
+    return file;
+}
+//# sourceMappingURL=extract.js.map

package/dist/core/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/core/extract.ts"],"names":[],"mappings":"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"}

package/dist/core/golden.js

@@ -0,0 +1,44 @@
+/** Pull the individual flag tokens out of a `flag` field like "-c, --codec" or
+ *  "-c/--codec" → ["-c", "--codec"]. Only tokens that start with "-" count. */
+export function flagTokens(flag) {
+    return flag
+        .split(/[\s,/|]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.startsWith('-'));
+}
+/**
+ * Return every flag token in the Schema that does NOT appear verbatim in the help text.
+ * A non-empty result means the model invented flags — a hallucination, and a failed
+ * extraction regardless of JSON validity.
+ */
+export function findHallucinatedFlags(schema, helpText) {
+    const hallucinated = [];
+    for (const opt of schema.options) {
+        for (const token of flagTokens(opt.flag)) {
+            if (!helpText.includes(token))
+                hallucinated.push(token);
+        }
+    }
+    return [...new Set(hallucinated)];
+}
+/**
+ * Verify that every option a demo task needs is present with the correct flag and type.
+ * Used by the per-tool golden tests; a failure here is a failed extraction even when the
+ * Schema parses.
+ */
+export function goldenCheck(schema, required) {
+    const missing = [];
+    const typeMismatches = [];
+    for (const need of required) {
+        const match = schema.options.find((opt) => flagTokens(opt.flag).includes(need.flag));
+        if (!match) {
+            missing.push(need.flag);
+            continue;
+        }
+        if (match.type !== need.type) {
+            typeMismatches.push(`${need.flag}: expected ${need.type}, got ${match.type}`);
+        }
+    }
+    return { ok: missing.length === 0 && typeMismatches.length === 0, missing, typeMismatches };
+}
+//# sourceMappingURL=golden.js.map

package/dist/core/golden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden.js","sourceRoot":"","sources":["../../src/core/golden.ts"],"names":[],"mappings":"AAMA;+EAC+E;AAC/E,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI;SACR,KAAK,CAAC,UAAU,CAAC;SACjB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,QAAgB;IACpE,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACjC,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC;AACpC,CAAC;AAkBD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAA0B;IACpE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACrF,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;YAC7B,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,cAAc,IAAI,CAAC,IAAI,SAAS,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;AAC9F,CAAC"}

package/dist/core/onboarding.js

@@ -0,0 +1,19 @@
+// Story 2.4 — friendly onboarding when a key is genuinely needed. This error is thrown ONLY
+// on the extraction tier, after override/cache/bundled have all missed: a user who can be
+// served without a key (demo tools, a cache hit, or --schema) never sees it.
+//
+// The message is intentionally kind and actionable — what to get, where, and how to set it
+// on both Windows and POSIX — never a stack trace or a silent failure.
+import { PreconditionError } from './errors.js';
+import { API_KEY_ENV } from '../shared/config.js';
+/** The one-time, key-needed onboarding error (exit 2). Never prints or reads the key. */
+export function apiKeyOnboardingError() {
+    return new PreconditionError(`This tool needs a one-time AI extraction, and no schema was found in your cache or the ` +
+        `bundled demo schemas — so an Anthropic API key is required.\n` +
+        `  1. Get a key:  https://console.anthropic.com/settings/keys\n` +
+        `  2. Set it in your shell, then re-run:\n` +
+        `       PowerShell:  $env:${API_KEY_ENV}="sk-ant-..."\n` +
+        `       POSIX:       export ${API_KEY_ENV}="sk-ant-..."\n` +
+        `Tip: the bundled demo tools (ffmpeg, yt-dlp, pandoc) work with no key at all.`);
+}
+//# sourceMappingURL=onboarding.js.map

package/dist/core/onboarding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding.js","sourceRoot":"","sources":["../../src/core/onboarding.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,0FAA0F;AAC1F,6EAA6E;AAC7E,EAAE;AACF,2FAA2F;AAC3F,uEAAuE;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,yFAAyF;AACzF,MAAM,UAAU,qBAAqB;IACnC,OAAO,IAAI,iBAAiB,CAC1B,yFAAyF;QACvF,+DAA+D;QAC/D,gEAAgE;QAChE,2CAA2C;QAC3C,4BAA4B,WAAW,iBAAiB;QACxD,8BAA8B,WAAW,iBAAiB;QAC1D,+EAA+E,CAClF,CAAC;AACJ,CAAC"}

package/dist/core/override.js

@@ -0,0 +1,26 @@
+// Story 2.2 — the `--schema <file>` override. A power user supplies their own hand-tuned
+// Schema; instagui uses it directly with NO tool-help invocation and NO API call. It sits at
+// the top of the resolution precedence (override > cache > bundled > extraction).
+//
+// Unlike the cache/bundled tiers, a bad override is a user-facing error, not a silent
+// fall-through: the user named this file explicitly, so a clear, reason-specific message
+// (exit code 2) is the right response.
+import { PreconditionError } from './errors.js';
+import { readSchemaFile } from './schema-file.js';
+/**
+ * Load and validate a `--schema` override file. Returns the parsed Schema, or throws a
+ * PreconditionError (exit 2) whose message points at exactly what is wrong.
+ */
+export function loadOverrideSchema(file) {
+    const result = readSchemaFile(file);
+    if (result.ok)
+        return result.schema;
+    const messages = {
+        missing: `--schema file not found: ${file}`,
+        unreadable: `--schema file could not be read: ${file} (${result.detail})`,
+        'invalid-json': `--schema file is not valid JSON: ${file} (${result.detail})`,
+        'invalid-schema': `--schema file does not match the instagui Schema: ${file}\n${result.detail}`,
+    };
+    throw new PreconditionError(messages[result.reason]);
+}
+//# sourceMappingURL=override.js.map

package/dist/core/override.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"override.js","sourceRoot":"","sources":["../../src/core/override.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,6FAA6F;AAC7F,kFAAkF;AAClF,EAAE;AACF,sFAAsF;AACtF,yFAAyF;AACzF,uCAAuC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IAEpC,MAAM,QAAQ,GAAyC;QACrD,OAAO,EAAE,4BAA4B,IAAI,EAAE;QAC3C,UAAU,EAAE,oCAAoC,IAAI,KAAK,MAAM,CAAC,MAAM,GAAG;QACzE,cAAc,EAAE,oCAAoC,IAAI,KAAK,MAAM,CAAC,MAAM,GAAG;QAC7E,gBAAgB,EAAE,qDAAqD,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE;KAChG,CAAC;IACF,MAAM,IAAI,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/core/resolve.js

@@ -0,0 +1,22 @@
+/**
+ * Resolve a Schema for `input.tool` by the fixed precedence above. `--schema` short-circuits
+ * before any capture or cache read; `--refresh` skips the two free lookup tiers so the
+ * result comes from a fresh extraction and overwrites the user cache.
+ */
+export async function resolveSchema(input, deps) {
+    if (input.schemaFile) {
+        return { schema: deps.loadOverride(input.schemaFile), source: 'override' };
+    }
+    if (!input.refresh) {
+        const cached = deps.readCache(input.tool);
+        if (cached)
+            return { schema: cached, source: 'cache' };
+        const bundled = deps.readBundled(input.tool);
+        if (bundled)
+            return { schema: bundled, source: 'bundled' };
+    }
+    const schema = await deps.extract();
+    const cachedTo = deps.writeCache(input.tool, schema);
+    return { schema, source: 'extraction', cachedTo };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/core/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/core/resolve.ts"],"names":[],"mappings":"AA2CA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAmB,EAAE,IAAiB;IACxE,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC7E,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAEvD,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,OAAO;YAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC7D,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;AACpD,CAAC"}

package/dist/core/schema-file.js

@@ -0,0 +1,34 @@
+// Shared schema-file reader used by all three non-extraction resolution tiers
+// (Story 2.1 cache, 2.2 --schema override, 2.3 bundled). One place decides how a Schema
+// JSON file is read and validated; each caller decides what to do with a failure:
+//   • cache / bundled  → treat any failure as "not available", fall through the chain
+//   • --schema override → surface the specific reason as a friendly PreconditionError
+import { readFileSync } from 'node:fs';
+import { Schema } from './schema.js';
+/**
+ * Read and validate a Schema JSON file. Never throws — the outcome is returned so each
+ * tier can choose its own failure behavior (silent fall-through vs. a friendly error).
+ */
+export function readSchemaFile(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, reason: err.code === 'ENOENT' ? 'missing' : 'unreadable', detail: err.message };
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (e) {
+        return { ok: false, reason: 'invalid-json', detail: e.message };
+    }
+    const parsed = Schema.safeParse(json);
+    if (!parsed.success) {
+        return { ok: false, reason: 'invalid-schema', detail: parsed.error.message };
+    }
+    return { ok: true, schema: parsed.data };
+}
+//# sourceMappingURL=schema-file.js.map

package/dist/core/schema-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-file.js","sourceRoot":"","sources":["../../src/core/schema-file.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wFAAwF;AACxF,kFAAkF;AAClF,sFAAsF;AACtF,sFAAsF;AACtF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAUrC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAA0B,CAAC;QACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;IACtG,CAAC;IACD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAG,CAAW,CAAC,OAAO,EAAE,CAAC;IAC7E,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IAC/E,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC"}

package/dist/core/schema.js

@@ -0,0 +1,58 @@
+// AD-4 — THE Schema contract. One Zod object, three consumers:
+//   • zodOutputFormat(Schema)  → constrains the extraction API call (shared/claude.ts)
+//   • z.infer<typeof Schema>   → the TS type used everywhere downstream
+//   • Schema.parse(value)      → runtime validation of extraction output, cache reads,
+//                                 --schema overrides, and bundled schemas
+//
+// Authored with `zod/v4` on purpose: @anthropic-ai/sdk's zodOutputFormat binds to the
+// zod v4 API (zod ≥3.25 ships it at the `zod/v4` subpath). Importing plain `zod` (v3)
+// here would type-mismatch against zodOutputFormat.
+import { z } from 'zod/v4';
+/**
+ * The control kind an option maps to in the Form. `path` is a string field in v1
+ * (no native picker — scope fence), kept distinct from `string` so the UI can hint.
+ */
+export const OptionType = z.enum(['string', 'number', 'boolean', 'enum', 'path']);
+/**
+ * A flag-style option. Every field is required by design: structured-output JSON schema
+ * mode is happiest with all-required + additionalProperties:false, and an explicit empty
+ * value ("" / [] / false) is less ambiguous to the model than an omitted key.
+ */
+export const Option = z.object({
+    /** Canonical identifier, e.g. "codec" or "verbose". Stable key for form + compose. */
+    name: z.string(),
+    /** The literal flag as it appears in help, e.g. "--codec", "-c", "-c/--codec". */
+    flag: z.string(),
+    type: OptionType,
+    /** One-line description; "" if the help gives none. */
+    description: z.string(),
+    /** Allowed values when type === "enum"; [] otherwise. */
+    enumValues: z.array(z.string()),
+    /** Whether the tool requires this option. */
+    required: z.boolean(),
+    /** Help-text section this belongs to, e.g. "Video options"; "" if ungrouped. */
+    group: z.string(),
+});
+/**
+ * A positional argument (e.g. ffmpeg input/output files). The money demo does not work
+ * without these — they are first-class, not folded into flags.
+ */
+export const Positional = z.object({
+    name: z.string(),
+    type: OptionType,
+    description: z.string(),
+    required: z.boolean(),
+    /** True if the positional accepts multiple values (e.g. "files..."). */
+    variadic: z.boolean(),
+});
+/** The single structured description of a Tool's interface — the contract between
+ *  capture, UI, and execution. */
+export const Schema = z.object({
+    /** The tool binary name, echoed from the request. */
+    tool: z.string(),
+    /** One-line summary of what the tool does; "" if unknown. */
+    summary: z.string(),
+    options: z.array(Option),
+    positionals: z.array(Positional),
+});
+//# sourceMappingURL=schema.js.map

package/dist/core/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,uFAAuF;AACvF,wEAAwE;AACxE,uFAAuF;AACvF,0EAA0E;AAC1E,EAAE;AACF,sFAAsF;AACtF,sFAAsF;AACtF,oDAAoD;AACpD,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAGlF;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,sFAAsF;IACtF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,kFAAkF;IAClF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,UAAU;IAChB,uDAAuD;IACvD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,yDAAyD;IACzD,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,gFAAgF;IAChF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC;AAGH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,UAAU;IAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,wEAAwE;IACxE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;CACtB,CAAC,CAAC;AAGH;kCACkC;AAClC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7B,qDAAqD;IACrD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,6DAA6D;IAC7D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IACxB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC;CACjC,CAAC,CAAC"}

package/dist/server/browser.js

@@ -0,0 +1,38 @@
+// server/browser.ts — auto-open the served Form in the default browser (AC 3.1). The URL is
+// always printed by the CLI too, so this is a convenience: a failure here is non-fatal.
+//
+// spawn is injected so tests can assert the platform-correct command WITHOUT launching a
+// browser. Uses spawn with an args array (never a shell string) even for the opener.
+import { spawn } from 'node:child_process';
+/**
+ * The platform-appropriate command to open `url` in the default browser.
+ *   win32 → cmd /c start "" <url>   (empty title arg so a quoted URL isn't taken as the title)
+ *   darwin → open <url>
+ *   else   → xdg-open <url>
+ * The URL is passed as a single argument — no shell interpolation.
+ */
+export function openCommand(url, platform) {
+    if (platform === 'win32')
+        return { cmd: 'cmd', args: ['/c', 'start', '', url] };
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [url] };
+    return { cmd: 'xdg-open', args: [url] };
+}
+/** Best-effort: launch the browser, swallowing any failure (the printed URL is the fallback). */
+export function openBrowser(url, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawnFn = deps.spawnFn ?? spawn;
+    const { cmd, args } = openCommand(url, platform);
+    try {
+        const child = spawnFn(cmd, args, { stdio: 'ignore', detached: false, windowsHide: true });
+        child.on('error', () => {
+            /* browser open is best-effort; the URL was printed */
+        });
+        child.unref?.();
+    }
+    catch {
+        /* ignore — non-fatal */
+    }
+    return { cmd, args };
+}
+//# sourceMappingURL=browser.js.map

package/dist/server/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/server/browser.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,wFAAwF;AACxF,EAAE;AACF,yFAAyF;AACzF,qFAAqF;AACrF,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAS3C;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,QAAyB;IAChE,IAAI,QAAQ,KAAK,OAAO;QAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;IAChF,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/D,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;AAC1C,CAAC;AAOD,iGAAiG;AACjG,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,OAAwB,EAAE;IACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;IACtC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1F,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACrB,sDAAsD;QACxD,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,wBAAwB;IAC1B,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AACvB,CAAC"}

package/dist/server/client.js

@@ -0,0 +1,146 @@
+// server/client.ts — the browser-side script embedded in the served page (as a string, so
+// the build stays a plain `tsc` with no bundler). It never composes commands itself: it
+// collects form state and asks the server (POST /preview, POST /run) so core/compose.ts is
+// the single source of truth. Run output arrives over SSE (/events); closing that stream is
+// what the server watches to kill an orphaned child (AD-5).
+//
+// Authored as a template string rather than real TS because it runs in the browser, not Node.
+// Kept intentionally small and framework-free (vanilla DOM).
+export const CLIENT_SCRIPT = String.raw `
+(function () {
+  var form = document.getElementById('form');
+  var previewEl = document.getElementById('preview');
+  var statusEl = document.getElementById('status');
+  var copyBtn = document.getElementById('copy');
+  var runBtn = document.getElementById('run');
+  var stopBtn = document.getElementById('stop');
+  var outputEl = document.getElementById('output');
+  var streamEl = document.getElementById('stream');
+  var exitEl = document.getElementById('exit');
+
+  var es = null;
+
+  // Collect { options, positionals } from every [data-kind] control. Booleans are
+  // true/false; everything else is the raw string value (compose decides emptiness).
+  function collectState() {
+    var options = {}, positionals = {};
+    var els = form.querySelectorAll('[data-kind]');
+    for (var i = 0; i < els.length; i++) {
+      var el = els[i];
+      var name = el.getAttribute('data-name');
+      var kind = el.getAttribute('data-kind');
+      var value = el.type === 'checkbox' ? el.checked : el.value;
+      if (kind === 'option') options[name] = value; else positionals[name] = value;
+    }
+    return { options: options, positionals: positionals };
+  }
+
+  var previewTimer = null;
+  function schedulePreview() {
+    if (previewTimer) clearTimeout(previewTimer);
+    previewTimer = setTimeout(updatePreview, 60);
+  }
+
+  function updatePreview() {
+    fetch('/preview', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(collectState()),
+    })
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (data) { if (data && typeof data.preview === 'string') previewEl.textContent = data.preview; })
+      .catch(function () { /* preview is best-effort; leave the last good value */ });
+  }
+
+  form.addEventListener('input', schedulePreview);
+  form.addEventListener('change', schedulePreview);
+
+  copyBtn.addEventListener('click', function () {
+    var text = previewEl.textContent || '';
+    var done = function () { statusEl.textContent = 'Copied.'; setTimeout(function () { statusEl.textContent = ''; }, 1500); };
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(done, fallbackCopy);
+    } else fallbackCopy();
+    function fallbackCopy() {
+      var ta = document.createElement('textarea');
+      ta.value = text; document.body.appendChild(ta); ta.select();
+      try { document.execCommand('copy'); done(); } catch (e) {}
+      document.body.removeChild(ta);
+    }
+  });
+
+  function setRunning(running) {
+    runBtn.disabled = running;
+    stopBtn.disabled = !running;
+    form.querySelectorAll('[data-kind]').forEach(function (el) { el.disabled = running; });
+  }
+
+  function closeStream() { if (es) { es.close(); es = null; } }
+
+  runBtn.addEventListener('click', function () {
+    outputEl.hidden = false;
+    streamEl.textContent = '';
+    exitEl.textContent = '';
+    exitEl.className = 'exit';
+    statusEl.textContent = 'Starting…';
+    setRunning(true);
+
+    var state = collectState();
+    closeStream();
+    es = new EventSource('/events');
+
+    es.addEventListener('out', function (ev) {
+      streamEl.textContent += ev.data === '' ? '\n' : JSON.parse(ev.data);
+      streamEl.scrollTop = streamEl.scrollHeight;
+    });
+    es.addEventListener('exit', function (ev) {
+      var payload = JSON.parse(ev.data);
+      var code = payload.code;
+      if (payload.signal) exitEl.textContent = 'Stopped (' + payload.signal + ')';
+      else if (code === null) exitEl.textContent = 'Command failed to start'; // e.g. missing binary
+      else exitEl.textContent = 'Exit code: ' + code;
+      // Anything but a clean 0 is styled as an error (red, bold) — including a failed start.
+      exitEl.className = 'exit ' + (code === 0 ? 'ok' : 'bad');
+      statusEl.textContent = '';
+      setRunning(false);
+      closeStream();
+    });
+    es.onopen = function () {
+      statusEl.textContent = 'Running…';
+      fetch('/run', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(state),
+      }).then(function (r) {
+        if (!r.ok) {
+          return r.text().then(function (t) {
+            statusEl.textContent = 'Run rejected: ' + (t || r.status);
+            setRunning(false);
+            closeStream();
+          });
+        }
+      }).catch(function () {
+        statusEl.textContent = 'Run failed to start.';
+        setRunning(false);
+        closeStream();
+      });
+    };
+    es.onerror = function () {
+      // A stream error after exit is expected (server closed it); only surface if still running.
+      if (es && runBtn.disabled && !stopBtn.disabled) {
+        statusEl.textContent = 'Connection lost.';
+        setRunning(false);
+        closeStream();
+      }
+    };
+  });
+
+  stopBtn.addEventListener('click', function () {
+    statusEl.textContent = 'Stopping…';
+    fetch('/stop', { method: 'POST' }).catch(function () {});
+  });
+
+  updatePreview();
+})();
+`;
+//# sourceMappingURL=client.js.map

package/dist/server/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/server/client.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,wFAAwF;AACxF,2FAA2F;AAC3F,4FAA4F;AAC5F,4DAA4D;AAC5D,EAAE;AACF,8FAA8F;AAC9F,6DAA6D;AAE7D,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwItC,CAAC"}