ccdeck 3.29.11 → 3.30.0

package/bin/cli/screen.js

@@ -0,0 +1,166 @@
+// The boot's terminal: the palette, the glyphs, the cursor, the status rows,
+// the wordmark and the spinner — everything bin/deck.js draws with.
+//
+// Lifted out of deck.js, where it was a block in the middle of the boot. The
+// answers are the same ones asked of the same environment, only asked when this
+// module loads instead of halfway down that file; nothing here has a side effect
+// until the boot calls takeCursor, at the point where the block used to hide it.
+import { pathToFileURL } from "node:url";
+import { dieOfSignal } from "../../src/server/supervisor.mjs";
+import {
+  CURSOR_HIDE, CURSOR_SHOW, colorProfile, elapsedSuffix, fit, glyphs, labelColumn, link, motionOK,
+  palette, spinnerFrames, statusLine, supportsHyperlinks, termColumns, unicodeOK, visibleWidth,
+} from "../../src/server/term.mjs";
+import { wordmark } from "../../src/server/wordmark.mjs";
+import { PKG_VERSION } from "./package.js";
+
+// ── the terminal we are printing into ─────────────────────────────────────────
+// Asked once, degraded from there — see src/server/term.mjs, which is where all
+// of this is decided and asserted. Below this point the deck writes no escape of
+// its own: colour comes from `P`, glyphs from `G`, layout from statusLine. That
+// is what makes NO_COLOR, a pipe, a CI log and a legacy Windows console one
+// question rather than thirty separate ones nobody remembers to ask.
+export const tty = Boolean(process.stdout.isTTY);
+export const PROFILE = colorProfile({ isTTY: tty });
+export const P = palette(PROFILE);
+export const UNICODE = unicodeOK();
+export const G = glyphs(UNICODE);
+export const LINKS = supportsHyperlinks({ profile: PROFILE });
+// The terminal's prefers-reduced-motion: nothing sleeps, spins or repaints in a
+// pipe, under CI, or with NO_COLOR set.
+export const MOTION = motionOK({ isTTY: tty, profile: PROFILE });
+export const write = (s) => process.stdout.write(s);
+// Read per line, never cached: a terminal can be resized while the deck runs,
+// and the pulse below is still on screen hours later.
+export const cols = () => termColumns(process.stdout);
+export const sleep = ms => new Promise(r => setTimeout(r, ms));
+export const fileLink = (path) => link(path, pathToFileURL(path).href, LINKS);
+
+// ── the cursor ────────────────────────────────────────────────────────────────
+// Hidden for as long as anything of ours is moving — the reveal, the spinner,
+// the pulse — and put back on every way out of this process: the ordinary exit,
+// all three signals, and an uncaught throw, which reaches 'exit' after Node has
+// printed it. Half of this is worse than none: a deck that dies with the cursor
+// hidden leaves the user's shell with no cursor and nothing to do about it but
+// `reset`.
+let cursorHidden = false;
+export const showCursor = () => {
+  if (!cursorHidden) return;
+  cursorHidden = false;
+  try { write(CURSOR_SHOW); } catch { /* stdout is gone; nothing left to restore */ }
+};
+/**
+ * Hide the cursor, if anything is going to move, and arm every way of putting
+ * it back. Called once, by the boot, at the point it starts drawing.
+ */
+export function takeCursor() {
+  if (MOTION) { cursorHidden = true; write(CURSOR_HIDE); }
+  process.on("exit", showCursor);
+  // SIGHUP is the one signal this process does not otherwise handle, so its
+  // default action would end us before 'exit' could run. Handled only to put the
+  // cursor back and then die of it exactly as before — the supervisor reads the
+  // signal, not an exit code.
+  process.on("SIGHUP", () => { showCursor(); dieOfSignal("SIGHUP"); });
+}
+
+// ── rows ──────────────────────────────────────────────────────────────────────
+// The status column is computed from the longest label. It used to be counted
+// into each string as trailing spaces, so any new row, or any label a character
+// longer, silently broke the alignment of every other one.
+const LABELS = [
+  "workspace", "Claude hooks", "Codex sessions", "Codex hooks", "claude-swap", "accounts",
+  "ccusage", "update", "name", "server ready", "log", "unknown option",
+  "missing value",
+];
+const LABEL_W = labelColumn(LABELS);
+
+export function row({ mark = " ", tone = P.ok, label = "", detail = "", detailTone = P.muted, keep = false }) {
+  return statusLine({
+    mark, label, detail, keep, labelWidth: LABEL_W, columns: cols(), ellipsis: G.ellipsis,
+    paint: {
+      mark: (s) => `${tone}${s}${P.reset}`,
+      detail: (s) => `${detailTone}${s}${P.reset}`,
+    },
+  }) + "\n";
+}
+
+// ── the wordmark ──────────────────────────────────────────────────────────────
+
+/**
+ * Hold anything else that wants to speak until the art is finished.
+ *
+ * #742, found while watching a first run through a pty: the startup jobs run
+ * UNDER the reveal on purpose, and one of them failing writes to console.error
+ * the moment it fails — which put
+ *
+ *     ccdeck ccusage: install failed: npm install ccusage failed: spawn npm ENOENT
+ *
+ * between the second and third rows of the logo. A wordmark with a stack of
+ * someone else's bad news through the middle of it is the first thing a new
+ * user sees, and it reads as a crash rather than as a note.
+ *
+ * The window is the reveal and nothing else — about 180ms — so at worst a
+ * message arrives a fifth of a second later than it would have, on the one
+ * stretch of the boot where there is nowhere for it to go. Restored in a
+ * `finally`, so a throw inside the reveal cannot leave the process mute.
+ */
+function holdConsole() {
+  const held = [];
+  const real = { warn: console.warn, error: console.error, log: console.log };
+  for (const k of Object.keys(real)) console[k] = (...args) => { held.push([k, args]); };
+  return () => {
+    Object.assign(console, real);
+    for (const [k, args] of held) real[k](...args);
+  };
+}
+
+export async function printBanner() {
+  const { lines } = wordmark({ columns: cols(), version: PKG_VERSION, profile: PROFILE, unicode: UNICODE, pal: P });
+  const release = holdConsole();
+  try {
+    for (const line of lines) {
+      write(line + "\n");
+      // A reveal, not a wait. The once-per-session work is already running under
+      // it (see startupWork), so the art costs the boot nothing and the deck is
+      // ready about when the last row lands. What used to be here — 560ms of
+      // spinner at "loading…" before a single art line — was dead time in a tool
+      // whose documented entry point is `npx ccdeck`.
+      if (MOTION && line) await sleep(45);
+    }
+  } finally {
+    release();
+  }
+}
+
+// ── a step, with a spinner only if it is slow enough to need one ──────────────
+// The interval's first frame is 80ms away, so anything already settled when we
+// get here paints nothing at all and the row below is the only trace of it.
+
+export async function step(label, work) {
+  if (!MOTION) return work;
+  const frames = spinnerFrames(UNICODE);
+  // Kept inside the terminal: a label that wraps is a label the \r below can
+  // only half erase, and what is left of it stays under the row that follows.
+  // Six columns for the indent and the spinner, four more so the elapsed
+  // seconds have somewhere to go without pushing the label off the edge.
+  const text = fit(label, cols() - 10, G.ellipsis);
+  const started = Date.now();
+  let i = 0;
+  let widest = 0;
+  const iv = setInterval(() => {
+    const line = `  ${P.accent}${frames[i++ % frames.length]}${P.reset}  ${P.muted}${text}${elapsedSuffix(Date.now() - started)}${P.reset}`;
+    widest = Math.max(widest, visibleWidth(line));
+    write(`\r${line}`);
+  }, 80);
+  try {
+    return await work;
+  } finally {
+    clearInterval(iv);
+    // Cleared rather than overwritten: the row that follows is a different
+    // length, and relying on it to be the longer of the two is how a spinner
+    // leaves its own tail on screen. Measured rather than computed, because the
+    // line grows when the elapsed seconds appear and again when they reach two
+    // digits. Nothing to clear if it never painted.
+    if (i) write("\r" + " ".repeat(widest) + "\r");
+  }
+}

