nearly-cli 0.1.2 → 0.1.5

package/README.md

@@ -24,7 +24,27 @@ Watch the first thirty seconds. The cover says what the diff cannot: an action t
 
 Node 18 or newer, Claude Code signed in, and git. No dependencies and no API key: agents run on your existing Claude subscription.
 
-Gating, recording and the record itself work on macOS, Linux and Windows. **Spoken narration is macOS only**, because it uses the built-in `say`. Elsewhere the record is built the same way and reads from its captions, or you can supply your own recordings with `--voice-dir`.
+### Platforms
+
+The suite runs on every push against macOS, Linux and Windows, on Node 18 and 22.
+
+| | macOS | Linux | Windows |
+|---|---|---|---|
+| Gate, recording, records | tested in CI | tested in CI | tested in CI |
+| Turning it on and off | tested in CI | tested in CI | tested in CI |
+| Updating itself | tested in CI | tested in CI | tested in CI |
+| Driving a real agent end to end | **run by hand** | not yet | not yet |
+| Handing the record over at `git push` | **run by hand** | not yet | not yet |
+| Spoken narration | yes | no | no |
+
+Narration uses the built-in `say`, so it is macOS only. Everywhere else the
+record is built identically and reads from its captions, or you can record the
+lines yourself with `--voice-dir`.
+
+The bottom two rows are the honest gap: CI proves the pieces work on all three,
+but a whole session with a real agent, and a real push through the hook, have
+only been done on macOS. If you are the first to try either on Windows or Linux,
+an issue with what broke would be genuinely useful.
 
 ## Use it on your own repo
 
@@ -34,6 +54,12 @@ One command, in the repo you want recorded.
 npx nearly-cli
 ```
 
+> **`npx` not recognised?** It comes with Node.js, so that error means Node is
+> not installed. Get it from [nodejs.org](https://nodejs.org) or, on Windows,
+> `winget install OpenJS.NodeJS.LTS`. Then **open a new terminal** so it picks up
+> the change, and check with `node --version`. You also need Claude Code signed
+> in: Nearly gates Claude Code sessions and does nothing without one.
+
 ```
 ✓ Nearly is on for my-app
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "A pull request tells you what changed. Nearly tells you what nearly happened: the commands a human refused, the pushes policy blocked, the turns rolled back.",
   "type": "module",
   "bin": {
@@ -34,6 +34,6 @@
   },
   "homepage": "https://anujpatel06.github.io/nearly/",
   "scripts": {
-    "test": "node --test --test-concurrency=1 test/"
+    "test": "node --test --test-concurrency=1 test/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs"
   }
 }

package/scripts/attach.mjs

