nearly-cli 0.1.5 → 0.1.7

package/server/index.mjs

@@ -16,14 +16,17 @@ 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 WORKTREES = path.join(paths.workspace(), '.worktrees');
 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)
 const HOOK_TIMEOUT_S = 180;             // Claude Code's own hook timeout; must be > ASK_TIMEOUT
 const MODEL = 'sonnet';
+// Overridable so the tests can exercise everything around starting an agent
+// without starting one, and so anyone whose binary is not called `claude` can
+// say so.
+const AGENT_CMD = process.env.NEARLY_AGENT_CMD || 'claude';
 const MAX_TURNS = '12';
 
 fs.mkdirSync(RECORDINGS, { recursive: true });
@@ -64,7 +67,7 @@ function summary(s) {
   };
 }
 function pendingView(p) {
-  return { id: p.id, session: p.sid, tool: p.tool, input: p.input, tier: p.tier, reason: p.reason, key: p.key, at: p.at };
+  return { id: p.id, session: p.sid, tool: p.tool, input: p.input, tier: p.tier, reason: p.reason, key: p.key, at: p.at, holdMs: p.holdMs };
 }
 
 function hooksSettings(sid) {
@@ -87,13 +90,54 @@ function git(cwd, args) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
 }
 
-function createSession({ name, prompt }) {
+// The repo an agent started from the dashboard should branch from. There is no
+// such thing as a default one: this used to assume a `workspace` folder beside
+// the code, which exists in a checkout and never exists when the tool is
+// installed from npm, so the button could only fail.
+function knownRepos() {
+  let listed = [];
+  try { listed = JSON.parse(fs.readFileSync(paths.repos(), 'utf8')); } catch { /* none yet */ }
+  const live = [...sessions.values()].filter((s) => s.attached && s.worktree).map((s) => s.worktree);
+  // A repo can be moved or deleted after it was turned on; offering one that is
+  // no longer there would just move the failure later.
+  return [...new Set([...live, ...listed])].filter((r) => fs.existsSync(path.join(r, '.git')));
+}
+
+function resolveRepo(given) {
+  // Nothing given: the repos you have turned Nearly on for are the ones you work
+  // in, so they are the only sensible guess. One is a default; several are a
+  // question, and guessing between them would branch the wrong project.
+  const candidates = given ? [path.resolve(given)] : knownRepos();
+
+  if (!candidates.length) {
+    throw new Error('No repo to start from. Run `nearly` in the repo you want, then try again — or give a path.');
+  }
+  if (!given && candidates.length > 1) {
+    throw new Error(`Several repos are attached. Say which one: ${candidates.join(', ')}`);
+  }
+  const repo = candidates[0];
+  if (!fs.existsSync(path.join(repo, '.git'))) throw new Error(`${repo} is not a git repository.`);
+  try {
+    // An unborn HEAD is the other way this failed: git cannot branch from a repo
+    // with no commits, and "invalid reference: main" explained none of that.
+    git(repo, ['rev-parse', 'HEAD']);
+  } catch {
+    throw new Error(`${repo} has no commits yet. Make one, then start an agent from it.`);
+  }
+  return repo;
+}
+
+function createSession({ name, prompt, repo: repoArg }) {
   if (sessions.size >= MAX_SESSIONS) throw new Error(`max ${MAX_SESSIONS} sessions on this machine`);
+  const repo = resolveRepo(repoArg);
   const id = randomUUID();
   const safe = String(name || 'agent').replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'agent';
-  const branch = `cr/${safe}-${id.slice(0, 4)}`;
+  const branch = `nearly/${safe}-${id.slice(0, 4)}`;
   const worktree = path.join(WORKTREES, `${safe}-${id.slice(0, 4)}`);
-  git(WORKSPACE, ['worktree', 'add', '-B', branch, worktree, 'main']);
+  // HEAD, not `main`: branch from where the person actually is. Hardcoding the
+  // branch name broke every repo on master, every repo mid-feature, and every
+  // repo that had simply never been called main.
+  git(repo, ['worktree', 'add', '-B', branch, worktree, 'HEAD']);
 
   const settingsPath = path.join(worktree, '.nearly-hooks.json');
   fs.writeFileSync(settingsPath, JSON.stringify(hooksSettings(id)));
@@ -111,12 +155,12 @@ function createSession({ name, prompt }) {
     '--max-turns', MAX_TURNS,
     '--name', safe,
   ];
-  const proc = spawn('claude', args, { cwd: worktree, stdio: ['pipe', 'pipe', 'pipe'] });
+  const proc = spawn(AGENT_CMD, args, { cwd: worktree, stdio: ['pipe', 'pipe', 'pipe'] });
   // An unhandled spawn error would take the whole server down and every other
   // session with it. The usual cause is Claude Code not being on PATH.
   proc.on('error', (e) => {
     const why = e.code === 'ENOENT'
-      ? 'Claude Code is not on PATH. Install it, or check `which claude`.'
+      ? `${AGENT_CMD} is not on PATH. Install Claude Code, or check \`which ${AGENT_CMD}\`.`
       : e.message;
     record(id, { type: 'stderr', text: `could not start the agent: ${why}` });
     s.state = 'exited';
@@ -127,8 +171,9 @@ function createSession({ name, prompt }) {
     id, name: safe, branch, worktree, proc, state: 'starting', turns: 0, lastText: '', currentTool: null,
     usage: null, rateLimit: null, pending: new Map(), events: [], startedAt: Date.now(), buf: '',
   };
+  s.repo = repo;
   sessions.set(id, s);
-  record(id, { type: 'session', subtype: 'created', name: safe, branch, worktree, prompt });
+  record(id, { type: 'session', subtype: 'created', name: safe, branch, worktree, repo, prompt });
 
   proc.stderr.on('data', (d) => record(id, { type: 'stderr', text: String(d).slice(0, 2000) }));
   proc.stdout.on('data', (d) => {
@@ -363,15 +408,25 @@ const server = http.createServer(async (req, res) => {
     if (ev === 'pre-tool') {
       const { tier, reason } = classifyWith(hook, rules);
       const id = hook.tool_use_id || randomUUID();
+      // Policy keys on the canonical name so a rule means the same thing in every
+      // harness; the record shows the harness's own name so it stays truthful
+      // about what actually ran.
+      const shown = hook.tool_label || hook.tool_name;
       const respond = (decision, why) => hookOk(res, {
         hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: `nearly: ${why}` },
       });
       if (!s) return respond('deny', 'unknown session');
-      if (tier === 'never') { record(sid, { type: 'decision', id, decision: 'deny', why: reason, scope: 'policy', tool: hook.tool_name, input: hook.tool_input, tier }); return respond('deny', `never (${reason})`); }
-      if (tier === 'log') { record(sid, { type: 'decision', id, decision: 'allow', why: reason, scope: 'policy', tool: hook.tool_name, input: hook.tool_input, tier }); return respond('allow', `do and log (${reason})`); }
+      if (tier === 'never') { record(sid, { type: 'decision', id, decision: 'deny', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier }); return respond('deny', `never (${reason})`); }
+      if (tier === 'log') { record(sid, { type: 'decision', id, decision: 'allow', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier }); return respond('allow', `do and log (${reason})`); }
       // ask: hold the response until the UI decides, or fail closed
-      const item = { id, sid, tool: hook.tool_name, input: hook.tool_input, tier, reason, key: ruleKey(hook), at: Date.now(), respond };
-      item.timer = setTimeout(() => decide(sid, id, 'deny', 'no human answer; nearly fails closed'), ASK_TIMEOUT_MS);
+      // A harness may say it will not wait as long as we would. It can shorten
+      // the deadline, never lengthen it: the point of the cap is that nobody
+      // else gets to decide by not answering.
+      const asked = Number(url.searchParams.get('hold')) || 0;
+      const holdMs = asked > 0 ? Math.min(asked, ASK_TIMEOUT_MS) : ASK_TIMEOUT_MS;
+      const item = { id, sid, tool: shown, input: hook.tool_input, tier, reason, key: ruleKey(hook), at: Date.now(), holdMs, respond };
+      item.timer = setTimeout(() => decide(sid, id, 'deny',
+        `no human answer in ${Math.round(holdMs / 1000)}s; nearly fails closed`), holdMs);
       s.pending.set(id, item);
       s.state = 'waiting';
       record(sid, { type: 'ask', ...pendingView(item) });
@@ -380,7 +435,7 @@ const server = http.createServer(async (req, res) => {
     }
 
     if (ev === 'post-tool') {
-      if (s) record(sid, { type: 'post_tool', id: hook.tool_use_id, tool: hook.tool_name, duration_ms: hook.duration_ms, response: trim(hook.tool_response ?? '') });
+      if (s) 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 ?? '') });
       return hookOk(res);
     }
     if (ev === 'stop') {
@@ -434,13 +489,13 @@ const server = http.createServer(async (req, res) => {
   }
   if (req.method === 'GET' && url.pathname === '/events') {
     res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
-    res.write(`data: ${JSON.stringify({ type: 'snapshot', sessions: [...sessions.values()].map(summary), rules: Object.fromEntries(rules), defaults: DEFAULT_TIER, askTimeoutMs: ASK_TIMEOUT_MS })}\n\n`);
+    res.write(`data: ${JSON.stringify({ type: 'snapshot', sessions: [...sessions.values()].map(summary), repos: knownRepos(), rules: Object.fromEntries(rules), defaults: DEFAULT_TIER, askTimeoutMs: ASK_TIMEOUT_MS })}\n\n`);
     clients.add(res);
     req.on('close', () => clients.delete(res));
     return;
   }
   if (req.method === 'GET' && url.pathname === '/state') {
-    return json(res, 200, { sessions: [...sessions.values()].map(summary), rules: Object.fromEntries(rules), defaults: DEFAULT_TIER, askTimeoutMs: ASK_TIMEOUT_MS });
+    return json(res, 200, { sessions: [...sessions.values()].map(summary), repos: knownRepos(), rules: Object.fromEntries(rules), defaults: DEFAULT_TIER, askTimeoutMs: ASK_TIMEOUT_MS });
   }
   if (req.method === 'GET' && url.pathname.startsWith('/recordings/')) {
     const id = url.pathname.split('/')[2];
@@ -451,7 +506,7 @@ const server = http.createServer(async (req, res) => {
     try {
       const b = JSON.parse(await readBody(req) || '{}');
       if (!b.prompt) return json(res, 400, { error: 'prompt required' });
-      const s = createSession({ name: b.name, prompt: b.prompt });
+      const s = createSession({ name: b.name, prompt: b.prompt, repo: b.repo });
       return json(res, 200, summary(s));
     } catch (e) { return json(res, 400, { error: e.message }); }
   }
@@ -529,7 +584,7 @@ server.on('error', (e) => {
 
 server.listen(PORT, HOST, () => {
   console.log(`nearly  http://${HOST}:${PORT}`);
-  console.log(`workspace     ${WORKSPACE}`);
+  console.log(`worktrees     ${WORKTREES}`);
   console.log(`recordings    ${RECORDINGS}`);
 });
 

package/server/paths.mjs

@@ -24,6 +24,15 @@ export const dataRoot = fromCheckout
   ? pkgRoot
   : join(process.env.NEARLY_HOME || join(homedir(), '.nearly'));
 
+// A file, with its directory guaranteed to exist — including when the path came
+// from an environment variable, which is where this went wrong the first time:
+// the default path was fixed and the override was left to fail on its own.
+function dataFile(envVar, name) {
+  const f = process.env[envVar] || join(dataRoot, name);
+  try { mkdirSync(dirname(f), { recursive: true }); } catch { /* caller will report */ }
+  return f;
+}
+
 export function dataDir(...parts) {
   const p = join(dataRoot, ...parts);
   try { mkdirSync(p, { recursive: true }); } catch { /* caller will report */ }
@@ -35,4 +44,20 @@ export const paths = {
   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')),
+  // Worktrees for agents started from the dashboard. Same reasoning as
+  // recordings: installed from npm this used to land inside the package — under
+  // the npx cache, even — where git has no repository to branch from and an
+  // upgrade deletes whatever survived.
+  workspace: () => process.env.NEARLY_WORKSPACE || dataDir('workspace'),
+  // The repos `nearly` has been turned on for. Kept so the dashboard knows what
+  // you work in before any session has run in it — otherwise the only repos it
+  // can offer are ones that are already going, which is no help when you are
+  // trying to start the first one.
+  repos: () => dataFile('NEARLY_REPOS', 'repos.json'),
+  // Where records are published, so a pull-request comment can link them. This
+  // lived in the package directory, which `npm install -g` replaces wholesale:
+  // the address was quietly lost on every upgrade and the next record went out
+  // with no link. Same lesson as recordings — anything a person configured
+  // belongs in their space, not in ours.
+  config: () => dataFile('NEARLY_CONFIG', 'config.json'),
 };

package/ui/index.html

@@ -121,6 +121,8 @@
 
   /* ---------- fleet ---------- */
   .new { margin: 0 12px 14px; display: grid; gap: 7px; }
+  .new[hidden] { display: none; }
+  .formErr { margin: 0; font-size: 12px; line-height: 1.45; color: var(--deny); }
   .fleet { padding: 0 12px 18px; display: grid; gap: 8px; }
   .agent {
     background: var(--panel); border: 1px solid var(--rule); border-radius: var(--r);
@@ -238,10 +240,13 @@
 <main>
   <div class="col">
     <div class="col-h"><span class="lbl">Agents</span><span class="count" id="fleetCount">0</span></div>
-    <form class="new" id="newForm">
+    <form class="new" id="newForm" hidden>
       <input name="name" placeholder="Name, e.g. docs" required autocomplete="off">
-      <textarea name="prompt" placeholder="What should this agent do in the workspace?" required></textarea>
+      <input name="repo" id="repoField" placeholder="Repo to branch from" list="repoList" autocomplete="off">
+      <datalist id="repoList"></datalist>
+      <textarea name="prompt" placeholder="What should this agent do on that branch?" required></textarea>
       <button type="submit" data-v="primary">Start agent</button>
+      <p class="formErr" id="newErr" hidden></p>
     </form>
     <div class="fleet" id="sessions"></div>
   </div>
@@ -260,6 +265,10 @@
 </main>
 
 <script>
+  // Lab mode — starting agents from the dashboard — is a different job from
+  // watching your own sessions be gated. It is the demo, not the product, so it
+  // is off unless asked for.
+  const LAB = new URLSearchParams(location.search).has('lab');
   const S = { sessions: new Map(), rules: {}, defaults: {}, askTimeoutMs: 120000 };
   const $ = (id) => document.getElementById(id);
   const fmtT = (ms) => new Date(ms).toLocaleTimeString([], { hour12: false });
@@ -313,7 +322,19 @@
         </div>`;
       el.appendChild(d);
     }
-    if (!S.sessions.size) el.innerHTML = '<div class="empty">No agents yet. Start one above and it runs on your Claude subscription, in its own git worktree.</div>';
+    if (!S.sessions.size) {
+      // What a person who just installed this is actually waiting for is their
+      // own next session, not a button. Saying otherwise taught the wrong
+      // product on the first screen anybody sees.
+      el.innerHTML = LAB
+        ? '<div class="empty">No agents yet. Start one above and it runs on your Claude subscription, on its own branch.</div>'
+        : `<div class="empty"><b>No sessions yet.</b>
+             Work as you normally would. Every session you run in a repo you have turned
+             Nearly on for appears here, and anything that needs you shows up alongside.
+             <div class="keys"><span><kbd>nearly agents</kbd><span>what is gated in a repo</span></span>
+             <span><kbd>nearly lab</kbd><span>start an agent from here instead</span></span></div>
+           </div>`;
+    }
   }
 
   function renderAsks() {
@@ -349,7 +370,7 @@
           <span class="tool">${esc(p.tool)}</span>
           <span class="who">${esc(p.sname)}</span>
           <span class="tag" title="Always and Never attach to this key">${esc(p.key || p.tool)}</span>
-          <span class="clock" data-wait="${p.at}"></span>
+          <span class="clock" data-wait="${p.at}" data-limit="${p.holdMs || ''}"></span>
         </div>
         <pre>${esc(prettyInput(p.tool, p.input))}</pre>
         <div class="blast"><span class="ic">▲</span><span>${blast(p.tool)}</span></div>
@@ -359,7 +380,7 @@
           <button data-v="deny" data-decide="deny" data-scope="once">Deny<kbd>D</kbd></button>
           <button data-v="deny" data-decide="deny" data-scope="always" title="Never allow ${esc(p.key || p.tool)} again this run">Never<kbd>⇧D</kbd></button>
         </div>
-        <div class="deadline" data-wait-bar="${p.at}">
+        <div class="deadline" data-wait-bar="${p.at}" data-limit="${p.holdMs || ''}">
           <div class="bar"><i></i></div>
           <div class="cap"></div>
         </div>
@@ -427,9 +448,9 @@
     if (ev.type === 'snapshot') {
       S.sessions.clear();
       for (const s of ev.sessions) S.sessions.set(s.id, s);
-      S.rules = ev.rules; S.defaults = ev.defaults;
+      S.rules = ev.rules; S.defaults = ev.defaults; S.repos = ev.repos || [];
       if (ev.askTimeoutMs) S.askTimeoutMs = ev.askTimeoutMs;
-      renderSessions(); renderAsks(); renderRules(); renderQuota();
+      renderSessions(); renderAsks(); renderRules(); renderQuota(); fillRepos();
       return;
     }
     if (ev.type === 'rules') { S.rules = ev.rules; renderRules(); return; }
@@ -440,7 +461,7 @@
     if (ev.type === 'decision') { s.pending = (s.pending || []).filter((p) => p.id !== ev.id); }
     if (ev.type === 'result') { s.turns = (s.turns || 0) + 1; s.state = 'idle'; }
     if (ev.type === 'session' && ev.subtype === 'exited') { s.state = 'exited'; s.pending = []; }
-    renderSessions(); renderAsks(); renderQuota(); logEvent(ev);
+    renderSessions(); renderAsks(); renderQuota(); fillRepos(); logEvent(ev);
   }
 
   function connect() {
@@ -451,13 +472,31 @@
   }
   connect();
 
+  if (LAB) $('newForm').hidden = false;
+
   $('newForm').onsubmit = async (e) => {
     e.preventDefault();
     const f = new FormData(e.target);
-    const r = await post('/sessions', { name: f.get('name'), prompt: f.get('prompt') });
-    if (r.error) alert(r.error); else e.target.reset();
+    const err = $('newErr');
+    err.hidden = true;
+    const r = await post('/sessions', { name: f.get('name'), prompt: f.get('prompt'), repo: f.get('repo')?.trim() || undefined });
+    // Inline, not an alert. The reason a start failed is almost always something
+    // you fix in the form right here, and a modal you have to dismiss first puts
+    // the answer behind a click.
+    if (r.error) { err.textContent = r.error; err.hidden = false; }
+    else { e.target.reset(); fillRepos(); }
   };
 
+  // The repos you have attached are the ones worth offering, and if there is
+  // exactly one it is the answer, so fill it in rather than asking.
+  function fillRepos() {
+    const repos = S.repos || [];
+    $('repoList').innerHTML = repos.map((r) => `<option value="${esc(r)}">`).join('');
+    const field = $('repoField');
+    if (repos.length === 1 && !field.value) field.value = repos[0];
+    field.placeholder = repos.length ? 'Repo to branch from' : 'Run `nearly` in a repo first';
+  }
+
   document.body.addEventListener('click', async (e) => {
     const b = e.target.closest('button');
     if (!b) return;
@@ -498,13 +537,17 @@
 
   // One ticker for every countdown on the page.
   function tickWaits() {
-    const limit = S.askTimeoutMs;
+    // Each request carries its own deadline: some harnesses will not wait as
+    // long as the rest, and a bar that drains at the wrong rate is worse than
+    // no bar.
     document.querySelectorAll('[data-wait]').forEach((el) => {
+      const limit = +el.dataset.limit || S.askTimeoutMs;
       const held = Date.now() - +el.dataset.wait;
       el.textContent = `held ${Math.round(held / 1000)}s`;
       el.dataset.urgent = held > limit * 0.75 ? '2' : held > limit * 0.4 ? '1' : '0';
     });
     document.querySelectorAll('[data-wait-bar]').forEach((el) => {
+      const limit = +el.dataset.limit || S.askTimeoutMs;
       const held = Date.now() - +el.dataset.waitBar;
       const left = Math.max(0, limit - held);
       const frac = Math.max(0, Math.min(1, left / limit));