instagui 0.1.0

package/dist/server/page.js

@@ -0,0 +1,172 @@
+/** Escape a string for use as HTML text or inside a double-quoted attribute. */
+function esc(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/** Embed a value as JSON inside a <script> tag without letting "</script>" break out. */
+function safeJson(value) {
+    return JSON.stringify(value).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
+}
+/** Render one option control. File paths are plain text fields — scope fence: no native
+ *  picker (AC 3.1). Booleans → checkbox, enums → dropdown, number → number input. */
+function optionControl(o) {
+    const id = `opt-${o.name}`;
+    const label = `<label for="${esc(id)}">` +
+        `<span class="name">${esc(o.name)}</span>` +
+        `<code class="flag">${esc(o.flag)}</code>` +
+        (o.required ? '<span class="req" title="required">*</span>' : '') +
+        `</label>`;
+    const desc = o.description ? `<p class="desc">${esc(o.description)}</p>` : '';
+    const common = `id="${esc(id)}" data-kind="option" data-name="${esc(o.name)}" data-type="${esc(o.type)}"` +
+        (o.required ? ' data-required="true"' : '');
+    let control;
+    if (o.type === 'boolean') {
+        control = `<input type="checkbox" ${common} />`;
+    }
+    else if (o.type === 'enum') {
+        const opts = ['<option value=""></option>', ...o.enumValues.map((v) => `<option value="${esc(v)}">${esc(v)}</option>`)];
+        control = `<select ${common}>${opts.join('')}</select>`;
+    }
+    else if (o.type === 'number') {
+        control = `<input type="number" ${common} placeholder="${esc(o.flag)}" />`;
+    }
+    else {
+        // string | path — both plain text fields (no picker for path).
+        const hint = o.type === 'path' ? ' placeholder="path…"' : '';
+        control = `<input type="text" ${common}${hint} />`;
+    }
+    const cls = o.type === 'boolean' ? 'field field-bool' : 'field';
+    return `<div class="${cls}">${label}${control}${desc}</div>`;
+}
+/** Render one positional control. Always a text field (variadic is a hint only in v1 so each
+ *  positional contributes exactly one verbatim argument). */
+function positionalControl(p) {
+    const id = `pos-${p.name}`;
+    const label = `<label for="${esc(id)}">` +
+        `<span class="name">${esc(p.name)}</span>` +
+        (p.variadic ? '<span class="badge">multiple</span>' : '') +
+        (p.required ? '<span class="req" title="required">*</span>' : '') +
+        `</label>`;
+    const desc = p.description ? `<p class="desc">${esc(p.description)}</p>` : '';
+    const placeholder = p.type === 'path' ? 'path…' : p.name;
+    const control = `<input type="text" id="${esc(id)}" data-kind="positional" data-name="${esc(p.name)}" ` +
+        `data-type="${esc(p.type)}"${p.required ? ' data-required="true"' : ''} placeholder="${esc(placeholder)}" />`;
+    return `<div class="field">${label}${control}${desc}</div>`;
+}
+/** Group options by their `group` field, preserving first-seen order; "" → "Options". */
+function groupOptions(options) {
+    const order = [];
+    const byGroup = new Map();
+    for (const o of options) {
+        const g = o.group || 'Options';
+        if (!byGroup.has(g)) {
+            byGroup.set(g, []);
+            order.push(g);
+        }
+        byGroup.get(g).push(o);
+    }
+    return order.map((group) => ({ group, options: byGroup.get(group) }));
+}
+const STYLE = `
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+  margin: 0; background: Canvas; color: CanvasText; line-height: 1.45; }
+header { padding: 1rem 1.25rem; border-bottom: 1px solid rgba(128,128,128,.3); }
+header h1 { margin: 0; font-size: 1.15rem; }
+header h1 code { font-size: 1.15rem; }
+header .summary { margin: .25rem 0 0; opacity: .8; font-size: .9rem; }
+main { display: grid; grid-template-columns: minmax(0,1fr) minmax(0,26rem); gap: 1.25rem;
+  padding: 1.25rem; align-items: start; }
+@media (max-width: 800px) { main { grid-template-columns: 1fr; } }
+fieldset { border: 1px solid rgba(128,128,128,.3); border-radius: 8px; margin: 0 0 1rem; padding: .75rem 1rem 1rem; }
+legend { font-weight: 600; padding: 0 .4rem; }
+.field { margin: .55rem 0; }
+.field-bool { display: flex; align-items: center; gap: .5rem; }
+.field-bool label { order: 2; margin: 0; }
+label { display: flex; align-items: baseline; gap: .5rem; font-size: .9rem; margin-bottom: .2rem; }
+label .name { font-weight: 600; }
+code.flag { font-size: .8rem; opacity: .75; }
+.req { color: #d33; font-weight: 700; }
+.badge { font-size: .65rem; text-transform: uppercase; letter-spacing: .04em; opacity: .6;
+  border: 1px solid currentColor; border-radius: 4px; padding: 0 .25rem; }
+.desc { margin: .15rem 0 0; font-size: .78rem; opacity: .7; }
+input[type=text], input[type=number], select { width: 100%; padding: .4rem .5rem; font: inherit;
+  border: 1px solid rgba(128,128,128,.4); border-radius: 6px; background: Field; color: FieldText; }
+.side { position: sticky; top: 1.25rem; }
+.preview { border: 1px solid rgba(128,128,128,.3); border-radius: 8px; padding: .75rem; }
+.preview h2 { margin: 0 0 .5rem; font-size: .8rem; text-transform: uppercase; letter-spacing: .05em; opacity: .7; }
+pre.cmd { margin: 0; padding: .6rem .7rem; background: rgba(128,128,128,.12); border-radius: 6px;
+  white-space: pre-wrap; word-break: break-all; font-size: .85rem; min-height: 1.2rem; }
+.row { display: flex; gap: .5rem; margin-top: .6rem; flex-wrap: wrap; }
+button { font: inherit; padding: .45rem .9rem; border-radius: 6px; border: 1px solid rgba(128,128,128,.4);
+  background: rgba(128,128,128,.12); color: inherit; cursor: pointer; }
+button.primary { background: #2563eb; border-color: #2563eb; color: #fff; }
+button:disabled { opacity: .5; cursor: not-allowed; }
+.output { margin-top: 1rem; }
+pre.stream { margin: .4rem 0 0; padding: .6rem .7rem; background: #0b0b0b; color: #e6e6e6;
+  border-radius: 6px; max-height: 24rem; overflow: auto; white-space: pre-wrap; word-break: break-all;
+  font-size: .82rem; min-height: 2rem; }
+.exit { margin-top: .5rem; font-size: .85rem; }
+.exit.ok { color: #16a34a; } .exit.bad { color: #dc2626; font-weight: 600; }
+.status { font-size: .8rem; opacity: .7; margin-top: .3rem; }
+`;
+/**
+ * Render the full single-page HTML document for `schema`. Self-contained (inline CSS + JS,
+ * no external resources). The embedded client script lives in server/client.ts.
+ */
+export function renderPage(schema, clientScript) {
+    const groups = groupOptions(schema.options);
+    const optionsHtml = groups
+        .map((g) => `<fieldset><legend>${esc(g.group)}</legend>${g.options.map(optionControl).join('')}</fieldset>`)
+        .join('');
+    const positionalsHtml = schema.positionals.length
+        ? `<fieldset><legend>Arguments</legend>${schema.positionals.map(positionalControl).join('')}</fieldset>`
+        : '';
+    const summary = schema.summary ? `<p class="summary">${esc(schema.summary)}</p>` : '';
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>instagui — ${esc(schema.tool)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header>
+  <h1>instagui <code>${esc(schema.tool)}</code></h1>
+  ${summary}
+</header>
+<main>
+  <form id="form" autocomplete="off">
+    ${positionalsHtml}
+    ${optionsHtml}
+  </form>
+  <div class="side">
+    <div class="preview">
+      <h2>Command preview</h2>
+      <pre class="cmd" id="preview">${esc(schema.tool)}</pre>
+      <div class="row">
+        <button type="button" id="copy">Copy</button>
+        <button type="button" id="run" class="primary">Run</button>
+        <button type="button" id="stop" disabled>Stop</button>
+      </div>
+      <div class="status" id="status"></div>
+    </div>
+    <div class="output" id="output" hidden>
+      <h2>Output</h2>
+      <pre class="stream" id="stream"></pre>
+      <div class="exit" id="exit"></div>
+    </div>
+  </div>
+</main>
+<script type="application/json" id="schema">${safeJson(schema)}</script>
+<script>${clientScript}</script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=page.js.map

package/dist/server/page.js.map

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

package/dist/server/run.js

@@ -0,0 +1,71 @@
+// server/run.ts — Story 3.3. Owns the single-run lifecycle: spawn the composed command with
+// an arguments ARRAY (never a shell), forward stdout+stderr to a sink, report the exit code,
+// and kill on Stop. Exactly one run in flight (AD-5): a second start is refused while one is
+// live. The server ties the sink's lifetime to the SSE connection, so a disconnect that
+// stops the sink also drives Stop → no orphaned child.
+//
+// spawn is injected so the controller is unit-testable with a fake child (no real process).
+import { spawn } from 'node:child_process';
+/**
+ * Single-run controller. `start` refuses while a run is live; `stop` terminates it
+ * (SIGTERM, escalating to SIGKILL if ignored). Exactly one child at a time.
+ */
+export class RunController {
+    child = null;
+    spawnFn;
+    constructor(spawnFn = spawn) {
+        this.spawnFn = spawnFn;
+    }
+    get running() {
+        return this.child !== null;
+    }
+    /** Spawn `cmd` with `args` (args array — no shell). Refuses if a run is already in flight. */
+    start(cmd, args, sink) {
+        if (this.child)
+            return { ok: false, reason: 'a run is already in progress' };
+        let child;
+        try {
+            child = this.spawnFn(cmd, args, { shell: false, windowsHide: true });
+        }
+        catch (err) {
+            return { ok: false, reason: `failed to start: ${err.message}` };
+        }
+        this.child = child;
+        child.stdout?.on('data', (c) => sink.out(c.toString('utf8')));
+        child.stderr?.on('data', (c) => sink.out(c.toString('utf8')));
+        const finish = (code, signal) => {
+            if (this.child !== child)
+                return; // already finished (guards error+close double-fire)
+            this.child = null;
+            sink.end({ code, signal });
+        };
+        child.on('error', (err) => {
+            // Map the most common failure — ENOENT (binary missing) — to the same friendly wording
+            // the CLI's ToolNotFoundError uses, instead of leaking a raw "spawn <tool> ENOENT".
+            // Any other spawn error falls back to its message. Either way: surface, then end.
+            const code = err.code;
+            const msg = code === 'ENOENT'
+                ? `instagui: "${cmd}" is not installed or not on your PATH.`
+                : `instagui: failed to run command: ${err.message}`;
+            sink.out(`${msg}\n`);
+            finish(null, null);
+        });
+        child.on('close', (code, signal) => finish(code, signal));
+        return { ok: true };
+    }
+    /** Kill the running child, if any. Returns whether there was one to kill. */
+    stop() {
+        const child = this.child;
+        if (!child)
+            return false;
+        child.kill('SIGTERM');
+        // Escalate if the child ignores SIGTERM. Timer is unref'd so it never holds the process.
+        const timer = setTimeout(() => {
+            if (this.child === child)
+                child.kill('SIGKILL');
+        }, 2000);
+        timer.unref?.();
+        return true;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/server/run.js.map

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

package/dist/server/server.js

@@ -0,0 +1,205 @@
+// server/server.ts — Story 3.1 (serve the Form) + 3.2 (POST /preview) + 3.3 (run/stream).
+// A single node:http server, bound to 127.0.0.1 only (NFR-2), that:
+//   GET  /         → the single-page Form (server/page.ts)
+//   POST /preview  → { args, preview } from core/compose.ts (read-only; no CSRF needed)
+//   GET  /events   → SSE stream carrying run output + exit (AD-5)
+//   POST /run      → compose + spawn (args array, never shell) and stream (AD-6)
+//   POST /stop     → kill the running child
+// State-changing endpoints (/run, /stop) fail closed on a missing/mismatched Origin (CSRF,
+// AD-6). Exactly one run in flight; the SSE connection owns the run, so a disconnect kills
+// the child. The API key never appears here — only the Schema and tool name are served.
+import { createServer } from 'node:http';
+import { compose } from '../core/compose.js';
+import { renderPage } from './page.js';
+import { CLIENT_SCRIPT } from './client.js';
+import { RunController } from './run.js';
+const DEFAULT_PORT = 5177;
+const DEFAULT_HOST = '127.0.0.1';
+const MAX_BODY_BYTES = 512 * 1024;
+/** Read a request body up to a hard cap; returns '' if the cap is exceeded (caller 400s). */
+function readBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let total = 0;
+        let aborted = false;
+        req.on('data', (c) => {
+            total += c.length;
+            if (total > MAX_BODY_BYTES) {
+                aborted = true;
+                resolve(null);
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => {
+            if (!aborted)
+                resolve(Buffer.concat(chunks).toString('utf8'));
+        });
+        req.on('error', () => {
+            if (!aborted)
+                resolve(null);
+        });
+    });
+}
+function sendJson(res, status, body) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(text);
+}
+function sendText(res, status, body) {
+    res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end(body);
+}
+/** Listen with EADDRINUSE fallback: try `port`, and on a clash retry on port 0 (OS-assigned)
+ *  so a busy default never crashes the launch (AC 3.1). Resolves the actually-bound port. */
+function listenWithFallback(server, port, host) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.removeListener('error', onError);
+            if (err.code === 'EADDRINUSE' && port !== 0) {
+                listenWithFallback(server, 0, host).then(resolve, reject);
+            }
+            else {
+                reject(err);
+            }
+        };
+        server.once('error', onError);
+        server.listen(port, host, () => {
+            server.removeListener('error', onError);
+            const addr = server.address();
+            resolve(typeof addr === 'object' && addr ? addr.port : port);
+        });
+    });
+}
+/**
+ * Start the Form server for `schema`. Binds 127.0.0.1 only; falls back off an occupied port.
+ * Resolves once listening, with the bound URL and a `close()` that tears down cleanly
+ * (ends any SSE stream and kills a running child).
+ */
+export async function startServer(opts, deps = {}) {
+    const host = opts.host ?? DEFAULT_HOST;
+    const controller = deps.controller ?? new RunController(deps.spawnFn);
+    const page = renderPage(opts.schema, CLIENT_SCRIPT);
+    let boundPort = 0;
+    // The single active SSE response; the run's output sink and lifecycle are tied to it.
+    let sseRes = null;
+    /** CSRF fail-closed: the Origin must be present AND match our own bound host:port. */
+    function originAllowed(req) {
+        const origin = req.headers.origin;
+        if (typeof origin !== 'string' || origin.length === 0)
+            return false;
+        // Accept our own bound host and the 127.0.0.1/localhost alias for it.
+        const allowed = new Set([`http://${host}:${boundPort}`, `http://localhost:${boundPort}`, `http://127.0.0.1:${boundPort}`]);
+        return allowed.has(origin);
+    }
+    const server = createServer((req, res) => {
+        handle(req, res).catch(() => {
+            if (!res.headersSent)
+                sendText(res, 500, 'instagui: internal error');
+            else
+                res.end();
+        });
+    });
+    async function handle(req, res) {
+        const method = req.method ?? 'GET';
+        const url = (req.url ?? '/').split('?')[0];
+        if (method === 'GET' && url === '/') {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+            res.end(page);
+            return;
+        }
+        if (method === 'POST' && url === '/preview') {
+            const raw = await readBody(req);
+            if (raw === null)
+                return sendText(res, 413, 'body too large');
+            let state;
+            try {
+                state = raw.trim() === '' ? {} : JSON.parse(raw);
+            }
+            catch {
+                return sendText(res, 400, 'invalid JSON');
+            }
+            const { args, preview } = compose(opts.schema, state ?? {});
+            return sendJson(res, 200, { args, preview });
+        }
+        if (method === 'GET' && url === '/events') {
+            res.writeHead(200, {
+                'content-type': 'text/event-stream; charset=utf-8',
+                'cache-control': 'no-cache, no-transform',
+                connection: 'keep-alive',
+            });
+            res.write(': connected\n\n');
+            // Replace any prior stream; the newest tab owns the run.
+            if (sseRes && sseRes !== res)
+                sseRes.end();
+            sseRes = res;
+            req.on('close', () => {
+                if (sseRes === res) {
+                    sseRes = null;
+                    // Disconnect (tab close/reload) must not leave an orphan child (AD-5).
+                    controller.stop();
+                }
+            });
+            return;
+        }
+        if (method === 'POST' && url === '/run') {
+            if (!originAllowed(req))
+                return sendText(res, 403, 'forbidden: bad Origin');
+            const sink = sseRes;
+            if (!sink)
+                return sendText(res, 428, 'open the event stream first');
+            const raw = await readBody(req);
+            if (raw === null)
+                return sendText(res, 413, 'body too large');
+            let state;
+            try {
+                state = raw.trim() === '' ? {} : JSON.parse(raw);
+            }
+            catch {
+                return sendText(res, 400, 'invalid JSON');
+            }
+            const { args } = compose(opts.schema, state ?? {});
+            const runSink = {
+                out: (chunk) => sseWrite(sink, 'out', chunk),
+                end: (result) => sseWrite(sink, 'exit', result),
+            };
+            const outcome = controller.start(opts.schema.tool, args, runSink);
+            if (!outcome.ok)
+                return sendText(res, 409, outcome.reason);
+            return sendText(res, 202, 'running');
+        }
+        if (method === 'POST' && url === '/stop') {
+            if (!originAllowed(req))
+                return sendText(res, 403, 'forbidden: bad Origin');
+            const killed = controller.stop();
+            return sendText(res, 200, killed ? 'stopping' : 'nothing to stop');
+        }
+        return sendText(res, 404, 'not found');
+    }
+    /** Serialize a value as one SSE event. JSON-encoded data stays single-line even with
+     *  embedded newlines, so the framing is never broken by tool output. */
+    function sseWrite(res, event, data) {
+        if (res.writableEnded)
+            return;
+        res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    }
+    boundPort = await listenWithFallback(server, opts.port ?? DEFAULT_PORT, host);
+    const url = `http://${host}:${boundPort}/`;
+    return {
+        url,
+        host,
+        port: boundPort,
+        close() {
+            return new Promise((resolve) => {
+                controller.stop();
+                if (sseRes) {
+                    sseRes.end();
+                    sseRes = null;
+                }
+                server.close(() => resolve());
+            });
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server/server.js.map

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

package/dist/shared/claude-code.js

@@ -0,0 +1,89 @@
+// DEV/TEST-ONLY extraction engine. Shells out to headless Claude Code (`claude -p`,
+// subscription-authenticated) instead of the Anthropic API, so extraction can be
+// exercised without an ANTHROPIC_API_KEY / API credits.
+//
+// It implements the SAME CompleteFn seam as shared/claude.ts and returns raw JSON text —
+// the caller (core/extract.ts) still runs Schema.parse() + one-retry + debug-file, so the
+// validation pipeline is identical to the SDK path.
+//
+// NOT a published requirement and NOT for user docs: it is inert unless INSTAGUI_ENGINE is
+// set to "claude-code", the SDK path remains primary/default, and it depends on a `claude`
+// binary that end users are not expected to have.
+import { spawn } from 'node:child_process';
+import { zodOutputFormat } from '@anthropic-ai/sdk/helpers/zod';
+/** Map an API model id to a Claude Code `--model` alias where possible; otherwise pass it
+ *  through. Subscription auth may override the selection — reported as a divergence. */
+function claudeCodeModel(model) {
+    if (model.includes('haiku'))
+        return 'haiku';
+    if (model.includes('sonnet'))
+        return 'sonnet';
+    if (model.includes('opus'))
+        return 'opus';
+    return model;
+}
+/** Compose the single prompt piped to `claude -p`. Claude Code has no server-side schema
+ *  enforcement, so the exact JSON Schema (derived from the same zod object) is appended
+ *  with a JSON-only instruction. */
+function composePrompt(req) {
+    const fmt = zodOutputFormat(req.outputSchema);
+    const jsonSchema = JSON.stringify(fmt.schema, null, 2);
+    return (`${req.system}\n\n${req.user}\n\n` +
+        `Respond with ONLY a single JSON object that conforms to this JSON Schema. ` +
+        `No markdown, no code fences, no commentary before or after.\n\n` +
+        `JSON Schema:\n${jsonSchema}`);
+}
+/** Pull the JSON object out of Claude Code's stdout. Transport-layer normalization only
+ *  (fences / surrounding prose); it does NOT validate — that stays in the shared pipeline
+ *  so malformed output still flows through retry + debug-file. */
+export function extractJsonText(stdout) {
+    let s = stdout.trim();
+    const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fence?.[1])
+        s = fence[1].trim();
+    const first = s.indexOf('{');
+    const last = s.lastIndexOf('}');
+    if (first !== -1 && last > first)
+        return s.slice(first, last + 1);
+    return s; // let JSON.parse fail downstream → retry → debug-file
+}
+function runClaude(args, stdin, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        // shell:true so a Windows `claude.cmd` shim resolves via PATHEXT. Args are simple
+        // flags (no untrusted values); the prompt goes over stdin, never the command line.
+        const child = spawn('claude', args, { shell: true });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`claude -p timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.stdout.on('data', (d) => (stdout += d.toString('utf8')));
+        child.stderr.on('data', (d) => (stderr += d.toString('utf8')));
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code });
+        });
+        child.stdin.write(stdin);
+        child.stdin.end();
+    });
+}
+/** CompleteFn implemented over `claude -p`. Dev/test only. */
+export const completeViaClaudeCode = async (req) => {
+    const prompt = composePrompt(req);
+    const args = ['-p', '--model', claudeCodeModel(req.model)];
+    const { stdout, stderr, code } = await runClaude(args, prompt, 180_000);
+    if (code !== 0) {
+        throw new Error(`claude -p exited with code ${code}: ${stderr.trim() || '(no stderr)'}`);
+    }
+    const json = extractJsonText(stdout);
+    if (json.trim().length === 0) {
+        throw new Error('claude -p returned empty output.');
+    }
+    return json;
+};
+//# sourceMappingURL=claude-code.js.map

package/dist/shared/claude-code.js.map

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

package/dist/shared/claude.js

@@ -0,0 +1,33 @@
+// AD-3 — a instagui-agnostic Claude client: prompt + output shape in, raw JSON text out.
+// It knows nothing about Tools, Schemas, or Forms — it takes any zod object as the
+// output shape and returns the model's raw JSON string. Callers run their own
+// validation (core does Schema.parse), which keeps the invalid raw text available for
+// debugging when validation fails.
+import Anthropic from '@anthropic-ai/sdk';
+import { zodOutputFormat } from '@anthropic-ai/sdk/helpers/zod';
+/**
+ * Send one completion and return the raw assistant text (expected to be JSON, but
+ * NOT validated here). Throws if the response carries no text block at all.
+ *
+ * @param client optional injected client; defaults to a real Anthropic() which reads
+ *               ANTHROPIC_API_KEY from the environment.
+ */
+export async function complete(req, client) {
+    const anthropic = client ?? new Anthropic();
+    const message = await anthropic.messages.create({
+        model: req.model,
+        max_tokens: req.maxTokens ?? 16000,
+        system: req.system,
+        messages: [{ role: 'user', content: req.user }],
+        output_config: { format: zodOutputFormat(req.outputSchema) },
+    });
+    const text = message.content
+        .filter((b) => b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('');
+    if (text.trim().length === 0) {
+        throw new Error('Claude returned no text content.');
+    }
+    return text;
+}
+//# sourceMappingURL=claude.js.map

package/dist/shared/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/shared/claude.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,mFAAmF;AACnF,8EAA8E;AAC9E,sFAAsF;AACtF,mCAAmC;AACnC,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAuBhE;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAsB,EAAE,MAAqB;IAC1E,MAAM,SAAS,GAAiB,MAAM,IAAK,IAAI,SAAS,EAA8B,CAAC;IAEvF,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC9C,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,GAAG,CAAC,SAAS,IAAI,KAAK;QAClC,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;QAC/C,aAAa,EAAE,EAAE,MAAM,EAAE,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE;KAC7D,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO;SACzB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC;SAC9D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAc,CAAC;SAC5B,IAAI,CAAC,EAAE,CAAC,CAAC;IAEZ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/shared/config.js

@@ -0,0 +1,17 @@
+// AD-3 — shared/ is instagui-agnostic. Config is limited to the two things the whole
+// program shares: the API key and the on-disk data dir. No Tool/Schema/Form concepts.
+import os from 'node:os';
+import path from 'node:path';
+/** The env var carrying the Anthropic key. Never logged or echoed. */
+export const API_KEY_ENV = 'ANTHROPIC_API_KEY';
+/** True when a key is present in the environment. Does not read or return its value. */
+export function hasApiKey() {
+    const v = process.env[API_KEY_ENV];
+    return typeof v === 'string' && v.trim().length > 0;
+}
+/** The per-user data directory (`~/.instagui`). Used by the cache in Epic 2; defined here
+ *  so the boundary lives in one place. */
+export function instaguiDir() {
+    return path.join(os.homedir(), '.instagui');
+}
+//# sourceMappingURL=config.js.map

package/dist/shared/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/shared/config.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,sFAAsF;AACtF,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,sEAAsE;AACtE,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAE/C,wFAAwF;AACxF,MAAM,UAAU,SAAS;IACvB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AACtD,CAAC;AAED;0CAC0C;AAC1C,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAC9C,CAAC"}