@inbrowser/agent 0.0.0-placeholder → 0.1.0

package/dist/cli/parse.js

@@ -0,0 +1,160 @@
+/**
+ * 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, hardenPath, hardenString } from './hardening.js';
+import { CLI_SPEC, findCommand } from './spec.js';
+export class UsageError extends Error {
+    hint;
+    name = 'UsageError';
+    constructor(message, hint) {
+        super(message);
+        this.hint = hint;
+    }
+}
+function optionByFlag(flags, cmd) {
+    const all = [...CLI_SPEC.globalOptions, ...(cmd?.options ?? [])];
+    return all.find((o) => o.name === flags || o.short === flags);
+}
+function coerceValue(spec, raw, field, cwd) {
+    if (spec.type === 'boolean')
+        return raw === true ? true : raw !== 'false';
+    if (raw === true) {
+        throw new UsageError(`${field} requires a value`, `Pass it as --${spec.name.replace(/^--/, '')} <value>`);
+    }
+    switch (spec.type) {
+        case 'number': {
+            const n = Number(raw);
+            if (!Number.isFinite(n))
+                throw new UsageError(`${field} expects a number, got ${JSON.stringify(raw)}`);
+            return n;
+        }
+        case 'enum': {
+            if (!spec.choices?.includes(raw)) {
+                throw new UsageError(`${field} expects one of ${spec.choices?.join(', ')}; got ${JSON.stringify(raw)}`);
+            }
+            return raw;
+        }
+        case 'string[]': {
+            const items = raw
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            for (const item of items) {
+                if (spec.validate)
+                    hardenString(field, item, spec.validate);
+            }
+            return items;
+        }
+        case 'path': {
+            return hardenPath(field, raw, spec.validate ?? {}, cwd);
+        }
+        case 'json': {
+            // The literal value here is either '-' (stdin sentinel) or a file path.
+            // Hardening for path-likeness applies, but we don't *resolve* — the
+            // command handler decides whether to read stdin or open a file.
+            if (raw === '-')
+                return '-';
+            return hardenPath(field, raw, { rejectControlChars: true, rejectQueryChars: true, maxLength: 1024 }, cwd);
+        }
+        case 'string':
+        default: {
+            if (spec.validate)
+                hardenString(field, raw, spec.validate);
+            return raw;
+        }
+    }
+}
+/**
+ * Parse argv into `{command, options, positional}`. The first
+ * non-option token is the command. Unknown flags throw `UsageError`.
+ */
+export function parseArgs(argv, cwd = process.cwd()) {
+    if (argv.length === 0) {
+        return { command: 'help', options: {}, positional: [], remainder: [] };
+    }
+    // First positional is the command. Allow `agent --help` and `agent -h` as shortcuts to help.
+    let commandName = '';
+    let cursor = 0;
+    while (cursor < argv.length) {
+        const tok = argv[cursor];
+        if (tok === '--help' || tok === '-h') {
+            commandName = 'help';
+            cursor += 1;
+            break;
+        }
+        if (tok === '--version' || tok === '-v') {
+            commandName = 'version';
+            cursor += 1;
+            break;
+        }
+        if (!tok.startsWith('-')) {
+            commandName = tok;
+            cursor += 1;
+            break;
+        }
+        // A leading global option before the command name is allowed; rewind.
+        break;
+    }
+    if (!commandName) {
+        commandName = 'help';
+    }
+    if (!findCommand(commandName) && commandName !== 'help') {
+        throw new UsageError(`unknown command: ${commandName}`, `Try one of: ${CLI_SPEC.commands.map((c) => c.name).join(', ')}`);
+    }
+    const cmd = findCommand(commandName);
+    const options = {};
+    const positional = [];
+    while (cursor < argv.length) {
+        const tok = argv[cursor];
+        if (tok === '--') {
+            positional.push(...argv.slice(cursor + 1));
+            break;
+        }
+        if (!tok.startsWith('-')) {
+            positional.push(tok);
+            cursor += 1;
+            continue;
+        }
+        // Support --name=value as well as --name value.
+        let flag = tok;
+        let inlineValue;
+        const eq = tok.indexOf('=');
+        if (eq > 0) {
+            flag = tok.slice(0, eq);
+            inlineValue = tok.slice(eq + 1);
+        }
+        const spec = optionByFlag(flag, cmd);
+        if (!spec) {
+            throw new UsageError(`unknown option ${flag} for "${commandName}"`, `Run \`agent describe --target commands\` to list valid options.`);
+        }
+        const key = spec.name.replace(/^--/, '');
+        if (spec.type === 'boolean') {
+            options[key] = inlineValue ? inlineValue !== 'false' : true;
+            cursor += 1;
+            continue;
+        }
+        let raw;
+        if (inlineValue !== undefined) {
+            raw = inlineValue;
+            cursor += 1;
+        }
+        else {
+            const next = argv[cursor + 1];
+            if (next === undefined) {
+                raw = true;
+                cursor += 1;
+            }
+            else {
+                raw = next;
+                cursor += 2;
+            }
+        }
+        options[key] = coerceValue(spec, raw, flag, cwd);
+    }
+    return { command: commandName, options, positional, remainder: argv.slice(cursor) };
+}
+export { InputHardeningError };
+//# sourceMappingURL=parse.js.map

