@mnemahq/cli 0.4.0 → 0.7.0

package/src/paging.mjs

@@ -0,0 +1,50 @@
+/**
+ * Stop reading when the caller has enough (t-630).
+ *
+ * ⭐ `--limit` DID NOT LIMIT ANYTHING. Every read command called `.all()`, and
+ * `paginate()` follows `next_cursor` to exhaustion — `limit` is only the page-SIZE
+ * query parameter. So a smaller `--limit` made the CLI do strictly more work:
+ *
+ *     mnema docs --limit 5
+ *       /api/public/v1/docs?limit=5
+ *       /api/public/v1/docs?limit=5&cursor=59e921a0-…
+ *       /api/public/v1/docs?limit=5&cursor=92360dfa-…
+ *       …and on, and on
+ *
+ * Measured against prod: it blew past a 10-request cap and was still walking the
+ * cursor chain. `mnema docs --limit 5` never returned — it was the command that
+ * hung this branch's own baseline capture — and had it finished it would have
+ * printed EVERY document, because the header counts the rows it collected.
+ *
+ * ⚠️ SO THE PRINTED COUNT CHANGES with this fix, and that is the point: it used to
+ * be "everything you have", now it is "what you asked for".
+ *
+ * `Paginated<T>` is an AsyncIterable, so stopping is simply a `break` — the
+ * generator is closed and the next page is never requested.
+ */
+
+/**
+ * Read at most `limit` items.
+ *
+ * Returns `more` so callers can say that the list was cut. A row count that
+ * silently means "there might be others" is the same lie `ask` and `graph` used to
+ * tell with their headers, and it is worth exactly as little.
+ */
+export async function take(paginated, limit) {
+  // ⚠️ `>= 0`, NOT `> 0`. With `> 0` a limit of ZERO fell through to Infinity and
+  // fetched the entire workspace — the exact bug this module exists to fix, hiding
+  // inside the fix, and it made the `max === 0` guard below unreachable. An
+  // explicit 0 means zero rows; only undefined, NaN or a negative is "unbounded".
+  const max = Number.isFinite(limit) && limit >= 0 ? Math.floor(limit) : Infinity;
+  const rows = [];
+  if (max === 0) return { rows, more: false };
+
+  for await (const item of paginated) {
+    rows.push(item);
+    // Read ONE past the limit rather than stopping exactly on it: that extra item
+    // is the only way to distinguish "exactly this many exist" from "there are
+    // more", and getting it wrong means the footer either lies or never appears.
+    if (rows.length > max) return { rows: rows.slice(0, max), more: true };
+  }
+  return { rows, more: false };
+}

package/src/read-commands.mjs

@@ -1,5 +1,5 @@
 /**
- * The read commands — tasks, docs, projects, ask, graph, briefing (t-624).
+ * The read commands — tasks, docs, projects, ask, graph, briefing (t-624, t-630).
  *
  * ⭐ EVERY ONE OF THESE IS A WRAPPER, NOT A CLIENT. They exist because t-623 put
  * the CLI on @mnemahq/sdk; each is four lines of SDK call plus formatting, and
@@ -16,12 +16,19 @@
  *             news. On a core build six of seven finding families cannot produce
  *             anything at all, and `coverage.notice` is the only thing that says so.
  *
+ * t-630 moved every heading, row and empty state onto render/layout.mjs so the
+ * grammar is one module's job rather than eleven call sites', and put `--limit`
+ * through take() so it stops the pagination instead of decorating it.
+ *
  * --json everywhere: a CLI you cannot pipe is half a CLI, and the SDK already
  * returns the shape worth emitting, so it costs one line each.
  */
 
 import { call, hasApiKey, canAuthenticate, renderError } from './client.mjs';
