@mnemahq/cli 0.3.1 → 0.7.0

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,53 @@
+/**
+ * One finding, in full (t-632).
+ *
+ * ⚠️ THE HEADLINE IS A SUMMARY, AND A SUMMARY OF A FINDING IS EXACTLY WHERE A
+ * NUMBER LOSES ITS CAVEATS. "0 of 1238 decisions turned into work" reads as an
+ * indictment until you know the window is 90 days and the engine only sees
+ * decisions that were recorded. So the detail view shows what the engine actually
+ * had — subject, evidence, window — rather than restating the headline larger.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+
+const Row = ({ label, children }) => html`
+  <${Box}>
+    <${Text} dimColor>${String(label).padEnd(10)}  <//>
+    <${Text}>${children}<//>
+  <//>`;
+
+export function Finding({ finding }) {
+  if (!finding) {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Nothing selected.<//><//>`;
+  }
+
+  const evidence = finding.evidence ?? finding.subjects ?? [];
+
+  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.grouped ? html`<${Row} label="grouped">${finding.count} occurrences<//>` : null}
+        ${finding.severity ? html`<${Row} label="severity">${finding.severity}<//>` : null}
+        ${finding.window ? html`<${Row} label="window">${finding.window}<//>` : null}
+      <//>
+
+      ${finding.detail
+        ? html`<${Box} marginTop=${1}><${Text} dimColor>${finding.detail}<//><//>`
+        : null}
+
+      ${Array.isArray(evidence) && evidence.length
+        ? html`
+          <${Box} flexDirection="column" marginTop=${1}>
+            <${Text} bold>Evidence<//>
+            ${evidence.slice(0, 8).map((e, i) => html`
+              <${Text} key=${i} dimColor>  ${typeof e === 'string' ? e : (e.label ?? e.title ?? JSON.stringify(e))}<//>`)}
+            ${evidence.length > 8
+              ? html`<${Text} dimColor>  … ${evidence.length - 8} more — mnema briefing --json<//>`
+              : null}
+          <//>`
+        : html`<${Box} marginTop=${1}><${Text} dimColor>No evidence rows came back with this finding.<//><//>`}
+    <//>`;
+}

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 [];
+}

package/src/util.mjs

@@ -28,14 +28,16 @@ export const DEFAULT_ORIGIN = process.env.MNEMA_API_ORIGIN || 'https://api.thebo
  */
 export const DEFAULT_APP_URL = process.env.MNEMA_APP_URL || 'https://mnema.theboringpeople.in';
 
-export const c = {
-  dim: (s) => `\x1b[2m${s}\x1b[0m`,
-  green: (s) => `\x1b[32m${s}\x1b[0m`,
-  red: (s) => `\x1b[31m${s}\x1b[0m`,
-  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
-  bold: (s) => `\x1b[1m${s}\x1b[0m`,
-  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
-};
+/**
+ * ⭐ RE-EXPORTED, NOT REDEFINED. `c` used to live here and emitted escapes
+ * unconditionally — no isTTY, no NO_COLOR — so `mnema tasks | less` was full of
+ * escape bytes and `mnema docs > out.txt` wrote them to disk.
+ *
+ * Re-exporting from render/theme.mjs means every existing
+ * `import { c } from './util.mjs'` picks up the TTY-aware version without a
+ * single call site changing. One line, whole-CLI effect.
+ */
+export { c, truncate, pad, table, section, width, link, mark, strip, displayWidth } from './render/theme.mjs';
 
 // ── git ──────────────────────────────────────────────────────────────────────
 
@@ -118,35 +120,92 @@ export async function apiFetch(origin, path, { token, method = 'GET', body } = {
 
 // ── prompts ────────────────────────────────────────────────────────────────────
 
+/**
+ * Ask a question and read one line.
+ *
+ * ⚠️ CTRL-D USED TO VANISH. There was no `close` handler, so EOF never resolved
+ * the promise — the process simply ran out of work and exited 0, halfway through
+ * `init`, with no message. A setup that stops silently and claims success is
+ * worse than one that fails, so EOF now rejects and the caller reports it.
+ */
 export function prompt(question) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
+  return new Promise((resolve, reject) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let answered = false;
+    rl.question(question, (a) => { answered = true; rl.close(); resolve(a.trim()); });
+    rl.on('close', () => {
+      if (!answered) reject(new Error('Cancelled.'));
+    });
+  });
 }
 
