@paradigma-inc/flywheel 0.1.26 → 0.1.51

package/src/setup/mode.mjs

@@ -0,0 +1,113 @@
+export class SetupModeUsageError extends Error {
+  constructor(message, exitCode = 2) {
+    super(message);
+    this.name = "SetupModeUsageError";
+    this.exitCode = exitCode;
+  }
+}
+
+// Input-validation errors (empty --api-key, bad --base-url, etc.) should
+// surface as usage failures with their own exit code rather than be wrapped
+// into per-host setup failures. Without this discriminator, `setup --mode cli
+// --api-key "   "` previously bubbled through `runCliSetupMode`'s catch-all,
+// got reshaped into agentResults, and exited 4 (operational failure) instead
+// of 1 (usage error) — inconsistent with `--mode mcp`, which lets the same
+// validation error propagate naturally to the top-level handler.
+export class SetupInputUsageError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "SetupInputUsageError";
+    this.exitCode = exitCode;
+  }
+}
+
+const VALID_MODES = new Set(["mcp", "cli"]);
+
+function normalizeModeCandidate(rawMode) {
+  const mode = String(rawMode || "")
+    .trim()
+    .toLowerCase();
+  if (!mode) {
+    throw new SetupModeUsageError(
+      "Setup mode cannot be empty. Use --mode <mcp|cli>, --mcp, or --cli.",
+    );
+  }
+  if (!VALID_MODES.has(mode)) {
+    throw new SetupModeUsageError(
+      `Unsupported setup mode '${mode}'. Use --mode <mcp|cli>, --mcp, or --cli.`,
+    );
+  }
+  return mode;
+}
+
+function normalizeExplicitModes(options = {}) {
+  const requestedModes = [];
+  const rawMode = options.mode;
+  if (Array.isArray(rawMode)) {
+    for (const candidate of rawMode) {
+      requestedModes.push(normalizeModeCandidate(candidate));
+    }
+  } else if (typeof rawMode === "string" && rawMode.trim().length > 0) {
+    requestedModes.push(normalizeModeCandidate(rawMode));
+  }
+
+  if (options.mcp === true) {
+    requestedModes.push("mcp");
+  }
+  if (options.cli === true) {
+    requestedModes.push("cli");
+  }
+
+  return [...new Set(requestedModes)];
+}
+
+function ensureNoModeConflict(requestedModes) {
+  if (requestedModes.length <= 1) {
+    return;
+  }
+  throw new SetupModeUsageError(
+    "Conflicting setup mode flags. Use exactly one of --mode <mcp|cli>, --mcp, or --cli.",
+  );
+}
+
+function missingModeError() {
+  return new SetupModeUsageError(
+    "Setup mode is required when stdin/stdout are not a TTY. Use --mode mcp (writes MCP host config + installs skills) or --mode cli (installs skills + configures the flywheel CLI binary).",
+  );
+}
+
+function resolvePromptResult(rawMode) {
+  const mode = normalizeModeCandidate(rawMode);
+  if (!VALID_MODES.has(mode)) {
+    throw new SetupModeUsageError(
+      "Interactive mode selection must resolve to either 'mcp' or 'cli'.",
+    );
+  }
+  return mode;
+}
+
+export function resolveSetupMode(
+  options = {},
+  { isInteractive = process.stdout.isTTY === true, promptMode = null } = {},
+) {
+  const requestedModes = normalizeExplicitModes(options);
+  ensureNoModeConflict(requestedModes);
+
+  if (requestedModes.length === 1) {
+    return requestedModes[0];
+  }
+
+  if (!isInteractive) {
+    throw missingModeError();
+  }
+
+  if (typeof promptMode !== "function") {
+    throw missingModeError();
+  }
+
+  const prompted = promptMode();
+  if (prompted && typeof prompted.then === "function") {
+    return prompted.then(resolvePromptResult);
+  }
+  return resolvePromptResult(prompted);
+}

package/src/setup/modes/cli.mjs

