@mnemahq/cli 0.1.1 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.1.1",
+  "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": {
@@ -29,9 +29,12 @@
   "devDependencies": {
     "vitest": "^3.2.7"
   },
+  "dependencies": {
+    "@mnemahq/sdk": "0.3.1"
+  },
   "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",
+    "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,8 +10,12 @@
  *   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, call, hasApiKey, canAuthenticate, renderError, mintHookToken } from './client.mjs';
+import {
+  cmdTasks, cmdNext, cmdDocs, cmdDoc, cmdProjects, cmdAsk, cmdGraph, cmdBriefing,
+} from './read-commands.mjs';
 import {
   DEFAULT_ORIGIN, DEFAULT_APP_URL, c, gitInfo, canonicalRepo, readConfig, writeConfig, removeConfigDir,
   apiFetch, prompt, promptHidden, localSessionsForRepo,
@@ -23,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 = [];
@@ -71,14 +93,13 @@ function fmtAge(mtimeMs) {
  */
 async function workspaceFromSession(origin) {
   try {
-    const token = await accessToken();
-    if (!token) return null;
-    const res = await fetch(`${origin}/api/me`, { headers: { Authorization: `Bearer ${token}` } });
-    if (!res.ok) return null;
-    const body = await res.json();
-    if (!body?.workspace_id) return null;
-    console.log(c.green(`\u2713 Workspace: ${body.workspace_name || body.workspace_id} (from your login)`));
-    return body.workspace_id;
+    if (!(await accessToken())) return null;
+    // Via the SDK: /api/public/v1/me returns camelCase, and the SDK is the only
+    // thing that should know that.
+    const me = await makeClient({ origin }).me();
+    if (!me?.workspaceId) return null;
+    console.log(c.green(`\u2713 Workspace: ${me.workspaceName || me.workspaceId} (from your login)`));
+    return me.workspaceId;
   } catch {
     return null;
   }
@@ -102,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
@@ -204,15 +245,23 @@ async function cmdSessions(flags) {
     console.log(`  ${s.sessionId.slice(0, 8)}…  ${fmtAge(s.mtimeMs).padStart(8)}  ${c.dim((s.sizeBytes / 1024).toFixed(0) + ' KB')}`);
   }
 
-  const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : null;
-  if (!apiKey) { console.log(c.dim('\n  (add an API key via `mnema init` to see server-side cost + status)')); return; }
+  if (!(await canAuthenticate(workspaceId))) {
+    console.log(c.dim('\n  (run `mnema login` — or add an API key — to see server-side cost + status)'));
+    return;
+  }
 
   const repo = canonicalRepo(git.remote);
-  const q = new URLSearchParams({ limit: String(limit) });
-  if (repo) q.set('repo', repo);
-  const r = await apiFetch(origin, `/api/public/v1/sessions?${q}`, { token: apiKey });
-  if (!r.ok) { console.log(c.yellow(`\n  server sessions unavailable (HTTP ${r.status})`)); return; }
-  const rows = r.json?.data?.sessions ?? [];
+  let rows = [];
+  try {
+    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
+    // hit rather than a bare HTTP number.
+    console.log(c.yellow(`\n  server sessions unavailable — ${e?.message ?? e}`));
+    return;
+  }
   console.log(c.bold(`\nServer sessions (${rows.length})`));
   for (const s of rows) {
     const cost = typeof s.totalCostUsd === 'number' ? `$${s.totalCostUsd.toFixed(4)}` : '$0';
@@ -241,12 +290,15 @@ async function cmdSearch(flags, rest) {
   const { origin, workspaceId } = resolveContext(flags);
   const query = rest.join(' ').trim();
   if (!query) { console.error(c.red('Usage: mnema search "<query>"')); process.exit(1); }
-  const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : (process.env.MNEMA_API_KEY || null);
-  if (!apiKey) { console.error(c.red('Search needs an API key. Run `mnema init` and provide one.')); process.exit(1); }
+  if (!(await canAuthenticate(workspaceId))) {
+    console.error(c.red('Search needs a credential — run `mnema login`, or `mnema init` with an API key.'));
+    process.exit(1);
+  }
 
-  const r = await apiFetch(origin, `/api/public/v1/docs/search?q=${encodeURIComponent(query)}`, { token: apiKey });
-  if (!r.ok) { console.error(c.red(`Search failed (HTTP ${r.status}): ${r.json?.error?.message || r.text || ''}`)); process.exit(1); }
-  const results = r.json?.data?.results ?? [];
+  let results = [];
+  try {
+    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) {
@@ -261,12 +313,17 @@ async function cmdPull(flags) {
   const { git, root, origin, workspaceId } = resolveContext(flags);
   const repo = flags.repo || canonicalRepo(git.remote);
   if (!repo) { console.error(c.red('No git remote to identify this repo. Set one, or pass --repo <url>.')); process.exit(1); }
-  const apiKey = (workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY;
-  if (!apiKey) { console.error(c.red('`mnema pull` needs an API key. Run `mnema init` and provide one.')); process.exit(1); }
+  if (!(await canAuthenticate(workspaceId))) {
+    console.error(c.red('`mnema pull` needs a credential — run `mnema login`, or `mnema init` with an API key.'));
+    process.exit(1);
+  }
 
-  const r = await apiFetch(origin, `/api/public/v1/repo-context?repo=${encodeURIComponent(repo)}`, { token: apiKey });
-  if (!r.ok) { console.error(c.red(`Pull failed (HTTP ${r.status}): ${r.json?.error?.message || r.text || ''}`)); process.exit(1); }
-  const docs = r.json?.data?.context ?? [];
+  let docs = [];
+  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 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);
@@ -308,7 +365,11 @@ async function cmdDoctor(flags) {
 
   const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : null;
   if (apiKey) {
-    let keyOk = false; try { keyOk = (await apiFetch(origin, '/api/public/v1/docs?limit=1', { token: apiKey })).ok; } catch { /* */ }
+    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 {
     ok('API key stored', false, 'optional — needed for search/sessions');
@@ -359,10 +420,23 @@ Commands:
   doctor       Diagnose install, hooks, auth, connectivity
   uninstall    Remove hooks and stored secrets
 
+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
+  projects     List projects
+  briefing     What deserves attention — pulse, deltas, findings
+
+Ask the knowledge graph (paid feature):
+  ask "q"      A cited answer, with the confidence it deserves
+  graph <a> [b]  Neighbourhood of a, or the shortest path from a to b
+
 Options:
   --workspace <id>   Workspace id (else prompted / MNEMA_WORKSPACE_ID)
   --origin <url>     API origin (default ${DEFAULT_ORIGIN})
-  --limit <n>        Row limit for sessions
+  --limit <n>        Row limit
+  --json             Machine-readable output (every read command)
   --yes              Non-interactive; skip optional prompts
   --purge            uninstall: also delete .mnema/config.json
   --version, --help
@@ -384,6 +458,17 @@ export async function run(argv) {
     case 'search':    return cmdSearch(flags, rest);
     case 'doctor':    return cmdDoctor(flags);
     case 'uninstall': return cmdUninstall(flags);
+
+    // 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 'next':      return cmdNext(flags, resolveContext(flags));
+    case 'docs':      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 undefined:
     case 'help':      return help();
     default:

package/src/client.mjs

@@ -0,0 +1,217 @@
+/**
+ * The one place the CLI talks to Mnema — through @mnemahq/sdk (§A2).
+ *
+ * ⭐ WHY THE RULE EXISTS, DEMONSTRATED THE HOUR IT WAS FOLLOWED. Rewiring the
+ * first command onto the SDK immediately turned up that `repos.context()` had
+ * been unwrapping the wrong envelope key since it shipped — it returned the repo
+ * URL string instead of the documents. The CLI's own raw fetch read the right key
+ * and had been right all along. An SDK its own CLI routes around has no first
+ * user, so its mistakes are found by everyone else instead.
+ *
+ * ⚠️ NOT EVERY REQUEST BELONGS HERE. `/install/mnema-hook.mjs` is a static asset,
+ * not an API call, and stays on plain fetch in hook-install.mjs. Routing it
+ * through a typed API client would imply an envelope and a credential that the
+ * endpoint neither sends nor wants.
+ */
+
+import { Mnema } from '@mnemahq/sdk';
+import { getSecret } from './secrets.mjs';
+import { accessToken } from './login.mjs';
+import { c, DEFAULT_APP_URL } from './util.mjs';
+
+/**
+ * A client carrying whichever credential this machine actually has.
+ *
+ * Order is deliberate: an API key is explicit, scoped, and what CI uses, so it
+ * wins. The OAuth token from `mnema login` is the human fallback. `getToken` is
+ * passed as a FUNCTION rather than a resolved string so the SDK re-reads it per
+ * 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, forceLogin = false }) {
+  const apiKey = forceLogin ? null : ((workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY || null);
+  return new Mnema(
+    apiKey
+      ? { apiKey, baseUrl: origin }
+      : { getToken: accessToken, baseUrl: origin },
+  );
+}
+
+/**
+ * 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);
+}
+
+/**
+ * True when this machine can authenticate AT ALL — by key or by login.
+ *
+ * ⭐ THE COMMANDS USED TO DEMAND A KEY, and that was a leftover from before the
+ * public API accepted both. `/api/public/v1` has taken an OAuth access token
+ * since the login flow shipped, so "Search needs an API key" was refusing work
+ * the server would happily have done for someone who had already run
+ * `mnema login`. Asking a person to go generate a credential they do not need is
+ * the kind of friction that makes a tool feel broken.
+ */
+export async function canAuthenticate(workspaceId) {
+  if (hasApiKey(workspaceId)) return true;
+  try { return Boolean(await accessToken()); } catch { return false; }
+}
+
+/**
+ * Turn a thrown SDK error into something a person can act on, and exit.
+ *
+ * ⭐ THIS IS THE POINT OF THE REWIRE, not a nicety. Every failure used to print
+ * `HTTP 402` and a raw body — which tells you a wall exists and nothing about
+ * which one. The hierarchy already knows: whether you need to log in, upgrade,
+ * top up, wait, or accept that this server does not have the feature at all.
+ * Four of those five have different fixes and the fifth cannot be fixed by
+ * paying.
+ *
+ * Errors are matched by NAME rather than instanceof: the CLI may load a
+ * different copy of @mnemahq/core than the SDK did (npm dedupes, pnpm does not
+ * always), and a cross-realm instanceof silently falls through to the generic
+ * branch — turning a good message back into a bad one for the exact reason this
+ * function exists.
+ */
+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.`));
+      // ⚠️ 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':
+      console.error(c.yellow(`${where}your ${e.plan ?? 'current'} plan does not include ${e.feature ?? 'this'}.`));
+      console.error(`  Needs the ${e.required ?? 'a paid'} plan.`);
+      console.error(`  ${c.dim(e.upgradeUrl ?? `${DEFAULT_APP_URL}/app/settings/billing`)}`);
+      break;
+
+    case 'FeatureUnavailableError':
+      // No upgrade link here on purpose. There is nothing to buy: this server's
+      // build does not contain the feature, and pointing at billing would sell
+      // someone a plan that cannot change their binary.
+      console.error(c.yellow(`${where}${e.feature ?? 'that feature'} is not available on this server.`));
+      console.error(`  ${c.dim(`This is a ${e.edition ?? 'core'} build — the enterprise modules are not installed.`)}`);
+      break;
+
+    case 'InsufficientCreditError': {
+      const need = typeof e.topUpNeededCents === 'number' ? `$${(e.topUpNeededCents / 100).toFixed(2)}` : 'more credit';
+      console.error(c.yellow(`${where}not enough credit for ${e.action ?? 'this action'}.`));
+      console.error(`  Top up ${need}. ${c.dim(`${DEFAULT_APP_URL}/app/settings/wallet`)}`);
+      break;
+    }
+
+    case 'RateLimitError': {
+      const secs = typeof e.retryAfterMs === 'number' ? Math.ceil(e.retryAfterMs / 1000) : null;
+      console.error(c.yellow(`${where}rate limited${secs ? ` — retry in ${secs}s` : ''}.`));
+      break;
+    }
+
+    case 'ValidationError':
+      console.error(c.red(`${where}${e.message}`));
+      if (e.fields) for (const [f, msgs] of Object.entries(e.fields)) console.error(`  ${f}: ${[].concat(msgs).join(', ')}`);
+      break;
+
+    case 'NetworkError':
+      console.error(c.red(`${where}could not reach the server.`));
+      console.error(`  ${c.dim(e.message)}`);
+      break;
+
+    default:
+      console.error(c.red(`${where}${e?.message ?? String(e)}`));
+      if (e?.status) console.error(`  ${c.dim(`HTTP ${e.status}`)}`);
+  }
+  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/keychain.mjs

@@ -181,8 +181,19 @@ export function deleteSecret(account) {
 }
 
 /** Where the CLI keeps non-secret login state (origin, workspace, expiry). */
+/**
+ * Where the CLI keeps non-secret login state.
+ *
+ * ⚠️ MNEMA_STATE_DIR EXISTS BECAUSE THE TEST SUITE ATE A REAL LOGIN. keychain's
+ * own test calls writeState({ origin: 'https://api.example', … }) to check the
+ * file round-trips — and with the path hard-wired to homedir() that wrote over
+ * the developer's actual ~/.mnema/auth.json. Running `pnpm test` silently
+ * repointed a working CLI at a fake host; the next command failed with
+ * `getaddrinfo api.example`, which reads like a network fault and is nothing of
+ * the kind. Tests must not be able to reach a real home directory.
+ */
 export function statePath() {
-  const dir = join(homedir(), '.mnema');
+  const dir = process.env.MNEMA_STATE_DIR || join(homedir(), '.mnema');
   mkdirSync(dir, { recursive: true });
   return join(dir, 'auth.json');
 }

package/src/read-commands.mjs

@@ -0,0 +1,196 @@
+/**
+ * The read commands — tasks, docs, projects, ask, graph, briefing (t-624).
+ *
+ * ⭐ EVERY ONE OF THESE IS A WRAPPER, NOT A CLIENT. They exist because t-623 put
+ * the CLI on @mnemahq/sdk; each is four lines of SDK call plus formatting, and
+ * none of them knows a URL, an envelope key or a header. That is the payoff §A2
+ * was arguing for: the surface grew without the transport growing with it.
+ *
+ * ⚠️ THE FORMATTING IS THE PART WITH JUDGEMENT IN IT, and two of these can lie by
+ * omission if it is done carelessly:
+ *
+ *   ask       the interpreter HEDGES below its confidence threshold. Printing the
+ *             sentence without the number turns a hedge into a claim, which is
+ *             worse than printing nothing.
+ *   briefing  a short list has three quite different causes and only one is good
+ *             news. On a core build six of seven finding families cannot produce
+ *             anything at all, and `coverage.notice` is the only thing that says so.
+ *
+ * --json everywhere: a CLI you cannot pipe is half a CLI, and the SDK already
+ * returns the shape worth emitting, so it costs one line each.
+ */
+
+import { call, hasApiKey, canAuthenticate, renderError } from './client.mjs';
+import { c } from './util.mjs';
+
+/** Machine output is the whole object; humans get the formatted view. */
+function emit(flags, value, render) {
+  if (flags.json) { console.log(JSON.stringify(value, null, 2)); return; }
+  render();
+}
+
+async function guard(workspaceId) {
+  if (await canAuthenticate(workspaceId)) return;
+  console.error(c.red('Not authenticated — run `mnema login`, or `mnema init` with an API key.'));
+  process.exit(1);
+}
+
+const trunc = (s, n) => (s && s.length > n ? `${s.slice(0, n - 1)}…` : (s ?? ''));
+
+// ── tasks ─────────────────────────────────────────────────────────────────────
+export async function cmdTasks(flags, ctx) {
+  await guard(ctx.workspaceId);
+  const limit = Number(flags.limit) || 20;
+  try {
+    const rows = await call(ctx, (m) => m.tasks.list({
+      limit,
+      ...(flags.status ? { status: flags.status } : {}),
+      ...(flags.project ? { project: flags.project } : {}),
+    }).all());
+    emit(flags, rows, () => {
+      if (!rows.length) return console.log(c.dim('No tasks match.'));
+      console.log(c.bold(`${rows.length} task(s)`));
+      for (const t of rows) {
+        const id = (t.publicId || t.id.slice(0, 8)).padEnd(8);
+        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, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'tasks' }); }
+}
+
+export async function cmdNext(flags, ctx) {
+  await guard(ctx.workspaceId);
+  try {
+    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}`);
+      if (t.description) console.log(c.dim(trunc(t.description.replace(/\s+/g, ' '), 300)));
+      // The branch name is the load-bearing part of this project's dev loop, so
+      // the CLI hands it over ready to paste rather than making it be derived.
+      if (t.publicId) {
+        const slug = t.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
+        console.log(`\n  ${c.dim('branch:')} git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
+      }
+    });
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'next' }); }
+}
+
+// ── docs ──────────────────────────────────────────────────────────────────────
+export async function cmdDocs(flags, ctx) {
+  await guard(ctx.workspaceId);
+  const limit = Number(flags.limit) || 20;
+  try {
+    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)`));
+      for (const d of rows) {
+        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, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'docs' }); }
+}
+
+export async function cmdDoc(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  const id = rest[0];
+  if (!id) { console.error(c.red('Usage: mnema doc <id>')); process.exit(1); }
+  try {
+    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, () => {
+      console.error(c.bold(d.title));
+      console.error(c.dim(`${d.path} · updated ${String(d.updatedAt).slice(0, 10)}`));
+      if (d.markdown) console.log(d.markdown);
+    });
+  } 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 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, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'projects' }); }
+}
+
+// ── graph: ask + traverse ─────────────────────────────────────────────────────
+export async function cmdAsk(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  const q = rest.join(' ').trim();
+  if (!q) { console.error(c.red('Usage: mnema ask "<question>"')); process.exit(1); }
+  try {
+    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
+      // rather than asserts when the graph is thin; a terminal that prints only
+      // the sentence promotes a hedge to a fact.
+      const pct = Math.round((a.confidence ?? 0) * 100);
+      const why = a.confidenceReason ? ` (${a.confidenceReason})` : '';
+      const line = `confidence ${pct}%${why} · tier ${a.tier}${a.usedFallback ? ' · fallback' : ''}`;
+      console.log(pct >= 60 ? c.dim(`\n${line}`) : c.yellow(`\n${line} — treat as a lead, not a fact`));
+      if (a.sources?.length) {
+        console.log(c.dim(`\nsources (${a.sources.length}):`));
+        for (const s of a.sources.slice(0, 5)) console.log(c.dim(`  ${trunc(s.title, 70)}`));
+      }
+    });
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'ask' }); }
+}
+
+export async function cmdGraph(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  const [from, to] = rest;
+  if (!from) { console.error(c.red('Usage: mnema graph <from> [to]')); process.exit(1); }
+  try {
+    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
+        // than printing an empty list and letting it read as an error.
+        if (!g.connected) return console.log(c.yellow(`No route between "${from}" and "${to}".`));
+        console.log(c.bold(`${g.hopCount} hop(s) from "${from}" to "${to}"`));
+        for (const id of g.path) {
+          const n = g.nodes.find((x) => x.id === id);
+          console.log(`  ${n ? trunc(n.label, 60) : id}${n?.type ? c.dim(`  [${n.type}]`) : ''}`);
+        }
+        return;
+      }
+      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, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'graph' }); }
+}
+
+// ── briefing ──────────────────────────────────────────────────────────────────
+export async function cmdBriefing(flags, ctx) {
+  await guard(ctx.workspaceId);
+  try {
+    const b = await call(ctx, (m) => m.findings.briefing());
+    emit(flags, b, () => {
+      const p = b.pulse;
+      console.log(c.bold('Pulse'));
+      console.log(`  ${p.activeProjects} active project(s) · ${p.problemsInActiveProjects} problem(s) · $${p.cost7dUsd} last 7d`);
+
+      // ⚠️ THE CAVEATS COME BEFORE THE LIST, on purpose. A short list has three
+      // causes and only one is good news; printing the findings first invites the
+      // reader to conclude "all clear" before reaching the reason it is short.
+      if (b.neverComputed) console.log(c.yellow('\n  The findings engine has never run for this workspace.'));
+      if (b.coverage?.degraded) console.log(c.yellow(`\n  ${b.coverage.notice}`));
+
+      console.log(c.bold(`\nFindings (${b.findings.length})`));
+      if (!b.findings.length) console.log(c.dim('  nothing surfaced'));
+      for (const f of b.findings) {
+        const count = f.grouped ? c.dim(` ×${f.count}`) : '';
+        console.log(`  ${c.dim(String(f.kind).padEnd(14))} ${trunc(f.headline, 90)}${count}`);
+      }
+    });
+  } catch (e) { renderError(e, { usedApiKey: hasApiKey(ctx.workspaceId), context: 'briefing' }); }
+}