@lingjingai/scriptctl 0.49.16 → 0.51.0

package/dist/cli.js

@@ -2,614 +2,185 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command, CommanderError } from "commander";
-import { CliError, EXIT_OK, EXIT_USAGE, scriptJsonPath } from "./common.js";
-import { getHelp } from "./help-text.js";
+import { CliError, EXIT_OK, EXIT_USAGE } from "./common.js";
+import { registerBatchCommands } from "./cli/register-batch.js";
+import { registerEditCommands } from "./cli/register-edits.js";
+import { registerQueryCommands } from "./cli/register-query.js";
+import { registerToolCommands } from "./cli/register-tools.js";
+import { registerWorkflowCommands } from "./cli/register-workflows.js";
 import { loadLocalEnv } from "./infra/env.js";
-import { emit, emitError } from "./output.js";
 import { PRODUCTION_LLM_COMPOSITION } from "./llm/composition.js";
-import { commandIngest } from "./usecases/ingest/command.js";
-import { commandIngestStatus } from "./usecases/ingest/status.js";
-import { commandView } from "./usecases/ingest/view-command.js";
-import { withScriptFileLock } from "./infra/script-working-copy.js";
-import { commandDoctor } from "./usecases/doctor.js";
-import { commandUpdate } from "./usecases/update.js";
-import { commandChangelog } from "./usecases/changelog.js";
-import { commandActions } from "./usecases/script/actions.js";
-import { commandActor } from "./usecases/script/actor.js";
-import { commandActors } from "./usecases/script/actors.js";
-import { commandAddEpisode } from "./usecases/script/add-episode.js";
-import { commandAddLocation } from "./usecases/script/add-location.js";
-import { commandAddProp } from "./usecases/script/add-prop.js";
-import { commandAddActor } from "./usecases/script/add-actor.js";
-import { commandAlias } from "./usecases/script/alias.js";
-import { commandAssets } from "./usecases/script/assets.js";
-import { commandContext } from "./usecases/script/context.js";
-import { commandCreate } from "./usecases/script/create.js";
-import { commandDelete } from "./usecases/script/delete.js";
-import { commandDescribe } from "./usecases/script/describe.js";
-import { commandExtend } from "./usecases/script/extend.js";
-import { commandDialogue } from "./usecases/script/dialogue.js";
-import { commandImportance } from "./usecases/script/importance.js";
-import { commandDo } from "./usecases/script/do.js";
-import { commandEmotion } from "./usecases/script/emotion.js";
-import { commandEpisodes } from "./usecases/script/episodes.js";
-import { commandInsert } from "./usecases/script/insert.js";
-import { commandIssues } from "./usecases/script/issues.js";
-import { commandLocations } from "./usecases/script/locations.js";
-import { commandMerge } from "./usecases/script/merge.js";
-import { commandMove } from "./usecases/script/move.js";
-import { commandProps } from "./usecases/script/props.js";
-import { commandRefs } from "./usecases/script/refs.js";
-import { commandRename } from "./usecases/script/rename.js";
-import { commandReplace } from "./usecases/script/replace.js";
-import { commandRole } from "./usecases/script/role.js";
-import { commandScenes } from "./usecases/script/scenes.js";
-import { commandScriptPatch } from "./usecases/script/script-patch.js";
-import { commandScriptValidate } from "./usecases/script/script-validate.js";
-import { commandSplit } from "./usecases/script/split.js";
-import { commandStates } from "./usecases/script/states.js";
-import { commandStateAdd } from "./usecases/script/state-add.js";
-import { commandStateDelete } from "./usecases/script/state-delete.js";
-import { commandStateRename } from "./usecases/script/state-rename.js";
-import { commandSummary } from "./usecases/script/summary.js";
-import { commandSynopsis } from "./usecases/script/synopsis.js";
-import { commandSynopsisGenerate } from "./usecases/script/synopsis-generate.js";
-import { commandTransition } from "./usecases/script/transition.js";
-import { commandType } from "./usecases/script/type.js";
-import { commandWorldview } from "./usecases/script/worldview.js";
-import { commandWriteAuthoring } from "./usecases/script/write-authoring.js";
-import { commandExportAuthoring } from "./usecases/script/export-authoring.js";
-import { commandIds } from "./usecases/script/ids.js";
-import { commandCheckout, commandWorkingCopyPublish, commandWorkingCopyStatus, } from "./usecases/script/working-copy.js";
-function packageRoot() {
-    const here = fileURLToPath(import.meta.url);
-    return path.resolve(path.dirname(here), "..");
-}
+import { emitError } from "./output.js";
 function readPackageVersion() {
-    try {
-        const pkgPath = path.join(packageRoot(), "package.json");
-        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-        return pkg.version ?? "0.0.0";
-    }
-    catch {
-        return "0.0.0";
-    }
-}
-const KNOWN_COMMANDS = new Set([
-    "doctor",
-    "update",
-    "changelog",
-    // Workflow
-    "ingest",
-    "ingest.status",
-    "view",
-    "checkout",
-    "status",
-    "publish",
-    "write",
-    "ids",
-    "export",
-    "export.script",
-    "export.episodes",
-    "export.episode-spans",
-    "export.scenes",
-    "export.scene-spans",
-    "export.action-spans",
-    // Query (plural-noun)
-    "summary", "episodes", "scenes", "actions", "actors", "locations", "props",
-    "assets", "states", "issues", "refs", "validate",
-    // Create + add entities
-    "create", "add-actor", "add-location", "add-prop", "add-episode",
-    // Edit content
-    "replace", "type", "actor", "emotion",
-    // Structure (multipolar)
-    "insert", "delete", "move", "split", "merge",
-    // Scene refs & transitions on actions
-    "transition", "scene-ref",
-    // Asset metadata
-    "rename", "describe", "alias", "role", "importance", "worldview", "synopsis", "synopsis.generate",
-    // Free-form namespace (any dimension)
-    "extend",
-    // State management
-    "state-add", "state-rename", "state-delete",
-    // Dialogue speaker / patch
-    "dialogue",
-    "patch", "do",
-]);
-// 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.
-const GROUP_COMMANDS = new Set(["export"]);
-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;
-    }
-    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);
-    }
-    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 allNonFlag.slice(0, matchLen);
-}
-function longestKnownPrefix(path) {
-    for (let len = path.length; len > 0; len--) {
-        if (KNOWN_COMMANDS.has(path.slice(0, len).join(".")))
-            return len;
-    }
-    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 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 mergedCommandOpts(cmd) {
-    const chain = [];
-    let current = cmd;
-    while (current) {
-        chain.unshift(current);
-        current = current.parent;
-    }
-    const merged = {};
-    for (const item of chain) {
-        Object.assign(merged, item.opts());
-    }
-    return merged;
-}
-const SCRIPT_ACCESS = new WeakMap();
-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(mergedCommandOpts(cmd));
-        if (positionals.length > 0)
-            normalized._args = positionals;
-        const invoke = async () => handler(normalized);
-        const result = SCRIPT_ACCESS.get(cmd) === "write"
-            ? await withScriptFileLock(scriptJsonPath(normalized), invoke)
-            : await invoke();
-        const [report, exitCode] = result;
-        emit(report, exitCode, state.jsonMode, state.format);
-        state.exitCode = exitCode;
-    };
-}
-function showGroupHelp(commandPathParts, state) {
-    return () => {
-        process.stdout.write(getHelp(commandPathParts) ?? getHelp([]) ?? "");
-        state.exitCode = EXIT_OK;
-    };
-}
-const appendStr = (value, prev) => [...prev, value];
-function withScriptOpts(cmd, access = "write") {
-    SCRIPT_ACCESS.set(cmd, access);
-    return cmd.option("--script-path <path>");
-}
-function withWorkingCopyOpts(cmd) {
-    SCRIPT_ACCESS.set(cmd, "write");
-    return cmd
-        .option("--script-path <path>")
-        .option("--project-group-no <no>");
-}
-// Selection flags shared by query commands and selector-driven write verbs:
-// the SAME vocabulary reads and writes. `--in` scopes by address (range /
-// region / '*' = whole script); the predicates AND-refine within scope.
-// On write verbs, `--apply` commits (default is a dry-run that reports the
-// blast radius and writes nothing); `--dry-run` is accepted as a no-op (it is
-// already the default) for symmetry.
-function withSelection(cmd) {
-    return cmd
-        .option("--in <selector>")
-        .option("--type <type>")
-        .option("--actor <id>")
-        .option("--grep <pattern>")
-        .option("--has <facet>")
-        .option("--apply")
-        .option("--dry-run");
+    const here = fileURLToPath(import.meta.url);
+    const packagePath = path.resolve(path.dirname(here), "..", "package.json");
+    const packageJson = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+    return packageJson.version;
 }
