@geraldmaron/construct 1.0.0

package/lib/role-preload.mjs

@@ -0,0 +1,52 @@
+/**
+ * lib/role-preload.mjs — inline role anti-pattern files into specialist prompts at sync time.
+ *
+ * Specialist prompts carry a marker: **Role guidance**: call `get_skill("roles/NAME")` before drafting.
+ * buildPrompt() in sync-agents.mjs replaces that marker with the role body so the content is always
+ * present — no runtime get_skill dependency. Flavor overlays (e.g. engineer.ai) are concatenated
+ * under the core role content.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+export const ROLE_DIRECTIVE_RE = /^[ \t]*\*\*Role guidance\*\*:\s*call\s+`get_skill\("roles\/([^"]+)"\)`\s*before\s*drafting\.[ \t]*$/m;
+
+export const PROMPT_WORD_CAP = 3600;
+
+function stripFrontmatter(body) {
+  if (!body.startsWith("---\n")) return body;
+  const end = body.indexOf("\n---\n", 4);
+  return end === -1 ? body : body.slice(end + 5);
+}
+
+function stripTopHeading(body) {
+  return body.replace(/^#\s+[^\n]*\n+/, "").replace(/^Load this[^\n]*\n+/, "");
+}
+
+export function readRoleFile(root, name) {
+  const p = path.join(root, "skills", "roles", `${name}.md`);
+  if (!fs.existsSync(p)) return null;
+  return stripTopHeading(stripFrontmatter(fs.readFileSync(p, "utf8"))).trim();
+}
+
+export function inlineRoleAntiPatterns(prompt, root, agentName = "(unknown)", warn = console.warn) {
+  const match = prompt.match(ROLE_DIRECTIVE_RE);
+  if (!match) return prompt;
+  const ref = match[1];
+  const [core, flavor] = ref.split(".");
+  const coreBody = readRoleFile(root, core);
+  if (!coreBody) {
+    warn(`[sync] ${agentName}: role file skills/roles/${core}.md missing; leaving directive in place`);
+    return prompt;
+  }
+  let block = `## Role guidance\n\n${coreBody}`;
+  if (flavor) {
+    const flavorBody = readRoleFile(root, `${core}.${flavor}`);
+    if (flavorBody) {
+      block += `\n\n### ${flavor} overlay\n\n${flavorBody}`;
+    } else {
+      warn(`[sync] ${agentName}: flavor file skills/roles/${core}.${flavor}.md missing`);
+    }
+  }
+  return prompt.replace(ROLE_DIRECTIVE_RE, block);
+}

package/lib/schemas/decision.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Decision",
+  "description": "Output from cx-architect: a documented architectural or design decision",
+  "type": "object",
+  "required": ["type", "goal", "approach", "tasks", "risks", "acceptanceCriteria"],
+  "properties": {
+    "type": { "type": "string", "enum": ["decision"] },
+    "goal": { "type": "string", "description": "Objective restated in one sentence" },
+    "approach": { "type": "string", "description": "Chosen strategy and rationale" },
+    "alternativesConsidered": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "tasks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "owner", "complexity"],
+        "properties": {
+          "description": { "type": "string" },
+          "owner": { "type": "string" },
+          "complexity": { "type": "string", "enum": ["S", "M", "L"] }
+        }
+      }
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["description", "mitigation"],
+        "properties": {
+          "description": { "type": "string" },
+          "mitigation": { "type": "string" }
+        }
+      }
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "doNotTouch": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Files or systems that must stay unchanged"
+    }
+  },
+  "additionalProperties": false
+}

package/lib/schemas/implementation.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Implementation",
+  "description": "Output from cx-engineer: summary of changes made",
+  "type": "object",
+  "required": ["type", "status", "filesChanged", "verificationChecklist"],
+  "properties": {
+    "type": { "type": "string", "enum": ["implementation"] },
+    "status": {
+      "type": "string",
+      "enum": ["DONE", "BLOCKED", "NEEDS_MAIN_INPUT"]
+    },
+    "filesChanged": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "action"],
+        "properties": {
+          "path": { "type": "string" },
+          "action": { "type": "string", "enum": ["created", "modified", "deleted"] },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "verificationChecklist": {
+      "type": "object",
+      "properties": {
+        "compilesWithoutErrors": { "type": "boolean" },
+        "existingTestsPass": { "type": "boolean" },
+        "newBehaviorHasCoverage": { "type": "boolean" },
+        "noHardcodedSecrets": { "type": "boolean" },
+        "noFileOver800Lines": { "type": "boolean" }
+      },
+      "required": ["compilesWithoutErrors", "existingTestsPass", "newBehaviorHasCoverage", "noHardcodedSecrets", "noFileOver800Lines"]
+    },
+    "blockerDescription": {
+      "type": "string",
+      "description": "Required when status is BLOCKED or NEEDS_MAIN_INPUT"
+    },
+    "needsMainInput": {
+      "type": "object",
+      "description": "Required when status is NEEDS_MAIN_INPUT",
+      "properties": {
+        "taskKey": { "type": "string" },
+        "question": { "type": "string" },
+        "safeDefault": { "type": "string" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/lib/schemas/review-report.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReviewReport",
+  "description": "Output from cx-reviewer or cx-security: findings from a code or security review",
+  "type": "object",
+  "required": ["type", "target", "verdict", "findings"],
+  "properties": {
+    "type": { "type": "string", "enum": ["review-report"] },
+    "target": { "type": "string", "description": "Files or scope reviewed" },
+    "verdict": {
+      "type": "string",
+      "enum": ["APPROVED", "APPROVED_WITH_WARNINGS", "BLOCKED"],
+      "description": "APPROVED = no CRITICAL/HIGH. APPROVED_WITH_WARNINGS = only HIGH (merge with caution). BLOCKED = CRITICAL found."
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["severity", "category", "location", "description", "fix"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"] },
+          "category": { "type": "string", "description": "e.g. correctness, security, regression, coverage, maintainability" },
+          "location": { "type": "string", "description": "file:line" },
+          "description": { "type": "string" },
+          "fix": { "type": "string", "description": "Concrete remediation" }
+        }
+      }
+    },
+    "summary": { "type": "string", "description": "One-paragraph summary of overall quality" }
+  },
+  "additionalProperties": false
+}

package/lib/schemas/test-report.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TestReport",
+  "description": "Output from cx-qa: results of test planning and execution",
+  "type": "object",
+  "required": ["type", "verdict", "passed", "failed", "coverage"],
+  "properties": {
+    "type": { "type": "string", "enum": ["test-report"] },
+    "verdict": {
+      "type": "string",
+      "enum": ["PASS", "FAIL"],
+      "description": "PASS = all tests green and coverage meets threshold. FAIL = failing tests or coverage below threshold."
+    },
+    "passed": { "type": "integer", "minimum": 0 },
+    "failed": { "type": "integer", "minimum": 0 },
+    "skipped": { "type": "integer", "minimum": 0 },
+    "coverage": {
+      "type": "object",
+      "properties": {
+        "overall": { "type": "number", "description": "0.0–100.0 percentage" },
+        "meetsThreshold": { "type": "boolean" },
+        "threshold": { "type": "number" }
+      }
+    },
+    "failingTests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "error"],
+        "properties": {
+          "name": { "type": "string" },
+          "error": { "type": "string" }
+        }
+      }
+    },
+    "gaps": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Untested behaviors that should have tests"
+    }
+  },
+  "additionalProperties": false
+}

package/lib/server/index.mjs

@@ -0,0 +1,334 @@
+/**
+ * lib/server/index.mjs — <one-line purpose>
+ *
+ * <2–6 line summary: what it does, who calls it, key side effects.>
+ */
+import { createServer } from 'http';
+import { readFileSync, writeFileSync, statSync, watch, existsSync, readdirSync } from 'fs';
+import { join, extname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { buildStatus as buildSharedStatus } from '../status.mjs';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const ROOT_DIR = join(__dirname, '..', '..');
+const HOME = homedir();
+const PORT = parseInt(process.env.PORT ?? '4242', 10);
+
+const STATIC_DIR = join(__dirname, 'static');
+const REGISTRY_FILE = join(ROOT_DIR, 'agents', 'registry.json');
+const FEATURES_FILE = join(HOME, '.construct', 'features.json');
+const WORKFLOW_FILE = join(process.cwd(), '.cx', 'workflow.json');
+const SKILLS_DIR = join(ROOT_DIR, 'skills');
+const COMMANDS_DIR = join(ROOT_DIR, 'commands');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+};
+
+function listCommands() {
+  if (!existsSync(COMMANDS_DIR)) return [];
+  const result = [];
+  for (const domain of readdirSync(COMMANDS_DIR).sort()) {
+    const domainPath = join(COMMANDS_DIR, domain);
+    try {
+      if (!statSync(domainPath).isDirectory()) continue;
+      const commands = [];
+      for (const file of readdirSync(domainPath).sort()) {
+        if (!file.endsWith('.md')) continue;
+        const content = readFileSync(join(domainPath, file), 'utf8');
+        const match = content.match(/^---\r?\n[\s\S]*?description:\s*(.+?)\r?\n[\s\S]*?---/);
+        const description = match ? match[1].trim() : file.replace('.md', '');
+        commands.push({ name: file.replace('.md', ''), description, slash: `/${domain}:${file.replace('.md', '')}` });
+      }
+      if (commands.length) result.push({ domain, commands });
+    } catch { continue; }
+  }
+  return result;
+}
+
+function listSkills() {
+  if (!existsSync(SKILLS_DIR)) return [];
+  const result = [];
+  for (const cat of readdirSync(SKILLS_DIR)) {
+    const catPath = join(SKILLS_DIR, cat);
+    try {
+      const stat = statSync(catPath);
+      if (!stat.isDirectory()) continue;
+      const files = readdirSync(catPath)
+        .filter(f => f.endsWith('.md') || f.endsWith('.mjs'))
+        .filter(f => f !== 'SKILL.md');
+      result.push({ category: cat, files });
+    } catch { continue; }
+  }
+  return result;
+}
+
+async function buildStatus() {
+  const status = await buildSharedStatus({
+    rootDir: ROOT_DIR,
+    cwd: process.cwd(),
+    homeDir: HOME,
+    dashboardPort: PORT,
+    selfDashboard: true,
+  });
+
+  return {
+    ...status,
+    skills: listSkills(),
+    commands: listCommands(),
+  };
+}
+
+async function handleSessionUsage(_req, res) {
+  try {
+    const status = await buildSharedStatus({
+      rootDir: ROOT_DIR,
+      cwd: process.cwd(),
+      homeDir: HOME,
+    });
+
+    const payload = {
+      source: status.sessionUsage?.status === 'available' ? 'local-session-log' : 'unavailable',
+      status: status.sessionUsage?.status ?? 'unavailable',
+      sessionUsage: status.sessionUsage,
+      guidance: status.sessionUsage?.status === 'available'
+        ? 'Construct can answer token usage questions from locally recorded session usage.'
+        : 'No local token usage has been recorded for this session yet.',
+    };
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(payload));
+  } catch (err) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: err.message }));
+  }
+}
+
+const sseClients = new Set();
+const activeWatchers = [];
+let watchRefreshTimer = null;
+
+function notifyClients() {
+  for (const res of sseClients) {
+    try { res.write('data: refresh\n\n'); }
+    catch { sseClients.delete(res); }
+  }
+}
+
+function closeWatchers() {
+  while (activeWatchers.length) {
+    try { activeWatchers.pop().close(); }
+    catch { /* ignore close errors */ }
+  }
+}
+
+function scheduleWatchRefresh() {
+  clearTimeout(watchRefreshTimer);
+  watchRefreshTimer = setTimeout(() => {
+    watchFiles();
+    notifyClients();
+  }, 150);
+}
+
+function addWatcher(target) {
+  if (!existsSync(target)) return;
+  try {
+    const watcher = watch(target, () => scheduleWatchRefresh());
+    activeWatchers.push(watcher);
+  } catch {
+    /* ignore watch errors */
+  }
+}
+
+function addDirectoryTreeWatch(root) {
+  if (!existsSync(root)) return;
+  addWatcher(root);
+  try {
+    for (const entry of readdirSync(root)) {
+      const full = join(root, entry);
+      try {
+        if (statSync(full).isDirectory()) addWatcher(full);
+      } catch {
+        /* ignore stat errors */
+      }
+    }
+  } catch {
+    /* ignore read errors */
+  }
+}
+
+function watchFiles() {
+  closeWatchers();
+  [REGISTRY_FILE, FEATURES_FILE, WORKFLOW_FILE].forEach(addWatcher);
+  addDirectoryTreeWatch(SKILLS_DIR);
+  addDirectoryTreeWatch(COMMANDS_DIR);
+}
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
+
+  if (url.pathname === '/events') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.write(': connected\n\n');
+    sseClients.add(res);
+    req.on('close', () => sseClients.delete(res));
+    return;
+  }
+
+  if (url.pathname === '/api/registry' && req.method === 'GET') {
+    try {
+      const registry = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ mcpServers: registry.mcpServers ?? {}, models: registry.models ?? {} }));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
+  if (url.pathname === '/api/status') {
+    try {
+      const status = await buildStatus();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(status));
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: err.message }));
+    }
+    return;
+  }
+
+  if (url.pathname === '/api/session-usage') {
+    await handleSessionUsage(req, res);
+    return;
+  }
+
+  if (req.method === 'POST') {
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', async () => {
+      try {
+        const data = JSON.parse(body || '{}');
+        const { approveWorkflow, approveTask } = await import('../workflow-state.mjs');
+        const { promoteHeadhunt, updatePromotionChallenge } = await import('../headhunt.mjs');
+
+        if (url.pathname === '/api/workflow/approve') {
+          const workflow = approveWorkflow(process.cwd(), data.note);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ success: true, workflow }));
+          notifyClients();
+        } else if (url.pathname === '/api/workflow/approve-task') {
+          if (!data.key) throw new Error('Missing task key');
+          const workflow = approveTask(process.cwd(), data.key, data.note);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ success: true, workflow }));
+          notifyClients();
+        } else if (url.pathname === '/api/headhunt/promote') {
+          if (!data.id) throw new Error('Missing overlay id');
+          const request = promoteHeadhunt(data.id, { cwd: process.cwd(), owner: data.owner || null });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ success: true, request }));
+          notifyClients();
+        } else if (url.pathname === '/api/headhunt/challenge') {
+          if (!data.id) throw new Error('Missing overlay id');
+          if (!data.status) throw new Error('Missing challenge status');
+          const request = updatePromotionChallenge(data.id, {
+            cwd: process.cwd(),
+            status: data.status,
+            note: data.note || null,
+          });
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ success: true, request }));
+          notifyClients();
+        } else if (url.pathname === '/api/registry/mcp') {
+          const registry = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+          if (!registry.mcpServers) registry.mcpServers = {};
+          const { action, id, server } = data;
+          if (!id || typeof id !== 'string' || !/^[\w-]+$/.test(id)) throw new Error('Invalid MCP server id');
+          if (action === 'delete') {
+            delete registry.mcpServers[id];
+          } else if (action === 'save' && server && typeof server === 'object') {
+            const entry = {};
+            if (server.type === 'url') {
+              if (!server.url) throw new Error('URL required for type=url');
+              entry.type = 'url';
+              entry.url = String(server.url);
+              if (server.headers && typeof server.headers === 'object') entry.headers = server.headers;
+            } else {
+              if (!server.command) throw new Error('command required');
+              entry.command = String(server.command);
+              entry.args = Array.isArray(server.args) ? server.args.map(String) : [];
+            }
+            if (server.description) entry.description = String(server.description);
+            registry.mcpServers[id] = entry;
+          } else {
+            throw new Error('action must be save or delete');
+          }
+          writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2) + '\n');
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ success: true }));
+          notifyClients();
+        } else if (url.pathname === '/api/registry/models') {
+          const registry = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));
+          const { tier, primary, fallback } = data;
+          const VALID_TIERS = ['reasoning', 'standard', 'fast'];
+          if (!VALID_TIERS.includes(tier)) throw new Error('tier must be reasoning, standard, or fast');
+          if (!primary || typeof primary !== 'string') throw new Error('primary model required');
+          if (!registry.models) registry.models = {};
+          registry.models[tier] = {
+            primary: String(primary),
+            fallback: Array.isArray(fallback) ? fallback.map(String).filter(Boolean) : [],
+          };
+          writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2) + '\n');
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ success: true }));
+          notifyClients();
+        } else {
+          res.writeHead(404);
+          res.end('Not found');
+        }
+      } catch (err) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+    });
+    return;
+  }
+
+  // Static files
+  let filePath = url.pathname === '/' ? '/index.html' : url.pathname;
+  const fullPath = join(STATIC_DIR, filePath);
+
+  if (!fullPath.startsWith(STATIC_DIR)) {
+    res.writeHead(403);
+    res.end('Forbidden');
+    return;
+  }
+
+  if (!existsSync(fullPath)) {
+    res.writeHead(404);
+    res.end('Not found');
+    return;
+  }
+
+  const ext = extname(fullPath);
+  const mime = MIME[ext] ?? 'application/octet-stream';
+  res.writeHead(200, { 'Content-Type': mime });
+  res.end(readFileSync(fullPath));
+});
+
+watchFiles();
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`Construct dashboard running at http://127.0.0.1:${PORT}`);
+});