@jhizzard/termdeck 0.8.0 → 0.10.0

package/packages/server/src/index.js

@@ -63,6 +63,54 @@ const { getFullHealth } = require('./health');
 const { themes, statusColors } = require('./themes');
 const { loadConfig, addProject, updateConfig } = require('./config');
 const { createAuthMiddleware, verifyWebSocketUpgrade, hasAuth } = require('./auth');
+const { createSprintRoutes } = require('./sprint-routes');
+const { createGraphRoutes } = require('./graph-routes');
+const orchestrationPreview = require('./orchestration-preview');
+
+// Sprint 37 T3 — lazy resolution of T2's CLI modules. The orchestration-preview
+// helper is decoupled from T2's templates.js / init-project.js; we resolve
+// them here and pass them into the helper. If a module is missing (e.g.
+// install hasn't been completed yet), the route surfaces a 503 with a clear
+// error rather than crashing the server.
+let _t2Templates = null;
+let _t2TemplatesResolved = false;
+function _getT2Templates() {
+  if (_t2TemplatesResolved) return _t2Templates;
+  _t2TemplatesResolved = true;
+  try { _t2Templates = require('../../cli/src/templates'); }
+  catch (_e) { _t2Templates = null; }
+  return _t2Templates;
+}
+
+let _t2InitProject = null;
+let _t2InitProjectResolved = false;
+function _getT2InitProject() {
+  if (_t2InitProjectResolved) return _t2InitProject;
+  _t2InitProjectResolved = true;
+  try {
+    const mod = require('../../cli/src/init-project');
+    _t2InitProject = (mod && typeof mod.initProject === 'function')
+      ? mod.initProject
+      : (typeof mod === 'function' ? mod : null);
+  } catch (_e) {
+    _t2InitProject = null;
+  }
+  return _t2InitProject;
+}
+
+function _getT2DestFor() {
+  try {
+    const mod = require('../../cli/src/init-project');
+    return (mod && typeof mod._destFor === 'function') ? mod._destFor : undefined;
+  } catch (_e) {
+    return undefined;
+  }
+}
+
+function _termdeckVersion() {
+  try { return require('../../../package.json').version; }
+  catch { return '0.0.0'; }
+}
 
 function createServer(config) {
   const app = express();
@@ -89,6 +137,14 @@ function createServer(config) {
   const clientDir = path.join(__dirname, '..', '..', 'client', 'public');
   app.use(express.static(clientDir));
 
+  // Serve repo-rooted /docs as static markdown so the dashboard right-rail Guide
+  // panel can fetch docs/orchestrator-guide.md and render it client-side.
+  // Sprint 37 T1.
+  const docsDir = path.join(__dirname, '..', '..', '..', 'docs');
+  if (fs.existsSync(docsDir)) {
+    app.use('/docs', express.static(docsDir));
+  }
+
   // Initialize database
   let db = null;
   if (Database) {
@@ -115,6 +171,17 @@ function createServer(config) {
   const mnestraBridge = createBridge(config);
   console.log(`[mnestra-bridge] mode=${mnestraBridge.mode}`);
 
+  // Sprint 38 / T3 — let RAGIntegration delegate vector recall to the
+  // bridge so we don't duplicate the embed pipeline. Graph recall stays
+  // in rag.js because it's a different RPC and doesn't share the
+  // direct/webhook/mcp mode shape.
+  rag.setBridge(mnestraBridge);
+  if (rag.graphRecall) {
+    console.log(
+      `[rag] graph-aware recall ENABLED (depth=${rag.graphRecallDepth}, k=${rag.graphRecallK}, half-life=${rag.graphRecallRecencyHalflifeDays}d)`
+    );
+  }
+
   // Initialize transcript writer (Session Transcripts — Sprint 6)
   const transcriptConfig = config.transcripts || {};
   const transcriptEnabled = transcriptConfig.enabled !== undefined
@@ -662,10 +729,12 @@ function createServer(config) {
     res.json(sessions.getAll());
   });
 
-  // POST /api/sessions - create a new terminal session
-  app.post('/api/sessions', (req, res) => {
-    const { command, cwd, project, label, type, theme, reason } = req.body;
-
+  // Reusable PTY spawn + wire helper. Used by POST /api/sessions and the
+  // in-dashboard 4+1 sprint runner (Sprint 37 T4) so multi-panel spawns reuse
+  // the same wiring (transcripts, RAG, Mnestra flashback) without copy-paste.
+  // Returns the Session object regardless of PTY success — status will be
+  // 'errored' if pty.spawn threw.
+  function spawnTerminalSession({ command, cwd, project, label, type, theme, reason }) {
     const rawCwd = cwd || config.projects?.[project]?.path || os.homedir();
     const resolvedCwd = path.resolve(rawCwd.replace(/^~/, os.homedir()));
 
@@ -679,7 +748,6 @@ function createServer(config) {
       reason: reason || 'launched via API'
     });
 
-    // Spawn PTY
     if (pty) {
       // Three launch shapes:
       //   (1) no command            → spawn the default shell interactively
@@ -827,9 +895,34 @@ function createServer(config) {
       session.meta.statusDetail = 'node-pty not available';
     }
 
+    return session;
+  }
+
+  // POST /api/sessions - create a new terminal session
+  app.post('/api/sessions', (req, res) => {
+    const { command, cwd, project, label, type, theme, reason } = req.body || {};
+    const session = spawnTerminalSession({ command, cwd, project, label, type, theme, reason });
     res.status(201).json(session.toJSON());
   });
 
+  // Sprint runner endpoints (Sprint 37 T4) — in-dashboard 4+1 sprint runner.
+  // Wraps spawnTerminalSession with two-stage submit + verify-and-poke.
+  createSprintRoutes({
+    app,
+    config,
+    spawnTerminalSession,
+    getSession: (id) => sessions.get(id),
+  });
+
+  // Graph endpoints (Sprint 38 T4) — knowledge-graph view backing graph.html.
+  // Reuses the petvetbid pg pool (same DATABASE_URL serves memory_items +
+  // memory_relationships alongside rumen_*). Graceful-degrades when the pool
+  // is absent.
+  createGraphRoutes({
+    app,
+    getPool: getRumenPool,
+  });
+
   // GET /api/sessions/:id - get session details
   app.get('/api/sessions/:id', (req, res) => {
     const session = sessions.get(req.params.id);
@@ -1145,6 +1238,66 @@ function createServer(config) {
     }
   });
 
+  // GET /api/projects/:name/orchestration-preview — Sprint 37 T3.
+  // Renders T2's scaffolding templates without writing to disk so the
+  // dashboard can show "if you ran `termdeck init --project <name>`, this
+  // is what would be created." Read-only.
+  app.get('/api/projects/:name/orchestration-preview', (req, res) => {
+    const templates = _getT2Templates();
+    if (!templates) {
+      return res.status(503).json({
+        error: 'Orchestration scaffolding unavailable: packages/cli/src/templates.js not loaded'
+      });
+    }
+    try {
+      const preview = orchestrationPreview.buildPreview({
+        name: req.params.name,
+        projects: config.projects || {},
+        cwd: process.cwd(),
+        templates,
+        destFor: _getT2DestFor(),
+        version: _termdeckVersion()
+      });
+      res.json(preview);
+    } catch (err) {
+      const status = err.statusCode || 500;
+      if (status >= 500) console.error('[orchestration-preview] GET failed:', err.message);
+      res.status(status).json({ error: err.message });
+    }
+  });
+
+  // POST /api/projects/:name/orchestration-preview/generate — Sprint 37 T3.
+  // Calls T2's initProject() to actually write the scaffolding. Body:
+  // { force?: boolean }. Returns the same envelope as the GET preview but
+  // with `created` instead of `wouldCreate`.
+  app.post('/api/projects/:name/orchestration-preview/generate', async (req, res) => {
+    const templates = _getT2Templates();
+    const initProject = _getT2InitProject();
+    if (!templates || !initProject) {
+      return res.status(503).json({
+        error: 'Orchestration scaffolding unavailable: T2 CLI modules not loaded'
+      });
+    }
+    const force = !!(req.body && req.body.force);
+    try {
+      const result = await orchestrationPreview.generateScaffolding({
+        name: req.params.name,
+        projects: config.projects || {},
+        cwd: process.cwd(),
+        force,
+        initProject,
+        templates,
+        destFor: _getT2DestFor(),
+        version: _termdeckVersion()
+      });
+      res.json(result);
+    } catch (err) {
+      const status = err.statusCode || 500;
+      if (status >= 500) console.error('[orchestration-preview] generate failed:', err.message);
+      res.status(status).json({ error: err.message });
+    }
+  });
+
   // GET /api/status - global status (control room data)
   app.get('/api/status', (req, res) => {
     const allSessions = sessions.getAll();

package/packages/server/src/orchestration-preview.js

@@ -0,0 +1,256 @@
+// Sprint 37 T3 — Orchestration preview helper.
+//
+// Renders the per-project scaffolding (CLAUDE.md, CONTRADICTIONS.md, etc.)
+// without writing to disk so the dashboard can show "if you ran
+// `termdeck init --project <name>` here, this is what would be created."
+//
+// All filesystem writes go through T2's initProject(); this file only
+// renders previews. Templates and the writer are injected by the caller so
+// the helper is unit-testable without depending on T2's CLI modules
+// directly — server route wires the production deps; tests pass stubs.
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Same constraint T2's CLI validator should enforce. Keep these in sync if
+// T2's regex differs at sprint close.
+const NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const PREVIEW_LINES = 30;
+
+function validateName(name) {
+  if (typeof name !== 'string' || !NAME_RE.test(name) || name.includes('..')) {
+    const err = new Error(
+      'Invalid project name: must be lowercase, start with a letter or digit, ' +
+      'and contain only letters, digits, dots, underscores, or hyphens.'
+    );
+    err.statusCode = 400;
+    throw err;
+  }
+}
+
+function expandHome(p) {
+  if (typeof p !== 'string') return p;
+  if (p === '~' || p.startsWith('~/')) return path.join(os.homedir(), p.slice(1));
+  return p;
+}
+
+// Decide where the scaffolding would land for a given project name:
+//   1. If `projects[name]` exists in config, use its `.path` (tilde-expanded,
+//      resolved). Preview shows what would be added/skipped against that dir.
+//   2. Otherwise, target = path.resolve(cwd, name). Preview shows a fresh
+//      project being created from scratch.
+function resolveTargetPath({ name, projects, cwd }) {
+  if (projects && Object.prototype.hasOwnProperty.call(projects, name)) {
+    const proj = projects[name];
+    if (proj && typeof proj.path === 'string' && proj.path) {
+      return path.resolve(expandHome(proj.path));
+    }
+  }
+  return path.resolve(cwd, name);
+}
+
+function previewContent(rendered) {
+  const lines = rendered.split('\n');
+  const totalLines = lines.length;
+  const truncated = totalLines > PREVIEW_LINES;
+  const contentPreview = truncated
+    ? lines.slice(0, PREVIEW_LINES).join('\n')
+    : rendered;
+  return { contentPreview, totalLines, truncated };
+}
+
+// Normalize templates.listTemplates() output. T2's templates.js returns a
+// flat array of filenames (e.g. 'CLAUDE.md.tmpl'); legacy/test stubs may
+// return objects with explicit { name, targetPath }. Either is accepted.
+//
+// `destFor` maps a filename → absolute path inside the project tree. T2
+// exports this from init-project.js as `_destFor`. The preview computes the
+// path relative to `projectRoot` so the response payload uses repo-relative
+// paths the UI can render directly.
+function normalizeTemplateItems(rawItems, destFor, projectRoot) {
+  const out = [];
+  for (const item of rawItems) {
+    if (typeof item === 'string') {
+      if (typeof destFor !== 'function') {
+        // No mapper available — best-effort: strip a trailing '.tmpl' and
+        // use the bare name as the target path. Fine for tests and a
+        // graceful fallback when init-project.js isn't on disk yet.
+        const fallback = item.endsWith('.tmpl') ? item.slice(0, -'.tmpl'.length) : item;
+        out.push({ name: item, targetPath: fallback });
+        continue;
+      }
+      let abs;
+      try {
+        abs = destFor(item, projectRoot);
+      } catch (err) {
+        // Unknown template — skip rather than fail the whole preview.
+        continue;
+      }
+      out.push({ name: item, targetPath: path.relative(projectRoot, abs) });
+      continue;
+    }
+    if (item && typeof item === 'object' && item.name && item.targetPath) {
+      out.push({ name: item.name, targetPath: item.targetPath });
+    }
+  }
+  return out;
+}
+
+function buildPreview({ name, projects, cwd, templates, destFor, version, now }) {
+  validateName(name);
+  if (!templates || typeof templates.listTemplates !== 'function' ||
+      typeof templates.renderTemplate !== 'function') {
+    const err = new Error('templates module is missing listTemplates / renderTemplate');
+    err.statusCode = 503;
+    throw err;
+  }
+
+  const targetPath = resolveTargetPath({ name, projects, cwd });
+  const exists = fs.existsSync(targetPath);
+  const renderedAt = (now && typeof now === 'function' ? now() : new Date()).toISOString();
+
+  const vars = {
+    project_name: name,
+    project_path: targetPath,
+    generated_at: renderedAt,
+    termdeck_version: version || '0.0.0'
+  };
+
+  const items = normalizeTemplateItems(templates.listTemplates() || [], destFor, targetPath);
+  const wouldCreate = [];
+  const wouldSkip = [];
+
+  for (const item of items) {
+    if (!item || !item.name || !item.targetPath) continue;
+    const filePath = path.join(targetPath, item.targetPath);
+    let rendered;
+    try {
+      rendered = templates.renderTemplate(item.name, vars);
+    } catch (err) {
+      // Surface render errors as a wouldSkip entry rather than failing the
+      // whole preview — gives the user actionable info without breaking the
+      // pane. (Most likely cause: template references a placeholder we don't
+      // populate yet — coordination point with T2.)
+      wouldSkip.push({
+        path: item.targetPath,
+        contentPreview: '',
+        totalLines: 0,
+        renderedAt,
+        reason: `render failed: ${err.message}`
+      });
+      continue;
+    }
+    const { contentPreview, totalLines } = previewContent(rendered);
+    const entry = {
+      path: item.targetPath,
+      contentPreview,
+      totalLines,
+      renderedAt
+    };
+
+    // If targetPath dir doesn't exist yet, every file is a wouldCreate.
+    // If it exists, individual files that already exist are wouldSkip.
+    const fileExists = exists && fs.existsSync(filePath);
+    if (fileExists) {
+      wouldSkip.push({ ...entry, reason: 'file already exists' });
+    } else {
+      wouldCreate.push(entry);
+    }
+  }
+
+  return {
+    projectName: name,
+    targetPath,
+    exists,
+    wouldCreate,
+    wouldSkip
+  };
+}
+
+// POST handler logic. Calls T2's initProject({ dryRun: false, force, cwd, name }),
+// then returns preview-shape with `created` populated. T2's initProject is
+// async and returns { exitCode, files } — we await it and translate a
+// non-zero exitCode into an HTTP-mappable error.
+async function generateScaffolding({ name, projects, cwd, force, initProject, templates, destFor, version, now }) {
+  validateName(name);
+  if (typeof initProject !== 'function') {
+    const err = new Error('initProject is not available — T2 init-project module not loaded');
+    err.statusCode = 503;
+    throw err;
+  }
+
+  const targetPath = resolveTargetPath({ name, projects, cwd });
+
+  // Refuse on existing non-empty dir without force, mirroring T2's CLI semantics.
+  if (fs.existsSync(targetPath)) {
+    const entries = (() => {
+      try { return fs.readdirSync(targetPath); } catch { return []; }
+    })();
+    const nonEmpty = entries.length > 0;
+    if (nonEmpty && !force) {
+      const err = new Error(
+        `Target ${targetPath} exists and is non-empty. Pass { force: true } to overwrite.`
+      );
+      err.statusCode = 409;
+      throw err;
+    }
+  }
+
+  // For fresh-name case, derive the cwd we hand to initProject from targetPath's
+  // parent so initProject({ name, cwd }) lands at the same targetPath.
+  const initCwd = path.dirname(targetPath);
+  const result = await initProject({ name, dryRun: false, force: !!force, cwd: initCwd });
+
+  if (result && typeof result === 'object' && typeof result.exitCode === 'number' && result.exitCode !== 0) {
+    const err = new Error(`initProject returned exit code ${result.exitCode}`);
+    err.statusCode = 500;
+    err.initProjectResult = result;
+    throw err;
+  }
+
+  // Re-render to return preview-shape with `created` populated. We re-read
+  // each file from disk so the response reflects exactly what landed.
+  const renderedAt = (now && typeof now === 'function' ? now() : new Date()).toISOString();
+  const created = [];
+  if (templates && typeof templates.listTemplates === 'function') {
+    const items = normalizeTemplateItems(templates.listTemplates() || [], destFor, targetPath);
+    for (const item of items) {
+      if (!item || !item.name || !item.targetPath) continue;
+      const filePath = path.join(targetPath, item.targetPath);
+      if (!fs.existsSync(filePath)) continue;
+      try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const { contentPreview, totalLines } = previewContent(raw);
+        created.push({
+          path: item.targetPath,
+          contentPreview,
+          totalLines,
+          renderedAt
+        });
+      } catch (err) {
+        // Skip unreadable files — caller can re-fetch the preview if needed.
+      }
+    }
+  }
+
+  return {
+    projectName: name,
+    targetPath,
+    exists: true,
+    created,
+    initProjectResult: result || null
+  };
+}
+
+module.exports = {
+  buildPreview,
+  generateScaffolding,
+  resolveTargetPath,
+  validateName,
+  expandHome,
+  _PREVIEW_LINES: PREVIEW_LINES,
+  _NAME_RE: NAME_RE
+};

package/packages/server/src/preflight.js

@@ -136,6 +136,82 @@ async function checkDatabase() {
   }
 }
 
+// Sprint 38 / T3 — graph-health check. Returns:
+//   pass : memory_relationships has rows AND last inferred_at < 48h ago
+//   warn : has rows but last inference > 48h ago (T2 cron may have drifted)
+//   fail : pg unreachable, table missing, or zero edges
+//
+// Reads `inferred_at` (T1's migration 009 column). Falls back to `created_at`
+// for the 749 pre-T2 edges that have no inferred_at value yet, so the check
+// doesn't perma-warn on the substrate that already exists.
+async function checkGraphHealth(config) {
+  // Only meaningful when graph features are enabled. Treat as pass with a
+  // descriptive detail so the banner doesn't FAIL on installs that haven't
+  // opted into graph recall yet.
+  const graphEnabled = config.rag?.graphRecall === true;
+  if (!graphEnabled) {
+    return { name: 'graph_health', passed: true, detail: 'graph recall disabled' };
+  }
+
+  const dbUrl = process.env.DATABASE_URL;
+  if (!dbUrl) {
+    return { name: 'graph_health', passed: false, detail: 'DATABASE_URL not set — cannot check graph' };
+  }
+
+  let pg;
+  try { pg = require('pg'); } catch (err) { pg = null; }
+  if (!pg) {
+    return { name: 'graph_health', passed: false, detail: 'pg module not installed' };
+  }
+
+  const pool = new pg.Pool({
+    connectionString: dbUrl,
+    max: 1,
+    connectionTimeoutMillis: 5000,
+  });
+
+  try {
+    // Single round-trip: edge count + last inference timestamp. coalesce on
+    // inferred_at so the substrate's pre-T2 edges register their created_at
+    // (otherwise max() returns NULL and the staleness check trips).
+    const res = await pool.query(
+      `SELECT
+         count(*)::int AS edges,
+         max(coalesce(inferred_at, created_at)) AS last_inferred_at
+       FROM memory_relationships`
+    );
+    const row = res.rows[0] || {};
+    const edges = Number(row.edges || 0);
+    if (edges === 0) {
+      return {
+        name: 'graph_health', passed: false,
+        detail: 'memory_relationships is empty — run T2 inference cron or seed edges manually',
+      };
+    }
+
+    const last = row.last_inferred_at ? new Date(row.last_inferred_at) : null;
+    if (!last) {
+      return {
+        name: 'graph_health', passed: true,
+        detail: `${edges.toLocaleString()} edges, last inference timestamp unknown`,
+      };
+    }
+
+    const agoMs = Date.now() - last.getTime();
+    const agoH = (agoMs / 3_600_000).toFixed(1);
+    const stale = agoMs > 48 * 3_600_000; // 48h cron drift threshold
+    return {
+      name: 'graph_health',
+      passed: !stale,
+      detail: stale
+        ? `${edges.toLocaleString()} edges, last inference ${agoH}h ago (stale — expected within 48h)`
+        : `${edges.toLocaleString()} edges, last inference ${agoH}h ago`,
+    };
+  } finally {
+    await pool.end().catch(() => {});
+  }
+}
+
 async function checkProjectPaths(config) {
   const projects = config.projects || {};
   const names = Object.keys(projects);
@@ -282,6 +358,10 @@ async function runPreflight(config) {
       name: 'shell_sanity', passed: false,
       detail: `check failed — ${err.message}`,
     })),
+    checkGraphHealth(config).catch((err) => ({
+      name: 'graph_health', passed: false,
+      detail: `check failed — ${err.message}`,
+    })),
   ]);
 
   const result = {
@@ -330,6 +410,7 @@ const REMEDIATION = {
   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)',
+  graph_health: 'Run T2 inference cron or apply migrations 009/010 to populate edges',
 };
 
 const CHECK_LABELS = {
@@ -339,6 +420,7 @@ const CHECK_LABELS = {
   database_url: 'Database',
   project_paths: 'Project paths',
   shell_sanity: 'Shell',
+  graph_health: 'Graph',
 };
 
 function printHealthBanner(result) {