@grainulation/harvest 1.0.0

package/lib/server.js

@@ -0,0 +1,494 @@
+#!/usr/bin/env node
+/**
+ * harvest serve -- local HTTP server for the harvest retrospective dashboard
+ *
+ * Sprint analytics: type distribution, evidence quality, velocity, decay alerts.
+ * SSE for live updates. Zero npm dependencies (node:http only).
+ *
+ * Usage:
+ *   harvest serve [--port 9096] [--root /path/to/sprints]
+ */
+
+import { createServer } from 'node:http';
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve, extname, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+// ── Crash handlers ──
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`[${new Date().toISOString()}] FATAL: ${err.stack || err}\n`);
+  process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`[${new Date().toISOString()}] WARN unhandledRejection: ${reason}\n`);
+});
+
+const PUBLIC_DIR = join(__dirname, '..', 'public');
+
+// ── CLI args ──────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+function arg(name, fallback) {
+  const i = args.indexOf(`--${name}`);
+  return i !== -1 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+const PORT = parseInt(arg('port', '9096'), 10);
+const CORS_ORIGIN = arg('cors', null);
+
+// Resolve ROOT: walk up from cwd to find a directory with claims.json
+function resolveRoot(initial) {
+  if (existsSync(join(initial, 'claims.json'))) return initial;
+  let dir = initial;
+  for (let i = 0; i < 5; i++) {
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+    if (existsSync(join(dir, 'claims.json'))) return dir;
+  }
+  return initial; // fall back to original
+}
+const ROOT = resolveRoot(resolve(arg('root', process.cwd())));
+
+// ── Verbose logging ──────────────────────────────────────────────────────────
+
+const verbose = process.argv.includes('--verbose') || process.argv.includes('-v');
+function vlog(...a) {
+  if (!verbose) return;
+  const ts = new Date().toISOString();
+  process.stderr.write(`[${ts}] harvest: ${a.join(' ')}\n`);
+}
+
+// ── Routes manifest ──────────────────────────────────────────────────────────
+
+const ROUTES = [
+  { method: 'GET', path: '/events', description: 'SSE event stream for live updates' },
+  { method: 'GET', path: '/api/sprints', description: 'List discovered sprints with claim counts' },
+  { method: 'GET', path: '/api/analysis/:name', description: 'Full analysis of a single sprint' },
+  { method: 'GET', path: '/api/calibration', description: 'Prediction calibration across all sprints' },
+  { method: 'GET', path: '/api/decay', description: 'Find stale claims needing refresh (?days=N)' },
+  { method: 'GET', path: '/api/dashboard', description: 'Combined analytics dashboard summary' },
+  { method: 'GET', path: '/api/docs', description: 'This API documentation page' },
+];
+
+// ── Load existing CJS modules via createRequire ──────────────────────────────
+
+const { analyze } = require('./analyzer.js');
+const { measureVelocity } = require('./velocity.js');
+const { checkDecay } = require('./decay.js');
+const { calibrate } = require('./calibration.js');
+const { loadSprints: loadDashboardSprints, buildHtml, claimsPaths } = require('./dashboard.js');
+
+// ── Sprint discovery ─────────────────────────────────────────────────────────
+
+function discoverSprints(rootDir) {
+  const sprints = [];
+  if (!existsSync(rootDir)) return sprints;
+
+  // Include root if it has claims.json
+  const directClaims = join(rootDir, 'claims.json');
+  if (existsSync(directClaims)) {
+    sprints.push(loadSingleSprint(rootDir));
+  }
+
+  // Scan subdirectories (two levels deep to catch sprints/<name>/claims.json)
+  try {
+    const entries = readdirSync(rootDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.')) continue;
+      const childDir = join(rootDir, entry.name);
+      const childClaims = join(childDir, 'claims.json');
+      if (existsSync(childClaims)) {
+        sprints.push(loadSingleSprint(childDir));
+      }
+      // Second level: scan subdirectories of this directory
+      try {
+        const subEntries = readdirSync(childDir, { withFileTypes: true });
+        for (const sub of subEntries) {
+          if (!sub.isDirectory()) continue;
+          if (sub.name.startsWith('.')) continue;
+          const subDir = join(childDir, sub.name);
+          const subClaims = join(subDir, 'claims.json');
+          if (existsSync(subClaims)) {
+            sprints.push(loadSingleSprint(subDir));
+          }
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* skip if unreadable */ }
+
+  return sprints;
+}
+
+function loadSingleSprint(dir) {
+  const sprint = {
+    name: basename(dir),
+    dir,
+    claims: [],
+    compilation: null,
+    gitLog: [],
+  };
+
+  const claimsPath = join(dir, 'claims.json');
+  try {
+    const raw = JSON.parse(readFileSync(claimsPath, 'utf8'));
+    sprint.claims = Array.isArray(raw) ? raw : raw.claims || [];
+  } catch { /* skip */ }
+
+  const compilationPath = join(dir, 'compilation.json');
+  if (existsSync(compilationPath)) {
+    try {
+      sprint.compilation = JSON.parse(readFileSync(compilationPath, 'utf8'));
+    } catch { /* skip */ }
+  }
+
+  // Git log for velocity
+  try {
+    const { execSync } = require('node:child_process');
+    sprint.gitLog = execSync(
+      `git log --oneline --format="%H|%ai|%s" -- claims.json`,
+      { cwd: dir, encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim().split('\n').filter(Boolean).map(line => {
+      const [hash, date, ...msg] = line.split('|');
+      return { hash, date, message: msg.join('|') };
+    });
+  } catch {
+    sprint.gitLog = [];
+  }
+
+  return sprint;
+}
+
+// ── State ─────────────────────────────────────────────────────────────────────
+
+let state = {
+  sprints: [],
+  lastRefresh: null,
+};
+
+const sseClients = new Set();
+
+function broadcast(event) {
+  const data = `data: ${JSON.stringify(event)}\n\n`;
+  for (const res of sseClients) {
+    try { res.write(data); } catch { sseClients.delete(res); }
+  }
+}
+
+function refreshState() {
+  state.sprints = discoverSprints(ROOT);
+  state.lastRefresh = new Date().toISOString();
+  broadcast({ type: 'state', data: { sprintCount: state.sprints.length, lastRefresh: state.lastRefresh } });
+}
+
+// ── MIME types ────────────────────────────────────────────────────────────────
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function jsonResponse(res, code, data) {
+  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(JSON.stringify(data));
+}
+
+// ── SSE live-reload injection ────────────────────────────────────────────────
+
+const SSE_SCRIPT = `
+<script>
+(function() {
+  var es, retryCount = 0;
+  var dot = document.getElementById('statusDot');
+  function connect() {
+    es = new EventSource('/events');
+    es.addEventListener('update', function() { location.reload(); });
+    es.onopen = function() {
+      retryCount = 0;
+      if (dot) dot.className = 'status-dot ok';
+      if (window._grainSetState) window._grainSetState('idle');
+    };
+    es.onerror = function() {
+      es.close();
+      if (dot) dot.className = 'status-dot';
+      if (window._grainSetState) window._grainSetState('orbit');
+      var delay = Math.min(30000, 1000 * Math.pow(2, retryCount)) + Math.random() * 1000;
+      retryCount++;
+      setTimeout(connect, delay);
+    };
+  }
+  connect();
+})();
+</script>`;
+
+function injectSSE(html) {
+  return html.replace('</body>', SSE_SCRIPT + '\n</body>');
+}
+
+// ── HTTP server ───────────────────────────────────────────────────────────────
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+
+  // CORS (only when --cors is passed)
+  if (CORS_ORIGIN) {
+    res.setHeader('Access-Control-Allow-Origin', CORS_ORIGIN);
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+  }
+
+  if (req.method === 'OPTIONS' && CORS_ORIGIN) {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  vlog('request', req.method, url.pathname);
+
+  // ── API: docs ──
+  if (req.method === 'GET' && url.pathname === '/api/docs') {
+    const html = `<!DOCTYPE html><html><head><title>harvest API</title>
+<style>body{font-family:system-ui;background:#0a0e1a;color:#e8ecf1;max-width:800px;margin:40px auto;padding:0 20px}
+table{width:100%;border-collapse:collapse}th,td{padding:8px 12px;border-bottom:1px solid #1e293b;text-align:left}
+th{color:#9ca3af}code{background:#1e293b;padding:2px 6px;border-radius:4px;font-size:13px}</style></head>
+<body><h1>harvest API</h1><p>${ROUTES.length} endpoints</p>
+<table><tr><th>Method</th><th>Path</th><th>Description</th></tr>
+${ROUTES.map(r => '<tr><td><code>'+r.method+'</code></td><td><code>'+r.path+'</code></td><td>'+r.description+'</td></tr>').join('')}
+</table></body></html>`;
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+    return;
+  }
+
+  // ── SSE endpoint ──
+  if (req.method === 'GET' && url.pathname === '/events') {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    });
+    res.write(`data: ${JSON.stringify({ type: 'state', data: { sprintCount: state.sprints.length, lastRefresh: state.lastRefresh } })}\n\n`);
+    const heartbeat = setInterval(() => {
+      try { res.write(': heartbeat\n\n'); } catch { clearInterval(heartbeat); }
+    }, 15000);
+    sseClients.add(res);
+    vlog('sse', `client connected (${sseClients.size} total)`);
+    req.on('close', () => { clearInterval(heartbeat); sseClients.delete(res); vlog('sse', `client disconnected (${sseClients.size} total)`); });
+    return;
+  }
+
+  // ── API: list sprints ──
+  if (req.method === 'GET' && url.pathname === '/api/sprints') {
+    refreshState();
+    const sprintList = state.sprints.map(s => ({
+      name: s.name,
+      dir: s.dir,
+      claimCount: s.claims.length,
+      hasCompilation: !!s.compilation,
+      gitCommits: s.gitLog.length,
+    }));
+    jsonResponse(res, 200, { sprints: sprintList });
+    return;
+  }
+
+  // ── API: full analysis of a sprint ──
+  if (req.method === 'GET' && url.pathname.startsWith('/api/analysis/')) {
+    const sprintName = decodeURIComponent(url.pathname.slice('/api/analysis/'.length));
+    if (!sprintName) { jsonResponse(res, 400, { error: 'missing sprint name' }); return; }
+
+    // Refresh and find the sprint
+    refreshState();
+    const sprint = state.sprints.find(s => s.name === sprintName);
+    if (!sprint) { jsonResponse(res, 404, { error: `sprint "${sprintName}" not found` }); return; }
+
+    const analysis = analyze([sprint]);
+    const velocity = measureVelocity([sprint]);
+
+    jsonResponse(res, 200, {
+      sprint: sprintName,
+      analysis,
+      velocity,
+    });
+    return;
+  }
+
+  // ── API: calibration (all sprints) ──
+  if (req.method === 'GET' && url.pathname === '/api/calibration') {
+    refreshState();
+    if (state.sprints.length === 0) {
+      jsonResponse(res, 200, { calibration: { summary: { totalSprints: 0 }, sprints: [] } });
+      return;
+    }
+    const result = calibrate(state.sprints);
+    jsonResponse(res, 200, { calibration: result });
+    return;
+  }
+
+  // ── API: decay detection ──
+  if (req.method === 'GET' && url.pathname === '/api/decay') {
+    const days = parseInt(url.searchParams.get('days') || '30', 10);
+    refreshState();
+    if (state.sprints.length === 0) {
+      jsonResponse(res, 200, { decay: { summary: { totalClaims: 0 }, stale: [], decaying: [], unresolved: [] } });
+      return;
+    }
+    const result = checkDecay(state.sprints, { thresholdDays: days });
+    jsonResponse(res, 200, { decay: result });
+    return;
+  }
+
+  // ── API: dashboard summary (all sprints combined) ──
+  if (req.method === 'GET' && url.pathname === '/api/dashboard') {
+    refreshState();
+    if (state.sprints.length === 0) {
+      jsonResponse(res, 200, {
+        sprintCount: 0,
+        totalClaims: 0,
+        analysis: null,
+        velocity: null,
+        decay: null,
+      });
+      return;
+    }
+    const analysis = analyze(state.sprints);
+    const velocity = measureVelocity(state.sprints);
+    const decay = checkDecay(state.sprints, { thresholdDays: 30 });
+
+    jsonResponse(res, 200, {
+      sprintCount: state.sprints.length,
+      totalClaims: state.sprints.reduce((a, s) => a + s.claims.length, 0),
+      analysis,
+      velocity,
+      decay,
+    });
+    return;
+  }
+
+  // ── Dashboard UI (template-injected) ──
+  if (req.method === 'GET' && (url.pathname === '/' || url.pathname === '/index.html')) {
+    try {
+      const sprints = loadDashboardSprints(ROOT);
+      if (sprints.length === 0) {
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end('<html><body style="background:#0a0e1a;color:#e2e8f0;font-family:monospace;padding:40px"><h1>No claims.json files found</h1><p>Watching for changes...</p>' + SSE_SCRIPT + '</body></html>');
+        return;
+      }
+      const html = injectSSE(buildHtml(sprints));
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(html);
+    } catch (err) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end('Error building dashboard: ' + err.message);
+    }
+    return;
+  }
+
+  // ── Static files (public/) ──
+  let filePath = url.pathname;
+  filePath = join(PUBLIC_DIR, filePath);
+
+  if (existsSync(filePath) && !statSync(filePath).isDirectory()) {
+    const ext = extname(filePath);
+    const mime = MIME[ext] || 'application/octet-stream';
+    try {
+      const content = readFileSync(filePath);
+      res.writeHead(200, { 'Content-Type': mime });
+      res.end(content);
+    } catch {
+      res.writeHead(500);
+      res.end('read error');
+    }
+    return;
+  }
+
+  // ── 404 ──
+  res.writeHead(404, { 'Content-Type': 'text/plain' });
+  res.end('not found');
+});
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+const shutdown = (signal) => {
+  console.log(`\nharvest: ${signal} received, shutting down...`);
+  for (const res of sseClients) { try { res.end(); } catch {} }
+  sseClients.clear();
+  server.close(() => process.exit(0));
+  setTimeout(() => process.exit(1), 5000);
+};
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+refreshState();
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.error(`\nharvest: port ${PORT} is already in use.`);
+    console.error(`  Try: harvest serve --port ${Number(PORT) + 1}`);
+    console.error(`  Or stop the process using port ${PORT}.\n`);
+    process.exit(1);
+  }
+  throw err;
+});
+
+// ── File watching for live reload ────────────────────────────────────────────
+
+import { watch as fsWatch } from 'node:fs';
+
+const watchers = [];
+let debounceTimer = null;
+
+function onClaimsChange() {
+  if (debounceTimer) clearTimeout(debounceTimer);
+  debounceTimer = setTimeout(() => {
+    refreshState();
+    // Send update event so SSE clients reload
+    const updateData = `event: update\ndata: ${JSON.stringify({ type: 'update' })}\n\n`;
+    for (const client of sseClients) {
+      try { client.write(updateData); } catch { sseClients.delete(client); }
+    }
+  }, 500);
+}
+
+function watchClaims() {
+  const paths = claimsPaths(ROOT);
+  for (const p of paths) {
+    try {
+      const w = fsWatch(p, { persistent: false }, () => onClaimsChange());
+      watchers.push(w);
+    } catch { /* file may not exist yet */ }
+  }
+  // Watch sprint directories for new claims files
+  for (const dir of [ROOT, join(ROOT, 'sprints'), join(ROOT, 'archive')]) {
+    if (!existsSync(dir)) continue;
+    try {
+      const w = fsWatch(dir, { persistent: false }, (_, filename) => {
+        if (filename && (filename === 'claims.json' || filename.includes('claims'))) {
+          onClaimsChange();
+        }
+      });
+      watchers.push(w);
+    } catch { /* ignore */ }
+  }
+}
+
+server.listen(PORT, '127.0.0.1', () => {
+  vlog('listen', `port=${PORT}`, `root=${ROOT}`);
+  console.log(`harvest: serving on http://localhost:${PORT}`);
+  console.log(`  sprints: ${state.sprints.length} found`);
+  console.log(`  root:    ${ROOT}`);
+  watchClaims();
+});
+
+export { server, PORT };

