@mnemahq/cli 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.10.0",
+  "version": "0.12.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.4.0"
+    "@mnemahq/sdk": "0.4.1"
   },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",

package/src/cli.mjs

@@ -15,6 +15,7 @@ import { cmdLogin, cmdLogout, accessToken } from './login.mjs';
 import { makeClient, call, hasApiKey, canAuthenticate, renderError, mintHookToken } from './client.mjs';
 import {
   cmdTasks, cmdNext, cmdDocs, cmdDoc, cmdProjects, cmdAsk, cmdGraph, cmdBriefing,
+  cmdFlows, cmdFlow,
 } from './read-commands.mjs';
 import {
   DEFAULT_ORIGIN, DEFAULT_APP_URL, c, truncate, width, mark, gitInfo, canonicalRepo, readConfig, writeConfig,
@@ -510,17 +511,22 @@ 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
   docs         List documents        [--limit]
   doc [id]     Print one document as markdown; no id opens a picker
   projects     List projects
+  flows        List flows
+  flow [slug]  One flow; no slug opens a picker
   briefing     What deserves attention — pulse, deltas, findings
 
 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 +571,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' || cmd === 'flows') 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 +661,29 @@ 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 'flows':
+      if (await maybeInteractive(flags, screenFor('flows', flags))) return 0;
+      return cmdFlows(flags, resolveContext(flags));
+    case 'flow':      return cmdFlow(flags, resolveContext(flags), rest);
     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/read-commands.mjs

@@ -27,7 +27,7 @@
 import { call, hasApiKey, canAuthenticate, renderError } from './client.mjs';
 import { take } from './paging.mjs';
 import { c, truncate, link, mark } from './util.mjs';
-import { heading, empty, rows, more, copyable } from './render/layout.mjs';
+import { heading, entries, empty, rows, more, copyable } from './render/layout.mjs';
 import { pick } from './render/pick.mjs';
 
 /** Machine output is the whole object; humans get the formatted view. */
@@ -274,3 +274,64 @@ export async function cmdBriefing(flags, ctx) {
     });
   } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'briefing' }); }
 }
+
+// ── flows ─────────────────────────────────────────────────────────────────────
+
+/**
+ * ⚠️ THE PUBLIC FLOW ENDPOINT RETURNS METADATA ONLY — no nodes, no steps, no run
+ * history. Rendering a "Steps" heading with nothing under it would be the exact
+ * silent-empty failure this codebase is named for: it would read as "this flow
+ * has no steps" when it means "this endpoint does not serve them". So the detail
+ * shows what is genuinely there and says where the rest lives.
+ */
+export async function cmdFlows(flags, ctx) {
+  await guard(ctx.workspaceId);
+  const limit = limitOf(flags, 50);
+  try {
+    const page = await call(ctx, (m) => take(m.flows.list(), limit));
+    emit(flags, page.rows, () => {
+      heading('Flows', page.rows.length);
+      if (!page.rows.length) return empty('No flows yet.', 'Build one in the app and it shows up here.');
+      rows(page.rows.map((f) => ({
+        cells: [f.slug ?? '', f.name ?? ''],
+        style: [c.cyan, undefined],
+      })));
+      more(page.more, `mnema flows --limit ${limit * 2}`);
+    });
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'flows' }); }
+}
+
+export async function cmdFlow(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  let slug = rest[0];
+  const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+  if (!slug && !flags.json && interactive) {
+    const page = await call(ctx, (m) => take(m.flows.list(), 50)).catch(() => null);
+    if (page?.rows.length) {
+      const chosen = await pick(page.rows.map((f) => ({ label: `${f.name ?? f.slug}` })), { title: 'Which flow?' });
+      if (chosen === null) return;
+      slug = page.rows[chosen].slug;
+    }
+  }
+  if (!slug) {
+    console.error(c.red('Usage: mnema flow <slug>'));
+    console.error(c.dim('  Run it without a slug in a terminal to pick from a list.'));
+    process.exit(1);
+  }
+  try {
+    const f = await call(ctx, (m) => m.flows.get(slug));
+    emit(flags, f, () => {
+      heading(f.name ?? slug);
+      entries([
+        { label: 'slug', value: f.slug ?? slug },
+        { label: 'published', value: f.publishedVersionId ? 'yes' : 'draft', state: Boolean(f.publishedVersionId) },
+        ...(f.projectId ? [{ label: 'project', value: f.projectId }] : []),
+        { label: 'updated', value: String(f.updatedAt ?? '').slice(0, 10), dim: true },
+      ]);
+      if (f.description) console.log(`\n  ${c.dim(f.description)}`);
+      // Saying this is the point: the absence of steps here is the endpoint's
+      // shape, not the flow's emptiness.
+      console.log(c.dim('\n  Steps and runs are not on the public API — open the flow in the app to walk it.'));
+    });
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'flow' }); }
+}

