@techninja/clearstack 0.4.4 → 0.4.5

package/README.md

@@ -18,9 +18,11 @@ This entire repository — the specification, the file structure, every componen
 npm install -D @techninja/clearstack
 npx clearstack init       # scaffold a spec-compliant project
 npm install
-npm run dev               # http://localhost:3000
+npm run spec watch        # start dev server + spec dashboard
 ```
 
+`npm run spec watch` is the recommended way to develop. It spawns your dev server, watches all source files, and runs spec checks continuously — linting, formatting, type checking, line limits, and i18n coverage all in one terminal. Violations surface instantly with file locations and split suggestions ready to copy into your LLM session.
+
 ## What's In The Box
 
 A project/task tracker that exercises every pattern in the spec: API-backed entities, localStorage-only state, realtime sync via SSE, schema-driven endpoints, and a full atomic design component hierarchy — all served as raw ES modules with zero build tools.
@@ -71,8 +73,9 @@ See [QUICKSTART.md](./docs/QUICKSTART.md) for the full walkthrough.
 ## Scripts
 
 ```bash
-npm start           # Start server
-npm run dev         # Start with --watch
+npm run spec watch  # Dev server + continuous spec dashboard (recommended)
+npm start           # Start server only
+npm run dev         # Start server with --watch
 npm test            # Node + browser tests
 npm run lint        # ESLint check
 npm run lint:fix    # ESLint auto-fix
