lean-computer-use 0.0.0-stage → 0.1.0

package/src/cli.mjs

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { packageRoot } from './paths.mjs';
+
+export const help = `lean-computer-use: native Mac app control
+
+Usage:
+  lean-computer-use [install] [--dir PATH] [--share DIR] [--with-hooks] [--dry-run] [--yes]
+  lean-computer-use uninstall [--dir PATH] [--share DIR] [--dry-run]
+  lean-computer-use doctor [--json]
+  lean-computer-use measure [--projects-dir DIR] [--since YYYY-MM-DD] [--tool-pattern REGEX] [--json]
+
+Aliases: --uninstall = uninstall; --dry = --dry-run
+Options: --help, --version
+Native app control needs macOS, Python 3 and cua-driver. The installer adds package files only.`;
+
+/** @param {string[]} args @param {Record<string, any>} adapters */
+export async function main(args = process.argv.slice(2), adapters = {}) {
+  const write = adapters.write || console.log;
+  if (args.length === 1 && args[0] === '--help') { write(help); return 0; }
+  if (args.length === 1 && args[0] === '--version') { write(JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version); return 0; }
+  let command = args[0] || 'install';
+  let rest = args.slice(1);
+  if (command === '--uninstall') command = 'uninstall';
+  else if (command.startsWith('--')) { command = 'install'; rest = args; }
+  if (command === 'install' || command === 'uninstall') {
+    const module = await import('./install.mjs');
+    return module[`${command}Command`](rest, { write, ...adapters.install });
+  }
+  if (command === 'doctor') return (await import('./doctor.mjs')).doctorCommand(rest, { write, ...adapters.doctor });
+  if (command === 'measure') return (await import('./measure.mjs')).measureCommand(rest, { write, ...adapters.measure });
+  throw Object.assign(new Error(`Unknown command: ${command}. Run lean-computer-use --help.`), { exitCode: 2 });
+}

package/src/doctor.mjs

