@techninja/clearstack 0.4.3 → 0.4.5

package/lib/spec-scan.js

@@ -0,0 +1,101 @@
+/**
+ * File scanning utilities — find, count, check lines, check imports.
+ * @module lib/spec-scan
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { resolve, extname, relative } from 'node:path';
+import { elapsed } from './spec-utils.js';
+
+/** @typedef {import('./spec-utils.js').CheckResult} CheckResult */
+/** @typedef {{ file: string, lines: number, max: number }} LineViolation */
+/** @typedef {{ file: string, spec: string }} ImportViolation */
+
+/** Recursively find files matching extensions, skipping ignored dirs. */
+export function findFiles(dir, extensions, ignoreDirs, root = dir) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = resolve(dir, entry.name);
+    const rel = relative(root, full);
+    if (entry.isDirectory()) {
+      if (ignoreDirs.some((ig) => entry.name === ig || rel === ig || rel.startsWith(ig + '/'))) continue;
+      results.push(...findFiles(full, extensions, ignoreDirs, root));
+    } else if (extensions.includes(extname(entry.name))) {
+      results.push(rel);
+    }
+  }
+  return results;
+}
+
+/**
+ * @param {string} root
+ * @param {string[]} extensions
+ * @param {string[]} ignoreDirs
+ * @returns {number}
+ */
+export function countFiles(root, extensions, ignoreDirs) {
+  return findFiles(root, extensions, ignoreDirs, root).length;
+}
+
+/**
+ * @param {string} root
+ * @param {string[]} extensions
+ * @param {number} max
+ * @param {string[]} ignoreDirs
+ * @param {string} label
+ * @param {{ exclude?: string, include?: string, localeMax?: number, quiet?: boolean }} [filter]
+ * @returns {CheckResult & { violations?: LineViolation[] }}
+ */
+export function checkFileLines(root, extensions, max, ignoreDirs, label, filter) {
+  const start = performance.now();
+  let files = findFiles(root, extensions, ignoreDirs, root);
+  if (filter?.exclude) files = files.filter((f) => !f.endsWith(filter.exclude));
+  if (filter?.include) files = files.filter((f) => f.endsWith(filter.include));
+  const localeMax = filter?.localeMax || max * 5;
+  const violations = [];
+  for (const file of files) {
+    const lines = readFileSync(resolve(root, file), 'utf-8').trimEnd().split('\n').length;
+    const limit = file.includes('/locales/') ? localeMax : max;
+    if (lines > limit) violations.push({ file, lines, max: limit });
+  }
+  const time = elapsed(start);
+  if (violations.length === 0) {
+    if (!filter?.quiet) console.log(`  ✅ ${label} (${files.length} files, ${time})`);
+    return { pass: true, label, time, files: files.length };
+  }
+  if (!filter?.quiet) {
+    console.log(`  ❌ ${label} — ${violations.length} violation(s):`);
+    for (const v of violations) console.log(`     ${v.file}: ${v.lines} lines (max ${v.max})`);
+  }
+  return { pass: false, label, time, files: files.length, violations };
+}
+
+/**
+ * @param {string} root
+ * @param {string[]} ignoreDirs
+ * @param {string} label
+ * @param {{ quiet?: boolean }} [opts]
+ * @returns {CheckResult & { violations?: ImportViolation[] }}
+ */
+export function checkImports(root, ignoreDirs, label, opts) {
+  const start = performance.now();
+  const files = findFiles(root, ['.js'], ignoreDirs, root)
+    .filter((f) => f.startsWith('src/') && !f.includes('vendor/') && !f.includes('api/') && !f.endsWith('.test.js') && !f.endsWith('server.js'));
+  const violations = [];
+  const importRe = /(?:^|\n)\s*import\s.*?from\s+['"](\.\.[^'"]*)['"]/g;
+  for (const file of files) {
+    const src = readFileSync(resolve(root, file), 'utf-8');
+    let m;
+    while ((m = importRe.exec(src)) !== null) violations.push({ file, spec: m[1] });
+  }
+  const time = elapsed(start);
+  if (violations.length === 0) {
+    if (!opts?.quiet) console.log(`  ✅ ${label} (${files.length} files, ${time})`);
+    return { pass: true, label, time, files: files.length };
+  }
+  if (!opts?.quiet) {
+    console.log(`  ❌ ${label} — ${violations.length} violation(s):`);
+    for (const v of violations) console.log(`     ${v.file}: import '${v.spec}' → use #prefix/ alias`);
+  }
+  return { pass: false, label, time, files: files.length, violations };
+}

