@paradigma-inc/flywheel 0.1.53 → 0.1.60

package/src/cli.mjs

@@ -2,18 +2,21 @@ import { Command } from "commander";
 import { checkbox, select } from "@inquirer/prompts";
 import ora from "ora";
 import pc from "picocolors";
-import { readFile } from "node:fs/promises";
+import { access, readFile, rm } from "node:fs/promises";
 import path from "node:path";
 
 import {
   ALL_HOST_NAMES,
   SERVER_NAME,
   SETUP_HOST_NAMES,
+  SKILL_ONLY_HOST_NAMES,
   detectHosts,
   getHost,
+  isSkillOnlyHost,
   normalizeHosts,
 } from "./agents.mjs";
 import {
+  readEntryServerUrl,
   readNamedConfigEntry,
   readJsonConfig,
   readTomlServerEntry,
@@ -28,6 +31,8 @@ import {
   listBundledSkills,
   partitionInstallSkillHosts,
   removeInstalledSkillsForHosts,
+  resolveInstalledSkillDir,
+  resolveFlywheelInstalledMarkerPath,
   SUPPORTED_INSTALL_SKILL_HOSTS,
   resolvePackageRoot,
 } from "./skill-installer.mjs";
@@ -42,6 +47,15 @@ import {
 import { findFlywheelMcpEntryNames } from "./setup/shared/prior-mode-detect.mjs";
 import { renderSetupSummary } from "./setup/shared/summary.mjs";
 
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export { buildGuidedSkillInstallPrompt };
 
 const INSTALL_SKILL_BASE_URL = "https://flywheel.paradigma.inc";
@@ -95,9 +109,12 @@ function normalizeAuthMode(value) {
 function selectedHostsFromOptions(options) {
   const hosts = [];
   if (options.claude) hosts.push("claude");
+  if (options.cursor) hosts.push("cursor");
+  if (options.universal) hosts.push("universal");
+  if (options.antigravity) hosts.push("antigravity");
   if (options.opencode) hosts.push("opencode");
   if (options.codex) hosts.push("codex");
-  if (options.cursor) hosts.push("cursor");
+  if (options.gemini) hosts.push("gemini");
   if (options.piMono) hosts.push("pi-mono");
   if (options.hermesAgent) hosts.push("hermes-agent");
   if (options.openclaw) hosts.push("openclaw");
@@ -109,6 +126,9 @@ const UNINSTALL_OPTION_KEY_BY_HOST = Object.freeze({
   codex: "codex",
   opencode: "opencode",
   cursor: "cursor",
+  gemini: "gemini",
+  universal: "universal",
+  antigravity: "antigravity",
   "pi-mono": "piMono",
   "hermes-agent": "hermesAgent",
   openclaw: "openclaw",
@@ -167,6 +187,9 @@ async function isAlreadyConfigured(hostName, scope, serverName) {
 
 async function readExistingServerState(hostName, scope, serverName) {
   const host = getHost(hostName);
+  if (isSkillOnlyHost(host)) {
+    return { exists: false, url: null, mcpPath: null };
+  }
   const mcpPath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
 
   if (host.mcp.configType === "toml") {
@@ -181,7 +204,7 @@ async function readExistingServerState(hostName, scope, serverName) {
   const entry = readNamedConfigEntry(existing, host.mcp.configKey, serverName);
   return {
     exists: entry !== null,
-    url: typeof entry?.url === "string" ? entry.url : null,
+    url: readEntryServerUrl(entry),
     mcpPath,
   };
 }
@@ -289,7 +312,19 @@ async function promptSetupMode() {
   return await select(buildSetupModePromptConfig());
 }
 
-function validateCliModeSkillFlags(options) {
+/**
+ * Validate the flag combination for --mode cli. Rejections raise
+ * `SetupModeUsageError` so the top-level handler reports them as usage
+ * errors (exit code 2) and not as operational failures.
+ *
+ * `--oauth` controls the MCP config written in --mode mcp (it omits the
+ * Authorization header so the IDE can discover MCP 2.0 OAuth instead).
+ * --mode cli writes no MCP config at all, so there is nothing for --oauth
+ * to modify. Silently accepting it would look successful but still fall
+ * back to API-key auth in the runtime config — a misconfiguration. Reject
+ * it up front with guidance toward the correct invocation.
+ */
+function validateCliModeFlags(options) {
   if (options.installSkill && options.skipSkill) {
     throw new SetupModeUsageError(
       "--install-skill and --skip-skill cannot be used together.",
@@ -302,10 +337,15 @@ function validateCliModeSkillFlags(options) {
       "--skip-skill is not supported with --mode cli; use --mode mcp --skip-skill for MCP-only setup.",
     );
   }
+  if (options.oauth === true) {
+    throw new SetupModeUsageError(
+      "--oauth is not supported with --mode cli. --oauth only affects the MCP config written by --mode mcp; re-run with --mode mcp --oauth, or drop --oauth for a CLI-mode setup.",
+    );
+  }
 }
 
 async function runCliModeCommand(options) {
-  validateCliModeSkillFlags(options);
+  validateCliModeFlags(options);
   const scope = options.project ? "project" : "global";
   const baseUrl = normalizeBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
   const serverUrl = `${baseUrl}/mcp-server`;
@@ -484,6 +524,9 @@ function isLikelyFlywheelMcpUrl(url) {
 
 async function listHostMcpEntries(hostName, scope) {
   const host = getHost(hostName);
+  if (isSkillOnlyHost(host)) {
+    return [];
+  }
   const filePath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
 
   if (host.mcp.configType === "toml") {
@@ -517,7 +560,7 @@ async function listHostMcpEntries(hostName, scope) {
     .filter(([, entry]) => entry && typeof entry === "object" && !Array.isArray(entry))
     .map(([serverName, entry]) => ({
       serverName,
-      url: typeof entry.url === "string" ? entry.url : null,
+      url: readEntryServerUrl(entry),
     }));
 }
 
@@ -533,14 +576,68 @@ async function resolveHostsWithRemainingFlywheelMcpEntries({ scope }) {
   return remainingHosts;
 }
 
+/**
+ * Determine which non-uninstalled hosts still claim bundled skill artifacts
+ * via their install marker, and therefore must keep their (possibly shared)
+ * skill directories intact.
+ *
+ * The install marker (`.flywheel-installed-by-<host>`) is written by
+ * `installBundledSkillForHosts` for any host whose install path produces no
+ * MCP entry:
+ *
+ *   - skill-only hosts (universal, antigravity): marker always written.
+ *   - MCP-capable hosts (codex, opencode, cursor, claude, pi-mono, openclaw,
+ *     gemini): marker written ONLY when the host was installed via
+ *     `--mode cli`, because CLI-mode installs write no MCP entry.
+ *
+ * A marker at a skill-root is therefore the unambiguous "this host still
+ * owns these skills" signal for both categories. Narrowing the retain pass
+ * to skill-only hosts would let `uninstall --universal` silently wipe the
+ * shared `.agents/skills/` dir out from under a still-installed CLI-mode
+ * codex. Using dir existence alone would over-retain for hosts that never
+ * installed anything. The per-host marker resolves both.
+ *
+ * `excludedHostNames` is the list of hosts currently being uninstalled;
+ * their markers will be removed and their artifacts are expected to go, so
+ * they are excluded from retention here.
+ */
+async function resolveSkillOnlyHostsRetainingArtifacts({
+  scope,
+  excludedHostNames = [],
+}) {
+  const excluded = new Set(excludedHostNames);
+  const retained = [];
+  for (const hostName of SUPPORTED_INSTALL_SKILL_HOSTS) {
+    if (excluded.has(hostName)) continue;
+    let markerPath;
+    try {
+      markerPath = resolveFlywheelInstalledMarkerPath(
+        process.cwd(),
+        hostName,
+        scope,
+      );
+    } catch {
+      // Host isn't registered with the flywheel skill installer; no marker
+      // to consult, nothing to retain.
+      continue;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    const markerExists = await pathExists(markerPath);
+    if (markerExists) {
+      retained.push(hostName);
+    }
+  }
+  return retained;
+}
+
 async function findFlywheelServerNamesOnHost(hostName, scope) {
   // Mirror setup's prior-mode detector: walk every MCP entry on the host and
   // keep those whose URL is Flywheel-identifying (hostname contains "flywheel"
   // or path === /mcp-server with a matching target origin). Uninstall must
-  // catch renamed/drifted entries (e.g. `[mcp_servers.flywheel-staging]`) that
-  // setup already detects; otherwise a user whose host has a non-default entry
-  // name is stuck between setup ("already installed") and uninstall ("not
-  // configured").
+  // catch renamed or drifted entries (e.g. a non-default TOML section name
+  // under `[mcp_servers.*]`) that setup already detects; otherwise a user
+  // whose host has a non-default entry name is stuck between setup ("already
+  // installed") and uninstall ("not configured").
   return await findFlywheelMcpEntryNames({ hostName, scope }).catch(() => []);
 }
 
@@ -574,10 +671,92 @@ async function isConfiguredForUninstallScope(
       { explicitServerName },
     );
     if (targets.length > 0) return true;
+    // Skill-only hosts and CLI-mode MCP-capable hosts never write an MCP
+    // entry, so the sweep above finds nothing for them. Fall back to the
+    // install marker: if this host wrote its own ownership marker in the
+    // selected scope, it IS configured for the purposes of the uninstall
+    // prompt.
+    if (SUPPORTED_INSTALL_SKILL_HOSTS.includes(hostName)) {
+      try {
+        const markerPath = resolveFlywheelInstalledMarkerPath(
+          process.cwd(),
+          hostName,
+          singleScope,
+        );
+        // eslint-disable-next-line no-await-in-loop
+        if (await pathExists(markerPath)) return true;
+      } catch {
+        // Host isn't registered with the skill installer; nothing to check.
+      }
+    }
   }
   return false;
 }
 
+/**
+ * Public wrapper exposing the uninstall-eligibility check used by the
+ * interactive prompt. Returns true when the host has either a Flywheel MCP
+ * entry OR a Flywheel install marker in the requested scope. Exported so
+ * tests can verify that skill-only hosts surface as configurable in the
+ * prompt even though they write no MCP entry.
+ */
+export async function isHostConfiguredForUninstall({
+  hostName,
+  scope = "project",
+  serverName = SERVER_NAME,
+} = {}) {
+  // Mirror `runUninstallCommand`'s derivation: only treat the caller's
+  // `serverName` as "explicit" when it differs from the package default.
+  // An explicit name short-circuits the Flywheel-identifying sweep in
+  // `resolveUninstallServerNamesForHost`, which the default-named case
+  // needs to run so drifted entries (and the marker fallback for
+  // skill-only / CLI-mode hosts) are reachable.
+  const explicitServerName =
+    typeof serverName === "string" &&
+    serverName.length > 0 &&
+    serverName !== SERVER_NAME
+      ? serverName
+      : null;
+  return isConfiguredForUninstallScope(hostName, scope, { explicitServerName });
+}
+
+/**
+ * Remove every Flywheel install marker for the requested hosts across the
+ * requested scopes. Exported and implemented as a standalone helper so it
+ * can run independently of bundled-skill discovery: a package with a
+ * missing or trimmed `skills/` directory must still be able to uninstall
+ * cleanly, otherwise stale markers leak into later prompt-eligibility,
+ * retention, and prior-mode-detection logic. `rm ..., { force: true }`
+ * makes the operation idempotent — hosts that never wrote a marker (e.g.
+ * MCP-capable hosts installed only via `--mode mcp`) are silent no-ops.
+ *
+ * Hosts not registered with the Flywheel skill installer are skipped
+ * rather than throwing, so callers can pass the full uninstall host list
+ * without pre-filtering.
+ */
+export async function cleanupHostInstallMarkers({
+  cwd = process.cwd(),
+  scopes = ["project"],
+  hostNames = [],
+} = {}) {
+  for (const singleScope of scopes) {
+    for (const hostName of hostNames) {
+      let markerPath;
+      try {
+        markerPath = resolveFlywheelInstalledMarkerPath(
+          cwd,
+          hostName,
+          singleScope,
+        );
+      } catch {
+        continue;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await rm(markerPath, { force: true });
+    }
+  }
+}
+
 async function promptUninstallScope(defaultScope) {
   try {
     return await select({
@@ -674,6 +853,14 @@ async function resolveUninstallTargets(options, { explicitServerName }) {
 
 async function removeHostConfig(hostName, scope, serverName) {
   const host = getHost(hostName);
+  if (isSkillOnlyHost(host)) {
+    return {
+      host: host.displayName,
+      scope,
+      filePath: null,
+      status: "not present",
+    };
+  }
   const filePath = await resolveMcpPath(mcpCandidatesForScope(host, scope));
 
   if (host.mcp.configType === "toml") {
@@ -733,7 +920,8 @@ async function runUninstallCommand(options) {
       // Resolve the concrete server name(s) to remove at the host/scope level.
       // When --name was not given, this iterates every Flywheel-identifying
       // entry (matching setup's prior-mode detector) so renamed or drifted
-      // entries (e.g. `[mcp_servers.flywheel-staging]`) are actually cleared.
+      // entries (non-default TOML section names under `[mcp_servers.*]`) are
+      // actually cleared.
       // eslint-disable-next-line no-await-in-loop
       const targetNames = await resolveUninstallServerNamesForHost(
         host,
@@ -743,10 +931,16 @@ async function runUninstallCommand(options) {
       if (targetNames.length === 0) {
         // eslint-disable-next-line no-await-in-loop
         const hostForDisplay = getHost(host);
-        // eslint-disable-next-line no-await-in-loop
-        const filePath = await resolveMcpPath(
-          mcpCandidatesForScope(hostForDisplay, singleScope),
-        );
+        // Skill-only hosts (universal, antigravity) have no MCP surface
+        // at all — `host.mcp` is null, so dereferencing `projectPaths` via
+        // `mcpCandidatesForScope` throws. Report the absence without
+        // consulting a path that doesn't exist for them.
+        const filePath = isSkillOnlyHost(hostForDisplay)
+          ? null
+          : // eslint-disable-next-line no-await-in-loop
+            await resolveMcpPath(
+              mcpCandidatesForScope(hostForDisplay, singleScope),
+            );
         mcpResults.push({
           host: hostForDisplay.displayName,
           scope: singleScope,
@@ -774,12 +968,26 @@ async function runUninstallCommand(options) {
     if (bundledSkillNames.length > 0) {
       const skillSpinner = ora("Removing Flywheel bundled skills...").start();
       for (const singleScope of scopes) {
-        // Prevent deleting shared skill directories while non-selected hosts
-        // mapped to the same location still have Flywheel MCP entries.
+        // Retain any skill directory still claimed by a non-uninstalled host.
+        // Two signals combine: (a) MCP-backed hosts whose Flywheel entries
+        // survived the MCP-removal pass above, and (b) any host with bundled
+        // skill artifacts still on disk (including skill-only hosts like
+        // universal/antigravity, which never advertise themselves via MCP
+        // entries). Without (b), uninstalling one MCP host would silently
+        // wipe a shared `.agents/skills/<skill>/` that another host still
+        // relies on.
         // eslint-disable-next-line no-await-in-loop
-        const configuredRetainHostNames = await resolveHostsWithRemainingFlywheelMcpEntries({
+        const mcpRetained = await resolveHostsWithRemainingFlywheelMcpEntries({
           scope: singleScope,
         });
+        // eslint-disable-next-line no-await-in-loop
+        const skillOnlyRetained = await resolveSkillOnlyHostsRetainingArtifacts({
+          scope: singleScope,
+          excludedHostNames: supportedHosts,
+        });
+        const configuredRetainHostNames = [
+          ...new Set([...mcpRetained, ...skillOnlyRetained]),
+        ];
         skillSpinner.text = `Removing bundled skills from ${supportedHosts.length} host(s) (${singleScope})...`;
         // eslint-disable-next-line no-await-in-loop
         bundledSkillResults.push(
@@ -794,6 +1002,19 @@ async function runUninstallCommand(options) {
       }
       skillSpinner.succeed("Bundled skill uninstall complete");
     }
+
+    // Install-marker cleanup runs independently of bundled-skill discovery.
+    // A broken or trimmed package (missing `skills/`) can leave
+    // `bundledSkillNames` empty — the skill-removal pass above legitimately
+    // no-ops in that case, but the ownership markers must still be cleared,
+    // otherwise a later `uninstall`/`setup` would treat the uninstalled
+    // host as still owning shared skill dirs (wrong retention) or as a
+    // prior CLI install (false cross-mode conflict).
+    await cleanupHostInstallMarkers({
+      cwd: process.cwd(),
+      scopes,
+      hostNames: supportedHosts,
+    });
   }
 
   log.blank();
@@ -882,15 +1103,25 @@ Examples:
   ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --auth-mode device --codex --project")}
   ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode cli --codex --project")}
   ${pc.green("npx --yes @paradigma-inc/flywheel setup --mode mcp --yes --codex --claude --cursor")}
-  ${pc.green(
-    "npx --yes @paradigma-inc/flywheel uninstall --scope all --hosts codex,claude,opencode,cursor,pi-mono,hermes-agent,openclaw",
-  )}
+  ${pc.green("npx --yes @paradigma-inc/flywheel uninstall --yes --scope all")}
 `,
     );
 
   program
     .command("setup")
     .description("Set up Flywheel for your AI coding host")
+    .optionsGroup("Hosts:")
+    .option("--claude", "Set up for Claude Code")
+    .option("--cursor", "Set up for Cursor")
+    .option("--universal", "Set up for Universal (.agents/skills)")
+    .option("--antigravity", "Set up for Antigravity (.agent/skills)")
+    .option("--opencode", "Set up for OpenCode")
+    .option("--codex", "Set up for Codex")
+    .option("--gemini", "Set up for Gemini CLI")
+    .option("--pi-mono", "Set up for Pi (pi-mono)")
+    .option("--hermes-agent", "Set up for Hermes Agent")
+    .option("--openclaw", "Set up for OpenClaw")
+    .optionsGroup("Mode:")
     .option(
       "--mode <mode>",
       "Install mode: mcp | cli (required in non-interactive; prompted in TTY, default: mcp)",
@@ -899,33 +1130,31 @@ Examples:
     )
     .option("--mcp", "Alias for --mode mcp")
     .option("--cli", "Alias for --mode cli")
-    .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")
+    .optionsGroup("Scope:")
     .option(
       "-p, --project",
       "Configure for current project instead of globally",
     )
-    .option("-y, --yes", "Skip host selection prompts")
-    .option("--force", "Reconcile prior install mode automatically via uninstall")
+    .option("-y, --yes", "Skip confirmation prompts")
+    .optionsGroup("Authentication:")
     .option("--api-key <key>", "Use API key authentication")
+    .option("--oauth", "Use OAuth endpoint (IDE handles auth flow)")
+    .optionsGroup("Skills:")
+    .option("--install-skill", "Install or refresh the bundled Flywheel skills")
+    .option("--skip-skill", "Skip bundled skill installation (MCP-only setup)")
+    .optionsGroup("Advanced:")
     .option(
       "--auth-mode <mode>",
-      "Authentication mode: auto | loopback | device (default: auto)",
+      "API-key mint flow: 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})`,
     )
     .option("--name <name>", `MCP server name (default: ${SERVER_NAME})`)
+    .option("--force", "Reconcile prior install mode automatically via uninstall")
     .action(async (options) => {
       await runSetupCommandViaRouter(options);
     });
@@ -934,15 +1163,18 @@ Examples:
     .command("uninstall")
     .description("Remove Flywheel MCP entries and bundled skills from selected hosts")
     .option("--claude", "Uninstall for Claude Code")
+    .option("--cursor", "Uninstall for Cursor")
+    .option("--universal", "Uninstall bundled skills from .agents/skills")
+    .option("--antigravity", "Uninstall bundled skills from .agent/skills")
     .option("--opencode", "Uninstall for OpenCode")
     .option("--codex", "Uninstall for Codex")
-    .option("--cursor", "Uninstall for Cursor")
+    .option("--gemini", "Uninstall for Gemini CLI")
     .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",
+      "Comma-separated: claude,cursor,universal,antigravity,opencode,codex,gemini,pi-mono,hermes-agent,openclaw",
     )
     .option("--scope <scope>", "all | global | project")
     .option(