@jhizzard/termdeck-stack 0.3.3 → 0.4.0

package/assets/hooks/README.md

@@ -0,0 +1,73 @@
+# TermDeck session-end memory hook
+
+The `@jhizzard/termdeck-stack` installer can drop `memory-session-end.js`
+into `~/.claude/hooks/` and wire it into `~/.claude/settings.json` under
+`hooks.Stop`. The installer prompts you before doing this; default is yes.
+
+## What the hook does
+
+On every Claude Code session close, Claude Code fires its `Stop` hook with
+a JSON payload on stdin:
+
+```json
+{ "transcript_path": "/path/to/session-transcript.jsonl", "cwd": "/path/where/you/were/working" }
+```
+
+The hook:
+
+1. Skips transcripts smaller than 5 KB (no signal in tiny sessions).
+2. Detects the project from `cwd` against a built-in regex table; falls
+   back to `"global"` when nothing matches.
+3. Spawns a detached ingester (`process-session.ts` from `rag-system`),
+   which reads the transcript and writes a session summary into Mnestra.
+4. Logs every step to `~/.claude/hooks/memory-hook.log`.
+
+The spawn is detached + unref'd, so Claude Code's session close is not
+blocked waiting for ingestion — the 30-second `timeout` in
+`settings.json` is a backstop, not a target.
+
+## Dependency on `rag-system`
+
+The hook delegates ingestion to a script inside the `rag-system` repo:
+
+```
+${RAG_DIR}/src/scripts/process-session.ts
+```
+
+`RAG_DIR` resolves in this order:
+
+1. `process.env.TERMDECK_RAG_DIR` (if set)
+2. `~/Documents/Graciella/rag-system` (default — Joshua's layout)
+
+**If the resolved `RAG_DIR` does not exist on disk, the hook logs that
+fact and exits cleanly.** It does not error, does not block session
+close, and does not leak a spawn. Fresh users who installed the stack
+but do not have `rag-system` checked out will see this skip-message in
+the log and nothing else — as if no hook were installed.
+
+A future TermDeck sprint will rewrite the hook to call Mnestra's MCP
+tools directly so the `rag-system` dependency drops away. Until then,
+this hook is most useful for users who already have `rag-system`
+available.
+
+## How to disable
+
+Two options:
+
+1. Edit `~/.claude/settings.json` and remove the entry under `hooks.Stop`
+   that references `memory-session-end.js`. Leave the file in place; it
+   simply won't fire.
+2. Or delete `~/.claude/hooks/memory-session-end.js` and remove the
+   `settings.json` entry. (Removing only the file leaves a broken
+   `command` in settings — Claude Code will log a missing-file error on
+   every session close.)
+
+Re-running `npx @jhizzard/termdeck-stack` after disabling will re-prompt
+to install. Decline at the prompt to stay opted out.
+
+## Log file
+
+`~/.claude/hooks/memory-hook.log` accumulates one line per session-close
+event. The hook never rotates it. If it grows unwieldy you can truncate
+it (`: > ~/.claude/hooks/memory-hook.log`) without affecting hook
+behavior.

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

@@ -0,0 +1,113 @@
+/**
+ * TermDeck session-end memory hook.
+ *
+ * Vendored from Joshua's ~/.claude/hooks/memory-session-end.js (2026-03-11).
+ * Installed by `@jhizzard/termdeck-stack` into ~/.claude/hooks/ and wired
+ * into ~/.claude/settings.json under hooks.Stop. Fires on every Claude Code
+ * session close.
+ *
+ * Behavior:
+ *   1. Reads {transcript_path, cwd} from stdin (Claude Code's Stop payload).
+ *   2. Skips small transcripts (<5KB).
+ *   3. Detects project from cwd against PROJECT_MAP (else "global").
+ *   4. Spawns the rag-system ingester detached, returns immediately.
+ *   5. Logs to ~/.claude/hooks/memory-hook.log.
+ *
+ * Path resolution (parameterized for portability — was hardcoded in source):
+ *   RAG_DIR := process.env.TERMDECK_RAG_DIR
+ *           || path.join(os.homedir(), 'Documents/Graciella/rag-system')
+ *
+ * If the resolved RAG_DIR doesn't exist on disk, the hook logs and exits
+ * cleanly. Fresh users who haven't installed rag-system get a no-op hook
+ * rather than a spawn error. See assets/hooks/README.md for the full story.
+ */
+
+const { spawn } = require('child_process');
+const { existsSync, statSync, appendFileSync } = require('fs');
+const { join } = require('path');
+const os = require('os');
+
+const RAG_DIR = process.env.TERMDECK_RAG_DIR
+  || join(os.homedir(), 'Documents', 'Graciella', 'rag-system');
+const PROCESS_SCRIPT = join(RAG_DIR, 'src', 'scripts', 'process-session.ts');
+const LOG_FILE = join(os.homedir(), '.claude', 'hooks', 'memory-hook.log');
+
+const PROJECT_MAP = [
+  { pattern: /\/PVB\//i, project: 'pvb' },
+  { pattern: /chopin-scheduler|chopin_scheduler/i, project: 'chopin-scheduler' },
+  { pattern: /ChopinNashville|ChopinInBohemia/i, project: 'chopin-nashville' },
+  { pattern: /rag-system/i, project: 'rag-system' },
+  { pattern: /PianoCameraAI/i, project: 'piano-camera' },
+  { pattern: /Practice Piano Network/i, project: 'ppn' },
+  { pattern: /StanczakJosh/i, project: 'stanczak' },
+  { pattern: /JoshIzPiano/i, project: 'joshizpiano' },
+  { pattern: /AutumnArtist/i, project: 'autumn-artist' },
+  { pattern: /Crosswords/i, project: 'crosswords' },
+  { pattern: /gorgias/i, project: 'gorgias' },
+  { pattern: /imessage-reader/i, project: 'imessage-reader' },
+  { pattern: /antigravity/i, project: 'antigravity' },
+];
+
+function detectProject(cwd) {
+  for (const { pattern, project } of PROJECT_MAP) {
+    if (pattern.test(cwd)) return project;
+  }
+  return 'global';
+}
+
+function log(msg) {
+  try {
+    appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`);
+  } catch (_) {}
+}
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const transcriptPath = data.transcript_path;
+    const cwd = data.cwd || '';
+
+    if (!transcriptPath) {
+      log('No transcript_path in input, skipping');
+      return;
+    }
+
+    try {
+      const stat = statSync(transcriptPath);
+      if (stat.size < 5000) {
+        log(`Skipping small transcript (${stat.size} bytes): ${transcriptPath}`);
+        return;
+      }
+    } catch (e) {
+      log(`Cannot stat transcript: ${transcriptPath} — ${e.message}`);
+      return;
+    }
+
+    if (!existsSync(PROCESS_SCRIPT)) {
+      log(`RAG_DIR not present (${RAG_DIR}); skipping ingestion. Set TERMDECK_RAG_DIR or install rag-system to enable.`);
+      return;
+    }
+
+    const project = detectProject(cwd);
+    log(`Processing session for project "${project}" from ${transcriptPath}`);
+
+    const child = spawn(
+      'npx',
+      ['tsx', PROCESS_SCRIPT, transcriptPath, '--project', project],
+      {
+        cwd: RAG_DIR,
+        detached: true,
+        stdio: 'ignore',
+        env: { ...process.env, DOTENV_CONFIG_PATH: join(RAG_DIR, '.env') },
+      }
+    );
+    child.unref();
+
+    log(`Spawned process-session (pid ${child.pid}) for project "${project}"`);
+  } catch (e) {
+    log(`Error: ${e.message}`);
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck-stack",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "One-command installer for the TermDeck developer memory stack: TermDeck + Mnestra + Rumen + Supabase MCP",
   "bin": {
     "termdeck-stack": "./src/index.js"
@@ -8,6 +8,7 @@
   "main": "./src/index.js",
   "files": [
     "src/**",
+    "assets/**",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/src/index.js

@@ -29,6 +29,16 @@ const path = require('node:path');
 const readline = require('node:readline/promises');
 const { spawn, spawnSync } = require('node:child_process');
 
+const mcpConfigLib = require('./mcp-config');
+const {
+  CLAUDE_MCP_PATH_CANONICAL,
+  CLAUDE_MCP_PATH_LEGACY,
+  readMcpServers,
+  mergeMcpServers,
+  writeMcpServers,
+  migrateLegacyIfPresent,
+} = mcpConfigLib;
+
 const ANSI = {
   green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', blue: '\x1b[34m',
   cyan: '\x1b[36m', magenta: '\x1b[35m', dim: '\x1b[2m', bold: '\x1b[1m',
@@ -36,7 +46,13 @@ const ANSI = {
 };
 
 const HOME = os.homedir();
-const MCP_CONFIG = path.join(HOME, '.claude', 'mcp.json');
+const MCP_CONFIG = CLAUDE_MCP_PATH_CANONICAL;
+const SETTINGS_JSON = path.join(HOME, '.claude', 'settings.json');
+const HOOK_DEST_DIR = path.join(HOME, '.claude', 'hooks');
+const HOOK_DEST = path.join(HOOK_DEST_DIR, 'memory-session-end.js');
+const HOOK_SOURCE = path.join(__dirname, '..', 'assets', 'hooks', 'memory-session-end.js');
+const HOOK_COMMAND = 'node ~/.claude/hooks/memory-session-end.js';
+const HOOK_TIMEOUT_SECONDS = 30;
 
 const LAYERS = [
   {
@@ -249,36 +265,40 @@ async function installLayers(plan, opts) {
   return failures;
 }
 
-// ── ~/.claude/mcp.json wiring ───────────────────────────────────────
-
-function readMcpConfig() {
-  if (!fs.existsSync(MCP_CONFIG)) return { mcpServers: {} };
-  try {
-    const parsed = JSON.parse(fs.readFileSync(MCP_CONFIG, 'utf8'));
-    if (!parsed.mcpServers) parsed.mcpServers = {};
-    return parsed;
-  } catch (_e) {
-    return { mcpServers: {} };
-  }
-}
-
-function writeMcpConfig(cfg) {
-  fs.mkdirSync(path.dirname(MCP_CONFIG), { recursive: true });
-  fs.writeFileSync(MCP_CONFIG, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
-}
+// ── ~/.claude.json wiring ───────────────────────────────────────────
+//
+// Sprint 36 T2: writes go to ~/.claude.json (the path Claude Code v2.1.119+
+// actually reads). On install, any entries living in the legacy
+// ~/.claude/mcp.json are merged forward — the legacy file is left in place
+// so users who pin other tooling to it keep working.
 
 function wireMcpEntries(plan, opts) {
   if (opts.dryRun) {
-    process.stdout.write(`${ANSI.bold}Would wire ~/.claude/mcp.json (dry-run skipped)${ANSI.reset}\n\n`);
+    process.stdout.write(`${ANSI.bold}Would wire ${MCP_CONFIG} (dry-run skipped)${ANSI.reset}\n\n`);
     return;
   }
-  const cfg = readMcpConfig();
+
+  // Step 1: forward-migrate any legacy entries, current always wins.
+  const migration = migrateLegacyIfPresent({ canonicalPath: MCP_CONFIG, legacyPath: CLAUDE_MCP_PATH_LEGACY });
+
+  // Step 2: re-read the canonical file (may have just been written by the
+  // migration) and apply our additions.
+  const current = readMcpServers(MCP_CONFIG);
+  if (current.malformed) {
+    process.stdout.write(
+      `${ANSI.red}✗${ANSI.reset} ${MCP_CONFIG} is malformed (${current.error || 'parse error'}); ` +
+      `not modified — fix the JSON and re-run.\n\n`
+    );
+    return;
+  }
+  const servers = { ...current.servers };
   const installedTiers = new Set(plan.map((l) => l.tier));
   const additions = [];
   const keptExisting = [];
 
-  if (installedTiers.has(2) && !cfg.mcpServers.mnestra) {
-    cfg.mcpServers.mnestra = {
+  if (installedTiers.has(2) && !servers.mnestra) {
+    servers.mnestra = {
+      type: 'stdio',
       command: 'mnestra',
       env: {
         SUPABASE_URL: '${SUPABASE_URL}',
@@ -287,12 +307,13 @@ function wireMcpEntries(plan, opts) {
       },
     };
     additions.push('mnestra');
-  } else if (cfg.mcpServers.mnestra) {
+  } else if (servers.mnestra) {
     keptExisting.push('mnestra');
   }
 
-  if (installedTiers.has(4) && !cfg.mcpServers.supabase) {
-    cfg.mcpServers.supabase = {
+  if (installedTiers.has(4) && !servers.supabase) {
+    servers.supabase = {
+      type: 'stdio',
       command: 'npx',
       args: ['-y', '@supabase/mcp-server-supabase@latest'],
       env: {
@@ -300,19 +321,215 @@ function wireMcpEntries(plan, opts) {
       },
     };
     additions.push('supabase');
-  } else if (cfg.mcpServers.supabase) {
+  } else if (servers.supabase) {
     keptExisting.push('supabase');
   }
 
-  if (additions.length === 0 && keptExisting.length === 0) return;
+  const migrated = (migration && migration.migrated) || [];
+  if (additions.length === 0 && keptExisting.length === 0 && migrated.length === 0) return;
 
-  process.stdout.write(`${ANSI.bold}Wiring ~/.claude/mcp.json...${ANSI.reset}\n`);
+  process.stdout.write(`${ANSI.bold}Wiring ${MCP_CONFIG}...${ANSI.reset}\n`);
+  if (migrated.length > 0) {
+    statusLine(
+      `${ANSI.cyan}↑${ANSI.reset}`,
+      `migrated ${migrated.length} entr${migrated.length === 1 ? 'y' : 'ies'} from legacy`,
+      `${migrated.join(', ')} (legacy ${CLAUDE_MCP_PATH_LEGACY} left in place)`,
+    );
+  }
   for (const name of additions) statusLine(`${ANSI.green}+${ANSI.reset}`, `${name} entry`, 'added');
   for (const name of keptExisting) statusLine(`${ANSI.dim}=${ANSI.reset}`, `${name} entry`, 'already present, kept as-is');
-  if (additions.length > 0) writeMcpConfig(cfg);
+  if (additions.length > 0) writeMcpServers(MCP_CONFIG, servers);
   process.stdout.write('\n');
 }
 
+// Test hook — exposed so unit tests can drive the merge primitives without
+// spawning a full installer. Not part of the public CLI surface.
+const _mcpInternals = {
+  readMcpServers,
+  mergeMcpServers,
+  writeMcpServers,
+  migrateLegacyIfPresent,
+};
+
+// ── Session-end hook bundling ───────────────────────────────────────
+
+// Returns true if the given hook-entry's `command` string references our
+// session-end hook file. Substring match is robust to `~` vs `$HOME` vs
+// absolute paths.
+function _isSessionEndHookEntry(entry) {
+  return entry && typeof entry.command === 'string'
+    && 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.
+function _mergeSessionEndHookEntry(settings, opts = {}) {
+  const command = opts.command || HOOK_COMMAND;
+  const timeout = opts.timeout != null ? opts.timeout : HOOK_TIMEOUT_SECONDS;
+
+  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) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    if (group.hooks.some(_isSessionEndHookEntry)) {
+      return { settings, status: 'already-installed' };
+    }
+  }
+
+  const entry = { type: 'command', command, timeout };
+  const emptyMatcher = settings.hooks.Stop.find(
+    (g) => g && g.matcher === '' && Array.isArray(g.hooks)
+  );
+  if (emptyMatcher) {
+    emptyMatcher.hooks.push(entry);
+  } else {
+    settings.hooks.Stop.push({ matcher: '', hooks: [entry] });
+  }
+  return { settings, status: 'installed' };
+}
+
+function _readSettingsJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { settings: {}, status: 'no-file' };
+  }
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    if (raw.trim() === '') return { settings: {}, status: 'empty' };
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { settings: {}, status: 'malformed', error: 'top-level must be an object' };
+    }
+    return { settings: parsed, status: 'ok' };
+  } catch (e) {
+    return { settings: {}, status: 'malformed', error: e.message };
+  }
+}
+
+function _writeSettingsJson(filePath, settings) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+// Compares two file contents byte-for-byte. Returns 'identical', 'different',
+// or 'missing-dest'.
+function _compareHookFiles(srcPath, destPath) {
+  if (!fs.existsSync(destPath)) return 'missing-dest';
+  const a = fs.readFileSync(srcPath);
+  const b = fs.readFileSync(destPath);
+  return a.equals(b) ? 'identical' : 'different';
+}
+
+async function promptYesNo({ question, defaultYes = true }) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultYes ? '(Y/n)' : '(y/N)';
+  const ans = (await rl.question(`  ${question} ${suffix} `)).trim().toLowerCase();
+  rl.close();
+  if (ans === '') return defaultYes;
+  return ans === 'y' || ans === 'yes';
+}
+
+// Orchestrator: prompt → file copy → settings.json merge.
+// Exposed so tests can drive it with explicit paths and a stub prompt.
+async function installSessionEndHook(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const sourcePath = opts.sourcePath || HOOK_SOURCE;
+  const destPath = opts.destPath || HOOK_DEST;
+  const settingsPath = opts.settingsPath || SETTINGS_JSON;
+  // promptInstall: () => Promise<boolean>; defaults to Y.
+  // promptOverwrite: () => Promise<boolean>; defaults to N.
+  const promptInstall = opts.promptInstall
+    || (() => promptYesNo({ question: "Install TermDeck's session-end memory hook?", defaultYes: true }));
+  const promptOverwrite = opts.promptOverwrite
+    || (() => promptYesNo({
+      question: `Existing hook found at ${destPath}. Overwrite?`,
+      defaultYes: false,
+    }));
+
+  rule();
+  process.stdout.write(`${ANSI.bold}Session-end memory hook${ANSI.reset}\n`);
+  process.stdout.write(`${ANSI.dim}  Fires on every Claude Code session close to summarize the session into Mnestra.${ANSI.reset}\n\n`);
+
+  const userWantsInstall = opts.assumeYes ? true
+    : opts.assumeNo ? false
+    : await promptInstall();
+
+  if (!userWantsInstall) {
+    statusLine(`${ANSI.dim}─${ANSI.reset}`, 'session-end hook', 'skipped (user declined)');
+    process.stdout.write('\n');
+    return { fileStatus: 'declined', settingsStatus: 'declined' };
+  }
+
+  // 1. File copy.
+  let fileStatus;
+  const cmp = _compareHookFiles(sourcePath, destPath);
+  if (cmp === 'missing-dest') {
+    if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would copy hook to ${destPath}`);
+      fileStatus = 'would-copy';
+    } else {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(sourcePath, destPath);
+      fs.chmodSync(destPath, 0o644);
+      statusLine(`${ANSI.green}+${ANSI.reset}`, 'hook file', `copied to ${destPath}`);
+      fileStatus = 'copied';
+    }
+  } else if (cmp === 'identical') {
+    statusLine(`${ANSI.dim}=${ANSI.reset}`, 'hook file', 'already present, identical contents');
+    fileStatus = 'already-current';
+  } else {
+    // different
+    const overwrite = opts.assumeYes ? false // --yes preserves existing on overwrite
+      : opts.forceOverwrite ? true
+      : await promptOverwrite();
+    if (!overwrite) {
+      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'hook file', `existing kept (differs from vendored copy)`);
+      fileStatus = 'kept-existing';
+    } else if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would overwrite ${destPath}`);
+      fileStatus = 'would-overwrite';
+    } else {
+      fs.copyFileSync(sourcePath, destPath);
+      fs.chmodSync(destPath, 0o644);
+      statusLine(`${ANSI.green}↻${ANSI.reset}`, 'hook file', `overwrote ${destPath}`);
+      fileStatus = 'overwritten';
+    }
+  }
+
+  // 2. Settings.json merge.
+  const read = _readSettingsJson(settingsPath);
+  let settingsStatus;
+  if (read.status === 'malformed') {
+    statusLine(`${ANSI.red}✗${ANSI.reset}`, 'settings.json', `malformed (${read.error}); not modified`);
+    settingsStatus = 'malformed';
+  } else {
+    const merged = _mergeSessionEndHookEntry(read.settings);
+    if (merged.status === 'already-installed') {
+      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'settings.json Stop hook', 'already installed');
+      settingsStatus = 'already-installed';
+    } else if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would merge Stop hook into ${settingsPath}`);
+      settingsStatus = 'would-install';
+    } else {
+      _writeSettingsJson(settingsPath, merged.settings);
+      statusLine(`${ANSI.green}+${ANSI.reset}`, 'settings.json Stop hook', 'merged');
+      settingsStatus = 'installed';
+    }
+  }
+
+  process.stdout.write('\n');
+  if (!dryRun && (fileStatus === 'copied' || settingsStatus === 'installed')) {
+    process.stdout.write(`  ${ANSI.dim}Hook installed at ${destPath}.${ANSI.reset}\n`);
+    process.stdout.write(`  ${ANSI.dim}It runs on every Claude Code session close to summarize the session into Mnestra.${ANSI.reset}\n`);
+    process.stdout.write(`  ${ANSI.dim}See assets/hooks/README.md in @jhizzard/termdeck-stack for details.${ANSI.reset}\n\n`);
+  }
+
+  return { fileStatus, settingsStatus };
+}
+
 // ── Next steps ──────────────────────────────────────────────────────
 
 function printNextSteps(plan, opts) {
@@ -405,6 +622,13 @@ async function main(argv) {
   // "already had everything but never set up Claude Code MCP" case.
   wireMcpEntries(wantedLayers, { dryRun: args.dryRun });
 
+  // Bundle the session-end memory hook (default-on, opt-in via prompt).
+  // --yes accepts the install but preserves any existing differing hook.
+  await installSessionEndHook({
+    dryRun: args.dryRun,
+    assumeYes: args.yes,
+  });
+
   printNextSteps(wantedLayers, { dryRun: args.dryRun });
 
   if (failures > 0) {
@@ -422,3 +646,16 @@ if (require.main === module) {
 }
 
 module.exports = main;
+module.exports._mergeSessionEndHookEntry = _mergeSessionEndHookEntry;
+module.exports._readSettingsJson = _readSettingsJson;
+module.exports._writeSettingsJson = _writeSettingsJson;
+module.exports._isSessionEndHookEntry = _isSessionEndHookEntry;
+module.exports._compareHookFiles = _compareHookFiles;
+module.exports.installSessionEndHook = installSessionEndHook;
+module.exports.HOOK_COMMAND = HOOK_COMMAND;
+module.exports.HOOK_TIMEOUT_SECONDS = HOOK_TIMEOUT_SECONDS;
+module.exports.HOOK_SOURCE = HOOK_SOURCE;
+module.exports._mcpInternals = _mcpInternals;
+module.exports.MCP_CONFIG_PATH = MCP_CONFIG;
+module.exports.CLAUDE_MCP_PATH_CANONICAL = CLAUDE_MCP_PATH_CANONICAL;
+module.exports.CLAUDE_MCP_PATH_LEGACY = CLAUDE_MCP_PATH_LEGACY;

package/src/mcp-config.js

@@ -0,0 +1,138 @@
+'use strict';
+
+// Canonical schema/CRUD for the Claude Code MCP server config.
+//
+// SIBLING COPY of packages/cli/src/mcp-config.js. Two physical copies
+// exist so each published npm package (@jhizzard/termdeck and
+// @jhizzard/termdeck-stack) stays self-contained — the stack-installer's
+// `files` field publishes only `src/**` and cannot require() into the
+// CLI package. Same exports, same semantics. Keep in sync.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CLAUDE_MCP_PATH_CANONICAL = path.join(os.homedir(), '.claude.json');
+const CLAUDE_MCP_PATH_LEGACY = path.join(os.homedir(), '.claude', 'mcp.json');
+
+function readMcpServers(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { servers: {}, raw: {}, missing: true, malformed: false };
+  }
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: err.message };
+  }
+  if (text.trim() === '') {
+    return { servers: {}, raw: {}, missing: false, malformed: false };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: err.message };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: 'top-level must be an object' };
+  }
+  const servers = (parsed.mcpServers && typeof parsed.mcpServers === 'object' && !Array.isArray(parsed.mcpServers))
+    ? parsed.mcpServers
+    : {};
+  return { servers, raw: parsed, missing: false, malformed: false };
+}
+
+function mergeMcpServers(currentServers, legacyServers) {
+  const out = {};
+  const legacy = (legacyServers && typeof legacyServers === 'object') ? legacyServers : {};
+  const current = (currentServers && typeof currentServers === 'object') ? currentServers : {};
+  for (const [name, entry] of Object.entries(legacy)) {
+    out[name] = entry;
+  }
+  for (const [name, entry] of Object.entries(current)) {
+    out[name] = entry;
+  }
+  return out;
+}
+
+function writeMcpServers(filePath, servers) {
+  const existing = readMcpServers(filePath);
+  const next = (existing.malformed || existing.missing)
+    ? {}
+    : { ...existing.raw };
+  next.mcpServers = servers || {};
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+  try { fs.chmodSync(filePath, 0o600); } catch (_e) { /* best-effort */ }
+}
+
+function migrateLegacyIfPresent(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const canonicalPath = opts.canonicalPath || CLAUDE_MCP_PATH_CANONICAL;
+  const legacyPath = opts.legacyPath || CLAUDE_MCP_PATH_LEGACY;
+
+  const canonical = readMcpServers(canonicalPath);
+  const legacy = readMcpServers(legacyPath);
+
+  const malformed = {};
+  if (canonical.malformed) malformed.canonical = canonical.error || true;
+  if (legacy.malformed) malformed.legacy = legacy.error || true;
+
+  if (legacy.missing || legacy.malformed) {
+    return {
+      migrated: [],
+      kept: [],
+      wrote: false,
+      canonicalPath,
+      legacyPath,
+      malformed: Object.keys(malformed).length ? malformed : undefined,
+    };
+  }
+
+  const migrated = [];
+  const kept = [];
+  const merged = { ...canonical.servers };
+  for (const [name, entry] of Object.entries(legacy.servers)) {
+    if (Object.prototype.hasOwnProperty.call(canonical.servers, name)) {
+      kept.push(name);
+    } else {
+      merged[name] = entry;
+      migrated.push(name);
+    }
+  }
+
+  if (migrated.length === 0) {
+    return {
+      migrated: [],
+      kept,
+      wrote: false,
+      canonicalPath,
+      legacyPath,
+      malformed: Object.keys(malformed).length ? malformed : undefined,
+    };
+  }
+
+  if (!dryRun) writeMcpServers(canonicalPath, merged);
+
+  return {
+    migrated,
+    kept,
+    wrote: !dryRun,
+    canonicalPath,
+    legacyPath,
+    malformed: Object.keys(malformed).length ? malformed : undefined,
+  };
+}
+
+module.exports = {
+  CLAUDE_MCP_PATH_CANONICAL,
+  CLAUDE_MCP_PATH_LEGACY,
+  readMcpServers,
+  mergeMcpServers,
+  writeMcpServers,
+  migrateLegacyIfPresent,
+};