@@ -85,6 +88,14 @@ npm run spec docs   # Check doc files ≤500 lines
 npm run spec update # Sync docs from upstream
 ```
 
+### Watch dashboard keys
+
+```
+q / Ctrl-C   quit
+↑ ↓           scroll violations
+c            copy violations to clipboard (paste into LLM)
+```
+
 ## License
 
 MIT

package/bin/cli.js

@@ -6,7 +6,7 @@
  *   clearstack init [-y] [--static|--fullstack] [--port 3000]
  *   clearstack update [--force]
  *   clearstack build [og|og-images|all] → generate OG pages and/or images
- *   clearstack check [code|docs|imports|lint|format|types|audit|all]
+ *   clearstack check [code|docs|imports|lint|format|types|audit|all|watch]
  *   clearstack report --json      → structured JSON output for tooling
  *   clearstack                   → interactive menu
  */
@@ -61,8 +61,13 @@ async function run(action) {
     await update(PKG_ROOT, { force: !!flags.force });
   } else if (action === 'check') {
     const subs = args.filter((a) => a !== cmd && !a.startsWith('-'));
-    const { check } = await import('../lib/check.js');
-    await check(process.cwd(), subs.join(' ') || undefined, { verbose: !!flags.verbose });
+    if (subs[0] === 'watch') {
+      const { startWatch } = await import('../lib/watch.js');
+      await startWatch(process.cwd());
+    } else {
+      const { check } = await import('../lib/check.js');
+      await check(process.cwd(), subs.join(' ') || undefined, { verbose: !!flags.verbose });
+    }
   } else if (action === 'report') {
     const { report } = await import('../lib/report.js');
     report(process.cwd(), { json: !!flags.json });

package/lib/check.js

@@ -6,11 +6,13 @@
 
 import { existsSync, readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { checkFileLines, runCmd, countFiles, checkImports } from './spec-utils.js';
+import { runCmd } from './spec-utils.js';
+import { countFiles, checkFileLines, checkImports } from './spec-scan.js';
 import { checkI18n } from './spec-i18n.js';
 import { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
-export { checkFileLines, runCmd, countFiles, findFiles, elapsed, checkImports } from './spec-utils.js';
+export { runCmd, elapsed } from './spec-utils.js';
+export { findFiles, countFiles, checkFileLines, checkImports } from './spec-scan.js';
 export { checkI18n } from './spec-i18n.js';
 export { loadConfig, buildCmds, detectRunner } from './spec-config.js';
 
@@ -38,7 +40,7 @@ async function loadExtensions(projectDir) {
   }
 }
 
-/** @typedef {{ key: string, name: string, parent?: string, run: (opts?: object) => boolean }} Check */
+/** @typedef {{ key: string, name: string, parent?: string, watchExts?: string[], run: (opts?: object) => (boolean | import('./spec-utils.js').CheckResult | Promise<import('./spec-utils.js').CheckResult>) }} Check */
 
 /** Find all jsconfig.json files — main config + subdirectories. */
 function findTypeConfigs(dir, runner) {
@@ -52,7 +54,7 @@ function findTypeConfigs(dir, runner) {
   }
   return configs.map((c) => ({
     key: c.key, name: `JSDoc types — ${c.label}`, parent: 'types',
-    run: () => runCmd(`Types (${c.label})`, `${runner} tsc --project ${c.path}`, dir).pass,
+    run: (o) => runCmd(`Types (${c.label})`, `${runner} tsc --project ${c.path} --noEmit`, dir, undefined, o),
   }));
 }
 
@@ -68,26 +70,26 @@ export async function buildChecks(dir, cfg, cmds) {
   const runner = detectRunner(dir);
   const builtin = [
     { key: 'es', name: 'ESLint', parent: 'lint',
-      run: () => runCmd('ESLint', cmds.lint, dir, `${js()} files`).pass },
+      run: (o) => runCmd('ESLint', cmds.lint, dir, `${js()} files`, o) },
     { key: 'css', name: 'Stylelint', parent: 'lint',
-      run: () => runCmd('Stylelint', cmds.stylelint, dir, `${css()} files`).pass },
+      run: (o) => runCmd('Stylelint', cmds.stylelint, dir, `${css()} files`, o) },
     { key: 'md', name: 'Markdown lint', parent: 'lint',
-      run: () => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`).pass },
+      run: (o) => runCmd('Markdown', cmds.mdlint, dir, `${md()} files`, o) },
     { key: 'prettier', name: 'Prettier', parent: 'format',
-      run: () => runCmd('Prettier', cmds.prettier, dir, `${js()} files`).pass },
+      run: (o) => runCmd('Prettier', cmds.prettier, dir, `${js()} files`, o) },
     { key: 'lines', name: `Code (max ${cfg.codeMax} lines)`, parent: 'code',
-      run: () => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern }).pass },
+      run: (o) => checkFileLines(dir, cfg.codeExt, cfg.codeMax, cfg.ignore, `Code (max ${cfg.codeMax} lines)`, { exclude: cfg.testPattern, ...o }) },
     { key: 'i18n', name: 'i18n readiness', parent: 'code',
-      run: (runOpts) => checkI18n(dir, cfg.ignore, 'i18n readiness', runOpts).pass },
+      run: (o) => checkI18n(dir, cfg.ignore, 'i18n readiness', o) },
     { key: 'tests', name: `Tests (max ${cfg.testMax} lines)`,
-      run: () => checkFileLines(dir, cfg.codeExt, cfg.testMax, cfg.ignore, `Tests (max ${cfg.testMax} lines)`, { include: cfg.testPattern }).pass },
+      run: (o) => checkFileLines(dir, cfg.codeExt, cfg.testMax, cfg.ignore, `Tests (max ${cfg.testMax} lines)`, { include: cfg.testPattern, ...o }) },
     { key: 'docs', name: `Docs (max ${cfg.docsMax} lines)`,
-      run: () => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`).pass },
+      run: (o) => checkFileLines(dir, cfg.docsExt, cfg.docsMax, cfg.ignore, `Docs (max ${cfg.docsMax} lines)`, o) },
     { key: 'imports', name: 'Import map aliases (no ../ imports)',
-      run: () => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)').pass },
+      run: (o) => checkImports(dir, cfg.ignore, 'Import map aliases (no ../ imports)', o) },
     ...findTypeConfigs(dir, runner),
     { key: 'audit', name: 'Security audit',
-      run: () => runCmd('Security audit', cmds.audit, dir).pass },
+      run: (o) => runCmd('Security audit', cmds.audit, dir, undefined, o) },
   ];
   const extensions = await loadExtensions(dir);
   if (!extensions.length) return builtin;
@@ -127,14 +129,16 @@ export async function check(projectDir, scope, opts) {
       console.log(`Available: ${[...tops, ...parentKeys(checks)].join(', ')}`);
       process.exit(1);
     }
-    const ok = matched.every((c) => c.run(opts));
+    const results = await Promise.all(matched.map((c) => c.run(opts)));
+    const ok = results.every((r) => typeof r === 'boolean' ? r : r.pass);
     if (!ok) process.exit(1);
     return;
   }
 
   console.log('🔍 Clearstack compliance checking now... 💙\n');
-  const results = checks.map((c) => c.run(opts));
-  const passed = results.filter(Boolean).length;
+  const results = await Promise.all(checks.map((c) => c.run(opts)));
+  const passes = results.map((r) => typeof r === 'boolean' ? r : r.pass);
+  const passed = passes.filter(Boolean).length;
   console.log(`\n${'='.repeat(40)}`);
   console.log(`${passed}/${results.length} checks passed.`);
   if (passed < results.length) process.exit(1);

package/lib/server-proc.js

@@ -0,0 +1,150 @@
+/**
+ * Dev server child process manager for spec watch dashboard.
+ * Spawns the server, captures output, and maintains a status row
+ * that the dashboard can render without any extra logic.
+ * @module lib/server-proc
+ */
+
+import { spawn, execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Detect the dev server command. Prefers SPEC_SERVER_CMD from env,
+ * then probes common entry points. Returns null for static projects.
+ * @param {string} dir @param {object} cfg @returns {string|null}
+ */
+export function detectServerCmd(dir, cfg) {
+  if (cfg.serverCmd) return cfg.serverCmd;
+  for (const entry of ['src/server.js', 'server.js', 'index.js']) {
+    if (existsSync(resolve(dir, entry))) return `node --watch ${entry}`;
+  }
+  return null;
+}
+
+/**
+ * Kill whatever process is listening on a given port.
+ * No-ops silently if nothing is found.
+ * @param {number} port
+ */
+export function killPort(port) {
+  try {
+    const pid = execSync(`lsof -ti tcp:${port}`, { encoding: 'utf-8' }).trim();
+    if (pid) execSync(`kill ${pid}`);
+  } catch { /* nothing listening, or kill already gone */ }
+}
+
+/** @typedef {'starting'|'running'|'restarting'|'crashed'|'disabled'} ServerStatus */
+
+/**
+ * @typedef {object} ServerRow
+ * @property {'server'} key
+ * @property {string} label
+ * @property {ServerStatus} status
+ * @property {boolean|null} pass
+ * @property {string} detail
+ * @property {string} [_errLine]
+ * @property {() => void} kill
+ */
+
+/** Lines from Node --watch we don't want to surface as the detail. */
+const NOISE = /^Debugger|^Waiting for|^\s*$/;
+
+/**
+ * Spawn the dev server and return a live ServerRow.
+ * The row object is mutated in place as output arrives — the dashboard
+ * just reads it on each render cycle.
+ *
+ * @param {string} cmd   e.g. 'node --watch src/server.js'
+ * @param {string} cwd   project root
+ * @param {object} env   merged into process.env for the child
+ * @param {() => void} onUpdate  called whenever status/detail changes
+ * @returns {ServerRow}
+ */
+export function spawnServer(cmd, cwd, env, onUpdate) {
+  /** @type {ServerRow} */
+  const row = {
+    key: 'server',
+    label: 'server',
+    status: 'starting',
+    pass: null,
+    detail: 'starting…',
+    kill: () => {},
+  };
+
+  const [bin, ...args] = cmd.split(/\s+/);
+  const child = spawn(bin, args, {
+    cwd,
+    env: { ...process.env, ...env, FORCE_COLOR: '0' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  row.kill = () => child.kill('SIGTERM');
+
+  /**
+   *
+   */
+  function onLine(line, isStderr) {
+    line = line.trim();
+    if (!line || NOISE.test(line)) return;
+
+    if (/restarting/i.test(line)) {
+      row.status = 'restarting';
+      row.pass = null;
+      row.detail = 'restarting…';
+      onUpdate();
+      return;
+    }
+    // Errors on stderr always override — don't let a stale URL persist
+    if (isStderr || /error|EADDR|EACCES|ENOENT/i.test(line)) {
+      row.status = 'crashed';
+      row.pass = false;
+      // Prefer 'Error: ...' lines; only upgrade, never downgrade
+      const isRich = /^Error:/i.test(line);
+      if (!row._errLine || (isRich && !/^Error:/i.test(row._errLine))) {
+        row._errLine = line.slice(0, 60);
+        row.detail = row._errLine;
+        onUpdate();
+      }
+      return;
+    }
+    if (/https?:\/\//i.test(line) || /listening|started|ready/i.test(line)) {
+      row.status = 'running';
+      row.pass = true;
+      row.detail = line;
+      onUpdate();
+      return;
+    }
+    if (row.status !== 'running') {
+      row.detail = line.slice(0, 60);
+      onUpdate();
+    }
+  }
+
+  child.stdout?.setEncoding('utf-8');
+  child.stderr?.setEncoding('utf-8');
+  /** @type {Array<[import('stream').Readable|null, boolean]>} */
+  const streams = [[child.stdout, false], [child.stderr, true]];
+  for (const [stream, isStderr] of streams) {
+    if (!stream) continue;
+    let buf = '';
+    stream.on('data', (chunk) => {
+      buf += chunk;
+      const lines = buf.split('\n');
+      buf = lines.pop();
+      for (const l of lines) onLine(l, isStderr);
+    });
+  }
+
+  child.on('close', (code, signal) => {
+    if (signal === 'SIGTERM') return;
+    row.status = 'crashed';
+    row.pass = false;
+    if (!row.detail || row.detail === 'starting…' || row.detail === 'restarting…') {
+      row.detail = `exited (code ${code ?? signal})`;
+    }
+    onUpdate();
+  });
+
+  return row;
+}

package/lib/spec-config.js

@@ -35,6 +35,8 @@ export function loadConfig(projectDir) {
   const local = existsSync(localPath) ? parseEnv(readFileSync(localPath, 'utf-8')) : {};
   const env = { ...base, ...local };
   return {
+    serverCmd: env.SPEC_SERVER_CMD || null,
+    rawEnv: env,
     codeMax: parseInt(env.SPEC_CODE_MAX_LINES) || 150,
     testMax: parseInt(env.SPEC_TEST_MAX_LINES) || 300,
     docsMax: parseInt(env.SPEC_DOCS_MAX_LINES) || 500,
@@ -45,14 +47,56 @@ export function loadConfig(projectDir) {
   };
 }
 
-/** Build check commands for the detected package manager. */
-export function buildCmds(projectDir) {
+/**
+ * Default ext→check-key mapping for built-ins.
+ * Extensions override this by declaring a `watchExts` array on their check object.
+ * @type {Record<string, string[]>}
+ */
+const EXT_DEFAULTS = {
+  '.js':  ['lines', 'es', 'prettier', 'frontend', 'imports', 'i18n'],
+  '.mjs': ['lines', 'es', 'frontend', 'imports'],
+  '.css': ['lines', 'css'],
+  '.md':  ['docs', 'md'],
+  '.json': ['i18n'],
+  '.php': [],
+};
+
+/** Checks that run on pure file reads — no subprocess, sub-millisecond. */
+export const FAST_CHECKS = new Set(['lines', 'docs', 'imports', 'i18n', 'tests']);
+
+/**
+ * Build ext→keys map, merging EXT_DEFAULTS with `watchExts` declared on extension checks.
+ * @param {object[]} checks
+ * @returns {(ext: string) => string[]}
+ */
+export function makeExtMap(checks) {
+  const map = new Map(Object.entries(EXT_DEFAULTS).map(([k, v]) => [k, new Set(v)]));
+  for (const c of checks) {
+    if (!c.watchExts) continue;
+    for (const ext of c.watchExts) {
+      if (!map.has(ext)) map.set(ext, new Set());
+      map.get(ext).add(c.key);
+    }
+  }
+  return (ext) => [...(map.get(ext) ?? [])];
+}
+
+/**
+ * @param {string} projectDir
+ * @param {{ watch?: boolean }} [opts]
+ */
+export function buildCmds(projectDir, opts) {
   const runner = detectRunner(projectDir);
-  // pnpm 9.x audit hits a retired npm endpoint (410). Use --ignore-registry-errors
-  // to avoid failing on registry issues outside the user's control.
   const audit = runner === 'pnpm exec'
     ? 'pnpm audit --prod --ignore-registry-errors'
     : 'npm audit --omit=dev';
+  if (opts?.watch) return {
+    lint: `${runner} eslint --config .configs/eslint.config.js .`,
+    stylelint: `${runner} stylelint --config .configs/.stylelintrc.json "src/**/*.css"`,
+    prettier: `${runner} prettier --config .configs/.prettierrc --check src scripts`,
+    mdlint: `${runner} markdownlint-cli2 --config .configs/.markdownlint.jsonc "docs/**/*.md" "*.md"`,
+    audit,
+  };
   return {
     lint: `${runner} eslint --config .configs/eslint.config.js . --fix`,
     stylelint: `${runner} stylelint --config .configs/.stylelintrc.json "src/**/*.css" --fix`,

package/lib/spec-i18n-locales.js

@@ -4,25 +4,27 @@
  */
 
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { execSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { resolve } from 'node:path';
 
+const execFileAsync = promisify(execFile);
+
 /**
  * Try to run `npx hybrids extract ./src` and parse the JSON output.
  * @param {string} root
- * @returns {Record<string, object>|null}
+ * @returns {Promise<Record<string, object>|null>}
  */
-export function tryHybridsExtract(root) {
+export async function tryHybridsExtract(root) {
   const srcDir = resolve(root, 'src');
   if (!existsSync(srcDir)) return null;
   try {
-    const out = execSync('npx hybrids extract ./src', {
+    const { stdout } = await execFileAsync('npx', ['hybrids', 'extract', './src'], {
       cwd: root,
       encoding: 'utf-8',
       timeout: 30000,
-      stdio: ['pipe', 'pipe', 'pipe'],
     });
-    return JSON.parse(out);
+    return JSON.parse(stdout);
   } catch {
     return null;
   }

package/lib/spec-i18n.js

@@ -6,17 +6,37 @@
 
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { findFiles, elapsed } from './spec-utils.js';
-import { tryHybridsExtract, loadLocales } from './spec-i18n-locales.js';
+import { elapsed } from './spec-utils.js';
+import { findFiles } from './spec-scan.js';
+import { tryHybridsExtract, loadLocales, parseLocaleJson } from './spec-i18n-locales.js';
 
 /** @typedef {import('./spec-utils.js').CheckResult} CheckResult */
 
-const PROSE_RE = />\s*[A-Z][a-z]{2,}[^<$`\\]{3,}\s*[<$]/g;
 const T_RE = /\bt\s*\(/;
 const MSG_RE = /\bmsg`/;
 const LOC_RE = /\blocalize\s*\(/;
-const INIT_RE = /loadLocale|localize\s*\(/;
-const TPL_RE = /html`[\s\S]*?`/g;
+
+/**
+ * Extract keys from the DEFAULTS object in a t()-based i18n.js file.
+ * @param {string} root
+ * @returns {string[]|null}
+ */
+function extractTDefaults(root) {
+  const candidates = ['src/utils/i18n.js', 'src/i18n.js', 'utils/i18n.js'];
+  for (const rel of candidates) {
+    const p = resolve(root, rel);
+    if (!existsSync(p)) continue;
+    const src = readFileSync(p, 'utf-8');
+    const block = src.match(/const DEFAULTS\s*=\s*\{([\s\S]*?)\};/);
+    if (!block) continue;
+    const keys = [];
+    const re = /['"]([\.\w]+)['"]\s*:/g;
+    let m;
+    while ((m = re.exec(block[1])) !== null) keys.push(m[1]);
+    if (keys.length) return keys;
+  }
+  return null;
+}
 
 /**
  * Check i18n readiness — informational, always passes.
@@ -24,9 +44,9 @@ const TPL_RE = /html`[\s\S]*?`/g;
  * @param {string[]} ignoreDirs
  * @param {string} label
  * @param {{ quiet?: boolean, verbose?: boolean }} [opts]
- * @returns {CheckResult}
+ * @returns {Promise<CheckResult>}
  */
-export function checkI18n(root, ignoreDirs, label, opts) {
+export async function checkI18n(root, ignoreDirs, label, opts) {
   const start = performance.now();
 
   const srcFiles = findFiles(root, ['.js'], ignoreDirs, root).filter(
@@ -37,13 +57,12 @@ export function checkI18n(root, ignoreDirs, label, opts) {
       !f.endsWith('.test.js'),
   );
 
-  let usesT = 0, usesMsg = 0, usesLocalize = 0, hasInit = false;
+  let usesT = 0, usesMsg = 0, usesLocalize = 0;
   for (const file of srcFiles) {
     const src = readFileSync(resolve(root, file), 'utf-8');
     if (T_RE.test(src)) usesT++;
     if (MSG_RE.test(src)) usesMsg++;
     if (LOC_RE.test(src)) usesLocalize++;
-    if (/router\/index|app.*init|main\.js/.test(file) && INIT_RE.test(src)) hasInit = true;
   }
 
   const localesDir = existsSync(resolve(root, 'src/locales'))
@@ -53,10 +72,9 @@ export function checkI18n(root, ignoreDirs, label, opts) {
       : null;
 
   const hasOverrides = localesDir ? existsSync(resolve(localesDir, 'overrides.json')) : false;
-  const extracted = tryHybridsExtract(root);
+  const extracted = await tryHybridsExtract(root);
   const extractedKeys = extracted ? Object.keys(extracted) : null;
   const locales = loadLocales(localesDir);
-  const languages = locales.map((l) => l.lang);
 
   const patternParts = [
     usesT ? `t() \u00d7${usesT}` : '',
@@ -65,61 +83,35 @@ export function checkI18n(root, ignoreDirs, label, opts) {
   ].filter(Boolean);
 
   const time = elapsed(start);
-
-  if (!opts?.quiet) {
-    const icon = patternParts.length ? '\u2705' : '\u26a0\ufe0f ';
-    const pattern = patternParts.length ? patternParts.join(', ') : 'none detected';
-    const langs = languages.length ? languages.join(', ') : 'en only';
-    const init = `${hasInit ? 'yes' : 'not detected'} \u00b7 Overrides: ${hasOverrides ? 'yes' : 'no'} \u00b7 Languages: ${langs}`;
-
-    let coverage = '';
-    if (extractedKeys && locales.length) {
-      const total = extractedKeys.length;
+  const coverage = [];
+  if (localesDir) {
+    // Key source priority: t() DEFAULTS + overrides → hybrids extract → overrides.json alone
+    const tKeys = extractTDefaults(root);
+    const overrideKeys = hasOverrides
+      ? [...parseLocaleJson(resolve(localesDir, 'overrides.json'))]
+      : [];
+    const masterKeys = tKeys
+      ? [...new Set([...tKeys, ...overrideKeys])]
+      : (extractedKeys ?? (overrideKeys.length ? overrideKeys : null));
+    if (masterKeys?.length && locales.length) {
       for (const loc of locales) {
-        const translated = extractedKeys.filter((k) => loc.keys.has(k)).length;
-        const pct = total > 0 ? Math.round((translated / total) * 100) : 0;
-        const missing = total - translated;
-        coverage += `\n     ${loc.lang}: ${translated}/${total} (${pct}%)${missing > 0 ? ` \u2014 ${missing} missing` : ' \u2714'}`;
-      }
-    } else if (extractedKeys) {
-      coverage = `\n     Extracted: ${extractedKeys.length} translatable strings`;
-    }
-
-    let unwrapped = '';
-    if (!extractedKeys) {
-      let hardcodedHits = 0, templateFiles = 0;
-      for (const file of srcFiles) {
-        const src = readFileSync(resolve(root, file), 'utf-8');
-        const templates = src.match(TPL_RE);
-        if (templates) {
-          templateFiles++;
-          for (const tpl of templates) {
-            const hits = tpl.match(PROSE_RE);
-            if (hits) hardcodedHits += hits.length;
-          }
-        }
-      }
-      if (hardcodedHits > 0) {
-        unwrapped = `\n     Unwrapped: ~${hardcodedHits} prose strings across ${templateFiles} template files`;
+        const translated = masterKeys.filter((k) => loc.keys.has(k)).length;
+        const pct = Math.round((translated / masterKeys.length) * 100);
+        const missing = masterKeys.length - translated;
+        coverage.push({ lang: loc.lang, pct, missing, total: masterKeys.length });
       }
     }
+  }
 
-    console.log(`  ${icon} ${label} (${time})\n     Pattern:   ${pattern}\n     Init:      ${init}${coverage}${unwrapped}`);
+  const coverageDetail = coverage.length
+    ? coverage.map((c) => `${c.lang} ${c.pct}%${c.missing ? ` (${c.missing} missing)` : ' ✓'}`).join(' · ')
+    : (locales.length === 0 ? 'en only' : '');
 
-    if (opts?.verbose && extractedKeys && locales.length) {
-      for (const loc of locales) {
-        const missing = extractedKeys.filter((k) => !loc.keys.has(k));
-        if (missing.length) {
-          console.log(`\n     Missing in ${loc.lang} (${missing.length}):`);
-          for (const k of missing.slice(0, 50)) {
-            const truncated = k.length > 70 ? k.slice(0, 70) + '\u2026' : k;
-            console.log(`       \u2022 ${truncated}`);
-          }
-          if (missing.length > 50) console.log(`       \u2026 and ${missing.length - 50} more`);
-        }
-      }
-    }
+  if (!opts?.quiet) {
+    const icon = patternParts.length ? '✅' : '⚠️ ';
+    const detail = coverageDetail || (patternParts.length ? patternParts.join(', ') : 'no i18n patterns detected');
+    console.log(`  ${icon} ${label} — ${detail} (${time})`);
   }
 
-  return { pass: true, label, time };
+  return { pass: true, label, time, detail: coverageDetail };
 }

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.4",
+  "version": "0.4.5",
   "type": "module",
   "description": "A no-build web component framework specification — scaffold, validate, and evolve spec-compliant projects",
   "bin": {
@@ -54,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",