@mnemahq/cli 0.4.0 → 0.9.0

package/src/tui/components/list.mjs

@@ -0,0 +1,91 @@
+/**
+ * One selectable list, used by every screen (t-632).
+ *
+ * ⚠️ ONE KEYBOARD MODEL, DEFINED ONCE. The fastest way to make a TUI feel
+ * unfinished is for two lists to disagree about whether k moves up.
+ *
+ * The visible window scrolls rather than the list growing without bound: a
+ * terminal has a fixed height, and a 40-row findings list drawn in full pushes the
+ * header and the caveat banner off the top — the same failure the login dot line
+ * had, where the progress indicator destroyed the information it decorated.
+ */
+
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { html } from '../h.mjs';
+
+export function List({ items, focused = true, height = 10, onSelect }) {
+  // ⭐ START ON A REAL ROW, NOT A HEADING. In the graph walker the very first row
+  // is always a type header ("rationale  97"), so a cursor initialised to 0 sits
+  // on something that cannot be opened — the user's first `enter` does nothing at
+  // all, which reads as a broken UI rather than a misplaced cursor. Caught by the
+  // test, not by looking at it.
+  const [cursor, setCursor] = useState(() => {
+    const i = items.findIndex((it) => !it.header);
+    return i === -1 ? 0 : i;
+  });
+  const [top, setTop] = useState(0);
+
+  // ⚠️ HEADERS ARE ROWS BUT NOT DESTINATIONS. The graph walker groups 201
+  // neighbours under type headings so the structure is visible, and a cursor that
+  // can land on "concept  46" would let you press enter on a heading — which has
+  // nothing to open. Movement skips them, in the direction you were already going.
+  const selectable = (i) => items[i] && !items[i].header;
+
+  const move = (delta) => {
+    const step = delta > 0 ? 1 : -1;
+    let next = cursor + delta;
+    while (next >= 0 && next < items.length && !selectable(next)) next += step;
+    // Ran off the end past a trailing header — fall back to the nearest selectable
+    // row rather than parking the cursor on a heading or losing it entirely.
+    if (next < 0 || next >= items.length) {
+      next = cursor;
+      let probe = delta > 0 ? items.length - 1 : 0;
+      while (probe >= 0 && probe < items.length && !selectable(probe)) probe += (delta > 0 ? -1 : 1);
+      if (selectable(probe)) next = probe;
+    }
+    setCursor(next);
+    if (next < top) setTop(next);
+    if (next >= top + height) setTop(next - height + 1);
+  };
+
+  const firstSelectable = items.findIndex((it) => !it.header);
+
+  useInput((input, key) => {
+    if (key.upArrow || input === 'k') move(-1);
+    else if (key.downArrow || input === 'j') move(1);
+    else if (input === 'g') { setCursor(Math.max(0, firstSelectable)); setTop(0); }
+    else if (input === 'G') { move(items.length); }
+    else if (key.return && onSelect && selectable(cursor)) onSelect(cursor);
+  }, { isActive: Boolean(focused) && items.some((i) => !i.header) });
+
+  const view = items.slice(top, top + height);
+  const leftWidth = Math.max(0, ...items.filter((i) => !i.header).map((i) => (i.left ?? '').length));
+
+  return html`
+    <${Box} flexDirection="column">
+      ${view.map((item, i) => {
+        const idx = top + i;
+        const on = idx === cursor && focused;
+        if (item.header) {
+          return html`
+            <${Box} key=${item.key ?? idx} marginTop=${idx === top ? 0 : 1}>
+              <${Text}>  <//>
+              <${Text} bold color="yellow">${item.label}<//>
+              ${item.count !== undefined ? html`<${Text} dimColor>  ${item.count}<//>` : null}
+            <//>`;
+        }
+        return html`
+          <${Box} key=${item.key ?? idx}>
+            <${Text} color=${on ? 'cyan' : undefined}>${on ? '❯ ' : '  '}<//>
+            ${item.left !== undefined
+              ? html`<${Text} dimColor>${item.left.padEnd(leftWidth)}  <//>`
+              : null}
+            <${Text} bold=${on} dimColor=${!on}>${item.label}<//>
+          <//>`;
+      })}
+      ${items.length > height
+        ? html`<${Text} dimColor>  ${cursor + 1}/${items.length}<//>`
+        : null}
+    <//>`;
+}