package/dist/cli/parse.js.map

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

package/dist/cli/session-log.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-session NDJSON log writer. Every CLI run gets one file at
+ * `<log-dir>/<sessionId>.ndjson` (unless --no-log). Each line is one
+ * event from the same stream the CLI emits — session_start, turn
+ * events, tool_call, tool_result, sandbox_event, turn_end, session_end.
+ *
+ * The final `session_end` event carries the metrics totals so the file
+ * is self-contained: an agent can `tail` the last line for a summary
+ * or stream the whole file for a full replay.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, writeSync } from 'node:fs';
+export interface SessionLog {
+    readonly path: string | null;
+    write(event: Record<string, unknown>): void;
+    close(): void;
+}
+export declare function defaultLogDir(): string;
+export interface OpenSessionLogOptions {
+    /** Absolute or already-resolved directory. Pass null/undefined to use the default. */
+    logDir?: string | null;
+    sessionId: string;
+    /** When true, returns a no-op writer. */
+    disabled?: boolean;
+    /** Defaults to fs primitives; injectable for tests. */
+    io?: {
+        existsSync: typeof existsSync;
+        mkdirSync: typeof mkdirSync;
+        openSync: typeof openSync;
+        writeSync: typeof writeSync;
+        closeSync: typeof closeSync;
+    };
+}
+export declare function openSessionLog(opts: OpenSessionLogOptions): SessionLog;
+//# sourceMappingURL=session-log.d.ts.map

package/dist/cli/session-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-log.d.ts","sourceRoot":"","sources":["../../src/cli/session-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIhF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C,KAAK,IAAI,IAAI,CAAC;CACf;AAQD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uDAAuD;IACvD,EAAE,CAAC,EAAE;QACH,UAAU,EAAE,OAAO,UAAU,CAAC;QAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;QAC5B,QAAQ,EAAE,OAAO,QAAQ,CAAC;QAC1B,SAAS,EAAE,OAAO,SAAS,CAAC;QAC5B,SAAS,EAAE,OAAO,SAAS,CAAC;KAC7B,CAAC;CACH;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,UAAU,CAwBtE"}

package/dist/cli/session-log.js