package/bin/cli/second-start.js

@@ -0,0 +1,120 @@
+// A second start, settled: attach to the deck that is already up, yield to one
+// that came up while this one was coming back, or stop what this start
+// replaces and go on.
+//
+// A bare `ccdeck` typed beside a deck that is already running used to build a
+// second everything on a random port, and neither half mentioned the other.
+// Then it attached only to a deck of exactly its own shape and built a second
+// one beside anything else — a different flag, an older version, or a login
+// item whose environment decided `codex` or the log path differently from the
+// shell's. src/server/running-deck.mjs carries the whole argument, the registry
+// read, the handshake and the rule; this is where the answer is acted on, and
+// bin/deck.js is where — and when — it is asked.
+//
+// A RESPAWN IS ASKED TOO, and answers differently. A restart is THIS deck
+// coming back, so there is nothing to attach to — but in the gap a crash
+// leaves, a `ccdeck` typed by hand finds no deck and starts one, and the
+// respawn that followed used to take a random port beside it. Now it finds
+// that deck and exits 0, and the supervisor, reading a clean exit, ends too.
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { isPortValue } from "../../src/server/args.mjs";
+import { PRODUCT } from "../../src/server/brand.mjs";
+import { liveDecks, olderVersion, secondStart, versionNote } from "../../src/server/running-deck.mjs";
+import { link } from "../../src/server/term.mjs";
+import { COMMAND, PKG_ROOT, PKG_VERSION } from "./package.js";
+import { G, LINKS, P, sleep, write } from "./screen.js";
+import { reportIncompleteFlags, reportUnknownFlags } from "./startup.js";
+
+/**
+ * Ask the rule, and do what it says. Resolves to the exit code when this start
+ * ends here — a yield, or an attach — having said why, and to null when it is
+ * to go on and boot. Nothing here exits the process: bin/deck.js does, so every
+ * way out is one its exit handlers already cover (#980).
+ */
+export async function settleSecondStart({ flags, workspace, persist, wantCodex, wantClaude, codexHome, openBrowser, RESPAWN }) {
+  // `--port` alone, not AGENT_DAG_PORT: the variable is how somebody RUNS a
+  // deck rather than which one they mean — the line `--stop` draws in
+  // bin/cli/one-shot.js.
+  const askedPort = flags.port != null && isPortValue(flags.port) ? Number(flags.port) : null;
+  const plan = secondStart({
+    live: await liveDecks().catch(() => []),
+    want: { workspace, persist, codex: wantCodex, claude: wantClaude, codexHome },
+    port: askedPort,
+    ours: PKG_VERSION,
+    fresh: flags.new === true,
+    respawn: RESPAWN,
+  });
+  if (plan.act === "yield") {
+    console.error(`${PRODUCT}: a deck started on ${plan.deck.port} while this one was coming back ${G.dash} leaving it to that one.`);
+    return 0;
+  }
+  // THE NEWEST START WINS. What is stopped here is either the deck this start
+  // replaces or, on an attach, a second deck left over from before this rule —
+  // the duplicate the rule exists to end. Each one is said, with why, because a
+  // deck that vanishes without a word is a mystery of its own.
+  if (plan.stop.length) {
+    const { stopDeck } = await import(pathToFileURL(join(PKG_ROOT, "src/server/stop-deck.mjs")).href);
+    for (const d of plan.stop) {
+      const why = plan.act === "replace" && flags.new === true
+        ? "you asked for a fresh one"
+        : olderVersion(d.version, PKG_VERSION)
+          ? (d.version ? `it was v${d.version}` : "it was an older version")
+          : plan.act === "attach" ? "it was a second deck" : "it was started with different settings";
+      const out = await stopDeck(d).catch(() => ({ ok: false, reason: "unreachable" }));
+      write(out.ok
+        ? `\n  ${P.ok}${G.ok}${P.reset}  stopped the deck on ${d.port}${P.muted}  ${G.bullet}  pid ${d.pid}  ${G.bullet}  ${why}${P.reset}\n`
+        : `\n  ${P.warn}${G.warn}  could not stop the deck on ${d.port} (pid ${d.pid}) ${G.dash} ${out.reason ?? out.how}${P.reset}\n`);
+    }
+  }
+  if (plan.act === "attach") {
+    const live = plan.deck;
+    const liveUrl = `http://127.0.0.1:${live.port}`;
+    const note = versionNote(live.version, PKG_VERSION);
+    // Not the startup report's rows. That report has a label column because it
+    // has twelve lines to align; this has two, and borrowing the column would
+    // indent a three-line message behind a gutter sized for "Codex sessions".
+    //
+    // The version chunk is dropped rather than printed as "v?" when the running
+    // deck is too old to report one — see versionNote, which says nothing in the
+    // same case for the same reason.
+    const ident = [live.version ? `v${live.version}` : "", `pid ${live.pid}`]
+      .filter(Boolean).join(`  ${G.bullet}  `);
+    write(`\n  ${P.ok}${G.ok}${P.reset}  deck already running${P.muted}  ${G.bullet}  ${ident}${P.reset}\n`);
+    // Its own line, always. The URL is the one detail an ellipsis would destroy
+    // — half an address is not a shorter address — and this message has no
+    // report to hand it to. Same rule as statusLine's `keep`.
+    write(`     ${P.accent}${P.bold}${link(liveUrl, liveUrl, LINKS)}${P.reset}\n`);
+    if (note) write(`  ${P.warn}${G.warn}  ${note}${P.reset}\n`);
+    // THE TYPO'S WARNING, on the path that has no startup report to carry it.
+    //
+    // The gate used to answer `true` for these two so the report would
+    // run and print them, and that is how `ccdeck --stpo` — a misspelling of
+    // the flag that STOPS a deck — came to build a second one. The warning was
+    // the requirement; the extra process never was. Printed here, in the same
+    // rows the report uses, so nothing is lost and nothing is started.
+    reportUnknownFlags(flags.unknown);
+    reportIncompleteFlags(flags.incomplete);
+    // The line that says a second deck was NOT started. Without it the command
+    // looks like it did nothing at all, which is the other way to be confusing
+    // about this — and it names the flag for the person who wanted a fresh one.
+    write(`\n  ${P.muted}${G.dash}  no second deck was started ${G.dash} \`${COMMAND} --new\` replaces it with a fresh one${P.reset}\n`);
+    if (openBrowser) {
+      write(`\n  ${P.ok}${P.bold}${G.play}  opening browser${G.ellipsis}${P.reset}\n\n`);
+      try {
+        const { openUrl, LAUNCH_GRACE_MS } = await import(pathToFileURL(join(PKG_ROOT, "src/server/open-url.mjs")).href);
+        openUrl(liveUrl);
+        // Held for exactly as long as openUrl needs to fall through to its next
+        // launcher. Every child it spawns is unref'd, so an immediate exit ends
+        // this process before a missing xdg-open has been answered by gio — and
+        // then no browser opens and nothing says why. The boot path never had
+        // to think about this because it stays alive forever.
+        await sleep(LAUNCH_GRACE_MS);
+      } catch { /* the URL is on screen; it can be clicked or pasted */ }
+    } else {
+      write("\n");
+    }
+    return 0;
+  }
+  return null;
+}