@jhizzard/termdeck-stack 0.5.0 → 0.5.1

package/assets/hooks/memory-session-end.js

@@ -2,25 +2,40 @@
  * TermDeck session-end memory hook (Mnestra-direct, no rag-system dependency).
  *
  * Vendored into ~/.claude/hooks/memory-session-end.js by @jhizzard/termdeck-stack.
- * Wired into ~/.claude/settings.json under hooks.Stop. Fires on Claude Code Stop event.
+ * Wired into ~/.claude/settings.json under hooks.SessionEnd — fires once per
+ * Claude Code session close (`/exit`, Ctrl+D, terminal close, or process kill).
+ *
+ * History: this hook was originally registered under hooks.Stop, which fires
+ * after every assistant turn. That meant the same transcript got embedded and
+ * INSERTed dozens of times per session (and most fired with env-var-missing
+ * because Claude Code launched outside TermDeck doesn't have SUPABASE_URL in
+ * scope). Sprint 48 close-out moved registration to SessionEnd (one row per
+ * session, fires deterministically on /exit) AND added the secrets-env
+ * fallback below so a standalone-Claude-Code launch picks up the credentials
+ * without needing them in the parent shell.
  *
  * Behavior:
  *   1. Reads {transcript_path, cwd, session_id, sessionType?} from stdin (Claude
- *      Code Stop payload, or a future server-driven invocation for non-Claude
- *      agents).
- *   2. Skips small transcripts (< MIN_TRANSCRIPT_BYTES, default 5KB).
- *   3. Validates env vars; logs and exits cleanly if any required key is missing.
- *   4. Detects project from cwd against PROJECT_MAP (else "global"). Extend the
+ *      Code SessionEnd payload, or a future server-driven invocation for
+ *      non-Claude agents).
+ *   2. Loads ~/.termdeck/secrets.env into process.env if any required key is
+ *      absent OR is a literal `${VAR}` placeholder (Sprint 47.5 hotfix
+ *      discipline — Claude Code does not expand `${VAR}` in MCP env, and we
+ *      can't trust the parent shell to have sourced secrets.env).
+ *   3. Skips small transcripts (< MIN_TRANSCRIPT_BYTES, default 5KB).
+ *   4. Validates env vars; logs and exits cleanly if any required key is still
+ *      missing after the secrets.env fallback.
+ *   5. Detects project from cwd against PROJECT_MAP (else "global"). Extend the
  *      map by editing the array below — see assets/hooks/README.md for guidance.
- *   5. Dispatches to a transcript parser by sessionType (Sprint 45 T4): Claude
+ *   6. Dispatches to a transcript parser by sessionType (Sprint 45 T4): Claude
  *      JSONL, Codex JSONL, Gemini single-JSON, or auto-detect when sessionType
  *      is absent. Builds a coarse summary from the resulting message list
  *      (last ~30 message excerpts).
- *   6. Embeds the summary via OpenAI text-embedding-3-small.
- *   7. POSTs ONE row to Supabase /rest/v1/memory_items with source_type='session_summary'.
- *   8. Logs every step to ~/.claude/hooks/memory-hook.log.
+ *   7. Embeds the summary via OpenAI text-embedding-3-small.
+ *   8. POSTs ONE row to Supabase /rest/v1/memory_items with source_type='session_summary'.
+ *   9. Logs every step to ~/.claude/hooks/memory-hook.log.
  *
- * Required env vars (validated at entry):
+ * Required env vars (validated at entry, after the secrets.env fallback):
  *   - SUPABASE_URL              e.g. https://<project-ref>.supabase.co
  *   - SUPABASE_SERVICE_ROLE_KEY      service-role key (NOT the anon key — needs INSERT on memory_items)
  *   - OPENAI_API_KEY            sk-... for text-embedding-3-small
@@ -47,6 +62,14 @@ const os = require('os');
 
 const LOG_FILE = join(os.homedir(), '.claude', 'hooks', 'memory-hook.log');
 
+// Resolved per-call so tests can override via TERMDECK_HOOK_SECRETS_PATH
+// (the const-at-load-time pattern would freeze the path before any test
+// that mutates HOME or the override env var gets a chance to take effect).
+function resolveSecretsPath() {
+  return process.env.TERMDECK_HOOK_SECRETS_PATH
+    || join(os.homedir(), '.termdeck', 'secrets.env');
+}
+
 // PROJECT_MAP — minimal default. Users extend by adding entries to this array.
 // Patterns match against the cwd reported by Claude Code at Stop time.
 // First match wins; falls through to "global".
@@ -72,9 +95,59 @@ function detectProject(cwd) {
   return 'global';
 }
 
+// Treat values shaped like `${VAR}` as unset. Claude Code does not expand
+// shell placeholders in MCP env or hook env, so a literal `${SUPABASE_URL}`
+// is non-empty-but-invalid — the same trap that caused the Sprint 47.5
+// hotfix on the stack-installer + mnestra MCP. Mirroring that discipline
+// here keeps the hook resilient if any future tooling regresses to the
+// placeholder pattern.
+function isUnexpandedPlaceholder(v) {
+  return typeof v === 'string' && v.startsWith('${') && v.endsWith('}');
+}
+
+// Load ~/.termdeck/secrets.env into process.env when keys are absent or
+// hold an unexpanded `${VAR}` placeholder. Concrete values already in
+// process.env always win — the fallback only fills gaps. Silent no-op if
+// the file is missing. Mirrors mnestra's loadTermdeckSecretsFallback so
+// the hook works in three launch contexts:
+//   1. Inside TermDeck PTY (Sprint 48 T4 PTY env merge supplies the vars).
+//   2. Standalone Claude Code launched from a shell with secrets.env sourced.
+//   3. Standalone Claude Code launched from a vanilla shell (this fallback).
+function loadTermdeckSecretsFallback() {
+  const secretsPath = resolveSecretsPath();
+  if (!existsSync(secretsPath)) return;
+  let raw;
+  try { raw = readFileSync(secretsPath, 'utf8'); }
+  catch (err) {
+    log(`secrets-env-read-failed: ${err && err.message ? err.message : String(err)}`);
+    return;
+  }
+  let loaded = 0;
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const m = trimmed.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    const cur = process.env[key];
+    if (cur && !isUnexpandedPlaceholder(cur)) continue;
+    let v = m[2];
+    if (v.length >= 2 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0]) {
+      v = v.slice(1, -1);
+    }
+    process.env[key] = v;
+    loaded++;
+  }
+  if (loaded > 0) debug(`secrets-env-loaded: ${loaded} keys from ${secretsPath}`);
+}
+
 function readEnv() {
+  loadTermdeckSecretsFallback();
   const required = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'OPENAI_API_KEY'];
