cawdev-cli 0.9.0

package/runner/scrollback.mjs

@@ -0,0 +1,165 @@
+// The terminal's own scrollback, with a live region pinned under it — R81.
+//
+// **This replaces a pane manager rather than adding a framework.** The client
+// used to take the alternate screen and repaint a viewport into it, which meant
+// the terminal's scroll, its wheel, its search and its copy all stopped working
+// the moment you attached, and the transcript above the fold was gone. Claude
+// Code's CLI does not do that, and the difference is the one people notice.
+//
+// So: transcript lines are PRINTED. They go into the scrollback and are never
+// touched again — which is what makes wheel, `shift+PgUp`, search and copy the
+// terminal's job rather than ours. Only the last few lines and the footer are
+// drawn, and they are the only thing that is ever erased.
+//
+// The whole mechanism is three escape sequences and one invariant:
+//
+//   **After every write, the cursor sits at column 0 of the live region's first
+//   row, and everything below it belongs to the live region.**
+//
+// Which makes the update trivial: erase from the cursor down (`ESC[0J`), print
+// whatever is being committed to the scrollback, print the live region, then
+// walk back up by however many rows it took.
+//
+// The one rule that keeps that arithmetic honest: **every live line is clipped
+// to the width.** A line that wraps occupies two rows and one row of cursor
+// arithmetic, and the difference between those two numbers is how a footer
+// eats a transcript. Committed lines are NOT clipped — they are the terminal's
+// to wrap, and its to reflow when the window changes.
+
+import { clip, colourDepth, stripAnsi } from '../lib/ansi.mjs';
+
+const ESC = '\x1b';
+const ERASE_DOWN = `${ESC}[0J`;
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+const RESET = `${ESC}[0m`;
+
+export class Scrollback {
+  /**
+   * @param out where to write. `process.stdout` in the real thing; anything
+   *   with `write` in a test, which is how the arithmetic below is checked
+   *   without a terminal.
+   */
+  constructor(out = process.stdout, {
+    colour = colourDepth(process.env, out) > 0,
+    // A dumb terminal is a TTY that cannot be repainted, and R83 needs to say
+    // so: everything drawn here assumes `ESC[0J` and `ESC[nA` mean something.
+    // Passed in rather than read here so the caller keeps one flag for "can this
+    // be drawn on at all", which is also what decides whether it reads keys.
+    tty = Boolean(out.isTTY) && process.env.TERM !== 'dumb',
+  } = {}) {
+    this.out = out;
+    this.drawn = 0;
+    this.pinned = [];
+    // A pipe, a `less`, a CI log. There is no cursor to move and no region to
+    // pin, so the live region simply stops existing and the transcript is the
+    // whole output — which is the honest degradation, not a lesser one.
+    this.tty = tty;
+    // **Two flags, because they are two questions.** `tty` is about a cursor;
+    // this is about escape codes, and `FORCE_COLOR` is somebody piping into
+    // something that does understand them. Where it is off, a committed line is
+    // stripped rather than merely un-tinted: the transcript carries the AGENT'S
+    // colour (R23), which our own painter has no say over, and a file full of
+    // `ESC[32m` is not what "legible through a pipe" means.
+    this.colour = colour;
+  }
+
+  get width() {
+    return this.out.columns ?? 80;
+  }
+
+  get height() {
+    return this.out.rows ?? 24;
+  }
+
+  /** Takes the cursor. The alternate screen is deliberately NOT entered. */
+  open() {
+    if (this.tty) {
+      this.out.write(HIDE_CURSOR);
+    }
+  }
+
+  /**
+   * Commit lines to the scrollback and replace what is pinned, in one write.
+   *
+   * **One call rather than two, and that is not tidiness.** Printing a line and
+   * then setting the footer is two erase-and-redraw cycles per line: on a
+   * session emitting a few hundred lines a second the terminal spends its time
+   * on escape codes, and — worse — the footer drawn by the first of the two is
+   * the *previous* one, so a stale prompt line flashes under everything that is
+   * printed. Both were visible in a real terminal.
+   *
+   * Committed lines are not clipped and not wrapped: a long line is the
+   * terminal's to fold, and folding it here would freeze today's width into the
+   * copy somebody takes tomorrow.
+   */
+  update(lines = [], live = this.pinned) {
+    this.pinned = live ?? [];
+    this.#write(Array.isArray(lines) ? lines : [lines], this.pinned);
+  }
+
+  /** Commit lines under whatever is already pinned. */
+  print(lines) {
+    this.update(lines, this.pinned);
+  }
+
+  /** Replace what is pinned at the bottom. */
+  live(lines) {
+    this.update([], lines ?? []);
+  }
+
+  /**
+   * The window changed shape.
+   *
+   * Nothing is repaired above the cursor, and that is the point: those lines
+   * are the terminal's now, and it has already reflowed them the way it
+   * reflows every other line in the buffer. Only the live region is redrawn.
+   */
+  resize() {
+    if (!this.tty) return;
+    this.out.write('\r');
+    this.drawn = 0;
+    this.#write([], this.pinned);
+  }
+
+  /** Give the terminal back, leaving the transcript where it is. */
+  close() {
+    if (!this.tty) return;
+    this.out.write(`${ERASE_DOWN}${SHOW_CURSOR}`);
+    this.drawn = 0;
+  }
+
+  /** A line as it should be committed: closed if coloured, plain if not. */
+  #commit(line) {
+    return this.colour ? `${line}${RESET}\n` : `${stripAnsi(line)}\n`;
+  }
+
+  #write(committed, live) {
+    if (!this.tty) {
+      // No region, so nothing to erase and nothing to walk back over.
+      if (committed.length) {
+        this.out.write(committed.map((line) => this.#commit(line)).join(''));
+      }
+      return;
+    }
+
+    // A live region taller than the window would scroll the transcript off the
+    // top and leave the cursor arithmetic pointing at rows that are no longer
+    // there. One row is kept for whatever is committed next.
+    const shown = live.slice(-Math.max(1, this.height - 1)).map((line) => clip(line, this.width));
+
+    let out = ERASE_DOWN;
+    for (const line of committed) {
+      out += this.#commit(line);
+    }
+    for (const line of shown) {
+      out += `${line}${RESET}\n`;
+    }
+    if (shown.length) {
+      out += `${ESC}[${shown.length}A`;
+    }
+    out += '\r';
+    this.out.write(out);
+    this.drawn = shown.length;
+  }
+}

