nearly-cli 0.1.0 → 0.1.3

package/README.md

@@ -31,31 +31,25 @@ Gating, recording and the record itself work on macOS, Linux and Windows. **Spok
 One command, in the repo you want recorded.
 
 ```bash
-cd ~/code/my-app
-nearly
+npx nearly-cli
 ```
 
 ```
 ✓ Nearly is on for my-app
 
   · every Claude Code session here is gated and recorded
+  · upgrades reach this repo automatically
   · the record is offered when you push
-  · records publish to https://you.github.io/nearly/records
 
   Now just work. Requests that need you appear at http://127.0.0.1:47653
   Nothing to leave running. Turn it off again with --off.
 ```
 
-It installs the Claude Code hooks and the git pre-push hook, and works out where records publish by reading the Nearly's own remote. Nothing to configure. `nearly off` removes all of it.
+That installs Nearly, turns it on for this repo, and works out where records go.
+Nothing to configure, no server to start, and `nearly off` removes all of it.
 
-**To get that command,** until this is on npm:
-
-```bash
-git clone https://github.com/anujpatel06/nearly ~/nearly
-npm link --prefix ~/nearly
-```
-
-No dependencies, so the link is instant. Once published it becomes `npx nearly-cli` with nothing to clone at all.
+Run it again in any other repo you want recorded. After the first time the
+command is just `nearly`.
 
 ### Upgrading
 
@@ -95,7 +89,7 @@ Nothing about how you work changes. Open the repo in VS Code or a terminal, star
 
 ### For a team
 
