cmdzero 0.5.0

package/src/router.js

@@ -0,0 +1,276 @@
+import { spawn } from 'node:child_process';
+
+// ---------------------------------------------------------------------------
+// Model routing — layered router (deterministic first, LLM tiebreak second).
+//
+// Tiers (see README for the routing table):
+//   1  component tweaks / styles / copy / existing components  → Sonnet-tier
+//   2  new logic & functionality, low error rate               → Opus-tier
+//   3  multi-feature / cross-cutting / mission-critical        → Opus xhigh → Fable
+//
+// "Speed" within a tier is the claude CLI's --effort flag (low..max), scaled
+// by a complexity score. Layer 1 is lexicon+structure heuristics (<1ms, free);
+// when its signals are ambiguous, Layer 2 asks Haiku to classify via
+// --json-schema (~1-3s, ~$0.001). CMDZERO_ROUTER=heuristic|hybrid|llm.
+// ---------------------------------------------------------------------------
+
+const MODELS = {
+  t1: process.env.CMDZERO_T1_MODEL || process.env.CMDZERO_FAST_MODEL || 'claude-sonnet-5',
+  t2: process.env.CMDZERO_T2_MODEL || process.env.CMDZERO_SMART_MODEL || 'claude-opus-4-8',
+  t3: process.env.CMDZERO_T3_MODEL || 'claude-opus-4-8',
+  t3Critical: process.env.CMDZERO_T3_CRITICAL_MODEL || 'claude-fable-5',
+};
+
+// --- Layer 1 lexicons ------------------------------------------------------
+
+const STYLE_COPY =
+  /(colou?r|\b(red|blue|green|yellow|orange|purple|pink|white|black|gr[ae]y|teal|indigo|emerald|amber|slate|navy|cream)\b|padding|margin|spacing|font|bigger|smaller|larger|tighter|wider|bold|italic|underline|round(ed)?|corner|radius|shadow|glow|gradient|background|border|align|cent(er|re)|width|height|gap|opacity|hover|focus|responsive|mobile|breakpoint|dark mode|reword|rewrite|rephrase|shorten|copy|headline|heading|title|caption|label|tone|punchier|catch(y|ier)|wording|typo|spelling)/i;
+
+const EXISTING_COMPONENT =
+  /(add another|duplicate|a copy of|move (the|this|it)|reorder|swap|reuse|use the existing|another instance|same as the|like the one)/i;
+
+const NEW_LOGIC =
+  /(implement|build|create|add a (new )?(feature|form|modal|dropdown|toggle|filter|search|carousel|slider|tab|accordion|tooltip|menu|pagination|stepper|wizard)|when (clicked|submitted|hovered|selected|scrolled)|on (click|submit|change|load|scroll)|fetch|\bapi\b|endpoint|request|\bstate\b|store|track|count(er|down)?|validat(e|ion)|debounce|localstorage|session storage|cookie|websocket|subscribe|drag|sortable|upload|download|timer|interval|keyboard shortcut)/i;
+
+// "signup form" is a UI task (tier 2); "sign in with google" is auth (tier 3) —
+// the sign in/up pattern only counts when followed by an auth-flow preposition.
+const MISSION_CRITICAL =
+  /(\bauth\b|authentication|oauth|\bsso\b|log ?in|log ?out|sign ?(in|up) (with|via|using|flow)|password|payment|checkout|billing|stripe|subscription|credit card|security|permission|\brole\b|admin|database|migration|schema|production|deploy|delete (all|account|user)|gdpr|\bpii\b|encrypt)/i;
+
+const MULTI_SCOPE =
+  /(across (the|all)|all pages|every (page|component|section)|entire (site|app|page)|throughout|end.to.end|site.wide|app.wide)/i;
+
+const BIG_REWORK = /(refactor|redesign|rebuild|overhaul|rework|migrate)/i;
+
+// --- Layer 1: deterministic scoring ---------------------------------------
+
+function complexityOf(instruction) {
+  let score = 0;
+  const words = instruction.trim().split(/\s+/).length;
+  if (words > 12) score++;
+  if (words > 30) score++;
+  const clauses =
+    (instruction.match(/\b(and|then|also|plus|as well as|after that)\b/gi) || []).length +
+    (instruction.match(/[;,]/g) || []).length;
+  if (clauses >= 2) score++;
+  if (clauses >= 4) score++;
+  if (MULTI_SCOPE.test(instruction) || BIG_REWORK.test(instruction)) score++;
+  return score >= 3 ? 'high' : score >= 1 ? 'medium' : 'low';
+}
+
+function heuristicTier(instruction) {
+  const critical = MISSION_CRITICAL.test(instruction);
+  const multi = MULTI_SCOPE.test(instruction);
+  const rework = BIG_REWORK.test(instruction);
+  const logic = NEW_LOGIC.test(instruction);
+  const surface = STYLE_COPY.test(instruction) || EXISTING_COMPONENT.test(instruction);
+
+  if (critical) return { tier: 3, critical: true, confident: true };
+  if ((multi || rework) && (logic || rework || complexityOf(instruction) === 'high'))
+    return { tier: 3, critical: false, confident: true };
+  if (logic) return { tier: 2, critical: false, confident: true };
+  if (surface) return { tier: 1, critical: false, confident: true };
+  // no signal at all — default to the cheap tier but flag for the LLM tiebreak
+  return { tier: 1, critical: false, confident: false };
+}
+
+// --- Layer 2: Haiku classifier for ambiguous requests ----------------------
+
+const CLASSIFY_SCHEMA = JSON.stringify({
+  type: 'object',
+  properties: {
+    tier: { type: 'integer', enum: [1, 2, 3] },
+    complexity: { type: 'string', enum: ['low', 'medium', 'high'] },
+  },
+  required: ['tier', 'complexity'],
+  additionalProperties: false,
+});
+
+function llmClassify(instruction, cwd) {
+  return new Promise((resolve) => {
+    const prompt = [
+      'Classify this UI change request for model routing. Reply with JSON only.',
+      'tier 1: visual tweaks, styles, copy edits, or rearranging existing components.',
+      'tier 2: new logic or functionality within one area (handlers, state, forms, data fetching).',
+      'tier 3: multi-feature or cross-cutting work, or anything touching auth/payments/data/security.',
+      'complexity: low = one small change; medium = a few steps; high = many steps or broad scope.',
+      `Request: "${instruction.slice(0, 400)}"`,
+    ].join('\n');
+    const child = spawn(
+      'claude',
+      ['-p', prompt, '--model', 'haiku', '--effort', 'low', '--json-schema', CLASSIFY_SCHEMA, '--output-format', 'json'],
+      { cwd, env: { ...process.env, CLAUDE_CODE_ENTRYPOINT: undefined } }
+    );
+    let out = '';
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, 15000);
+    timer.unref?.();
+    child.stdout.on('data', (d) => (out += d));
+    child.on('close', () => {
+      clearTimeout(timer);
+      try {
+        const envelope = JSON.parse(out);
+        // --json-schema puts the validated object in structured_output
+        const parsed =
+          envelope.structured_output ??
+          (typeof envelope.result === 'string' && envelope.result ? JSON.parse(envelope.result) : envelope.result);
+        if (parsed && [1, 2, 3].includes(parsed.tier)) return resolve(parsed);
+      } catch { /* fall through */ }
+      resolve(null);
+    });
+    child.on('error', () => { clearTimeout(timer); resolve(null); });
+  });
+}
+
+// --- Route resolution -------------------------------------------------------
+
+const EFFORT = {
+  1: { low: 'low', medium: 'medium', high: 'high' },
+  2: { low: 'medium', medium: 'high', high: 'xhigh' },
+};
+
+function resolveRoute(tier, complexity, critical, source) {
+  if (tier === 3) {
+    const frontier = critical || complexity === 'high';
+    return {
+      tier,
+      complexity,
+      model: frontier ? MODELS.t3Critical : MODELS.t3,
+      // Fable's thinking is always on; effort still scales depth. Opus tier-3
+      // runs at xhigh — the setting recommended for the hardest agentic work.
+      effort: frontier ? 'high' : 'xhigh',
+      kind: critical ? 'mission-critical' : 'multi-feature',
+      source,
+    };
+  }
+  return {
+    tier,
+    complexity,
+    model: tier === 1 ? MODELS.t1 : MODELS.t2,
+    effort: EFFORT[tier][complexity],
+    kind: tier === 1 ? 'tweak' : 'feature',
+    source,
+  };
+}
+
+/**
+ * Route an instruction to {tier, complexity, model, effort}. Async because
+ * ambiguous requests may consult the Haiku classifier (hybrid mode).
+ */
+export async function classify(instruction, { cwd } = {}) {
+  const mode = process.env.CMDZERO_ROUTER || 'hybrid';
+  const h = heuristicTier(instruction);
+  let tier = h.tier;
+  let critical = h.critical;
+  let complexity = complexityOf(instruction);
+  let source = 'heuristic';
+
+  const wantLLM = mode === 'llm' || (mode === 'hybrid' && !h.confident);
+  if (wantLLM) {
+    const llm = await llmClassify(instruction, cwd);
+    if (llm) {
+      tier = llm.tier;
+      complexity = llm.complexity;
+      critical = critical || (llm.tier === 3 && MISSION_CRITICAL.test(instruction));
+      source = 'llm';
+    }
+  }
+  return resolveRoute(tier, complexity, critical, source);
+}
+
+/** Synchronous heuristic-only classification (used by tests and dry runs). */
+export function classifySync(instruction) {
+  const h = heuristicTier(instruction);
+  return resolveRoute(h.tier, complexityOf(instruction), h.critical, 'heuristic');
+}
+
+export function buildPrompt({ file, target, instruction, tailwind = true }) {
+  const styleRule = tailwind
+    ? 'use Tailwind classes for styling'
+    : "this project does NOT use Tailwind — match the file's existing styling approach (inline styles, CSS variables, or the project's stylesheets)";
+  return [
+    `You are making a surgical UI edit in a React codebase.`,
+    `Edit ONLY this file: ${file}`,
+    `The user selected this element (lines ${target.lines.start}-${target.lines.end}):`,
+    '```jsx',
+    target.snippet,
+    '```',
+    `Instruction: ${instruction}`,
+    `Rules: ${styleRule}, keep the change minimal and scoped to the selected element (and directly related code in the same file), do not reformat unrelated code, do not touch any other file.`,
+    'The file must remain valid JSX after your edit — in particular, if you add a sibling element at the root of a component return, wrap the siblings in a fragment (<>...</>).',
+  ].join('\n');
+}
+
+/**
+ * Spawn a headless claude run. `onSpawn` receives the child process so the
+ * caller can register it for cancellation. If cancelled (child killed), the
+ * promise resolves with { ok: false, cancelled: true }.
+ */
+export function runClaude({ prompt, model, effort, cwd, onEvent, onSpawn }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const args = [
+      '-p',
+      prompt,
+      '--model',
+      model,
+      '--allowedTools',
+      'Read,Edit',
+      '--permission-mode',
+      'acceptEdits',
+      '--output-format',
+      'json',
+    ];
+    if (effort) args.push('--effort', effort);
+    const child = spawn(
+      'claude',
+      args,
+      // detached → the child leads its own process group, so cancelling can
+      // signal the whole group (claude + any tool subprocesses it spawns).
+      // Killing only the top process orphans children that keep stdio pipes
+      // open, which would stall the 'close' event and the restore that follows.
+      { cwd, env: { ...process.env, CLAUDE_CODE_ENTRYPOINT: undefined }, detached: true }
+    );
+    let cancelled = false;
+    const signalGroup = (sig) => {
+      try { process.kill(-child.pid, sig); } // negative pid = process group
+      catch { try { child.kill(sig); } catch {} } // fall back to the single process
+    };
+    child.__cancel = () => {
+      cancelled = true;
+      signalGroup('SIGTERM');
+      setTimeout(() => { if (!child.killed) signalGroup('SIGKILL'); }, 1500).unref?.();
+    };
+    onSpawn?.(child);
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('close', (code) => {
+      const durationMs = Date.now() - started;
+      if (cancelled) {
+        resolve({ ok: false, cancelled: true, durationMs });
+        return;
+      }
+      if (code !== 0) {
+        resolve({ ok: false, error: err.trim() || `claude exited ${code}`, durationMs });
+        return;
+      }
+      let meta = {};
+      try {
+        const parsed = JSON.parse(out);
+        meta = {
+          costUSD: parsed.total_cost_usd,
+          turns: parsed.num_turns,
+          result: parsed.result,
+        };
+      } catch {
+        meta = { result: out.slice(0, 500) };
+      }
+      resolve({ ok: true, durationMs, ...meta });
+    });
+    child.on('error', (e) => {
+      resolve({ ok: false, error: `failed to spawn claude: ${e.message}` });
+    });
+    onEvent?.({ status: 'running', model });
+  });
+}

