bantamkit-mcp 0.30.0 → 0.31.0

package/dist/pricing.js

@@ -0,0 +1,357 @@
+/**
+ * Layer 4 (Policy/Profile): the price table, and the arithmetic that turns tokens into money.
+ *
+ * A port of `runtime-py/src/bantamkit/pricing.py`, arm for arm. The Python module is the
+ * reference and carries the full reasoning -- why the shipped table has NO rates, why the
+ * three properties are where they are, why money is an integer. Read it first; what follows
+ * here is only what this side does DIFFERENTLY, and every one of those is a mechanical
+ * consequence of the language rather than a decision.
+ *
+ * 1. `BigInt` FOR THE MULTIPLY, `number` ON THE WIRE. `count * rate` with both operands
+ *    allowed up to 2**53-1 reaches 2**106, which a JS `number` rounds silently and Python
+ *    does not. So the product, the half-up rounding and the running total are all `bigint`
+ *    here, and only the final micro-USD -- bounded by the shared 2**53-1 ceiling, refused
+ *    above it on BOTH sides with the same sentence -- becomes a `number`. Python needs none
+ *    of this because its `int` is arbitrary precision; the ceiling exists so that the place
+ *    where the two would part company is a refusal rather than a wrong answer.
+ *
+ * 2. `pyRepr` AND `cmpCodepoint`, NOT `JSON.stringify` AND `.sort()`. Every quoted name in
+ *    a sentence goes through `pyRepr` because Python's `repr` is what the reference emits,
+ *    and every "which offender is named first" goes through `cmpCodepoint` because
+ *    `.sort()` is UTF-16 code-unit order and `sorted()` is code-point order. Both are
+ *    already the port's shared primitives and both are already under conformance.
+ *
+ * 3. `JSON.parse` IS THE STRICTER READER AND PYTHON WAS BROUGHT TO IT. `json.loads` accepts
+ *    the bare tokens `NaN` / `Infinity` / `-Infinity`; `JSON.parse` does not. The reference
+ *    passes `parse_constant` to refuse them, so both sides answer
+ *    `price table is not valid JSON: <path>` for the same bytes.
+ *
+ * 4. AN INTEGRAL FLOAT IS A COUNT. `JSON.parse('3000000.0')` is `3000000` and cannot be told
+ *    from the integer; the reference therefore accepts an integral `float` and narrows it,
+ *    rather than refusing a spelling this side cannot even see.
+ *
+ * `tools/conformance/suites/pricing.mjs` is the gate.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assetsRoot } from './assets.js';
+import { BantamError } from './errors.js';
+import { cmpCodepoint, pyRepr } from './pysem.js';
+export const PRICES_ENV = 'BANTAMKIT_PRICES';
+export const PRICE_SCHEMA_VERSION = 1;
+export const CURRENCY = 'USD';
+export const RATE_UNIT = 'micro_usd_per_million_tokens';
+/** A rate is micro-USD per this many tokens. */
+export const TOKENS_PER_RATE_UNIT = 1000000;
+/** Micro-USD in one USD. Also the rounding divisor, hence `HALF` below. */
+export const MICROS_PER_UNIT = 1000000;
+const MICROS_PER_UNIT_BIG = 1000000n;
+const HALF_BIG = 500000n;
+/** The largest integer both runtimes represent exactly. */
+export const MAX_SAFE_INT = 2 ** 53 - 1;
+const MAX_SAFE_INT_BIG = BigInt(Number.MAX_SAFE_INTEGER);
+/**
+ * The four classes the host's own `usage` block distinguishes, in the order the ledger
+ * accumulates them. This tuple is the unit of pricing; see property 1 in the reference.
+ */
+export const TOKEN_CLASSES = [
+    'input_tokens',
+    'cache_creation_input_tokens',
+    'cache_read_input_tokens',
+    'output_tokens',
+];
+const CLASSES = TOKEN_CLASSES.join(', ');
+const TABLE_KEYS = ['schema_version', 'currency', 'unit', 'note', 'rates'];
+const RATE_META = ['recorded', 'source'];
+/**
+ * The table on disk is malformed.
+ *
+ * This THROWS rather than returning `{unavailable}`, and the split is deliberate: a broken
+ * price table is an operator configuration fault that must stop and name itself, while an
+ * unpriced model is a normal, expected answer that a caller keeps working past.
+ */
+export class PriceTableError extends BantamError {
+}
+/**
+ * A non-negative integer both runtimes hold exactly, however JSON spelled it.
+ *
+ * `Number.isInteger` is false for `Infinity` and `NaN`, which is what makes `1e400` -- valid
+ * JSON here, `inf` after `json.loads` there -- refuse identically on both sides.
+ */
+function isCount(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_SAFE_INT;
+}
+/** The number behind an accepted count. Only ever called after `isCount`. `-0` normalises to `0`. */
+function asCount(value) {
+    return value + 0;
+}
+/**
+ * Sorted by code point, so "which key is named first" is not a function of object order.
+ *
+ * `JSON.parse` hoists integer-like keys ahead of the rest and orders them numerically;
+ * `json.loads` preserves the file. Naming the code-point-least offender makes the two answer
+ * the same sentence for the same file.
+ */
+function sortedByCodePoint(names) {
+    return [...names].sort(cmpCodepoint);
+}
+/**
+ * `YYYY-MM-DD`, shape and range only -- deliberately not a calendar.
+ *
+ * A real calendar check would be `datetime.date` on the reference side, which this side has
+ * no equivalent of without writing a third leap-year rule. 2026-02-31 passes and that is a
+ * known, stated limit.
+ */
+function isDate(value) {
+    if (typeof value !== 'string' || value.length !== 10)
+        return false;
+    if (value[4] !== '-' || value[7] !== '-')
+        return false;
+    for (const part of [value.slice(0, 4), value.slice(5, 7), value.slice(8, 10)]) {
+        for (const ch of part) {
+            if (ch < '0' || ch > '9')
+                return false;
+        }
+    }
+    const month = Number(value.slice(5, 7));
+    const day = Number(value.slice(8, 10));
+    return month >= 1 && month <= 12 && day >= 1 && day <= 31;
+}
+/**
+ * `$BANTAMKIT_PRICES` verbatim if set, else the shipped table in the asset pack.
+ *
+ * The override wins even when it is wrong -- same arm order and same reasoning as
+ * `assetsRoot()`: an override that points nowhere must fail naming itself rather than fall
+ * through to a table the operator did not ask for.
+ */
+export function priceTablePath() {
+    const env = process.env[PRICES_ENV];
+    if (env)
+        return env;
+    return join(assetsRoot(), 'pricing', 'default.json');
+}
+/**
+ * Read and validate a price table. `path` is used VERBATIM in every message it appears in,
+ * never normalised, because `Path('./x')` is `x` on the reference side and `./x` here and the
+ * fault sentence would then differ over a path neither runtime chose.
+ */
+export function loadPriceTable(path) {
+    const label = path === undefined ? priceTablePath() : path;
+    if (!existsSync(label)) {
+        throw new PriceTableError(`price table not found: ${label}`);
+    }
+    let raw;
+    try {
+        // The decoder's own text is NOT quoted. `validate.mjs` covers the two decoders'
+        // sentences separately and they are not identical everywhere; quoting one here would
+        // make every malformed table a divergence, over bytes that name the same fault.
+        raw = decodePriceJson(readFileSync(label, 'utf8'));
+    }
+    catch {
+        throw new PriceTableError(`price table is not valid JSON: ${label}`);
+    }
+    return validatePriceTable(raw);
+}
+/**
+ * The decode both runtimes must agree on, in one place so the gate can reach it.
+ *
+ * This side is already the strict one -- `JSON.parse` rejects the bare `NaN` / `Infinity` /
+ * `-Infinity` tokens that `json.loads` accepts -- so the function is a plain `JSON.parse`
+ * and the reference is what had to move. It exists as a named arm anyway, because a rule
+ * that lives in only one of two runtimes is a rule the conformance harness cannot reach.
+ */
+export function decodePriceJson(text) {
+    return JSON.parse(text);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Every rule the table must satisfy, each with its own sentence.
+ *
+ * Returns a NORMALISED table: the top-level keys in a fixed order, rate names in code-point
+ * order, and every count narrowed. See the reference for the ONE thing normalisation cannot
+ * buy -- the iteration order of `rates` for a model name JavaScript reads as an array index.
+ */
+export function validatePriceTable(raw) {
+    if (!isPlainObject(raw)) {
+        throw new PriceTableError('price table must be a JSON object');
+    }
+    const unknown = sortedByCodePoint(Object.keys(raw).filter((k) => !TABLE_KEYS.includes(k)));
+    if (unknown.length > 0) {
+        throw new PriceTableError(`price table has unknown key ${pyRepr(unknown[0])}`);
+    }
+    // No parsed VALUE is ever interpolated into a sentence below -- only key names and
+    // integers this module computed. A parsed value would drag the two runtimes' number
+    // formatting into the message, which is a serialiser divergence wearing an error
+    // message's clothes.
+    const version = raw['schema_version'];
+    if (!isCount(version) || version !== PRICE_SCHEMA_VERSION) {
+        throw new PriceTableError('price table schema_version must be the integer 1');
+    }
+    if (raw['currency'] !== CURRENCY) {
+        throw new PriceTableError("price table currency must be the string 'USD'");
+    }
+    if (raw['unit'] !== RATE_UNIT) {
+        throw new PriceTableError("price table unit must be the string 'micro_usd_per_million_tokens'");
+    }
+    if ('note' in raw && typeof raw['note'] !== 'string') {
+        throw new PriceTableError('price table note must be a string');
+    }
+    const rates = raw['rates'];
+    if (!isPlainObject(rates)) {
+        throw new PriceTableError('price table rates must be a JSON object');
+    }
+    const built = {};
+    for (const model of sortedByCodePoint(Object.keys(rates))) {
+        built[model] = validateRate(model, rates[model]);
+    }
+    // Assigned in the reference's own key order -- `note`, when present, sits between `unit`
+    // and `rates` -- because insertion order is what `JSON.stringify` emits and the suite
+    // compares the serialised table.
+    const out = {};
+    out.schema_version = PRICE_SCHEMA_VERSION;
+    out.currency = CURRENCY;
+    out.unit = RATE_UNIT;
+    if ('note' in raw)
+        out.note = raw['note'];
+    out.rates = built;
+    return out;
+}
+function validateRate(model, rate) {
+    if (!isPlainObject(rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} must be a JSON object`);
+    }
+    const known = [...RATE_META, ...TOKEN_CLASSES];
+    const unknown = sortedByCodePoint(Object.keys(rate).filter((k) => !known.includes(k)));
+    if (unknown.length > 0) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} has unknown key ${pyRepr(unknown[0])}`);
+    }
+    // Property 2, enforced where it cannot be skipped: at load, before any arithmetic.
+    if (!('recorded' in rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} is missing 'recorded' -- a rate with no date is not a fact`);
+    }
+    if (!isDate(rate['recorded'])) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} has a 'recorded' that is not a YYYY-MM-DD date`);
+    }
+    if (!('source' in rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} is missing 'source' -- a rate with no source cannot be re-derived`);
+    }
+    if (typeof rate['source'] !== 'string' || rate['source'] === '') {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} has a 'source' that is not a non-empty string`);
+    }
+    for (const cls of TOKEN_CLASSES) {
+        if (cls in rate && !isCount(rate[cls])) {
+            throw new PriceTableError(`price table rate ${pyRepr(model)} prices ${pyRepr(cls)} with something that is not a ` +
+                `non-negative integer below 2**53`);
+        }
+    }
+    if (!TOKEN_CLASSES.some((cls) => cls in rate)) {
+        throw new PriceTableError(`price table rate ${pyRepr(model)} prices no token class at all`);
+    }
+    const narrowed = { ...rate };
+    for (const cls of TOKEN_CLASSES) {
+        if (cls in rate)
+            narrowed[cls] = asCount(rate[cls]);
+    }
+    return rateView(narrowed);
+}
+/** `build_identity`'s shape, on purpose: one key, and the key IS the refusal. */
+function unavailable(reason) {
+    return { unavailable: reason };
+}
+/**
+ * Micro-USD as a fixed-6-decimal string, built from integers only.
+ *
+ * Non-negative input only; every producer in this module is a sum of non-negative products.
+ */
+export function formatMicros(micros) {
+    const n = BigInt(micros);
+    return `${n / MICROS_PER_UNIT_BIG}.${String(n % MICROS_PER_UNIT_BIG).padStart(6, '0')}`;
+}
+/**
+ * The cost of one `usage` block under one model's rate, or a named refusal.
+ *
+ * `table` must be a table `validatePriceTable` returned.
+ *
+ * THE ORDER OF THE CHECKS IS PART OF THE CONTRACT. The usage is validated BEFORE the model is
+ * looked up, so a caller who passed a malformed usage is told that, rather than being sent to
+ * edit a price table over a bug in the call.
+ *
+ * THE USAGE MUST CARRY ALL FOUR CLASSES AND NOTHING ELSE. See the reference: a token class
+ * silently ignored is money silently dropped, and a class silently defaulted to zero is money
+ * silently invented.
+ */
+export function priceTokens(table, model, usage) {
+    if (typeof model !== 'string') {
+        return unavailable('model must be a string');
+    }
+    if (!isPlainObject(usage)) {
+        return unavailable('usage must be a mapping of token class to count');
+    }
+    const extra = sortedByCodePoint(Object.keys(usage).filter((k) => !TOKEN_CLASSES.includes(k)));
+    if (extra.length > 0) {
+        return unavailable(`usage has unknown token class ${pyRepr(extra[0])} -- the price table prices exactly ${CLASSES}`);
+    }
+    for (const cls of TOKEN_CLASSES) {
+        if (!(cls in usage)) {
+            return unavailable(`usage is missing token class ${pyRepr(cls)} -- all four of ${CLASSES} must be ` +
+                `given, because a missing count is not a zero`);
+        }
+        if (!isCount(usage[cls])) {
+            return unavailable(`usage token class ${pyRepr(cls)} is not a non-negative integer below 2**53`);
+        }
+    }
+    const rate = table.rates?.[model];
+    if (rate === undefined) {
+        return unavailable(`no rate recorded for model ${pyRepr(model)} -- add one with its date and source, or ` +
+            `point ${PRICES_ENV} at a table that has it`);
+    }
+    const breakdown = {};
+    let total = 0n;
+    for (const cls of TOKEN_CLASSES) {
+        const count = asCount(usage[cls]);
+        let micros;
+        if (!(cls in rate)) {
+            // Zero tokens cost zero under ANY rate, so this arm invents nothing. Any other count
+            // with no rate is property 3 and is refused rather than silently dropped.
+            if (count !== 0) {
+                return unavailable(`rate for model ${pyRepr(model)} does not price ${pyRepr(cls)}, and ${count} such ` +
+                    `tokens were used -- a missing rate is not a zero`);
+            }
+            micros = 0n;
+        }
+        else {
+            micros = (BigInt(count) * BigInt(rate[cls]) + HALF_BIG) / MICROS_PER_UNIT_BIG;
+        }
+        breakdown[cls] = Number(micros);
+        total += micros;
+    }
+    if (total > MAX_SAFE_INT_BIG) {
+        return unavailable(`cost for model ${pyRepr(model)} exceeds 2**53-1 micro-USD, which is the largest ` +
+            `integer both runtimes represent exactly`);
+    }
+    const micros = Number(total);
+    return {
+        model,
+        currency: CURRENCY,
+        micros,
+        amount: formatMicros(micros),
+        breakdown,
+        rate: rateView(rate),
+    };
+}
+/**
+ * The rate that produced a cost, echoed in a fixed key order so the answer is re-derivable.
+ *
+ * Fixed order rather than the file's own order, because the file's order is not stable across
+ * the two JSON parsers and this object is compared byte for byte by the conformance suite.
+ */
+function rateView(rate) {
+    const view = { recorded: rate['recorded'], source: rate['source'] };
+    for (const cls of TOKEN_CLASSES) {
+        if (cls in rate)
+            view[cls] = rate[cls];
+    }
+    return view;
+}

