@smeltjs/core 0.2.0 → 0.3.0

package/dist/cli/shell.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The CLI's edge, in one module: the name people type, where its bytes come from and
+ * go, and the codes it hands back to the shell.
+ *
+ * These three used to live in `args.ts` and `run.ts` — the two modules that now read
+ * the subcommand registry. A verb file needs all three, so leaving them there would
+ * make `args.ts → subcommands/* → args.ts` a cycle, which is exactly the shape that
+ * once forced the `--harness` help list to be hand-typed (see
+ * `src/harness/registry.ts`). **This file imports nothing**, so every module under
+ * `cli/` can read it and nothing has to be written twice to avoid a loop.
+ */
+/** The command people type. Independent of the package name. */
+export declare const CLI_NAME = "smelt";
+/**
+ * Where a wizard's answers come from: lines of text arriving over time, and nothing
+ * more. `process.stdin` is one, a scripted `Readable.from([...])` in a test is
+ * another, an async generator is a third.
+ *
+ * **Stated structurally, never as `NodeJS.ReadableStream`.** A `.d.ts` that names an
+ * ambient namespace only typechecks inside a compilation that pulled `@types/node`
+ * into its *global* scope, and a consumer building with `skipLibCheck: false` and a
+ * narrowed `types` array (or no `@types/node` at its own root — the ordinary case
+ * under pnpm) fails on smelt's declarations rather than on their own code. Naming the
+ * node type by import does not help: TypeScript resolves `node:stream` — and bare
+ * `stream` — only through the same globally-included `@types/node`. So the published
+ * surface describes the shape smelt actually consumes, which needs no node types at
+ * all, and {@link answerReader} is the one adapter that reads it.
+ * `test/guards/packaging.test.ts` holds the shipped declarations to it.
+ */
+export type AnswerStream = AsyncIterable<string | Uint8Array>;
+/**
+ * One wizard's answers, one line at a time, plus the release that ends the process.
+ *
+ * `release` is not housekeeping — it is the difference between a wizard that exits and
+ * one the user has to Ctrl-C. See {@link answerReader}.
+ */
+export interface AnswerReader {
+    /** The next line, without its terminator, or `undefined` once input has ended. */
+    next(): Promise<string | undefined>;
+    /** Stop reading and let go of the source, so nothing it owns keeps the loop alive. */
+    release(): Promise<void>;
+}
+/**
+ * Read {@link AnswerStream} as lines — and, when the wizard is done, **let go of it**.
+ *
+ * This exists because the obvious adapter is a trap. Wrapping the answer stream in
+ * `Readable.from(...)` and handing that to `readline` reads the source through *its*
+ * async iterator, and closing the readline interface or destroying the wrapper ends
+ * only the wrapper: the source is left mid-`next()`, still subscribed, still holding
+ * its handle. On the real CLI that source is `process.stdin`, so `smelt init` wrote
+ * every file, printed `Done.` and then sat there forever — a hang only visible on an
+ * open pipe or a TTY, because EOF happens to end the iteration by itself, and EOF is
+ * what every scripted test hands it.
+ *
+ * So the source's own iterator is held here and nothing else touches it. `release`
+ * calls its `return()`, which is the contract an async iterable already has for "I am
+ * finished with you": `process.stdin`'s destroys the stream and unrefs the handle, an
+ * async generator runs its `finally`, and a plain array iterator does nothing at all.
+ * Crucially `release` is called between reads, never during one — an iterator awaiting
+ * `next()` cannot be returned out of, which is the very state the `Readable.from`
+ * wrapper left the source in.
+ *
+ * Bytes are decoded as UTF-8 across chunk boundaries, so a multi-byte character split
+ * across two reads survives; `\r\n` and a final line with no terminator both behave as
+ * readline did.
+ */
+export declare function answerReader(input: AnswerStream): AnswerReader;
+/**
+ * Exit codes, and why there are five of them.
+ *
+ * A CLI that returns 0 whatever happens is the shell-level version of a stub that
+ * returns `[]`: the caller cannot tell success from failure, so a pipeline built on it
+ * fails silently. **`overBudget` is the load-bearing one.** A plan that did not fit is
+ * not an error — smelt refused to cut the regions the caller asked to keep, which is
+ * correct — but it is also not success, and a script must be able to see the
+ * difference without parsing prose.
+ */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly overBudget: 1;
+    readonly usage: 2;
+    readonly refused: 3;
+    readonly unexpected: 4;
+};
+/** Where the CLI's bytes come from and go. Injected so `runCli` is testable in-process. */
+export interface CliIo {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    /** All of stdin, as UTF-8. @throws {CliUsageError} when nothing is piped. */
+    readonly stdin: () => string;
+    /** The package version, for `--version`. */
+    readonly version: string;
+    /**
+     * Where `smelt.config.json` discovery starts, and where `init` writes. Defaults to
+     * the process working directory; tests pass a temp directory to stay hermetic.
+     */
+    readonly cwd?: string;
+    /**
+     * Interactive input for `smelt init` — the wizard reads answers line by line, which
+     * the one-shot `stdin()` above cannot provide. `bin.ts` passes the real stdin
+     * stream; tests pass a scripted one. Absent means `init` is a usage error.
+     * See {@link AnswerStream} for why the type is structural.
+     */
+    readonly initInput?: AnswerStream;
+}
+//# sourceMappingURL=shell.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/cli/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gEAAgE;AAChE,eAAO,MAAM,QAAQ,UAAU,CAAC;AAEhC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACpC,sFAAsF;IACtF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CA2C9D;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI;aACf,EAAE,EAAE,CAAC;aACL,UAAU,EAAE,CAAC;aACb,KAAK,EAAE,CAAC;aACR,OAAO,EAAE,CAAC;aACV,UAAU,EAAE,CAAC;CACL,CAAC;AAEX,2FAA2F;AAC3F,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC;CACnC","sourcesContent":["/**\n * The CLI's edge, in one module: the name people type, where its bytes come from and\n * go, and the codes it hands back to the shell.\n *\n * These three used to live in `args.ts` and `run.ts` — the two modules that now read\n * the subcommand registry. A verb file needs all three, so leaving them there would\n * make `args.ts → subcommands/* → args.ts` a cycle, which is exactly the shape that\n * once forced the `--harness` help list to be hand-typed (see\n * `src/harness/registry.ts`). **This file imports nothing**, so every module under\n * `cli/` can read it and nothing has to be written twice to avoid a loop.\n */\n\n/** The command people type. Independent of the package name. */\nexport const CLI_NAME = 'smelt';\n\n/**\n * Where a wizard's answers come from: lines of text arriving over time, and nothing\n * more. `process.stdin` is one, a scripted `Readable.from([...])` in a test is\n * another, an async generator is a third.\n *\n * **Stated structurally, never as `NodeJS.ReadableStream`.** A `.d.ts` that names an\n * ambient namespace only typechecks inside a compilation that pulled `@types/node`\n * into its *global* scope, and a consumer building with `skipLibCheck: false` and a\n * narrowed `types` array (or no `@types/node` at its own root — the ordinary case\n * under pnpm) fails on smelt's declarations rather than on their own code. Naming the\n * node type by import does not help: TypeScript resolves `node:stream` — and bare\n * `stream` — only through the same globally-included `@types/node`. So the published\n * surface describes the shape smelt actually consumes, which needs no node types at\n * all, and {@link answerReader} is the one adapter that reads it.\n * `test/guards/packaging.test.ts` holds the shipped declarations to it.\n */\nexport type AnswerStream = AsyncIterable<string | Uint8Array>;\n\n/**\n * One wizard's answers, one line at a time, plus the release that ends the process.\n *\n * `release` is not housekeeping — it is the difference between a wizard that exits and\n * one the user has to Ctrl-C. See {@link answerReader}.\n */\nexport interface AnswerReader {\n  /** The next line, without its terminator, or `undefined` once input has ended. */\n  next(): Promise<string | undefined>;\n  /** Stop reading and let go of the source, so nothing it owns keeps the loop alive. */\n  release(): Promise<void>;\n}\n\n/**\n * Read {@link AnswerStream} as lines — and, when the wizard is done, **let go of it**.\n *\n * This exists because the obvious adapter is a trap. Wrapping the answer stream in\n * `Readable.from(...)` and handing that to `readline` reads the source through *its*\n * async iterator, and closing the readline interface or destroying the wrapper ends\n * only the wrapper: the source is left mid-`next()`, still subscribed, still holding\n * its handle. On the real CLI that source is `process.stdin`, so `smelt init` wrote\n * every file, printed `Done.` and then sat there forever — a hang only visible on an\n * open pipe or a TTY, because EOF happens to end the iteration by itself, and EOF is\n * what every scripted test hands it.\n *\n * So the source's own iterator is held here and nothing else touches it. `release`\n * calls its `return()`, which is the contract an async iterable already has for \"I am\n * finished with you\": `process.stdin`'s destroys the stream and unrefs the handle, an\n * async generator runs its `finally`, and a plain array iterator does nothing at all.\n * Crucially `release` is called between reads, never during one — an iterator awaiting\n * `next()` cannot be returned out of, which is the very state the `Readable.from`\n * wrapper left the source in.\n *\n * Bytes are decoded as UTF-8 across chunk boundaries, so a multi-byte character split\n * across two reads survives; `\\r\\n` and a final line with no terminator both behave as\n * readline did.\n */\nexport function answerReader(input: AnswerStream): AnswerReader {\n  const iterator = input[Symbol.asyncIterator]();\n  const decoder = new TextDecoder('utf-8');\n  let pending = '';\n  let ended = false;\n\n  const takeLine = (): string | undefined => {\n    const newline = pending.indexOf('\\n');\n    if (newline === -1) return undefined;\n    const line = pending.slice(0, newline);\n    pending = pending.slice(newline + 1);\n    return line.endsWith('\\r') ? line.slice(0, -1) : line;\n  };\n\n  return {\n    async next(): Promise<string | undefined> {\n      for (;;) {\n        const line = takeLine();\n        if (line !== undefined) return line;\n        if (ended) {\n          if (pending === '') return undefined;\n          const last = pending;\n          pending = '';\n          return last;\n        }\n        const step = await iterator.next();\n        if (step.done === true) {\n          ended = true;\n          pending += decoder.decode(); // flush a truncated multi-byte sequence\n          continue;\n        }\n        pending +=\n          typeof step.value === 'string'\n            ? step.value\n            : decoder.decode(step.value, { stream: true });\n      }\n    },\n    async release(): Promise<void> {\n      ended = true;\n      pending = '';\n      await iterator.return?.();\n    },\n  };\n}\n\n/**\n * Exit codes, and why there are five of them.\n *\n * A CLI that returns 0 whatever happens is the shell-level version of a stub that\n * returns `[]`: the caller cannot tell success from failure, so a pipeline built on it\n * fails silently. **`overBudget` is the load-bearing one.** A plan that did not fit is\n * not an error — smelt refused to cut the regions the caller asked to keep, which is\n * correct — but it is also not success, and a script must be able to see the\n * difference without parsing prose.\n */\nexport const EXIT = {\n  ok: 0,\n  overBudget: 1,\n  usage: 2,\n  refused: 3,\n  unexpected: 4,\n} as const;\n\n/** Where the CLI's bytes come from and go. Injected so `runCli` is testable in-process. */\nexport interface CliIo {\n  readonly stdout: (text: string) => void;\n  readonly stderr: (text: string) => void;\n  /** All of stdin, as UTF-8. @throws {CliUsageError} when nothing is piped. */\n  readonly stdin: () => string;\n  /** The package version, for `--version`. */\n  readonly version: string;\n  /**\n   * Where `smelt.config.json` discovery starts, and where `init` writes. Defaults to\n   * the process working directory; tests pass a temp directory to stay hermetic.\n   */\n  readonly cwd?: string;\n  /**\n   * Interactive input for `smelt init` — the wizard reads answers line by line, which\n   * the one-shot `stdin()` above cannot provide. `bin.ts` passes the real stdin\n   * stream; tests pass a scripted one. Absent means `init` is a usage error.\n   * See {@link AnswerStream} for why the type is structural.\n   */\n  readonly initInput?: AnswerStream;\n}\n"]}

