buildline 0.6.0 → 0.7.0

package/README.md

@@ -138,6 +138,7 @@ Start at 2. Raise it as your gates and acceptance scenarios earn trust. [More on
 - run several sessions at once, one per feature: each gets its own track
 - the model under each station is the one that runs it
 - `↑↓` to inspect tasks and history, `⏎` to open the station on its model, `a` to approve, `q` to quit
+- a **chime** when a feature starts waiting on you or ships, so you can look away; `m` mutes it, `npx buildline sound off` turns it off for good (the dashboard chimes too)
 
 ## The dashboard
 
@@ -196,6 +197,7 @@ npx buildline watch                  live view of the line in the terminal
 npx buildline step <station> [id]    open a station on its model  --headless --model
 npx buildline models                 choose models  set <station|phase> <model> · check
 npx buildline run <id>               autopilot with Claude Code /goal  --headless
+npx buildline sound [on|off]         chime when a feature needs you or ships
 npx buildline gates                  run quality gates
 npx buildline doctor                 check the setup
 npx buildline update                 refresh managed files, keep your edits

package/bin/buildline.js

@@ -18,10 +18,11 @@ ${pc.bold('Commands')}
   ${pc.cyan('new')} "<title>"            open a feature  ${pc.dim('--type fix|feature|epic  --owner <name>  --parent <id>')}
   ${pc.cyan('approve')} <id> <stage>     record a human approval (spec | design | plan)  ${pc.dim('--by <name>')}
   ${pc.cyan('move')} <id> <station>      move a feature to a station  ${pc.dim('--note "<why>"')}
-  ${pc.cyan('watch')}                    live view of the line in your terminal  ${pc.dim('--shipped  --once  --no-intro')}
-  ${pc.cyan('ui')}                       open the dashboard in your browser  ${pc.dim('--port <n>  --no-open')}
+  ${pc.cyan('watch')}                    live view of the line in your terminal  ${pc.dim('--shipped  --once  --no-intro  --quiet')}
+  ${pc.cyan('ui')}                       open the dashboard in your browser  ${pc.dim('--port <n>  --no-open  --quiet')}
   ${pc.cyan('step')} <station> [id]      open a station in the CLI and model set for it  ${pc.dim('--model <m>  --headless  --print')}
   ${pc.cyan('models')}                   choose models per station  ${pc.dim('set <station|phase> <model> · check')}
+  ${pc.cyan('sound')} [on|off]           chime when a feature needs you or ships (watch and dashboard)
   ${pc.cyan('run')} [id]                 autopilot: build → verify → review with Claude Code /goal  ${pc.dim('--headless  --print')}
   ${pc.cyan('gates')} [names...]         run the quality gates
   ${pc.cyan('doctor')}                   check the setup
@@ -75,13 +76,14 @@ const { values: opts, positionals } = parseArgs({
     once: { type: 'boolean' },
     shipped: { type: 'boolean' },
     'no-intro': { type: 'boolean' },
+    quiet: { type: 'boolean', short: 'q' },
     help: { type: 'boolean', short: 'h' },
     version: { type: 'boolean', short: 'v' },
   },
 });
 
 const root = path.resolve(opts.cwd || process.cwd());
