@lifeaitools/rdc-skills 0.25.4 → 0.25.9

package/scripts/local-install-with-stop.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Install rdc-skills globally FROM LOCAL SOURCE, using the stop-first sequence.
+#
+# This is the empirical test of the fix: the same `npm install -g` that produced
+# EBUSY should now succeed because the lock holder is stopped first. It is a LOCAL
+# install (a path, not the registry) — nothing is published.
+#
+# The restart is unconditional: leaving the MCP down after a failed install would
+# be worse than the failure being repaired.
+set -u
+
+HOLDER=rdc-skills-mcp
+
+echo "== before =="
+pm2 jlist | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{const p=JSON.parse(s).find(x=>x.name===process.argv[1]);console.log('  '+process.argv[1]+': '+(p?p.pm2_env.status:'absent'));})" "$HOLDER"
+npm ls -g '@lifeaitools/rdc-skills' --depth=0 2>/dev/null | tail -1
+
+echo "== stop the lock holder =="
+pm2 stop "$HOLDER" >/dev/null 2>&1 && echo "  stopped $HOLDER" || echo "  could not stop (may be absent)"
+
+echo "== npm install -g from local source =="
+set +e
+npm install -g "C:/Dev/rdc-skills" 2>&1 | tail -5
+INSTALL_RC=${PIPESTATUS[0]}
+set -e
+echo "  install exit=$INSTALL_RC"
+
+echo "== restart (always) =="
+pm2 restart "$HOLDER" >/dev/null 2>&1 && echo "  restarted $HOLDER" || echo "  restart FAILED"
+
+echo "== after =="
+npm ls -g '@lifeaitools/rdc-skills' --depth=0 2>/dev/null | tail -1
+for i in 1 2 3 4 5 6 7 8; do
+  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 3 http://127.0.0.1:3110/health 2>/dev/null)
+  [ "$code" = "200" ] && break
+  sleep 1
+done
+echo "  health 3110 -> HTTP ${code:-none}"
+curl -s --max-time 3 http://127.0.0.1:3110/health 2>/dev/null | head -c 200
+echo
+exit "$INSTALL_RC"

