@inbrowser/agent 0.0.0-placeholder → 0.2.0

package/dist/cli/llm/openrouter.js

@@ -0,0 +1,285 @@
+/**
+ * OpenRouter `LlmClient` for the CLI's `agent run`.
+ *
+ * Distinct from the playground's `openrouterProvider` in
+ * `examples/admin-compat-browser/src/openrouter.ts` (which is browser-
+ * specific — reads keys from localStorage, surfaces BYOK forms, etc.).
+ * This module is CLI-native: it takes its config explicitly at
+ * construction time (no env-var sniffing here — the caller decides
+ * how to source the key) and implements the narrow `LlmClient`
+ * contract that `@inbrowser/agent`' strategy + session expect.
+ *
+ * Streams via OpenAI-compatible SSE. Function-calling supported via
+ * `tools` + `tool_choice: 'auto'`. Reasoning surfaced through
+ * `reasoning.effort` + `include_reasoning` headers for models that
+ * carry extended thinking (GLM, DeepSeek-R1, Claude, GPT reasoning
+ * models). Cost surfaced through OpenRouter's per-call `usage.cost`
+ * field so the agent's `MetricsCollector` doesn't need a per-model
+ * pricing table for OpenRouter-served models.
+ */
+const ENDPOINT = 'https://openrouter.ai/api/v1/chat/completions';
+export function openRouterClient(config) {
+    const endpoint = config.baseUrl ?? ENDPOINT;
+    const effort = config.reasoningEffort ?? 'off';
+    return {
+        id: `openrouter:${config.model}`,
+        supportsTools: true,
+        async *chat(req, signal) {
+            const messages = toOaiMessages(req.messages);
+            const tools = req.toolUseEnabled && req.tools.length > 0
+                ? req.tools.map((t) => ({
+                    type: 'function',
+                    function: {
+                        name: t.name,
+                        description: t.description,
+                        parameters: t.parameters,
+                    },
+                }))
+                : undefined;
+            const body = {
+                model: config.model,
+                messages,
+                stream: true,
+                ...(tools ? { tools, tool_choice: 'auto' } : {}),
+                ...(effort !== 'off'
+                    ? {
+                        reasoning: { effort, summary: 'auto' },
+                        include_reasoning: true,
+                    }
+                    : {}),
+            };
+            const headers = {
+                'content-type': 'application/json',
+                authorization: `Bearer ${config.apiKey}`,
+            };
+            if (config.referer)
+                headers['http-referer'] = config.referer;
+            if (config.title)
+                headers['x-title'] = config.title;
+            let res;
+            try {
+                res = await fetch(endpoint, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(body),
+                    signal,
+                });
+            }
+            catch (err) {
+                yield { kind: 'error', message: `OpenRouter network error: ${errMsg(err)}` };
+                return;
+            }
+            if (!res.ok || !res.body) {
+                const detail = await res.text().catch(() => '');
+                yield {
+                    kind: 'error',
+                    message: `OpenRouter ${res.status}: ${detail || res.statusText}`,
+                };
+                return;
+            }
+            // Accumulators for the streaming turn.
+            const details = { requestedModel: config.model };
+            const toolBuf = new Map();
+            let usage;
+            let aborted = false;
+            try {
+                for await (const chunk of streamSse(res.body, signal)) {
+                    if (signal.aborted) {
+                        aborted = true;
+                        break;
+                    }
+                    const c = chunk;
+                    // Provenance — last-write-wins. The fields the agent's
+                    // TurnDetails actually carries are `servedModel`,
+                    // `fingerprint`, and free-form `routing`; OpenRouter's
+                    // response id goes into routing alongside any other
+                    // provider-specific signals.
+                    if (c.model && !details.servedModel)
+                        details.servedModel = c.model;
+                    if (c.system_fingerprint && !details.fingerprint) {
+                        details.fingerprint = c.system_fingerprint;
+                    }
+                    if (c.id) {
+                        details.routing = { ...(details.routing ?? {}), responseId: c.id };
+                    }
+                    const choice = c.choices?.[0];
+                    if (choice) {
+                        const delta = choice.delta ?? {};
+                        if (typeof delta.content === 'string' && delta.content.length > 0) {
+                            yield { kind: 'text', chunk: delta.content };
+                        }
+                        // Reasoning: flat string OR structured array. Both → thinking events.
+                        // Reasoning surface — providers send ONE of three shapes per
+                        // chunk, but some (e.g. GLM) send both `reasoning` and
+                        // `reasoning_content` for legacy-proxy compat. Pick the
+                        // first non-empty shape and ignore the rest, otherwise the
+                        // thinking pane shows every token twice. Matches the
+                        // playground's openrouter.ts ordering.
+                        const thinkingChunk = pickReasoning(delta.reasoning, delta.reasoning_content, delta.reasoning_details);
+                        if (thinkingChunk)
+                            yield { kind: 'thinking', chunk: thinkingChunk };
+                        // Tool calls — accumulated per index, emitted at finish.
+                        if (Array.isArray(delta.tool_calls)) {
+                            for (const tc of delta.tool_calls) {
+                                const i = tc.index;
+                                const slot = toolBuf.get(i) ?? { id: '', name: '', argsBuf: '' };
+                                if (tc.id)
+                                    slot.id = tc.id;
+                                if (tc.function?.name)
+                                    slot.name = tc.function.name;
+                                if (tc.function?.arguments)
+                                    slot.argsBuf += tc.function.arguments;
+                                toolBuf.set(i, slot);
+                            }
+                        }
+                    }
+                    if (c.usage) {
+                        usage = {
+                            promptTokens: c.usage.prompt_tokens ?? 0,
+                            completionTokens: c.usage.completion_tokens ?? 0,
+                            ...(c.usage.prompt_tokens_details?.cached_tokens !== undefined
+                                ? { cachedTokens: c.usage.prompt_tokens_details.cached_tokens }
+                                : {}),
+                            ...(c.usage.cost !== undefined ? { costUsd: c.usage.cost } : {}),
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                if (signal.aborted) {
+                    aborted = true;
+                }
+                else {
+                    yield { kind: 'error', message: `OpenRouter stream error: ${errMsg(err)}` };
+                    return;
+                }
+            }
+            // Emit accumulated tool calls before the turn-complete sentinel.
+            for (const slot of toolBuf.values()) {
+                if (!slot.name)
+                    continue;
+                let args = slot.argsBuf;
+                if (slot.argsBuf.length > 0) {
+                    try {
+                        args = JSON.parse(slot.argsBuf);
+                    }
+                    catch {
+                        // Leave as raw string; let the dispatcher surface the parse error.
+                    }
+                }
+                else {
+                    args = {};
+                }
+                yield {
+                    kind: 'tool_call',
+                    id: slot.id || `tc_${Math.random().toString(36).slice(2, 10)}`,
+                    name: slot.name,
+                    args,
+                };
+            }
+            if (aborted) {
+                yield { kind: 'error', message: 'OpenRouter stream aborted' };
+                return;
+            }
+            yield {
+                kind: 'turn_complete',
+                usage: usage ?? { promptTokens: 0, completionTokens: 0 },
+                details,
+            };
+        },
+    };
+}
+// ─── helpers ─────────────────────────────────────────────────────────
+/**
+ * Pick the right reasoning surface from a chunk. Providers can fill
+ * `delta.reasoning` (flat string — DeepSeek-R1, Claude, GLM, Kimi,
+ * Minimax), `delta.reasoning_content` (legacy alias some proxies
+ * still emit alongside `reasoning`), or `delta.reasoning_details[]`
+ * (structured — OpenAI GPT-5 series). Returns the first non-empty
+ * value found; subsequent ones are dropped to avoid duplicated
+ * thinking output.
+ */
+function pickReasoning(flat, alias, details) {
+    if (typeof flat === 'string' && flat.length > 0)
+        return flat;
+    if (typeof alias === 'string' && alias.length > 0)
+        return alias;
+    if (Array.isArray(details)) {
+        const parts = [];
+        for (const r of details) {
+            const text = r.summary ?? r.text;
+            if (typeof text === 'string' && text.length > 0)
+                parts.push(text);
+        }
+        if (parts.length > 0)
+            return parts.join('');
+    }
+    return null;
+}
+function toOaiMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'tool') {
+            out.push({
+                role: 'tool',
+                content: m.resultJson ?? '',
+                tool_call_id: m.callId ?? '',
+            });
+            continue;
+        }
+        const msg = { role: m.role, content: m.text };
+        if (m.role === 'assistant' && m.toolCalls && m.toolCalls.length > 0) {
+            msg.tool_calls = m.toolCalls.map((tc) => ({
+                id: tc.callId,
+                type: 'function',
+                function: { name: tc.name, arguments: JSON.stringify(tc.args ?? {}) },
+            }));
+        }
+        out.push(msg);
+    }
+    return out;
+}
+/**
+ * Async iterator over OpenAI-compatible SSE chunks. Yields parsed JSON
+ * objects, stops on `data: [DONE]`. Lines that aren't `data: ...` or
+ * that fail to parse are silently dropped — the OpenAI streaming spec
+ * permits comments + heartbeats.
+ */
+async function* streamSse(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder('utf-8');
+    let buf = '';
+    try {
+        while (!signal.aborted) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            // SSE messages are separated by blank lines. Process complete
+            // events; keep the trailing partial in the buffer.
+            let idx;
+            while ((idx = buf.indexOf('\n')) >= 0) {
+                const rawLine = buf.slice(0, idx).replace(/\r$/, '');
+                buf = buf.slice(idx + 1);
+                if (!rawLine.startsWith('data:'))
+                    continue;
+                const payload = rawLine.slice(5).trim();
+                if (payload === '[DONE]')
+                    return;
+                try {
+                    yield JSON.parse(payload);
+                }
+                catch {
+                    // Drop malformed chunk; keep streaming.
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=openrouter.js.map

package/dist/cli/llm/openrouter.js.map

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

package/dist/cli/main.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `agent` CLI entry. The `bin/agent.ts` shebang script is a one-liner
+ * that imports `main` from here so the dispatching logic stays
+ * importable + unit-testable.
+ *
+ * Top-level guarantees:
+ *   - argv is parsed against `spec.ts` with input hardening enforced
+ *     before any side effect.
+ *   - Errors are emitted as a single structured event and surface as
+ *     non-zero exit codes (64 for usage/hardening, 1 for runtime).
+ *   - Output mode auto-selects: NDJSON when stdout is not a TTY,
+ *     text when it is, overridden by --output.
+ */
+import type { AgentDefinition } from '../types/agent.js';
+import type { ProjectContext } from '../types/project-context.js';
+export interface MainOptions {
+    argv?: readonly string[];
+    cwd?: string;
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+    now?: () => string;
+    /**
+     * Agents to expose under `agent serve`. The bare CLI ships zero
+     * built-ins; host packages wire their own here. Ignored by every
+     * other subcommand.
+     */
+    serveAgents?: AgentDefinition[];
+    /** Pre-built `ProjectContext` for `agent serve` live-mode tools. */
+    serveAgentApp?: ProjectContext;
+}
+export declare function main(opts?: MainOptions): Promise<number>;
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAclE,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,oEAAoE;IACpE,aAAa,CAAC,EAAE,cAAc,CAAC;CAChC;AAED,wBAAsB,IAAI,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4FlE"}

package/dist/cli/main.js

@@ -0,0 +1,106 @@
+/**
+ * `agent` CLI entry. The `bin/agent.ts` shebang script is a one-liner
+ * that imports `main` from here so the dispatching logic stays
+ * importable + unit-testable.
+ *
+ * Top-level guarantees:
+ *   - argv is parsed against `spec.ts` with input hardening enforced
+ *     before any side effect.
+ *   - Errors are emitted as a single structured event and surface as
+ *     non-zero exit codes (64 for usage/hardening, 1 for runtime).
+ *   - Output mode auto-selects: NDJSON when stdout is not a TTY,
+ *     text when it is, overridden by --output.
+ */
+import { describeCommand } from './commands/describe.js';
+import { eventsCommand } from './commands/events.js';
+import { fleetCommand } from './commands/fleet.js';
+import { helpCommand, versionCommand } from './commands/help.js';
+import { migrateCommand } from './commands/migrate.js';
+import { runCommand } from './commands/run.js';
+import { schemaCommand } from './commands/schema.js';
+import { serveCommand } from './commands/serve.js';
+import { undoCommand } from './commands/undo.js';
+import { createEmitter, errorEvent, pickMode } from './output.js';
+import { InputHardeningError, UsageError, parseArgs } from './parse.js';
+export async function main(opts = {}) {
+    const argv = opts.argv ?? process.argv.slice(2);
+    const cwd = opts.cwd ?? process.cwd();
+    const stdout = opts.stdout ?? process.stdout;
+    let mode = pickMode(undefined, stdout);
+    let emit = createEmitter({ mode }, stdout);
+    let args;
+    try {
+        args = parseArgs(argv, cwd);
+    }
+    catch (err) {
+        if (err instanceof InputHardeningError) {
+            emit.event(errorEvent(err), () => `error: ${err.message}`);
+            emit.finish();
+            return 64;
+        }
+        if (err instanceof UsageError) {
+            emit.event({ type: 'error', name: 'UsageError', message: err.message, hint: err.hint }, () => `error: ${err.message}${err.hint ? `\n  hint: ${err.hint}` : ''}`);
+            emit.finish();
+            return 64;
+        }
+        emit.event(errorEvent(err));
+        emit.finish();
+        return 2;
+    }
+    // Honor --output / --fields globally (re-create the emitter now that we know).
+    const requested = args.options['output'] ?? undefined;
+    mode = pickMode(requested, stdout);
+    const rawFields = args.options['fields'];
+    const fields = Array.isArray(rawFields) ? rawFields : undefined;
+    emit = createEmitter({ mode, fields }, stdout);
+    // --help on any subcommand: re-route to the help command scoped to it.
+    if (args.options['help']) {
+        return helpCommand({ command: 'help', options: {}, positional: [args.command], remainder: [] }, emit);
+    }
+    try {
+        switch (args.command) {
+            case 'run':
+                return await runCommand(args, { emit, now: opts.now });
+            case 'fleet':
+                return await fleetCommand(args, { emit, now: opts.now });
+            case 'describe':
+                return describeCommand(args, emit);
+            case 'schema':
+                return schemaCommand(emit);
+            case 'events':
+                return eventsCommand(args, { emit });
+            case 'undo':
+                return undoCommand(args, { emit, now: opts.now });
+            case 'serve':
+                return await serveCommand(args, {
+                    emit,
+                    now: opts.now,
+                    ...(opts.serveAgents ? { agents: opts.serveAgents } : {}),
+                    ...(opts.serveAgentApp ? { agentApp: opts.serveAgentApp } : {}),
+                });
+            case 'migrate':
+                return migrateCommand(args, { emit, now: opts.now });
+            case 'version':
+                return versionCommand(emit);
+            case 'help':
+            default:
+                return helpCommand(args, emit);
+        }
+    }
+    catch (err) {
+        if (err instanceof InputHardeningError) {
+            emit.event(errorEvent(err), () => `error: ${err.message}`);
+            emit.finish();
+            return 64;
+        }
+        if (err instanceof UsageError) {
+            emit.event({ type: 'error', name: 'UsageError', message: err.message, hint: err.hint }, () => `error: ${err.message}${err.hint ? `\n  hint: ${err.hint}` : ''}`);
+            emit.finish();
+            return 64;
+        }
+        emit.event(errorEvent(err), () => `error: ${err instanceof Error ? err.message : String(err)}`);
+        emit.finish();
+        return 1;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/cli/main.js.map

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

package/dist/cli/output.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Output layer — Agent DX axes 1 (machine-readable) + 4 (context window
+ * discipline). Three modes:
+ *
+ *   - `ndjson` — one JSON object per line, flushed as it's emitted.
+ *     Default when stdout is not a TTY. Streams paginated/long
+ *     results.
+ *   - `json` — single buffered JSON object at the end (for describe /
+ *     schema / one-shot help).
+ *   - `text` — human-readable, ANSI-styled. Default in a TTY.
+ *
+ * Field filtering via `--fields` applies to ndjson and json. Field
+ * names are matched literally against the top-level keys of the
+ * emitted object. Unmatched fields are dropped silently.
+ */
+import type { WriteStream } from 'node:tty';
+export type OutputMode = 'ndjson' | 'json' | 'text';
+export interface OutputOptions {
+    mode: OutputMode;
+    /** Allowlist of top-level fields to include in ndjson/json output. */
+    fields?: readonly string[];
+    /** Disable ANSI styling. Auto-true when not a TTY. */
+    noColor?: boolean;
+}
+export interface Emitter {
+    readonly mode: OutputMode;
+    /** Emit one event (NDJSON line) or buffer it (JSON). Pass `text` for plain text mode. */
+    event(obj: Record<string, unknown>, plain?: () => string): void;
+    /** Flush buffered output. For ndjson + text this is a no-op. */
+    finish(): void;
+}
+export declare function pickMode(preferred: OutputMode | undefined, stream: NodeJS.WriteStream | WriteStream): OutputMode;
+export declare function createEmitter(opts: OutputOptions, stream?: NodeJS.WriteStream): Emitter;
+/** Convenience: bundle an Error into a structured event. */
+export declare function errorEvent(err: unknown): Record<string, unknown>;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,sEAAsE;IACtE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,sDAAsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,yFAAyF;IACzF,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAChE,gEAAgE;IAChE,MAAM,IAAI,IAAI,CAAC;CAChB;AAcD,wBAAgB,QAAQ,CACtB,SAAS,EAAE,UAAU,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,CAAC,WAAW,GAAG,WAAW,GACvC,UAAU,CAGZ;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,MAAM,GAAE,MAAM,CAAC,WAA4B,GAC1C,OAAO,CAuCT;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBhE"}

package/dist/cli/output.js

@@ -0,0 +1,95 @@
+/**
+ * Output layer — Agent DX axes 1 (machine-readable) + 4 (context window
+ * discipline). Three modes:
+ *
+ *   - `ndjson` — one JSON object per line, flushed as it's emitted.
+ *     Default when stdout is not a TTY. Streams paginated/long
+ *     results.
+ *   - `json` — single buffered JSON object at the end (for describe /
+ *     schema / one-shot help).
+ *   - `text` — human-readable, ANSI-styled. Default in a TTY.
+ *
+ * Field filtering via `--fields` applies to ndjson and json. Field
+ * names are matched literally against the top-level keys of the
+ * emitted object. Unmatched fields are dropped silently.
+ */
+function projectFields(obj, fields) {
+    if (!fields || fields.length === 0)
+        return obj;
+    const out = {};
+    for (const f of fields) {
+        if (Object.prototype.hasOwnProperty.call(obj, f))
+            out[f] = obj[f];
+    }
+    return out;
+}
+export function pickMode(preferred, stream) {
+    if (preferred)
+        return preferred;
+    return stream.isTTY ? 'text' : 'ndjson';
+}
+export function createEmitter(opts, stream = process.stdout) {
+    const fields = opts.fields;
+    if (opts.mode === 'ndjson') {
+        return {
+            mode: 'ndjson',
+            event(obj) {
+                stream.write(JSON.stringify(projectFields(obj, fields)) + '\n');
+            },
+            finish() { },
+        };
+    }
+    if (opts.mode === 'json') {
+        const buf = [];
+        return {
+            mode: 'json',
+            event(obj) {
+                buf.push(projectFields(obj, fields));
+            },
+            finish() {
+                // Emit a single object when there's exactly one event (describe / schema /
+                // help shapes). Otherwise emit an array — preserves stream-like callers
+                // that only buffered for terminal output.
+                const payload = buf.length === 1 ? buf[0] : buf;
+                stream.write(JSON.stringify(payload, null, 2) + '\n');
+            },
+        };
+    }
+    // text — ignore fields, prefer the `plain()` thunk if provided.
+    return {
+        mode: 'text',
+        event(obj, plain) {
+            if (plain) {
+                stream.write(plain() + '\n');
+            }
+            else {
+                stream.write(JSON.stringify(obj) + '\n');
+            }
+        },
+        finish() { },
+    };
+}
+/** Convenience: bundle an Error into a structured event. */
+export function errorEvent(err) {
+    if (err instanceof Error) {
+        const out = {
+            type: 'error',
+            ts: new Date().toISOString(),
+            name: err.name,
+            message: err.message,
+        };
+        // Surface our own fields (InputHardeningError carries field/reason).
+        for (const k of Object.keys(err)) {
+            if (k === 'message' || k === 'stack' || k === 'name')
+                continue;
+            out[k] = err[k];
+        }
+        return out;
+    }
+    return {
+        type: 'error',
+        ts: new Date().toISOString(),
+        message: String(err),
+    };
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

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

package/dist/cli/parse.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Schema-driven arg parser. Inputs flow through `hardenString`/`hardenPath`
+ * per the rules declared in `spec.ts` — there is no second source of
+ * truth. Returns a typed `ParsedArgs` or throws `InputHardeningError`
+ * (already structured for NDJSON emission).
+ */
+import { InputHardeningError } from './hardening.js';
+export interface ParsedArgs {
+    command: string;
+    options: Record<string, string | number | boolean | string[]>;
+    positional: string[];
+    /** Original argv minus the parsed command, useful for diagnostics. */
+    remainder: string[];
+}
+export declare class UsageError extends Error {
+    readonly hint?: string | undefined;
+    readonly name = "UsageError";
+    constructor(message: string, hint?: string | undefined);
+}
+/**
+ * Parse argv into `{command, options, positional}`. The first
+ * non-option token is the command. Unknown flags throw `UsageError`.
+ */
+export declare function parseArgs(argv: readonly string[], cwd?: string): ParsedArgs;
+export { InputHardeningError };
+//# sourceMappingURL=parse.d.ts.map

package/dist/cli/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/cli/parse.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAA4B,MAAM,gBAAgB,CAAC;AAI/E,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAC;IAC9D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,qBAAa,UAAW,SAAQ,KAAK;IAIjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IAHxB,SAAkB,IAAI,gBAAgB;gBAEpC,OAAO,EAAE,MAAM,EACN,IAAI,CAAC,EAAE,MAAM,YAAA;CAIzB;AAoED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,GAAE,MAAsB,GAAG,UAAU,CAiG1F;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAC"}