@jhizzard/termdeck 0.7.3 → 0.9.0

package/packages/server/src/config.js

@@ -298,11 +298,107 @@ function addProject({ name, path: projectPath, defaultTheme, defaultCommand }) {
   return parsed.projects;
 }
 
+// Apply a structural patch to ~/.termdeck/config.yaml. Sprint 36 introduces
+// this for the dashboard RAG toggle (PATCH /api/config) but the helper is
+// generic — pass a deep partial of the config tree, every leaf in `patch` that
+// matches the whitelist gets written through. Returns the parsed-from-disk
+// post-write tree (NOT post-substitution; we only persist user-authored values
+// here, never substituted secrets).
+//
+// Whitelist deliberately tight. Only fields a UI can safely flip live belong
+// here. Adding a new field is an explicit one-line edit (vs. a freeform writer
+// that would let a buggy/malicious client change `port`, `shell`, or projects).
+//
+// Comments and formatting in config.yaml are NOT preserved — same trade-off
+// as `addProject`. The yaml package's parseDocument API can preserve comments
+// but we'd need to migrate addProject too for consistency; that's a follow-up.
+const UPDATABLE_PATHS = new Set([
+  'rag.enabled'
+]);
+
+function flattenPatch(obj, prefix = '') {
+  const out = [];
+  if (obj == null || typeof obj !== 'object' || Array.isArray(obj)) return out;
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+      out.push(...flattenPatch(v, key));
+    } else {
+      out.push([key, v]);
+    }
+  }
+  return out;
+}
+
+function setPath(obj, segs, value) {
+  let cur = obj;
+  for (let i = 0; i < segs.length - 1; i++) {
+    const s = segs[i];
+    if (cur[s] == null || typeof cur[s] !== 'object') cur[s] = {};
+    cur = cur[s];
+  }
+  cur[segs[segs.length - 1]] = value;
+}
+
+function updateConfig(patch, configPath = CONFIG_PATH) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    throw new Error('updateConfig: patch must be a plain object');
+  }
+
+  const flat = flattenPatch(patch);
+  if (flat.length === 0) {
+    throw new Error('updateConfig: patch is empty');
+  }
+
+  for (const [key, val] of flat) {
+    if (!UPDATABLE_PATHS.has(key)) {
+      throw new Error(`updateConfig: ${key} is not in the updatable whitelist`);
+    }
+    if (key === 'rag.enabled' && typeof val !== 'boolean') {
+      throw new Error('updateConfig: rag.enabled must be a boolean');
+    }
+  }
+
+  const yaml = require('yaml');
+  let parsed = {};
+  if (fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    try {
+      parsed = yaml.parse(raw) || {};
+    } catch (err) {
+      throw new Error(`config.yaml is not valid YAML — refusing to overwrite: ${err.message}`);
+    }
+  }
+
+  for (const [key, val] of flat) {
+    setPath(parsed, key.split('.'), val);
+  }
+
+  if (fs.existsSync(configPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const bak = `${configPath}.${ts}.bak`;
+    try {
+      fs.copyFileSync(configPath, bak);
+    } catch (err) {
+      console.warn('[config] Could not write backup before updateConfig:', err.message);
+    }
+  }
+
+  const out = yaml.stringify(parsed);
+  fs.writeFileSync(configPath, out, 'utf-8');
+  console.log(`[config] updateConfig wrote ${flat.map(([k]) => k).join(', ')}`);
+
+  return parsed;
+}
+
 module.exports = {
   loadConfig,
   addProject,
+  updateConfig,
   // exported for tests / introspection
   _parseDotenv: parseDotenv,
   _substituteEnv: substituteEnv,
+  _flattenPatch: flattenPatch,
+  _UPDATABLE_PATHS: UPDATABLE_PATHS,
   _paths: { CONFIG_DIR, CONFIG_PATH, SECRETS_PATH }
 };

package/packages/server/src/index.js

@@ -61,8 +61,55 @@ const { TranscriptWriter } = require('./transcripts');
 const { createHealthHandler, runPreflight } = require('./preflight');
 const { getFullHealth } = require('./health');
 const { themes, statusColors } = require('./themes');
