agentplane 0.1.9 → 0.2.1

package/dist/cli/spec/docs-render.d.ts

@@ -0,0 +1,3 @@
+import type { HelpJson } from "./help-render.js";
+export declare function renderCliDocsMdx(specs: readonly HelpJson[]): string;
+//# sourceMappingURL=docs-render.d.ts.map

package/dist/cli/spec/docs-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-render.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/docs-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AA2BjD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAsGnE"}

package/dist/cli/spec/docs-render.js

@@ -0,0 +1,118 @@
+function escInline(text) {
+    return text.replaceAll("`", "\\`");
+}
+function toAnchor(text) {
+    return text
+        .toLowerCase()
+        .replaceAll(/[^a-z0-9]+/g, "-")
+        .replaceAll(/(^-|-$)/g, "");
+}
+function formatDefaultValue(value) {
+    if (value === undefined)
+        return "";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "bigint")
+        return value.toString();
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+export function renderCliDocsMdx(specs) {
+    const byGroup = new Map();
+    for (const s of specs) {
+        const g = s.group || "Other";
+        byGroup.set(g, [...(byGroup.get(g) ?? []), s]);
+    }
+    const groups = [...byGroup.keys()].toSorted((a, b) => a.localeCompare(b));
+    const groupEntries = groups.map((g) => ({
+        group: g,
+        specs: (byGroup.get(g) ?? []).toSorted((a, b) => a.id.join(" ").localeCompare(b.id.join(" "))),
+    }));
+    const indexLines = groupEntries.flatMap(({ group, specs }) => [
+        `- ${group}`,
+        ...specs.map((s) => {
+            const title = s.id.join(" ");
+            return `  - [${title}](#${toAnchor(title)})`;
+        }),
+    ]);
+    const bodyLines = groupEntries.flatMap(({ group, specs }) => {
+        const groupHeader = ["", `## ${group}`];
+        const commandBlocks = specs.flatMap((s) => {
+            const summaryLines = s.description
+                ? ["", escInline(s.summary), "", escInline(s.description)]
+                : ["", escInline(s.summary)];
+            const usageLines = ["", "Usage:", "", "```text", ...(s.usage ?? []), "```"];
+            const visibleOpts = (s.options ?? []).filter((o) => !o.hidden);
+            const optionLines = visibleOpts.length === 0
+                ? []
+                : [
+                    "",
+                    "Options:",
+                    "",
+                    ...visibleOpts.map((o) => {
+                        const short = o.short ? `-${o.short}, ` : "";
+                        const head = o.kind === "string"
+                            ? `${short}--${o.name} ${o.valueHint ?? "<value>"}`
+                            : `${short}--${o.name}`;
+                        const meta = [
+                            o.required ? "required" : null,
+                            o.repeatable ? "repeatable" : null,
+                            o.choices && o.choices.length > 0 ? `choices=${o.choices.join("|")}` : null,
+                            o.patternHint ? `format=${o.patternHint}` : null,
+                            o.default === undefined ? null : `default=${formatDefaultValue(o.default)}`,
+                            o.deprecated ? `deprecated=${o.deprecated}` : null,
+                        ].filter((x) => x !== null);
+                        const suffix = meta.length > 0 ? ` (${meta.join(", ")})` : "";
+                        return `- \`${escInline(head)}\`: ${escInline(o.description)}${escInline(suffix)}`;
+                    }),
+                ];
+            const notesLines = s.notes && s.notes.length > 0
+                ? ["", "Notes:", "", ...s.notes.map((n) => `- ${escInline(n)}`)]
+                : [];
+            const examplesLines = s.examples && s.examples.length > 0
+                ? [
+                    "",
+                    "Examples:",
+                    "",
+                    ...s.examples.flatMap((ex) => {
+                        const why = ex.why ? [`- ${escInline(ex.why)}`] : [];
+                        return ["```sh", ex.cmd, "```", ...why];
+                    }),
+                ]
+                : [];
+            return [
+                "",
+                `### ${s.id.join(" ")}`,
+                "",
+                ...summaryLines,
+                ...usageLines,
+                ...optionLines,
+                ...notesLines,
+                ...examplesLines,
+            ];
+        });
+        return [...groupHeader, ...commandBlocks];
+    });
+    const lines = [
+        "# CLI Reference (Generated)",
+        "",
+        "This page is generated from the CLI command specs. Do not edit it by hand; edit the specs instead.",
+        "",
+        "## Index",
+        "",
+        ...indexLines,
+        ...bodyLines,
+        "",
+    ];
+    return lines.join("\n");
+}

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

