bantamkit-mcp 0.29.2 → 0.31.0

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>;