@synsci/thesis 0.1.0

package/src/cli.mjs

@@ -0,0 +1,1111 @@
+import { Command } from "commander";
+import inquirer from "inquirer";
+import ora from "ora";
+import pc from "picocolors";
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+
+import {
+  ALL_HOST_NAMES,
+  SERVER_NAME,
+  SETUP_HOST_NAMES,
+  detectHosts,
+  getHost,
+  normalizeHosts,
+} from "./agents.mjs";
+import {
+  appendTomlServer,
+  mergeServerEntry,
+  readNamedConfigEntry,
+  readJsonConfig,
+  readTomlServerEntry,
+  readYamlConfig,
+  removeCodexTomlServer,
+  removeJsonServerEntry,
+  resolveMcpPath,
+  writeJsonConfig,
+  writeYamlConfig,
+} from "./mcp-writer.mjs";
+import {
+  acquireApiKeyViaBrowserBridge,
+  acquireApiKeyViaDeviceFlow,
+  resolveSetupAuthMode,
+} from "./setup-auth.mjs";
+import {
+  cleanupInstalledSkillArtifactsForHosts,
+  formatSupportedInstallSkillHosts,
+  inspectInstalledSkillArtifactsForHosts,
+  installBundledSkillForHosts,
+  listBundledSkills,
+  partitionInstallSkillHosts,
+  resolveInstalledSkillDir,
+  resolvePackageRoot,
+} from "./skill-installer.mjs";
+
+const INSTALL_SKILL_BASE_URL = "https://thesis.syntheticsciences.ai";
+const DEFAULT_BASE_URL =
+  process.env.THESIS_PUBLIC_BASE_URL || INSTALL_SKILL_BASE_URL;
+const NON_INTERACTIVE_SKILL_DECISION_ERROR =
+  "Non-interactive setup requires one of --install-skill or --skip-skill.";
+const MUTUALLY_EXCLUSIVE_SKILL_FLAGS_ERROR =
+  "--install-skill and --skip-skill cannot be used together.";
+const GUIDED_SKILL_DECISION_TEST_ENV =
+  "THESIS_GUIDED_SKILL_DECISION_FOR_TESTS";
+const ENABLE_TEST_SEAMS_ENV = "THESIS_ENABLE_TEST_SEAMS";
+
+const log = {
+  info: (message) => console.log(pc.cyan(message)),
+  warn: (message) => console.log(pc.yellow(`Warning: ${message}`)),
+  error: (message) => console.log(pc.red(`Error: ${message}`)),
+  plain: (message) => console.log(message),
+  blank: () => console.log(""),
+};
+
+const CHECKBOX_THEME = {
+  style: {
+    highlight: (text) => pc.green(text),
+    disabledChoice: (text) => ` ${pc.dim("o")} ${pc.dim(text)}`,
+  },
+};
+
+function normalizeBaseUrl(value) {
+  const normalized = String(value || "").trim();
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(normalized);
+  } catch {
+    throw new Error("Base URL must be a valid absolute URL.");
+  }
+
+  if (parsedUrl.pathname !== "/" || parsedUrl.search || parsedUrl.hash) {
+    throw new Error(
+      "Base URL must be a public Thesis origin without a path, query, or hash.",
+    );
+  }
+
+  return parsedUrl.origin;
+}
+
+function normalizeServerName(value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    throw new Error("Server name cannot be empty.");
+  }
+  return normalized;
+}
+
+function normalizeAuthMode(value) {
+  const normalized = String(value || "auto")
+    .trim()
+    .toLowerCase();
+  if (
+    normalized === "auto" ||
+    normalized === "loopback" ||
+    normalized === "device"
+  ) {
+    return normalized;
+  }
+  throw new Error("Auth mode must be one of: auto, loopback, device.");
+}
+
+function selectedHostsFromOptions(options) {
+  const hosts = [];
+  if (options.claude) hosts.push("claude");
+  if (options.opencode) hosts.push("opencode");
+  if (options.codex) hosts.push("codex");
+  if (options.cursor) hosts.push("cursor");
+  if (options.piMono) hosts.push("pi-mono");
+  if (options.hermesAgent) hosts.push("hermes-agent");
+  if (options.openclaw) hosts.push("openclaw");
+  return hosts;
+}
+
+function parseHostsList(value) {
+  if (!value) return [];
+  return normalizeHosts(
+    String(value)
+      .split(",")
+      .map((item) => item.trim())
+      .filter(Boolean),
+  );
+}
+
+function mcpCandidatesForScope(host, scope) {
+  if (scope === "global") return host.mcp.globalPaths;
+  return host.mcp.projectPaths.map((candidate) =>
+    path.join(process.cwd(), candidate),
+  );
+}
+
+async function isAlreadyConfigured(hostName, scope, serverName) {
+  const existingState = await readExistingServerState(
+    hostName,
+    scope,
+    serverName,
+  );
+  return existingState.exists;
+}
+
+async function readExistingServerState(hostName, scope, serverName) {
+  const host = getHost(hostName);
+  const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
+
+  if (host.mcp.configType === "toml") {
+    const { exists, url } = await readTomlServerEntry(mcpPath, serverName);
+    return { exists, url, mcpPath };
+  }
+
+  const existing =
+    host.mcp.configType === "yaml"
+      ? await readYamlConfig(mcpPath)
+      : await readJsonConfig(mcpPath);
+  const entry = readNamedConfigEntry(
+    existing,
+    host.mcp.configKey,
+    serverName,
+  );
+  return {
+    exists: entry !== null,
+    url: typeof entry?.url === "string" ? entry.url : null,
+    mcpPath,
+  };
+}
+
+async function inspectInstallSkillHosts({
+  hostNames,
+  scope,
+  serverName,
+  serverUrl,
+}) {
+  const hostStates = new Map();
+  const needsSetupHosts = [];
+  const driftHosts = [];
+
+  for (const hostName of hostNames) {
+    // eslint-disable-next-line no-await-in-loop
+    const existingState = await readExistingServerState(
+      hostName,
+      scope,
+      serverName,
+    );
+    if (!existingState.exists) {
+      needsSetupHosts.push(hostName);
+      hostStates.set(hostName, {
+        classification: "needs-setup",
+        mcpPath: existingState.mcpPath,
+      });
+      continue;
+    }
+
+    if (existingState.url === serverUrl) {
+      hostStates.set(hostName, {
+        classification: "matching",
+        mcpPath: existingState.mcpPath,
+      });
+      continue;
+    }
+
+    driftHosts.push({
+      hostName,
+      mcpPath: existingState.mcpPath,
+      existingUrl: existingState.url ?? "(missing URL)",
+    });
+    hostStates.set(hostName, {
+      classification: "drift",
+      mcpPath: existingState.mcpPath,
+    });
+  }
+
+  return { hostStates, needsSetupHosts, driftHosts };
+}
+
+function formatInstallSkillDriftError({
+  hostName,
+  scope,
+  serverName,
+  existingUrl,
+  requestedUrl,
+}) {
+  const host = getHost(hostName);
+  const scopeFlag =
+    scope === "project" ? "--scope project" : "--scope global";
+  return `Thesis MCP entry '${serverName}' for ${host.displayName} already points to ${existingUrl}, not ${requestedUrl}. Run 'thesis uninstall ${scopeFlag} --${hostName} --name ${serverName}' first or choose a different --name.`;
+}
+
+function getGuidedSkillDecisionOverrideForTests() {
+  const testSeamsEnabled =
+    String(process.env[ENABLE_TEST_SEAMS_ENV] || "").trim() === "1";
+  if (!testSeamsEnabled) {
+    return "";
+  }
+
+  const normalizedGuidedDecisionOverride = String(
+    process.env[GUIDED_SKILL_DECISION_TEST_ENV] || "",
+  )
+    .trim()
+    .toLowerCase();
+  if (normalizedGuidedDecisionOverride.length === 0) {
+    return "";
+  }
+  if (
+    normalizedGuidedDecisionOverride === "accept" ||
+    normalizedGuidedDecisionOverride === "decline" ||
+    normalizedGuidedDecisionOverride === "abort"
+  ) {
+    return normalizedGuidedDecisionOverride;
+  }
+
+  throw new Error(
+    `${GUIDED_SKILL_DECISION_TEST_ENV} must be one of: accept, decline, abort.`,
+  );
+}
+
+async function promptHosts(scope, detected, serverName) {
+  const choices = await Promise.all(
+    ALL_HOST_NAMES.map(async (hostName) => {
+      const configured = await isAlreadyConfigured(
+        hostName,
+        scope,
+        serverName,
+      ).catch(() => false);
+      return {
+        name: SETUP_HOST_NAMES[hostName],
+        value: hostName,
+        checked: detected.includes(hostName),
+        disabled: configured ? "(already configured)" : false,
+      };
+    }),
+  );
+
+  if (choices.every((choice) => Boolean(choice.disabled))) {
+    log.info("Thesis is already configured for all detected hosts.");
+    return null;
+  }
+
+  try {
+    const { selectedHosts } = await inquirer.prompt([
+      {
+        type: "checkbox",
+        name: "selectedHosts",
+        message: "Which hosts do you want to set up?",
+        choices,
+        loop: false,
+        validate: (selected) =>
+          selected.length > 0 || "Select at least one host.",
+      },
+    ]);
+    return selectedHosts;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveHosts(
+  options,
+  scope,
+  serverName,
+  allowPrompt = true,
+) {
+  const explicit = selectedHostsFromOptions(options);
+  if (explicit.length > 0) return explicit;
+
+  const detected = await detectHosts(scope);
+  const promptDisabled =
+    options.yes || process.stdout.isTTY !== true || !allowPrompt;
+  if (detected.length > 0 && promptDisabled) {
+    return detected;
+  }
+
+  if (promptDisabled) {
+    log.warn(
+      "No hosts were detected for prompt-free setup. Pass explicit host flags such as --codex.",
+    );
+    return [];
+  }
+
+  log.blank();
+  const selected = await promptHosts(scope, detected, serverName);
+  if (!selected) {
+    log.warn("Setup cancelled");
+    return [];
+  }
+  return selected;
+}
+
+async function resolveApiKey(options, baseUrl) {
+  if (Object.hasOwn(options, "apiKey")) {
+    const normalizedApiKey = String(options.apiKey || "").trim();
+    if (normalizedApiKey.length === 0) {
+      throw new Error("--api-key cannot be empty.");
+    }
+    return normalizedApiKey;
+  }
+
+  const requestedAuthMode = normalizeAuthMode(options.authMode || "auto");
+  const resolvedAuthMode = resolveSetupAuthMode({
+    requestedMode: requestedAuthMode,
+  });
+
+  const spinner = ora("Configuring authentication...").start();
+  try {
+    const keyName = `thesis-setup-${randomBytes(3).toString("hex")}`;
+    const authResult =
+      resolvedAuthMode === "device"
+        ? await acquireApiKeyViaDeviceFlow({
+            baseUrl,
+            keyName,
+            verificationBaseUrl: baseUrl,
+          })
+        : await acquireApiKeyViaBrowserBridge({
+            baseUrl,
+            keyName,
+          });
+    spinner.succeed(`Authenticated (${resolvedAuthMode})`);
+    return authResult.apiKey;
+  } catch (error) {
+    spinner.fail("Authentication failed");
+    const message =
+      error instanceof Error ? error.message : "Authentication failed.";
+    if (resolvedAuthMode === "loopback" && requestedAuthMode === "auto") {
+      throw new Error(
+        `${message} Try --auth-mode device on remote shells.`,
+      );
+    }
+    throw new Error(message);
+  }
+}
+
+async function setupHost(hostName, scope, serverUrl, apiKey, serverName) {
+  const host = getHost(hostName);
+  const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
+
+  if (host.mcp.configType === "toml") {
+    const { alreadyExists } = await appendTomlServer(
+      mcpPath,
+      serverName,
+      host.mcp.buildEntry({ serverUrl, apiKey }),
+    );
+    return {
+      host: host.displayName,
+      status: alreadyExists
+        ? "already configured"
+        : "configured with API Key",
+      filePath: mcpPath,
+    };
+  }
+
+  const existing =
+    host.mcp.configType === "yaml"
+      ? await readYamlConfig(mcpPath)
+      : await readJsonConfig(mcpPath);
+  const { config, alreadyExists } = mergeServerEntry(
+    existing,
+    host.mcp.configKey,
+    serverName,
+    host.mcp.buildEntry({ serverUrl, apiKey }),
+  );
+  if (config !== existing) {
+    if (host.mcp.configType === "yaml") {
+      await writeYamlConfig(mcpPath, config);
+    } else {
+      await writeJsonConfig(mcpPath, config);
+    }
+  }
+  return {
+    host: host.displayName,
+    status: alreadyExists
+      ? "already configured"
+      : "configured with API Key",
+    filePath: mcpPath,
+  };
+}
+
+function printSetupResults(results, scope, serverUrl) {
+  log.blank();
+  log.plain(pc.green("Thesis setup complete"));
+  log.blank();
+  log.plain(`  Scope: ${pc.bold(scope)}`);
+  log.plain(`  Server URL: ${pc.bold(serverUrl)}`);
+  for (const result of results) {
+    const icon = result.status.startsWith("configured")
+      ? pc.green("+")
+      : pc.dim("~");
+    log.plain(`  ${pc.bold(result.host)}`);
+    log.plain(`    ${icon} ${result.status}`);
+    log.plain(`      ${pc.dim(result.filePath)}`);
+  }
+  log.blank();
+}
+
+async function promptGuidedSkillInstall(
+  bundledSkillNames,
+  unsupportedHosts,
+  guidedDecisionOverride = "",
+) {
+  if (guidedDecisionOverride === "accept") {
+    return true;
+  }
+  if (
+    guidedDecisionOverride === "decline" ||
+    guidedDecisionOverride === "abort"
+  ) {
+    return false;
+  }
+
+  const message = buildGuidedSkillInstallPrompt({
+    unsupportedHosts,
+    bundledSkillNames,
+  });
+
+  try {
+    const { shouldInstall } = await inquirer.prompt([
+      {
+        type: "confirm",
+        name: "shouldInstall",
+        message,
+        default: true,
+      },
+    ]);
+    return shouldInstall;
+  } catch {
+    return false;
+  }
+}
+
+export function buildGuidedSkillInstallPrompt({
+  unsupportedHosts,
+  bundledSkillNames,
+}) {
+  const usesPlural = bundledSkillNames.length > 1;
+  if (unsupportedHosts.length > 0) {
+    return usesPlural
+      ? `Also install or refresh the bundled Thesis skills for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`
+      : `Also install or refresh the bundled Thesis skill for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`;
+  }
+  return usesPlural
+    ? "Also install or refresh the bundled Thesis skills?"
+    : "Also install or refresh the bundled Thesis skill?";
+}
+
+function logBundledSkillInstallPlan({
+  bundledSkillNames,
+  projectRoot,
+  scope,
+  supportedHosts,
+}) {
+  for (const hostName of supportedHosts) {
+    const hostDisplayName = getHost(hostName).displayName;
+    const resolvedSkillRoot = path.dirname(
+      resolveInstalledSkillDir(
+        projectRoot,
+        hostName,
+        scope,
+        bundledSkillNames[0],
+      ),
+    );
+    log.plain(
+      `Installing bundled skills for ${hostDisplayName} (${scope}: ${resolvedSkillRoot}): ${bundledSkillNames.join(", ")}`,
+    );
+  }
+}
+
+function normalizeSkillDecisionMode(options) {
+  if (options.installSkill && options.skipSkill) {
+    throw new Error(MUTUALLY_EXCLUSIVE_SKILL_FLAGS_ERROR);
+  }
+  if (options.installSkill) return "install";
+  if (options.skipSkill) return "skip";
+  return "guided";
+}
+
+async function discardInstallSkillCleanupState(cleanupState) {
+  if (!cleanupState?.backupRoot) {
+    return null;
+  }
+  await rm(cleanupState.backupRoot, { force: true, recursive: true });
+  return null;
+}
+
+async function runSetupCommand(options) {
+  const projectRoot = process.cwd();
+  const skillDecisionMode = normalizeSkillDecisionMode(options);
+  const guidedSkillDecisionOverride =
+    getGuidedSkillDecisionOverrideForTests();
+  const nonInteractive = process.stdout.isTTY !== true;
+  const hasGuidedDecisionOverride =
+    guidedSkillDecisionOverride.length > 0;
+  if (
+    nonInteractive &&
+    skillDecisionMode === "guided" &&
+    !hasGuidedDecisionOverride
+  ) {
+    throw new Error(NON_INTERACTIVE_SKILL_DECISION_ERROR);
+  }
+
+  const scope = options.project ? "project" : "global";
+  const baseUrl = normalizeBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
+  const serverUrl = `${baseUrl}/mcp-server`;
+  const serverName = normalizeServerName(options.name || SERVER_NAME);
+  const hosts = await resolveHosts(
+    options,
+    scope,
+    serverName,
+    skillDecisionMode === "guided",
+  );
+  if (hosts.length === 0) return;
+
+  const { supportedHosts, unsupportedHosts } =
+    partitionInstallSkillHosts(hosts);
+  const packageRoot = resolvePackageRoot();
+  const bundledSkillNames =
+    skillDecisionMode === "skip" || supportedHosts.length === 0
+      ? []
+      : await listBundledSkills(packageRoot);
+
+  if (skillDecisionMode === "install" && supportedHosts.length === 0) {
+    throw new Error(
+      `--install-skill is not supported for: ${unsupportedHosts.join(", ")}. Supported hosts: ${formatSupportedInstallSkillHosts()}.`,
+    );
+  }
+  if (
+    skillDecisionMode !== "skip" &&
+    supportedHosts.length > 0 &&
+    bundledSkillNames.length === 0
+  ) {
+    throw new Error(
+      `No bundled skills found under ${path.join(packageRoot, "skills")}.`,
+    );
+  }
+
+  const {
+    hostStates = new Map(),
+    needsSetupHosts = [],
+    driftHosts = [],
+  } = await inspectInstallSkillHosts({
+    hostNames: hosts,
+    scope,
+    serverName,
+    serverUrl,
+  });
+
+  const installDriftHosts = driftHosts;
+
+  if (skillDecisionMode === "install" && installDriftHosts.length > 0) {
+    throw new Error(
+      formatInstallSkillDriftError({
+        hostName: installDriftHosts[0].hostName,
+        scope,
+        serverName,
+        existingUrl: installDriftHosts[0].existingUrl,
+        requestedUrl: serverUrl,
+      }),
+    );
+  }
+
+  let cleanupState = null;
+  try {
+    if (skillDecisionMode === "install") {
+      logBundledSkillInstallPlan({
+        bundledSkillNames,
+        projectRoot,
+        scope,
+        supportedHosts,
+      });
+      cleanupState = await inspectInstalledSkillArtifactsForHosts({
+        projectRoot,
+        hostNames: supportedHosts,
+        scope,
+        skillNames: bundledSkillNames,
+      });
+      await installBundledSkillForHosts({
+        projectRoot,
+        hostNames: supportedHosts,
+        scope,
+        serverName,
+        serverUrl,
+        skillNames: bundledSkillNames,
+      });
+      if (unsupportedHosts.length > 0) {
+        log.plain(
+          `--install-skill skipped unsupported hosts (MCP-only): ${unsupportedHosts.join(", ")}.`,
+        );
+      }
+    }
+
+    const hostsNeedingSetup = needsSetupHosts;
+    let apiKey = null;
+    if (hostsNeedingSetup.length > 0) {
+      apiKey = await resolveApiKey(options, baseUrl);
+      if (!apiKey) {
+        if (cleanupState) {
+          await cleanupInstalledSkillArtifactsForHosts({
+            projectRoot,
+            hostNames: supportedHosts,
+            priorState: cleanupState,
+            scope,
+            skillNames: bundledSkillNames,
+          });
+          cleanupState = null;
+        }
+        log.warn("Setup cancelled");
+        return;
+      }
+    }
+
+    let setupResults = [];
+    const spinner = ora("Setting up Thesis MCP...").start();
+    try {
+      const results = [];
+      for (const hostName of hosts) {
+        if (!needsSetupHosts.includes(hostName)) {
+          results.push({
+            host: getHost(hostName).displayName,
+            status: "already configured",
+            filePath: hostStates.get(hostName).mcpPath,
+          });
+          continue;
+        }
+
+        spinner.text = `Setting up ${getHost(hostName).displayName}...`;
+        // eslint-disable-next-line no-await-in-loop
+        results.push(
+          await setupHost(
+            hostName,
+            scope,
+            serverUrl,
+            apiKey,
+            serverName,
+          ),
+        );
+      }
+      spinner.succeed("MCP setup complete");
+      setupResults = results;
+    } catch (error) {
+      spinner.fail("Setup failed");
+      throw error;
+    }
+
+    if (skillDecisionMode !== "guided") {
+      const completedCleanupState = cleanupState;
+      cleanupState = null;
+      await discardInstallSkillCleanupState(completedCleanupState);
+      printSetupResults(setupResults, scope, serverUrl);
+      return;
+    }
+
+    if (supportedHosts.length === 0) {
+      log.plain(
+        `Bundled skill installation is unavailable for the selected hosts (${hosts.join(", ")}). Continuing with MCP-only setup.`,
+      );
+      printSetupResults(setupResults, scope, serverUrl);
+      return;
+    }
+
+    const shouldInstallSkill = await promptGuidedSkillInstall(
+      bundledSkillNames,
+      unsupportedHosts,
+      guidedSkillDecisionOverride,
+    );
+    if (!shouldInstallSkill) {
+      printSetupResults(setupResults, scope, serverUrl);
+      return;
+    }
+
+    if (installDriftHosts.length > 0) {
+      throw new Error(
+        formatInstallSkillDriftError({
+          hostName: installDriftHosts[0].hostName,
+          scope,
+          serverName,
+          existingUrl: installDriftHosts[0].existingUrl,
+          requestedUrl: serverUrl,
+        }),
+      );
+    }
+
+    logBundledSkillInstallPlan({
+      bundledSkillNames,
+      projectRoot,
+      scope,
+      supportedHosts,
+    });
+    cleanupState = await inspectInstalledSkillArtifactsForHosts({
+      projectRoot,
+      hostNames: supportedHosts,
+      scope,
+      skillNames: bundledSkillNames,
+    });
+    await installBundledSkillForHosts({
+      projectRoot,
+      hostNames: supportedHosts,
+      scope,
+      serverName,
+      serverUrl,
+      skillNames: bundledSkillNames,
+    });
+    if (unsupportedHosts.length > 0) {
+      log.plain(
+        `Guided skill install skipped unsupported hosts (MCP-only): ${unsupportedHosts.join(", ")}.`,
+      );
+    }
+    const completedCleanupState = cleanupState;
+    cleanupState = null;
+    await discardInstallSkillCleanupState(completedCleanupState);
+    printSetupResults(setupResults, scope, serverUrl);
+  } catch (error) {
+    if (cleanupState) {
+      await cleanupInstalledSkillArtifactsForHosts({
+        projectRoot,
+        hostNames: supportedHosts,
+        priorState: cleanupState,
+        scope,
+        skillNames: bundledSkillNames,
+      });
+    }
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Uninstall
+// ---------------------------------------------------------------------------
+
+function parseUninstallScope(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (
+    normalized === "global" ||
+    normalized === "project" ||
+    normalized === "all"
+  ) {
+    return normalized;
+  }
+  return "all";
+}
+
+function scopesFromUninstallScope(scope) {
+  return scope === "all" ? ["global", "project"] : [scope];
+}
+
+async function isConfiguredForUninstallScope(
+  hostName,
+  scope,
+  serverName,
+) {
+  const scopes = scopesFromUninstallScope(scope);
+  for (const singleScope of scopes) {
+    // eslint-disable-next-line no-await-in-loop
+    const configured = await isAlreadyConfigured(
+      hostName,
+      singleScope,
+      serverName,
+    ).catch(() => false);
+    if (configured) return true;
+  }
+  return false;
+}
+
+async function promptUninstallScope(defaultScope) {
+  try {
+    const { selectedScope } = await inquirer.prompt([
+      {
+        type: "list",
+        name: "selectedScope",
+        message: "Which scope do you want to uninstall from?",
+        choices: [
+          { name: "All (global and project)", value: "all" },
+          { name: "Global", value: "global" },
+          { name: "Project", value: "project" },
+        ],
+        default: defaultScope,
+      },
+    ]);
+    return selectedScope;
+  } catch {
+    return null;
+  }
+}
+
+async function promptUninstallHosts(scope, serverName) {
+  const choices = await Promise.all(
+    ALL_HOST_NAMES.map(async (hostName) => {
+      const configured = await isConfiguredForUninstallScope(
+        hostName,
+        scope,
+        serverName,
+      );
+      return {
+        name: SETUP_HOST_NAMES[hostName],
+        value: hostName,
+        checked: configured,
+        disabled: configured ? false : "(not configured)",
+      };
+    }),
+  );
+
+  if (choices.every((choice) => Boolean(choice.disabled))) {
+    log.info("Thesis is not configured for the selected scope.");
+    return null;
+  }
+
+  try {
+    const { selectedHosts } = await inquirer.prompt([
+      {
+        type: "checkbox",
+        name: "selectedHosts",
+        message: "Which hosts do you want to uninstall?",
+        choices,
+        loop: false,
+        validate: (selected) =>
+          selected.length > 0 || "Select at least one host.",
+      },
+    ]);
+    return selectedHosts;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveUninstallTargets(options, serverName) {
+  const explicitHostsFromFlags = selectedHostsFromOptions(options);
+  const explicitHostsFromList =
+    explicitHostsFromFlags.length === 0
+      ? parseHostsList(options.hosts)
+      : [];
+  const hasExplicitHosts =
+    explicitHostsFromFlags.length > 0 ||
+    explicitHostsFromList.length > 0;
+  const hasExplicitScope =
+    typeof options.scope === "string" &&
+    options.scope.trim().length > 0;
+
+  let scope = parseUninstallScope(options.scope || "all");
+  let hosts =
+    explicitHostsFromFlags.length > 0
+      ? explicitHostsFromFlags
+      : explicitHostsFromList.length > 0
+        ? explicitHostsFromList
+        : [...ALL_HOST_NAMES];
+
+  if (!options.yes) {
+    if (!hasExplicitScope) {
+      log.blank();
+      const selectedScope = await promptUninstallScope(scope);
+      if (!selectedScope) {
+        log.warn("Uninstall cancelled");
+        return null;
+      }
+      scope = selectedScope;
+    }
+
+    if (!hasExplicitHosts) {
+      const selectedHosts = await promptUninstallHosts(
+        scope,
+        serverName,
+      );
+      if (!selectedHosts) {
+        log.warn("Uninstall cancelled");
+        return null;
+      }
+      hosts = selectedHosts;
+    }
+  }
+
+  return { scope, hosts };
+}
+
+async function removeHostConfig(hostName, scope, serverName) {
+  const host = getHost(hostName);
+  const filePath = await resolveMcpPath(
+    mcpCandidatesForScope(host, scope),
+  );
+
+  if (host.mcp.configType === "toml") {
+    const result = await removeCodexTomlServer({
+      filePath,
+      serverName,
+    });
+    return {
+      host: host.displayName,
+      scope,
+      filePath,
+      status: result.changed ? "removed" : "not present",
+    };
+  }
+
+  const current =
+    host.mcp.configType === "yaml"
+      ? await readYamlConfig(filePath)
+      : await readJsonConfig(filePath);
+  const next = removeJsonServerEntry({
+    config: current,
+    configKey: host.mcp.configKey,
+    serverName,
+  });
+  if (next.changed) {
+    if (host.mcp.configType === "yaml") {
+      await writeYamlConfig(filePath, next.config);
+    } else {
+      await writeJsonConfig(filePath, next.config);
+    }
+  }
+  return {
+    host: host.displayName,
+    scope,
+    filePath,
+    status: next.changed ? "removed" : "not present",
+  };
+}
+
+async function runUninstallCommand(options) {
+  const serverName = normalizeServerName(options.name || SERVER_NAME);
+  const resolved = await resolveUninstallTargets(options, serverName);
+  if (!resolved) return;
+  const { scope, hosts } = resolved;
+  const scopes = scopesFromUninstallScope(scope);
+
+  const spinner = ora("Removing Thesis MCP entries...").start();
+  const results = [];
+  for (const singleScope of scopes) {
+    for (const host of hosts) {
+      spinner.text = `Removing from ${getHost(host).displayName} (${singleScope})...`;
+      // eslint-disable-next-line no-await-in-loop
+      results.push(
+        await removeHostConfig(host, singleScope, serverName),
+      );
+    }
+  }
+  spinner.succeed("Uninstall complete");
+
+  log.blank();
+  log.plain(pc.green("Thesis uninstall complete"));
+  log.blank();
+  for (const result of results) {
+    const icon =
+      result.status === "removed" ? pc.green("-") : pc.dim("~");
+    log.plain(
+      `  ${pc.bold(result.host)} ${pc.dim(`(${result.scope})`)}`,
+    );
+    log.plain(`    ${icon} ${result.status}`);
+    log.plain(`      ${pc.dim(result.filePath)}`);
+  }
+  log.blank();
+}
+
+// ---------------------------------------------------------------------------
+// Program
+// ---------------------------------------------------------------------------
+
+function buildProgram() {
+  const program = new Command();
+  program
+    .name("thesis")
+    .description("Thesis by Synthetic Sciences -- CLI setup tool")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  ${pc.green("npx @synsci/thesis setup")}
+  ${pc.green("npx @synsci/thesis setup --install-skill")}
+  ${pc.green("npx @synsci/thesis setup --skip-skill")}
+  ${pc.green("npx @synsci/thesis setup --auth-mode device --codex --project")}
+  ${pc.green("npx @synsci/thesis setup --codex --project")}
+  ${pc.green("npx @synsci/thesis setup --yes --codex --claude --cursor")}
+  ${pc.green(
+    "npx @synsci/thesis uninstall --scope all --hosts codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
+  )}
+`,
+    );
+
+  program
+    .command("setup")
+    .description("Set up Thesis MCP for your AI coding host")
+    .option("--claude", "Set up for Claude Code")
+    .option("--opencode", "Set up for OpenCode")
+    .option("--codex", "Set up for Codex")
+    .option("--cursor", "Set up for Cursor")
+    .option("--pi-mono", "Set up for Pi (pi-mono)")
+    .option("--hermes-agent", "Set up for Hermes Agent")
+    .option("--openclaw", "Set up for OpenClaw")
+    .option(
+      "-p, --project",
+      "Configure for current project instead of globally",
+    )
+    .option("-y, --yes", "Skip host selection prompts")
+    .option("--api-key <key>", "Use API key authentication")
+    .option(
+      "--auth-mode <mode>",
+      "Authentication mode: auto | loopback | device (default: auto)",
+      normalizeAuthMode,
+      "auto",
+    )
+    .option(
+      "--install-skill",
+      "Install or refresh the bundled Thesis skills",
+    )
+    .option(
+      "--skip-skill",
+      "Skip bundled skill installation (MCP-only setup)",
+    )
+    .option(
+      "--base-url <url>",
+      `Public Thesis origin used for setup and MCP config (default: ${DEFAULT_BASE_URL})`,
+    )
+    .option(
+      "--name <name>",
+      `MCP server name (default: ${SERVER_NAME})`,
+    )
+    .action(async (options) => {
+      await runSetupCommand(options);
+    });
+
+  program
+    .command("uninstall")
+    .description("Remove Thesis MCP entries from host configs")
+    .option("--claude", "Uninstall for Claude Code")
+    .option("--opencode", "Uninstall for OpenCode")
+    .option("--codex", "Uninstall for Codex")
+    .option("--cursor", "Uninstall for Cursor")
+    .option("--pi-mono", "Uninstall for Pi (pi-mono)")
+    .option("--hermes-agent", "Uninstall for Hermes Agent")
+    .option("--openclaw", "Uninstall for OpenClaw")
+    .option(
+      "--hosts <list>",
+      "Comma-separated: codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
+    )
+    .option("--scope <scope>", "all | global | project")
+    .option(
+      "--name <name>",
+      `MCP server name to remove (default: ${SERVER_NAME})`,
+    )
+    .option("-y, --yes", "Skip uninstall selection prompts")
+    .action(async (options) => {
+      await runUninstallCommand(options);
+    });
+
+  return program;
+}
+
+export async function run(argv = process.argv) {
+  try {
+    const program = buildProgram();
+    await program.parseAsync(argv);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.name === "ExitPromptError"
+    ) {
+      process.exit(0);
+    }
+    if (
+      error instanceof Error &&
+      /cancelled/i.test(error.message)
+    ) {
+      log.warn(error.message);
+      process.exit(0);
+    }
+    throw error;
+  }
+}