tweaklocal 0.1.0

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "tweaklocal",
+  "version": "0.1.0",
+  "description": "Tweak your UI live in the browser and write the changes straight to source. Copy and Tailwind edits cost zero tokens; everything else routes to a right-sized model via headless claude.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "tweaklocal": "bin/tweaklocal.js" },
+  "scripts": { "start": "node bin/tweaklocal.js" },
+  "files": ["bin", "src", "overlay", "README.md"],
+  "dependencies": {
+    "@babel/parser": "^7.26.0"
+  },
+  "keywords": ["devtools", "tailwind", "visual-editor", "claude", "ai", "nextjs", "vite", "react"]
+}

package/src/resolver.js

@@ -0,0 +1,234 @@
+import { parse } from '@babel/parser';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseSource(content, file) {
+  const plugins = /\.tsx?$/.test(file) ? ['typescript', 'jsx'] : ['jsx'];
+  return parse(content, { sourceType: 'module', plugins, errorRecovery: true });
+}
+
+function walk(node, cb) {
+  if (!node || typeof node.type !== 'string') return;
+  cb(node);
+  for (const key of Object.keys(node)) {
+    if (key === 'loc') continue;
+    const v = node[key];
+    if (Array.isArray(v)) v.forEach((c) => c && typeof c.type === 'string' && walk(c, cb));
+    else if (v && typeof v.type === 'string') walk(v, cb);
+  }
+}
+
+/** loc format: "<relative file>:<line 1-based>:<col 0-based>" (matches the babel stamp) */
+export function parseLoc(loc) {
+  const m = /^(.*):(\d+):(\d+)$/.exec(loc);
+  if (!m) throw new Error(`bad loc: ${loc}`);
+  return { file: m[1], line: Number(m[2]), col: Number(m[3]) };
+}
+
+export function loadTarget(root, loc) {
+  const parsed = parseLoc(loc);
+  const { line, col } = parsed;
+  // Stamps come from two sources: the babel plugin (root-relative path,
+  // 0-based column) and the @tweaklocal/react dev runtime (absolute path,
+  // 1-based column). Normalize the path and match either column convention.
+  const file = path.isAbsolute(parsed.file)
+    ? path.relative(root, parsed.file)
+    : parsed.file;
+  if (file.startsWith('..')) throw new Error('file outside root');
+  const abs = path.resolve(root, file);
+  const content = fs.readFileSync(abs, 'utf8');
+  const ast = parseSource(content, file);
+  let element = null;
+  let nearMiss = null;
+  walk(ast, (n) => {
+    if (n.type !== 'JSXElement' || !n.openingElement.loc) return;
+    const s = n.openingElement.loc.start;
+    if (s.line !== line) return;
+    if (s.column === col) element = n;
+    else if (s.column === col - 1 && !nearMiss) nearMiss = n;
+  });
+  element = element || nearMiss;
+  if (!element) throw new Error(`no JSX element at ${loc}`);
+  return { file, abs, content, element };
+}
+
+export function describeTarget(root, loc) {
+  const { file, content, element } = loadTarget(root, loc);
+  const opening = element.openingElement;
+  const texts = element.children
+    .filter((c) => c.type === 'JSXText' && c.value.trim())
+    .map((c) => ({ value: c.value.trim(), start: c.start, end: c.end }));
+  const classAttr = opening.attributes.find(
+    (a) =>
+      a.type === 'JSXAttribute' &&
+      a.name.name === 'className' &&
+      a.value &&
+      a.value.type === 'StringLiteral'
+  );
+  return {
+    file,
+    tagName: opening.name.name,
+    span: { start: element.start, end: element.end },
+    lines: { start: element.loc.start.line, end: element.loc.end.line },
+    snippet: content.slice(element.start, element.end),
+    texts,
+    className: classAttr ? classAttr.value.value : null,
+  };
+}
+
+export function applyTextEdit(root, loc, oldText, newText) {
+  const { abs, content, element } = loadTarget(root, loc);
+  const node = element.children.find(
+    (c) => c.type === 'JSXText' && c.value.trim() === oldText.trim()
+  );
+  if (!node) throw new Error(`text "${oldText}" not found in element at ${loc}`);
+  const raw = content.slice(node.start, node.end);
+  const leading = raw.match(/^\s*/)[0];
+  const trailing = raw.match(/\s*$/)[0];
+  const next =
+    content.slice(0, node.start) + leading + newText + trailing + content.slice(node.end);
+  return writeChecked(abs, content, next);
+}
+
+export function applyClassEdit(root, loc, removes = [], adds = []) {
+  const { abs, content, element } = loadTarget(root, loc);
+  const opening = element.openingElement;
+  const attr = opening.attributes.find(
+    (a) =>
+      a.type === 'JSXAttribute' &&
+      a.name.name === 'className' &&
+      a.value &&
+      a.value.type === 'StringLiteral'
+  );
+  let next;
+  if (attr) {
+    let classes = attr.value.value.split(/\s+/).filter(Boolean);
+    classes = classes.filter((c) => !removes.includes(c));
+    for (const a of adds) if (!classes.includes(a)) classes.push(a);
+    next =
+      content.slice(0, attr.value.start + 1) +
+      classes.join(' ') +
+      content.slice(attr.value.end - 1);
+  } else {
+    const pos = opening.name.end;
+    next =
+      content.slice(0, pos) + ` className="${adds.join(' ')}"` + content.slice(pos);
+  }
+  return writeChecked(abs, content, next);
+}
+
+/**
+ * Merge CSS properties into the element's inline style prop — the
+ * styling-system-agnostic edit lane (works with CSS modules, styled-components,
+ * vanilla CSS, anything). styles: { camelCaseProp: value | null }, null removes.
+ * Appended keys win in React's style object, so replacements are drop+append.
+ */
+export function applyStyleEdit(root, loc, styles) {
+  const { abs, content, element } = loadTarget(root, loc);
+  const opening = element.openingElement;
+  const toSrc = (v) => (typeof v === 'number' ? String(v) : `'${String(v).replace(/'/g, "\\'")}'`);
+  const attr = opening.attributes.find(
+    (a) => a.type === 'JSXAttribute' && a.name.name === 'style'
+  );
+
+  if (!attr) {
+    const entries = Object.entries(styles).filter(([, v]) => v != null);
+    if (!entries.length) return writeChecked(abs, content, content);
+    const obj = entries.map(([k, v]) => `${k}: ${toSrc(v)}`).join(', ');
+    const pos = opening.name.end;
+    return writeChecked(
+      abs,
+      content,
+      content.slice(0, pos) + ` style={{ ${obj} }}` + content.slice(pos)
+    );
+  }
+
+  const expr =
+    attr.value && attr.value.type === 'JSXExpressionContainer' ? attr.value.expression : null;
+  if (!expr || expr.type !== 'ObjectExpression')
+    throw new Error('style prop is not an object literal — describe the change instead');
+
+  // Rebuild the object: keep untouched properties (and spreads) verbatim,
+  // drop replaced/removed keys, append new values last.
+  const parts = [];
+  for (const p of expr.properties) {
+    if (p.type === 'ObjectProperty' && !p.computed) {
+      const name =
+        p.key.type === 'Identifier' ? p.key.name : p.key.type === 'StringLiteral' ? p.key.value : null;
+      if (name && name in styles) continue;
+    }
+    parts.push(content.slice(p.start, p.end));
+  }
+  for (const [k, v] of Object.entries(styles)) if (v != null) parts.push(`${k}: ${toSrc(v)}`);
+
+  // Preserve multi-line formatting when the original object was multi-line.
+  const original = content.slice(expr.start, expr.end);
+  let objSrc;
+  if (original.includes('\n') && expr.properties.length) {
+    const firstProp = expr.properties[0];
+    const lineStart = content.lastIndexOf('\n', firstProp.start) + 1;
+    const indent = content.slice(lineStart, firstProp.start).match(/^\s*/)[0];
+    const braceLineStart = content.lastIndexOf('\n', expr.end - 1) + 1;
+    const braceIndent = content.slice(braceLineStart).match(/^\s*/)[0];
+    objSrc = `{\n${indent}${parts.join(`,\n${indent}`)},\n${braceIndent}}`;
+  } else {
+    objSrc = `{ ${parts.join(', ')} }`;
+  }
+  return writeChecked(
+    abs,
+    content,
+    content.slice(0, expr.start) + objSrc + content.slice(expr.end)
+  );
+}
+
+/**
+ * Delete the element from source, consuming its whole line(s) when it sits
+ * alone on them. Refuses (throws) if the removal would leave the file
+ * unparseable — e.g. deleting a component's only root element.
+ */
+export function applyDeleteElement(root, loc, { dryRun = false } = {}) {
+  const { abs, content, element, file } = loadTarget(root, loc);
+  let start = element.start;
+  let end = element.end;
+  const lineStart = content.lastIndexOf('\n', start - 1) + 1;
+  const afterMatch = content.slice(end).match(/^[ \t]*\n/);
+  if (/^[ \t]*$/.test(content.slice(lineStart, start)) && afterMatch) {
+    start = lineStart;
+    end += afterMatch[0].length;
+  }
+  const next = content.slice(0, start) + content.slice(end);
+  try {
+    parseSource(next, file);
+  } catch {
+    // Almost always: this element is the ONLY thing its component (or a
+    // .map() callback) renders, so removing it would leave an empty
+    // `return ()` or `.map(() => ())` — invalid JS. Detect that specific,
+    // near-universal case to give an actionable message instead of a
+    // generic parse error.
+    const before = content.slice(0, start).trimEnd();
+    const soleReturn = /(return\s*\(?|=>\s*\(?)$/.test(before);
+    throw new Error(
+      soleReturn
+        ? "can't delete — it's the only thing this component (or list item) renders; deleting it would leave nothing to return. Describe the change instead (e.g. \"remove this from the list\") and it'll route through the model."
+        : 'deleting this element would break the file — describe the change instead'
+    );
+  }
+  if (dryRun) return { abs, before: content, after: next, wouldWrite: false };
+  return writeChecked(abs, content, next);
+}
+
+/** Returns null if the file parses, else the parse error message. */
+export function checkSyntax(root, file) {
+  const abs = path.resolve(root, file);
+  try {
+    parseSource(fs.readFileSync(abs, 'utf8'), file);
+    return null;
+  } catch (e) {
+    return e.message;
+  }
+}
+
+function writeChecked(abs, before, after) {
+  fs.writeFileSync(abs, after);
+  return { abs, before, after };
+}

package/src/router.js

@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process';
+
+// Behavior verbs only — visual states like "on hover"/"on focus" are style
+// (Tailwind variants), not functionality.
+const FUNCTIONALITY = /(click|toggle|open|close|submit|fetch|load|save|state|counter|count|when |scroll to|navigate|link to|form|validate|sort|filter|search|api|localstorage|modal|dropdown|expand|collapse|disable|enable|animate|animation|add a |remove the )/i;
+
+/**
+ * Route a natural-language tweak to a model tier.
+ * Style/copy → fast model, functionality → reasoning model.
+ * Overridable via TWEAKLOCAL_FAST_MODEL / TWEAKLOCAL_SMART_MODEL.
+ */
+export function classify(instruction) {
+  const isFunc = FUNCTIONALITY.test(instruction);
+  return {
+    kind: isFunc ? 'functionality' : 'style/copy',
+    model: isFunc
+      ? process.env.TWEAKLOCAL_SMART_MODEL || 'sonnet'
+      : process.env.TWEAKLOCAL_FAST_MODEL || 'haiku',
+  };
+}
+
+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');
+}
+
+export function runClaude({ prompt, model, cwd, onEvent }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn(
+      'claude',
+      [
+        '-p',
+        prompt,
+        '--model',
+        model,
+        '--allowedTools',
+        'Read,Edit',
+        '--permission-mode',
+        'acceptEdits',
+        '--output-format',
+        'json',
+      ],
+      { cwd, env: { ...process.env, CLAUDE_CODE_ENTRYPOINT: undefined } }
+    );
+    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 (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,243 @@
+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, 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.TWEAKLOCAL_BASELINE_COST || 0.093),
+  ms: Number(process.env.TWEAKLOCAL_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 sseClients = new Set();
+  let nextId = 1;
+  const tailwind = detectTailwind(root);
+  const telemetry = initTelemetry({ version: VERSION, tailwind });
+
+  const savingsPath = path.join(root, '.tweaklocal', '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 });
+      }
+
+      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);
+          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);
+          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(', ');
+          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 }); // 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);
+          remember(id, write);
+          broadcast({ type: 'tweak', id, kind: 'delete', status: 'done', tokens: 0, label: `deleted <${target.tagName}>`, ...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/nl') {
+          const id = nextId++;
+          const { file } = parseLoc(body.loc);
+          const target = describeTarget(root, body.loc);
+          const route = classify(body.instruction);
+          const abs = path.resolve(root, file);
+          remember(id, { abs, before: fs.readFileSync(abs, 'utf8') });
+          broadcast({ type: 'tweak', id, kind: route.kind, status: 'queued', model: route.model, label: body.instruction.slice(0, 60) });
+          json(res, { ok: true, id, model: route.model, kind: route.kind });
+
+          const prompt = buildPrompt({ file, target, instruction: body.instruction, tailwind });
+          const result = await runClaude({
+            prompt,
+            model: route.model,
+            cwd: root,
+            onEvent: (e) => broadcast({ type: 'tweak', id, ...e }),
+          });
+
+          // 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,
+              cwd: root,
+            });
+            result.durationMs += retry.durationMs || 0;
+            if (retry.costUSD) result.costUSD = (result.costUSD || 0) + retry.costUSD;
+            parseErr = checkSyntax(root, file);
+          }
+          if (parseErr) {
+            const entry = undoStack.get(String(id));
+            fs.writeFileSync(entry.abs, entry.before);
+            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,
+            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(
+        `[tweaklocal] port ${port} is already in use (another daemon running?).\n` +
+          `         Stop it with: lsof -ti:${port} | xargs kill\n` +
+          `         Or pick another port: tweaklocal --port ${port + 1} (and set window.TWEAKLOCAL_ORIGIN to match)`
+      );
+      process.exit(1);
+    }
+    throw e;
+  });
+  server.listen(port, () => {
+    console.log(`[tweaklocal] daemon on http://localhost:${port} (root: ${root})`);
+  });
+  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 TWEAKLOCAL_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.TWEAKLOCAL_TELEMETRY_URL || 'https://telemetry.tweaklocal.dev/v1/events';
+const CONFIG_PATH = path.join(os.homedir(), '.tweaklocal', 'telemetry.json');
+const FLUSH_MS = 60_000;
+
+export function telemetryDisabled() {
+  const v = String(process.env.TWEAKLOCAL_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 = [
+  '[tweaklocal] Anonymous usage telemetry helps prioritize framework support.',
+  '             Collected: version, OS, tweak counts. Never: code, file paths,',
+  '             prompts, or anything identifying.',
+  '             Opt out any time: TWEAKLOCAL_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 };
+  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 };
+}