@lingjingai/scriptctl 0.1.0 → 0.3.0

package/dist/cli.js

@@ -1,433 +1,346 @@
+import { Command, CommanderError } from "commander";
 import { CliError, EXIT_OK, EXIT_USAGE } from "./common.js";
 import { getHelp } from "./help-text.js";
 import { loadLocalEnv } from "./infra/env.js";
 import { emit, emitError } from "./output.js";
 import { commandInit, commandInspect, commandValidate, } from "./usecases/direct.js";
 import { commandDoctor } from "./usecases/doctor.js";
+import { commandEpisodeBatch, commandEpisodeDraft, commandEpisodeInit, commandEpisodeMerge, commandEpisodePush, commandEpisodeSpec, commandEpisodeWorkspace, } from "./usecases/episode.js";
 import { commandExport, commandScriptAction, commandScriptContext, commandScriptDialogue, commandScriptInspect, commandScriptPatch, commandScriptSpeaker, commandScriptState, commandScriptValidate, } from "./usecases/script.js";
-const SCRIPT_NESTED_GROUPS = new Set(["state", "context", "action", "speaker", "dialogue"]);
-const NESTED_COMMANDS = new Set([
-    "script.state.add",
-    "script.state.rename",
-    "script.state.describe",
-    "script.state.refs",
-    "script.state.delete-plan",
-    "script.state.delete-apply",
-    "script.context.set",
-    "script.context.clear",
-    "script.action.state-change",
-    "script.action.state-remove",
-    "script.action.transition-set",
-    "script.action.transition-clear",
-    "script.speaker.add",
-    "script.dialogue.speakers",
-    "script.dialogue.overlap",
+const KNOWN_COMMANDS = new Set([
+    "doctor",
+    "direct", "direct.init", "direct.validate", "direct.inspect", "direct.export",
+    "script", "script.inspect", "script.validate", "script.patch",
+    "script.state", "script.state.add", "script.state.rename", "script.state.describe",
+    "script.state.refs", "script.state.delete-plan", "script.state.delete-apply",
+    "script.context", "script.context.set", "script.context.clear",
+    "script.action", "script.action.state-change", "script.action.state-remove",
+    "script.action.transition-set", "script.action.transition-clear",
+    "script.speaker", "script.speaker.add",
+    "script.dialogue", "script.dialogue.speakers", "script.dialogue.overlap",
+    "episode", "episode.init", "episode.draft", "episode.batch", "episode.workspace", "episode.merge", "episode.push", "episode.spec",
 ]);
-function key(command) {
-    return command.join(".");
-}
-function parseOptions(command, argv) {
-    const opts = {};
-    const positionals = [];
-    let jsonMode = false;
-    const specs = optionSpecs(command);
-    const flagSet = new Set(specs.flags);
-    const arraySet = new Set(specs.arrays);
-    const valueSet = new Set(specs.values);
-    let i = 0;
-    while (i < argv.length) {
-        const token = argv[i];
-        if (token === "--json") {
-            jsonMode = true;
-            i += 1;
-            continue;
-        }
-        if (token.startsWith("--")) {
-            const eqIdx = token.indexOf("=");
-            const rawName = eqIdx >= 0 ? token.slice(2, eqIdx) : token.slice(2);
-            const camel = rawName.replace(/-/g, "_");
-            const name = aliasRename(camel);
-            if (flagSet.has(name)) {
-                opts[name] = true;
-                i += 1;
-                continue;
-            }
-            let value;
-            if (eqIdx >= 0) {
-                value = token.slice(eqIdx + 1);
-                i += 1;
-            }
-            else {
-                if (i + 1 >= argv.length) {
-                    throw new CliError("USAGE ERROR: Invalid arguments", "Invalid arguments.", {
-                        exitCode: EXIT_USAGE,
-                        required: [`Run: scriptctl ${command.join(" ")} --help`],
-                        received: [`option --${rawName} requires a value`],
-                        nextSteps: [`Run: scriptctl ${command.join(" ")} --help`],
-                    });
-                }
-                value = argv[i + 1];
-                i += 2;
-            }
-            if (arraySet.has(name)) {
-                if (!Array.isArray(opts[name]))
-                    opts[name] = [];
-                opts[name].push(value);
-            }
-            else if (valueSet.has(name)) {
-                opts[name] = value;
-            }
-            else {
-                // Allow unknown options for forward-compat but record verbatim
-                opts[name] = value;
-            }
-            continue;
-        }
-        positionals.push(token);
-        i += 1;
+// Groups are command nodes that exist only to host subcommands. Extra non-flag tokens
+// after a group path indicate an unknown subcommand (e.g. `direct nope` → error).
+// Leaves are real commands that can accept positional arguments (e.g. `episode draft <n>`).
+const GROUP_COMMANDS = new Set([
+    "direct",
+    "script",
+    "script.state",
+    "script.context",
+    "script.action",
+    "script.speaker",
+    "script.dialogue",
+    "episode",
+]);
+function extractLeadingPath(args) {
+    // Collect leading non-flag tokens, then take only as many as form the longest known
+    // command prefix. Trailing tokens are treated as either:
+    //   - positional arguments (when the matched node is a leaf, e.g. `episode draft 1`)
+    //   - unknown subcommands (when the matched node is a group, e.g. `direct nope`)
+    const allNonFlag = [];
+    for (const tok of args) {
+        if (tok.startsWith("-"))
+            break;
+        allNonFlag.push(tok);
+        if (allNonFlag.length >= 5)
+            break;
     }
-    if (specs.acceptsPositionals)
-        opts["_args"] = positionals;
-    // Validate required
-    for (const required of specs.required) {
-        if (!(required in opts)) {
-            throw new CliError("USAGE ERROR: Invalid arguments", "Invalid arguments.", {
-                exitCode: EXIT_USAGE,
-                required: [`Run: scriptctl ${command.join(" ")} --help`],
-                received: [`missing --${required.replace(/_/g, "-")}`],
-                nextSteps: [`Run: scriptctl ${command.join(" ")} --help`],
-            });
-        }
+    const matchLen = longestKnownPrefix(allNonFlag);
+    if (matchLen === 0) {
+        // No known command at all — return up to 3 tokens for a readable error.
+        return allNonFlag.slice(0, 3);
     }
-    // Apply defaults
-    for (const [k, v] of Object.entries(specs.defaults)) {
-        if (!(k in opts))
-            opts[k] = v;
+    const matchedKey = allNonFlag.slice(0, matchLen).join(".");
+    const isGroup = GROUP_COMMANDS.has(matchedKey);
+    if (isGroup && allNonFlag.length > matchLen) {
+        // Group + extra tokens = unknown subcommand. Return the truncated path so the
+        // validator (knownLen < cmdPath.length) reports an error.
+        return allNonFlag.slice(0, Math.min(allNonFlag.length, 3));
     }
-    return { opts, jsonMode };
-}
-function aliasRename(camel) {
-    // argparse used dest="from"; we keep TS field also "from"
-    return camel;
+    return allNonFlag.slice(0, matchLen);
 }
-function optionSpecs(command) {
-    const k = key(command);
-    if (k === "direct.init") {
-        return {
-            flags: [],
-            values: ["source_path", "workspace_path", "provider", "model", "concurrency", "batch_mode", "batch_target_lines", "batch_max_chars", "batch_min_lines"],
-            arrays: [],
-            required: ["source_path"],
-            defaults: { workspace_path: "workspace", provider: "anthropic", concurrency: "30", batch_mode: "episode", batch_target_lines: "36", batch_max_chars: "1800", batch_min_lines: "12" },
-            acceptsPositionals: false,
-        };
-    }
-    if (k === "direct.validate") {
-        return {
-            flags: [],
-            values: ["workspace_path", "script_path"],
-            arrays: [],
-            required: [],
-            defaults: { workspace_path: "workspace" },
-            acceptsPositionals: false,
-        };
-    }
-    if (k === "direct.inspect") {
-        return {
-            flags: [],
-            values: ["workspace_path", "target", "id", "episode"],
-            arrays: [],
-            required: ["target"],
-            defaults: { workspace_path: "workspace" },
-            acceptsPositionals: false,
-        };
-    }
-    if (k === "direct.export") {
-        return {
-            flags: ["force"],
-            values: ["workspace_path", "output_path", "project_group_no", "request_id"],
-            arrays: [],
-            required: [],
-            defaults: { workspace_path: "workspace", output_path: "output" },
-            acceptsPositionals: false,
-        };
-    }
-    if (k === "script.inspect") {
-        return {
-            flags: [],
-            values: ["script_path", "workspace_path", "project_group_no", "target", "id"],
-            arrays: [],
-            required: [],
-            defaults: { workspace_path: "workspace", target: "summary" },
-            acceptsPositionals: false,
-        };
-    }
-    if (k === "script.validate") {
-        return {
-            flags: [],
-            values: ["script_path", "workspace_path", "project_group_no"],
-            arrays: [],
-            required: [],
-            defaults: { workspace_path: "workspace" },
-            acceptsPositionals: false,
-        };
-    }
-    if (k === "script.patch") {
-        return {
-            flags: [],
-            values: ["script_path", "workspace_path", "project_group_no", "request_id", "patch"],
-            arrays: [],
-            required: ["patch"],
-            defaults: { workspace_path: "workspace" },
-            acceptsPositionals: false,
-        };
-    }
-    if (k.startsWith("script.state.")) {
-        const sub = command[2];
-        const values = ["script_path", "workspace_path", "project_group_no", "request_id"];
-        const required = [];
-        const defaults = { workspace_path: "workspace" };
-        if (sub === "add" || sub === "rename") {
-            values.push("name");
-            required.push("name");
-        }
-        if (sub === "describe") {
-            values.push("description");
-            required.push("description");
-        }
-        if (sub === "add") {
-            values.push("description", "state_id");
-            defaults["description"] = "";
-        }
-        if (sub === "delete-apply") {
-            values.push("strategy", "replacement");
-            required.push("strategy");
-        }
-        return { flags: [], values, arrays: [], required, defaults, acceptsPositionals: true };
-    }
-    if (k.startsWith("script.context.")) {
-        const sub = command[2];
-        const values = ["script_path", "workspace_path", "project_group_no", "request_id"];
-        const required = [];
-        if (sub === "set") {
-            values.push("state");
-            required.push("state");
-        }
-        return {
-            flags: [],
-            values,
-            arrays: [],
-            required,
-            defaults: { workspace_path: "workspace" },
-            acceptsPositionals: true,
-        };
-    }
-    if (k.startsWith("script.action.")) {
-        const sub = command[2];
-        const values = ["script_path", "workspace_path", "project_group_no", "request_id"];
-        const required = [];
-        const defaults = { workspace_path: "workspace" };
-        if (sub === "state-change") {
-            values.push("to", "from", "effective");
-            required.push("to");
-            defaults["effective"] = "after";
-        }
-        if (sub === "transition-set") {
-            values.push("process", "contrast");
-            required.push("process", "contrast");
-        }
-        return { flags: [], values, arrays: [], required, defaults, acceptsPositionals: true };
-    }
-    if (k === "script.speaker.add") {
-        return {
-            flags: [],
-            values: ["script_path", "workspace_path", "project_group_no", "request_id", "kind", "name", "source_id", "voice_desc", "speaker_id"],
-            arrays: [],
-            required: ["kind", "name"],
-            defaults: { workspace_path: "workspace", voice_desc: "" },
-            acceptsPositionals: true,
-        };
-    }
-    if (k === "script.dialogue.speakers") {
-        return {
-            flags: [],
-            values: ["script_path", "workspace_path", "project_group_no", "request_id", "delivery"],
-            arrays: ["speaker"],
-            required: [],
-            defaults: { workspace_path: "workspace", delivery: "simultaneous" },
-            acceptsPositionals: true,
-        };
+function longestKnownPrefix(path) {
+    for (let len = path.length; len > 0; len--) {
+        if (KNOWN_COMMANDS.has(path.slice(0, len).join(".")))
+            return len;
     }
-    if (k === "script.dialogue.overlap") {
-        return {
-            flags: [],
-            values: ["script_path", "workspace_path", "project_group_no", "request_id"],
-            arrays: ["line"],
-            required: [],
-            defaults: { workspace_path: "workspace" },
-            acceptsPositionals: true,
-        };
+    return 0;
+}
+function commandPath(cmd) {
+    const parts = [];
+    let c = cmd;
+    while (c) {
+        const name = c.name();
+        if (!name || name === "scriptctl")
+            break;
+        parts.unshift(name);
+        c = c.parent;
     }
-    return {
-        flags: [],
-        values: ["script_path", "workspace_path", "project_group_no", "request_id"],
-        arrays: [],
-        required: [],
-        defaults: { workspace_path: "workspace" },
-        acceptsPositionals: true,
+    return parts;
+}
+function camelToSnake(s) {
+    return s.replace(/([A-Z])/g, "_$1").toLowerCase();
+}
+function normalizeOpts(opts) {
+    const out = {};
+    for (const [k, v] of Object.entries(opts))
+        out[camelToSnake(k)] = v;
+    return out;
+}
+function dispatch(handler, state) {
+    return async (...args) => {
+        const cmd = args[args.length - 1];
+        const positionals = args.slice(0, -2).filter((p) => p !== undefined);
+        const normalized = normalizeOpts(cmd.opts());
+        if (positionals.length > 0)
+            normalized._args = positionals;
+        const [report, exitCode] = await handler(normalized);
+        emit(report, exitCode, state.jsonMode);
+        state.exitCode = exitCode;
     };
 }
-function resolveCommand(argv) {
-    if (argv.length === 0)
-        return null;
-    if (argv[0] === "doctor")
-        return { command: ["doctor"], rest: argv.slice(1) };
-    if (argv[0] !== "direct" && argv[0] !== "script")
-        return null;
-    const group = argv[0];
-    if (argv.length < 2)
-        return { command: [group], rest: [] };
-    if (argv[1] === "--help" || argv[1] === "-h")
-        return { command: [group], rest: [] };
-    if (group === "script" && SCRIPT_NESTED_GROUPS.has(argv[1])) {
-        if (argv.length < 3 || argv[2] === "--help" || argv[2] === "-h") {
-            return { command: ["script", argv[1]], rest: [] };
-        }
-        return { command: ["script", argv[1], argv[2]], rest: argv.slice(3) };
-    }
-    return { command: [group, argv[1]], rest: argv.slice(2) };
+function showGroupHelp(commandPathParts, state) {
+    return () => {
+        process.stdout.write(getHelp(commandPathParts) ?? getHelp([]) ?? "");
+        state.exitCode = EXIT_OK;
+    };
 }
-function unknownCommandError(argv, jsonMode) {
-    const received = argv.length > 0 ? argv[0] : "<empty>";
-    return emitError(new CliError("USAGE ERROR: Unknown command group", "Unknown command group.", {
-        exitCode: EXIT_USAGE,
-        required: ["doctor, direct, or script"],
-        received: [received],
-        nextSteps: ["Run: scriptctl --help"],
-    }), jsonMode);
+const appendStr = (value, prev) => [...prev, value];
+function withScriptOpts(cmd) {
+    return cmd
+        .option("--script-path <path>")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--project-group-no <no>")
+        .option("--request-id <id>");
+}
+function buildProgram(state) {
+    const program = new Command("scriptctl")
+        .exitOverride()
+        .allowExcessArguments(false)
+        .allowUnknownOption(false)
+        .configureOutput({
+        writeOut: (str) => process.stdout.write(str),
+        writeErr: () => {
+            /* swallowed; we emit our own envelope */
+        },
+    })
+        .configureHelp({
+        formatHelp: (cmd) => getHelp(commandPath(cmd)) ?? getHelp([]) ?? "",
+    });
+    program.command("doctor").action(dispatch((o) => commandDoctor(o), state));
+    // ============================== direct ==============================
+    const direct = program.command("direct").action(showGroupHelp(["direct"], state));
+    direct.command("init")
+        .requiredOption("--source-path <path>")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--provider <name>", "", "anthropic")
+        .option("--model <model>")
+        .option("--concurrency <n>", "", "30")
+        .option("--batch-mode <mode>", "", "episode")
+        .option("--batch-target-lines <n>", "", "36")
+        .option("--batch-max-chars <n>", "", "1800")
+        .option("--batch-min-lines <n>", "", "12")
+        .action(dispatch(commandInit, state));
+    direct.command("validate")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--script-path <path>")
+        .action(dispatch((o) => commandValidate(o), state));
+    direct.command("inspect")
+        .requiredOption("--target <target>")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--id <id>")
+        .option("--episode <e>")
+        .action(dispatch((o) => commandInspect(o), state));
+    direct.command("export")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--output-path <path>", "", "output")
+        .option("--project-group-no <no>")
+        .option("--request-id <id>")
+        .option("--force")
+        .action(dispatch(commandExport, state));
+    // ============================== script ==============================
+    const script = program.command("script").action(showGroupHelp(["script"], state));
+    withScriptOpts(script.command("inspect"))
+        .option("--target <target>", "", "summary")
+        .option("--id <id>")
+        .option("--min-chars <n>")
+        .option("--max-chars <n>")
+        .action(dispatch(commandScriptInspect, state));
+    withScriptOpts(script.command("validate")).action(dispatch(commandScriptValidate, state));
+    withScriptOpts(script.command("patch"))
+        .requiredOption("--patch <file>")
+        .action(dispatch(commandScriptPatch, state));
+    // ------- script state -------
+    const scriptState = script.command("state").action(showGroupHelp(["script", "state"], state));
+    withScriptOpts(scriptState.command("add <target>"))
+        .requiredOption("--name <name>")
+        .option("--description <text>", "", "")
+        .option("--state-id <id>")
+        .action(dispatch((o) => commandScriptState(o, "add"), state));
+    withScriptOpts(scriptState.command("rename <target>"))
+        .requiredOption("--name <name>")
+        .action(dispatch((o) => commandScriptState(o, "rename"), state));
+    withScriptOpts(scriptState.command("describe <target>"))
+        .requiredOption("--description <text>")
+        .action(dispatch((o) => commandScriptState(o, "describe"), state));
+    withScriptOpts(scriptState.command("refs <target>"))
+        .action(dispatch((o) => commandScriptState(o, "refs"), state));
+    withScriptOpts(scriptState.command("delete-plan <target>"))
+        .action(dispatch((o) => commandScriptState(o, "delete-plan"), state));
+    withScriptOpts(scriptState.command("delete-apply <target>"))
+        .requiredOption("--strategy <strategy>")
+        .option("--replacement <id>")
+        .action(dispatch((o) => commandScriptState(o, "delete-apply"), state));
+    // ------- script context -------
+    const scriptContext = script.command("context").action(showGroupHelp(["script", "context"], state));
+    withScriptOpts(scriptContext.command("set <at> <target>"))
+        .requiredOption("--state <id>")
+        .action(dispatch((o) => commandScriptContext(o, "set"), state));
+    withScriptOpts(scriptContext.command("clear <at> <target>"))
+        .action(dispatch((o) => commandScriptContext(o, "clear"), state));
+    // ------- script action -------
+    const scriptAction = script.command("action").action(showGroupHelp(["script", "action"], state));
+    withScriptOpts(scriptAction.command("state-change <at> <target>"))
+        .requiredOption("--to <id>")
+        .option("--from <id>")
+        .option("--effective <when>", "", "after")
+        .action(dispatch((o) => commandScriptAction(o, "state-change"), state));
+    withScriptOpts(scriptAction.command("state-remove <at> <target>"))
+        .action(dispatch((o) => commandScriptAction(o, "state-remove"), state));
+    withScriptOpts(scriptAction.command("transition-set <at> <target>"))
+        .requiredOption("--process <text>")
+        .requiredOption("--contrast <text>")
+        .action(dispatch((o) => commandScriptAction(o, "transition-set"), state));
+    withScriptOpts(scriptAction.command("transition-clear <at> <target>"))
+        .action(dispatch((o) => commandScriptAction(o, "transition-clear"), state));
+    // ------- script speaker -------
+    const scriptSpeaker = script.command("speaker").action(showGroupHelp(["script", "speaker"], state));
+    withScriptOpts(scriptSpeaker.command("add"))
+        .requiredOption("--kind <kind>")
+        .requiredOption("--name <name>")
+        .option("--source-id <id>")
+        .option("--voice-desc <text>", "", "")
+        .option("--speaker-id <id>")
+        .action(dispatch((o) => commandScriptSpeaker(o, "add"), state));
+    // ------- script dialogue -------
+    const scriptDialogue = script.command("dialogue").action(showGroupHelp(["script", "dialogue"], state));
+    withScriptOpts(scriptDialogue.command("speakers <at>"))
+        .option("--speaker <id>", "", appendStr, [])
+        .option("--delivery <mode>", "", "simultaneous")
+        .action(dispatch((o) => commandScriptDialogue(o, "speakers"), state));
+    withScriptOpts(scriptDialogue.command("overlap <at>"))
+        .option("--line <spec>", "", appendStr, [])
+        .action(dispatch((o) => commandScriptDialogue(o, "overlap"), state));
+    // ============================== episode ==============================
+    const episode = program.command("episode").action(showGroupHelp(["episode"], state));
+    episode.command("init")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--force")
+        .action(dispatch((o) => commandEpisodeInit(o), state));
+    episode.command("draft <n>")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--prompt-template <path>")
+        .option("--outline <path>")
+        .option("--ref <spec>", "", appendStr, [])
+        .option("--from-md <path>")
+        .option("--provider <name>")
+        .option("--model <model>")
+        .option("--max-tokens <n>")
+        .option("--regen")
+        .option("--resume")
+        .action(dispatch((o) => commandEpisodeDraft(o), state));
+    episode.command("batch")
+        .requiredOption("--range <a-b>")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--prompt-template <path>")
+        .option("--outline <path>")
+        .option("--ref <spec>", "", appendStr, [])
+        .option("--provider <name>")
+        .option("--model <model>")
+        .option("--max-tokens <n>")
+        .action(dispatch((o) => commandEpisodeBatch(o), state));
+    episode.command("workspace")
+        .option("--workspace-path <path>", "", "workspace")
+        .action(dispatch((o) => commandEpisodeWorkspace(o), state));
+    episode.command("merge")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--meta-path <path>")
+        .option("--from <n>")
+        .option("--to <n>")
+        .option("--force")
+        .action(dispatch((o) => commandEpisodeMerge(o), state));
+    episode.command("push")
+        .option("--workspace-path <path>", "", "workspace")
+        .option("--project-group-no <no>")
+        .option("--request-id <id>")
+        .action(dispatch((o) => commandEpisodePush(o), state));
+    episode.command("spec")
+        .action(dispatch((o) => commandEpisodeSpec(o), state));
+    return program;
 }
-const TOP_LEVEL_GROUPS_WITHOUT_SUB = new Set([
-    "direct",
-    "script",
-    "script.state",
-    "script.context",
-    "script.action",
-    "script.speaker",
-    "script.dialogue",
-]);
 export async function main(argv = null) {
     loadLocalEnv();
-    const argsAll = argv ?? process.argv.slice(2);
-    let jsonMode = argsAll.includes("--json");
-    const args = argsAll.filter((a) => a !== "--json");
-    if (args.length === 0 || (args.length === 1 && (args[0] === "--help" || args[0] === "-h"))) {
-        process.stdout.write(getHelp([]) ?? "");
-        return EXIT_OK;
-    }
-    const resolved = resolveCommand(args);
-    if (resolved === null)
-        return unknownCommandError(args, jsonMode);
-    const { command, rest } = resolved;
-    const cmdKey = key(command);
-    if (TOP_LEVEL_GROUPS_WITHOUT_SUB.has(cmdKey)) {
-        if (rest.length === 0 || rest[0] === "--help" || rest[0] === "-h") {
-            process.stdout.write(getHelp(command) ?? "");
+    let args = argv ?? process.argv.slice(2);
+    const state = { jsonMode: args.includes("--json"), exitCode: EXIT_OK };
+    args = args.filter((a) => a !== "--json");
+    const wantsHelp = args.includes("--help") || args.includes("-h");
+    const cmdPath = extractLeadingPath(args);
+    if (cmdPath.length === 0) {
+        if (args.length === 0 || wantsHelp) {
+            process.stdout.write(getHelp([]) ?? "");
             return EXIT_OK;
         }
+        return emitError(new CliError("USAGE ERROR: Unknown command", "Unknown command.", {
+            exitCode: EXIT_USAGE,
+            required: ["valid scriptctl command"],
+            received: [args.join(" ") || "<empty>"],
+            nextSteps: ["Run: scriptctl --help"],
+        }), state.jsonMode);
     }
-    if (cmdKey === "doctor") {
-        if (rest.length > 0 && (rest[0] === "--help" || rest[0] === "-h")) {
-            process.stdout.write(getHelp(["doctor"]) ?? "");
-            return EXIT_OK;
-        }
-        const [report, exitCode] = commandDoctor({});
-        emit(report, exitCode, jsonMode);
-        return exitCode;
-    }
-    // Validate command is recognized
-    const helpExists = getHelp(command) !== undefined;
-    if (!helpExists && !NESTED_COMMANDS.has(cmdKey)) {
-        const required = command[0] === "direct"
-            ? ["init, validate, inspect, export"]
-            : ["inspect, validate, patch, state, context, action, speaker, dialogue"];
-        return emitError(new CliError(`USAGE ERROR: Unknown ${command[0]} command`, "Unknown command.", {
+    const knownLen = longestKnownPrefix(cmdPath);
+    if (knownLen < cmdPath.length) {
+        return emitError(new CliError("USAGE ERROR: Unknown command", "Unknown command.", {
             exitCode: EXIT_USAGE,
-            required,
-            received: [command.join(" ")],
-            nextSteps: [`Run: scriptctl ${command[0]} --help`],
-        }), jsonMode);
+            required: ["valid scriptctl command"],
+            received: [cmdPath.join(" ")],
+            nextSteps: ["Run: scriptctl --help"],
+        }), state.jsonMode);
     }
-    if (rest.includes("--help") || rest.includes("-h")) {
-        let helpText = getHelp(command);
-        if (helpText === undefined && command.length >= 2) {
-            helpText = getHelp(command.slice(0, 2));
-        }
-        if (helpText === undefined)
-            helpText = getHelp([]) ?? "";
-        process.stdout.write(helpText);
+    if (wantsHelp) {
+        process.stdout.write(getHelp(cmdPath) ?? getHelp([]) ?? "");
         return EXIT_OK;
     }
+    const program = buildProgram(state);
     try {
-        const parsed = parseOptions(command, rest);
-        if (parsed.jsonMode)
-            jsonMode = true;
-        const handler = pickHandler(command);
-        if (!handler) {
-            throw new CliError("USAGE ERROR: Handler missing", "Handler missing.", {
+        await program.parseAsync(args, { from: "user" });
+        return state.exitCode;
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            const code = err.code;
+            if (code === "commander.help" ||
+                code === "commander.helpDisplayed" ||
+                code === "commander.version") {
+                return EXIT_OK;
+            }
+            const message = err.message || "Invalid arguments.";
+            return emitError(new CliError("USAGE ERROR: Invalid arguments", "Invalid arguments.", {
                 exitCode: EXIT_USAGE,
-                required: ["supported command"],
-                received: [command.join(" ")],
-                nextSteps: ["Run scriptctl --help"],
-            });
+                required: ["Run: scriptctl --help"],
+                received: [message],
+                nextSteps: ["Run: scriptctl --help"],
+            }), state.jsonMode);
         }
-        const result = await handler(parsed.opts);
-        const [report, exitCode] = result;
-        emit(report, exitCode, jsonMode);
-        return exitCode;
-    }
-    catch (exc) {
-        if (exc instanceof CliError)
-            return emitError(exc, jsonMode);
-        const err = exc;
+        if (err instanceof CliError)
+            return emitError(err, state.jsonMode);
+        const e = err;
         return emitError(new CliError("RUNTIME FAILED: Unexpected error", "Unexpected error.", {
             exitCode: 70,
             required: ["successful command execution"],
-            received: [err?.name ?? "Error"],
+            received: [e?.name ?? "Error"],
             nextSteps: ["Rerun with valid inputs or inspect workspace artifacts."],
-        }), jsonMode);
-    }
-}
-function pickHandler(command) {
-    const k = key(command);
-    if (k === "direct.init")
-        return commandInit;
-    if (k === "direct.validate")
-        return (opts) => commandValidate(opts);
-    if (k === "direct.inspect")
-        return (opts) => commandInspect(opts);
-    if (k === "direct.export")
-        return commandExport;
-    if (k === "script.inspect")
-        return commandScriptInspect;
-    if (k === "script.validate")
-        return commandScriptValidate;
-    if (k === "script.patch")
-        return commandScriptPatch;
-    if (command.length === 3 && command[0] === "script" && command[1] === "state") {
-        return (opts) => commandScriptState(opts, command[2]);
-    }
-    if (command.length === 3 && command[0] === "script" && command[1] === "context") {
-        return (opts) => commandScriptContext(opts, command[2]);
-    }
-    if (command.length === 3 && command[0] === "script" && command[1] === "action") {
-        return (opts) => commandScriptAction(opts, command[2]);
-    }
-    if (command.length === 3 && command[0] === "script" && command[1] === "speaker") {
-        return (opts) => commandScriptSpeaker(opts, command[2]);
-    }
-    if (command.length === 3 && command[0] === "script" && command[1] === "dialogue") {
-        return (opts) => commandScriptDialogue(opts, command[2]);
+        }), state.jsonMode);
     }
-    return null;
 }
 //# sourceMappingURL=cli.js.map