@mnemahq/cli 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Mnema CLI — connect a repo to your Mnema workspace: install session capture, sweep past sessions, and search from the terminal.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
     "htm": "^3.1.1",
     "ink": "^6.8.0",
     "react": "^19.2.7",
-    "@mnemahq/sdk": "0.3.1"
+    "@mnemahq/sdk": "0.4.0"
   },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

package/src/cli.mjs

@@ -510,6 +510,9 @@ Commands:
   uninstall    Remove hooks and stored secrets
   tui          Open the interactive briefing explicitly (Node 20+, a terminal)
 
+On a terminal, the read commands below open a NAVIGABLE view — arrow keys to move,
+enter to open, esc to go back. Piped or with --json they print as they always have.
+
 Read your workspace:
   tasks        List tasks            [--status --project --limit]
   next         The next task to pick up, with a ready-made branch name
@@ -520,7 +523,7 @@ Read your workspace:
 
 Ask the knowledge graph (paid feature):
   ask "q"      A cited answer, with the confidence it deserves
-  graph        Neighbourhood of a node, or the path between two
+  graph        Walk a node's neighbours; graph <a> <b> prints the path between two
 
 Examples:
   mnema                                  the interactive briefing
@@ -565,6 +568,49 @@ writes plain text.
  * because `node --check` parses without resolving and would never notice a stray
  * `import { Box } from 'ink'` in read-commands.mjs.
  */
