@mnemahq/cli 0.1.0

package/src/cli.mjs

@@ -0,0 +1,354 @@
+/**
+ * Mnema CLI command dispatcher.
+ *
+ *   mnema init       link this repo to a workspace + install session capture
+ *   mnema status     is it connected, what was captured, last session
+ *   mnema sessions   recent sessions for this repo (local + server)
+ *   mnema sweep      opt-in backfill of past local sessions
+ *   mnema search     search your workspace from the terminal
+ *   mnema doctor     diagnose install, hooks, auth, connectivity
+ *   mnema uninstall  cleanly reverse everything
+ */
+
+import { existsSync } from 'node:fs';
+import { cmdLogin, cmdLogout } from './login.mjs';
+import {
+  DEFAULT_ORIGIN, c, gitInfo, canonicalRepo, readConfig, writeConfig, removeConfigDir,
+  apiFetch, prompt, promptHidden, localSessionsForRepo,
+} from './util.mjs';
+import { getSecret, setSecret, deleteSecrets, backendName, usingFallback } from './secrets.mjs';
+import {
+  installHook, uninstallHook, hookInstalled, hookConfigPath, defaultDeveloperId, sweepScriptPath,
+} from './hook-install.mjs';
+import { applyContext, scaffold } from './artifacts.mjs';
+import { execFileSync } from 'node:child_process';
+
+const VERSION = '0.1.0';
+
+function parseFlags(argv) {
+  const flags = {}; const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      if (argv[i + 1] && !argv[i + 1].startsWith('--')) { flags[key] = argv[++i]; }
+      else flags[key] = true;
+    } else rest.push(a);
+  }
+  return { flags, rest };
+}
+
+function resolveContext(flags) {
+  const git = gitInfo();
+  const root = git.root || process.cwd();
+  const cfg = readConfig(root) || {};
+  const origin = flags.origin || cfg.apiOrigin || DEFAULT_ORIGIN;
+  const workspaceId = flags.workspace || cfg.workspaceId || process.env.MNEMA_WORKSPACE_ID || null;
+  return { git, root, cfg, origin, workspaceId };
+}
+
+function fmtAge(mtimeMs) {
+  const s = Math.floor((Date.now() - mtimeMs) / 1000);
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+// ── init ───────────────────────────────────────────────────────────────────────
+
+async function cmdInit(flags) {
+  const git = gitInfo();
+  const root = git.root || process.cwd();
+  if (!git.root) console.log(c.yellow('! Not inside a git repository — session git context will be limited.'));
+
+  const origin = flags.origin || process.env.MNEMA_API_ORIGIN || DEFAULT_ORIGIN;
+  const existing = readConfig(root);
+
+  let workspaceId = flags.workspace || process.env.MNEMA_WORKSPACE_ID || existing?.workspaceId;
+  if (!workspaceId) workspaceId = await prompt('Workspace id: ');
+  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');
+  if (!hookToken) hookToken = await promptHidden('Hook token (Settings → Developer): ');
+  if (!hookToken) { console.error(c.red('A hook token is required.')); process.exit(1); }
+
+  let apiKey = process.env.MNEMA_API_KEY || getSecret(workspaceId, 'api-key') || '';
+  if (!apiKey && !flags.yes) apiKey = await promptHidden('API key for search/sessions (optional, Enter to skip): ');
+
+  // Store secrets in the OS keychain (or 0600 fallback).
+  setSecret(workspaceId, 'hook-token', hookToken);
+  if (apiKey) setSecret(workspaceId, 'api-key', apiKey);
+  if (usingFallback()) console.log(c.yellow(`! No OS keychain found — secrets stored in ${backendName()}.`));
+
+  process.stdout.write('Installing capture hook… ');
+  try {
+    await installHook({ origin, workspaceId, hookToken, developerId: defaultDeveloperId() });
+    console.log(c.green('done'));
+  } catch (e) {
+    console.log(c.red('failed'));
+    console.error(`  ${e.message}`);
+    process.exit(1);
+  }
+
+  // Knowledge extraction is OPT-IN and sends session transcripts for LLM processing
+  // — an explicit, separate consent (a paid graph feature).
+  let knowledge = existing?.knowledge === true;
+  if (flags.knowledge === true) knowledge = true;
+  else if (flags.knowledge === 'false' || flags['no-knowledge']) knowledge = false;
+  else if (!flags.yes && process.stdin.isTTY) {
+    console.log(c.dim('\n  Session → knowledge extraction (optional, paid graph feature): on each session end,'));
+    console.log(c.dim('  Mnema sends the session transcript (your prompts + assistant text, never file'));
+    console.log(c.dim('  contents) to extract durable decisions/gotchas into your graph. Off by default.'));
+    const a = await prompt('  Enable session→knowledge extraction? [y/N] ');
+    knowledge = /^y(es)?$/i.test(a);
+  }
+
+  const repoUrl = canonicalRepo(git.remote);
+  writeConfig(root, {
+    workspaceId,
+    apiOrigin: origin,
+    repo: repoUrl ? { canonicalUrl: repoUrl } : undefined,
+    knowledge,
+    createdAt: new Date().toISOString(),
+  });
+  scaffold(root); // .mnema/NOTABILITY.md + .gitignore + context/
+
+  console.log('');
+  console.log(c.green('✓ Mnema connected.'));
+  console.log(`  Workspace : ${workspaceId}`);
+  console.log(`  Repo      : ${repoUrl || c.dim('(no git remote)')}`);
+  console.log(`  Secrets   : ${backendName()}`);
+  console.log(`  Config    : .mnema/config.json ${c.dim('(safe to commit — no secrets)')}`);
+  console.log(`  Knowledge : ${knowledge ? c.green('on — sessions extracted to your graph') : c.dim('off (enable later: mnema init --knowledge)')}`);
+  console.log('');
+  console.log(c.dim('  Start a Claude Code session — it will appear under Sessions with its cost.'));
+  console.log(c.dim('  Backfill past sessions: mnema sweep   ·   Check anytime: mnema status'));
+}
+
+// ── status ───────────────────────────────────────────────────────────────────────
+
+async function cmdStatus(flags) {
+  const { git, root, cfg, origin, workspaceId } = resolveContext(flags);
+  console.log(c.bold('Mnema status'));
+  console.log(`  Workspace : ${workspaceId || c.red('not linked — run `mnema init`')}`);
+  console.log(`  Origin    : ${origin}`);
+  console.log(`  Repo      : ${canonicalRepo(git.remote) || c.dim('(no git remote)')}`);
+  console.log(`  Hook      : ${hookInstalled() ? c.green('installed') : c.red('not installed')}`);
+
+  process.stdout.write('  API       : ');
+  try {
+    const r = await apiFetch(origin, '/install/mnema-hook.mjs');
+    console.log(r.ok ? c.green('reachable') : c.yellow(`HTTP ${r.status}`));
+  } catch { console.log(c.red('unreachable')); }
+
+  const local = localSessionsForRepo(git.root, 1);
+  if (local.length) {
+    console.log(`  Last local session: ${local[0].sessionId.slice(0, 8)}… ${c.dim(fmtAge(local[0].mtimeMs))}`);
+  } else {
+    console.log(`  Last local session: ${c.dim('none found')}`);
+  }
+  void cfg;
+}
+
+// ── sessions ───────────────────────────────────────────────────────────────────
+
+async function cmdSessions(flags) {
+  const { git, origin, workspaceId } = resolveContext(flags);
+  const limit = Number(flags.limit) || 10;
+
+  const local = localSessionsForRepo(git.root, limit);
+  console.log(c.bold(`Local sessions for this repo (${local.length})`));
+  if (!local.length) console.log(c.dim('  none found under ~/.claude/projects'));
+  for (const s of local) {
+    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; }
+
+  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 ?? [];
+  console.log(c.bold(`\nServer sessions (${rows.length})`));
+  for (const s of rows) {
+    const cost = typeof s.totalCostUsd === 'number' ? `$${s.totalCostUsd.toFixed(4)}` : '$0';
+    console.log(`  ${(s.developerId || '?').padEnd(16)} ${String(s.status).padEnd(10)} ${cost.padStart(10)}  ${c.dim(s.model || '')}`);
+  }
+}
+
+// ── sweep ───────────────────────────────────────────────────────────────────────
+
+function cmdSweep() {
+  const script = sweepScriptPath();
+  if (!existsSync(script)) {
+    console.error(c.red('Sweep script not found — run `mnema init` first.'));
+    process.exit(1);
+  }
+  try {
+    execFileSync(process.execPath, [script], { stdio: 'inherit' });
+  } catch (e) {
+    process.exit(e.status || 1);
+  }
+}
+
+// ── search ───────────────────────────────────────────────────────────────────────
+
+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); }
+
+  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 ?? [];
+  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) {
+    console.log(`  ${c.bold(d.title || d.path || d.id)}`);
+    if (d.preview) console.log(`    ${c.dim(String(d.preview).replace(/\s+/g, ' ').slice(0, 140))}`);
+  }
+}
+
+// ── pull ───────────────────────────────────────────────────────────────────────
+
+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); }
+
+  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 ?? [];
+
+  scaffold(root);
+  const s = applyContext(root, docs);
+
+  const line = (label, arr, color) => { if (arr.length) console.log(`  ${color(label)} ${arr.length}`); };
+  console.log(c.bold(`Synced .mnema/context from ${repo}`));
+  if (!docs.length) console.log(c.dim('  no docs are bound to this repo yet (add a project with this repo URL).'));
+  line('written  ', s.written, c.green);
+  line('updated  ', s.updated, c.green);
+  line('up-to-date', s.upToDate, c.dim);
+  line('kept local', s.kept, c.yellow);
+  line('orphaned ', s.orphaned, c.dim);
+  if (s.conflicts.length) {
+    console.log(c.red(`  conflicts ${s.conflicts.length} — server version written beside your file as *.remote.md:`));
+    for (const rel of s.conflicts) console.log(`    ${rel}  ${c.dim('vs')}  ${rel.replace(/\.md$/, '.remote.md')}`);
+  }
+  console.log(c.dim('\n  .mnema/context is committed and readable offline. Edit NOTABILITY.md to tune capture.'));
+}
+
+// ── doctor ───────────────────────────────────────────────────────────────────────
+
+async function cmdDoctor(flags) {
+  const { git, root, origin, workspaceId } = resolveContext(flags);
+  const checks = [];
+  const ok = (label, pass, note) => checks.push({ label, pass, note });
+
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  ok('Node >= 18', nodeMajor >= 18, `v${process.versions.node}`);
+  let gitOk = false; try { execFileSync('git', ['--version'], { stdio: 'ignore' }); gitOk = true; } catch { /* */ }
+  ok('git available', gitOk);
+  ok('inside a git repo', !!git.root, git.root || 'no');
+  ok('workspace linked', !!workspaceId, workspaceId || '.mnema/config.json missing');
+  ok('hook token stored', !!(workspaceId && getSecret(workspaceId, 'hook-token')), `store: ${backendName()}`);
+  ok('capture hook installed', hookInstalled());
+
+  process.stdout.write('  … checking connectivity\r');
+  let apiReach = false; try { apiReach = (await apiFetch(origin, '/install/mnema-hook.mjs')).ok; } catch { /* */ }
+  ok('API reachable', apiReach, origin);
+
+  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 { /* */ }
+    ok('API key valid', keyOk);
+  } else {
+    ok('API key stored', false, 'optional — needed for search/sessions');
+  }
+
+  console.log(c.bold('Mnema doctor            '));
+  for (const ch of checks) {
+    const mark = ch.pass ? c.green('✓') : c.red('✗');
+    console.log(`  ${mark} ${ch.label.padEnd(26)} ${ch.note ? c.dim(ch.note) : ''}`);
+  }
+  const failed = checks.filter((ch) => !ch.pass && ch.label !== 'API key stored');
+  if (failed.length) { console.log(c.yellow(`\n  ${failed.length} issue(s). Run \`mnema init\` to (re)connect.`)); process.exit(1); }
+  console.log(c.green('\n  All good.'));
+  void root;
+}
+
+// ── uninstall ───────────────────────────────────────────────────────────────────
+
+async function cmdUninstall(flags) {
+  const { root, workspaceId } = resolveContext(flags);
+  uninstallHook();
+  if (workspaceId) deleteSecrets(workspaceId);
+  let purge = flags.purge === true;
+  if (!purge && process.stdin.isTTY) {
+    const a = await prompt('Also remove .mnema/config.json from this repo? [y/N] ');
+    purge = /^y(es)?$/i.test(a);
+  }
+  if (purge) removeConfigDir(root);
+  console.log(c.green('✓ Mnema hooks and secrets removed.') + (purge ? ' .mnema/ deleted.' : ` ${c.dim('.mnema/config.json kept.')}`));
+}
+
+// ── help ───────────────────────────────────────────────────────────────────────
+
+function help() {
+  console.log(`mnema ${VERSION} — connect a repo to your Mnema workspace
+
+Usage: mnema <command> [options]
+
+Commands:
+  login        Sign in (opens a browser; tokens go to your OS keychain)
+  logout       Remove stored credentials
+  init         Link this repo to a workspace and install session capture
+  status       Show connection, hook, and last session
+  sessions     List recent sessions for this repo (local + server)
+  sweep        Backfill past local sessions (opt-in)
+  pull         Export repo-bound docs into .mnema/context (server-is-truth)
+  search "q"   Search your workspace from the terminal
+  doctor       Diagnose install, hooks, auth, connectivity
+  uninstall    Remove hooks and stored secrets
+
+Options:
+  --workspace <id>   Workspace id (else prompted / MNEMA_WORKSPACE_ID)
+  --origin <url>     API origin (default ${DEFAULT_ORIGIN})
+  --limit <n>        Row limit for sessions
+  --yes              Non-interactive; skip optional prompts
+  --purge            uninstall: also delete .mnema/config.json
+  --version, --help
+`);
+}
+
+export async function run(argv) {
+  const { flags, rest } = parseFlags(argv);
+  if (flags.version) { console.log(VERSION); return; }
+  const cmd = rest.shift();
+  switch (cmd) {
+    case 'login':     return cmdLogin(flags);
+    case 'logout':    return cmdLogout();
+    case 'init':      return cmdInit(flags);
+    case 'status':    return cmdStatus(flags);
+    case 'sessions':  return cmdSessions(flags);
+    case 'sweep':     return cmdSweep();
+    case 'pull':      return cmdPull(flags);
+    case 'search':    return cmdSearch(flags, rest);
+    case 'doctor':    return cmdDoctor(flags);
+    case 'uninstall': return cmdUninstall(flags);
+    case undefined:
+    case 'help':      return help();
+    default:
+      console.error(c.red(`Unknown command: ${cmd}`));
+      help();
+      process.exit(1);
+  }
+}

