@jhizzard/termdeck 0.3.9 → 0.4.2

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.
@@ -133,8 +138,120 @@ function createServer(config) {
   // ==================== REST API ====================
 
   // GET /api/health - preflight health checks (Sprint 6 T1, wired by T3)
+  // SECURITY NOTE: Returns operational detail (memory counts, DB latency, project paths,
+  // RAG breaker state). Intentional for local-first use — TermDeck binds to 127.0.0.1 by
+  // default and the CLI guardrail blocks beyond-localhost binds without explicit opt-in.
+  // For any non-loopback deployment (Sprint 18+ remote story), gate this route behind auth
+  // 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());
@@ -429,7 +546,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/rag.js

@@ -59,8 +59,12 @@ class RAGIntegration {
     };
 
     // 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 }
+    // After 3 consecutive 404s, open the breaker. The breaker auto-transitions
+    // to half-open after 5 minutes, allowing one retry attempt. A successful
+    // retry fully resets the breaker; a failed retry re-opens it for another
+    // 5-minute backoff window.
+    this._circuitBreaker = new Map(); // table -> { count, open, openedAt, halfOpen }
+    this._halfOpenDelayMs = 5 * 60 * 1000;
 
     if (this.enabled) {
       this._startSync();
@@ -142,22 +146,34 @@ class RAGIntegration {
     }, this._projectFor(session));
   }
 
-  // Circuit breaker check — returns true if pushes to this table are disabled
+  // Circuit breaker check — returns true if pushes to this table are disabled.
+  // Has a side effect: when the 5-minute half-open window has elapsed, flips
+  // the breaker to half-open and permits one retry attempt through.
   _isCircuitOpen(table) {
     const state = this._circuitBreaker.get(table);
-    return !!(state && state.open);
+    if (!state || !state.open) return false;
+    if (state.halfOpen) return true; // retry already in flight — block concurrent pushes
+
+    const elapsed = Date.now() - (state.openedAt || 0);
+    if (elapsed >= this._halfOpenDelayMs) {
+      state.halfOpen = true;
+      console.log(`[rag] circuit breaker half-open for ${table}, retrying`);
+      return false; // allow one attempt through
+    }
+    return true;
   }
 
   // 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 };
+      state = { count: 0, open: false, openedAt: null, halfOpen: false };
       this._circuitBreaker.set(table, state);
     }
     state.count += 1;
     if (state.count >= 3 && !state.open) {
       state.open = true;
+      state.openedAt = Date.now();
       console.warn(`[rag] circuit breaker open for ${table} — disabling pushes (table may not exist in Supabase)`);
     }
   }
@@ -208,8 +224,14 @@ class RAGIntegration {
       // Success — reset any accumulated 404 count for this table
       this._resetCircuit(table);
     } catch (err) {
-      // Log at warn (not error) to reduce noise — the circuit breaker handles persistence
-      if (!this._isCircuitOpen(table)) {
+      const state = this._circuitBreaker.get(table);
+      if (state && state.halfOpen) {
+        // Half-open retry failed — re-open for another 5-minute backoff window
+        state.halfOpen = false;
+        state.openedAt = Date.now();
+        console.warn(`[rag] circuit breaker re-opened for ${table} after half-open retry failed`);
+      } else if (!state || !state.open) {
+        // Log at warn (not error) to reduce noise — the circuit breaker handles persistence
         console.warn('[rag] push to', table, 'failed:', err.message);
       }
       throw err; // Propagate to caller so sync loop knows this event failed

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
+};

package/packages/server/src/transcripts.js

@@ -46,6 +46,8 @@ class TranscriptWriter {
     // Lazy pool
     this._pool = null;
     this._poolFailed = false;
+    this._poolFailedAt = 0;
+    this._poolRetryMs = 30_000;
 
     // Start flush timer
     this._timer = null;
@@ -56,7 +58,13 @@ class TranscriptWriter {
 
   // Lazy-init pg.Pool (same pattern as getRumenPool in index.js)
   _getPool() {
-    if (this._pool || this._poolFailed) return this._pool;
+    if (this._pool) return this._pool;
+    if (this._poolFailed) {
+      if (Date.now() - this._poolFailedAt < this._poolRetryMs) return null;
+      console.warn('[transcript] retrying pool creation after 30s cooldown');
+      this._poolFailed = false;
+      this._poolFailedAt = 0;
+    }
     if (!pg || !this._databaseUrl) return null;
     try {
       this._pool = new pg.Pool({
@@ -72,6 +80,7 @@ class TranscriptWriter {
     } catch (err) {
       console.error('[transcript] pool creation failed:', err.message);
       this._poolFailed = true;
+      this._poolFailedAt = Date.now();
       return null;
     }
   }