@jhizzard/termdeck-stack 0.4.0 → 0.4.1

package/assets/hooks/README.md

@@ -2,72 +2,131 @@
 
 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.
+`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:
+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" }
+{ "transcript_path": "/path/to/session.jsonl", "cwd": "/path/where/you/were/working", "session_id": "..." }
 ```
 
 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`.
+1. Skips transcripts smaller than 5 KB (no signal in tiny sessions —
+   override via `TERMDECK_HOOK_MIN_BYTES`).
+2. Validates env vars (`SUPABASE_URL`, `SUPABASE_SERVICE_KEY`,
+   `OPENAI_API_KEY`); if any are missing, logs the missing list and
+   exits cleanly without blocking the session close.
+3. Detects the project from `cwd` against a built-in regex table; falls
+   back to `"global"` when nothing matches. **The default table is
+   intentionally empty** — see "Customizing the project map" below to
+   add your own entries.
+4. Builds a coarse session summary from the last ~30 messages of the
+   transcript (~7 KB cap to stay inside OpenAI's embedding-input
+   budget).
+5. Embeds the summary via OpenAI `text-embedding-3-small` (1,536-dim).
+6. POSTs **one row** to Supabase `/rest/v1/memory_items` with
+   `source_type='session_summary'`.
+7. Logs every step to `~/.claude/hooks/memory-hook.log`.
+
+The hook is **fail-soft**: any error (network, parse, env-var-missing,
+malformed transcript) is logged and the hook exits 0. Claude Code's
+session close is never blocked.
+
+## Required environment
+
+The hook needs three env vars at run time:
+
+| Var | What | How to set |
+|---|---|---|
+| `SUPABASE_URL` | Your Supabase project URL (e.g. `https://abc.supabase.co`) | `~/.termdeck/secrets.env` (Tier 2) |
+| `SUPABASE_SERVICE_KEY` | Service-role key with INSERT on `memory_items`. **Not the anon key.** | `~/.termdeck/secrets.env` |
+| `OPENAI_API_KEY` | OpenAI key for embedding inference | `~/.termdeck/secrets.env` or your shell |
+
+Claude Code propagates the parent shell's environment into hook
+processes, so anything in your shell init or
+`~/.termdeck/secrets.env` (sourced by `scripts/start.sh` /
+`npx @jhizzard/termdeck`) is visible to the hook.
+
+If any of the three is missing the log line will name them:
 
-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.
+```
+[2026-04-27T21:30:00.000Z] env-var-missing: OPENAI_API_KEY — set these in ~/.termdeck/secrets.env or your shell to enable Mnestra ingestion. Skipping.
+```
 
-## Dependency on `rag-system`
+## Customizing the project map
 
-The hook delegates ingestion to a script inside the `rag-system` repo:
+The hook ships with an **empty `PROJECT_MAP`** by default — every
+session lands under `project: 'global'` until you add entries. To add
+your own:
 