@@ -0,0 +1,87 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { locations, payloadFiles, safePath, digest, packageRoot } from './paths.mjs';
+import { hooksRegistered } from './hooks-register.mjs';
+
+/** @param {{dir?: string, share?: string}} options @param {Record<string, any>} adapters */
+export function doctor(options = {}, adapters = {}) {
+  const env = adapters.env || process.env;
+  const platform = adapters.platform || process.platform;
+  const version = adapters.nodeVersion || process.versions.node;
+  const source = adapters.source || packageRoot;
+  const roots = locations(options, env);
+  const run = adapters.run || ((command, args) => spawnSync(command, args, { env, encoding: 'utf8', timeout: 5000, windowsHide: true }));
+  const checks = [];
+  const add = (id, status, message, fix) => checks.push({ id, status, message, fix });
+  const command = (name, args) => {
+    try { return run(name, args); } catch (error) { return { status: null, stdout: '', stderr: error.message, error }; }
+  };
+  const text = result => `${result.stdout || ''}\n${result.stderr || ''}`.trim();
+  const node = Number.parseInt(version.split('.')[0], 10);
+  add('platform', platform === 'darwin' ? 'PASS' : 'WARN', platform === 'darwin' ? 'macOS native control supported' : 'skipped: macOS only', 'Run native control on macOS.');
+  add('node', node >= 22 ? 'PASS' : 'FAIL', `Node ${version}`, 'Use Node 22 or newer.');
+  const python = command('python3', ['--version']);
+  add('python', python.status === 0 ? 'PASS' : 'FAIL', python.status === 0 ? text(python) : 'python3 is unavailable', 'Install Python 3 and put python3 on PATH.');
+  if (platform !== 'darwin') {
+    for (const id of ['osascript', 'driver', 'daemon', 'permissions', 'telemetry']) add(id, 'WARN', 'skipped: macOS only', 'Run this check on macOS.');
+  } else {
+    const script = command('osascript', ['-e', 'return "ready"']);
+    add('osascript', script.status === 0 ? 'PASS' : 'FAIL', script.status === 0 ? 'osascript is available' : 'osascript is unavailable', 'Restore the macOS osascript command on PATH.');
+    const driver = command('cua-driver', ['--version']);
+    add('driver', driver.status === 0 ? 'PASS' : 'FAIL', driver.status === 0 ? text(driver) : 'cua-driver is unavailable', 'Follow docs/cua-driver-install.md and put cua-driver on PATH.');
+    const daemon = command('cua-driver', ['status']);
+    const stopped = /\b(stopped|not running|inactive|disconnected)\b/i.test(text(daemon));
+    add('daemon', daemon.status === 0 && !stopped ? 'PASS' : 'WARN', daemon.status === 0 && !stopped ? 'daemon is running' : 'daemon is stopped; desk starts it on demand', 'Run desk when native control is needed.');
+    const permissions = command('cua-driver', ['permissions', 'status', '--json']);
+    let granted = false;
+    try {
+      const value = JSON.parse(permissions.stdout);
+      const state = value.permissions || value;
+      granted = permissions.status === 0 && state.accessibility === true && state.screen_recording === true;
+    } catch { /* An unreadable status is a failed permission check. */ }
+    add('permissions', granted ? 'PASS' : 'FAIL', granted ? 'Accessibility and Screen Recording are granted' : 'Accessibility or Screen Recording needs approval', 'Run cua-driver permissions grant, approve both permissions, then rerun doctor.');
+    const telemetry = command('cua-driver', ['telemetry', 'status']);
+    let disabled = telemetry.status === 0 && /\bdisabled\b/i.test(text(telemetry));
+    try {
+      const value = JSON.parse(telemetry.stdout);
+      disabled = telemetry.status === 0 && (value.enabled === false || value.telemetry === false || value.status === 'disabled');
+    } catch { /* Text status is also supported. */ }
+    add('telemetry', disabled ? 'PASS' : 'WARN', disabled ? 'telemetry is disabled' : 'telemetry status needs attention', 'Run cua-driver telemetry disable, then cua-driver telemetry status.');
+  }
+  try {
+    const payload = payloadFiles(roots, source).filter(file => file.root === 'dir' || file.path.startsWith('desk/'));
+    const missing = payload.filter(file => {
+      try {
+        const path = safePath(roots[file.root], file.path);
+        return !existsSync(path) || digest(readFileSync(path)) !== digest(file.content);
+      } catch { return true; }
+    });
+    add('installed-files', missing.length ? 'FAIL' : 'PASS', missing.length ? `${missing.length} installed files are missing or changed` : 'skill, agent and desk files match the package', 'Run lean-computer-use install --yes with the same --dir and --share.');
+  } catch (error) {
+    add('installed-files', 'FAIL', `Package files cannot be checked: ${error.message}`, 'Reinstall the npm package, then run lean-computer-use install --yes.');
+  }
+  try {
+    const path = safePath(roots.dir, 'settings.json');
+    const settings = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : {};
+    const registered = hooksRegistered(settings, join(roots.share, 'hooks'), source);
+    add('hooks', registered ? 'PASS' : 'WARN', registered ? 'optional hooks are registered' : 'optional hooks are not registered', 'Run lean-computer-use install --with-hooks --yes with the same --dir and --share.');
+  } catch {
+    add('hooks', 'WARN', 'optional hook registration could not be read', 'Review settings.json, then run lean-computer-use install --with-hooks --yes.');
+  }
+  return { checks, exitCode: checks.some(check => check.status === 'FAIL') ? 1 : 0 };
+}
+
+/** @param {string[]} args @param {Record<string, any>} adapters */
+export function doctorCommand(args = [], adapters = {}) {
+  const options = { json: false };
+  for (const arg of args) {
+    if (arg === '--json') options.json = true;
+    else throw Object.assign(new Error(`Unknown option: ${arg}`), { exitCode: 2 });
+  }
+  const result = doctor(adapters.options || {}, adapters);
+  const write = adapters.write || console.log;
+  if (options.json) write(JSON.stringify(result, null, 2));
+  else for (const check of result.checks) write(`${check.status} ${check.id}: ${check.message}; fix: ${check.fix}`);
+  return result.exitCode;
+}