-import { c, truncate } from './util.mjs';
+import { take } from './paging.mjs';
+import { c, truncate, link, mark } from './util.mjs';
+import { heading, empty, rows, more, copyable } from './render/layout.mjs';
+import { pick } from './render/pick.mjs';
 
 /** Machine output is the whole object; humans get the formatted view. */
 function emit(flags, value, render) {
@@ -35,28 +42,34 @@ async function guard(workspaceId) {
   process.exit(1);
 }
 
-// ⚠️ The old local helper measured `.length` — UTF-16 code units — so a CJK title
-// or an emoji made the column visibly ragged. truncate() from the theme measures
-// terminal columns instead.
-const trunc = (s, n) => truncate(s ?? '', n);
+const limitOf = (flags, fallback) => Number(flags.limit) || fallback;
+
+/** The short id a human actually reads back to you. */
+const shortId = (row) => row.publicId || String(row.id).slice(0, 8);
 
 // ── tasks ─────────────────────────────────────────────────────────────────────
 export async function cmdTasks(flags, ctx) {
   await guard(ctx.workspaceId);
-  const limit = Number(flags.limit) || 20;
+  const limit = limitOf(flags, 20);
   try {
-    const rows = await call(ctx, (m) => m.tasks.list({
+    const page = await call(ctx, (m) => take(m.tasks.list({
       limit,
       ...(flags.status ? { status: flags.status } : {}),
       ...(flags.project ? { project: flags.project } : {}),
-    }).all());
-    emit(flags, rows, () => {
-      if (!rows.length) return console.log(c.dim('No tasks match.'));
-      console.log(c.bold(`${rows.length} task(s)`));
-      for (const t of rows) {
-        const id = (t.publicId || t.id.slice(0, 8)).padEnd(8);
-        console.log(`  ${c.cyan(id)} ${String(t.status).padEnd(12)} ${c.dim(String(t.priority).padEnd(8))} ${trunc(t.title, 70)}`);
+    }), limit));
+    emit(flags, page.rows, () => {
+      heading('Tasks', page.rows.length);
+      if (!page.rows.length) {
+        return empty(
+          flags.status || flags.project ? 'No tasks match those filters.' : 'No tasks yet.',
+          flags.status || flags.project ? 'Drop the filters to see the whole board.' : undefined,
+        );
       }
+      rows(page.rows.map((t) => ({
+        cells: [shortId(t), String(t.status), String(t.priority), t.title ?? ''],
+        style: [c.cyan, undefined, c.dim, undefined],
+      })));
+      more(page.more, `mnema tasks --limit ${limit * 2}`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'tasks' }); }
 }
@@ -66,14 +79,26 @@ export async function cmdNext(flags, ctx) {
   try {
     const t = await call(ctx, (m) => m.tasks.next());
     emit(flags, t, () => {
-      if (!t) return console.log(c.dim('Nothing queued — the board is clear.'));
-      console.log(`${c.bold(t.publicId || t.id)}  ${t.title}`);
-      if (t.description) console.log(c.dim(trunc(t.description.replace(/\s+/g, ' '), 300)));
-      // The branch name is the load-bearing part of this project's dev loop, so
-      // the CLI hands it over ready to paste rather than making it be derived.
+      heading('Next');
+      if (!t) return empty('Nothing queued — the board is clear.');
+      rows([{ cells: [shortId(t), t.title ?? ''], style: [c.cyan, undefined] }]);
+      if (t.description) {
+        console.log(c.dim(`  ${truncate(t.description.replace(/\s+/g, ' '), 300)}`));
+      }
+      // A real URL, so make it clickable where the terminal supports it. link()
+      // degrades to "label (url)" when colour is off, rather than emitting an OSC 8
+      // sequence into someone's pipe.
+      if (t.githubPrUrl) console.log(`  ${c.dim('pr:')} ${link(t.githubPrUrl, t.githubPrUrl)}`);
+      // ⚠️ THE BRANCH NAME IS THE LOAD-BEARING PART OF THIS PROJECT'S DEV LOOP —
+      // it is the only signal that needs no cooperation from anything else, and
+      // from it the hook links the session, the PR links the task and the board
+      // moves on its own. So it is printed PLAIN: no colour, no padding, no
+      // truncation, because a padded string carries invisible trailing whitespace
+      // into the clipboard and an escape sequence carries worse.
       if (t.publicId) {
-        const slug = t.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
-        console.log(`\n  ${c.dim('branch:')} git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
+        const slug = String(t.title ?? '').toLowerCase()
+          .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
+        copyable('branch:', `git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
       }
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'next' }); }
@@ -82,30 +107,59 @@ export async function cmdNext(flags, ctx) {
 // ── docs ──────────────────────────────────────────────────────────────────────
 export async function cmdDocs(flags, ctx) {
   await guard(ctx.workspaceId);
-  const limit = Number(flags.limit) || 20;
+  const limit = limitOf(flags, 20);
   try {
-    const rows = await call(ctx, (m) => m.docs.list({ limit }).all());
-    emit(flags, rows, () => {
-      if (!rows.length) return console.log(c.dim('No docs.'));
-      console.log(c.bold(`${rows.length} doc(s)`));
-      for (const d of rows) {
-        console.log(`  ${c.dim(d.id.slice(0, 8))}  ${trunc(d.title, 60).padEnd(60)} ${c.dim(String(d.updatedAt).slice(0, 10))}`);
-      }
+    const page = await call(ctx, (m) => take(m.docs.list({ limit }), limit));
+    emit(flags, page.rows, () => {
+      heading('Documents', page.rows.length);
+      if (!page.rows.length) return empty('No documents yet.', 'Docs you write in the app show up here.');
+      rows(page.rows.map((d) => ({
+        cells: [String(d.id).slice(0, 8), String(d.updatedAt).slice(0, 10), d.title ?? ''],
+        style: [c.dim, c.dim, undefined],
+      })));
+      more(page.more, `mnema docs --limit ${limit * 2}`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'docs' }); }
 }
 
 export async function cmdDoc(flags, ctx, rest) {
   await guard(ctx.workspaceId);
-  const id = rest[0];
-  if (!id) { console.error(c.red('Usage: mnema doc <id>')); process.exit(1); }
+  let id = rest[0];
+  // ⭐ OFFER, DO NOT DEMAND. With no id this printed a usage line, so the real
+  // workflow was: run `mnema docs`, read a truncated title, select eight hex
+  // characters with the mouse, paste them back. The list command already knows
+  // every id; asking the user to ferry one across is work the tool can do.
+  //
+  // ⚠️ Only when a human is actually there. pick() returns null on a non-TTY (and
+  // --json means a script is reading), so the usage error remains the answer for
+  // every non-interactive caller — no hanging on a stdin that will never speak.
+  // ⚠️ CHECK THE TERMINAL BEFORE THE NETWORK. Testing interactivity only inside
+  // pick() meant a piped `mnema doc` fetched fifty documents and then threw them
+  // away — a round trip, and a rate-limit slot, spent on a picker nobody can see.
+  const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+  if (!id && !flags.json && interactive) {
+    const page = await call(ctx, (m) => take(m.docs.list({ limit: 50 }), 50)).catch(() => null);
+    if (page?.rows.length) {
+      const chosen = await pick(
+        page.rows.map((d) => ({ label: `${d.title ?? '(untitled)'}  ${String(d.updatedAt).slice(0, 10)}` })),
+        { title: 'Which document?' },
+      );
+      if (chosen === null) return;
+      id = page.rows[chosen].id;
+    }
+  }
+  if (!id) {
+    console.error(c.red('Usage: mnema doc <id>'));
+    console.error(c.dim('  Run it without an id in a terminal to pick from a list.'));
+    process.exit(1);
+  }
   try {
     const d = await call(ctx, (m) => m.docs.get(id));
-    // Markdown goes to stdout unadorned so `mnema doc <id> > file.md` works and
-    // the heading is not silently baked into the file.
+    // ⚠️ MARKDOWN TO STDOUT, EVERYTHING ELSE TO STDERR, so `mnema doc <id> > f.md`
+    // gets the document alone and the heading is not silently baked into the file.
     emit(flags, d, () => {
-      console.error(c.bold(d.title));
-      console.error(c.dim(`${d.path} · updated ${String(d.updatedAt).slice(0, 10)}`));
+      console.error(c.bold(d.title ?? '(untitled)'));
+      console.error(c.dim(`${d.path ?? ''} · updated ${String(d.updatedAt).slice(0, 10)}`));
       if (d.markdown) console.log(d.markdown);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'doc' }); }
@@ -114,12 +168,17 @@ export async function cmdDoc(flags, ctx, rest) {
 // ── projects ──────────────────────────────────────────────────────────────────
 export async function cmdProjects(flags, ctx) {
   await guard(ctx.workspaceId);
+  const limit = limitOf(flags, 50);
   try {
-    const rows = await call(ctx, (m) => m.projects.list().all());
-    emit(flags, rows, () => {
-      if (!rows.length) return console.log(c.dim('No projects.'));
-      console.log(c.bold(`${rows.length} project(s)`));
-      for (const p of rows) console.log(`  ${c.dim(p.id.slice(0, 8))}  ${trunc(p.name, 50)}`);
+    const page = await call(ctx, (m) => take(m.projects.list(), limit));
+    emit(flags, page.rows, () => {
+      heading('Projects', page.rows.length);
+      if (!page.rows.length) return empty('No projects yet.');
+      rows(page.rows.map((p) => ({
+        cells: [String(p.id).slice(0, 8), p.name ?? ''],
+        style: [c.dim, undefined],
+      })));
+      more(page.more, `mnema projects --limit ${limit * 2}`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'projects' }); }
 }
@@ -141,16 +200,12 @@ export async function cmdAsk(flags, ctx, rest) {
       const line = `confidence ${pct}%${why} · tier ${a.tier}${a.usedFallback ? ' · fallback' : ''}`;
       console.log(pct >= 60 ? c.dim(`\n${line}`) : c.yellow(`\n${line} — treat as a lead, not a fact`));
       if (a.sources?.length) {
-        // ⚠️ THE HEADER USED TO LIE. It printed "sources (7):" and then listed
-        // five, silently. Either show them all or say how many are hidden —
-        // a count that does not match the rows under it teaches the reader to
-        // distrust every other number in the output.
         const SHOWN = 5;
         const shown = a.sources.slice(0, SHOWN);
-        const hidden = a.sources.length - shown.length;
-        console.log(c.dim(`\nsources (${a.sources.length}):`));
-        for (const s of shown) console.log(c.dim(`  ${trunc(s.title, 70)}`));
-        if (hidden > 0) console.log(c.dim(`  … ${hidden} more — --json for all`));
+        console.log('');
+        heading('Sources', a.sources.length);
+        rows(shown.map((s) => ({ cells: [truncate(s.title ?? '', 70)], style: [c.dim] })));
+        more(a.sources.length - shown.length, 'mnema ask --json "…"');
       }
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'ask' }); }
@@ -164,22 +219,27 @@ export async function cmdGraph(flags, ctx, rest) {
     const g = await call(ctx, (m) => m.graph.traverse(from, to));
     emit(flags, g, () => {
       if (to) {
-        // connected:false is an ANSWER, not a failure — say so plainly rather
+        // ⚠️ connected:false IS AN ANSWER, not a failure — say so plainly rather
         // than printing an empty list and letting it read as an error.
-        if (!g.connected) return console.log(c.yellow(`No route between "${from}" and "${to}".`));
-        console.log(c.bold(`${g.hopCount} hop(s) from "${from}" to "${to}"`));
-        for (const id of g.path) {
-          const n = g.nodes.find((x) => x.id === id);
-          console.log(`  ${n ? trunc(n.label, 60) : id}${n?.type ? c.dim(`  [${n.type}]`) : ''}`);
+        if (!g.connected) {
+          heading('Path');
+          return empty(`No route between "${from}" and "${to}".`, 'They are in the graph but nothing links them.');
         }
+        heading('Path', `${g.hopCount} hop${g.hopCount === 1 ? '' : 's'}`);
+        rows(g.path.map((id) => {
+          const n = g.nodes.find((x) => x.id === id);
+          return { cells: [n?.type ?? '', n ? truncate(n.label, 60) : id], style: [c.dim, undefined] };
+        }));
         return;
       }
-      console.log(c.bold(`${g.nodes.length} node(s), ${g.edges.length} edge(s) around "${from}"`));
-      // ⚠️ SAME LIE AS `ask`: the header reported the true count and the body
-      // stopped at 25 without a word.
       const CAP = 25;
-      for (const n of g.nodes.slice(0, CAP)) console.log(`  ${trunc(n.label, 60).padEnd(60)} ${c.dim(n.type ?? '')}`);
-      if (g.nodes.length > CAP) console.log(c.dim(`  … ${g.nodes.length - CAP} more — --json for all`));
+      heading(`Around "${from}"`, `${g.nodes.length} node${g.nodes.length === 1 ? '' : 's'} · ${g.edges.length} edge${g.edges.length === 1 ? '' : 's'}`);
+      if (!g.nodes.length) return empty(`Nothing is connected to "${from}" yet.`);
+      rows(g.nodes.slice(0, CAP).map((n) => ({
+        cells: [n.type ?? '', truncate(n.label, 60)],
+        style: [c.dim, undefined],
+      })));
+      more(g.nodes.length - CAP, `mnema graph --json "${from}"`);
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'graph' }); }
 }
@@ -191,21 +251,26 @@ export async function cmdBriefing(flags, ctx) {
     const b = await call(ctx, (m) => m.findings.briefing());
     emit(flags, b, () => {
       const p = b.pulse;
-      console.log(c.bold('Pulse'));
-      console.log(`  ${p.activeProjects} active project(s) · ${p.problemsInActiveProjects} problem(s) · $${p.cost7dUsd} last 7d`);
+      heading('Pulse');
+      rows([
+        { cells: ['projects', String(p.activeProjects)], style: [c.dim, undefined] },
+        { cells: ['problems', String(p.problemsInActiveProjects)], style: [c.dim, p.problemsInActiveProjects > 0 ? c.yellow : undefined] },
+        { cells: ['spend 7d', `$${p.cost7dUsd}`], style: [c.dim, undefined] },
+      ]);
 
       // ⚠️ THE CAVEATS COME BEFORE THE LIST, on purpose. A short list has three
       // causes and only one is good news; printing the findings first invites the
       // reader to conclude "all clear" before reaching the reason it is short.
-      if (b.neverComputed) console.log(c.yellow('\n  The findings engine has never run for this workspace.'));
-      if (b.coverage?.degraded) console.log(c.yellow(`\n  ${b.coverage.notice}`));
+      if (b.neverComputed) console.log(c.yellow(`\n  ${mark.warn()} The findings engine has never run for this workspace.`));
+      if (b.coverage?.degraded) console.log(c.yellow(`\n  ${mark.warn()} ${b.coverage.notice}`));
 
-      console.log(c.bold(`\nFindings (${b.findings.length})`));
-      if (!b.findings.length) console.log(c.dim('  nothing surfaced'));
-      for (const f of b.findings) {
-        const count = f.grouped ? c.dim(` ×${f.count}`) : '';
-        console.log(`  ${c.dim(String(f.kind).padEnd(14))} ${trunc(f.headline, 90)}${count}`);
-      }
+      console.log('');
+      heading('Findings', b.findings.length);
+      if (!b.findings.length) return empty('Nothing surfaced.');
+      rows(b.findings.map((f) => ({
+        cells: [String(f.kind), `${truncate(f.headline, 90)}${f.grouped ? ` ×${f.count}` : ''}`],
+        style: [c.dim, undefined],
+      })));
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'briefing' }); }
 }

package/src/render/layout.mjs

@@ -0,0 +1,117 @@
+/**
+ * One output grammar for the whole CLI (t-630).
+ *
+ * ⭐ THE CLI READ AS FOUR DIFFERENT PROGRAMS. Not because any one line was wrong,
+ * but because there were four heading grammars in eleven call sites:
+ *
+ *     Mnema status                     product-prefixed
+ *     Server sessions (7)              noun + parenthesised count
+ *     12 task(s)                       count-first, with the "(s)" tell
+ *     Pulse                            bare noun
+ *
+ * and three empty-state voices ("No docs.", "none found", "nothing surfaced"), and
+ * eleven hand-picked padEnd widths that had nothing to agree with. t-628 built the
+ * primitives; this module spends them, and it exists so the grammar is enforced by
+ * a function signature rather than by everyone remembering.
+ *
+ * The grammar, in one line each:
+ *
+ *     heading    Title Case noun, left. Count or context, dim, right.
+ *     rows       a table. Columns measured from content, last column absorbs.
+ *     empty      one dim sentence saying what is absent, then what to do.
+ *     footer     never a bare number. If something was cut, the command to see it.
+ *
+ * ⚠️ AND ONE RULE THAT IS NOT COSMETIC: anything the user is meant to COPY —
+ * the branch name from `next`, a conflict path from `pull` — is printed plain.
+ * No colour, no padding, no truncation. A padded string carries invisible trailing
+ * whitespace into their clipboard and an escape sequence carries worse.
+ */
+
+import { c, section, table, truncate, width, mark, glyph } from './theme.mjs';
+
+/** `Tasks                                        12` */
+export function heading(title, meta) {
+  console.log(section(title, meta == null ? undefined : String(meta)));
+}
+
+/**
+ * The one empty state.
+ *
+ * `hint` is where the CLI earns its keep: "No documents yet." is a dead end,
+ * "No documents yet. / Docs you create in the app appear here." is an answer.
+ */
+export function empty(sentence, hint) {
+  console.log(c.dim(`  ${sentence}`));
+  if (hint) console.log(c.dim(`  ${hint}`));
+}
+
+/** Aligned rows. `rows` is `[{ cells, style? }]` — see theme.table. */
+export function rows(list, opts) {
+  for (const line of table(list, opts)) console.log(line);
+}
+
+/**
+ * What was left out, and the exact command that shows it.
+ *
+ * ⚠️ THIS IS THE ANTI-LIE. Three places used to print a header count and then a
+ * shorter body with no word about it: `ask` said "sources (7)" and listed five,
+ * `graph` capped at 25 silently, `search` cut previews mid-sentence. A count that
+ * disagrees with the rows beneath it teaches the reader to distrust every other
+ * number in the output.
+ */
+export function more(hiddenOrTrue, command) {
+  if (!hiddenOrTrue) return;
+  const what = typeof hiddenOrTrue === 'number' ? `${hiddenOrTrue} more` : 'more available';
+  console.log(c.dim(`  … ${what} — ${command}`));
+}
+
+/** A line the user is expected to copy. Plain, always. */
+export function copyable(label, text) {
+  console.log(`\n  ${c.dim(label)} ${text}`);
+}
+
+/**
+ * `[glyph] label   value` — ONE primitive for every label/value block.
+ *
+ * ⚠️ ONE CALL, ONE TABLE, and that matters more than it looks. My first pass at
+ * `status` used three separate helpers, so the three groups measured their label
+ * columns independently and printed at three different widths — reproducing, in
+ * miniature, the exact defect this PR exists to remove. Anything meant to line up
+ * has to be measured together, which means it has to be ONE call.
+ *
+ * `state` is: true → ✓, false → ✗, 'warn' → !, null/undefined → no glyph at all.
+ * A blank glyph rather than a dot, because a bullet in front of "workspace" is
+ * decoration pretending to be information.
+ *
+ * ⚠️ PLAIN GLYPH + STYLE FUNCTION, never mark.ok(). table() strips escapes in
+ * order to measure a cell, so a pre-coloured glyph goes in coloured and comes out
+ * plain — which is what happened the first time I wrote the doctor list, and it
+ * rendered with colourless ticks. Pad first, colour last, always.
+ */
+export function entries(list) {
+  const g = (state) => {
+    if (state === true) return [glyph.ok, c.green];
+    if (state === false) return [glyph.bad, c.red];
+    if (state === 'warn') return [glyph.warn, c.yellow];
+    return ['', undefined];
+  };
+  rows(list.map((e) => {
+    const [mk, mkStyle] = g(e.state);
+    return {
+      cells: [mk, e.label, e.value ?? ''],
+      style: [mkStyle, c.dim, e.dim ? c.dim : e.style],
+    };
+  }));
+}
+
+/** Check list — every row carries a pass/fail glyph. */
+export function checks(list) {
+  entries(list.map((ch) => ({ label: ch.label, value: ch.note ?? '', state: ch.pass ?? false, dim: true })));
+}
+
+/** Plain `label   value` rows, no glyph column content. */
+export function fields(pairs) {
+  entries(pairs.map(([label, value, style]) => ({ label, value, state: null, style })));
+}
+
+export { c, truncate, width, mark };

package/src/render/pick.mjs

@@ -0,0 +1,131 @@
+/**
+ * Choose from a list without copying an id (t-631).
+ *
+ * ⭐ THE CLI KEPT ASKING FOR THINGS IT COULD OFFER. `mnema doc` with no argument
+ * printed "Usage: mnema doc <id>" — so the actual workflow was: run `mnema docs`,
+ * read a truncated title, select eight hex characters with the mouse, paste. Every
+ * id in this CLI is a UUID prefix that nobody can hold in their head, and the list
+ * command already knows all of them.
+ *
+ * ⚠️ RAW MODE IS THE DANGEROUS PART, and the danger is entirely in the exits. A
+ * process that leaves the terminal in raw mode with the cursor hidden hands back a
+ * shell where typing shows nothing and Ctrl-C does not work — the user's next move
+ * is to close the window. So there is exactly ONE restore path here, every exit
+ * goes through it, and it is also wired to SIGINT and to process exit. This is the
+ * single most damaging thing a terminal UI can get wrong, and it is worth more care
+ * than the feature itself.
+ */
+
+import { c, truncate, width } from './theme.mjs';
+
+const HIDE = '\x1b[?25l';
+const SHOW = '\x1b[?25h';
+const CLEAR = '\x1b[K';
+
+/** How many rows to show at once. Longer lists scroll within this window. */
+const WINDOW = 10;
+
+/**
+ * @param items  [{ label, hint }]
+ * @returns the chosen index, or null if cancelled / not interactive
+ */
+export function pick(items, { title = 'Select', stream = process.stderr, input = process.stdin } = {}) {
+  // Not interactive: there is nothing to drive the selection with. Returning null
+  // rather than hanging on a stdin that will never produce a keypress.
+  if (!items.length || !input.isTTY || !stream.isTTY || typeof input.setRawMode !== 'function') {
+    return Promise.resolve(null);
+  }
+
+  return new Promise((resolve) => {
+    let cursor = 0;
+    let top = 0;
+    let drawn = 0;
+    let finished = false;
+
+    const paint = () => {
+      // Move back over what we drew last time, clearing as we go.
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      const w = width();
+      const lines = [];
+      lines.push(`${c.bold(title)}  ${c.dim('↑↓ move · enter select · esc cancel')}`);
+      const view = items.slice(top, top + WINDOW);
+      for (let i = 0; i < view.length; i += 1) {
+        const idx = top + i;
+        const on = idx === cursor;
+        const label = truncate(view[i].label ?? '', w - 6);
+        // ⚠️ Colour AFTER truncation — the ordering rule from t-628. Truncating a
+        // coloured string cuts inside the escape and leaves the terminal stuck in
+        // whatever attribute was open.
+        lines.push(on ? `${c.cyan('❯')} ${c.bold(label)}` : `  ${c.dim(label)}`);
+      }
+      if (items.length > WINDOW) {
+        lines.push(c.dim(`  ${cursor + 1}/${items.length}`));
+      }
+      stream.write(lines.map((l) => `${CLEAR}${l}`).join('\n') + '\n');
+      drawn = lines.length;
+    };
+
+    // ⭐ ONE restore path. Every exit — enter, esc, Ctrl-C, an unexpected throw,
+    // the process dying — comes through here, and it is idempotent.
+    const restore = () => {
+      if (finished) return;
+      finished = true;
+      try { input.setRawMode(false); } catch { /* already closed */ }
+      input.pause();
+      input.removeListener('data', onData);
+      process.removeListener('SIGINT', onSigint);
+      process.removeListener('exit', restore);
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      for (let i = 0; i < drawn; i += 1) stream.write(`${CLEAR}\n`);
+      if (drawn) stream.write(`\x1b[${drawn}A`);
+      stream.write(SHOW);
+    };
+
+    function onSigint() {
+      restore();
+      // Exit the way an unhandled Ctrl-C would, so shells see the right status.
+      process.exit(130);
+    }
+
+    // Named constants, because a literal control byte pasted into source is
+    // invisible in a diff and unreadable in a comparison.
+    const CTRL_C = '\u0003';
+    const CTRL_D = '\u0004';
+    const ESC = '\u001b';
+    const UP = '\u001b[A';
+    const DOWN = '\u001b[B';
+    const PGUP = '\u001b[5~';
+    const PGDN = '\u001b[6~';
+
+    function onData(buf) {
+      const s = buf.toString('utf8');
+      // ⚠️ In raw mode Ctrl-C is DATA, not a signal — nothing else handles it.
+      if (s === CTRL_C) { onSigint(); return; }
+      if (s === CTRL_D || s === ESC || s === 'q') { restore(); resolve(null); return; }
+      if (s === '\r' || s === '\n') { restore(); resolve(cursor); return; }
+
+      let moved = 0;
+      if (s === UP || s === 'k') moved = -1;
+      else if (s === DOWN || s === 'j') moved = 1;
+      else if (s === PGUP) moved = -WINDOW;
+      else if (s === PGDN) moved = WINDOW;
+      else if (s === 'g') { cursor = 0; top = 0; paint(); return; }
+      else if (s === 'G') { cursor = items.length - 1; top = Math.max(0, items.length - WINDOW); paint(); return; }
+      if (!moved) return;
+
+      cursor = Math.min(items.length - 1, Math.max(0, cursor + moved));
+      if (cursor < top) top = cursor;
+      if (cursor >= top + WINDOW) top = cursor - WINDOW + 1;
+      paint();
+    }
+
+    stream.write(HIDE);
+    input.setRawMode(true);
+    input.resume();
+    input.setEncoding('utf8');
+    input.on('data', onData);
+    process.on('SIGINT', onSigint);
+    process.on('exit', restore);
+    paint();
+  });
+}