package/lib/spec-utils.js

@@ -1,11 +1,9 @@
 /**
- * Shared spec utilities — file scanning, command running, timing.
- * Used by both the clearstack CLI and the POC spec runner.
+ * Shared spec utilities — timing and command running.
+ * File scanning lives in spec-scan.js.
  * @module lib/spec-utils
  */
 
-import { readFileSync, readdirSync } from 'node:fs';
-import { resolve, extname, relative } from 'node:path';
 import { execSync } from 'node:child_process';
 
 /** @param {number} start */
@@ -14,104 +12,7 @@ export function elapsed(start) {
   return d < 1000 ? `${Math.round(d)}ms` : `${(d / 1000).toFixed(1)}s`;
 }
 
-/** Recursively find files matching extensions, skipping ignored dirs. */
-export function findFiles(dir, extensions, ignoreDirs, root = dir) {
-  const results = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = resolve(dir, entry.name);
-    const rel = relative(root, full);
-    if (entry.isDirectory()) {
-      if (ignoreDirs.some((ig) => entry.name === ig || rel === ig || rel.startsWith(ig + '/'))) continue;
-      results.push(...findFiles(full, extensions, ignoreDirs, root));
-    } else if (extensions.includes(extname(entry.name))) {
-      results.push(rel);
-    }
-  }
-  return results;
-}
-
-/**
- * Count files matching extensions.
- * @param {string} root
- * @param {string[]} extensions
- * @param {string[]} ignoreDirs
- * @returns {number}
- */
-export function countFiles(root, extensions, ignoreDirs) {
-  return findFiles(root, extensions, ignoreDirs, root).length;
-}
-
-/** @typedef {{ pass: boolean, label: string, time: string, files?: number, errors?: string[] }} CheckResult */
-/** @typedef {{ file: string, lines: number, max: number }} LineViolation */
-/** @typedef {{ file: string, spec: string }} ImportViolation */
-
-/**
- * Check file line counts with timing.
- * @param {string} root
- * @param {string[]} extensions
- * @param {number} max
- * @param {string[]} ignoreDirs
- * @param {string} label
- * @param {{ exclude?: string, include?: string, quiet?: boolean }} [filter]
- * @returns {CheckResult & { violations?: LineViolation[] }}
- */
-export function checkFileLines(root, extensions, max, ignoreDirs, label, filter) {
-  const start = performance.now();
-  let files = findFiles(root, extensions, ignoreDirs, root);
-  if (filter?.exclude) files = files.filter((f) => !f.endsWith(filter.exclude));
-  if (filter?.include) files = files.filter((f) => f.endsWith(filter.include));
-  const violations = [];
-  for (const file of files) {
-    const lines = readFileSync(resolve(root, file), 'utf-8').trimEnd().split('\n').length;
-    if (lines > max) violations.push({ file, lines, max });
-  }
-  const time = elapsed(start);
-  if (violations.length === 0) {
-    if (!filter?.quiet) console.log(`  ✅ ${label} (${files.length} files, ${time})`);
-    return { pass: true, label, time, files: files.length };
-  }
-  if (!filter?.quiet) {
-    console.log(`  ❌ ${label} — ${violations.length} violation(s):`);
-    for (const v of violations) console.log(`     ${v.file}: ${v.lines} lines (max ${v.max})`);
-  }
-  return { pass: false, label, time, files: files.length, violations };
-}
-
-/**
- * Check for relative parent imports (`../`) in browser-facing JS files.
- * Same-directory (`./`) and server/test files are allowed.
- * @param {string} root
- * @param {string[]} ignoreDirs
- * @param {string} label
- * @param {{ quiet?: boolean }} [opts]
- * @returns {CheckResult & { violations?: ImportViolation[] }}
- */
-export function checkImports(root, ignoreDirs, label, opts) {
-  const start = performance.now();
-  const files = findFiles(root, ['.js'], ignoreDirs, root)
-    .filter((f) => f.startsWith('src/') && !f.includes('vendor/') && !f.includes('api/') && !f.endsWith('.test.js') && !f.endsWith('server.js'));
-  const violations = [];
-  const importRe = /(?:^|\n)\s*import\s.*?from\s+['"](\.\.[^'"]*)['"]|(?:^|\n)\s*import\s+['"](\.\.[^'"]*)['"]|(?:^|\n)\s*export\s.*?from\s+['"](\.\.[^'"]*)['"/]/g;
-  for (const file of files) {
-    const src = readFileSync(resolve(root, file), 'utf-8');
-    let m;
-    while ((m = importRe.exec(src)) !== null) {
-      const spec = m[1] || m[2] || m[3];
-      violations.push({ file, spec });
-    }
-  }
-  const time = elapsed(start);
-  if (violations.length === 0) {
-    if (!opts?.quiet) console.log(`  ✅ ${label} (${files.length} files, ${time})`);
-    return { pass: true, label, time, files: files.length };
-  }
-  if (!opts?.quiet) {
-    console.log(`  ❌ ${label} — ${violations.length} violation(s):`);
-    for (const v of violations) console.log(`     ${v.file}: import '${v.spec}' → use #prefix/ alias`);
-  }
-  return { pass: false, label, time, files: files.length, violations };
-}
-
+/** @typedef {{ pass: boolean, label: string, time: string, detail?: string, files?: number, errors?: string[], violations?: object[] }} CheckResult */
 
 /**
  * Run a shell command, report pass/fail with timing.
@@ -131,16 +32,20 @@ export function runCmd(label, cmd, cwd, stats, opts) {
     return { pass: true, label, time: elapsed(start), files: parseInt(stats) || undefined };
   } catch (err) {
     const out = (err.stdout || '') + (err.stderr || '');
-    const ownErrors = out.trim().split('\n')
-      .filter((l) => l.trim() && !l.includes('node_modules'));
-    if (ownErrors.length === 0) {
+    const lines = out.trim().split('\n').filter((l) => l.trim());
+    const ownErrors = lines.filter((l) => !/[/\\]node_modules[/\\]/.test(l));
+    const isPrettier = cmd.includes('prettier');
+    const display = isPrettier
+      ? ownErrors.filter((l) => l.startsWith('[warn]') && !l.includes('Run Prettier'))
+      : ownErrors;
+    if (display.length === 0) {
       if (!opts?.quiet) console.log(`  ✅ ${label}${suffix(stats)}`);
       return { pass: true, label, time: elapsed(start) };
     }
     if (!opts?.quiet) {
       console.log(`  ❌ ${label}${suffix(stats)}`);
-      for (const line of ownErrors) console.log(`     ${line}`);
+      for (const line of display) console.log(`     ${line}`);
     }
-    return { pass: false, label, time: elapsed(start), errors: ownErrors };
+    return { pass: false, label, time: elapsed(start), errors: display };
   }
 }

package/lib/watch-lifecycle.js

@@ -0,0 +1,47 @@
+/**
+ * Watch lifecycle — quit, self-restart, and fs.watch setup.
+ * @module lib/watch-lifecycle
+ */
+
+import { watch } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { resolve, extname } from 'node:path';
+import { destroyScreen, setQuit } from './watch-ui.js';
+import { setOnCopyNote } from './watch-widgets.js';
+
+/**
+ * Register quit + restart handlers and start fs.watch on project and lib dirs.
+ * @param {{ serverRow: object|null, specRows: object[], projectDir: string, watchDirs: string[], schedule: (ext: string) => void, renderNote: () => void }} ctx
+ */
+export function setupLifecycle(ctx) {
+  const { serverRow, specRows, projectDir, watchDirs, schedule, renderNote } = ctx;
+
+  const quit = () => {
+    serverRow?.kill();
+    destroyScreen();
+    const passing = specRows.filter((r) => r.pass).length;
+    console.log(`Spec watch stopped. Final state: ${passing}/${specRows.length} checks passing`);
+    process.exit(0);
+  };
+
+  const restart = () => {
+    serverRow?.kill();
+    destroyScreen();
+    console.log('\nSpec files changed — run `npm run spec watch` to restart.');
+    process.exit(0);
+  };
+
+  setQuit(quit);
+  setOnCopyNote(renderNote);
+  process.on('SIGINT', quit);
+
+  for (const dir of watchDirs) {
+    watch(resolve(projectDir, dir), { recursive: true }, (_event, filename) => {
+      if (filename) schedule(extname(filename));
+    });
+  }
+
+  for (const dir of ['lib', 'bin'].filter((d) => existsSync(resolve(projectDir, d)))) {
+    watch(resolve(projectDir, dir), { recursive: true }, restart);
+  }
+}