-const o = { ...opts, dryRun: opts['dry-run'], ci: opts['no-ci'] ? false : opts.ci, open: !opts['no-open'], intro: !opts['no-intro'] };
+const o = { ...opts, dryRun: opts['dry-run'], ci: opts['no-ci'] ? false : opts.ci, open: !opts['no-open'], intro: !opts['no-intro'], sound: !opts.quiet };
 const [cmd, ...rest] = positionals;
 
 async function main() {
@@ -117,6 +119,8 @@ async function main() {
       return cli.models(root, rest, o);
     case 'run':
       return cli.run(root, rest[0], o);
+    case 'sound':
+      return cli.sound(root, rest[0]);
     case 'gates':
       return cli.gates(root, rest);
     case 'doctor':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildline",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Install an AI software factory into any project. A spec-driven pipeline for Claude Code (and any AGENTS.md-compatible agent), for developers, designers and product managers.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -8,6 +8,7 @@ import { AGENTS, AUTONOMY, VERSION, makeConfig, plan, apply, removePlan, applyRe
 import { loadManifest } from './files.js';
 import { PHASES, MODEL_STATIONS, CLIS, modelFor, parseModel, parseModelList, describeModel, discoverModelOptions, checkModel, stationPrompt, launchArgs, externalClis } from './models.js';
 import { listFeatures, findFeature, createFeature, approve, setStatus, nextAction, moveBlocker, STATIONS, TYPES } from './features.js';
+import { chime } from './sound.js';
 
 const LOGO = [
   pc.yellow('  ┌┐ ┬ ┬┬┬  ┌┬┐┬  ┬┌┐┌┌─┐'),
@@ -270,6 +271,19 @@ export async function watch(root, opts = {}) {
   if (next?.action === 'ui') return (await import('./server.js')).serve(root, {});
 }
 
+export function sound(root, value) {
+  const config = loadConfig(root);
+  if (value) {
+    if (!['on', 'off'].includes(value)) throw new Error('Usage: buildline sound [on|off]');
+    if (value === 'on') delete config.sound;
+    else config.sound = false;
+    fs.writeFileSync(configPath(root), JSON.stringify(config, null, 2) + '\n');
+  }
+  const on = config.sound !== false;
+  console.log(`${on ? pc.green('♪') : pc.dim('♪')} Sound is ${on ? 'on' : 'off'}: ${on ? '`watch` and the dashboard chime when a feature needs you or ships.' : 'no chime.'} ${pc.dim(on ? 'Turn off: buildline sound off' : 'Turn on: buildline sound on')}`);
+  if (on && value === 'on') chime();
+}
+
 // ---- new / approve / move ----------------------------------------------------
 
 export async function newFeature(root, title, opts) {

package/src/features.js

@@ -219,3 +219,15 @@ export function liveState(feature, sessions, at = Date.now()) {
     waiting: !working.length && mine.some((s) => s.state === 'waiting'),
   };
 }
+
+/** What the chime is for: 'waiting' when a feature needs a person, 'done' once it ships, else null. */
+export function attention(feature, live) {
+  if (feature.status === 'done') return 'done';
+  return feature.blocked || live?.waiting ? 'waiting' : null;
+}
+
+/** Ids whose attention changed to waiting or done since `before` (a Map from the last look). */
+export function newAttention(before, now) {
+  if (!before) return [];
+  return [...now].filter(([id, a]) => a && before.get(id) !== a).map(([id]) => id);
+}

package/src/server.js

@@ -33,8 +33,9 @@ function openBrowser(url) {
   } catch {}
 }
 
-function state(root) {
+function state(root, opts = {}) {
   const config = JSON.parse(fs.readFileSync(path.join(root, '.buildline', 'buildline.json'), 'utf8'));
+  if (opts.sound === false) config.sound = false;
   const sessions = readSessions(root);
   const features = listFeatures(root).map(({ path: _p, ...f }) => ({
     ...f,
@@ -89,7 +90,7 @@ export function serve(root, opts = {}) {
       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 (req.method === 'GET' && url.pathname === '/api/state') return send(200, state(root, opts));
 
       if (url.pathname === '/api/file') {
         if (req.method === 'GET') {

package/src/sound.js

@@ -0,0 +1,29 @@
+// The one sound Buildline makes: a short chime when a feature needs a person or
+// ships. Plays the system's own notification sound where there is one, and falls
+// back to the terminal bell. Off with `"sound": false` in buildline.json.
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const PLAYERS = {
+  darwin: ['afplay', '/System/Library/Sounds/Glass.aiff'],
+  linux: ['paplay', '/usr/share/sounds/freedesktop/stereo/complete.oga'],
+};
+
+let last = 0;
+
+export function chime(out = process.stdout) {
+  if (Date.now() - last < 3000) return; // several features at once still make one sound
+  last = Date.now();
+  const bell = () => out.write('\x07');
+  const player = PLAYERS[process.platform];
+  if (!player || !fs.existsSync(player[1])) return bell();
+  try {
+    const child = spawn(player[0], [player[1]], { stdio: 'ignore', detached: true });
+    child.on('error', bell);
+    child.unref();
+  } catch {
+    bell();
+  }
+}
+
+export const soundOn = (config) => config?.sound !== false;

package/src/tui.js

@@ -7,7 +7,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import pc from 'picocolors';
-import { listFeatures, nextAction, approve, readSessions, readActivity, liveState } from './features.js';
+import { listFeatures, nextAction, approve, readSessions, readActivity, liveState, attention, newAttention } from './features.js';
+import { chime, soundOn } from './sound.js';
 import { modelFor, describeModel } from './models.js';
 import { AUTONOMY, VERSION } from './install.js';
 
@@ -113,7 +114,8 @@ function loadState(root, showShipped) {
     .flatMap((f) => (f.history || []).map((h) => ({ ...h, id: f.id, key: `${f.id}|${h.at}|${h.note}` })))
     .concat(tools)
     .sort((a, b) => String(a.at).localeCompare(String(b.at)));
-  return { config, all, features, events, sessions };
+  const needs = new Map(all.map((f) => [f.id, attention(f, liveState(f, sessions))]));
+  return { config, all, features, events, sessions, needs };
 }
 
 const stationIndex = (status) => (status === 'new' ? 0 : status === 'done' ? TRACK.length : TRACK.indexOf(status));
@@ -304,7 +306,7 @@ function render(st, ui, W, H) {
   }
 
   // footer
-  const keys = [['↑↓', 'select'], ['⏎', 'open'], ['a', 'approve'], ['u', 'dashboard'], ['s', ui.shipped ? 'hide shipped' : 'shipped'], ['q', 'quit']];
+  const keys = [['↑↓', 'select'], ['⏎', 'open'], ['a', 'approve'], ['u', 'dashboard'], ['s', ui.shipped ? 'hide shipped' : 'shipped'], ['m', ui.sound ? 'mute' : 'unmute'], ['q', 'quit']];
   let fx = 1;
   const foot = screen[H - 1];
   if (ui.message && ui.messageUntil > Date.now()) fx = foot.put(1, ` ${ui.message} `, C.flash);
@@ -446,8 +448,10 @@ export async function watch(root, opts = {}) {
   }
   const ui = { root, tick: 0, sel: 0, scroll: 0, flash: new Map(), freshEvents: new Map(), shipped: false, message: '', messageUntil: 0 };
   let st = loadState(root, ui.shipped);
+  ui.sound = opts.sound !== false && soundOn(st.config);
   let lastStatus = new Map(st.all.map((f) => [f.id, f.status]));
   let seen = new Set(st.events.map((e) => e.key));
+  let needs = st.needs;
 
   out.write('\x1b[?1049h\x1b[?25l');
   if (opts.intro !== false) await boot(out, st, root);
@@ -462,6 +466,8 @@ export async function watch(root, opts = {}) {
       if (lastStatus.has(f.id) && lastStatus.get(f.id) !== f.status) ui.flash.set(f.id, Date.now() + 2500);
     }
     for (const e of st.events) if (!seen.has(e.key)) ui.freshEvents.set(e.key, Date.now() + 4000);
+    if (newAttention(needs, st.needs).length && ui.sound) chime(out);
+    needs = st.needs;
     lastStatus = new Map(st.all.map((f) => [f.id, f.status]));
     seen = new Set(st.events.map((e) => e.key));
     ui.sel = Math.max(0, Math.min(ui.sel, st.features.length - 1));
@@ -496,6 +502,7 @@ export async function watch(root, opts = {}) {
       if (k === '\x1b[A' || k === 'k') ui.sel = Math.max(0, ui.sel - 1);
       else if (k === '\x1b[B' || k === 'j') ui.sel = Math.min(st.features.length - 1, ui.sel + 1);
       else if (k === 's') (ui.shipped = !ui.shipped), refresh();
+      else if (k === 'm') (ui.sound = !ui.sound), say(ui.sound ? '♪ sound on' : 'sound muted until you quit');
       else if (k === 'u') return done({ action: 'ui' });
       else if ((k === '\r' || k === '\n') && f) {
         if (f.status === 'done') say(`${f.id} has shipped`);

package/src/ui/index.html

@@ -152,6 +152,7 @@ dialog h2 { margin: 0 0 12px; font-size: 17px; }
     <button role="tab" aria-selected="false" data-view="context">Context</button>
   </nav>
   <span class="spacer"></span>
+  <button class="btn" id="soundBtn" aria-pressed="true"></button>
   <button class="btn" id="whoami" title="Name used for approvals"></button>
   <button class="btn primary" id="newBtn">+ New</button>
 </header>
@@ -287,6 +288,10 @@ async function render() {
   $('#project').textContent = S.config.project;
   $('#autonomy').textContent = S.autonomyLabel || `L${S.config.autonomy}`;
   $('#whoami').textContent = me() ? `👤 ${me()}` : 'Set your name';
+  const on = soundOn();
+  $('#soundBtn').textContent = on ? '♪ Sound on' : '♪ Sound off';
+  $('#soundBtn').setAttribute('aria-pressed', on);
+  $('#soundBtn').title = on ? 'Chimes when a feature needs you or ships. Click to mute.' : 'Click to chime when a feature needs you or ships.';
   document.querySelectorAll('nav.tabs button').forEach((b) => b.setAttribute('aria-selected', b.dataset.view === view));
   if (!(view === 'context' && ctxEditing && $('#ctxEditor'))) $('#main').innerHTML = view === 'board' ? renderBoard() : await renderContext();
   if (openId) await renderDrawer();
@@ -343,6 +348,7 @@ $('#newDialog').addEventListener('close', async () => {
 });
 $('#newBtn').onclick = newFeature;
 $('#whoami').onclick = askName;
+$('#soundBtn').onclick = () => { try { localStorage.setItem('buildline.sound', soundOn() ? 'off' : 'on'); } catch {} render(); if (soundOn()) chime(true); };
 $('#backdrop').onclick = closeDrawer;
 document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && openId && !editing) closeDrawer(); });
 document.addEventListener('click', (e) => {
@@ -352,15 +358,42 @@ document.addEventListener('click', (e) => {
   const x = e.target.closest('[data-ctx]'); if (x) { ctxPath = x.dataset.ctx; ctxEditing = false; render(); }
 });
 
+// ---- sound: one chime when a feature needs a person or ships ----
+let audio = null, needs = null, lastChime = 0;
+const soundOn = () => { let v = null; try { v = localStorage.getItem('buildline.sound'); } catch {} return v ? v === 'on' : S?.config.sound !== false; };
+const attention = (f) => (f.status === 'done' ? 'done' : f.blocked || f.live?.waiting ? 'waiting' : null);
+// Browsers only allow sound after the page has been touched, so the audio starts on the first click or key.
+const unlock = () => { audio ||= new (window.AudioContext || window.webkitAudioContext)(); audio.resume(); };
+['pointerdown', 'keydown'].forEach((e) => document.addEventListener(e, unlock, { once: true }));
+function chime(force = false) {
+  if (!audio || (!force && Date.now() - lastChime < 3000)) return;
+  lastChime = Date.now();
+  const t = audio.currentTime, out = audio.createGain();
+  out.connect(audio.destination);
+  out.gain.setValueAtTime(0.0001, t);
+  out.gain.exponentialRampToValueAtTime(0.25, t + 0.01);
+  out.gain.exponentialRampToValueAtTime(0.0001, t + 1.2);
+  for (const [hz, level] of [[880, 1], [1320, 0.35], [1760, 0.15]]) {
+    const o = audio.createOscillator(), g = audio.createGain();
+    o.frequency.value = hz; g.gain.value = level;
+    o.connect(g).connect(out); o.start(t); o.stop(t + 1.25);
+  }
+}
+function listen() {
+  const now = new Map(S.features.map((f) => [f.id, attention(f)]));
+  if (needs && soundOn() && [...now].some(([id, a]) => a && needs.get(id) !== a)) chime();
+  needs = now;
+}
+
 async function refresh() {
   try {
     const next = await api('/api/state');
     const changed = JSON.stringify(next) !== JSON.stringify(S);
-    S = next; if (changed) await render();
+    S = next; listen(); if (changed) await render();
   } catch (e) { toast('Dashboard lost connection: is `buildline ui` still running?'); }
 }
 refresh();
-setInterval(() => { if (!document.hidden && !editing && !ctxEditing) refresh(); }, 2000);
+setInterval(() => { if (!editing && !ctxEditing) refresh(); }, 2000);
 </script>
 </body>
 </html>