package/dist/cli/shell.js

@@ -0,0 +1,100 @@
+/**
+ * The CLI's edge, in one module: the name people type, where its bytes come from and
+ * go, and the codes it hands back to the shell.
+ *
+ * These three used to live in `args.ts` and `run.ts` — the two modules that now read
+ * the subcommand registry. A verb file needs all three, so leaving them there would
+ * make `args.ts → subcommands/* → args.ts` a cycle, which is exactly the shape that
+ * once forced the `--harness` help list to be hand-typed (see
+ * `src/harness/registry.ts`). **This file imports nothing**, so every module under
+ * `cli/` can read it and nothing has to be written twice to avoid a loop.
+ */
+/** The command people type. Independent of the package name. */
+export const CLI_NAME = 'smelt';
+/**
+ * Read {@link AnswerStream} as lines — and, when the wizard is done, **let go of it**.
+ *
+ * This exists because the obvious adapter is a trap. Wrapping the answer stream in
+ * `Readable.from(...)` and handing that to `readline` reads the source through *its*
+ * async iterator, and closing the readline interface or destroying the wrapper ends
+ * only the wrapper: the source is left mid-`next()`, still subscribed, still holding
+ * its handle. On the real CLI that source is `process.stdin`, so `smelt init` wrote
+ * every file, printed `Done.` and then sat there forever — a hang only visible on an
+ * open pipe or a TTY, because EOF happens to end the iteration by itself, and EOF is
+ * what every scripted test hands it.
+ *
+ * So the source's own iterator is held here and nothing else touches it. `release`
+ * calls its `return()`, which is the contract an async iterable already has for "I am
+ * finished with you": `process.stdin`'s destroys the stream and unrefs the handle, an
+ * async generator runs its `finally`, and a plain array iterator does nothing at all.
+ * Crucially `release` is called between reads, never during one — an iterator awaiting
+ * `next()` cannot be returned out of, which is the very state the `Readable.from`
+ * wrapper left the source in.
+ *
+ * Bytes are decoded as UTF-8 across chunk boundaries, so a multi-byte character split
+ * across two reads survives; `\r\n` and a final line with no terminator both behave as
+ * readline did.
+ */
+export function answerReader(input) {
+    const iterator = input[Symbol.asyncIterator]();
+    const decoder = new TextDecoder('utf-8');
+    let pending = '';
+    let ended = false;
+    const takeLine = () => {
+        const newline = pending.indexOf('\n');
+        if (newline === -1)
+            return undefined;
+        const line = pending.slice(0, newline);
+        pending = pending.slice(newline + 1);
+        return line.endsWith('\r') ? line.slice(0, -1) : line;
+    };
+    return {
+        async next() {
+            for (;;) {
+                const line = takeLine();
+                if (line !== undefined)
+                    return line;
+                if (ended) {
+                    if (pending === '')
+                        return undefined;
+                    const last = pending;
+                    pending = '';
+                    return last;
+                }
+                const step = await iterator.next();
+                if (step.done === true) {
+                    ended = true;
+                    pending += decoder.decode(); // flush a truncated multi-byte sequence
+                    continue;
+                }
+                pending +=
+                    typeof step.value === 'string'
+                        ? step.value
+                        : decoder.decode(step.value, { stream: true });
+            }
+        },
+        async release() {
+            ended = true;
+            pending = '';
+            await iterator.return?.();
+        },
+    };
+}
+/**
+ * Exit codes, and why there are five of them.
+ *
+ * A CLI that returns 0 whatever happens is the shell-level version of a stub that
+ * returns `[]`: the caller cannot tell success from failure, so a pipeline built on it
+ * fails silently. **`overBudget` is the load-bearing one.** A plan that did not fit is
+ * not an error — smelt refused to cut the regions the caller asked to keep, which is
+ * correct — but it is also not success, and a script must be able to see the
+ * difference without parsing prose.
+ */
+export const EXIT = {
+    ok: 0,
+    overBudget: 1,
+    usage: 2,
+    refused: 3,
+    unexpected: 4,
+};
+//# sourceMappingURL=shell.js.map