package/lib/watch-ui.js

@@ -0,0 +1,148 @@
+/**
+ * Spec watch UI — rendering, split candidates, violation extraction.
+ * Widget construction lives in watch-widgets.js.
+ * @module lib/watch-ui
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { screen, statusBox, divider, logBox, getSpin, getCopyNote } from './watch-widgets.js';
+
+export { setQuit } from './watch-widgets.js';
+
+// ── Split candidate detection ─────────────────────────────────────────────────
+
+/**
+ * Suggest split seams for a file that exceeds the line limit.
+ * Prefers `// SPLIT CANDIDATE:` comments, falls back to heuristics.
+ * @param {string} filePath absolute path
+ * @returns {string[]}
+ */
+export function splitCandidates(filePath) {
+  if (!existsSync(filePath)) return [];
+  const lines = readFileSync(filePath, 'utf-8').split('\n');
+  const explicit = [];
+  lines.forEach((l, i) => {
+    const m = l.match(/\/\/\s*SPLIT CANDIDATE:\s*(.+)/i);
+    if (m) explicit.push(`  L${i + 1}: ${m[1].trim()}`);
+  });
+  if (explicit.length) return explicit;
+
+  const seams = [];
+  lines.forEach((l, i) => {
+    // Only exported functions/classes are meaningful split boundaries
+    if (/^export (async function|function|class)/.test(l)) seams.push(i + 1);
+  });
+  if (seams.length < 2) return [];
+  const suggestions = [];
+  for (let i = 0; i < seams.length - 1 && suggestions.length < 3; i++) {
+    const start = seams[i], end = seams[i + 1] - 1;
+    if (end - start < 10) continue;
+    // Peek at the function name for a more useful suggestion
+    const nameMatch = lines[start - 1]?.match(/^export (?:async )?function (\w+)/);
+    const hint = nameMatch ? `→ ${nameMatch[1]}()` : 'consider extracting';
+    suggestions.push(`  L${start}-${end}: ${hint}`);
+  }
+  return suggestions;
+}
+
+// ── Violation extraction ──────────────────────────────────────────────────────
+
+/**
+ * Process a failed check row into violation tuples for the log panel.
+ * @param {object} row
+ * @param {string} projectDir
+ * @returns {string[][]}
+ */
+export function extractViolations(row, projectDir) {
+  if (row.pass) return [];
+  if (row.result?.violations?.length) {
+    return row.result.violations.map((v) => {
+      if (v.spec !== undefined) return [v.file, `import '${v.spec}' → use #prefix/ alias`];
+      const candidates = splitCandidates(resolve(projectDir, v.file));
+      return [v.file, `${v.lines} lines (max ${v.max}, +${v.lines - v.max} over)`, ...candidates];
+    });
+  }
+  if (row.result?.errors?.length) {
+    return [[(row.label ?? row.name ?? row.key), row.result.errors.slice(0, 3).join('\n')]];
+  }
+  return [];
+}
+
+// ── Render ────────────────────────────────────────────────────────────────────
+
+/** @param {object} r */
+function rowIcon(r) {
+  if (r.key === 'server') {
+    if (r.status === 'running')    return '{green-fg}ok{/}';
+    if (r.status === 'crashed')    return '{red-fg}!{/} ';
+    if (r.status === 'restarting') return '{yellow-fg}~{/} ';
+    return '{grey-fg}' + getSpin() + '{/}';
+  }
+  if (r.pass === null) return '{grey-fg}' + getSpin() + '{/}';
+  if (r.pass)          return '{green-fg}ok{/}';
+  return '{red-fg}!{/} ';
+}
+
+/**
+ * Render the dashboard.
+ * @param {object[]} rows
+ * @param {string} lastCheck
+ * @param {string[]} watchDirs
+ * @param {string[][]} violations
+ */
+export function render(rows, lastCheck, watchDirs, violations) {
+  const labelWidth = Math.max(...rows.map((r) => (r.label ?? r.name ?? r.key).length));
+  const statusLines = rows.map((r) => {
+    const name = (r.label ?? r.name ?? r.key).padEnd(labelWidth);
+    const styled = r.pass === false ? `{red-fg}${name}{/}` : name;
+    const detail = r.detail ? `{grey-fg}${r.detail}{/}` : '';
+    return ` ${rowIcon(r)} ${styled}  ${detail}`;
+  });
+  statusLines.push('');
+  statusLines.push(`{grey-fg} watching ${watchDirs.join(', ')}   last check: ${lastCheck}{/}${getCopyNote()}`);
+  statusBox.setContent(statusLines.join('\n'));
+  statusBox.height = statusLines.length;
+
+  const statusHeight = statusLines.length + 1;
+  divider.top = statusHeight;
+  logBox.top = statusHeight + 1;
+
+  if (violations.length) {
+    const logLines = ['{yellow-fg}─── Copy below into your LLM session ───{/}'];
+    for (const [file, detail, ...candidates] of violations) {
+      logLines.push('');
+      logLines.push(`{cyan-fg}${file}{/}`);
+      logLines.push(detail);
+      if (candidates.length) {
+        logLines.push('{grey-fg}Split candidates:{/}');
+        for (const c of candidates) logLines.push(`{grey-fg}${c}{/}`);
+      }
+    }
+    logBox.setContent(logLines.join('\n'));
+    logBox.show();
+    divider.show();
+  } else {
+    logBox.hide();
+    divider.hide();
+  }
+
+  screen.render();
+}
+
+/** Tear down the blessed screen cleanly. */
+export function destroyScreen() {
+  screen.destroy();
+}
+
+/** Refresh just the status box — used for transient notes like copy confirmation. */
+export function renderNote(rows, lastCheck, watchDirs) {
+  const labelWidth = Math.max(...rows.map((r) => (r.label ?? r.name ?? r.key).length));
+  const lines = [
+    ...rows.map((r) => { const n = (r.label ?? r.name ?? r.key).padEnd(labelWidth); return ` ${rowIcon(r)} ${r.pass === false ? `{red-fg}${n}{/}` : n}  ${r.detail ? `{grey-fg}${r.detail}{/}` : ''}`; }),
+    '',
+    `{grey-fg} watching ${watchDirs.join(', ')}   last check: ${lastCheck}{/}${getCopyNote()}`,
+  ];
+  statusBox.setContent(lines.join('\n'));
+  screen.render();
+}

