changeledger 0.3.0

package/src/viewer/public/templates.js

@@ -0,0 +1,9 @@
+import { html, nothing, render, svg } from 'lit-html';
+import { unsafeHTML } from 'lit-html/directives/unsafe-html.js';
+import { safeHtml } from './security.js';
+
+export { html, nothing, render, svg };
+
+export function markdownHtml(markdown) {
+  return unsafeHTML(safeHtml(markdown));
+}

package/src/viewer/public/view-parts.js

@@ -0,0 +1,162 @@
+import { cssIdent } from './security.js';
+import { html, markdownHtml, nothing } from './templates.js';
+
+const MARK = { done: '✓', todo: '○', blocked: '✕' };
+
+export const humanizeStatus = (status) => {
+  const text = String(status ?? '').replaceAll('-', ' ');
+  return text ? text[0].toUpperCase() + text.slice(1) : '';
+};
+
+export function statusSummary(statuses) {
+  if (!statuses.size) return 'All statuses';
+  if (statuses.size === 1) return humanizeStatus([...statuses][0]);
+  return `${statuses.size} statuses`;
+}
+
+export function statusTag(status) {
+  return html`<span
+    class="status-tag"
+    style=${`--status-color: var(--status-${cssIdent(status)}, var(--status-muted))`}
+  ><i aria-hidden="true"></i>${humanizeStatus(status)}</span>`;
+}
+
+export function sortIndicator(direction) {
+  const path = direction > 0 ? 'M2.5 6.5 5 4l2.5 2.5' : 'M2.5 3.5 5 6l2.5-2.5';
+  return html`<svg class="sort-indicator" viewBox="0 0 10 10" width="10" height="10" aria-hidden="true">
+    <path d=${path}></path>
+  </svg>`;
+}
+
+export function closeButton(label = 'Close detail', extraClass = '') {
+  return html`<button type="button" class=${`icon-button close ${extraClass}`.trim()} aria-label=${label} title=${label}>
+    <svg viewBox="0 0 16 16" aria-hidden="true">
+      <path d="M3.75 3.75 12.25 12.25M12.25 3.75 3.75 12.25"></path>
+    </svg>
+  </button>`;
+}
+
+export function validationPanel() {
+  return html`<section class="validation-actions" aria-labelledby="validation-title">
+    <div class="validation-copy">
+      <span class="validation-kicker">Human checkpoint</span>
+      <h2 id="validation-title">Ready for your verdict</h2>
+      <p>Test the complete change, then accept it or send it back with a precise reason.</p>
+    </div>
+    <div class="validation-controls">
+      <button type="button" class="button button-primary" data-validation="pass">Accept change</button>
+      <div class="rejection-field">
+        <label for="validation-reason">Reason for rejection</label>
+        <input id="validation-reason" data-validation-reason type="text" placeholder="What still needs work?" />
+        <p class="validation-error" role="alert" hidden></p>
+      </div>
+      <button type="button" class="button button-danger" data-validation="fail">Reject with reason</button>
+    </div>
+  </section>`;
+}
+
+export function splitGraduationHistory(body) {
+  const lines = String(body ?? '').split('\n');
+  let cursor = 0;
+  while (cursor < lines.length && !lines[cursor].trim()) cursor += 1;
+  if (/^#\s+/.test(lines[cursor] ?? '')) {
+    cursor += 1;
+    while (cursor < lines.length && !lines[cursor].trim()) cursor += 1;
+  }
+  const start = cursor;
+  const entries = [];
+  while (/^>\s+Graduado del change\s+/.test(lines[cursor] ?? '')) {
+    entries.push(lines[cursor].replace(/^>\s+/, ''));
+    cursor += 1;
+  }
+  if (!entries.length) return { before: '', entries: [], after: String(body ?? '') };
+  while (cursor < lines.length && !lines[cursor].trim()) cursor += 1;
+  return {
+    before: lines.slice(0, start).join('\n').trim(),
+    entries,
+    after: lines.slice(cursor).join('\n'),
+  };
+}
+
+export function specBody(body) {
+  const { before, entries, after } = splitGraduationHistory(body);
+  if (!entries.length) return html`<div class="stage-content">${markdownHtml(after)}</div>`;
+  return html`<div class="stage-content spec-content">
+    ${before ? markdownHtml(before) : nothing}
+    <details class="graduation-history">
+      <summary>
+        <span class="history-icon" aria-hidden="true">↳</span>
+        <span>Graduation history</span>
+        <span class="history-count">${entries.length}</span>
+      </summary>
+      <ol>${entries.map((entry) => html`<li>${entry}</li>`)}</ol>
+    </details>
+    ${markdownHtml(after)}
+  </div>`;
+}
+
+export function card(c) {
+  const pct = c.progress.total ? Math.round((c.progress.done / c.progress.total) * 100) : 0;
+  const blocked = c.progress.blocked
+    ? html`<span class="flag-blocked">● ${c.progress.blocked} blocked</span>`
+    : nothing;
+  return html`
+    <div
+      class=${`card ${c.archived ? 'archived' : ''}`}
+      data-id=${c.id}
+      style=${`--type-color: var(--${cssIdent(c.type)})`}
+    >
+      <div class="card-top">
+        <span class="card-id">#${c.id}</span>
+        <span class="type-tag">${c.type}</span>
+      </div>
+      <div class="card-title">${c.title}</div>
+      ${c.progress.total ? html`<div class="progress"><i style=${`width:${pct}%`}></i></div>` : nothing}
+      <div class="card-meta">
+        ${c.progress.total ? html`<span>${c.progress.done}/${c.progress.total} tasks</span>` : nothing}
+        ${c.owner ? html`<span class="owner">@${c.owner}</span>` : nothing}
+        ${blocked}
+      </div>
+    </div>`;
+}
+
+export function stageBlock(c, s) {
+  const content = s.key === 'plan' && c.tasks.length ? taskList(c.tasks) : markdownHtml(s.body);
+  return html`
+    <div class="stage" id=${`stage-${s.key}`}>
+      <h2>${s.heading}</h2>
+      <div class="stage-content">${content}</div>
+    </div>`;
+}
+
+export function taskList(tasks) {
+  return html`<ul class="tasks">
+    ${tasks.map((t) => {
+      const cr = (t.criteria || []).map((x) => html`<span class="cr">${x}</span>`);
+      const when = t.resolvedAt ? html`<span class="when">${t.resolvedAt}</span>` : nothing;
+      const reason = t.reason ? html`<span class="reason">— ${t.reason}</span>` : nothing;
+      return html`<li class=${`task ${t.state}`}>
+        <span class="mark">${MARK[t.state]}</span>
+        <span class="text">${t.text} ${cr} ${reason}</span>
+        ${when}
+      </li>`;
+    })}
+  </ul>`;
+}
+
+export function tableRow(c) {
+  const pct = c.progress.total ? Math.round((c.progress.done / c.progress.total) * 100) : 0;
+  const prog = c.progress.total
+    ? `${c.progress.done}/${c.progress.total}${c.progress.blocked ? ` · ${c.progress.blocked}!` : ''} (${pct}%)`
+    : '—';
+  return html`<tr data-id=${c.id}>
+    <td class="mono cell-id cell-nowrap">#${c.id}</td>
+    <td class="cell-title cell-nowrap">${c.title}</td>
+    <td class="cell-type cell-nowrap">
+      <span class="type-tag" style=${`--type-color: var(--${cssIdent(c.type)})`}>${c.type}</span>
+    </td>
+    <td class="cell-status cell-nowrap">${statusTag(c.status)}</td>
+    <td class="mono cell-progress cell-nowrap">${prog}</td>
+    <td class="mono cell-deps">${(c.depends_on || []).join(', ') || '—'}</td>
+  </tr>`;
+}

