@paradigma-inc/flywheel 0.1.35 → 0.1.52

package/src/setup/modes/mcp-command.mjs

@@ -0,0 +1,850 @@
+import { checkbox, confirm } from "@inquirer/prompts";
+import ora from "ora";
+import pc from "picocolors";
+import { rm } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  ALL_HOST_NAMES,
+  SERVER_NAME,
+  detectHosts,
+  getHost,
+  normalizeHosts,
+} from "../../agents.mjs";
+import {
+  readNamedConfigEntry,
+  readJsonConfig,
+  readTomlServerEntry,
+  readYamlConfig,
+  resolveMcpPath,
+} from "../../mcp-writer.mjs";
+import {
+  resolveSetupApiKey,
+} from "../../setup-auth.mjs";
+import {
+  cleanupInstalledSkillArtifactsForHosts,
+  formatSupportedInstallSkillHosts,
+  inspectInstalledSkillArtifactsForHosts,
+  installBundledSkillForHosts,
+  listBundledSkills,
+  partitionInstallSkillHosts,
+  resolveInstalledSkillDir,
+  resolvePackageRoot,
+  resolveSkillsAgentName,
+} from "../../skill-installer.mjs";
+import { runMcpSetupMode } from "./mcp.mjs";
+import { SetupModeUsageError } from "../mode.mjs";
+import {
+  detectPriorModeForSetup,
+  formatPriorModeConflictError,
+} from "../shared/prior-mode-detect.mjs";
+import { renderSetupSummary } from "../shared/summary.mjs";
+
+const INSTALL_SKILL_BASE_URL = "https://flywheel.paradigma.inc";
+const DEFAULT_BASE_URL =
+  process.env.FLYWHEEL_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 = "FLYWHEEL_GUIDED_SKILL_DECISION_FOR_TESTS";
+const ENABLE_TEST_SEAMS_ENV = "FLYWHEEL_ENABLE_TEST_SEAMS";
+
+const log = {
+  info: (message) => console.log(pc.cyan(message)),
+  warn: (message) => console.log(pc.yellow(`⚠ ${message}`)),
+  error: (message) => console.log(pc.red(`✖ ${message}`)),
+  plain: (message) => console.log(message),
+  blank: () => console.log(""),
+};
+
+const CHECKBOX_THEME = {
+  style: {
+    highlight: (text) => pc.green(text),
+    disabledChoice: (text) => ` ${pc.dim("◯")} ${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 Flywheel 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 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 mcpCandidatesForScope(host, scope) {
+  if (scope === "global") return host.mcp.globalPaths;
+  return host.mcp.projectPaths.map((candidate) =>
+    path.join(process.cwd(), candidate),
+  );
+}
+
+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 isAlreadyConfigured(hostName, scope, serverName) {
+  const existingState = await readExistingServerState(
+    hostName,
+    scope,
+    serverName,
+  );
+  return existingState.exists;
+}
+
+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 `Flywheel MCP entry '${serverName}' for ${host.displayName} already points to ${existingUrl}, not ${requestedUrl}. Run 'flywheel 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 = [];
+  for (const hostName of ALL_HOST_NAMES) {
+    // eslint-disable-next-line no-await-in-loop
+    const configured = await isAlreadyConfigured(
+      hostName,
+      scope,
+      serverName,
+    ).catch(() => false);
+    const label = configured
+      ? `${getHost(hostName).displayName} ${pc.dim("(already configured)")}`
+      : getHost(hostName).displayName;
+    choices.push({
+      name: label,
+      value: hostName,
+      checked: detected.includes(hostName),
+    });
+  }
+
+  try {
+    return await checkbox({
+      message: "Which hosts do you want to set up?",
+      choices,
+      loop: false,
+      theme: CHECKBOX_THEME,
+      validate: (selected) =>
+        selected.length > 0 || "Select at least one host.",
+    });
+  } 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 resolved = await resolveSetupApiKey({
+      options,
+      baseUrl,
+    });
+    return resolved.apiKey;
+  }
+
+  const spinner = ora("Configuring authentication...").start();
+  try {
+    const resolved = await resolveSetupApiKey({
+      options,
+      baseUrl,
+    });
+    spinner.succeed(`Authenticated (${resolved.authMode})`);
+    return resolved.apiKey;
+  } catch (error) {
+    spinner.fail("Authentication failed");
+    const message = error instanceof Error ? error.message : String(error);
+    if (/cancelled/i.test(message)) {
+      return null;
+    }
+    throw new Error(message);
+  }
+}
+
+function buildSetupResultRows({ selectedHosts, hostStates, setupResult }) {
+  const byAgent = new Map(
+    setupResult.agentResults.map((result) => [result.agent, result]),
+  );
+
+  return selectedHosts.map((hostName) => {
+    const host = getHost(hostName);
+    const agentResult = byAgent.get(hostName);
+    if (!agentResult) {
+      return {
+        host: host.displayName,
+        status: "unknown",
+        filePath: hostStates.get(hostName)?.mcpPath || "(unknown)",
+      };
+    }
+
+    if (agentResult.success !== true) {
+      return {
+        host: host.displayName,
+        status: "failed",
+        filePath: hostStates.get(hostName)?.mcpPath || "(unknown)",
+      };
+    }
+
+    const alreadyConfigured =
+      Array.isArray(agentResult.skippedSteps) &&
+      agentResult.skippedSteps.includes("already-configured");
+
+    return {
+      host: host.displayName,
+      status: alreadyConfigured ? "already configured" : "configured with API Key",
+      filePath:
+        agentResult.touchedFiles[0] || hostStates.get(hostName)?.mcpPath || "(unknown)",
+    };
+  });
+}
+
+function printSetupResults(
+  results,
+  scope,
+  serverUrl,
+  { showSkillRefreshGuidance = false, experimentalSyncAgents = [] } = {},
+) {
+  log.blank();
+  log.plain(pc.green("✔ Flywheel 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)}`);
+  }
+  if (showSkillRefreshGuidance) {
+    log.blank();
+    log.plain("  Bundled skill refresh guidance");
+    log.plain(
+      `    Preferred: ${pc.bold("npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill --project")}`,
+    );
+    log.plain(
+      `      ${pc.bold("npm install --save-dev @paradigma-inc/flywheel@latest")}`,
+    );
+    if (experimentalSyncAgents.length === 1) {
+      log.plain("    Optional path via skills experimental_sync:");
+      log.plain(
+        `      ${pc.bold(`npx skills experimental_sync --agent ${experimentalSyncAgents[0]} -y`)}`,
+      );
+    } else if (experimentalSyncAgents.length > 1) {
+      log.plain("    Optional path via skills experimental_sync for selected hosts:");
+      for (const agentName of experimentalSyncAgents) {
+        log.plain(
+          `      ${pc.bold(`npx skills experimental_sync --agent ${agentName} -y`)}`,
+        );
+      }
+    }
+  }
+  log.blank();
+}
+
+function resolveExperimentalSyncAgentsForHosts(supportedHosts) {
+  const agentNames = [];
+  const seenAgentNames = new Set();
+
+  for (const hostName of supportedHosts) {
+    const agentName = resolveSkillsAgentName(hostName);
+    if (seenAgentNames.has(agentName)) {
+      continue;
+    }
+    seenAgentNames.add(agentName);
+    agentNames.push(agentName);
+  }
+
+  return agentNames;
+}
+
+export function buildGuidedSkillInstallPrompt({
+  unsupportedHosts,
+  bundledSkillNames,
+}) {
+  const usesPlural = bundledSkillNames.length > 1;
+  if (unsupportedHosts.length > 0) {
+    return usesPlural
+      ? `Also install or refresh the bundled Flywheel skills for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`
+      : `Also install or refresh the bundled Flywheel skill for supported hosts? Unsupported hosts (${unsupportedHosts.join(", ")}) will remain MCP-only.`;
+  }
+  return usesPlural
+    ? "Also install or refresh the bundled Flywheel skills?"
+    : "Also install or refresh the bundled Flywheel skill?";
+}
+
+async function promptGuidedSkillInstall(
+  bundledSkillNames,
+  unsupportedHosts,
+  guidedSkillDecisionOverride,
+) {
+  if (guidedSkillDecisionOverride === "accept") {
+    return true;
+  }
+  if (
+    guidedSkillDecisionOverride === "decline" ||
+    guidedSkillDecisionOverride === "abort"
+  ) {
+    return false;
+  }
+
+  log.blank();
+  const message = buildGuidedSkillInstallPrompt({
+    unsupportedHosts,
+    bundledSkillNames,
+  });
+
+  try {
+    return await confirm({
+      message,
+      default: true,
+      theme: CHECKBOX_THEME,
+    });
+  } catch {
+    return false;
+  }
+}
+
+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;
+}
+
+function printSetupResultSummary(setupResult) {
+  const lines = renderSetupSummary(setupResult);
+  log.blank();
+  for (const line of lines) {
+    log.plain(`  ${line}`);
+  }
+  log.blank();
+}
+
+export async function runMcpModeCommand(options, deps = {}) {
+  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 { exitCode: 0 };
+  }
+
+  const { supportedHosts, unsupportedHosts } = partitionInstallSkillHosts(hosts);
+  const packageRoot = resolvePackageRoot();
+  const bundledSkillNames =
+    skillDecisionMode === "skip" || supportedHosts.length === 0
+      ? []
+      : await listBundledSkills(packageRoot);
+
+  if (skillDecisionMode === "install" && supportedHosts.length === 0) {
+    if (options.allowUnsupportedSkillInstall !== true) {
+      throw new Error(
+        `--install-skill is not supported for: ${unsupportedHosts.join(", ")}. Supported hosts: ${formatSupportedInstallSkillHosts()}.`,
+      );
+    }
+    log.plain(
+      `Bundled skill install skipped (unsupported-only host selection: ${unsupportedHosts.join(", ")}).`,
+    );
+  }
+  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,
+  });
+
+  // Capture prior-mode state before any install/auth side effects so the
+  // detector does not classify artifacts created by this same command as
+  // pre-existing CLI-mode installs, and so a refuse or reconcile decision
+  // happens before we touch disk or start a browser auth flow. Running this
+  // inside runMcpSetupMode (the prior placement) meant --force would uninstall
+  // the freshly installed bundled skills, and the non-force path would still
+  // have run auth before surfacing the conflict.
+  const priorModeSnapshot = await detectPriorModeForSetup({
+    targetMode: "mcp",
+    selectedHosts: hosts,
+    scope,
+    cwd: projectRoot,
+    serverName,
+    serverUrl,
+  });
+  const reconciled = [];
+  if (
+    priorModeSnapshot.priorMode &&
+    priorModeSnapshot.affectedHosts.length > 0
+  ) {
+    if (deps.force !== true) {
+      throw new SetupModeUsageError(
+        formatPriorModeConflictError(priorModeSnapshot),
+      );
+    }
+    if (typeof deps.reconcilePriorMode !== "function") {
+      throw new Error(
+        "reconcilePriorMode dependency is required when --force is used.",
+      );
+    }
+    const reconcileEntries = Array.isArray(priorModeSnapshot.entries)
+      ? priorModeSnapshot.entries
+      : priorModeSnapshot.affectedHosts.map((hostName) => ({
+          hostName,
+          serverNames: [],
+        }));
+    for (const entry of reconcileEntries) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await deps.reconcilePriorMode({
+          priorMode: priorModeSnapshot.priorMode,
+          targetMode: "mcp",
+          hostNames: [entry.hostName],
+          serverNames: entry.serverNames,
+          scope,
+          cwd: projectRoot,
+          serverName,
+          serverUrl,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const reconcileError = new Error(
+          `Failed to reconcile prior --mode ${priorModeSnapshot.priorMode} artifacts for host ${entry.hostName}: ${message}`,
+        );
+        reconcileError.exitCode = 4;
+        throw reconcileError;
+      }
+    }
+    reconciled.push(
+      `removed prior --mode ${priorModeSnapshot.priorMode} artifacts for host(s): ${priorModeSnapshot.affectedHosts.join(", ")}`,
+    );
+  }
+
+  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(", ")}.`,
+        );
+      }
+    }
+
+    let apiKey = null;
+    const explicitApiKeyProvided = Object.hasOwn(options, "apiKey");
+    const shouldResolveApiKey =
+      needsSetupHosts.length > 0 ||
+      explicitApiKeyProvided;
+    if (shouldResolveApiKey) {
+      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 { exitCode: 0 };
+      }
+    }
+
+    const setupResult = await runMcpSetupMode({
+      selectedHosts: hosts,
+      scope,
+      cwd: projectRoot,
+      // Prior-mode enforcement already ran before install/auth (above); skip
+      // the inner detector so a --force reconcile cannot re-uninstall the
+      // skills this command just installed, and so the non-force conflict
+      // path short-circuits before we reach this point.
+      force: false,
+      serverName,
+      serverUrl,
+      apiKey,
+      detectPriorMode: async () => ({
+        priorMode: null,
+        affectedHosts: [],
+        entries: [],
+      }),
+      reconcilePriorMode: deps.reconcilePriorMode,
+    });
+    if (reconciled.length > 0) {
+      setupResult.reconciled = [
+        ...(Array.isArray(setupResult.reconciled) ? setupResult.reconciled : []),
+        ...reconciled,
+      ];
+    }
+
+    if (setupResult.exitCode !== 0) {
+      printSetupResultSummary(setupResult);
+      const failureDetails = setupResult.agentResults
+        .filter((result) => result.success !== true)
+        .flatMap((result) =>
+          Array.isArray(result.warnings) ? result.warnings : [],
+        )
+        .join(" | ");
+      const error = new Error(
+        failureDetails.length > 0
+          ? `MCP setup encountered host-level failures: ${failureDetails}`
+          : "MCP setup encountered host-level failures.",
+      );
+      error.exitCode = setupResult.exitCode;
+      throw error;
+    }
+
+    const setupRows = buildSetupResultRows({
+      selectedHosts: hosts,
+      hostStates,
+      setupResult,
+    });
+
+    if (skillDecisionMode !== "guided") {
+      const completedCleanupState = cleanupState;
+      cleanupState = null;
+      await discardInstallSkillCleanupState(completedCleanupState);
+      const showSkillRefreshGuidance =
+        scope === "project" &&
+        skillDecisionMode === "install" &&
+        supportedHosts.length > 0;
+      printSetupResults(setupRows, scope, serverUrl, {
+        showSkillRefreshGuidance,
+        experimentalSyncAgents: showSkillRefreshGuidance
+          ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+          : [],
+      });
+      return setupResult;
+    }
+
+    if (supportedHosts.length === 0) {
+      log.plain(
+        `Bundled skill installation is unavailable for the selected hosts (${hosts.join(", ")}). Continuing with MCP-only setup.`,
+      );
+      printSetupResults(setupRows, scope, serverUrl);
+      return setupResult;
+    }
+
+    const shouldInstallSkill = await promptGuidedSkillInstall(
+      bundledSkillNames,
+      unsupportedHosts,
+      guidedSkillDecisionOverride,
+    );
+    if (!shouldInstallSkill) {
+      printSetupResults(setupRows, scope, serverUrl);
+      return setupResult;
+    }
+
+    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);
+    const showSkillRefreshGuidance =
+      scope === "project" && supportedHosts.length > 0;
+    printSetupResults(setupRows, scope, serverUrl, {
+      showSkillRefreshGuidance,
+      experimentalSyncAgents: showSkillRefreshGuidance
+        ? resolveExperimentalSyncAgentsForHosts(supportedHosts)
+        : [],
+    });
+    return setupResult;
+  } catch (error) {
+    if (cleanupState) {
+      await cleanupInstalledSkillArtifactsForHosts({
+        projectRoot,
+        hostNames: supportedHosts,
+        priorState: cleanupState,
+        scope,
+        skillNames: bundledSkillNames,
+      });
+    }
+    throw error;
+  }
+}