@jhizzard/termdeck 0.6.2 → 0.6.4

package/README.md

@@ -171,7 +171,7 @@ Honest limits, stated upfront so the skeptic has nothing to chase:
 - **Not a replacement for reading docs.** It's the shortest path to a memory you already wrote. If the memory isn't there, the feature does nothing.
 - **Not fully local by default.** Tier 2+ reaches out to Supabase for storage and OpenAI for embeddings. Tier 1 is fully local. A fully-local Tier 2 (local Postgres + local embeddings) is on the roadmap.
 - **Not free forever.** Tier 2+ pays OpenAI fractions of a cent per memory for embeddings. Self-hosted embeddings via Ollama are on the roadmap.
-- **Not proven at scale.** v0.6.1, validated against 4,590 memories in one developer's production store. The Rumen 2026-04-19 re-kickstart processed 166 sessions into 166 insights in ~5.5 minutes. No multi-user data yet. Bug reports and issues welcome.
+- **Not proven at scale.** v0.6.4, validated against 4,669 memories in one developer's production store. The Rumen 2026-04-19 re-kickstart processed 166 sessions into 166 insights in ~5.5 minutes. No multi-user data yet. Bug reports and issues welcome.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/cli/src/init-mnestra.js

@@ -5,15 +5,28 @@
 //
 // Steps:
 //   1. Collect Supabase URL, service_role key, direct DB URL, OpenAI + Anthropic keys
-//   2. Connect via `pg` using the direct URL
-//   3. Apply the six bundled Mnestra migrations in order
-//   4. Write ~/.termdeck/secrets.env (merge-aware, preserves existing values)
+//      (or reuse the saved set in ~/.termdeck/secrets.env if present)
+//   2. Persist ~/.termdeck/secrets.env immediately — merge-aware, preserves
+//      existing values. Done BEFORE any database work so a later pg connect
+//      or migration failure doesn't lose the user's typed-in keys.
+//   3. Connect via `pg` using the direct URL
+//   4. Apply the six bundled Mnestra migrations in order
 //   5. Update ~/.termdeck/config.yaml to enable RAG + point at ${VAR} refs
+//      (only after migrations apply cleanly — otherwise the server would
+//      try to use an incomplete schema on next startup)
 //   6. Verify with a memory_status_aggregation() call
 //
 // Flags:
 //   --help              Print usage and exit
-//   --yes               Reserved (no-op as of v0.6.2 — wizard no longer asks "Proceed?" after secrets)
+//   --yes               Reuse saved secrets without re-prompting if a complete
+//                       set is already on disk (otherwise the wizard asks
+//                       interactively before reusing)
+//   --reset             Ignore saved secrets and re-prompt for everything
+//   --from-env          Skip every prompt; read all five secrets from the
+//                       process environment (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY,
+//                       DATABASE_URL, OPENAI_API_KEY, ANTHROPIC_API_KEY).
+//                       Required for terminals that fight with our raw-mode
+//                       secret prompt and for CI / scripted installs.
 //   --dry-run           Print what the wizard would do; don't touch the DB or filesystem
 //   --skip-verify       Skip the final memory_status_aggregation() check
 //