-const { loadConfig, addProject } = require('./config');
+const { loadConfig, addProject, updateConfig } = require('./config');
 const { createAuthMiddleware, verifyWebSocketUpgrade, hasAuth } = require('./auth');
+const { createSprintRoutes } = require('./sprint-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 +136,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) {
@@ -662,10 +717,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 +736,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 +883,25 @@ 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),
+  });
+
   // GET /api/sessions/:id - get session details
   app.get('/api/sessions/:id', (req, res) => {
     const session = sessions.get(req.params.id);
@@ -1069,16 +1141,64 @@ function createServer(config) {
     res.json(t);
   });
 
-  // GET /api/config - current config (sanitized)
-  app.get('/api/config', (req, res) => {
-    res.json({
+  // Public-shape helper so GET and PATCH return the same envelope.
+  function publicConfigPayload() {
+    return {
       projects: config.projects || {},
       defaultTheme: config.defaultTheme,
+      // ragEnabled is the EFFECTIVE state (after credential eligibility).
+      // ragConfigEnabled is the user's intent from config.yaml. The dashboard
+      // toggle reads ragConfigEnabled (intent) but renders a warning when it
+      // diverges from ragEnabled (e.g. enabled in config but Supabase creds
+      // missing → effective state stays off).
       ragEnabled: rag.enabled,
+      ragConfigEnabled: !!(config.rag && config.rag.enabled),
+      ragSupabaseConfigured: !!(config.rag?.supabaseUrl && config.rag?.supabaseKey),
       aiQueryAvailable: !!(config.rag?.supabaseUrl && config.rag?.supabaseKey && config.rag?.openaiApiKey),
       statusColors,
       firstRun
-    });
+    };
+  }
+
+  // GET /api/config - current config (sanitized)
+  app.get('/api/config', (req, res) => {
+    res.json(publicConfigPayload());
+  });
+
+  // PATCH /api/config - update writable config fields. Sprint 36 T3 Deliverable A.
+  // Body: { rag: { enabled: boolean } } — the only currently writable path.
+  // Persists to ~/.termdeck/config.yaml, live-updates the in-memory integration,
+  // and broadcasts a `config_changed` WS event so all open dashboards re-render
+  // their RAG indicator without a refresh.
+  app.patch('/api/config', (req, res) => {
+    const body = req.body;
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return res.status(400).json({ error: 'body must be a JSON object' });
+    }
+    try {
+      updateConfig(body);
+    } catch (err) {
+      return res.status(400).json({ error: err.message });
+    }
+
+    if (body.rag && typeof body.rag.enabled === 'boolean') {
+      rag.setEnabled(body.rag.enabled);
+    }
+
+    const payload = publicConfigPayload();
+
+    try {
+      const wsPayload = JSON.stringify({ type: 'config_changed', config: payload });
+      wss.clients.forEach((client) => {
+        if (client.readyState === 1) {
+          try { client.send(wsPayload); } catch (err) { console.error('[ws] config_changed send failed:', err); }
+        }
+      });
+    } catch (err) {
+      console.error('[ws] config_changed broadcast failed:', err);
+    }
+
+    res.json(payload);
   });
 
   // POST /api/projects - add a new project on the fly, persist to config.yaml
@@ -1097,6 +1217,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();
@@ -1466,6 +1646,14 @@ function createServer(config) {
 
     ws.on('close', () => {
       console.log(`[ws] Client disconnected from session ${sessionId}`);
+      // Intentional: PTYs survive WS close. The session stays in the manager,
+      // the PTY keeps running, and reconnecting (?session=<id>) re-binds.
+      // PTY teardown happens only via DELETE /api/sessions/:id (user-initiated)
+      // or the PTY's own exit event. Hard-refresh is therefore non-destructive.
+      // Sprint 36 T3 Deliverable C audit (2026-04-27): the briefing predicted
+      // this handler would call pty.kill() — it does not. Joshua's original
+      // hard-refresh-loses-PTYs symptom was the reclaimStalePort SIGKILL chain
+      // (orchestrator hotfix #2, 15:25 ET), not a WS-close cascade.
       if (session.ws === ws) {
         session.ws = null;
       }

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