@mnemahq/cli 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.9.0",
+  "version": "0.10.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/tui/app.mjs

@@ -20,6 +20,9 @@ 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' };
 
@@ -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/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}
+    <//>`;
+}