@smeltjs/core 0.2.0 → 0.4.0

package/dist/cli/subcommands/map.js

@@ -0,0 +1,132 @@
+import { CliUsageError } from '../../errors.js';
+import { budgetRequired, readTree } from '../../ops/inputs.js';
+import { mapTree } from '../../ops/verbs.js';
+import { CONFIG_FILE_NAME } from '../config.js';
+import { formatMapReport } from '../report.js';
+import { CLI_NAME, EXIT } from '../shell.js';
+import { parseBudget } from './flags.js';
+/**
+ * The `smelt map --json` envelope format. Its own version line, because the two
+ * envelopes carry different structures and must be able to move independently —
+ * a map envelope has no elided bytes to carry, since a map elides nothing.
+ */
+export const CLI_MAP_JSON_FORMAT = 'smelt-map-cli/v1';
+export const mapCommand = {
+    name: 'map',
+    flags: ['budget', 'focus', 'ignore', 'cache', 'json'],
+    refusal: `map reads a whole tree, detects each file's language itself, and is not a planner ` +
+        `strategy — it returns a map, not an elision plan, and elides nothing, so there is ` +
+        `nothing to put back.`,
+    usage: {
+        synopsis: [
+            'map <dir> --budget <bytes> [--focus <term>]... [--ignore <entry>]... [--cache <dir>]',
+        ],
+        section: {
+            heading: 'MAP',
+            body: `  ${CLI_NAME} map <dir> renders a ranked symbol map of a whole repository — modelled\n` +
+                `  on Aider's repo-map (aider.chat/docs/repomap.html, design by Paul Gauthier) — to\n` +
+                `  stdout, with a short report on stderr. Local files only: symlinks are never\n` +
+                `  followed, binary files are skipped, and the map writes nothing to disk unless\n` +
+                `  --cache names a directory. Every included symbol carries a receipt: its\n` +
+                `  definition site and the measured reference counts that ranked it. Unlike a\n` +
+                `  smelt run, map never exits\n` +
+                `  1: a plan can come back over budget because ${CLI_NAME} refuses to cut regions you\n` +
+                `  asked to keep, but the map fits itself to the budget by construction — symbols\n` +
+                `  are appended in rank order until the next line would not fit.`,
+        },
+    },
+    /**
+     * Exactly one directory, and the same budget rules as everywhere else — a missing
+     * `--budget` is not an error *here* (the config may carry `defaultBudgetBytes`), a
+     * malformed one always is.
+     */
+    parse(values, positionals) {
+        if (positionals.length < 2) {
+            throw new CliUsageError(`${CLI_NAME}: map needs the directory to read.\n` +
+                `  ${CLI_NAME} map <dir> --budget <bytes> [--focus <term>]...`);
+        }
+        if (positionals.length > 2) {
+            throw new CliUsageError(`${CLI_NAME}: map takes exactly one directory, got ` +
+                `${String(positionals.length - 1)} (${positionals.slice(1).join(', ')}).`);
+        }
+        const budgetBytes = parseBudget(values.budget);
+        return {
+            mode: 'map',
+            dir: positionals[1],
+            ...(budgetBytes === undefined ? {} : { budgetBytes }),
+            focus: values.focus ?? [],
+            ignore: values.ignore ?? [],
+            ...(values.cache === undefined ? {} : { cacheDir: values.cache }),
+            json: values.json === true,
+        };
+    },
+    resolve(invocation, config) {
+        return resolveMapRun(invocation, config());
+    },
+    run(resolved, io) {
+        return runMap(resolved, io);
+    },
+};
+/**
+ * Merge one `'map'`-mode invocation with the loaded config and the built-ins. The
+ * config contributes exactly what it contributes to a smelt run — `defaultBudgetBytes`,
+ * a default the user chose explicitly — and nothing else: the store and strategy legs
+ * are single-blob concerns, and the map ignores them rather than reinterpreting them.
+ *
+ * @throws {CliUsageError} when neither `--budget` nor the config names a budget.
+ */
+export function resolveMapRun(invocation, config) {
+    const budgetBytes = invocation.budgetBytes ?? config?.config.defaultBudgetBytes;
+    if (budgetBytes === undefined) {
+        throw new CliUsageError(`${CLI_NAME}: ` +
+            budgetRequired({
+                knob: '--budget',
+                stake: 'the map to leave out',
+                advice: `Pass --budget, or set defaultBudgetBytes in ${CONFIG_FILE_NAME} ` +
+                    `(\`${CLI_NAME} init\` writes one).\n` +
+                    `  ${CLI_NAME} map src --budget 4000 --focus handleRequest`,
+            }));
+    }
+    return {
+        budgetBytes,
+        budgetSource: invocation.budgetBytes !== undefined ? 'flag' : 'config',
+        dir: invocation.dir,
+        focus: invocation.focus,
+        ...(invocation.ignore.length === 0 ? {} : { ignore: invocation.ignore }),
+        ...(invocation.cacheDir === undefined ? {} : { cacheDir: invocation.cacheDir }),
+        json: invocation.json,
+    };
+}
+/**
+ * One `smelt map` run: prove the target is a tree, hand it to {@link mapTree}, render.
+ *
+ * The merge, including the budget-required refusal, lives in {@link resolveMapRun} —
+ * the same arrangement the smelt verb uses over its {@link ResolvedRun}. The walk
+ * itself belongs to no front door: the `repo_map` tool calls the same op, and refuses
+ * a file with the same sentence in its own vocabulary.
+ */
+async function runMap(run, io) {
+    const tree = readTree(run.dir, run.dir, {
+        tree: 'map',
+        file: `\`${CLI_NAME} <file>\``,
+    });
+    if (!tree.ok)
+        throw new CliUsageError(`${CLI_NAME}: ${tree.refusal}`);
+    const map = await mapTree({
+        root: tree.value,
+        budgetBytes: run.budgetBytes,
+        focus: run.focus,
+        ...(run.ignore === undefined ? {} : { ignore: run.ignore }),
+        ...(run.cacheDir === undefined ? {} : { cacheDir: run.cacheDir }),
+    });
+    if (run.json) {
+        const mapEnvelope = { format: CLI_MAP_JSON_FORMAT, map };
+        io.stdout(`${JSON.stringify(mapEnvelope, null, 2)}\n`);
+    }
+    else {
+        io.stdout(map.text);
+    }
+    io.stderr(formatMapReport({ map, source: run.dir, budgetSource: run.budgetSource }));
+    return EXIT.ok;
+}
+//# sourceMappingURL=map.js.map