@@ -16,7 +16,7 @@
 // it, and if it cannot start, Claude Code falls back to its own prompts and
 // nothing breaks.
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
 import { join, resolve, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
@@ -40,15 +40,31 @@ function pkgVersion() {
   catch { return 'latest'; }
 }
 
-// Only trust a `nearly` on PATH if it really is this tool.
+// Only trust a `nearly` on PATH if it really is this tool and it will still be
+// there tomorrow.
+//
+// npx puts its own temporary bin first on PATH for the life of the process, so
+// during `npx nearly-cli` a naive lookup finds a `nearly` that ceases to exist
+// the moment npx exits. Believing it meant writing hooks that call a command
+// nobody has, which fail on every tool call, which means no gate at all.
 function onPath() {
+  const args = process.platform === 'win32' ? ['nearly'] : ['-a', 'nearly'];
+  let found = [];
   try {
-    const p = execFileSync(process.platform === 'win32' ? 'where' : 'which', ['nearly'],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().split('\n')[0];
-    if (!p) return null;
-    const out = execFileSync(p, ['--which'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    return out ? p : null;
+    found = execFileSync(process.platform === 'win32' ? 'where' : 'which', args,
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim().split('\n').filter(Boolean);
   } catch { return null; }
+
+  for (const p of found) {
+    let resolved = p;
+    try { resolved = realpathSync(p); } catch { /* keep the literal path */ }
+    if (/[\\/]_npx[\\/]/.test(p) || /[\\/]_npx[\\/]/.test(resolved)) continue;  // vanishes when npx exits
+    try {
+      const out = execFileSync(p, ['--which'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      if (out) return p;
+    } catch { /* not our command; try the next one */ }
+  }
+  return null;
 }
 
 const fromPackage = /[\\/]node_modules[\\/]/.test(root) || /[\\/]_npx[\\/]/.test(root);
@@ -62,7 +78,7 @@ const viaNpx = /[\\/]_npx[\\/]/.test(root);
 function installGlobally() {
   if (!viaNpx || onPath() || argv.includes('--no-install') || process.env.NEARLY_NO_INSTALL === '1') return false;
   process.stdout.write(dim(`  Installing nearly so upgrades reach you… `));
-  const r = spawnSync('npm', ['install', '-g', `nearly-cli@${pkgVersion()}`, '--silent', '--no-fund', '--no-audit'],
+  const r = spawnSync(NPM, ['install', '-g', `nearly-cli@${pkgVersion()}`, '--silent', '--no-fund', '--no-audit'],
     { encoding: 'utf8', timeout: 180_000 });
   if (r.status === 0 && onPath()) { console.log('done'); return true; }
   console.log(dim('skipped'));
@@ -72,11 +88,13 @@ function installGlobally() {
 }
 let installed = onPath();
 const hookCmd = (ev) => installed
-  ? `nearly hook ${ev}`
+  ? `nearly hook ${ev}`   // verified above to survive this process
   : fromPackage
     ? `npx -y nearly-cli@${pkgVersion()} hook ${ev}`
     : `node ${JSON.stringify(HOOK)} ${ev}`;
-const updateNote = installed
+// A function, not a value: the install below changes the answer, and computing
+// it early told a fresh install it was pinned when it was not.
+const updateNote = () => installed
   ? 'upgrades reach this repo automatically'
   : fromPackage
     ? `pinned to v${pkgVersion()} — run nearly again here after upgrading`
@@ -89,6 +107,9 @@ const nameIdx = argv.indexOf('--name');
 const name = (nameIdx !== -1 ? argv[nameIdx + 1] : basename(repo))
   .replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'repo';
 
+// npm is a .cmd shim on Windows and Node will not run one through spawn unless
+// it is named exactly. Without this, installing and upgrading both fail there.
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const ok = (s) => `\x1b[32m${s}\x1b[0m`;
@@ -201,7 +222,7 @@ if (off) {
 console.log(`${ok('✓')} ${bold('Nearly is on')} for ${bold(name)}  ${dim(repo)}`);
 console.log('');
 console.log(`  ${ok('·')} every Claude Code session here is gated and recorded`);
-console.log(`  ${ok('·')} ${dim(updateNote)}`);
+console.log(`  ${ok('·')} ${dim(updateNote())}`);
 console.log(`  ${ok('·')} ${push.status === 0 ? 'the record is offered when you push' : dim('pre-push hook skipped: ' + (push.stderr || '').trim().split('\n')[0])}`);
 if (base) {
   console.log(`  ${ok('·')} records publish to ${base}`);

package/scripts/update-check.mjs

@@ -24,6 +24,9 @@ import { spawnSync, execFileSync } from 'node:child_process';
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 const DAY = 24 * 60 * 60 * 1000;
 
+// npm is a .cmd shim on Windows and Node will not run one through spawn unless
+// it is named exactly. Without this, installing and upgrading both fail there.
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 
@@ -100,7 +103,7 @@ export function applyUpdate(u) {
   }
 
   process.stdout.write(dim(`  Updating Nearly ${u.from} → ${u.to}… `));
-  const r = spawnSync('npm', ['install', '-g', `${u.name}@${u.to}`, '--silent', '--no-fund', '--no-audit'],
+  const r = spawnSync(NPM, ['install', '-g', `${u.name}@${u.to}`, '--silent', '--no-fund', '--no-audit'],
     { encoding: 'utf8', timeout: 120_000 });
 
   if (r.status === 0) {