@jhizzard/termdeck 1.4.0 → 1.6.0

package/packages/server/src/sprints/nudge.js

@@ -0,0 +1,147 @@
+'use strict';
+
+const {
+  SprintRequestError,
+  resolvePanelSessions,
+  runTwoStageSubmit,
+  sendError,
+} = require('./inject');
+
+const ALLOWED_NUDGE_KINDS = new Set([
+  'post-landed-reminder',
+  'status-check',
+  'tooling-failure-recover',
+  'custom',
+]);
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateNudgeBody(body) {
+  const input = isPlainObject(body) ? body : {};
+  if (!Array.isArray(input.panels) || input.panels.length === 0) {
+    throw new SprintRequestError('panels must be a non-empty array');
+  }
+
+  const kind = typeof input.kind === 'string' ? input.kind.trim() : '';
+  if (!ALLOWED_NUDGE_KINDS.has(kind)) {
+    throw new SprintRequestError(
+      `kind must be one of: ${Array.from(ALLOWED_NUDGE_KINDS).join(', ')}`,
+    );
+  }
+
+  const panels = input.panels.map((panel, index) => {
+    if (!isPlainObject(panel)) {
+      throw new SprintRequestError(`panels[${index}] must be an object`);
+    }
+    const tag = typeof panel.tag === 'string' ? panel.tag.trim() : '';
+    const sessionId = typeof panel.sessionId === 'string' ? panel.sessionId.trim() : '';
+    if (!tag) throw new SprintRequestError(`panels[${index}].tag is required`);
+    if (!sessionId) throw new SprintRequestError(`panels[${index}].sessionId is required`);
+    return { tag, sessionId };
+  });
+
+  const context = isPlainObject(input.context) ? input.context : {};
+  if (kind === 'custom') {
+    const text = typeof input.text === 'string'
+      ? input.text
+      : (typeof context.custom_text === 'string' ? context.custom_text : context.customText);
+    if (typeof text !== 'string' || text.length === 0) {
+      throw new SprintRequestError('custom nudge requires text or context.custom_text');
+    }
+  }
+  if (kind === 'post-landed-reminder') {
+    if (!context.open_red) {
+      throw new SprintRequestError('post-landed-reminder requires context.open_red');
+    }
+    if (!context.test_repro && !context.testRepro) {
+      throw new SprintRequestError('post-landed-reminder requires context.test_repro');
+    }
+  }
+
+  return { panels, kind, context, text: input.text };
+}
+
+function valueFromMaybeObject(value, preferredKeys) {
+  if (typeof value === 'string') return value;
+  if (!isPlainObject(value)) return String(value || '');
+  for (const key of preferredKeys) {
+    if (typeof value[key] === 'string' && value[key]) return value[key];
+  }
+  return JSON.stringify(value);
+}
+
+function buildNudgeText({ panel, kind, context, text }) {
+  if (kind === 'custom') {
+    return typeof text === 'string' ? text : (context.custom_text || context.customText);
+  }
+
+  if (kind === 'post-landed-reminder') {
+    const sprintName = context.sprint_name || context.sprintName || 'current sprint';
+    const fileLine = valueFromMaybeObject(context.open_red, ['file_line', 'fileLine', 'line']);
+    const testRepro = context.test_repro || context.testRepro;
+    return [
+      `ORCHESTRATOR NUDGE — ${sprintName}.`,
+      `${panel.tag}: T4 audit found ${fileLine} with repro ${testRepro}.`,
+      `Your fix should land as \`### [${panel.tag}] LANDED ...\` to STATUS.md once tests pass and the auditor has reacted.`,
+    ].join(' ');
+  }
+
+  if (kind === 'status-check') {
+    const minutes = context.silent_minutes || context.silentMinutes || 'several';
+    return [
+      'ORCHESTRATOR STATUS-CHECK.',
+      `STATUS.md has been silent for ${minutes} minutes.`,
+      `Post a \`### [${panel.tag}] CHECKPOINT\` with your current progress, or \`LANDED\` if done.`,
+    ].join(' ');
+  }
+
+  return [
+    'ORCHESTRATOR RECOVERY — your shell tooling appears to have died.',
+    'POST a final TOOLING-FAILURE CHECKPOINT to STATUS.md with what you have verified so far.',
+    'The orchestrator will spawn a codex-rescue subagent as the verification fallback.',
+  ].join(' ');
+}
+
+function createSprintNudgeHandler({ getSession, writeInput, sleep, options } = {}) {
+  return async (req, res) => {
+    try {
+      const parsed = validateNudgeBody(req.body || {});
+      resolvePanelSessions(parsed.panels, getSession);
+      const panels = parsed.panels.map((panel) => ({
+        ...panel,
+        text: buildNudgeText({
+          panel,
+          kind: parsed.kind,
+          context: parsed.context,
+          text: parsed.text,
+        }),
+      }));
+      const snapshots = await runTwoStageSubmit({
+        panels,
+        getSession,
+        writeInput,
+        sleep,
+        options,
+        source: 'sprint-nudge',
+      });
+      return res.json({ ok: true, panels: snapshots });
+    } catch (err) {
+      return sendError(res, err);
+    }
+  };
+}
+
+function createSprintNudgeRoutes(opts) {
+  if (!opts || !opts.app) throw new Error('app required');
+  opts.app.post('/api/sprints/nudge', createSprintNudgeHandler(opts));
+}
+
+module.exports = {
+  ALLOWED_NUDGE_KINDS,
+  buildNudgeText,
+  createSprintNudgeHandler,
+  createSprintNudgeRoutes,
+  validateNudgeBody,
+};