package/dist/cli/subcommands/map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.js","sourceRoot":"","sources":["../../../src/cli/subcommands/map.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAwDzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAStD,MAAM,CAAC,MAAM,UAAU,GAA8C;IACnE,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC;IACrD,OAAO,EACL,oFAAoF;QACpF,oFAAoF;QACpF,sBAAsB;IACxB,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,sFAAsF;SACvF;QACD,OAAO,EAAE;YACP,OAAO,EAAE,KAAK;YACd,IAAI,EACF,KAAK,QAAQ,2EAA2E;gBACxF,sFAAsF;gBACtF,iFAAiF;gBACjF,mFAAmF;gBACnF,6EAA6E;gBAC7E,gFAAgF;gBAChF,gCAAgC;gBAChC,iDAAiD,QAAQ,+BAA+B;gBACxF,oFAAoF;gBACpF,iEAAiE;SACpE;KACF;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAkB,EAAE,WAA8B;QACtD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,sCAAsC;gBAC/C,KAAK,QAAQ,iDAAiD,CACjE,CAAC;QACJ,CAAC;QACD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,yCAAyC;gBAClD,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC5E,CAAC;QACJ,CAAC;QACD,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC/C,OAAO;YACL,IAAI,EAAE,KAAK;YACX,GAAG,EAAE,WAAW,CAAC,CAAC,CAAE;YACpB,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;YACrD,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YACjE,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,IAAI;SAC3B,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,UAAyB,EAAE,MAAoB;QACrD,OAAO,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,GAAG,CAAC,QAAwB,EAAE,EAAS;QACrC,OAAO,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAyB,EACzB,MAAgC;IAEhC,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,IAAI,MAAM,EAAE,MAAM,CAAC,kBAAkB,CAAC;IAChF,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,aAAa,CACrB,GAAG,QAAQ,IAAI;YACb,cAAc,CAAC;gBACb,IAAI,EAAE,UAAU;gBAChB,KAAK,EAAE,sBAAsB;gBAC7B,MAAM,EACJ,+CAA+C,gBAAgB,GAAG;oBAClE,MAAM,QAAQ,wBAAwB;oBACtC,KAAK,QAAQ,8CAA8C;aAC9D,CAAC,CACL,CAAC;IACJ,CAAC;IAED,OAAO;QACL,WAAW;QACX,YAAY,EAAE,UAAU,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ;QACtE,GAAG,EAAE,UAAU,CAAC,GAAG;QACnB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;QACxE,GAAG,CAAC,UAAU,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC;QAC/E,IAAI,EAAE,UAAU,CAAC,IAAI;KACtB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,MAAM,CAAC,GAAmB,EAAE,EAAS;IAClD,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE;QACtC,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,KAAK,QAAQ,WAAW;KAC/B,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,aAAa,CAAC,GAAG,QAAQ,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAEtE,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC;QACxB,IAAI,EAAE,IAAI,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QAC3D,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;KAClE,CAAC,CAAC;IAEH,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,MAAM,WAAW,GAAuB,EAAE,MAAM,EAAE,mBAAmB,EAAE,GAAG,EAAE,CAAC;QAC7E,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;SAAM,CAAC;QACN,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;IACD,EAAE,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC;IAErF,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC","sourcesContent":["import { CliUsageError } from '../../errors.ts';\nimport { budgetRequired, readTree } from '../../ops/inputs.ts';\nimport { mapTree } from '../../ops/verbs.ts';\nimport type { RepoMap } from '../../repomap/map.ts';\nimport { CONFIG_FILE_NAME } from '../config.ts';\nimport type { LoadedConfig } from '../config.ts';\nimport { formatMapReport } from '../report.ts';\nimport { CLI_NAME, EXIT } from '../shell.ts';\nimport type { CliIo } from '../shell.ts';\n\nimport { parseBudget } from './flags.ts';\nimport type { FlagValues } from './flags.ts';\nimport type { ConfigSource, Subcommand } from './subcommand.ts';\n\n/**\n * `smelt map <dir>` — the repo map's front door.\n *\n * Deliberately **not** a `--strategy` name: `buildRepoMap` returns a {@link RepoMap},\n * not an `ElisionPlan` — nothing is elided, stored, or reversible — so it gets its own\n * verb and its own envelope instead of a strategy name that would lie about what comes\n * back. And it never exits {@link EXIT.overBudget}: a smelt plan may refuse to cut kept\n * regions and come back too big, while the map fits itself to the budget by\n * construction, so no exit code pretends an over-budget map can happen.\n */\n\n/**\n * `smelt map <dir>` — the repo-map subcommand, parsed. A separate shape rather than\n * more optional fields on `SmeltInvocation`, because the two commands share\n * almost nothing: a map has a directory instead of a file/stdin, an ignore list and\n * a cache directory instead of a language and a strategy.\n */\nexport interface MapInvocation {\n  readonly mode: 'map';\n  /** The repository root to map. Always present — `map` without a directory is a usage error. */\n  readonly dir: string;\n  /** `undefined` means the flag was not given — the config default may apply. */\n  readonly budgetBytes?: number;\n  readonly focus: readonly string[];\n  /** `--ignore` entries, replacing the built-in default list when non-empty. */\n  readonly ignore: readonly string[];\n  /** `--cache <dir>`: only when given does the map write to disk. */\n  readonly cacheDir?: string;\n  readonly json: boolean;\n}\n\n/**\n * Everything one `smelt map` run needs, fully merged — {@link ResolvedRun}'s sibling,\n * not a contortion of it. The two commands share exactly one merged value (the\n * budget), so they share the *seam* that owns precedence — every verb resolving its\n * own flags against the same config — not a struct whose fields would mostly be lies\n * for one of them: a map has no store, no strategy, no stdin, and its ignore/cache\n * legs mean nothing to a single-blob run.\n */\nexport interface ResolvedMapRun {\n  readonly budgetBytes: number;\n  /** Where the budget came from. A missing budget never gets here — it throws. */\n  readonly budgetSource: 'flag' | 'config';\n  readonly dir: string;\n  readonly focus: readonly string[];\n  /** `undefined` means \"use the library's default ignore list\". Flags only. */\n  readonly ignore?: readonly string[];\n  /** Only when present does the map write to disk. Flags only; the config has no say. */\n  readonly cacheDir?: string;\n  readonly json: boolean;\n}\n\n/**\n * The `smelt map --json` envelope format. Its own version line, because the two\n * envelopes carry different structures and must be able to move independently —\n * a map envelope has no elided bytes to carry, since a map elides nothing.\n */\nexport const CLI_MAP_JSON_FORMAT = 'smelt-map-cli/v1';\n\n/** What `smelt map --json` prints: the {@link RepoMap} verbatim, versioned. */\nexport interface CliMapJsonEnvelope {\n  readonly format: string;\n  /** The {@link RepoMap} exactly as `buildRepoMap` returned it. */\n  readonly map: RepoMap;\n}\n\nexport const mapCommand: Subcommand<MapInvocation, ResolvedMapRun> = {\n  name: 'map',\n  flags: ['budget', 'focus', 'ignore', 'cache', 'json'],\n  refusal:\n    `map reads a whole tree, detects each file's language itself, and is not a planner ` +\n    `strategy — it returns a map, not an elision plan, and elides nothing, so there is ` +\n    `nothing to put back.`,\n  usage: {\n    synopsis: [\n      'map <dir> --budget <bytes> [--focus <term>]... [--ignore <entry>]... [--cache <dir>]',\n    ],\n    section: {\n      heading: 'MAP',\n      body:\n        `  ${CLI_NAME} map <dir> renders a ranked symbol map of a whole repository — modelled\\n` +\n        `  on Aider's repo-map (aider.chat/docs/repomap.html, design by Paul Gauthier) — to\\n` +\n        `  stdout, with a short report on stderr. Local files only: symlinks are never\\n` +\n        `  followed, binary files are skipped, and the map writes nothing to disk unless\\n` +\n        `  --cache names a directory. Every included symbol carries a receipt: its\\n` +\n        `  definition site and the measured reference counts that ranked it. Unlike a\\n` +\n        `  smelt run, map never exits\\n` +\n        `  1: a plan can come back over budget because ${CLI_NAME} refuses to cut regions you\\n` +\n        `  asked to keep, but the map fits itself to the budget by construction — symbols\\n` +\n        `  are appended in rank order until the next line would not fit.`,\n    },\n  },\n\n  /**\n   * Exactly one directory, and the same budget rules as everywhere else — a missing\n   * `--budget` is not an error *here* (the config may carry `defaultBudgetBytes`), a\n   * malformed one always is.\n   */\n  parse(values: FlagValues, positionals: readonly string[]): MapInvocation {\n    if (positionals.length < 2) {\n      throw new CliUsageError(\n        `${CLI_NAME}: map needs the directory to read.\\n` +\n          `  ${CLI_NAME} map <dir> --budget <bytes> [--focus <term>]...`,\n      );\n    }\n    if (positionals.length > 2) {\n      throw new CliUsageError(\n        `${CLI_NAME}: map takes exactly one directory, got ` +\n          `${String(positionals.length - 1)} (${positionals.slice(1).join(', ')}).`,\n      );\n    }\n    const budgetBytes = parseBudget(values.budget);\n    return {\n      mode: 'map',\n      dir: positionals[1]!,\n      ...(budgetBytes === undefined ? {} : { budgetBytes }),\n      focus: values.focus ?? [],\n      ignore: values.ignore ?? [],\n      ...(values.cache === undefined ? {} : { cacheDir: values.cache }),\n      json: values.json === true,\n    };\n  },\n\n  resolve(invocation: MapInvocation, config: ConfigSource): ResolvedMapRun {\n    return resolveMapRun(invocation, config());\n  },\n\n  run(resolved: ResolvedMapRun, io: CliIo): Promise<number> {\n    return runMap(resolved, io);\n  },\n};\n\n/**\n * Merge one `'map'`-mode invocation with the loaded config and the built-ins. The\n * config contributes exactly what it contributes to a smelt run — `defaultBudgetBytes`,\n * a default the user chose explicitly — and nothing else: the store and strategy legs\n * are single-blob concerns, and the map ignores them rather than reinterpreting them.\n *\n * @throws {CliUsageError} when neither `--budget` nor the config names a budget.\n */\nexport function resolveMapRun(\n  invocation: MapInvocation,\n  config: LoadedConfig | undefined,\n): ResolvedMapRun {\n  const budgetBytes = invocation.budgetBytes ?? config?.config.defaultBudgetBytes;\n  if (budgetBytes === undefined) {\n    throw new CliUsageError(\n      `${CLI_NAME}: ` +\n        budgetRequired({\n          knob: '--budget',\n          stake: 'the map to leave out',\n          advice:\n            `Pass --budget, or set defaultBudgetBytes in ${CONFIG_FILE_NAME} ` +\n            `(\\`${CLI_NAME} init\\` writes one).\\n` +\n            `  ${CLI_NAME} map src --budget 4000 --focus handleRequest`,\n        }),\n    );\n  }\n\n  return {\n    budgetBytes,\n    budgetSource: invocation.budgetBytes !== undefined ? 'flag' : 'config',\n    dir: invocation.dir,\n    focus: invocation.focus,\n    ...(invocation.ignore.length === 0 ? {} : { ignore: invocation.ignore }),\n    ...(invocation.cacheDir === undefined ? {} : { cacheDir: invocation.cacheDir }),\n    json: invocation.json,\n  };\n}\n\n/**\n * One `smelt map` run: prove the target is a tree, hand it to {@link mapTree}, render.\n *\n * The merge, including the budget-required refusal, lives in {@link resolveMapRun} —\n * the same arrangement the smelt verb uses over its {@link ResolvedRun}. The walk\n * itself belongs to no front door: the `repo_map` tool calls the same op, and refuses\n * a file with the same sentence in its own vocabulary.\n */\nasync function runMap(run: ResolvedMapRun, io: CliIo): Promise<number> {\n  const tree = readTree(run.dir, run.dir, {\n    tree: 'map',\n    file: `\\`${CLI_NAME} <file>\\``,\n  });\n  if (!tree.ok) throw new CliUsageError(`${CLI_NAME}: ${tree.refusal}`);\n\n  const map = await mapTree({\n    root: tree.value,\n    budgetBytes: run.budgetBytes,\n    focus: run.focus,\n    ...(run.ignore === undefined ? {} : { ignore: run.ignore }),\n    ...(run.cacheDir === undefined ? {} : { cacheDir: run.cacheDir }),\n  });\n\n  if (run.json) {\n    const mapEnvelope: CliMapJsonEnvelope = { format: CLI_MAP_JSON_FORMAT, map };\n    io.stdout(`${JSON.stringify(mapEnvelope, null, 2)}\\n`);\n  } else {\n    io.stdout(map.text);\n  }\n  io.stderr(formatMapReport({ map, source: run.dir, budgetSource: run.budgetSource }));\n\n  return EXIT.ok;\n}\n"]}

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

