@paradigma-inc/flywheel 0.1.4 → 0.1.9

package/src/cli.mjs

@@ -1,7 +1,8 @@
 import { Command } from "commander";
-import { checkbox, select } from "@inquirer/prompts";
+import { checkbox, confirm, select } from "@inquirer/prompts";
 import ora from "ora";
 import pc from "picocolors";
+import { rm } from "node:fs/promises";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 
@@ -16,8 +17,9 @@ import {
 import {
   appendTomlServer,
   mergeServerEntry,
+  readNamedConfigEntry,
   readJsonConfig,
-  readTomlServerExists,
+  readTomlServerEntry,
   readYamlConfig,
   removeCodexTomlServer,
   removeJsonServerEntry,
@@ -25,10 +27,32 @@ import {
   writeJsonConfig,
   writeYamlConfig,
 } from "./mcp-writer.mjs";
-import { acquireApiKeyViaBrowserBridge } from "./setup-auth.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://flywheel.paradigma.inc";
 const DEFAULT_BASE_URL =
-  process.env.FLYWHEEL_PUBLIC_BASE_URL || "https://flywheel.paradigma.inc";
+  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)),
@@ -71,6 +95,20 @@ function normalizeServerName(value) {
   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");
@@ -100,39 +138,122 @@ function mcpCandidatesForScope(host, scope) {
   );
 }
 
-function readConfigSection(config, configKey) {
-  const pathParts = Array.isArray(configKey) ? configKey : [configKey];
-  let current = config && typeof config === "object" ? config : {};
-  for (const part of pathParts) {
-    if (
-      !current ||
-      typeof current !== "object" ||
-      Array.isArray(current) ||
-      !(part in current)
-    ) {
-      return {};
-    }
-    const next = current[part];
-    if (!next || typeof next !== "object" || Array.isArray(next)) {
-      return {};
-    }
-    current = next;
-  }
-  return current;
+async function isAlreadyConfigured(hostName, scope, serverName) {
+  const existingState = await readExistingServerState(
+    hostName,
+    scope,
+    serverName,
+  );
+  return existingState.exists;
 }
 
-async function isAlreadyConfigured(hostName, scope, serverName) {
+async function readExistingServerState(hostName, scope, serverName) {
   const host = getHost(hostName);
   const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
+
   if (host.mcp.configType === "toml") {
-    return readTomlServerExists(mcpPath, serverName);
+    const { exists, url } = await readTomlServerEntry(mcpPath, serverName);
+    return { exists, url, mcpPath };
   }
+
   const existing =
     host.mcp.configType === "yaml"
       ? await readYamlConfig(mcpPath)
       : await readJsonConfig(mcpPath);
-  const section = readConfigSection(existing, host.mcp.configKey);
-  return serverName in section;
+  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 `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) {
@@ -171,12 +292,23 @@ async function promptHosts(scope, detected, serverName) {
   }
 }
 
-async function resolveHosts(options, scope, serverName) {
+async function resolveHosts(options, scope, serverName, allowPrompt = true) {
   const explicit = selectedHostsFromOptions(options);
   if (explicit.length > 0) return explicit;
 
   const detected = await detectHosts(scope);
-  if (detected.length > 0 && options.yes) return detected;
+  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);
@@ -188,20 +320,43 @@ async function resolveHosts(options, scope, serverName) {
 }
 
 async function resolveApiKey(options, baseUrl) {
-  if (options.apiKey) return options.apiKey.trim();
+  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 = `flywheel-setup-${randomBytes(3).toString("hex")}`;
-    const authResult = await acquireApiKeyViaBrowserBridge({
-      baseUrl,
-      keyName,
-    });
-    spinner.succeed("Authenticated");
+    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");
-    throw error;
+    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);
   }
 }
 
@@ -263,31 +418,319 @@ function printSetupResults(results, scope, serverUrl) {
   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 {
+    return await confirm({
+      message,
+      default: true,
+      theme: CHECKBOX_THEME,
+    });
+  } 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 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?";
+}
+
+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);
+  const hosts = await resolveHosts(
+    options,
+    scope,
+    serverName,
+    skillDecisionMode === "guided",
+  );
   if (hosts.length === 0) return;
 
-  const apiKey = await resolveApiKey(options, baseUrl);
-  if (!apiKey) {
-    log.warn("Setup cancelled");
-    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 spinner = ora("Setting up Flywheel...").start();
-  const results = [];
-  for (const hostName of hosts) {
-    spinner.text = `Setting up ${getHost(hostName).displayName}...`;
-    // eslint-disable-next-line no-await-in-loop
-    results.push(
-      await setupHost(hostName, scope, serverUrl, apiKey, serverName),
+  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 Flywheel 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;
   }
-  spinner.succeed("Setup complete");
-  printSetupResults(results, scope, serverUrl);
 }
 
 function parseUninstallScope(value) {
@@ -496,11 +939,14 @@ function buildProgram() {
       "after",
       `
 Examples:
-  ${pc.green("npx @paradigma-inc/flywheel setup")}
-  ${pc.green("npx @paradigma-inc/flywheel setup --codex --project")}
-  ${pc.green("npx @paradigma-inc/flywheel setup --yes --codex --claude --cursor")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --install-skill")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --skip-skill")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --auth-mode device --codex --project")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --codex --project")}
+  ${pc.green("npx --yes @paradigma-inc/flywheel setup --yes --codex --claude --cursor")}
   ${pc.green(
-    "npx @paradigma-inc/flywheel uninstall --scope all --hosts codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
+    "npx --yes @paradigma-inc/flywheel uninstall --scope all --hosts codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
   )}
 `,
     );
@@ -521,6 +967,14 @@ Examples:
     )
     .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 Flywheel skills")
+    .option("--skip-skill", "Skip bundled skill installation (MCP-only setup)")
     .option(
       "--base-url <url>",
       `Public Flywheel origin used for setup and MCP config (default: ${DEFAULT_BASE_URL})`,