dev-diagnosis-cli 0.1.7 → 0.2.0

package/lib/mcp.mjs

@@ -0,0 +1,271 @@
+/**
+ * MCP server mode: `dev-diagnosis --mcp`.
+ *
+ * A stdio MCP server in the standard library only — the same code the
+ * CLI runs, served over JSON-RPC 2.0, one message per line. Agents
+ * connect with the usual config:
+ *
+ *   { "mcpServers": { "dev-diagnosis": { "command": "dev-diagnosis", "args": ["--mcp"] } } }
+ *
+ * Protocol: `initialize` (2024-11-05), `notifications/initialized`,
+ * `tools/list`, `tools/call`, `ping`. Each tool returns the same JSON
+ * the CLI's --json output produces, so an agent that already knows the
+ * CLI output knows the tool output too.
+ *
+ * Sandbox: `--sandbox <dir>` (alias `--root`) restricts every path the
+ * tools touch to that directory. A path outside it is rejected with a
+ * plain error before anything runs. The `path` tool takes only a
+ * command name, so it has nothing to sandbox and is always allowed.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  UsageError, allJson, applyContextFixAndRescan, rescanContext, runAll,
+  runCacheCheck, runContextCheck, runFlakesCheck, runPathCheck,
+  stripCacheStdout,
+} from './checks.mjs';
+
+export const MCP_PROTOCOL_VERSION = '2024-11-05';
+
+const TOOLS = [
+  {
+    name: 'diagnose_context',
+    description: 'Find the files an AI coding agent should not read in a repo: build output, lockfiles, logs and oversized files. Returns a 0-100 score, the noise found, the token estimate, and the .aiignore suggestions that would fix it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Repo to scan (default: the sandbox root, or the current directory without one).' },
+        fix: { type: 'boolean', description: 'Write the .aiignore suggestions into <path>/.aiignore.' },
+      },
+    },
+  },
+  {
+    name: 'diagnose_path',
+    description: 'Diagnose why a CLI command is missing: one row per shell context (current, login, non-login, daemon-like), shadowed copies, toolchain installs, and a copy-paste fix.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'Command to look up, for example "node".' },
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'diagnose_cache',
+    description: 'Time one build command cold (cache moved aside) and warm (cache present) and say whether the cache pays. The cache directory is restored afterwards.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Project directory to run the build in (default: the sandbox root, or the current directory without one).' },
+        command: { type: 'array', items: { type: 'string' }, description: 'Build command as an argv array, for example ["node", "build.mjs"].' },
+        cacheDir: { type: 'string', description: 'Cache directory to measure (default: auto-detected under the project).' },
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'diagnose_flakes',
+    description: 'Rank flaky tests from JUnit XML across CI runs, including passed-on-retry. Each subdirectory of the runs directory is one run; each *.xml file directly under it is a run of its own.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Runs directory to scan.' },
+        top: { type: 'integer', description: 'Show only the N highest-ranked flaky tests.' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'diagnose_all',
+    description: 'Run every check that has what it needs and print one unified report: context always runs, path runs with a command name, flakes with a runs directory, cache with a build command. Checks without their input are listed as skipped.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Repo to diagnose (default: the sandbox root, or the current directory without one).' },
+        command: { type: 'string', description: 'Command name for the path check, for example "node".' },
+        flakesDir: { type: 'string', description: 'JUnit runs directory for the flakes check.' },
+        buildCommand: { type: 'array', items: { type: 'string' }, description: 'Build command as an argv array for the cache check.' },
+        cacheDir: { type: 'string', description: 'Cache directory to measure (default: auto-detected).' },
+        fix: { type: 'boolean', description: 'Write the context check .aiignore suggestions.' },
+        top: { type: 'integer', description: 'Show only the N highest-ranked flaky tests.' },
+      },
+    },
+  },
+];
+
+/** Resolve a tool argument to an absolute path inside the sandbox, or throw. */
+export function resolveInSandbox(sandbox, value, label) {
+  if (value == null || value === '') return sandbox || process.cwd();
+  const resolved = path.resolve(sandbox || process.cwd(), value);
+  if (!sandbox) return resolved;
+  const root = path.resolve(sandbox);
+  if (resolved === root) return resolved;
+  const rel = path.relative(root, resolved);
+  if (rel.startsWith(`..${path.sep}`) || rel === '..' || path.isAbsolute(rel)) {
+    throw new Error(`${label} is outside the sandbox (${sandbox}): ${value}`);
+  }
+  return resolved;
+}
+
+function textResult(payload) {
+  return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: false };
+}
+
+function errorResult(message) {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+function callTool(name, args, sandbox) {
+  const input = args && typeof args === 'object' ? args : {};
+  switch (name) {
+    case 'diagnose_context': {
+      const target = resolveInSandbox(sandbox, input.path, 'path');
+      const check = runContextCheck(target);
+      // With fix, the tool answers with the post-fix scan — an agent
+      // reading the result needs to know whether the repo is fixed
+      // now, not what it scored before the fix.
+      if (input.fix) return textResult(applyContextFixAndRescan(check).result);
+      return textResult(check.result);
+    }
+    case 'diagnose_path': {
+      if (!input.command) throw new UsageError('diagnose_path needs a command');
+      return textResult(runPathCheck(input.command).result);
+    }
+    case 'diagnose_cache': {
+      if (!Array.isArray(input.command) || input.command.length === 0) {
+        throw new UsageError('diagnose_cache needs a build command array');
+      }
+      const root = resolveInSandbox(sandbox, input.path, 'path');
+      const cacheDir = input.cacheDir
+        ? resolveInSandbox(sandbox, path.resolve(root, input.cacheDir), 'cacheDir')
+        : undefined;
+      const check = runCacheCheck({ buildCommand: input.command, cacheDir, cwd: root });
+      return textResult(stripCacheStdout(check.result));
+    }
+    case 'diagnose_flakes': {
+      if (!input.path) throw new UsageError('diagnose_flakes needs a runs directory');
+      const dir = resolveInSandbox(sandbox, input.path, 'path');
+      const check = runFlakesCheck(dir);
+      const out = input.top != null ? { ...check.result, tests: check.result.tests.slice(0, input.top) } : check.result;
+      return textResult(out);
+    }
+    case 'diagnose_all': {
+      const root = resolveInSandbox(sandbox, input.path, 'path');
+      // flakesDir is relative to the sandbox (or cwd), like the CLI's
+      // --flakes is relative to the process cwd — not to the repo root.
+      const flakesDir = input.flakesDir
+        ? resolveInSandbox(sandbox, input.flakesDir, 'flakesDir')
+        : null;
+      // cacheDir is relative to the repo root, like the CLI's
+      // --cache-dir.
+      const cacheDir = input.cacheDir
+        ? resolveInSandbox(sandbox, path.resolve(root, input.cacheDir), 'cacheDir')
+        : null;
+      const run = runAll({
+        root,
+        commandName: input.command || null,
+        flakesDir,
+        buildCommand: Array.isArray(input.buildCommand) && input.buildCommand.length > 0 ? input.buildCommand : null,
+        cacheDir,
+      });
+      if (input.fix) {
+        run.applyContextFix();
+        rescanContext(run);
+      }
+      return textResult(allJson(run, input.top != null ? input.top : null));
+    }
+    default:
+      throw new Error(`unknown tool: ${name}`);
+  }
+}
+
+function handleMessage(message, sandbox, version) {
+  if (message == null || typeof message !== 'object' || Array.isArray(message)) {
+    return { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid Request' } };
+  }
+  const { method, id, params } = message;
+  // A notification (no id) never gets a response.
+  const isNotification = id === undefined;
+  if (typeof method !== 'string') {
+    return isNotification ? null : { jsonrpc: '2.0', id: id ?? null, error: { code: -32600, message: 'Invalid Request' } };
+  }
+  if (method.startsWith('notifications/')) return null;
+  if (isNotification) return null;
+
+  const respond = (result) => ({ jsonrpc: '2.0', id, result });
+  const fail = (code, text) => ({ jsonrpc: '2.0', id, error: { code, message: text } });
+
+  try {
+    switch (method) {
+      case 'initialize':
+        return respond({
+          protocolVersion: MCP_PROTOCOL_VERSION,
+          capabilities: { tools: {} },
+          serverInfo: { name: 'dev-diagnosis', version },
+        });
+      case 'ping':
+        return respond({});
+      case 'tools/list':
+        return respond({ tools: TOOLS });
+      case 'tools/call': {
+        if (!params || typeof params.name !== 'string') return fail(-32602, 'tools/call needs a tool name');
+        try {
+          return respond(callTool(params.name, params.arguments, sandbox));
+        } catch (error) {
+          // A tool failure is a tool result with isError, not a
+          // JSON-RPC error: the call itself worked, the check did not.
+          return respond(errorResult(error.message));
+        }
+      }
+      default:
+        return fail(-32601, `Method not found: ${method}`);
+    }
+  } catch (error) {
+    return fail(-32603, error.message);
+  }
+}
+
+/**
+ * Serve MCP over stdio until stdin closes. One JSON message per line;
+ * a malformed line gets a -32700 parse error and the server keeps going.
+ * Resolves when stdin ends; never throws for a bad message.
+ */
+export function runMcpServer(options = {}) {
+  const sandbox = options.sandbox ? path.resolve(options.sandbox) : null;
+  const version = options.version || '0.2.0';
+  if (sandbox) {
+    let stat;
+    try { stat = fs.statSync(sandbox); } catch { stat = null; }
+    if (!stat || !stat.isDirectory()) throw new Error(`sandbox is not a directory: ${sandbox}`);
+  }
+  let buffer = '';
+  const write = (payload) => process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    let newline = buffer.indexOf('\n');
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).replace(/\r$/, '');
+      buffer = buffer.slice(newline + 1);
+      if (line.trim() === '') {
+        newline = buffer.indexOf('\n');
+        continue;
+      }
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+        newline = buffer.indexOf('\n');
+        continue;
+      }
+      const response = handleMessage(message, sandbox, version);
+      if (response) write(response);
+      newline = buffer.indexOf('\n');
+    }
+  });
+  return new Promise((resolve) => {
+    process.stdin.on('end', resolve);
+    process.stdin.resume();
+  });
+}