package/src/hooks-register.mjs

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { packageRoot, shellQuote, safeRelative } from './paths.mjs';
+
+export const hookMarker = 'lean-computer-use';
+const ours = entry => entry?.marker === hookMarker;
+
+export function registrations(hooksDir, source = packageRoot) {
+  const template = readFileSync(join(source, 'hooks/settings-snippet.json'), 'utf8');
+  const result = JSON.parse(template);
+  const events = result.hooks || result;
+  for (const entries of Object.values(events)) {
+    for (const entry of entries) {
+      for (const hook of entry.hooks || []) {
+        if (!hook.command?.includes('__HOOKS_DIR__')) continue;
+        const match = /^(?:["'])?__HOOKS_DIR__\/([^"']+)(?:["'])?$/.exec(hook.command);
+        if (!match) throw new Error('Hook template must name one local shim');
+        hook.command = shellQuote(join(hooksDir, safeRelative(match[1])));
+      }
+    }
+  }
+  return events;
+}
+
+export function mergeHooks(settings, hooksDir, source = packageRoot) {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Settings must be a JSON object');
+  const result = structuredClone(settings);
+  result.hooks ??= {};
+  if (!result.hooks || typeof result.hooks !== 'object' || Array.isArray(result.hooks)) throw new Error('Settings hooks must be an object');
+  for (const [event, entries] of Object.entries(registrations(hooksDir, source))) {
+    const current = result.hooks[event] || [];
+    if (!Array.isArray(current)) throw new Error(`Settings ${event} hooks must be an array`);
+    result.hooks[event] = [...current.filter(entry => !ours(entry)), ...entries.map(entry => ({ ...entry, marker: hookMarker }))];
+  }
+  return result;
+}
+
+export function removeHooks(settings) {
+  const result = structuredClone(settings);
+  if (!result?.hooks || typeof result.hooks !== 'object' || Array.isArray(result.hooks)) return result;
+  for (const [event, entries] of Object.entries(result.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const kept = entries.filter(entry => !ours(entry));
+    if (kept.length) result.hooks[event] = kept;
+    else delete result.hooks[event];
+  }
+  if (!Object.keys(result.hooks).length) delete result.hooks;
+  return result;
+}
+
+export function hooksRegistered(settings, hooksDir, source = packageRoot) {
+  const expected = registrations(hooksDir, source);
+  return Object.entries(expected).every(([event, entries]) => entries.every(entry =>
+    (settings?.hooks?.[event] || []).some(actual => ours(actual) && actual.matcher === entry.matcher &&
+      JSON.stringify(actual.hooks) === JSON.stringify(entry.hooks))));
+}

package/src/install.mjs

@@ -0,0 +1,291 @@
+import { existsSync, readFileSync, writeFileSync, lstatSync, chmodSync, unlinkSync, rmdirSync, readdirSync, openSync, closeSync, constants } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { locations, safePath, safeRelative, ensureDirectory, payloadFiles, digest, packageRoot, shellQuote } from './paths.mjs';
+import { mergeHooks, removeHooks } from './hooks-register.mjs';
+
+const manifestName = 'install-manifest.json';
+const format = value => `${JSON.stringify(value, null, 2)}\n`;
+const hashFile = path => digest(readFileSync(path));
+const fail = (message, exitCode = 2) => Object.assign(new Error(message), { exitCode });
+
+function readJson(path, label) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch { throw fail(`Invalid ${label} JSON: ${path}. Repair the file before continuing.`); }
+}
+
+function captureAnchors(roots) {
+  return Object.fromEntries(Object.entries(roots).map(([root, target]) => {
+    let path = target;
+    let parents = 0;
+    while (!existsSync(path)) { path = dirname(path); parents++; }
+    safePath(path);
+    const stat = lstatSync(path);
+    if (!stat.isDirectory()) throw fail(`Expected a directory: ${path}`);
+    return [root, { parents, identity: { dev: stat.dev, ino: stat.ino } }];
+  }));
+}
+
+export function parseInstallArgs(args) {
+  /** @type {Record<string, any>} */
+  const options = { yes: false, dryRun: false, withHooks: false };
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--yes') options.yes = true;
+    else if (arg === '--dry-run' || arg === '--dry') options.dryRun = true;
+    else if (arg === '--with-hooks') options.withHooks = true;
+    else if (arg === '--dir' || arg === '--share') {
+      const value = args[++index];
+      if (!value || value.startsWith('--')) throw fail(`Missing value for ${arg}`);
+      options[arg.slice(2)] = value;
+    } else throw fail(`Unknown option: ${arg}`);
+  }
+  return options;
+}
+
+function validEntry(entry) {
+  if (!entry || !['dir', 'share'].includes(entry.root)) throw fail('Invalid manifest root');
+  safeRelative(entry.path);
+  const allowed = entry.root === 'dir'
+    ? entry.path.startsWith('skills/lean-computer-use/') || entry.path === 'agents/desk-runner.md' || entry.path === 'settings.json'
+    : entry.path.startsWith('desk/') || entry.path.startsWith('hooks/');
+  if (!allowed || !/^[a-f0-9]{64}$/.test(entry.hash)) throw fail('Invalid manifest entry');
+  if (entry.retainedBackups && !Array.isArray(entry.retainedBackups)) throw fail('Invalid retained backups');
+  for (const backup of [entry.backup, ...(entry.retainedBackups || [])].filter(Boolean)) {
+    safeRelative(backup.path);
+    if (!backup.path.startsWith(`${entry.path}.bak`) || !/^[a-f0-9]{64}$/.test(backup.hash)) throw fail('Invalid manifest backup');
+  }
+}
+
+function directoryPath(roots, directory) {
+  if (!directory.parents) return safePath(roots[directory.root], directory.path);
+  if (directory.path || !Number.isInteger(directory.parents) || directory.parents < 1 || directory.parents > 64) throw fail('Invalid manifest parent directory');
+  let path = roots[directory.root];
+  for (let index = 0; index < directory.parents; index++) {
+    const parent = dirname(path);
+    if (parent === path || dirname(parent) === parent) throw fail('Filesystem root is not an install directory');
+    path = parent;
+  }
+  return safePath(path);
+}
+
+export function readManifest(roots) {
+  const path = safePath(roots.share, manifestName);
+  if (!existsSync(path)) return null;
+  const manifest = readJson(path, 'manifest');
+  if (manifest.version !== 1 || manifest.roots?.dir !== roots.dir || manifest.roots?.share !== roots.share || !Array.isArray(manifest.files) || !Array.isArray(manifest.directories)) throw fail(`Invalid install manifest: ${path}`);
+  for (const root of ['dir', 'share']) {
+    const anchor = manifest.anchors?.[root];
+    if (!anchor || !Number.isInteger(anchor.parents) || anchor.parents < 0 || anchor.parents > 64 || typeof anchor.identity?.dev !== 'number' || typeof anchor.identity?.ino !== 'number') throw fail('Invalid install anchor');
+    let anchorPath = roots[root];
+    for (let index = 0; index < anchor.parents; index++) {
+      if (dirname(anchorPath) === anchorPath) throw fail('Invalid install anchor depth');
+      anchorPath = dirname(anchorPath);
+    }
+    safePath(anchorPath);
+    const stat = lstatSync(anchorPath);
+    if (!stat.isDirectory() || stat.dev !== anchor.identity.dev || stat.ino !== anchor.identity.ino) throw fail('Install anchor changed; review the manifest before uninstalling.');
+  }
+  manifest.files.forEach(validEntry);
+  const seen = new Set();
+  for (const entry of manifest.files) {
+    const id = `${entry.root}:${entry.path}`;
+    if (seen.has(id)) throw fail('Duplicate manifest entry');
+    seen.add(id);
+    safePath(roots[entry.root], entry.path);
+    if (entry.backup) safePath(roots[entry.root], entry.backup.path);
+    for (const backup of entry.retainedBackups || []) safePath(roots[entry.root], backup.path);
+  }
+  for (const directory of manifest.directories) {
+    if (!['dir', 'share'].includes(directory.root)) throw fail('Invalid manifest directory');
+    if (!directory.identity || typeof directory.identity.dev !== 'number' || typeof directory.identity.ino !== 'number') throw fail('Invalid manifest directory identity');
+    if (directory.parents && directory.parents >= manifest.anchors[directory.root].parents) throw fail('Manifest directory escapes its install anchor');
+    if (directory.path) safeRelative(directory.path);
+    const resolved = directoryPath(roots, directory);
+    const owned = directory.parents || resolved === roots[directory.root] || manifest.files.some(entry => {
+      const file = join(roots[entry.root], entry.path);
+      return file.startsWith(`${resolved}/`) || file.startsWith(`${resolved}\\`);
+    });
+    if (!owned) throw fail('Manifest directory is not owned');
+  }
+  return manifest;
+}
+
+function writeChecked(path, content, mode) {
+  safePath(path);
+  if (existsSync(path) && !lstatSync(path).isFile()) throw fail(`Expected a regular file: ${path}`);
+  const descriptor = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | (constants.O_NOFOLLOW || 0), mode);
+  try { writeFileSync(descriptor, content); } finally { closeSync(descriptor); }
+  chmodSync(path, mode);
+}
+
+function backupFor(roots, entry) {
+  const base = `${entry.path}.bak`;
+  let path = base;
+  let index = 1;
+  while (existsSync(safePath(roots[entry.root], path))) path = `${base}.${index++}`;
+  return path;
+}
+
+function directoriesInside(roots, created) {
+  return created.flatMap(path => {
+    const stat = lstatSync(path);
+    const identity = { dev: stat.dev, ino: stat.ino };
+    for (const root of ['dir', 'share']) {
+      const rel = relative(roots[root], path);
+      if (!rel.startsWith('..') && !rel.startsWith('/') && !rel.includes(':')) return [{ root, path: rel.split('\\').join('/'), identity }];
+      let ancestor = roots[root];
+      for (let parents = 1; dirname(ancestor) !== ancestor; parents++) {
+        ancestor = dirname(ancestor);
+        if (ancestor === path) return [{ root, path: '', parents, identity }];
+      }
+    }
+    return [];
+  });
+}
+
+/** @param {string[]} args @param {Record<string, any>} adapters */
+export async function installCommand(args = [], adapters = {}) {
+  const options = parseInstallArgs(args);
+  const write = adapters.write || console.log;
+  const roots = locations(options, adapters.env || process.env);
+  Object.values(roots).forEach(path => safePath(path));
+  const source = adapters.source || packageRoot;
+  const previous = readManifest(roots);
+  const anchors = previous?.anchors || captureAnchors(roots);
+  const files = payloadFiles(roots, source);
+  if (options.withHooks) {
+    const path = safePath(roots.dir, 'settings.json');
+    const current = existsSync(path) ? readJson(path, 'settings') : {};
+    files.push({ root: 'dir', path: 'settings.json', content: Buffer.from(format(mergeHooks(current, join(roots.share, 'hooks'), source))), mode: existsSync(path) ? lstatSync(path).mode & 0o777 : 0o600, settings: true });
+  }
+  const plan = files.map(file => {
+    const path = safePath(roots[file.root], file.path);
+    if (existsSync(path) && !lstatSync(path).isFile()) throw fail(`Expected a regular file: ${path}`);
+    const exists = existsSync(path);
+    return { ...file, absolute: path, hash: digest(file.content), action: !exists ? 'create' : hashFile(path) === digest(file.content) ? 'keep' : 'replace' };
+  });
+  write(`Install plan (${options.dryRun ? 'dry run' : 'preview'}):`);
+  for (const file of plan) write(`${file.action}: ${file.absolute}`);
+  write(`manifest: ${join(roots.share, manifestName)}`);
+  if (options.dryRun) return 0;
+  if (!options.yes && plan.some(file => file.action === 'replace')) throw fail('Replacing a differing file requires --yes. Review --dry-run first.');
+  if (!options.yes) {
+    const input = adapters.input || process.stdin;
+    const output = adapters.output || process.stdout;
+    if (!input.isTTY) throw fail('Install needs confirmation. Review --dry-run, then pass --yes.');
+    const prompt = createInterface({ input, output });
+    let answer;
+    try { answer = await prompt.question('Install these files? [y/N] '); } finally { prompt.close(); }
+    if (!/^y(es)?$/i.test(answer.trim())) { write('Install cancelled.'); return 0; }
+  }
+  const created = [];
+  const records = previous ? [...previous.files] : [];
+  for (const file of plan) {
+    const oldIndex = records.findIndex(entry => entry.root === file.root && entry.path === file.path);
+    const old = oldIndex >= 0 ? records[oldIndex] : null;
+    if (file.action === 'keep' && !old) continue;
+    let backup = old?.backup;
+    const retainedBackups = [...(old?.retainedBackups || [])];
+    if (file.action === 'replace') {
+      if (!backup || hashFile(file.absolute) !== old?.hash) {
+        const backupPath = backupFor(roots, file);
+        const original = readFileSync(safePath(roots[file.root], file.path));
+        const mode = lstatSync(file.absolute).mode & 0o777;
+        writeChecked(safePath(roots[file.root], backupPath), original, mode);
+        if (backup) retainedBackups.push(backup);
+        backup = { path: backupPath, hash: digest(original), mode };
+      }
+    }
+    if (file.action !== 'keep') {
+      ensureDirectory(dirname(file.absolute), created);
+      writeChecked(safePath(roots[file.root], file.path), file.content, file.mode);
+    }
+    const record = { root: file.root, path: file.path, hash: file.hash, mode: file.mode, ...(backup ? { backup } : {}), ...(retainedBackups.length ? { retainedBackups } : {}), ...(file.settings ? { settings: true } : {}) };
+    if (oldIndex >= 0) records[oldIndex] = record;
+    else records.push(record);
+  }
+  ensureDirectory(roots.share, created);
+  const directories = [...(previous?.directories || []), ...directoriesInside(roots, created)];
+  const unique = [...new Map(directories.map(value => [`${value.root}:${value.path}:${value.parents || 0}`, value])).values()];
+  writeChecked(safePath(roots.share, manifestName), format({ version: 1, packageVersion: '0.1.0', roots, anchors, files: records, directories: unique }), 0o600);
+  if (!options.withHooks) {
+    write(`Optional hooks: ${join(roots.share, 'hooks/settings-snippet.json')}`);
+    write(`Merge hooks into ${join(roots.dir, 'settings.json')} with: lean-computer-use install --dir ${shellQuote(roots.dir)} --share ${shellQuote(roots.share)} --with-hooks --yes`);
+  }
+  write('Installed. Run lean-computer-use doctor.');
+  return 0;
+}
+
+/** @param {string[]} args @param {Record<string, any>} adapters */
+export async function uninstallCommand(args = [], adapters = {}) {
+  const options = parseInstallArgs(args);
+  const write = adapters.write || console.log;
+  const roots = locations(options, adapters.env || process.env);
+  const manifest = readManifest(roots);
+  if (!manifest) throw fail(`Install manifest not found: ${join(roots.share, manifestName)}`);
+  const actions = [];
+  for (const entry of manifest.files) {
+    for (const backup of entry.retainedBackups || []) write(`keep backup: ${safePath(roots[entry.root], backup.path)} (earlier user contents; restore manually if needed)`);
+    const path = safePath(roots[entry.root], entry.path);
+    if (!existsSync(path)) {
+      if (entry.backup) write(`keep backup: ${safePath(roots[entry.root], entry.backup.path)} (installed file is missing; restore manually if needed)`);
+      continue;
+    }
+    if (!lstatSync(path).isFile()) throw fail(`Expected a regular file: ${path}`);
+    const matches = hashFile(path) === entry.hash;
+    if (matches) {
+      if (entry.backup) {
+        const backup = safePath(roots[entry.root], entry.backup.path);
+        if (!existsSync(backup) || hashFile(backup) !== entry.backup.hash) {
+          write(`keep: ${path} (backup changed or missing; restore manually)`);
+          continue;
+        }
+        actions.push({ entry, path, kind: 'restore', backup });
+      } else actions.push({ entry, path, kind: 'remove' });
+    } else if (entry.settings) {
+      const settings = readJson(path, 'settings');
+      const cleaned = removeHooks(settings);
+      if (entry.backup) write(`keep backup: ${safePath(roots[entry.root], entry.backup.path)} (settings changed; restore manually if needed)`);
+      actions.push({ entry, path, kind: 'unregister', content: format(cleaned) });
+    } else {
+      write(`keep: ${path} (user-edited file)`);
+      if (entry.backup) write(`keep backup: ${safePath(roots[entry.root], entry.backup.path)} (original user contents; restore manually if needed)`);
+    }
+  }
+  for (const action of actions) write(`${action.kind}: ${action.path}`);
+  write(`remove manifest: ${join(roots.share, manifestName)}`);
+  write('For blocks pasted manually, remove only the entries marked lean-computer-use from your settings.');
+  if (options.dryRun) return 0;
+  for (const action of actions) {
+    const path = safePath(roots[action.entry.root], action.entry.path);
+    if (!existsSync(path)) continue;
+    if (action.kind === 'unregister') {
+      const current = readJson(path, 'settings');
+      writeChecked(path, format(removeHooks(current)), lstatSync(path).mode & 0o777);
+      continue;
+    }
+    if (hashFile(path) !== action.entry.hash) { write(`keep: ${path} (changed during uninstall)`); continue; }
+    if (action.kind === 'restore') {
+      const backup = safePath(roots[action.entry.root], action.entry.backup.path);
+      if (hashFile(backup) !== action.entry.backup.hash) throw fail(`Backup changed: ${backup}`);
+      writeChecked(path, readFileSync(backup), action.entry.backup.mode || 0o644);
+      safePath(roots[action.entry.root], action.entry.backup.path);
+      unlinkSync(backup);
+    } else {
+      safePath(roots[action.entry.root], action.entry.path);
+      unlinkSync(path);
+    }
+  }
+  safePath(roots.share, manifestName);
+  unlinkSync(join(roots.share, manifestName));
+  for (const directory of manifest.directories.sort((a, b) => directoryPath(roots, b).length - directoryPath(roots, a).length)) {
+    const path = directoryPath(roots, directory);
+    if (!existsSync(path)) continue;
+    const stat = lstatSync(path);
+    if (stat.dev !== directory.identity.dev || stat.ino !== directory.identity.ino) { write(`keep directory: ${path} (replaced since install)`); continue; }
+    if (stat.isDirectory() && readdirSync(path).length === 0) { directoryPath(roots, directory); rmdirSync(path); }
+  }
+  write('Uninstalled owned files.');
+  return 0;
+}