package/src/viewer/public/view-renderers.js

@@ -0,0 +1,191 @@
+import { cssIdent } from './security.js';
+import { html, nothing, svg } from './templates.js';
+
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+export function graphSvg(changes) {
+  if (!changes.length) {
+    return html`<p class="empty">No changes match the current filters.</p>`;
+  }
+
+  const byId = new Map(changes.map((c) => [String(c.id), c]));
+  const depthCache = new Map();
+  const depth = (id, seen = new Set()) => {
+    if (depthCache.has(id)) return depthCache.get(id);
+    if (seen.has(id)) return 0;
+    const nextSeen = new Set(seen);
+    nextSeen.add(id);
+    const c = byId.get(String(id));
+    const deps = (c?.depends_on || []).filter((d) => byId.has(String(d)));
+    const d = deps.length ? 1 + Math.max(...deps.map((x) => depth(String(x), nextSeen))) : 0;
+    depthCache.set(id, d);
+    return d;
+  };
+
+  const layers = {};
+  for (const c of changes) {
+    const d = depth(String(c.id));
+    layers[d] ||= [];
+    layers[d].push(c);
+  }
+
+  const COL = 230;
+  const ROW = 78;
+  const W = 180;
+  const H = 52;
+  const pos = new Map();
+  for (const [d, items] of Object.entries(layers)) {
+    items.forEach((c, i) => {
+      pos.set(String(c.id), { x: +d * COL + 30, y: i * ROW + 30 });
+    });
+  }
+
+  const width = (Math.max(...Object.keys(layers).map(Number)) + 1) * COL + 60;
+  const height = Math.max(...Object.values(layers).map((l) => l.length)) * ROW + 60;
+
+  const edges = changes
+    .flatMap((c) =>
+      (c.depends_on || [])
+        .filter((d) => pos.has(String(d)))
+        .map((d) => ({ from: pos.get(String(d)), to: pos.get(String(c.id)) })),
+    )
+    .map((e) => {
+      const x1 = e.from.x + W;
+      const y1 = e.from.y + H / 2;
+      const x2 = e.to.x;
+      const y2 = e.to.y + H / 2;
+      const mx = (x1 + x2) / 2;
+      return svg`<path class="edge" d=${`M${x1},${y1} C${mx},${y1} ${mx},${y2} ${x2},${y2}`} />`;
+    });
+
+  const nodes = changes.map((c) => {
+    const p = pos.get(String(c.id));
+    return svg`<g class="node" data-id=${c.id} transform=${`translate(${p.x},${p.y})`}>
+        <rect width=${W} height=${H} stroke=${`var(--${cssIdent(c.type)})`}></rect>
+        <text class="nid" x="10" y="18">#${c.id} · ${c.status}</text>
+        <text x="10" y="36">${clip(c.title, 24)}</text>
+      </g>`;
+  });
+
+  return html`
+    <svg viewBox=${`0 0 ${width} ${height}`} height=${height}>
+      <defs>
+        <marker id="arrow" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
+          <path d="M0,0 L7,3 L0,6 Z" fill="var(--muted)"></path>
+        </marker>
+      </defs>
+      ${edges}${nodes}
+    </svg>`;
+}
+
+export function specsListHtml(specs, fmtDateTime) {
+  return specs.length
+    ? specs.map(
+        (s, i) => html`<div class="spec-card" data-i=${i}>
+          <div class="spec-title">${s.title}</div>
+          <div class="card-meta">
+            <span title=${s.updated || ''}>${fmtDateTime(s.updated)}</span>
+            ${(s.tags || []).map((t) => html`<span class="pill">${t}</span>`)}
+          </div>
+        </div>`,
+      )
+    : html`<p class="empty">No specs yet. Truth graduates here as changes complete.</p>`;
+}
+
+export function fmtDuration(ms) {
+  if (!ms || ms < 0) return '—';
+  const h = ms / 3600000;
+  if (h < 48) return `${h.toFixed(1)} h`;
+  return `${(h / 24).toFixed(1)} d`;
+}
+
+function barRows(items, label, value, fmt = (v) => v) {
+  const max = Math.max(1, ...items.map(value));
+  return items.map(
+    (it) =>
+      html`<div class="bar-row">
+        <span class="bar-date">${label(it)}</span>
+        <span class="bar" style=${`width:${(value(it) / max) * 100}%`}></span>
+        <span class="mono">${fmt(value(it))}</span>
+      </div>`,
+  );
+}
+
+export function metricsHtml(metrics = {}) {
+  const wip = metrics.wip || {};
+  const wipTotal = Object.values(wip).reduce((a, b) => a + b, 0);
+  const cards = [
+    ['Closed', metrics.count ?? 0],
+    ['Avg cycle', fmtDuration(metrics.avgCycleMs)],
+    ['Median cycle', fmtDuration(metrics.medianCycleMs)],
+    ['WIP', wipTotal],
+    ['Blocked time', fmtDuration(metrics.blockedMs)],
+  ].map(
+    ([label, val]) =>
+      html`<div class="metric-card">
+          <div class="metric-val">${val}</div>
+          <div class="metric-label">${label}</div>
+        </div>`,
+  );
+
+  const wipChips = Object.entries(wip).map(([s, n]) => html`<span class="pill">${s}: ${n}</span>`);
+
+  const lead = (metrics.timeInStatus || []).filter((t) => t.avgMs > 0);
+  const leadBars = lead.length
+    ? barRows(
+        lead,
+        (t) => t.state,
+        (t) => t.avgMs,
+        fmtDuration,
+      )
+    : html`<p class="empty">No data yet.</p>`;
+
+  const tp = metrics.throughput || [];
+  const tpBars = tp.length
+    ? barRows(
+        tp,
+        (t) => html`<span class="mono">${t.date}</span>`,
+        (t) => t.count,
+      )
+    : html`<p class="empty">No closed changes yet.</p>`;
+
+  const aging = metrics.aging || [];
+  const agingRows = aging.length
+    ? html`<ul class="git-commits">
+        ${aging.map(
+          (a) =>
+            html`<li><span class="mono">#${a.id}</span> <span class="when">${fmtDuration(a.ms)}</span></li>`,
+        )}
+      </ul>`
+    : html`<p class="empty">Nothing in progress.</p>`;
+
+  const byType = metrics.byType || [];
+  const typeRows = byType.length
+    ? html`<table class="grid">
+        <thead>
+          <tr><th>Type</th><th>Closed</th><th>Avg cycle</th></tr>
+        </thead>
+        <tbody>
+          ${byType.map(
+            (t) => html`<tr>
+              <td><span class="type-tag" style=${`--type-color: var(--${cssIdent(t.type)})`}>${t.type}</span></td>
+              <td class="mono">${t.closed}</td>
+              <td class="mono">${fmtDuration(t.avgCycleMs)}</td>
+            </tr>`,
+          )}
+        </tbody>
+      </table>`
+    : html`<p class="empty">No closed changes yet.</p>`;
+
+  return html`
+    <div class="metrics-cards">${cards}</div>
+    ${wipChips.length ? html`<div class="detail-meta">${wipChips}</div>` : nothing}
+    <h3 class="metrics-h">Avg time in status (lead time per stage)</h3>
+    <div>${leadBars}</div>
+    <h3 class="metrics-h">Throughput (closed per day)</h3>
+    <div>${tpBars}</div>
+    <h3 class="metrics-h">Aging — in progress</h3>
+    ${agingRows}
+    <h3 class="metrics-h">By type</h3>
+    ${typeRows}`;
+}

package/src/viewer/server/router.mjs

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { gitRefs } from '../../git.mjs';
+import { publicDir } from '../../paths.mjs';
+import { loadRepoAsync } from '../../repo.mjs';
+import { changeStatus, resolveProjects, searchProjects, serialize } from '../domain.mjs';
+import { isAuthorizedWrite, isLocalHost } from './security.mjs';
+
+const require = createRequire(import.meta.url);
+
+// Browser builds of the markdown/diagram libs, resolved from node_modules
+// (installed as dependencies) and served under /vendor/*.
+function vendorFile(route) {
+  try {
+    if (route === '/vendor/marked.min.js') {
+      return path.join(path.dirname(require.resolve('marked/package.json')), 'lib/marked.umd.js');
+    }
+    if (route === '/vendor/mermaid.min.js') {
+      return require.resolve('mermaid/dist/mermaid.min.js');
+    }
+    if (route === '/vendor/purify.min.js') {
+      return require.resolve('dompurify/dist/purify.min.js');
+    }
+    if (route.startsWith('/vendor/lit-html/')) {
+      const subpath = route.slice('/vendor/lit-html/'.length);
+      if (subpath === 'lit-html.js') return require.resolve('lit-html');
+      return require.resolve(`lit-html/${subpath}`);
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+};
+
+// Defensive headers for a local-only UI: never sniff types, never cache, and
+// forbid embedding in a frame (clickjacking).
+const SECURITY_HEADERS = {
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Cache-Control': 'no-store',
+};
+
+const MAX_BODY = 64 * 1024; // a status payload is tiny; cap to stay defensive
+
+function send(res, code, type, body) {
+  res.writeHead(code, { 'Content-Type': type, ...SECURITY_HEADERS });
+  res.end(body);
+}
+
+// Injects the per-process write token into the served page so same-origin JS can
+// read it; cross-origin pages cannot, by the same-origin policy.
+function serveIndex(res, token) {
+  const safeToken = JSON.stringify(token).replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+  const html = fs
+    .readFileSync(path.join(publicDir, 'index.html'), 'utf8')
+    .replace("'__CHANGELEDGER_TOKEN_VALUE__'", safeToken);
+  send(res, 200, MIME['.html'], html);
+}
+
+// Builds the HTTP request listener. Exposed (with an injectable token) so the
+// security boundary is testable over real HTTP without opening a browser.
+export function createRequestListener(cwd, localOnly, token) {
+  return async (req, res) => {
+    try {
+      if (!isLocalHost(req)) {
+        send(res, 403, MIME['.json'], JSON.stringify({ error: 'non-local host rejected' }));
+        return;
+      }
+      const url = new URL(req.url, 'http://127.0.0.1');
+      const route = url.pathname;
+      const params = url.searchParams;
+
+      if (req.method === 'POST' && route === '/api/status') {
+        if (!isAuthorizedWrite(req, token)) {
+          send(res, 403, MIME['.json'], JSON.stringify({ error: 'unauthorized write' }));
+          req.destroy();
+          return;
+        }
+        let raw = '';
+        let aborted = false;
+        req.on('data', (chunk) => {
+          if (aborted) return;
+          raw += chunk;
+          if (raw.length > MAX_BODY) {
+            aborted = true;
+            send(res, 413, MIME['.json'], JSON.stringify({ error: 'body too large' }));
+            req.destroy();
+          }
+        });
+        req.on('end', () => {
+          if (aborted) return;
+          let payload;
+          try {
+            payload = JSON.parse(raw || '{}');
+          } catch {
+            send(res, 400, MIME['.json'], JSON.stringify({ error: 'invalid JSON body' }));
+            return;
+          }
+          const { projects } = resolveProjects(cwd, localOnly);
+          const { code, body } = changeStatus(projects, payload);
+          send(res, code, MIME['.json'], JSON.stringify(body));
+        });
+        return;
+      }
+
+      if (route === '/api/projects') {
+        send(res, 200, MIME['.json'], JSON.stringify(resolveProjects(cwd, localOnly)));
+        return;
+      }
+      if (route === '/api/git') {
+        const rawId = params.get('id');
+        if (rawId && !/^[0-9]{8}-[0-9]{6}$/.test(rawId)) {
+          send(res, 400, MIME['.json'], JSON.stringify({ error: 'invalid id' }));
+          return;
+        }
+        const { projects } = resolveProjects(cwd, localOnly);
+        const proj = projects.find((p) => p.id === params.get('project'));
+        if (!proj?.alive) {
+          send(res, 200, MIME['.json'], JSON.stringify({ commits: [], branches: [] }));
+          return;
+        }
+        send(res, 200, MIME['.json'], JSON.stringify(gitRefs(proj.path, rawId)));
+        return;
+      }
+      if (route === '/api/search') {
+        const { projects } = resolveProjects(cwd, localOnly);
+        send(res, 200, MIME['.json'], JSON.stringify(searchProjects(projects, params.get('q'))));
+        return;
+      }
+      if (route === '/api/repo') {
+        const { projects } = resolveProjects(cwd, localOnly);
+        const proj = projects.find((p) => p.id === params.get('project'));
+        if (!proj) {
+          send(res, 404, MIME['.json'], JSON.stringify({ error: 'no project' }));
+          return;
+        }
+        if (!proj.alive) {
+          send(res, 410, MIME['.json'], JSON.stringify({ error: 'project path is gone' }));
+          return;
+        }
+        send(res, 200, MIME['.json'], JSON.stringify(serialize(await loadRepoAsync(proj.path))));
+        return;
+      }
+
+      const vendor = vendorFile(route);
+      if (vendor) {
+        if (fs.existsSync(vendor)) send(res, 200, MIME['.js'], fs.readFileSync(vendor));
+        else send(res, 404, 'text/plain', 'vendor lib not installed');
+        return;
+      }
+
+      if (route === '/' || route === '/index.html') {
+        serveIndex(res, token);
+        return;
+      }
+      const file = staticFile(route);
+      if (file) {
+        send(res, 200, MIME[path.extname(file)] ?? 'text/plain', fs.readFileSync(file));
+      } else {
+        send(res, 404, 'text/plain', 'Not found');
+      }
+    } catch (e) {
+      process.stderr.write(`[changeledger-viewer] ${e.message}\n`);
+      send(res, 500, MIME['.json'], JSON.stringify({ error: 'Internal server error' }));
+    }
+  };
+}
+
+export function staticFile(route) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(route);
+  } catch {
+    return null;
+  }
+  if (decoded.includes('\0')) return null;
+
+  const rel = decoded.replace(/^\/+/, '');
+  const file = path.resolve(publicDir, rel);
+  if (!isInsidePath(publicDir, file)) return null;
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return null;
+
+  const realPublic = fs.realpathSync(publicDir);
+  const realFile = fs.realpathSync(file);
+  if (!isInsidePath(realPublic, realFile)) return null;
+  return file;
+}
+
+function isInsidePath(root, target) {
+  const rel = path.relative(path.resolve(root), path.resolve(target));
+  return rel === '' || (rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}

package/src/viewer/server/security.mjs

@@ -0,0 +1,27 @@
+const LOOPBACK = new Set(['127.0.0.1', '::1', 'localhost']);
+
+// Bare hostname from a Host/Origin authority, dropping the port and IPv6
+// brackets. '' when absent.
+export function hostnameOf(authority) {
+  if (!authority) return '';
+  const m = String(authority).match(/^(\[[^\]]+\]|[^:]+)(?::\d+)?$/);
+  const host = m ? m[1] : authority;
+  return host.replace(/^\[|\]$/g, '');
+}
+
+// The request must be addressed to the loopback host. This (with the loopback
+// bind) defends against DNS-rebinding: a rebinding attack reaches the socket but
+// carries the attacker's domain in Host.
+export function isLocalHost(req) {
+  return LOOPBACK.has(hostnameOf(req.headers.host));
+}
+
+// A write must come from the viewer's own page: a same-origin Origin (when the
+// browser sends one) and the per-process token the page was given. A
+// cross-origin attacker cannot read the token, so it cannot forge the header.
+export function isAuthorizedWrite(req, token) {
+  if (req.headers['x-changeledger-token'] !== token) return false;
+  const origin = req.headers.origin;
+  if (origin && !LOOPBACK.has(hostnameOf(new URL(origin).host))) return false;
+  return true;
+}