-```
-${RAG_DIR}/src/scripts/process-session.ts
+1. Open `~/.claude/hooks/memory-session-end.js` after the installer
+   has dropped it.
+2. Find the `PROJECT_MAP` array near the top of the file.
+3. Add one entry per project; each entry is `{ pattern, project }`
+   where `pattern` is a regex matched against `cwd`:
+
+```js
+const PROJECT_MAP = [
+  { pattern: /\/PVB\//i,           project: 'pvb' },
+  { pattern: /\/my-startup\//i,    project: 'my-startup' },
+  { pattern: /chopin-nashville/i,  project: 'chopin-nashville' },
+];
 ```
 
-`RAG_DIR` resolves in this order:
+First match wins. Iteration order is array order, so put more specific
+patterns first. Anything that doesn't match falls through to
+`'global'`.
 
-1. `process.env.TERMDECK_RAG_DIR` (if set)
-2. `~/Documents/Graciella/rag-system` (default — Joshua's layout)
+The map is local-only — it's never sent to any service. Editing it
+takes effect on the next Claude Code session close (no restart
+needed).
 
-**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.
+## Coexistence with Joshua's `rag-system` hook
 
-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.
+If you have Joshua's private `rag-system` repo and his rag-system-based
+session hook installed, this bundled hook and that one can coexist:
+
+- The bundled hook writes `source_type='session_summary'` — one row
+  per session, summary-only.
+- The `rag-system` hook writes `source_type='fact'` — multiple rows
+  per session via Claude Haiku fact extraction + dedup.
+
+Different `source_type` values mean the two paths don't dedup against
+each other. If both are installed at the same path
+(`~/.claude/hooks/memory-session-end.js`) the installer will prompt
+before overwriting; choose accordingly.
 
 ## 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
+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.)
+   `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.
+
+## Optional flags
 
-Re-running `npx @jhizzard/termdeck-stack` after disabling will re-prompt
-to install. Decline at the prompt to stay opted out.
+| Env var | Effect |
+|---|---|
+| `TERMDECK_HOOK_DEBUG=1` | Verbose `[debug]` lines in the log |
+| `TERMDECK_HOOK_MIN_BYTES=10000` | Override the 5 KB skip threshold |
 
 ## 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
+`~/.claude/hooks/memory-hook.log` accumulates one line per session
+event (skips, errors, ingests). 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

@@ -1,53 +1,64 @@
 /**
- * TermDeck session-end memory hook.
+ * TermDeck session-end memory hook (Mnestra-direct, no rag-system dependency).
  *
- * 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.
+ * 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.
  *
  * 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.
+ *   1. Reads {transcript_path, cwd, session_id} from stdin (Claude Code Stop payload).
+ *   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
+ *      map by editing the array below — see assets/hooks/README.md for guidance.
+ *   5. Builds a coarse session summary from the transcript (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.
  *
- * Path resolution (parameterized for portability — was hardcoded in source):
- *   RAG_DIR := process.env.TERMDECK_RAG_DIR
- *           || path.join(os.homedir(), 'Documents/Graciella/rag-system')
+ * Required env vars (validated at entry):
+ *   - SUPABASE_URL              e.g. https://luvvbrpaopnblvxdxwzb.supabase.co
+ *   - SUPABASE_SERVICE_KEY      service-role key (NOT the anon key — needs INSERT on memory_items)
+ *   - OPENAI_API_KEY            sk-... for text-embedding-3-small
  *
- * 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.
+ * Optional:
+ *   - TERMDECK_HOOK_DEBUG=1            verbose logging
+ *   - TERMDECK_HOOK_MIN_BYTES=5000     transcript size threshold
+ *
+ * Fail-soft contract: any error (network, parse, env-var-missing, malformed transcript)
+ * logs and exits 0. Never blocks Claude Code session close.
+ *
+ * Co-existence with Joshua's personal rag-system hook: this bundled hook writes
+ * source_type='session_summary' (one row per session). Joshua's personal hook
+ * writes source_type='fact' (multiple rows from extractFacts pipeline). Different
+ * source_types coexist in memory_items without dedup collisions.
  */
 
-const { spawn } = require('child_process');
-const { existsSync, statSync, appendFileSync } = require('fs');
+'use strict';
+
+const { existsSync, statSync, appendFileSync, readFileSync } = 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');
 
+// 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".
 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' },
+  // Example entries — uncomment + edit, or add your own:
+  // { pattern: /\/myproject\//i,        project: 'my-project' },
+  // { pattern: /work-stuff/i,           project: 'work' },
 ];
 
+const MIN_TRANSCRIPT_BYTES = parseInt(process.env.TERMDECK_HOOK_MIN_BYTES || '5000', 10);
+const DEBUG = process.env.TERMDECK_HOOK_DEBUG === '1';
+
+function log(msg) {
+  try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`); }
+  catch (_) { /* fail-soft */ }
+}
+function debug(msg) { if (DEBUG) log(`[debug] ${msg}`); }
+
 function detectProject(cwd) {
   for (const { pattern, project } of PROJECT_MAP) {
     if (pattern.test(cwd)) return project;
@@ -55,59 +66,173 @@ function detectProject(cwd) {
   return 'global';
 }
 
-function log(msg) {
-  try {
-    appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`);
-  } catch (_) {}
+function readEnv() {
+  const required = ['SUPABASE_URL', 'SUPABASE_SERVICE_KEY', 'OPENAI_API_KEY'];
+  const missing = required.filter((k) => !process.env[k]);
+  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;
+  }
+  return {
+    supabaseUrl: process.env.SUPABASE_URL.replace(/\/$/, ''),
+    supabaseKey: process.env.SUPABASE_SERVICE_KEY,
+    openaiKey: process.env.OPENAI_API_KEY,
+  };
 }
 