package/lib/templates.js

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * harvest -> barn edge: template discovery for report formatting.
+ *
+ * If barn is available (filesystem or HTTP), harvest can offer its
+ * templates as alternative report formats. Graceful fallback to
+ * harvest's built-in formatting when barn is not reachable.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+
+const BARN_PORT = 9093;
+const BARN_SIBLINGS = [
+  path.join(__dirname, '..', '..', 'barn', 'templates'),
+  path.join(__dirname, '..', '..', '..', 'barn', 'templates'),
+];
+
+/**
+ * Probe barn via filesystem (sibling checkout) or localhost API.
+ * Returns { available: true, templates: [...] } or { available: false }.
+ */
+function discoverTemplates() {
+  // Strategy 1: filesystem sibling
+  for (const dir of BARN_SIBLINGS) {
+    if (fs.existsSync(dir)) {
+      try {
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.html'));
+        const templates = files.map(f => {
+          const content = fs.readFileSync(path.join(dir, f), 'utf8');
+          const placeholders = [...new Set(content.match(/\{\{[A-Z_]+\}\}/g) || [])];
+          const commentMatch = content.match(/<!--\s*(.*?)\s*-->/);
+          return {
+            name: f.replace('.html', ''),
+            placeholders,
+            description: commentMatch ? commentMatch[1] : '',
+            source: 'filesystem',
+          };
+        });
+        return { available: true, templates, source: dir };
+      } catch {
+        continue;
+      }
+    }
+  }
+  return { available: false, templates: [] };
+}
+
+/**
+ * Async probe: try barn's HTTP API for template list.
+ * Falls back to filesystem discovery if the server is not running.
+ */
+function discoverTemplatesAsync() {
+  return new Promise((resolve) => {
+    const req = http.get(`http://127.0.0.1:${BARN_PORT}/api/state`, { timeout: 2000 }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        try {
+          const state = JSON.parse(body);
+          const templates = (state.templates || []).map(t => ({
+            name: t.name,
+            placeholders: t.placeholders || [],
+            description: t.description || '',
+            source: 'http',
+          }));
+          resolve({ available: true, templates, source: `http://127.0.0.1:${BARN_PORT}` });
+        } catch {
+          resolve(discoverTemplates());
+        }
+      });
+    });
+    req.on('error', () => resolve(discoverTemplates()));
+    req.on('timeout', () => { req.destroy(); resolve(discoverTemplates()); });
+  });
+}
+
+module.exports = { discoverTemplates, discoverTemplatesAsync, BARN_PORT };