@@ -0,0 +1,81 @@
+import type { AgentsInvocation } from './agents.ts';
+import type { FlagName, FlagValues } from './flags.ts';
+import type { HooksInvocation } from './hooks.ts';
+import type { InitInvocation } from './init.ts';
+import type { MapInvocation } from './map.ts';
+import type { RetrieveInvocation } from './retrieve.ts';
+import type { SmeltInvocation } from './smelt.ts';
+import type { StatsInvocation } from './stats.ts';
+import type { Subcommand, Verb } from './subcommand.ts';
+/**
+ * The registry — every verb `smelt` answers to, one {@link Subcommand} each.
+ *
+ * `Record<Verb, Subcommand>` on purpose, exactly like `LANGUAGE_PROFILES` and
+ * `HARNESS_PROFILES`: adding a `Verb` in `subcommand.ts` without writing its file is a
+ * compile error, so the verb list and the facts cannot drift. Every derived view — the
+ * USAGE block, the help's sections, the `map only.` prefixes in OPTIONS, and above all
+ * the flag-ownership refusal below — is computed from this object, never written twice.
+ *
+ * Key order is meaningful: it is the order every rendered list uses (USAGE, the help
+ * sections, the owners named in a refusal), so keep it stable and append new verbs at
+ * the end.
+ */
+export declare const SUBCOMMANDS: Readonly<Record<Verb, AnySubcommand>>;
+/** Everything `parseSmeltArgs` can return. Narrow on `mode`. */
+export type CliInvocation = SmeltInvocation | InitInvocation | MapInvocation | RetrieveInvocation | StatsInvocation | HooksInvocation | AgentsInvocation;
+/**
+ * One registry entry, with its verb's own invocation and resolved types erased.
+ *
+ * The erasure is what lets six differently-typed commands live in one `Record`, and it
+ * is safe because the two ends are never crossed: `runCli` hands a command exactly the
+ * invocation that command's own `parse` produced (`verbFor` maps each `mode` back to
+ * the verb that minted it), and the resolved value never leaves the pair of calls that
+ * makes and consumes it.
+ */
+export type AnySubcommand = Subcommand<CliInvocation, unknown>;
+/** Every command, in registry order. The list every rendered block walks. */
+export declare const SUBCOMMAND_LIST: readonly AnySubcommand[];
+/**
+ * The verbs with a word on the command line — everything but the default one.
+ *
+ * The default verb is excluded deliberately: `smelt smelt` is a file named `smelt`,
+ * not a recursive invocation, the same way `smelt map` as a *file* needs `./map`.
+ */
+export declare const NAMED_VERBS: readonly Verb[];
+/**
+ * Which command a command line selects: `positionals[0]` when it names a verb, the
+ * default verb otherwise. The whole of subcommand dispatch, in one lookup.
+ */
+export declare function subcommandFor(positionals: readonly string[]): AnySubcommand;
+/** The command that produced an invocation, for dispatch. */
+export declare function commandFor(mode: Exclude<CliInvocation['mode'], 'help' | 'version'>): AnySubcommand;
+/**
+ * The commands that own a flag, in registry order — empty for the two global flags,
+ * which no verb owns. A flag with exactly one owner has an unambiguous home worth
+ * naming in a refusal (and worth prefixing its OPTIONS entry with); a flag several
+ * verbs share (`--json`, `--budget`, `--focus`) has none, and pointing at one of them
+ * would be a guess.
+ */
+export declare function ownersOf(flag: FlagName): readonly AnySubcommand[];
+/**
+ * Refuse every flag the chosen verb does not own — the one message that replaced five
+ * hand-written ones.
+ *
+ * Before this existed, each verb refused each other verb's flags in prose, so the
+ * refusals were O(verbs × flags) sentences kept in sync by hand and an eleventh flag
+ * edited five of them. Now ownership is declared once per verb and the message is
+ * generated from three derived facts, in the order a reader needs them:
+ *
+ *   1. **what this verb takes**, and what it got instead — the offending flag, named;
+ *   2. **where the flag does belong**, when exactly one verb owns it, listed as that
+ *      owner's *exclusively* owned flags (so `--ignore` here still reads "--ignore and
+ *      --cache belong to `smelt map`", exactly as the hand-written message did);
+ *   3. **why not here** — the verb's own `refusal` sentence, the half of the old
+ *      messages worth keeping, and the only half a verb still writes.
+ *
+ * Every refusal stays a {@link CliUsageError}, so every one of them still exits 2.
+ *
+ * @throws {CliUsageError} naming the offending flag, this verb, and the flag's owner.
+ */
+export declare function refuseForeignFlags(command: AnySubcommand, values: FlagValues): void;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/cli/subcommands/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAQ7D,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,cAAc,GACd,aAAa,GACb,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,gBAAgB,CAAC;AAErB;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AAE/D,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAA+B,CAAC;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,IAAI,EAEtC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAI3E;AAmBD,6DAA6D;AAC7D,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,GACvD,aAAa,CAEf;AAYD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,aAAa,EAAE,CAEjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAYnF","sourcesContent":["import { CliUsageError } from '../../errors.ts';\nimport { CLI_NAME } from '../shell.ts';\n\nimport { agentsCommand } from './agents.ts';\nimport type { AgentsInvocation } from './agents.ts';\nimport { flagList, VERB_FLAGS } from './flags.ts';\nimport type { FlagName, FlagValues, VerbFlag } from './flags.ts';\nimport { hooksCommand } from './hooks.ts';\nimport type { HooksInvocation } from './hooks.ts';\nimport { initCommand } from './init.ts';\nimport type { InitInvocation } from './init.ts';\nimport { mapCommand } from './map.ts';\nimport type { MapInvocation } from './map.ts';\nimport { retrieveCommand } from './retrieve.ts';\nimport type { RetrieveInvocation } from './retrieve.ts';\nimport { smeltCommand } from './smelt.ts';\nimport type { SmeltInvocation } from './smelt.ts';\nimport { statsCommand } from './stats.ts';\nimport type { StatsInvocation } from './stats.ts';\nimport { DEFAULT_VERB } from './subcommand.ts';\nimport type { Subcommand, Verb } from './subcommand.ts';\n\n/**\n * The registry — every verb `smelt` answers to, one {@link Subcommand} each.\n *\n * `Record<Verb, Subcommand>` on purpose, exactly like `LANGUAGE_PROFILES` and\n * `HARNESS_PROFILES`: adding a `Verb` in `subcommand.ts` without writing its file is a\n * compile error, so the verb list and the facts cannot drift. Every derived view — the\n * USAGE block, the help's sections, the `map only.` prefixes in OPTIONS, and above all\n * the flag-ownership refusal below — is computed from this object, never written twice.\n *\n * Key order is meaningful: it is the order every rendered list uses (USAGE, the help\n * sections, the owners named in a refusal), so keep it stable and append new verbs at\n * the end.\n */\nexport const SUBCOMMANDS: Readonly<Record<Verb, AnySubcommand>> = {\n  smelt: smeltCommand,\n  init: initCommand,\n  map: mapCommand,\n  retrieve: retrieveCommand,\n  stats: statsCommand,\n  hooks: hooksCommand,\n  agents: agentsCommand,\n};\n\n/** Everything `parseSmeltArgs` can return. Narrow on `mode`. */\nexport type CliInvocation =\n  | SmeltInvocation\n  | InitInvocation\n  | MapInvocation\n  | RetrieveInvocation\n  | StatsInvocation\n  | HooksInvocation\n  | AgentsInvocation;\n\n/**\n * One registry entry, with its verb's own invocation and resolved types erased.\n *\n * The erasure is what lets six differently-typed commands live in one `Record`, and it\n * is safe because the two ends are never crossed: `runCli` hands a command exactly the\n * invocation that command's own `parse` produced (`verbFor` maps each `mode` back to\n * the verb that minted it), and the resolved value never leaves the pair of calls that\n * makes and consumes it.\n */\nexport type AnySubcommand = Subcommand<CliInvocation, unknown>;\n\n/** Every command, in registry order. The list every rendered block walks. */\nexport const SUBCOMMAND_LIST: readonly AnySubcommand[] = Object.values(SUBCOMMANDS);\n\n/**\n * The verbs with a word on the command line — everything but the default one.\n *\n * The default verb is excluded deliberately: `smelt smelt` is a file named `smelt`,\n * not a recursive invocation, the same way `smelt map` as a *file* needs `./map`.\n */\nexport const NAMED_VERBS: readonly Verb[] = SUBCOMMAND_LIST.map((command) => command.name).filter(\n  (name) => name !== DEFAULT_VERB,\n);\n\n/**\n * Which command a command line selects: `positionals[0]` when it names a verb, the\n * default verb otherwise. The whole of subcommand dispatch, in one lookup.\n */\nexport function subcommandFor(positionals: readonly string[]): AnySubcommand {\n  const first = positionals[0];\n  const named = NAMED_VERBS.find((verb) => verb === first);\n  return SUBCOMMANDS[named ?? DEFAULT_VERB];\n}\n\n/**\n * Which verb minted an invocation. Total over the modes `parseSmeltArgs` can return\n * for a verb, so a new mode without a home is a compile error — `'reconstruct'` maps\n * to the default verb because `--reconstruct` is that verb's second job, not a\n * seventh command.\n */\nconst VERB_BY_MODE = {\n  smelt: 'smelt',\n  reconstruct: 'smelt',\n  init: 'init',\n  map: 'map',\n  retrieve: 'retrieve',\n  stats: 'stats',\n  hooks: 'hooks',\n  agents: 'agents',\n} as const satisfies Record<Exclude<CliInvocation['mode'], 'help' | 'version'>, Verb>;\n\n/** The command that produced an invocation, for dispatch. */\nexport function commandFor(\n  mode: Exclude<CliInvocation['mode'], 'help' | 'version'>,\n): AnySubcommand {\n  return SUBCOMMANDS[VERB_BY_MODE[mode]];\n}\n\n/** How a command is named in prose. The default verb has no word to name it by. */\nfunction label(command: AnySubcommand): string {\n  return command.name === DEFAULT_VERB ? 'a single-blob run' : command.name;\n}\n\n/** How a command is named as the *owner* of a flag: the form you would type. */\nfunction ownerLabel(command: AnySubcommand): string {\n  return command.name === DEFAULT_VERB ? 'a single-blob run' : `\\`${CLI_NAME} ${command.name}\\``;\n}\n\n/**\n * The commands that own a flag, in registry order — empty for the two global flags,\n * which no verb owns. A flag with exactly one owner has an unambiguous home worth\n * naming in a refusal (and worth prefixing its OPTIONS entry with); a flag several\n * verbs share (`--json`, `--budget`, `--focus`) has none, and pointing at one of them\n * would be a guess.\n */\nexport function ownersOf(flag: FlagName): readonly AnySubcommand[] {\n  return SUBCOMMAND_LIST.filter((command) => (command.flags as readonly string[]).includes(flag));\n}\n\n/**\n * Refuse every flag the chosen verb does not own — the one message that replaced five\n * hand-written ones.\n *\n * Before this existed, each verb refused each other verb's flags in prose, so the\n * refusals were O(verbs × flags) sentences kept in sync by hand and an eleventh flag\n * edited five of them. Now ownership is declared once per verb and the message is\n * generated from three derived facts, in the order a reader needs them:\n *\n *   1. **what this verb takes**, and what it got instead — the offending flag, named;\n *   2. **where the flag does belong**, when exactly one verb owns it, listed as that\n *      owner's *exclusively* owned flags (so `--ignore` here still reads \"--ignore and\n *      --cache belong to `smelt map`\", exactly as the hand-written message did);\n *   3. **why not here** — the verb's own `refusal` sentence, the half of the old\n *      messages worth keeping, and the only half a verb still writes.\n *\n * Every refusal stays a {@link CliUsageError}, so every one of them still exits 2.\n *\n * @throws {CliUsageError} naming the offending flag, this verb, and the flag's owner.\n */\nexport function refuseForeignFlags(command: AnySubcommand, values: FlagValues): void {\n  const foreign = VERB_FLAGS.filter(\n    (flag) => values[flag] !== undefined && !command.flags.includes(flag),\n  );\n  if (foreign.length === 0) return;\n\n  const takes =\n    command.flags.length === 0\n      ? `${label(command)} takes no flags (got ${flagList(foreign)}).`\n      : `${label(command)} takes only ${flagList(command.flags)} (got ${flagList(foreign)}).`;\n\n  throw new CliUsageError(`${CLI_NAME}: ${takes}${redirects(foreign)} ${command.refusal}`);\n}\n\n/**\n * ` --ignore and --cache belong to \\`smelt map\\`.` — one clause per single-owner verb.\n *\n * A clause names only the flags its owner owns **alone**, never the ones it shares.\n * `ownersOf(flag).length === 1` is the same test that decided the owner deserved a\n * clause at all, applied to the whole clause: a shared flag (`--budget`, `--focus`,\n * `--json`) has no single home, so naming it here would assert an ownership that the\n * OPTIONS block — which prefixes `map only.` by the same rule — correctly denies.\n */\nfunction redirects(foreign: readonly VerbFlag[]): string {\n  const owners = SUBCOMMAND_LIST.filter((owner) =>\n    foreign.some((flag) => {\n      const claimants = ownersOf(flag);\n      return claimants.length === 1 && claimants[0] === owner;\n    }),\n  );\n  return owners\n    .map((owner) => {\n      const elsewhere = owner.flags.filter((flag) => ownersOf(flag).length === 1);\n      const verb = elsewhere.length === 1 ? 'belongs' : 'belong';\n      return ` ${flagList(elsewhere)} ${verb} to ${ownerLabel(owner)}.`;\n    })\n    .join('');\n}\n"]}

