buildline 0.0.0-stage → 0.3.0

package/src/install.js

@@ -0,0 +1,280 @@
+// Builds the list of files the factory installs for a given config, and applies
+// it safely (see files.js). Also merges hooks/permissions into .claude/settings.json.
+import fs from 'node:fs';
+import path from 'node:path';
+import { render, templatesDir } from './render.js';
+import { loadManifest, saveManifest, planWrite, applyPlan, planRemove, hash } from './files.js';
+import { modelFor, STATION_SUBAGENTS, CLIS } from './models.js';
+
+export const VERSION = JSON.parse(fs.readFileSync(path.join(templatesDir, '..', 'package.json'), 'utf8')).version;
+
+export const AGENTS = {
+  claude: { label: 'Claude Code', hint: 'skills, subagents, hooks' },
+  codex: { label: 'Codex CLI', hint: 'reads AGENTS.md' },
+  cursor: { label: 'Cursor', hint: '.cursor/rules' },
+  gemini: { label: 'Gemini CLI', hint: 'GEMINI.md' },
+  copilot: { label: 'GitHub Copilot', hint: 'reads AGENTS.md' },
+};
+
+export const AUTONOMY = {
+  1: { label: 'L1 · Assist', hint: 'human approves every station; agent never moves on alone' },
+  2: { label: 'L2 · Guided', hint: 'human approves spec + plan; agent builds, verifies, reviews' },
+  3: { label: 'L3 · Autopilot', hint: 'human approves spec; agent plans and runs build→review unattended' },
+  4: { label: 'L4 · Dark factory', hint: 'spec → ready-to-merge PR with no checkpoints; human merges' },
+};
+
+const STATION_SKILLS = [
+  ['buildline', 'buildline', 'Software factory front door: shows feature status, what is next, and routes to the right station (onboard, new, spec, design, plan, build, verify, review, ship). Use when the user says "buildline" or "factory", asks what to do next, or wants to start any piece of work.', '[what you want to do]'],
+  ['buildline-onboard', 'onboard', 'Onboard the software factory: interview for a new project and scaffold it, or map an existing codebase into .buildline/context files and real quality gates. Use when setting up the factory or when context files are stale.', ''],
+  ['buildline-new', 'new', 'Buildline intake: turn an idea, request or bug report into a sized feature (fix / feature / epic) with a brief. Use when someone proposes a feature, reports a bug, or says "new feature".', '<idea or bug description>'],
+  ['buildline-spec', 'spec', 'Buildline spec station: interview the PM and write testable requirements and Given/When/Then acceptance scenarios for a feature. Use when writing or refining a feature spec.', '<feature id>'],
+  ['buildline-design', 'design', 'Buildline design station: UX flows, screen states, components, copy and accessibility, plus technical design, for a feature. Use for design or technical approach work on a factory feature.', '<feature id>'],
+  ['buildline-plan', 'plan', 'Buildline plan station: break a feature spec into small, verifiable, ordered tasks in feature.json. Use when a spec is ready for planning.', '<feature id>'],
+  ['buildline-build', 'build', 'Buildline build station: implement a feature task by task behind the quality gates, test-first, with evidence and a commit per task. Use to implement or continue implementing a factory feature.', '<feature id>'],
+  ['buildline-verify', 'verify', 'Buildline verify station: independently check a feature against its acceptance scenarios with gates, the running app and browser checks. Use when all build tasks pass.', '<feature id>'],
+  ['buildline-review', 'review', 'Buildline review station: review a feature diff against its spec and principles, then prepare the PR description. Use when verification passes.', '<feature id>'],
+  ['buildline-ship', 'ship', 'Buildline ship station: open the PR, update the changelog and fold learnings back into the context files.', '<feature id>', true],
+  ['buildline-autopilot', 'autopilot', 'Buildline autopilot: run build, verify and review in a loop until the feature is ready to ship or blocked. Pairs with /goal for unattended runs.', '<feature id>', true],
+];
+
+const read = (rel) => fs.readFileSync(path.join(templatesDir, rel), 'utf8');
+const bullets = (items, fallback = 'TODO') => (items?.length ? items.map((i) => `- ${i}`).join('\n') : `- ${fallback}`);
+
+export function defaultGates(stack) {
+  const order = ['lint', 'typecheck', 'test', 'build'];
+  return order.filter((k) => stack.commands?.[k]).map((name) => ({ name, command: stack.commands[name], required: true }));
+}
+
+export function makeConfig(stack, answers) {
+  return {
+    version: 1,
+    project: answers.project || stack.name,
+    autonomy: answers.autonomy ?? 2,
+    team: answers.team || ['developer', 'designer', 'pm'],
+    agents: answers.agents || ['claude', 'codex', 'cursor'],
+    ci: answers.ci ?? false,
+    stack: {
+      greenfield: stack.empty,
+      languages: stack.languages,
+      frameworks: stack.frameworks,
+      ui: stack.ui,
+      testing: stack.testing,
+      packageManager: stack.packageManager,
+      monorepo: stack.monorepo,
+    },
+    commands: { dev: stack.commands?.dev || null },
+    gates: answers.gates || defaultGates(stack),
+    models: answers.models || {},
+  };
+}
+
+function ciSetup(config) {
+  const pm = config.stack.packageManager;
+  const steps = [];
+  if (pm === 'pnpm') steps.push('      - uses: pnpm/action-setup@v4', '      - run: pnpm install --frozen-lockfile');
+  else if (pm === 'yarn') steps.push('      - run: yarn install --frozen-lockfile');
+  else if (pm === 'bun') steps.push('      - uses: oven-sh/setup-bun@v2', '      - run: bun install');
+  else if (pm === 'npm') steps.push('      - run: npm ci');
+  else if (pm === 'uv') steps.push('      - uses: astral-sh/setup-uv@v5', '      - run: uv sync');
+  else if (pm === 'poetry' || pm === 'pip') steps.push('      - uses: actions/setup-python@v5', "        with: { python-version: '3.12' }", pm === 'poetry' ? '      - run: pipx install poetry && poetry install' : '      - run: pip install -r requirements.txt');
+  return steps.join('\n');
+}
+
+/** Every file the factory manages, for this config. */
+export function buildEntries(root, config) {
+  const has = (a) => config.agents.includes(a);
+  const gatesList = config.gates.length
+    ? config.gates.map((g) => `- **${g.name}**: \`${g.command}\`${g.required === false ? ' (optional)' : ''}`).join('\n')
+    : '- _None configured yet. Run `/buildline-onboard` or add commands to `gates` in `.buildline/buildline.json`._';
+  const vars = {
+    gatesList,
+    stackBullets: bullets([...config.stack.frameworks, ...config.stack.languages, config.stack.packageManager && `Package manager: ${config.stack.packageManager}`].filter(Boolean)),
+    uiBullets: config.stack.ui.length ? `Detected: ${config.stack.ui.join(', ')}.` : '',
+    ciSetup: ciSetup(config),
+  };
+
+  const entries = [];
+  const add = (p, content, extra = {}) => entries.push({ path: p, content, mode: 'file', ...extra });
+
+  entries.push({ path: 'AGENTS.md', mode: 'block', header: '# AGENTS.md', content: render(read('AGENTS.block.md'), vars) });
+
+  if (has('claude')) {
+    const claudePath = path.join(root, 'CLAUDE.md');
+    const existing = fs.existsSync(claudePath) ? fs.readFileSync(claudePath, 'utf8').replace(/<!-- buildline:start[\s\S]*?buildline:end -->/, '') : '';
+    const agentsImport = /@\.?\/?AGENTS\.md/.test(existing) ? '' : '@AGENTS.md\n';
+    entries.push({ path: 'CLAUDE.md', mode: 'block', header: '# CLAUDE.md', position: 'top', content: render(read('CLAUDE.block.md'), { agentsImport }) });
+
+    for (const [name, station, description, hint, manualOnly] of STATION_SKILLS) {
+      const m = modelFor(config, station);
+      const front = [
+        '---',
+        `name: ${name}`,
+        `description: ${JSON.stringify(description)}`,
+        hint ? `argument-hint: ${JSON.stringify(hint)}` : null,
+        manualOnly ? 'disable-model-invocation: true' : null,
+        m.cli === 'claude' && m.model ? `model: ${m.model}` : null,
+        '---',
+      ].filter(Boolean);
+      const handoff =
+        m.cli === 'claude'
+          ? ''
+          : `\nThis project runs the ${station} station on ${CLIS[m.cli].label} (\`models.${station}\` in \`.buildline/buildline.json\`). Hand it off: run \`npx buildline step ${station} $ARGUMENTS --headless\` with Bash, wait for it to finish, then summarise what it did and what is next. If the command fails because ${m.cli} isn't installed, say so and carry on with the playbook below yourself.\n`;
+      const body = `${handoff}\nRead \`.buildline/stations/${station}.md\` now and follow it step by step. It is the single source of truth for this station, shared with every other agent in the project.\n\nArguments: $ARGUMENTS\n`;
+      add(`.claude/skills/${name}/SKILL.md`, front.join('\n') + '\n' + body);
+    }
+    const subagentStation = Object.fromEntries(Object.entries(STATION_SUBAGENTS).map(([st, agent]) => [`${agent}.md`, st]));
+    for (const f of fs.readdirSync(path.join(templatesDir, 'agents'))) {
+      const m = subagentStation[f] ? modelFor(config, subagentStation[f]) : null;
+      const content = read(`agents/${f}`);
+      add(`.claude/agents/${f}`, m?.cli === 'claude' && m.model ? content.replace(/^model: .*$/m, `model: ${m.model}`) : content);
+    }
+  }
+  if (has('cursor')) add('.cursor/rules/buildline.mdc', read('cursor.mdc'));
+  if (has('gemini')) entries.push({ path: 'GEMINI.md', mode: 'block', header: '# GEMINI.md', position: 'top', content: read('GEMINI.block.md') });
+
+  add('.buildline/buildline.json', JSON.stringify(config, null, 2) + '\n', { userOwned: true });
+  add('.buildline/README.md', render(read('buildline-readme.md'), { project: config.project }));
+  add('.buildline/principles.md', read('principles.md'), { userOwned: true });
+  for (const f of ['product.md', 'architecture.md', 'design.md']) add(`.buildline/context/${f}`, render(read(`context/${f}`), vars), { userOwned: true });
+  for (const f of fs.readdirSync(path.join(templatesDir, 'stations'))) add(`.buildline/stations/${f}`, read(`stations/${f}`));
+  for (const f of ['spec.md', 'progress.md']) add(`.buildline/templates/${f}`, read(`feature/${f}`));
+  add('.buildline/bin/gates.mjs', read('bin/gates.mjs'), { executable: true });
+  add('.buildline/bin/hook.mjs', read('bin/hook.mjs'), { executable: true });
+  add('.buildline/features/.gitkeep', '');
+  if (config.ci) add('.github/workflows/buildline.yml', render(read('ci/buildline.yml'), vars));
+  return entries;
+}
+
+// ---- .claude/settings.json ---------------------------------------------------
+
+const HOOK_MARK = '.buildline/bin/hook.mjs';
+const hookCmd = (mode) => `node "$CLAUDE_PROJECT_DIR/.buildline/bin/hook.mjs" ${mode}`;
+
+export function settingsAllow(config) {
+  const allow = ['Bash(node .buildline/bin/gates.mjs)', 'Bash(node .buildline/bin/gates.mjs *)', 'Bash(npx buildline *)'];
+  for (const g of config.gates) allow.push(`Bash(${g.command})`, `Bash(${g.command} *)`);
+  return [...new Set(allow)];
+}
+
+/** Returns { content, changed, added } or { error }. Never drops user settings. */
+export function mergeSettings(root, config) {
+  const file = path.join(root, '.claude', 'settings.json');
+  let settings = {};
+  if (fs.existsSync(file)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (err) {
+      return { error: `.claude/settings.json is not valid JSON (${err.message}); left untouched.` };
+    }
+  }
+  const before = JSON.stringify(settings);
+  settings.hooks ??= {};
+  const ensureHook = (event, matcher, mode) => {
+    const groups = (settings.hooks[event] ??= []);
+    const present = groups.some((g) => (g.hooks || []).some((h) => h.command?.includes(HOOK_MARK)));
+    if (!present) groups.push({ ...(matcher ? { matcher } : {}), hooks: [{ type: 'command', command: hookCmd(mode) }] });
+  };
+  ensureHook('SessionStart', null, 'session-start');
+  ensureHook('PreToolUse', 'Edit|Write|MultiEdit', 'guard');
+
+  settings.permissions ??= {};
+  settings.permissions.allow ??= [];
+  const added = settingsAllow(config).filter((r) => !settings.permissions.allow.includes(r));
+  settings.permissions.allow.push(...added);
+
+  const content = JSON.stringify(settings, null, 2) + '\n';
+  return { content, changed: JSON.stringify(settings) !== before, added };
+}
+
+export function unmergeSettings(root, manifest) {
+  const file = path.join(root, '.claude', 'settings.json');
+  if (!fs.existsSync(file)) return null;
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+  for (const event of Object.keys(settings.hooks || {})) {
+    settings.hooks[event] = settings.hooks[event]
+      .map((g) => ({ ...g, hooks: (g.hooks || []).filter((h) => !h.command?.includes(HOOK_MARK)) }))
+      .filter((g) => g.hooks.length);
+    if (!settings.hooks[event].length) delete settings.hooks[event];
+  }
+  if (settings.hooks && !Object.keys(settings.hooks).length) delete settings.hooks;
+  const ours = new Set(manifest.settingsAllow || []);
+  if (settings.permissions?.allow) {
+    settings.permissions.allow = settings.permissions.allow.filter((r) => !ours.has(r));
+    if (!settings.permissions.allow.length) delete settings.permissions.allow;
+    if (!Object.keys(settings.permissions).length) delete settings.permissions;
+  }
+  return Object.keys(settings).length ? JSON.stringify(settings, null, 2) + '\n' : '';
+}
+
+// ---- top level ---------------------------------------------------------------
+
+/** Plan an install/update. Nothing is written. */
+export function plan(root, config, { force = false } = {}) {
+  const manifest = loadManifest(root);
+  const entries = buildEntries(root, config);
+  const plans = entries.map((e) => ({ ...planWrite(root, manifest, e, { force }), mode: e.mode, executable: e.executable }));
+  let settings = null;
+  if (config.agents.includes('claude')) {
+    settings = mergeSettings(root, config);
+    if (!settings.error && settings.changed) {
+      plans.push({ rel: '.claude/settings.json', action: fs.existsSync(path.join(root, '.claude/settings.json')) ? 'merge' : 'create', content: settings.content, mode: 'settings' });
+    }
+  }
+  return { manifest, plans, settings };
+}
+
+export function apply(root, { manifest, plans, settings }) {
+  applyPlan(root, manifest, plans.filter((p) => p.mode !== 'settings'));
+  const s = plans.find((p) => p.mode === 'settings');
+  if (s) {
+    fs.mkdirSync(path.join(root, '.claude'), { recursive: true });
+    fs.writeFileSync(path.join(root, s.rel), s.content);
+    manifest.settingsAllow = [...new Set([...(manifest.settingsAllow || []), ...(settings?.added || [])])];
+  }
+  manifest.version = VERSION;
+  manifest.installedAt ??= new Date().toISOString();
+  manifest.updatedAt = new Date().toISOString();
+  saveManifest(root, manifest);
+}
+
+export function removePlan(root, config) {
+  const manifest = loadManifest(root);
+  const entries = buildEntries(root, config);
+  const plans = planRemove(root, manifest, entries);
+  const settings = unmergeSettings(root, manifest);
+  return { manifest, plans, settings };
+}
+
+export function applyRemove(root, { plans, settings }) {
+  for (const p of plans) {
+    const abs = path.join(root, p.rel);
+    if (p.action === 'delete') fs.rmSync(abs, { force: true });
+    else if (p.action === 'strip-block') fs.writeFileSync(abs, p.content);
+  }
+  if (settings !== null && settings !== undefined) {
+    const file = path.join(root, '.claude', 'settings.json');
+    if (settings === '') fs.rmSync(file, { force: true });
+    else fs.writeFileSync(file, settings);
+  }
+  fs.rmSync(path.join(root, '.buildline', 'manifest.json'), { force: true });
+  // Remove now-empty directories we created, deepest first. Feature data is never deleted.
+  for (const d of ['.buildline/bin', '.buildline/stations', '.buildline/templates', '.cursor/rules', '.cursor', '.claude/agents', '.claude/skills', '.claude', '.github/workflows', '.github']) {
+    const abs = path.join(root, d);
+    try {
+      if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+        for (const sub of fs.readdirSync(abs)) {
+          const s = path.join(abs, sub);
+          if (fs.statSync(s).isDirectory() && !fs.readdirSync(s).length) fs.rmdirSync(s);
+        }
+        if (!fs.readdirSync(abs).length) fs.rmdirSync(abs);
+      }
+    } catch {}
+  }
+}
+
+export { hash };