package/src/server.js

@@ -0,0 +1,316 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describeTarget, applyTextEdit, applyClassEdit, applyStyleEdit, applyDeleteElement, applyMove, parseLoc, checkSyntax } from './resolver.js';
+import { classify, buildPrompt, runClaude } from './router.js';
+import { initTelemetry, DISCLOSURE } from './telemetry.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const OVERLAY_PATH = path.join(__dirname, '..', 'overlay', 'overlay.js');
+const VERSION = JSON.parse(
+  fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')
+).version;
+
+// Baseline for "estimated savings": median unscoped-agent edit from
+// packages/benchmark results (sonnet, Read/Edit/Glob/Grep). Overridable.
+const BASELINE = {
+  usd: Number(process.env.CMDZERO_BASELINE_COST || 0.093),
+  ms: Number(process.env.CMDZERO_BASELINE_MS || 19000),
+};
+
+function detectTailwind(root) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }.tailwindcss);
+  } catch {
+    return false;
+  }
+}
+
+export function startServer({ root, port = 4100 }) {
+  const undoStack = new Map(); // id -> { abs, before }
+  const running = new Map(); // id -> child process (for cancellation)
+  const sseClients = new Set();
+  let nextId = 1;
+  const tailwind = detectTailwind(root);
+  const telemetry = initTelemetry({ version: VERSION, tailwind });
+
+  const savingsPath = path.join(root, '.cmdzero', 'savings.json');
+  let totals = { usd: 0, ms: 0, count: 0 };
+  try { totals = JSON.parse(fs.readFileSync(savingsPath, 'utf8')); } catch { /* first run */ }
+  function recordSavings(costUSD = 0, ms = 0) {
+    const saved = { usd: Math.max(0, BASELINE.usd - costUSD), ms: Math.max(0, BASELINE.ms - ms) };
+    totals.usd += saved.usd;
+    totals.ms += saved.ms;
+    totals.count += 1;
+    try {
+      fs.mkdirSync(path.dirname(savingsPath), { recursive: true });
+      fs.writeFileSync(savingsPath, JSON.stringify(totals));
+    } catch { /* savings persistence is best-effort */ }
+    return { saved, totals };
+  }
+
+  function broadcast(event) {
+    const line = `data: ${JSON.stringify(event)}\n\n`;
+    for (const res of sseClients) res.write(line);
+  }
+
+  function remember(id, write) {
+    undoStack.set(String(id), { abs: write.abs, before: write.before });
+  }
+
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Headers', 'content-type');
+    if (req.method === 'OPTIONS') return res.end();
+
+    const url = new URL(req.url, `http://localhost:${port}`);
+
+    try {
+      if (req.method === 'GET' && url.pathname === '/overlay.js') {
+        res.setHeader('Content-Type', 'text/javascript');
+        return res.end(fs.readFileSync(OVERLAY_PATH));
+      }
+
+      if (req.method === 'GET' && url.pathname === '/api/health') {
+        return json(res, { ok: true, root, totals, tailwind, telemetry: !telemetry.disabled });
+      }
+
+      if (req.method === 'GET' && url.pathname === '/api/events') {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          Connection: 'keep-alive',
+        });
+        res.write('\n');
+        sseClients.add(res);
+        req.on('close', () => sseClients.delete(res));
+        return;
+      }
+
+      if (req.method === 'POST') {
+        const body = await readJson(req);
+
+        if (url.pathname === '/api/resolve') {
+          return json(res, describeTarget(root, body.loc));
+        }
+
+        if (url.pathname === '/api/edit-text') {
+          const id = nextId++;
+          const write = applyTextEdit(root, body.loc, body.oldText, body.newText);
+          remember(id, write);
+          telemetry.record('copy');
+          broadcast({ type: 'tweak', id, kind: 'copy', status: 'done', tokens: 0, label: `copy: "${body.newText.slice(0, 40)}"`, ...recordSavings(0, 50) });
+          return json(res, { ok: true, id });
+        }
+
+        if (url.pathname === '/api/edit-class') {
+          const id = nextId++;
+          const write = applyClassEdit(root, body.loc, body.remove || [], body.add || []);
+          remember(id, write);
+          telemetry.record('style');
+          broadcast({ type: 'tweak', id, kind: 'style', status: 'done', tokens: 0, label: `style: ${(body.add || []).join(' ')}`, ...recordSavings(0, 50) });
+          return json(res, { ok: true, id });
+        }
+
+        if (url.pathname === '/api/edit-style') {
+          const id = nextId++;
+          const write = applyStyleEdit(root, body.loc, body.styles || {});
+          remember(id, write);
+          const desc = Object.entries(body.styles || {})
+            .map(([k, v]) => `${k}: ${v}`)
+            .join(', ');
+          telemetry.record('style');
+          broadcast({ type: 'tweak', id, kind: 'style', status: 'done', tokens: 0, label: `style: ${desc.slice(0, 50)}`, ...recordSavings(0, 50) });
+          return json(res, { ok: true, id });
+        }
+
+        if (url.pathname === '/api/delete') {
+          if (body.dryRun) {
+            applyDeleteElement(root, body.loc, { dryRun: true, index: body.index }); // throws if unsafe, writes nothing
+            return json(res, { ok: true, dryRun: true });
+          }
+          const id = nextId++;
+          const target = describeTarget(root, body.loc);
+          const write = applyDeleteElement(root, body.loc, { index: body.index });
+          remember(id, write);
+          telemetry.record('delete');
+          const label = write.removedUsage
+            ? `removed <${write.removedUsage}> usage`
+            : write.removedBlock
+              ? `deleted ${write.removedBlock}`
+              : `deleted <${target.tagName}>`;
+          broadcast({ type: 'tweak', id, kind: 'delete', status: 'done', tokens: 0, label, ...recordSavings(0, 50) });
+          return json(res, { ok: true, id });
+        }
+
+        if (url.pathname === '/api/move') {
+          if (body.dryRun) {
+            applyMove(root, body.loc, { dir: body.dir, index: body.index, toIndex: body.toIndex, dryRun: true });
+            return json(res, { ok: true, dryRun: true });
+          }
+          const id = nextId++;
+          const write = applyMove(root, body.loc, { dir: body.dir, index: body.index, toIndex: body.toIndex });
+          remember(id, write);
+          telemetry.record('move');
+          broadcast({ type: 'tweak', id, kind: 'move', status: 'done', tokens: 0, label: `moved ${write.moved}`, ...recordSavings(0, 50) });
+          return json(res, { ok: true, id });
+        }
+
+        if (url.pathname === '/api/undo') {
+          const entry = undoStack.get(String(body.id));
+          if (!entry) return json(res, { ok: false, error: 'unknown tweak id' }, 404);
+          fs.writeFileSync(entry.abs, entry.before);
+          undoStack.delete(String(body.id));
+          broadcast({ type: 'tweak', id: body.id, status: 'reverted' });
+          return json(res, { ok: true });
+        }
+
+        if (url.pathname === '/api/cancel') {
+          const child = running.get(String(body.id));
+          if (!child) return json(res, { ok: false, error: 'task not running' }, 404);
+          child.__cancel(); // kills the process; the nl handler restores the file
+          return json(res, { ok: true });
+        }
+
+        if (url.pathname === '/api/classify') {
+          // dry-run the router: no file writes, no model edit run (the hybrid
+          // router may still consult the Haiku classifier on ambiguous input)
+          const route = await classify(body.instruction || '', { cwd: root });
+          return json(res, { ok: true, ...route });
+        }
+
+        if (url.pathname === '/api/nl') {
+          const id = nextId++;
+          const { file } = parseLoc(body.loc);
+          const target = describeTarget(root, body.loc);
+          const route = await classify(body.instruction, { cwd: root });
+          // Manual model override from the picker: keep the router's effort/tier
+          // (still sized to the request) but force the model the user chose.
+          if (body.model && body.model !== 'auto') {
+            route.model = body.model;
+            route.tier = 'manual';
+          }
+          const abs = path.resolve(root, file);
+          remember(id, { abs, before: fs.readFileSync(abs, 'utf8') });
+          telemetry.record('nl');
+          broadcast({ type: 'tweak', id, kind: route.kind, status: 'queued', model: route.model, effort: route.effort, tier: route.tier, label: body.instruction.slice(0, 60) });
+          json(res, { ok: true, id, model: route.model, effort: route.effort, tier: route.tier, kind: route.kind });
+
+          const restore = () => {
+            const entry = undoStack.get(String(id));
+            if (entry) fs.writeFileSync(entry.abs, entry.before);
+          };
+
+          const prompt = buildPrompt({ file, target, instruction: body.instruction, tailwind });
+          const result = await runClaude({
+            prompt,
+            model: route.model,
+            effort: route.effort,
+            cwd: root,
+            onEvent: (e) => broadcast({ type: 'tweak', id, ...e }),
+            onSpawn: (child) => running.set(String(id), child),
+          });
+          running.delete(String(id));
+
+          // Cancelled mid-run: undo any partial edit and stop — no retry, no
+          // savings credit.
+          if (result.cancelled) {
+            restore();
+            undoStack.delete(String(id));
+            broadcast({ type: 'tweak', id, status: 'cancelled', model: route.model });
+            return;
+          }
+
+          // The model's edit must leave the file parseable: retry once with
+          // the parse error, then revert if it's still broken.
+          let parseErr = checkSyntax(root, file);
+          if (result.ok && parseErr) {
+            broadcast({ type: 'tweak', id, status: 'running', model: route.model, label: `${body.instruction.slice(0, 40)} (fixing syntax)` });
+            const retry = await runClaude({
+              prompt: `Your previous edit to ${file} left it with a JSX/JS syntax error:\n${parseErr}\n\nFix ${file} so it parses cleanly while preserving the intended change: ${body.instruction}\nEdit ONLY that file.`,
+              model: route.model,
+              effort: route.effort,
+              cwd: root,
+              onSpawn: (child) => running.set(String(id), child),
+            });
+            running.delete(String(id));
+            if (retry.cancelled) {
+              restore();
+              undoStack.delete(String(id));
+              broadcast({ type: 'tweak', id, status: 'cancelled', model: route.model });
+              return;
+            }
+            result.durationMs += retry.durationMs || 0;
+            if (retry.costUSD) result.costUSD = (result.costUSD || 0) + retry.costUSD;
+            parseErr = checkSyntax(root, file);
+          }
+          if (parseErr) {
+            restore();
+            result.ok = false;
+            result.error = `edit reverted — file was left unparseable: ${parseErr.slice(0, 120)}`;
+          }
+
+          broadcast({
+            type: 'tweak',
+            id,
+            status: result.ok ? 'done' : 'error',
+            model: route.model,
+            effort: route.effort,
+            tier: route.tier,
+            durationMs: result.durationMs,
+            costUSD: result.costUSD,
+            error: result.error,
+            ...(result.ok ? recordSavings(result.costUSD || 0, result.durationMs || 0) : {}),
+          });
+          return;
+        }
+      }
+
+      res.statusCode = 404;
+      res.end('not found');
+    } catch (e) {
+      json(res, { ok: false, error: e.message }, 400);
+    }
+  });
+
+  server.on('error', (e) => {
+    if (e.code === 'EADDRINUSE') {
+      console.error(
+        `[cmdzero] port ${port} is already in use (another daemon running?).\n` +
+          `         Stop it with: lsof -ti:${port} | xargs kill\n` +
+          `         Or pick another port: cmdzero --port ${port + 1} (and set window.CMDZERO_ORIGIN to match)`
+      );
+      process.exit(1);
+    }
+    throw e;
+  });
+  server.listen(port, () => {
+    console.log(`[cmdzero] daemon on http://localhost:${port} (root: ${root})`);
+    console.log('[cmdzero] docs & updates → https://cmdzero.dev');
+    if (telemetry.firstRun && !telemetry.disabled) console.log(DISCLOSURE);
+  });
+  return server;
+}
+
+function json(res, obj, status = 200) {
+  if (res.writableEnded) return;
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json');
+  res.end(JSON.stringify(obj));
+}
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.on('data', (c) => (data += c));
+    req.on('end', () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}

