@mnemahq/cli 0.10.0 → 0.11.0

package/package.json

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

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

@@ -26,9 +26,9 @@ 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

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,
   });