@mcsherrylabs/pi-meerkat 0.10.1 → 0.11.0

package/installer/check-single-sdk.mjs

@@ -0,0 +1,151 @@
+// Single-SDK gate for the Meerkat derived images (FR-015/023/029, contracts/processor-image.md §2).
+//
+// The base image already carries exactly one @mcsherrylabs/evolver-client under /app/node_modules.
+// A derived image must not shadow it with a second copy, so the build stage installs the Meerkat
+// tree, proves it contains exactly one client at the pinned version == the base SDK's version, then
+// DELETES it (−−strip) so the final stage merges node_modules over the base and the base's own copy
+// is the only candidate. The final stage re-counts on the real image filesystem (−−count-image).
+//
+// Usage:
+//   node check-single-sdk.mjs <root> --expect <version> (--strip | --count-image) [--base-sdk /base-sdk.json]
+//
+//   --strip       assert exactly one node_modules/**/@mcsherrylabs/evolver-client/package.json under
+//                 <root> at version == --expect == the base SDK's version, refuse any top-level
+//                 hoisted base-SDK dependency (@noble/*) at a different version, then delete the
+//                 client directory so the final merge cannot shadow the base's copy.
+//   --count-image walk / (skipping /proc, /sys, /dev) and require exactly one client package.json at
+//                 /app/node_modules/@mcsherrylabs/evolver-client/package.json at version --expect.
+//
+// Plain Node ESM, no dependencies. Exits non-zero with a precise message on any violation.
+import { lstat, readFile, readdir, rm } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+
+const SDK = "@mcsherrylabs/evolver-client";
+
+function fail(message) {
+  process.stderr.write(`check-single-sdk: ${message}\n`);
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  if (args.length < 4) fail("usage: node check-single-sdk.mjs <root> --expect <version> (--strip | --count-image) [--base-sdk /base-sdk.json]");
+  const root = args[0];
+  let expect, mode, baseSdk = "/base-sdk.json";
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--expect") { expect = args[++i]; }
+    else if (args[i] === "--strip") { mode = "strip"; }
+    else if (args[i] === "--count-image") { mode = "count-image"; }
+    else if (args[i] === "--base-sdk") { baseSdk = args[++i]; }
+    else fail(`unrecognized argument: ${args[i]}`);
+  }
+  if (!expect) fail("missing --expect <version>");
+  if (!mode) fail("missing required mode: --strip or --count-image");
+  return { root, expect, mode, baseSdk };
+}
+
+async function json(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); }
+  catch (error) { fail(`cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+async function isDir(path) {
+  try { return (await lstat(path)).isDirectory(); } catch { return false; }
+}
+
+// Recursively collect every file at a path ending in `suffix`, pruning symlinked directories and
+// node_modules below an already-stripped client (never, since we strip only after collecting).
+async function walkFiles(dir, suffix, seenPaths = []) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); }
+  catch { return seenPaths; }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isSymbolicLink() || entry.isFile() && !full.endsWith(suffix)) continue;
+    if (entry.isDirectory()) {
+      await walkFiles(full, suffix, seenPaths);
+    } else if (full.endsWith(suffix)) {
+      seenPaths.push(full);
+    }
+  }
+  return seenPaths;
+}
+
+async function findSdkCopies(root) {
+  const index = `${sep}node_modules${sep}@mcsherrylabs${sep}evolver-client${sep}package.json`;
+  const hits = [];
+  async function descend(dir) {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules") {
+          // Direct scan of the two candidate SDK locations is enough to find a client copy; a
+          // nested client inside another package's node_modules is a full descent.
+          await descend(full);
+        } else {
+          await descend(full);
+        }
+      } else if (entry.name === "package.json" && full.endsWith(index)) {
+        hits.push(full);
+      }
+    }
+  }
+  await descend(root);
+  return hits;
+}
+
+const { root, expect, mode, baseSdk } = parseArgs(process.argv);
+
+if (mode === "strip") {
+  const base = await json(baseSdk);
+  if (typeof base.version !== "string" || !base.version) fail(`base SDK manifest ${baseSdk} has no version`);
+  if (base.version !== expect) fail(`base SDK version ${base.version} != pinned --expect ${expect}`);
+  const hits = await findSdkCopies(root);
+  if (hits.length !== 1) fail(`expected exactly one @mcsherrylabs/evolver-client under ${root}, found ${hits.length}${hits.length ? ":\n  " + hits.join("\n  ") : ""}`);
+  const sdk = await json(hits[0]);
+  if (sdk.version !== expect) fail(`build-stage SDK version ${sdk.version} != pinned --expect ${expect} (base ${base.version})`);
+  // Deleting the build-stage client also deletes its nested dependencies; after the final merge the
+  // base's client resolves @noble/* from /app/node_modules top level. A Meerkat dependency hoisting a
+  // different @noble/* version would silently replace the base SDK's crypto, so refuse that up front.
+  const deps = base.dependencies ?? {};
+  for (const [name, pin] of Object.entries(deps)) {
+    const top = join(root, "node_modules", name, "package.json");
+    if (!(await isDir(join(root, "node_modules", name)))) continue;
+    const dep = await json(top);
+    if (dep.version !== pin) fail(`top-level ${name}@${dep.version} would replace the base SDK's pin ${pin}; refusing to strip`);
+  }
+  // Delete exactly the client directory so the final stage resolves the base's copy.
+  const dir = join(root, "node_modules", "@mcsherrylabs", "evolver-client");
+  await rm(dir, { recursive: true, force: true });
+  process.stdout.write(`check-single-sdk: stripped ${dir} (version ${expect} == base; ${hits.length} copy)\n`);
+} else {
+  // --count-image: the real image filesystem has exactly one client, at the app root.
+  const skipped = new Set(["/proc", "/sys", "/dev"]);
+  const hits = [];
+  async function scan(dir) {
+    if (skipped.has(dir)) return;
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); }
+    catch { return; }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const full = join(dir, entry.name);
+      if (full.endsWith(`${sep}@mcsherrylabs${sep}evolver-client${sep}package.json`) && entry.isFile()) {
+        hits.push(full);
+      } else if (entry.isDirectory()) {
+        await scan(full);
+      }
+    }
+  }
+  await scan("/");
+  if (hits.length !== 1) fail(`expected exactly one @mcsherrylabs/evolver-client on the image filesystem, found ${hits.length}${hits.length ? ":\n  " + hits.join("\n  ") : ""}`);
+  if (hits[0] !== join(sep, "app", "node_modules", "@mcsherrylabs", "evolver-client", "package.json"))
+    fail(`the single SDK must live at /app/node_modules/@mcsherrylabs/evolver-client/package.json, found ${hits[0]}`);
+  const sdk = await json(hits[0]);
+  if (sdk.version !== expect) fail(`image SDK version ${sdk.version} != pinned --expect ${expect}`);
+  process.stdout.write(`check-single-sdk: exactly one SDK at ${hits[0]} (version ${expect})\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcsherrylabs/pi-meerkat",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Meerkat zero-parameter DevNet installer (local chain with --local), stdio MCP facade and registry tools, with a private pinned Evolver MCP child. Preserves the announcement contract and existing Pi extension.",
   "bin": {
     "meerkat-mcp": "./dist/mcp-cli.js"
@@ -29,9 +29,9 @@
     "check:plan-two:client": "tsx test/mcp-client-checks.ts"
   },
   "dependencies": {
-    "@mcsherrylabs/evolver-client": "0.23.0",
-    "@mcsherrylabs/evolver-core": "0.2.1",
-    "@mcsherrylabs/evolver-mcp": "0.16.0",
+    "@mcsherrylabs/evolver-client": "0.24.0",
+    "@mcsherrylabs/evolver-core": "0.2.2",
+    "@mcsherrylabs/evolver-mcp": "0.17.0",
     "@modelcontextprotocol/sdk": "1.32.1",
     "typebox": "1.3.32"
   },

package/dist/installer-runtime/dist/src/runtime.js

@@ -1,192 +0,0 @@
-// Meerkat composition root for the shared processor, not a second collector/runtime.
-// All paths/capabilities are operator-fixed here; requests can supply only a channel id.
-import { join } from "node:path";
-import { connect as netConnect } from "node:net";
-import { lstat, unlink } from "node:fs/promises";
-import { nodeControlRestarter, nodeObserver, nodePuller, startControlServer, startProcessor, startReadServer, subscriptionConfig, subscriptionController, } from "@mcsherrylabs/evolver-client/processor";
-import { ensureStateDir } from "./env.js";
-const productionSdk = {
-    nodeControlRestarter, nodeObserver, nodePuller, startControlServer, startProcessor,
-    startReadServer, subscriptionConfig, subscriptionController,
-};
-export function processorBinding() {
-    return { chainId: process.env.EVOLVER_CHAIN_ID?.trim() ?? "", nodeId: process.env.APP_NODE_ID?.trim() ?? "" };
-}
-export function processorConfigPath(target) {
-    return process.env.EVOLVER_SUBSCRIPTIONS_FILE?.trim() || join(target.stateDir, "subscriptions", "channels.conf");
-}
-export function processorStatePath(target) {
-    return join(target.stateDir, "registry.db");
-}
-/** A stale control socket left by an unclean registry exit would make the SDK's control
- * server refuse to bind ("Never unlink/steal a pre-existing socket"). Only when the path is
- * a SOCKET and nobody is listening (ECONNREFUSED on a bounded connect) is it safe to unlink:
- * this process is the sole owner of its control directory. A live owner (connect succeeds) or
- * any other error, or a non-socket path, is left untouched so the SDK refuses as designed. */
-export async function removeStaleControlSocket(socketPath) {
-    let stat;
-    try {
-        stat = await lstat(socketPath);
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return;
-        throw error;
-    }
-    if (!stat.isSocket())
-        return; // never unlink a non-socket; the node/SDK fails closed on it
-    const result = await new Promise(resolve => {
-        const socket = netConnect(socketPath);
-        const timer = setTimeout(() => { socket.destroy(); resolve("error"); }, 1000);
-        socket.once("connect", () => { clearTimeout(timer); socket.destroy(); resolve("connected"); });
-        socket.once("error", (error) => {
-            clearTimeout(timer);
-            resolve(error.code === "ECONNREFUSED" ? "refused" : "error");
-        });
-    });
-    if (result === "refused")
-        await unlink(socketPath);
-}
-export async function startMeerkatProcessor(args, sdk = productionSdk) {
-    const binding = processorBinding();
-    // Synchronous SDK validation of fixed expectations, NOT an online-node startup dependency.
-    const observe = sdk.nodeObserver({ baseUrl: args.target.nodeUrl, binding });
-    const config = sdk.subscriptionConfig(processorConfigPath(args.target));
-    await config.read(); // missing/malformed declaration refuses before opening storage; never reseed
-    let initialized = false;
-    ensureStateDir(args.target);
-    const runtime = await sdk.startProcessor({
-        store: {
-            path: processorStatePath(args.target), binding,
-            modules: args.worker ? [args.worker] : [],
-            limits: { maxEntriesPerChannel: 1000, maxBodyBytes: 64 * 1024 * 1024 },
-        },
-        puller: sdk.nodePuller(args.node), config,
-        // SDK initialization normally attempts setup (which can pace). Defer that attempt until
-        // the caller explicitly paces/runs: service composition binds recovery listeners first.
-        // Every subsequent pace still uses the SDK's verified node/chain/ACTIVE gate.
-        observe: async () => {
-            if (!initialized)
-                throw new Error("Meerkat listeners not started; collection deferred");
-            return observe();
-        },
-        tip: async () => String(await args.node.currentRound()),
-        modules: args.lifecycle ? [args.lifecycle] : [], say: args.say,
-    }).catch(error => {
-        if (error?.name === "ProcessorOwnerLockError") {
-            args.say(error.message);
-            args.say("MANUAL FORCE RECOVERY REQUIRED if the owner has died. Using the SAME Compose project/env/files/volumes: 1) docker compose stop app; stop any other collectors and disable all external automatic restarts. 2) Only when fenced: docker compose run --rm --no-deps app node dist/scripts/recover-owner.js --force. 3) docker compose up -d --no-deps app. For a host-run app, stop it and its supervisor first, then run node dist/scripts/recover-owner.js --force with the SAME target/state environment and restart normally. Ordinary restart or --force-recreate does NOT clear the lock. Never delete database/WAL or reinitialize subscriptions.");
-        }
-        throw error;
-    });
-    initialized = true;
-    return runtime;
-}
-/** Always attempt every release, including when another close fails. */
-export async function closeMeerkat(actions) {
-    const errors = [];
-    for (const action of actions) {
-        try {
-            await action();
-        }
-        catch (error) {
-            errors.push(error);
-        }
-    }
-    if (errors.length)
-        throw new AggregateError(errors, "Meerkat shutdown failed");
-}
-export async function startMeerkatServers(args, sdk = productionSdk) {
-    const servers = [];
-    try {
-        servers.push(await sdk.startReadServer({
-            store: args.runtime.store, port: args.port,
-            host: process.env.PROCESSOR_READ_HOST?.trim() || "127.0.0.1", routes: args.routes, say: args.say,
-        }));
-        const socketPath = process.env.EVOLVER_PROCESSOR_CONTROL_SOCKET?.trim();
-        if (socketPath) {
-            await removeStaleControlSocket(socketPath);
-            const binding = processorBinding();
-            const controller = sdk.subscriptionController({
-                binding, runtime: args.runtime, config: sdk.subscriptionConfig(processorConfigPath(args.target)),
-                observe: sdk.nodeObserver({ baseUrl: args.target.nodeUrl, binding }),
-                restart: sdk.nodeControlRestarter({ socketPath: "/node-control/node.sock", expected: binding }),
-            });
-            servers.push(await sdk.startControlServer({ socketPath, mode: 0o660, controller, say: args.say }));
-        }
-        return { port: servers[0].port, close: () => closeMeerkat([...servers].reverse().map(server => () => server.close())) };
-    }
-    catch (error) {
-        try {
-            await closeMeerkat(servers.reverse().map(server => () => server.close()));
-        }
-        catch (cleanup) {
-            throw new AggregateError([error, cleanup], "Meerkat listener startup failed");
-        }
-        throw error;
-    }
-}
-/** One service owner: bind listeners before run/setup, and release the worker on partial bind. */
-export async function startMeerkatService(args, sdk = productionSdk) {
-    const runtime = await startMeerkatProcessor(args, sdk);
-    let servers;
-    try {
-        servers = await startMeerkatServers({ ...args, runtime, routes: args.routes(runtime) }, sdk);
-        runtime.run();
-        let stopping;
-        return { runtime, port: servers.port, stop() {
-                return stopping ??= closeMeerkat([() => servers.close(), () => runtime.stop()]);
-            } };
-    }
-    catch (error) {
-        try {
-            await closeMeerkat([...(servers ? [() => servers.close()] : []), () => runtime.stop()]);
-        }
-        catch (cleanup) {
-            throw new AggregateError([error, cleanup], "Meerkat service startup failed");
-        }
-        throw error;
-    }
-}
-/** Signals and normal/error completion share one cleanup path, including partial async startup. */
-export function meerkatShutdown(signals = process) {
-    let stopping;
-    const releases = [];
-    const stop = () => stopping ??= closeMeerkat([...releases].reverse());
-    const onSignal = () => { void stop().then(() => signals.exit(0), error => { console.error(error); signals.exit(1); }); };
-    signals.once("SIGINT", onSignal);
-    signals.once("SIGTERM", onSignal);
-    return {
-        async own(start, release) {
-            if (stopping)
-                throw new Error("Meerkat stopped during startup");
-            const pending = start();
-            // Register before awaiting so a signal DURING startup waits for and releases its result.
-            releases.push(async () => {
-                let resource;
-                try {
-                    resource = await pending;
-                }
-                catch {
-                    return;
-                } // startup owns its partial cleanup
-                await release(resource);
-            });
-            const resource = await pending;
-            if (stopping) {
-                await stopping;
-                throw new Error("Meerkat stopped during startup");
-            }
-            return resource;
-        },
-        async close() {
-            try {
-                await stop();
-            }
-            finally {
-                signals.removeListener("SIGINT", onSignal);
-                signals.removeListener("SIGTERM", onSignal);
-            }
-        },
-    };
-}