package/src/tui/h.mjs

@@ -0,0 +1,23 @@
+/**
+ * JSX-shaped syntax without a build step (t-632).
+ *
+ * htm bound to React.createElement gives tagged-template markup that parses at
+ * runtime and caches per call site, so `.mjs` files stay directly runnable:
+ *
+ *     html`<${Box} flexDirection="column"><${Text}>hi<//><//>`
+ *
+ * ⚠️ THIS IS THE LEAST-BAD OPTION, NOT A GOOD ONE. It reads worse than JSX, and
+ * every Ink example on the internet needs translating to it. The alternative was
+ * adding esbuild, which would end this package's no-build-step property — src/ is
+ * published verbatim, `files` needs no dist entry, and `node --check` over src is
+ * the whole typecheck. That property is worth more than nicer syntax.
+ *
+ * ⚠️ AND THE CLOSING TAG IS `<//>`, not `</Box>`. Getting it wrong is a runtime
+ * parse error rather than a compile error, which is the real cost of no build.
+ */
+
+import React from 'react';
+import htm from 'htm';
+
+export const html = htm.bind(React.createElement);
+export { React };

package/src/tui/launch.mjs

@@ -0,0 +1,61 @@
+/**
+ * The lazy boundary (t-632).
+ *
+ * ⭐ THIS MODULE IS ONLY EVER REACHED THROUGH `await import()`. That is the whole
+ * design: one seam in cli.mjs, so that inside src/tui/** the imports can be
+ * ordinary static ones rather than dozens of dynamic imports scattered through
+ * components. Nothing outside src/tui/ may import anything in it statically.
+ *
+ * Measured, on this machine:
+ *
+ *     import('ink')       136–141 ms
+ *     mnema --version      59–65 ms
+ *
+ * So a static import would roughly triple the cost of every one-shot command —
+ * and `mnema` runs from capture hooks and shell prompts, not just by hand.
+ *
+ * ⚠️ A TUI THAT CRASHES WITHOUT RESTORING THE TERMINAL IS WORSE THAN NO TUI. Ink
+ * takes the alternate screen and hides the cursor; if the process dies without
+ * unmounting, the user gets back a shell with an invisible cursor and no echo. So
+ * unmount runs from an uncaughtException handler as well as from the normal exit,
+ * and the cursor is shown again explicitly rather than trusting the library to do
+ * it on the way out of an abnormal exit.
+ */
+
+import { render } from 'ink';
+import { html } from './h.mjs';
+import { App } from './app.mjs';
+
+const SHOW_CURSOR = '\x1b[?25h';
+
+export async function startTui(ctx) {
+  const instance = render(html`<${App} ctx=${ctx} />`, {
+    // Ink's own exitOnCtrlC would leave our own key handling out of the loop.
+    exitOnCtrlC: true,
+  });
+
+  const restore = () => {
+    try { instance.unmount(); } catch { /* already gone */ }
+    try { process.stdout.write(SHOW_CURSOR); } catch { /* stream closed */ }
+  };
+
+  const onFatal = (err) => {
+    restore();
+    // Print AFTER restoring, or the message lands on the alternate screen and
+    // vanishes with it — the user sees a crash with no text.
+    process.stderr.write(`\nmnema: ${err?.stack ?? err}\n`);
+    process.exit(1);
+  };
+
+  process.on('uncaughtException', onFatal);
+  process.on('unhandledRejection', onFatal);
+
+  try {
+    await instance.waitUntilExit();
+  } finally {
+    process.off('uncaughtException', onFatal);
+    process.off('unhandledRejection', onFatal);
+    try { process.stdout.write(SHOW_CURSOR); } catch { /* stream closed */ }
+  }
+  return 0;
+}