package/runner/select.mjs

@@ -0,0 +1,316 @@
+// One select widget, written once — R83.
+//
+// **The CLI was the one surface that threw the agent's options away.**
+// `ask_user` has carried `options` since R10 — the agent has usually already
+// worked out the two or three answers it can act on — and the console renders
+// them as buttons. Here the question printed and you retyped one of them,
+// spelled correctly. A permission request had the same shape and the same
+// problem: R60's three answers were three single keys bolted to the side of a
+// scrolling transcript rather than a thing you look at and choose from.
+//
+// So there is ONE of these and everything that offers a choice is it: the
+// question picker, the permission decision, and R81's `L` run overlay, which
+// stops being its own code. A second implementation of "a cursor, some rows and
+// a window that walks" is a second place for the arithmetic to be wrong by one.
+//
+// Three rules the widget keeps:
+//
+//   1. **It draws into R81's live region and never rewrites the scrollback.**
+//      `lines()` returns rows; the client pins them. Nothing here writes.
+//   2. **Getting to free text costs one key.** `ask_user` says people can still
+//      answer in prose because the options are the agent's GUESS at the shape of
+//      the decision, and the whole value of asking a person is that they can say
+//      the thing that was not on the list. So the last row opens a line editor,
+//      and Esc from there comes back to the list rather than abandoning the
+//      answer.
+//   3. **Where there is no cursor to move it is a numbered list read from
+//      stdin** — a plain prompt, not a broken repaint. {@link plainLines} and
+//      {@link pickFromLine} are that path, and they are the same rows.
+//
+// Pure, and rendered from a plain object, for R62's reason: a widget built
+// inside a draw method can only be checked by looking at it, and three of R81's
+// five layout bugs were found by rendering at four widths and READING them.
+
+import { clip, keyList, painter, visibleWidth } from '../lib/ansi.mjs';
+
+const ESC = '\x1b';
+
+/** The row that is always last on a question, and what choosing it means. */
+export const WRITE_MY_OWN = '__write-my-own__';
+
+// Arrows, and the keys people who live in a terminal press instead of arrows.
+// Tab is here because R81's run list took it and taking it away would be a
+// regression nobody asked for.
+const DOWN = new Set([`${ESC}[B`, `${ESC}OB`, '\t', '\x0e', 'j']);
+const UP = new Set([`${ESC}[A`, `${ESC}OA`, `${ESC}[Z`, '\x10', 'k']);
+
+/**
+ * A choice: a title, some rows, and a cursor.
+ *
+ * `kind` is for the caller — it is what tells the client whether a chosen row is
+ * an answer, a decision or a run to watch. The widget itself does not care.
+ */
+export class Select {
+  constructor({ kind = 'choice', title = '', rows = [], at = 0, empty = null, hint = null }) {
+    this.kind = kind;
+    this.title = title;
+    this.rows = rows;
+    this.empty = empty;
+    this.hint = hint;
+    this.at = Math.max(0, Math.min(at, Math.max(0, rows.length - 1)));
+  }
+
+  get row() {
+    return this.rows[this.at] ?? null;
+  }
+
+  /** Whether the last row opens a line editor — rule 2 above. */
+  get freeText() {
+    return this.rows.some((row) => row.id === WRITE_MY_OWN);
+  }
+
+  move(by) {
+    if (!this.rows.length) {
+      this.at = 0;
+      return;
+    }
+    this.at = (this.at + by + this.rows.length) % this.rows.length;
+  }
+
+  /**
+   * One key, and what it settled.
+   *
+   * Returns null for a key that means nothing here, so the caller can decide
+   * whether it means something to IT — which is how the single permission keys
+   * keep working while the picker is open.
+   *
+   * **A digit chooses rather than merely moving.** It is the only key on this
+   * widget that is faster than the arrows, and making it a two-step would spend
+   * the whole reason somebody reached for it.
+   */
+  key(pressed) {
+    if (pressed === ESC) {
+      return { done: 'cancelled', row: null };
+    }
+    if (pressed === '\r' || pressed === '\n') {
+      return { done: 'chosen', row: this.row };
+    }
+    if (DOWN.has(pressed)) {
+      this.move(1);
+      return { done: null, moved: true };
+    }
+    if (UP.has(pressed)) {
+      this.move(-1);
+      return { done: null, moved: true };
+    }
+    if (/^[1-9]$/.test(pressed)) {
+      const at = Number(pressed) - 1;
+      if (at < this.rows.length) {
+        this.at = at;
+        return { done: 'chosen', row: this.rows[at] };
+      }
+      return null;
+    }
+    return null;
+  }
+
+  lines(width, ink = painter(3), room = 8) {
+    return selectLines(this, width, ink, room);
+  }
+}
+
+/**
+ * The widget, drawn.
+ *
+ * The window walks with the cursor rather than the list scrolling under it: a
+ * machine with twenty runs should still show the one you are on, and a question
+ * with a dozen options should still show the one about to be chosen.
+ */
+export function selectLines(select, width, ink = painter(3), room = 8) {
+  const lines = [];
+  if (select.title) {
+    lines.push(clip(` ${ink.muted(select.title)}`, width));
+  }
+  if (!select.rows.length) {
+    lines.push(clip(`  ${ink.muted(select.empty ?? 'nothing to choose from')}`, width));
+  }
+
+  const shown = Math.max(1, Math.min(select.rows.length, room));
+  const from = Math.max(0, Math.min(select.at - Math.floor(shown / 2), select.rows.length - shown));
+  select.rows.slice(from, from + shown).forEach((row, offset) => {
+    const at = from + offset;
+    lines.push(rowLine(row, {
+      chosen: at === select.at,
+      marker: row.marker ?? ' ',
+      // Past nine there is no digit to offer, and a number nobody can press is
+      // worse than a space.
+      number: at < 9 ? String(at + 1) : ' ',
+    }, width, ink));
+  });
+  if (select.rows.length > shown) {
+    lines.push(clip(`  ${ink.muted(`… ${select.rows.length - shown} more`)}`, width));
+  }
+
+  lines.push(hintLine(select, width, ink));
+  return lines;
+}
+
+/**
+ * What to press.
+ *
+ * **`esc leave` has its room reserved rather than taking its chances.**
+ * {@link keyList} drops whole keys from the right, which is the correct
+ * behaviour and would drop exactly the wrong one here: leaving is the key
+ * somebody reaches for when they do not want any of this, and it is the last
+ * thing that should go when the terminal is narrow. So the others are given
+ * what is left over and it is written after them, in the order somebody reads.
+ * It is the same rule R51's banner keeps about `n refuse`.
+ */
+function hintLine(select, width, ink) {
+  const leave = ink.muted('esc leave');
+  const room = width - visibleWidth(leave) - 4;
+  if (room < 10) {
+    return clip(` ${leave}`, width);
+  }
+  const keys = [ink.muted('↑↓ move'), ink.muted('enter choose')];
+  if (select.rows.length > 1) {
+    keys.push(ink.muted('1-9 pick'));
+  }
+  if (select.hint) {
+    keys.push(ink.muted(select.hint));
+  }
+  return clip(` ${keyList(keys, '', room, ink)}${ink.muted(' · ')}${leave}`, width);
+}
+
+/**
+ * One row, and what gives way when there is not enough of it.
+ *
+ * A row may bring its own renderer — `runLine` narrows a run's LABEL and keeps
+ * the reason it is queued, which is R58's lesson about which half should survive
+ * and is not a rule a generic row could guess. Everything else is a label, a
+ * `short` wording of it, and a hint beside it, and they give way in that order:
+ *
+ *   1. **The hint goes first.** It is a gloss; the label is the thing being
+ *      chosen. Rendered at forty columns the other way round, this row read
+ *      `2 Allow Bash(mvn *) for the rest of  dies with the session`, which
+ *      spends the last columns on the aside and cuts the answer.
+ *   2. **Then the wording shortens, a whole phrasing at a time.** R78's rule,
+ *      and this is the widget where it matters most: `Allow Bash(mvn *) for th`
+ *      describes a promise nobody made, and these words are a decision about
+ *      what a machine may do rather than a status.
+ *   3. Only a terminal too narrow for the short wording on its own reaches the
+ *      clip, and there is nothing better than a cut line to give it.
+ */
+function rowLine(row, opts, width, ink) {
+  if (row.render) {
+    return row.render(opts, width, ink);
+  }
+  const head = `${opts.chosen ? ink.bold('❯') : ' '}${opts.marker ?? ' '}${ink.muted(opts.number ?? ' ')} `;
+  const room = width - visibleWidth(head);
+  const hint = row.hint ? `  ${row.hint}` : '';
+
+  const label = String(row.label ?? '');
+  const fits = (text, withHint) =>
+    visibleWidth(text) + (withHint ? visibleWidth(hint) : 0) <= room;
+
+  const withHint = fits(label, true);
+  const text = fits(label, false) || !row.short || !fits(row.short, false)
+    ? clip(label, Math.max(8, room))
+    : row.short;
+
+  return clip(
+    `${head}${opts.chosen ? ink.text(text) : text}${withHint ? ink.muted(hint) : ''}`,
+    width,
+  );
+}
+
+/**
+ * The same choice where there is no cursor to move — R62's rule, R81's rule.
+ *
+ * Through a pipe, on a dumb terminal, or anywhere the live region does not
+ * exist, this is what a picker is: the rows PRINTED with numbers beside them and
+ * a line read from stdin. Not a lesser widget — a different one, and the honest
+ * shape for a stream that cannot be repainted.
+ *
+ * The free-text row does not need a number here. Anything that is not a number
+ * IS the free text, which is what a plain prompt has always meant.
+ */
+export function plainLines(select, { many = false } = {}) {
+  const lines = ['', select.title ? ` ${select.title}` : ' choose:'];
+  if (!select.rows.length) {
+    lines.push(`  ${select.empty ?? 'nothing to choose from'}`);
+  }
+  select.rows.forEach((row, at) => {
+    // A hint that repeats the label is noise — "1) cawdev — cawdev" — and it
+    // happens whenever a thing's name and its identifier agree, which for a
+    // slug is most of the time.
+    const hint = row.hint && row.hint !== row.label ? `  — ${row.hint}` : '';
+    lines.push(`  ${at + 1}) ${row.label}${hint}`);
+  });
+  // The LAST line is the instruction, and there is exactly one of it. R93 added
+  // a question with several answers and printed its own instruction under this
+  // one, so the screen said "a number:" and then "several numbers:" — the
+  // widget knowing both forms is what stops that.
+  lines.push(many
+    ? '  several numbers, or enter for all:'
+    : select.freeText
+      ? '  a number, or just type your answer:'
+      : '  a number:');
+  return lines;
+}
+
+/**
+ * A typed line, against the rows.
+ *
+ * Returns null for a line that settles nothing, so the caller asks again rather
+ * than guessing — except where free text is on offer, in which case a line that
+ * is not a number is the answer itself.
+ */
+export function pickFromLine(select, typed) {
+  const text = String(typed ?? '').trim();
+  if (!text) {
+    return null;
+  }
+  if (/^[0-9]+$/.test(text)) {
+    const row = select.rows[Number(text) - 1];
+    return row ? { done: 'chosen', row } : null;
+  }
+  const free = select.rows.find((row) => row.id === WRITE_MY_OWN);
+  return free ? { done: 'chosen', row: free, text } : null;
+}
+
+/**
+ * Several rows from one typed line — R93.
+ *
+ * Here rather than in the setup walk because R83's rule is that choosing is
+ * this file's job, and a second parser for "1, 3" living next to the first
+ * would be the drift that rule exists to prevent. No free text: a question with
+ * more than one answer has no "write my own" row, since the rows are the
+ * choices and not a guess at them.
+ *
+ * Returns an empty array for a line that settles nothing, so the caller asks
+ * again. A number naming no row makes the whole line nothing rather than
+ * silently choosing the rest: somebody who typed `1 2 9` meant three, and
+ * giving them two of them is a wrong answer wearing a right one's clothes.
+ */
+export function pickManyFromLine(select, typed) {
+  const text = String(typed ?? '').trim();
+  if (!text) {
+    return [];
+  }
+  const wanted = text.split(/[\s,]+/).filter(Boolean);
+  const picked = [];
+  for (const part of wanted) {
+    if (!/^[0-9]+$/.test(part)) {
+      return [];
+    }
+    const row = select.rows[Number(part) - 1];
+    if (!row) {
+      return [];
+    }
+    if (!picked.includes(row)) {
+      picked.push(row);
+    }
+  }
+  return picked;
+}