package/dist/cli/subcommands/registry.js

@@ -0,0 +1,141 @@
+import { CliUsageError } from '../../errors.js';
+import { CLI_NAME } from '../shell.js';
+import { agentsCommand } from './agents.js';
+import { flagList, VERB_FLAGS } from './flags.js';
+import { hooksCommand } from './hooks.js';
+import { initCommand } from './init.js';
+import { mapCommand } from './map.js';
+import { retrieveCommand } from './retrieve.js';
+import { smeltCommand } from './smelt.js';
+import { statsCommand } from './stats.js';
+import { DEFAULT_VERB } from './subcommand.js';
+/**
+ * The registry — every verb `smelt` answers to, one {@link Subcommand} each.
+ *
+ * `Record<Verb, Subcommand>` on purpose, exactly like `LANGUAGE_PROFILES` and
+ * `HARNESS_PROFILES`: adding a `Verb` in `subcommand.ts` without writing its file is a
+ * compile error, so the verb list and the facts cannot drift. Every derived view — the
+ * USAGE block, the help's sections, the `map only.` prefixes in OPTIONS, and above all
+ * the flag-ownership refusal below — is computed from this object, never written twice.
+ *
+ * Key order is meaningful: it is the order every rendered list uses (USAGE, the help
+ * sections, the owners named in a refusal), so keep it stable and append new verbs at
+ * the end.
+ */
+export const SUBCOMMANDS = {
+    smelt: smeltCommand,
+    init: initCommand,
+    map: mapCommand,
+    retrieve: retrieveCommand,
+    stats: statsCommand,
+    hooks: hooksCommand,
+    agents: agentsCommand,
+};
+/** Every command, in registry order. The list every rendered block walks. */
+export const SUBCOMMAND_LIST = Object.values(SUBCOMMANDS);
+/**
+ * The verbs with a word on the command line — everything but the default one.
+ *
+ * The default verb is excluded deliberately: `smelt smelt` is a file named `smelt`,
+ * not a recursive invocation, the same way `smelt map` as a *file* needs `./map`.
+ */
+export const NAMED_VERBS = SUBCOMMAND_LIST.map((command) => command.name).filter((name) => name !== DEFAULT_VERB);
+/**
+ * Which command a command line selects: `positionals[0]` when it names a verb, the
+ * default verb otherwise. The whole of subcommand dispatch, in one lookup.
+ */
+export function subcommandFor(positionals) {
+    const first = positionals[0];
+    const named = NAMED_VERBS.find((verb) => verb === first);
+    return SUBCOMMANDS[named ?? DEFAULT_VERB];
+}
+/**
+ * Which verb minted an invocation. Total over the modes `parseSmeltArgs` can return
+ * for a verb, so a new mode without a home is a compile error — `'reconstruct'` maps
+ * to the default verb because `--reconstruct` is that verb's second job, not a
+ * seventh command.
+ */
+const VERB_BY_MODE = {
+    smelt: 'smelt',
+    reconstruct: 'smelt',
+    init: 'init',
+    map: 'map',
+    retrieve: 'retrieve',
+    stats: 'stats',
+    hooks: 'hooks',
+    agents: 'agents',
+};
+/** The command that produced an invocation, for dispatch. */
+export function commandFor(mode) {
+    return SUBCOMMANDS[VERB_BY_MODE[mode]];
+}
+/** How a command is named in prose. The default verb has no word to name it by. */
+function label(command) {
+    return command.name === DEFAULT_VERB ? 'a single-blob run' : command.name;
+}
+/** How a command is named as the *owner* of a flag: the form you would type. */
+function ownerLabel(command) {
+    return command.name === DEFAULT_VERB ? 'a single-blob run' : `\`${CLI_NAME} ${command.name}\``;
+}
+/**
+ * The commands that own a flag, in registry order — empty for the two global flags,
+ * which no verb owns. A flag with exactly one owner has an unambiguous home worth
+ * naming in a refusal (and worth prefixing its OPTIONS entry with); a flag several
+ * verbs share (`--json`, `--budget`, `--focus`) has none, and pointing at one of them
+ * would be a guess.
+ */
+export function ownersOf(flag) {
+    return SUBCOMMAND_LIST.filter((command) => command.flags.includes(flag));
+}
+/**
+ * Refuse every flag the chosen verb does not own — the one message that replaced five
+ * hand-written ones.
+ *
+ * Before this existed, each verb refused each other verb's flags in prose, so the
+ * refusals were O(verbs × flags) sentences kept in sync by hand and an eleventh flag
+ * edited five of them. Now ownership is declared once per verb and the message is
+ * generated from three derived facts, in the order a reader needs them:
+ *
+ *   1. **what this verb takes**, and what it got instead — the offending flag, named;
+ *   2. **where the flag does belong**, when exactly one verb owns it, listed as that
+ *      owner's *exclusively* owned flags (so `--ignore` here still reads "--ignore and
+ *      --cache belong to `smelt map`", exactly as the hand-written message did);
+ *   3. **why not here** — the verb's own `refusal` sentence, the half of the old
+ *      messages worth keeping, and the only half a verb still writes.
+ *
+ * Every refusal stays a {@link CliUsageError}, so every one of them still exits 2.
+ *
+ * @throws {CliUsageError} naming the offending flag, this verb, and the flag's owner.
+ */
+export function refuseForeignFlags(command, values) {
+    const foreign = VERB_FLAGS.filter((flag) => values[flag] !== undefined && !command.flags.includes(flag));
+    if (foreign.length === 0)
+        return;
+    const takes = command.flags.length === 0
+        ? `${label(command)} takes no flags (got ${flagList(foreign)}).`
+        : `${label(command)} takes only ${flagList(command.flags)} (got ${flagList(foreign)}).`;
+    throw new CliUsageError(`${CLI_NAME}: ${takes}${redirects(foreign)} ${command.refusal}`);
+}
+/**
+ * ` --ignore and --cache belong to \`smelt map\`.` — one clause per single-owner verb.
+ *
+ * A clause names only the flags its owner owns **alone**, never the ones it shares.
+ * `ownersOf(flag).length === 1` is the same test that decided the owner deserved a
+ * clause at all, applied to the whole clause: a shared flag (`--budget`, `--focus`,
+ * `--json`) has no single home, so naming it here would assert an ownership that the
+ * OPTIONS block — which prefixes `map only.` by the same rule — correctly denies.
+ */
+function redirects(foreign) {
+    const owners = SUBCOMMAND_LIST.filter((owner) => foreign.some((flag) => {
+        const claimants = ownersOf(flag);
+        return claimants.length === 1 && claimants[0] === owner;
+    }));
+    return owners
+        .map((owner) => {
+        const elsewhere = owner.flags.filter((flag) => ownersOf(flag).length === 1);
+        const verb = elsewhere.length === 1 ? 'belongs' : 'belong';
+        return ` ${flagList(elsewhere)} ${verb} to ${ownerLabel(owner)}.`;
+    })
+        .join('');
+}
+//# sourceMappingURL=registry.js.map

