@mcsherrylabs/pi-meerkat 0.7.0 → 0.8.0

package/installer/runtime-control.mjs

@@ -0,0 +1,172 @@
+// Fixed-target installer helper, not an MCP tool or arbitrary URL/shell executor.
+import { mkdir, readFile, writeFile, unlink, lstat } from 'node:fs/promises';
+import { publishSessionPid } from './session-files.mjs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { loadFacadeConfig, saveFacadeConfig } from '../dist/mcp-config.js';
+const [mode, argument] = process.argv.slice(2);
+const TIMEOUT = 180_000;
+const agentDir = '/meerkat/agent';
+const configPath = join(agentDir, 'facade.json');
+async function json(path, headers) {
+  const response = await fetch(path, { headers: { Accept: 'application/json', ...headers }, signal: AbortSignal.timeout(5000) });
+  if (!response.ok) throw new Error(`read ${new URL(path).pathname}: HTTP ${response.status}`);
+  return response.json();
+}
+async function until(description, check) {
+  const end = Date.now() + TIMEOUT;
+  let reason = 'not observed';
+  while (Date.now() < end) {
+    try { return await check(); } catch (e) { if (e?.permanent) throw e; reason = e instanceof Error ? e.message : 'read failed'; }
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+  throw new Error(`${description} not ready within ${TIMEOUT / 1000}s: ${reason}; state retained, nothing reset`);
+}
+async function child(command, args, env) {
+  await new Promise((resolve, reject) => {
+    const proc = spawn(command, args, { env, stdio: ['ignore', 'ignore', 'pipe'] });
+    let reason = '';
+    proc.stderr.on('data', data => { reason = (reason + String(data)).slice(-8192); });
+    const timer = setTimeout(() => proc.kill('SIGTERM'), TIMEOUT);
+    const hard = setTimeout(() => proc.kill('SIGKILL'), TIMEOUT + 5000);
+    proc.once('error', reject);
+    proc.once('close', code => { clearTimeout(timer); clearTimeout(hard);
+      code === 0 ? resolve() : reject(new Error(`released Evolver bootstrap failed: ${reason}`)); });
+  });
+}
+function parameters() {
+  const args = JSON.parse(argument);
+  if (!/^[A-Za-z0-9]{1,50}$/.test(args.nodeId) || !/^[A-Za-z0-9]{1,50}$/.test(args.committeeId) || !/^[A-Za-z0-9]{1,50}$/.test(args.identity) ||
+      !/^meerkat\.[0-9a-f]{24}\.announcements$/.test(args.channel)) throw new Error('invalid saved deployment parameters');
+  if (args.binding && (args.binding.nodeId !== args.nodeId || !/^[0-9a-f]{64}$/.test(args.binding.chainId))) throw new Error('invalid saved binding');
+  return args;
+}
+const sessions = join(agentDir, 'sessions');
+function sessionPath(token) {
+  if (!/^[0-9a-f]{32}$/.test(token)) throw new Error('invalid owned session token');
+  return join(sessions, `${token}.json`);
+}
+async function stopSession(token) {
+  const path = sessionPath(token);
+  let saved;
+  try { saved = JSON.parse(await readFile(path, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return; throw e; }
+  if (!Number.isSafeInteger(saved.pid) || (saved.pid !== 0 && saved.pid < 2)) throw new Error('invalid owned session process');
+  if (saved.pid === 0) {
+    // The host allocated this token before starting exec; cancellation wins the startup race.
+    await writeFile(`${path}.cancel`, '', { flag: 'wx', mode: 0o600 }).catch(e => { if (e.code !== 'EEXIST') throw e; });
+  } else {
+    let cmd;
+    try { cmd = (await readFile(`/proc/${saved.pid}/cmdline`, 'utf8')).split('\0'); }
+    catch (e) {
+      if (e.code === 'ENOENT') {
+        try { await lstat(path); } catch (gone) { if (gone.code === 'ENOENT') return; throw gone; }
+        throw new Error('owned session ended without cleanup; no PID reuse or lock recovery');
+      }
+      throw e;
+    }
+    if (!cmd.includes('serve-session') || !cmd.includes(token)) throw new Error('owned session PID no longer matches; refusing signal');
+    process.kill(saved.pid, 'SIGTERM');
+  }
+  const end = Date.now() + 15_000;
+  while (Date.now() < end) {
+    try {
+      await lstat(path);
+      if (saved.pid === 0 && JSON.parse(await readFile(path, 'utf8')).pid > 0) { await stopSession(token); return; }
+    } catch (e) { if (e.code === 'ENOENT') return; throw e; }
+    await new Promise(resolve => setTimeout(resolve, 25));
+  }
+  throw new Error('owned facade did not finish child/socket cleanup within 15s');
+}
+async function main() {
+  if (mode === 'prepare-session') {
+    await mkdir(sessions, { recursive: true, mode: 0o700 });
+    await writeFile(sessionPath(argument), JSON.stringify({ pid: 0 }), { flag: 'wx', mode: 0o600 });
+    return;
+  }
+  if (mode === 'discard-session') {
+    const path = sessionPath(argument);
+    const saved = JSON.parse(await readFile(path, 'utf8'));
+    if (saved.pid !== 0) throw new Error('cannot discard a running owned session');
+    await unlink(path);
+    return;
+  }
+  if (mode === 'serve-session') {
+    const path = sessionPath(argument);
+    const saved = JSON.parse(await readFile(path, 'utf8'));
+    if (saved.pid !== 0) throw new Error('owned session token is already running');
+    // Import/configuration has a startup interval before the facade installs its handlers.
+    // Install guards BEFORE publishing the PID; publish atomically so a concurrent stop never
+    // sees a truncated/partial descriptor or a live PID with no cleanup handler.
+    let cancelled = false;
+    const earlyStop = () => { cancelled = true; };
+    process.once('SIGTERM', earlyStop); process.once('SIGINT', earlyStop);
+    try {
+      await publishSessionPid(path, process.pid);
+      try { await lstat(`${path}.cancel`); cancelled = true; } catch (e) { if (e.code !== 'ENOENT') throw e; }
+      if (cancelled) return;
+      process.argv = [process.execPath, new URL('../dist/mcp-cli.js', import.meta.url).pathname, '--config', configPath];
+      // The CLI's existing shutdown path handles EOF/signals and awaits its exact private child.
+      const facade = import('../dist/mcp-cli.js');
+      const abort = setInterval(() => { if (cancelled && process.listenerCount('SIGTERM') > 0) process.emit('SIGTERM'); }, 10);
+      try { await facade; } finally { clearInterval(abort); }
+    } finally {
+      process.off('SIGTERM', earlyStop); process.off('SIGINT', earlyStop);
+      await unlink(path);
+      await unlink(`${path}.cancel`).catch(e => { if (e.code !== 'ENOENT') throw e; });
+    }
+    return;
+  }
+  if (mode === 'stop-session') { await stopSession(argument); return; }
+  const args = parameters();
+  if (mode === 'committee-ready') {
+    await until('owned local consensus committee', async () => {
+      const status = await json('http://committee:8440/status');
+      if (status.nodeId && status.nodeId !== args.committeeId) throw Object.assign(new Error('owned committee identity differs'), { permanent: true });
+      if (status.nodeId !== args.committeeId || !Number.isInteger(status.blockHeight) || status.blockHeight < 2 || status.selfQuorumIndex !== 0 || status.appliedRound !== null)
+        throw new Error('committee has not committed/funded its local chain with ordinary apply');
+    });
+    return;
+  }
+  if (mode === 'node-binding') {
+    const binding = await until('owned processing node', async () => {
+      const value = await json('http://node:8440/api/channel/processor-state');
+      if (!value.processing || !/^[0-9a-f]{64}$/.test(value.binding?.chainId)) throw new Error('processing/genesis observation not ready');
+      if (value.binding.nodeId !== args.nodeId) throw Object.assign(new Error('owned node identity differs; refusing re-pairing'), { permanent: true });
+      if (args.binding && args.binding.chainId !== value.binding.chainId) throw Object.assign(new Error('saved genesis differs; refusing re-pairing'), { permanent: true });
+      return value.binding;
+    });
+    process.stdout.write(JSON.stringify(binding) + '\n');
+    return;
+  }
+  if (!args.binding) throw new Error('missing saved node binding');
+  const headers = { 'x-evolver-chain-id': args.binding.chainId, 'x-evolver-node-id': args.binding.nodeId };
+  if (mode === 'ready') {
+    await until('Meerkat registry/channel/inbox', async () => {
+      const summary = await json('http://127.0.0.1:8090/summary', headers);
+      await json('http://127.0.0.1:8090/inbox', headers);
+      if (summary.channel !== args.channel) throw new Error('registry channel differs');
+      const terms = await json(`http://node:8440/api/explorer/channels/${encodeURIComponent(args.channel)}`);
+      if (!Array.isArray(terms.owners) || !terms.owners.length || terms.writePolicy !== 'open' || terms.da) throw new Error('registry channel not provisioned with open writes/no DA');
+    });
+    return;
+  }
+  if (mode === 'bootstrap') {
+    const { resolveUpstreamBin } = await import('../dist/mcp-upstream.js');
+    const cli = await resolveUpstreamBin();
+    await child(process.execPath, [cli, '--bootstrap', '--target', 'local', '--identity', args.identity], {
+      PATH: process.env.PATH, HOME: agentDir, EVOLVER_NODE: 'http://node:8440', EVOLVER_FAUCET_URL: 'http://committee:8440',
+      EVOLVER_CONTENT_URL: 'http://node:8450', EVOLVER_MCP_STATE_DIR: agentDir, EVOLVER_BOOTSTRAP_CWD: agentDir,
+    });
+    const config = { version: 1, url: 'http://node:8440', identity: args.identity, tls: { insecure: false },
+      meerkat: { contentUrl: 'http://node:8450', keyPath: join(agentDir, `${args.identity}.key`), keyType: 'bls',
+        registryUrl: 'http://127.0.0.1:8090', chainId: args.binding.chainId, nodeId: args.nodeId, channel: args.channel } };
+    let existing;
+    try { existing = await loadFacadeConfig(configPath); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    if (existing) { if (JSON.stringify(existing) !== JSON.stringify(config)) throw new Error('unrelated saved facade authority; refusing replacement'); }
+    else await saveFacadeConfig(configPath, config);
+    return;
+  }
+  throw new Error('unknown installer runtime operation');
+}
+await main().catch(error => { console.error(error instanceof Error ? error.message : 'installer runtime failed'); process.exitCode = 1; });

package/installer/session-files.mjs

@@ -0,0 +1,16 @@
+// A remote session PID must become visible all at once; stop-session may read concurrently.
+import { open, rename, unlink } from 'node:fs/promises';
+export async function publishSessionPid(path, pid, prepared = async () => {}) {
+  const temporary = `${path}.${pid}.tmp`;
+  const handle = await open(temporary, 'wx', 0o600);
+  let renamed = false;
+  try {
+    try { await handle.writeFile(JSON.stringify({ pid })); await handle.sync(); }
+    finally { await handle.close(); }
+    await prepared();
+    await rename(temporary, path);
+    renamed = true;
+  } finally {
+    if (!renamed) await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mcsherrylabs/pi-meerkat",
-  "version": "0.7.0",
-  "description": "Meerkat stdio MCP facade and registry tools, with a private pinned Evolver MCP child. Owns the announcement wire contract and preserves the existing Pi extension.",
+  "version": "0.8.0",
+  "description": "Meerkat zero-parameter local installer, 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"
   },
@@ -17,7 +17,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/bundle-installer.mjs",
     "prepack": "npm run build",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
@@ -25,7 +25,7 @@
     "check:surface": "tsx test/surface-checks.ts",
     "test": "npm run build && npm run typecheck && npm run check:contract && npm run check:surface && npm run check:inbox && npm run check:mcp:unit && npm run check:plan-two:client",
     "check:inbox": "tsx test/inbox-tool-checks.ts",
-    "check:mcp:unit": "tsx test/mcp-announce-checks.ts && tsx test/mcp-facade-unit-checks.ts",
+    "check:mcp:unit": "tsx test/mcp-announce-checks.ts && tsx test/mcp-facade-unit-checks.ts && tsx test/installer-checks.ts && tsx test/detail-read-checks.ts && node test/installer-session-checks.mjs",
     "check:plan-two:client": "tsx test/mcp-client-checks.ts"
   },
   "dependencies": {
@@ -48,6 +48,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "installer",
     "extensions",
     "skills",
     "README.md"