@jhizzard/termdeck 0.3.1 → 0.3.3

package/README.md

@@ -22,6 +22,16 @@ Enabling Flashback takes **one additional 15-minute setup step** — see Tier 2
 
 ---
 
+## Documentation hierarchy
+
+- **This README** — quickstart, pitch, and links
+- **[docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)** — full 4-tier installation guide
+- **[termdeck-docs.vercel.app](https://termdeck-docs.vercel.app)** — reference docs (Astro/Starlight)
+- **docs/launch/** — launch collateral (Show HN, Twitter, etc.)
+- **docs/sprint-N-*/** — historical sprint logs (append-only, not maintained post-sprint)
+
+---
+
 ## How Flashback works
 
 When a panel's status transitions to `errored`, the server's output analyzer fires an event. The mnestra bridge takes the session context (type, project, last command, error tail) and queries your Mnestra memory store for the top similar match. If it finds one above the relevance threshold, the result is pushed to the panel's WebSocket as a `proactive_memory` message. The client renders it as a toast anchored to the panel, showing the match's project tag, source type, similarity score, and content snippet. You click the toast to expand into the Memory tab of that panel's drawer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/client/public/app.js

@@ -2403,29 +2403,43 @@
       document.getElementById('healthBadgeLabel').textContent = 'Health: offline';
     }
 