package/dist/cli/subcommands/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/cli/subcommands/registry.ts"],"names":[],"mappings":"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","sourcesContent":["import { CliUsageError } from '../../errors.ts';\nimport { CLI_NAME } from '../shell.ts';\n\nimport { agentsCommand } from './agents.ts';\nimport type { AgentsInvocation } from './agents.ts';\nimport { flagList, VERB_FLAGS } from './flags.ts';\nimport type { FlagName, FlagValues, VerbFlag } from './flags.ts';\nimport { hooksCommand } from './hooks.ts';\nimport type { HooksInvocation } from './hooks.ts';\nimport { initCommand } from './init.ts';\nimport type { InitInvocation } from './init.ts';\nimport { mapCommand } from './map.ts';\nimport type { MapInvocation } from './map.ts';\nimport { retrieveCommand } from './retrieve.ts';\nimport type { RetrieveInvocation } from './retrieve.ts';\nimport { smeltCommand } from './smelt.ts';\nimport type { SmeltInvocation } from './smelt.ts';\nimport { statsCommand } from './stats.ts';\nimport type { StatsInvocation } from './stats.ts';\nimport { DEFAULT_VERB } from './subcommand.ts';\nimport type { Subcommand, Verb } from './subcommand.ts';\n\n/**\n * The registry — every verb `smelt` answers to, one {@link Subcommand} each.\n *\n * `Record<Verb, Subcommand>` on purpose, exactly like `LANGUAGE_PROFILES` and\n * `HARNESS_PROFILES`: adding a `Verb` in `subcommand.ts` without writing its file is a\n * compile error, so the verb list and the facts cannot drift. Every derived view — the\n * USAGE block, the help's sections, the `map only.` prefixes in OPTIONS, and above all\n * the flag-ownership refusal below — is computed from this object, never written twice.\n *\n * Key order is meaningful: it is the order every rendered list uses (USAGE, the help\n * sections, the owners named in a refusal), so keep it stable and append new verbs at\n * the end.\n */\nexport const SUBCOMMANDS: Readonly<Record<Verb, AnySubcommand>> = {\n  smelt: smeltCommand,\n  init: initCommand,\n  map: mapCommand,\n  retrieve: retrieveCommand,\n  stats: statsCommand,\n  hooks: hooksCommand,\n  agents: agentsCommand,\n};\n\n/** Everything `parseSmeltArgs` can return. Narrow on `mode`. */\nexport type CliInvocation =\n  | SmeltInvocation\n  | InitInvocation\n  | MapInvocation\n  | RetrieveInvocation\n  | StatsInvocation\n  | HooksInvocation\n  | AgentsInvocation;\n\n/**\n * One registry entry, with its verb's own invocation and resolved types erased.\n *\n * The erasure is what lets six differently-typed commands live in one `Record`, and it\n * is safe because the two ends are never crossed: `runCli` hands a command exactly the\n * invocation that command's own `parse` produced (`verbFor` maps each `mode` back to\n * the verb that minted it), and the resolved value never leaves the pair of calls that\n * makes and consumes it.\n */\nexport type AnySubcommand = Subcommand<CliInvocation, unknown>;\n\n/** Every command, in registry order. The list every rendered block walks. */\nexport const SUBCOMMAND_LIST: readonly AnySubcommand[] = Object.values(SUBCOMMANDS);\n\n/**\n * The verbs with a word on the command line — everything but the default one.\n *\n * The default verb is excluded deliberately: `smelt smelt` is a file named `smelt`,\n * not a recursive invocation, the same way `smelt map` as a *file* needs `./map`.\n */\nexport const NAMED_VERBS: readonly Verb[] = SUBCOMMAND_LIST.map((command) => command.name).filter(\n  (name) => name !== DEFAULT_VERB,\n);\n\n/**\n * Which command a command line selects: `positionals[0]` when it names a verb, the\n * default verb otherwise. The whole of subcommand dispatch, in one lookup.\n */\nexport function subcommandFor(positionals: readonly string[]): AnySubcommand {\n  const first = positionals[0];\n  const named = NAMED_VERBS.find((verb) => verb === first);\n  return SUBCOMMANDS[named ?? DEFAULT_VERB];\n}\n\n/**\n * Which verb minted an invocation. Total over the modes `parseSmeltArgs` can return\n * for a verb, so a new mode without a home is a compile error — `'reconstruct'` maps\n * to the default verb because `--reconstruct` is that verb's second job, not a\n * seventh command.\n */\nconst VERB_BY_MODE = {\n  smelt: 'smelt',\n  reconstruct: 'smelt',\n  init: 'init',\n  map: 'map',\n  retrieve: 'retrieve',\n  stats: 'stats',\n  hooks: 'hooks',\n  agents: 'agents',\n} as const satisfies Record<Exclude<CliInvocation['mode'], 'help' | 'version'>, Verb>;\n\n/** The command that produced an invocation, for dispatch. */\nexport function commandFor(\n  mode: Exclude<CliInvocation['mode'], 'help' | 'version'>,\n): AnySubcommand {\n  return SUBCOMMANDS[VERB_BY_MODE[mode]];\n}\n\n/** How a command is named in prose. The default verb has no word to name it by. */\nfunction label(command: AnySubcommand): string {\n  return command.name === DEFAULT_VERB ? 'a single-blob run' : command.name;\n}\n\n/** How a command is named as the *owner* of a flag: the form you would type. */\nfunction ownerLabel(command: AnySubcommand): string {\n  return command.name === DEFAULT_VERB ? 'a single-blob run' : `\\`${CLI_NAME} ${command.name}\\``;\n}\n\n/**\n * The commands that own a flag, in registry order — empty for the two global flags,\n * which no verb owns. A flag with exactly one owner has an unambiguous home worth\n * naming in a refusal (and worth prefixing its OPTIONS entry with); a flag several\n * verbs share (`--json`, `--budget`, `--focus`) has none, and pointing at one of them\n * would be a guess.\n */\nexport function ownersOf(flag: FlagName): readonly AnySubcommand[] {\n  return SUBCOMMAND_LIST.filter((command) => (command.flags as readonly string[]).includes(flag));\n}\n\n/**\n * Refuse every flag the chosen verb does not own — the one message that replaced five\n * hand-written ones.\n *\n * Before this existed, each verb refused each other verb's flags in prose, so the\n * refusals were O(verbs × flags) sentences kept in sync by hand and an eleventh flag\n * edited five of them. Now ownership is declared once per verb and the message is\n * generated from three derived facts, in the order a reader needs them:\n *\n *   1. **what this verb takes**, and what it got instead — the offending flag, named;\n *   2. **where the flag does belong**, when exactly one verb owns it, listed as that\n *      owner's *exclusively* owned flags (so `--ignore` here still reads \"--ignore and\n *      --cache belong to `smelt map`\", exactly as the hand-written message did);\n *   3. **why not here** — the verb's own `refusal` sentence, the half of the old\n *      messages worth keeping, and the only half a verb still writes.\n *\n * Every refusal stays a {@link CliUsageError}, so every one of them still exits 2.\n *\n * @throws {CliUsageError} naming the offending flag, this verb, and the flag's owner.\n */\nexport function refuseForeignFlags(command: AnySubcommand, values: FlagValues): void {\n  const foreign = VERB_FLAGS.filter(\n    (flag) => values[flag] !== undefined && !command.flags.includes(flag),\n  );\n  if (foreign.length === 0) return;\n\n  const takes =\n    command.flags.length === 0\n      ? `${label(command)} takes no flags (got ${flagList(foreign)}).`\n      : `${label(command)} takes only ${flagList(command.flags)} (got ${flagList(foreign)}).`;\n\n  throw new CliUsageError(`${CLI_NAME}: ${takes}${redirects(foreign)} ${command.refusal}`);\n}\n\n/**\n * ` --ignore and --cache belong to \\`smelt map\\`.` — one clause per single-owner verb.\n *\n * A clause names only the flags its owner owns **alone**, never the ones it shares.\n * `ownersOf(flag).length === 1` is the same test that decided the owner deserved a\n * clause at all, applied to the whole clause: a shared flag (`--budget`, `--focus`,\n * `--json`) has no single home, so naming it here would assert an ownership that the\n * OPTIONS block — which prefixes `map only.` by the same rule — correctly denies.\n */\nfunction redirects(foreign: readonly VerbFlag[]): string {\n  const owners = SUBCOMMAND_LIST.filter((owner) =>\n    foreign.some((flag) => {\n      const claimants = ownersOf(flag);\n      return claimants.length === 1 && claimants[0] === owner;\n    }),\n  );\n  return owners\n    .map((owner) => {\n      const elsewhere = owner.flags.filter((flag) => ownersOf(flag).length === 1);\n      const verb = elsewhere.length === 1 ? 'belongs' : 'belong';\n      return ` ${flagList(elsewhere)} ${verb} to ${ownerLabel(owner)}.`;\n    })\n    .join('');\n}\n"]}

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