@@ -0,0 +1,9 @@
+import { CliError } from "../../shared/errors.js";
+import type { CommandSpec } from "./spec.js";
+export declare function usageError(opts: {
+    message: string;
+    spec?: CommandSpec<unknown>;
+    command?: string;
+    context?: Record<string, unknown>;
+}): CliError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7C,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,GAAG,QAAQ,CAgBX"}

package/dist/cli/spec/errors.js

@@ -0,0 +1,18 @@
+import { CliError } from "../../shared/errors.js";
+import { renderCommandHelpText } from "./help-render.js";
+export function usageError(opts) {
+    const command = opts.command ?? (opts.spec ? opts.spec.id.join(" ") : undefined);
+    const usage = opts.spec && renderCommandHelpText(opts.spec, { compact: true, includeHeader: false });
+    const fullMessage = usage ? `${opts.message}\n\n${usage}` : opts.message;
+    const context = {};
+    if (command)
+        context.command = command;
+    if (opts.context)
+        Object.assign(context, opts.context);
+    return new CliError({
+        exitCode: 2,
+        code: "E_USAGE",
+        message: fullMessage,
+        context: Object.keys(context).length > 0 ? context : undefined,
+    });
+}

package/dist/cli/spec/help-render.d.ts

@@ -0,0 +1,43 @@
+import type { CommandSpec } from "./spec.js";
+export type HelpJson = {
+    id: string[];
+    group: string;
+    summary: string;
+    description?: string;
+    usage: string[];
+    args: {
+        name: string;
+        required: boolean;
+        variadic?: boolean;
+        valueHint?: string;
+        description?: string;
+    }[];
+    options: {
+        name: string;
+        kind: "boolean" | "string";
+        short?: string;
+        description: string;
+        hidden?: boolean;
+        deprecated?: string;
+        required?: boolean;
+        repeatable?: boolean;
+        minCount?: number;
+        valueHint?: string;
+        default?: unknown;
+        choices?: string[];
+        patternHint?: string;
+    }[];
+    examples: {
+        cmd: string;
+        why?: string;
+    }[];
+    notes: string[];
+};
+export declare function renderUsageLines(spec: CommandSpec<unknown>): string[];
+export declare function renderCommandHelpText(spec: CommandSpec<unknown>, opts: {
+    compact: boolean;
+    includeHeader: boolean;
+}): string;
+export declare function renderCommandHelpJson(spec: CommandSpec<unknown>): HelpJson;
+export declare function renderRegistryHelpText(specs: readonly CommandSpec<unknown>[]): string;
+//# sourceMappingURL=help-render.d.ts.map

package/dist/cli/spec/help-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-render.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/help-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,WAAW,EAAiC,MAAM,WAAW,CAAC;AAErF,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,EAAE,CAAC;IACJ,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;QAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,EAAE,CAAC;IACJ,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAkBF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAkBrE;AAoDD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,EAC1B,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE,GACjD,MAAM,CA+BR;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,QAAQ,CAmD1E;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,WAAW,CAAC,OAAO,CAAC,EAAE,GAAG,MAAM,CAyBrF"}

package/dist/cli/spec/help-render.js