package/src/tui/app.mjs

@@ -23,12 +23,13 @@ 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';
+import { Flows, Flow } from './screens/flows.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
@@ -71,6 +72,7 @@ export function App({ ctx }) {
     if (input === 'g') { setStack([{ name: 'graph' }]); return; }
     if (input === 't') { setStack([{ name: 'tasks' }]); return; }
     if (input === 'd') { setStack([{ name: 'docs' }]); return; }
+    if (input === 'f') { setStack([{ name: 'flows' }]); return; }
   });
 
   if (fatal?.kind === 'auth') {
@@ -100,6 +102,11 @@ export function App({ ctx }) {
       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 === 'flows') {
+    body = html`<${Flows} ctx=${wrapped} focused=${true}
+      onOpen=${(f) => push({ name: 'flow', flow: f })} />`;
+  } else if (top.name === 'flow') {
+    body = html`<${Flow} ctx=${wrapped} flow=${top.flow} />`;
   } else if (top.name === 'briefing') {
     body = html`<${Briefing} ctx=${wrapped} focused=${true} onOpen=${(f) => push({ name: 'finding', finding: f })} />`;
   } else if (top.name === 'node') {
@@ -144,13 +151,13 @@ export function App({ ctx }) {
  * 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';
+const JUMPS = 'b briefing · g graph · t tasks · d docs · f flows · q quit';
 
 function footerFor(top) {
   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 === 'tasks' || top.name === 'docs' || top.name === 'flows') return `↑↓ move · enter open · ${JUMPS}`;
+  if (top.name === 'task' || top.name === 'flow') 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') {

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/flows.mjs

@@ -0,0 +1,77 @@
+/**
+ * Flows (t-640).
+ *
+ * ⚠️ THE PUBLIC ENDPOINT SERVES METADATA ONLY — no nodes, no steps, no runs. A
+ * "Steps" heading with nothing under it would read as "this flow is empty" when
+ * it means "this endpoint does not serve them", which is exactly the silent-empty
+ * failure this codebase is named for. So the detail shows what is genuinely there
+ * and names where the rest lives.
+ */
+
+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';
+
+export function Flows({ ctx, focused, onOpen }) {
+  const { status, data, error, elapsed, at } = useResource('flows', () =>
+    ctx.call((m) => take(m.flows.list(), 60)));
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Loading flows… ${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>Flows<//>
+        <${Text} dimColor>  ${rows.length}${data?.more ? '+' : ''} · ${ago(at)}<//>
+      <//>
+      ${rows.length === 0
+        ? html`<${Text} dimColor>No flows yet.<//>`
+        : html`<${List}
+            items=${rows.map((f) => ({ key: f.id ?? f.slug, left: f.slug ?? '', label: f.name ?? '' }))}
+            focused=${focused}
+            height=${12}
+            onSelect=${(i) => onOpen(rows[i])}
+          />`}
+    <//>`;
+}
+
+export function Flow({ ctx, flow }) {
+  const { status, data, error, elapsed } = useResource(`flow:${flow?.slug}`, () =>
+    ctx.call((m) => m.flows.get(flow.slug)));
+
+  if (status === 'loading') {
+    return html`<${Box} paddingX=${1}><${Text} dimColor>Opening ${flow?.name ?? ''}… ${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<//>
+    <//>`;
+  }
+  const f = data ?? flow ?? {};
+
+  return html`
+    <${Box} flexDirection="column" paddingX=${1}>
+      <${Text} bold>${f.name ?? f.slug ?? '(unnamed)'}<//>
+      <${Box} flexDirection="column" marginTop=${1}>
+        <${Box}><${Text} dimColor>slug       <//><${Text} color="cyan">${f.slug ?? ''}<//><//>
+        <${Box}><${Text} dimColor>published  <//>
+          <${Text} color=${f.publishedVersionId ? 'green' : undefined}>${f.publishedVersionId ? 'yes' : 'draft'}<//><//>
+        <${Box}><${Text} dimColor>updated    <//><${Text}>${String(f.updatedAt ?? '').slice(0, 10)}<//><//>
+      <//>
+      ${f.description
+        ? html`<${Box} marginTop=${1}><${Text} dimColor>${f.description}<//><//>`
+        : null}
+      <${Box} marginTop=${1}>
+        <${Text} dimColor>Steps and runs are not on the public API — open the flow in the app to walk it.<//>
+      <//>
+    <//>`;
+}