package/src/models.js

@@ -0,0 +1,66 @@
+// Per-station model routing. `models` in buildline.json maps a station (or
+// "default") to a Claude Code model (opus, sonnet, haiku, a full model id) or to
+// another CLI: "codex", "codex:<model>", "gemini", "gemini:<model>".
+
+export const MODEL_STATIONS = ['onboard', 'new', 'spec', 'design', 'plan', 'build', 'verify', 'review', 'ship'];
+
+export const CLIS = {
+  claude: { label: 'Claude Code', install: 'https://code.claude.com' },
+  codex: { label: 'Codex CLI', install: 'npm i -g @openai/codex' },
+  gemini: { label: 'Gemini CLI', install: 'npm i -g @google/gemini-cli' },
+};
+
+// The subagent each station leans on, so its model follows the station's.
+export const STATION_SUBAGENTS = {
+  onboard: 'buildline-mapper',
+  spec: 'buildline-spec-critic',
+  design: 'buildline-design-reviewer',
+  verify: 'buildline-verifier',
+  review: 'buildline-reviewer',
+};
+
+const BALANCED = { spec: 'opus', design: 'opus', plan: 'opus', build: 'sonnet', verify: 'sonnet', review: 'opus' };
+
+export const PRESETS = {
+  session: { label: 'Same model everywhere', hint: 'every station uses the model you start the agent with', models: {} },
+  balanced: { label: 'Balanced', hint: 'Opus for spec, design, plan and review; Sonnet builds and verifies', models: BALANCED },
+  budget: { label: 'Budget', hint: 'Sonnet everywhere, Haiku for intake', models: { default: 'sonnet', new: 'haiku' } },
+  second: { label: 'Second opinion', hint: 'Balanced, and Codex reviews every diff', models: { ...BALANCED, review: 'codex' } },
+};
+
+/** "opus" → { cli: 'claude', model: 'opus' }; "codex:gpt-5" → { cli: 'codex', model: 'gpt-5' }. */
+export function parseModel(value) {
+  const v = String(value ?? '').trim();
+  if (!v || v === 'inherit') return { cli: 'claude', model: null };
+  const [head, ...rest] = v.split(':');
+  if (CLIS[head]) return { cli: head, model: rest.join(':') || null };
+  return { cli: 'claude', model: v };
+}
+
+export function modelFor(config, station) {
+  const models = config.models || {};
+  return parseModel(models[station] ?? models.default);
+}
+
+export const describeModel = ({ cli, model }) => (cli === 'claude' ? model || 'session model' : `${cli}${model ? ':' + model : ''}`);
+
+/** Prompt that starts a station in the given CLI. */
+export function stationPrompt(cli, station, id) {
+  const arg = id ? ` ${id}` : '';
+  if (cli === 'claude') return station === 'buildline' ? `/buildline${arg}` : `/buildline-${station}${arg}`;
+  const target = id ? ` for feature ${id}` : '';
+  return `Follow .buildline/stations/${station}.md step by step${target}. Project rules are in AGENTS.md.`;
+}
+
+/** [command, args] that launches a CLI with a prompt, interactively or headless. */
+export function launchArgs({ cli, model }, prompt, { headless = false } = {}) {
+  // Headless runs may edit files in the workspace (like Claude's acceptEdits), nothing more.
+  if (cli === 'codex') return ['codex', [...(headless ? ['exec', '--sandbox', 'workspace-write'] : []), ...(model ? ['-m', model] : []), prompt]];
+  if (cli === 'gemini') return ['gemini', [...(model ? ['-m', model] : []), ...(headless ? ['--approval-mode', 'auto_edit', '-p'] : ['-i']), prompt]];
+  return ['claude', [...(model ? ['--model', model] : []), ...(headless ? ['-p', prompt, '--permission-mode', 'acceptEdits'] : [prompt])]];
+}
+
+/** CLIs a config needs installed, besides Claude Code. */
+export function externalClis(config) {
+  return [...new Set(Object.values(config.models || {}).map((v) => parseModel(v).cli).filter((c) => c !== 'claude'))];
+}

