@duyquangnvx/agent-cli 0.27.0 → 0.28.0

package/dist/runtime-codes.js

@@ -1,7 +1,3 @@
-import { DOCTOR_PROBLEMS } from "./built-ins/doctor.js";
-import { NOT_GLOBAL_INSTALL } from "./built-ins/install/global-npm.js";
-import { INSTALL_FAILED, NO_LATEST, NPM_FAILED, REGISTRY_AUTH, REGISTRY_UNREACHABLE, } from "./built-ins/npm.js";
-import { NOT_ON_PATH } from "./built-ins/setup.js";
 import { INVALID_INPUT, UNKNOWN_COMMAND, UNKNOWN_OPTION } from "./command-line/usage.js";
 import { CONFIRMATION_MISMATCH, CONFIRMATION_REQUIRED } from "./context/confirm.js";
 import { NOT_CONFIRMED } from "./context/cost.js";
@@ -16,6 +12,55 @@ import { STDIN_STALLED } from "./context/stdin.js";
 import { TOOL_MISSING } from "./context/tools.js";
 import { INTERNAL } from "./errors.js";
 import { UNKNOWN_FIELD } from "./list.js";
+export const DOCTOR_PROBLEMS = "DOCTOR_PROBLEMS";
+export const NOT_GLOBAL_INSTALL = "NOT_GLOBAL_INSTALL";
+export const NOT_ON_PATH = "NOT_ON_PATH";
+export const REGISTRY_UNREACHABLE = "REGISTRY_UNREACHABLE";
+export const REGISTRY_AUTH = "REGISTRY_AUTH";
+export const INSTALL_FAILED = "INSTALL_FAILED";
+export const NPM_FAILED = "NPM_FAILED";
+export const NO_LATEST = "NO_LATEST";
+/** The Runtime codes any Command can meet, which no Command declares. */
+const anyCommandErrors = {
+    [INVALID_INPUT]: { class: "caller" },
+    [UNKNOWN_OPTION]: { class: "caller" },
+    [UNKNOWN_COMMAND]: { class: "caller" },
+    [UNKNOWN_FIELD]: { class: "caller" },
+    [CONFIRMATION_REQUIRED]: { class: "caller" },
+    [CONFIRMATION_MISMATCH]: { class: "caller" },
+    [NOT_CONFIRMED]: { class: "operator" },
+    [NEEDS_OPERATOR]: { class: "operator" },
+    [OUTPUT_EXISTS]: { class: "caller" },
+    [STDIN_STALLED]: { class: "caller" },
+    [INTERRUPTED]: { class: "interrupted" },
+    [DEADLINE_EXCEEDED]: { class: "wait" },
+    [INTERNAL]: { class: "bug" },
+    [PERMISSION_DENIED]: { class: "operator" },
+    [DISK_FULL]: { class: "operator" },
+    [NOT_FOUND]: { class: "caller" },
+    [ALREADY_EXISTS]: { class: "caller" },
+    [NOT_A_FILE]: { class: "caller" },
+    [TOOL_FAILED]: { class: "operator" },
+    [TOOL_MISSING]: { class: "operator" },
+    [SECRET_MISSING]: { class: "operator" },
+    [PROJECT_INVALID]: { class: "operator" },
+};
+/**
+ * The Runtime codes only some Commands reach: each Command that throws one, Built-in or the CLI's
+ * own, declares it in `errors`, as it does a code of the CLI's Error table.
+ */
+export const declaredRuntimeErrors = {
+    [DOCTOR_PROBLEMS]: { class: "operator" },
+    [NOT_GLOBAL_INSTALL]: { class: "operator" },
+    [NOT_ON_PATH]: { class: "operator" },
+    [REGISTRY_UNREACHABLE]: { class: "operator" },
+    [REGISTRY_AUTH]: { class: "operator" },
+    [INSTALL_FAILED]: { class: "operator" },
+    [NPM_FAILED]: { class: "operator" },
+    [NO_LATEST]: { class: "source" },
+};
+/** The Runtime's own Error table: every code it fails a run with, and the class that must act. */
+export const runtimeErrors = { ...anyCommandErrors, ...declaredRuntimeErrors };
 /** Every code the Runtime fails a run with, keyed by itself, to catch or assert one. */
 export const runtimeCodes = {
     INVALID_INPUT,
@@ -49,4 +94,15 @@ export const runtimeCodes = {
     NPM_FAILED,
     NO_LATEST,
 };
+export const anyCommandClasses = Object.values(anyCommandErrors).map((declaration) => declaration.class);
+export function isRuntimeCode(code) {
+    return Object.hasOwn(runtimeErrors, code);
+}
+export function isDeclaredRuntimeCode(code) {
+    return Object.hasOwn(declaredRuntimeErrors, code);
+}
+/** Whether a Command or `doctor` row throwing `code` must declare it: a code of `table`, or a Runtime one only some reach. */
+export function mustDeclare(code, table) {
+    return Object.hasOwn(table, code) || isDeclaredRuntimeCode(code);
+}
 //# sourceMappingURL=runtime-codes.js.map

package/dist/runtime-codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-codes.js","sourceRoot":"","sources":["../src/runtime-codes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EACL,cAAc,EACd,SAAS,EACT,UAAU,EACV,aAAa,EACb,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACL,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,wFAAwF;AACxF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa;IACb,cAAc;IACd,eAAe;IACf,aAAa;IACb,qBAAqB;IACrB,qBAAqB;IACrB,aAAa;IACb,cAAc;IACd,aAAa;IACb,aAAa;IACb,WAAW;IACX,iBAAiB;IACjB,QAAQ;IACR,iBAAiB;IACjB,SAAS;IACT,SAAS;IACT,cAAc;IACd,UAAU;IACV,WAAW;IACX,YAAY;IACZ,cAAc;IACd,eAAe;IACf,eAAe;IACf,kBAAkB;IAClB,WAAW;IACX,oBAAoB;IACpB,aAAa;IACb,cAAc;IACd,UAAU;IACV,SAAS;CACD,CAAC"}
+{"version":3,"file":"runtime-codes.js","sourceRoot":"","sources":["../src/runtime-codes.ts"],"names":[],"mappings":"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"}

package/docs/example/cli.test.ts

@@ -241,8 +241,8 @@ describe("links check", () => {
 });
 
 describe("links doctor", () => {
-  async function doctor(env: Record<string, string>, config?: unknown) {
-    const cwd = await folderWith(LINKS);
+  async function doctor(env: Record<string, string>, config?: unknown, links: unknown = LINKS) {
+    const cwd = await folderWith(links);
     if (config !== undefined) {
       await writeFile(join(cwd, "links.config.json"), JSON.stringify(config));
     }
@@ -268,6 +268,13 @@ describe("links doctor", () => {
     });
   });
 
+  test("a corrupt links.json fails doctor in the store row as CORRUPT_DATA, exit 1", async () => {
+    const { result, row } = await doctor({ PATH: await pathWith("git") }, undefined, "not links");
+
+    expect(row("store")).toMatchObject({ state: "problem", code: "CORRUPT_DATA" });
+    expect(result.exitCode).toBe(1);
+  });
+
   test("the tag row reads the Project file's tag", async () => {
     const { row } = await doctor({ PATH: await pathWith("git") }, { tag: "work" });
 

package/docs/example/cli.ts

@@ -148,6 +148,7 @@ const check = defineCommand({
 
 const store: DoctorCheck<Ports, Settings> = {
   name: "store",
+  errors: ["CORRUPT_DATA"],
   run: async (ctx) => {
     const links = await readLinks(ctx);
     return { state: "ok", message: `${linksPath(ctx.cwd)} holds ${links.length} links` };

package/docs/example/folder.ts

@@ -39,6 +39,7 @@ export function fakeFiles(overrides: Partial<Files>): Files {
     remove: async () => {},
     mkdir: async () => {},
     stat: async () => undefined,
+    realPath: async () => undefined,
     ...overrides,
   };
 }

package/docs/guides/commands.md

@@ -26,7 +26,7 @@ Data over 30,000 characters spills to a file, so make a list that may grow a Lis
 
 Reach the outside through `ctx`, so tests control it:
 
-- the working directory and environment as `ctx.cwd` and `ctx.env`;
+- the working directory, environment and platform as `ctx.cwd`, `ctx.env` and `ctx.platform`, which `runCli`'s `platform` replaces in a test;
 - the file system through `ctx.files`, whose failures name the path; a `node:fs` failure is a bug (exit 70). Pass `mode` to its `write` or `mkdir` for a file or folder holding tokens. Catch a file code from `runtimeCodes` to say what to do instead, as [`example/bundle.ts`](../example/bundle.ts) turns `ALREADY_EXISTS` into its own `BUNDLE_EXISTS`;
 - a key or token through `ctx.secret(name)`, for a name in the Command's `secrets`. The Runtime reads each declared Secret from the environment, then the CLI's `.env` at `ctx.envFile` (`~/.config/<name>/.env`, or under `$XDG_CONFIG_HOME`), an empty value counting as unset, and fails the run with `SECRET_MISSING` before any work, `--dry-run` included, when one is unset; so `ctx.secret` returns a `Secret`, never `undefined`. The exception is a key that only replaces something the CLI already has, such as a token that overrides a saved login: declared `optional: true`, its absence fails nothing and `ctx.secret` may give `undefined`, while help still names it, so an agent learns the key exists. Messages name its `origin` and keep its `value` out of the agent's context. `doctor` reports every declared Secret it needs, and each optional one that is set; a key it should check that no Command requires goes in `defineCli({ secrets })`;
 - a program through `ctx.spawn`, listed in the Command's `tools`, so a missing one fails before any work and `doctor` checks it. Its `stdin` option feeds the program, from an async iterable for input too large to hold, and its `onLine` option receives each line the program writes as it comes;

package/docs/guides/doctor.md

@@ -5,6 +5,7 @@ Every multi-Command CLI has a built-in `doctor` that reports one row per check:
 ```ts
 const store: DoctorCheck<Ports, Settings> = {
   name: "store",
+  errors: ["CORRUPT_DATA"],
   run: async (ctx) => {
     const links = await readLinks(ctx);
     return { state: "ok", message: `${linksPath(ctx.cwd)} holds ${links.length} links` };
@@ -36,7 +37,7 @@ A row returns one of:
 - `{ state: "problem", message, fix?, code? }`, where `fix` is the command that fixes the problem, which `doctor` gives as a Next step before its own rerun, and `code` is one of the Error table's or the Runtime's;
 - `{ state: "skipped", message }` for a row not checked, such as "not checked: the bridge is down", so one cause shows up as one problem. It never fails `doctor`.
 
-When any row is a problem, `doctor` fails with one error per problem row, its `code` or `DOCTOR_PROBLEMS` (exit 2) without one, so it exits by the class that must act first as any Command does: an expired session 3, a network failure 75. Give a problem the code of its real cause. A row that throws becomes its own problem, with a `CliError`'s message and hint as the message, its first Next step other than `ctx.rerun()` as `fix`, and its code as `code`; the failure ends with `doctor` as typed, which a rerun in the row's hint means. A row whose `ctx.spawn` finds no declared tool on `PATH` is `skipped`, since that tool's row reports it. Each row runs under its own deadline, 10 s unless it sets `deadlineMs`, and `ctx.signal` aborts at that deadline, so pass it on. A row with `advisory: true` shows its problem and `fix` but never fails `doctor`; when it has no `fix`, `next` ends with `doctor` as typed.
+When any row is a problem, `doctor` fails with one error per problem row, its `code` or `DOCTOR_PROBLEMS` (exit 2) without one, so it exits by the class that must act first as any Command does: an expired session 3, a network failure 75. Give a problem the code of its real cause, and list in the row's `errors` each code of the Error table, and each Runtime code only some Commands reach, that it fails with, thrown or returned, as a Command does: the `store` row above declares `CORRUPT_DATA`, which `readLinks` throws. A row failing with a code it does not declare fails `doctor` as a bug (exit 70), even when another row declares it. `doctor`'s own `errors`, which `--help --json` lists, are `DOCTOR_PROBLEMS` and the codes of every row that is not advisory. A row that throws becomes its own problem, with a `CliError`'s message and hint as the message, its first Next step other than `ctx.rerun()` as `fix`, and its code as `code`; the failure ends with `doctor` as typed, which a rerun in the row's hint means. A row whose `ctx.spawn` finds no declared tool on `PATH` is `skipped`, since that tool's row reports it. Each row runs under its own deadline, 10 s unless it sets `deadlineMs`, and `ctx.signal` aborts at that deadline, so pass it on. A row with `advisory: true` shows its problem and `fix` but never fails `doctor`; when it has no `fix`, `next` ends with `doctor` as typed.
 
 The Runtime's `secrets` row checks every Secret the CLI and its Commands declare, naming where each came from and never its value, so no row of yours reads a key. An optional Secret appears only when set, unless some Command or the CLI needs the same name.
 

package/docs/guides/errors.md

@@ -21,7 +21,7 @@ export const errors = defineErrors({
 
 When a `details` field is worth reading in text mode too, such as a stack, name it in the code's `print` rather than repeating it in the message, which `--json` would then carry twice.
 
-Each Command lists in `errors` the table codes it throws, its helpers' and ports' included, so a shared store's `CORRUPT_DATA` goes on every Command that reads the store. A run ending in a table code its Command does not declare, directly or as an `AggregateError` leaf, fails as a bug (exit 70) naming the code and the Command, so the Command's tests catch a missing one; `defineCli` throws on a code the table lacks. Runtime codes are never listed.
+Each Command lists in `errors` the table codes it throws, its helpers' and ports' included, so a shared store's `CORRUPT_DATA` goes on every Command that reads the store. A run ending in a table code its Command does not declare, directly or as an `AggregateError` leaf, fails as a bug (exit 70) naming the code and the Command, so the Command's tests catch a missing one; `defineCli` throws on a code the table lacks. A Runtime code any Command can meet, such as `NOT_FOUND` or `TOOL_MISSING`, is never listed; one only some Commands reach (`NOT_GLOBAL_INSTALL`, `NOT_ON_PATH`, `REGISTRY_UNREACHABLE`, `REGISTRY_AUTH`, `INSTALL_FAILED`, `NPM_FAILED`, `NO_LATEST`, `DOCTOR_PROBLEMS`) is declared like a table code by each Command that throws it, the Built-in Commands included. A `doctor` row declares its codes in its own `errors` ([`doctor` rows](doctor.md)). `--help` lists only the exit codes some Command can end in, so exit 3 shows only when a code of class `source` is declared.
 
 Inside a Command, throw `ctx.fail(code, init, options?)`, typed to the Command's `errors` and each code's `details`, so an undeclared code is a type error. A helper outside a Command, such as [`example/store.ts`](../example/store.ts), throws through the `cliError` that `agentCli` returns, typed by the whole table.
 

package/docs/guides/testing.md

@@ -17,7 +17,7 @@ test("--dry-run prints the Plan and saves nothing", async () => {
 
 The scaffolded `test/global-setup.ts` points `TMPDIR` at one root that it removes after the run, so these folders leave nothing behind; a CLI without it should add one.
 
-One test checks every example, the Built-in Commands' included: `checkExamples(cli)` from `@duyquangnvx/agent-cli/testing` throws one error listing each example that does not tokenize, route to a Command or pass its schemas. The scaffolded test calls it already.
+One test checks every example, the Built-in Commands' included: `checkExamples(cli)` from `@duyquangnvx/agent-cli/testing` throws one error listing each example that does not tokenize, route to a Command or pass its schemas. The scaffolded test calls it already. Under `runCli`, a failure's Next steps face the same check: a Next step that would not run as given, such as one missing a required option or holding a placeholder like `<id>` for a number, fails the run as a bug (exit 70) naming it and why.
 
 Under `--json`, stderr is JSON Lines: one `{"progress":"..."}` per progress line, then `{ errors: [{ code, message, hint, next?, details?, retryAt? }] }` as the last line, even for one error. Assert a failure's code through `runtimeCodes`, so a misspelt code fails type checking:
 
@@ -63,6 +63,7 @@ A Command that awaits native threads, such as sharp's, runs work the clock canno
 - `spawnDetached`: replace it to answer for a detached child, such as a Daemon: return `{ pid }`. A test that fakes `spawn` but not `spawnDetached` fails as a bug when the Command starts one, rather than start a real child.
 - `tools`: put a folder holding an empty executable of that name on the test's `PATH`.
 - `stdin`: pass the text an `orStdin` arg reads as `runCli`'s `stdin` option.
+- `platform`: pass `"win32"` to run the Runtime's Windows branches on any OS, where it would read `process.platform`: hint wording, a declared tool found on `PATH` by its `PATHEXT` extension, such as an executable `ffmpeg.CMD`, and the npm file (`npm.cmd`), bin folder and global `node_modules` folder the Built-in Commands use. Starting a real child and retrying a real file rename still follow the host.
 
 ## What the Runtime already tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/agent-cli",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Runtime for agent-first command-line tools: owns parsing, output, errors and exit codes.",
   "type": "module",
   "engines": {

package/dist/command-errors.d.ts

@@ -1,8 +0,0 @@
-import { type CommandSpec } from "./command-spec.js";
-import type { Cli } from "./define.js";
-/**
- * `error`, or a bug naming each Error table code in it that the Command does not declare in its
- * `errors`. Runtime codes are never in the table, and a built-in's failures, `doctor` rows'
- * included, belong to no declaration, so both pass.
- */
-export declare function checkedCodes(error: unknown, { command, path, builtIn }: CommandSpec, cli: Pick<Cli, "name" | "errors">): unknown;

package/dist/command-errors.js

@@ -1,25 +0,0 @@
-import { commandLabel } from "./command-spec.js";
-import { errorTableOf } from "./error-table.js";
-import { CliError, errorsOf } from "./errors.js";
-/**
- * `error`, or a bug naming each Error table code in it that the Command does not declare in its
- * `errors`. Runtime codes are never in the table, and a built-in's failures, `doctor` rows'
- * included, belong to no declaration, so both pass.
- */
-export function checkedCodes(error, { command, path, builtIn }, cli) {
-    if (builtIn)
-        return error;
-    const table = errorTableOf(cli);
-    const declared = new Set(command.errors ?? []);
-    const undeclared = errorsOf(error).flatMap((leaf) => leaf instanceof CliError && Object.hasOwn(table, leaf.code) && !declared.has(leaf.code)
-        ? [leaf.code]
-        : []);
-    if (undeclared.length === 0)
-        return error;
-    const label = commandLabel(path, cli.name).join(" ");
-    const codes = [...new Set(undeclared)].join(", ");
-    return new Error(`\`${label}\` threw ${codes}, which its errors do not declare`, {
-        cause: error,
-    });
-}
-//# sourceMappingURL=command-errors.js.map

package/dist/command-errors.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"command-errors.js","sourceRoot":"","sources":["../src/command-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAe,EACvC,GAAiC;IAEjC,IAAI,OAAO;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAClD,IAAI,YAAY,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QACrF,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACb,CAAC,CAAC,EAAE,CACP,CAAC;IACF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClD,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,YAAY,KAAK,mCAAmC,EAAE;QAC/E,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC"}

package/dist/command-line/route-line.d.ts

@@ -1,15 +0,0 @@
-import type { SpecNode } from "../command-spec.js";
-import type { Invocation } from "./invocation.js";
-import { type CommandRoute } from "./route.js";
-import type { ShellWords } from "./shell-words.js";
-/** A line a test checks: the Command it routes to, or why it routes to none. */
-export type RoutedLine = {
-    readonly ok: true;
-    readonly routed: CommandRoute;
-    readonly invocation: Invocation;
-} | {
-    readonly ok: false;
-    readonly reason: string;
-};
-/** Routes `argv`, the line's words after the Run-as, to a Command of `root`. */
-export declare function routeLine(root: SpecNode, runAs: string, argv: ShellWords): RoutedLine;

package/dist/command-line/route-line.js

@@ -1,18 +0,0 @@
-import { route } from "./route.js";
-/** Routes `argv`, the line's words after the Run-as, to a Command of `root`. */
-export function routeLine(root, runAs, argv) {
-    if (!argv.ok)
-        return { ok: false, reason: `it does not tokenize: ${argv.reason}` };
-    const invocation = { runAs, argv: argv.words, flags: [] };
-    const routed = route(root, invocation);
-    switch (routed.kind) {
-        case "usage error":
-            return { ok: false, reason: routed.error.message };
-        case "help":
-        case "version":
-            return { ok: false, reason: "it names no Command" };
-        case "command":
-            return { ok: true, routed, invocation };
-    }
-}
-//# sourceMappingURL=route-line.js.map

package/dist/command-line/route-line.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"route-line.js","sourceRoot":"","sources":["../../src/command-line/route-line.ts"],"names":[],"mappings":"AAEA,OAAO,EAAqB,KAAK,EAAE,MAAM,YAAY,CAAC;AAQtD,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,IAAc,EAAE,KAAa,EAAE,IAAgB;IACvE,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;IACnF,MAAM,UAAU,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACvC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,aAAa;YAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACrD,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS;YACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;QACtD,KAAK,SAAS;YACZ,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC5C,CAAC;AACH,CAAC"}