@mnemahq/cli 0.4.0 → 0.7.0

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