package/src/hook-install.mjs

@@ -0,0 +1,111 @@
+/**
+ * Installs / removes the Mnema Claude Code capture hook — the same result as the
+ * server's /install/claude-hooks.sh, but in pure Node so the CLI needs no bash or
+ * curl and works cross-platform. Idempotent and safe to re-run.
+ */
+
+import { homedir, userInfo, hostname } from 'node:os';
+import { join, dirname } from 'node:path';
+import { mkdirSync, writeFileSync, existsSync, readFileSync, rmSync, chmodSync } from 'node:fs';
+
+const HOOK_EVENTS = ['SessionStart', 'SessionEnd', 'Stop', 'PostToolUse', 'PostToolUseFailure'];
+
+export function claudeDir() { return join(homedir(), '.claude'); }
+export function hooksDir() { return join(claudeDir(), 'hooks'); }
+export function settingsPath() { return join(claudeDir(), 'settings.json'); }
+export function hookScriptPath() { return join(hooksDir(), 'mnema-hook.mjs'); }
+export function sweepScriptPath() { return join(hooksDir(), 'mnema-sweep.mjs'); }
+export function hookConfigPath() { return join(hooksDir(), 'mnema.config.json'); }
+
+export function defaultDeveloperId() {
+  let user = 'dev';
+  try { user = userInfo().username || 'dev'; } catch { /* ignore */ }
+  return `${user}@${hostname()}`;
+}
+
+async function fetchText(url) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15000);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) throw new Error(`GET ${url} → ${res.status}`);
+    return await res.text();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isMnema(h) {
+  return h && h.command && String(h.command).includes('mnema-hook');
+}
+
+function readSettings() {
+  try { return JSON.parse(readFileSync(settingsPath(), 'utf8')); } catch { return {}; }
+}
+
+function stripMnema(settings) {
+  if (!settings.hooks) return settings;
+  for (const ev of Object.keys(settings.hooks)) {
+    const arr = Array.isArray(settings.hooks[ev]) ? settings.hooks[ev] : [];
+    const cleaned = arr
+      .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !isMnema(h)) }))
+      .filter((g) => (g.hooks || []).length > 0);
+    if (cleaned.length) settings.hooks[ev] = cleaned;
+    else delete settings.hooks[ev];
+  }
+  return settings;
+}
+
+function writeSettings(settings) {
+  mkdirSync(dirname(settingsPath()), { recursive: true });
+  writeFileSync(settingsPath(), JSON.stringify(settings, null, 2));
+}
+
+export function hookInstalled() {
+  if (!existsSync(hookScriptPath())) return false;
+  const s = readSettings();
+  if (!s.hooks) return false;
+  return Object.values(s.hooks).some(
+    (groups) => Array.isArray(groups) && groups.some((g) => (g.hooks || []).some(isMnema)),
+  );
+}
+
+/** Idempotent install: fetch assets, write config (0600), register the hook. */
+export async function installHook({ origin, workspaceId, hookToken, developerId }) {
+  const dir = hooksDir();
+  mkdirSync(dir, { recursive: true });
+
+  const [hookJs, sweepJs] = await Promise.all([
+    fetchText(`${origin}/install/mnema-hook.mjs`),
+    fetchText(`${origin}/install/mnema-sweep.mjs`),
+  ]);
+  writeFileSync(hookScriptPath(), hookJs);
+  writeFileSync(sweepScriptPath(), sweepJs);
+
+  writeFileSync(
+    hookConfigPath(),
+    JSON.stringify({ origin, token: hookToken, workspaceId, developerId: developerId || defaultDeveloperId() }, null, 2),
+    { mode: 0o600 },
+  );
+  try { chmodSync(hookConfigPath(), 0o600); } catch { /* best effort */ }
+  writeFileSync(join(dir, 'mnema-activated-at'), String(Math.floor(Date.now() / 1000)));
+
+  // Register the command hook, idempotently (strip any prior mnema entries first).
+  const settings = stripMnema(readSettings());
+  settings.hooks = settings.hooks || {};
+  const cmd = `node "${hookScriptPath()}"`;
+  for (const ev of HOOK_EVENTS) {
+    const arr = Array.isArray(settings.hooks[ev]) ? settings.hooks[ev] : [];
+    arr.push({ hooks: [{ type: 'command', command: cmd }] });
+    settings.hooks[ev] = arr;
+  }
+  writeSettings(settings);
+}
+
+/** Reverse installHook: unregister + remove files. */
+export function uninstallHook() {
+  writeSettings(stripMnema(readSettings()));
+  for (const p of [hookScriptPath(), sweepScriptPath(), hookConfigPath(), join(hooksDir(), 'mnema-activated-at')]) {
+    if (existsSync(p)) { try { rmSync(p); } catch { /* ignore */ } }
+  }
+}