package/src/render.js

@@ -0,0 +1,9 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const templatesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates');
+
+/** Replaces {{name}} placeholders. GitHub's ${{ expr }} (with spaces) is left alone. */
+export function render(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (m, key) => (key in vars ? String(vars[key] ?? '') : m));
+}

package/src/server.js

@@ -0,0 +1,143 @@
+// Local dashboard for the factory. Binds to 127.0.0.1 only; write requests need
+// a per-session token embedded in the page, and only factory markdown files can
+// be read or edited.
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import pc from 'picocolors';
+import { listFeatures, findFeature, createFeature, approve, setStatus, nextAction } from './features.js';
+import { AUTONOMY, VERSION } from './install.js';
+import { goalFor } from './cli.js';
+
+const uiFile = path.join(path.dirname(fileURLToPath(import.meta.url)), 'ui', 'index.html');
+
+const READABLE = [/^\.buildline\/features\/[^/]+\/(spec|progress)\.md$/, /^\.buildline\/context\/[\w-]+\.md$/, /^\.buildline\/principles\.md$/, /^\.buildline\/stations\/[\w-]+\.md$/, /^\.buildline\/README\.md$/];
+const WRITABLE = [/^\.buildline\/features\/[^/]+\/spec\.md$/, /^\.buildline\/context\/[\w-]+\.md$/, /^\.buildline\/principles\.md$/];
+
+function safeRel(root, rel, rules) {
+  if (typeof rel !== 'string' || rel.includes('..') || rel.includes('\0')) return null;
+  const norm = rel.replace(/\\/g, '/').replace(/^\/+/, '');
+  if (!rules.some((r) => r.test(norm))) return null;
+  const abs = path.resolve(root, norm);
+  return abs.startsWith(path.resolve(root) + path.sep) ? abs : null;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+  } catch {}
+}
+
+function state(root) {
+  const config = JSON.parse(fs.readFileSync(path.join(root, '.buildline', 'buildline.json'), 'utf8'));
+  const features = listFeatures(root).map(({ path: _p, ...f }) => ({
+    ...f,
+    next: nextAction({ ...f, path: _p }, config.autonomy),
+    goal: goalFor(f),
+  }));
+  const contextDir = path.join(root, '.buildline', 'context');
+  const context = fs.existsSync(contextDir)
+    ? fs.readdirSync(contextDir).filter((f) => f.endsWith('.md')).map((f) => {
+        const rel = `.buildline/context/${f}`;
+        return { name: f.replace('.md', ''), path: rel, todo: fs.readFileSync(path.join(root, rel), 'utf8').includes('TODO') };
+      })
+    : [];
+  context.push({ name: 'principles', path: '.buildline/principles.md', todo: false });
+  return { version: VERSION, config, autonomyLabel: AUTONOMY[config.autonomy]?.label, features, context };
+}
+
+const readBody = (req) =>
+  new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', (c) => {
+      data += c;
+      if (data.length > 2_000_000) reject(new Error('Body too large'));
+    });
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+
+export function serve(root, opts = {}) {
+  if (!fs.existsSync(path.join(root, '.buildline', 'buildline.json'))) {
+    throw new Error('No factory here. Run npx buildline init first.');
+  }
+  const token = crypto.randomBytes(16).toString('hex');
+  const port = Number(opts.port) || 4545;
+
+  const server = http.createServer(async (req, res) => {
+    const send = (code, body, type = 'application/json') => {
+      res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+      res.end(type === 'application/json' ? JSON.stringify(body) : body);
+    };
+    try {
+      // Guard against DNS rebinding: only answer requests addressed to localhost.
+      const host = (req.headers.host || '').split(':')[0];
+      if (!['localhost', '127.0.0.1'].includes(host)) return send(403, { error: 'Forbidden host' });
+
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      if (req.method === 'GET' && url.pathname === '/') {
+        const html = fs.readFileSync(uiFile, 'utf8').replace('__BUILDLINE_TOKEN__', token);
+        return send(200, html, 'text/html; charset=utf-8');
+      }
+      if (!url.pathname.startsWith('/api/')) return send(404, { error: 'Not found' });
+      if (req.method !== 'GET' && req.headers['x-buildline-token'] !== token) return send(403, { error: 'Bad token' });
+
+      if (req.method === 'GET' && url.pathname === '/api/state') return send(200, state(root));
+
+      if (url.pathname === '/api/file') {
+        if (req.method === 'GET') {
+          const abs = safeRel(root, url.searchParams.get('path'), READABLE);
+          if (!abs || !fs.existsSync(abs)) return send(404, { error: 'Not readable' });
+          return send(200, { content: fs.readFileSync(abs, 'utf8') });
+        }
+        if (req.method === 'PUT') {
+          const { path: rel, content } = JSON.parse(await readBody(req));
+          const abs = safeRel(root, rel, WRITABLE);
+          if (!abs || typeof content !== 'string') return send(400, { error: 'Not writable' });
+          fs.writeFileSync(abs, content);
+          return send(200, { ok: true });
+        }
+      }
+
+      if (req.method === 'POST' && url.pathname === '/api/features') {
+        const { title, type, owner } = JSON.parse(await readBody(req));
+        const f = createFeature(root, { title, type, owner: owner || null });
+        return send(200, { id: f.id, dir: f.dir });
+      }
+
+      const m = /^\/api\/features\/([^/]+)\/(approve|move)$/.exec(url.pathname);
+      if (req.method === 'POST' && m) {
+        const f = findFeature(root, decodeURIComponent(m[1]));
+        if (!f) return send(404, { error: 'No such feature' });
+        const body = JSON.parse(await readBody(req));
+        if (m[2] === 'approve') approve(f, body.stage, body.by);
+        else setStatus(f, body.status, body.note);
+        return send(200, { ok: true });
+      }
+      send(404, { error: 'Not found' });
+    } catch (err) {
+      send(400, { error: err.message });
+    }
+  });
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE' && !opts.port) {
+      opts.port = port + 1;
+      return serve(root, opts);
+    }
+    console.error(`${pc.red('✘')} ${err.message}`);
+    process.exitCode = 1;
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    const url = `http://127.0.0.1:${port}`;
+    console.log(`\n  ${pc.yellow('▲ buildline dashboard')}  ${pc.cyan(url)}\n  ${pc.dim('Ctrl+C to stop. Only reachable from this machine.')}\n`);
+    if (opts.open !== false) openBrowser(url);
+  });
+  return server;
+}