@jhizzard/termdeck 0.8.0 → 0.9.0

package/packages/server/src/index.js

@@ -63,6 +63,53 @@ 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 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);
@@ -1145,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();

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/sprint-inject.js

@@ -0,0 +1,156 @@
+'use strict';
+
+// Two-stage submit pattern for the in-dashboard 4+1 sprint runner (Sprint 37 T4).
+//
+// The cardinal rule from the global 4+1 inject mandate:
+//
+//   Stage 1: write `\x1b[200~<prompt>\x1b[201~` to each session in turn,
+//            with a small inter-session gap. NO trailing CR.
+//   Settle:  ~400ms so the PTY flushes the paste to the input handler.
+//   Stage 2: write `\r` alone to each session.
+//
+// Single-stage `<prompt>\x1b[201~\r` is BANNED — when the close marker and the
+// CR ride in one PTY write, the OS-level chunk boundary is non-deterministic;
+// some lanes treat `\r` as the trailing paste byte rather than a submit
+// keystroke, leaving panels visually populated but waiting on a human Enter.
+// That cost Joshua broken sleep during ClaimGuard Sprints 4-5 (2026-04-26) and
+// the Sprint-36 inject (2026-04-27). This module is the structural fix.
+//
+// After both stages, this module verifies each panel reaches `status:'thinking'`
+// within `verifyTimeoutMs`. Any lane that didn't get there is auto-poked
+// (single CR-flood); we never page the user.
+//
+// Pure logic — caller injects writeBytes/getStatus/sleep so tests don't need
+// a live PTY. Wired in by sprint-routes.js.
+
+const DEFAULTS = {
+  gapMs: 250,
+  settleMs: 400,
+  verifyTimeoutMs: 8000,
+  verifyPollMs: 500,
+  postPokeWaitMs: 500,
+};
+
+async function injectSprintPrompts({
+  sessionIds,
+  prompts,
+  writeBytes,
+  getStatus,
+  sleep,
+  options,
+}) {
+  if (!Array.isArray(sessionIds) || !Array.isArray(prompts)) {
+    throw new Error('sessionIds and prompts must be arrays');
+  }
+  if (sessionIds.length !== prompts.length) {
+    throw new Error('sessionIds and prompts must be the same length');
+  }
+  if (sessionIds.length === 0) {
+    throw new Error('at least one session required');
+  }
+  if (typeof writeBytes !== 'function') {
+    throw new Error('writeBytes(sessionId, bytes) callback required');
+  }
+  if (typeof sleep !== 'function') {
+    throw new Error('sleep(ms) callback required');
+  }
+
+  const opts = { ...DEFAULTS, ...(options || {}) };
+
+  const lanes = sessionIds.map((sessionId, i) => ({
+    sessionId,
+    prompt: prompts[i],
+    paste: null,
+    submit: null,
+    verified: false,
+    poked: false,
+    finalStatus: null,
+  }));
+
+  // Stage 1: paste-only across all lanes, gapMs between each.
+  for (let i = 0; i < lanes.length; i++) {
+    const lane = lanes[i];
+    const payload = `\x1b[200~${lane.prompt}\x1b[201~`;
+    try {
+      const r = await writeBytes(lane.sessionId, payload);
+      lane.paste = { ok: true, bytes: (r && r.bytes) || payload.length };
+    } catch (err) {
+      lane.paste = { ok: false, error: err && err.message ? err.message : String(err) };
+    }
+    if (i < lanes.length - 1) await sleep(opts.gapMs);
+  }
+
+  // Settle window — long enough for the PTY to flush each paste to the TUI's
+  // input handler before the trailing CR lands.
+  await sleep(opts.settleMs);
+
+  // Stage 2: submit-only (\r alone, guaranteed its own PTY write).
+  for (let i = 0; i < lanes.length; i++) {
+    const lane = lanes[i];
+    if (!lane.paste || !lane.paste.ok) {
+      lane.submit = { ok: false, skipped: 'paste-failed' };
+      continue;
+    }
+    try {
+      const r = await writeBytes(lane.sessionId, '\r');
+      lane.submit = { ok: true, bytes: (r && r.bytes) || 1 };
+    } catch (err) {
+      lane.submit = { ok: false, error: err && err.message ? err.message : String(err) };
+    }
+    if (i < lanes.length - 1) await sleep(opts.gapMs);
+  }
+
+  // Verify: poll each lane's status until it reads `thinking` or we hit the
+  // deadline. Lanes that never thinking → auto-/poke (cr-flood).
+  if (typeof getStatus === 'function') {
+    const deadline = Date.now() + opts.verifyTimeoutMs;
+    while (Date.now() < deadline) {
+      let anyPending = false;
+      for (const lane of lanes) {
+        if (lane.verified) continue;
+        try {
+          const s = await getStatus(lane.sessionId);
+          lane.finalStatus = s && s.status ? s.status : null;
+          if (lane.finalStatus === 'thinking') {
+            lane.verified = true;
+          } else {
+            anyPending = true;
+          }
+        } catch {
+          anyPending = true;
+        }
+      }
+      if (!anyPending) break;
+      await sleep(opts.verifyPollMs);
+    }
+
+    // Auto-poke (cr-flood) any lane that didn't reach `thinking`. Best-effort —
+    // never page the user; the orchestrator dashboard surfaces the result.
+    for (const lane of lanes) {
+      if (lane.verified) continue;
+      try {
+        await writeBytes(lane.sessionId, '\r\r\r');
+        lane.poked = true;
+      } catch (err) {
+        lane.pokeError = err && err.message ? err.message : String(err);
+        continue;
+      }
+      await sleep(opts.postPokeWaitMs);
+      try {
+        const s = await getStatus(lane.sessionId);
+        lane.finalStatus = s && s.status ? s.status : lane.finalStatus;
+        if (lane.finalStatus === 'thinking') lane.verified = true;
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  const ok = lanes.every((l) => l.paste && l.paste.ok && l.submit && l.submit.ok);
+  return { ok, lanes };
+}
+
+module.exports = {
+  injectSprintPrompts,
+  DEFAULTS,
+};