@smartspec/cli 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# SmartSpec
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plan systems and define the contracts between them, with your own AI. SmartSpec is a desktop app that your AI connects to over MCP.
+
+This package is the `smartspec` command.
+
+SmartSpec must be installed in your Applications folder: that's where `setup` and your agents expect it. If you download it from the [releases](https://github.com/tw050x/smartspec/releases/latest), drag it into Applications.
+
+## Install the app
+
+```sh
+npx @smartspec/cli install
+```
+
+Downloads the latest SmartSpec for your Mac from the project's [GitHub releases](https://github.com/tw050x/smartspec/releases), checks it against the release's checksum, and puts it in Applications (asking before it replaces an older one), then offers to set up your agents. Once installed, SmartSpec keeps itself up to date.
+
+## Set up your agents
+
+```sh
+npx @smartspec/cli setup
+```
+
+Finds SmartSpec in your Applications folder and adds it to Claude Desktop and Claude Code, asking before each. (`--yes` doesn't ask.) Claude Desktop's settings file keeps everything else in it, and a copy of the file as it was is saved beside it. Agents run the connection built into the app, so they don't need Node.js once they're set up. You can do the same from the app: click its MCP server status, at the top right.
+
+## Wait for the user
+
+```sh
+npx @smartspec/cli wait proposal --id <id>
+```
+
+Stays until the user has accepted or discarded a proposal, then prints what happened and exits. AI apps that can run commands in the background use it to carry on as soon as the user is done; SmartSpec's tools give them the exact command. `wait --help` lists its exit codes.
+
+## Check the connection
+
+```sh
+npx @smartspec/cli doctor
+```
+
+Checks that SmartSpec is installed and answering, and that Claude Desktop and Claude Code are set up for it where it is now, and says what to fix.
+
+## Run the connection with npx
+
+For agents you'd rather set up with `npx`, the command `npx -y @smartspec/cli mcp` runs SmartSpec's MCP connection. It opens the installed app when your agent first uses it, wherever the app is, and if the app isn't installed it tells your agent where to send you. For example:
+
+```sh
+claude mcp add --scope user smartspec -- npx -y @smartspec/cli mcp
+```
+
+## Requirements
+
+- macOS (Apple silicon or Intel); Windows is planned.
+- Node.js 18 or later, which runs `npx`.

package/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// The smartspec command (npx @smartspec/cli <command>): installs the SmartSpec app, sets up AI apps to
+// use it, checks the connection, and runs SmartSpec's MCP connection for agents set up with npx.
+
+const HELP = `Usage: npx @smartspec/cli <command>
+
+Commands:
+  install [--yes] Download the latest SmartSpec app into Applications, then offer setup
+  setup [--yes]   Add SmartSpec to Claude Desktop and Claude Code (asks first; --yes doesn't)
+  doctor          Check SmartSpec and its connections, and say what to fix
+  mcp             Run SmartSpec's MCP connection (what agents set up with npx run)
+  wait            Stay until the user has done what an AI is waiting for (wait --help)
+
+SmartSpec itself is a Mac app: install it with the install command, or download it from
+https://github.com/tw050x/smartspec/releases/latest.`;
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (command === 'mcp') {
+  await import('./mcp.js');
+} else if (command === 'wait') {
+  const { WAIT_HELP, wait } = await import('./lib/wait.js');
+  if (rest.includes('--help') || rest.includes('-h')) console.log(WAIT_HELP);
+  else process.exitCode = await wait(rest);
+} else if (['install', 'setup', 'doctor'].includes(command)) {
+  const commands = await import('./lib/commands.js');
+  const ask = commands.terminalAsk({ yes: rest.includes('--yes') || rest.includes('-y') });
+  try {
+    process.exitCode = await commands[command]({ ask });
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+} else {
+  console.log(HELP);
+  process.exitCode = command && !['help', '--help', '-h'].includes(command) ? 1 : 0;
+}

package/lib/agents.js

@@ -0,0 +1,89 @@
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+// Setting up AI apps to reach SmartSpec, shared by the app (its MCP panel, see the app's
+// connect.js) and the smartspec command (setup and doctor). Each AI app runs `entry`: SmartSpec's
+// MCP launcher (mcp.js), which is inside the app, run with the app's own executable as Node, so
+// the AI app needs nothing else installed.
+
+// The entry for an installed app, from its bundle's path.
+export function launcherFor(appBundle) {
+  return {
+    command: path.join(appBundle, 'Contents', 'MacOS', 'SmartSpec'),
+    args: [path.join(appBundle, 'Contents', 'Resources', 'cli', 'mcp.js')],
+    env: { ELECTRON_RUN_AS_NODE: '1' },
+  };
+}
+
+// A word for a shell, quoted only if it needs it.
+const shellWord = (word) => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`);
+
+// Each AI app knows SmartSpec by `name`: smartspec, or smartspec-dev for a development copy, so the
+// two can be set up side by side.
+
+// Claude Code's command to add it, for every project (user scope).
+export const claudeCodeCommand = ({ command, args, env }, name = 'smartspec') => [
+  `claude mcp add --scope user ${name}`,
+  ...Object.entries(env).map(([k, v]) => `-e ${shellWord(`${k}=${v}`)}`),
+  '--',
+  ...[command, ...args].map(shellWord),
+].join(' ');
+
+// The JSON config entry that Claude Desktop and most other agents take.
+export const configJson = (entry, name = 'smartspec') => JSON.stringify({ mcpServers: { [name]: entry } }, null, 2);
+
+// --- Claude Desktop ---------------------------------------------------------------------------
+
+// Claude Desktop keeps its MCP servers in this file. Tests and development point SmartSpec at
+// another with SMARTSPEC_CLAUDE_CONFIG (which the packaged app ignores), so they never touch the
+// real one.
+export function claudeDesktopConfig({ env = process.env, home = os.homedir(), allowOverride = true } = {}) {
+  if (allowOverride && env.SMARTSPEC_CLAUDE_CONFIG) return path.resolve(env.SMARTSPEC_CLAUDE_CONFIG);
+  return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+}
+
+// The config file's contents: {} if there's no file yet; null if it isn't JSON SmartSpec can
+// safely change (then it's left alone).
+async function readConfig(file) {
+  let text;
+  try {
+    text = await fs.readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    return null;
+  }
+  if (!text.trim()) return {};
+  try {
+    const config = JSON.parse(text);
+    return config && typeof config === 'object' && !Array.isArray(config) ? config : null;
+  } catch {
+    return null;
+  }
+}
+
+// Where Claude Desktop stands: 'not-installed' (no Claude Desktop folder), 'unreadable' (its config
+// file isn't JSON), 'not-added', 'added', or 'different' (SmartSpec is set up differently, say from
+// before the app moved).
+export async function claudeDesktopStatus(file, entry, name = 'smartspec') {
+  if (!existsSync(path.dirname(file))) return { state: 'not-installed' };
+  const config = await readConfig(file);
+  if (!config) return { state: 'unreadable', file };
+  const current = config.mcpServers?.[name];
+  if (!current) return { state: 'not-added' };
+  return { state: isDeepStrictEqual(current, entry) ? 'added' : 'different' };
+}
+
+// Adds SmartSpec to Claude Desktop's config file, or brings its entry up to date, keeping
+// everything else in the file. The file as it was is copied beside it first.
+export async function addToClaudeDesktop(file, entry, name = 'smartspec') {
+  const config = await readConfig(file);
+  if (!config) throw new Error(`Claude Desktop’s settings file isn’t in a form SmartSpec can safely change, so it was left alone: ${file}`);
+  if (existsSync(file)) await fs.copyFile(file, `${file}.before-smartspec`);
+  const updated = { ...config, mcpServers: { ...(config.mcpServers ?? {}), [name]: entry } };
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify(updated, null, 2)}\n`);
+  return claudeDesktopStatus(file, entry, name);
+}