package/dist/selfupdate.d.ts

@@ -0,0 +1,320 @@
+/**
+ * The command the operator typed, on BOTH runtimes. Not the package name — see the module
+ * docstring: PyPI has `bantamkit`, npm has `bantamkit-mcp`, and only this word is the same on
+ * both, so only this word can appear in a sentence the reference and this file share verbatim.
+ */
+export declare const PROGRAM = "bantamkit-mcp";
+/** The npm package this install would upgrade. Divergent by construction (`DISTRIBUTION`). */
+export declare const PACKAGE = "bantamkit-mcp";
+/**
+ * The one URL this toolbox ever fetches. Divergent by construction (`INDEX_URL`).
+ *
+ * `/latest` and not the full packument: the packument carries every version ever published and
+ * grows without bound, and the question here is one string. Measured 2026-09-11 — this document
+ * is 26 keys and carries `version` at the top level.
+ */
+export declare const INDEX_URL = "https://registry.npmjs.org/bantamkit-mcp/latest";
+/**
+ * Explicit, and short enough that a person who typed the flag does not think it hung.
+ * AS-7(3): the network is not on any other path here, so nothing else inherits this.
+ */
+export declare const DEFAULT_TIMEOUT_SECONDS = 10;
+/**
+ * What stands in for an installer that printed nothing, so the report has ONE shape rather
+ * than a line that is sometimes there. A conditional line is a second thing to port.
+ */
+export declare const NO_OUTPUT = "(nothing)";
+/**
+ * Line 1 of every report, and the opening of the no-route refusal. It carries BOTH numbers
+ * because "up to date" without them is unfalsifiable by the person reading it.
+ */
+export declare const COMPARISON = "{program} {installed} is installed; the package index has {latest}.";
+/** The user asked for this word specifically: "ถ้า match ให้แสดงคำ uptodate". */
+export declare const UP_TO_DATE = "up to date.";
+/**
+ * The registry BEHIND the installed version. A real state, not a curiosity: a checkout build,
+ * or a release that has not been published yet, both land here.
+ */
+export declare const AHEAD = "the installed version is ahead of the package index; there is nothing to update to.";
+/** What the command is about to run. The command itself is divergent; this line is not. */
+export declare const UPDATING = "updating from the package index: {command}";
+/** The installer's own words, never summarised. Both runtimes print the block the same way. */
+export declare const PRINTED = "the command printed:";
+export declare const UPDATED = "updated {program} from {installed} to {latest}.";
+/** AS-7(1), measured. This is the line that makes the success true rather than plausible. */
+export declare const RESTART: string;
+export declare const NO_ROUTE: string;
+export declare const TIMED_OUT: string;
+export declare const UNREACHABLE: string;
+export declare const NOT_A_VERSION: string;
+/**
+ * Multi-line on purpose. The installer's output is the only thing that says WHY it failed,
+ * and a refusal that swallowed it would send the operator to re-run the command by hand.
+ */
+export declare const COMMAND_FAILED: string;
+/**
+ * The install shape itself could not be derived — `identity.Undetermined`, which is what an
+ * origin that is neither an index nor a path on this machine raises (`git+https://…`). That
+ * exception already carries the operator's next step, so this sentence quotes it rather than
+ * paraphrasing it, and refuses rather than picking a route.
+ */
+export declare const SHAPE_UNKNOWN: string;
+/**
+ * The two ways a well-formed HTTP response can still not carry a version, as the `{why}` of
+ * `NOT_A_VERSION`. Both runtimes ask a different URL and read a different JSON path, so what
+ * is compared is that the same two failures produce the same two sentences.
+ */
+export declare const NOT_JSON = "the response is not JSON";
+export declare const NO_VERSION_FIELD = "the response carries no version string";
+/**
+ * The fallthrough for a shape word `ROUTES` has never heard of — `INSTALL_SHAPES` growing a
+ * sixth word. Not divergent: it names no package manager, so it is the reference's sentence.
+ */
+export declare const NO_RECORDED_ROUTE = "There is no recorded update route for a {shape} install, so --update will not guess one.";
+/**
+ * Per shape, what the real update route is — the answer to "then how DO I update this?".
+ * DIVERGENT BY CONSTRUCTION and registered in `docs/porting.md` by J46-31: the reference's
+ * rows name pip and a Python tree; these name npm and a BUILT one.
+ *
+ * `registry` is absent on purpose, exactly as it is there. It is the one shape that HAS a
+ * route through this flag, so a sentence telling its operator to go do it by hand would never
+ * be reachable, and an unreachable sentence is one more thing for nobody to check.
+ *
+ * `{command}` is the SAME string `upgradeCommand` builds and `UPDATING` prints, never a second
+ * spelling of it — `local-file` is the one row whose advice is an actual command, and the
+ * README's measured fix for the real incident is exactly this: `npm i --prefix
+ * ~/.local/share/bantamkit-mcp bantamkit-mcp@latest`.
+ *
+ * `linked` and `checkout` BOTH say "rebuild it". That is not padding and it is the difference
+ * from the reference that matters most on this side: an editable Python install serves the
+ * `.py` files a `git pull` just changed, and a Node install serves `dist/`, which is build
+ * output. `README.md#updating`'s checkout row already says `git pull && npm ci && npm run
+ * build`, and a route that stopped at `git pull` would be a remedy that changes nothing.
+ *
+ * `ephemeral` IS NOT A TRANSLATION OF THE REFERENCE'S ROW, and making it one would make it
+ * false. There it says "the next run fetches {latest} by itself", which is true of a `pipx
+ * run` environment; here the shape is an `npx` cache, and `README.md#silent-version-float`
+ * measured that `npx -y bantamkit-mcp` RESOLVES `latest` ONCE AND CACHES IT — two people with
+ * byte-identical config can be running builds resolved weeks apart. So this row is true of the
+ * cache that actually exists rather than of a fresh resolve that does not happen, and it names
+ * the only thing that changes it: the spec on the host's command line.
+ */
+export declare const ROUTES: Record<string, string>;
+/**
+ * A refusal carrying the sentence the operator should read. Never a stack trace.
+ *
+ * The same contract `hostinstall.InstallError` has, and for the same reason: `--update` can
+ * fail for four reasons that are all somebody else's to fix, and a stack trace names none.
+ */
+export declare class UpdateRefused extends Error {
+}
+/**
+ * The clock ran out. THE CONTRACT BETWEEN `fetchIndex` AND `update` IS THIS TYPE.
+ *
+ * On the reference side the distinction is `TimeoutError` vs any other `OSError`, and the
+ * ORDER of the two `except` clauses is load-bearing because `TimeoutError` IS an `OSError`.
+ * The Node hazard is the same one with different names, and it is MEASURED (Node v25.2.1):
+ * an `AbortSignal.timeout` abort arrives as a `DOMException` whose `name` is `'TimeoutError'`
+ * — and `DOMException` IS `instanceof Error`. So a `catch` that tested `instanceof Error`
+ * first would swallow every timeout into the unreachable arm, which names the wrong problem
+ * and sends the operator to check a network that is working. `test/selfupdate.test.mjs` pins
+ * both halves: that this class is an `Error`, and that the real abort reason is one too.
+ */
+export declare class IndexTimeout extends Error {
+}
+/**
+ * The install shape and the path it can be pointed at, as `--update` needs them.
+ *
+ * DELIBERATELY NOT `identity.Install`. That record carries `sourceReason`, which is the
+ * `build_identity` wire shape's business and not this flag's; and this keeps the whole
+ * decision table testable by constructing a shape directly, including shape words this
+ * runtime would never derive. `runUpdate` does the one-line translation.
+ */
+export interface Origin {
+    readonly shape: string;
+    readonly source: string;
+}
+/**
+ * WHERE an `npm install` would have to point to replace THIS copy, and whether that is the
+ * global tree. Not a second install-shape detector — it derives no shape and answers no shape
+ * question; the shape comes from `currentInstall()` and from nowhere else.
+ *
+ * `global` IS A RECORD, NOT A GUESS, AND THE DIFFERENCE IS DESTRUCTIVE. Measured on this
+ * machine 2026-09-11 with npm 11.6.2:
+ *
+ *   - `npm install --prefix <dir> <pkg>` installs into `<dir>/node_modules` and, when `<dir>`
+ *     already has the `package.json` npm itself wrote there, leaves every sibling package
+ *     alone.
+ *   - with NO `package.json` in `<dir>` — which is exactly the global tree's shape, confirmed
+ *     at `/Users/kktest/.local/share/mise/installs/node/25.2.1/lib`, where `node_modules` holds
+ *     `@shopify`, `eas-cli` and `npm` and there is no `package.json` beside it — the same
+ *     command PRUNES the siblings. A fixture with two packages came back with one.
+ *
+ * So the presence of that `package.json` is the discriminator, and it is a file npm writes for
+ * a `--prefix` install and does not write for a global one. Getting this backwards would make
+ * `--update` delete a developer's other global CLIs, which is worse than every failure this
+ * flag has a sentence for.
+ *
+ * `root` is `''` when no `node_modules` ancestor exists at all. That arm cannot be reached
+ * from the `registry` shape — `deriveInstall` answers `registry` only from inside a
+ * `node_modules` — and the pairing is pinned in `test/selfupdate.test.mjs` rather than left as
+ * a comment, because the global command it produces needs no root and would otherwise be
+ * silently plausible.
+ */
+export interface Environment {
+    readonly root: string;
+    readonly global: boolean;
+}
+export declare function installEnvironment(runningFile?: string): Environment;
+/**
+ * `str.format` over the one substitution shape these sentences use — `{name}` and nothing else.
+ *
+ * A missing key THROWS, the way `str.format` raises `KeyError`, rather than leaving `{name}`
+ * in the text: an unsubstituted placeholder reaching the operator is a defect the reference's
+ * suite asserts against by name, and a silent passthrough is how one ships.
+ */
+export declare function fill(template: string, values: Readonly<Record<string, string | number>>): string;
+/**
+ * `shlex.join`: `shlex.quote` each word and space them.
+ *
+ * Hand-rolled from CPython's own rule — `_find_unsafe = re.compile(r'[^\w@%+=:,./-]', re.ASCII)`
+ * — because the rendered command is printed to the operator by `UPDATING`, by `COMMAND_FAILED`
+ * and by the `local-file` route, and a prefix path with a space in it is the normal case on
+ * macOS and on Windows. Single quotes, with an embedded `'` closed and reopened the way
+ * `shlex.quote` does it, so the line can be pasted back into a shell unchanged.
+ */
+export declare function shlexJoin(command: readonly string[]): string;
+/**
+ * The version string out of the registry's JSON, or a named refusal. Pure — no network here.
+ *
+ * SPLIT FROM THE FETCH SO THE GARBAGE CASE IS TESTED THROUGH THE REAL PARSER, exactly as the
+ * reference splits it: a test that stubbed a parsed version would prove nothing about what
+ * happens when a captive-portal login page comes back with a 200, which is the realistic shape
+ * of "the index answered and it was not the index".
+ *
+ * THE JSON PATH IS THE DIVERGENCE. PyPI nests it at `info.version`; `registry.npmjs.org/<pkg>/
+ * latest` carries it at the top level. Both refusals below are the same two sentences.
+ */
+export declare function latestFromIndexPayload(text: string): string;
+/**
+ * The ONLY network call in this runtime. One request, one timeout, two failure words.
+ *
+ * THE PLATFORM'S `fetch`, NOT A DEPENDENCY. `package.json` declares exactly one runtime
+ * dependency and the pure-node `npx` install is a standing ruling, so the HTTP client is the
+ * one Node ships (>= 18, and `engines` already requires >= 20) and the deadline is
+ * `AbortSignal.timeout`, which is the same object the abort arrives as.
+ *
+ * THE CONTRACT WITH `update` IS THE EXCEPTION TYPE — see `IndexTimeout`. Measured on Node
+ * v25.2.1 against a local socket that accepts and never answers: the rejection is a
+ * `DOMException` named `TimeoutError`. Everything else is a `TypeError: fetch failed` whose
+ * `cause` carries the sentence worth printing — `connect ECONNREFUSED 127.0.0.1:49999`,
+ * `getaddrinfo ENOTFOUND …` — so the cause's message is what `UNREACHABLE` interpolates and
+ * the bare "fetch failed" never reaches an operator.
+ *
+ * A non-2xx is an `Error` and not a timeout, the way the reference turns `HTTPError` into a
+ * plain `OSError`; and the body is decoded leniently, because a body that is not UTF-8 is not
+ * a version either and should be refused BY NAME in `latestFromIndexPayload`.
+ */
+export declare function fetchIndex(url?: string, timeout?: number): Promise<string>;
+/**
+ * What a `registry` install upgrades with, ON THE TREE IT IS ACTUALLY IN.
+ *
+ * The reference's reason transfers exactly: "the server may be running from a venv whose `pip`
+ * is not the one first on `PATH`, and upgrading the wrong environment is a failure that
+ * reports success." Here the wrong environment is a different `node_modules`, and `--prefix` is
+ * npm's own way of naming the right one.
+ *
+ * `--global` FOR THE GLOBAL TREE AND NEVER `--prefix`. See `installEnvironment`: on a tree with
+ * no `package.json` beside `node_modules`, `npm install --prefix` prunes every sibling package.
+ * Both arms are the rows `README.md#updating` already documents.
+ *
+ * `@latest` IS NOT DECORATION. `npm install <pkg>` in a tree that already declares `<pkg>`
+ * satisfies the existing range rather than moving it, which is a command that exits 0 having
+ * changed nothing — the J46-4 defect, arrived at through npm's semantics rather than through
+ * this code's.
+ */
+export declare function upgradeCommand(environment: Environment): string[];
+/**
+ * Run the installer, capture what it said, return both. The only side effect in this module.
+ *
+ * CAPTURED RATHER THAN INHERITED so the report has one shape whether or not anybody is
+ * watching, and so a test can inject a substitute and assert on the command WITHOUT a real
+ * install ever running.
+ *
+ * THE ONE PLACE THIS IS NOT THE REFERENCE'S BEHAVIOUR: `stderr=STDOUT` genuinely interleaves
+ * the two streams in the order they happened, and `spawnSync` has no fd-dup, so the two pipes
+ * are concatenated instead — stdout, then stderr. npm writes its progress to stderr and its
+ * result to stdout, so an operator reading a failure still gets both, in two blocks rather than
+ * one. The installer's own words are never compared across runtimes; the sentences around them
+ * are.
+ *
+ * `shell: true` ON WINDOWS ONLY, the idiom `hostinstall.installViaClaudeCli` established for
+ * the same reason: npm is a `npm.cmd` batch shim there and `spawnSync` returns ENOENT for a
+ * batch file without a shell. Arguments are quoted because `cmd.exe` gets a string.
+ */
+export declare function runInstaller(command: readonly string[]): [number, string];
+/**
+ * -1 when the index is ahead, 0 when they agree, 1 when the installed version is ahead.
+ *
+ * The shorter of the two is padded with numeric zeros, so `0.30` and `0.30.0` agree — which is
+ * what a person means by them and what both registries would print for one release.
+ */
+export declare function compareVersions(installed: string, latest: string): number;
+/**
+ * `10` rather than `10.0`, because the sentence is read by a person, not parsed.
+ *
+ * The reference spells this out so that Node's default rendering of a whole number is what
+ * both sides print, which is what keeps `TIMED_OUT` byte-identical instead of ruled. Here it
+ * is the identity function on a number, and it exists so the pairing is visible from both
+ * files rather than only from one.
+ */
+export declare function seconds(timeout: number): string;
+export interface UpdateOptions {
+    readonly fetch?: (url: string, timeout: number) => Promise<string> | string;
+    readonly installer?: (command: string[]) => [number, string];
+    readonly url?: string;
+    readonly timeout?: number;
+    readonly environment?: Environment;
+}
+/**
+ * The whole flag: ask the index, compare, and act — or refuse, by name.
+ *
+ * THE TWO SEAMS ARE `fetch` AND `installer`, and they are options with real defaults rather
+ * than module bindings a test rewrites. A test that reached the registry would fail on a plane
+ * and pass for the wrong reason off a cache; a test that ran a real installer would rewrite the
+ * developer's own `node_modules` mid-suite. Both substitutes are handed in here, so every arm
+ * below is reachable offline and the npm command is CAPTURED, never run.
+ *
+ * THE INDEX IS ASKED BEFORE THE SHAPE IS JUDGED, and that order is the reference's and is
+ * deliberate. The user asked the flag to go and check the latest version; an operator on a
+ * checkout five releases behind is owed that number even though this flag will not be the thing
+ * that installs it. The shape decides the ACTION, never whether the question is asked.
+ */
+export declare function update(installed: string, origin: Origin, options?: UpdateOptions): Promise<string>;
+/**
+ * `--update` on the CLI: ask the package index, act on the answer, print what happened, exit.
+ *
+ * THE SENTENCES ARE NOT HERE. This function owns three things and nothing else: where the
+ * shape comes from, which stream each outcome is written to, and the exit code.
+ *
+ * STDOUT + EXIT 0 IS ONLY FOR AN ANSWER THAT IS ALREADY TRUE — up to date, the index behind,
+ * or an update that actually ran. Everything else is `error: <sentence>` on stderr and exit 1,
+ * including the install shapes this flag will not touch: an operator who typed `--update`
+ * asked for an update, and a command that exits 0 having changed nothing is the J46-4 defect
+ * by name. Exit 1 rather than 2 because argparse already owns 2 for a usage error.
+ *
+ * THE SHAPE IS `currentInstall()`'s ANSWER AND NOT A SECOND DETECTOR. J46-12 (`c9372ca`)
+ * shipped it as a module-level function taking no arguments and touching no server state,
+ * explicitly so this flag could ask it before a store or a transport exists.
+ *
+ * `Undetermined` — a `git+https://…` origin, which is neither an index nor a path on this
+ * machine — is a refusal and not a fallback. Its own message already names the route, so it is
+ * quoted rather than paraphrased.
+ *
+ * THE WRITERS ARE ARGUMENTS so this arm is testable without a subprocess and without rewriting
+ * `process.stdout`. `cli.ts` hands in the real two. Both receive a UTF-8 string, which is LF
+ * on every platform — the same reason the reference goes through `sys.stdout.buffer`, where
+ * `print` would emit CRLF on Windows and a byte-comparing conformance runner would read that
+ * as a divergence belonging to the writer rather than to the product.
+ */
+export declare function runUpdate(out: (text: string) => void, err: (text: string) => void, installed: string, packageDirectory: string, options?: UpdateOptions): Promise<number>;