bantamkit-mcp 0.34.1 → 0.34.3

package/README.md

@@ -30,7 +30,7 @@ intentional difference written down as a ruling.
 | [The operator CLI: `bantamkit-memory`](#the-operator-cli-bantamkit-memory) | The second bin: status, lint, compact, archive, restore |
 | [Memory stores are layered by default](#memory-stores-are-layered-by-default) | Why not to add `--store` by reflex |
 | [The asset pack](#the-asset-pack) | What ships in `assets/` and how it is found |
-| [Sharing a store with the Python server](#sharing-a-store-with-the-python-server) | Concurrent writes, and one hand-edit to avoid |
+| [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) | One store; concurrent writes, one hand-edit to avoid |
 | [Development](#development) | Build, test, conformance |
 | [Measurements and history](#measurements-and-history) | Where the measured numbers behind this page live |
 
@@ -261,7 +261,7 @@ dependency in a temp directory that will be deleted, and `npm update` cannot hel
 | Two machines with one config run different builds | [Silent version float](#silent-version-float): compare `build_id` |
 | `bantamkit_status` still shows the old version after an update | The host has not reconnected; restart the server |
 | Recall finds nothing, or the wrong store | Set `BANTAMKIT_MEMORY_DIR`; the reply names the store it searched |
-| `malformed fact file …` | A hand-edited fact has a bare non-string field; see [Sharing a store](#sharing-a-store-with-the-python-server) |
+| `malformed fact file …` | A hand-edited fact has a bare non-string field; see [Where the Python and Node servers differ](#where-the-python-and-node-servers-differ) |
 | `AssetNotFound: no assets directory found; set BANTAMKIT_ASSETS` | See [The asset pack](#the-asset-pack) |
 
 ## Configuration
@@ -381,9 +381,12 @@ the pack ships whole — 91 files / 238,751 bytes on 2026-09-15 — or `assets_d
 3. `<repo>/assets/` — two levels above `dist/`, for a dev checkout with nothing vendored.
 4. Otherwise `AssetNotFound: no assets directory found; set BANTAMKIT_ASSETS`.
 
-## Sharing a store with the Python server
+## Where the Python and Node servers differ
 
-Both servers read and write the same memory store; byte-compatibility is the product.
+Both servers read and write the same on-disk store; byte-compatibility is the product. Every
+feature lands in both in one change, and a conformance case compares their answers. Differences
+are deliberate and each is ruled in the
+[divergence table](https://github.com/Ink01101011/bantamkit/blob/main/docs/porting.md#where-the-two-runtimes-deliberately-differ):
 
 - **Concurrent writes are safe for the memory store and lossy for the checkpoint, in both
   runtimes.** `index.md` is derived from `facts/`, so the last writer re-enumerates everything

package/dist/eventlog.js

@@ -55,8 +55,8 @@
  * notice — the failure mode a diagnostic can least afford.
  */
 import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs';
-import { cmpCodepoint, osErrorClassName, pyExists, PyOSError, pyJoin, pyName, pyParent, pyParents } from './memory/pyfs.js';
-import { ensureBantamkitGitignore } from './memory/store.js';
+import { cmpCodepoint, osErrorClassName, pyExists, PyOSError, pyJoin, pyName, pyParent } from './memory/pyfs.js';
+import { bantamkitDirFor, ensureBantamkitGitignore } from './memory/store.js';
 /**
  * Environment switch. Unset or `off`/`0`/`false`/`no`/empty -> disabled. `on`/`1`/`true`/
  * `yes` -> the default file inside the memory store. Anything else is taken as the literal
@@ -254,13 +254,12 @@ export class EventLog {
         // USER RULING #2 (J51-8b): the ignore file is written only when THIS call is what
         // creates `.bantamkit`, so existence has to be checked BEFORE the mkdir below -- after
         // it, the directory unconditionally exists and the question is unanswerable.
-        let bantamkitDir = null;
-        for (const parent of pyParents(path)) {
-            if (pyName(parent) === '.bantamkit') {
-                bantamkitDir = parent;
-                break;
-            }
-        }
+        //
+        // J54-3: the walk moved into `bantamkitDirFor` beside the writer it feeds, so the two
+        // creators in this runtime ask the same question in the same words rather than keeping a
+        // copy each. The answer here is unchanged -- a log file is never itself named
+        // `.bantamkit`, so self-or-ancestors and ancestors give the same directory.
+        const bantamkitDir = bantamkitDirFor(path);
         const bantamkitDirExistedBefore = bantamkitDir !== null && pyExists(bantamkitDir);
         // `pyParent` and not `node:path`'s `dirname`: this module is reached from a Windows
         // host through the same code, and the reference's `Path(...).parent` is the spelling

package/dist/hostinstall.js

@@ -37,6 +37,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { currentInstall, Undetermined } from './mcp/identity.js';
+import { bantamkitDirFor, ensureBantamkitGitignore } from './memory/store.js';
 import { compareVersions, keptCli, keptManifest, keptPrefix, PACKAGE, runInstaller, shlexJoin } from './npminstall.js';
 import { dumpJson, fromJs } from './pyjson.js';
 export { keptCli, keptPrefix };
@@ -319,7 +320,28 @@ export function thisCommand(options = {}) {
     }
     const command = ['npm', 'install', '--prefix', prefix, `${PACKAGE}@${version}`];
     const rendered = shlexJoin(command);
+    // THE THIRD `.bantamkit` CREATOR (J54-3), and the one that creates the most of it: npm makes
+    // a missing `--prefix` itself, so this line — not `MemoryStore`, not `EventLog` — is what
+    // brings `<homedir>/.bantamkit` into existence on a machine that has never saved a memory.
+    // Measured on the machine this was found on: 28 MB of install tree under a `~/.bantamkit`
+    // with no `.gitignore`, every byte of it untracked in a `$HOME` that is a git repository.
+    //
+    // Checked BEFORE npm runs, per user ruling #2, for the reason both other creators check it
+    // before their own mkdir: afterwards the directory exists either way and the question
+    // "did THIS call create it" is unanswerable. A `~/.bantamkit` that was already there —
+    // holding an older kept install, a memory store, or an ignore file the operator deleted on
+    // purpose — is left exactly as it is.
+    const bantamkitDir = bantamkitDirFor(prefix);
+    const bantamkitDirExistedBefore = bantamkitDir !== null && existsSync(bantamkitDir);
     const [code, output] = (options.installer ?? runInstaller)(command);
+    // BEFORE THE REFUSALS, AND THAT ORDER IS MEASURED, not tidy. A `npm install --prefix` that
+    // FAILS still leaves the prefix behind: measured 2026-09-18 with `npm_config_offline=true`
+    // against an empty cache — exit 1, and `<home>/.bantamkit/mcp` there afterwards. A refusal
+    // that returned first would leave exactly the directory this closes over: made by bantamkit's
+    // own command, holding nothing anybody asked for, and visible to git. The helper never
+    // creates `bantamkitDir` itself, so an installer that made nothing writes nothing here.
+    if (bantamkitDir !== null)
+        ensureBantamkitGitignore(bantamkitDir, !bantamkitDirExistedBefore);
     const refused = `could not make the kept install at ${prefix}, so no host configuration was changed: ${rendered} exited ${code}`;
     if (code !== 0)
         throw new InstallError(`${refused}: ${lastLine(output)}`);

package/dist/memory/store.d.ts

@@ -33,6 +33,14 @@ export declare const BANTAMKIT_GITIGNORE_TEXT: string;
  * a `.bantamkit` that git can see (or ignore one it should not), which is the whole bug this
  * closes.
  *
+ * THE CREATORS, ENUMERATED (J54-3), because "anything else" is how one got missed: in THIS
+ * runtime there are exactly three — `MemoryStore.ensureDirs`, `EventLog`'s append-time
+ * `mkdirSync`, and `hostinstall.thisCommand`, where `--install` from an `npx` cache has npm
+ * create `<homedir>/.bantamkit/mcp` (npm makes a missing `--prefix` itself). The first two ask
+ * `bantamkitDirFor` which directory the decision is about rather than assuming the root's
+ * parent is it; the third is the one the reference does not have at all, because the offline
+ * install is Node-only by user ruling. `docs/porting.md` carries the row.
+ *
  * NEVER REWRITES. A `.gitignore` that already exists -- whatever its bytes -- is left
  * exactly as it is, kept as a second guard even when `created` is `true`: an operator who
  * deleted it to commit the directory keeps that decision, and this never diffs its own
@@ -48,6 +56,27 @@ export declare const BANTAMKIT_GITIGNORE_TEXT: string;
  * bring `.bantamkit` into existence early.
  */
 export declare function ensureBantamkitGitignore(directory: string, created: boolean): void;
+/**
+ * The `.bantamkit` directory a recursive mkdir of `path` would create or fill, or `null` when
+ * there is none: `path` itself if it is named `.bantamkit`, otherwise its nearest ancestor
+ * that is. `runtime-py/src/bantamkit/memory/store.py`'s `bantamkit_dir_for` is the reference.
+ *
+ * WHY A WALK AND NOT `pyParent(path)` (J54-3). Every creator has to hand
+ * `ensureBantamkitGitignore` the directory the decision is ABOUT, and the parent is the right
+ * answer for exactly one shape of path, `<x>/.bantamkit/memory`. A store rooted AT the
+ * `.bantamkit` directory (`--store ~/.bantamkit`) or nested deeper under it creates a
+ * `.bantamkit` whose gitignore decision was taken about the wrong directory — so no decision
+ * was taken at all, and git could see the whole tree. MEASURED, not hypothetical: `~/.bantamkit`
+ * on the machine this was found on holds an empty `facts/` and `archive/` beside `memory/`,
+ * left by a store once rooted at it, and no `.gitignore`.
+ *
+ * NEAREST AND NOT OUTERMOST, which is the choice `EventLog`'s append already made and this
+ * function now carries for both creators.
+ *
+ * READ-ONLY. It looks at names, never at the filesystem, so it is equally valid before or after
+ * the mkdir — but `created` is answered by checking THIS path's existence BEFORE.
+ */
+export declare function bantamkitDirFor(path: string): string | null;
 /** `sorted(VALID_TYPES)` is what the error message interpolates, so the order is load-bearing. */
 export declare const VALID_TYPES: readonly ["feedback", "project", "reference", "user"];
 /**

package/dist/memory/store.js

@@ -42,7 +42,7 @@ import { basename } from 'node:path';
 import { BantamError } from '../errors.js';
 import { formatFact, parseFrontmatter, pySplit, pyStrip, todayLocal } from './factfile.js';
 import { PyScalar } from './pyyaml.js';
-import { asPyOSError, cmpCodepoint, matchesMd, pyExists, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, pyParent, pyReadText, pyReplace, pyScandirNames, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, PyOSError, sortedPathNames, } from './pyfs.js';
+import { asPyOSError, cmpCodepoint, matchesMd, pyExists, pyJoin, pyLexists, pyMkdirParents, pyMtimeDate, pyName, pyParent, pyParents, pyReadText, pyReplace, pyScandirNames, pySuffix, pyUnlink, pyWithSuffix, pyWriteText, PyOSError, sortedPathNames, } from './pyfs.js';
 /**
  * The exact bytes written into a `.bantamkit/.gitignore` the first time such a directory is
  * brought into existence (user ruling 2026-09-15, `.shiftwork/notes-job51/P0-probes.md`).
@@ -76,6 +76,14 @@ export const BANTAMKIT_GITIGNORE_TEXT = '# Created by bantamkit: this directory
  * a `.bantamkit` that git can see (or ignore one it should not), which is the whole bug this
  * closes.
  *
+ * THE CREATORS, ENUMERATED (J54-3), because "anything else" is how one got missed: in THIS
+ * runtime there are exactly three — `MemoryStore.ensureDirs`, `EventLog`'s append-time
+ * `mkdirSync`, and `hostinstall.thisCommand`, where `--install` from an `npx` cache has npm
+ * create `<homedir>/.bantamkit/mcp` (npm makes a missing `--prefix` itself). The first two ask
+ * `bantamkitDirFor` which directory the decision is about rather than assuming the root's
+ * parent is it; the third is the one the reference does not have at all, because the offline
+ * install is Node-only by user ruling. `docs/porting.md` carries the row.
+ *
  * NEVER REWRITES. A `.gitignore` that already exists -- whatever its bytes -- is left
  * exactly as it is, kept as a second guard even when `created` is `true`: an operator who
  * deleted it to commit the directory keeps that decision, and this never diffs its own
@@ -103,6 +111,33 @@ export function ensureBantamkitGitignore(directory, created) {
         /* best-effort: a missing ignore file is not worth a lost fact */
     }
 }
+/**
+ * The `.bantamkit` directory a recursive mkdir of `path` would create or fill, or `null` when
+ * there is none: `path` itself if it is named `.bantamkit`, otherwise its nearest ancestor
+ * that is. `runtime-py/src/bantamkit/memory/store.py`'s `bantamkit_dir_for` is the reference.
+ *
+ * WHY A WALK AND NOT `pyParent(path)` (J54-3). Every creator has to hand
+ * `ensureBantamkitGitignore` the directory the decision is ABOUT, and the parent is the right
+ * answer for exactly one shape of path, `<x>/.bantamkit/memory`. A store rooted AT the
+ * `.bantamkit` directory (`--store ~/.bantamkit`) or nested deeper under it creates a
+ * `.bantamkit` whose gitignore decision was taken about the wrong directory — so no decision
+ * was taken at all, and git could see the whole tree. MEASURED, not hypothetical: `~/.bantamkit`
+ * on the machine this was found on holds an empty `facts/` and `archive/` beside `memory/`,
+ * left by a store once rooted at it, and no `.gitignore`.
+ *
+ * NEAREST AND NOT OUTERMOST, which is the choice `EventLog`'s append already made and this
+ * function now carries for both creators.
+ *
+ * READ-ONLY. It looks at names, never at the filesystem, so it is equally valid before or after
+ * the mkdir — but `created` is answered by checking THIS path's existence BEFORE.
+ */
+export function bantamkitDirFor(path) {
+    for (const candidate of [path, ...pyParents(path)]) {
+        if (pyName(candidate) === '.bantamkit')
+            return candidate;
+    }
+    return null;
+}
 /** `sorted(VALID_TYPES)` is what the error message interpolates, so the order is load-bearing. */
 export const VALID_TYPES = ['feedback', 'project', 'reference', 'user'];
 /**
@@ -598,8 +633,13 @@ export class MemoryStore {
         // Checked BEFORE the mkdir below, per user ruling #2: this is the one moment that can
         // tell whether `.bantamkit` already existed. After the mkdir it unconditionally exists
         // either way, so the answer has to be captured now or not at all.
-        const bantamkitDir = pyParent(this.root);
-        const bantamkitDirExistedBefore = pyExists(bantamkitDir);
+        //
+        // J54-3: `bantamkitDirFor`, not `pyParent`. The mkdirs below create every missing
+        // component of `this.root` — a root that IS the `.bantamkit` directory, or one nested
+        // deeper under it, brought a `.bantamkit` into existence while the decision was being
+        // taken about some other directory, which meant no decision at all.
+        const bantamkitDir = bantamkitDirFor(this.root);
+        const bantamkitDirExistedBefore = bantamkitDir !== null && pyExists(bantamkitDir);
         try {
             pyMkdirParents(pyJoin(this.root, 'facts'));
             pyMkdirParents(pyJoin(this.root, 'archive'));
@@ -610,7 +650,8 @@ export class MemoryStore {
             throw new MemoryValidationError(`memory store could not be created: ${this.root}; the directory is not` +
                 ' there and this filesystem would not make it, so nothing was written');
         }
-        ensureBantamkitGitignore(bantamkitDir, !bantamkitDirExistedBefore);
+        if (bantamkitDir !== null)
+            ensureBantamkitGitignore(bantamkitDir, !bantamkitDirExistedBefore);
     }
     // ---- ops ----
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.34.1",
+  "version": "0.34.3",
   "description": "Memory MCP server for Claude Code, Cursor, VS Code Copilot and Claude Desktop: per-person memory, JSON Schema validation, shift-work tools. Pure Node; install once with npx, run offline.",
   "keywords": [
     "mcp",