ccdeck 3.29.11 → 3.30.0

package/src/server/term.mjs

@@ -17,6 +17,10 @@
 // The two exceptions are the cursor constants, which are strings the caller
 // writes, because who restores the cursor and when is a lifecycle question and
 // belongs with the lifecycle.
+//
+// What the deck says with these answers lives beside them: the drawn wordmark
+// the boot opens with in wordmark.mjs, and the pulse line it leaves on screen
+// in pulse-line.mjs.
 
 // ── colour profile ───────────────────────────────────────────────────────────
 //
@@ -104,8 +108,8 @@ export function fg([r, g, b], profile, fallback) {
 }
 
 // The canvas' own tokens (src/web/styles.css), so the terminal and the page are
-// one product rather than two. The ramp is the wordmark's vertical gradient:
-// lit at the top, settling into the deeper tone at the baseline.
+// one product rather than two. The ramp is the wordmark's vertical gradient
+// (wordmark.mjs): lit at the top, settling into the deeper tone at the baseline.
 const BRAND = {
   accentSoft: [[186, 230, 253], "\x1b[96m"],
   accent:     [[125, 211, 252], "\x1b[96m"],
@@ -233,8 +237,9 @@ export const SPINNER_ELAPSED_AFTER_MS = 3_000;
  *
  * Whole seconds, floored, and never a tenth: a number that changes ten times a
  * second is a second spinner rather than an answer about the first one. Here
- * rather than in bin/deck.js because that file runs a deck when it is imported,
- * and this is the one part of `step` worth holding still in a test.
+ * rather than beside `step` in bin/cli/screen.js, which asks the real terminal
+ * its questions the moment it is imported, and this is the one part of `step`
+ * worth holding still in a test.
  */
 export function elapsedSuffix(ms, after = SPINNER_ELAPSED_AFTER_MS) {
   return ms < after ? "" : `  ${Math.floor(ms / 1000)}s`;
@@ -432,255 +437,12 @@ export function statusLine({
   return `${pad}${paintMark(mark)}  ${paintLabel(padded)}  ${paintDetail(fitted)}`;
 }
 
-// ── wordmark ─────────────────────────────────────────────────────────────────
-//
-// Drawn, not pasted out of a figlet font — six letters on a 4×6 pixel grid,
-// printed two pixel rows to a text row with the half-block characters, which is
-// what gives it a lowercase with real ascenders in three lines instead of six.
-// The old banner said `agents-deck`, a name the repo, the command, the README
-// and the docs stopped using; this one says what the product is called.
-
-const LETTERS = {
-  c: ["....", "....", ".###", "#...", "#...", ".###"],
-  d: ["...#", "...#", ".###", "#..#", "#..#", ".###"],
-  e: ["....", "....", ".###", "####", "#...", ".###"],
-  k: ["#...", "#...", "#.##", "##..", "#.#.", "#..#"],
-};
-
-/** Two pixel rows into one text row: ▀ upper only, ▄ lower only, █ both. */
-function squash(top, bottom) {
-  let out = "";
-  for (let i = 0; i < top.length; i++) {
-    const t = top[i] === "#";
-    const b = bottom[i] === "#";
-    out += t && b ? "█" : t ? "▀" : b ? "▄" : " ";
-  }
-  return out;
-}
-
-function renderWord(word) {
-  const rows = ["", "", ""];
-  for (const [n, ch] of [...word].entries()) {
-    const px = LETTERS[ch];
-    for (let r = 0; r < 3; r++) rows[r] += (n ? " " : "") + squash(px[r * 2], px[r * 2 + 1]);
-  }
-  return rows.map((r) => r.replace(/\s+$/, ""));
-}
-
-/** The drawn mark itself, three text rows of half-blocks.
- *
- *  Exported for one reader, and it is a test rather than a caller (#383). This
- *  is the ONLY place the art's true width can be measured: `renderWord` trims
- *  each row's trailing blanks, so the rows are not all the same length, and the
- *  arithmetic in WORDMARK_WIDTH below is a hand-computed prediction of the
- *  widest of them. Nothing in the banner path compares the two — `wordmark()`
- *  gates on WORDMARK_WIDTH and then prints THESE lines — so an under-counting
- *  width lets the art render into a terminal too narrow to hold it and the
- *  three rows wrap into six. See wordmark-art-width.test.ts, which is the
- *  comparison this export exists to make possible. */
-export const WORDMARK_LINES = renderWord("ccdeck");
-/** 29 columns of art, plus the two-space indent every other line uses. */
-export const WORDMARK_WIDTH = 2 + LETTERS.c[0].length * 6 + 5;
-
-/**
- * The tagline, longest version that fits — the name and version are the part
- * that must survive, the rest is context.
- *
- * `prefix` is how many columns are already spent on the line the tagline lands
- * on, and it is a parameter because the three layouts below do not agree on it
- * (#383). In the full banner the tagline gets a line of its own behind a
- * two-space indent; in the compact and plain ones it shares the line with the
- * product name, which costs eight or nine columns more. This budget was
- * hard-coded at 2 for all three, so between 21 and 31 columns — the widths where
- * the compact form is chosen and the medium tagline still looks affordable —
- * the banner printed a 36-column line into a terminal that could not hold it and
- * the first thing a user saw wrapped. `columns - 1` keeps the last cell empty,
- * because a line ending exactly at the right margin makes some terminals wrap
- * anyway.
- */
-function tagline(version, columns, bullet, prefix) {
-  const v = `v${version}`;
-  const options = [
-    `${v} ${bullet} live agent DAG ${bullet} Claude Code + Codex`,
-    `${v} ${bullet} live agent DAG`,
-    v,
-  ];
-  return options.find((o) => o.length + prefix <= columns - 1) ?? v;
-}
-
-// What each layout spends before the tagline starts, counted off the strings
-// built in `wordmark` below: "  ccdeck " for plain, "  ccdeck  " for compact,
-// and the bare two-space indent for the full banner's own tagline line.
-const PLAIN_PREFIX_W   = "  ccdeck ".length;
-const COMPACT_PREFIX_W = "  ccdeck  ".length;
-const TAG_INDENT_W     = "  ".length;
-
-/**
- * The wordmark, in the largest form this terminal can hold.
- *
- *   "full"    — the drawn mark, three rows, on a vertical gradient
- *   "compact" — the name in the accent, for a terminal too narrow for the art
- *               or a console without the half-block glyphs
- *   "plain"   — no escapes at all: a pipe, a CI log, NO_COLOR
- *
- * Returns the lines to print, blank lines included, so the caller writes them
- * and nothing else decides how much air the banner gets.
- */
-export function wordmark({
-  columns = 80, version = "0.0.0", profile = "none", unicode = true, pal = palette(profile),
-} = {}) {
-  const g = glyphs(unicode);
-  // Each layout asks for its own tagline, because each leaves it a different
-  // amount of room — see the prefix constants above.
-  const tag = (prefix) => tagline(version, columns, g.bullet, prefix);
-
-  if (profile === "none") return { kind: "plain", lines: ["", `  ccdeck ${tag(PLAIN_PREFIX_W)}`, ""] };
-  if (!unicode || columns < WORDMARK_WIDTH + 1) {
-    return { kind: "compact", lines: ["", `  ${pal.bold}${pal.accent}ccdeck${pal.reset}  ${pal.muted}${tag(COMPACT_PREFIX_W)}${pal.reset}`, ""] };
-  }
-
-  const ramp = [pal.accentSoft, pal.accent, pal.accentDeep];
-  return {
-    kind: "full",
-    lines: [
-      "",
-      ...WORDMARK_LINES.map((l, i) => `  ${ramp[i]}${l}${pal.reset}`),
-      "",
-      `  ${pal.muted}${tag(TAG_INDENT_W)}${pal.reset}`,
-      "",
-    ],
-  };
-}
-
-// ── the pulse line ───────────────────────────────────────────────────────────
-
-/**
- * The one line that stays on screen for hours, sized to the terminal it is on.
- *
- * It is redrawn over itself with `\r`, so both messages are padded to one width
- * — the shorter has to cover the longer — and that width is clamped to the real
- * terminal: at 40 columns the old 58-character message wrapped, after which the
- * `\r` only ever reached the second row and every repaint left the first one
- * behind. A deck no hook can find is not listening in any sense the user cares
- * about, which is why that state has a message here at all.
- *
- * `claude` is what makes that last sentence conditional. A deck watching only
- * Codex is not waiting on a hook: startCodexWatcher is started by startServer
- * and never consults the discovery file, and writesCodexLog keeps a deck with no
- * record on disk writing its log. Capture and persistence both work perfectly
- * there, while this line used to repaint "hooks cannot find this deck" every
- * 800ms, forever (#404) — a permanent alarm about a mechanism that deck does not
- * use. The one-time report at boot still says what IS lost; see
- * unregisteredDetail.
- */
-export function pulseText({
-  registered = true, claude = true, columns = 80, unicode = true, indent = 2, busy = null,
-} = {}) {
-  const g = glyphs(unicode);
-  const room = Math.max(4, columns - indent - 3 - 1);
-  const pick = (options) => options.find((o) => o.length <= room) ?? options[options.length - 1].slice(0, room);
-
-  const rest = pick([`listening ${g.dash} Ctrl+C to stop`, "listening"]);
-  const bad = pick([
-    `listening, but not registered ${g.dash} hooks cannot find this deck`,
-    `not registered ${g.dash} hooks cannot find this deck`,
-    "not registered",
-  ]);
-  // Both branches are still measured, registered or not, because the line is
-  // redrawn over itself and the shorter message has to cover the longer one on
-  // the beat after a deck loses its registration.
-  //
-  // The width is deliberately computed from the two FIXED messages only. `busy`
-  // comes and goes on a single boot — an install starts, the line names it, the
-  // install ends and the line goes back to Ctrl+C — so a width that grew to fit
-  // the label would have to shrink again afterwards, and the shorter line would
-  // leave the tail of the longer one on screen. Instead the label is shown only
-  // where it already fits — 60 columns and wider, measured — and below that the
-  // line says the true thing it has always said.
-  const width = Math.min(room, Math.max(rest.length, bad.length));
-  // What is still happening, rather than what is always true. `Ctrl+C to stop`
-  // is the right thing to say to somebody with nothing left to wait for, and
-  // the wrong thing to say to somebody watching an install.
-  const label = typeof busy === "string" && busy.trim() ? busy.trim() : null;
-  const working = label ? `listening ${g.bullet} ${label}` : null;
-  const ok = working && working.length <= width ? working : rest;
-  return (registered || !claude ? ok : bad).padEnd(width);
-}
-
-/**
- * Whether the line has anything left to say by moving.
- *
- * #742. The dot alternated green and grey every 800ms for as long as the deck
- * ran, and a blinking indicator beside a status line is the vocabulary of
- * "working on it" — so a boot that had finished in a second read as one that
- * never finished, and people said so. The deck's own web UI already retired
- * this once: the pill goes quiet at rest (#720). The terminal did not.
- *
- * Motion is now spent on the two states where something is genuinely
- * outstanding — a deck no hook can find, and a background job still running —
- * and nowhere else. At rest the dot is painted once, in the healthy colour, and
- * left alone. Movement then means something changed, which is the only thing
- * movement should ever mean on a line somebody leaves open for hours.
- */
-export function pulseMoves({ registered = true, claude = true, busy = null } = {}) {
-  if (!registered && claude) return true;
-  return typeof busy === "string" && busy.trim() !== "";
-}
-
-/**
- * Whether the dot is lit on this beat.
- *
- * `"on"` on every beat of a deck at rest, which is what makes the line still:
- * bin/deck.js paints a beat only when the frame differs from the one already on
- * screen, so a dot that is always lit is a line written once and then left
- * alone. Alternating is reserved for the states pulseMoves admits.
- *
- * The beat is a parameter rather than counted here so this is a function of its
- * inputs and nothing else — and so a test can ask what the twentieth beat of an
- * idle deck looks like without waiting sixteen seconds for it.
- */
-export function pulseDot(beat, { registered = true, claude = true, busy = null } = {}) {
-  if (!pulseMoves({ registered, claude, busy })) return "on";
-  return beat % 2 === 0 ? "on" : "off";
-}
-
-/**
- * The second line of the "not registered" report, which bin/deck.js prints once
- * per change of state rather than every beat.
- *
- * What a missing discovery file costs is not the same on the two capture paths,
- * and the old sentence — "hooks find this deck through <file>, so until that
- * file exists no events arrive" — stated the Claude Code answer as if it were
- * both. On a Codex-only deck it is false twice over: no hook is looking for this
- * deck, and events do keep arriving, because the rollout watcher reads the files
- * directly. What that deck really loses is the writer election in
- * log-writer.mjs, which is how several decks tailing one rollout agree on which
- * of them appends it to a shared events log. A deck with no record on disk is
- * assumed to be writing, so nothing is dropped — the log can gain the same line
- * twice instead.
- *
- * @param file the discovery file that could not be written.
- * @param claude whether this deck is watching Claude Code at all.
- * @param dash the em dash, or the ASCII stand-in on a console that cannot draw
- *   one (#797). A parameter for the same reason `renameNotice` takes one: this
- *   module's own header says "every glyph the deck prints — punctuation
- *   included, since an em dash is as absent from CP437 as a check mark — comes
- *   from one of them", and this sentence had it hardcoded. On a legacy cmd.exe
- *   or the Linux virtual console the reader got a box in the middle of the one
- *   line explaining why no events are arriving.
- */
-export function unregisteredDetail({ file, claude = true, dash = "—" }) {
-  if (claude) {
-    return `Claude Code hooks find this deck through ${file}, so until that file exists no Claude Code events arrive.`;
-  }
-  return `Codex capture does not use ${file} ${dash} the deck tails the rollout files itself ${dash} so events still arrive. Only decks sharing one events log need it, to agree on which of them records.`;
-}
-
 // ── cursor ───────────────────────────────────────────────────────────────────
 //
 // Strings rather than writers: hiding the cursor is trivial and restoring it is
 // not — it has to happen on the normal exit, on SIGINT/SIGTERM/SIGHUP and after
 // an uncaught throw, and getting that half-right leaves the user's shell with
-// no cursor after the deck is gone. The lifecycle owns it; see bin/deck.js.
+// no cursor after the deck is gone. The lifecycle owns it; see takeCursor in
+// bin/cli/screen.js.
 export const CURSOR_HIDE = "\x1b[?25l";
 export const CURSOR_SHOW = "\x1b[?25h";