-`.claude/settings.local.json` is per-person and stays out of git, which is right while you are trying it. To turn it on for everyone, move the same hooks into `.claude/settings.json` and commit that file. Once this is on npm the hooks invoke `npx nearly-cli`, so a teammate who clones the repo needs nothing installed beyond Node.
+`.claude/settings.local.json` is per-person and stays out of git, which is right while you are trying it. To turn it on for everyone, move the same hooks into `.claude/settings.json` and commit that file. The hooks invoke `nearly` by name, so a teammate who clones the repo runs `npx nearly-cli` once and is set up.
 
 ## Why the gate is not the point
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "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": {
@@ -30,7 +30,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/anujpatel06/nearly.git"
+    "url": "git+https://github.com/anujpatel06/nearly.git"
   },
   "homepage": "https://anujpatel06.github.io/nearly/",
   "scripts": {

package/scripts/attach.mjs

@@ -16,10 +16,11 @@
 // 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';
+import { dataRoot } from '../server/paths.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const HOOK = join(root, 'scripts', 'hook.mjs');
@@ -39,21 +40,55 @@ 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);
-const installed = onPath();
+const viaNpx = /[\\/]_npx[\\/]/.test(root);
+
+// `npx nearly-cli` should be the whole of it. An npx run is a temporary
+// download, so hooks pointing at it would pin a version in a directory npm
+// clears, and no fix would ever reach this repo. Install it properly instead,
+// once, out loud, so the one command someone types actually leaves them with a
+// working tool. --no-install skips it.
+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'],
+    { encoding: 'utf8', timeout: 180_000 });
+  if (r.status === 0 && onPath()) { console.log('done'); return true; }
+  console.log(dim('skipped'));
+  console.log(dim('    Running from npx instead. Upgrades will not reach this repo automatically;'));
+  console.log(dim('    npm install -g nearly-cli when you want that.'));
+  return false;
+}
+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}`;
@@ -80,6 +115,10 @@ if (!existsSync(join(repo, '.git'))) {
   process.exit(1);
 }
 
+// Do this before the hooks are written, so they can point at the installed
+// command rather than a temporary npx download.
+if (!off && installGlobally()) installed = onPath();
+
 // ---------------------------------------------------------------------------
 // Claude Code hooks
 // ---------------------------------------------------------------------------
@@ -185,9 +224,9 @@ if (base) {
 } else {
   // Only reachable from a clone of the upstream repo, where publishing needs a
   // fork the person actually controls.
-  console.log(`  ${ok('·')} ${dim('records stay on this machine')}`);
-  console.log(`    ${dim('to publish them, fork this repo, turn on GitHub Pages, then:')}`);
-  console.log(`    ${dim('NEARLY_URL_BASE=https://<you>.github.io/<fork>/records nearly')}`);
+  console.log(`  ${ok('·')} ${dim(`records are kept in ${dataRoot.replace(process.env.HOME || '~', '~')}`)}`);
+  console.log(`    ${dim('to link them from a pull request, host that folder anywhere and:')}`);
+  console.log(`    ${dim('NEARLY_URL_BASE=https://your-host/records nearly')}`);
 }
 console.log('');
 console.log(`  Now just work. Requests that need you appear at ${bold(`http://127.0.0.1:${PORT}`)}`);

package/scripts/build-recap.mjs

@@ -16,11 +16,12 @@ import { join, dirname, basename, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
+import { paths } from '../server/paths.mjs';
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
-const recordingsDir = process.env.NEARLY_RECORDINGS || join(root, 'recordings');
+const recordingsDir = paths.recordings();
 const templatePath = join(root, 'ui', 'recap.template.html');
-const outDir = process.env.NEARLY_OUT || join(root, 'ui', 'records');
+const outDir = paths.pages();
 
 // ---------------------------------------------------------------------------
 // args
@@ -635,7 +636,7 @@ if (!noAudio) {
 sb.totalS = sb.scenes.reduce((n, s) => n + s.durS, 0);
 
 mkdirSync(outDir, { recursive: true });
-const storyDirOut = process.env.NEARLY_STORY || join(root, 'records');
+const storyDirOut = paths.records();
 mkdirSync(storyDirOut, { recursive: true });
 const safe = (x) => String(x).replace(/[^a-z0-9._-]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
 const slug = BRANCH ? `${safe(sb.name)}--${safe(BRANCH)}` : `${sb.name}-${sb.id.slice(0, 4)}`;

package/scripts/post-recap.mjs

@@ -14,6 +14,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
+import { paths } from '../server/paths.mjs';
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 const argv = process.argv.slice(2);
@@ -22,7 +23,7 @@ const ubIdx = argv.indexOf('--url-base');
 const urlBase = (ubIdx !== -1 ? argv[ubIdx + 1] : process.env.NEARLY_URL_BASE || '').replace(/\/$/, '');
 const target = argv.find((a, i) => !a.startsWith('--') && argv[i - 1] !== '--url-base') || 'latest';
 
-const dir = join(root, 'records');
+const dir = paths.records();
 const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
 if (!files.length) { console.error('no storyboards in records/. Run build-recap first.'); process.exit(1); }
 let file;

package/scripts/publish-pages.mjs

@@ -16,11 +16,12 @@
 import { readFileSync, writeFileSync, readdirSync, mkdirSync, copyFileSync, existsSync, statSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { paths } from '../server/paths.mjs';
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
-const storyDir = join(root, 'records');
-const builtDir = join(root, 'ui', 'records');
-const docsDir = join(root, 'docs');
+const storyDir = paths.records();
+const builtDir = paths.pages();
+const docsDir = paths.docs();
 const outRecaps = join(docsDir, 'records');
 
 const argv = process.argv.slice(2);

package/scripts/push-record.mjs

@@ -10,6 +10,7 @@ import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { createInterface } from 'node:readline';
+import { paths } from '../server/paths.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const repo = resolve(process.argv[2] || '.');
@@ -55,7 +56,7 @@ if (build.status !== 0) {
 
 const safe = (x) => String(x).replace(/[^a-z0-9._-]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
 const slug = `${safe(basename(repo))}--${safe(branch)}`;
-const storyPath = join(root, 'records', `${slug}.json`);
+const storyPath = join(paths.records(), `${slug}.json`);
 if (!existsSync(storyPath)) bail('record built but not found on disk');
 
 const sb = JSON.parse(readFileSync(storyPath, 'utf8'));

package/server/index.mjs

@@ -11,13 +11,14 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_TIER, ruleKey, classify as classifyWith } from './policy.mjs';
+import { paths } from './paths.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const PORT = Number(process.env.NEARLY_PORT || 47653);
 const HOST = '127.0.0.1';
 const WORKSPACE = path.join(ROOT, 'workspace');
 const WORKTREES = path.join(WORKSPACE, '.worktrees');
-const RECORDINGS = process.env.NEARLY_RECORDINGS || path.join(ROOT, 'recordings');
+const RECORDINGS = paths.recordings();
 const UI = path.join(ROOT, 'ui', 'index.html');
 const MAX_SESSIONS = 3;                 // 8 GB machine
 const ASK_TIMEOUT_MS = Number(process.env.NEARLY_ASK_TIMEOUT_MS || 120_000);         // UI must answer before this; then we fail CLOSED (deny)

package/server/paths.mjs

@@ -0,0 +1,38 @@
+// Where Nearly keeps what it records.
+//
+// Installed from npm, the package directory is replaced wholesale on every
+// upgrade, so anything written there is destroyed by the next `npm install -g`.
+// Recordings are the one thing in this project that cannot be regenerated:
+// every record, every count, every refusal is derived from them. They belong in
+// the user's own space.
+//
+// Run from a checkout, the checkout is the workspace, which is what a
+// contributor expects and what the tests rely on.
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, '..');
+
+// A checkout has a .git directory; an installed package does not.
+export const fromCheckout = existsSync(join(pkgRoot, '.git'));
+
+export const dataRoot = fromCheckout
+  ? pkgRoot
+  : join(process.env.NEARLY_HOME || join(homedir(), '.nearly'));
+
+export function dataDir(...parts) {
+  const p = join(dataRoot, ...parts);
+  try { mkdirSync(p, { recursive: true }); } catch { /* caller will report */ }
+  return p;
+}
+
+export const paths = {
+  recordings: () => process.env.NEARLY_RECORDINGS || dataDir('recordings'),
+  records: () => process.env.NEARLY_STORY || dataDir('records'),
+  pages: () => process.env.NEARLY_OUT || (fromCheckout ? join(pkgRoot, 'ui', 'records') : dataDir('pages', 'records')),
+  docs: () => (fromCheckout ? join(pkgRoot, 'docs') : dataDir('pages')),
+};