@extuitive/skill 0.1.0

package/bin/cli.mjs

@@ -0,0 +1,932 @@
+#!/usr/bin/env node
+/**
+ * `npx extuitive install | update | uninstall | doctor`
+ *
+ * Reached through the `extuitive` launcher package (`packages/extuitive`), whose only job is
+ * to import this file; `npx github:fl100inc/extuitive-skill` runs it straight from the repo.
+ *
+ * Argument parsing, prompting, and printing. All the decisions live in `src/`; this file
+ * exists to turn them into something readable in a terminal — and, increasingly, readable by
+ * an agent that will summarise it for a person. That second reader is why the completion
+ * output is a fixed-shape block with one line per fact (skill, server, sign-in) rather than
+ * prose: an agent can repeat three labelled lines faithfully and will paraphrase a paragraph.
+ * `--json` exists for the same reader.
+ *
+ * One rule worth stating: with no `--host` and no TTY, this refuses rather than guessing.
+ * Writing into someone's home directory from a CI job that meant to do nothing of the sort
+ * is not a mistake worth being convenient about.
+ */
+import { createInterface } from "node:readline/promises";
+import process from "node:process";
+
+import {
+  DEFAULT_MCP_ENDPOINT,
+  EXAMPLE_PROMPTS,
+  NPX_COMMAND,
+  PACKAGE_NAME,
+  SKILL_COMMANDS,
+} from "../src/constants.mjs";
+import { detectHosts, displayPath, getHost, HOST_IDS } from "../src/hosts.mjs";
+import {
+  backupsRoot,
+  buildSkillBundles,
+  inspectInstalledSkills,
+  inspectSkillBundles,
+  installSkills,
+  removeSkillBundles,
+  uninstallSkills,
+} from "../src/install.mjs";
+import {
+  authInstructions,
+  manualSteps,
+  registerMcpServer,
+  serverAvailabilityNotice,
+  skillAvailabilityNotice,
+  unregisterMcpServer,
+} from "../src/mcp-setup.mjs";
+import { diagnose, readHostServerStatus } from "../src/doctor.mjs";
+
+const USAGE = `
+${PACKAGE_NAME} — install the Extuitive agent skill and connect it to the Extuitive MCP server.
+
+Usage
+  ${NPX_COMMAND} install [options]
+  ${NPX_COMMAND} update [options]
+  ${NPX_COMMAND} uninstall [options]
+  ${NPX_COMMAND} doctor [options]
+
+Hosts
+  claude          The claude CLI, and the Code tab of the Claude Desktop app.
+  codex           The Codex CLI, the Codex desktop app, and the IDE extension,
+                  which share one config and one skills directory.
+  claude-desktop  The Chat and Cowork tabs of the Claude Desktop app. Skills there
+                  are uploaded to your account rather than copied to disk, so this
+                  builds a .zip and tells you where to add it.
+
+Options
+  --host <name|all>           Which host to set up. Required without a TTY.
+  --scope <user|project>      Install for every project or just this one. Default: user.
+  --dir <path>                Install into this directory instead of the host's default.
+  --endpoint <url>            MCP endpoint. Default: ${DEFAULT_MCP_ENDPOINT}
+  --keep-server               Leave the MCP server registered (uninstall only).
+  --dry-run                   Report what would change without changing anything.
+  --yes, -y                   Accept defaults; never prompt.
+  --json                      Machine-readable output.
+  --help, -h                  Show this message.
+
+Where the skill goes
+  Claude Code     ~/.claude/skills/extuitive
+  Codex           $CODEX_HOME/skills/extuitive   (~/.codex/skills/extuitive)
+  Claude Desktop  ~/.extuitive-skill/bundles/extuitive.zip, for you to upload
+
+update refreshes an install already on this machine and stays quiet when there is
+nothing to do. uninstall removes the skill and the MCP registration; it never
+touches your backups.
+
+Installs one skill, "extuitive", invoked with a command:
+  ${SKILL_COMMANDS.map((command) => `/extuitive ${command}`).join("\n  ")}
+
+No Extuitive account needed in advance — you can create one during sign-in.
+`.trim();
+
+function parseArgs(argv) {
+  const options = {
+    command: null,
+    host: null,
+    scope: "user",
+    dir: null,
+    endpoint: DEFAULT_MCP_ENDPOINT,
+    writeConfig: false,
+    keepServer: false,
+    dryRun: false,
+    yes: false,
+    json: false,
+    help: false,
+  };
+
+  const rest = [...argv];
+  while (rest.length > 0) {
+    const arg = rest.shift();
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+    } else if (arg === "--write-config") {
+      // Accepted and ignored. It used to permit enabling Codex's `[features] skills` flag,
+      // which Codex no longer has. Rejecting it would break every script and README that
+      // still passes it.
+      options.writeConfig = true;
+    } else if (arg === "--keep-server") {
+      options.keepServer = true;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--host") {
+      options.host = rest.shift() ?? null;
+    } else if (arg === "--scope") {
+      options.scope = rest.shift() ?? "user";
+    } else if (arg === "--dir") {
+      options.dir = rest.shift() ?? null;
+    } else if (arg === "--endpoint") {
+      options.endpoint = rest.shift() ?? DEFAULT_MCP_ENDPOINT;
+    } else if (arg.startsWith("-") === true) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (options.command === null) {
+      options.command = arg;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+const COMMANDS = ["install", "update", "uninstall", "doctor"];
+
+function validate(options) {
+  if (options.command !== null && COMMANDS.includes(options.command) === false) {
+    throw new Error(`Unknown command: ${options.command}`);
+  }
+  if (["user", "project"].includes(options.scope) === false) {
+    throw new Error(`--scope must be user or project, got: ${options.scope}`);
+  }
+  // `both` predates there being three hosts. Kept working rather than rejected, because it
+  // is in the README, in shell history, and in whatever notes people wrote down — and it
+  // has only ever meant "all of them".
+  if (options.host !== null && [...HOST_IDS, "all", "both"].includes(options.host) === false) {
+    throw new Error(`--host must be one of ${HOST_IDS.join(", ")}, or all — got: ${options.host}`);
+  }
+  try {
+    new URL(options.endpoint);
+  } catch {
+    throw new Error(`--endpoint is not a valid URL: ${options.endpoint}`);
+  }
+}
+
+const BULLET = "  •";
+
+function heading(text) {
+  console.log(`\n${text}`);
+  console.log("─".repeat(Math.min(text.length, 72)));
+}
+
+function resolveHostIds(options, detections) {
+  if (options.host === "all" || options.host === "both") {
+    return [...HOST_IDS];
+  }
+  if (options.host !== null) {
+    return [options.host];
+  }
+  return detections.filter((detection) => detection.installed === true).map((d) => d.host.id);
+}
+
+/**
+ * Which hosts to set up, asked rather than assumed.
+ *
+ * Every option carries what it covers, because two of the three overlap on one machine: the
+ * Claude Desktop app appears twice, once as its Code tab under Claude Code and once as its
+ * Chat and Cowork tabs. Someone shown a bare "Claude Code / Claude Desktop" pair has no way
+ * to know that, and picking one when they needed both is the mistake this list exists to
+ * prevent.
+ */
+async function promptForHosts(detections) {
+  const installed = detections.filter((detection) => detection.installed === true);
+
+  if (installed.length === 0) {
+    return [];
+  }
+  if (installed.length === 1) {
+    console.log(`Found ${installed[0].host.label} — ${installed[0].host.surfaces}.`);
+    return [installed[0].host.id];
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const labels = installed.map(
+      (detection, index) =>
+        `  ${index + 1}) ${detection.host.label} — ${detection.host.surfaces}`,
+    );
+    console.log("Found more than one host:");
+    console.log(labels.join("\n"));
+    console.log(`  ${installed.length + 1}) All of them`);
+    const answer = (await rl.question("Install into which? [all] ")).trim();
+
+    if (answer === "" || answer === String(installed.length + 1)) {
+      return installed.map((detection) => detection.host.id);
+    }
+    const index = Number.parseInt(answer, 10) - 1;
+    if (Number.isInteger(index) === true && index >= 0 && index < installed.length) {
+      return [installed[index].host.id];
+    }
+    return installed.map((detection) => detection.host.id);
+  } finally {
+    rl.close();
+  }
+}
+
+/* ------------------------------------------------------------------------------------------ */
+/* Setting a host up, as data                                                                  */
+/* ------------------------------------------------------------------------------------------ */
+
+/**
+ * Sign-in, as something we can print without lying about it.
+ *
+ * Install cannot see the host's credential store, so the only states it can honestly claim
+ * are the ones the host reports (`connected`, `needs_auth`) and "we just registered this, so
+ * nobody has signed in yet". Everything else is `unverified`, which is printed with the
+ * sign-in step and a note that it may already be done.
+ */
+function signInState(host, { registration, server }) {
+  const auth = authInstructions(host);
+  const instruction =
+    auth.inSession === true
+      ? `In a new ${host.label} session: ${auth.primary}`
+      : auth.primary;
+
+  if (registration.status === "manual_only") {
+    // Adding the connector and signing in are one flow in the app, so the instruction is
+    // the sign-in half of a step the person has not taken yet.
+    return { state: "in_app", instruction, inSession: false };
+  }
+  if (["skipped_dry_run", "cli_missing", "cli_broken", "failed"].includes(registration.status)) {
+    return { state: "after_registration", instruction, inSession: auth.inSession };
+  }
+  if (server?.state === "connected") {
+    return { state: "connected", instruction, inSession: auth.inSession };
+  }
+  if (server?.state === "needs_auth") {
+    return { state: "needed", instruction, inSession: auth.inSession };
+  }
+  if (registration.status === "registered" && server === null) {
+    // Just registered and no way to ask: nobody has signed in to a server that did not
+    // exist a moment ago.
+    return { state: "needed", instruction, inSession: auth.inSession };
+  }
+  return { state: "unverified", instruction, inSession: auth.inSession };
+}
+
+/**
+ * Put the skill where the host will find it, whichever of the two things that means.
+ *
+ * The returned `bundle` is the archive to be uploaded, or null for a host that reads a
+ * directory. Callers use its presence rather than the host id to decide what to print.
+ */
+async function placeSkills(host, options) {
+  if (host.skillDelivery === "bundle") {
+    const result = await buildSkillBundles(host, {
+      dir: options.dir,
+      dryRun: options.dryRun,
+    });
+    return { ...result, bundle: result.skills[0]?.destination ?? null };
+  }
+
+  const result = await installSkills(host, {
+    scope: options.scope,
+    dir: options.dir,
+    dryRun: options.dryRun,
+  });
+  return { ...result, bundle: null };
+}
+
+/**
+ * Everything install or update does for one host, returned rather than printed.
+ *
+ * `update` differs from `install` in one decision only: it asks the host whether the server
+ * is registered before registering it, because it runs repeatedly and re-adding a server
+ * that exists is a refusal both CLIs print as an error. Install registers unconditionally
+ * and treats "already exists" as success.
+ */
+async function setupHost(host, detection, options, { mode }) {
+  const cliAvailable = detection?.cliAvailable ?? false;
+
+  const skills = await placeSkills(host, options);
+
+  let server = null;
+  let registration;
+
+  if (host.mcpSetup === "connector-ui") {
+    // No side effects on either path: registration is a list of steps and the status is
+    // "cannot be read from here". Asked the same way in both modes so the summary is too.
+    registration = await registerMcpServer(host, { endpoint: options.endpoint, scope: options.scope });
+    server = readHostServerStatus(host, { cliAvailable });
+  } else if (mode === "update") {
+    server = readHostServerStatus(host, { cliAvailable });
+    if (server.state === "absent") {
+      registration = await registerMcpServer(host, {
+        endpoint: options.endpoint,
+        scope: options.scope,
+        dryRun: options.dryRun,
+        cliAvailable,
+      });
+    } else {
+      registration = { status: server.state === "unknown" ? "unknown" : "already_registered", command: null };
+    }
+  } else {
+    registration = await registerMcpServer(host, {
+      endpoint: options.endpoint,
+      scope: options.scope,
+      dryRun: options.dryRun,
+      cliAvailable,
+    });
+    // Asked even after a fresh registration, because a token from an earlier install may
+    // still be in the host's credential store — Codex keeps them in the keychain, keyed by
+    // server, and removing the server does not remove the token. Saying "sign in" to someone
+    // who is signed in is the small lie that makes people distrust the rest.
+    if (["registered", "already_registered"].includes(registration.status) && cliAvailable === true) {
+      server = readHostServerStatus(host, { cliAvailable });
+    }
+  }
+
+  const signIn = signInState(host, { registration, server });
+  const changed = skills.skills.some(
+    (skill) => skill.action !== "unchanged" || (skill.migrated ?? []).length > 0,
+  );
+  const registeredNow = registration.status === "registered";
+
+  return {
+    host: host.id,
+    label: host.label,
+    cli: host.cliResolution,
+    delivery: host.skillDelivery,
+    skillsRoot: skills.destinationRoot,
+    skills: skills.skills,
+    bundle: skills.bundle,
+    registration,
+    server,
+    signIn,
+    availability: {
+      skill: skillAvailabilityNotice(host),
+      server: serverAvailabilityNotice(host),
+    },
+    examples: EXAMPLE_PROMPTS,
+    changed,
+    registeredNow,
+    dryRun: options.dryRun,
+  };
+}
+
+/* ------------------------------------------------------------------------------------------ */
+/* Printing                                                                                    */
+/* ------------------------------------------------------------------------------------------ */
+
+const LABEL_WIDTH = 12;
+const STATE_WIDTH = 15;
+
+function row(label, state, rest = "") {
+  const lead = `  ${label.padEnd(LABEL_WIDTH)}${state.padEnd(STATE_WIDTH)}`;
+  console.log(rest === "" ? lead.trimEnd() : `${lead}${rest}`);
+}
+
+/** A continuation line under a row, aligned with the row's third column. */
+function cont(text) {
+  console.log(`  ${"".padEnd(LABEL_WIDTH + STATE_WIDTH)}${text}`);
+}
+
+function skillStateWord(skill, dryRun, bundled) {
+  if (skill.action === "unchanged") {
+    return "up to date";
+  }
+  const words = bundled === true
+    ? { created: ["built", "would build"], replaced: ["rebuilt", "would rebuild"] }
+    : { created: ["installed", "would install"], replaced: ["updated", "would update"] };
+  return words[skill.action][dryRun === true ? 1 : 0];
+}
+
+function printSkillRows(host, report, options) {
+  const bundled = report.delivery === "bundle";
+
+  // Said rather than passed over. A flag that was accepted and then had no effect is the
+  // kind of thing someone finds out about weeks later, by wondering why a skill they scoped
+  // to one project is available in all of them.
+  if (options.scope === "project" && host.supportsScope === false) {
+    console.log(`  Ignoring --scope project: a ${host.label} skill belongs to your account,`);
+    console.log("  not to a directory, so there is no per-project install to make.");
+  }
+
+  for (const skill of report.skills) {
+    const size = typeof skill.bytes === "number" ? ` (${describeSize(skill.bytes)})` : "";
+    row(bundled === true ? "Bundle" : "Skill", skillStateWord(skill, report.dryRun, bundled), `${displayPath(skill.destination)}${size}`);
+    if (bundled === false) {
+      cont(skill.skillFile);
+    }
+    if (skill.backup !== null) {
+      cont(`previous copy kept at ${displayPath(skill.backup)}`);
+    }
+    for (const move of skill.migrated ?? []) {
+      if (move.action === "removed") {
+        cont(`${report.dryRun ? "would move" : "moved"} from ${displayPath(move.from)}`);
+      } else if (move.action === "backed_up") {
+        cont(
+          `${report.dryRun ? "would move" : "moved"} from ${displayPath(move.from)}` +
+            (move.backup === null ? " (that copy differed; it would be kept in backups)" : ` (that copy differed; kept at ${displayPath(move.backup)})`),
+        );
+      } else {
+        cont(`left a copy at ${displayPath(move.from)} — the new copy could not be verified`);
+      }
+    }
+    if (skill.verified === false) {
+      cont("the installed files do not match the bundled skill; rerun install");
+    }
+  }
+}
+
+function printServerRow(host, report) {
+  const { registration } = report;
+
+  if (registration.status === "manual_only") {
+    // Not a fallback. This host has no CLI and no config file we may write, so the panel
+    // is the install. Saying so keeps it from reading as a refusal.
+    row("Connector", "add in app", "Settings > Connectors > Add custom connector");
+    return;
+  }
+
+  if (registration.status === "registered") {
+    row("MCP server", "registered", registration.command);
+  } else if (registration.status === "already_registered") {
+    row("MCP server", "registered", registration.command === null ? "already there" : `already there (${registration.command})`);
+  } else if (registration.status === "skipped_dry_run") {
+    row("MCP server", "would add", registration.command);
+  } else if (registration.status === "unknown") {
+    row("MCP server", "unknown", report.server?.detail ?? "could not ask the host");
+  } else if (registration.status === "cli_missing") {
+    row("MCP server", "not added", `${host.cli} is not on PATH`);
+  } else if (registration.status === "cli_broken") {
+    row("MCP server", "not added", `${host.cli} does not run — ${registration.detail}`);
+  } else {
+    row("MCP server", "not added", registration.detail);
+  }
+
+  if (["cli_missing", "cli_broken", "failed"].includes(registration.status)) {
+    cont(`Register it yourself: ${registration.command}`);
+    if (registration.manual !== undefined) {
+      cont(`or add to ${displayPath(registration.manual.path)}:`);
+      for (const line of registration.manual.body.trimEnd().split("\n")) {
+        cont(`  ${line}`);
+      }
+    }
+  }
+}
+
+function printSignInRow(report) {
+  const { signIn } = report;
+  if (signIn.state === "connected") {
+    row("Sign-in", "connected", report.server?.detail ?? "");
+    return;
+  }
+  if (signIn.state === "needed") {
+    row("Sign-in", "needed", signIn.instruction);
+  } else if (signIn.state === "in_app") {
+    row("Sign-in", "in the app", signIn.instruction);
+  } else if (signIn.state === "after_registration") {
+    row("Sign-in", "needed", `after registering: ${signIn.instruction}`);
+  } else {
+    row("Sign-in", "unverified", signIn.instruction);
+    cont("If the Extuitive tools already work for you, this is done.");
+  }
+  cont("Opens a browser; only you can complete it.");
+}
+
+/**
+ * The block an installing agent is expected to relay. Three facts, then when each becomes
+ * usable, then what to type. Ordered so the true part ("the skill is available") comes first
+ * and the conditional part ("once you sign in") is attached to the thing it conditions.
+ */
+function printSummary(host, report, options) {
+  printSkillRows(host, report, options);
+  printServerRow(host, report);
+  printSignInRow(report);
+
+  console.log("");
+  const serverRegistered = ["registered", "already_registered"].includes(report.registration.status);
+  if (report.dryRun === true) {
+    console.log("  Nothing was changed.");
+  } else if (report.registration.status === "manual_only") {
+    console.log(`  ${report.availability.skill} ${report.availability.server}`);
+  } else if (report.signIn.state === "connected") {
+    console.log(`  ${report.availability.skill} The Extuitive tools are connected.`);
+  } else if (serverRegistered === true) {
+    console.log(`  ${report.availability.skill} ${report.availability.server}`);
+  } else {
+    console.log(`  ${report.availability.skill} The Extuitive tools need the MCP server registered first (above).`);
+  }
+  if (host.invocationNote !== null) {
+    // Worth stating because the other hosts train the opposite habit: there is no
+    // `/extuitive` here, so the examples below are the whole invocation syntax.
+    console.log(`  ${host.invocationNote}`);
+  }
+  console.log(`  Try: ${report.examples.map((prompt) => `"${prompt}"`).join("  ·  ")}`);
+}
+
+/**
+ * What is left for the person to do, when anything is.
+ *
+ * Two different reasons lead here and they are framed differently. A CLI host lands here
+ * after something went wrong, and "finish this by hand" is the right frame. A connector-UI
+ * host lands here every time, because the panel is the install — and that frame would read
+ * as a failure of an install that worked exactly as designed.
+ */
+function printRemainingSteps(host, report, options) {
+  const manualOptions = { endpoint: options.endpoint, scope: options.scope, bundle: report.bundle };
+  if (report.registration.status === "manual_only") {
+    printManualSteps(host, manualOptions, `Do the rest in ${host.label}:`);
+  } else if (["cli_missing", "cli_broken", "failed"].includes(report.registration.status)) {
+    printManualSteps(host, manualOptions);
+  }
+}
+
+/**
+ * The remaining steps, numbered.
+ *
+ * `lead` is a parameter because the same list arrives two ways. For a CLI host it is a
+ * fallback after something went wrong, and "finish this by hand" is the right frame. For
+ * Claude Desktop it is the entire supported route, and that frame would read as a failure
+ * of an install that worked exactly as designed.
+ */
+function printManualSteps(host, options, lead = `Finish setting up ${host.label} by hand:`) {
+  console.log(`\n  ${lead}`);
+  for (const [index, step] of manualSteps(host, options).entries()) {
+    console.log(`\n  ${index + 1}. ${step.title}`);
+    for (const line of step.body.split("\n")) {
+      console.log(`       ${line}`);
+    }
+  }
+}
+
+/** A bundle size, in the units a person reads a download in. */
+function describeSize(bytes) {
+  if (typeof bytes !== "number") {
+    return "";
+  }
+  return bytes < 1024 ? `${bytes} B` : `${Math.round(bytes / 102.4) / 10} KB`;
+}
+
+function emitJson(command, options, reports) {
+  console.log(JSON.stringify({ command, dryRun: options.dryRun, hosts: reports }, null, 2));
+}
+
+/* ------------------------------------------------------------------------------------------ */
+/* Commands                                                                                    */
+/* ------------------------------------------------------------------------------------------ */
+
+async function commandInstall(options) {
+  const detections = detectHosts();
+  let hostIds = resolveHostIds(options, detections);
+
+  const interactive = process.stdin.isTTY === true && options.yes === false && options.json === false;
+  if (options.host === null) {
+    if (interactive === true) {
+      hostIds = await promptForHosts(detections);
+    } else if (hostIds.length === 0) {
+      throw new Error(
+        `No host detected and no --host given. Pass --host ${HOST_IDS.join(", --host ")}, or --host all.`,
+      );
+    }
+  }
+
+  if (hostIds.length === 0) {
+    console.log("Could not find Claude Code, Codex, or Claude Desktop on this machine.");
+    console.log(`Install one, then run: ${NPX_COMMAND} install`);
+    return 1;
+  }
+
+  const reports = [];
+  for (const hostId of hostIds) {
+    const host = getHost(hostId);
+    const detection = detections.find((candidate) => candidate.host.id === hostId);
+    reports.push({ host, report: await setupHost(host, detection, options, { mode: "install" }) });
+  }
+
+  if (options.json === true) {
+    emitJson("install", options, reports.map((entry) => entry.report));
+    return 0;
+  }
+
+  if (options.dryRun === true) {
+    console.log("Dry run — nothing will be written.");
+  }
+  if (options.writeConfig === true) {
+    console.log("Note: --write-config is no longer needed; Codex skills are on by default.");
+  }
+
+  for (const { host, report } of reports) {
+    heading(`${host.label} — ${host.surfaces}`);
+    printSummary(host, report, options);
+    printRemainingSteps(host, report, options);
+  }
+
+  console.log("\nNo Extuitive account yet? The sign-in page has a Sign up button —");
+  console.log("create one there with a one-time email code, in the same step.");
+  console.log(`\nCheck everything with: ${NPX_COMMAND} doctor`);
+  return 0;
+}
+
+/**
+ * Hosts that already have a copy of the skill, which is not the same set as hosts that exist.
+ *
+ * Update refreshes what is there rather than installing anywhere new: someone who chose
+ * Claude Code only should not acquire a Codex install by running update. An explicit `--host`
+ * overrides that, since naming a host is asking for it. A copy at the previous location
+ * counts — that is exactly the person update exists to move.
+ */
+async function resolveUpdateTargets(options, detections) {
+  if (options.host !== null) {
+    return resolveHostIds(options, detections);
+  }
+
+  const targets = [];
+  for (const detection of detections.filter((candidate) => candidate.installed === true)) {
+    // For a bundle host "already installed" can only mean "a bundle was built here". The
+    // uploaded copy is in an account and cannot be seen from a shell, so a machine that
+    // built one and then had its bundle directory cleared drops out of update — which is
+    // the same conservative answer this gives a host whose skills were deleted by hand.
+    const inspection =
+      detection.host.skillDelivery === "bundle"
+        ? await inspectSkillBundles(detection.host, { dir: options.dir })
+        : await inspectInstalledSkills(detection.host, { scope: options.scope, dir: options.dir });
+
+    const present = inspection.skills.some((skill) => skill.present === true);
+    if (present === true || (inspection.previous ?? []).length > 0) {
+      targets.push(detection.host.id);
+    }
+  }
+  return targets;
+}
+
+/**
+ * Refresh an existing install in place.
+ *
+ * `install` already does the file work correctly and idempotently, so this is deliberately
+ * thin. What makes it a separate command is what it does *not* print: an update is a routine
+ * thing to run repeatedly, and re-issuing the sign-up pitch every time trains people to
+ * ignore all of it. The summary block is short enough to print every time; the extras are
+ * not.
+ */
+async function commandUpdate(options) {
+  const detections = detectHosts();
+  const hostIds = await resolveUpdateTargets(options, detections);
+
+  if (hostIds.length === 0) {
+    if (options.json === true) {
+      emitJson("update", options, []);
+    } else {
+      console.log("The Extuitive skill is not installed here yet.");
+      console.log(`Install it with: ${NPX_COMMAND} install`);
+    }
+    return 1;
+  }
+
+  const reports = [];
+  for (const hostId of hostIds) {
+    const host = getHost(hostId);
+    const detection = detections.find((candidate) => candidate.host.id === hostId);
+    reports.push({ host, report: await setupHost(host, detection, options, { mode: "update" }) });
+  }
+
+  if (options.json === true) {
+    emitJson("update", options, reports.map((entry) => entry.report));
+    return 0;
+  }
+
+  if (options.dryRun === true) {
+    console.log("Dry run — nothing will be written.");
+  }
+
+  for (const { host, report } of reports) {
+    heading(host.label);
+    printSummary(host, report, options);
+    if (report.changed === false && report.registeredNow === false) {
+      console.log("\n  Already up to date.");
+      continue;
+    }
+    // A rebuilt bundle changes nothing until it is uploaded again, so this is the one host
+    // where a successful update still leaves the person with something to do.
+    if (report.bundle !== null && report.changed === true && options.dryRun === false) {
+      console.log(`\n  Upload the new bundle to pick this up: ${displayPath(report.bundle)}`);
+      console.log(`  In ${host.label}: Customize > Skills. Uploading again replaces the old copy.`);
+    }
+  }
+
+  return 0;
+}
+
+async function commandUninstall(options) {
+  const detections = detectHosts();
+  const hostIds = resolveHostIds(options, detections);
+
+  if (hostIds.length === 0) {
+    console.log("No host detected. Nothing to remove.");
+    return 0;
+  }
+
+  if (options.dryRun === true) {
+    console.log("Dry run — nothing will be removed.\n");
+  }
+
+  for (const hostId of hostIds) {
+    const host = getHost(hostId);
+    const detection = detections.find((candidate) => candidate.host.id === hostId);
+    heading(host.label);
+
+    const bundled = host.skillDelivery === "bundle";
+    const result = bundled === true
+      ? await removeSkillBundles(host, { dir: options.dir, dryRun: options.dryRun })
+      : await uninstallSkills(host, { scope: options.scope, dir: options.dir, dryRun: options.dryRun });
+
+    for (const skill of result.skills) {
+      const name = bundled === true ? `${skill.name}.zip` : skill.name;
+      const where = skill.previousLocation === true ? ` from previous location ${displayPath(skill.destination)}` : ` (${displayPath(skill.destination)})`;
+      const verb = skill.action === "removed" && options.dryRun === true ? "would be removed" : skill.action;
+      console.log(`${BULLET} ${name} ${verb}${where}`);
+    }
+
+    if (options.keepServer === true) {
+      console.log(`${BULLET} Left the MCP server registered (--keep-server).`);
+    } else {
+      const removal = await unregisterMcpServer(host, {
+        scope: options.scope,
+        dryRun: options.dryRun,
+        cliAvailable: detection?.cliAvailable ?? false,
+      });
+
+      if (removal.status === "unregistered") {
+        console.log(`${BULLET} Unregistered the MCP server (${removal.command})`);
+      } else if (removal.status === "already_absent") {
+        console.log(`${BULLET} MCP server was not registered`);
+      } else if (removal.status === "skipped_dry_run") {
+        console.log(`${BULLET} Would run: ${removal.command}`);
+      } else if (removal.status === "manual_only") {
+        console.log(`${BULLET} The connector is still there — removing it is a click, not a command:`);
+        for (const step of removal.steps) {
+          console.log(`     ${step}`);
+        }
+      } else if (removal.status === "cli_missing") {
+        console.log(`${BULLET} ${host.cli} is not on PATH, so the server is still registered.`);
+        console.log(`     Remove it yourself: ${removal.command}`);
+      } else if (removal.status === "cli_broken") {
+        console.log(`${BULLET} ${host.cli} does not run (${removal.detail}), so the server is still registered.`);
+        console.log(`     Remove it yourself: ${removal.command}`);
+      } else {
+        console.log(`${BULLET} Could not unregister the MCP server: ${removal.detail}`);
+        console.log(`     Remove it yourself: ${removal.command}`);
+      }
+    }
+
+    // Deleting the bundle removed the archive, not the skill. The skill went to an account
+    // when it was uploaded and is still there, on every device signed into it — so an
+    // uninstall that stopped at the file would be describing a removal that did not happen.
+    if (bundled === true) {
+      console.log(`\n  The uploaded copy is in your Anthropic account, not on this machine.`);
+      console.log(`  Remove it in ${host.label}: Customize > Skills, open extuitive,`);
+      console.log("  then the ... menu and Delete.");
+    }
+
+    // Said plainly because it is the one thing an uninstall cannot finish. The token lives
+    // in the host's own credential store, which is not ours to read or clear, so claiming a
+    // clean removal without mentioning it would be a claim we cannot back.
+    console.log(`\n  Your sign-in is still in ${host.label}'s credential store; that is its`);
+    console.log("  to hold, not ours to clear. Revoking access is done from Extuitive.");
+  }
+
+  console.log(`\nBackups were left alone at ${displayPath(backupsRoot())}`);
+  console.log("They exist because an install found a skill it did not write. Delete them");
+  console.log("yourself once you are sure you do not want them.");
+
+  return 0;
+}
+
+function describeProbe(probe) {
+  if (probe.state === "reachable") {
+    return "reachable, awaiting sign-in";
+  }
+  if (probe.state === "authenticated") {
+    return "reachable and accepting requests";
+  }
+  if (probe.state === "unreachable") {
+    return `unreachable — ${probe.detail}`;
+  }
+  return probe.detail;
+}
+
+async function commandDoctor(options) {
+  const everyHost = options.host === "all" || options.host === "both" || options.host === null;
+  const hostFilter = everyHost === true ? null : [options.host];
+  const report = await diagnose({
+    hosts: hostFilter,
+    scope: options.scope,
+    dir: options.dir,
+    endpoint: options.endpoint,
+  });
+
+  if (options.json === true) {
+    const serializable = {
+      ...report,
+      hosts: report.hosts.map((entry) => ({ ...entry, host: entry.host.id })),
+    };
+    console.log(JSON.stringify(serializable, null, 2));
+    return report.hosts.some((entry) =>
+      entry.problems.some((problem) => problem.advisory !== true),
+    )
+      ? 1
+      : 0;
+  }
+
+  heading("Endpoint");
+  console.log(`  ${report.endpoint}`);
+  console.log(`  ${describeProbe(report.probe)}`);
+
+  if (report.anyHostDetected === false) {
+    console.log("\nNo Claude Code, Codex, or Claude Desktop installation found.");
+    console.log(`Install one, then run: ${NPX_COMMAND} install`);
+    return 1;
+  }
+
+  let blocking = 0;
+
+  for (const entry of report.hosts) {
+    const bundled = entry.host.skillDelivery === "bundle";
+    heading(`${entry.host.label} — ${entry.host.surfaces}`);
+    const cli = entry.cliResolution;
+    if (cli.state !== "none") {
+      console.log(
+        `  ${"CLI".padEnd(10)}${cli.state === "available" ? `${cli.path} (${cli.detail})` : cli.state === "broken" ? `broken — ${cli.detail}` : "not found"}`,
+      );
+    }
+    console.log(`  ${(bundled === true ? "Bundle" : "Skills").padEnd(10)}${displayPath(entry.skillsRoot)}`);
+
+    for (const skill of entry.inspection.skills) {
+      // The two hosts fail differently and so are marked differently. A copied skill is
+      // wrong when its declared name and its directory disagree; a bundle is wrong when it
+      // was built from an older version of the skill than the one in this package.
+      const healthy =
+        skill.present === true && (bundled === true ? skill.current : skill.nameMatches) === true;
+      console.log(`${BULLET} [${healthy === true ? "ok" : "--"}] ${skill.name}`);
+    }
+    for (const copy of entry.previous ?? []) {
+      console.log(`${BULLET} [--] ${copy.name} also at previous location ${displayPath(copy.path)}`);
+    }
+
+    console.log(
+      `  ${(bundled === true ? "Connector" : "Server").padEnd(10)}${entry.server.state} — ${entry.server.detail}`,
+    );
+
+    const real = entry.problems.filter((problem) => problem.advisory !== true);
+    const advisories = entry.problems.filter((problem) => problem.advisory === true);
+    blocking += real.length;
+
+    if (real.length === 0) {
+      console.log("\n  Nothing blocking.");
+    }
+    for (const problem of real) {
+      console.log(`\n  ${problem.what}`);
+      for (const line of problem.fix.split("\n")) {
+        console.log(`    ${line}`);
+      }
+    }
+    for (const advisory of advisories) {
+      console.log(`\n  Note: ${advisory.what}`);
+      console.log(`    ${advisory.fix}`);
+    }
+  }
+
+  console.log("");
+  return blocking === 0 ? 0 : 1;
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+    validate(options);
+  } catch (error) {
+    console.error(`${error.message}\n`);
+    console.error(USAGE);
+    return 2;
+  }
+
+  if (options.help === true || options.command === null) {
+    console.log(USAGE);
+    return options.command === null && options.help === false ? 2 : 0;
+  }
+
+  // Dispatched by name with no fallback. A default of `doctor` would answer a mistyped
+  // command by silently running something else and reporting success.
+  const commands = {
+    install: commandInstall,
+    update: commandUpdate,
+    uninstall: commandUninstall,
+    doctor: commandDoctor,
+  };
+
+  return commands[options.command](options);
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    console.error(`\n${error.message}`);
+    process.exitCode = 1;
+  });