@paradigma-inc/flywheel 0.1.52 → 0.1.60

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

@@ -9,9 +9,11 @@ import {
   SERVER_NAME,
   detectHosts,
   getHost,
+  isSkillOnlyHost,
   normalizeHosts,
 } from "../../agents.mjs";
 import {
+  readEntryServerUrl,
   readNamedConfigEntry,
   readJsonConfig,
   readTomlServerEntry,
@@ -26,6 +28,7 @@ import {
   formatSupportedInstallSkillHosts,
   inspectInstalledSkillArtifactsForHosts,
   installBundledSkillForHosts,
+  isDirectCopySkillHost,
   listBundledSkills,
   partitionInstallSkillHosts,
   resolveInstalledSkillDir,
@@ -94,9 +97,12 @@ function normalizeServerName(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");
@@ -112,6 +118,9 @@ function mcpCandidatesForScope(host, scope) {
 
 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") {
@@ -126,7 +135,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,
   };
 }
@@ -151,6 +160,21 @@ async function inspectInstallSkillHosts({
   const driftHosts = [];
 
   for (const hostName of hostNames) {
+    const host = getHost(hostName);
+    // Skill-only hosts (universal, antigravity) never write an MCP config, so
+    // they are not candidates for "needs setup" / "drift" / "matching"
+    // classification. Skipping them here is what keeps the auth-resolution
+    // gate downstream accurate: without this branch they would land in
+    // `needsSetupHosts` and force an API-key mint on `setup --mode mcp
+    // --universal --skip-skill`, which is a pure no-op path that must stay
+    // hermetic (no browser, no blocking prompt).
+    if (isSkillOnlyHost(host)) {
+      hostStates.set(hostName, {
+        classification: "skill-only",
+        mcpPath: null,
+      });
+      continue;
+    }
     // eslint-disable-next-line no-await-in-loop
     const existingState = await readExistingServerState(
       hostName,
@@ -315,7 +339,53 @@ async function resolveApiKey(options, baseUrl) {
   }
 }
 
-function buildSetupResultRows({ selectedHosts, hostStates, setupResult }) {
+/**
+ * Classify an agent result for the human-readable MCP setup summary.
+ *
+ * The terminal outcomes are:
+ *   - "failed"    → explicit host-level failure (success === false).
+ *   - "skipped"   → the host was intentionally bypassed (skill-only host in
+ *                   MCP mode, or any agent result that carries success === null
+ *                   or status === "skipped"). Agents that fall into this
+ *                   bucket must NOT be rendered as failed, because the setup
+ *                   itself exited 0 and the user's expectation is that a
+ *                   green exit implies a green summary row.
+ *   - "already configured"      → the desired MCP entry was already on disk.
+ *   - "configured (OAuth)"      → oauth mode wrote a config without any
+ *                                 Authorization header; labelling this as
+ *                                 "API Key" would be inaccurate and would
+ *                                 confuse users auditing the auth model.
+ *   - "configured with API Key" → default MCP-mode success path, which writes
+ *                                 a Bearer token into the host config.
+ */
+function classifyAgentOutcome(agentResult, { oauthMode = false } = {}) {
+  if (agentResult.success === false) {
+    return "failed";
+  }
+  if (
+    agentResult.success === null ||
+    agentResult.status === "skipped" ||
+    (Array.isArray(agentResult.skippedSteps) &&
+      (agentResult.skippedSteps.includes("skill-only-host") ||
+        agentResult.skippedSteps.includes("unsupported-host")))
+  ) {
+    return "skipped";
+  }
+  const alreadyConfigured =
+    Array.isArray(agentResult.skippedSteps) &&
+    agentResult.skippedSteps.includes("already-configured");
+  if (alreadyConfigured) {
+    return "already configured";
+  }
+  return oauthMode ? "configured (OAuth)" : "configured with API Key";
+}
+
+function buildSetupResultRows({
+  selectedHosts,
+  hostStates,
+  setupResult,
+  oauthMode = false,
+}) {
   const byAgent = new Map(
     setupResult.agentResults.map((result) => [result.agent, result]),
   );
@@ -331,23 +401,14 @@ function buildSetupResultRows({ selectedHosts, hostStates, setupResult }) {
       };
     }
 
-    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");
-
+    const status = classifyAgentOutcome(agentResult, { oauthMode });
     return {
       host: host.displayName,
-      status: alreadyConfigured ? "already configured" : "configured with API Key",
+      status,
       filePath:
-        agentResult.touchedFiles[0] || hostStates.get(hostName)?.mcpPath || "(unknown)",
+        agentResult.touchedFiles?.[0] ||
+        hostStates.get(hostName)?.mcpPath ||
+        "(unknown)",
     };
   });
 }
@@ -402,6 +463,12 @@ function resolveExperimentalSyncAgentsForHosts(supportedHosts) {
   const seenAgentNames = new Set();
 
   for (const hostName of supportedHosts) {
+    // Direct-copy hosts (gemini, universal, antigravity) bypass the `skills`
+    // CLI entirely, so they have no agent name to sync with. Skip them from
+    // the experimental_sync guidance block.
+    if (isDirectCopySkillHost(hostName)) {
+      continue;
+    }
     const agentName = resolveSkillsAgentName(hostName);
     if (seenAgentNames.has(agentName)) {
       continue;
@@ -522,6 +589,13 @@ export async function runMcpModeCommand(options, deps = {}) {
     throw new Error(NON_INTERACTIVE_SKILL_DECISION_ERROR);
   }
 
+  const oauthMode = options.oauth === true;
+  if (oauthMode && Object.hasOwn(options, "apiKey")) {
+    throw new SetupModeUsageError(
+      "--api-key and --oauth are mutually exclusive: choose one.",
+    );
+  }
+
   const scope = options.project ? "project" : "global";
   const baseUrl = normalizeBaseUrl(options.baseUrl || DEFAULT_BASE_URL);
   const serverUrl = `${baseUrl}/mcp-server`;
@@ -682,8 +756,7 @@ export async function runMcpModeCommand(options, deps = {}) {
     let apiKey = null;
     const explicitApiKeyProvided = Object.hasOwn(options, "apiKey");
     const shouldResolveApiKey =
-      needsSetupHosts.length > 0 ||
-      explicitApiKeyProvided;
+      !oauthMode && (needsSetupHosts.length > 0 || explicitApiKeyProvided);
     if (shouldResolveApiKey) {
       apiKey = await resolveApiKey(options, baseUrl);
       if (!apiKey) {
@@ -714,6 +787,11 @@ export async function runMcpModeCommand(options, deps = {}) {
       serverName,
       serverUrl,
       apiKey,
+      // Tell the writers to reconcile auth-mode mismatches (Authorization
+      // header added/removed) only when the user explicitly set `--oauth` or
+      // `--api-key`. Without that, a passive rerun must stay idempotent and
+      // preserve the existing bearer header on disk rather than stripping it.
+      enforceAuthMode: oauthMode || explicitApiKeyProvided,
       detectPriorMode: async () => ({
         priorMode: null,
         affectedHosts: [],
@@ -749,6 +827,7 @@ export async function runMcpModeCommand(options, deps = {}) {
       selectedHosts: hosts,
       hostStates,
       setupResult,
+      oauthMode,
     });
 
     if (skillDecisionMode !== "guided") {

package/src/setup/modes/mcp.mjs

@@ -1,6 +1,9 @@
 import path from "node:path";
 
-import { getHost as defaultGetHost } from "../../agents.mjs";
+import {
+  getHost as defaultGetHost,
+  isSkillOnlyHost,
+} from "../../agents.mjs";
 import { SUPPORTED_INSTALL_SKILL_HOSTS } from "../../skill-installer.mjs";
 import { resolveMcpPath as defaultResolveMcpPath } from "../../mcp-writer.mjs";
 import { SetupModeUsageError } from "../mode.mjs";
@@ -38,6 +41,12 @@ export async function runMcpSetupMode({
   serverName,
   serverUrl,
   apiKey,
+  // `enforceAuthMode` is the "explicit auth intent" signal forwarded by the
+  // CLI layer (true when `--oauth` is set or `--api-key` was passed). When
+  // true, writers reconcile a mismatched Authorization header on an existing
+  // entry; when false, they stay idempotent by name so a benign rerun does
+  // not wipe the previously-minted bearer key.
+  enforceAuthMode = false,
   supportedCliHosts = SUPPORTED_INSTALL_SKILL_HOSTS,
   detectPriorMode = detectPriorModeForSetup,
   reconcilePriorMode = null,
@@ -116,6 +125,19 @@ export async function runMcpSetupMode({
     let host = null;
     try {
       host = getHost(hostName);
+      if (isSkillOnlyHost(host)) {
+        agentResults.push({
+          agent: hostName,
+          success: null,
+          status: "skipped",
+          touchedFiles: [],
+          skippedSteps: ["skill-only-host"],
+          warnings: [
+            `${host.displayName} is a skill-only host; MCP config write skipped.`,
+          ],
+        });
+        continue;
+      }
       const candidates = resolveCandidatesForScope(host, scope, cwd);
       const filePath = await resolveMcpPath(candidates);
       const entry = host.mcp.buildEntry({ serverUrl, apiKey });
@@ -127,6 +149,7 @@ export async function runMcpSetupMode({
           configKey: host.mcp.configKey,
           serverName,
           entry,
+          enforceAuthMode,
         });
       } else if (host.mcp.configType === "yaml") {
         patchResult = await patchYamlServer({
@@ -134,6 +157,7 @@ export async function runMcpSetupMode({
           configKey: host.mcp.configKey,
           serverName,
           entry,
+          enforceAuthMode,
         });
       } else {
         patchResult = await patchJsonServer({
@@ -141,6 +165,7 @@ export async function runMcpSetupMode({
           configKey: host.mcp.configKey,
           serverName,
           entry,
+          enforceAuthMode,
         });
       }
 

package/src/setup/shared/prior-mode-detect.mjs

@@ -1,10 +1,15 @@
 import path from "node:path";
 import { access, readFile } from "node:fs/promises";
 
-import { getHost as defaultGetHost } from "../../agents.mjs";
+import {
+  getHost as defaultGetHost,
+  isSkillOnlyHost,
+  SKILL_ONLY_HOST_NAMES,
+} from "../../agents.mjs";
 import {
   parseTomlSectionName,
   parseTomlStringValue,
+  readEntryServerUrl,
   readJsonConfig as defaultReadJsonConfig,
   readNamedConfigEntry as defaultReadNamedConfigEntry,
   readTomlServerEntry as defaultReadTomlServerEntry,
@@ -15,6 +20,7 @@ import {
   listBundledSkills as defaultListBundledSkills,
   resolveInstalledSkillDir as defaultResolveInstalledSkillDir,
   resolvePackageRoot as defaultResolvePackageRoot,
+  resolveFlywheelInstalledMarkerPath,
   SUPPORTED_INSTALL_SKILL_HOSTS,
 } from "../../skill-installer.mjs";
 
@@ -70,7 +76,8 @@ async function hasMatchingMcpEntry({
         ? await readYamlConfig(filePath)
         : await readJsonConfig(filePath);
     const entry = readNamedConfigEntry(config, host.mcp.configKey, serverName);
-    return typeof entry?.url === "string" && entry.url === serverUrl;
+    const entryUrl = readEntryServerUrl(entry);
+    return entryUrl !== null && entryUrl === serverUrl;
   } catch {
     return false;
   }
@@ -87,8 +94,8 @@ function originOf(url) {
 // A URL is treated as a Flywheel MCP endpoint only when both its pathname is
 // `/mcp-server` AND its origin is Flywheel-identifying. "Flywheel-identifying"
 // means either (a) the hostname contains the substring "flywheel" (covers
-// `flywheel.paradigma.inc`, `flywheel-staging.*`, self-hosted
-// `flywheel.<tenant>.*`, etc.) or (b) the URL's full origin (scheme + host +
+// the canonical `flywheel.paradigma.inc`, subdomain variants, and self-hosted
+// `flywheel.<tenant>.*`) or (b) the URL's full origin (scheme + host +
 // port) matches the target base URL's origin, so dev installs against
 // `http://localhost:8000` and self-hosted tenants still round-trip. Comparing
 // full origin rather than hostname alone is load-bearing on multi-tenant
@@ -215,13 +222,8 @@ export async function findFlywheelMcpEntryNames({
     }
     const matches = [];
     for (const [entryName, entry] of Object.entries(section)) {
-      if (
-        entry &&
-        typeof entry === "object" &&
-        !Array.isArray(entry) &&
-        typeof entry.url === "string" &&
-        isFlywheelMcpUrl(entry.url, targetOrigin)
-      ) {
+      const entryUrl = readEntryServerUrl(entry);
+      if (entryUrl !== null && isFlywheelMcpUrl(entryUrl, targetOrigin)) {
         matches.push(entryName);
       }
     }
@@ -231,6 +233,90 @@ export async function findFlywheelMcpEntryNames({
   }
 }
 
+/**
+ * Determine whether a truly skill-only host's ownership marker is present at
+ * the skills-root that `hostName` would write into. The two destination
+ * roots can coincide on shared paths — e.g. `--universal` writes into
+ * `.agents/skills/` which is also where `--codex` / `--opencode` / `--cursor`
+ * land. When a skill-only host marker is present there, any skill artifacts
+ * at that root are attributable to the skill-only host, not to `hostName`.
+ *
+ * This MUST iterate `SKILL_ONLY_HOST_NAMES`, not the wider direct-copy set:
+ * Gemini CLI also uses the direct-copy skill path but is MCP-capable, so
+ * attributing its own `.gemini/skills/` artifacts to itself via this helper
+ * would silently suppress the legitimate cross-mode conflict when the user
+ * transitions `--mode cli --gemini` → `--mode mcp --gemini`.
+ */
+async function skillsRootClaimedBySkillOnlyHost({
+  hostName,
+  scope,
+  cwd,
+  skillNames,
+  resolveInstalledSkillDir,
+}) {
+  if (!Array.isArray(skillNames) || skillNames.length === 0) {
+    return false;
+  }
+  const candidateSkillPath = resolveInstalledSkillDir(
+    cwd,
+    hostName,
+    scope,
+    skillNames[0],
+  );
+  const candidateSkillsRoot = path.dirname(candidateSkillPath);
+
+  // Case where the target host has its own install marker: the artifacts
+  // are co-owned — the skill-only marker alone no longer fully explains the
+  // skill dir contents, so the suppression must NOT fire. This is the
+  // difference between:
+  //   `setup --mode cli --universal`           → only universal marker
+  //   `setup --mode cli --universal --codex`   → universal + codex markers
+  // In the first case, codex's MCP setup is a fresh install and no conflict
+  // should be raised. In the second case, codex had a real CLI install of
+  // its own and the cross-mode conflict must fire.
+  try {
+    const selfMarkerPath = resolveFlywheelInstalledMarkerPath(cwd, hostName, scope);
+    if (await pathExists(selfMarkerPath)) {
+      return false;
+    }
+  } catch {
+    // hostName isn't registered with the flywheel skill installer; nothing
+    // to subtract — fall through to the skill-only scan below.
+  }
+
+  // Note: there is no reliable post-hoc signal for a CLI install of an
+  // MCP-capable host that pre-dates the per-host ownership marker scheme.
+  // `skills-lock.json` would seem like one, but its entries are keyed by
+  // skill name (not by agent) and are left behind by BOTH CLI-mode installs
+  // and MCP-mode installs with `--install-skill`, including stale entries
+  // that survive a host uninstall. Using the lock as a legacy fallback
+  // therefore false-positives on the common flow "MCP install → uninstall →
+  // universal install → MCP re-install", so we do not treat it as a cross-
+  // mode conflict signal. The legacy marker-less upgrade cohort (users on a
+  // release before ownership markers existed) can pass `--force` or re-run
+  // their CLI setup to acquire the marker; from there everything converges
+  // on the accurate per-host signal.
+  for (const skillOnlyHostName of SKILL_ONLY_HOST_NAMES) {
+    // Skill-only hosts whose destination path cannot overlap this host's
+    // path cannot explain any artifact found here. Only markers at the same
+    // skills-root are load-bearing.
+    let markerPath;
+    try {
+      markerPath = resolveFlywheelInstalledMarkerPath(cwd, skillOnlyHostName, scope);
+    } catch {
+      continue;
+    }
+    if (path.dirname(markerPath) !== candidateSkillsRoot) {
+      continue;
+    }
+    // eslint-disable-next-line no-await-in-loop
+    if (await pathExists(markerPath)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 async function hostHasBundledSkillArtifacts({
   hostName,
   scope,
@@ -238,15 +324,32 @@ async function hostHasBundledSkillArtifacts({
   skillNames,
   resolveInstalledSkillDir,
 }) {
+  let foundAny = false;
   for (const skillName of skillNames) {
     // eslint-disable-next-line no-await-in-loop
     const skillPath = resolveInstalledSkillDir(cwd, hostName, scope, skillName);
     // eslint-disable-next-line no-await-in-loop
     if (await pathExists(skillPath)) {
-      return true;
+      foundAny = true;
+      break;
     }
   }
-  return false;
+  if (!foundAny) {
+    return false;
+  }
+  // Found skill artifacts at this host's path. Attribute them to a
+  // skill-only host that explicitly claims the same skills-root (via its
+  // installation marker) rather than to this host — otherwise an MCP host
+  // sharing `.agents/skills/` with `--universal` would be misreported as
+  // having a prior CLI-mode install of its own.
+  const claimed = await skillsRootClaimedBySkillOnlyHost({
+    hostName,
+    scope,
+    cwd,
+    skillNames,
+    resolveInstalledSkillDir,
+  });
+  return !claimed;
 }
 
 export function formatPriorModeConflictError({
@@ -363,7 +466,23 @@ export async function detectPriorModeForSetup({
     };
   }
 
-  const supportedHostSet = new Set(unique(supportedCliHosts));
+  // Skill-only hosts (universal, antigravity) never write an MCP config, so
+  // every one of their installs — regardless of whether it was invoked with
+  // `--mode cli` or `--mode mcp --install-skill` — leaves the same on-disk
+  // shape: bundled skill dirs and nothing else. Treating a lingering skill
+  // dir under such a host as "a prior CLI install" would raise a bogus
+  // cross-mode conflict on every rerun of the same command. Filter them
+  // out of the CLI candidate universe up front so a subsequent `--mode mcp`
+  // pass stays idempotent.
+  const supportedHostSet = new Set(
+    unique(supportedCliHosts).filter((hostName) => {
+      try {
+        return !isSkillOnlyHost(getHost(hostName));
+      } catch {
+        return true;
+      }
+    }),
+  );
   const mcpTouchedHosts = new Set([
     ...exactMatchHosts,
     ...flywheelEntryNamesByHost.keys(),