package/lib/watch-widgets.js

@@ -0,0 +1,82 @@
+/**
+ * Blessed widget tree for the spec watch dashboard.
+ * Constructed once at import time and shared across render calls.
+ * @module lib/watch-widgets
+ */
+
+import { createRequire } from 'node:module';
+import { execFile } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+const blessed = require('blessed');
+
+export const screen = blessed.screen({ smartCSR: true, title: 'Clearstack Spec Watch' });
+
+export const outer = blessed.box({
+  top: 0, left: 0, width: '100%', height: '100%',
+  border: { type: 'line' },
+  label: { text: ' {blue-fg}♥{/blue-fg} Clearstack Spec Watch  q quit  ↑↓ scroll  c copy {/}', side: 'left' },
+  tags: true,
+  style: { border: { fg: 'cyan' }, label: { fg: 'grey', bold: false } },
+});
+
+export const statusBox = blessed.box({
+  top: 0, left: 0, width: '100%-2', height: 1,
+  tags: true,
+  style: { fg: 'white' },
+});
+
+export const divider = blessed.line({
+  top: 1, left: 0, width: '100%-2', orientation: 'horizontal',
+  style: { fg: 'grey' },
+});
+
+export const logBox = blessed.scrollablebox({
+  top: 2, left: 0, width: '100%-2', bottom: 1,
+  tags: true, scrollable: true, alwaysScroll: true,
+  scrollbar: { ch: '│', style: { fg: 'grey' } },
+  style: { fg: 'white' },
+});
+
+outer.append(statusBox);
+outer.append(divider);
+outer.append(logBox);
+screen.append(outer);
+
+const SPINNER = ['⠋  ', '⠙  ', '⠹  ', '⠸  ', '⠼  ', '⠴  ', '⠦  ', '⠧  ', '⠇  ', '⠏  '];
+let spinFrame = 0;
+export const getSpin = () => SPINNER[spinFrame % SPINNER.length];
+
+const spinInterval = setInterval(() => { spinFrame++; screen.render(); }, 80);
+spinInterval.unref(); // don't keep process alive just for the spinner
+
+let _quit = () => process.exit(0);
+export const setQuit = (fn) => { _quit = fn; };
+
+let _copyNote = '';
+export const getCopyNote = () => _copyNote;
+let _onCopyNote = () => {};
+export const setOnCopyNote = (fn) => { _onCopyNote = fn; };
+
+screen.key(['C-c', 'q'], () => _quit());
+screen.key(['pageup', 'up'], () => { logBox.scroll(-1); screen.render(); });
+screen.key(['pagedown', 'down'], () => { logBox.scroll(1); screen.render(); });
+screen.key(['c'], () => {
+  const raw = logBox.getContent()
+    .replace(/\{[^}]+\}/g, '')          // blessed tags
+    .replace(/\x1b\[[\d;]*m/g, '')       // ANSI escape codes
+    .split('\n').slice(1).join('\n')     // drop header line
+    .trim();
+  if (!raw) return;
+  const [cmd, ...args] = process.platform === 'darwin'
+    ? ['pbcopy']
+    : ['xclip', '-selection', 'clipboard'];
+  const proc = execFile(cmd, args);
+  proc.stdin.end(raw);
+  proc.on('close', (code) => {
+    _copyNote = code === 0 ? '{green-fg}  ✓ copied{/}' : '{red-fg}  ✗ copy failed{/}';
+    _onCopyNote();
+    setTimeout(() => { _copyNote = ''; _onCopyNote(); }, 1500);
+  });
+  proc.on('error', () => { _copyNote = '{red-fg}  ✗ clipboard unavailable{/}'; _onCopyNote(); });
+});

