bantamkit-mcp 0.29.1 → 0.30.0

package/README.md

@@ -1,7 +1,7 @@
 # bantamkit-mcp
 
 The bantamkit MCP server as a pure-Node package: `npx bantamkit-mcp`, no Python, no
-`uv`, no `pipx`, no interpreter bootstrap. It serves the same eleven tools, the same
+`uv`, no `pipx`, no interpreter bootstrap. It serves the same thirteen tools, the same
 `bantamkit_status` prompt and the same two resource templates as `runtime-py`'s server,
 reads and writes the same memory store, and is checked against the Python server frame by
 frame — 4500+ conformance cases, with every intentional difference written down as a

package/assets/tools/memory_dream.json

@@ -0,0 +1,20 @@
+{
+  "name": "memory_dream",
+  "description": "Consolidate the memories the project layer and the machine-wide profile layer hold under the SAME NAME, and say exactly what changed. Byte-identical copies collapse to one; a pair that has diverged is UNIONED — every claim from both copies survives, never a winner-takes-all — and a relative date in a body is annotated with the day it resolves to against that fact's own mtime, never against today. The survivor stays in the writable project layer and the profile copy MOVES to that store's archive/: nothing is deleted and any consumed memory can be restored by name. This is a correctness pass, not a token saving: the profile index is derived at read time and is not loaded from a prompt, so consolidating it frees approximately no bytes — what it buys is one copy of a ruling instead of two that can disagree. It defaults to a DRY RUN because the profile store is machine-wide: a memory archived out of it stops answering for every other project on this machine that has no store of its own. Read the plan first, then call it again with dry_run false to apply it.",
+  "surfaces": ["mcp"],
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "dry_run": {
+        "type": "boolean",
+        "description": "Preview only. True (the default) performs every read, merge and projection and writes nothing. Pass false to apply the plan."
+      }
+    }
+  },
+  "output_schema": {
+    "properties": { "result": { "title": "Result", "type": "string" } },
+    "required": ["result"],
+    "type": "object",
+    "title": "memory_dreamOutput"
+  }
+}

package/assets/tools/repo_map.json

@@ -0,0 +1,44 @@
+{
+  "name": "repo_map",
+  "description": "A ranked map of a source tree: every file's definitions, ordered by how central that file is to the files you name in `focus`, truncated to a byte budget. Call it when you are about to work on a file and want to know which OTHER files matter to it — the ports, the callers, the module it reaches through a private helper — rather than reading a directory listing and guessing. `focus` is the file or files you are editing, relative to `root` and POSIX-separated; they are excluded from the listing because you already have them open, and an empty focus gives plain centrality over the whole tree. This is a PRECISION pass and it is not a token saving: the gate this feature was supposed to clear was refuted by measurement — discovery is 0.114% of real prompt tokens, because 97.8% of the bill is cache_read — so a map does not make a session cheaper. What it buys is the right file found sooner. Nothing the scanner cannot read is dropped silently: every unread file resolves into a named omission (unknown-language, unreadable-bytes, size-cap, no-definitions, unreachable, per-file-cap, budget) counted in a footer that is NOT charged to the budget. The budget is UTF-8 BYTES of the listing, not tokens; there is no model tokenizer in either runtime and this tool will not pretend to one.",
+  "surfaces": [
+    "mcp"
+  ],
+  "parameters": {
+    "type": "object",
+    "required": [
+      "root"
+    ],
+    "properties": {
+      "root": {
+        "type": "string",
+        "description": "Directory to map, absolute or relative to the server's working directory"
+      },
+      "focus": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "The files you are working on, relative to `root` and POSIX-separated. They are excluded from the listing. A name that is not a scanned source is ignored rather than refused."
+      },
+      "budget": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "UTF-8 bytes of listing to render; default 4000. The omission footer is not charged against it."
+      }
+    }
+  },
+  "output_schema": {
+    "properties": {
+      "result": {
+        "title": "Result",
+        "type": "string"
+      }
+    },
+    "required": [
+      "result"
+    ],
+    "type": "object",
+    "title": "repo_mapOutput"
+  }
+}

package/dist/docread.d.ts

@@ -34,6 +34,7 @@
  * (`utf8Scan`).
  */
 import { BantamError } from './errors.js';
+import { cmpCodepoint, pyRepr, pyStrip } from './pysem.js';
 export declare const NS_S = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}";
 export declare const NS_W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}";
 export declare const NS_R = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}";