package/lib/report.mjs

@@ -16,3 +16,15 @@ export function formatMs(ms) {
   if (ms < 1000) return `${Math.round(ms)} ms`;
   return `${(ms / 1000).toFixed(2)} s`;
 }
+
+/** Short form for a token estimate: 420, 4.2k, 1.2M. */
+export function formatTokens(tokens) {
+  if (tokens == null) return '—';
+  if (tokens < 1000) return String(tokens);
+  if (tokens < 1000000) {
+    const value = tokens / 1000;
+    return `${value >= 100 ? Math.round(value) : value.toFixed(1).replace(/\.0$/, '')}k`;
+  }
+  const value = tokens / 1000000;
+  return `${value >= 100 ? Math.round(value) : value.toFixed(1).replace(/\.0$/, '')}M`;
+}

package/lib/setup.mjs

@@ -0,0 +1,249 @@
+/**
+ * One-command install: `dev-diagnosis setup`.
+ *
+ * Detects which agents are installed on this machine and writes the MCP
+ * config that wires dev-diagnosis into each of them — Claude Code,
+ * Codex CLI, Cursor and VS Code. The command always shows a preview of
+ * exactly what would be written before it writes anything, and it
+ * never silently overwrites:
+ *
+ * - a config that already mentions dev-diagnosis is reported as
+ *   already wired and left alone;
+ * - a config that exists without it is merged (other entries kept) and
+ *   the change is reported;
+ * - a missing config is created with just the dev-diagnosis entry.
+ *
+ * A config file that cannot be parsed is left alone and reported as an
+ * error for that agent — the tool never rewrites a file it cannot read.
+ * TOML (Codex) is appended to, never rewritten: only the
+ * `[mcp_servers.dev-diagnosis]` section is added when it is absent.
+ *
+ * Detection is by config file or by the agent's CLI being on PATH, so
+ * an agent with no config yet still gets one. The MCP entry itself is
+ * the same shape the README documents: command `dev-diagnosis`, args
+ * `["--mcp"]`. If `dev-diagnosis` is not on PATH, setup warns that the
+ * agents will not be able to run it until it is installed globally.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { lookupCommand } from './pathcheck.mjs';
+
+export const MCP_COMMAND = 'dev-diagnosis';
+export const MCP_ARGS = ['--mcp'];
+export const MCP_ENTRY = { command: MCP_COMMAND, args: MCP_ARGS };
+
+export function mcpEntryJson() {
+  return { mcpServers: { 'dev-diagnosis': MCP_ENTRY } };
+}
+
+export function vscodeSettingsPath(home) {
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json');
+  }
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    return path.join(appData, 'Code', 'User', 'settings.json');
+  }
+  return path.join(home, '.config', 'Code', 'User', 'settings.json');
+}
+
+/**
+ * The agents setup knows about. Each entry describes where its MCP
+ * config lives and how it is stored. `configPath` is a function of
+ * the home directory so tests can point it at a temp dir.
+ */
+export function agentDefs(home) {
+  return [
+    {
+      id: 'claude-code',
+      name: 'Claude Code',
+      binaries: ['claude'],
+      format: 'json',
+      configPath: path.join(home, '.claude.json'),
+      mergeKey: ['mcpServers'],
+    },
+    {
+      id: 'codex',
+      name: 'Codex CLI',
+      binaries: ['codex'],
+      format: 'toml',
+      configPath: path.join(home, '.codex', 'config.toml'),
+      mergeKey: null,
+    },
+    {
+      id: 'cursor',
+      name: 'Cursor',
+      binaries: ['cursor'],
+      format: 'json',
+      configPath: path.join(home, '.cursor', 'mcp.json'),
+      mergeKey: ['mcpServers'],
+    },
+    {
+      id: 'vscode',
+      name: 'VS Code',
+      binaries: ['code'],
+      format: 'json',
+      configPath: vscodeSettingsPath(home),
+      mergeKey: ['mcp', 'servers'],
+    },
+  ];
+}
+
+function binaryOnPath(name, pathEnv) {
+  return lookupCommand(name, pathEnv || process.env.PATH || '').resolved;
+}
+
+function readJsonFile(file) {
+  try {
+    return { data: JSON.parse(fs.readFileSync(file, 'utf8')), error: null };
+  } catch (error) {
+    return { data: null, error: error.message };
+  }
+}
+
+function nestedGet(obj, keys) {
+  let current = obj;
+  for (const key of keys) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+function nestedSet(obj, keys, value) {
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i += 1) {
+    if (current[keys[i]] == null || typeof current[keys[i]] !== 'object') current[keys[i]] = {};
+    current = current[keys[i]];
+  }
+  current[keys[keys.length - 1]] = value;
+  return obj;
+}
+
+function tomlSection() {
+  return '[mcp_servers.dev-diagnosis]\ncommand = "dev-diagnosis"\nargs = ["--mcp"]\n';
+}
+
+function hasTomlEntry(content) {
+  return /^\s*\[mcp_servers\.dev-diagnosis\]/m.test(content);
+}
+
+/**
+ * Detect installed agents. `options` takes { home, pathEnv } so tests
+ * can point detection at a temp HOME without touching the real one.
+ * An agent counts as installed when its config file exists or its CLI
+ * is on PATH. Returns one row per agent: { id, name, format,
+ * configPath, detected, via } where via is 'config', 'binary' or
+ * 'config+binary'.
+ */
+export function detectAgents(options = {}) {
+  const home = options.home || os.homedir();
+  const pathEnv = options.pathEnv !== undefined ? options.pathEnv : process.env.PATH || '';
+  return agentDefs(home).map((def) => {
+    const hasConfig = fs.existsSync(def.configPath);
+    const hasBinary = def.binaries.some((name) => binaryOnPath(name, pathEnv));
+    const via = hasConfig && hasBinary ? 'config+binary' : hasConfig ? 'config' : hasBinary ? 'binary' : null;
+    return { ...def, detected: hasConfig || hasBinary, via };
+  });
+}
+
+/**
+ * Work out what setup would do for each detected agent, without
+ * writing anything. Returns { agents, commandOnPath } where each agent
+ * row carries:
+ *   status: 'already-wired' | 'merge' | 'create' | 'unreadable'
+ *   preview: the exact text that would be written or added (for
+ *     'merge' on JSON, the added entry; for 'create', the full file)
+ *   note: human-readable explanation for unreadable configs.
+ */
+export function planSetup(options = {}) {
+  const home = options.home || os.homedir();
+  const agents = detectAgents({ home, pathEnv: options.pathEnv }).filter((agent) => agent.detected);
+  const commandOnPath = binaryOnPath(MCP_COMMAND, options.pathEnv !== undefined ? options.pathEnv : process.env.PATH || '');
+  const planned = agents.map((agent) => {
+    const row = { id: agent.id, name: agent.name, format: agent.format, configPath: agent.configPath, mergeKey: agent.mergeKey };
+    if (agent.format === 'toml') {
+      if (!fs.existsSync(agent.configPath)) {
+        return { ...row, status: 'create', preview: tomlSection() };
+      }
+      const content = fs.readFileSync(agent.configPath, 'utf8');
+      if (hasTomlEntry(content)) return { ...row, status: 'already-wired', preview: null };
+      return { ...row, status: 'merge', preview: tomlSection() };
+    }
+    // JSON formats: merge under mergeKey, never touch other entries.
+    if (!fs.existsSync(agent.configPath)) {
+      const data = nestedSet({}, agent.mergeKey, { 'dev-diagnosis': MCP_ENTRY });
+      return { ...row, status: 'create', preview: `${JSON.stringify(data, null, 2)}\n` };
+    }
+    const { data, error } = readJsonFile(agent.configPath);
+    if (error) {
+      return { ...row, status: 'unreadable', preview: null, note: `could not parse ${agent.configPath}: ${error} — left alone` };
+    }
+    const existing = nestedGet(data, agent.mergeKey);
+    if (existing && typeof existing === 'object' && existing['dev-diagnosis'] !== undefined) {
+      return { ...row, status: 'already-wired', preview: null };
+    }
+    if (existing !== undefined && (existing === null || typeof existing !== 'object')) {
+      return { ...row, status: 'unreadable', preview: null, note: `${agent.mergeKey.join('.')} in ${agent.configPath} is not an object — left alone` };
+    }
+    return { ...row, status: 'merge', preview: JSON.stringify({ 'dev-diagnosis': MCP_ENTRY }, null, 2) };
+  });
+  return { agents: planned, commandOnPath };
+}
+
+/**
+ * Carry out a plan from planSetup(). Writes only 'merge' and 'create'
+ * rows; 'already-wired' and 'unreadable' rows are reported and left
+ * alone. Returns one result per agent: { id, name, configPath,
+ * action: 'already-wired' | 'merged' | 'created' | 'unreadable',
+ * detail }.
+ */
+export function applySetup(plan) {
+  return plan.agents.map((row) => {
+    const base = { id: row.id, name: row.name, configPath: row.configPath };
+    if (row.status === 'already-wired') return { ...base, action: 'already-wired', detail: 'dev-diagnosis is already in this config' };
+    if (row.status === 'unreadable') return { ...base, action: 'unreadable', detail: row.note };
+    fs.mkdirSync(path.dirname(row.configPath), { recursive: true });
+    if (row.format === 'toml') {
+      if (row.status === 'create') {
+        fs.writeFileSync(row.configPath, row.preview);
+        return { ...base, action: 'created', detail: 'created with the dev-diagnosis MCP server entry' };
+      }
+      const existing = fs.readFileSync(row.configPath, 'utf8');
+      const joined = existing.endsWith('\n') || existing === '' ? `${existing}${row.preview}` : `${existing}\n${row.preview}`;
+      fs.writeFileSync(row.configPath, joined);
+      return { ...base, action: 'merged', detail: 'appended [mcp_servers.dev-diagnosis] to the existing config' };
+    }
+    if (row.status === 'create') {
+      fs.writeFileSync(row.configPath, row.preview);
+      return { ...base, action: 'created', detail: 'created with the dev-diagnosis MCP server entry' };
+    }
+    const { data } = readJsonFile(row.configPath);
+    nestedSet(data, [...row.mergeKey, 'dev-diagnosis'], MCP_ENTRY);
+    fs.writeFileSync(row.configPath, `${JSON.stringify(data, null, 2)}\n`);
+    return { ...base, action: 'merged', detail: 'added dev-diagnosis under the existing MCP servers, other entries kept' };
+  });
+}
+
+/**
+ * Report which detected agents are wired and which are not. Returns
+ * { rows, detected, allWired } where each row is { id, name,
+ * configPath, wired }. An agent with an unreadable config counts as
+ * not wired.
+ */
+export function checkSetup(options = {}) {
+  const plan = planSetup(options);
+  const rows = plan.agents.map((row) => ({
+    id: row.id,
+    name: row.name,
+    configPath: row.configPath,
+    wired: row.status === 'already-wired',
+    status: row.status,
+  }));
+  return {
+    rows,
+    detected: rows.length,
+    allWired: rows.length > 0 && rows.every((row) => row.wired),
+  };
+}