@@ -0,0 +1,317 @@
+import { constants as fsConstants } from "node:fs";
+import { access, rm } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  cleanupInstalledSkillArtifactsForHosts,
+  inspectInstalledSkillArtifactsForHosts,
+  installBundledSkillForHosts,
+  listBundledSkills,
+  resolvePackageRoot,
+  SUPPORTED_INSTALL_SKILL_HOSTS,
+} from "../../skill-installer.mjs";
+import { SetupInputUsageError, SetupModeUsageError } from "../mode.mjs";
+import {
+  detectPriorModeForSetup,
+  formatPriorModeConflictError,
+} from "../shared/prior-mode-detect.mjs";
+import { writeRuntimeConfig } from "../../runtime/runtime-config.mjs";
+import { resolveSetupApiKey } from "../../setup-auth.mjs";
+import { validateModeHostSupport } from "../preflight.mjs";
+import { aggregateSetupResult } from "../shared/summary.mjs";
+
+// Windows npm/pnpm global installs write the CLI shim as `flywheel.cmd`
+// (sometimes `.exe`) rather than a bare `flywheel` — shell resolution relies
+// on the PATHEXT environment variable to pick the right suffix. Probing only
+// the literal name works on POSIX but always reports "missing" on Windows,
+// which then emits a spurious `npm install -g` hint even when Flywheel is on
+// PATH. Probe PATHEXT variants on win32 so the summary is accurate there too.
+const DEFAULT_WINDOWS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+
+function resolveCandidateExtensions({ platform, env }) {
+  if (platform !== "win32") {
+    return [""];
+  }
+  const rawPathExt =
+    typeof env.PATHEXT === "string" && env.PATHEXT.trim().length > 0
+      ? env.PATHEXT
+      : DEFAULT_WINDOWS_PATHEXT;
+  // Lowercase each suffix before probing: npm/pnpm global installs write the
+  // shim as lowercase (`flywheel.cmd`, `flywheel.exe`). Windows filesystems
+  // are case-insensitive so the probe still succeeds against uppercase files;
+  // on a case-sensitive filesystem (WSL bind-mounts, some test rigs) the
+  // lowercase form matches what installers actually put on disk.
+  const suffixes = rawPathExt
+    .split(";")
+    .map((ext) => ext.trim().toLowerCase())
+    .filter(Boolean);
+  // Probe bare name first so a no-suffix shim still wins; then each PATHEXT
+  // suffix in declared order (Windows shells use first-match).
+  return ["", ...suffixes];
+}
+
+// `npx --yes @paradigma-inc/flywheel setup` — the recommended invocation in
+// the tutorial — injects a transient shim at
+// `<cache>/_npx/<hash>/node_modules/.bin/flywheel` onto PATH for the duration
+// of that one command. A naive "first match wins" probe would report the
+// binary as "detected on PATH", suppress the `npm install -g` post-install
+// hint, then leave the user with bundled skills but no persistent CLI once
+// the npx process exits. Skip any PATH entry that sits inside an `_npx`
+// cache directory so only persistent installs count as "on PATH".
+function isNpxCacheDir(directory) {
+  const segments = directory.split(/[\\/]/);
+  return segments.includes("_npx");
+}
+
+export async function resolveFlywheelBinaryOnPath({
+  env = process.env,
+  platform = process.platform,
+} = {}) {
+  const rawPath = typeof env.PATH === "string" ? env.PATH : "";
+  const pathEntries = rawPath
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  const extensions = resolveCandidateExtensions({ platform, env });
+
+  for (const directory of pathEntries) {
+    if (isNpxCacheDir(directory)) {
+      continue;
+    }
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `flywheel${extension}`);
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await access(candidate, fsConstants.X_OK);
+        return candidate;
+      } catch {
+        // Keep searching.
+      }
+    }
+  }
+
+  return null;
+}
+
+export async function runCliSetupMode({
+  selectedHosts = [],
+  scope = "project",
+  cwd = process.cwd(),
+  force = false,
+  apiKey,
+  authMode = "auto",
+  baseUrl = "https://flywheel.paradigma.inc",
+  serverName = "flywheel",
+  serverUrl = "https://flywheel.paradigma.inc/mcp-server",
+  supportedCliHosts = SUPPORTED_INSTALL_SKILL_HOSTS,
+  detectPriorMode = detectPriorModeForSetup,
+  reconcilePriorMode = null,
+  resolvePackageRootFn = resolvePackageRoot,
+  listSkillNames = listBundledSkills,
+  installSkillForHosts = installBundledSkillForHosts,
+  inspectSkillArtifactsForHosts = inspectInstalledSkillArtifactsForHosts,
+  cleanupSkillArtifactsForHosts = cleanupInstalledSkillArtifactsForHosts,
+  removeDir = rm,
+  resolveSetupApiKeyFn = resolveSetupApiKey,
+  writeRuntimeConfigFn = writeRuntimeConfig,
+  resolveFlywheelBinaryPath = resolveFlywheelBinaryOnPath,
+  env = process.env,
+} = {}) {
+  const { supportedHosts, unsupportedHosts, warnings } = validateModeHostSupport({
+    mode: "cli",
+    selectedHosts,
+    supportedCliHosts,
+  });
+  const reconciled = [];
+
+  const priorModeMatch = await detectPriorMode({
+    targetMode: "cli",
+    selectedHosts: supportedHosts,
+    scope,
+    cwd,
+    serverName,
+    serverUrl,
+    supportedCliHosts,
+  });
+  if (priorModeMatch.priorMode && priorModeMatch.affectedHosts.length > 0) {
+    if (force !== true) {
+      throw new SetupModeUsageError(
+        formatPriorModeConflictError(priorModeMatch),
+      );
+    }
+
+    if (typeof reconcilePriorMode !== "function") {
+      throw new Error(
+        "reconcilePriorMode dependency is required when --force is used.",
+      );
+    }
+
+    const reconcileEntries = Array.isArray(priorModeMatch.entries)
+      ? priorModeMatch.entries
+      : priorModeMatch.affectedHosts.map((hostName) => ({
+          hostName,
+          serverNames: [],
+        }));
+
+    // Reconcile each detected entry by its actual serverName so renamed or
+    // drifted Flywheel MCP entries are removed, not just entries under the
+    // current request's --name. Without this the summary would falsely report
+    // "Reconciled: removed prior --mode mcp artifacts" while the drifted
+    // entry remained on disk and both modes stayed active.
+    for (const entry of reconcileEntries) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await reconcilePriorMode({
+          priorMode: priorModeMatch.priorMode,
+          targetMode: "cli",
+          hostNames: [entry.hostName],
+          serverNames: entry.serverNames,
+          scope,
+          cwd,
+          serverName,
+          serverUrl,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const reconcileError = new Error(
+          `Failed to reconcile prior --mode ${priorModeMatch.priorMode} artifacts for host ${entry.hostName}: ${message}`,
+        );
+        reconcileError.exitCode = 4;
+        throw reconcileError;
+      }
+    }
+
+    reconciled.push(
+      `removed prior --mode ${priorModeMatch.priorMode} artifacts for host(s): ${priorModeMatch.affectedHosts.join(", ")}`,
+    );
+  }
+
+  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,
+    });
+
+    const authResult = await resolveSetupApiKeyFn({
+      options: {
+        apiKey,
+        authMode,
+      },
+      baseUrl,
+    });
+    const runtimeConfig = await writeRuntimeConfigFn({
+      origin: baseUrl,
+      apiKey: authResult.apiKey,
+    });
+    runtimeConfigPath = runtimeConfig.configPath;
+
+    const resolvedBinaryPath = await resolveFlywheelBinaryPath({ env });
+    pathHint = resolvedBinaryPath
+      ? `flywheel binary detected on PATH at ${resolvedBinaryPath}.`
+      : "Next step: run `npm install -g @paradigma-inc/flywheel` to make the flywheel CLI available on PATH (required for bundled skills' CLI-mode routing).";
+
+    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;
+    }
+
+    // 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;
+    }
+
+    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,
+      });
+    }
+  }
+
+  for (const hostName of unsupportedHosts) {
+    agentResults.push({
+      agent: hostName,
+      success: null,
+      status: "skipped",
+      touchedFiles: [],
+      skippedSteps: ["unsupported-host"],
+      warnings: [`CLI mode skipped unsupported host ${hostName}.`],
+    });
+  }
+
+  const nextSteps =
+    supportedHosts.length > 0
+      ? [
+          `flywheel setup --mode cli --yes ${supportedHosts
+            .map((hostName) => `--${hostName}`)
+            .join(" ")}`,
+        ]
+      : ["flywheel setup --mode cli --yes --codex"];
+  if (pathHint) {
+    nextSteps.unshift(pathHint);
+  }
+
+  return aggregateSetupResult({
+    mode: "cli",
+    agentResults,
+    reconciled,
+    warnings,
+    nextSteps,
+  });
+}