@@ -52,19 +53,15 @@ export declare const OMIT_UNMAPPED = "unmapped-text";
 export declare const OMIT_UNREAD_TAIL = "unread-tail";
 export declare const OMIT_SIZE_CAP = "size-cap";
 export declare const OMIT_UNPLACED_CELL = "unplaced-cell";
+export declare const OMIT_DUPLICATE_CELL = "duplicate-cell";
 /** Extraction failed. The message names what was seen, never just the format's own error. */
 export declare class DocumentReadError extends BantamError {
 }
-/** `str.strip()` with no argument. */
-export declare function pyStrip(s: string): string;
+export { cmpCodepoint, pyRepr, pyStrip };
 /** `str.split()` with no argument: runs of whitespace, no empty fields. */
 export declare function pySplit(s: string): string[];
 /** `str.splitlines()`: Python's line boundaries, terminators dropped. */
 export declare function pySplitlines(s: string): string[];
-/** `sorted()` on strings: by code point, which is not what `Array.sort` does above U+FFFF. */
-export declare function cmpCodepoint(a: string, b: string): number;
-/** `repr(str)`. */
-export declare function pyRepr(s: string): string;
 /** `repr(bytes)`. */
 export declare function bytesRepr(buf: Uint8Array): string;
 export interface Utf8Scan {
@@ -190,6 +187,35 @@ export declare class BadZipFile extends Error {
     constructor(message: string);
 }
 export declare function crc32(buf: Uint8Array): number;
+/**
+ * How much ONE MEMBER of a zip this reader will decompress and parse. The ceiling on the
+ * PARSE, which is a different door from `XLSX_MAX_TEXT_BYTES`: that one bounds the text a
+ * workbook renders, and it never stands in front of this, because `readMember` decompresses
+ * the member whole and `parsePart` builds a tree from it before the first row is rendered.
+ *
+ * MEASURED 2026-09-06 on this machine, through `docread.extract` on THIS runtime at the
+ * shipped constants, on a sheet of N `<row><c t="inlineStr"><is><t>x</t></is></c></row>`
+ * deflated by `deflateRawSync`, peak RSS from `process.resourceUsage().maxRSS`:
+ * 400,000 rows are 58,378 bytes on disk, declare 19,600,112, and took RSS from 102.2 MB to
+ * 1,039.3 MB in 1,019 ms with NO omission; 1,000,000 rows are 143,939 bytes, declare
+ * 49,000,112, and took it from 158.6 MB to 2,290.8 MB in 2,667 ms. Linear and unbounded —
+ * the memory is the `XmlElement` tree, not the text, so a budget over the rendering could
+ * not see it. The reference measured the same shape at 342.2 MB and 838.8 MB through
+ * `tracemalloc`; the numbers are not comparable (one counts a Python allocator, the other a
+ * whole process) and the SHAPE is what both of them state.
+ *
+ * 16 MiB, the number `TEXT_MAX_BYTES` states, because "how much of a file this reader reads"
+ * is one number — but under its OWN NAME, because it bounds a member of a container and not a
+ * file on a disk, and a bar that varies one must not be varying the other. The reference
+ * measured the corpus behind the figure: 25 OOXML/ODF packages under the goal's roots, the
+ * largest single XML member among them 4,283,286 bytes, 3.9x under this.
+ *
+ * A REFUSAL and not a truncation, which is the one place this module departs from
+ * "disclose, never truncate": half an XML document is not a smaller XML document, and a tree
+ * built from a severed member would carry text that is not what the file says. So the reader
+ * stops and names the member, the number the file declares and its own ceiling.
+ */
+export declare const ZIP_MEMBER_MAX_BYTES: number;
 /** `zipfile.ZipFile` read-only: the central directory, and `read(name)` with a CRC check. */
 export declare class ZipReader {
     private readonly data;
@@ -209,6 +235,8 @@ export declare class ZipReader {
         isDir: boolean;
     }[];
     has(name: string): boolean;
+    /** `getinfo(name).file_size`: what the central directory DECLARES, before any inflate. */
+    declaredSize(name: string): number;
     /** `ZipFile.read(name)`; a missing member is a `KeyError` — here `RangeError`, see `readMember`. */
     read(name: string): Buffer;
 }
@@ -293,6 +321,32 @@ export declare const XLSX_MAX_COLUMNS = 16384;
  */
 export declare const UNPLACED_SHAPE = "the column of a cell whose reference is not letters then digits";
 export declare const UNPLACED_RANGE = "the column of a cell past XFD, the last column the format has";
+export declare const DUPLICATE_CELL = "the text of a cell a later cell in the same row and column replaced";
+/**
+ * How much text ONE WORKBOOK may materialise, all sheets together. `XLSX_MAX_COLUMNS` bounds a
+ * ROW and nothing bounded the document, which is a ceiling with a hole in it: the width is
+ * bought a row at a time. MEASURED 2026-09-06 on both runtimes: 20,000 rows each holding one
+ * `XFD1` cell deflate to 53,967 bytes and materialise 327,680,000 bytes in ~9 s — 6,072x, out
+ * of a file small enough to mail.
+ *
+ * 16 MiB, the same figure `TEXT_MAX_BYTES` carries and for the same kind of reason, but under
+ * its OWN NAME because the two bound different things: bytes read off a disk there, bytes
+ * rendered out of a container here, and a bar that varies one must not be varying the other.
+ * MEASURED 2026-09-06 over the goal's roots: 15 `.xlsx`, the largest 8,664,227 bytes on disk,
+ * and the largest RENDERING among them 754,520 bytes — 22x under this budget, so no real
+ * workbook on this machine meets it.
+ *
+ * It bounds the RENDERING and nothing else. The sentence that stood here said it bounded the
+ * rendering "because the file is already bounded", and that was FALSE for the whole life of
+ * this constant: `readMember` decompressed a member whole and `parsePart` built a tree from
+ * it, both before the first row was rendered and both outside this budget, so 58,378 bytes on
+ * disk took RSS to 1,039.3 MB with no omission and this ceiling never saw it (review round 5,
+ * H1). What bounds the file is `ZIP_MEMBER_MAX_BYTES`, one door earlier; this bounds what
+ * comes out of it. The shortfall is disclosed as `OMIT_SIZE_CAP` counting the rows no sheet
+ * rendered: a row is what a caller addresses, and a byte count of text that was never built
+ * would be a number this reader cannot honestly produce.
+ */
+export declare const XLSX_MAX_TEXT_BYTES: number;
 /**
  * `B7` -> `[1, '']`. The cell's own reference decides its column; XML order is a fallback.
  *
@@ -320,8 +374,22 @@ export declare const UNPLACED_RANGE = "the column of a cell past XFD, the last c
  * spends asking for more.
  */
 export declare function columnIndex(ref: string | undefined, fallback: number): [number, string];
-export declare function extractXlsx(path: string): Document;
-export declare function extractDocx(path: string): Document;
+/**
+ * Every declared sheet, under ONE `XLSX_MAX_TEXT_BYTES` budget for the whole workbook.
+ *
+ * The budget is the document's, so it is made here and not in `sheetRows`, and the shortfall
+ * is disclosed at the document's grain for the same reason — it is not a fact about the sheet
+ * the budget happened to run out on. The cap is stated BEFORE the media tally, because the
+ * media a reader met is a count of what it met underneath the cap.
+ *
+ * `opened` is the reader `sniff` already had to build to decide this file is an OOXML package
+ * (entries (a)/(j)): before it was handed down, one `extract` read the whole archive off disk
+ * TWICE. It is a parameter and never a field, so its lifetime is this call — a reader kept
+ * across calls would answer from bytes no longer on disk, which is exactly what the document
+ * cache one layer up is keyed on (realpath, size, mtime_ns) to avoid.
+ */
+export declare function extractXlsx(path: string, opened?: ZipReader | null): Document;
+export declare function extractDocx(path: string, opened?: ZipReader | null): Document;
 /** `html.unescape`. */
 export declare function unescape(s: string): string;
 /** Rendered rows of one HTML fragment. A pure function of the string: no I/O, no host. */
@@ -349,6 +417,12 @@ export declare function a2bUu(line: Uint8Array): Buffer;
  */
 export declare function decodeUu(encoded: Buffer): Buffer;
 export declare function extractMhtml(path: string): Document;
+/**
+ * Markup to rows, up to `TEXT_MAX_BYTES` of it, saying how much it did not read.
+ *
+ * BOUNDED, entry (k): this did `readFileSync(path)`, so a 1 GB `.html` was materialised whole
+ * where a 1 GB `.txt` had stopped at the cap and counted the rest since J10.
+ */
 export declare function extractHtml(path: string): Document;
 export declare function extractText(path: string): Document;
 /** Dispatch on what the file IS. Anything unreadable raises, naming the container. */