@jhizzard/termdeck 0.2.5 → 0.3.1

package/packages/server/src/preflight.js

@@ -0,0 +1,373 @@
+// TermDeck Preflight Health Check
+// Runs at startup to verify the entire memory stack is operational.
+// Each check is independent — one failure does not block others.
+//
+// Exports:
+//   runPreflight(config)       — run all checks, return result object
+//   createHealthHandler(config) — Express route handler for GET /api/health
+
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Cache preflight results for 60s
+let _cachedResult = null;
+let _cachedAt = 0;
+const CACHE_TTL_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// Individual checks
+// ---------------------------------------------------------------------------
+
+async function checkMnestra(config) {
+  const rag = config.rag || {};
+  const url = rag.mnestraWebhookUrl
+    ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '/health')
+    : 'http://localhost:37778/health';
+
+  const body = await httpGet(url, 3000);
+  const data = tryParseJSON(body);
+  const total = data && (data.total || data.memories || data.count);
+  if (total != null) {
+    return { name: 'mnestra_reachable', passed: true, detail: `${Number(total).toLocaleString()} memories` };
+  }
+  // Got 200 but no count — still reachable
+  return { name: 'mnestra_reachable', passed: true, detail: 'reachable (no memory count)' };
+}
+
+async function checkMnestraMemories(config) {
+  // If Mnestra responded with a count in the reachable check we can skip
+  // a second request — but since checks run independently we check the
+  // memory_status endpoint separately.
+  const rag = config.rag || {};
+  const baseUrl = rag.mnestraWebhookUrl
+    ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '')
+    : 'http://localhost:37778';
+
+  const body = await httpGet(`${baseUrl}/health`, 3000);
+  const data = tryParseJSON(body);
+  const total = data && (data.total || data.memories || data.count);
+  if (total != null && Number(total) > 0) {
+    return { name: 'mnestra_has_memories', passed: true, detail: `${Number(total).toLocaleString()} memories loaded` };
+  }
+  if (total != null && Number(total) === 0) {
+    return { name: 'mnestra_has_memories', passed: false, detail: 'Mnestra running but 0 memories — run `mnestra ingest`' };
+  }
+  return { name: 'mnestra_has_memories', passed: false, detail: 'could not determine memory count' };
+}
+
+async function checkRumen(config) {
+  // Try to query rumen_jobs table via DATABASE_URL for last successful job
+  const dbUrl = process.env.DATABASE_URL;
+  if (!dbUrl) {
+    return { name: 'rumen_recent', passed: false, detail: 'DATABASE_URL not set — cannot check Rumen jobs' };
+  }
+
+  let pg;
+  try { pg = require('pg'); } catch (err) { pg = null; }
+  if (!pg) {
+    return { name: 'rumen_recent', passed: false, detail: 'pg module not installed' };
+  }
+
+  const pool = new pg.Pool({
+    connectionString: dbUrl,
+    max: 1,
+    connectionTimeoutMillis: 5000,
+  });
+
+  try {
+    const res = await pool.query(
+      `SELECT status, completed_at, insights_generated
+       FROM rumen_jobs
+       WHERE status = 'done'
+       ORDER BY completed_at DESC
+       LIMIT 1`
+    );
+    if (res.rows.length === 0) {
+      return { name: 'rumen_recent', passed: false, detail: 'no completed Rumen jobs found' };
+    }
+    const row = res.rows[0];
+    const completedAt = new Date(row.completed_at);
+    const agoMs = Date.now() - completedAt.getTime();
+    const agoMin = Math.round(agoMs / 60_000);
+    const insights = row.insights_generated || 0;
+    const recent = agoMs < 30 * 60_000; // within 30 minutes
+    return {
+      name: 'rumen_recent',
+      passed: recent,
+      detail: recent
+        ? `last job ${agoMin}m ago, ${insights} insights`
+        : `last job ${agoMin}m ago (stale — expected within 30m), ${insights} insights`,
+    };
+  } finally {
+    await pool.end().catch(() => {});
+  }
+}
+
+async function checkDatabase() {
+  const dbUrl = process.env.DATABASE_URL;
+  if (!dbUrl) {
+    return { name: 'database_url', passed: false, detail: 'DATABASE_URL not set' };
+  }
+
+  let pg;
+  try { pg = require('pg'); } catch (err) { pg = null; }
+  if (!pg) {
+    return { name: 'database_url', passed: false, detail: 'pg module not installed' };
+  }
+
+  const pool = new pg.Pool({
+    connectionString: dbUrl,
+    max: 1,
+    connectionTimeoutMillis: 5000,
+  });
+
+  const t0 = Date.now();
+  try {
+    const res = await pool.query('SELECT 1 AS ok');
+    const ms = Date.now() - t0;
+    if (res.rows[0] && res.rows[0].ok === 1) {
+      return { name: 'database_url', passed: true, detail: `connected in ${ms}ms` };
+    }
+    return { name: 'database_url', passed: false, detail: 'SELECT 1 returned unexpected result' };
+  } finally {
+    await pool.end().catch(() => {});
+  }
+}
+
+async function checkProjectPaths(config) {
+  const projects = config.projects || {};
+  const names = Object.keys(projects);
+  if (names.length === 0) {
+    return { name: 'project_paths', passed: true, detail: 'no projects configured' };
+  }
+
+  let ok = 0;
+  const missing = [];
+  for (const name of names) {
+    const p = projects[name];
+    const resolved = (p.path || '').replace(/^~/, os.homedir());
+    if (fs.existsSync(resolved)) {
+      ok++;
+    } else {
+      missing.push(name);
+    }
+  }
+
+  const total = names.length;
+  if (missing.length === 0) {
+    return { name: 'project_paths', passed: true, detail: `${ok}/${total} paths exist` };
+  }
+  return {
+    name: 'project_paths',
+    passed: false,
+    detail: `${ok}/${total} paths exist — missing: ${missing.join(', ')}`,
+  };
+}
+
+async function checkShellSanity() {
+  const shell = process.env.SHELL || '/bin/bash';
+  const shellName = path.basename(shell);
+
+  return new Promise((resolve) => {
+    let ptyMod;
+    try { ptyMod = require('@homebridge/node-pty-prebuilt-multiarch'); } catch (err) { ptyMod = null; }
+    if (!ptyMod) {
+      try { ptyMod = require('node-pty'); } catch (err) { ptyMod = null; }
+    }
+    if (!ptyMod) {
+      resolve({ name: 'shell_sanity', passed: false, detail: 'node-pty not available' });
+      return;
+    }
+
+    const t0 = Date.now();
+    let output = '';
+    let resolved = false;
+
+    const proc = ptyMod.spawn(shell, ['-l', '-c', 'echo TERMDECK_OK'], {
+      name: 'xterm-256color',
+      cols: 80,
+      rows: 24,
+      cwd: os.homedir(),
+      env: process.env,
+    });
+
+    proc.onData((data) => {
+      output += data;
+      if (output.includes('TERMDECK_OK') && !resolved) {
+        resolved = true;
+        const ms = ((Date.now() - t0) / 1000).toFixed(1);
+        proc.kill();
+        resolve({ name: 'shell_sanity', passed: true, detail: `${shellName} OK in ${ms}s` });
+      }
+    });
+
+    proc.onExit(({ exitCode }) => {
+      if (!resolved) {
+        resolved = true;
+        const ms = ((Date.now() - t0) / 1000).toFixed(1);
+        resolve({
+          name: 'shell_sanity',
+          passed: false,
+          detail: `${shellName} exited ${exitCode} after ${ms}s without OK`,
+        });
+      }
+    });
+
+    // 3s timeout
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        try { proc.kill(); } catch (err) { /* cleanup — process may already be dead */ }
+        resolve({ name: 'shell_sanity', passed: false, detail: `${shellName} timed out after 3s` });
+      }
+    }, 3000);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helper (no external dependencies — uses built-in http)
+// ---------------------------------------------------------------------------
+
+function httpGet(url, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, { timeout: timeoutMs }, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}`));
+        res.resume();
+        return;
+      }
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve(body));
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+  });
+}
+
+function tryParseJSON(str) {
+  try { return JSON.parse(str); } catch (err) { return null; }
+}
+
+// ---------------------------------------------------------------------------
+// Main preflight runner
+// ---------------------------------------------------------------------------
+
+async function runPreflight(config) {
+  const checks = await Promise.all([
+    checkMnestra(config).catch((err) => ({
+      name: 'mnestra_reachable', passed: false,
+      detail: `unreachable — ${err.message}. Start with \`mnestra serve\``,
+    })),
+    checkMnestraMemories(config).catch((err) => ({
+      name: 'mnestra_has_memories', passed: false,
+      detail: `check failed — ${err.message}`,
+    })),
+    checkRumen(config).catch((err) => ({
+      name: 'rumen_recent', passed: false,
+      detail: `check failed — ${err.message}`,
+    })),
+    checkDatabase().catch((err) => ({
+      name: 'database_url', passed: false,
+      detail: `connection failed — ${err.message}`,
+    })),
+    checkProjectPaths(config).catch((err) => ({
+      name: 'project_paths', passed: false,
+      detail: `check failed — ${err.message}`,
+    })),
+    checkShellSanity().catch((err) => ({
+      name: 'shell_sanity', passed: false,
+      detail: `check failed — ${err.message}`,
+    })),
+  ]);
+
+  const result = {
+    passed: checks.every((c) => c.passed),
+    checks,
+    timestamp: new Date().toISOString(),
+  };
+
+  _cachedResult = result;
+  _cachedAt = Date.now();
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Express route handler factory (GET /api/health)
+//
+// T3 or index.js wires this into the app:
+//   const { createHealthHandler } = require('./preflight');
+//   app.get('/api/health', createHealthHandler(config));
+// ---------------------------------------------------------------------------
+
+function createHealthHandler(config) {
+  return async (_req, res) => {
+    // Return cached result if fresh
+    if (_cachedResult && (Date.now() - _cachedAt) < CACHE_TTL_MS) {
+      return res.json(_cachedResult);
+    }
+    try {
+      const result = await runPreflight(config);
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI banner printer
+// ---------------------------------------------------------------------------
+
+const REMEDIATION = {
+  mnestra_reachable: 'Start Mnestra with `mnestra serve`',
+  mnestra_has_memories: 'Run `mnestra ingest` to populate the memory store',
+  rumen_recent: 'Check Rumen Edge Function deployment or run `termdeck init --rumen`',
+  database_url: 'Set DATABASE_URL in ~/.termdeck/secrets.env',
+  project_paths: 'Fix paths in ~/.termdeck/config.yaml → projects',
+  shell_sanity: 'Check $SHELL and your login profile (~/.zshrc or ~/.bashrc)',
+};
+
+const CHECK_LABELS = {
+  mnestra_reachable: 'Mnestra',
+  mnestra_has_memories: 'Mnestra data',
+  rumen_recent: 'Rumen',
+  database_url: 'Database',
+  project_paths: 'Project paths',
+  shell_sanity: 'Shell',
+};
+
+function printHealthBanner(result) {
+  const green = '\x1b[32m';
+  const red = '\x1b[31m';
+  const dim = '\x1b[2m';
+  const reset = '\x1b[0m';
+  const bold = '\x1b[1m';
+
+  for (const check of result.checks) {
+    const label = (CHECK_LABELS[check.name] || check.name).padEnd(18, ' ');
+    const dots = '.'.repeat(Math.max(1, 20 - label.length));
+    if (check.passed) {
+      console.log(`  ${green}✓${reset} ${dim}[health]${reset} ${label}${dim}${dots}${reset} ${green}OK${reset} ${dim}(${check.detail})${reset}`);
+    } else {
+      console.log(`  ${red}✗${reset} ${dim}[health]${reset} ${label}${dim}${dots}${reset} ${red}FAIL${reset} ${dim}(${check.detail})${reset}`);
+      const hint = REMEDIATION[check.name];
+      if (hint) {
+        console.log(`           ${dim}→ ${hint}${reset}`);
+      }
+    }
+  }
+
+  const failCount = result.checks.filter((c) => !c.passed).length;
+  if (failCount === 0) {
+    console.log(`\n  ${green}${bold}All ${result.checks.length} health checks passed.${reset}\n`);
+  } else {
+    console.log(`\n  ${red}${bold}${failCount}/${result.checks.length} health checks failed.${reset} TermDeck will still run, but memory features may be degraded.\n`);
+  }
+}
+
+module.exports = { runPreflight, createHealthHandler, printHealthBanner };

package/packages/server/src/rag.js

@@ -22,6 +22,10 @@ class RAGIntegration {
       commandLog: config.rag?.tables?.commands || 'mnestra_commands'
     };
 
+    // Circuit breaker: track consecutive 404s per table name.
+    // After 3 consecutive 404s, disable pushes to that table until restart.
+    this._circuitBreaker = new Map(); // table -> { count: number, open: boolean }
+
     if (this.enabled) {
       this._startSync();
     }
@@ -95,6 +99,33 @@ class RAGIntegration {
     }, session.meta.project);
   }
 
+  // Circuit breaker check — returns true if pushes to this table are disabled
+  _isCircuitOpen(table) {
+    const state = this._circuitBreaker.get(table);
+    return !!(state && state.open);
+  }
+
+  // Record a 404 for a table; opens the breaker after 3 consecutive hits
+  _record404(table) {
+    let state = this._circuitBreaker.get(table);
+    if (!state) {
+      state = { count: 0, open: false };
+      this._circuitBreaker.set(table, state);
+    }
+    state.count += 1;
+    if (state.count >= 3 && !state.open) {
+      state.open = true;
+      console.error(`[rag] circuit breaker open for ${table} — 3 consecutive 404s, disabling pushes until server restart`);
+    }
+  }
+
+  // Reset the breaker for a table on successful push
+  _resetCircuit(table) {
+    if (this._circuitBreaker.has(table)) {
+      this._circuitBreaker.delete(table);
+    }
+  }
+
   // Push a single event to Supabase
   async _pushEvent(event) {
     if (!this.enabled) return;
@@ -102,6 +133,9 @@ class RAGIntegration {
     const layer = this._determineLayer(event);
     const table = this.tables[layer];
 
+    // Skip if circuit breaker is open for this table
+    if (this._isCircuitOpen(table)) return;
+
     try {
       const response = await fetch(`${this.supabaseUrl}/rest/v1/${table}`, {
         method: 'POST',
@@ -122,8 +156,14 @@ class RAGIntegration {
       });
 
       if (!response.ok) {
+        if (response.status === 404) {
+          this._record404(table);
+        }
         throw new Error(`Supabase responded ${response.status}`);
       }
+
+      // Success — reset any accumulated 404 count for this table
+      this._resetCircuit(table);
     } catch (err) {
       // Will be retried by sync loop
       console.error('[mnestra] Push failed:', err.message);

package/packages/server/src/session.js

@@ -51,7 +51,11 @@ const PATTERNS = {
     command: /^[\$#%❯>]\s+(.+)$/m
   },
   // Broad error markers across shells, compilers, scripts, and HTTP servers.
-  error: /\b(error|Error|ERROR|exception|Exception|Traceback|fatal|FATAL|segmentation fault|panic|EACCES|ECONNREFUSED|ENOENT|command not found|undefined reference|cannot find module|failed with exit code|\b5\d\d\b)\b/
+  // Includes the literal "No such file or directory" phrase because many Unix
+  // tools (cat, ls, cd, rm, etc.) report filesystem misses in plain English
+  // without ever emitting the ENOENT errno code. Flagged as a gap by Rumen's
+  // first production kickstart insight on 2026-04-15.
+  error: /\b(error|Error|ERROR|exception|Exception|Traceback|fatal|FATAL|segmentation fault|panic|EACCES|ECONNREFUSED|ENOENT|command not found|undefined reference|cannot find module|failed with exit code|No such file or directory|Permission denied|\b5\d\d\b)\b/
 };
 
 class Session {
@@ -89,6 +93,9 @@ class Session {
       ragEvents: []                          // buffer before flush
     };
 
+    // Transcript chunk counter — monotonic per session for deterministic replay
+    this.transcriptChunkIndex = 0;
+
     // Output analysis state
     this._outputBuffer = '';
     this._outputFlushTimer = null;
@@ -279,6 +286,10 @@ class Session {
     }
   }
 
+  getNextChunkIndex() {
+    return this.transcriptChunkIndex++;
+  }
+
   _detectErrors(clean) {
     if (!PATTERNS.error.test(clean)) return;
 
@@ -289,7 +300,7 @@ class Session {
     // Mirror status-change callback so T1 sees 'errored' in status_broadcast without
     // waiting for the 3s debounce.
     if (oldStatus !== 'errored' && this.onStatusChange) {
-      try { this.onStatusChange(this, oldStatus, 'errored'); } catch {}
+      try { this.onStatusChange(this, oldStatus, 'errored'); } catch (err) { console.error('[pty] onStatusChange error:', err.message); }
     }
 
     // Server-side rate limit: at most one error_detected event every 30s per session

package/packages/server/src/setup/rumen/functions/rumen-tick/index.ts

@@ -20,7 +20,12 @@
 // @ts-ignore  Deno std import resolved at runtime.
 import { serve } from 'https://deno.land/std@0.224.0/http/server.ts';
 // @ts-ignore  npm specifier resolved at runtime.
-import { runRumenJob, createPoolFromUrl } from 'npm:@jhizzard/rumen@0.1.0';
+// NOTE: `__RUMEN_VERSION__` is a placeholder. `termdeck init --rumen` reads the
+// current published version from the npm registry at deploy time and rewrites
+// this line in a staged copy of the file before running `supabase functions
+// deploy`. This source file on disk MUST keep the placeholder — do not commit
+// a real version number here. See packages/cli/src/init-rumen.js.
+import { runRumenJob, createPoolFromUrl } from 'npm:@jhizzard/rumen@__RUMEN_VERSION__';
 
 // @ts-ignore  Deno global available at runtime.
 declare const Deno: { env: { get: (k: string) => string | undefined } };

package/packages/server/src/setup/rumen/migrations/001_rumen_tables.sql

@@ -1,9 +1,11 @@
--- Rumen v0.1 schema
--- Non-destructive: creates three new tables under the rumen_ namespace.
+-- Rumen schema — self-healing migration.
+-- Non-destructive: creates three new tables under the rumen_ namespace and
+-- brings any pre-existing tables (from partial prior installs) up to the
+-- current shape via ALTER TABLE ADD COLUMN IF NOT EXISTS.
 -- Does NOT modify or reference Mnestra's existing memory_items / memory_sessions tables.
 --
 -- Apply with:
---   psql "$DIRECT_URL" -f migrations/001_rumen_tables.sql
+--   psql "$DATABASE_URL" -f migrations/001_rumen_tables.sql
 
 BEGIN;
 
@@ -23,6 +25,21 @@ CREATE TABLE IF NOT EXISTS rumen_jobs (
   completed_at          TIMESTAMPTZ
 );
 
+-- Backfill columns for schema drift from earlier install attempts.
+-- CREATE TABLE IF NOT EXISTS is a no-op on existing tables, so without this
+-- block the subsequent CREATE INDEX statements would fail on columns that
+-- never got added.
+ALTER TABLE rumen_jobs
+  ADD COLUMN IF NOT EXISTS triggered_by         TEXT,
+  ADD COLUMN IF NOT EXISTS status               TEXT,
+  ADD COLUMN IF NOT EXISTS sessions_processed   INTEGER NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS insights_generated   INTEGER NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS questions_generated  INTEGER NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS error_message        TEXT,
+  ADD COLUMN IF NOT EXISTS source_session_ids   UUID[] NOT NULL DEFAULT '{}',
+  ADD COLUMN IF NOT EXISTS started_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  ADD COLUMN IF NOT EXISTS completed_at         TIMESTAMPTZ;
+
 CREATE INDEX IF NOT EXISTS idx_rumen_jobs_status
   ON rumen_jobs (status);
 
@@ -49,6 +66,15 @@ CREATE TABLE IF NOT EXISTS rumen_insights (
   created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
+ALTER TABLE rumen_insights
+  ADD COLUMN IF NOT EXISTS job_id               UUID,
+  ADD COLUMN IF NOT EXISTS source_memory_ids    UUID[] NOT NULL DEFAULT '{}',
+  ADD COLUMN IF NOT EXISTS projects             TEXT[] NOT NULL DEFAULT '{}',
+  ADD COLUMN IF NOT EXISTS insight_text         TEXT,
+  ADD COLUMN IF NOT EXISTS confidence           NUMERIC(4, 3) NOT NULL DEFAULT 0.000,
+  ADD COLUMN IF NOT EXISTS acted_upon           BOOLEAN NOT NULL DEFAULT FALSE,
+  ADD COLUMN IF NOT EXISTS created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW();
+
 CREATE INDEX IF NOT EXISTS idx_rumen_insights_job_id
   ON rumen_insights (job_id);
 
@@ -78,6 +104,16 @@ CREATE TABLE IF NOT EXISTS rumen_questions (
   created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
+ALTER TABLE rumen_questions
+  ADD COLUMN IF NOT EXISTS job_id               UUID,
+  ADD COLUMN IF NOT EXISTS session_id           UUID,
+  ADD COLUMN IF NOT EXISTS question             TEXT,
+  ADD COLUMN IF NOT EXISTS context              TEXT,
+  ADD COLUMN IF NOT EXISTS asked_at             TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS answered_at          TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS answer               TEXT,
+  ADD COLUMN IF NOT EXISTS created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW();
+
 CREATE INDEX IF NOT EXISTS idx_rumen_questions_job_id
   ON rumen_questions (job_id);