package/src/tui/screens/briefing.mjs

@@ -0,0 +1,74 @@
+/**
+ * The home screen: what deserves attention (t-632).
+ *
+ * ⚠️ THE COVERAGE CAVEATS RENDER ABOVE THE LIST, and that is not a layout
+ * preference. read-commands.mjs:198 prints them first on purpose: a short findings
+ * list has three quite different causes and only one of them is good news. On a
+ * core build six of the seven finding families cannot produce anything at all, and
+ * `coverage.notice` is the only thing that says so. Put the banner under the list,
+ * where it is off-screen on a short terminal, and the reader concludes "all clear"
+ * from a list that is short because the engine never ran.
+ */
+
+import { Box, Text, useInput } from 'ink';
+import { html } from '../h.mjs';
+import { useResource, ago } from '../store.mjs';
+import { List } from '../components/list.mjs';
+
+export function Briefing({ ctx, onOpen, focused }) {
+  const { status, data, error, elapsed, at, reload } = useResource('briefing', () =>
+    ctx.call((m) => m.findings.briefing()));
+
+  // Refresh is explicit. See store.mjs: a list that reorders under a moving cursor
+  // means pressing enter on row three opens what is now row four.
+  useInput((input) => { if (input === 'r') reload(); }, { isActive: Boolean(focused) });
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}>
+      <${Text} dimColor>Loading the briefing… ${elapsed > 1 ? `${elapsed}s` : ''}<//>
+    <//>`;
+  }
+
+  if (error && !data) {
+    return html`<${Box} flexDirection="column" paddingX=${1}>
+      <${Text} color="red">${error.message ?? String(error)}<//>
+      <${Text} dimColor>r to retry · q to quit<//>
+    <//>`;
+  }
+
+  const b = data ?? {};
+  const p = b.pulse ?? {};
+  const findings = b.findings ?? [];
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Box} gap=${3}>
+        <${Text}><${Text} dimColor>projects </>${p.activeProjects ?? 0}<//>
+        <${Text}><${Text} dimColor>problems </><${Text} color=${(p.problemsInActiveProjects ?? 0) > 0 ? 'yellow' : undefined}>${p.problemsInActiveProjects ?? 0}<//><//>
+        <${Text}><${Text} dimColor>spend 7d </>$${p.cost7dUsd ?? 0}<//>
+        <${Text} dimColor>${ago(at)}${status === 'refreshing' ? ' · refreshing' : ''}<//>
+      <//>
+
+      ${b.neverComputed ? html`<${Box} marginTop=${1}><${Text} color="yellow">! The findings engine has never run for this workspace.<//><//>` : null}
+      ${b.coverage?.degraded ? html`<${Box} marginTop=${1}><${Text} color="yellow">! ${b.coverage.notice}<//><//>` : null}
+
+      <${Box} marginTop=${1}>
+        <${Text} bold>Findings<//>
+        <${Text} dimColor>  ${findings.length}<//>
+      <//>
+
+      ${findings.length === 0
+        ? html`<${Text} dimColor>  Nothing surfaced.<//>`
+        : html`<${List}
+            items=${findings.map((f) => ({
+              key: f.id ?? f.headline,
+              left: String(f.kind ?? ''),
+              label: `${f.headline ?? ''}${f.grouped ? ` ×${f.count}` : ''}`,
+            }))}
+            focused=${focused}
+            onSelect=${(i) => onOpen(findings[i])}
+          />`}
+
+      ${error ? html`<${Box} marginTop=${1}><${Text} color="yellow">refresh failed — ${error.message ?? String(error)}<//><//>` : null}
+    <//>`;
+}

