cawdev-cli 1.1.1 → 1.2.1

package/runner/card-import.mjs

@@ -0,0 +1,115 @@
+// Cards from a JSON file — `cawdev import <file>` and `/import` in the
+// terminal, over `POST /api/projects/{slug}/roadmap/import`.
+//
+// The file is either a bare array of cards or `{ "cards": [...] }`, each card
+// `{ title, body?, kind?, severity?, priority?, status?, section?, tags?,
+// assignee? }`. A card with a severity and no kind is an issue. What a card
+// may hold is the server's to say, card by card (`CardImportService`): this
+// side only refuses what is not a list of objects at all, because a file that
+// is not JSON is a sentence the person should read before anything is sent.
+//
+// Zero dependencies, like everything in tools/.
+
+/** The most cards one call takes — `CardImportService.MAX_CARDS`. */
+export const MAX_CARDS = 200;
+
+/**
+ * The cards in a file's text, or a thrown sentence saying what is wrong with
+ * it. Pure: the console's dialog spells the same rule in `board/card-import.ts`.
+ */
+export function cardsFrom(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (failure) {
+    throw new Error(`not JSON: ${failure.message}`);
+  }
+  const cards = Array.isArray(parsed) ? parsed : parsed?.cards;
+  if (!Array.isArray(cards)) {
+    throw new Error('expected a list of cards, or an object with a "cards" list');
+  }
+  if (!cards.length) {
+    throw new Error('the file holds no cards');
+  }
+  if (cards.length > MAX_CARDS) {
+    throw new Error(`at most ${MAX_CARDS} cards in one import — the file holds ${cards.length}`);
+  }
+  const notCards = cards.findIndex((card) => !card || typeof card !== 'object' || Array.isArray(card));
+  if (notCards !== -1) {
+    throw new Error(`card ${notCards + 1} is not an object`);
+  }
+  return cards;
+}
+
+/**
+ * One call. `dryRun` files nothing and says what would be. A card whose title
+ * is taken (on the board, or earlier in the file) is skipped and listed in
+ * `duplicates` unless `allowDuplicates`.
+ */
+export function importCards(session, slug, cards, { dryRun = false, status, allowDuplicates = false } = {}) {
+  return session.request(
+    `/api/projects/${encodeURIComponent(slug)}/roadmap/import?dryRun=${dryRun}`,
+    {
+      method: 'POST',
+      body: { cards, ...(status ? { status } : {}), ...(allowDuplicates ? { allowDuplicates: true } : {}) },
+    },
+  );
+}
+
+/** How many of each kind, in words: `3 issues and 1 roadmap card`. */
+export function countWords(filed) {
+  const issues = filed.filter((card) => card.kind === 'ISSUE').length;
+  const roadmap = filed.length - issues;
+  const parts = [];
+  if (issues) parts.push(`${issues} issue${issues === 1 ? '' : 's'}`);
+  if (roadmap) parts.push(`${roadmap} roadmap card${roadmap === 1 ? '' : 's'}`);
+  return parts.join(' and ') || 'no card';
+}
+
+/**
+ * The lines a result is told in. Every refusal is named with its place in the
+ * file (from 1, as an editor counts) and its title, so it can be found and
+ * fixed; a real run lists the refs it filed. A duplicate names what it
+ * repeats: the project's card, or the file's own earlier one.
+ */
+export function resultLines(result, slug, ink) {
+  const lines = [];
+  const filed = result.filed ?? [];
+  const refused = result.refused ?? [];
+  const duplicates = result.duplicates ?? [];
+  const tail = (refused.length ? ink.warn(` · ${refused.length} refused`) : '')
+    + (duplicates.length ? ink.muted(` · ${duplicates.length} skipped as duplicates`) : '');
+  if (result.dryRun) {
+    lines.push(`  ${ink.text(`${countWords(filed)} would be filed on ${slug}`)}${tail}`);
+  } else {
+    lines.push(`  ${ink.success(`filed ${countWords(filed)} on ${slug}`)}${tail}`);
+    for (const card of filed) {
+      lines.push(`    ${ink.accent(card.ref ?? '?')} ${ink.muted(card.title)}`);
+    }
+  }
+  for (const card of refused) {
+    lines.push(`    ${ink.danger(`#${card.index + 1}`)} ${ink.muted(card.title ?? '(no title)')} — ${card.reason}`);
+  }
+  for (const card of duplicates) {
+    const of = card.ref ? `already ${card.ref}` : `same as #${card.sameAs + 1}`;
+    lines.push(`    ${ink.muted(`#${card.index + 1} ${card.title} — ${of}`)}`);
+  }
+  return lines;
+}
+
+/**
+ * Which project, when the command did not name one: the project whose checkout
+ * the directory stands in (the deepest, when checkouts nest), else the one
+ * project this machine serves. Null when it cannot be told, and the command
+ * asks for `--project`. `pathsOf` and `absolute` are configure's and paths'.
+ */
+export function projectFor(projects, cwd, { pathsOf, absolute }) {
+  const slugs = Object.keys(projects ?? {});
+  const inside = (path) => cwd === path || cwd.startsWith(`${path.replace(/\/+$/, '')}/`);
+  const here = slugs
+    .flatMap((slug) => pathsOf(projects[slug]).map((path) => [slug, absolute(path)]))
+    .filter(([, path]) => inside(path))
+    .sort((left, right) => right[1].length - left[1].length);
+  if (here.length) return here[0][0];
+  return slugs.length === 1 ? slugs[0] : null;
+}

package/runner/cawdev.mjs

@@ -30,8 +30,10 @@ import { asker, askOne, mintForThisMachine, setUpThisMachine } from './bootstrap
 import { liveSockets, probeSocket, socketPathFor } from './control.mjs';
 import {
   addProject, addWorkspace, readConfigFile, reloadIfRunning, removeProject, setAcceptsRulesFromConsole,
-  setMaxPlanningRuns, setQuality, setAgentEnabled, thisRunnerId,
+  setMaxPlanningRuns, setQuality, setAgentEnabled, thisRunnerId, pathsOf,
 } from './configure.mjs';
+import { cardsFrom, importCards, projectFor, resultLines } from './card-import.mjs';
+import { absolute, expandHome } from './paths.mjs';
 import { restartNeededFor, runnerNameOf } from '../lib/runner-config.mjs';
 import { Select } from './select.mjs';
 import { storedSession } from './sign-in.mjs';
@@ -72,6 +74,16 @@ const USAGE = `
   cawdev config planning-limit <n>       how many planning runs (PLAN, SCOPE, AUDIT, REVIEW) run here at once; 0 is no limit
   cawdev config show                     this machine's config, token redacted
 
+  cawdev import <file.json>              file the cards of a JSON file: a list
+                                         of {title, body, severity, tags, …},
+                                         or {"cards": [...]}. Checks first, then
+                                         asks. --project <slug> (else the
+                                         checkout you stand in), --status <S>
+                                         where cards naming none land,
+                                         --dry-run to only check, --yes to not ask.
+                                         A card whose title is taken is skipped;
+                                         --allow-duplicates files it anyway
+
   On a machine with no config, cawdev sets one up: it signs you in through the
   browser, asks which projects this machine should run agents for, clones them,
   and mints its own runner token. No token is ever typed. \`cawdev config\` is
@@ -568,6 +580,58 @@ export async function runAction([verb, ...rest], { configPath, file, url, sessio
   throw new Error(`Not a cawdev config command: ${verb}. See cawdev --help.`);
 }
 
+/**
+ * `cawdev import <file>` — the cards of a JSON file, filed as you. A dry run
+ * goes first and is shown, so what would be refused is read before anything
+ * is written; then it asks, unless `--yes`. Running it twice files the cards
+ * twice, which is why it asks.
+ */
+export async function runImport(args, ink, { cwd = process.cwd(), say = (line) => console.log(line) } = {}) {
+  const takesValue = new Set(['--project', '--status', '--config', '--url', '--runner']);
+  const path = args.find((arg, at) => !arg.startsWith('--') && !takesValue.has(args[at - 1]));
+  if (!path) {
+    throw new Error('Name the file: cawdev import <file.json> [--project <slug>] [--dry-run]');
+  }
+  const cards = cardsFrom(await readFile(resolve(cwd, expandHome(path)), 'utf8').catch((failure) => {
+    throw new Error(`Could not read ${path}: ${failure.message}`);
+  }));
+
+  const configPath = await findConfig(args, process.env, cwd);
+  const file = configPath ? await readConfigFile(configPath) : null;
+  const slug = valueOf(args, '--project') ?? projectFor(file?.projects, cwd, { pathsOf, absolute });
+  if (!slug) {
+    throw new Error('Which project? Name it: cawdev import <file.json> --project <slug>');
+  }
+  const session = await storedSession(signInUrl(file, args));
+  if (!session.signedIn) {
+    throw new Error('Not signed in on this machine. Run `cawdev` and /login, or `cawdev --setup`.');
+  }
+  const status = valueOf(args, '--status') ?? undefined;
+  const allowDuplicates = args.includes('--allow-duplicates');
+
+  say(`  ${ink.muted(`${path}: ${cards.length} card${cards.length === 1 ? '' : 's'}, checking against ${slug}…`)}`);
+  const checked = await importCards(session, slug, cards, { dryRun: true, status, allowDuplicates });
+  for (const line of resultLines(checked, slug, ink)) say(line);
+  if (args.includes('--dry-run') || !checked.filed?.length) {
+    return checked;
+  }
+  if (!args.includes('--yes')) {
+    const ask = asker();
+    try {
+      const answer = (await ask.line(`  File ${checked.filed.length} on ${slug}? [y/N] `)).trim();
+      if (!/^y(es)?$/i.test(answer)) {
+        say(`  ${ink.muted('Nothing filed.')}`);
+        return checked;
+      }
+    } finally {
+      ask.close();
+    }
+  }
+  const done = await importCards(session, slug, cards, { status, allowDuplicates });
+  for (const line of resultLines(done, slug, ink)) say(line);
+  return done;
+}
+
 /** The config as somebody would want to read it back — never the secret. */
 export function printConfig(file, ink, say) {
   const shown = { ...file };
@@ -592,6 +656,11 @@ async function main() {
     return;
   }
 
+  if (argv[0] === 'import') {
+    await runImport(argv.slice(1), ink);
+    return;
+  }
+
   const url = await launchUrl(argv);
 
   if (argv.includes('--version')) {

package/runner/diff-view.mjs

@@ -0,0 +1,252 @@
+// A branch's diff, in the terminal — `/review` (attach.mjs).
+//
+// The diff comes from local git, never from the platform: this terminal runs
+// on a machine with a checkout of the project, `git fetch` moves refs and
+// touches no file, and `git diff base...branch` reads objects only, so it is
+// safe even in a checkout somebody is working in. No endpoint carries a diff,
+// and it is the same for GitHub, GitLab and Bitbucket.
+//
+// Two halves. `branchDiff` is the plumbing (git, a bounded buffer). `parseDiff`
+// and `layoutDiff` are pure: text in, files out; files in, rows out — the rows
+// already wrapped to the width, so the reader's row numbers are the file
+// headers' and `n`/`p` can jump to them.
+//
+// Zero dependencies, like everything in tools/.
+
+import { spawn } from 'node:child_process';
+import { wrap } from '../lib/ansi.mjs';
+
+/** The most diff text read; past it the diff is cut and says so. */
+export const MAX_DIFF_BYTES = 8 * 1024 * 1024;
+
+/** A file this long opens folded: a review reads it on purpose, not by scrolling past it. */
+export const FOLD_OVER_LINES = 400;
+
+/** Generated files nobody reviews line by line. */
+const GENERATED = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|[^/]*\.lock|go\.sum)$/;
+
+/**
+ * Text from a diff, made safe to draw: a file's bytes can hold escape
+ * sequences, and a diff printed raw could move the cursor, retitle the window
+ * or worse. Tabs become spaces so the width is what is drawn.
+ */
+export function printableDiffLine(text) {
+  return String(text)
+    .replace(/\t/g, '    ')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '�');
+}
+
+/** `a/x` → `x`, and git's quoted form of a path with odd bytes. */
+function pathOf(side) {
+  let text = side.trim();
+  if (text.startsWith('"') && text.endsWith('"')) {
+    text = text.slice(1, -1).replace(/\\(.)/g, '$1');
+  }
+  return text.replace(/^[ab]\//, '');
+}
+
+/**
+ * `git diff` output → files. Each file: `path` (the new one; the old one for a
+ * deletion), `oldPath` when renamed, `status` (added, deleted, renamed,
+ * modified), `binary`, `additions`, `deletions`, and `lines`: hunk headers and
+ * the lines under them, each `{ kind: 'hunk' | 'add' | 'del' | 'ctx' | 'note', text }`.
+ */
+export function parseDiff(text) {
+  const files = [];
+  let file = null;
+  for (const raw of String(text).split('\n')) {
+    if (raw.startsWith('diff --git ')) {
+      const match = /^diff --git (\S+|"[^"]*") (\S+|"[^"]*")$/.exec(raw);
+      file = {
+        path: match ? pathOf(match[2]) : raw.slice(11),
+        oldPath: null,
+        status: 'modified',
+        binary: false,
+        additions: 0,
+        deletions: 0,
+        lines: [],
+      };
+      files.push(file);
+      continue;
+    }
+    if (!file) continue;
+    if (raw.startsWith('@@')) {
+      file.lines.push({ kind: 'hunk', text: raw });
+      continue;
+    }
+    const inHunk = file.lines.length > 0;
+    if (!inHunk) {
+      // The header between `diff --git` and the first hunk.
+      if (raw.startsWith('new file mode')) file.status = 'added';
+      else if (raw.startsWith('deleted file mode')) file.status = 'deleted';
+      else if (raw.startsWith('rename from ')) {
+        file.status = 'renamed';
+        file.oldPath = raw.slice(12);
+      } else if (raw.startsWith('rename to ')) file.path = raw.slice(10);
+      else if (raw.startsWith('Binary files ') || raw === 'GIT binary patch') file.binary = true;
+      else if (raw.startsWith('--- ') && file.status === 'deleted') file.path = pathOf(raw.slice(4));
+      continue;
+    }
+    if (raw.startsWith('+')) {
+      file.additions++;
+      file.lines.push({ kind: 'add', text: raw });
+    } else if (raw.startsWith('-')) {
+      file.deletions++;
+      file.lines.push({ kind: 'del', text: raw });
+    } else if (raw.startsWith('\\')) {
+      file.lines.push({ kind: 'note', text: raw });
+    } else if (raw !== '' || file.lines.length) {
+      file.lines.push({ kind: 'ctx', text: raw });
+    }
+  }
+  // The split leaves a last empty context line where the text ended in \n.
+  for (const each of files) {
+    while (each.lines.length && each.lines.at(-1).kind === 'ctx' && each.lines.at(-1).text === '') {
+      each.lines.pop();
+    }
+  }
+  return files;
+}
+
+/** Whether a file opens folded: generated, binary, or too long to read by scrolling. */
+export function foldedByDefault(file) {
+  return file.binary || GENERATED.test(file.path) || file.lines.length > FOLD_OVER_LINES;
+}
+
+/**
+ * The rows the reader draws, wrapped to `width`, and where each file starts.
+ *
+ * @param review `{ files, folded: Set<path>, branch, base, cut, stale }`
+ * @returns `{ rows, fileRows }` — `fileRows[i]` is the row of `files[i]`'s header.
+ */
+export function layoutDiff(review, width, ink) {
+  const { files, folded = new Set(), branch, base, cut = false, stale = false } = review;
+  const room = Math.max(10, width);
+  const rows = [];
+  const push = (line) => rows.push(...wrap(line, room));
+  const additions = files.reduce((sum, file) => sum + file.additions, 0);
+  const deletions = files.reduce((sum, file) => sum + file.deletions, 0);
+
+  push(`${ink.bold(branch ?? '')} ${ink.muted(`into ${base ?? '?'}`)}  `
+    + `${ink.muted(`${files.length} file${files.length === 1 ? '' : 's'}`)} `
+    + `${ink.success(`+${additions}`)} ${ink.danger(`−${deletions}`)}`);
+  if (stale) push(ink.warn('origin could not be fetched: this is the checkout\'s copy, and may be behind'));
+  if (cut) push(ink.warn('the diff was cut: it is longer than the terminal reads'));
+  if (!files.length) {
+    push(ink.muted('no change between the two: nothing to review'));
+    return { rows, fileRows: [] };
+  }
+  push('');
+  for (const file of files) {
+    push(`  ${statusMark(file, ink)} ${printableDiffLine(file.path)}  `
+      + `${ink.success(`+${file.additions}`)} ${ink.danger(`−${file.deletions}`)}`);
+  }
+
+  const fileRows = [];
+  for (const file of files) {
+    push('');
+    fileRows.push(rows.length);
+    const open = !folded.has(file.path);
+    const named = file.oldPath ? `${file.oldPath} → ${file.path}` : file.path;
+    push(`${ink.bold(`${open ? '▾' : '▸'} ${printableDiffLine(named)}`)}  `
+      + `${ink.success(`+${file.additions}`)} ${ink.danger(`−${file.deletions}`)} ${ink.muted(file.status)}`);
+    if (file.binary) {
+      push(ink.muted('  binary: not drawn'));
+      continue;
+    }
+    if (!open) {
+      push(ink.muted(`  folded: ${file.lines.length} lines · f opens it`));
+      continue;
+    }
+    for (const line of file.lines) {
+      const text = printableDiffLine(line.text);
+      if (line.kind === 'hunk') push(ink.accent(text));
+      else if (line.kind === 'add') push(ink.success(text));
+      else if (line.kind === 'del') push(ink.danger(text));
+      else push(ink.muted(text));
+    }
+  }
+  return { rows, fileRows };
+}
+
+function statusMark(file, ink) {
+  if (file.status === 'added') return ink.success('A');
+  if (file.status === 'deleted') return ink.danger('D');
+  if (file.status === 'renamed') return ink.accent('R');
+  return ink.muted('M');
+}
+
+/** Which file the row is in: the last header at or above it, or -1 above the first. */
+export function fileAt(fileRows, row) {
+  let at = -1;
+  fileRows.forEach((start, i) => {
+    if (start <= row) at = i;
+  });
+  return at;
+}
+
+// --- the plumbing ------------------------------------------------------------
+
+/** One git command in `cwd`; stdout capped at `max` bytes. Never throws. */
+export function git(cwd, args, { max = MAX_DIFF_BYTES } = {}) {
+  return new Promise((done) => {
+    let child;
+    try {
+      child = spawn('git', ['-C', cwd, ...args], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // A fetch never asks a person: the terminal is drawing over the tty.
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? 'ssh -o BatchMode=yes' },
+      });
+    } catch (failure) {
+      done({ code: -1, out: '', err: failure.message, cut: false });
+      return;
+    }
+    const chunks = [];
+    let size = 0;
+    let cut = false;
+    let err = '';
+    child.stdout.on('data', (chunk) => {
+      if (cut) return;
+      if (size + chunk.length > max) {
+        chunks.push(chunk.subarray(0, max - size));
+        cut = true;
+        child.kill();
+        return;
+      }
+      chunks.push(chunk);
+      size += chunk.length;
+    });
+    child.stderr.on('data', (chunk) => {
+      err += chunk;
+    });
+    child.on('error', (failure) => done({ code: -1, out: '', err: failure.message, cut: false }));
+    child.on('close', (code) => done({ code: cut ? 0 : code, out: Buffer.concat(chunks).toString('utf8'), err: err.trim(), cut }));
+  });
+}
+
+/**
+ * The diff of `branch` against `base` in the checkout at `cwd`: what the
+ * branch adds since it left the base (three dots, from the merge base).
+ * Fetches both first; a fetch that fails (offline, a branch never pushed)
+ * falls back to what the checkout already has, and says so in `stale`.
+ * Throws a sentence when neither ref can be found.
+ */
+export async function branchDiff(cwd, { branch, base }, run = git) {
+  const fetched = await run(cwd, ['fetch', '--quiet', 'origin', base, branch], { max: 1 << 20 });
+  const ref = async (name) => {
+    for (const candidate of [`origin/${name}`, name]) {
+      const found = await run(cwd, ['rev-parse', '--verify', '--quiet', `${candidate}^{commit}`], { max: 4096 });
+      if (found.code === 0 && found.out.trim()) return candidate;
+    }
+    return null;
+  };
+  const head = await ref(branch);
+  if (!head) throw new Error(`${branch} is not in ${cwd}, on origin or here`);
+  const from = await ref(base);
+  if (!from) throw new Error(`${base} is not in ${cwd}, on origin or here`);
+  const diff = await run(cwd, ['-c', 'core.quotepath=off', 'diff', '--no-color', '--no-ext-diff', '-M',
+    `${from}...${head}`]);
+  if (diff.code !== 0) throw new Error(`git diff failed: ${diff.err || `exit ${diff.code}`}`);
+  return { files: parseDiff(diff.out), cut: diff.cut, stale: fetched.code !== 0, head, from };
+}

package/runner/git-lock.mjs

@@ -0,0 +1,73 @@
+/**
+ * A git lock a crash left behind, and the `/clean` that removes it.
+ *
+ * When the machine dies mid-git (a crash, a power cut), git leaves
+ * `.git/index.lock` behind and refuses every later command in that checkout
+ * with "Unable to create '…/index.lock': File exists". Every session that
+ * prepares its branch there fails the same way, and `/continue` alone only
+ * fails again. `/clean` removes the lock; `/continue` then picks the session up.
+ *
+ * <strong>The path is read from the failure, then checked against the run's
+ * own checkout.</strong> The failure text travels through the platform, so it
+ * is trusted no further than a lock file inside `<workspace>/.git/` (or the
+ * reading worktree's admin directory beside it). Anything else is refused, and
+ * the path is named so a person can judge it.
+ *
+ * <strong>Young locks are left alone.</strong> A lock a live git holds is
+ * seconds old at most, because the daemon never opens an editor; one older
+ * than `MIN_AGE_MS` is a leftover. Refusing a fresh one is the direction
+ * `tool-rules.mjs` fails in: unsure means held.
+ */
+import { rm, stat } from 'node:fs/promises';
+import { basename, sep } from 'node:path';
+
+/** How old a lock must be before `/clean` calls it a leftover. */
+export const MIN_AGE_MS = 60_000;
+
+const LOCK_SAID = /Unable to create '([^']+\.lock)': File exists/;
+
+/**
+ * The stale lock a session stopped on, or null. `said` is the run's
+ * `exitSummary`; `workspace` the checkout it ran in. Pure.
+ */
+export function staleLockOf(said, workspace) {
+  const path = LOCK_SAID.exec(String(said ?? ''))?.[1];
+  if (!path || !workspace || path.includes(`${sep}..${sep}`)) {
+    return null;
+  }
+  const root = workspace.endsWith(sep) ? workspace.slice(0, -1) : workspace;
+  const own = path.startsWith(`${root}${sep}.git${sep}`);
+  // The reading copy (`<first>-read`) is a worktree: its lock lives in the
+  // main checkout's `.git/worktrees/<name>/`.
+  const worktree = path.includes(`${sep}.git${sep}worktrees${sep}${basename(root)}${sep}`);
+  return own || worktree ? path : null;
+}
+
+/**
+ * Removes the lock if it is old enough to be a leftover. Resolves to what was
+ * done, in words the terminal prints: `{ removed, said }`. Never throws.
+ */
+export async function removeStaleLock(path, { now = Date.now(), minAgeMs = MIN_AGE_MS } = {}) {
+  let info;
+  try {
+    info = await stat(path);
+  } catch (failure) {
+    if (failure.code === 'ENOENT') {
+      return { removed: false, said: `${path} is already gone — /continue picks it back up` };
+    }
+    return { removed: false, said: `could not read ${path}: ${failure.message}` };
+  }
+  const age = now - info.mtimeMs;
+  if (age < minAgeMs) {
+    return {
+      removed: false,
+      said: `${path} is ${Math.max(0, Math.round(age / 1000))}s old — a git may still hold it; try again in a minute`,
+    };
+  }
+  try {
+    await rm(path);
+  } catch (failure) {
+    return { removed: false, said: `could not remove ${path}: ${failure.message}` };
+  }
+  return { removed: true, said: `removed ${path}` };
+}