@grainulation/barn 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.0.0
+
+Initial release.
+
+- 17 built-in HTML templates (brief, explainer, dashboard, slide-deck, RFC, ADR, and more)
+- Web template browser with tag filtering, source/preview/info tabs
+- `detect-sprints` tool for finding active wheat sprints across repos
+- `generate-manifest` for building wheat-manifest.json
+- `build-pdf` for Markdown-to-PDF conversion
+- SSE live-reload when templates change
+- Zero runtime dependencies

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grainulation contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# barn
+
+Open tools for structured research. Use with wheat, or use standalone.
+
+Barn extracts the reusable utilities from the [wheat](https://github.com/grainulation/wheat) research sprint system into a standalone package. Zero npm dependencies -- Node built-in only.
+
+## Install
+
+```bash
+npm install @grainulation/barn
+```
+
+Or use directly:
+
+```bash
+npx @grainulation/barn detect-sprints --json
+```
+
+## Tools
+
+### detect-sprints
+
+Find sprint directories in a repo by scanning for `claims.json` files. Uses git history to determine which sprint is active.
+
+```bash
+barn detect-sprints              # Human-readable output
+barn detect-sprints --json       # Machine-readable JSON
+barn detect-sprints --active     # Print only the active sprint path
+barn detect-sprints --root /path # Scan a specific directory
+```
+
+### generate-manifest
+
+Build a `wheat-manifest.json` topic map from claims, files, and git history. Gives AI tools (and humans) a single file that describes the entire sprint state.
+
+```bash
+barn generate-manifest                        # Write wheat-manifest.json
+barn generate-manifest --root /path           # Target a specific repo
+barn generate-manifest --out custom-name.json # Custom output path
+```
+
+### build-pdf
+
+Convert markdown to PDF via `md-to-pdf` (invoked through npx -- no local install needed).
+
+```bash
+barn build-pdf output/brief.md
+```
+
+## Templates
+
+HTML templates for sprint artifacts. Self-contained (inline CSS/JS, no external deps), dark theme, mobile responsive.
+
+- **adr.html** -- Architecture Decision Record
+- **brief.html** -- Sprint brief / recommendation document
+- **certificate.html** -- Compilation certificate
+- **changelog.html** -- Sprint changelog
+- **comparison.html** -- Side-by-side comparison dashboard
+- **conflict-map.html** -- Claim conflict visualization
+- **dashboard.html** -- Sprint status dashboard
+- **email-digest.html** -- Email digest summary
+- **evidence-matrix.html** -- Evidence tier matrix
+- **explainer.html** -- Full-screen scroll-snap presentation
+- **handoff.html** -- Knowledge transfer document
+- **one-pager.html** -- Single-page executive summary
+- **postmortem.html** -- Sprint postmortem
+- **rfc.html** -- Request for Comments
+- **risk-register.html** -- Risk tracking register
+- **slide-deck.html** -- Slide deck presentation
+- **wiki-page.html** -- Wiki-style documentation page
+
+Copy templates into your project:
+
+```bash
+cp node_modules/@grainulation/barn/templates/explainer.html ./output/
+```
+
+## Philosophy
+
+- Zero npm dependencies. Node built-in modules only.
+- Git as the source of truth. No config files for state that git already knows.
+- Self-describing structures. New sessions understand the repo without full scans.
+- Works with AI search tools (Glob, Grep, Read) out of the box.
+
+## License
+
+MIT

package/bin/barn.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * barn — CLI for grainulation/barn tools
+ *
+ * Usage:
+ *   barn <command> [options]
+ *
+ * Commands:
+ *   detect-sprints    Find sprint directories in a repo
+ *   generate-manifest Build wheat-manifest.json topic map
+ *   build-pdf         Convert markdown to PDF via npx md-to-pdf
+ *   help              Show this help message
+ *
+ * Zero npm dependencies (Node built-in only).
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { fork } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOLS_DIR = join(__dirname, '..', 'tools');
+
+const LIB_DIR = join(__dirname, '..', 'lib');
+
+// ── --version / -v ───────────────────────────────────────────────────────────
+import { readFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === '--version' || command === '-v') {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const verbose = process.argv.includes('--verbose');
+function vlog(...a) {
+  if (!verbose) return;
+  const ts = new Date().toISOString();
+  process.stderr.write(`[${ts}] barn: ${a.join(' ')}\n`);
+}
+export { vlog, verbose };
+
+const commands = {
+  'detect-sprints': 'detect-sprints.js',
+  'generate-manifest': 'generate-manifest.js',
+  'build-pdf': 'build-pdf.js',
+};
+
+vlog('startup', `command=${command || '(none)'}`, `cwd=${process.cwd()}`);
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  console.log(`barn — open tools for structured research
+
+Usage:
+  barn <command> [options]
+
+Commands:
+  serve               Start the template browser UI
+  detect-sprints      Find sprint directories in a repo
+  generate-manifest   Build wheat-manifest.json topic map
+  build-pdf <file>    Convert markdown to PDF via npx md-to-pdf
+  help                Show this help message
+
+Examples:
+  barn serve --port 9093 --root /path/to/repo
+  barn detect-sprints --json
+  barn detect-sprints --active
+  barn generate-manifest --root /path/to/repo
+  barn build-pdf output/brief.md
+
+Options:
+  --version, -v   Print version and exit
+  --verbose        Enable verbose logging to stderr
+
+Zero npm dependencies. Node built-in only.
+https://github.com/grainulation/barn`);
+  process.exit(0);
+}
+
+// ── serve command (lib/server.js) ──
+if (command === 'serve') {
+  const serverPath = join(LIB_DIR, 'server.js');
+  const child = fork(serverPath, args.slice(1), { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+  process.on('SIGTERM', () => child.kill('SIGTERM'));
+  process.on('SIGINT', () => child.kill('SIGINT'));
+} else if (commands[command]) {
+  const toolPath = join(TOOLS_DIR, commands[command]);
+  const child = fork(toolPath, args.slice(1), { stdio: 'inherit' });
+  child.on('exit', (code) => process.exit(code ?? 0));
+} else {
+  console.error(`barn: unknown command: ${command}`);
+  console.error(`Run "barn help" for available commands.`);
+  process.exit(1);
+}

package/lib/index.js

@@ -0,0 +1,93 @@
+/**
+ * @grainulation/barn — public API surface
+ *
+ * Exports:
+ *   name, version          — package metadata
+ *   loadTemplates(dir)     — scan a directory for .html templates + .json sidecars
+ *   detectSprints(root)    — git-based sprint detection (re-export)
+ *   generateManifest(opts) — build wheat-manifest.json topic map (re-export)
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+export const name = pkg.name;
+export const version = pkg.version;
+
+/**
+ * Scan a directory for .html templates and optional .json sidecar metadata.
+ * Pure function — no side effects, no logging, no server state.
+ *
+ * @param {string} templatesDir — absolute path to the templates directory
+ * @returns {Array<object>} — array of template metadata objects
+ */
+export function loadTemplates(templatesDir) {
+  const templates = [];
+  if (!existsSync(templatesDir)) return templates;
+
+  for (const file of readdirSync(templatesDir)) {
+    if (!file.endsWith('.html')) continue;
+    const filePath = join(templatesDir, file);
+    const content = readFileSync(filePath, 'utf8');
+    const tplName = file.replace('.html', '');
+
+    // Extract placeholders
+    const placeholders = [...new Set(content.match(/\{\{[A-Z_]+\}\}/g) || [])];
+
+    // Extract description from first comment
+    const commentMatch = content.match(/<!--\s*(.*?)\s*-->/);
+    let description = commentMatch ? commentMatch[1] : '';
+
+    // Count lines and size
+    const lines = content.split('\n').length;
+    const size = statSync(filePath).size;
+
+    // Detect features
+    const features = [];
+    if (content.includes('scroll-snap')) features.push('scroll-snap');
+    if (content.includes('@media')) features.push('responsive');
+    if (content.includes('var(--')) features.push('css-variables');
+    if (content.includes('<table')) features.push('tables');
+    if (content.includes('.card')) features.push('cards');
+    if (content.includes('.slide')) features.push('slides');
+
+    // Merge optional template.json metadata
+    const metaPath = join(templatesDir, tplName + '.json');
+    let title = tplName;
+    let tags = [];
+    let author = '';
+    let tplVersion = '';
+    let exportPresets = [];
+    let seedPacks = [];
+    let scaffoldConfig = null;
+    if (existsSync(metaPath)) {
+      try {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf8'));
+        if (meta.title) title = meta.title;
+        if (meta.description) description = meta.description;
+        if (Array.isArray(meta.tags)) tags = meta.tags;
+        if (meta.author) author = meta.author;
+        if (meta.version) tplVersion = meta.version;
+        if (Array.isArray(meta.exportPresets)) exportPresets = meta.exportPresets;
+        if (Array.isArray(meta.seedPacks)) seedPacks = meta.seedPacks;
+        if (meta.scaffoldConfig && typeof meta.scaffoldConfig === 'object') scaffoldConfig = meta.scaffoldConfig;
+      } catch {
+        // skip malformed sidecar
+      }
+    }
+
+    templates.push({
+      name: tplName, file, title, placeholders, description, lines, size,
+      features, tags, author, version: tplVersion, exportPresets, seedPacks, scaffoldConfig,
+    });
+  }
+  return templates;
+}
+
+// Re-export tools
+export { detectSprints } from '../tools/detect-sprints.js';
+export { generateManifest } from '../tools/generate-manifest.js';

package/lib/server.js

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+/**
+ * barn serve — local HTTP server for the barn UI
+ *
+ * Two-column template browser with sprint auto-detection.
+ * SSE for live updates, POST endpoints for actions.
+ * Zero npm dependencies (node:http only).
+ *
+ * Usage:
+ *   barn serve [--port 9093] [--root /path/to/repo]
+ */
+
+import { createServer } from 'node:http';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { readFile, stat, readdir } from 'node:fs/promises';
+import { join, resolve, extname, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { loadTemplates as _loadTemplates } from './index.js';
+
+const __dirname = dirname(fileURLToPath(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 PKG = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+const PUBLIC_DIR = join(__dirname, '..', 'public');
+const TEMPLATES_DIR = join(__dirname, '..', 'templates');
+const TOOLS_DIR = join(__dirname, '..', 'tools');
+
+// ── 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', '9093'), 10);
+const ROOT = resolve(arg('root', process.cwd()));
+const CORS_ORIGIN = arg('cors', null);
+
+// ── 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}] barn: ${a.join(' ')}\n`);
+}
+
+// ── Routes manifest ──────────────────────────────────────────────────────────
+
+const ROUTES = [
+  { method: 'GET', path: '/health', description: 'Health check (tool, version, port, uptime)' },
+  { method: 'GET', path: '/events', description: 'SSE event stream for live updates' },
+  { method: 'GET', path: '/api/state', description: 'Current state (templates, sprints, manifest)' },
+  { method: 'GET', path: '/api/template', description: 'Template content by ?name parameter' },
+  { method: 'GET', path: '/api/search', description: 'Search templates by ?q=<query> (name, description, placeholders, features)' },
+  { method: 'POST', path: '/api/refresh', description: 'Refresh state from disk' },
+  { method: 'GET', path: '/api/docs', description: 'This API documentation page' },
+];
+
+// ── State ─────────────────────────────────────────────────────────────────────
+
+let state = {
+  templates: [],
+  sprints: [],
+  activeSprint: null,
+  manifest: 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); }
+  }
+}
+
+// ── Data loading ──────────────────────────────────────────────────────────────
+
+function loadTemplates() {
+  vlog('read', TEMPLATES_DIR);
+  return _loadTemplates(TEMPLATES_DIR);
+}
+
+function loadSprints() {
+  const mod = join(TOOLS_DIR, 'detect-sprints.js');
+  if (!existsSync(mod)) return Promise.resolve({ sprints: [], active: null });
+
+  return new Promise((resolve) => {
+    execFile('node', [mod, '--json', '--root', ROOT], {
+      timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'],
+    }, (err, stdout) => {
+      if (err) { resolve({ sprints: [], active: null }); return; }
+      try {
+        const data = JSON.parse(stdout);
+        resolve({
+          sprints: data.sprints || [],
+          active: (data.sprints || []).find(s => s.status === 'active') || null,
+        });
+      } catch {
+        resolve({ sprints: [], active: null });
+      }
+    });
+  });
+}
+
+function loadManifest() {
+  const manifestPath = join(ROOT, 'wheat-manifest.json');
+  if (!existsSync(manifestPath)) return null;
+  try {
+    return JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+let refreshPending = null;
+async function refreshState() {
+  if (refreshPending) return refreshPending;
+  refreshPending = (async () => {
+    state.templates = await loadTemplates();
+    const sprintData = await loadSprints();
+    state.sprints = sprintData.sprints;
+    state.activeSprint = sprintData.active;
+    state.manifest = loadManifest();
+    broadcast({ type: 'state', data: state });
+  })();
+  try { return await refreshPending; } finally { refreshPending = null; }
+}
+
+// ── 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',
+};
+
+// ── HTTP server ───────────────────────────────────────────────────────────────
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${PORT}`);
+
+  // CORS headers (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);
+
+  // ── Health check ──
+  if (req.method === 'GET' && url.pathname === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ tool: 'barn', version: PKG.version, port: PORT, uptime: process.uptime() }));
+    return;
+  }
+
+  // ── API: docs ──
+  if (req.method === 'GET' && url.pathname === '/api/docs') {
+    const html = `<!DOCTYPE html><html><head><title>barn 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>barn 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: state })}\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: state ──
+  if (req.method === 'GET' && url.pathname === '/api/state') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(state));
+    return;
+  }
+
+  // ── API: search templates ──
+  if (req.method === 'GET' && url.pathname === '/api/search') {
+    const q = (url.searchParams.get('q') || '').toLowerCase().trim();
+    if (!q) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(state.templates));
+      return;
+    }
+    const filtered = state.templates.filter(tpl => {
+      const haystack = [
+        tpl.name,
+        tpl.title,
+        tpl.description,
+        ...tpl.placeholders,
+        ...tpl.features,
+        ...tpl.tags,
+      ].join(' ').toLowerCase();
+      return haystack.includes(q);
+    });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(filtered));
+    return;
+  }
+
+  // ── API: template content ──
+  if (req.method === 'GET' && url.pathname === '/api/template') {
+    const name = url.searchParams.get('name');
+    if (!name) { res.writeHead(400); res.end('missing name'); return; }
+    const filePath = resolve(TEMPLATES_DIR, name + '.html');
+    if (!filePath.startsWith(TEMPLATES_DIR)) { res.writeHead(403); res.end('forbidden'); return; }
+    if (!existsSync(filePath)) { res.writeHead(404); res.end('not found'); return; }
+    res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end(readFileSync(filePath, 'utf8'));
+    return;
+  }
+
+  // ── API: refresh ──
+  if (req.method === 'POST' && url.pathname === '/api/refresh') {
+    await refreshState();
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(state));
+    return;
+  }
+
+  // ── Static files ──
+  let filePath = url.pathname === '/' ? '/index.html' : url.pathname;
+
+  // Prevent directory traversal
+  const resolved = resolve(PUBLIC_DIR, '.' + filePath);
+  if (!resolved.startsWith(PUBLIC_DIR)) {
+    res.writeHead(403);
+    res.end('forbidden');
+    return;
+  }
+
+  if (existsSync(resolved) && statSync(resolved).isFile()) {
+    const ext = extname(resolved);
+    res.writeHead(200, { 'Content-Type': MIME[ext] || 'application/octet-stream' });
+    res.end(readFileSync(resolved));
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('not found');
+});
+
+// ── File watching ─────────────────────────────────────────────────────────────
+
+// Build a fingerprint of filenames + mtimes for change detection
+async function dirFingerprint(dir) {
+  if (!existsSync(dir)) return '';
+  const files = await readdir(dir);
+  const parts = [];
+  for (const f of files) {
+    if (!f.endsWith('.html') && !f.endsWith('.json')) continue;
+    try {
+      const s = await stat(join(dir, f));
+      parts.push(`${f}:${s.mtimeMs}`);
+    } catch { /* removed between readdir and stat */ }
+  }
+  return parts.sort().join('|');
+}
+
+async function claimsFingerprint() {
+  const claimsPath = join(ROOT, 'claims.json');
+  try {
+    const s = await stat(claimsPath);
+    return `claims:${s.mtimeMs}`;
+  } catch { return ''; }
+}
+
+let lastTemplatesFP = '';
+let lastClaimsFP = '';
+
+const watchInterval = setInterval(async () => {
+  try {
+    const [tFP, cFP] = await Promise.all([
+      dirFingerprint(TEMPLATES_DIR),
+      claimsFingerprint(),
+    ]);
+    if (tFP !== lastTemplatesFP || cFP !== lastClaimsFP) {
+      lastTemplatesFP = tFP;
+      lastClaimsFP = cFP;
+      await refreshState();
+    }
+  } catch { /* ignore polling errors */ }
+}, 2000);
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+const shutdown = (signal) => {
+  console.log(`\nbarn: ${signal} received, shutting down...`);
+  clearInterval(watchInterval);
+  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 ─────────────────────────────────────────────────────────────────────
+
+await refreshState();
+// Seed fingerprints so the poller doesn't re-trigger immediately
+[lastTemplatesFP, lastClaimsFP] = await Promise.all([
+  dirFingerprint(TEMPLATES_DIR),
+  claimsFingerprint(),
+]);
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.error(`barn: port ${PORT} already in use — try --port <other>`);
+    process.exit(1);
+  }
+  if (err.code === 'EACCES') {
+    console.error(`barn: permission denied for port ${PORT}`);
+    process.exit(1);
+  }
+  throw err;
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  vlog('listen', `port=${PORT}`, `root=${ROOT}`);
+  console.log(`barn: serving on http://localhost:${PORT}`);
+  console.log(`  templates: ${state.templates.length} found`);
+  console.log(`  sprints: ${state.sprints.length} detected`);
+  if (state.activeSprint) {
+    console.log(`  active: ${state.activeSprint.name} (${state.activeSprint.phase})`);
+  }
+  console.log(`  root: ${ROOT}`);
+});