@@ -0,0 +1,74 @@
+import type { LoadedConfig } from '../config.ts';
+import type { Subcommand } from './subcommand.ts';
+/**
+ * `smelt retrieve <hash>` — the marker's `retrieve("hash")`, as a real command.
+ *
+ * The exact original bytes go to stdout and **nothing else does**: no report, no
+ * trailing newline the store did not hold, no re-encoding. Trailing-newline fidelity
+ * is not pedantry — the retrieved bytes get spliced back into reasoning about the
+ * original, and an almost-right blob is the silent wrong answer this project refuses.
+ *
+ * The retrieval IS counted — that is the point. `store.retrieve()` journals the hit,
+ * so an agent working from pure shell moves the same `expansionRate` a tool-calling
+ * consumer moves, and over-pruning stays visible whichever loop is in use. Errors are
+ * the store's own, verbatim: `UnknownHashError` for a hash never elided,
+ * `StoreCorruptionError` for bytes that no longer hash to their name — distinct
+ * texts, both exiting {@link EXIT.refused}.
+ */
+/**
+ * `smelt retrieve <hash>` — parsed. A sibling shape, not a field on somebody else's:
+ * nothing but the hash, because the command's whole contract is "hash in, exact bytes
+ * out" — the same contract as the `smelt_retrieve` tool, reachable from a shell.
+ */
+export interface RetrieveInvocation {
+    readonly mode: 'retrieve';
+    /** The hash exactly as the marker printed it. Validated by the store, not here. */
+    readonly hash: string;
+}
+/**
+ * Everything `smelt retrieve` and `smelt stats` need from the config, fully merged:
+ * the persistent store's directory, already resolved against the config file. The
+ * third `Resolved*Run`, and the only one two verbs share — because they share the
+ * whole of it: no budget, no strategy, no file leg at all, only the store leg, which
+ * is config-only. `stats` resolves through {@link resolveStoreRun} rather than
+ * restating it.
+ */
+export interface ResolvedStoreRun {
+    /** Absolute path of the directory store, resolved against the config file. */
+    readonly storePath: string;
+}
+/**
+ * What `retrieve` runs on: the shared store leg, plus the hash this invocation named.
+ * A composition rather than a wider {@link ResolvedStoreRun}, because `stats` shares
+ * the store leg and has no hash — a field that is meaningless for half its users is
+ * how a shared struct starts lying.
+ */
+export interface ResolvedRetrieveRun {
+    readonly store: ResolvedStoreRun;
+    readonly hash: string;
+}
+export declare const retrieveCommand: Subcommand<RetrieveInvocation, ResolvedRetrieveRun>;
+/**
+ * The store leg alone, for the two commands whose entire job is the store between
+ * runs. The refusal is the point: `retrieve` exists so the marker's
+ * `retrieve("hash")` works from a later shell — cross-run retrieval — and a memory
+ * store dies with the process that filled it, so with a memory store (or no config
+ * at all) there is nothing those commands could honestly read. Answering with
+ * `UnknownHashError` or all-zero stats instead would be the quiet wrong answer this
+ * project refuses everywhere: the hash *was* elided, the counters *did* move — in a
+ * store that no longer exists.
+ *
+ * **This is a policy, not a law, which is why it stays here and is not exported.** The
+ * shared half — a config's store decision (`configuredStore`) and opening it
+ * (`openStore` in `ops/inputs.ts`) — is what every consumer needs and now what every
+ * consumer imports. This function is the CLI's ruling *on top of* that decision, and
+ * the MCP server deliberately rules the other way: it accepts a memory store, serves
+ * the whole session from it, and says how to get persistence at the moment an unknown
+ * hash makes the difference visible. Exporting this would offer that server the CLI's
+ * refusal wearing the name of a shared law — the fork this seam exists to end, running
+ * in the other direction.
+ *
+ * @throws {CliUsageError} when no config exists, or the configured store is memory.
+ */
+export declare function resolveStoreRun(command: 'retrieve' | 'stats', config: LoadedConfig | undefined): ResolvedStoreRun;
+//# sourceMappingURL=retrieve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/cli/subcommands/retrieve.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKjD,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AAEH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,eAAe,EAAE,UAAU,CAAC,kBAAkB,EAAE,mBAAmB,CAgD/E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,UAAU,GAAG,OAAO,EAC7B,MAAM,EAAE,YAAY,GAAG,SAAS,GAC/B,gBAAgB,CAgBlB","sourcesContent":["import { CliUsageError } from '../../errors.ts';\nimport { openStore } from '../../ops/inputs.ts';\nimport { retrieveBytes } from '../../ops/verbs.ts';\nimport { CONFIG_FILE_NAME, configuredStore } from '../config.ts';\nimport type { LoadedConfig } from '../config.ts';\nimport { CLI_NAME, EXIT } from '../shell.ts';\nimport type { CliIo } from '../shell.ts';\n\nimport type { FlagValues } from './flags.ts';\nimport type { ConfigSource, Subcommand } from './subcommand.ts';\n\n/**\n * `smelt retrieve <hash>` — the marker's `retrieve(\"hash\")`, as a real command.\n *\n * The exact original bytes go to stdout and **nothing else does**: no report, no\n * trailing newline the store did not hold, no re-encoding. Trailing-newline fidelity\n * is not pedantry — the retrieved bytes get spliced back into reasoning about the\n * original, and an almost-right blob is the silent wrong answer this project refuses.\n *\n * The retrieval IS counted — that is the point. `store.retrieve()` journals the hit,\n * so an agent working from pure shell moves the same `expansionRate` a tool-calling\n * consumer moves, and over-pruning stays visible whichever loop is in use. Errors are\n * the store's own, verbatim: `UnknownHashError` for a hash never elided,\n * `StoreCorruptionError` for bytes that no longer hash to their name — distinct\n * texts, both exiting {@link EXIT.refused}.\n */\n\n/**\n * `smelt retrieve <hash>` — parsed. A sibling shape, not a field on somebody else's:\n * nothing but the hash, because the command's whole contract is \"hash in, exact bytes\n * out\" — the same contract as the `smelt_retrieve` tool, reachable from a shell.\n */\nexport interface RetrieveInvocation {\n  readonly mode: 'retrieve';\n  /** The hash exactly as the marker printed it. Validated by the store, not here. */\n  readonly hash: string;\n}\n\n/**\n * Everything `smelt retrieve` and `smelt stats` need from the config, fully merged:\n * the persistent store's directory, already resolved against the config file. The\n * third `Resolved*Run`, and the only one two verbs share — because they share the\n * whole of it: no budget, no strategy, no file leg at all, only the store leg, which\n * is config-only. `stats` resolves through {@link resolveStoreRun} rather than\n * restating it.\n */\nexport interface ResolvedStoreRun {\n  /** Absolute path of the directory store, resolved against the config file. */\n  readonly storePath: string;\n}\n\n/**\n * What `retrieve` runs on: the shared store leg, plus the hash this invocation named.\n * A composition rather than a wider {@link ResolvedStoreRun}, because `stats` shares\n * the store leg and has no hash — a field that is meaningless for half its users is\n * how a shared struct starts lying.\n */\nexport interface ResolvedRetrieveRun {\n  readonly store: ResolvedStoreRun;\n  readonly hash: string;\n}\n\nexport const retrieveCommand: Subcommand<RetrieveInvocation, ResolvedRetrieveRun> = {\n  name: 'retrieve',\n  flags: [],\n  refusal:\n    `retrieve prints the exact original bytes for one hash, nothing else — even ` +\n    `--json would wrap what must come back verbatim.`,\n  usage: {\n    synopsis: ['retrieve <hash>'],\n    section: {\n      heading: 'RETRIEVE & STATS',\n      body:\n        `  Every marker carries the hash of the bytes it replaced — <<smelt/v1: … —\\n` +\n        `  retrieve(\"hash\")>> — and the marker's retrieve(\"hash\") is this command:\\n` +\n        `  ${CLI_NAME} retrieve <hash> prints the exact original bytes on stdout, byte for\\n` +\n        `  byte, nothing else. That closes the loop from pure shell: an agent that got a\\n` +\n        `  marker asks for the bytes back with a command instead of a tool call, and the\\n` +\n        `  retrieval is counted — asking for material back is exactly what the expansion\\n` +\n        `  rate measures. An unknown hash and damaged bytes are distinct refusals (exit 3):\\n` +\n        `  \"never elided\" and \"the store was corrupted\" call for different responses.`,\n    },\n  },\n\n  /**\n   * The hash and nothing else. Every flag is refused by the registry's one generated\n   * message rather than ignored — the command prints the exact original bytes on\n   * stdout and nothing more, so a flag that changed the output would break the one\n   * contract it has, and a flag silently dropped would be a setting the user believed\n   * was in force.\n   */\n  parse(_values: FlagValues, positionals: readonly string[]): RetrieveInvocation {\n    if (positionals.length !== 2) {\n      throw new CliUsageError(\n        `${CLI_NAME}: retrieve needs exactly one hash — the one a marker printed.\\n` +\n          `  ${CLI_NAME} retrieve 84998967370f38bc`,\n      );\n    }\n    return { mode: 'retrieve', hash: positionals[1]! };\n  },\n\n  resolve(invocation: RetrieveInvocation, config: ConfigSource): ResolvedRetrieveRun {\n    return { store: resolveStoreRun('retrieve', config()), hash: invocation.hash };\n  },\n\n  run(resolved: ResolvedRetrieveRun, io: CliIo): number {\n    const store = openStore({ kind: 'directory', path: resolved.store.storePath });\n    io.stdout(retrieveBytes({ store, hash: resolved.hash }));\n    return EXIT.ok;\n  },\n};\n\n/**\n * The store leg alone, for the two commands whose entire job is the store between\n * runs. The refusal is the point: `retrieve` exists so the marker's\n * `retrieve(\"hash\")` works from a later shell — cross-run retrieval — and a memory\n * store dies with the process that filled it, so with a memory store (or no config\n * at all) there is nothing those commands could honestly read. Answering with\n * `UnknownHashError` or all-zero stats instead would be the quiet wrong answer this\n * project refuses everywhere: the hash *was* elided, the counters *did* move — in a\n * store that no longer exists.\n *\n * **This is a policy, not a law, which is why it stays here and is not exported.** The\n * shared half — a config's store decision (`configuredStore`) and opening it\n * (`openStore` in `ops/inputs.ts`) — is what every consumer needs and now what every\n * consumer imports. This function is the CLI's ruling *on top of* that decision, and\n * the MCP server deliberately rules the other way: it accepts a memory store, serves\n * the whole session from it, and says how to get persistence at the moment an unknown\n * hash makes the difference visible. Exporting this would offer that server the CLI's\n * refusal wearing the name of a shared law — the fork this seam exists to end, running\n * in the other direction.\n *\n * @throws {CliUsageError} when no config exists, or the configured store is memory.\n */\nexport function resolveStoreRun(\n  command: 'retrieve' | 'stats',\n  config: LoadedConfig | undefined,\n): ResolvedStoreRun {\n  const store = configuredStore(config);\n  if (store.kind !== 'directory') {\n    const state =\n      config === undefined\n        ? `there is no ${CONFIG_FILE_NAME} here`\n        : `the ${CONFIG_FILE_NAME} at ${config.path} uses a memory store`;\n    throw new CliUsageError(\n      `${CLI_NAME}: ${command} needs a persistent store, and ${state}. Cross-run ` +\n        `retrieval is the point of the store: a memory store dies with the process ` +\n        `that made it, so a marker's hash from an earlier run names bytes this run ` +\n        `never held. Configure {\"store\": {\"kind\": \"directory\", \"path\": …}} in ` +\n        `${CONFIG_FILE_NAME} — \\`${CLI_NAME} init\\` writes one.`,\n    );\n  }\n  return { storePath: store.path };\n}\n"]}