-/** Prompt without echoing (for secrets). Falls back to visible if not a TTY. */
+/**
+ * Prompt for a secret without echoing it.
+ *
+ * ⚠️ THREE THINGS WERE WRONG HERE, and two of them were security-adjacent.
+ *
+ * 1. NOTHING WAS ECHOED AT ALL — not even a mask. Pasting a 106-character API key
+ *    looked exactly like pressing nothing, so the only way to find out whether it
+ *    had registered was to hit Enter and see what happened. A dot per grapheme
+ *    fixes that without revealing length-sensitive content any more than the
+ *    cursor position already does.
+ *
+ * 2. CTRL-C EXITED WITHOUT RESTORING RAW MODE. Node usually repairs the tty on
+ *    exit, so it *usually* looked fine — which is exactly what makes it the kind
+ *    of bug that surfaces on someone else's terminal months later.
+ *
+ * 3. ESCAPE SEQUENCES WERE APPENDED VERBATIM. An arrow key is `\x1b[A`; that went
+ *    straight into the secret, as did Ctrl-U, Ctrl-W and bracketed-paste markers.
+ *    The user saw nothing (see 1) and got an authentication failure with no clue.
+ *    Control bytes are now filtered rather than stored.
+ *
+ * Falls back to a visible readline when stdin is not a TTY — deliberate, so
+ * `echo $TOKEN | mnema init` still works in CI.
+ */
 export function promptHidden(question) {
-  return new Promise((resolve) => {
+  return new Promise((resolve, reject) => {
     const { stdin, stdout } = process;
     if (!stdin.isTTY) {
-      // Non-interactive: read one line plainly.
       const rl = createInterface({ input: stdin, output: stdout });
-      rl.question(question, (a) => { rl.close(); resolve(a.trim()); });
+      let answered = false;
+      rl.question(question, (a) => { answered = true; rl.close(); resolve(a.trim()); });
+      rl.on('close', () => { if (!answered) reject(new Error('Cancelled.')); });
       return;
     }
+
     stdout.write(question);
     stdin.setRawMode(true);
     stdin.resume();
     let buf = '';
+
+    // One restore path for every exit, so raw mode cannot leak.
+    const restore = () => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.removeListener('data', onData);
+    };
+
     const onData = (ch) => {
       const s = ch.toString('utf8');
-      if (s === '\r' || s === '\n') {
-        stdin.setRawMode(false); stdin.pause(); stdin.removeListener('data', onData);
-        stdout.write('\n'); resolve(buf.trim()); return;
+
+      if (s === '\r' || s === '\n') { restore(); stdout.write('\n'); resolve(buf.trim()); return; }
+      if (s === '\u0003') { restore(); stdout.write('\n'); reject(new Error('Cancelled.')); return; }  // Ctrl-C
+      if (s === '\u0004') { restore(); stdout.write('\n'); reject(new Error('Cancelled.')); return; }  // Ctrl-D
+      if (s === '\u0015') { stdout.write(`\r${question}${' '.repeat(buf.length)}\r${question}`); buf = ''; return; } // Ctrl-U
+
+      if (s === '\u007f' || s === '\b') {
+        if (buf.length) { buf = buf.slice(0, -1); stdout.write('\b \b'); }
+        return;
       }
-      if (s === '') { stdout.write('\n'); process.exit(1); }        // Ctrl-C
-      if (s === '' || s === '\b') { buf = buf.slice(0, -1); return; } // backspace
+
+      // ⚠️ Drop anything with a control byte in it — arrow keys, function keys,
+      // bracketed-paste markers. Storing these was silent corruption of a secret.
+      if (/[\u0000-\u001f\u007f]/.test(s)) return;
+
       buf += s;
+      stdout.write('•'.repeat([...s].length));
     };
+
     stdin.on('data', onData);
   });
 }