nearly-cli 0.1.18 → 0.1.20

package/README.md

@@ -226,7 +226,7 @@ Nothing about how you work changes. Open the repo in VS Code or a terminal, star
 1. **Reads run silently.** Anything that only looks at your code is allowed and logged.
 2. **Anything that changes or reaches out is held.** It appears at http://127.0.0.1:47653 with the command, what it can affect, and a countdown. Answer with `A` or `D`, or shift for always and never. Nobody answering means denied after two minutes.
 3. **The record builds itself** when the session ends.
-4. **At `git push`** the hook merges every session on that branch, prints what was refused, and asks whether to post it. Say no and the push just continues.
+4. **At `git push`** the hook merges every session on that branch, prints what was refused, and posts it to the branch's open pull request. When the agent opens the pull request itself, the record is posted right then.
 5. **Your reviewer opens the pull request** and the record is there, as one comment that updates on every push rather than a new one each time.
 
 ### For a team
@@ -377,16 +377,23 @@ node scripts/install-push-hook.mjs ~/code/my-app
 ```
 
 That installs a `pre-push` hook. On your next push it builds the branch record,
-prints what it found including anything refused, and — only if there is an open
-pull request — asks whether to post it. Answer `y` and it comments; anything else
-and the push just continues.
+prints what it found including anything refused, and posts it to the branch's
+open pull request — one comment, updated on every push after that.
+
+It used to ask first, in the terminal. That never happened in practice: the push
+that matters is the agent's own ("raise a PR"), an agent's push has no terminal,
+and so nothing was ever posted and every reviewer saw an empty pull request. The
+pull request is also usually opened after that push, so Nearly now posts as soon
+as it sees the agent run `gh pr create` too.
 
 Three rules it follows:
 
 - **It never blocks a push.** No sessions on the branch, no server, a crash, a
   timeout: it prints one dim line at most and exits 0.
-- **It never posts without you.** A record of what you refused is more revealing
-  than a diff. Publishing that to a shared pull request is your call, every time.
+- **Posting is on unless you turn it off.** The record includes every prompt word
+  for word. `nearly --no-post` stops posting for a repo and `nearly --post` turns
+  it back on; `NEARLY_NO_POST=1` stops it everywhere. A merged or closed pull
+  request is never posted to.
 - **It stays fast.** Narration is skipped by default, because a minute of `say`
   at every push is not acceptable. Set `NEARLY_AUDIO=1` when you want the good one.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs test/detect.test.mjs test/adapters.test.mjs test/spawn.test.mjs test/stale-server.test.mjs test/outside.test.mjs test/runtime.test.mjs"
+    "test": "node --test --test-concurrency=1 test/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs test/detect.test.mjs test/adapters.test.mjs test/spawn.test.mjs test/stale-server.test.mjs test/outside.test.mjs test/posting.test.mjs test/runtime.test.mjs"
   }
 }

package/scripts/attach.mjs

@@ -10,7 +10,7 @@
 //     gated and recorded whether you start them in a terminal, in VS Code or in
 //     JetBrains. Claude Code always; Cursor, Antigravity, Copilot, Codex, Gemini
 //     and Windsurf when the repo shows signs of them, or on --agent=
-//   · a git pre-push hook, so the record is offered when the work leaves your
+//   · a git pre-push hook, so the record is posted when the work leaves your
 //     machine
 //   · where the records are published, read from the Nearly's own remote
 //   · one hook in Claude Code's user settings, so a session opened in another
@@ -30,6 +30,7 @@ import { installRuntime, hasRuntime, isRuntime, runtimeCommand } from './runtime
 import { ADAPTERS } from '../server/adapters.mjs';
 import { installOutside, removeOutside, attachedRepos, userSettingsFile } from './outside.mjs';
 import { prForBranch } from './pr-state.mjs';
+import { postingOff, setPosting } from './posting.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const HOOK = join(root, 'scripts', 'hook.mjs');
@@ -271,6 +272,10 @@ try {
 // in its user settings covers the rest, and stays only while some repo still
 // has Nearly on. Never from a pinned npx call: that would put a registry lookup
 // in front of every tool call in every session on the machine.
+if (!off && (argv.includes('--no-post') || argv.includes('--post'))) {
+  try { setPosting(repo, argv.includes('--post')); } catch (e) { notes.push(`could not save the posting choice: ${e.message}`); }
+}
+
 let reach = null;
 const claudeWired = wired.some((a) => a.id === 'claude-code');
 if (!off && claudeWired && !localOnly && (installed || runtime || !fromPackage)) {
@@ -405,12 +410,14 @@ if (push.status === 0) {
   // request on a push. Said here, because the natural thing is to look at a pull
   // request that already exists and wonder where the record is.
   const pr = prForBranch(repo);
-  if (pr.state === 'open') {
-    console.log(`  ${ok('·')} the record is added to #${pr.number} on your next push ${dim('— sessions from now on')}`);
+  if (postingOff(repo)) {
+    console.log(`  ${ok('·')} the record is built on push but not posted ${dim('— nearly --post puts it on the pull request')}`);
+  } else if (pr.state === 'open') {
+    console.log(`  ${ok('·')} the record is posted to #${pr.number} on your next push ${dim('— sessions from now on; nearly --no-post stops it')}`);
   } else if (pr.state === 'merged' || pr.state === 'closed') {
-    console.log(`  ${ok('·')} the record is offered on your next push ${dim(`— #${pr.number} for this branch is ${pr.state}, so open a new pull request first`)}`);
+    console.log(`  ${ok('·')} the record is posted on your next push ${dim(`— #${pr.number} for this branch is ${pr.state}, so open a new pull request first`)}`);
   } else {
-    console.log(`  ${ok('·')} the record is offered on your next push ${dim('— sessions from now on, once a pull request is open')}`);
+    console.log(`  ${ok('·')} the record is posted to the pull request when it is opened, and updated on every push ${dim('— nearly --no-post stops it')}`);
   }
 } else {
   // All of it: when a pre-push hook of yours is already there, the lines after

package/scripts/build-recap.mjs

@@ -160,6 +160,22 @@ function patch(cwd, range, maxLines = 48) {
 const short = (s, n = 90) => { s = String(s ?? '').replace(/\s+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
 const secs = (ms) => (ms / 1000).toFixed(1);
 const plural = (n, w, ws = w + 's') => `${n} ${n === 1 ? w : ws}`;
+// "5221s" is a number nobody reads as an hour and a half.
+const clock = (s) => {
+  s = Math.round(s);
+  if (s < 90) return `${s}s`;
+  const h = Math.floor(s / 3600), m = Math.round((s % 3600) / 60);
+  return h ? `${h}h ${String(m).padStart(2, '0')}m` : `${Math.round(s / 60)}m`;
+};
+const spoken = (s) => {
+  s = Math.round(s);
+  if (s < 90) return plural(s, 'second');
+  const h = Math.floor(s / 3600), m = Math.round((s % 3600) / 60);
+  return h ? `${plural(h, 'hour')}${m ? ` ${plural(m, 'minute')}` : ''}` : plural(Math.round(s / 60), 'minute');
+};
+// Tools that only look. Anything else allowed without asking changed something,
+// and calling it read-only told a reviewer that edits were only reads.
+const READS = new Set(['Read', 'Grep', 'Glob', 'LS', 'WebFetch', 'WebSearch', 'TodoWrite']);
 
 function describeInput(tool, input = {}) {
   if (tool === 'Bash') return input.command || '';
@@ -253,6 +269,9 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
   // itself the fact. Leaving it implied reads as "nothing needed approving"
   // when what happened is that nobody was asked.
   const unattended = decisions.some((d) => d.scope === 'auto');
+  // With nobody watching, "waiting on a human: 0.0s" and "asked Anuj: 0" are not
+  // facts about the work, just columns about a supervisor who was not there.
+  const nobodyThere = unattended && !humanDecisions.length && !humanWaitMs && !asks.length;
   scenes.push({
     kind: 'cover',
     title: headlineBits.length ? headlineBits.join(', ') : 'A session with nothing to flag',
@@ -268,14 +287,14 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
     repo: worktree ? basename(worktree) : null,
     branch: created?.branch || null,
     stats: [
-      ['Ran for', `${durS.toFixed(0)}s`, ''],
-      [V('Waiting on a human', 'Waiting on you'), `${secs(humanWaitMs)}s`, 'ask'],
+      ['Ran for', clock(durS), ''],
+      ...(nobodyThere ? [] : [[V('Waiting on a human', 'Waiting on you'), `${secs(humanWaitMs)}s`, 'ask']]),
       ['Tool calls', String(toolUses.length), ''],
-      [V('Asked ' + AUTHOR, 'Asked you'), String(humanDecisions.length), ''],
+      ...(nobodyThere ? [] : [[V('Asked ' + AUTHOR, 'Asked you'), String(humanDecisions.length), '']]),
       ['Refused', String(denied.length), denied.length ? 'deny' : ''],
       ['Rolled back', String(undos.length), undos.length ? 'undo' : ''],
     ],
-    narration: `${sbRuns > 1 ? `${plural(sbRuns, 'agent session')} on this branch, ${durS.toFixed(0)} seconds in total` : `Agent ${name} ran for ${durS.toFixed(0)} seconds`} under ${supPoss} supervision. ${plural(toolUses.length, 'tool call')}, ${humanDecisions.length} held for a decision, ${denied.length} refused${undos.length ? `, ${plural(undos.length, 'turn')} rolled back` : ''}.`,
+    narration: `${sbRuns > 1 ? `${plural(sbRuns, 'agent session')} on this branch, ${spoken(durS)} in total` : `Agent ${name} ran for ${spoken(durS)}`}${nobodyThere ? ', with nobody watching' : ` under ${supPoss} supervision`}. ${plural(toolUses.length, 'tool call')}, ${nobodyThere ? '' : `${humanDecisions.length} held for a decision, `}${denied.length} refused${undos.length ? `, ${plural(undos.length, 'turn')} rolled back` : ''}.`,
   });
 
   // 2. intent. One scene per thing that was asked for, in order, so a branch
@@ -290,10 +309,13 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
   const flushQuiet = () => {
     if (!quiet.length) return;
     const tools = [...new Set(quiet.map((q) => q.tool))];
+    const onlyReads = quiet.every((q) => READS.has(q.tool));
+    const byRule = quiet.every((q) => !q.auto);
     scenes.push({
       kind: 'quiet',
+      onlyReads,
       items: quiet.map((q) => ({ tool: q.tool, sub: short(describeInput(q.tool, q.input), 80) })),
-      narration: `${plural(quiet.length, 'read-only step')} ran without asking: ${tools.join(', ')}. Logged, not gated.`,
+      narration: `${plural(quiet.length, onlyReads ? 'read-only step' : 'step')} ran without asking: ${tools.join(', ')}. ${onlyReads || byRule ? 'Logged, not gated.' : 'Nobody was watching, so nobody was asked; every one is logged.'}`,
     });
     quiet = [];
   };
@@ -318,7 +340,7 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
       const tool = e.tool;
       const input = ask?.input ?? e.input ?? {};
       const res = results.find((r) => r.id === e.id);
-      if (e.tier === 'log') { quiet.push({ tool, input }); continue; }
+      if (e.tier === 'log') { quiet.push({ tool, input, auto: e.scope === 'auto' }); continue; }
       flushQuiet();
       const human = e.waitedMs != null;
       const w = human ? secs(e.waitedMs) : null;

package/scripts/posting.mjs

@@ -0,0 +1,21 @@
+// Whether a repo's record is posted to its pull request on push. On unless it
+// was turned off for that repo, or for everything with NEARLY_NO_POST=1.
+
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { paths } from '../server/paths.mjs';
+
+const key = (repo) => { try { return realpathSync.native(repo); } catch { return repo; } };
+const read = () => { try { return existsSync(paths.config()) ? JSON.parse(readFileSync(paths.config(), 'utf8')) : {}; } catch { return {}; } };
+
+export function postingOff(repo) {
+  if (process.env.NEARLY_NO_POST === '1') return true;
+  return (read().noPost || []).includes(key(repo));
+}
+
+export function setPosting(repo, on) {
+  const cfg = read();
+  const list = new Set(cfg.noPost || []);
+  if (on) list.delete(key(repo)); else list.add(key(repo));
+  cfg.noPost = [...list];
+  writeFileSync(paths.config(), JSON.stringify(cfg, null, 2) + '\n');
+}

package/scripts/push-record.mjs

@@ -1,5 +1,11 @@
 // What the pre-push hook runs. Builds the branch's session record, shows what
-// it found, and asks whether to hand it to the reviewer.
+// it found, and puts it on the branch's open pull request.
+//
+// It used to ask first, in the terminal. But the push that matters is usually
+// made by the agent — "raise a PR" — and an agent's push has no terminal, so the
+// question was never asked and nothing was ever posted. The reviewer saw an
+// empty pull request on every branch Nearly had recorded. Now it posts, as one
+// comment that each push updates; `nearly --no-post` stops it for a repo.
 //
 //   node scripts/push-record.mjs <repo-path>
 //
@@ -9,7 +15,6 @@ import { readFileSync, existsSync } from 'node:fs';
 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)), '..'));
@@ -121,21 +126,10 @@ if (pr.state !== 'open') {
   console.log('');
   process.exit(0);
 }
-const prUrl = pr.url || null;
-
-if (process.env.NEARLY_NO_TTY === '1' || !process.stdin.isTTY) {
-  console.log(dim('  No terminal to ask on, so nothing was posted.'));
-  console.log(dim(`  Post it yourself: node scripts/post-recap.mjs ${slug}${URL_BASE ? ` --url-base ${URL_BASE}` : ''}`));
-  console.log('');
-  process.exit(0);
-}
-
-const rl = createInterface({ input: process.stdin, output: process.stdout });
-const answer = await new Promise((r) => rl.question(`  Post this record to ${prUrl || 'the pull request'}? [y/N] `, r))
-  .finally(() => rl.close());
 
-if (!/^y(es)?$/i.test(String(answer).trim())) {
-  console.log(dim('  Not posted. Push continues.'));
+const { postingOff } = await import('./posting.mjs');
+if (postingOff(repo)) {
+  console.log(dim(`  Not posted: posting is off for this repo. \`nearly --post\` turns it back on.`));
   console.log('');
   process.exit(0);
 }
@@ -144,7 +138,7 @@ const postArgs = [join(root, 'scripts', 'post-recap.mjs'), slug];
 if (URL_BASE) postArgs.push('--url-base', URL_BASE);
 const post = spawnSync(process.execPath, postArgs, { cwd: root, encoding: 'utf8', timeout: 60_000 });
 console.log(post.status === 0
-  ? `  Posted. ${(post.stdout || '').trim()}`
+  ? `  Record ${(post.stdout || '').trim()} ${dim('(nearly --no-post stops this)')}`
   : red(`  Could not post: ${(post.stderr || post.stdout || '').trim().split('\n').pop()}`));
 console.log('');
 process.exit(0);

package/server/index.mjs

@@ -243,6 +243,28 @@ function modelFromTranscript(p) {
   return null;
 }
 
+// "Raise a PR" pushes the branch first and opens the pull request second. The
+// push found no pull request to post to, and nothing happens after the pull
+// request exists — so on the agent's own branch, the one thing a reviewer opens
+// never had a record on it. When an agent opens one, post straight away, from a
+// process of its own so the agent is not kept waiting.
+const OPENED = /\bgh\s+pr\s+create\b/;
+function postWhenOpened(s, hook) {
+  const cmd = hook.tool_input?.command;
+  if (typeof cmd !== 'string' || !OPENED.test(cmd)) return;
+  const said = typeof hook.tool_response === 'string' ? hook.tool_response : JSON.stringify(hook.tool_response ?? '');
+  if (!/\/pull\/\d+/.test(said)) return;              // it did not open one
+  try {
+    const child = spawn(process.execPath, [path.join(ROOT, 'scripts', 'push-record.mjs'), s.worktree], {
+      cwd: s.worktree, detached: true, stdio: 'ignore',
+      env: { ...process.env, NEARLY_NO_UPDATE: '1', NEARLY_NO_TTY: '1' },
+    });
+    child.on('error', () => { /* the next push posts it */ });
+    child.unref();
+    record(s.id, { type: 'hook', event: 'record-posting', detail: 'pull request opened' });
+  } catch { /* the next push posts it */ }
+}
+
 // The most recent thing the person typed, from a Claude Code transcript.
 function promptFromTranscript(p) {
   if (!p || !fs.existsSync(p)) return null;
@@ -529,6 +551,7 @@ const server = http.createServer(async (req, res) => {
       const seen = s && hook.tool_use_id && s.posted?.has(hook.tool_use_id);
       if (s && hook.tool_use_id) { s.posted ||= new Set(); s.posted.add(hook.tool_use_id); if (s.posted.size > 500) s.posted.delete(s.posted.values().next().value); }
       if (s && !seen) record(sid, { type: 'post_tool', id: hook.tool_use_id, tool: hook.tool_label || hook.tool_name, duration_ms: hook.duration_ms, response: trim(hook.tool_response ?? '') });
+      if (s && !seen && s.attached && s.worktree) postWhenOpened(s, hook);
       return hookOk(res);
     }
     if (ev === 'stop') {

package/server/policy.mjs

@@ -270,7 +270,10 @@ function expand(raw, st) {
   let s = String(raw);
   if (s === '~' || s.startsWith('~/') || s.startsWith('~\\')) s = path.join(os.homedir(), s.slice(1));
   else if (/^~[^/\\]/.test(s)) return { unknown: `another user's home directory (${raw})` };
-  const vars = { HOME: os.homedir(), USERPROFILE: os.homedir(), TMPDIR: process.env.TMPDIR || os.tmpdir(), TMP: os.tmpdir(), TEMP: os.tmpdir(), PWD: st.cwd };
+  // Variables set earlier on the same line count: `S=/tmp/scratch; rm -f $S/x`
+  // is a scratch file, and refusing it as "decided at run time" stopped real work.
+  // One set to something unknowable stays unknowable (null).
+  const vars = { HOME: os.homedir(), USERPROFILE: os.homedir(), TMPDIR: process.env.TMPDIR || os.tmpdir(), TMP: os.tmpdir(), TEMP: os.tmpdir(), PWD: st.cwd, ...(st.vars || {}) };
   s = s.replace(/\$\(\s*pwd\s*\)/g, () => st.cwd ?? '\0');
   s = s.replace(/\$\{?env:([A-Za-z_]+)\}?/gi, (_, k) => vars[k.toUpperCase()] ?? '\0');
   s = s.replace(/\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g, (_, k) => vars[k] ?? '\0');
@@ -742,7 +745,13 @@ function stageReason(stage, pipe, idx, st, depth) {
 
 // What a command changes for the commands after it on the same line.
 function applyState(stage, st) {
-  const { argv, prog } = unwrap(stage.words);
+  const { argv, prog, assigns } = unwrap(stage.words);
+  // `NAME=value` on its own sets a shell variable for the rest of the line. With
+  // a command after it, it only sets that command's environment, and the shell
+  // has already expanded the line by then — so it changes nothing here.
+  const remember = (k, v) => { const x = expand(v, st); (st.vars ||= {})[k] = x.path ?? null; };
+  if (!prog) { for (const [k, v] of Object.entries(assigns)) remember(k, v); return; }
+  if (prog === 'unset') { for (const a of argv.slice(1)) if (st.vars) delete st.vars[a]; return; }
   if (['cd', 'pushd', 'set-location', 'sl', 'chdir'].includes(prog)) {
     const target = argv.slice(1).find((a) => !a.startsWith('-'));
     if (!target) { st.cwd = os.homedir(); return; }
@@ -753,7 +762,12 @@ function applyState(stage, st) {
   }
   if (prog === 'popd') { st.cwd = null; return; }
   if (prog === 'export') {
-    for (const a of argv.slice(1)) { const m = a.match(/^GIT_DIR=(.*)$/); if (m) st.gitDir = m[1]; }
+    for (const a of argv.slice(1)) {
+      const m = a.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      if (m[1] === 'GIT_DIR') st.gitDir = m[2];
+      remember(m[1], m[2]);
+    }
     return;
   }
   if (prog !== 'git') return;
@@ -795,7 +809,7 @@ function analyze(src, st, depth = 0) {
 function stateFor(cwd) {
   const dir = cwd ? (real(cwd) || cwd) : null;
   const top = dir ? git(dir, ['rev-parse', '--show-toplevel']) : null;
-  return { cwd: dir, root: top ? (real(top) || top) : null, branch: null, gitDir: null, aliases: {} };
+  return { cwd: dir, root: top ? (real(top) || top) : null, branch: null, gitDir: null, aliases: {}, vars: {} };
 }
 
 // The reason a command must never run, or null. Exported for the tests, which

package/ui/recap.template.html

@@ -300,7 +300,7 @@ const render = {
   quiet: (s) => `
     <div class="eyebrow"><span class="lbl">Ran without asking</span>${T('auto', 'log tier')}</div>
     <div class="rows">${s.items.map((i) => `<div class="row"><span class="t">${esc(i.tool)}</span><span class="s" title="${esc(i.sub)}">${esc(i.sub)}</span>${T('auto', 'receipt')}</div>`).join('')}</div>
-    <div class="sub" style="margin-top:auto">Read-only tools run on the log tier. Nobody was asked, but every call is on the record.</div>`,
+    <div class="sub" style="margin-top:auto">${s.onlyReads === false ? 'Allowed without anyone being asked. Every call is on the record.' : 'Read-only tools run on the log tier. Nobody was asked, but every call is on the record.'}</div>`,
 
   decision: (s) => {
     const d = s.tier === 'never' ? 'never' : s.decision;