package/lib/skill.mjs

@@ -0,0 +1,81 @@
+/**
+ * Agent Skills generation: `dev-diagnosis --skill-generate`.
+ *
+ * Writes a Claude Agent Skills SKILL.md that tells an agent to run
+ * dev-diagnosis when it starts work in a repo, read the verdicts, fix
+ * what fails, and re-run to confirm. Default scope is --project
+ * (./.claude/skills/dev-diagnosis/SKILL.md); --global writes
+ * ~/.claude/skills/dev-diagnosis/SKILL.md instead.
+ *
+ * Never overwrites: if the SKILL.md already exists, generation stops
+ * with a plain message and the caller exits 1 — the file may hold the
+ * user's own edits.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const SKILL_DIR_NAME = 'dev-diagnosis';
+
+export const SKILL_MD = `---
+name: dev-diagnosis
+description: Diagnose a repo before working in it — context noise that wastes tokens, missing commands, build-cache value, flaky tests. Run when starting work in a repository, after a build or test failure, or when an agent session feels slow.
+---
+
+# dev-diagnosis
+
+Run this before reading a repo, and again after fixing what it finds.
+
+## When to use it
+
+- Starting work in a repository you have not diagnosed yet.
+- An agent session feels slow, or the context looks full of files it should not be reading.
+- A build is slow, a command is missing, or tests keep failing on retry.
+
+## Run it
+
+\`\`\`sh
+dev-diagnosis all
+\`\`\`
+
+If the command is not installed, use \`npx dev-diagnosis-cli\` instead. Run it in the repo directory; pass a path to diagnose another one (\`dev-diagnosis all ./other-repo\`).
+
+## Read the verdicts
+
+- **context FAIL** — the repo has noise an AI agent should not read (build output, lockfiles, logs, oversized files). The report lists the files and the token estimate. Fix it with \`dev-diagnosis context --fix\`, which writes the suggestions into \`.aiignore\`, then re-run \`dev-diagnosis all\` to confirm the score is 100/100.
+- **path FAIL** — a command is missing in the current shell. The report says which shell contexts have it and prints a copy-paste fix; apply the fix, then re-run.
+- **flakes FAIL** — the report ranks the flaky tests. Look at the top-ranked test first; a test marked \`new\` broke recently, \`chronic\` has been unstable for a while.
+- **cache FAIL** — the verdict says whether the build cache pays. If it costs more than it saves, the cache setup is the problem, not the build.
+
+Skipped checks are not failures: they just need their input
+(\`--command <name>\` for path, \`--flakes <runs-dir>\` for flakes,
+\`-- <build-command>\` for cache).
+
+## Rules
+
+- Fix what FAILs before starting the real work; a 75/100 repo costs real tokens on every turn.
+- Always re-run \`dev-diagnosis all\` after a fix and confirm it passes.
+- Never edit \`.aiignore\` by hand to hide a failure you have not read — the file is the record of what the agent agreed not to read.
+`;
+
+export function skillPath(scope = 'project', base = process.cwd()) {
+  if (scope === 'global') {
+    return path.join(os.homedir(), '.claude', 'skills', SKILL_DIR_NAME, 'SKILL.md');
+  }
+  return path.join(path.resolve(base), '.claude', 'skills', SKILL_DIR_NAME, 'SKILL.md');
+}
+
+/**
+ * Write the SKILL.md. Returns `{ path, created: true }` on success,
+ * or `{ path, created: false, reason }` when the file already exists —
+ * the caller prints the reason and exits 1.
+ */
+export function generateSkill(scope = 'project', base = process.cwd()) {
+  const target = skillPath(scope, base);
+  if (fs.existsSync(target)) {
+    return { path: target, created: false, reason: `already exists: ${target}` };
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, SKILL_MD);
+  return { path: target, created: true };
+}

package/package.json

@@ -38,8 +38,8 @@
   },
   "scripts": {
     "example": "node examples/demo.mjs",
-    "test": "node --test"
+    "test": "node --test --test-concurrency=1"
   },
   "type": "module",
-  "version": "0.1.7"
+  "version": "0.2.0"
 }