package/src/tui/screens/finding.mjs

@@ -0,0 +1,89 @@
+/**
+ * One finding, and the way into the graph beneath it (t-632, corrected t-634).
+ *
+ * ⭐ I BUILT THE FIRST VERSION AGAINST THE SDK'S `Finding` INTERFACE AND IT WAS
+ * THE WRONG SHAPE. That interface describes a MEMBER of a grouped finding; a
+ * briefing row is something else entirely. Checked against prod, a briefing row
+ * carries:
+ *
+ *     id, grouped, kind, rule, headline, count, score, members, subjectKeys
+ *
+ * and NOT `subject`, `subjectNodeId`, `evidence`, `detail`, `severity` or
+ * `window` — every one of which the first version rendered. So every finding
+ * showed "No evidence rows came back with this finding", which reads as the engine
+ * returning nothing when in fact the screen was reading fields that were never
+ * there. A feature running clean and producing nothing, again, and it survived a
+ * PR because the tests used the shape I had invented rather than the shape prod
+ * sends.
+ *
+ * ⚠️ TWO GENUINELY DIFFERENT SHAPES, and conflating them is what caused it:
+ *
+ *   grouped   has `members[]`, and each member IS a full finding WITH a
+ *             subjectNodeId — so this is the real drill-down: finding → the
+ *             specific pair of contradicting decisions → that node in the graph.
+ *   single    is an aggregate over thousands of rows ("1,238 decisions have no
+ *             task"). There is no one node it is about, and inventing a subject
+ *             so the UI looks uniform would be worse than saying so.
+ *
+ * Live when this was written: 2 grouped (4 and 5 members), 7 single.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+import { List } from '../components/list.mjs';
+
+const Row = ({ label, children }) => html`
+  <${Box}>
+    <${Text} dimColor>${String(label).padEnd(9)}  <//>
+    <${Text}>${children}<//>
+  <//>`;
+
+export function Finding({ finding, focused, onOpenSubject }) {
+  if (!finding) {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Nothing selected.<//><//>`;
+  }
+
+  const members = Array.isArray(finding.members) ? finding.members : [];
+  const pct = typeof finding.score === 'number' ? `${Math.round(finding.score * 100)}%` : null;
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Text} bold>${finding.headline ?? '(no headline)'}<//>
+
+      <${Box} flexDirection="column" marginTop=${1}>
+        ${html`<${Row} label="kind">${finding.kind ?? '—'}<//>`}
+        ${finding.rule ? html`<${Row} label="rule">${finding.rule}<//>` : null}
+        ${pct ? html`<${Row} label="score">${pct}<//>` : null}
+      <//>
+
+      ${members.length
+        ? html`
+          <${Box} flexDirection="column" marginTop=${1}>
+            <${Box}>
+              <${Text} bold>Occurrences<//>
+              <${Text} dimColor>  ${members.length} · enter opens one in the graph<//>
+            <//>
+            <${List}
+              items=${members.map((m) => ({
+                key: m.id,
+                left: m.subject ?? '',
+                label: m.headline ?? '',
+              }))}
+              focused=${focused}
+              height=${8}
+              onSelect=${(i) => {
+                const m = members[i];
+                if (m?.subjectNodeId && onOpenSubject) {
+                  onOpenSubject({ id: m.subjectNodeId, label: m.subject ?? undefined });
+                }
+              }}
+            />
+          <//>`
+        : html`
+          <${Box} marginTop=${1} flexDirection="column">
+            <${Text} dimColor>An aggregate across the whole workspace, not one node —<//>
+            <${Text} dimColor>so there is nothing single to open from here.<//>
+            <${Text} dimColor>\`mnema briefing --json\` has the full row.<//>
+          <//>`}
+    <//>`;
+}

package/src/tui/screens/node.mjs

@@ -0,0 +1,106 @@
+/**
+ * One graph node, and everything connected to it (t-634).
+ *
+ * ⭐ THIS IS THE SCREEN THE TUI WAS MISSING. The briefing ended at a finding and
+ * stopped, so the most interesting surface Mnema has — the graph — could only be
+ * reached by typing a node label into a one-shot command and reading a flat list.
+ * A community connects to concepts, concepts to rationales; the point is to walk
+ * that, not to print it.
+ *
+ * ⚠️ GROUPED BY TYPE, IN ONE LIST, and that shape is a decision rather than a
+ * default. A real hub returns 201 neighbours across 8 types — concept 46,
+ * rationale 97, gap 37, decision 6, issue 10, and so on. A flat list of 201 is
+ * unusable; a type picker that then opens a second list makes every node two
+ * keystrokes further away and hides the interesting fact that there are 97
+ * rationales here. Headers in a single scrolling list show the structure AND keep
+ * every node one keystroke away.
+ *
+ * ⚠️ AND WE WALK BY ID, NOT BY LABEL. traverse() accepts both — verified against
+ * prod — but re-resolving a label could land on a different node that happens to
+ * share a name, which in a knowledge graph is not a hypothetical.
+ */
+
+import { Box, Text, useInput } from 'ink';
+import { html } from '../h.mjs';
+import { useResource, ago } from '../store.mjs';
+import { List } from '../components/list.mjs';
+
+/** Most numerous first: the shape of a neighbourhood is itself information. */
+function group(nodes, centreId) {
+  const byType = new Map();
+  for (const n of nodes) {
+    if (n.id === centreId) continue;
+    if (!byType.has(n.type)) byType.set(n.type, []);
+    byType.get(n.type).push(n);
+  }
+  const rows = [];
+  for (const [type, list] of [...byType.entries()].sort((a, b) => b[1].length - a[1].length)) {
+    rows.push({ header: true, key: `h:${type}`, label: type, count: list.length });
+    for (const n of list) rows.push({ key: n.id, label: n.label ?? '(unlabelled)', node: n });
+  }
+  return rows;
+}
+
+export function NodeScreen({ ctx, target, focused, onOpen, trail = [] }) {
+  const key = target.id ?? target.label;
+  const { status, data, error, elapsed, at, reload } = useResource(`node:${key}`, () =>
+    ctx.call((m) => m.graph.traverse(key)));
+
+  useInput((input) => { if (input === 'r') reload(); }, { isActive: Boolean(focused) });
+
+  if (status === 'loading') {
+    return html`<${Box} flexDirection="column" paddingX=${1}>
+      ${trail.length ? html`<${Text} dimColor>${trail.join(' › ')}<//>` : null}
+      <${Text} dimColor>Walking to ${target.label ?? key}… ${elapsed > 1 ? `${elapsed}s` : ''}<//>
+    <//>`;
+  }
+
+  if (error && !data) {
+    return html`<${Box} flexDirection="column" paddingX=${1}>
+      <${Text} color="red">${error.message ?? String(error)}<//>
+      <${Text} dimColor>r to retry · esc to go back<//>
+    <//>`;
+  }
+
+  const g = data ?? { nodes: [], edges: [] };
+  // The centre is the node we asked for. Match on id when we have one, and fall
+  // back to the label only when we arrived here by name from the command line.
+  const centre = g.nodes.find((n) => n.id === target.id)
+    ?? g.nodes.find((n) => n.label === target.label)
+    ?? { label: target.label ?? key, type: '?' };
+  const rows = group(g.nodes, centre.id);
+  const neighbours = rows.filter((r) => !r.header).length;
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      ${trail.length > 1
+        ? html`<${Text} dimColor>${trail.slice(0, -1).join(' › ')} ›<//>`
+        : null}
+
+      <${Box}>
+        <${Text} bold>${centre.label}<//>
+        <${Text} dimColor>  ${centre.type}<//>
+        ${centre.isGodNode ? html`<${Text} color="yellow">  ★ load-bearing<//>` : null}
+      <//>
+
+      ${centre.summary
+        ? html`<${Box} marginTop=${1}><${Text} dimColor>${centre.summary}<//><//>`
+        : null}
+
+      <${Box} marginTop=${1}>
+        <${Text} bold>Connected<//>
+        <${Text} dimColor>  ${neighbours} node${neighbours === 1 ? '' : 's'} · ${g.edges.length} edge${g.edges.length === 1 ? '' : 's'} · ${ago(at)}<//>
+      <//>
+
+      ${neighbours === 0
+        ? html`<${Text} dimColor>  Nothing is connected to this node yet.<//>`
+        : html`<${List}
+            items=${rows}
+            focused=${focused}
+            height=${12}
+            onSelect=${(i) => onOpen(rows[i].node)}
+          />`}
+
+      ${error ? html`<${Box} marginTop=${1}><${Text} color="yellow">refresh failed — ${error.message ?? String(error)}<//><//>` : null}
+    <//>`;
+}