-function buildProgram(state, llm) {
+export function buildProgram(state, llm = PRODUCTION_LLM_COMPOSITION) {
     const program = new Command("scriptctl")
+        .description("Read, edit, ingest, and publish structured scripts")
+        .usage("<command> [options]")
         .exitOverride()
         .allowExcessArguments(false)
         .allowUnknownOption(false)
+        .showHelpAfterError(false)
         .configureOutput({
-        writeOut: (str) => process.stdout.write(str),
+        writeOut: (text) => process.stdout.write(text),
         writeErr: () => {
-            /* swallowed; we emit our own envelope */
+            // Commander errors are emitted once through the scriptctl error model.
         },
     })
-        .configureHelp({
-        formatHelp: (cmd) => getHelp(commandPath(cmd)) ?? getHelp([]) ?? "",
-    });
-    program.command("doctor")
-        .option("--llm-config <path>")
-        .action(dispatch((o) => commandDoctor(o), state));
-    program.command("update")
-        .option("--dry-run")
-        .option("--patch")
-        .action(dispatch((o) => commandUpdate(o), state));
-    program.command("changelog [version]")
-        .option("--from <version>")
-        .option("--to <version>")
-        .option("--unreleased")
-        .action(dispatch((o) => commandChangelog(o), state));
-    const ingest = program.command("ingest")
-        .option("--source-path <path>")
-        .option("--workspace-path <path>", "", "workspace")
-        .option("--llm-config <path>")
-        .option("--concurrency <n>")
-        .option("--fps <n>")
-        .option("--force")
-        .action(dispatch((options) => commandIngest(options, llm), state));
-    // `ingest status` — derive progress from the workspace's real file state (no
-    // model, no store). The runtime watcher / frontend consume `--json`.
-    // NB: --workspace-path is inherited from the parent `ingest` command — if the
-    // subcommand redeclared it, commander would attribute the user's value to the
-    // parent and clobber it with the subcommand's default in mergedCommandOpts.
-    ingest.command("status")
-        .action(dispatch((options) => commandIngestStatus(options), state));
-    program.command("view")
-        .option("--workspace-path <path>", "", "workspace")
-        .option("--watch")
-        .option("--port <n>")
-        .action(dispatch((options) => commandView(options), state));
-    withWorkingCopyOpts(program.command("checkout"))
-        .option("--discard-local")
-        .action(dispatch(commandCheckout, state));
-    withScriptOpts(program.command("status"))
-        .action(dispatch(commandWorkingCopyStatus, state));
-    withWorkingCopyOpts(program.command("publish"))
-        .action(dispatch(commandWorkingCopyPublish, state));
-    withScriptOpts(program.command("write <file>"))
-        .option("--create")
-        .option("--replace")
-        .option("--apply")
-        .option("--plan <digest>")
-        .action(dispatch(commandWriteAuthoring, state));
-    withScriptOpts(program.command("ids"), "read")
-        .requiredOption("--kind <kind>")
-        .requiredOption("--count <n>")
-        .action(dispatch(commandIds, state));
-    const exportCommand = program.command("export")
-        .action(showGroupHelp(["export"], state));
-    withScriptOpts(exportCommand.command("script"), "read")
-        .requiredOption("--output <file>")
-        .action(dispatch((opts) => commandExportAuthoring("script", opts), state));
-    for (const kind of ["episodes", "episode-spans", "scenes", "scene-spans", "action-spans"]) {
-        withScriptOpts(exportCommand.command(kind), "read")
-            .requiredOption("--in <selector>")
-            .requiredOption("--output <file>")
-            .action(dispatch((opts) => commandExportAuthoring(kind, opts), state));
-    }
-    // ============================== query (plural-noun) ==============================
-    withScriptOpts(program.command("summary"), "read")
-        .action(dispatch(commandSummary, state));
-    withScriptOpts(program.command("episodes"), "read")
-        .option("--id <id>")
-        .option("--in <addr>")
-        .option("--min-chars <n>")
-        .option("--max-chars <n>")
-        .action(dispatch(commandEpisodes, state));
-    withScriptOpts(program.command("scenes"), "read")
-        .option("--in <addr>")
-        .option("--has-actor <id>")
-        .option("--has-location <id>")
-        .option("--has-prop <id>")
-        .action(dispatch(commandScenes, state));
-    withScriptOpts(program.command("actions"), "read")
-        .option("--in <addr>")
-        .option("--grep <text>")
-        .option("--type <type>")
-        .option("--actor <id>")
-        .option("--has <kind>")
-        .option("--context <n>")
-        .action(dispatch(commandActions, state));
-    withScriptOpts(program.command("actors"), "read")
-        .option("--id <id>")
-        .option("--name <text>")
-        .option("--in <addr>")
-        .option("--counts")
-        .action(dispatch(commandActors, state));
-    withScriptOpts(program.command("locations"), "read")
-        .option("--id <id>")
-        .option("--name <text>")
-        .option("--in <addr>")
-        .option("--counts")
-        .action(dispatch(commandLocations, state));
-    withScriptOpts(program.command("props"), "read")
-        .option("--id <id>")
-        .option("--name <text>")
-        .option("--in <addr>")
-        .option("--counts")
-        .action(dispatch(commandProps, state));
-    withScriptOpts(program.command("assets"), "read")
-        .option("--kind <kind>")
-        .option("--id <id>")
-        .option("--name <text>")
-        .option("--in <addr>")
-        .option("--counts")
-        .action(dispatch(commandAssets, state));
-    withScriptOpts(program.command("states <asset-addr>"), "read")
-        .action(dispatch(commandStates, state));
-    withScriptOpts(program.command("issues"), "read")
-        .option("--severity <severity>")
-        .option("--code <code>")
-        .action(dispatch(commandIssues, state));
-    withScriptOpts(program.command("refs <addr>"), "read")
-        .option("--level <level>")
-        .action(dispatch(commandRefs, state));
-    withScriptOpts(program.command("validate"), "read")
-        .action(dispatch(commandScriptValidate, state));
-    // ============================== create + add entities ==============================
-    withScriptOpts(program.command("create"))
-        .option("--title <title>")
-        .option("--force")
-        .action(dispatch(commandCreate, state));
-    withScriptOpts(program.command("add-actor <name>"))
-        .option("--id <id>")
-        .option("--role <role>")
-        .option("--description <text>")
-        .option("--alias <alias>", "", appendStr, [])
-        .action(dispatch(commandAddActor, state));
-    withScriptOpts(program.command("add-location <name>"))
-        .option("--id <id>")
-        .option("--description <text>")
-        .action(dispatch(commandAddLocation, state));
-    withScriptOpts(program.command("add-prop <name>"))
-        .option("--id <id>")
-        .option("--description <text>")
-        .action(dispatch(commandAddProp, state));
-    withScriptOpts(program.command("add-episode"))
-        .option("--id <id>")
-        .option("--title <title>")
-        .action(dispatch(commandAddEpisode, state));
-    // ============================== edit verbs ==============================
-    // ----- content (single-point address OR a selection for a sweep) -----
-    withSelection(withScriptOpts(program.command("replace [at]")))
-        .requiredOption("--from <text>")
-        .option("--to <text>", "", "")
-        .option("--all")
-        .option("--regex")
-        .action(dispatch(commandReplace, state));
-    withSelection(withScriptOpts(program.command("type [at] [type]")))
-        .action(dispatch(commandType, state));
-    withSelection(withScriptOpts(program.command("actor [at] [actor-id]")))
-        .action(dispatch(commandActor, state));
-    withSelection(withScriptOpts(program.command("emotion [at] [emotion]")))
-        .option("--clear")
-        .action(dispatch(commandEmotion, state));
-    // ----- structure (multipolar by first-arg address format) -----
-    withScriptOpts(program.command("insert <addr>"))
-        .option("--type <type>")
-        .option("--content <text>")
-        .option("--emotion <emotion>")
-        .option("--at <idx>")
-        .option("--before <addr>")
-        .option("--after <addr>")
-        .option("--actor <id>")
-        .option("--kind <kind>", "non-actor speaker: system|broadcast|offscreen|group")
-        .option("--label <text>", "optional label for a non-actor speaker")
-        .option("--location <id>")
-        .option("--time <time>")
-        .option("--space <space>")
-        .option("--scene-id <id>")
-        .action(dispatch(commandInsert, state));
-    withScriptOpts(program.command("delete <addr>"))
-        .option("--strategy <strategy>")
-        .option("--replacement <addr>")
-        .option("--force")
-        .action(dispatch(commandDelete, state));
-    withScriptOpts(program.command("move <addr> <to>"))
-        .option("--at <idx>")
-        .action(dispatch(commandMove, state));
-    withScriptOpts(program.command("split <ep/scn>"))
-        .requiredOption("--at <idx>")
-        .option("--new-scene-id <id>")
-        .action(dispatch(commandSplit, state));
-    withScriptOpts(program.command("merge <src>"))
-        .requiredOption("--into <dst>")
-        .action(dispatch(commandMerge, state));
-    // ----- transition / scene refs -----
-    withSelection(withScriptOpts(program.command("transition [at] [target]")))
-        .option("--process <text>")
-        .option("--contrast <text>")
-        .option("--clear")
-        .action(dispatch(commandTransition, state));
-    withScriptOpts(program.command("scene-ref <at> <target>"))
-        .option("--state <id>")
-        .option("--clear")
-        .option("--remove")
-        .option("--append")
-        .option("--occurrence <n>")
-        .action(dispatch(commandContext, state));
-    // ----- asset metadata -----
-    withScriptOpts(program.command("rename <target> <name>"))
-        .action(dispatch(commandRename, state));
-    withScriptOpts(program.command("describe <target> <text>"))
-        .action(dispatch(commandDescribe, state));
-    withScriptOpts(program.command("alias <target>"))
-        .option("--add <alias>", "", appendStr, [])
-        .option("--remove <alias>", "", appendStr, [])
-        .action(dispatch(commandAlias, state));
-    withScriptOpts(program.command("role <target> <role>"))
-        .action(dispatch(commandRole, state));
-    withScriptOpts(program.command("importance <target> <importance>"))
-        .action(dispatch(commandImportance, state));
-    withScriptOpts(program.command("worldview <value>"))
-        .action(dispatch(commandWorldview, state));
-    const synopsis = withScriptOpts(program.command("synopsis [target-or-text] [text]"))
-        .action(dispatch(commandSynopsis, state));
-    withScriptOpts(synopsis.command("generate"))
-        .option("--llm-config <path>")
-        .option("--concurrency <n>", "", "30")
-        .option("--checkpoint <dir>")
-        .option("--overwrite")
-        .option("--apply")
-        .option("--dry-run")
-        .action(dispatch((options) => commandSynopsisGenerate(options, llm), state));
-    // NB: the value-parsing flag is `--json-value`, NOT `--json` — the global
-    // `--json` output-mode flag is stripped from argv before commander runs (see
-    // main()), so it can never reach this subcommand.
-    withScriptOpts(program.command("extend <addr> [key] [value]"))
-        .option("--json-value", "parse value as JSON (number/bool/object/array)")
-        .option("--clear", "delete the key (or the whole container if no key)")
-        .action(dispatch(commandExtend, state));
-    // ----- state management -----
-    withScriptOpts(program.command("state-add <target> <name>"))
-        .option("--description <text>", "", "")
-        .option("--state-id <id>")
-        .action(dispatch(commandStateAdd, state));
-    withScriptOpts(program.command("state-rename <target> <name>"))
-        .action(dispatch(commandStateRename, state));
-    withScriptOpts(program.command("state-delete <target>"))
-        .requiredOption("--strategy <strategy>")
-        .option("--replacement <id>")
-        .action(dispatch(commandStateDelete, state));
-    // ----- dialogue speaker (v3: single inline speaker per line) -----
-    withScriptOpts(program.command("dialogue <at>"))
-        .option("--actor <id>", "set the line's speaker to an actor")
-        .option("--kind <kind>", "non-actor speaker: system|broadcast|offscreen|group")
-        .option("--label <text>", "optional label for a non-actor speaker")
-        .action(dispatch(commandDialogue, state));
-    // ----- do (verb-script transaction) -----
-    withScriptOpts(program.command("do [file]"))
-        .option("--apply")
-        .option("--dry-run")
-        .action(dispatch(commandDo, state));
-    // ----- patch (machine / jq op interchange) -----
-    // <file> is OPTIONAL because --schema dumps op schemas without a file.
-    // When --schema is absent the patch / dry-run paths require <file>; the
-    // handler enforces that.
-    withScriptOpts(program.command("patch [file]"))
-        .option("--schema [op]")
-        .option("--dry-run")
-        .action(dispatch((o) => {
-        const args = o["_args"] || [];
-        if (args[0])
-            o["patch"] = args[0];
-        return commandScriptPatch(o);
-    }, state));
+        .option("-j, --json", "Output structured JSON")
+        .option("--format <format>", "Output format (addr)")
+        .version(readPackageVersion(), "-v, --version", "Show the scriptctl version");
+    registerWorkflowCommands(program, state, llm);
+    registerQueryCommands(program, state, llm);
+    registerEditCommands(program, state, llm);
+    registerBatchCommands(program, state);
+    registerToolCommands(program, state);
     return program;
 }
-export async function main(argv = null, llm = PRODUCTION_LLM_COMPOSITION) {
-    loadLocalEnv();
-    let args = argv ?? process.argv.slice(2);
-    // `--format <fmt>` is a global output toggle (like --json). `addr` emits a bare
-    // newline-delimited address stream from a query's rows[] — clean xargs input.
-    let format;
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a.startsWith("--format=")) {
-            format = a.slice("--format=".length);
-            args.splice(i, 1);
-            i--;
+function optionFor(command, token) {
+    const flag = token.split("=", 1)[0];
+    let current = command;
+    while (current) {
+        const option = current.options.find((candidate) => candidate.short === flag || candidate.long === flag);
+        if (option)
+            return option;
+        current = current.parent;
+    }
+    return undefined;
+}
+function scanShortOptions(command, token) {
+    if (!token.startsWith("-") || token.startsWith("--") || token.length < 2) {
+        return { recognized: false, json: false, hasAttachedValue: false };
+    }
+    let json = false;
+    for (let index = 1; index < token.length; index += 1) {
+        const option = optionFor(command, `-${token[index]}`);
+        if (!option?.short) {
+            return { recognized: false, json: false, hasAttachedValue: false };
         }
-        else if (a === "--format") {
-            const v = args[i + 1];
-            // Only consume the next token as the value when it isn't itself a flag —
-            // otherwise `--format --json` would silently eat --json.
-            if (v !== undefined && !v.startsWith("-")) {
-                format = v;
-                args.splice(i, 2);
-            }
-            else
-                args.splice(i, 1);
-            i--;
+        if (option.short === "-j")
+            json = true;
+        if (option.required || option.optional) {
+            return {
+                recognized: true,
+                json,
+                valueOption: option,
+                hasAttachedValue: index < token.length - 1,
+            };
         }
     }
-    const state = { jsonMode: args.includes("--json"), exitCode: EXIT_OK, format };
-    args = args.filter((a) => a !== "--json");
-    if (args.includes("--version")) {
-        process.stdout.write(`${readPackageVersion()}\n`);
-        return EXIT_OK;
+    return { recognized: true, json, hasAttachedValue: false };
+}
+function isRecognizedOptionToken(command, token) {
+    if (token === "--")
+        return true;
+    if (token.startsWith("--"))
+        return optionFor(command, token) !== undefined;
+    return scanShortOptions(command, token).recognized;
+}
+function consumesNextValue(command, option, next) {
+    if (next === undefined || next === "--")
+        return false;
+    if (option.required)
+        return !isRecognizedOptionToken(command, next);
+    return option.optional && !next.startsWith("-");
+}
+function initialJsonMode(program, args) {
+    let command = program;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === "--")
+            break;
+        if (token.startsWith("--")) {
+            if (token === "--json")
+                return true;
+            const option = optionFor(command, token);
+            if (option
+                && !token.includes("=")
+                && consumesNextValue(command, option, args[index + 1]))
+                index += 1;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            const scanned = scanShortOptions(command, token);
+            if (scanned.recognized && scanned.json)
+                return true;
+            if (scanned.recognized
+                && scanned.valueOption
+                && !scanned.hasAttachedValue
+                && consumesNextValue(command, scanned.valueOption, args[index + 1]))
+                index += 1;
+            continue;
+        }
+        const child = command.commands.find((candidate) => candidate.name() === token);
+        if (child)
+            command = child;
     }
-    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 false;
+}
+function helpTarget(program, args) {
+    let command = program;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token.startsWith("-")) {
+            const option = optionFor(command, token);
+            if (option && !token.includes("=") && (option.required || option.optional))
+                index += 1;
+            continue;
         }
-        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);
+        const child = command.commands.find((candidate) => candidate.name() === token);
+        if (!child)
+            break;
+        command = child;
     }
