@mnemahq/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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 @@
   },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",
-    "typecheck": "node --check bin/mnema.mjs && node --check src/cli.mjs && node --check src/util.mjs && node --check src/secrets.mjs && node --check src/client.mjs && node --check src/read-commands.mjs",
+    "typecheck": "node --check bin/mnema.mjs && node --check src/cli.mjs && node --check src/util.mjs && node --check src/secrets.mjs && node --check src/client.mjs && node --check src/read-commands.mjs && node --check test/version.test.mjs",
     "test": "vitest run"
   }
 }

package/src/cli.mjs

@@ -10,9 +10,9 @@
  *   mnema uninstall  cleanly reverse everything
  */
 
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { cmdLogin, cmdLogout, accessToken } from './login.mjs';
-import { makeClient, canAuthenticate, renderError } from './client.mjs';
+import { makeClient, call, hasApiKey, canAuthenticate, renderError, mintHookToken } from './client.mjs';
 import {
   cmdTasks, cmdNext, cmdDocs, cmdDoc, cmdProjects, cmdAsk, cmdGraph, cmdBriefing,
 } from './read-commands.mjs';
@@ -27,7 +27,25 @@ import {
 import { applyContext, scaffold } from './artifacts.mjs';
 import { execFileSync } from 'node:child_process';
 
-const VERSION = '0.1.0';
+/**
+ * ⚠️ READ FROM package.json, NEVER HAND-WRITTEN. This was `const VERSION =
+ * '0.1.0'` and stayed that way through 0.1.1 and 0.3.0 — so every release of
+ * this CLI reported the same wrong number, and `mnema --version` was useless for
+ * the one job it has.
+ *
+ * The cost was not cosmetic. After 0.3.0 shipped with eight new commands,
+ * `mnema --help` printed "mnema 0.1.0" and the old command list, because the
+ * global install was stale and npm does not upgrade an installed global when you
+ * publish. The right fix was one line — `npm i -g @mnemahq/cli@latest` — but a
+ * binary that misreports itself makes that undiagnosable, and the honest reading
+ * of the evidence was "you shipped nothing".
+ *
+ * Resolved relative to import.meta.url, not cwd: the CLI runs from whatever
+ * directory the user happens to be in. package.json is always in the tarball.
+ */
+const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
 
 function parseFlags(argv) {
   const flags = {}; const rest = [];
@@ -105,6 +123,26 @@ async function cmdInit(flags) {
   if (!workspaceId) { console.error(c.red('A workspace id is required.')); process.exit(1); }
 
   let hookToken = process.env.MNEMA_HOOK_TOKEN || getSecret(workspaceId, 'hook-token');
+
+  // ⚠️ ONLY MINT WHEN THERE IS NOTHING STORED. Minting ROTATES — the server keeps
+  // a hash, so `regenerate` is the only way to obtain a token and it invalidates
+  // the previous one. Re-running `init` on a second machine must not silently
+  // kill capture on the first.
+  if (!hookToken) {
+    process.stdout.write('Getting a hook token… ');
+    const minted = await mintHookToken({ origin, workspaceId });
+    if (minted) {
+      hookToken = minted;
+      console.log(c.green('done'));
+      console.log(c.dim('  A new token was issued. Any OTHER machine set up for this workspace'));
+      console.log(c.dim('  must re-run `mnema init` — the previous token no longer works.'));
+    } else {
+      // Not logged in, not the owner (the endpoint is owner-only), or offline.
+      // Fall through to asking, with the right pointer.
+      console.log(c.dim('not available — enter one manually'));
+    }
+  }
+
   if (!hookToken) {
     // ⚠️ NOT "Settings → Developer". That page does not exist and never did in
     // this shape — the hook token moved to the Access page when tokens were
@@ -215,9 +253,8 @@ async function cmdSessions(flags) {
   const repo = canonicalRepo(git.remote);
   let rows = [];
   try {
-    rows = await makeClient({ origin, workspaceId })
-      .sessions.list({ limit, ...(repo ? { repo } : {}) })
-      .all();
+    rows = await call({ origin, workspaceId }, (m) =>
+      m.sessions.list({ limit, ...(repo ? { repo } : {}) }).all());
   } catch (e) {
     // Non-fatal by design: the LOCAL list above is the useful half and has
     // already printed. Degrading here is deliberate, and it says which wall it
@@ -260,8 +297,8 @@ async function cmdSearch(flags, rest) {
 
   let results = [];
   try {
-    results = await makeClient({ origin, workspaceId }).docs.search(query);
-  } catch (e) { renderError(e, { context: 'search' }); }
+    results = await call({ origin, workspaceId }, (m) => m.docs.search(query));
+  } catch (e) { renderError(e, { context: 'search', usedApiKey: hasApiKey(workspaceId) }); }
   if (!results.length) { console.log(c.dim('No results.')); return; }
   console.log(c.bold(`${results.length} result(s) for "${query}"`));
   for (const d of results) {
@@ -285,8 +322,8 @@ async function cmdPull(flags) {
   try {
     // `.context`, not the whole result — `.repo` is the URL the server matched.
     // Reading the wrong one of these two is the bug this rewire found in the SDK.
-    docs = (await makeClient({ origin, workspaceId }).repos.context(repo)).context ?? [];
-  } catch (e) { renderError(e, { context: 'pull' }); }
+    docs = (await call({ origin, workspaceId }, (m) => m.repos.context(repo))).context ?? [];
+  } catch (e) { renderError(e, { context: 'pull', usedApiKey: hasApiKey(workspaceId) }); }
 
   scaffold(root);
   const s = applyContext(root, docs);
@@ -329,6 +366,9 @@ async function cmdDoctor(flags) {
   const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : null;
   if (apiKey) {
     let keyOk = false;
+    // Probes the KEY specifically — no fallback — because that is the thing
+    // doctor is reporting on. Using call() here would mask a dead key behind a
+    // working login and print a green tick for a credential that does not work.
     try { await makeClient({ origin, workspaceId }).docs.list({ limit: 1 }).pages().next(); keyOk = true; } catch { /* */ }
     ok('API key valid', keyOk);
   } else {

package/src/client.mjs

@@ -28,8 +28,8 @@ import { c, DEFAULT_APP_URL } from './util.mjs';
  * request — that is what makes a refresh mid-command work instead of failing on
  * a token that expired thirty seconds ago.
  */
-export function makeClient({ origin, workspaceId }) {
-  const apiKey = (workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY || null;
+export function makeClient({ origin, workspaceId, forceLogin = false }) {
+  const apiKey = forceLogin ? null : ((workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY || null);
   return new Mnema(
     apiKey
       ? { apiKey, baseUrl: origin }
@@ -37,6 +37,45 @@ export function makeClient({ origin, workspaceId }) {
   );
 }
 
+/**
+ * Run an SDK call, and if a STORED API KEY is rejected, retry once with the login.
+ *
+ * ⭐ THE TRAP THIS REMOVES. makeClient prefers an explicit API key, which is right
+ * — a key is scoped and deliberate. But a DEAD key then shadows a perfectly good
+ * login forever, and the failure told the user to do the one thing that could not
+ * help:
+ *
+ *     $ mnema docs      -> not authenticated. Run `mnema login`.
+ *     $ mnema login     -> ✓ Logged in.
+ *     $ mnema docs      -> not authenticated. Run `mnema login`.
+ *
+ * The login was never the credential in play. An instruction that cannot work is
+ * worse than none: it spends the reader's remaining trust in the tool.
+ *
+ * ⚠️ THE SDK CANNOT DO THIS FOR US. packages/core resolves `Bearer apiKey`
+ * whenever apiKey is set and never consults getToken, so `onUnauthorized` can
+ * ask for a retry but cannot change which credential the retry uses. The swap has
+ * to happen out here, by building a second client.
+ *
+ * ⚠️ AND IT IS ANNOUNCED, not silent. Quietly using a different identity than the
+ * one configured is its own confusion — the next question would be "which
+ * credential ran this?", and the answer should not require reading source.
+ */
+export async function call(ctx, fn) {
+  try {
+    return await fn(makeClient(ctx));
+  } catch (e) {
+    const isAuth = e?.constructor?.name === 'AuthError';
+    if (!isAuth || ctx.forceLogin || !hasApiKey(ctx.workspaceId)) throw e;
+    let loggedIn = false;
+    try { loggedIn = Boolean(await accessToken()); } catch { /* no login */ }
+    if (!loggedIn) throw e;
+    console.error(c.yellow('  stored API key was rejected — using your login instead.'));
+    console.error(c.dim('  Run `mnema init` to replace the key, or ignore this if you meant to use the login.'));
+    return await fn(makeClient({ ...ctx, forceLogin: true }));
+  }
+}
+
 /** True when an explicit API key is configured. Cheap; no network. */
 export function hasApiKey(workspaceId) {
   return Boolean((workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY);
@@ -73,14 +112,24 @@ export async function canAuthenticate(workspaceId) {
  * branch — turning a good message back into a bad one for the exact reason this
  * function exists.
  */
-export function renderError(e, { context = '' } = {}) {
+export function renderError(e, { context = '', usedApiKey = false } = {}) {
+  const opts = { usedApiKey };
   const name = e?.constructor?.name ?? '';
   const where = context ? `${context}: ` : '';
 
   switch (name) {
     case 'AuthError':
       console.error(c.red(`${where}not authenticated.`));
-      console.error(`  ${e.fix ?? 'Run `mnema login`.'}`);
+      // ⚠️ NAME THE CREDENTIAL THAT FAILED. The SDK's generic fix is "Run `mnema
+      // login`", which is exactly wrong when the thing that was rejected is a
+      // stored API KEY and a valid login already exists — the user runs it,
+      // succeeds, and nothing changes.
+      if (opts.usedApiKey) {
+        console.error('  The stored API key was rejected.');
+        console.error('  Run `mnema init` to replace it, or `mnema login` to use a login instead.');
+      } else {
+        console.error(`  ${e.fix ?? 'Run `mnema login`.'}`);
+      }
       break;
 
     case 'PlanRequiredError':
@@ -126,3 +175,43 @@ export function renderError(e, { context = '' } = {}) {
   }
   process.exit(1);
 }
+
+/**
+ * Mint a hook token for this workspace, using the login (t-627).
+ *
+ * ⭐ WHY THIS EXISTS. Setting up a repo meant fetching three things from two
+ * settings pages. The workspace id now comes from /api/me and the API key is
+ * optional — this was the last piece of copy-paste, and it never needed to be one:
+ * the endpoint has existed all along and has accepted a bearer token since t-613.
+ *
+ * ⚠️ THE HOOK TOKEN CANNOT SIMPLY BE THE LOGIN, and that is deliberate rather than
+ * unfinished. installHook writes it in PLAINTEXT to ~/.claude/mnema-hook.json,
+ * where an unattended process reads it after every session. A narrow,
+ * single-purpose token belongs in a file like that; an OAuth refresh token — which
+ * can mint access tokens for the whole account — does not.
+ *
+ * ⚠️ AND MINTING ROTATES. The server keeps only a HASH, so there is no way to read
+ * an existing token back; `regenerate` is the only path and it invalidates the old
+ * one. Callers MUST check for a stored token first — minting unconditionally would
+ * silently break capture on every other machine the user has set up. That check
+ * lives in cmdInit, not here, because this function's job is to mint and it should
+ * not pretend otherwise.
+ *
+ * Returns null rather than throwing: not logged in, not the owner (the endpoint is
+ * owner-only), or offline are all ordinary, and the caller falls back to asking.
+ */
+export async function mintHookToken({ origin, workspaceId }) {
+  try {
+    const token = await accessToken();
+    if (!token) return null;
+    const res = await fetch(`${origin}/api/workspaces/${workspaceId}/regenerate-hook-token`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body?.hookToken ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/read-commands.mjs

@@ -20,7 +20,7 @@
  * returns the shape worth emitting, so it costs one line each.
  */
 
-import { makeClient, canAuthenticate, renderError } from './client.mjs';
+import { call, hasApiKey, canAuthenticate, renderError } from './client.mjs';
 import { c } from './util.mjs';
 
 /** Machine output is the whole object; humans get the formatted view. */
@@ -42,11 +42,11 @@ export async function cmdTasks(flags, ctx) {
   await guard(ctx.workspaceId);
   const limit = Number(flags.limit) || 20;
   try {
-    const rows = await makeClient(ctx).tasks.list({
+    const rows = await call(ctx, (m) => m.tasks.list({
       limit,
       ...(flags.status ? { status: flags.status } : {}),
       ...(flags.project ? { project: flags.project } : {}),
-    }).all();
+    }).all());
     emit(flags, rows, () => {
       if (!rows.length) return console.log(c.dim('No tasks match.'));
       console.log(c.bold(`${rows.length} task(s)`));
@@ -55,13 +55,13 @@ export async function cmdTasks(flags, ctx) {
         console.log(`  ${c.cyan(id)} ${String(t.status).padEnd(12)} ${c.dim(String(t.priority).padEnd(8))} ${trunc(t.title, 70)}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'tasks' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'tasks' }); }
 }
 
 export async function cmdNext(flags, ctx) {
   await guard(ctx.workspaceId);
   try {
-    const t = await makeClient(ctx).tasks.next();
+    const t = await call(ctx, (m) => m.tasks.next());
     emit(flags, t, () => {
       if (!t) return console.log(c.dim('Nothing queued — the board is clear.'));
       console.log(`${c.bold(t.publicId || t.id)}  ${t.title}`);
@@ -73,7 +73,7 @@ export async function cmdNext(flags, ctx) {
         console.log(`\n  ${c.dim('branch:')} git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'next' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'next' }); }
 }
 
 // ── docs ──────────────────────────────────────────────────────────────────────
@@ -81,7 +81,7 @@ export async function cmdDocs(flags, ctx) {
   await guard(ctx.workspaceId);
   const limit = Number(flags.limit) || 20;
   try {
-    const rows = await makeClient(ctx).docs.list({ limit }).all();
+    const rows = await call(ctx, (m) => m.docs.list({ limit }).all());
     emit(flags, rows, () => {
       if (!rows.length) return console.log(c.dim('No docs.'));
       console.log(c.bold(`${rows.length} doc(s)`));
@@ -89,7 +89,7 @@ export async function cmdDocs(flags, ctx) {
         console.log(`  ${c.dim(d.id.slice(0, 8))}  ${trunc(d.title, 60).padEnd(60)} ${c.dim(String(d.updatedAt).slice(0, 10))}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'docs' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'docs' }); }
 }
 
 export async function cmdDoc(flags, ctx, rest) {
@@ -97,7 +97,7 @@ export async function cmdDoc(flags, ctx, rest) {
   const id = rest[0];
   if (!id) { console.error(c.red('Usage: mnema doc <id>')); process.exit(1); }
   try {
-    const d = await makeClient(ctx).docs.get(id);
+    const d = await call(ctx, (m) => m.docs.get(id));
     // Markdown goes to stdout unadorned so `mnema doc <id> > file.md` works and
     // the heading is not silently baked into the file.
     emit(flags, d, () => {
@@ -105,20 +105,20 @@ export async function cmdDoc(flags, ctx, rest) {
       console.error(c.dim(`${d.path} · updated ${String(d.updatedAt).slice(0, 10)}`));
       if (d.markdown) console.log(d.markdown);
     });
-  } catch (e) { renderError(e, { context: 'doc' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'doc' }); }
 }
 
 // ── projects ──────────────────────────────────────────────────────────────────
 export async function cmdProjects(flags, ctx) {
   await guard(ctx.workspaceId);
   try {
-    const rows = await makeClient(ctx).projects.list().all();
+    const rows = await call(ctx, (m) => m.projects.list().all());
     emit(flags, rows, () => {
       if (!rows.length) return console.log(c.dim('No projects.'));
       console.log(c.bold(`${rows.length} project(s)`));
       for (const p of rows) console.log(`  ${c.dim(p.id.slice(0, 8))}  ${trunc(p.name, 50)}`);
     });
-  } catch (e) { renderError(e, { context: 'projects' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'projects' }); }
 }
 
 // ── graph: ask + traverse ─────────────────────────────────────────────────────
@@ -127,7 +127,7 @@ export async function cmdAsk(flags, ctx, rest) {
   const q = rest.join(' ').trim();
   if (!q) { console.error(c.red('Usage: mnema ask "<question>"')); process.exit(1); }
   try {
-    const a = await makeClient(ctx).graph.ask(q, { ...(flags.budget ? { budgetMs: Number(flags.budget) } : {}) });
+    const a = await call(ctx, (m) => m.graph.ask(q, { ...(flags.budget ? { budgetMs: Number(flags.budget) } : {}) }));
     emit(flags, a, () => {
       console.log(a.answer);
       // ⚠️ NEVER WITHOUT THE CONFIDENCE. The interpreter deliberately hedges
@@ -142,7 +142,7 @@ export async function cmdAsk(flags, ctx, rest) {
         for (const s of a.sources.slice(0, 5)) console.log(c.dim(`  ${trunc(s.title, 70)}`));
       }
     });
-  } catch (e) { renderError(e, { context: 'ask' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'ask' }); }
 }
 
 export async function cmdGraph(flags, ctx, rest) {
@@ -150,7 +150,7 @@ export async function cmdGraph(flags, ctx, rest) {
   const [from, to] = rest;
   if (!from) { console.error(c.red('Usage: mnema graph <from> [to]')); process.exit(1); }
   try {
-    const g = await makeClient(ctx).graph.traverse(from, to);
+    const g = await call(ctx, (m) => m.graph.traverse(from, to));
     emit(flags, g, () => {
       if (to) {
         // connected:false is an ANSWER, not a failure — say so plainly rather
@@ -166,14 +166,14 @@ export async function cmdGraph(flags, ctx, rest) {
       console.log(c.bold(`${g.nodes.length} node(s), ${g.edges.length} edge(s) around "${from}"`));
       for (const n of g.nodes.slice(0, 25)) console.log(`  ${trunc(n.label, 60).padEnd(60)} ${c.dim(n.type ?? '')}`);
     });
-  } catch (e) { renderError(e, { context: 'graph' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'graph' }); }
 }
 
 // ── briefing ──────────────────────────────────────────────────────────────────
 export async function cmdBriefing(flags, ctx) {
   await guard(ctx.workspaceId);
   try {
-    const b = await makeClient(ctx).findings.briefing();
+    const b = await call(ctx, (m) => m.findings.briefing());
     emit(flags, b, () => {
       const p = b.pulse;
       console.log(c.bold('Pulse'));
@@ -192,5 +192,5 @@ export async function cmdBriefing(flags, ctx) {
         console.log(`  ${c.dim(String(f.kind).padEnd(14))} ${trunc(f.headline, 90)}${count}`);
       }
     });
-  } catch (e) { renderError(e, { context: 'briefing' }); }
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'briefing' }); }
 }