-  const missing = required.filter((k) => !process.env[k]);
+  const missing = required.filter((k) => {
+    const v = process.env[k];
+    return !v || isUnexpandedPlaceholder(v);
+  });
   if (missing.length) {
     log(`env-var-missing: ${missing.join(', ')} — set these in ~/.termdeck/secrets.env or your shell to enable Mnestra ingestion. Skipping.`);
     return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck-stack",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "One-command installer for the TermDeck developer memory stack: TermDeck + Mnestra + Rumen + Supabase MCP",
   "bin": {
     "termdeck-stack": "./src/index.js"

package/src/index.js

@@ -436,33 +436,60 @@ function _isSessionEndHookEntry(entry) {
     && entry.command.includes('memory-session-end.js');
 }
 
-// Pure: merges our Stop entry into the given settings object. Idempotent.
-// Returns { settings, status } where status is 'already-installed' or
-// 'installed'. Mutates the input.
+// Pure: merges our SessionEnd entry into the given settings object. Idempotent.
+// Returns { settings, status } where status is 'already-installed', 'installed',
+// or 'migrated-from-stop' (when an old `Stop` entry pointing at our hook is
+// detected and moved over to `SessionEnd`). Mutates the input.
+//
+// Why SessionEnd, not Stop: the `Stop` event fires after every assistant turn,
+// so a Stop-registered session-summary hook embeds + INSERTs the same growing
+// transcript dozens of times per session. The `SessionEnd` event fires once
+// per Claude Code session close (`/exit`, Ctrl+D, terminal close, kill) — the
+// correct semantics for "summarize this session." Sprint 48 close-out moved
+// the registration; the migration branch below heals existing installs from
+// `@jhizzard/termdeck-stack@<=0.5.0` that wired the hook under `Stop`.
 function _mergeSessionEndHookEntry(settings, opts = {}) {
   const command = opts.command || HOOK_COMMAND;
   const timeout = opts.timeout != null ? opts.timeout : HOOK_TIMEOUT_SECONDS;
+  const entry = { type: 'command', command, timeout };
 
   if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
-  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
 
-  for (const group of settings.hooks.Stop) {
+  // Migrate any pre-Sprint-48 Stop registration of OUR hook to SessionEnd.
+  // We only touch entries that match `_isSessionEndHookEntry` — any unrelated
+  // Stop hooks the user has are preserved verbatim.
+  let migrated = false;
+  if (Array.isArray(settings.hooks.Stop)) {
+    for (const group of settings.hooks.Stop) {
+      if (!group || !Array.isArray(group.hooks)) continue;
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter((e) => !_isSessionEndHookEntry(e));
+      if (group.hooks.length !== before) migrated = true;
+    }
+    settings.hooks.Stop = settings.hooks.Stop.filter(
+      (g) => g && Array.isArray(g.hooks) && g.hooks.length > 0
+    );
+    if (settings.hooks.Stop.length === 0) delete settings.hooks.Stop;
+  }
+
+  if (!Array.isArray(settings.hooks.SessionEnd)) settings.hooks.SessionEnd = [];
+
+  for (const group of settings.hooks.SessionEnd) {
     if (!group || !Array.isArray(group.hooks)) continue;
     if (group.hooks.some(_isSessionEndHookEntry)) {
-      return { settings, status: 'already-installed' };
+      return { settings, status: migrated ? 'migrated-from-stop' : 'already-installed' };
     }
   }
 
-  const entry = { type: 'command', command, timeout };
-  const emptyMatcher = settings.hooks.Stop.find(
+  const emptyMatcher = settings.hooks.SessionEnd.find(
     (g) => g && g.matcher === '' && Array.isArray(g.hooks)
   );
   if (emptyMatcher) {
     emptyMatcher.hooks.push(entry);
   } else {
-    settings.hooks.Stop.push({ matcher: '', hooks: [entry] });
+    settings.hooks.SessionEnd.push({ matcher: '', hooks: [entry] });
   }
-  return { settings, status: 'installed' };
+  return { settings, status: migrated ? 'migrated-from-stop' : 'installed' };
 }
 
 function _readSettingsJson(filePath) {
@@ -583,14 +610,23 @@ async function installSessionEndHook(opts = {}) {
   } else {
     const merged = _mergeSessionEndHookEntry(read.settings);
     if (merged.status === 'already-installed') {
-      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'settings.json Stop hook', 'already installed');
+      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'settings.json SessionEnd hook', 'already installed');
       settingsStatus = 'already-installed';
+    } else if (merged.status === 'migrated-from-stop') {
+      if (dryRun) {
+        statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would migrate Stop hook → SessionEnd in ${settingsPath}`);
+        settingsStatus = 'would-migrate';
+      } else {
+        _writeSettingsJson(settingsPath, merged.settings);
+        statusLine(`${ANSI.green}↻${ANSI.reset}`, 'settings.json SessionEnd hook', 'migrated from Stop (was firing on every turn)');
+        settingsStatus = 'migrated';
+      }
     } else if (dryRun) {
-      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would merge Stop hook into ${settingsPath}`);
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would merge SessionEnd hook into ${settingsPath}`);
       settingsStatus = 'would-install';
     } else {
       _writeSettingsJson(settingsPath, merged.settings);
-      statusLine(`${ANSI.green}+${ANSI.reset}`, 'settings.json Stop hook', 'merged');
+      statusLine(`${ANSI.green}+${ANSI.reset}`, 'settings.json SessionEnd hook', 'merged');
       settingsStatus = 'installed';
     }
   }

package/src/launcher.js

@@ -154,6 +154,87 @@ function ensureFirstRunConfig(_fs = fs) {
   return true;
 }
 
+// Sprint 49 T4 — walk up from the resolved `termdeck` binary to find the
+// installed `@jhizzard/termdeck` package root and require its agent-adapter
+// registry + mcp-autowire helper. The installer is a zero-dep package (no
+// `dependencies` field in package.json) so we cannot require these by package
+// name; instead we resolve by absolute path. Works for both global installs
+// (`/usr/local/lib/node_modules/@jhizzard/termdeck/...`) and dev checkouts
+// where the binary symlinks back into the source tree. Returns null when the
+// adapter tree isn't reachable — caller skips auto-wire with a warning.
+function loadTermdeckExports(termdeckBinary, _fs = fs) {
+  if (!termdeckBinary) return null;
+  let realPath;
+  try { realPath = _fs.realpathSync(termdeckBinary); }
+  catch (_) { return null; }
+  let dir = path.dirname(realPath);
+  for (let i = 0; i < 10; i++) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (_fs.existsSync(pkgPath)) {
+      let pkg;
+      try { pkg = JSON.parse(_fs.readFileSync(pkgPath, 'utf8')); }
+      catch (_) { pkg = null; }
+      if (pkg && pkg.name === '@jhizzard/termdeck') {
+        const adaptersPath = path.join(dir, 'packages/server/src/agent-adapters');
+        const autowirePath = path.join(dir, 'packages/server/src/mcp-autowire.js');
+        if (_fs.existsSync(adaptersPath) && _fs.existsSync(autowirePath)) {
+          try {
+            const adaptersMod = require(adaptersPath);
+            const autowireMod = require(autowirePath);
+            return {
+              adapters: adaptersMod.AGENT_ADAPTERS,
+              ensureMnestraBlock: autowireMod.ensureMnestraBlock,
+              packageRoot: dir,
+            };
+          } catch (_) { return null; }
+        }
+        return null;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// Sprint 49 T4 — iterates an adapter registry (record or array) and calls
+// `ensureMnestraBlock(adapter, opts)` for each adapter that declares a non-null
+// `mcpConfig`. Adapters with `mcpConfig: null` (Claude — user-managed via
+// `claude mcp add`) are skipped without invoking the helper. Helper exceptions
+// on a single adapter don't abort the loop — they're captured under
+// `errored[]` so the launcher can continue with the remaining adapters and
+// surface diagnostics in the step line.
+//
+// Returns { wired: string[], unchanged: string[], skipped: string[],
+//           errored: { name, error }[] } — caller renders a one-line summary.
+// Idempotent: a second call against an already-wired environment shifts every
+// adapter from `wired` to `unchanged` because the helper's per-shape
+// detect-existing branches return `{ unchanged: true }` on no-op writes.
+function autowireMcp(adapters, ensureMnestraBlockFn, opts = {}) {
+  const summary = { wired: [], unchanged: [], skipped: [], errored: [] };
+  if (!adapters || typeof ensureMnestraBlockFn !== 'function') return summary;
+  const list = Array.isArray(adapters) ? adapters : Object.values(adapters);
+  for (const adapter of list) {
+    const name = (adapter && adapter.name) || '<unknown>';
+    if (!adapter || !adapter.mcpConfig) {
+      summary.skipped.push(name);
+      continue;
+    }
+    let result;
+    try {
+      result = ensureMnestraBlockFn(adapter, opts);
+    } catch (err) {
+      summary.errored.push({ name, error: err && err.message ? err.message : String(err) });
+      continue;
+    }
+    if (result && result.wrote) summary.wired.push(name);
+    else if (result && result.unchanged) summary.unchanged.push(name);
+    else summary.skipped.push(name);
+  }
+  return summary;
+}
+
 function spawnDetached(command, args, logPath, env, _spawn = child_process.spawn, _fs = fs) {
   // open() the log file then pass the fd to spawn so the child inherits a
   // real disk-backed stdout/stderr. Close our handle after spawn so we
@@ -197,9 +278,9 @@ async function startStack(opts = {}) {
   const secrets = readSecrets(SECRETS_PATH, _fs);
   const secretCount = Object.keys(secrets).length;
   if (secretCount === 0) {
-    step('1/3', 'Loading secrets', 'WARN', `(no readable keys in ${SECRETS_PATH} — run \`npx @jhizzard/termdeck-stack\` to set up)`);
+    step('1/4', 'Loading secrets', 'WARN', `(no readable keys in ${SECRETS_PATH} — run \`npx @jhizzard/termdeck-stack\` to set up)`);
   } else {
-    step('1/3', 'Loading secrets', 'OK', `(${secretCount} keys from ${SECRETS_PATH})`);
+    step('1/4', 'Loading secrets', 'OK', `(${secretCount} keys from ${SECRETS_PATH})`);
   }
 
   // Resolve binaries.
@@ -210,32 +291,62 @@ async function startStack(opts = {}) {
   }
   const mnestraInvocation = resolveMnestraInvocation({ ..._deps, fs: _fs, whichBinary: _deps.whichBinary });
 
-  // Step 2: mnestra
+  // Step 2: auto-wire MCP for non-Claude adapters (Sprint 49 T4)
+  let autowireSummary = null;
+  if (opts.noWire) {
+    step('2/4', 'Auto-wiring MCP', 'SKIP', '(--no-wire)');
+  } else {
+    const termdeckExports = (_deps.termdeckExports !== undefined)
+      ? _deps.termdeckExports
+      : loadTermdeckExports(termdeckBinary, _fs);
+    if (!termdeckExports) {
+      step('2/4', 'Auto-wiring MCP', 'WARN', '(@jhizzard/termdeck adapter tree not resolvable — skipping)');
+    } else {
+      autowireSummary = autowireMcp(
+        termdeckExports.adapters,
+        termdeckExports.ensureMnestraBlock,
+        { secrets },
+      );
+      const parts = [];
+      for (const name of autowireSummary.wired) parts.push(`${name} (wrote)`);
+      for (const name of autowireSummary.unchanged) parts.push(`${name} (unchanged)`);
+      for (const e of autowireSummary.errored) parts.push(`${e.name} (error: ${e.error})`);
+      if (autowireSummary.wired.length === 0 && autowireSummary.unchanged.length === 0 && autowireSummary.errored.length === 0) {
+        step('2/4', 'Auto-wiring MCP', 'SKIP', '(no adapters declare mcpConfig)');
+      } else if (autowireSummary.errored.length > 0 && autowireSummary.wired.length === 0 && autowireSummary.unchanged.length === 0) {
+        step('2/4', 'Auto-wiring MCP', 'FAIL', parts.join(', '));
+      } else {
+        step('2/4', 'Auto-wiring MCP', 'OK', parts.join(', '));
+      }
+    }
+  }
+
+  // Step 3: mnestra
   const childEnv = { ...process.env, ...secrets };
   let mnestraPid = null;
   if (!mnestraInvocation) {
-    step('2/3', 'Starting Mnestra', 'SKIP', '(not installed — npm i -g @jhizzard/mnestra)');
+    step('3/4', 'Starting Mnestra', 'SKIP', '(not installed — npm i -g @jhizzard/mnestra)');
   } else if (!secrets.SUPABASE_URL || !secrets.SUPABASE_SERVICE_ROLE_KEY) {
-    step('2/3', 'Starting Mnestra', 'WARN', '(SUPABASE_URL / SERVICE_ROLE_KEY missing — run wizard)');
+    step('3/4', 'Starting Mnestra', 'WARN', '(SUPABASE_URL / SERVICE_ROLE_KEY missing — run wizard)');
   } else {
     const child = spawnDetached(mnestraInvocation.command, mnestraInvocation.args, MNESTRA_LOG_PATH, childEnv, _spawn, _fs);
     mnestraPid = child.pid;
     const health = await waitForHealth(`http://127.0.0.1:${mnestraPort}/healthz`, HEALTH_RETRIES, _fetch);
     if (health.ok) {
       const rows = (health.body && health.body.store && health.body.store.rows) || 0;
-      step('2/3', 'Starting Mnestra', 'OK', `(:${mnestraPort}, ${rows} memories)`);
+      step('3/4', 'Starting Mnestra', 'OK', `(:${mnestraPort}, ${rows} memories)`);
     } else {
-      step('2/3', 'Starting Mnestra', 'FAIL', `(no /healthz response — see ${MNESTRA_LOG_PATH})`);
+      step('3/4', 'Starting Mnestra', 'FAIL', `(no /healthz response — see ${MNESTRA_LOG_PATH})`);
     }
   }
 
-  // Step 3: termdeck
+  // Step 4: termdeck
   const termdeckChild = spawnDetached(termdeckBinary, ['--port', String(port), '--no-stack'], TERMDECK_LOG_PATH, childEnv, _spawn, _fs);
   const termdeckHealth = await waitForHealth(`http://127.0.0.1:${port}/api/health`, HEALTH_RETRIES, _fetch);
   if (termdeckHealth.ok) {
-    step('3/3', 'Starting TermDeck', 'OK', `(:${port})`);
+    step('4/4', 'Starting TermDeck', 'OK', `(:${port})`);
   } else {
-    step('3/3', 'Starting TermDeck', 'FAIL', `(no /api/health response — see ${TERMDECK_LOG_PATH})`);
+    step('4/4', 'Starting TermDeck', 'FAIL', `(no /api/health response — see ${TERMDECK_LOG_PATH})`);
   }
 
   const pidRecord = {
@@ -344,6 +455,8 @@ module.exports = {
   _ensureFirstRunConfig: ensureFirstRunConfig,
   _probeHealth: probeHealth,
   _spawnDetached: spawnDetached,
+  _autowireMcp: autowireMcp,
+  _loadTermdeckExports: loadTermdeckExports,
   PID_PATH,
   SECRETS_PATH,
   CONFIG_PATH,