@@ -41,15 +54,25 @@ const HELP = [
   '',
   'Flags:',
   '  --help            Print this message and exit',
-  '  --yes             Reserved (no-op as of v0.6.2 — kept for forward compatibility)',
+  '  --yes             Reuse saved secrets without prompting (if a complete',
+  '                    set is already on disk in ~/.termdeck/secrets.env)',
+  '  --reset           Ignore saved secrets and re-prompt for everything',
+  '  --from-env        Skip every prompt; read SUPABASE_URL,',
+  '                    SUPABASE_SERVICE_ROLE_KEY, DATABASE_URL, OPENAI_API_KEY,',
+  '                    ANTHROPIC_API_KEY from environment variables instead.',
+  '                    Useful for terminals that fight with raw-mode secret',
+  '                    prompts (MobaXterm SSH, some Windows shells) and for',
+  '                    CI / scripted installs.',
   '  --dry-run         Print the plan without touching the database or filesystem',
   '  --skip-verify     Skip the final memory_status_aggregation() sanity call',
   '',
   'What this does:',
   '  1. Prompts for Supabase URL, service_role key, direct Postgres connection',
-  '     string, OpenAI API key, and (optional) Anthropic API key.',
-  '  2. Applies the six Mnestra schema + RPC migrations via node-postgres.',
-  '  3. Writes ~/.termdeck/secrets.env (merge-aware, preserves existing values).',
+  '     string, OpenAI API key, and (optional) Anthropic API key — or reuses',
+  '     saved values if a complete set already exists in secrets.env.',
+  '  2. Writes ~/.termdeck/secrets.env IMMEDIATELY (merge-aware) so a later',
+  '     pg connect or migration failure does not lose what you typed in.',
+  '  3. Connects to Postgres and applies the six Mnestra schema + RPC migrations.',
   '  4. Updates ~/.termdeck/config.yaml to enable RAG and reference ${VAR} keys.',
   '  5. Verifies the Mnestra store is reachable via memory_status_aggregation().',
   '',
@@ -58,16 +81,91 @@ const HELP = [
 ].join('\n');
 
 function parseFlags(argv) {
-  const out = { help: false, yes: false, dryRun: false, skipVerify: false };
+  const out = {
+    help: false,
+    yes: false,
+    reset: false,
+    fromEnv: false,
+    dryRun: false,
+    skipVerify: false
+  };
   for (const a of argv) {
     if (a === '--help' || a === '-h') out.help = true;
     else if (a === '--yes' || a === '-y') out.yes = true;
+    else if (a === '--reset') out.reset = true;
+    else if (a === '--from-env') out.fromEnv = true;
     else if (a === '--dry-run') out.dryRun = true;
     else if (a === '--skip-verify') out.skipVerify = true;
   }
   return out;
 }
 
+// Build inputs from process.env directly, skipping every askSecret prompt.
+// Used by --from-env so callers on terminals that fight with our raw-mode
+// secret prompt (Brad's MobaXterm SSH report 2026-04-25, fourth occurrence)
+// can hand the wizard their secrets via env vars instead. Also makes the
+// wizard scriptable for CI / one-shot installers. Returns the same shape
+// as collectInputs() so the rest of main() doesn't care which path filled
+// it. Throws with an actionable message when a required env var is missing
+// or fails its shape check — `--from-env` is strict by design (no fallback
+// to prompts), since callers using it have explicitly opted into the
+// non-interactive path.
+function inputsFromEnv() {
+  const env = process.env;
+  const missing = [];
+  const required = {
+    SUPABASE_URL: env.SUPABASE_URL,
+    SUPABASE_SERVICE_ROLE_KEY: env.SUPABASE_SERVICE_ROLE_KEY,
+    DATABASE_URL: env.DATABASE_URL,
+    OPENAI_API_KEY: env.OPENAI_API_KEY
+  };
+  for (const [k, v] of Object.entries(required)) {
+    if (!v || !v.trim()) missing.push(k);
+  }
+  if (missing.length > 0) {
+    throw new Error(
+      `--from-env is missing required environment variable(s): ${missing.join(', ')}.\n` +
+      'Set every required key in your shell or pass them on the command line, e.g.:\n' +
+      '  SUPABASE_URL=https://xyz.supabase.co \\\n' +
+      '  SUPABASE_SERVICE_ROLE_KEY=sb_secret_... \\\n' +
+      '  DATABASE_URL=postgres://postgres.<ref>:<pw>@<pooler-host>:6543/postgres \\\n' +
+      '  OPENAI_API_KEY=sk-proj-... \\\n' +
+      '  ANTHROPIC_API_KEY=sk-ant-... \\\n' +
+      '  termdeck init --mnestra --from-env'
+    );
+  }
+
+  const projectUrl = urlHelper.parseProjectUrl(required.SUPABASE_URL);
+  if (!projectUrl.ok) {
+    throw new Error(`SUPABASE_URL is malformed: ${projectUrl.error}`);
+  }
+
+  const dbErr = urlHelper.looksLikePostgresUrl(required.DATABASE_URL);
+  if (dbErr) throw new Error(`DATABASE_URL: ${dbErr}`);
+
+  const srErr = urlHelper.looksLikeServiceRole(required.SUPABASE_SERVICE_ROLE_KEY);
+  if (srErr) throw new Error(`SUPABASE_SERVICE_ROLE_KEY: ${srErr}`);
+
+  const oaErr = urlHelper.looksLikeOpenAiKey(required.OPENAI_API_KEY);
+  if (oaErr) throw new Error(`OPENAI_API_KEY: ${oaErr}`);
+
+  const anthropicKey = (env.ANTHROPIC_API_KEY || '').trim() || null;
+  if (anthropicKey) {
+    const aErr = urlHelper.looksLikeAnthropicKey(anthropicKey);
+    if (aErr) {
+      process.stdout.write(`  (warning: ANTHROPIC_API_KEY ${aErr} — storing anyway)\n`);
+    }
+  }
+
+  return {
+    projectUrl,
+    serviceRoleKey: required.SUPABASE_SERVICE_ROLE_KEY,
+    databaseUrl: required.DATABASE_URL,
+    openaiKey: required.OPENAI_API_KEY,
+    anthropicKey
+  };
+}
+
 function printBanner() {
   process.stdout.write(`
 TermDeck Mnestra Setup
@@ -76,13 +174,20 @@ TermDeck Mnestra Setup
 This wizard configures TermDeck's Tier 2 memory layer (Mnestra) by:
   1. Asking for your Supabase URL and service_role key
   2. Asking for a direct Postgres connection string
-  3. Applying six SQL migrations to the database
-  4. Asking for an OpenAI API key (embeddings)
-  5. Asking for an Anthropic API key (optional, summaries)
-  6. Writing ~/.termdeck/secrets.env
-  7. Updating ~/.termdeck/config.yaml to enable RAG
+  3. Asking for an OpenAI API key (embeddings)
+  4. Asking for an Anthropic API key (optional, summaries)
+  5. Writing ~/.termdeck/secrets.env (before any database work, so a
+     pg failure cannot lose what you typed in)
+  6. Connecting to Postgres + applying six SQL migrations
+  7. Updating ~/.termdeck/config.yaml to enable RAG (only after
+     migrations apply cleanly)
   8. Verifying the connection with a memory_status call
 
+If you already have a complete ~/.termdeck/secrets.env, the wizard will
+offer to reuse it (or pass --yes to skip the prompt and resume directly).
+If your terminal fights with the secret prompt, set the five env vars and
+pass --from-env to skip every prompt entirely.
+
 Press Ctrl+C at any time to cancel.
 
 `);
@@ -92,7 +197,59 @@ function step(msg) { process.stdout.write(`→ ${msg}`); }
 function ok(suffix = '') { process.stdout.write(` ✓${suffix ? ' ' + suffix : ''}\n`); }
 function fail(err) { process.stdout.write(` ✗\n    ${err}\n`); }
 
-async function collectInputs({ yes }) {
+// Read whatever secrets are already on disk. Returns hydrated input shape if
+// a complete set is present, or null if the user still needs to be prompted
+// for at least one required value. Anthropic remains optional throughout.
+function loadSavedSecrets() {
+  const saved = dotenv.readSecrets();
+  const required = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'DATABASE_URL', 'OPENAI_API_KEY'];
+  const present = required.filter((k) => saved[k]);
+  if (present.length < required.length) {
+    return { complete: false, present, saved };
+  }
+  const projectUrl = urlHelper.parseProjectUrl(saved.SUPABASE_URL);
+  if (!projectUrl.ok) return { complete: false, present, saved };
+  return {
+    complete: true,
+    present,
+    saved,
+    inputs: {
+      projectUrl,
+      serviceRoleKey: saved.SUPABASE_SERVICE_ROLE_KEY,
+      databaseUrl: saved.DATABASE_URL,
+      openaiKey: saved.OPENAI_API_KEY,
+      anthropicKey: saved.ANTHROPIC_API_KEY || null
+    }
+  };
+}
+
+async function collectInputs({ yes, reset }) {
+  // Resume path — Brad's case at 2026-04-25 17:50 ET ("If it got that far did
+  // it write the correct secret.env? If so, can I manually do the next steps?").
+  // If a complete set of secrets is already on disk, offer to reuse them so a
+  // re-run after a pg connect failure does not require retyping everything.
+  if (!reset) {
+    const found = loadSavedSecrets();
+    if (found.complete) {
+      const ref = found.inputs.projectUrl.projectRef;
+      const masked = urlHelper.maskSecret(found.inputs.databaseUrl);
+      process.stdout.write(
+        `Found saved secrets in ~/.termdeck/secrets.env (project ${ref}, db ${masked}).\n`
+      );
+      const reuse = yes ? true : await prompts.confirm('  Reuse saved secrets?', { defaultYes: true });
+      if (reuse) {
+        process.stdout.write('  Reusing saved secrets. Skipping prompts.\n\n');
+        return found.inputs;
+      }
+      process.stdout.write('  Re-prompting.\n\n');
+    } else if (found.present.length > 0) {
+      process.stdout.write(
+        `Note: ~/.termdeck/secrets.env has ${found.present.length}/4 required keys ` +
+        `(${found.present.join(', ')}). Re-prompting for the rest.\n\n`
+      );
+    }
+  }
+
   const projectUrlStr = await prompts.askRequired(
     '? Supabase Project URL (e.g. https://xyz.supabase.co)',
     {
@@ -129,16 +286,6 @@ async function collectInputs({ yes }) {
     }
   }
 
-  // No confirm here — the user already opted in by typing
-  // `termdeck init --mnestra` and supplying every secret. The previous
-  // confirm gate was the consistent failure point in Brad's reports
-  // (2026-04-25 twice + a third report after v0.6.1) on terminals that
-  // emit stray bytes (CRLF, ANSI cursor reports, paste-bracketing) which
-  // contaminated readline and made the confirm fast-resolve to "no" or
-  // an empty cancel. Migrations are `IF NOT EXISTS` so a re-run is safe;
-  // Ctrl-C still aborts cleanly. The `--yes` flag is preserved as a
-  // stable CLI surface for callers/scripts and for future use.
-  void yes;
   process.stdout.write('\n');
 
   return {
@@ -229,33 +376,39 @@ async function verifyStatus(client) {
   }
 }
 
-function writeLocalConfig(inputs, dryRun) {
+// Persist secrets BEFORE any pg work so a connect/migration failure can't
+// throw away what the user typed in. Brad's 2026-04-25 18:30 ET report
+// ("It's killing before writing the file. Postgrep line not added to my
+// existing file, so it wasn't changed") was caused by writeLocalConfig
+// running AFTER applyMigrations — when migrations or pg connect failed,
+// secrets.env was never updated. Splitting the writes lets secrets land
+// on disk first; config.yaml only flips to rag.enabled=true once the
+// schema is actually in place.
+function writeSecretsFile(inputs, dryRun) {
   step('Writing ~/.termdeck/secrets.env...');
-  if (dryRun) { ok('(dry-run)'); }
-  else {
-    dotenv.writeSecrets({
-      SUPABASE_URL: inputs.projectUrl.url,
-      SUPABASE_SERVICE_ROLE_KEY: inputs.serviceRoleKey,
-      DATABASE_URL: inputs.databaseUrl,
-      OPENAI_API_KEY: inputs.openaiKey,
-      ...(inputs.anthropicKey ? { ANTHROPIC_API_KEY: inputs.anthropicKey } : {})
-    });
-    ok();
-  }
+  if (dryRun) { ok('(dry-run)'); return; }
+  dotenv.writeSecrets({
+    SUPABASE_URL: inputs.projectUrl.url,
+    SUPABASE_SERVICE_ROLE_KEY: inputs.serviceRoleKey,
+    DATABASE_URL: inputs.databaseUrl,
+    OPENAI_API_KEY: inputs.openaiKey,
+    ...(inputs.anthropicKey ? { ANTHROPIC_API_KEY: inputs.anthropicKey } : {})
+  });
+  ok();
+}
 
+function writeYamlConfig(dryRun) {
   step('Updating ~/.termdeck/config.yaml (rag.enabled: true)...');
-  if (dryRun) { ok('(dry-run)'); }
-  else {
-    const r = yaml.updateRagConfig({
-      enabled: true,
-      supabaseUrl: '${SUPABASE_URL}',
-      supabaseKey: '${SUPABASE_SERVICE_ROLE_KEY}',
-      openaiApiKey: '${OPENAI_API_KEY}',
-      anthropicApiKey: '${ANTHROPIC_API_KEY}'
-    });
-    if (r.backup) ok(`(backup: ${path.basename(r.backup)})`);
-    else ok();
-  }
+  if (dryRun) { ok('(dry-run)'); return; }
+  const r = yaml.updateRagConfig({
+    enabled: true,
+    supabaseUrl: '${SUPABASE_URL}',
+    supabaseKey: '${SUPABASE_SERVICE_ROLE_KEY}',
+    openaiApiKey: '${OPENAI_API_KEY}',
+    anthropicApiKey: '${ANTHROPIC_API_KEY}'
+  });
+  if (r.backup) ok(`(backup: ${path.basename(r.backup)})`);
+  else ok();
 }
 
 function printNextSteps() {
@@ -270,6 +423,14 @@ Next steps:
 `);
 }
 
+function printResumeHint() {
+  process.stderr.write(
+    '\nYour secrets are saved at ~/.termdeck/secrets.env.\n' +
+    'To retry just the database step (no need to re-enter keys):\n' +
+    '  termdeck init --mnestra --yes\n'
+  );
+}
+
 async function main(argv) {
   const flags = parseFlags(argv || []);
   if (flags.help) {
@@ -280,19 +441,46 @@ async function main(argv) {
   printBanner();
 
   let inputs;
+  if (flags.fromEnv) {
+    // Skip every interactive prompt — secrets come from process.env. Used
+    // when the user's terminal fights with the raw-mode secret prompt
+    // (Brad/MobaXterm SSH, 2026-04-25 fourth report) or when the wizard
+    // is being driven from a CI/install script.
+    process.stdout.write('Reading secrets from environment variables (--from-env).\n\n');
+    try {
+      inputs = inputsFromEnv();
+    } catch (err) {
+      process.stderr.write(`\n[init --mnestra] ${err.message}\n`);
+      return 2;
+    }
+  } else {
+    try {
+      inputs = await collectInputs({ yes: flags.yes, reset: flags.reset });
+    } catch (err) {
+      process.stderr.write(`\n[init --mnestra] ${err.message}\n`);
+      return 2;
+    }
+  }
+
+  // Persist secrets BEFORE pg work. If the wizard dies past this point
+  // (connect timeout, migration error, Ctrl-C), the saved file lets the
+  // user re-run with --yes and skip straight to the database step.
+  process.stdout.write('\n');
   try {
-    inputs = await collectInputs({ yes: flags.yes });
+    writeSecretsFile(inputs, flags.dryRun);
   } catch (err) {
-    process.stderr.write(`\n[init --mnestra] ${err.message}\n`);
-    return 2;
+    fail(err.message);
+    process.stderr.write(
+      '\nFailed to write ~/.termdeck/secrets.env. Check the directory is writable.\n'
+    );
+    return 6;
   }
 
-  process.stdout.write('\n');
   step('Connecting to Supabase...');
   if (flags.dryRun) {
     ok('(dry-run, skipped)');
     await applyMigrations(null, true);
-    writeLocalConfig(inputs, true);
+    writeYamlConfig(true);
     process.stdout.write('\nDry run complete. No changes were made.\n');
     return 0;
   }
@@ -306,13 +494,14 @@ async function main(argv) {
     process.stderr.write(
       '\nDouble-check the connection string from Supabase → Project Settings → Database → Connection String.\n'
     );
+    printResumeHint();
     return 3;
   }
 
   try {
     await checkExistingStore(client);
     await applyMigrations(client, false);
-    writeLocalConfig(inputs, false);
+    writeYamlConfig(false);
     if (!flags.skipVerify) {
       const verified = await verifyStatus(client);
       if (!verified) {
@@ -326,6 +515,7 @@ async function main(argv) {
     }
   } catch (err) {
     process.stderr.write(`\n[init --mnestra] ${err.message}\n`);
+    printResumeHint();
     return 5;
   } finally {
     try { await client.end(); } catch (_err) { /* ignore */ }

package/packages/cli/src/init-rumen.js

@@ -210,6 +210,35 @@ function runShellCaptured(command, args, opts = {}) {
   return { ok: r.status === 0, code: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
 }
 
+// Detect the "no access token" signature in `supabase link` stderr so the
+// wizard can surface a path-aware hint instead of dumping raw CLI output at
+// the user. Brad hit this on 2026-04-26 00:25 UTC on MobaXterm SSH after
+// v0.6.3 unblocked init --mnestra: he had no SUPABASE_ACCESS_TOKEN env var
+// and `supabase login` requires a browser, which his SSH session doesn't
+// have. The actionable path on a non-desktop install is always a PAT from
+// the dashboard — link() now points users straight at it.
+function looksLikeMissingAccessToken(stderr) {
+  if (!stderr) return false;
+  return /Access token not provided/i.test(stderr) ||
+    /SUPABASE_ACCESS_TOKEN environment variable/i.test(stderr);
+}
+
+function printAccessTokenHint() {
+  process.stderr.write(
+    '\nThe Supabase CLI needs a Personal Access Token to link your project.\n' +
+    'On a desktop install you can run `supabase login`, but that opens a\n' +
+    'browser, so SSH/headless users should use the env-var path instead:\n' +
+    '\n' +
+    '  1. Generate a token: https://supabase.com/dashboard/account/tokens\n' +
+    '  2. Export it in your shell:\n' +
+    '       export SUPABASE_ACCESS_TOKEN=sbp_...\n' +
+    '  3. Re-run: termdeck init --rumen\n' +
+    '\n' +
+    'TermDeck does not store this token — it only lives in your shell\n' +
+    'environment for the duration of the install.\n'
+  );
+}
+
 async function link(projectRef, dryRun) {
   step(`Running: supabase link --project-ref ${projectRef}...`);
   if (dryRun) { ok('(dry-run)'); return true; }
@@ -217,6 +246,7 @@ async function link(projectRef, dryRun) {
   if (!r.ok) {
     fail(`supabase link failed (exit ${r.code})`);
     if (r.stderr) process.stderr.write(r.stderr + '\n');
+    if (looksLikeMissingAccessToken(r.stderr)) printAccessTokenHint();
     return false;
   }
   ok();
@@ -512,3 +542,6 @@ if (require.main === module) {
 }
 
 module.exports = main;
+// Test surface — kept on the same export object so the regression suite can
+// pin the access-token detection without spawning a real `supabase` binary.
+module.exports._looksLikeMissingAccessToken = looksLikeMissingAccessToken;