package/src/tui/store.mjs

@@ -0,0 +1,65 @@
+/**
+ * Fetching, for the TUI (t-632).
+ *
+ * Hand-rolled rather than a data library: the requirements are small, and a
+ * dependency here would land on the lazy side of the boundary but still be
+ * installed for every user of the package.
+ *
+ * ⚠️ THE ELAPSED CLOCK ONLY TICKS WHILE LOADING. An interval that runs whenever
+ * the component is mounted re-renders the whole tree ten times a second forever,
+ * which on a terminal means a visible flicker and a pegged CPU on an idle screen.
+ *
+ * ⚠️ AND IT DOES NOT POLL. A list that reorders itself under a moving cursor is
+ * hostile — you press enter on what was row three and open what is now row four.
+ * Load on mount, show how stale it is, refresh on `r`.
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export function useResource(key, fetcher) {
+  const [state, setState] = useState({ status: 'loading', data: null, error: null, at: null });
+  const [elapsed, setElapsed] = useState(0);
+  const [nonce, setNonce] = useState(0);
+  const alive = useRef(true);
+
+  useEffect(() => () => { alive.current = false; }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    setState((s) => ({ ...s, status: s.data ? 'refreshing' : 'loading', error: null }));
+    setElapsed(0);
+    Promise.resolve()
+      .then(fetcher)
+      .then((data) => {
+        if (cancelled || !alive.current) return;
+        setState({ status: 'ready', data, error: null, at: Date.now() });
+      })
+      .catch((error) => {
+        if (cancelled || !alive.current) return;
+        // ⚠️ KEEP THE OLD DATA. A failed refresh should not blank a screen the
+        // user is reading; it should say the refresh failed.
+        setState((s) => ({ status: 'error', data: s.data, error, at: s.at }));
+      });
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, nonce]);
+
+  useEffect(() => {
+    if (state.status !== 'loading' && state.status !== 'refreshing') return undefined;
+    const t = setInterval(() => setElapsed((n) => n + 1), 1000);
+    return () => clearInterval(t);
+  }, [state.status]);
+
+  const reload = useCallback(() => setNonce((n) => n + 1), []);
+  return { ...state, elapsed, reload };
+}
+
+/** "3m ago" — so a screen that is not polling still says how old it is. */
+export function ago(at) {
+  if (!at) return '';
+  const s = Math.floor((Date.now() - at) / 1000);
+  if (s < 5) return 'just now';
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  return `${Math.floor(s / 3600)}h ago`;
+}