package/src/keychain.mjs

@@ -0,0 +1,207 @@
+/**
+ * OS credential storage for the CLI (§C1).
+ *
+ * ⭐ NEVER A PLAINTEXT TOKEN IN A DOTFILE. A refresh token in `~/.mnemarc` is
+ * readable by every process the user runs, survives in backups, and gets committed
+ * by accident. Each platform already has a place for this and we use it:
+ *
+ *   macOS    security(1)          → login keychain
+ *   Linux    secret-tool(1)       → libsecret / GNOME Keyring
+ *   Windows  PowerShell + DPAPI   → per-user encrypted blob
+ *
+ * ⚠️ WINDOWS IS THE ODD ONE, and honestly so. Windows Credential Manager's own
+ * store (cmdkey) cannot return a secret to a script — it is designed for the OS to
+ * consume, not the caller. So we use DPAPI (`ProtectedData.Protect`, CurrentUser
+ * scope), which is the same protection Credential Manager itself relies on: the
+ * ciphertext is bound to the Windows account and is useless if copied elsewhere.
+ * The file is opaque; it is NOT a plaintext dotfile.
+ *
+ * ⚠️ HEADLESS FALLBACK IS EXPLICIT, NOT SILENT. On a CI box with no keyring, we
+ * do NOT quietly write plaintext — that is how a "secure" store becomes a file
+ * nobody audits. We refuse, and tell the caller to use MNEMA_API_KEY instead.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, chmodSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+const SERVICE = 'mnema';
+
+function run(cmd, args, input) {
+  return execFileSync(cmd, args, {
+    encoding: 'utf8',
+    input,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: 10_000,
+  }).trim();
+}
+
+function has(cmd) {
+  try {
+    run(platform() === 'win32' ? 'where' : 'which', [cmd]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── macOS ──────────────────────────────────────────────────────────────────────
+const macos = {
+  available: () => platform() === 'darwin' && has('security'),
+  get(account) {
+    try {
+      // -w prints only the password. A missing item exits non-zero, which is a
+      // "not logged in", not an error worth surfacing.
+      return run('security', ['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
+    } catch {
+      return null;
+    }
+  },
+  set(account, secret) {
+    // -U updates in place; without it a second login throws "item already exists".
+    run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', account, '-w', secret]);
+  },
+  del(account) {
+    try { run('security', ['delete-generic-password', '-s', SERVICE, '-a', account]); } catch { /* absent */ }
+  },
+  name: 'macOS Keychain',
+};
+
+// ── Linux ──────────────────────────────────────────────────────────────────────
+const linux = {
+  available: () => platform() === 'linux' && has('secret-tool'),
+  get(account) {
+    try {
+      const out = run('secret-tool', ['lookup', 'service', SERVICE, 'account', account]);
+      return out || null;
+    } catch {
+      return null;
+    }
+  },
+  set(account, secret) {
+    // secret-tool reads the secret from stdin, so it never appears in `ps`.
+    run('secret-tool', ['store', '--label=Mnema CLI', 'service', SERVICE, 'account', account], `${secret}\n`);
+  },
+  del(account) {
+    try { run('secret-tool', ['clear', 'service', SERVICE, 'account', account]); } catch { /* absent */ }
+  },
+  name: 'libsecret (GNOME Keyring)',
+};
+
+// ── Windows ────────────────────────────────────────────────────────────────────
+function dpapiPath(account) {
+  const dir = join(process.env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'mnema');
+  return join(dir, `${account.replace(/[^a-zA-Z0-9._-]/g, '_')}.dpapi`);
+}
+
+const windows = {
+  available: () => platform() === 'win32' && has('powershell'),
+  get(account) {
+    const file = dpapiPath(account);
+    if (!existsSync(file)) return null;
+    try {
+      const b64 = readFileSync(file, 'utf8').trim();
+      if (!b64) return null;
+      const script = `
+        Add-Type -AssemblyName System.Security;
+        $b = [Convert]::FromBase64String('${b64}');
+        $p = [Security.Cryptography.ProtectedData]::Unprotect($b, $null, 'CurrentUser');
+        [Text.Encoding]::UTF8.GetString($p)
+      `;
+      return run('powershell', ['-NoProfile', '-NonInteractive', '-Command', script]) || null;
+    } catch {
+      return null;
+    }
+  },
+  set(account, secret) {
+    const file = dpapiPath(account);
+    mkdirSync(join(file, '..'), { recursive: true });
+    const script = `
+      Add-Type -AssemblyName System.Security;
+      $s = [Console]::In.ReadToEnd();
+      $b = [Text.Encoding]::UTF8.GetBytes($s.Trim());
+      $p = [Security.Cryptography.ProtectedData]::Protect($b, $null, 'CurrentUser');
+      [Convert]::ToBase64String($p)
+    `;
+    const b64 = run('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], secret);
+    writeFileSync(file, b64, { mode: 0o600 });
+  },
+  del(account) {
+    try { unlinkSync(dpapiPath(account)); } catch { /* absent */ }
+  },
+  name: 'Windows DPAPI (per-user)',
+};
+
+const BACKENDS = [macos, linux, windows];
+
+/** The store for this machine, or null when none is usable. */
+export function backend() {
+  return BACKENDS.find((b) => b.available()) ?? null;
+}
+
+export function backendName() {
+  return backend()?.name ?? 'none available';
+}
+
+export class NoKeychainError extends Error {
+  constructor() {
+    super(
+      'No OS credential store is available on this machine.\n'
+      + '  macOS   : the `security` command is missing\n'
+      + '  Linux   : install libsecret-tools (Debian/Ubuntu: apt install libsecret-tools)\n'
+      + '  Windows : PowerShell is not on PATH\n\n'
+      + 'For CI and headless machines, set MNEMA_API_KEY instead of logging in.\n'
+      + 'Mnema will NOT write a token to a plaintext file as a fallback.',
+    );
+    this.name = 'NoKeychainError';
+  }
+}
+
+export function getSecret(account) {
+  const b = backend();
+  if (!b) return null;
+  return b.get(account);
+}
+
+export function setSecret(account, secret) {
+  const b = backend();
+  if (!b) throw new NoKeychainError();
+  b.set(account, secret);
+  // Prove it round-trips NOW, not on next launch. A store that silently accepts a
+  // write and returns nothing later is worse than one that refuses up front.
+  const check = b.get(account);
+  if (check !== secret) {
+    throw new Error(`${b.name} accepted the credential but did not return it. Refusing to claim you are logged in.`);
+  }
+}
+
+export function deleteSecret(account) {
+  backend()?.del(account);
+}
+
+/** Where the CLI keeps non-secret login state (origin, workspace, expiry). */
+export function statePath() {
+  const dir = join(homedir(), '.mnema');
+  mkdirSync(dir, { recursive: true });
+  return join(dir, 'auth.json');
+}
+
+export function readState() {
+  try {
+    return JSON.parse(readFileSync(statePath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** ⚠️ Non-secret ONLY. Tokens go to the keychain; this file must stay boring. */
+export function writeState(state) {
+  const p = statePath();
+  writeFileSync(p, JSON.stringify(state, null, 2));
+  try { chmodSync(p, 0o600); } catch { /* best effort on Windows */ }
+}
+
+export function clearState() {
+  try { unlinkSync(statePath()); } catch { /* absent */ }
+}