-    const knownLen = longestKnownPrefix(cmdPath);
-    if (knownLen < cmdPath.length) {
-        return emitError(new CliError("USAGE ERROR: Unknown command", "Unknown command.", {
-            exitCode: EXIT_USAGE,
-            required: ["valid scriptctl command"],
-            received: [cmdPath.join(" ")],
-            nextSteps: ["Run: scriptctl --help"],
-        }), state.jsonMode);
+    const names = [];
+    let current = command;
+    while (current && current.parent) {
+        names.unshift(current.name());
+        current = current.parent;
     }
-    if (wantsHelp) {
-        process.stdout.write(getHelp(cmdPath) ?? getHelp([]) ?? "");
+    return ["scriptctl", ...names, "--help"].join(" ");
+}
+function commanderMessage(error) {
+    return error.message.replace(/^error:\s*/i, "").replace(/\.$/, "");
+}
+export async function main(argv = null, llm = PRODUCTION_LLM_COMPOSITION) {
+    loadLocalEnv();
+    const args = argv ?? process.argv.slice(2);
+    const state = { jsonMode: false, exitCode: EXIT_OK };
+    const program = buildProgram(state, llm);
+    state.jsonMode = initialJsonMode(program, args);
+    if (args.length === 0) {
+        program.outputHelp();
         return EXIT_OK;
     }
-    const program = buildProgram(state, llm);
     try {
         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") {
+    catch (error) {
+        if (error instanceof CommanderError) {
+            if (error.code === "commander.help"
+                || error.code === "commander.helpDisplayed"
+                || error.code === "commander.version") {
                 return EXIT_OK;
             }
-            const message = err.message || "Invalid arguments.";
-            return emitError(new CliError("USAGE ERROR: Invalid arguments", "Invalid arguments.", {
+            return emitError(new CliError(commanderMessage(error), {
                 exitCode: EXIT_USAGE,
-                required: ["Run: scriptctl --help"],
-                received: [message],
-                nextSteps: ["Run: scriptctl --help"],
+                errorCode: "USAGE_ERROR",
+                hint: `Run '${helpTarget(program, args)}'.`,
             }), state.jsonMode);
         }
-        if (err instanceof CliError)
-            return emitError(err, state.jsonMode);
-        const e = err;
-        return emitError(new CliError("RUNTIME FAILED: Unexpected error", "Unexpected error.", {
+        if (error instanceof CliError)
+            return emitError(error, state.jsonMode);
+        const message = error instanceof Error ? error.message : String(error);
+        return emitError(new CliError(message, {
             exitCode: 70,
-            required: ["successful command execution"],
-            received: [e?.name ?? "Error"],
-            nextSteps: ["Rerun with valid inputs or inspect workspace artifacts."],
+            errorCode: "RUNTIME_ERROR",
         }), state.jsonMode);
     }
 }