package/scripts/probe-box-lock.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * Prove the box-wide update is SINGLE-FLIGHT under concurrent session starts.
+ *
+ * The bug this guards: rdc-skills is one box-wide npm package and one PM2 process,
+ * but every session/worktree runs the SessionStart hook. Without a lock, N sessions
+ * each conclude "unhealthy" and each run `npm install -g` on the same directory.
+ *
+ * Imports the REAL implementation from hooks/lib/box-lock.js. An earlier version
+ * kept its own copy of these functions, which drifted to the old algorithm — so it
+ * reported PASS for code that was not shipping. A test that duplicates its subject
+ * tests nothing.
+ */
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const HOOK_LIB = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'hooks', 'lib', 'box-lock.js');
+const { acquireBoxLock, releaseBoxLock, LOCK_PATH, LOCK_STALE_MS } = require(HOOK_LIB);
+
+const release = () => { try { fs.unlinkSync(LOCK_PATH); } catch { /* ignore */ } };
+
+release(); // clean slate
+let fail = 0;
+const check = (name, ok) => { console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}`); if (!ok) fail++; };
+
+// 1. Happy path. SEQUENTIAL and in-process, so it proves only that a held lock is
+//    not handed out twice — it cannot exercise interleaving. Test 7 does that.
+const winners = Array.from({ length: 10 }, () => acquireBoxLock()).filter(Boolean).length;
+check(`sequential starts: exactly 1 updater of 10 (got ${winners})`, winners === 1);
+
+// 2. A live holder is respected — a follower must NOT steal the lock.
+check('live lock respected', acquireBoxLock() === false);
+
+// 3. Release hands the box to the next session.
+releaseBoxLock();
+check('after release, next session leads', acquireBoxLock() === true);
+releaseBoxLock();
+
+// 4. A dead owner must not wedge every future session forever.
+fs.writeFileSync(LOCK_PATH, JSON.stringify({ pid: 999999, ts: new Date().toISOString() }));
+check('dead owner reclaimed', acquireBoxLock() === true);
+releaseBoxLock();
+
+// 5. A stale-but-live lock (crashed mid-install, PID reused) is reclaimed by age.
+fs.writeFileSync(LOCK_PATH, JSON.stringify({
+  pid: process.pid, ts: new Date(Date.now() - LOCK_STALE_MS - 1000).toISOString(),
+}));
+check('stale lock reclaimed by age', acquireBoxLock() === true);
+releaseBoxLock();
+
+// 6. Corrupt bodies must not wedge the box. `pid: 0` is the sharp one:
+//    process.kill(0, 0) signals the CURRENT PROCESS GROUP and succeeds, so a naive
+//    liveness check reads it as alive forever; paired with an unparseable ts, the
+//    age check is NaN and never trips either.
+for (const body of ['not json', '{"pid":0,"ts":"garbage"}', '{"pid":-1,"ts":null}', '{}']) {
+  fs.writeFileSync(LOCK_PATH, body);
+  check(`corrupt lock reclaimed: ${body.slice(0, 26)}`, acquireBoxLock() === true);
+  releaseBoxLock();
+}
+
+// 7. REAL concurrency against a STALE lock — the reclaim TOCTOU.
+//
+//    The naive reclaim (read -> judge stale -> unlink -> open 'wx') lets two racers
+//    both judge the lock stale, and the loser's unlink deletes the WINNER's fresh
+//    lock, so both become leader and both run `npm install -g`. Sequential calls in
+//    one process can never surface this; only real processes racing can.
+{
+  // A leader HOLDS the lock briefly before exiting. Without the hold, a winner
+  // exits (releasing on 'exit') before the next racer even calls acquire, so every
+  // racer wins in turn and the result looks like a race that never happened.
+  const racer = `
+    const { acquireBoxLock } = require(${JSON.stringify(HOOK_LIB)});
+    const go = Number(process.argv[2]);
+    while (Date.now() < go) { /* spin to a shared start instant */ }
+    const won = acquireBoxLock();
+    process.stdout.write(won ? 'LEADER' : 'follower');
+    if (won) { const until = Date.now() + 600; while (Date.now() < until) {} }
+  `;
+
+  // spawn(), NOT spawnSync(): spawnSync BLOCKS until each child exits, so the
+  // "racers" ran strictly one after another and never overlapped. That flaw made
+  // this test report 12/12 double-leaders against correct code.
+  const runRound = () => new Promise((resolve) => {
+    fs.writeFileSync(LOCK_PATH, JSON.stringify({ pid: 999999, ts: new Date().toISOString() }));
+    const go = Date.now() + 400;
+    const out = [];
+    let done = 0;
+    for (let i = 0; i < 4; i++) {
+      const kid = spawn(process.execPath, ['-e', racer, String(go)], { stdio: ['ignore', 'pipe', 'ignore'] });
+      let buf = '';
+      kid.stdout.on('data', (d) => { buf += d; });
+      kid.on('close', () => {
+        out.push(buf);
+        if (++done === 4) resolve(out.filter((o) => o.includes('LEADER')).length);
+      });
+    }
+  });
+
+  const ROUNDS = 12;
+  let doubleLeader = 0;
+  let noLeader = 0;
+  for (let r = 0; r < ROUNDS; r++) {
+    const leaders = await runRound();
+    if (leaders > 1) doubleLeader++;
+    if (leaders === 0) noLeader++;
+    release();
+  }
+  check(`concurrent reclaim: no round elected 2 leaders (${doubleLeader}/${ROUNDS} bad)`, doubleLeader === 0);
+  // Every racer bailing would be "safe" but useless — nobody would repair the box.
+  check(`concurrent reclaim: a leader was elected each round (${noLeader}/${ROUNDS} empty)`, noLeader === 0);
+}
+release();
+
+// 8. NEGATIVE CONTROL — does test 7 actually have teeth?
+//
+// This suite has already produced two false verdicts: a copy of the implementation
+// that drifted (reported PASS for code that was not shipping), and a spawnSync
+// harness whose "racers" never overlapped (reported FAIL for code that was fine).
+// A concurrency test that cannot fail is worse than no test, so run the SAME
+// harness against a deliberately naive lock and require that it catches it.
+{
+  const naivePath = path.join(os.tmpdir(), `naive-box-lock-${process.pid}.js`);
+  fs.writeFileSync(naivePath, `
+    const fs = require('node:fs');
+    const LOCK_PATH = ${JSON.stringify(`${LOCK_PATH}.naive`)};
+    // The original algorithm: read -> judge stale -> unlink -> open('wx').
+    // No rename, no identity check. This is what shipped before the fix.
+    function acquireBoxLock() {
+      for (let a = 0; a < 2; a++) {
+        try { const fd = fs.openSync(LOCK_PATH, 'wx');
+          fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: new Date().toISOString() }));
+          fs.closeSync(fd); return true;
+        } catch (err) {
+          if (err.code !== 'EEXIST') return false;
+          try { fs.unlinkSync(LOCK_PATH); } catch { return false; }
+        }
+      }
+      return false;
+    }
+    module.exports = { acquireBoxLock, LOCK_PATH };
+  `);
+  const naiveLock = `${LOCK_PATH}.naive`;
+  const naiveRacer = `
+    const { acquireBoxLock } = require(${JSON.stringify(naivePath)});
+    const go = Number(process.argv[2]);
+    while (Date.now() < go) {}
+    const won = acquireBoxLock();
+    process.stdout.write(won ? 'LEADER' : 'follower');
+    if (won) { const until = Date.now() + 600; while (Date.now() < until) {} }
+  `;
+  const naiveRound = () => new Promise((resolve) => {
+    fs.writeFileSync(naiveLock, JSON.stringify({ pid: 999999, ts: new Date().toISOString() }));
+    const go = Date.now() + 400;
+    const out = []; let done = 0;
+    for (let i = 0; i < 4; i++) {
+      const kid = spawn(process.execPath, ['-e', naiveRacer, String(go)], { stdio: ['ignore', 'pipe', 'ignore'] });
+      let buf = '';
+      kid.stdout.on('data', (d) => { buf += d; });
+      kid.on('close', () => { out.push(buf); if (++done === 4) resolve(out.filter((o) => o.includes('LEADER')).length); });
+    }
+  });
+  let caught = 0;
+  const ROUNDS = 12;
+  for (let r = 0; r < ROUNDS; r++) {
+    if (await naiveRound() > 1) caught++;
+    try { fs.unlinkSync(naiveLock); } catch { /* ignore */ }
+  }
+  check(`negative control: harness DETECTS the naive lock (${caught}/${ROUNDS} rounds caught)`, caught > 0);
+  try { fs.unlinkSync(naivePath); } catch { /* ignore */ }
+  try { fs.unlinkSync(naiveLock); } catch { /* ignore */ }
+}
+
+console.log(fail ? `\n${fail} FAILURE(S)` : '\nall box-lock invariants hold');
+process.exit(fail ? 1 : 0);

package/scripts/probe-installed-hooks.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Prove the INSTALLED hook tree can actually load.
+ *
+ * The source was fine, the npm tarball was fine, and only the copied result was
+ * broken: copyHookFiles() was flat, so hooks/lib/ was never created at the
+ * destination and require('./lib/box-lock') died MODULE_NOT_FOUND — a SessionStart
+ * hook exiting non-zero with EMPTY stdout on every session, before any health check
+ * could run, so its own repair path could never recover it.
+ *
+ * File-presence checks in the repo would not have caught that. This replays the
+ * real copy into a scratch dir and LOADS the result.
+ */
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { copyHookFiles } = require(path.join(ROOT, 'scripts', 'install-rdc-skills.js'));
+
+let fail = 0;
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`);
+  if (!ok) fail++;
+};
+
+const dst = fs.mkdtempSync(path.join(os.tmpdir(), 'rdc-hooks-install-'));
+const count = copyHookFiles(path.join(ROOT, 'hooks'), dst);
+check(`copied hook files (${count})`, count > 0);
+
+// The exact loss: a nested dir the flat copy skipped.
+check('hooks/lib/ exists at destination', fs.existsSync(path.join(dst, 'lib')));
+check('hooks/lib/box-lock.js copied', fs.existsSync(path.join(dst, 'lib', 'box-lock.js')));
+check('hooks/lib/run-evidence-gate.mjs copied (.mjs was filtered out too)',
+  fs.existsSync(path.join(dst, 'lib', 'run-evidence-gate.mjs')));
+
+// Load every top-level hook for real. --check only parses; it does not resolve
+// require(), which is precisely what broke.
+const hooks = fs.readdirSync(dst).filter((f) => f.endsWith('.js'));
+const unresolved = [];
+for (const h of hooks) {
+  const entry = path.join(dst, h).replace(/\\/g, '/');
+  const res = spawnSync(process.execPath, ['-e', `require(${JSON.stringify(entry)})`], {
+    encoding: 'utf8', input: '', timeout: 20000,
+  });
+  const out = `${res.stdout || ''}${res.stderr || ''}`;
+  if (/MODULE_NOT_FOUND|Cannot find module/.test(out)) {
+    unresolved.push(`${h}: ${(out.match(/Cannot find module '[^']+'/) || [''])[0]}`);
+  }
+}
+check(`all ${hooks.length} installed hooks resolve their imports`, unresolved.length === 0,
+  unresolved.slice(0, 3).join(' | '));
+
+fs.rmSync(dst, { recursive: true, force: true });
+console.log(fail ? `\n${fail} FAILURE(S)` : '\ninstalled hook tree loads cleanly');
+process.exit(fail ? 1 : 0);

