@smeltjs/core 0.1.0

package/dist/cli/config.js

@@ -0,0 +1,144 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CliUsageError } from '../errors.js';
+import { isStrategy, STRATEGIES } from '../plan/planners.js';
+import { CLI_NAME } from './args.js';
+/**
+ * `smelt.config.json` — CLI defaults, and nothing more.
+ *
+ * This file exists so `smelt` can be run without retyping the same flags, and it is
+ * deliberately a *CLI* concern: the programmatic API never reads it. A library that
+ * reads config files off the caller's disk is a library whose behaviour depends on
+ * where it was invoked from, which is exactly the class of invisible input smelt
+ * refuses. `createSmelter()` takes explicit arguments; the CLI translates this file
+ * into those arguments, and explicit flags always win over it.
+ *
+ * The schema is versioned (`"smeltConfig": 1`) for the same reason the marker and the
+ * `--json` envelope are: files outlive the binaries that wrote them, and a mismatch
+ * must be identifiable rather than half-understood. Parsing is strict — an unknown
+ * key, a wrong type, or an unknown version is a {@link CliUsageError}, never a shrug.
+ * A config the CLI silently ignored would be a budget the user *thought* they set.
+ */
+/** The file name looked for, from the working directory upward. */
+export const CONFIG_FILE_NAME = 'smelt.config.json';
+/** The schema version this build reads and writes. */
+export const CONFIG_VERSION = 1;
+/**
+ * The nearest `smelt.config.json`, walking up from `cwd` to the filesystem root —
+ * the same discovery shape as `package.json`, so a config at a repo root covers the
+ * whole tree. `undefined` when there is none, which is not an error: flags alone are
+ * a complete interface.
+ */
+export function findConfigFile(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const candidate = join(dir, CONFIG_FILE_NAME);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Find and parse the nearest config. `undefined` when no file exists; a file that
+ * exists but is malformed **throws** — see {@link parseConfig}. The distinction is the
+ * point: "no config" is a fine state, "a config you cannot have meant" is not.
+ *
+ * @throws {CliUsageError} when a config file exists and is malformed.
+ */
+export function loadNearestConfig(cwd) {
+    const path = findConfigFile(cwd);
+    if (path === undefined)
+        return undefined;
+    return { path, config: parseConfig(readFileSync(path, 'utf8'), path) };
+}
+/**
+ * Parse and validate one config file, strictly.
+ *
+ * Strict means: unknown keys are refused, not skipped. A typo'd `defaultBudgetByte`
+ * that parsed cleanly would leave the user believing a default was set while every
+ * run ignored it — a config error whose failure mode is *silence*, which is the one
+ * failure shape this project refuses everywhere else too.
+ *
+ * @throws {CliUsageError} naming the file and the exact problem.
+ */
+export function parseConfig(text, path) {
+    const bad = (why) => new CliUsageError(`${CLI_NAME}: malformed ${CONFIG_FILE_NAME} at ${path}: ${why}\n` +
+        `Fix it or delete it — a config smelt cannot read is never silently ignored. ` +
+        `\`${CLI_NAME} init\` can rewrite it.`);
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        throw bad(`not JSON (${cause instanceof Error ? cause.message : String(cause)}).`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw bad('expected a JSON object at the top level.');
+    }
+    const fields = value;
+    if (fields['smeltConfig'] !== CONFIG_VERSION) {
+        throw bad(`"smeltConfig" is ${JSON.stringify(fields['smeltConfig'])}; this build reads version ` +
+            `${String(CONFIG_VERSION)}. The schema is versioned so a mismatch is visible ` +
+            `instead of half-understood.`);
+    }
+    const known = ['smeltConfig', 'defaultBudgetBytes', 'strategy', 'store'];
+    const unknown = Object.keys(fields).filter((key) => !known.includes(key));
+    if (unknown.length > 0) {
+        throw bad(`unknown key${unknown.length === 1 ? '' : 's'} ${unknown.map((k) => `"${k}"`).join(', ')}. ` +
+            `Known keys: ${known.join(', ')}. Unknown keys are refused because a typo that ` +
+            `parsed cleanly would be a setting you believed was set.`);
+    }
+    const budget = fields['defaultBudgetBytes'];
+    if (budget !== undefined && (typeof budget !== 'number' || !Number.isInteger(budget))) {
+        throw bad(`"defaultBudgetBytes" must be a whole number of UTF-8 bytes.`);
+    }
+    if (typeof budget === 'number' && budget <= 0) {
+        throw bad(`"defaultBudgetBytes" must be greater than zero, got ${String(budget)}.`);
+    }
+    const strategy = fields['strategy'];
+    if (strategy !== undefined && (typeof strategy !== 'string' || !isStrategy(strategy))) {
+        throw bad(`"strategy" must be ${STRATEGIES.map((s) => `"${s}"`).join(' or ')}, ` +
+            `got ${JSON.stringify(strategy)}.`);
+    }
+    const store = parseStore(fields['store'], bad);
+    return {
+        smeltConfig: CONFIG_VERSION,
+        ...(budget === undefined ? {} : { defaultBudgetBytes: budget }),
+        ...(strategy === undefined ? {} : { strategy }),
+        ...(store === undefined ? {} : { store }),
+    };
+}
+function parseStore(value, bad) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw bad(`"store" must be an object like {"kind":"memory"} or {"kind":"directory","path":…}.`);
+    }
+    const fields = value;
+    const kind = fields['kind'];
+    if (kind === 'memory') {
+        const extra = Object.keys(fields).filter((key) => key !== 'kind');
+        if (extra.length > 0)
+            throw bad(`"store" of kind "memory" takes no other keys.`);
+        return { kind: 'memory' };
+    }
+    if (kind === 'directory') {
+        const path = fields['path'];
+        if (typeof path !== 'string' || path === '') {
+            throw bad(`"store" of kind "directory" needs a non-empty "path".`);
+        }
+        const extra = Object.keys(fields).filter((key) => key !== 'kind' && key !== 'path');
+        if (extra.length > 0)
+            throw bad(`"store" of kind "directory" takes only "kind" and "path".`);
+        return { kind: 'directory', path };
+    }
+    throw bad(`"store".kind must be "memory" or "directory", got ${JSON.stringify(kind)}.`);
+}
+/** `store.path` is relative to the config file, so the config works from any cwd. */
+export function resolveStorePath(loaded, path) {
+    return resolve(dirname(loaded.path), path);
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/cli/config.ts"],"names":[],"mappings":"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"}

package/dist/cli/init.d.ts

@@ -0,0 +1,56 @@
+import type { SmeltConfigStore } from './config.ts';
+/**
+ * `smelt init` — the setup wizard.
+ *
+ * The same testability pattern as `run.ts`: the wizard is a pure function over an
+ * input/output pair, so every flow — fresh run, back-navigation, re-run editing,
+ * declined overwrites — runs in-process in tests, and `bin.ts` wires the real stdio.
+ *
+ * Three rules shape everything here:
+ *
+ *  1. **Nothing is written until the final confirm**, which lists exactly what will be
+ *     written or changed. A wizard that writes as it goes cannot be backed out of.
+ *  2. **An existing file is never overwritten without an explicit per-file yes.** Not
+ *     a global "overwrite all", not a default — one question per existing file, and
+ *     anything but a literal `yes` skips it. Guarded by
+ *     `test/guards/init-wizard.test.ts`, with a mutation proving the guard goes red.
+ *  3. **Every step accepts `back`.** A wizard you cannot reverse inside is a form.
+ *
+ * Law 4 note: the wizard's copy states what each choice *does*, never what it saves —
+ * no percentages, no rates, no numbers smelt has not measured.
+ */
+/** The generated measure-hook stub's file name. */
+export declare const MEASURE_STUB_FILE = "smelt.measure.ts";
+/** The generated reranker stub's file name. */
+export declare const RERANK_STUB_FILE = "smelt.rerank.ts";
+/** Where the wizard's bytes come from and go. Injected so `runInit` is testable in-process. */
+export interface InitIo {
+    /** Interactive input — the real stdin in `bin.ts`, a scripted stream in tests. */
+    readonly input: NodeJS.ReadableStream;
+    readonly output: (text: string) => void;
+    /**
+     * Where config discovery starts, and where a fresh run's files land. An edit run
+     * writes next to the discovered config instead — which may be an ancestor of `cwd`,
+     * and the "About to write" listing names that directory before anything is written.
+     */
+    readonly cwd: string;
+}
+/**
+ * The wizard, start to finish. Returns an exit code (0 in every completed flow,
+ * including "declined to write anything").
+ *
+ * @throws {CliUsageError} on a malformed existing config, or when input ends before
+ *   the wizard finishes — both are usage-shaped, and nothing further is written.
+ */
+export declare function runInit(io: InitIo): Promise<number>;
+/** The config file, serialized with a stable key order so re-runs diff cleanly. */
+export declare function renderConfig(choices: {
+    readonly budgetBytes: number | undefined;
+    readonly store: SmeltConfigStore;
+    readonly strategy: 'lexical' | 'structural';
+}): string;
+/** The `smelt.measure.ts` the wizard writes. Exported so tests can compile it. */
+export declare function measureStubSource(): string;
+/** The `smelt.rerank.ts` the wizard writes. Exported so tests can compile it. */
+export declare function rerankStubSource(): string;
+//# sourceMappingURL=init.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AAEpD,+CAA+C;AAC/C,eAAO,MAAM,gBAAgB,oBAAoB,CAAC;AAElD,+FAA+F;AAC/F,MAAM,WAAW,MAAM;IACrB,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAwBD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBzD;AAmUD,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,YAAY,CAAC;CAC7C,GAAG,MAAM,CAQT;AAcD,kFAAkF;AAClF,wBAAgB,iBAAiB,IAAI,MAAM,CA+B1C;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,IAAI,MAAM,CA6DzC"}

package/dist/cli/init.js

@@ -0,0 +1,449 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { CliUsageError } from '../errors.js';
+import { STRUCTURAL_LANGUAGES } from '../plan/structural.js';
+import { CLI_NAME } from './args.js';
+import { CONFIG_FILE_NAME, CONFIG_VERSION, findConfigFile, parseConfig } from './config.js';
+/**
+ * `smelt init` — the setup wizard.
+ *
+ * The same testability pattern as `run.ts`: the wizard is a pure function over an
+ * input/output pair, so every flow — fresh run, back-navigation, re-run editing,
+ * declined overwrites — runs in-process in tests, and `bin.ts` wires the real stdio.
+ *
+ * Three rules shape everything here:
+ *
+ *  1. **Nothing is written until the final confirm**, which lists exactly what will be
+ *     written or changed. A wizard that writes as it goes cannot be backed out of.
+ *  2. **An existing file is never overwritten without an explicit per-file yes.** Not
+ *     a global "overwrite all", not a default — one question per existing file, and
+ *     anything but a literal `yes` skips it. Guarded by
+ *     `test/guards/init-wizard.test.ts`, with a mutation proving the guard goes red.
+ *  3. **Every step accepts `back`.** A wizard you cannot reverse inside is a form.
+ *
+ * Law 4 note: the wizard's copy states what each choice *does*, never what it saves —
+ * no percentages, no rates, no numbers smelt has not measured.
+ */
+/** The generated measure-hook stub's file name. */
+export const MEASURE_STUB_FILE = 'smelt.measure.ts';
+/** The generated reranker stub's file name. */
+export const RERANK_STUB_FILE = 'smelt.rerank.ts';
+/**
+ * The wizard, start to finish. Returns an exit code (0 in every completed flow,
+ * including "declined to write anything").
+ *
+ * @throws {CliUsageError} on a malformed existing config, or when input ends before
+ *   the wizard finishes — both are usage-shaped, and nothing further is written.
+ */
+export async function runInit(io) {
+    const rl = createInterface({ input: io.input });
+    const lines = rl[Symbol.asyncIterator]();
+    const ask = async (prompt) => {
+        io.output(prompt);
+        const next = await lines.next();
+        if (next.done === true) {
+            throw new CliUsageError(`${CLI_NAME} init: input ended before the wizard finished. ` +
+                `Files already confirmed and written stay; nothing further was written.`);
+        }
+        return next.value.trim();
+    };
+    try {
+        const existing = loadExisting(io.cwd);
+        return existing === undefined
+            ? await freshRun(io, ask)
+            : await editRun(io, ask, existing.path, existing.config);
+    }
+    finally {
+        rl.close();
+    }
+}
+function loadExisting(cwd) {
+    const path = findConfigFile(cwd);
+    if (path === undefined)
+        return undefined;
+    // Malformed is a loud usage error, not a silent fresh start: overwriting a config
+    // the user wrote, because it had a typo, would be the wizard deciding for them.
+    return { path, config: parseConfig(readFileSync(path, 'utf8'), path) };
+}
+const STEPS = [
+    { id: 'budget', run: stepBudget },
+    { id: 'store', run: stepStore },
+    { id: 'strategy', run: stepStrategy },
+    { id: 'measure', run: stepMeasure },
+    { id: 'rerank', run: stepRerank },
+];
+async function freshRun(io, ask) {
+    io.output(`${CLI_NAME} init — sets up ${CONFIG_FILE_NAME} in ${io.cwd}.\n` +
+        `Answer \`back\` at any step to return to the previous one. ` +
+        `Nothing is written until you confirm at the end.\n\n`);
+    const choices = {
+        budgetBytes: undefined,
+        store: { kind: 'memory' },
+        strategy: 'lexical',
+        measureStub: false,
+        rerankStub: false,
+    };
+    let index = 0;
+    for (;;) {
+        while (index < STEPS.length) {
+            const outcome = await STEPS[index].run(io, ask, choices, io.cwd);
+            if (outcome === 'back') {
+                if (index === 0)
+                    io.output(`This is the first step — there is nothing before it.\n`);
+                else
+                    index -= 1;
+            }
+            else {
+                index += 1;
+            }
+        }
+        const verdict = await confirmAndWrite(io, ask, choices, io.cwd);
+        if (verdict !== 'back')
+            return 0;
+        index = STEPS.length - 1;
+    }
+}
+async function editRun(io, ask, configPath, config) {
+    const dir = dirname(configPath);
+    const choices = {
+        budgetBytes: config.defaultBudgetBytes,
+        store: config.store ?? { kind: 'memory' },
+        strategy: config.strategy ?? 'lexical',
+        measureStub: false,
+        rerankStub: false,
+    };
+    io.output(`${CLI_NAME} init — ${CONFIG_FILE_NAME} already exists at ${configPath}.\n` +
+        `Change one setting at a time; nothing is written until you confirm.\n`);
+    for (;;) {
+        io.output(`\nCurrent values:\n${summary(choices, dir)}\n`);
+        const answer = await ask(`Change which setting? (budget / store / strategy / measure / rerank, ` +
+            `\`done\` to review and confirm, \`back\` to leave without writing)\n> `);
+        if (answer === 'back') {
+            io.output(`Left as it was. Nothing has been written.\n`);
+            return 0;
+        }
+        if (answer === 'done') {
+            const verdict = await confirmAndWrite(io, ask, choices, dir);
+            if (verdict !== 'back')
+                return 0;
+            continue; // back from confirm returns to this menu
+        }
+        const step = STEPS.find((candidate) => candidate.id === answer);
+        if (step === undefined) {
+            io.output(`Not a setting: "${answer}". One of: budget, store, strategy, measure, rerank.\n`);
+            continue;
+        }
+        await step.run(io, ask, choices, dir); // its own `back` returns here
+    }
+}
+function summary(choices, dir) {
+    const stubLine = (file, generate) => {
+        if (generate)
+            return `generate ${file}`;
+        return existsSync(join(dir, file)) ? `${file} exists (kept as is)` : 'none';
+    };
+    return [
+        `  budget:    ${choices.budgetBytes === undefined ? '(not set)' : `${String(choices.budgetBytes)} bytes`}`,
+        `  store:     ${choices.store.kind === 'memory' ? 'memory' : `directory (${choices.store.path})`}`,
+        `  strategy:  ${choices.strategy}`,
+        `  measure:   ${stubLine(MEASURE_STUB_FILE, choices.measureStub)}`,
+        `  rerank:    ${stubLine(RERANK_STUB_FILE, choices.rerankStub)}`,
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// The steps. Each one accepts `back`.
+// ---------------------------------------------------------------------------
+async function stepBudget(io, ask, choices) {
+    io.output(`\nDefault byte budget — used when a \`${CLI_NAME}\` run omits --budget.\n` +
+        `Budgets are UTF-8 bytes, permanently; an explicit --budget always wins.\n` +
+        `There is no suggested number: the right budget depends on your traffic, and ` +
+        `smelt does not invent numbers it has not measured.\n`);
+    for (;;) {
+        const current = choices.budgetBytes === undefined ? '' : ` [${String(choices.budgetBytes)}]`;
+        const answer = await ask(`budget in bytes${current} (or back)> `);
+        if (answer === 'back')
+            return 'back';
+        if (answer === '' && choices.budgetBytes !== undefined)
+            return 'ok';
+        if (/^\d+$/.test(answer) && Number(answer) > 0) {
+            choices.budgetBytes = Number(answer);
+            return 'ok';
+        }
+        io.output(`A whole number of bytes greater than zero, e.g. 4000.\n`);
+    }
+}
+async function stepStore(io, ask, choices) {
+    io.output(`\nWhere elided bytes live. Every elision is reversible only while a store holds ` +
+        `its bytes (Law 3):\n` +
+        `  1. memory     — per-process; retrievals do not survive the process\n` +
+        `  2. directory  — persistent, content-addressed, on disk; retrieval counters ` +
+        `survive restarts\n`);
+    for (;;) {
+        const current = choices.store.kind === 'memory' ? '1' : '2';
+        const answer = await ask(`store (1/2) [${current}] (or back)> `);
+        if (answer === 'back')
+            return 'back';
+        const pick = answer === '' ? current : answer;
+        if (pick === '1') {
+            choices.store = { kind: 'memory' };
+            return 'ok';
+        }
+        if (pick === '2') {
+            const previous = choices.store.kind === 'directory' ? choices.store.path : '.smelt/store';
+            const path = await ask(`store directory, relative to ${CONFIG_FILE_NAME} [${previous}]> `);
+            if (path === 'back')
+                continue; // back to the store choice, not out of the step
+            choices.store = { kind: 'directory', path: path === '' ? previous : path };
+            return 'ok';
+        }
+        io.output(`1 for memory, 2 for directory, or back.\n`);
+    }
+}
+async function stepStrategy(io, ask, choices) {
+    io.output(`\nDefault planner strategy — used when a run omits --strategy:\n` +
+        `  1. lexical     — line windows around your focus terms; works on any text\n` +
+        `  2. structural  — parses ${String(STRUCTURAL_LANGUAGES.length)} languages with ` +
+        `bundled grammars (${STRUCTURAL_LANGUAGES.join(', ')}) and ` +
+        `collapses siblings by name; refuses other languages rather than approximating\n`);
+    for (;;) {
+        const current = choices.strategy === 'lexical' ? '1' : '2';
+        const answer = await ask(`strategy (1/2) [${current}] (or back)> `);
+        if (answer === 'back')
+            return 'back';
+        const pick = answer === '' ? current : answer;
+        if (pick === '1' || pick === '2') {
+            choices.strategy = pick === '1' ? 'lexical' : 'structural';
+            return 'ok';
+        }
+        io.output(`1 for lexical, 2 for structural, or back.\n`);
+    }
+}
+async function stepMeasure(io, ask, choices, dir) {
+    const exists = existsSync(join(dir, MEASURE_STUB_FILE));
+    io.output(`\nMeasure hook — your own counter (a tokenizer, usually), so results carry a ` +
+        `second, labelled number next to the byte counts. smelt ships none: a token ` +
+        `count without its tokenizer named is not a measurement.\n` +
+        `  1. none\n` +
+        `  2. generate ${MEASURE_STUB_FILE}, a typed stub you fill in\n` +
+        (exists ? `(${MEASURE_STUB_FILE} already exists; it is never deleted from here.)\n` : ``));
+    for (;;) {
+        const answer = await ask(`measure (1/2) [${choices.measureStub ? '2' : '1'}] (or back)> `);
+        if (answer === 'back')
+            return 'back';
+        const pick = answer === '' ? (choices.measureStub ? '2' : '1') : answer;
+        if (pick === '1' || pick === '2') {
+            choices.measureStub = pick === '2';
+            return 'ok';
+        }
+        io.output(`1 for none, 2 to generate the stub, or back.\n`);
+    }
+}
+async function stepRerank(io, ask, choices, dir) {
+    const exists = existsSync(join(dir, RERANK_STUB_FILE));
+    io.output(`\nReranker — a RerankStage of your own. smelt never bundles one and never will: ` +
+        `an outbound call must live in your code, under your key, visible in your own ` +
+        `review (Law 1).\n` +
+        `  1. none\n` +
+        `  2. generate ${RERANK_STUB_FILE}, a typed stub with the HTTP call sketched as a TODO\n` +
+        (exists ? `(${RERANK_STUB_FILE} already exists; it is never deleted from here.)\n` : ``));
+    for (;;) {
+        const answer = await ask(`rerank (1/2) [${choices.rerankStub ? '2' : '1'}] (or back)> `);
+        if (answer === 'back')
+            return 'back';
+        const pick = answer === '' ? (choices.rerankStub ? '2' : '1') : answer;
+        if (pick === '1' || pick === '2') {
+            choices.rerankStub = pick === '2';
+            return 'ok';
+        }
+        io.output(`1 for none, 2 to generate the stub, or back.\n`);
+    }
+}
+// ---------------------------------------------------------------------------
+// The confirm step: the only place anything is written
+// ---------------------------------------------------------------------------
+const writeLabel = (write) => {
+    if (write.unchanged)
+        return 'unchanged — nothing to write';
+    return write.exists ? 'exists — will ask before overwriting' : 'new';
+};
+async function confirmAndWrite(io, ask, choices, dir) {
+    if (choices.budgetBytes === undefined) {
+        // Unreachable in the fresh flow (the budget step requires a number) but reachable
+        // from an edit of a config that never had one — `defaultBudgetBytes` is optional,
+        // so such a config parses fine. The wizard still insists: a confirm without a
+        // budget would write a file this wizard just called incomplete. `back` here is a
+        // real `back` — it returns to the caller, never falls forward into the confirm.
+        io.output(`No budget is set yet — set one before confirming.\n`);
+        if ((await stepBudget(io, ask, choices)) === 'back')
+            return 'back';
+    }
+    const writes = plannedWrites(choices, dir);
+    io.output(`\nAbout to write, into ${dir}:\n` +
+        writes.map((write) => `  ${write.name.padEnd(20)} (${writeLabel(write)})\n`).join('') +
+        `Nothing has been written yet.\n`);
+    for (;;) {
+        const answer = await ask(`confirm (yes / no / back)> `);
+        if (answer === 'back')
+            return 'back';
+        if (answer === 'no') {
+            io.output(`Nothing was written.\n`);
+            return 'done';
+        }
+        if (answer === 'yes')
+            break;
+        io.output(`yes to write, no to leave everything untouched, back to change a setting.\n`);
+    }
+    for (const write of writes) {
+        if (write.unchanged) {
+            io.output(`  ${write.name} — unchanged, not rewritten\n`);
+            continue;
+        }
+        if (write.exists) {
+            // The per-file consent rule: one explicit question per existing file, and only
+            // a literal `yes` overwrites. This is the line the mutation
+            // `init-overwrite-without-consent` breaks to prove the guard can go red.
+            const answer = await ask(`  ${write.name} exists — overwrite it? (yes/no)> `);
+            if (answer !== 'yes') {
+                io.output(`  skipped ${write.name} — the existing file was not touched\n`);
+                continue;
+            }
+        }
+        writeFileSync(write.path, write.content);
+        io.output(`  wrote ${write.name}\n`);
+    }
+    io.output(`Done.\n`);
+    return 'done';
+}
+function plannedWrites(choices, dir) {
+    const plan = (name, content) => {
+        const path = join(dir, name);
+        const exists = existsSync(path);
+        const unchanged = exists && readFileSync(path, 'utf8') === content;
+        return { name, path, content, exists, unchanged };
+    };
+    const writes = [plan(CONFIG_FILE_NAME, renderConfig(choices))];
+    if (choices.measureStub)
+        writes.push(plan(MEASURE_STUB_FILE, measureStubSource()));
+    if (choices.rerankStub)
+        writes.push(plan(RERANK_STUB_FILE, rerankStubSource()));
+    return writes;
+}
+/** The config file, serialized with a stable key order so re-runs diff cleanly. */
+export function renderConfig(choices) {
+    const config = {
+        smeltConfig: CONFIG_VERSION,
+        ...(choices.budgetBytes === undefined ? {} : { defaultBudgetBytes: choices.budgetBytes }),
+        strategy: choices.strategy,
+        store: choices.store,
+    };
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+// ---------------------------------------------------------------------------
+// The generated stubs. String literals on purpose: smelt's own import graph must not
+// gain an HTTP client, and the zero-network guard's string-stripper ignores string
+// bodies — the sketched fetch below lives in the CONSUMER'S file, never in smelt's.
+//
+// The comment token between `from` and the package name in each stub's import line is
+// deliberate: the guard's import scanner reads raw source, so spelling that import
+// plainly inside this template would register as an edge in smelt's own graph — which
+// it is not. The comment keeps the generated file valid TypeScript while keeping this
+// data out of the guard's walk.
+// ---------------------------------------------------------------------------
+/** The `smelt.measure.ts` the wizard writes. Exported so tests can compile it. */
+export function measureStubSource() {
+    return `/**
+ * Measure hook — generated by \`smelt init\`.
+ *
+ * smelt's budgets are UTF-8 bytes, permanently; this hook adds a second, labelled
+ * number to every result in YOUR unit, counted by YOUR tokenizer. Both \`id\` and
+ * \`unit\` are required: a count without the counter named is not a measurement.
+ *
+ * Wire it in, in your own code:
+ *
+ *   const smelter = createSmelter({ defaultBudgetBytes: 8_000, measure });
+ *
+ * with createSmelter imported from your @smeltjs/core install and measure from here.
+ */
+import type { Measure } from /* your install */ '@smeltjs/core';
+
+export const measure: Measure = {
+  // TODO: name the counter that produces these numbers, e.g. 'tiktoken/o200k_base'.
+  id: 'TODO/your-tokenizer',
+  unit: 'tokens',
+  count(text: string): number {
+    // TODO: replace with your real tokenizer. It must be local and synchronous —
+    // a count() that calls an API would make your process call an API on every smelt.
+    // e.g.  return encode(text).length;
+    throw new Error(
+      'smelt.measure.ts: count() is not implemented yet — ' +
+        'fill it in with your tokenizer (length of input: ' + String(text.length) + ')',
+    );
+  },
+};
+`;
+}
+/** The `smelt.rerank.ts` the wizard writes. Exported so tests can compile it. */
+export function rerankStubSource() {
+    return `/**
+ * Reranker stub — generated by \`smelt init\`.
+ *
+ * smelt itself makes zero network calls and never bundles a reranker (Law 1): the
+ * moment one ships as a default, every consumer's source code leaves the machine and
+ * they find out from a changelog, or never. So the outbound call lives HERE, in your
+ * file, reading your env var, visible in your own review.
+ *
+ * Wire it into your own pipeline; smelt never calls this for you.
+ */
+import type { RerankCandidate, RerankedCandidate, RerankStage } from /* your install */ '@smeltjs/core';
+
+/** The env var YOUR code reads. Rename it to match your vendor. */
+const API_KEY_ENV = 'RERANKER_API_KEY';
+
+export const rerank: RerankStage = {
+  id: 'my-reranker/v1',
+  async rerank(
+    candidates: readonly RerankCandidate[],
+    query: string,
+  ): Promise<readonly RerankedCandidate[]> {
+    const apiKey = process.env[API_KEY_ENV];
+    if (apiKey === undefined || apiKey === '') {
+      throw new Error(
+        'smelt.rerank.ts: ' + API_KEY_ENV + ' is not set. This stage makes an outbound ' +
+          'HTTP call from YOUR code with YOUR key; without a key it refuses to pretend.',
+      );
+    }
+
+    // TODO: the outbound call. Voyage AI is one example vendor; any reranker with an
+    // HTTP API fits this shape:
+    //
+    //   const response = await fetch('https://api.voyageai.com/v1/rerank', {
+    //     method: 'POST',
+    //     headers: {
+    //       'content-type': 'application/json',
+    //       authorization: \`Bearer \${apiKey}\`,
+    //     },
+    //     body: JSON.stringify({
+    //       query,
+    //       documents: candidates.map((candidate) => candidate.text),
+    //     }),
+    //   });
+    //   if (!response.ok) throw new Error('rerank failed: ' + String(response.status));
+    //   const body = (await response.json()) as {
+    //     data: { index: number; relevance_score: number }[];
+    //   };
+    //   return body.data.map(({ index, relevance_score }) => ({
+    //     ...candidates[index]!,
+    //     score: relevance_score,
+    //   }));
+    //
+    void candidates;
+    void query;
+    throw new Error(
+      'smelt.rerank.ts: implement the outbound call sketched above, then delete this throw.',
+    );
+  },
+};
+`;
+}
+//# sourceMappingURL=init.js.map