package/src/telemetry.js

@@ -0,0 +1,97 @@
+// Anonymous usage telemetry — loud about itself, trivial to disable.
+// Collected: package version, node version, OS platform, whether Tailwind was
+// detected, and per-kind tweak COUNTS. Never: code, file paths, file names,
+// prompts, or anything identifying. Disable with CMDZERO_TELEMETRY=0 or
+// the DO_NOT_TRACK=1 convention.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const ENDPOINT =
+  process.env.CMDZERO_TELEMETRY_URL || 'https://telemetry.cmdzero.dev/v1/events';
+const CONFIG_PATH = path.join(os.homedir(), '.cmdzero', 'telemetry.json');
+const FLUSH_MS = 60_000;
+
+export function telemetryDisabled() {
+  const v = String(process.env.CMDZERO_TELEMETRY ?? '').toLowerCase();
+  if (v === '0' || v === 'false' || v === 'off') return true;
+  if (String(process.env.DO_NOT_TRACK) === '1') return true;
+  return false;
+}
+
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveConfig(config) {
+  try {
+    fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config));
+  } catch {
+    /* telemetry must never break the daemon */
+  }
+}
+
+export const DISCLOSURE = [
+  '[cmdzero] Anonymous usage telemetry helps prioritize framework support.',
+  '             Collected: version, OS, tweak counts. Never: code, file paths,',
+  '             prompts, or anything identifying.',
+  '             Opt out any time: CMDZERO_TELEMETRY=0  (DO_NOT_TRACK=1 also respected)',
+].join('\n');
+
+export function initTelemetry({ version, tailwind }) {
+  let config = loadConfig();
+  const firstRun = !config;
+  if (firstRun) {
+    // random id, derived from nothing — only distinguishes installs in aggregate
+    config = { anonymousId: crypto.randomUUID(), notifiedAt: new Date().toISOString() };
+    saveConfig(config);
+  }
+  const disabled = telemetryDisabled();
+  const counts = { copy: 0, style: 0, delete: 0, nl: 0, move: 0 };
+  let flushTimer = null;
+
+  function send(event, extra = {}) {
+    if (disabled) return;
+    try {
+      fetch(ENDPOINT, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          event,
+          anonymousId: config.anonymousId,
+          version,
+          node: process.version,
+          platform: os.platform(),
+          tailwind,
+          ts: Date.now(),
+          ...extra,
+        }),
+        signal: AbortSignal.timeout(3000),
+      }).catch(() => {});
+    } catch {
+      /* fire and forget */
+    }
+  }
+
+  function record(kind) {
+    if (disabled || !(kind in counts)) return;
+    counts[kind]++;
+    if (!flushTimer) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        send('tweaks', { counts: { ...counts } });
+        for (const k of Object.keys(counts)) counts[k] = 0;
+      }, FLUSH_MS);
+      flushTimer.unref?.();
+    }
+  }
+
+  send('boot');
+  return { firstRun, disabled, record };
+}