@@ -0,0 +1,185 @@
+function renderArgUsage(arg) {
+    const hint = arg.valueHint ?? `<${arg.name}>`;
+    const base = arg.variadic ? `${hint} ...` : hint;
+    return arg.required ? base : `[${base}]`;
+}
+function renderRequiredStringOptionUsage(opt) {
+    const long = `--${opt.name}`;
+    const hint = opt.valueHint;
+    if (opt.repeatable) {
+        const base = `${long} ${hint}`;
+        return `${base} [${base} ...]`;
+    }
+    return `${long} ${hint}`;
+}
+export function renderUsageLines(spec) {
+    if (spec.synopsis && spec.synopsis.length > 0)
+        return [...spec.synopsis];
+    const parts = ["agentplane", ...spec.id];
+    const args = spec.args ?? [];
+    for (const a of args)
+        parts.push(renderArgUsage(a));
+    const opts = (spec.options ?? []).filter((o) => !o.hidden);
+    const requiredOpts = opts.filter((o) => o.kind === "string" && o.required === true);
+    const optionalExists = opts.some((o) => !(o.kind === "string" && o.required));
+    // Show required options explicitly to reduce confusion.
+    for (const o of requiredOpts)
+        parts.push(renderRequiredStringOptionUsage(o));
+    if (optionalExists)
+        parts.push("[options]");
+    return [parts.join(" ")];
+}
+function renderOptionsLines(spec) {
+    const opts = (spec.options ?? []).filter((o) => !o.hidden);
+    if (opts.length === 0)
+        return [];
+    const lines = [];
+    for (const o of opts) {
+        const short = o.short ? `-${o.short}, ` : "";
+        let head = `  ${short}--${o.name}`;
+        if (o.kind === "string")
+            head += ` ${o.valueHint}`;
+        const meta = [];
+        if (o.kind === "string" && o.required)
+            meta.push("required");
+        if (o.kind === "string" && o.repeatable)
+            meta.push("repeatable");
+        if (o.kind === "string" && o.minCount && o.minCount > 0)
+            meta.push(`min=${o.minCount}`);
+        if (o.kind === "string" && o.choices && o.choices.length > 0)
+            meta.push(`choices=${o.choices.join("|")}`);
+        if (o.kind === "string" && o.patternHint)
+            meta.push(`format=${o.patternHint}`);
+        if (o.default !== undefined)
+            meta.push(`default=${String(o.default)}`);
+        if (o.deprecated)
+            meta.push(`deprecated=${o.deprecated}`);
+        const suffix = meta.length > 0 ? ` (${meta.join(", ")})` : "";
+        lines.push(`${head}  ${o.description}${suffix}`);
+    }
+    return lines;
+}
+function renderArgsLines(spec) {
+    const args = spec.args ?? [];
+    if (args.length === 0)
+        return [];
+    const lines = [];
+    for (const a of args) {
+        const hint = a.valueHint ?? `<${a.name}>`;
+        const req = a.required ? "required" : "optional";
+        const varSuffix = a.variadic ? ", variadic" : "";
+        const desc = a.description ? `  ${a.description}` : "";
+        lines.push(`  ${a.name} ${hint} (${req}${varSuffix})${desc}`);
+    }
+    return lines;
+}
+function renderExamplesLines(examples) {
+    if (!examples || examples.length === 0)
+        return [];
+    const lines = [];
+    for (const ex of examples) {
+        lines.push(`  ${ex.cmd}`);
+        if (ex.why)
+            lines.push(`    # ${ex.why}`);
+    }
+    return lines;
+}
+export function renderCommandHelpText(spec, opts) {
+    const lines = [];
+    if (opts.includeHeader) {
+        lines.push(`${spec.id.join(" ")} - ${spec.summary}`, "");
+    }
+    lines.push("Usage:");
+    for (const u of renderUsageLines(spec))
+        lines.push(`  ${u}`);
+    const argLines = renderArgsLines(spec);
+    if (!opts.compact && argLines.length > 0) {
+        lines.push("", "Args:", ...argLines);
+    }
+    const optLines = renderOptionsLines(spec);
+    if (optLines.length > 0) {
+        lines.push("", "Options:", ...optLines);
+    }
+    if (!opts.compact && spec.notes && spec.notes.length > 0) {
+        lines.push("", "Notes:", ...spec.notes.map((n) => `  - ${n}`));
+    }
+    if (!opts.compact) {
+        const exLines = renderExamplesLines(spec.examples);
+        if (exLines.length > 0) {
+            lines.push("", "Examples:", ...exLines);
+        }
+    }
+    return lines.join("\n");
+}
+export function renderCommandHelpJson(spec) {
+    const options = (spec.options ?? []).map((o) => {
+        if (o.kind === "boolean") {
+            return {
+                name: o.name,
+                kind: "boolean",
+                short: o.short,
+                description: o.description,
+                hidden: o.hidden,
+                deprecated: o.deprecated,
+                default: o.default,
+            };
+        }
+        return {
+            name: o.name,
+            kind: "string",
+            short: o.short,
+            description: o.description,
+            hidden: o.hidden,
+            deprecated: o.deprecated,
+            required: o.required,
+            repeatable: o.repeatable,
+            minCount: o.minCount,
+            valueHint: o.valueHint,
+            default: o.default,
+            choices: o.choices ? [...o.choices] : undefined,
+            patternHint: o.patternHint,
+        };
+    });
+    const args = (spec.args ?? []).map((a) => ({
+        name: a.name,
+        required: a.required,
+        variadic: a.variadic,
+        valueHint: a.valueHint,
+        description: a.description,
+    }));
+    const examples = (spec.examples ?? []).map((e) => ({ cmd: e.cmd, why: e.why }));
+    return {
+        id: [...spec.id],
+        group: spec.group,
+        summary: spec.summary,
+        description: spec.description,
+        usage: renderUsageLines(spec),
+        args,
+        options,
+        examples,
+        notes: spec.notes ? [...spec.notes] : [],
+    };
+}
+export function renderRegistryHelpText(specs) {
+    const byGroup = new Map();
+    for (const s of specs) {
+        const arr = byGroup.get(s.group) ?? [];
+        arr.push(s);
+        byGroup.set(s.group, arr);
+    }
+    const groups = [...byGroup.keys()].toSorted((a, b) => a.localeCompare(b));
+    const lines = [
+        "Usage:",
+        "  agentplane help [<cmd...>] [--compact] [--json]",
+        "",
+        "Commands:",
+    ];
+    for (const g of groups) {
+        lines.push(`  ${g}:`);
+        const cmds = byGroup.get(g).toSorted((a, b) => a.id.join(" ").localeCompare(b.id.join(" ")));
+        for (const s of cmds) {
+            lines.push(`    ${s.id.join(" ")}  ${s.summary}`);
+        }
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,10 @@
+import type { CommandHandler, CommandSpec } from "./spec.js";
+import type { CommandRegistry } from "./registry.js";
+export type HelpParsed = {
+    cmd: string[];
+    compact: boolean;
+    json: boolean;
+};
+export declare const helpSpec: CommandSpec<HelpParsed>;
+export declare function makeHelpHandler(registry: CommandRegistry): CommandHandler<HelpParsed>;
+//# sourceMappingURL=help.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAQ7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAwB5C,CAAC;AAEF,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAAC,UAAU,CAAC,CAuCrF"}

package/dist/cli/spec/help.js

@@ -0,0 +1,64 @@
+import { renderCommandHelpJson, renderCommandHelpText, renderRegistryHelpText, } from "./help-render.js";
+import { suggestOne } from "./suggest.js";
+import { usageError } from "./errors.js";
+export const helpSpec = {
+    id: ["help"],
+    group: "Core",
+    summary: "Show help for a command.",
+    description: "Renders spec-derived help for migrated commands. Use --compact for minimal output and --json for machine-readable help.",
+    args: [{ name: "cmd", required: false, variadic: true, valueHint: "<cmd>" }],
+    options: [
+        { kind: "boolean", name: "compact", description: "Compact help (usage + options)." },
+        { kind: "boolean", name: "json", description: "Emit JSON help (success output)." },
+    ],
+    examples: [
+        { cmd: "agentplane help", why: "List commands available in cli2 registry." },
+        { cmd: "agentplane help task new --compact", why: "Show compact help for a command." },
+        { cmd: "agentplane help task new --json", why: "Show JSON help for a command." },
+    ],
+    parse: (raw) => {
+        const cmd = raw.args.cmd ?? [];
+        return {
+            cmd: Array.isArray(cmd) ? cmd.map(String) : [String(cmd)],
+            compact: raw.opts.compact === true,
+            json: raw.opts.json === true,
+        };
+    },
+};
+export function makeHelpHandler(registry) {
+    return (_ctx, p) => {
+        const specs = registry.list().map((e) => e.spec);
+        if (p.cmd.length === 0) {
+            if (p.json) {
+                const out = specs.map((s) => renderCommandHelpJson(s));
+                process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`${renderRegistryHelpText(specs)}\n`);
+            }
+            return Promise.resolve(0);
+        }
+        const match = registry.match(p.cmd);
+        if (match?.consumed !== p.cmd.length) {
+            const input = p.cmd.join(" ");
+            const candidates = specs.map((s) => s.id.join(" "));
+            const suggestion = suggestOne(input, candidates);
+            const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
+            throw usageError({
+                spec: helpSpec,
+                command: "help",
+                message: `Unknown command: ${input}.${suffix}`,
+            });
+        }
+        if (p.json) {
+            process.stdout.write(`${JSON.stringify(renderCommandHelpJson(match.spec), null, 2)}\n`);
+            return Promise.resolve(0);
+        }
+        const text = renderCommandHelpText(match.spec, {
+            compact: p.compact,
+            includeHeader: true,
+        });
+        process.stdout.write(`${text}\n`);
+        return Promise.resolve(0);
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { CommandSpec, ParsedRaw } from "./spec.js";
+type ParsedCommand<TParsed> = {
+    raw: ParsedRaw;
+    parsed: TParsed;
+};
+export declare function parseCommandArgv<TParsed>(spec: CommandSpec<TParsed>, argv: readonly string[]): ParsedCommand<TParsed>;
+export {};
+//# sourceMappingURL=parse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../../src/cli/spec/parse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAc,SAAS,EAAE,MAAM,WAAW,CAAC;AAIpE,KAAK,aAAa,CAAC,OAAO,IAAI;IAC5B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AA6EF,wBAAgB,gBAAgB,CAAC,OAAO,EACtC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,EAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,aAAa,CAAC,OAAO,CAAC,CAiIxB"}

package/dist/cli/spec/parse.js

@@ -0,0 +1,188 @@
+import { suggestOne } from "./suggest.js";
+import { usageError } from "./errors.js";
+function isOptionToken(tok) {
+    return tok.startsWith("-") && tok !== "-";
+}
+function indexOptions(spec) {
+    const byLong = new Map();
+    const byShort = new Map();
+    const candidates = [];
+    for (const o of spec.options ?? []) {
+        byLong.set(`--${o.name}`, o);
+        candidates.push(`--${o.name}`);
+        if (o.short) {
+            byShort.set(`-${o.short}`, o);
+            candidates.push(`-${o.short}`);
+        }
+    }
+    return { byLong, byShort, candidates };
+}
+function setOpt(raw, opt, value) {
+    const key = opt.name;
+    if (opt.kind === "boolean") {
+        raw.opts[key] = Boolean(value);
+        return;
+    }
+    const coerced = opt.coerce ? opt.coerce(String(value)) : String(value);
+    if (opt.repeatable) {
+        const existing = raw.opts[key];
+        const arr = Array.isArray(existing) ? [...existing] : [];
+        if (Array.isArray(coerced)) {
+            for (const v of coerced)
+                arr.push(v);
+        }
+        else {
+            arr.push(coerced);
+        }
+        raw.opts[key] = arr;
+        return;
+    }
+    if (raw.opts[key] !== undefined) {
+        throw usageError({ message: `Duplicate option: --${key}` });
+    }
+    raw.opts[key] = coerced;
+}
+function validateOptValue(spec, opt, value) {
+    if (opt.kind !== "string")
+        return;
+    if (opt.choices && opt.choices.length > 0 && !opt.choices.includes(value)) {
+        throw usageError({
+            spec,
+            message: `Invalid value for --${opt.name}: ${value} (expected one of: ${opt.choices.join(", ")})`,
+        });
+    }
+    if (opt.pattern && !opt.pattern.test(value)) {
+        const hint = opt.patternHint ? ` (${opt.patternHint})` : "";
+        throw usageError({
+            spec,
+            message: `Invalid value for --${opt.name}: ${value}${hint}`,
+        });
+    }
+}
+function normalizeForValidation(opt, rawValue) {
+    if (opt.kind !== "string")
+        return rawValue;
+    if (!opt.coerce)
+        return rawValue;
+    const coerced = opt.coerce(rawValue);
+    return typeof coerced === "string" ? coerced : rawValue;
+}
+export function parseCommandArgv(spec, argv) {
+    const { byLong, byShort, candidates } = indexOptions(spec);
+    const raw = { args: {}, opts: {}, extra: [] };
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (!tok)
+            continue;
+        if (tok === "--") {
+            positionals.push(...argv.slice(i + 1).filter(Boolean));
+            break;
+        }
+        if (!isOptionToken(tok)) {
+            positionals.push(tok);
+            continue;
+        }
+        // Long options: --name or --name=value
+        if (tok.startsWith("--")) {
+            const eq = tok.indexOf("=");
+            const head = eq === -1 ? tok : tok.slice(0, eq);
+            const opt = byLong.get(head);
+            if (!opt) {
+                const sugg = suggestOne(head, candidates);
+                const suffix = sugg ? ` Did you mean ${sugg}?` : "";
+                throw usageError({ spec, message: `Unknown option: ${head}.${suffix}` });
+            }
+            if (opt.kind === "boolean") {
+                if (eq === -1) {
+                    setOpt(raw, opt, true);
+                    continue;
+                }
+                throw usageError({ spec, message: `Option ${head} does not take a value` });
+            }
+            const value = eq === -1 ? argv[i + 1] : tok.slice(eq + 1);
+            if (value === undefined || value === null || value === "") {
+                throw usageError({ spec, message: `Missing value after ${head}` });
+            }
+            const rawValue = String(value);
+            validateOptValue(spec, opt, normalizeForValidation(opt, rawValue));
+            setOpt(raw, opt, rawValue);
+            if (eq === -1)
+                i++;
+            continue;
+        }
+        // Short options: -m value (no grouping)
+        const opt = byShort.get(tok);
+        if (!opt) {
+            const sugg = suggestOne(tok, candidates);
+            const suffix = sugg ? ` Did you mean ${sugg}?` : "";
+            throw usageError({ spec, message: `Unknown option: ${tok}.${suffix}` });
+        }
+        if (opt.kind === "boolean") {
+            setOpt(raw, opt, true);
+            continue;
+        }
+        const value = argv[i + 1];
+        if (!value)
+            throw usageError({ spec, message: `Missing value after ${tok}` });
+        const rawValue = String(value);
+        validateOptValue(spec, opt, normalizeForValidation(opt, rawValue));
+        setOpt(raw, opt, rawValue);
+        i++;
+    }
+    // Apply defaults and validate required/minCount.
+    for (const o of spec.options ?? []) {
+        if (o.kind === "boolean") {
+            if (raw.opts[o.name] === undefined && o.default !== undefined)
+                raw.opts[o.name] = o.default;
+            continue;
+        }
+        if (raw.opts[o.name] === undefined && o.default !== undefined)
+            raw.opts[o.name] = o.default;
+        if (o.required === true && raw.opts[o.name] === undefined) {
+            throw usageError({ spec, message: `Missing required option: --${o.name}` });
+        }
+        if (o.repeatable && o.minCount && o.minCount > 0) {
+            const v = raw.opts[o.name];
+            const count = Array.isArray(v) ? v.length : 0;
+            if (count < o.minCount) {
+                throw usageError({
+                    spec,
+                    message: `Option --${o.name} must be provided at least ${o.minCount} time(s)`,
+                });
+            }
+        }
+    }
+    // Positional args.
+    let cursor = 0;
+    for (const a of spec.args ?? []) {
+        if (a.variadic) {
+            const rest = positionals.slice(cursor);
+            if (a.required && rest.length === 0) {
+                throw usageError({ spec, message: `Missing required argument: ${a.name}` });
+            }
+            raw.args[a.name] = rest;
+            cursor = positionals.length;
+            break;
+        }
+        const v = positionals[cursor];
+        if (v === undefined) {
+            if (a.required)
+                throw usageError({ spec, message: `Missing required argument: ${a.name}` });
+            raw.args[a.name] = undefined;
+            continue;
+        }
+        raw.args[a.name] = v;
+        cursor++;
+    }
+    raw.extra = positionals.slice(cursor);
+    if (raw.extra.length > 0) {
+        throw usageError({ spec, message: `Unexpected argument: ${raw.extra[0]}` });
+    }
+    if (spec.validateRaw)
+        spec.validateRaw(raw);
+    const parsed = spec.parse ? spec.parse(raw) : raw.opts;
+    if (spec.validate)
+        spec.validate(parsed);
+    return { raw, parsed };
+}