contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/dashboard-data.mjs

@@ -0,0 +1,198 @@
+/**
+ * Dashboard data reader — single owner of "read the project's current
+ * state into a structured object" (ticket 051).
+ *
+ * Every consumer (the snapshot generator and the live `--watch` server)
+ * goes through `buildDashboardData(root)`. Files are re-read on each
+ * call; there is no caching — the data object is the snapshot.
+ *
+ * Zero deps. YAML frontmatter is parsed with a small inline parser
+ * (key: value pairs only — the kit's tickets/ADRs do not use nested
+ * YAML).
+ *
+ * Single-sourced paths via `paths.mjs` per rule 4.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import {
+  PLATFORM_DIR,
+  MEMORY_DIR,
+  DECISIONS_DIR,
+  SESSIONS_DIR,
+  CHANGELOG,
+  CONFIG_FILE,
+} from '../../runtime/config/paths.mjs';
+
+const PIPELINE_DIR = `${PLATFORM_DIR}/pipeline`;
+const ROADMAP_FILE = `${MEMORY_DIR}/roadmap.md`;
+const LANES = ['backlog', 'working', 'testing', 'conclusion'];
+
+/** Strip a leading UTF-8 BOM if present (rule 4). */
+const stripBom = (s) => s.replace(/^/, '');
+
+/** Read a file as utf-8; returns '' on any failure (defensive — rule 2). */
+function readSafe(path) {
+  try { return stripBom(readFileSync(path, 'utf-8')); } catch { return ''; }
+}
+
+/**
+ * Parse YAML-frontmatter from a markdown file's text.
+ *
+ * @param {string} text
+ * @returns {{ data: Record<string, string>, body: string }}
+ */
+export function parseFrontmatter(text) {
+  if (!text.startsWith('---')) return { data: {}, body: text };
+  const end = text.indexOf('\n---', 4);
+  if (end === -1) return { data: {}, body: text };
+  const raw = text.slice(4, end).trim();
+  const body = text.slice(end + 4).replace(/^\n/, '');
+  const data = {};
+  for (const line of raw.split('\n')) {
+    const m = /^([\w-]+):\s*(.*)$/.exec(line);
+    if (m) data[m[1]] = m[2].trim();
+  }
+  return { data, body };
+}
+
+function readTicket(lane, file, dir) {
+  const text = readSafe(resolve(dir, file));
+  const { data, body } = parseFrontmatter(text);
+  const lines = body.split('\n').filter((l) => l.trim().length > 0);
+  const firstHeading = lines.find((l) => l.startsWith('## ')) || '';
+  const bodyExcerpt = (firstHeading ? body.split(firstHeading)[1] || '' : body).slice(0, 280).trim();
+  return {
+    id: data.id || file.slice(0, 3),
+    title: data.title || firstHeading.replace(/^##\s+/, '') || file.replace(/\.md$/, ''),
+    type: data.type || '',
+    priority: data.priority || '',
+    sla: data.sla || '',
+    status: data.status || lane,
+    source: data.source || '',
+    bodyExcerpt,
+    file: `${PIPELINE_DIR}/${lane}/${file}`,
+    lane,
+  };
+}
+
+function readLane(lane, root) {
+  const dir = resolve(root, PIPELINE_DIR, lane);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('.'))
+    .map((file) => readTicket(lane, file, dir))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function readPipeline(root) {
+  const out = {};
+  for (const lane of LANES) out[lane] = readLane(lane, root);
+  return out;
+}
+
+function readAdrs(root) {
+  const dir = resolve(root, DECISIONS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /^\d{4}-.+\.md$/.test(f))
+    .map((file) => {
+      const text = readSafe(resolve(dir, file));
+      const number = file.slice(0, 4);
+      const titleMatch = /^#\s+ADR-\d+:\s*(.+)$/m.exec(text);
+      const statusMatch = /^-\s*\*\*Status\*\*:\s*(.+)$/m.exec(text);
+      const dateMatch = /^-\s*\*\*Date\*\*:\s*(.+)$/m.exec(text);
+      return {
+        number,
+        title: titleMatch ? titleMatch[1].trim() : file.replace(/^\d{4}-/, '').replace(/\.md$/, ''),
+        status: statusMatch ? statusMatch[1].trim() : 'Unknown',
+        date: dateMatch ? dateMatch[1].trim() : '',
+        file: `${DECISIONS_DIR}/${file}`,
+      };
+    })
+    .sort((a, b) => b.number.localeCompare(a.number));
+}
+
+function readSessions(root, limit = 10) {
+  const dir = resolve(root, SESSIONS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /^\d{4}-\d{2}-\d{2}-\d{2,}-.+\.md$/.test(f))
+    .map((file) => {
+      const text = readSafe(resolve(dir, file));
+      const dateMatch = /^-\s*\*\*Date\*\*:\s*(.+)$/m.exec(text);
+      const numMatch = /^-\s*\*\*Session number\*\*:\s*(.+)$/m.exec(text);
+      const branchMatch = /^-\s*\*\*Branch\*\*:\s*`?([^`\n]+)`?$/m.exec(text);
+      const titleMatch = /^#\s+(.+)$/m.exec(text);
+      return {
+        number: numMatch ? numMatch[1].trim() : file.split('-')[3] || '',
+        title: titleMatch ? titleMatch[1].trim() : file.replace(/\.md$/, ''),
+        date: dateMatch ? dateMatch[1].trim() : file.slice(0, 10),
+        branch: branchMatch ? branchMatch[1].trim() : '',
+        file: `${SESSIONS_DIR}/${file}`,
+      };
+    })
+    .sort((a, b) => b.number.localeCompare(a.number, undefined, { numeric: true }))
+    .slice(0, limit);
+}
+
+function readRoadmap(root) {
+  const text = readSafe(resolve(root, ROADMAP_FILE));
+  return { exists: text.length > 0, markdown: text };
+}
+
+function readChangelogUnreleased(root) {
+  const text = readSafe(resolve(root, CHANGELOG));
+  const idx = text.indexOf('## [Unreleased]');
+  if (idx === -1) return '';
+  const after = text.slice(idx + '## [Unreleased]'.length);
+  const next = after.search(/\n## \[/);
+  return (next === -1 ? after : after.slice(0, next)).trim();
+}
+
+function readConfig(root) {
+  try {
+    return JSON.parse(stripBom(readFileSync(resolve(root, CONFIG_FILE), 'utf-8')));
+  } catch { return null; }
+}
+
+function readBranch(root) {
+  try {
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000,
+    }).trim();
+  } catch { return ''; }
+}
+
+/**
+ * Build the full dashboard data object.
+ *
+ * @param {string} root  project root (absolute)
+ * @returns {object}     plain JS data object — no Dates, no functions
+ */
+export function buildDashboardData(root) {
+  const config = readConfig(root);
+  const pipeline = readPipeline(root);
+  return {
+    meta: {
+      project: basename(root),
+      branch: readBranch(root),
+      level: config?.level ?? null,
+      platformDir: PLATFORM_DIR,
+      generatedAt: Date.now(),
+    },
+    pipeline,
+    counts: {
+      backlog: pipeline.backlog.length,
+      working: pipeline.working.length,
+      testing: pipeline.testing.length,
+      conclusion: pipeline.conclusion.length,
+    },
+    adrs: readAdrs(root),
+    sessions: readSessions(root),
+    roadmap: readRoadmap(root),
+    changelogUnreleased: readChangelogUnreleased(root),
+  };
+}
+
+export const DASHBOARD_LANES = LANES;

package/templates/contextkit/tools/scripts/dashboard-html.mjs

@@ -0,0 +1,215 @@
+/**
+ * Dashboard HTML renderer — turns a data object from `dashboard-data.mjs`
+ * into a single self-contained HTML string (ticket 051).
+ *
+ * Single string output, no streaming. Inline CSS + inline JS, no
+ * external assets. Works opened directly from the file system AND when
+ * served by `dashboard-server.mjs` (the live `--watch` mode appends a
+ * tiny SSE-reconnecting client at the bottom).
+ *
+ * The renderer is **purely functional** — same input gives the same
+ * HTML. Reads no files; mutates no globals. Easy to unit-test.
+ */
+
+const TYPE_COLORS = {
+  bug: '#e3413c', chore: '#7a8497', increment: '#3b6ef0',
+  spike: '#8b5cf6', docs: '#10b981',
+};
+const PRI_COLORS = {
+  P1: '#e3413c', P2: '#f59e0b', P3: '#facc15', P4: '#9ca3af',
+};
+const ADR_STATUS_COLORS = {
+  Accepted: '#10b981', Proposed: '#f59e0b', Superseded: '#9ca3af',
+};
+
+const escapeHtml = (s) => String(s ?? '')
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+const fmtTime = (ms) => {
+  const d = new Date(ms);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+};
+
+const renderBadge = (text, color) =>
+  `<span class="badge" style="background:${color}">${escapeHtml(text)}</span>`;
+
+const renderCard = (t) => {
+  const typeBadge = t.type ? renderBadge(t.type, TYPE_COLORS[t.type] || '#7a8497') : '';
+  const priBadge = t.priority ? renderBadge(t.priority, PRI_COLORS[t.priority] || '#9ca3af') : '';
+  const sla = t.sla ? `<span class="sla" title="SLA">⏰ ${escapeHtml(t.sla)}</span>` : '';
+  const src = t.source ? `<span class="src" title="source">↳ ${escapeHtml(t.source)}</span>` : '';
+  return `<article class="card" data-id="${escapeHtml(t.id)}">
+    <header><span class="tid">#${escapeHtml(t.id)}</span>${typeBadge}${priBadge}</header>
+    <h3>${escapeHtml(t.title)}</h3>
+    <footer>${sla}${src}</footer>
+  </article>`;
+};
+
+const LANE_META = {
+  backlog:    { title: 'Backlog',    icon: '📋', tone: 'lane-backlog' },
+  working:    { title: 'Working',    icon: '🔵', tone: 'lane-working' },
+  testing:    { title: 'Testing',    icon: '🟡', tone: 'lane-testing' },
+  conclusion: { title: 'Concluded',  icon: '✅', tone: 'lane-conclusion' },
+};
+
+const renderLane = (lane, tickets) => {
+  const meta = LANE_META[lane];
+  const items = tickets.length
+    ? tickets.map(renderCard).join('')
+    : `<div class="empty">— empty —</div>`;
+  return `<section class="lane ${meta.tone}">
+    <header><span class="lane-icon">${meta.icon}</span><h2>${meta.title}</h2><span class="lane-count">${tickets.length}</span></header>
+    <div class="lane-body">${items}</div>
+  </section>`;
+};
+
+const renderAdrs = (adrs) => {
+  if (!adrs.length) return '<p class="empty">No ADRs yet.</p>';
+  return adrs.slice(0, 12).map((a) => {
+    const statusColor = ADR_STATUS_COLORS[a.status?.split(/[\s(]/)[0]] || '#9ca3af';
+    return `<article class="adr"><header>
+      <span class="adr-num">ADR-${escapeHtml(a.number)}</span>
+      ${renderBadge(a.status?.split('(')[0].trim() || '?', statusColor)}
+      <span class="adr-date">${escapeHtml(a.date)}</span>
+    </header><h4>${escapeHtml(a.title)}</h4></article>`;
+  }).join('');
+};
+
+const renderSessions = (sessions) => {
+  if (!sessions.length) return '<p class="empty">No sessions logged yet.</p>';
+  return sessions.map((s) => `<article class="session">
+    <header><span class="sess-num">Session ${escapeHtml(s.number)}</span><span class="sess-date">${escapeHtml(s.date)}</span></header>
+    <h4>${escapeHtml(s.title)}</h4>
+    <footer>${s.branch ? `<code>${escapeHtml(s.branch)}</code>` : ''}</footer>
+  </article>`).join('');
+};
+
+const renderMarkdownLight = (md) => {
+  if (!md) return '';
+  return escapeHtml(md)
+    .replace(/^### (.+)$/gm, '<h4>$1</h4>')
+    .replace(/^## (.+)$/gm, '<h3>$1</h3>')
+    .replace(/^# (.+)$/gm, '<h2>$1</h2>')
+    .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+    .replace(/`([^`]+)`/g, '<code>$1</code>')
+    .replace(/^- (.+)$/gm, '<li>$1</li>')
+    .replace(/(<li>.*?<\/li>\n?)+/gs, (m) => `<ul>${m}</ul>`)
+    .replace(/\n\n/g, '</p><p>')
+    .replace(/^(?!<)/gm, '');
+};
+
+/**
+ * Render the full HTML document for a dashboard data object.
+ *
+ * @param {object} data         from buildDashboardData()
+ * @param {object} [opts]
+ * @param {boolean} [opts.live] when true, append the SSE client script
+ * @returns {string}            self-contained HTML
+ */
+export function renderDashboardHTML(data, opts = {}) {
+  const live = !!opts.live;
+  const indicator = live
+    ? `<span class="live-pill" id="live-pill"><span class="dot"></span>live</span>`
+    : `<span class="snap-pill">snapshot · ${fmtTime(data.meta.generatedAt)}</span>`;
+  const liveScript = live ? `<script>${CLIENT_JS}</script>` : '';
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(data.meta.project)} — ContextDevKit dashboard</title>
+<style>${CSS}</style>
+</head><body>
+<header class="topbar">
+  <div class="brand"><strong>${escapeHtml(data.meta.project)}</strong><span class="muted">·</span><code>${escapeHtml(data.meta.branch || '?')}</code><span class="muted">·</span>L${data.meta.level ?? '?'}</div>
+  ${indicator}
+</header>
+<main>
+  <section class="counts">
+    ${Object.entries(data.counts).map(([k, v]) => `<div class="count ${LANE_META[k].tone}"><span class="n">${v}</span><span class="l">${LANE_META[k].title}</span></div>`).join('')}
+  </section>
+  <section class="pipeline" id="pipeline">
+    ${['backlog', 'working', 'testing', 'conclusion'].map((l) => renderLane(l, data.pipeline[l])).join('')}
+  </section>
+  <section class="two-col">
+    <div><h2>Recent ADRs</h2><div class="adrs" id="adrs">${renderAdrs(data.adrs)}</div></div>
+    <div><h2>Recent sessions</h2><div class="sessions" id="sessions">${renderSessions(data.sessions)}</div></div>
+  </section>
+  <details class="block"><summary><h2>CHANGELOG · [Unreleased]</h2></summary><div class="md" id="changelog">${renderMarkdownLight(data.changelogUnreleased)}</div></details>
+  ${data.roadmap.exists ? `<details class="block"><summary><h2>Roadmap</h2></summary><div class="md" id="roadmap">${renderMarkdownLight(data.roadmap.markdown)}</div></details>` : ''}
+</main>
+<footer class="footnote">ContextDevKit · ${escapeHtml(data.meta.platformDir)}/ · generated ${fmtTime(data.meta.generatedAt)}</footer>
+${liveScript}
+</body></html>`;
+}
+
+const CSS = `
+:root { color-scheme: light dark; --bg:#fff; --fg:#1f2328; --muted:#7a8497; --card:#f6f7f9; --border:#e1e4e8; --accent:#5046e5; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0c0c10; --fg:#e4e6eb; --muted:#9ca3af; --card:#16161c; --border:#2a2a33; } }
+* { box-sizing: border-box; } body { margin:0; font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",system-ui,sans-serif; background:var(--bg); color:var(--fg); }
+.topbar { display:flex; align-items:center; justify-content:space-between; padding:14px 24px; border-bottom:1px solid var(--border); position:sticky; top:0; background:var(--bg); z-index:10; }
+.brand { display:flex; gap:8px; align-items:center; } .brand code { font:12px/1 ui-monospace,Menlo,monospace; padding:3px 6px; border:1px solid var(--border); border-radius:4px; }
+.muted { color:var(--muted); } .live-pill { display:inline-flex; align-items:center; gap:6px; padding:4px 10px; border-radius:12px; background:#10b981; color:#fff; font-weight:600; font-size:12px; }
+.live-pill .dot { width:8px; height:8px; background:#fff; border-radius:50%; animation: pulse 2s infinite; }
+.live-pill.stale { background:#e3413c; } .snap-pill { font-size:12px; color:var(--muted); }
+@keyframes pulse { 0%,100% { opacity:1 } 50% { opacity:.4 } }
+main { max-width: 1600px; margin: 0 auto; padding: 24px; }
+.counts { display:grid; grid-template-columns: repeat(4, 1fr); gap:12px; margin-bottom:24px; }
+.count { padding:14px; border-radius:8px; background:var(--card); border:1px solid var(--border); display:flex; justify-content:space-between; align-items:baseline; }
+.count .n { font-size:28px; font-weight:700; } .count .l { color:var(--muted); }
+.pipeline { display:grid; grid-template-columns: repeat(4, minmax(220px, 1fr)); gap:14px; margin-bottom:32px; }
+@media (max-width:1100px) { .pipeline { grid-template-columns: repeat(2, 1fr); } } @media (max-width:680px) { .pipeline { grid-template-columns: 1fr; } }
+.lane { background:var(--card); border:1px solid var(--border); border-radius:8px; display:flex; flex-direction:column; min-height:200px; }
+.lane > header { display:flex; align-items:center; gap:8px; padding:12px 14px; border-bottom:1px solid var(--border); }
+.lane > header h2 { font-size:13px; font-weight:600; text-transform:uppercase; letter-spacing:.5px; margin:0; flex:1; }
+.lane-count { background:var(--bg); border:1px solid var(--border); padding:1px 8px; border-radius:10px; font-size:11px; font-weight:600; }
+.lane-body { padding:8px; display:flex; flex-direction:column; gap:8px; flex:1; }
+.lane-backlog > header { color:#7a8497; } .lane-working > header { color:#3b6ef0; }
+.lane-testing > header { color:#f59e0b; } .lane-conclusion > header { color:#10b981; }
+.card { background:var(--bg); border:1px solid var(--border); border-radius:6px; padding:10px; transition: transform .1s ease, box-shadow .1s ease; }
+.card:hover { transform: translateY(-1px); box-shadow: 0 2px 8px rgba(0,0,0,.08); border-color:var(--accent); }
+.card header { display:flex; gap:6px; align-items:center; margin-bottom:6px; }
+.card .tid { font:11px/1 ui-monospace,Menlo,monospace; color:var(--muted); margin-right:auto; }
+.card h3 { font-size:13px; font-weight:600; margin:0; line-height:1.35; }
+.card footer { display:flex; flex-direction:column; gap:2px; margin-top:6px; font-size:11px; color:var(--muted); }
+.badge { display:inline-block; padding:1px 7px; border-radius:8px; color:#fff; font-size:10px; font-weight:600; letter-spacing:.3px; text-transform:uppercase; }
+.empty { color:var(--muted); font-style:italic; padding:12px; text-align:center; font-size:12px; }
+.two-col { display:grid; grid-template-columns: 1fr 1fr; gap:24px; margin-bottom:24px; } @media (max-width:900px) { .two-col { grid-template-columns: 1fr; } }
+.two-col h2 { font-size:14px; font-weight:600; text-transform:uppercase; letter-spacing:.5px; color:var(--muted); margin:0 0 10px; }
+.adrs, .sessions { display:flex; flex-direction:column; gap:8px; }
+.adr, .session { background:var(--card); border:1px solid var(--border); border-radius:6px; padding:10px 12px; }
+.adr header, .session header { display:flex; gap:8px; align-items:center; margin-bottom:4px; }
+.adr-num, .sess-num { font:11px/1 ui-monospace,Menlo,monospace; font-weight:600; }
+.adr-date, .sess-date { font-size:11px; color:var(--muted); margin-left:auto; }
+.adr h4, .session h4 { font-size:13px; margin:0; font-weight:500; line-height:1.35; }
+.session footer { margin-top:4px; font-size:11px; }
+.block { background:var(--card); border:1px solid var(--border); border-radius:8px; padding:0 16px; margin-bottom:16px; }
+.block summary { cursor:pointer; padding:14px 0; list-style:none; }
+.block summary h2 { display:inline; font-size:14px; font-weight:600; text-transform:uppercase; letter-spacing:.5px; color:var(--muted); margin:0; }
+.block summary::before { content:'▸ '; color:var(--muted); } .block[open] summary::before { content:'▾ '; }
+.md { padding-bottom:16px; } .md h3 { font-size:13px; text-transform:uppercase; letter-spacing:.5px; color:var(--muted); margin:14px 0 4px; }
+.md ul { padding-left:20px; margin:6px 0; } .md code { background:var(--bg); border:1px solid var(--border); padding:1px 4px; border-radius:3px; font:12px ui-monospace,Menlo,monospace; }
+.footnote { text-align:center; padding:24px; font-size:11px; color:var(--muted); }
+`;
+
+const CLIENT_JS = `
+const pill = document.getElementById('live-pill');
+const renderLane = (l, items) => items.length ? items.map(t => \`<article class="card"><header><span class="tid">#\${t.id}</span></header><h3>\${t.title}</h3></article>\`).join('') : '<div class="empty">— empty —</div>';
+function applyData(d) {
+  for (const lane of ['backlog','working','testing','conclusion']) {
+    const sel = document.querySelector('.lane-' + lane + ' .lane-body');
+    const cnt = document.querySelector('.lane-' + lane + ' .lane-count');
+    if (sel && d.pipeline[lane]) sel.innerHTML = renderLane(lane, d.pipeline[lane]);
+    if (cnt) cnt.textContent = d.pipeline[lane].length;
+  }
+  for (const [k, v] of Object.entries(d.counts || {})) {
+    const el = document.querySelector('.count.lane-' + k + ' .n'); if (el) el.textContent = v;
+  }
+}
+function connect() {
+  const ev = new EventSource('/events');
+  ev.onopen = () => { if (pill) { pill.classList.remove('stale'); } };
+  ev.onerror = () => { if (pill) { pill.classList.add('stale'); } ev.close(); setTimeout(connect, 1500); };
+  ev.onmessage = (e) => { try { applyData(JSON.parse(e.data)); } catch {} };
+}
+connect();
+`;

package/templates/contextkit/tools/scripts/dashboard-server.mjs

@@ -0,0 +1,129 @@
+/**
+ * Dashboard live server (`--watch` mode) — ticket 051.
+ *
+ * Spawns a tiny `node:http` server bound to 127.0.0.1 only. Two routes:
+ *   GET /         → serves the dashboard HTML with the live-mode client
+ *   GET /events   → text/event-stream that pushes the rebuilt data
+ *                    object whenever a file in the platform dir changes
+ *
+ * Change detection: `fs.watch` on `contextkit/` recursive=true with a
+ * 200 ms debouncer collapsing bursts (e.g. `pipeline.mjs sync`
+ * rewriting indices). A 15 s heartbeat keeps the SSE connection alive
+ * through reverse proxies (not that we proxy — we bind localhost — but
+ * defensive).
+ *
+ * Zero deps. Defensive: any failure logs and continues (rule 2 — never
+ * break the dev loop). Clean shutdown on SIGINT.
+ */
+import { createServer } from 'node:http';
+import { watch as fsWatch } from 'node:fs';
+import { resolve } from 'node:path';
+import { PLATFORM_DIR } from '../../runtime/config/paths.mjs';
+import { buildDashboardData } from './dashboard-data.mjs';
+import { renderDashboardHTML } from './dashboard-html.mjs';
+
+const HEARTBEAT_MS = 15_000;
+const DEBOUNCE_MS = 200;
+const DEFAULT_PORT = 4242;
+
+/**
+ * Resolve the port to bind to (CLI override > env > default).
+ *
+ * @param {string[]} argv  process.argv slice
+ * @returns {number}
+ */
+export function resolvePort(argv = []) {
+  const flag = argv.find((a) => a.startsWith('--port='));
+  if (flag) {
+    const n = Number(flag.slice('--port='.length));
+    if (Number.isInteger(n) && n > 0 && n < 65536) return n;
+  }
+  const env = process.env.CONTEXTDEVKIT_DASHBOARD_PORT;
+  if (env) {
+    const n = Number(env);
+    if (Number.isInteger(n) && n > 0 && n < 65536) return n;
+  }
+  return DEFAULT_PORT;
+}
+
+/**
+ * Start the live dashboard server. Resolves once it is listening.
+ *
+ * @param {object} opts
+ * @param {string} opts.root  project root (absolute)
+ * @param {number} opts.port  port to bind on 127.0.0.1
+ * @returns {Promise<{ close: () => void, port: number }>}
+ */
+export async function startDashboardServer({ root, port }) {
+  const clients = new Set();
+  let cachedData = buildDashboardData(root);
+  let cachedHtml = renderDashboardHTML(cachedData, { live: true });
+  let debounceHandle = null;
+  let watcher = null;
+
+  const broadcast = (payload) => {
+    const line = `data: ${JSON.stringify(payload)}\n\n`;
+    for (const res of clients) {
+      try { res.write(line); } catch { /* socket dead — onClose will clean up */ }
+    }
+  };
+
+  const rebuild = () => {
+    try {
+      cachedData = buildDashboardData(root);
+      cachedHtml = renderDashboardHTML(cachedData, { live: true });
+      broadcast(cachedData);
+    } catch (err) {
+      process.stderr.write(`dashboard: rebuild failed: ${err.message}\n`);
+    }
+  };
+
+  const scheduleRebuild = () => {
+    if (debounceHandle) clearTimeout(debounceHandle);
+    debounceHandle = setTimeout(rebuild, DEBOUNCE_MS);
+  };
+
+  const server = createServer((req, res) => {
+    if (req.url === '/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no',
+      });
+      res.write(`data: ${JSON.stringify(cachedData)}\n\n`);
+      clients.add(res);
+      const heartbeat = setInterval(() => {
+        try { res.write(': hb\n\n'); } catch { /* dead */ }
+      }, HEARTBEAT_MS);
+      req.on('close', () => {
+        clearInterval(heartbeat);
+        clients.delete(res);
+      });
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(cachedHtml);
+  });
+
+  try {
+    watcher = fsWatch(resolve(root, PLATFORM_DIR), { recursive: true }, () => scheduleRebuild());
+  } catch (err) {
+    process.stderr.write(`dashboard: fs.watch failed (recursive may not be supported here): ${err.message}\n`);
+  }
+
+  await new Promise((res, rej) => {
+    server.once('error', rej);
+    server.listen(port, '127.0.0.1', res);
+  });
+
+  return {
+    port: server.address().port,
+    close: () => {
+      try { watcher?.close(); } catch { /* defensive */ }
+      for (const r of clients) { try { r.end(); } catch { /* defensive */ } }
+      clients.clear();
+      server.close();
+    },
+  };
+}

package/templates/contextkit/tools/scripts/dashboard.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * `/dashboard` entry — ticket 051.
+ *
+ * Two modes, one binary:
+ *   node contextkit/tools/scripts/dashboard.mjs                  # snapshot → dashboard.html
+ *   node contextkit/tools/scripts/dashboard.mjs --watch          # live server on :4242
+ *   node contextkit/tools/scripts/dashboard.mjs --watch --port=N # override port
+ *   node contextkit/tools/scripts/dashboard.mjs --out=path.html  # custom snapshot output
+ *
+ * Snapshot mode is offline-friendly: the resulting file is self-contained
+ * (inline CSS + JS, no external assets) and can be opened by double-click.
+ * Live mode binds 127.0.0.1 only — never accessible from the network.
+ *
+ * Zero deps. Defensive (rule 2 — never break the dev loop).
+ */
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildDashboardData } from './dashboard-data.mjs';
+import { renderDashboardHTML } from './dashboard-html.mjs';
+
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(`--${name}`) || argv.includes(`-${name[0]}`);
+const valueFlag = (name) => {
+  const hit = argv.find((a) => a.startsWith(`--${name}=`));
+  return hit ? hit.slice(name.length + 3) : null;
+};
+
+const WANT_HELP = flag('help') || argv.includes('-h');
+const WANT_WATCH = flag('watch');
+const OUT = valueFlag('out') || 'dashboard.html';
+
+const help = () => process.stdout.write(`Usage: dashboard.mjs [--watch] [--port=N] [--out=PATH]
+
+Snapshot mode (default):
+  Writes a self-contained HTML file (default: ./dashboard.html) and exits.
+  Open it in a browser. The file shows the state at the moment of generation.
+
+Live mode (--watch):
+  Spawns a tiny HTTP server on 127.0.0.1:4242 (override with --port=N or
+  $CONTEXTDEVKIT_DASHBOARD_PORT). The page reconnects automatically via SSE
+  and re-renders when files in the platform dir change.
+
+Examples:
+  node contextkit/tools/scripts/dashboard.mjs
+  node contextkit/tools/scripts/dashboard.mjs --watch
+  node contextkit/tools/scripts/dashboard.mjs --watch --port=8080
+  node contextkit/tools/scripts/dashboard.mjs --out=tmp/state.html
+`);
+
+async function runSnapshot(root) {
+  const data = buildDashboardData(root);
+  const html = renderDashboardHTML(data, { live: false });
+  const outPath = resolve(root, OUT);
+  writeFileSync(outPath, html, 'utf-8');
+  process.stdout.write(`📊 dashboard snapshot → ${outPath}\n`);
+  process.stdout.write(`   Open with your file:// viewer or just double-click.\n`);
+}
+
+async function runLive(root) {
+  const { startDashboardServer, resolvePort } = await import('./dashboard-server.mjs');
+  const port = resolvePort(argv);
+  let server;
+  try {
+    server = await startDashboardServer({ root, port });
+  } catch (err) {
+    if (err.code === 'EADDRINUSE') {
+      process.stderr.write(`dashboard: port ${port} is in use — try --port=N or stop the conflicting process.\n`);
+    } else {
+      process.stderr.write(`dashboard: failed to start on port ${port}: ${err.message}\n`);
+    }
+    process.exit(1);
+    return;
+  }
+  const url = `http://127.0.0.1:${server.port}`;
+  process.stdout.write(`📊 dashboard live → ${url}\n`);
+  process.stdout.write(`   Watching ${root}/contextkit/ — Ctrl+C to stop.\n`);
+  const shutdown = () => {
+    process.stdout.write(`\n   dashboard stopped.\n`);
+    server.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+const isMain = (() => {
+  try {
+    const here = new URL(import.meta.url).pathname.toLowerCase();
+    const entry = process.argv[1]
+      ? new URL('file://' + process.argv[1].replace(/\\/g, '/')).pathname.toLowerCase()
+      : '';
+    return here === entry;
+  } catch { return false; }
+})();
+
+if (isMain) {
+  if (WANT_HELP) {
+    help();
+    process.exit(0);
+  }
+  const root = process.cwd();
+  (WANT_WATCH ? runLive(root) : runSnapshot(root)).catch((err) => {
+    process.stderr.write(`dashboard: ${err.message}\n`);
+    process.exit(1);
+  });
+}