package/lib/watch.js

@@ -0,0 +1,131 @@
+/**
+ * Spec watch dashboard — continuous compliance monitoring.
+ * Runs affected checks on file change with 500ms debounce.
+ * UI rendering lives in watch-ui.js.
+ * @module lib/watch
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig, buildCmds, makeExtMap, FAST_CHECKS } from './spec-config.js';
+import { buildChecks } from './check.js';
+import { render, extractViolations, renderNote } from './watch-ui.js';
+import { spawnServer, detectServerCmd } from './server-proc.js';
+import { setupLifecycle } from './watch-lifecycle.js';
+
+/** Adapt a Check from buildChecks into a watch row (adds pass/detail/result state). */
+function toRow(check) {
+  return { ...check, pass: null, detail: '', result: null };
+}
+
+/**
+ * Start the spec watch dashboard.
+ * @param {string} projectDir
+ */
+export async function startWatch(projectDir) {
+  const cfg = loadConfig(projectDir);
+  const cmds = buildCmds(projectDir, { watch: true });
+  const checks = await buildChecks(projectDir, cfg, cmds);
+  const specRows = checks.map(toRow);
+  const checksForExt = makeExtMap(checks);
+
+  const watchDirs = ['src', 'scripts', 'docs'].filter((d) =>
+    existsSync(resolve(projectDir, d)),
+  );
+
+  let lastCheck = 'never';
+  let fastTimer = null;
+  let slowTimer = null;
+  /** @type {Set<string>} */
+  const fastPending = new Set();
+  /** @type {Set<string>} */
+  const slowPending = new Set();
+
+  // Render immediately — server spawns and checks run async behind it
+  const serverCmd = detectServerCmd(projectDir, cfg);
+
+  /** @type {import('./server-proc.js').ServerRow|null} */
+  const serverRow = serverCmd ? { key: 'server', label: 'server', status: 'starting', pass: null, detail: 'starting…', kill: () => {} } : null;
+  const rows = serverRow ? [serverRow, ...specRows] : specRows;
+
+  /**
+   *
+   */
+  function spawnAndWatch() {
+    const proc = spawnServer(serverCmd, projectDir, cfg.rawEnv, () => {
+      serverRow.status = proc.status;
+      serverRow.pass = proc.pass;
+      serverRow.detail = proc.detail;
+      serverRow.kill = proc.kill;
+      render(rows, lastCheck, watchDirs, currentViolations);
+    });
+  }
+  if (serverCmd) spawnAndWatch();
+
+  /** @type {string[][]} */
+  let currentViolations = [];
+  render(rows, lastCheck, watchDirs, currentViolations);
+
+  /**
+   *
+   */
+  function runKeys(keys) {
+    const toRun = specRows.filter((r) => keys.has(r.key));
+    if (!toRun.length) return;
+    let i = 0;
+    /**
+     *
+     */
+    async function next() {
+      if (i >= toRun.length) {
+        const now = new Date();
+        lastCheck = `${now.getHours()}:${String(now.getMinutes()).padStart(2, '0')}:${String(now.getSeconds()).padStart(2, '0')}`;
+        render(rows, lastCheck, watchDirs, currentViolations);
+        return;
+      }
+      const row = toRun[i++];
+      const raw = await row.run({ quiet: true });
+      row.result = typeof raw === 'boolean' ? { pass: raw } : raw;
+      row.pass = row.result.pass;
+      row.detail = row.pass
+        ? (row.result.detail ?? (row.result.files ? `${row.result.files} files` : ''))
+        : (row.result.violations?.length
+            ? `${row.result.violations.length} violation(s)`
+            : (() => { const errs = row.result.errors ?? []; const n = errs.filter((l) => /\.(js|ts|css|md)/.test(l)).length || errs.length; return `${n} error(s)`; })());
+      // Rebuild violations from all currently-failed rows
+      currentViolations = specRows.flatMap((r) => extractViolations(r, projectDir));
+      render(rows, lastCheck, watchDirs, currentViolations);
+      setImmediate(next);
+    }
+    setImmediate(next);
+  }
+
+  /**
+   *
+   */
+  function runFast() { const keys = new Set(fastPending); fastPending.clear(); runKeys(keys); }
+  /**
+   *
+   */
+  function runSlow() { const keys = new Set(slowPending); slowPending.clear(); runKeys(keys); }
+
+  /**
+   *
+   */
+  function schedule(ext) {
+    for (const k of checksForExt(ext)) {
+      if (FAST_CHECKS.has(k)) fastPending.add(k);
+      else slowPending.add(k);
+    }
+    if (fastPending.size) { clearTimeout(fastTimer); fastTimer = setTimeout(runFast, 50); }
+    if (slowPending.size) { clearTimeout(slowTimer); slowTimer = setTimeout(runSlow, 1500); }
+  }
+
+  runKeys(new Set(specRows.map((r) => r.key)));
+
+  setupLifecycle({
+    serverRow, specRows, projectDir, watchDirs,
+    schedule,
+    renderNote: () => renderNote(rows, lastCheck, watchDirs),
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techninja/clearstack",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -12,6 +12,10 @@
     "templates/",
     "docs/"
   ],
+  "exports": {
+    ".": "./lib/check.js",
+    "./lib/*": "./lib/*"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/techninja/clearstack.git"
@@ -50,7 +54,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inquirer/prompts": "^8.3.2"
+    "@inquirer/prompts": "^8.3.2",
+    "blessed": "^0.1.81"
   },
   "devDependencies": {
     "@open-wc/testing": "^4.0.0",