package/scripts/probe-lock-holders.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Read-only probe: which PM2 processes hold the global rdc-skills package dir?
+ *
+ * Mirrors processesHoldingPackage() in hooks/check-rdc-environment.js so the
+ * matcher can be verified WITHOUT running a real repair (which would stop the
+ * MCP and reinstall the package).
+ *
+ * `npm install -g` upgrades by renaming that directory; Windows refuses to rename
+ * a live process's cwd, which is the EBUSY that hard-blocked sessions.
+ */
+import { execSync } from 'node:child_process';
+import path from 'node:path';
+
+const shell = (c) => execSync(c, { encoding: 'utf8', timeout: 15000 }).trim();
+const norm = (p) => String(p || '').toLowerCase().replace(/\\/g, '/');
+
+const root = shell('npm root -g');
+const pkgDir = norm(path.join(root, '@lifeaitools', 'rdc-skills'));
+
+const all = JSON.parse(shell('pm2 jlist'));
+const holders = all.filter((p) => {
+  const cwd = norm(p?.pm2_env?.pm_cwd);
+  return cwd && (cwd === pkgDir || cwd.startsWith(`${pkgDir}/`));
+});
+
+console.log(`package dir : ${pkgDir}`);
+console.log(`pm2 procs   : ${all.length}`);
+for (const p of holders) {
+  console.log(`  HOLDS LOCK: ${p.name}  status=${p.pm2_env.status}  cwd=${norm(p.pm2_env.pm_cwd)}`);
+}
+console.log(
+  holders.length
+    ? `\nMATCHED ${holders.length} — these are stopped before npm -g, so EBUSY is avoided.`
+    : '\nNO MATCH — nothing holds the dir; npm -g would have been safe anyway.',
+);