package/dist/cli/subcommands/retrieve.js

@@ -0,0 +1,84 @@
+import { CliUsageError } from '../../errors.js';
+import { openStore } from '../../ops/inputs.js';
+import { retrieveBytes } from '../../ops/verbs.js';
+import { CONFIG_FILE_NAME, configuredStore } from '../config.js';
+import { CLI_NAME, EXIT } from '../shell.js';
+export const retrieveCommand = {
+    name: 'retrieve',
+    flags: [],
+    refusal: `retrieve prints the exact original bytes for one hash, nothing else — even ` +
+        `--json would wrap what must come back verbatim.`,
+    usage: {
+        synopsis: ['retrieve <hash>'],
+        section: {
+            heading: 'RETRIEVE & STATS',
+            body: `  Every marker carries the hash of the bytes it replaced — <<smelt/v1: … —\n` +
+                `  retrieve("hash")>> — and the marker's retrieve("hash") is this command:\n` +
+                `  ${CLI_NAME} retrieve <hash> prints the exact original bytes on stdout, byte for\n` +
+                `  byte, nothing else. That closes the loop from pure shell: an agent that got a\n` +
+                `  marker asks for the bytes back with a command instead of a tool call, and the\n` +
+                `  retrieval is counted — asking for material back is exactly what the expansion\n` +
+                `  rate measures. An unknown hash and damaged bytes are distinct refusals (exit 3):\n` +
+                `  "never elided" and "the store was corrupted" call for different responses.`,
+        },
+    },
+    /**
+     * The hash and nothing else. Every flag is refused by the registry's one generated
+     * message rather than ignored — the command prints the exact original bytes on
+     * stdout and nothing more, so a flag that changed the output would break the one
+     * contract it has, and a flag silently dropped would be a setting the user believed
+     * was in force.
+     */
+    parse(_values, positionals) {
+        if (positionals.length !== 2) {
+            throw new CliUsageError(`${CLI_NAME}: retrieve needs exactly one hash — the one a marker printed.\n` +
+                `  ${CLI_NAME} retrieve 84998967370f38bc`);
+        }
+        return { mode: 'retrieve', hash: positionals[1] };
+    },
+    resolve(invocation, config) {
+        return { store: resolveStoreRun('retrieve', config()), hash: invocation.hash };
+    },
+    run(resolved, io) {
+        const store = openStore({ kind: 'directory', path: resolved.store.storePath });
+        io.stdout(retrieveBytes({ store, hash: resolved.hash }));
+        return EXIT.ok;
+    },
+};
+/**
+ * The store leg alone, for the two commands whose entire job is the store between
+ * runs. The refusal is the point: `retrieve` exists so the marker's
+ * `retrieve("hash")` works from a later shell — cross-run retrieval — and a memory
+ * store dies with the process that filled it, so with a memory store (or no config
+ * at all) there is nothing those commands could honestly read. Answering with
+ * `UnknownHashError` or all-zero stats instead would be the quiet wrong answer this
+ * project refuses everywhere: the hash *was* elided, the counters *did* move — in a
+ * store that no longer exists.
+ *
+ * **This is a policy, not a law, which is why it stays here and is not exported.** The
+ * shared half — a config's store decision (`configuredStore`) and opening it
+ * (`openStore` in `ops/inputs.ts`) — is what every consumer needs and now what every
+ * consumer imports. This function is the CLI's ruling *on top of* that decision, and
+ * the MCP server deliberately rules the other way: it accepts a memory store, serves
+ * the whole session from it, and says how to get persistence at the moment an unknown
+ * hash makes the difference visible. Exporting this would offer that server the CLI's
+ * refusal wearing the name of a shared law — the fork this seam exists to end, running
+ * in the other direction.
+ *
+ * @throws {CliUsageError} when no config exists, or the configured store is memory.
+ */
+export function resolveStoreRun(command, config) {
+    const store = configuredStore(config);
+    if (store.kind !== 'directory') {
+        const state = config === undefined
+            ? `there is no ${CONFIG_FILE_NAME} here`
+            : `the ${CONFIG_FILE_NAME} at ${config.path} uses a memory store`;
+        throw new CliUsageError(`${CLI_NAME}: ${command} needs a persistent store, and ${state}. Cross-run ` +
+            `retrieval is the point of the store: a memory store dies with the process ` +
+            `that made it, so a marker's hash from an earlier run names bytes this run ` +
+            `never held. Configure {"store": {"kind": "directory", "path": …}} in ` +
+            `${CONFIG_FILE_NAME} — \`${CLI_NAME} init\` writes one.`);
+    }
+    return { storePath: store.path };
+}
+//# sourceMappingURL=retrieve.js.map