package/src/measure.mjs

@@ -0,0 +1,184 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+
+const defaultPattern = '^mcp__(computer-use|cua-driver)__';
+const usageKeys = ['input_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens'];
+const number = value => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+
+function firstWord(command, start = 0) {
+  let value = '';
+  let quote = '';
+  let index = start;
+  while (/\s/.test(command[index] || '') && index < command.length) index++;
+  for (; index < command.length; index++) {
+    const character = command[index];
+    if (character === '\\' && quote !== "'" && index + 1 < command.length) { value += command[++index]; continue; }
+    if (quote) {
+      if (character === quote) quote = '';
+      else value += character;
+    } else if (character === '"' || character === "'") quote = character;
+    else if (/\s|[;&|<>]/.test(character)) break;
+    else value += character;
+  }
+  return { value, end: index };
+}
+
+function commandSegments(command) {
+  const segments = [];
+  let part = '';
+  let quote = '';
+  let escaped = false;
+  let comment = false;
+  let bodies = [];
+  for (let index = 0; index < command.length; index++) {
+    const character = command[index];
+    if (comment && character !== '\n') continue;
+    if (character === '\n') comment = false;
+    if (escaped) { part += character; escaped = false; continue; }
+    if (character === '\\' && quote !== "'") { part += character; escaped = true; continue; }
+    if (quote) { part += character; if (character === quote) quote = ''; continue; }
+    if (character === '"' || character === "'") { quote = character; part += character; continue; }
+    if (character === '#' && (index === 0 || /\s|[;&|]/.test(command[index - 1]))) { comment = true; continue; }
+    if (character === '<' && command[index + 1] === '<' && command[index - 1] !== '<' && command[index + 2] !== '<') {
+      const stripTabs = command[index + 2] === '-';
+      const marker = firstWord(command, index + (stripTabs ? 3 : 2));
+      if (marker.value) bodies.push({ marker: marker.value, stripTabs });
+      part += command.slice(index, marker.end);
+      index = marker.end - 1;
+      continue;
+    }
+    if (/[;&|\n]/.test(character)) {
+      segments.push(part);
+      part = '';
+      if (character === '\n' && bodies.length) {
+        for (const body of bodies) {
+          while (index < command.length) {
+            const next = command.indexOf('\n', index + 1);
+            const end = next < 0 ? command.length : next;
+            const line = command.slice(index + 1, end);
+            index = end;
+            if ((body.stripTabs ? line.replace(/^\t+/, '') : line) === body.marker) break;
+          }
+        }
+        bodies = [];
+      }
+      continue;
+    }
+    part += character;
+  }
+  segments.push(part);
+  return segments;
+}
+
+export function isDeskCommand(command) {
+  if (typeof command !== 'string') return false;
+  return commandSegments(command).some(segment => ['desk', 'desk-read', 'desk-clean'].includes(firstWord(segment).value.split('/').pop()));
+}
+
+export function transcriptFiles(directory) {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap(entry => {
+    if (entry.isSymbolicLink() || ['.git', 'node_modules', '.venv', 'dist', 'build'].includes(entry.name)) return [];
+    const path = join(directory, entry.name);
+    return entry.isDirectory() ? transcriptFiles(path) : entry.isFile() && entry.name.endsWith('.jsonl') ? [path] : [];
+  });
+}
+
+export function groupStats(messages) {
+  const totals = messages.map(message => message.total).sort((a, b) => a - b);
+  const steps = totals.length;
+  const total = totals.reduce((sum, value) => sum + value, 0);
+  const reread = messages.reduce((sum, message) => sum + message.reread, 0);
+  const middle = Math.floor(steps / 2);
+  return {
+    steps,
+    median: !steps ? 0 : steps % 2 ? totals[middle] : (totals[middle - 1] + totals[middle]) / 2,
+    p90: steps ? totals[Math.ceil(steps * 0.9) - 1] : 0,
+    mean: steps ? total / steps : 0,
+    total,
+    rereadShare: total ? reread / total : 0,
+  };
+}
+
+/** @param {{projectsDir?: string, since?: string, toolPattern?: string}} options */
+export function measureTranscripts(options = {}) {
+  const directory = resolve(options.projectsDir || join(homedir(), '.claude/projects'));
+  const pattern = new RegExp(options.toolPattern || defaultPattern);
+  let since = null;
+  if (options.since) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(options.since) || !Number.isFinite(Date.parse(options.since)) || new Date(options.since).toISOString().slice(0, 10) !== options.since) throw new Error('--since needs a date in YYYY-MM-DD form');
+    since = Date.parse(options.since);
+  }
+  const files = transcriptFiles(directory);
+  const messages = new Map();
+  let malformedLines = 0;
+  for (const path of files) {
+    const lines = readFileSync(path, 'utf8').split(/\r?\n/);
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex];
+      if (!line.trim()) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { malformedLines++; continue; }
+      if (!entry || typeof entry !== 'object') continue;
+      const message = entry.message;
+      if (entry.type !== 'assistant' && message?.role !== 'assistant') continue;
+      if (!message || !Array.isArray(message.content)) continue;
+      if (since !== null) {
+        const timestamp = Date.parse(entry.timestamp || message.timestamp || '');
+        if (!Number.isFinite(timestamp) || timestamp < since) continue;
+      }
+      const native = message.content.some(block => {
+        if (block?.type !== 'tool_use') return false;
+        pattern.lastIndex = 0;
+        return typeof block.name === 'string' && (pattern.test(block.name) || block.name === 'Bash' && isDeskCommand(block.input?.command));
+      });
+      const usage = message.usage || {};
+      const total = usageKeys.reduce((sum, key) => sum + number(usage[key]), 0);
+      const reread = number(usage.cache_creation_input_tokens) + number(usage.cache_read_input_tokens);
+      const id = typeof message.id === 'string' && message.id ? message.id : `${path}:${lineIndex}`;
+      const current = messages.get(id);
+      const value = { total, reread, native: native || current?.native || false, sidechain: Boolean(entry.isSidechain) };
+      if (!current || total > current.total) messages.set(id, value);
+      else if (native) current.native = true;
+    }
+  }
+  const values = [...messages.values()].filter(message => message.native);
+  return {
+    files: files.length,
+    malformedLines,
+    main: groupStats(values.filter(message => !message.sidechain)),
+    subagent: groupStats(values.filter(message => message.sidechain)),
+  };
+}
+
+export function parseMeasureArgs(args) {
+  /** @type {Record<string, any>} */
+  const options = { json: false };
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--json') options.json = true;
+    else if (['--projects-dir', '--since', '--tool-pattern'].includes(arg)) {
+      const value = args[++index];
+      if (!value || value.startsWith('--')) throw Object.assign(new Error(`Missing value for ${arg}`), { exitCode: 2 });
+      options[{ '--projects-dir': 'projectsDir', '--since': 'since', '--tool-pattern': 'toolPattern' }[arg]] = value;
+    } else throw Object.assign(new Error(`Unknown option: ${arg}`), { exitCode: 2 });
+  }
+  return options;
+}
+
+/** @param {string[]} args @param {{write?: (line: string) => void}} adapters */
+export function measureCommand(args = [], adapters = {}) {
+  const options = parseMeasureArgs(args);
+  const write = adapters.write || console.log;
+  const result = measureTranscripts(options);
+  if (options.json) { write(JSON.stringify(result, null, 2)); return 0; }
+  if (result.main.steps + result.subagent.steps === 0) { write(`0 native-app steps found in ${result.files} files`); return 0; }
+  write('Group     Steps  Median  P90  Mean  Total  Re-read');
+  for (const group of ['main', 'subagent']) {
+    const value = result[group];
+    write(`${group.padEnd(9)} ${value.steps}      ${value.median}     ${value.p90}  ${Number(value.mean.toFixed(1))}   ${value.total}    ${(value.rereadShare * 100).toFixed(1)}%`);
+  }
+  write(`Files: ${result.files}; malformed lines skipped: ${result.malformedLines}`);
+  return 0;
+}