+/**
+ * ⭐ THE COMMAND YOU TYPED SHOULD DO THE THING YOU NAMED.
+ *
+ * `mnema graph "Workspace Security & Management"` printed 25 rows and "… 176
+ * more" and stopped. The navigable walker existed, but it lived behind bare
+ * `mnema` and a `g` keybinding — so the obvious command gave a static dump and
+ * the answer was "run a different command and press a key". Nobody does that.
+ * They type the thing they want.
+ *
+ * ⚠️ THE ONE-SHOT PATH IS UNCHANGED. --json, a pipe, no TTY, --no-tui, CI: all
+ * still print exactly what they printed before, byte for byte. Scripts are the
+ * contract. This only changes what a HUMAN AT A TERMINAL gets.
+ *
+ * @returns true if the interactive view took over.
+ */
+/**
+ * Which screen a read command should open on, or null to stay one-shot.
+ *
+ * Exported so the ROUTING is testable without spawning ink — the decision is the
+ * part that was wrong, and a test that re-implements it in the test file proves
+ * nothing about this function.
+ */
+export function screenFor(cmd, flags, rest = []) {
+  if (flags.json) return null;
+  if (cmd === 'graph') {
+    // `graph <a> <b>` is a path query — one answer, not a place to walk.
+    if (rest.length > 1) return null;
+    return rest[0] ? { name: 'node', target: { label: rest[0] } } : { name: 'graph' };
+  }
+  if (cmd === 'tasks' || cmd === 'docs' || cmd === 'briefing') return { name: cmd };
+  return null;
+}
+
+async function maybeInteractive(flags, screen) {
+  if (!screen) return false;
+  if (flags.json) return false;
+  if (!tuiEligibility(flags).ok) return false;
+  const { startTui } = await import('./tui/launch.mjs');
+  const ctx = resolveContext(flags);
+  await startTui({ ...ctx, version: VERSION, call: (fn) => call(ctx, fn) }, screen);
+  return true;
+}
+
 async function openTuiOrHelp(flags) {
   const gate = tuiEligibility(flags);
   if (gate.ok) {
@@ -612,14 +658,25 @@ export async function run(argv) {
 
     // Reads. Each resolves context once and hands the SDK client to a wrapper;
     // none of them knows a URL or an envelope key (§A2, t-623).
-    case 'tasks':     return cmdTasks(flags, resolveContext(flags));
+    case 'tasks':
+      if (await maybeInteractive(flags, screenFor('tasks', flags))) return 0;
+      return cmdTasks(flags, resolveContext(flags));
     case 'next':      return cmdNext(flags, resolveContext(flags));
-    case 'docs':      return cmdDocs(flags, resolveContext(flags));
+    case 'docs':
+      if (await maybeInteractive(flags, screenFor('docs', flags))) return 0;
+      return cmdDocs(flags, resolveContext(flags));
     case 'doc':       return cmdDoc(flags, resolveContext(flags), rest);
     case 'projects':  return cmdProjects(flags, resolveContext(flags));
     case 'ask':       return cmdAsk(flags, resolveContext(flags), rest);
-    case 'graph':     return cmdGraph(flags, resolveContext(flags), rest);
-    case 'briefing':  return cmdBriefing(flags, resolveContext(flags));
+    case 'graph':
+      // With a node named, open the walker AT it. With no argument, open the hub
+      // list. `graph <a> <b>` is a path query — a single answer, not a place to
+      // walk — so that one stays one-shot.
+      if (await maybeInteractive(flags, screenFor('graph', flags, rest))) return 0;
+      return cmdGraph(flags, resolveContext(flags), rest);
+    case 'briefing':
+      if (await maybeInteractive(flags, screenFor('briefing', flags))) return 0;
+      return cmdBriefing(flags, resolveContext(flags));
     case 'tui':
       // An EXPLICIT request that cannot be honoured fails loudly (exit 1); the
       // implicit one below degrades to help and exits 0. That asymmetry is

package/src/tui/app.mjs

@@ -20,12 +20,15 @@ import { Briefing } from './screens/briefing.mjs';
 import { Finding } from './screens/finding.mjs';
 import { NodeScreen } from './screens/node.mjs';
 import { Header } from './components/header.mjs';
+import { GraphHome } from './screens/graph-home.mjs';
+import { Tasks, Task } from './screens/tasks.mjs';
+import { Docs, Doc } from './screens/docs.mjs';
 
 const HOME = { name: 'briefing' };
 
-export function App({ ctx }) {
+export function App({ ctx, initial }) {
   const { exit } = useApp();
-  const [stack, setStack] = useState([HOME]);
+  const [stack, setStack] = useState([initial ?? HOME]);
   const [fatal, setFatal] = useState(null);
 
   // ⭐ THE AUTH TAKEOVER HAS TO BE WIRED, not merely rendered. Every screen fetches
@@ -52,10 +55,22 @@ export function App({ ctx }) {
   const push = (screen) => setStack((s) => [...s, screen]);
   const pop = () => setStack((s) => (s.length > 1 ? s.slice(0, -1) : s));
 
+  // ⭐ ONE KEY TO EACH PLACE, FROM ANYWHERE. The previous build could only reach
+  // the graph by drilling through a GROUPED finding — and only 2 of 9 live
+  // findings are grouped, so most of the briefing was a dead end and tasks and
+  // docs still meant quitting and re-running with arguments.
+  //
+  // ⚠️ THESE REPLACE THE ROOT rather than pushing, so mashing g t d g cannot
+  // build a forty-deep stack that takes forty escapes to unwind. `esc` then means
+  // "back one step within a section", which is what it looks like it means.
   useInput((input, key) => {
     if (input === 'q' || (key.ctrl && input === 'c')) { exit(); return; }
     if (key.escape) { pop(); return; }
     if (fatal?.kind === 'auth' && input === 'l') { exit(); return; }
+    if (input === 'b') { setStack([HOME]); return; }
+    if (input === 'g') { setStack([{ name: 'graph' }]); return; }
+    if (input === 't') { setStack([{ name: 'tasks' }]); return; }
+    if (input === 'd') { setStack([{ name: 'docs' }]); return; }
   });
 
   if (fatal?.kind === 'auth') {
@@ -72,7 +87,20 @@ export function App({ ctx }) {
   const trail = stack.filter((s) => s.name === 'node').map((s) => s.target.label ?? s.target.id);
 
   let body;
-  if (top.name === 'briefing') {
+  if (top.name === 'graph') {
+    body = html`<${GraphHome} ctx=${wrapped} focused=${true}
+      onOpen=${(n) => push({ name: 'node', target: n })} />`;
+  } else if (top.name === 'tasks') {
+    body = html`<${Tasks} ctx=${wrapped} focused=${true}
+      onOpen=${(t) => push({ name: 'task', task: t })} />`;
+  } else if (top.name === 'task') {
+    body = html`<${Task} task=${top.task} />`;
+  } else if (top.name === 'docs') {
+    body = html`<${Docs} ctx=${wrapped} focused=${true}
+      onOpen=${(d) => push({ name: 'doc', doc: d })} />`;
+  } else if (top.name === 'doc') {
+    body = html`<${Doc} ctx=${wrapped} doc=${top.doc} focused=${true} />`;
+  } else if (top.name === 'briefing') {
     body = html`<${Briefing} ctx=${wrapped} focused=${true} onOpen=${(f) => push({ name: 'finding', finding: f })} />`;
   } else if (top.name === 'node') {
     body = html`<${NodeScreen}
@@ -109,19 +137,31 @@ export function App({ ctx }) {
     <//>`;
 }
 
-/** The keys that actually do something on THIS screen — never a generic legend. */
+/**
+ * The keys that actually do something on THIS screen — never a generic legend.
+ *
+ * ⚠️ ADVERTISING A KEY THAT DOES NOTHING teaches people the UI is unresponsive,
+ * which is worse than not mentioning it. The global jumps are appended once, in
+ * one place, so they cannot drift per screen.
+ */
+const JUMPS = 'b briefing · g graph · t tasks · d docs · q quit';
+
 function footerFor(top) {
-  if (top.name === 'briefing') return '↑↓ move · enter open · r refresh · q quit';
-  if (top.name === 'node') return '↑↓ move · enter walk in · esc back · r refresh · q quit';
+  if (top.name === 'briefing') return `↑↓ move · enter open · r refresh · ${JUMPS}`;
+  if (top.name === 'graph') return `↑↓ move · enter walk in · ${JUMPS}`;
+  if (top.name === 'tasks' || top.name === 'docs') return `↑↓ move · enter open · ${JUMPS}`;
+  if (top.name === 'task') return `esc back · ${JUMPS}`;
+  if (top.name === 'doc') return `j/k scroll · esc back · ${JUMPS}`;
+  if (top.name === 'node') return `↑↓ move · enter walk in · esc back · r refresh · ${JUMPS}`;
   if (top.name === 'finding') {
     // Only offer the key that works. A grouped finding has members to open; a
     // single one is an aggregate with nothing beneath it, and advertising `enter`
     // there teaches people the UI is unresponsive.
     return top.finding?.members?.length
-      ? '↑↓ move · enter open in graph · esc back · q quit'
-      : 'esc back · q quit';
+      ? `↑↓ move · enter open in graph · esc back · ${JUMPS}`
+      : `esc back · ${JUMPS}`;
   }
-  return 'esc back · q quit';
+  return `esc back · ${JUMPS}`;
 }
 
 export { HOME };

package/src/tui/launch.mjs

@@ -28,8 +28,14 @@ import { App } from './app.mjs';
 
 const SHOW_CURSOR = '\x1b[?25h';
 
-export async function startTui(ctx) {
-  const instance = render(html`<${App} ctx=${ctx} />`, {
+/**
+ * @param initial  the screen to open on. `mnema graph "X"` opens the walker AT X
+ *                 rather than at the briefing, because the command someone typed
+ *                 should do the thing they named — not drop them at a home screen
+ *                 with a keybinding to hunt for.
+ */
+export async function startTui(ctx, initial) {
+  const instance = render(html`<${App} ctx=${ctx} initial=${initial} />`, {
     // Ink's own exitOnCtrlC would leave our own key handling out of the loop.
     exitOnCtrlC: true,
   });

package/src/tui/screens/docs.mjs

@@ -0,0 +1,101 @@
+/**
+ * Documents, and one of them open (t-638).
+ *
+ * ⚠️ THE VIEWER DEPENDS ON THE SDK FIX IN t-637. docs.get asked for `data.doc`
+ * where the API returns the document directly in `data`, so it resolved to
+ * undefined and the one-shot `mnema doc` crashed on `d.title`. This screen shows
+ * a real error rather than a blank pane if it is ever undefined again — a viewer
+ * that renders nothing for a document that exists is the failure this codebase
+ * keeps producing.
+ */
+
+import { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { html } from '../h.mjs';
+import { useResource, ago } from '../store.mjs';
+import { List } from '../components/list.mjs';
+import { take } from '../../paging.mjs';
+
+export function Docs({ ctx, focused, onOpen }) {
+  const { status, data, error, elapsed, at } = useResource('docs', () =>
+    ctx.call((m) => take(m.docs.list({ limit: 40 }), 40)));
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Loading documents… ${elapsed > 1 ? `${elapsed}s` : ''}<//><//>`;
+  }
+  if (error && !data) {
+    return html`<${Box} paddingX=${1}><${Text} color="red">${error.message ?? String(error)}<//><//>`;
+  }
+
+  const rows = data?.rows ?? [];
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Box}>
+        <${Text} bold>Documents<//>
+        <${Text} dimColor>  ${rows.length}${data?.more ? '+' : ''} · ${ago(at)}<//>
+      <//>
+      ${rows.length === 0
+        ? html`<${Text} dimColor>No documents yet.<//>`
+        : html`<${List}
+            items=${rows.map((d) => ({
+              key: d.id,
+              left: String(d.updatedAt ?? '').slice(0, 10),
+              label: d.title ?? '(untitled)',
+            }))}
+            focused=${focused}
+            height=${12}
+            onSelect=${(i) => onOpen(rows[i])}
+          />`}
+    <//>`;
+}
+
+const PAGE = 16;
+
+export function Doc({ ctx, doc, focused }) {
+  const [top, setTop] = useState(0);
+  const { status, data, error, elapsed } = useResource(`doc:${doc?.id}`, () =>
+    ctx.call((m) => m.docs.get(doc.id)));
+
+  // ⚠️ EVERY HOOK BEFORE EVERY EARLY RETURN. React requires a stable call order,
+  // and this component returns early for loading, error and empty — so a
+  // useInput placed after those runs on some renders and not others, which is
+  // the "rendered fewer hooks than expected" crash. Guarding with `isActive`
+  // rather than by placement is what keeps the order fixed.
+  const lineCount = String(data?.markdown ?? '').split('\n').length;
+  useInput((input, key) => {
+    if (key.downArrow || input === 'j') setTop((t) => Math.min(Math.max(0, lineCount - PAGE), t + 1));
+    else if (key.upArrow || input === 'k') setTop((t) => Math.max(0, t - 1));
+    else if (input === ' ') setTop((t) => Math.min(Math.max(0, lineCount - PAGE), t + PAGE));
+  }, { isActive: Boolean(focused) && lineCount > PAGE });
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Opening ${doc?.title ?? ''}… ${elapsed > 1 ? `${elapsed}s` : ''}<//><//>`;
+  }
+  if (error) {
+    return html`<${Box} flexDirection="column" paddingX=${1}>
+      <${Text} color="red">${error.message ?? String(error)}<//>
+      <${Text} dimColor>esc to go back<//>
+    <//>`;
+  }
+  // ⚠️ NOT A BLANK PANE. If the SDK ever hands back undefined again, say so.
+  if (!data) {
+    return html`<${Box} paddingX=${1}>
+      <${Text} color="yellow">The API returned no document body for this id.<//>
+    <//>`;
+  }
+
+  const lines = String(data.markdown ?? '').split('\n');
+  const view = lines.slice(top, top + PAGE);
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Text} bold>${data.title ?? '(untitled)'}<//>
+      <${Text} dimColor>${data.path ?? ''} · updated ${String(data.updatedAt ?? '').slice(0, 10)}<//>
+      <${Box} flexDirection="column" marginTop=${1}>
+        ${view.map((l, i) => html`<${Text} key=${i}>${l || ' '}<//>`)}
+      <//>
+      ${lines.length > PAGE
+        ? html`<${Text} dimColor>  ${Math.min(top + PAGE, lines.length)}/${lines.length} lines · j/k to scroll<//>`
+        : null}
+    <//>`;
+}

package/src/tui/screens/graph-home.mjs

@@ -0,0 +1,61 @@
+/**
+ * A way INTO the graph (t-638).
+ *
+ * ⭐ THE GRAPH WAS UNREACHABLE. t-634 wired the node walker but the only door to
+ * it was drilling through a GROUPED finding — and only 2 of the 9 live findings
+ * are grouped, so for most of the briefing there was no way in at all. The most
+ * interesting thing Mnema knows had no entry point, which is exactly what "graph
+ * doesnt appear inside the cli ui" means.
+ *
+ * ⚠️ GOD NODES ARE THE RIGHT FRONT DOOR, and this is a judgement rather than a
+ * convenience. An alphabetical list of 900 concepts is a phone book: every entry
+ * equally weighted, none of them a starting point. godNodes() returns the
+ * structurally load-bearing ones — highest betweenness, largest blast radius —
+ * which is to say the places the graph is actually dense. Verified against prod:
+ * 12 hubs, each with label, type and a real summary.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+import { useResource, ago } from '../store.mjs';
+import { List } from '../components/list.mjs';
+
+export function GraphHome({ ctx, focused, onOpen }) {
+  const { status, data, error, elapsed, at } = useResource('graph:home', () =>
+    ctx.call((m) => m.graph.godNodes({ limit: 20 }).all()));
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}>
+      <${Text} dimColor>Finding the hubs… ${elapsed > 1 ? `${elapsed}s` : ''}<//>
+    <//>`;
+  }
+
+  if (error && !data) {
+    return html`<${Box} flexDirection="column" paddingX=${1}>
+      <${Text} color="red">${error.message ?? String(error)}<//>
+      <${Text} dimColor>The graph is a paid feature — this build or plan may not have it.<//>
+    <//>`;
+  }
+
+  const nodes = data ?? [];
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Box}>
+        <${Text} bold>Graph<//>
+        <${Text} dimColor>  ${nodes.length} hub${nodes.length === 1 ? '' : 's'} · ${ago(at)}<//>
+      <//>
+      <${Text} dimColor>The most connected nodes — start here and walk.<//>
+
+      ${nodes.length === 0
+        ? html`<${Box} marginTop=${1}><${Text} dimColor>No hubs yet. The graph needs more material before structure emerges.<//><//>`
+        : html`<${Box} marginTop=${1}>
+            <${List}
+              items=${nodes.map((n) => ({ key: n.id, left: String(n.type ?? ''), label: n.label ?? '(unlabelled)' }))}
+              focused=${focused}
+              height=${12}
+              onSelect=${(i) => onOpen(nodes[i])}
+            />
+          <//>`}
+    <//>`;
+}

package/src/tui/screens/tasks.mjs

@@ -0,0 +1,73 @@
+/**
+ * The board, without leaving the app (t-638).
+ *
+ * ⚠️ THE BRANCH NAME IS THE POINT. This project's whole dev loop hangs on naming
+ * the branch `t-<n>-<slug>` — it is the only signal that needs no cooperation
+ * from anything else. So the detail view's job is to hand that over ready to
+ * paste, exactly as the one-shot `mnema next` does.
+ */
+
+import { Box, Text } from 'ink';
+import { html } from '../h.mjs';
+import { useResource, ago } from '../store.mjs';
+import { List } from '../components/list.mjs';
+import { take } from '../../paging.mjs';
+
+const slugOf = (t) => String(t.title ?? '').toLowerCase()
+  .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
+
+export function Tasks({ ctx, focused, onOpen }) {
+  const { status, data, error, elapsed, at } = useResource('tasks', () =>
+    ctx.call((m) => take(m.tasks.list({ limit: 40 }), 40)));
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Loading tasks… ${elapsed > 1 ? `${elapsed}s` : ''}<//><//>`;
+  }
+  if (error && !data) {
+    return html`<${Box} paddingX=${1}><${Text} color="red">${error.message ?? String(error)}<//><//>`;
+  }
+
+  const rows = data?.rows ?? [];
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Box}>
+        <${Text} bold>Tasks<//>
+        <${Text} dimColor>  ${rows.length}${data?.more ? '+' : ''} · ${ago(at)}<//>
+      <//>
+      ${rows.length === 0
+        ? html`<${Text} dimColor>Nothing on the board.<//>`
+        : html`<${List}
+            items=${rows.map((t) => ({
+              key: t.id,
+              left: `${t.publicId ?? String(t.id).slice(0, 8)}  ${String(t.status ?? '')}`,
+              label: t.title ?? '',
+            }))}
+            focused=${focused}
+            height=${12}
+            onSelect=${(i) => onOpen(rows[i])}
+          />`}
+    <//>`;
+}
+
+export function Task({ task }) {
+  if (!task) return html`<${Box} paddingX=${1}><${Text} dimColor>Nothing selected.<//><//>`;
+  const slug = slugOf(task);
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Text} bold>${task.title ?? '(untitled)'}<//>
+      <${Box} marginTop=${1} flexDirection="column">
+        <${Box}><${Text} dimColor>id        <//><${Text} color="cyan">${task.publicId ?? task.id}<//><//>
+        <${Box}><${Text} dimColor>status    <//><${Text}>${task.status ?? '—'}<//><//>
+        <${Box}><${Text} dimColor>priority  <//><${Text}>${task.priority ?? '—'}<//><//>
+      <//>
+      ${task.description
+        ? html`<${Box} marginTop=${1}><${Text} dimColor>${String(task.description).replace(/\s+/g, ' ').slice(0, 400)}<//><//>`
+        : null}
+      ${task.publicId
+        ? html`<${Box} marginTop=${1} flexDirection="column">
+            <${Text} dimColor>branch<//>
+            <${Text}>git checkout -b ${task.publicId}${slug ? `-${slug}` : ''}<//>
+          <//>`
+        : null}
+    <//>`;
+}