@paradigma-inc/flywheel 0.1.154 → 0.2.0

package/src/setup/modes/cli.mjs

@@ -238,7 +238,9 @@ export async function runCliSetupMode({
     serverUrl,
     supportedCliHosts,
   });
-  if (priorModeMatch.priorMode && priorModeMatch.affectedHosts.length > 0) {
+  const hasPriorModeConflict =
+    Boolean(priorModeMatch.priorMode) && priorModeMatch.affectedHosts.length > 0;
+  if (hasPriorModeConflict) {
     if (force !== true) {
       throw new SetupModeUsageError(
         formatPriorModeConflictError(priorModeMatch),
@@ -250,7 +252,85 @@ export async function runCliSetupMode({
         "reconcilePriorMode dependency is required when --force is used.",
       );
     }
+  }
+
+  const packageRoot = resolvePackageRootFn();
+  const skillNames = await listSkillNames(packageRoot);
+  if (skillNames.length === 0) {
+    throw new Error(`No bundled skills found under ${packageRoot}/skills.`);
+  }
+
+  const agentResults = [];
+  let runtimeConfigPath = null;
+  let pathHint = null;
+  let cleanupState = null;
+
+  // Usage errors (bad flags, empty --api-key, mode conflicts) are
+  // user-input problems, not operational failures on any particular host.
+  // Rethrow so they surface with their intended exit code and let the
+  // top-level handler print the message once — matching how `--mode mcp`
+  // already behaves. Wrapping them as per-host failures would falsely
+  // attribute a user-input error to every selected host and force the
+  // setup summary to exit 4 (operational) instead of 1/2 (usage). Shared by
+  // the prerequisite stage and the skill stage below so both stages classify
+  // failures identically and cannot drift apart.
+  function recordOperationalFailure(error) {
+    if (
+      error instanceof SetupInputUsageError ||
+      error instanceof SetupModeUsageError
+    ) {
+      throw error;
+    }
+
+    const message = error instanceof Error ? error.message : String(error);
+    for (const hostName of supportedHosts) {
+      agentResults.push({
+        agent: hostName,
+        success: false,
+        touchedFiles: [],
+        skippedSteps: ["skill-install"],
+        warnings: [message],
+        error: message,
+      });
+    }
+  }
 
+  // Prerequisites that can fail run before anything destructive: resolving
+  // the API key, confirming the server accepts it, and writing the CLI
+  // runtime configuration all happen before the forced reconcile below
+  // removes an existing --mode mcp host entry. That way an ordinary
+  // auth/network/config failure leaves the prior MCP entry intact instead of
+  // a machine with neither mode working. A skill-install failure *after* a
+  // successful reconcile is a separate, accepted boundary: the runtime
+  // config is already written, so the CLI stays usable and rerunning the
+  // same command converges — this boundary is intentional, not a gap.
+  let prerequisiteFailed = false;
+  if (!skillOnlyOnly) {
+    try {
+      const resolvedAuth = authResult ?? await resolveSetupApiKeyFn({
+        options: {
+          apiKey,
+          authMode,
+        },
+        baseUrl,
+      });
+      await validateRemoteReadinessFn({
+        baseUrl,
+        apiKey: resolvedAuth.apiKey,
+      });
+      const runtimeConfig = await writeRuntimeConfigFn({
+        origin: baseUrl,
+        apiKey: resolvedAuth.apiKey,
+        credentialProfile: await credentialProfileForSetupBaseUrl(baseUrl),
+      });
+      runtimeConfigPath = runtimeConfig.configPath;
+    } catch (error) {
+      recordOperationalFailure(error);
+      prerequisiteFailed = true;
+    }
+  }
+
+  if (!prerequisiteFailed && hasPriorModeConflict) {
     const reconcileEntries = Array.isArray(priorModeMatch.entries)
       ? priorModeMatch.entries
       : priorModeMatch.affectedHosts.map((hostName) => ({
@@ -291,120 +371,71 @@ export async function runCliSetupMode({
     );
   }
 
-  const packageRoot = resolvePackageRootFn();
-  const skillNames = await listSkillNames(packageRoot);
-  if (skillNames.length === 0) {
-    throw new Error(`No bundled skills found under ${packageRoot}/skills.`);
-  }
-
-  const agentResults = [];
-  let runtimeConfigPath = null;
-  let pathHint = null;
-  let cleanupState = null;
-  try {
-    cleanupState = await inspectSkillArtifactsForHosts({
-      projectRoot: cwd,
-      hostNames: supportedHosts,
-      scope,
-      skillNames,
-    });
-
-    await installSkillForHosts({
-      projectRoot: cwd,
-      hostNames: supportedHosts,
-      scope,
-      serverName,
-      serverUrl,
-      skillNames,
-      // CLI-mode install: write a per-host ownership marker for every host
-      // so a later `setup --mode mcp --<host>` can detect this install via
-      // the marker even when the skills-root is shared with other hosts.
-      cliMode: true,
-    });
-
-    // Skill-only hosts (e.g. --universal, --antigravity) do not bind to the
-    // flywheel CLI binary — they just drop skill directories for the IDE or
-    // toolchain to read. Skip API-key minting, runtime-config writing, and
-    // the binary-on-PATH hint when every selected host is skill-only, so a
-    // `flywheel setup --universal --mode cli --yes` run is entirely hermetic.
-    if (!skillOnlyOnly) {
-      const resolvedAuth = authResult ?? await resolveSetupApiKeyFn({
-        options: {
-          apiKey,
-          authMode,
-        },
-        baseUrl,
-      });
-      await validateRemoteReadinessFn({
-        baseUrl,
-        apiKey: resolvedAuth.apiKey,
-      });
-      const runtimeConfig = await writeRuntimeConfigFn({
-        origin: baseUrl,
-        apiKey: resolvedAuth.apiKey,
-        credentialProfile: await credentialProfileForSetupBaseUrl(baseUrl),
-      });
-      runtimeConfigPath = runtimeConfig.configPath;
-
-      const resolvedBinaryPath = await resolveFlywheelBinaryPath({
-        env,
-        platform,
+  if (!prerequisiteFailed) {
+    try {
+      cleanupState = await inspectSkillArtifactsForHosts({
+        projectRoot: cwd,
+        hostNames: supportedHosts,
+        scope,
+        skillNames,
       });
-      pathHint = resolvedBinaryPath
-        ? `flywheel binary detected on PATH at ${resolvedBinaryPath}.`
-        : formatMissingFlywheelPathHint({ platform });
-    }
 
-    if (cleanupState?.backupRoot) {
-      await removeDir(cleanupState.backupRoot, { force: true, recursive: true });
-      cleanupState = null;
-    }
-
-    for (const hostName of supportedHosts) {
-      agentResults.push({
-        agent: hostName,
-        success: true,
-        touchedFiles: runtimeConfigPath ? [runtimeConfigPath] : [],
-        skippedSteps: [],
-        warnings: [],
-      });
-    }
-  } catch (error) {
-    if (cleanupState) {
-      await cleanupSkillArtifactsForHosts({
+      await installSkillForHosts({
         projectRoot: cwd,
         hostNames: supportedHosts,
-        priorState: cleanupState,
         scope,
+        serverName,
+        serverUrl,
         skillNames,
+        // CLI-mode install: write a per-host ownership marker for every host
+        // so a later `setup --mode mcp --<host>` can detect this install via
+        // the marker even when the skills-root is shared with other hosts.
+        cliMode: true,
       });
-      cleanupState = null;
-    }
 
-    // Usage errors (bad flags, empty --api-key, mode conflicts) are
-    // user-input problems, not operational failures on any particular host.
-    // Rethrow so they surface with their intended exit code and let the
-    // top-level handler print the message once — matching how `--mode mcp`
-    // already behaves. Wrapping them as per-host failures would falsely
-    // attribute a user-input error to every selected host and force the
-    // setup summary to exit 4 (operational) instead of 1/2 (usage).
-    if (
-      error instanceof SetupInputUsageError ||
-      error instanceof SetupModeUsageError
-    ) {
-      throw error;
-    }
+      // Skill-only hosts (e.g. --universal, --antigravity) do not bind to
+      // the flywheel CLI binary — they just drop skill directories for the
+      // IDE or toolchain to read. Skip the binary-on-PATH hint when every
+      // selected host is skill-only, so a
+      // `flywheel setup --universal --mode cli --yes` run is entirely
+      // hermetic.
+      if (!skillOnlyOnly) {
+        const resolvedBinaryPath = await resolveFlywheelBinaryPath({
+          env,
+          platform,
+        });
+        pathHint = resolvedBinaryPath
+          ? `flywheel binary detected on PATH at ${resolvedBinaryPath}.`
+          : formatMissingFlywheelPathHint({ platform });
+      }
 
-    const message = error instanceof Error ? error.message : String(error);
-    for (const hostName of supportedHosts) {
-      agentResults.push({
-        agent: hostName,
-        success: false,
-        touchedFiles: [],
-        skippedSteps: ["skill-install"],
-        warnings: [message],
-        error: message,
-      });
+      if (cleanupState?.backupRoot) {
+        await removeDir(cleanupState.backupRoot, { force: true, recursive: true });
+        cleanupState = null;
+      }
+
+      for (const hostName of supportedHosts) {
+        agentResults.push({
+          agent: hostName,
+          success: true,
+          touchedFiles: runtimeConfigPath ? [runtimeConfigPath] : [],
+          skippedSteps: [],
+          warnings: [],
+        });
+      }
+    } catch (error) {
+      if (cleanupState) {
+        await cleanupSkillArtifactsForHosts({
+          projectRoot: cwd,
+          hostNames: supportedHosts,
+          priorState: cleanupState,
+          scope,
+          skillNames,
+        });
+        cleanupState = null;
+      }
+
+      recordOperationalFailure(error);
     }
   }
 

package/src/update/cache.mjs

@@ -24,8 +24,10 @@ export function resolveUpdateCheckCachePath({
       String(env.LOCALAPPDATA || "").trim() ||
       path.join(homeDir, "AppData", "Local");
   } else {
-    cacheRoot =
-      String(env.XDG_CACHE_HOME || "").trim() || path.join(homeDir, ".cache");
+    const xdgCacheHome = String(env.XDG_CACHE_HOME || "").trim();
+    cacheRoot = path.isAbsolute(xdgCacheHome)
+      ? xdgCacheHome
+      : path.join(homeDir, ".cache");
   }
   return path.join(cacheRoot, "flywheel", "update-check.json");
 }