@jhizzard/termdeck 0.4.0 → 0.4.3

package/packages/server/src/index.js

@@ -57,7 +57,7 @@ const { RAGIntegration } = require('./rag');
 const { createBridge } = require('./mnestra-bridge');
 const { writeSessionLog } = require('./session-logger');
 const { TranscriptWriter } = require('./transcripts');
-const { createHealthHandler } = require('./preflight');
+const { createHealthHandler, runPreflight } = require('./preflight');
 const { themes, statusColors } = require('./themes');
 const { loadConfig, addProject } = require('./config');
 const { createAuthMiddleware, verifyWebSocketUpgrade, hasAuth } = require('./auth');
@@ -69,6 +69,11 @@ function createServer(config) {
 
   app.use(express.json());
 
+  // First-run detection (Sprint 19 T3): true when ~/.termdeck/config.yaml
+  // does not exist. Surfaced on /api/config so the client can offer the
+  // setup wizard on first visit. T1's /api/setup endpoint may reuse this.
+  const firstRun = !fs.existsSync(path.join(os.homedir(), '.termdeck', 'config.yaml'));
+
   // Optional token auth (Sprint 9 T3). Zero-op when no token is configured,
   // so local users see no behavior change. Mounted before static + routes so
   // unauthenticated requests never touch app.js / index.html.
@@ -140,6 +145,113 @@ function createServer(config) {
   // or scope the response to a minimal {status, version} payload.
   app.get('/api/health', createHealthHandler(config));
 
+  // GET /api/setup - setup wizard tier status (Sprint 19 T1)
+  // Reuses preflight checks (mnestra_reachable, rumen_recent) and pairs them
+  // with filesystem + config signals to classify which of the 4 TermDeck tiers
+  // the user has reached:
+  //   1. TermDeck running (always active when this handler responds)
+  //   2. Mnestra reachable + DATABASE_URL available (partial if only reachable)
+  //   3. Rumen job seen recently (partial if DATABASE_URL set but no recent job)
+  //   4. At least one project configured in config.yaml
+  // Cached for 60s so the setup UI can poll without re-running shell/PTY probes.
+  const SETUP_CONFIG_DIR = path.join(os.homedir(), '.termdeck');
+  const SETUP_SECRETS_PATH = path.join(SETUP_CONFIG_DIR, 'secrets.env');
+  const SETUP_CACHE_TTL_MS = 60_000;
+  let _setupCache = null;
+  let _setupCachedAt = 0;
+
+  app.get('/api/setup', async (req, res) => {
+    if (_setupCache && (Date.now() - _setupCachedAt) < SETUP_CACHE_TTL_MS) {
+      return res.json(_setupCache);
+    }
+
+    try {
+      const preflight = await runPreflight(config);
+      const byName = {};
+      for (const c of preflight.checks) byName[c.name] = c;
+
+      const hasConfigFile = !firstRun;
+      const hasSecretsFile = fs.existsSync(SETUP_SECRETS_PATH);
+      const hasDatabaseUrl = !!process.env.DATABASE_URL;
+      const hasMnestraRunning = !!(byName.mnestra_reachable && byName.mnestra_reachable.passed);
+      const hasRumenDeployed = !!(byName.rumen_recent && byName.rumen_recent.passed);
+      const projectCount = Object.keys(config.projects || {}).length;
+
+      const tier1 = {
+        status: 'active',
+        detail: `TermDeck running on :${config.port || 3000}`
+      };
+
+      let tier2;
+      if (hasMnestraRunning && hasDatabaseUrl) {
+        tier2 = {
+          status: 'active',
+          detail: byName.mnestra_reachable.detail || 'Mnestra reachable'
+        };
+      } else if (hasMnestraRunning && !hasDatabaseUrl) {
+        tier2 = {
+          status: 'partial',
+          detail: 'Mnestra reachable but DATABASE_URL not set'
+        };
+      } else {
+        tier2 = {
+          status: 'not_configured',
+          detail: (byName.mnestra_reachable && byName.mnestra_reachable.detail) || 'Mnestra not reachable'
+        };
+      }
+
+      let tier3;
+      if (hasRumenDeployed) {
+        tier3 = { status: 'active', detail: byName.rumen_recent.detail };
+      } else if (hasDatabaseUrl && byName.rumen_recent &&
+                 /no completed Rumen jobs|stale/i.test(byName.rumen_recent.detail || '')) {
+        tier3 = { status: 'partial', detail: byName.rumen_recent.detail };
+      } else {
+        tier3 = {
+          status: 'not_configured',
+          detail: (byName.rumen_recent && byName.rumen_recent.detail) || 'Rumen not deployed'
+        };
+      }
+
+      const tier4 = projectCount > 0
+        ? { status: 'active', detail: `${projectCount} project${projectCount === 1 ? '' : 's'} configured` }
+        : { status: 'not_configured', detail: 'No project paths in config.yaml' };
+
+      const tiers = { 1: tier1, 2: tier2, 3: tier3, 4: tier4 };
+
+      // Current tier = highest contiguous tier with status active or partial.
+      let tier = 0;
+      for (let i = 1; i <= 4; i++) {
+        if (tiers[i].status === 'active' || tiers[i].status === 'partial') {
+          tier = i;
+        } else {
+          break;
+        }
+      }
+
+      const payload = {
+        tier,
+        tiers,
+        config: {
+          hasSecretsFile,
+          hasConfigFile,
+          hasDatabaseUrl,
+          hasMnestraRunning,
+          hasRumenDeployed,
+          projectCount
+        },
+        firstRun
+      };
+
+      _setupCache = payload;
+      _setupCachedAt = Date.now();
+      res.json(payload);
+    } catch (err) {
+      console.error('[setup] /api/setup failed:', err.message);
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   // GET /api/sessions - list all active sessions
   app.get('/api/sessions', (req, res) => {
     res.json(sessions.getAll());
@@ -263,6 +375,7 @@ function createServer(config) {
         // configured, regardless of the push-loop flag.
         session.onErrorDetected = (sess, ctx) => {
           const question = `${sess.meta.type} error ${ctx.lastCommand || ''} ${ctx.tail || ''}`.trim();
+          console.log(`[flashback] error detected in session ${sess.id} (type=${sess.meta.type}, project=${sess.meta.project || 'none'}), querying Mnestra via ${mnestraBridge.mode}…`);
           mnestraBridge.queryMnestra({
             question,
             project: sess.meta.project,
@@ -274,16 +387,26 @@ function createServer(config) {
               status: 'errored'
             }
           }).then((result) => {
+            const count = (result.memories || []).length;
+            console.log(`[flashback] query returned ${count} matches for session ${sess.id}`);
             const hit = (result.memories || [])[0];
-            if (!hit) return;
+            if (!hit) {
+              console.log(`[flashback] no matches — skipping proactive_memory send for session ${sess.id}`);
+              return;
+            }
             if (sess.ws && sess.ws.readyState === 1) {
               try {
                 sess.ws.send(JSON.stringify({ type: 'proactive_memory', hit }));
+                console.log(`[flashback] proactive_memory sent to session ${sess.id} (source_type=${hit.source_type}, project=${hit.project})`);
               } catch (err) {
+                console.error('[flashback] proactive_memory send failed:', err);
                 console.error('[ws] proactive_memory send failed:', err);
               }
+            } else {
+              console.log(`[flashback] ws not open for session ${sess.id} (readyState=${sess.ws ? sess.ws.readyState : 'null'}) — dropped hit`);
             }
           }).catch((err) => {
+            console.error(`[flashback] query failed for session ${sess.id}: ${err.message}`);
             console.warn('[mnestra-bridge] proactive query failed:', err.message);
           });
         };
@@ -434,7 +557,8 @@ function createServer(config) {
       defaultTheme: config.defaultTheme,
       ragEnabled: rag.enabled,
       aiQueryAvailable: !!(config.rag?.supabaseUrl && config.rag?.supabaseKey && config.rag?.openaiApiKey),
-      statusColors
+      statusColors,
+      firstRun
     });
   });
 

package/packages/server/src/mnestra-bridge/index.js

@@ -47,6 +47,24 @@ function createBridge(config) {
     const embeddingData = await embeddingRes.json();
     const embedding = embeddingData.data[0].embedding;
 
+    // NOTE: memory_hybrid_search (migrations/004) accepts exactly 8 named params:
+    //   query_text, query_embedding, match_count, full_text_weight,
+    //   semantic_weight, rrf_k, filter_project, filter_source_type.
+    // PostgREST matches RPC functions by the set of JSON keys in the body — any
+    // extra key (e.g. recency_weight, decay_days) makes it fail to resolve the
+    // overload and return 404 "Could not find the function". That was silently
+    // killing every Flashback query for 15 sprints.
+    const rpcBody = {
+      query_text: question,
+      query_embedding: `[${embedding.join(',')}]`,
+      match_count: 10,
+      full_text_weight: 1.0,
+      semantic_weight: 1.0,
+      rrf_k: 60,
+      filter_project: searchAll ? null : (project || null),
+      filter_source_type: null
+    };
+    console.log(`[flashback] direct RPC → memory_hybrid_search project=${rpcBody.filter_project ?? 'ALL'} q="${question.slice(0, 60)}"`);
     const searchRes = await fetch(`${supabaseUrl}/rest/v1/rpc/memory_hybrid_search`, {
       method: 'POST',
       headers: {
@@ -54,31 +72,23 @@ function createBridge(config) {
         'apikey': supabaseKey,
         'Authorization': `Bearer ${supabaseKey}`
       },
-      body: JSON.stringify({
-        query_text: question,
-        query_embedding: `[${embedding.join(',')}]`,
-        match_count: 10,
-        full_text_weight: 1.0,
-        semantic_weight: 1.0,
-        rrf_k: 60,
-        filter_project: searchAll ? null : (project || null),
-        filter_source_type: null,
-        recency_weight: 0.15,
-        decay_days: 30.0
-      })
+      body: JSON.stringify(rpcBody)
     });
     if (!searchRes.ok) {
       const err = await searchRes.text();
+      console.error(`[flashback] direct RPC failed ${searchRes.status}:`, err);
       console.error('[mnestra-bridge:direct] supabase search failed:', err);
-      throw new Error('Memory search failed');
+      throw new Error(`Memory search failed (${searchRes.status})`);
     }
     const rows = await searchRes.json();
+    console.log(`[flashback] direct RPC returned ${rows.length} rows`);
     return {
       memories: rows.map((m) => ({
         content: m.content,
         source_type: m.source_type,
         project: m.project,
-        similarity: m.similarity,
+        // memory_hybrid_search returns `score`, not `similarity`.
+        similarity: m.similarity ?? m.score ?? null,
         created_at: m.created_at
       })),
       total: rows.length

package/packages/server/src/session.js

@@ -322,7 +322,10 @@ class Session {
 
     // Server-side rate limit: at most one error_detected event every 30s per session
     const now = Date.now();
-    if (now - this._lastErrorFireAt < 30000) return;
+    if (now - this._lastErrorFireAt < 30000) {
+      console.log(`[flashback] error detected in session ${this.id} but rate-limited (${Math.round((30000 - (now - this._lastErrorFireAt)) / 1000)}s left)`);
+      return;
+    }
     this._lastErrorFireAt = now;
 
     if (this.onErrorDetected) {
@@ -333,8 +336,11 @@ class Session {
       try {
         this.onErrorDetected(this, { lastCommand, tail });
       } catch (err) {
+        console.error('[flashback] onErrorDetected handler threw:', err);
         console.error('[session] onErrorDetected handler error:', err);
       }
+    } else {
+      console.log(`[flashback] error detected in session ${this.id} but no onErrorDetected handler wired`);
     }
   }
 

package/packages/server/src/skill-installer.js

@@ -0,0 +1,166 @@
+// Skill installer (Sprint 20 / SkillForge foundation).
+// Writes generated skills to ~/.claude/skills/ as markdown files with frontmatter,
+// lists installed skills, and removes them. Used by the `termdeck forge` CLI.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const FRONTMATTER_KEYS = ['name', 'description', 'trigger', 'source', 'generated'];
+
+function getSkillsDir() {
+  const override = process.env.TERMDECK_SKILLS_DIR;
+  if (override && override.trim()) return path.resolve(override);
+  const home = os.homedir();
+  if (!home) {
+    return path.resolve(process.cwd(), '.claude', 'skills');
+  }
+  return path.join(home, '.claude', 'skills');
+}
+
+function ensureSkillsDir() {
+  const dir = getSkillsDir();
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function validateName(name) {
+  if (!name || typeof name !== 'string') {
+    throw new Error('skill name is required');
+  }
+  if (!/^[a-z0-9][a-z0-9_-]*$/i.test(name)) {
+    throw new Error(`invalid skill name: ${name} (use letters, digits, - or _)`);
+  }
+}
+
+function skillPath(name) {
+  validateName(name);
+  return path.join(getSkillsDir(), `${name}.md`);
+}
+
+function escapeFrontmatterValue(value) {
+  const str = String(value ?? '');
+  if (str.includes('\n')) {
+    return JSON.stringify(str);
+  }
+  if (/^[\s"'`]|[:#]\s|[\s"'`]$/.test(str)) {
+    return JSON.stringify(str);
+  }
+  return str;
+}
+
+function buildMarkdown(skill) {
+  const generated = skill.generated || new Date().toISOString();
+  const frontmatter = { ...skill, generated };
+  const lines = ['---'];
+  for (const key of FRONTMATTER_KEYS) {
+    if (frontmatter[key] === undefined || frontmatter[key] === null) continue;
+    lines.push(`${key}: ${escapeFrontmatterValue(frontmatter[key])}`);
+  }
+  lines.push('---');
+  lines.push('');
+  const body = (skill.content || skill.body || '').replace(/\s+$/, '');
+  if (body) {
+    lines.push(body);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function parseFrontmatter(markdown) {
+  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return {};
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (!m) continue;
+    let value = m[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      try { value = JSON.parse(value); } catch (_) { value = value.slice(1, -1); }
+    }
+    meta[m[1]] = value;
+  }
+  return meta;
+}
+
+function installSkill(skill, options = {}) {
+  if (!skill || typeof skill !== 'object') {
+    throw new Error('installSkill: skill object is required');
+  }
+  validateName(skill.name);
+  const dir = ensureSkillsDir();
+  const filepath = path.join(dir, `${skill.name}.md`);
+  const exists = fs.existsSync(filepath);
+  if (exists && !options.overwrite) {
+    const err = new Error(`skill already exists: ${skill.name}`);
+    err.code = 'SKILL_EXISTS';
+    err.path = filepath;
+    throw err;
+  }
+  const markdown = buildMarkdown(skill);
+  fs.writeFileSync(filepath, markdown, 'utf-8');
+  return { path: filepath, overwritten: exists };
+}
+
+function listInstalledSkills() {
+  const dir = getSkillsDir();
+  if (!fs.existsSync(dir)) return [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const filepath = path.join(dir, entry.name);
+    let meta = {};
+    let stat = null;
+    try {
+      const content = fs.readFileSync(filepath, 'utf-8');
+      meta = parseFrontmatter(content);
+      stat = fs.statSync(filepath);
+    } catch (err) {
+      // skip unreadable file, keep going
+      continue;
+    }
+    skills.push({
+      name: meta.name || entry.name.replace(/\.md$/, ''),
+      description: meta.description || '',
+      trigger: meta.trigger || '',
+      source: meta.source || '',
+      generated: meta.generated || (stat ? stat.mtime.toISOString() : ''),
+      path: filepath
+    });
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  return skills;
+}
+
+function skillExists(name) {
+  try {
+    return fs.existsSync(skillPath(name));
+  } catch (_) {
+    return false;
+  }
+}
+
+function removeSkill(name) {
+  const filepath = skillPath(name);
+  if (!fs.existsSync(filepath)) {
+    const err = new Error(`skill not found: ${name}`);
+    err.code = 'SKILL_NOT_FOUND';
+    err.path = filepath;
+    throw err;
+  }
+  fs.unlinkSync(filepath);
+  return { path: filepath };
+}
+
+module.exports = {
+  getSkillsDir,
+  installSkill,
+  listInstalledSkills,
+  removeSkill,
+  skillExists,
+  // exposed for tests
+  _buildMarkdown: buildMarkdown,
+  _parseFrontmatter: parseFrontmatter
+};