package/src/tui-gate.mjs

@@ -0,0 +1,79 @@
+/**
+ * Whether to open the interactive UI, and why not when not (t-632).
+ *
+ * ⚠️ THIS FILE MUST NEVER IMPORT INK. It is loaded on every single invocation of
+ * `mnema`, including `mnema --version` from a shell prompt and the capture hook.
+ * `import('ink')` costs ~140ms measured, against a ~60ms `mnema --version`, so a
+ * static import here would make every one-shot several times slower for a feature
+ * almost no invocation uses. The decision has to be cheap; only the answer "yes"
+ * is allowed to be expensive.
+ *
+ * ⭐ AND `node --check` WILL NOT CATCH A MISTAKE HERE. It parses without resolving,
+ * so `import { Box } from 'ink'` at the top of this file is syntactically fine and
+ * nothing goes red until a user's `mnema status` crashes or crawls. That is what
+ * test/no-ink-in-oneshot.test.mjs is for.
+ */
+
+/** ink 6 requires Node 20 — the same floor @mnemahq/sdk already declares. */
+export const MIN_NODE = 20;
+
+const nodeMajor = () => Number(process.versions.node.split('.')[0]);
+
+/**
+ * @returns {{ok: boolean, reason?: string, detail?: string}}
+ */
+export function tuiEligibility(flags = {}, env = process.env, out = process.stdout, inp = process.stdin) {
+  // An explicit no wins over everything, including MNEMA_TUI=always.
+  if (flags['no-tui'] || env.MNEMA_TUI === 'never' || env.MNEMA_NO_TUI) {
+    return { ok: false, reason: 'opted-out' };
+  }
+
+  // ⚠️ THE NODE CHECK IS NOT OVERRIDABLE. MNEMA_TUI=always exists so tests can
+  // exercise the positive path without a pty; it must not be able to force a
+  // runtime that cannot load the library into trying.
+  if (nodeMajor() < MIN_NODE) {
+    return { ok: false, reason: 'node', detail: `v${process.versions.node}` };
+  }
+
+  // ⚠️ RAW MODE IS A HARD REQUIREMENT OF INK, so this is not overridable either.
+  // Found by running `MNEMA_TUI=always mnema` through a pipe: Ink starts, cannot
+  // put stdin in raw mode, and renders its own internal fallback — which emits a
+  // React "two children with the same key" warning straight into the user's output
+  // and leaves a half-drawn screen that responds to nothing. I spent a while
+  // hunting that key in MY components before proving it came from Ink's internals:
+  // with a raw-mode-capable stdin the same tree renders clean.
+  //
+  // A UI that cannot receive a keypress is not a UI, so refuse rather than start.
+  if (typeof inp.setRawMode !== 'function') {
+    return { ok: false, reason: 'no-raw-mode' };
+  }
+
+  if (env.MNEMA_TUI === 'always') return { ok: true };
+
+  if (!out.isTTY || !inp.isTTY) return { ok: false, reason: 'not-a-tty' };
+  if (env.TERM === 'dumb') return { ok: false, reason: 'dumb-terminal' };
+  // Ink degrades to line-by-line under CI, but we would rather not start at all.
+  if (env.CI) return { ok: false, reason: 'ci' };
+
+  return { ok: true };
+}
+
+/**
+ * What to tell the user, and on which stream.
+ *
+ * ⚠️ `not-a-tty` SAYS NOTHING AT ALL. Piping `mnema` to read its help is a
+ * perfectly good thing to do, and a nag in that case is noise in someone's data.
+ * The node case does explain itself, because "I ran mnema and got help" deserves
+ * a reason — but on stderr, so `mnema | cat` still gets clean help on stdout.
+ */
+export function explainUnavailable(reason, detail) {
+  if (reason === 'node') {
+    return [
+      `The interactive UI needs Node ${MIN_NODE} or newer — you are on ${detail}.`,
+      'Everything below works on your version. For the UI: nvm install 22',
+    ];
+  }
+  if (reason === 'dumb-terminal') return ['This terminal reports TERM=dumb, so the interactive UI is off.'];
+  if (reason === 'no-raw-mode') return ['This terminal cannot enter raw mode, so the interactive UI cannot read keys.'];
+  return [];
+}