-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 || '';
+function buildSummary(transcriptPath) {
+  let raw;
+  try { raw = readFileSync(transcriptPath, 'utf8'); }
+  catch (e) { log(`read-transcript-failed: ${e.message}`); return null; }
 
-    if (!transcriptPath) {
-      log('No transcript_path in input, skipping');
-      return;
+  const lines = raw.split('\n').filter(Boolean);
+  const messages = [];
+  for (const line of lines) {
+    let msg;
+    try { msg = JSON.parse(line); } catch (_) { continue; }
+    const role = msg?.message?.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const content = msg.message.content;
+    let text = '';
+    if (typeof content === 'string') text = content;
+    else if (Array.isArray(content)) {
+      text = content.filter((c) => c && c.type === 'text').map((c) => c.text).join(' ');
     }
+    if (text) messages.push({ role, content: text.slice(0, 400) });
+  }
 
-    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 (messages.length < 5) {
+    debug(`session-too-short: ${messages.length} messages, skipping`);
+    return null;
+  }
 
-    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 tail = messages.slice(-30);
+  const summary =
+    `Session with ${messages.length} messages.\n\n` +
+    tail.map((m) => `[${m.role}] ${m.content}`).join('\n');
+  // OpenAI text-embedding-3-small accepts up to 8192 tokens (~32K chars).
+  // 7000 chars is a safe headroom that survives multibyte expansion.
+  return summary.slice(0, 7000);
+}
+
+async function embedText(text, openaiKey) {
+  try {
+    const res = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${openaiKey}`,
+      },
+      body: JSON.stringify({ model: 'text-embedding-3-small', input: text }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      log(`openai-embed-failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+      return null;
     }
+    const data = await res.json();
+    return data?.data?.[0]?.embedding || null;
+  } catch (e) {
+    log(`openai-embed-exception: ${e.message}`);
+    return null;
+  }
+}
 
-    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}"`);
+async function postMemoryItem({ supabaseUrl, supabaseKey, content, embedding, project, sessionId }) {
+  try {
+    const res = await fetch(`${supabaseUrl}/rest/v1/memory_items`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'apikey': supabaseKey,
+        'Authorization': `Bearer ${supabaseKey}`,
+        'Prefer': 'return=minimal',
+      },
+      body: JSON.stringify({
+        content,
+        embedding: `[${embedding.join(',')}]`,
+        source_type: 'session_summary',
+        category: 'workflow',
+        project,
+        source_session_id: sessionId || null,
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      log(`supabase-insert-failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+      return false;
+    }
+    return true;
   } catch (e) {
-    log(`Error: ${e.message}`);
+    log(`supabase-insert-exception: ${e.message}`);
+    return false;
+  }
+}
+
+async function processStdinPayload(input) {
+  let data;
+  try { data = JSON.parse(input); }
+  catch (e) { log(`parse-stdin-failed: ${e.message}`); return; }
+
+  const transcriptPath = data.transcript_path;
+  const cwd = data.cwd || '';
+  const sessionId =
+    data.session_id ||
+    (transcriptPath ? transcriptPath.split('/').pop().replace('.jsonl', '') : null);
+
+  if (!transcriptPath) { log('no-transcript-path: skipping'); return; }
+
+  let stat;
+  try { stat = statSync(transcriptPath); }
+  catch (e) { log(`cannot-stat-transcript: ${transcriptPath} — ${e.message}`); return; }
+
+  if (stat.size < MIN_TRANSCRIPT_BYTES) {
+    debug(`small-transcript: ${stat.size} bytes < ${MIN_TRANSCRIPT_BYTES}, skipping`);
+    return;
   }
-});
+
+  const env = readEnv();
+  if (!env) return;
+
+  const project = detectProject(cwd);
+  debug(`project="${project}", session=${sessionId}`);
+
+  const summary = buildSummary(transcriptPath);
+  if (!summary) return;
+
+  const embedding = await embedText(summary, env.openaiKey);
+  if (!embedding) return;
+
+  const ok = await postMemoryItem({
+    supabaseUrl: env.supabaseUrl,
+    supabaseKey: env.supabaseKey,
+    content: summary,
+    embedding,
+    project,
+    sessionId,
+  });
+
+  if (ok) log(`ingested: project="${project}" session=${sessionId} bytes=${summary.length}`);
+}
+
+// Module-export contract for testability. When run as a script (require.main === module),
+// read stdin and process. When require()d (tests), expose helpers.
+if (require.main === module) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    processStdinPayload(input).catch((e) => log(`hook-error: ${e.message}`));
+  });
+} else {
+  module.exports = {
+    PROJECT_MAP,
+    detectProject,
+    readEnv,
+    buildSummary,
+    embedText,
+    postMemoryItem,
+    processStdinPayload,
+    LOG_FILE,
+  };
+}

package/package.json

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