@@ -0,0 +1,52 @@
+/**
+ * Per-session NDJSON log writer. Every CLI run gets one file at
+ * `<log-dir>/<sessionId>.ndjson` (unless --no-log). Each line is one
+ * event from the same stream the CLI emits — session_start, turn
+ * events, tool_call, tool_result, sandbox_event, turn_end, session_end.
+ *
+ * The final `session_end` event carries the metrics totals so the file
+ * is self-contained: an agent can `tail` the last line for a summary
+ * or stream the whole file for a full replay.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname } from 'node:path';
+const NOOP_LOG = {
+    path: null,
+    write() { },
+    close() { },
+};
+export function defaultLogDir() {
+    return `${homedir()}/.pyric/sessions`;
+}
+export function openSessionLog(opts) {
+    if (opts.disabled)
+        return NOOP_LOG;
+    const dir = opts.logDir && opts.logDir.length > 0 ? opts.logDir : defaultLogDir();
+    const path = `${dir.replace(/\/$/, '')}/${opts.sessionId}.ndjson`;
+    const io = opts.io ?? { existsSync, mkdirSync, openSync, writeSync, closeSync };
+    if (!io.existsSync(dir))
+        io.mkdirSync(dir, { recursive: true });
+    // Also defensively ensure the parent of `path` exists when the session id
+    // contains a '/' — disallowed by hardening, but cheap to guard.
+    const parent = dirname(path);
+    if (parent && !io.existsSync(parent))
+        io.mkdirSync(parent, { recursive: true });
+    const fd = io.openSync(path, 'a');
+    let closed = false;
+    return {
+        path,
+        write(event) {
+            if (closed)
+                return;
+            io.writeSync(fd, JSON.stringify(event) + '\n');
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            io.closeSync(fd);
+        },
+    };
+}
+//# sourceMappingURL=session-log.js.map

package/dist/cli/session-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-log.js","sourceRoot":"","sources":["../../src/cli/session-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChF,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,MAAM,QAAQ,GAAe;IAC3B,IAAI,EAAE,IAAI;IACV,KAAK,KAAI,CAAC;IACV,KAAK,KAAI,CAAC;CACX,CAAC;AAEF,MAAM,UAAU,aAAa;IAC3B,OAAO,GAAG,OAAO,EAAE,kBAAkB,CAAC;AACxC,CAAC;AAkBD,MAAM,UAAU,cAAc,CAAC,IAA2B;IACxD,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACnC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IAClF,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,SAAS,SAAS,CAAC;IAClE,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;IAChF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,0EAA0E;IAC1E,gEAAgE;IAChE,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChF,MAAM,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,KAAK;YACT,IAAI,MAAM;gBAAE,OAAO;YACnB,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACjD,CAAC;QACD,KAAK;YACH,IAAI,MAAM;gBAAE,OAAO;YACnB,MAAM,GAAG,IAAI,CAAC;YACd,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/cli/spec.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Single source of truth for the CLI command schema. Used for:
+ *
+ *   - Runtime arg parsing (`parse.ts` consults this for option types
+ *     and required-ness).
+ *   - Schema introspection (`agent describe`, `agent schema`,
+ *     `--help --json` all surface this verbatim).
+ *   - Per-axis guarantees in the Agent DX CLI scale rubric:
+ *       axis 3 (schema introspection): every command + option is here.
+ *       axis 5 (input hardening): `validate` records the rules the
+ *         parser must enforce.
+ *       axis 6 (safety rails): the `mutating` flag marks where
+ *         `--dry-run` MUST be honored.
+ */
+export type OptionType = 'string' | 'number' | 'boolean' | 'string[]' | 'enum' | 'json' | 'path';
+export interface OptionSpec {
+    name: string;
+    short?: string;
+    type: OptionType;
+    description: string;
+    default?: string | number | boolean | null;
+    required?: boolean;
+    /** For type === 'enum' */
+    choices?: readonly string[];
+    /** Hardening rules for type === 'string' | 'path' */
+    validate?: {
+        rejectControlChars?: boolean;
+        rejectPathTraversal?: boolean;
+        rejectQueryChars?: boolean;
+        maxLength?: number;
+        pattern?: string;
+    };
+    /** When true, supplying this option is destructive — covered by --dry-run. */
+    mutating?: boolean;
+}
+export interface CommandSpec {
+    name: string;
+    description: string;
+    /** Whether this command can change side-effects (writes session log, runs LLM, etc). */
+    mutating: boolean;
+    options: readonly OptionSpec[];
+    /** Free-form positional after options; documented but not destructured. */
+    positional?: {
+        name: string;
+        description: string;
+    };
+    examples?: readonly {
+        input: string;
+        description: string;
+    }[];
+}
+export interface CliSpec {
+    name: string;
+    version: string;
+    description: string;
+    /** Global options that apply to every subcommand. */
+    globalOptions: readonly OptionSpec[];
+    commands: readonly CommandSpec[];
+}
+export declare const CLI_SPEC: CliSpec;
+export declare function findCommand(name: string): CommandSpec | undefined;
+//# sourceMappingURL=spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/cli/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjG,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,EAAE;QACT,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,QAAQ,CAAC,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9D;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,aAAa,EAAE,SAAS,UAAU,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAClC;AAoXD,eAAO,MAAM,QAAQ,EAAE,OAgKtB,CAAC;AAEF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEjE"}