package/packages/server/src/sprints/status-parser.js

@@ -0,0 +1,129 @@
+/**
+ * STATUS.md parser for TermDeck.
+ *
+ * Scans the whole file to extract the latest state for each lane.
+ */
+
+const fs = require('fs');
+
+function parseStatusMd(filePath) {
+  const result = {
+    lanes: {},
+    open_red_count: 0,
+    last_orchestrator_post: null,
+    last_final_verdict: null
+  };
+
+  if (!fs.existsSync(filePath)) {
+    return result;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+
+  // Regex per BRIEF (loosened for multiple suffixes):
+  // ^### \[(T\d+(?:-[A-Z0-9-]+)?|ORCH)\] (FINDING|PROPOSE|LANDED|DONE|AUDIT-RED|AUDIT-CONCERN|CHECKPOINT|FINAL-VERDICT|STATUS|RULING) (\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}) ET — (.*?)$
+  const POST_RE = /^### \[(T\d+(?:-[A-Z0-9-]+)?|ORCH)\] (FINDING|PROPOSE|LANDED|DONE|AUDIT-RED|AUDIT-CONCERN|CHECKPOINT|FINAL-VERDICT|STATUS|RULING) (\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}) ET — (.*?)$/;
+
+  const laneLandeds = {}; // laneTag -> latest LANDED timestamp
+  const openReds = []; // List of {tag, timestamp, gist}
+
+  lines.forEach((line, index) => {
+    const match = line.match(POST_RE);
+    if (!match) return;
+
+    const [full, tag, verb, date, time, gist] = match;
+    const timestamp = `${date}T${time}:00`; 
+    const lineNum = index + 1;
+
+    if (tag === 'ORCH') {
+      result.last_orchestrator_post = gist;
+      return;
+    }
+
+    // Ensure lane entry
+    if (!result.lanes[tag]) {
+      result.lanes[tag] = {
+        last_post: null,
+        open_reds_against_me: [],
+        landed_since_last_red: false
+      };
+    }
+
+    result.lanes[tag].last_post = {
+      verb,
+      timestamp: `${date}T${time}:00-04:00`,
+      line: lineNum,
+      gist
+    };
+
+    if (verb === 'LANDED') {
+      laneLandeds[tag] = timestamp;
+    }
+
+    if (verb === 'AUDIT-RED') {
+      const mentionedLanes = gist.match(/T\d+(?:-[A-Z0-9-]+)?/g) || [];
+      mentionedLanes.forEach(targetLane => {
+        // Ensure the mentioned lane also exists in result.lanes
+        if (!result.lanes[targetLane]) {
+          result.lanes[targetLane] = {
+            last_post: null,
+            open_reds_against_me: [],
+            landed_since_last_red: false
+          };
+        }
+        openReds.push({ tag: targetLane, timestamp, gist });
+      });
+    }
+
+    if (verb === 'FINAL-VERDICT') {
+      result.last_final_verdict = {
+        verb,
+        timestamp: `${date}T${time}:00-04:00`,
+        gist
+      };
+    }
+  });
+
+  // Calculate landed_since_last_red and open_reds_against_me
+  Object.keys(result.lanes).forEach(tag => {
+    const lastLanded = laneLandeds[tag];
+    
+    result.lanes[tag].open_reds_against_me = openReds
+      .filter(red => red.tag === tag && (!lastLanded || lastLanded <= red.timestamp))
+      .map(red => ({ timestamp: red.timestamp, gist: red.gist }));
+
+    const allRedsForLane = openReds.filter(red => red.tag === tag);
+    if (allRedsForLane.length === 0) {
+      result.lanes[tag].landed_since_last_red = !!lastLanded;
+    } else {
+      const latestRedTs = allRedsForLane.reduce((max, r) => r.timestamp > max ? r.timestamp : max, "");
+      result.lanes[tag].landed_since_last_red = !!(lastLanded && lastLanded > latestRedTs);
+    }
+  });
+
+  // Count open reds
+  const uniqueOpenReds = new Set();
+  openReds.forEach(red => {
+    const lastLanded = laneLandeds[red.tag];
+    if (!lastLanded || lastLanded <= red.timestamp) {
+      uniqueOpenReds.add(`${red.tag}:${red.timestamp}`);
+    }
+  });
+  result.open_red_count = uniqueOpenReds.size;
+
+  // Final Verdict lanes_with_open_defects
+  if (result.last_final_verdict) {
+    const openDefects = [];
+    Object.keys(result.lanes).forEach(tag => {
+      if (result.lanes[tag].open_reds_against_me.length > 0) {
+        openDefects.push(tag);
+      }
+    });
+    result.last_final_verdict.lanes_with_open_defects = openDefects;
+  }
+
+  return result;
+}
+
+module.exports = { parseStatusMd };

package/packages/server/src/templates/template-engine.js

@@ -0,0 +1,197 @@
+'use strict';
+
+// Sprint 69 T1 — boot-prompt template engine.
+//
+// Looks up templates by (cliType × role), substitutes {{variable}} tokens,
+// and returns the paste-ready string. Default templates ship in
+// packages/server/share/termdeck/templates/. A per-file override at
+// ~/.termdeck/templates/<cli>-<role>.txt wins when present so projects can
+// customise without forking the package.
+//
+// Public contract (consumed by T2's POST /api/sprints/inject handler):
+//   loadTemplate(cliType, role, variables) -> string
+//     Throws TemplateNotFoundError if neither override nor default exists.
+//     Throws MissingVariableError if any {{var}} would be left unsubstituted;
+//     the error's `missingVariables` array names every unfilled token (not
+//     just the first) so callers can validate the whole template in one pass.
+//   requiredVariables(cliType, role) -> string[]
+//     Pre-scans a template for {{var}} tokens; lets the inject endpoint
+//     validate the request body before rendering.
+//
+// Token grammar: /\{\{(\w+)\}\}/g — flat names, no whitespace, no dotted
+// paths. Deliberately simpler than the Sprint 47 boot-prompt-resolver (which
+// supported `{{lane.tag}}`) so the inject body shape stays flat and the
+// failure mode (unsubstituted token left in the rendered output) is easy to
+// reason about.
+//
+// Override-directory resolution order:
+//   1. process.env.TERMDECK_TEMPLATES_OVERRIDE_DIR (set in tests; also usable
+//      for system-wide installs e.g. /etc/termdeck/templates/).
+//   2. ~/.termdeck/templates/ — the documented per-user override location.
+//   3. <repo>/packages/server/share/termdeck/templates/ — the in-package
+//      defaults that ship with @jhizzard/termdeck.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const SUPPORTED_CLI_TYPES = Object.freeze(['claude-code', 'codex', 'gemini', 'grok']);
+const SUPPORTED_ROLES = Object.freeze(['worker', 'auditor', 'orchestrator']);
+
+// Filename convention: `<cliType>-<role>.txt`. `cliType` is the literal
+// session-manager `meta.type` value (verified at session.js:165 — the
+// canonical types are 'shell' / 'claude-code' / 'gemini' / 'python-server' /
+// 'one-shot'). No aliasing layer — per the [ORCH] RULING 2026-05-20 13:13 ET,
+// `meta.type` flows from `GET /api/sessions` straight into `loadTemplate` so
+// T2's inject endpoint stays a one-liner. If the inject caller needs to
+// normalize a short-form name (e.g. 'claude') to 'claude-code', that's the
+// caller's normalization layer (see T2's `normalizeCliType` in
+// packages/server/src/sprints/inject.js).
+
+// Templates live alongside the server package: packages/server/share/termdeck/templates/.
+// __dirname here is packages/server/src/templates, so '..' twice lands at
+// packages/server/, then into share/termdeck/templates.
+const DEFAULT_TEMPLATE_DIR = path.join(
+  __dirname,
+  '..',
+  '..',
+  'share',
+  'termdeck',
+  'templates'
+);
+
+class TemplateNotFoundError extends Error {
+  constructor(message, { cliType, role, lookedUpPaths } = {}) {
+    super(message);
+    this.name = 'TemplateNotFoundError';
+    this.cliType = cliType;
+    this.role = role;
+    this.lookedUpPaths = Array.isArray(lookedUpPaths) ? lookedUpPaths : [];
+  }
+}
+
+class MissingVariableError extends Error {
+  constructor(message, { cliType, role, missingVariables } = {}) {
+    super(message);
+    this.name = 'MissingVariableError';
+    this.cliType = cliType;
+    this.role = role;
+    this.missingVariables = Array.isArray(missingVariables) ? missingVariables : [];
+  }
+}
+
+function _overrideDir() {
+  if (process.env.TERMDECK_TEMPLATES_OVERRIDE_DIR) {
+    return process.env.TERMDECK_TEMPLATES_OVERRIDE_DIR;
+  }
+  return path.join(os.homedir(), '.termdeck', 'templates');
+}
+
+function _resolveTemplatePath(cliType, role) {
+  if (!cliType || typeof cliType !== 'string') {
+    throw new TemplateNotFoundError(
+      `loadTemplate requires a string cliType; got ${cliType === undefined ? 'undefined' : JSON.stringify(cliType)}`,
+      { cliType, role, lookedUpPaths: [] }
+    );
+  }
+  if (!role || typeof role !== 'string') {
+    throw new TemplateNotFoundError(
+      `loadTemplate requires a string role; got ${role === undefined ? 'undefined' : JSON.stringify(role)}`,
+      { cliType, role, lookedUpPaths: [] }
+    );
+  }
+
+  if (!SUPPORTED_CLI_TYPES.includes(cliType)) {
+    throw new TemplateNotFoundError(
+      `Unknown cliType="${cliType}". Supported: ${SUPPORTED_CLI_TYPES.join(', ')}.`,
+      { cliType, role, lookedUpPaths: [] }
+    );
+  }
+  if (!SUPPORTED_ROLES.includes(role)) {
+    throw new TemplateNotFoundError(
+      `Unknown role="${role}". Supported: ${SUPPORTED_ROLES.join(', ')}.`,
+      { cliType, role, lookedUpPaths: [] }
+    );
+  }
+
+  const filename = `${cliType}-${role}.txt`;
+  const overrideCandidate = path.join(_overrideDir(), filename);
+  const defaultCandidate = path.join(DEFAULT_TEMPLATE_DIR, filename);
+
+  if (fs.existsSync(overrideCandidate)) {
+    return { path: overrideCandidate, source: 'override' };
+  }
+  if (fs.existsSync(defaultCandidate)) {
+    return { path: defaultCandidate, source: 'default' };
+  }
+
+  throw new TemplateNotFoundError(
+    `Template not found for cliType="${cliType}" role="${role}". Looked up override=${overrideCandidate}, default=${defaultCandidate}.`,
+    { cliType, role, lookedUpPaths: [overrideCandidate, defaultCandidate] }
+  );
+}
+
+function _scanVariables(rawTemplate) {
+  const found = new Set();
+  // Fresh regex per call — global regexes carry stateful lastIndex.
+  const re = /\{\{(\w+)\}\}/g;
+  let m;
+  while ((m = re.exec(rawTemplate)) !== null) {
+    found.add(m[1]);
+  }
+  return found;
+}
+
+function loadTemplate(cliType, role, variables) {
+  const { path: templatePath } = _resolveTemplatePath(cliType, role);
+  const raw = fs.readFileSync(templatePath, 'utf8');
+  const vars = (variables && typeof variables === 'object') ? variables : {};
+
+  // First pass: substitute every {{name}} whose name is present (and not
+  // null/undefined). Empty string IS a valid substitution. We use a fresh
+  // regex per replace call so multiple loadTemplate() calls don't interact.
+  const rendered = raw.replace(/\{\{(\w+)\}\}/g, (match, name) => {
+    if (
+      Object.prototype.hasOwnProperty.call(vars, name) &&
+      vars[name] !== undefined &&
+      vars[name] !== null
+    ) {
+      return String(vars[name]);
+    }
+    return match;
+  });
+
+  // Second pass: detect any {{...}} still in the rendered string. If any
+  // remain, the contract is violated — name them all so the caller fixes
+  // them in one pass instead of one-at-a-time.
+  const leftover = _scanVariables(rendered);
+  if (leftover.size > 0) {
+    const missing = Array.from(leftover).sort();
+    throw new MissingVariableError(
+      `Missing template variables for ${cliType}/${role}: ${missing.join(', ')}`,
+      { cliType, role, missingVariables: missing }
+    );
+  }
+
+  return rendered;
+}
+
+function requiredVariables(cliType, role) {
+  const { path: templatePath } = _resolveTemplatePath(cliType, role);
+  const raw = fs.readFileSync(templatePath, 'utf8');
+  return Array.from(_scanVariables(raw)).sort();
+}
+
+module.exports = {
+  loadTemplate,
+  requiredVariables,
+  TemplateNotFoundError,
+  MissingVariableError,
+  SUPPORTED_CLI_TYPES,
+  SUPPORTED_ROLES,
+  DEFAULT_TEMPLATE_DIR,
+  // Internal helpers exported for unit tests; not part of the public contract.
+  _resolveTemplatePath,
+  _overrideDir,
+  _scanVariables,
+};