+    // Tier 2/3 checks only shown when the user has configured those tiers.
+    // Without DATABASE_URL, mnestra/rumen/database checks are irrelevant noise.
+    const TIER1_CHECKS = new Set(['project_paths', 'shell_sanity']);
+    const TIER23_CHECKS = new Set(['mnestra_reachable', 'mnestra_has_memories', 'rumen_recent', 'database_url']);
+
+    function filterChecksByTier(checks) {
+      const hasDb = checks.some(c => c.name === 'database_url' && c.passed);
+      if (hasDb) return checks; // full stack configured — show everything
+      // No DATABASE_URL: only show Tier 1 checks
+      return checks.filter(c => TIER1_CHECKS.has(c.name));
+    }
+
     function renderHealthBadge(data) {
       const badge = document.getElementById('healthBadge');
       if (!badge) return;
       badge.style.display = '';
 
-      const checks = data.checks || [];
+      const allChecks = data.checks || [];
+      const checks = filterChecksByTier(allChecks);
       const total = checks.length;
-      const passed = checks.filter(c => c.ok).length;
+      const passed = checks.filter(c => c.passed).length;
       const allOk = passed === total && total > 0;
+      const tierLabel = total < allChecks.length ? 'Tier 1' : 'Stack';
 
       if (allOk) {
         badge.className = 'health-badge hb-green';
-        document.getElementById('healthBadgeLabel').textContent = 'Stack: OK';
+        document.getElementById('healthBadgeLabel').textContent = `${tierLabel}: OK`;
       } else if (total === 0) {
         badge.className = 'health-badge hb-amber';
         document.getElementById('healthBadgeLabel').textContent = 'Stack: ?';
       } else {
         badge.className = 'health-badge hb-red';
-        document.getElementById('healthBadgeLabel').textContent = `Stack: ${passed}/${total}`;
+        document.getElementById('healthBadgeLabel').textContent = `${tierLabel}: ${passed}/${total}`;
       }
 
-      // Update dropdown content
-      renderHealthDropdown(data);
+      // Update dropdown content — pass filtered checks
+      renderHealthDropdown({ ...data, checks });
     }
 
     function renderHealthDropdown(data) {
@@ -2439,16 +2453,16 @@
 
       let html = '';
       for (const check of checks) {
-        const icon = check.ok ? '✓' : '✗';
-        const cls = check.ok ? 'hd-ok' : 'hd-fail';
+        const icon = check.passed ? '✓' : '✗';
+        const cls = check.passed ? 'hd-ok' : 'hd-fail';
         const name = check.name || 'Unknown';
         const detail = check.detail || '';
-        const remediation = check.ok ? '' : (check.remediation ? `<div class="hd-remediation">${escapeHtml(check.remediation)}</div>` : '');
+        const remediation = check.passed ? '' : (check.remediation ? `<div class="hd-remediation">${escapeHtml(check.remediation)}</div>` : '');
         html += `<div class="hd-check ${cls}">
           <span class="hd-icon">${icon}</span>
           <span class="hd-name">${escapeHtml(name)}</span>
           <span class="hd-dots"></span>
-          <span class="hd-status">${check.ok ? 'OK' : 'FAIL'}</span>
+          <span class="hd-status">${check.passed ? 'OK' : 'FAIL'}</span>
           <span class="hd-detail">${escapeHtml(detail)}</span>
           ${remediation}
         </div>`;

package/packages/client/public/style.css

@@ -39,17 +39,27 @@
       display: flex;
       align-items: center;
       justify-content: space-between;
-      padding: 0 16px;
+      gap: 10px;
+      padding: 0 12px;
       height: 42px;
       background: var(--tg-surface);
       border-bottom: 1px solid var(--tg-border);
       flex-shrink: 0;
+      overflow-x: auto;
+      overflow-y: hidden;
+      min-width: 0;
+      scrollbar-width: thin;
+      flex-wrap: nowrap;
     }
 
+    .topbar::-webkit-scrollbar { height: 4px; }
+    .topbar::-webkit-scrollbar-thumb { background: var(--tg-border); border-radius: 2px; }
+
     .topbar-left {
       display: flex;
       align-items: center;
       gap: 12px;
+      flex-shrink: 0;
     }
 
     .topbar-logo {
@@ -66,7 +76,7 @@
 
     .topbar-stats {
       display: flex;
-      gap: 16px;
+      gap: 10px;
       font-size: 11px;
       color: var(--tg-text-dim);
     }
@@ -84,6 +94,7 @@
       background: var(--tg-bg);
       padding: 3px;
       border-radius: var(--tg-radius-sm);
+      flex-shrink: 0;
     }
 
     .layout-btn {
@@ -104,7 +115,8 @@
     .topbar-right {
       display: flex;
       align-items: center;
-      gap: 8px;
+      gap: 4px;
+      flex-shrink: 0;
     }
 
     .topbar-right button {
@@ -112,7 +124,7 @@
       border: 1px solid var(--tg-border);
       color: var(--tg-text-dim);
       font-size: 11px;
-      padding: 4px 12px;
+      padding: 4px 8px;
       border-radius: var(--tg-radius-sm);
       cursor: pointer;
       font-family: var(--tg-sans);

package/packages/server/src/index.js

@@ -20,9 +20,17 @@ try { pg = require('pg'); } catch { pg = null; }
 // servers without DATABASE_URL never pay the connection cost.
 let _rumenPool = null;
 let _rumenPoolFailed = false;
+let _rumenPoolFailedAt = 0;
+const RUMEN_POOL_RETRY_MS = 30_000;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function getRumenPool() {
-  if (_rumenPool || _rumenPoolFailed) return _rumenPool;
+  if (_rumenPool) return _rumenPool;
+  if (_rumenPoolFailed) {
+    if (Date.now() - _rumenPoolFailedAt < RUMEN_POOL_RETRY_MS) return null;
+    console.warn('[rumen] retrying pool creation after 30s cooldown');
+    _rumenPoolFailed = false;
+    _rumenPoolFailedAt = 0;
+  }
   if (!pg || !process.env.DATABASE_URL) return null;
   try {
     _rumenPool = new pg.Pool({
@@ -38,6 +46,7 @@ function getRumenPool() {
   } catch (err) {
     console.warn('[rumen] failed to create pg pool:', err.message);
     _rumenPoolFailed = true;
+    _rumenPoolFailedAt = Date.now();
     return null;
   }
 }
@@ -484,14 +493,14 @@ function createServer(config) {
   // GET /api/transcripts/search - FTS across all sessions
   // (Must be registered before :sessionId to avoid route collision)
   app.get('/api/transcripts/search', async (req, res) => {
-    if (!transcriptWriter) return res.json([]);
+    if (!transcriptWriter) return res.json({ results: [] });
     const q = req.query.q;
     if (!q) return res.status(400).json({ error: 'Missing q parameter' });
     const since = req.query.since || null;
     const limit = Math.min(Math.max(parseInt(req.query.limit) || 50, 1), 200);
     try {
       const results = await transcriptWriter.search(q, { since, limit });
-      res.json(results);
+      res.json({ results });
     } catch (err) {
       console.error('[transcript] search endpoint error:', err.message);
       res.status(500).json({ error: 'Transcript search failed' });
@@ -499,13 +508,24 @@ function createServer(config) {
   });
 
   // GET /api/transcripts/recent - time-windowed crash recovery
+  // Returns { sessions: [ { session_id, chunks: [...] }, ... ] }
   app.get('/api/transcripts/recent', async (req, res) => {
-    if (!transcriptWriter) return res.json([]);
+    if (!transcriptWriter) return res.json({ sessions: [] });
     const minutes = Math.min(Math.max(parseInt(req.query.minutes) || 60, 1), 1440);
     const limit = Math.min(Math.max(parseInt(req.query.limit) || 500, 1), 2000);
     try {
-      const results = await transcriptWriter.getRecent(minutes, limit);
-      res.json(results);
+      const rows = await transcriptWriter.getRecent(minutes, limit);
+      // Group by session_id for client consumption
+      const grouped = new Map();
+      for (const row of rows) {
+        if (!grouped.has(row.session_id)) grouped.set(row.session_id, []);
+        grouped.get(row.session_id).push(row);
+      }
+      const sessions = [];
+      for (const [session_id, chunks] of grouped) {
+        sessions.push({ session_id, chunks });
+      }
+      res.json({ sessions });
     } catch (err) {
       console.error('[transcript] recent endpoint error:', err.message);
       res.status(500).json({ error: 'Transcript recent query failed' });
@@ -513,13 +533,16 @@ function createServer(config) {
   });
 
   // GET /api/transcripts/:sessionId - ordered chunks for a session
+  // Returns { content: string } (joined transcript text)
   app.get('/api/transcripts/:sessionId', async (req, res) => {
-    if (!transcriptWriter) return res.json([]);
+    if (!transcriptWriter) return res.json({ content: '', lines: [] });
     const limit = req.query.limit ? Math.min(Math.max(parseInt(req.query.limit), 1), 5000) : undefined;
     const since = req.query.since || undefined;
     try {
       const chunks = await transcriptWriter.getSessionTranscript(req.params.sessionId, { limit, since });
-      res.json(chunks);
+      const lines = chunks.map(c => c.content);
+      const content = lines.join('');
+      res.json({ content, lines, chunks });
     } catch (err) {
       console.error('[transcript] session transcript endpoint error:', err.message);
       res.status(500).json({ error: 'Transcript retrieval failed' });

package/packages/server/src/preflight.js

@@ -23,12 +23,12 @@ const CACHE_TTL_MS = 60_000;
 async function checkMnestra(config) {
   const rag = config.rag || {};
   const url = rag.mnestraWebhookUrl
-    ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '/health')
-    : 'http://localhost:37778/health';
+    ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '/healthz')
+    : 'http://localhost:37778/healthz';
 
   const body = await httpGet(url, 3000);
   const data = tryParseJSON(body);
-  const total = data && (data.total || data.memories || data.count);
+  const total = data && (data.store?.rows ?? data.total ?? data.memories ?? data.count ?? null);
   if (total != null) {
     return { name: 'mnestra_reachable', passed: true, detail: `${Number(total).toLocaleString()} memories` };
   }
@@ -45,9 +45,9 @@ async function checkMnestraMemories(config) {
     ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '')
     : 'http://localhost:37778';
 
-  const body = await httpGet(`${baseUrl}/health`, 3000);
+  const body = await httpGet(`${baseUrl}/healthz`, 3000);
   const data = tryParseJSON(body);
-  const total = data && (data.total || data.memories || data.count);
+  const total = data && (data.store?.rows ?? data.total ?? data.memories ?? data.count ?? null);
   if (total != null && Number(total) > 0) {
     return { name: 'mnestra_has_memories', passed: true, detail: `${Number(total).toLocaleString()} memories loaded` };
   }

package/packages/server/src/rag.js

@@ -165,8 +165,8 @@ class RAGIntegration {
       // 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);
+      throw err; // Propagate to caller so sync loop knows this event failed
     }
   }
 

package/packages/server/src/transcripts.js

@@ -28,6 +28,7 @@ class TranscriptWriter {
     this._databaseUrl = databaseUrl;
     this._batchSize = options.batchSize || 50;
     this._flushIntervalMs = options.flushIntervalMs || 2000;
+    this._maxBufferSize = options.maxBufferSize || 10000;
     this._enabled = options.enabled !== false;
 
     // Per-session monotonic chunk counters
@@ -91,6 +92,11 @@ class TranscriptWriter {
     const idx = this._counters.get(sessionId) || 0;
     this._counters.set(sessionId, idx + 1);
 
+    // Cap buffer to prevent unbounded growth during sustained DB failures
+    if (this._buffer.length >= this._maxBufferSize) {
+      this._buffer.splice(0, this._buffer.length - this._maxBufferSize + 1);
+    }
+
     this._buffer.push({
       sessionId,
       content: stripped,