package/runner/session-store.mjs

@@ -0,0 +1,78 @@
+// Where the CLI remembers who you are — R81.
+//
+// One file, `~/.cawdev/session.json`, mode 0600, holding the session cookies
+// the platform handed back after somebody approved a sign-in in their browser.
+// **What is stored is a person's session and nothing else**: no password ever
+// reaches this process, and the daemon's own token is not in here — R52's rule
+// that a run's credential can never be borrowed for a decision is exactly why
+// these two are different files.
+//
+// Keyed by URL, because one machine can point at more than one cawdev and
+// reusing a cookie across instances is either a 401 or, worse, not one.
+//
+// Zero dependencies, like everything in tools/.
+
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** Beside the sockets: one directory a person can chmod, back up, or delete. */
+export function sessionFile() {
+  return join(homedir(), '.cawdev', 'session.json');
+}
+
+function key(url) {
+  return String(url).replace(/\/+$/, '');
+}
+
+async function readAll() {
+  try {
+    const parsed = JSON.parse(await readFile(sessionFile(), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    // No file, unreadable, or half-written. None of the three is worth an
+    // error: the answer to all of them is "you are not signed in yet".
+    return {};
+  }
+}
+
+/** What was stored for one instance, or null. */
+export async function loadSession(url) {
+  const stored = (await readAll())[key(url)];
+  if (!stored?.cookies || !stored.email) {
+    return null;
+  }
+  return { email: stored.email, cookies: new Map(Object.entries(stored.cookies)) };
+}
+
+/**
+ * Remember a session for next time.
+ *
+ * The directory is created 0700 and the file forced to 0600 **after** writing:
+ * `writeFile`'s mode is masked by the process umask, so asking for 0600 and
+ * getting 0644 is the normal outcome rather than the unusual one, and a
+ * world-readable session cookie is the whole thing this file must not be.
+ */
+export async function saveSession(url, { email, cookies }) {
+  const all = await readAll();
+  all[key(url)] = {
+    email,
+    cookies: Object.fromEntries(cookies instanceof Map ? cookies : Object.entries(cookies ?? {})),
+    savedAt: new Date().toISOString(),
+  };
+  await mkdir(dirname(sessionFile()), { recursive: true, mode: 0o700 });
+  await writeFile(sessionFile(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+  await chmod(sessionFile(), 0o600).catch(() => undefined);
+}
+
+/** Forget one instance. Signing out, and what a dead cookie earns. */
+export async function clearSession(url) {
+  const all = await readAll();
+  if (!(key(url) in all)) {
+    return;
+  }
+  delete all[key(url)];
+  await mkdir(dirname(sessionFile()), { recursive: true, mode: 0o700 });
+  await writeFile(sessionFile(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+  await chmod(sessionFile(), 0o600).catch(() => undefined);
+}