package/dist/cli/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/cli/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,QAAQ,GAAG,OAAO,CAAC;AAiChC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAmB;IAC9C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;IAC/C,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,KAAK,GAAG,KAAK,CAAC;IAElB,MAAM,QAAQ,GAAG,GAAuB,EAAE;QACxC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,OAAO,KAAK,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;QACrC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;QACvC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,IAAI;YACR,SAAS,CAAC;gBACR,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;gBACxB,IAAI,IAAI,KAAK,SAAS;oBAAE,OAAO,IAAI,CAAC;gBACpC,IAAI,KAAK,EAAE,CAAC;oBACV,IAAI,OAAO,KAAK,EAAE;wBAAE,OAAO,SAAS,CAAC;oBACrC,MAAM,IAAI,GAAG,OAAO,CAAC;oBACrB,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACnC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACvB,KAAK,GAAG,IAAI,CAAC;oBACb,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,wCAAwC;oBACrE,SAAS;gBACX,CAAC;gBACD,OAAO;oBACL,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;wBAC5B,CAAC,CAAC,IAAI,CAAC,KAAK;wBACZ,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,CAAC;QACH,CAAC;QACD,KAAK,CAAC,OAAO;YACX,KAAK,GAAG,IAAI,CAAC;YACb,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,EAAE,EAAE,CAAC;IACL,UAAU,EAAE,CAAC;IACb,KAAK,EAAE,CAAC;IACR,OAAO,EAAE,CAAC;IACV,UAAU,EAAE,CAAC;CACL,CAAC","sourcesContent":["/**\n * The CLI's edge, in one module: the name people type, where its bytes come from and\n * go, and the codes it hands back to the shell.\n *\n * These three used to live in `args.ts` and `run.ts` — the two modules that now read\n * the subcommand registry. A verb file needs all three, so leaving them there would\n * make `args.ts → subcommands/* → args.ts` a cycle, which is exactly the shape that\n * once forced the `--harness` help list to be hand-typed (see\n * `src/harness/registry.ts`). **This file imports nothing**, so every module under\n * `cli/` can read it and nothing has to be written twice to avoid a loop.\n */\n\n/** The command people type. Independent of the package name. */\nexport const CLI_NAME = 'smelt';\n\n/**\n * Where a wizard's answers come from: lines of text arriving over time, and nothing\n * more. `process.stdin` is one, a scripted `Readable.from([...])` in a test is\n * another, an async generator is a third.\n *\n * **Stated structurally, never as `NodeJS.ReadableStream`.** A `.d.ts` that names an\n * ambient namespace only typechecks inside a compilation that pulled `@types/node`\n * into its *global* scope, and a consumer building with `skipLibCheck: false` and a\n * narrowed `types` array (or no `@types/node` at its own root — the ordinary case\n * under pnpm) fails on smelt's declarations rather than on their own code. Naming the\n * node type by import does not help: TypeScript resolves `node:stream` — and bare\n * `stream` — only through the same globally-included `@types/node`. So the published\n * surface describes the shape smelt actually consumes, which needs no node types at\n * all, and {@link answerReader} is the one adapter that reads it.\n * `test/guards/packaging.test.ts` holds the shipped declarations to it.\n */\nexport type AnswerStream = AsyncIterable<string | Uint8Array>;\n\n/**\n * One wizard's answers, one line at a time, plus the release that ends the process.\n *\n * `release` is not housekeeping — it is the difference between a wizard that exits and\n * one the user has to Ctrl-C. See {@link answerReader}.\n */\nexport interface AnswerReader {\n  /** The next line, without its terminator, or `undefined` once input has ended. */\n  next(): Promise<string | undefined>;\n  /** Stop reading and let go of the source, so nothing it owns keeps the loop alive. */\n  release(): Promise<void>;\n}\n\n/**\n * Read {@link AnswerStream} as lines — and, when the wizard is done, **let go of it**.\n *\n * This exists because the obvious adapter is a trap. Wrapping the answer stream in\n * `Readable.from(...)` and handing that to `readline` reads the source through *its*\n * async iterator, and closing the readline interface or destroying the wrapper ends\n * only the wrapper: the source is left mid-`next()`, still subscribed, still holding\n * its handle. On the real CLI that source is `process.stdin`, so `smelt init` wrote\n * every file, printed `Done.` and then sat there forever — a hang only visible on an\n * open pipe or a TTY, because EOF happens to end the iteration by itself, and EOF is\n * what every scripted test hands it.\n *\n * So the source's own iterator is held here and nothing else touches it. `release`\n * calls its `return()`, which is the contract an async iterable already has for \"I am\n * finished with you\": `process.stdin`'s destroys the stream and unrefs the handle, an\n * async generator runs its `finally`, and a plain array iterator does nothing at all.\n * Crucially `release` is called between reads, never during one — an iterator awaiting\n * `next()` cannot be returned out of, which is the very state the `Readable.from`\n * wrapper left the source in.\n *\n * Bytes are decoded as UTF-8 across chunk boundaries, so a multi-byte character split\n * across two reads survives; `\\r\\n` and a final line with no terminator both behave as\n * readline did.\n */\nexport function answerReader(input: AnswerStream): AnswerReader {\n  const iterator = input[Symbol.asyncIterator]();\n  const decoder = new TextDecoder('utf-8');\n  let pending = '';\n  let ended = false;\n\n  const takeLine = (): string | undefined => {\n    const newline = pending.indexOf('\\n');\n    if (newline === -1) return undefined;\n    const line = pending.slice(0, newline);\n    pending = pending.slice(newline + 1);\n    return line.endsWith('\\r') ? line.slice(0, -1) : line;\n  };\n\n  return {\n    async next(): Promise<string | undefined> {\n      for (;;) {\n        const line = takeLine();\n        if (line !== undefined) return line;\n        if (ended) {\n          if (pending === '') return undefined;\n          const last = pending;\n          pending = '';\n          return last;\n        }\n        const step = await iterator.next();\n        if (step.done === true) {\n          ended = true;\n          pending += decoder.decode(); // flush a truncated multi-byte sequence\n          continue;\n        }\n        pending +=\n          typeof step.value === 'string'\n            ? step.value\n            : decoder.decode(step.value, { stream: true });\n      }\n    },\n    async release(): Promise<void> {\n      ended = true;\n      pending = '';\n      await iterator.return?.();\n    },\n  };\n}\n\n/**\n * Exit codes, and why there are five of them.\n *\n * A CLI that returns 0 whatever happens is the shell-level version of a stub that\n * returns `[]`: the caller cannot tell success from failure, so a pipeline built on it\n * fails silently. **`overBudget` is the load-bearing one.** A plan that did not fit is\n * not an error — smelt refused to cut the regions the caller asked to keep, which is\n * correct — but it is also not success, and a script must be able to see the\n * difference without parsing prose.\n */\nexport const EXIT = {\n  ok: 0,\n  overBudget: 1,\n  usage: 2,\n  refused: 3,\n  unexpected: 4,\n} as const;\n\n/** Where the CLI's bytes come from and go. Injected so `runCli` is testable in-process. */\nexport interface CliIo {\n  readonly stdout: (text: string) => void;\n  readonly stderr: (text: string) => void;\n  /** All of stdin, as UTF-8. @throws {CliUsageError} when nothing is piped. */\n  readonly stdin: () => string;\n  /** The package version, for `--version`. */\n  readonly version: string;\n  /**\n   * Where `smelt.config.json` discovery starts, and where `init` writes. Defaults to\n   * the process working directory; tests pass a temp directory to stay hermetic.\n   */\n  readonly cwd?: string;\n  /**\n   * Interactive input for `smelt init` — the wizard reads answers line by line, which\n   * the one-shot `stdin()` above cannot provide. `bin.ts` passes the real stdin\n   * stream; tests pass a scripted one. Absent means `init` is a usage error.\n   * See {@link AnswerStream} for why the type is structural.\n   */\n  readonly initInput?: AnswerStream;\n}\n"]}

package/dist/cli/subcommands/flags.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Every flag the CLI accepts, once.
+ *
+ * The table is the companion the {@link Subcommand} registry needs: a verb declares
+ * the flags it owns as `FlagName[]`, so the type of that list — and therefore whether
+ * a verb can claim a flag that does not exist — comes from here. It carries three
+ * things that used to be written in three places:
+ *
+ *   1. **How `node:util.parseArgs` reads the flag.** The option table used to be a
+ *      literal inside `parseSmeltArgs`.
+ *   2. **The name.** `FlagName` is `keyof typeof CLI_FLAGS`, so an eleventh flag is
+ *      spelled once and every verb's ownership list typechecks against it.
+ *   3. **Its OPTIONS entry in `--help`.** Including the `map only.` / `hooks only.`
+ *      prefix, which is *not* stored here: it is generated from the registry's
+ *      ownership (see `renderOptions` in `cli/usage.ts`), because "which verb owns
+ *      this flag" is a fact the registry already holds and prose that restates it is
+ *      prose that can go stale.
+ *
+ * Key order is meaningful: it is the order the OPTIONS block renders and the order a
+ * refusal lists flags in, so keep it stable and append new flags where they read best.
+ */
+export declare const CLI_FLAGS: {
+    readonly budget: {
+        readonly type: 'string';
+    };
+    readonly focus: {
+        readonly type: 'string';
+        readonly multiple: true;
+    };
+    readonly language: {
+        readonly type: 'string';
+    };
+    readonly strategy: {
+        readonly type: 'string';
+    };
+    readonly ignore: {
+        readonly type: 'string';
+        readonly multiple: true;
+    };
+    readonly cache: {
+        readonly type: 'string';
+    };
+    readonly harness: {
+        readonly type: 'string';
+    };
+    readonly json: {
+        readonly type: 'boolean';
+    };
+    readonly reconstruct: {
+        readonly type: 'boolean';
+    };
+    readonly help: {
+        readonly type: 'boolean';
+        readonly short: 'h';
+    };
+    readonly version: {
+        readonly type: 'boolean';
+    };
+};
+/** Every flag name, as a type. A verb cannot claim a flag that is not in the table. */
+export type FlagName = keyof typeof CLI_FLAGS;
+/**
+ * The flags answered *before* any verb, so no verb owns them and no verb may refuse
+ * them: `smelt map --help` prints the help, exactly as it always has. Every other flag
+ * belongs to at least one verb — `test/guards/subcommand-registry.test.ts` pins that.
+ */
+export declare const GLOBAL_FLAGS: readonly ["help", "version"];
+/** A flag a verb can own — everything but the two global ones. */
+export type VerbFlag = Exclude<FlagName, (typeof GLOBAL_FLAGS)[number]>;
+/** Every ownable flag, in table order: the list a refusal checks a verb against. */
+export declare const VERB_FLAGS: readonly VerbFlag[];
+/**
+ * `--a`, `--a and --b`, `--a, --b and --c` — in flag-table order, always.
+ *
+ * Every refusal that names more than one flag spells the list this way: the
+ * ownership refusal in `./registry.ts`, and the default verb's `--reconstruct`
+ * refusal in `./smelt.ts`. It lives with the table because the *order* is the
+ * table's — a refusal that listed flags in the order the user happened to type them
+ * would read differently every time, and two refusals disagreeing about how to spell
+ * the same pair is the kind of drift this file exists to remove.
+ */
+export declare function flagList(flags: readonly VerbFlag[]): string;
+/** What one flag's parsed value looks like, derived from how `parseArgs` was told to read it. */
+type FlagValue<F> = F extends {
+    readonly type: 'boolean';
+} ? boolean : F extends {
+    readonly multiple: true;
+} ? readonly string[] : string;
+/**
+ * The parsed flags, as every `Subcommand.parse` sees them: one optional field per
+ * flag, typed by the table above. Absent means the user did not type it — which is
+ * the only thing a refusal needs to know, and the only thing a verb may act on.
+ */
+export type FlagValues = {
+    readonly [K in FlagName]?: FlagValue<(typeof CLI_FLAGS)[K]>;
+};
+/** How one flag appears in the OPTIONS block of `--help`. */
+export interface FlagHelp {
+    /** The left column, e.g. `--budget <bytes>` or `-h, --help`. */
+    readonly label: string;
+    /**
+     * The description, already wrapped to the OPTIONS column — a function because three
+     * entries render a registry (`SUPPORTED_LANGUAGES`, `STRATEGIES` +
+     * `STRUCTURAL_LANGUAGES`, `HARNESS_IDS`) rather than a hand-typed list. The
+     * ownership prefix is not here; it is generated.
+     */
+    body(): readonly string[];
+}
+/**
+ * A comma-separated list under an OPTIONS entry's hanging indent, wrapped where the
+ * hand-typed version wrapped. `--strategy` and `--language` render their registries on
+ * one line because they fit; the harness ids do not, and a list long enough to wrap is
+ * exactly the list nobody keeps in sync by hand.
+ */
+export declare function optionList(items: readonly string[], width: number): readonly string[];
+/**
+ * The OPTIONS entry for every flag. `Record<FlagName, FlagHelp>` on purpose: a flag
+ * added to {@link CLI_FLAGS} without a help entry is a compile error, so the help text
+ * cannot fall behind what the parser accepts.
+ */
+export declare const FLAG_HELP: Readonly<Record<FlagName, FlagHelp>>;
+/**
+ * `--budget` has no built-in default, for the same reason `smelt()` has none: a budget
+ * smelt invented would be smelt deciding how much of the caller's context to throw
+ * away, silently, at a number nobody chose. A *missing* flag is not an error here,
+ * though — `smelt.config.json` may carry a `defaultBudgetBytes` the user chose
+ * explicitly, and the verb's `resolve` errors only when neither exists. A malformed
+ * value is always an error.
+ *
+ * It lives with the flag rather than with a verb because two verbs own `--budget`, and
+ * the two of them agreeing on what "4kb" means is not something to leave to chance.
+ *
+ * The *lexing* is the CLI's own and stays here — argv carries strings, so `4kb` and a
+ * leading `-` are answered by a digits-only test before anything numeric happens. The
+ * *rule* and *the sentence that refuses it* come from `ops/inputs.ts`, which is also
+ * where the `smelt_file` tool gets them: two surfaces, one law, spelled `--budget`
+ * here and `"budgetBytes"` there.
+ */
+export declare function parseBudget(raw: string | undefined): number | undefined;
+export {};
+//# sourceMappingURL=flags.d.ts.map

package/dist/cli/subcommands/flags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../../../src/cli/subcommands/flags.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS;aACpB,MAAM;iBAAI,IAAI,EAAE,QAAQ;;aACxB,KAAK;iBAAI,IAAI,EAAE,QAAQ;iBAAE,QAAQ;;aACjC,QAAQ;iBAAI,IAAI,EAAE,QAAQ;;aAC1B,QAAQ;iBAAI,IAAI,EAAE,QAAQ;;aAC1B,MAAM;iBAAI,IAAI,EAAE,QAAQ;iBAAE,QAAQ;;aAClC,KAAK;iBAAI,IAAI,EAAE,QAAQ;;aACvB,OAAO;iBAAI,IAAI,EAAE,QAAQ;;aACzB,IAAI;iBAAI,IAAI,EAAE,SAAS;;aACvB,WAAW;iBAAI,IAAI,EAAE,SAAS;;aAC9B,IAAI;iBAAI,IAAI,EAAE,SAAS;iBAAE,KAAK,EAAE,GAAG;;aACnC,OAAO;iBAAI,IAAI,EAAE,SAAS;;CAClB,CAAC;AAEX,uFAAuF;AACvF,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,SAAS,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,YAAY,8BAA6D,CAAC;AAEvF,kEAAkE;AAClE,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAExE,oFAAoF;AACpF,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAEzC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,GAAG,MAAM,CAI3D;AAED,iGAAiG;AACjG,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACtD,OAAO,GACP,CAAC,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,GACnC,SAAS,MAAM,EAAE,GACjB,MAAM,CAAC;AAEb;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAEzF,6DAA6D;AAC7D,MAAM,WAAW,QAAQ;IACvB,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,IAAI,IAAI,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAerF;AAKD;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,CA8E1D,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOvE","sourcesContent":["import { SUPPORTED_LANGUAGES } from '../../detect.ts';\nimport { CliUsageError } from '../../errors.ts';\nimport { HARNESS_IDS } from '../../harness/registry.ts';\nimport { budgetFault, budgetMalformed } from '../../ops/inputs.ts';\nimport type { BudgetFault } from '../../ops/inputs.ts';\nimport { STRATEGIES, DEFAULT_STRATEGY } from '../../plan/planners.ts';\nimport { STRUCTURAL_LANGUAGES } from '../../plan/structural.ts';\nimport { DEFAULT_REPO_IGNORE } from '../../repomap/map.ts';\nimport { CLI_NAME } from '../shell.ts';\n\n/**\n * Every flag the CLI accepts, once.\n *\n * The table is the companion the {@link Subcommand} registry needs: a verb declares\n * the flags it owns as `FlagName[]`, so the type of that list — and therefore whether\n * a verb can claim a flag that does not exist — comes from here. It carries three\n * things that used to be written in three places:\n *\n *   1. **How `node:util.parseArgs` reads the flag.** The option table used to be a\n *      literal inside `parseSmeltArgs`.\n *   2. **The name.** `FlagName` is `keyof typeof CLI_FLAGS`, so an eleventh flag is\n *      spelled once and every verb's ownership list typechecks against it.\n *   3. **Its OPTIONS entry in `--help`.** Including the `map only.` / `hooks only.`\n *      prefix, which is *not* stored here: it is generated from the registry's\n *      ownership (see `renderOptions` in `cli/usage.ts`), because \"which verb owns\n *      this flag\" is a fact the registry already holds and prose that restates it is\n *      prose that can go stale.\n *\n * Key order is meaningful: it is the order the OPTIONS block renders and the order a\n * refusal lists flags in, so keep it stable and append new flags where they read best.\n */\nexport const CLI_FLAGS = {\n  budget: { type: 'string' },\n  focus: { type: 'string', multiple: true },\n  language: { type: 'string' },\n  strategy: { type: 'string' },\n  ignore: { type: 'string', multiple: true },\n  cache: { type: 'string' },\n  harness: { type: 'string' },\n  json: { type: 'boolean' },\n  reconstruct: { type: 'boolean' },\n  help: { type: 'boolean', short: 'h' },\n  version: { type: 'boolean' },\n} as const;\n\n/** Every flag name, as a type. A verb cannot claim a flag that is not in the table. */\nexport type FlagName = keyof typeof CLI_FLAGS;\n\n/**\n * The flags answered *before* any verb, so no verb owns them and no verb may refuse\n * them: `smelt map --help` prints the help, exactly as it always has. Every other flag\n * belongs to at least one verb — `test/guards/subcommand-registry.test.ts` pins that.\n */\nexport const GLOBAL_FLAGS = ['help', 'version'] as const satisfies readonly FlagName[];\n\n/** A flag a verb can own — everything but the two global ones. */\nexport type VerbFlag = Exclude<FlagName, (typeof GLOBAL_FLAGS)[number]>;\n\n/** Every ownable flag, in table order: the list a refusal checks a verb against. */\nexport const VERB_FLAGS: readonly VerbFlag[] = Object.keys(CLI_FLAGS).filter(\n  (name): name is VerbFlag => !(GLOBAL_FLAGS as readonly string[]).includes(name),\n);\n\n/**\n * `--a`, `--a and --b`, `--a, --b and --c` — in flag-table order, always.\n *\n * Every refusal that names more than one flag spells the list this way: the\n * ownership refusal in `./registry.ts`, and the default verb's `--reconstruct`\n * refusal in `./smelt.ts`. It lives with the table because the *order* is the\n * table's — a refusal that listed flags in the order the user happened to type them\n * would read differently every time, and two refusals disagreeing about how to spell\n * the same pair is the kind of drift this file exists to remove.\n */\nexport function flagList(flags: readonly VerbFlag[]): string {\n  const spelled = VERB_FLAGS.filter((flag) => flags.includes(flag)).map((flag) => `--${flag}`);\n  if (spelled.length <= 1) return spelled.join('');\n  return `${spelled.slice(0, -1).join(', ')} and ${spelled.at(-1) ?? ''}`;\n}\n\n/** What one flag's parsed value looks like, derived from how `parseArgs` was told to read it. */\ntype FlagValue<F> = F extends { readonly type: 'boolean' }\n  ? boolean\n  : F extends { readonly multiple: true }\n    ? readonly string[]\n    : string;\n\n/**\n * The parsed flags, as every `Subcommand.parse` sees them: one optional field per\n * flag, typed by the table above. Absent means the user did not type it — which is\n * the only thing a refusal needs to know, and the only thing a verb may act on.\n */\nexport type FlagValues = { readonly [K in FlagName]?: FlagValue<(typeof CLI_FLAGS)[K]> };\n\n/** How one flag appears in the OPTIONS block of `--help`. */\nexport interface FlagHelp {\n  /** The left column, e.g. `--budget <bytes>` or `-h, --help`. */\n  readonly label: string;\n  /**\n   * The description, already wrapped to the OPTIONS column — a function because three\n   * entries render a registry (`SUPPORTED_LANGUAGES`, `STRATEGIES` +\n   * `STRUCTURAL_LANGUAGES`, `HARNESS_IDS`) rather than a hand-typed list. The\n   * ownership prefix is not here; it is generated.\n   */\n  body(): readonly string[];\n}\n\n/**\n * A comma-separated list under an OPTIONS entry's hanging indent, wrapped where the\n * hand-typed version wrapped. `--strategy` and `--language` render their registries on\n * one line because they fit; the harness ids do not, and a list long enough to wrap is\n * exactly the list nobody keeps in sync by hand.\n */\nexport function optionList(items: readonly string[], width: number): readonly string[] {\n  const lines: string[] = [];\n  let line = '';\n  items.forEach((item, index) => {\n    const word = index === items.length - 1 ? `${item}.` : `${item},`;\n    const candidate = line === '' ? word : `${line} ${word}`;\n    if (line !== '' && candidate.length > width) {\n      lines.push(line);\n      line = word;\n    } else {\n      line = candidate;\n    }\n  });\n  lines.push(line);\n  return lines;\n}\n\n/** The width an OPTIONS description wraps within, once its 23-column indent is removed. */\nconst OPTION_BODY_WIDTH = 65;\n\n/**\n * The OPTIONS entry for every flag. `Record<FlagName, FlagHelp>` on purpose: a flag\n * added to {@link CLI_FLAGS} without a help entry is a compile error, so the help text\n * cannot fall behind what the parser accepts.\n */\nexport const FLAG_HELP: Readonly<Record<FlagName, FlagHelp>> = {\n  budget: {\n    label: '--budget <bytes>',\n    body: () => [\n      'Required, unless smelt.config.json sets defaultBudgetBytes.',\n      'Soft ceiling for the output, in UTF-8 bytes (for map: a hard',\n      'ceiling, met by construction). No built-in default: a budget',\n      `${CLI_NAME} invented would decide for you.`,\n    ],\n  },\n  focus: {\n    label: '--focus <term>',\n    body: () => [\n      'What you were looking for. Repeatable. Matching regions and',\n      'their context survive; the runs between them collapse. For',\n      'map: symbols matching a term (by name or path) are promoted',\n      'to the front of the fill order, ranks unchanged.',\n    ],\n  },\n  language: {\n    label: '--language <id>',\n    body: () => [`Override detection. One of: ${[...SUPPORTED_LANGUAGES, 'unknown'].join(', ')}.`],\n  },\n  strategy: {\n    label: '--strategy <id>',\n    body: () => [\n      `${STRATEGIES.join(', ')}. Defaults to ${DEFAULT_STRATEGY}, unless`,\n      'smelt.config.json says otherwise. structural parses',\n      `${STRUCTURAL_LANGUAGES.join(', ')};`,\n      'any other language is refused, never approximated. auto picks',\n      'structural for those languages and lexical for the rest, and',\n      'the report names whichever one actually ran.',\n    ],\n  },\n  ignore: {\n    label: '--ignore <entry>',\n    body: () => [\n      'Repeatable. Replaces the default ignore list',\n      // Read off DEFAULT_REPO_IGNORE, never re-typed: help text that lists a default\n      // by hand is help text that will one day describe a different default.\n      `(${DEFAULT_REPO_IGNORE.join(', ')}): a bare name matches any path segment,`,\n      'an entry containing / is a root-relative prefix.',\n    ],\n  },\n  cache: {\n    label: '--cache <dir>',\n    body: () => [\n      'Directory for the tags cache, keyed by content',\n      'hash. Only when given does the map write to disk at all.',\n    ],\n  },\n  harness: {\n    label: '--harness <id>',\n    body: () => [\n      'Skip harness detection and target one id:',\n      ...optionList(HARNESS_IDS, OPTION_BODY_WIDTH),\n    ],\n  },\n  json: {\n    label: '--json',\n    body: () => [\n      'Print a JSON envelope on stdout instead of the text:',\n      '{ format, result, elided } for a smelt run — `result` is',\n      'the SmeltResult verbatim, `elided` carries the bytes, so',\n      'the envelope can be reconstructed; feed it back with',\n      '--reconstruct. For map: { format, map }, the RepoMap',\n      'structure verbatim.',\n    ],\n  },\n  reconstruct: {\n    label: '--reconstruct',\n    body: () => [\n      'Read a --json envelope and print the original text, byte for',\n      'byte. This is Law 3 you can run from a shell.',\n    ],\n  },\n  help: { label: '-h, --help', body: () => ['This text.'] },\n  version: { label: '--version', body: () => ['The package version.'] },\n};\n\n/**\n * `--budget` has no built-in default, for the same reason `smelt()` has none: a budget\n * smelt invented would be smelt deciding how much of the caller's context to throw\n * away, silently, at a number nobody chose. A *missing* flag is not an error here,\n * though — `smelt.config.json` may carry a `defaultBudgetBytes` the user chose\n * explicitly, and the verb's `resolve` errors only when neither exists. A malformed\n * value is always an error.\n *\n * It lives with the flag rather than with a verb because two verbs own `--budget`, and\n * the two of them agreeing on what \"4kb\" means is not something to leave to chance.\n *\n * The *lexing* is the CLI's own and stays here — argv carries strings, so `4kb` and a\n * leading `-` are answered by a digits-only test before anything numeric happens. The\n * *rule* and *the sentence that refuses it* come from `ops/inputs.ts`, which is also\n * where the `smelt_file` tool gets them: two surfaces, one law, spelled `--budget`\n * here and `\"budgetBytes\"` there.\n */\nexport function parseBudget(raw: string | undefined): number | undefined {\n  if (raw === undefined) return undefined;\n  if (!/^\\d+$/.test(raw)) throw refuseBudget('not-an-integer', raw);\n  const value = Number(raw);\n  const fault = budgetFault(value);\n  if (fault !== undefined) throw refuseBudget(fault, raw);\n  return value;\n}\n\n/** The malformed-budget refusal, in the CLI's currency: prefixed, and exit 2. */\nfunction refuseBudget(fault: BudgetFault, raw: string): CliUsageError {\n  return new CliUsageError(`${CLI_NAME}: ${budgetMalformed(fault, '--budget', raw)}`);\n}\n"]}

package/dist/cli/subcommands/flags.js

@@ -0,0 +1,208 @@
+import { SUPPORTED_LANGUAGES } from '../../detect.js';
+import { CliUsageError } from '../../errors.js';
+import { HARNESS_IDS } from '../../harness/registry.js';
+import { budgetFault, budgetMalformed } from '../../ops/inputs.js';
+import { STRATEGIES, DEFAULT_STRATEGY } from '../../plan/planners.js';
+import { STRUCTURAL_LANGUAGES } from '../../plan/structural.js';
+import { DEFAULT_REPO_IGNORE } from '../../repomap/map.js';
+import { CLI_NAME } from '../shell.js';
+/**
+ * Every flag the CLI accepts, once.
+ *
+ * The table is the companion the {@link Subcommand} registry needs: a verb declares
+ * the flags it owns as `FlagName[]`, so the type of that list — and therefore whether
+ * a verb can claim a flag that does not exist — comes from here. It carries three
+ * things that used to be written in three places:
+ *
+ *   1. **How `node:util.parseArgs` reads the flag.** The option table used to be a
+ *      literal inside `parseSmeltArgs`.
+ *   2. **The name.** `FlagName` is `keyof typeof CLI_FLAGS`, so an eleventh flag is
+ *      spelled once and every verb's ownership list typechecks against it.
+ *   3. **Its OPTIONS entry in `--help`.** Including the `map only.` / `hooks only.`
+ *      prefix, which is *not* stored here: it is generated from the registry's
+ *      ownership (see `renderOptions` in `cli/usage.ts`), because "which verb owns
+ *      this flag" is a fact the registry already holds and prose that restates it is
+ *      prose that can go stale.
+ *
+ * Key order is meaningful: it is the order the OPTIONS block renders and the order a
+ * refusal lists flags in, so keep it stable and append new flags where they read best.
+ */
+export const CLI_FLAGS = {
+    budget: { type: 'string' },
+    focus: { type: 'string', multiple: true },
+    language: { type: 'string' },
+    strategy: { type: 'string' },
+    ignore: { type: 'string', multiple: true },
+    cache: { type: 'string' },
+    harness: { type: 'string' },
+    json: { type: 'boolean' },
+    reconstruct: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean' },
+};
+/**
+ * The flags answered *before* any verb, so no verb owns them and no verb may refuse
+ * them: `smelt map --help` prints the help, exactly as it always has. Every other flag
+ * belongs to at least one verb — `test/guards/subcommand-registry.test.ts` pins that.
+ */
+export const GLOBAL_FLAGS = ['help', 'version'];
+/** Every ownable flag, in table order: the list a refusal checks a verb against. */
+export const VERB_FLAGS = Object.keys(CLI_FLAGS).filter((name) => !GLOBAL_FLAGS.includes(name));
+/**
+ * `--a`, `--a and --b`, `--a, --b and --c` — in flag-table order, always.
+ *
+ * Every refusal that names more than one flag spells the list this way: the
+ * ownership refusal in `./registry.ts`, and the default verb's `--reconstruct`
+ * refusal in `./smelt.ts`. It lives with the table because the *order* is the
+ * table's — a refusal that listed flags in the order the user happened to type them
+ * would read differently every time, and two refusals disagreeing about how to spell
+ * the same pair is the kind of drift this file exists to remove.
+ */
+export function flagList(flags) {
+    const spelled = VERB_FLAGS.filter((flag) => flags.includes(flag)).map((flag) => `--${flag}`);
+    if (spelled.length <= 1)
+        return spelled.join('');
+    return `${spelled.slice(0, -1).join(', ')} and ${spelled.at(-1) ?? ''}`;
+}
+/**
+ * A comma-separated list under an OPTIONS entry's hanging indent, wrapped where the
+ * hand-typed version wrapped. `--strategy` and `--language` render their registries on
+ * one line because they fit; the harness ids do not, and a list long enough to wrap is
+ * exactly the list nobody keeps in sync by hand.
+ */
+export function optionList(items, width) {
+    const lines = [];
+    let line = '';
+    items.forEach((item, index) => {
+        const word = index === items.length - 1 ? `${item}.` : `${item},`;
+        const candidate = line === '' ? word : `${line} ${word}`;
+        if (line !== '' && candidate.length > width) {
+            lines.push(line);
+            line = word;
+        }
+        else {
+            line = candidate;
+        }
+    });
+    lines.push(line);
+    return lines;
+}
+/** The width an OPTIONS description wraps within, once its 23-column indent is removed. */
+const OPTION_BODY_WIDTH = 65;
+/**
+ * The OPTIONS entry for every flag. `Record<FlagName, FlagHelp>` on purpose: a flag
+ * added to {@link CLI_FLAGS} without a help entry is a compile error, so the help text
+ * cannot fall behind what the parser accepts.
+ */
+export const FLAG_HELP = {
+    budget: {
+        label: '--budget <bytes>',
+        body: () => [
+            'Required, unless smelt.config.json sets defaultBudgetBytes.',
+            'Soft ceiling for the output, in UTF-8 bytes (for map: a hard',
+            'ceiling, met by construction). No built-in default: a budget',
+            `${CLI_NAME} invented would decide for you.`,
+        ],
+    },
+    focus: {
+        label: '--focus <term>',
+        body: () => [
+            'What you were looking for. Repeatable. Matching regions and',
+            'their context survive; the runs between them collapse. For',
+            'map: symbols matching a term (by name or path) are promoted',
+            'to the front of the fill order, ranks unchanged.',
+        ],
+    },
+    language: {
+        label: '--language <id>',
+        body: () => [`Override detection. One of: ${[...SUPPORTED_LANGUAGES, 'unknown'].join(', ')}.`],
+    },
+    strategy: {
+        label: '--strategy <id>',
+        body: () => [
+            `${STRATEGIES.join(', ')}. Defaults to ${DEFAULT_STRATEGY}, unless`,
+            'smelt.config.json says otherwise. structural parses',
+            `${STRUCTURAL_LANGUAGES.join(', ')};`,
+            'any other language is refused, never approximated. auto picks',
+            'structural for those languages and lexical for the rest, and',
+            'the report names whichever one actually ran.',
+        ],
+    },
+    ignore: {
+        label: '--ignore <entry>',
+        body: () => [
+            'Repeatable. Replaces the default ignore list',
+            // Read off DEFAULT_REPO_IGNORE, never re-typed: help text that lists a default
+            // by hand is help text that will one day describe a different default.
+            `(${DEFAULT_REPO_IGNORE.join(', ')}): a bare name matches any path segment,`,
+            'an entry containing / is a root-relative prefix.',
+        ],
+    },
+    cache: {
+        label: '--cache <dir>',
+        body: () => [
+            'Directory for the tags cache, keyed by content',
+            'hash. Only when given does the map write to disk at all.',
+        ],
+    },
+    harness: {
+        label: '--harness <id>',
+        body: () => [
+            'Skip harness detection and target one id:',
+            ...optionList(HARNESS_IDS, OPTION_BODY_WIDTH),
+        ],
+    },
+    json: {
+        label: '--json',
+        body: () => [
+            'Print a JSON envelope on stdout instead of the text:',
+            '{ format, result, elided } for a smelt run — `result` is',
+            'the SmeltResult verbatim, `elided` carries the bytes, so',
+            'the envelope can be reconstructed; feed it back with',
+            '--reconstruct. For map: { format, map }, the RepoMap',
+            'structure verbatim.',
+        ],
+    },
+    reconstruct: {
+        label: '--reconstruct',
+        body: () => [
+            'Read a --json envelope and print the original text, byte for',
+            'byte. This is Law 3 you can run from a shell.',
+        ],
+    },
+    help: { label: '-h, --help', body: () => ['This text.'] },
+    version: { label: '--version', body: () => ['The package version.'] },
+};
+/**
+ * `--budget` has no built-in default, for the same reason `smelt()` has none: a budget
+ * smelt invented would be smelt deciding how much of the caller's context to throw
+ * away, silently, at a number nobody chose. A *missing* flag is not an error here,
+ * though — `smelt.config.json` may carry a `defaultBudgetBytes` the user chose
+ * explicitly, and the verb's `resolve` errors only when neither exists. A malformed
+ * value is always an error.
+ *
+ * It lives with the flag rather than with a verb because two verbs own `--budget`, and
+ * the two of them agreeing on what "4kb" means is not something to leave to chance.
+ *
+ * The *lexing* is the CLI's own and stays here — argv carries strings, so `4kb` and a
+ * leading `-` are answered by a digits-only test before anything numeric happens. The
+ * *rule* and *the sentence that refuses it* come from `ops/inputs.ts`, which is also
+ * where the `smelt_file` tool gets them: two surfaces, one law, spelled `--budget`
+ * here and `"budgetBytes"` there.
+ */
+export function parseBudget(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        throw refuseBudget('not-an-integer', raw);
+    const value = Number(raw);
+    const fault = budgetFault(value);
+    if (fault !== undefined)
+        throw refuseBudget(fault, raw);
+    return value;
+}
+/** The malformed-budget refusal, in the CLI's currency: prefixed, and exit 2. */
+function refuseBudget(fault, raw) {
+    return new CliUsageError(`${CLI_NAME}: ${budgetMalformed(fault, '--budget', raw)}`);
+}
+//# sourceMappingURL=flags.js.map