package/lib/apps.js

@@ -0,0 +1,38 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { APP_ID, APP_NAME } from './platform.js';
+
+// Finding the installed SmartSpec app, for the smartspec command's setup and doctor.
+
+const run = promisify(execFile);
+
+// Copies that aren't installed: on a disk image, in the Bin, or a download kept by an earlier
+// version's launcher.
+const notInstalled = (p) => p.startsWith('/Volumes/') || p.includes('/.Trash/') || p.includes('/Library/Caches/');
+
+// The installed app's bundle: the one in Applications if there is one, else wherever macOS has
+// seen one (Spotlight, by the app's ID). Null if there's none.
+export async function findApp({ home = os.homedir() } = {}) {
+  for (const p of [`/Applications/${APP_NAME}.app`, path.join(home, 'Applications', `${APP_NAME}.app`)]) {
+    if (existsSync(p)) return p;
+  }
+  try {
+    const { stdout } = await run('mdfind', [`kMDItemCFBundleIdentifier == '${APP_ID}'`]);
+    return stdout.split('\n').map((p) => p.trim()).find((p) => p.endsWith('.app') && !notInstalled(p)) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// The app's version, from its Info.plist; null if it can't be read.
+export async function appVersion(appBundle) {
+  try {
+    const { stdout } = await run('plutil', ['-extract', 'CFBundleShortVersionString', 'raw', path.join(appBundle, 'Contents', 'Info.plist')]);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}

package/lib/bridge.js

@@ -0,0 +1,136 @@
+import { randomUUID } from 'node:crypto';
+import readline from 'node:readline';
+import { mcpUrl } from './platform.js';
+
+// Carries MCP messages between an AI app, which talks to this launcher over stdio (one JSON-RPC
+// message per line), and the app's MCP server over HTTP. The first message the app has to
+// answer opens it, and waits until it's running. If the app goes away (say the user quits it),
+// the next message opens it again.
+//
+// `ensure()` makes sure the app is running; `token()` reads its current token.
+//
+// With `offline` (server.json: what the app's server says about itself, see
+// scripts/server-snapshot.mjs), the bridge answers the AI app's handshake itself, and its requests
+// for the lists of tools and prompts until the app is running, so an AI app isn't kept waiting,
+// and nothing is opened until the AI uses a tool.
+export function runBridge({ input = process.stdin, output = process.stdout, env = process.env, ensure, token, log = () => {}, offline = null, version = '0.0.0', heartbeatMs = 20000 }) {
+  let ready = null;
+  let running = false;
+  // This connection's session, which keeps its own window in the app; the AI app's name for itself,
+  // to show there; and whether this launcher started the app, so the session has the window it opened.
+  const session = randomUUID();
+  let client = null;
+  let startedApp = false;
+  let heartbeat = null;
+  const whenReady = () => (ready ??= ensure().then((started) => {
+    running = true;
+    if (started) startedApp = true;
+    heartbeat ??= setInterval(() => notify('alive').catch(() => {}), heartbeatMs);
+    heartbeat.unref?.();
+  }, (error) => {
+    ready = null; // try again with the next message
+    throw error;
+  }));
+
+  const write = (message) => output.write(`${JSON.stringify(message)}\n`);
+  const fail = (id, message) => id !== undefined && write({ jsonrpc: '2.0', id, error: { code: -32000, message } });
+  const answer = (id, result) => write({ jsonrpc: '2.0', id, result });
+
+  // The reply the bridge gives itself, if it does, to a message the app would otherwise answer.
+  function local(message) {
+    if (!offline) return undefined;
+    const { method, params } = message;
+    if (method === 'initialize') {
+      const asked = params?.protocolVersion;
+      return {
+        protocolVersion: offline.protocolVersions.includes(asked) ? asked : offline.protocolVersions[0],
+        capabilities: offline.capabilities,
+        serverInfo: { name: 'smartspec', version },
+        instructions: offline.instructions,
+      };
+    }
+    if (running) return undefined;
+    if (method === 'ping') return {};
+    if (method === 'tools/list') return { tools: offline.tools };
+    if (method === 'prompts/list') return { prompts: offline.prompts };
+    return undefined;
+  }
+
+  const sessionHeaders = () => ({
+    'x-smartspec-session': session,
+    ...(client && { 'x-smartspec-client': client }),
+    ...(startedApp && { 'x-smartspec-started-app': '1' }),
+  });
+  // Tells the app about the session itself, once it's running.
+  async function notify(what) {
+    const res = await fetch(`${mcpUrl(env)}/${what}`, { method: 'POST', headers: { authorization: `Bearer ${token()}`, ...sessionHeaders() } });
+    await res.body?.cancel();
+  }
+
+  async function post(line) {
+    const res = await fetch(mcpUrl(env), {
+      method: 'POST',
+      headers: { ...sessionHeaders(), 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: `Bearer ${token() ?? ''}` },
+      body: line,
+    });
+    return { status: res.status, text: (await res.text()).trim() };
+  }
+
+  async function forward(line, message) {
+    await whenReady();
+    let reply;
+    try {
+      reply = await post(line);
+    } catch {
+      // Nothing listening: the app was closed since. Open it again and retry once.
+      ready = null;
+      running = false;
+      await whenReady();
+      reply = await post(line);
+    }
+    if (reply.status >= 400) {
+      let reason = `The app refused the request (HTTP ${reply.status}).`;
+      try {
+        reason = JSON.parse(reply.text).error ?? reason;
+      } catch {}
+      return fail(message.id, reason);
+    }
+    if (reply.text) output.write(`${reply.text}\n`);
+  }
+
+  const pending = new Set();
+  const lines = readline.createInterface({ input });
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    // Notifications (no id) mean nothing to the app's server until it's running: it keeps no state
+    // between requests.
+    if (offline && message.id === undefined && !running) return;
+    if (message.method === 'initialize' && typeof message.params?.clientInfo?.name === 'string') {
+      client = message.params.clientInfo.name.replace(/[^\w .-]/g, '').slice(0, 60) || null;
+    }
+    const reply = local(message);
+    if (reply !== undefined) return answer(message.id, reply);
+    const job = forward(line, message).catch((error) => {
+      log(error.message);
+      // A tool call gets the reason as its result, which the AI reads and can pass on (say, that
+      // the app isn't installed).
+      if (message.method === 'tools/call') answer(message.id, { isError: true, content: [{ type: 'text', text: error.message }] });
+      else fail(message.id, error.message);
+    });
+    pending.add(job);
+    job.finally(() => pending.delete(job));
+  });
+
+  // The AI app has gone: so has this session.
+  return new Promise((resolve) => lines.on('close', () => Promise.allSettled([...pending]).then(async () => {
+    clearInterval(heartbeat);
+    if (running) await notify('end').catch(() => {});
+    resolve();
+  })));
+}

package/lib/claude-code.js

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+// Claude Code, through its own `claude mcp` commands (it keeps its MCP servers itself).
+
+const run = promisify(execFile);
+
+// Whether the claude command is on this computer.
+export async function hasClaudeCode() {
+  try {
+    await run('claude', ['--version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// SmartSpec's entry in Claude Code: null if there's none, else what `claude mcp get` says about it.
+export async function claudeCodeEntry() {
+  try {
+    const { stdout } = await run('claude', ['mcp', 'get', 'smartspec'], { timeout: 60 * 1000 });
+    return stdout;
+  } catch {
+    return null; // `claude mcp get` fails when there's no such server
+  }
+}
+
+// Whether that entry runs `entry`.
+export const claudeCodeRuns = (details, entry) => Boolean(details?.includes(entry.command) && details.includes(entry.args[0]));
+
+// Adds SmartSpec for every project (user scope), replacing an entry it had.
+export async function addToClaudeCode(entry, { replace = false } = {}) {
+  if (replace) await run('claude', ['mcp', 'remove', 'smartspec']);
+  await run('claude', ['mcp', 'add-json', '--scope', 'user', 'smartspec', JSON.stringify({ type: 'stdio', ...entry })]);
+}

package/lib/commands.js

@@ -0,0 +1,180 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { addToClaudeDesktop, claudeDesktopConfig, claudeDesktopStatus, launcherFor } from './agents.js';
+import { appVersion, findApp } from './apps.js';
+import { addToClaudeCode, claudeCodeEntry, claudeCodeRuns, hasClaudeCode } from './claude-code.js';
+import { appRunning, installDir, installRelease, latestRelease, quitApp } from './install.js';
+import { probe } from './launch.js';
+import { APP_NAME, DOWNLOAD_PAGE } from './platform.js';
+
+// The smartspec command's install, setup and doctor. install puts the latest release of the app
+// in Applications, then offers setup. setup and doctor find the installed app, then look at each
+// AI app SmartSpec can set up itself (Claude Desktop and Claude Code): setup adds SmartSpec to them,
+// asking first; doctor only looks, and says what to fix. `out` is where they write;
+// `ask(question)` resolves true for yes.
+
+const ok = (text) => `  ✓ ${text}`;
+const bad = (text) => `  ✗ ${text}`;
+const note = (text) => `    ${text}`;
+
+// The installed app and the entry for it, or a reason there's none.
+async function installedApp() {
+  const app = await findApp();
+  if (!app) return { problem: `${APP_NAME} isn't installed. Install it with: npx @smartspec/cli install (or download it from ${DOWNLOAD_PAGE}), then run this again.` };
+  const version = await appVersion(app);
+  return { app, version, entry: launcherFor(app) };
+}
+
+// Asks on the terminal; with --yes, or with no terminal to ask on, says yes.
+export function terminalAsk({ yes = false } = {}) {
+  return async (question) => {
+    if (yes || !process.stdin.isTTY) return true;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+    rl.close();
+    return answer === '' || answer === 'y' || answer === 'yes';
+  };
+}
+
+// The download's progress on one line of the terminal, if there is one.
+function progressLine(stream = process.stdout) {
+  if (!stream.isTTY) return { update() {}, done() {} };
+  let shown = -1;
+  return {
+    update(received, total) {
+      const percent = total ? Math.floor((received / total) * 100) : null;
+      if (percent === shown) return;
+      shown = percent;
+      const mb = (n) => Math.round(n / 1e6);
+      stream.write(`\r  ${percent ?? '…'}%  ${mb(received)}${total ? ` of ${mb(total)}` : ''} MB   `);
+    },
+    done: () => stream.write('\r\x1b[K'),
+  };
+}
+
+export async function install({ out = console.log, ask = terminalAsk() } = {}) {
+  if (process.platform !== 'darwin') {
+    out(`${APP_NAME} runs on macOS for now.`);
+    return 1;
+  }
+  const { version, zip } = await latestRelease();
+  if (!zip) {
+    out(`The latest release (${version}) has no build for this Mac (${process.arch}).`);
+    return 1;
+  }
+  const dir = await installDir();
+  const target = path.join(dir, `${APP_NAME}.app`);
+  const current = existsSync(target) ? await appVersion(target) : null;
+  if (current === version) out(ok(`${APP_NAME} ${version} is already installed in ${target}`));
+  else {
+    if (existsSync(target) && !(await ask(`Replace ${APP_NAME} ${current ?? ''} in ${dir} with ${version}?`))) {
+      out('Left as it is.');
+      return 0;
+    }
+    if (await appRunning()) {
+      if (!(await ask(`${APP_NAME} is open. Quit it, to install ${version}?`))) {
+        out(`Quit ${APP_NAME}, then run this again.`);
+        return 1;
+      }
+      await quitApp();
+    }
+    out(`Downloading ${APP_NAME} ${version} for this Mac…`);
+    const line = progressLine();
+    try {
+      await installRelease(zip, dir, { progress: line.update });
+    } finally {
+      line.done();
+    }
+    out(ok(`Installed ${APP_NAME} ${version} in ${target}`));
+  }
+  if (await ask('\nSet up Claude Desktop and Claude Code to use it now?')) {
+    out('');
+    return setup({ out, ask });
+  }
+  out('Set them up later with: npx @smartspec/cli setup');
+  return 0;
+}
+
+export async function setup({ out = console.log, ask = terminalAsk() } = {}) {
+  const found = await installedApp();
+  if (found.problem) {
+    out(found.problem);
+    return 1;
+  }
+  out(`Setting up ${APP_NAME} ${found.version} (${found.app}).`);
+  let failed = false;
+
+  out('\nClaude Desktop');
+  const file = claudeDesktopConfig();
+  const desktop = await claudeDesktopStatus(file, found.entry);
+  if (desktop.state === 'not-installed') out(note('Not on this Mac.'));
+  else if (desktop.state === 'added') out(ok('Already set up.'));
+  else if (desktop.state === 'unreadable') {
+    out(bad(`Its settings file isn't in a form SmartSpec can safely change, so it was left alone: ${file}`));
+    failed = true;
+  } else if (await ask(`  ${desktop.state === 'different' ? 'Update SmartSpec in' : 'Add SmartSpec to'} Claude Desktop's settings (a copy of the file is kept)?`)) {
+    await addToClaudeDesktop(file, found.entry);
+    out(ok('Done. Quit Claude Desktop and open it again to connect.'));
+  } else out(note('Skipped.'));
+
+  out('\nClaude Code');
+  if (!(await hasClaudeCode())) out(note('Not on this computer (no claude command).'));
+  else {
+    const details = await claudeCodeEntry();
+    if (claudeCodeRuns(details, found.entry)) out(ok('Already set up.'));
+    else if (await ask(`  ${details ? 'Replace SmartSpec’s setup in' : 'Add SmartSpec to'} Claude Code, for all your projects?`)) {
+      try {
+        await addToClaudeCode(found.entry, { replace: Boolean(details) });
+        out(ok('Done. Start a new Claude Code session to connect.'));
+      } catch (error) {
+        out(bad(`Claude Code didn't take it: ${error.stderr?.trim() || error.message}`));
+        failed = true;
+      }
+    } else out(note('Skipped.'));
+  }
+
+  out(`\nFor other agents, open ${APP_NAME} and click its MCP server status, at the top right.`);
+  return failed ? 1 : 0;
+}
+
+export async function doctor({ out = console.log } = {}) {
+  let problems = 0;
+  const fail = (text, fix) => {
+    problems++;
+    out(bad(text));
+    if (fix) out(note(fix));
+  };
+
+  out(`${APP_NAME}`);
+  const found = await installedApp();
+  if (found.problem) {
+    fail(found.problem);
+    return 1;
+  }
+  out(ok(`${APP_NAME} ${found.version} is installed in ${found.app}`));
+  const state = await probe();
+  if (state === 'up') out(ok(`${APP_NAME} is running, and its MCP server answers`));
+  else if (state === 'locked') fail(`Something answers on SmartSpec's port, but not with SmartSpec's token`, 'Quit SmartSpec and open it again.');
+  else out(note(`${APP_NAME} isn't running. That's fine: your agent opens it when it needs it.`));
+
+  out('\nClaude Desktop');
+  const desktop = await claudeDesktopStatus(claudeDesktopConfig(), found.entry);
+  if (desktop.state === 'not-installed') out(note('Not on this Mac.'));
+  else if (desktop.state === 'added') out(ok('Set up for SmartSpec where it is now'));
+  else if (desktop.state === 'not-added') fail('SmartSpec isn’t set up in Claude Desktop', 'Run: npx @smartspec/cli setup');
+  else if (desktop.state === 'different') fail('Claude Desktop is set up for SmartSpec somewhere else (or the old way)', 'Run: npx @smartspec/cli setup');
+  else fail(`Its settings file isn't valid JSON: ${desktop.file}`, 'Fix or remove the file, then run: npx @smartspec/cli setup');
+
+  out('\nClaude Code');
+  if (!(await hasClaudeCode())) out(note('Not on this computer (no claude command).'));
+  else {
+    const details = await claudeCodeEntry();
+    if (claudeCodeRuns(details, found.entry)) out(ok('Set up for SmartSpec where it is now'));
+    else if (details) fail('Claude Code is set up for SmartSpec somewhere else (or the old way)', 'Run: npx @smartspec/cli setup');
+    else fail('SmartSpec isn’t set up in Claude Code', 'Run: npx @smartspec/cli setup');
+  }
+
+  out(problems ? `\n${problems} thing${problems === 1 ? '' : 's'} to fix.` : '\nAll good.');
+  return problems ? 1 : 0;
+}