@paradigma-inc/flywheel 0.1.35 → 0.1.52

package/src/setup/modes/mcp.mjs

@@ -0,0 +1,176 @@
+import path from "node:path";
+
+import { getHost as defaultGetHost } 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";
+import { patchJsonServer as defaultPatchJsonServer } from "../io/patchers/json.mjs";
+import { patchTomlServer as defaultPatchTomlServer } from "../io/patchers/toml.mjs";
+import { patchYamlServer as defaultPatchYamlServer } from "../io/patchers/yaml.mjs";
+import {
+  detectPriorModeForSetup,
+  formatPriorModeConflictError,
+} from "../shared/prior-mode-detect.mjs";
+import { aggregateSetupResult } from "../shared/summary.mjs";
+
+function unique(values = []) {
+  return [...new Set(values)];
+}
+
+function resolveCandidatesForScope(host, scope, cwd) {
+  if (scope === "global") {
+    return host.mcp.globalPaths;
+  }
+  return host.mcp.projectPaths.map((candidate) => path.join(cwd, candidate));
+}
+
+function buildNextStep(selectedHosts) {
+  return `flywheel setup --mode mcp --yes ${selectedHosts
+    .map((hostName) => `--${hostName}`)
+    .join(" ")}`;
+}
+
+export async function runMcpSetupMode({
+  selectedHosts = [],
+  scope = "global",
+  cwd = process.cwd(),
+  force = false,
+  serverName,
+  serverUrl,
+  apiKey,
+  supportedCliHosts = SUPPORTED_INSTALL_SKILL_HOSTS,
+  detectPriorMode = detectPriorModeForSetup,
+  reconcilePriorMode = null,
+  getHost = defaultGetHost,
+  resolveMcpPath = defaultResolveMcpPath,
+  patchJsonServer = defaultPatchJsonServer,
+  patchTomlServer = defaultPatchTomlServer,
+  patchYamlServer = defaultPatchYamlServer,
+} = {}) {
+  const normalizedHosts = unique(selectedHosts);
+  const agentResults = [];
+  const reconciled = [];
+
+  const priorModeMatch = await detectPriorMode({
+    targetMode: "mcp",
+    selectedHosts: normalizedHosts,
+    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 using its actual serverName(s). Prior CLI
+    // installs carry no MCP entry names and the callback falls back to the
+    // current request's --name for the skill uninstall path; prior MCP installs
+    // may have drifted names and must be removed by those names.
+    for (const entry of reconcileEntries) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await reconcilePriorMode({
+          priorMode: priorModeMatch.priorMode,
+          targetMode: "mcp",
+          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(", ")}`,
+    );
+  }
+
+  for (const hostName of normalizedHosts) {
+    let host = null;
+    try {
+      host = getHost(hostName);
+      const candidates = resolveCandidatesForScope(host, scope, cwd);
+      const filePath = await resolveMcpPath(candidates);
+      const entry = host.mcp.buildEntry({ serverUrl, apiKey });
+
+      let patchResult;
+      if (host.mcp.configType === "toml") {
+        patchResult = await patchTomlServer({
+          filePath,
+          configKey: host.mcp.configKey,
+          serverName,
+          entry,
+        });
+      } else if (host.mcp.configType === "yaml") {
+        patchResult = await patchYamlServer({
+          filePath,
+          configKey: host.mcp.configKey,
+          serverName,
+          entry,
+        });
+      } else {
+        patchResult = await patchJsonServer({
+          filePath,
+          configKey: host.mcp.configKey,
+          serverName,
+          entry,
+        });
+      }
+
+      agentResults.push({
+        agent: hostName,
+        success: true,
+        touchedFiles: patchResult.touchedFiles,
+        skippedSteps: patchResult.alreadyExists ? ["already-configured"] : [],
+        warnings: [],
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      agentResults.push({
+        agent: host?.name || hostName,
+        success: false,
+        touchedFiles: [],
+        skippedSteps: ["mcp-write"],
+        warnings: [message],
+        error: message,
+      });
+    }
+  }
+
+  return aggregateSetupResult({
+    mode: "mcp",
+    agentResults,
+    reconciled,
+    nextSteps:
+      normalizedHosts.length > 0
+        ? [buildNextStep(normalizedHosts)]
+        : ["flywheel setup --mode mcp --yes --codex"],
+  });
+}

package/src/setup/preflight.mjs

@@ -0,0 +1,54 @@
+function unique(values = []) {
+  return [...new Set(values)];
+}
+
+export class SetupPreflightError extends Error {
+  constructor(message, exitCode = 2) {
+    super(message);
+    this.name = "SetupPreflightError";
+    this.exitCode = exitCode;
+  }
+}
+
+export function validateModeHostSupport({
+  mode,
+  selectedHosts = [],
+  supportedCliHosts = [],
+} = {}) {
+  const normalizedHosts = unique(selectedHosts);
+  const supportedCliHostSet = new Set(unique(supportedCliHosts));
+
+  if (mode !== "cli") {
+    return {
+      supportedHosts: normalizedHosts,
+      unsupportedHosts: [],
+      warnings: [],
+    };
+  }
+
+  const supportedHosts = normalizedHosts.filter((host) =>
+    supportedCliHostSet.has(host),
+  );
+  const unsupportedHosts = normalizedHosts.filter(
+    (host) => !supportedCliHostSet.has(host),
+  );
+
+  if (supportedHosts.length === 0 && unsupportedHosts.length > 0) {
+    throw new SetupPreflightError(
+      `CLI mode does not support selected hosts: ${unsupportedHosts.join(", ")}.`,
+    );
+  }
+
+  const warnings =
+    unsupportedHosts.length > 0
+      ? [
+          `CLI mode skipped unsupported hosts: ${unsupportedHosts.join(", ")}.`,
+        ]
+      : [];
+
+  return {
+    supportedHosts,
+    unsupportedHosts,
+    warnings,
+  };
+}

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

@@ -0,0 +1,412 @@
+import path from "node:path";
+import { access, readFile } from "node:fs/promises";
+
+import { getHost as defaultGetHost } from "../../agents.mjs";
+import {
+  parseTomlSectionName,
+  parseTomlStringValue,
+  readJsonConfig as defaultReadJsonConfig,
+  readNamedConfigEntry as defaultReadNamedConfigEntry,
+  readTomlServerEntry as defaultReadTomlServerEntry,
+  readYamlConfig as defaultReadYamlConfig,
+  resolveMcpPath as defaultResolveMcpPath,
+} from "../../mcp-writer.mjs";
+import {
+  listBundledSkills as defaultListBundledSkills,
+  resolveInstalledSkillDir as defaultResolveInstalledSkillDir,
+  resolvePackageRoot as defaultResolvePackageRoot,
+  SUPPORTED_INSTALL_SKILL_HOSTS,
+} from "../../skill-installer.mjs";
+
+function unique(values = []) {
+  return [...new Set(values)];
+}
+
+function sortHosts(hostNames = []) {
+  return [...hostNames].sort((left, right) => left.localeCompare(right));
+}
+
+function resolveCandidatesForScope(host, scope, cwd) {
+  if (scope === "global") {
+    return host.mcp.globalPaths;
+  }
+  return host.mcp.projectPaths.map((candidate) => path.join(cwd, candidate));
+}
+
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function hasMatchingMcpEntry({
+  hostName,
+  scope,
+  cwd,
+  serverName,
+  serverUrl,
+  getHost,
+  resolveMcpPath,
+  readTomlServerEntry,
+  readJsonConfig,
+  readYamlConfig,
+  readNamedConfigEntry,
+}) {
+  try {
+    const host = getHost(hostName);
+    const candidates = resolveCandidatesForScope(host, scope, cwd);
+    const filePath = await resolveMcpPath(candidates);
+
+    if (host.mcp.configType === "toml") {
+      const entry = await readTomlServerEntry(filePath, serverName);
+      return entry.exists && entry.url === serverUrl;
+    }
+
+    const config =
+      host.mcp.configType === "yaml"
+        ? await readYamlConfig(filePath)
+        : await readJsonConfig(filePath);
+    const entry = readNamedConfigEntry(config, host.mcp.configKey, serverName);
+    return typeof entry?.url === "string" && entry.url === serverUrl;
+  } catch {
+    return false;
+  }
+}
+
+function originOf(url) {
+  try {
+    return new URL(url).origin.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+// 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 +
+// 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
+// localhost setups: a user running `setup --mode cli --base-url
+// http://localhost:8000` must not have an unrelated
+// `http://localhost:11434/mcp-server` (say, a different dev service on the
+// same loopback) classified as a prior Flywheel install — without this check,
+// `--force` reconciliation would then uninstall that unrelated service.
+function isFlywheelMcpUrl(url, targetOrigin) {
+  if (typeof url !== "string" || url.trim().length === 0) {
+    return false;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.pathname !== "/mcp-server") {
+    return false;
+  }
+  if (parsed.hostname.toLowerCase().includes("flywheel")) {
+    return true;
+  }
+  return targetOrigin !== null && parsed.origin.toLowerCase() === targetOrigin;
+}
+
+async function findFlywheelTomlEntryNames(filePath, targetOrigin) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch {
+    return [];
+  }
+  const lines = raw.replace(/\r\n/g, "\n").split("\n");
+  const matches = [];
+  let currentServerName = null;
+  let currentUrl = null;
+
+  const commitCurrent = () => {
+    if (
+      currentServerName !== null &&
+      currentUrl !== null &&
+      isFlywheelMcpUrl(currentUrl, targetOrigin)
+    ) {
+      matches.push(currentServerName);
+    }
+    currentServerName = null;
+    currentUrl = null;
+  };
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const sectionName = parseTomlSectionName(trimmed);
+
+    if (sectionName) {
+      commitCurrent();
+      // Capture any tail after `mcp_servers.` as the candidate server name.
+      // `normalizeServerName` in setup accepts names containing dots (TOML
+      // allows dotted section keys as a single server name, e.g.
+      // `[mcp_servers.legacy.flywheel]`), so restricting to `[A-Za-z0-9_-]+`
+      // would let a valid cross-mode install slip through detection. The
+      // `url` presence check in commitCurrent() is what discriminates real
+      // server sections from sub-tables like `.http_headers`: sub-tables
+      // carry headers, not urls, so they never commit.
+      const serverMatch = sectionName.match(/^mcp_servers\.(.+)$/);
+      if (serverMatch) {
+        currentServerName = serverMatch[1];
+      }
+      continue;
+    }
+
+    if (currentServerName === null) continue;
+
+    const urlMatch = trimmed.match(/^url\s*=\s*(.+)$/);
+    if (!urlMatch) continue;
+    currentUrl = parseTomlStringValue(urlMatch[1]);
+  }
+  commitCurrent();
+
+  return unique(matches);
+}
+
+export async function findFlywheelMcpEntryNames({
+  hostName,
+  scope,
+  cwd = process.cwd(),
+  targetOrigin = null,
+  getHost = defaultGetHost,
+  resolveMcpPath = defaultResolveMcpPath,
+  readJsonConfig = defaultReadJsonConfig,
+  readYamlConfig = defaultReadYamlConfig,
+}) {
+  try {
+    const host = getHost(hostName);
+    const candidates = resolveCandidatesForScope(host, scope, cwd);
+    const filePath = await resolveMcpPath(candidates);
+
+    if (host.mcp.configType === "toml") {
+      return await findFlywheelTomlEntryNames(filePath, targetOrigin);
+    }
+
+    const config =
+      host.mcp.configType === "yaml"
+        ? await readYamlConfig(filePath)
+        : await readJsonConfig(filePath);
+    const configKeyPath = Array.isArray(host.mcp.configKey)
+      ? host.mcp.configKey
+      : [host.mcp.configKey];
+    let section = config;
+    for (const key of configKeyPath) {
+      if (
+        !section ||
+        typeof section !== "object" ||
+        Array.isArray(section) ||
+        !(key in section)
+      ) {
+        return [];
+      }
+      section = section[key];
+    }
+    if (!section || typeof section !== "object" || Array.isArray(section)) {
+      return [];
+    }
+    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)
+      ) {
+        matches.push(entryName);
+      }
+    }
+    return unique(matches);
+  } catch {
+    return [];
+  }
+}
+
+async function hostHasBundledSkillArtifacts({
+  hostName,
+  scope,
+  cwd,
+  skillNames,
+  resolveInstalledSkillDir,
+}) {
+  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;
+    }
+  }
+  return false;
+}
+
+export function formatPriorModeConflictError({
+  priorMode,
+  affectedHosts,
+}) {
+  const hostList = sortHosts(affectedHosts).join(", ");
+  return `Flywheel is already installed in --mode ${priorMode} for host(s) ${hostList}. Run \`npx --yes @paradigma-inc/flywheel uninstall\` first, or re-run this command with --force to reconcile automatically.`;
+}
+
+export async function detectPriorModeForSetup({
+  targetMode,
+  selectedHosts = [],
+  scope = "project",
+  cwd = process.cwd(),
+  serverName = "flywheel",
+  serverUrl = "https://flywheel.paradigma.inc/mcp-server",
+  supportedCliHosts = SUPPORTED_INSTALL_SKILL_HOSTS,
+  getHost = defaultGetHost,
+  resolveMcpPath = defaultResolveMcpPath,
+  readTomlServerEntry = defaultReadTomlServerEntry,
+  readJsonConfig = defaultReadJsonConfig,
+  readYamlConfig = defaultReadYamlConfig,
+  readNamedConfigEntry = defaultReadNamedConfigEntry,
+  resolvePackageRootFn = defaultResolvePackageRoot,
+  listSkillNames = defaultListBundledSkills,
+  resolveInstalledSkillDir = defaultResolveInstalledSkillDir,
+} = {}) {
+  const normalizedHosts = unique(selectedHosts);
+  if (normalizedHosts.length === 0) {
+    return { priorMode: null, affectedHosts: [], entries: [] };
+  }
+
+  const targetOrigin = originOf(serverUrl);
+
+  // Two signals combine to identify a prior MCP install on a host:
+  //   1. exactMatchHosts — a server entry under the requested serverName with
+  //      the requested serverUrl (the canonical "already set up" signal).
+  //   2. flywheelEntryNamesByHost — any Flywheel-identifying entry (by
+  //      hostname + path) under that host, regardless of the entry's name.
+  //      This catches drifted or renamed Flywheel entries (for example a user
+  //      who installed under `--name legacy-flywheel`) so --force can actually
+  //      remove them instead of silently installing alongside.
+  const exactMatchHosts = [];
+  const flywheelEntryNamesByHost = new Map();
+  for (const hostName of normalizedHosts) {
+    // eslint-disable-next-line no-await-in-loop
+    if (
+      await hasMatchingMcpEntry({
+        hostName,
+        scope,
+        cwd,
+        serverName,
+        serverUrl,
+        getHost,
+        resolveMcpPath,
+        readTomlServerEntry,
+        readJsonConfig,
+        readYamlConfig,
+        readNamedConfigEntry,
+      })
+    ) {
+      exactMatchHosts.push(hostName);
+    }
+    // eslint-disable-next-line no-await-in-loop
+    const flywheelEntries = await findFlywheelMcpEntryNames({
+      hostName,
+      scope,
+      cwd,
+      targetOrigin,
+      getHost,
+      resolveMcpPath,
+      readJsonConfig,
+      readYamlConfig,
+    });
+    if (flywheelEntries.length > 0) {
+      flywheelEntryNamesByHost.set(hostName, flywheelEntries);
+    }
+  }
+
+  if (targetMode === "cli") {
+    // Any Flywheel MCP entry on a selected host must block a CLI-mode install
+    // without --force, not only entries matching the canonical serverName +
+    // serverUrl. A prior install under a renamed server or drifted base URL
+    // is still a prior MCP install, and missing it would silently leave both
+    // wirings active. Return per-host entry names so the reconcile path can
+    // uninstall the specific drifted entry rather than defaulting to the
+    // current request's --name (which may not exist on disk).
+    const affectedMap = new Map();
+    for (const hostName of exactMatchHosts) {
+      if (!affectedMap.has(hostName)) {
+        affectedMap.set(hostName, new Set());
+      }
+      affectedMap.get(hostName).add(serverName);
+    }
+    for (const [hostName, entryNames] of flywheelEntryNamesByHost) {
+      if (!affectedMap.has(hostName)) {
+        affectedMap.set(hostName, new Set());
+      }
+      for (const entryName of entryNames) {
+        affectedMap.get(hostName).add(entryName);
+      }
+    }
+    const entries = [...affectedMap.entries()]
+      .map(([hostName, serverNames]) => ({
+        hostName,
+        serverNames: [...serverNames].sort(),
+      }))
+      .sort((left, right) => left.hostName.localeCompare(right.hostName));
+    return {
+      priorMode: entries.length > 0 ? "mcp" : null,
+      affectedHosts: entries.map((entry) => entry.hostName),
+      entries,
+    };
+  }
+
+  const supportedHostSet = new Set(unique(supportedCliHosts));
+  const mcpTouchedHosts = new Set([
+    ...exactMatchHosts,
+    ...flywheelEntryNamesByHost.keys(),
+  ]);
+  const cliCandidateHosts = normalizedHosts.filter(
+    (hostName) =>
+      supportedHostSet.has(hostName) && !mcpTouchedHosts.has(hostName),
+  );
+  if (cliCandidateHosts.length === 0) {
+    return { priorMode: null, affectedHosts: [], entries: [] };
+  }
+
+  const packageRoot = resolvePackageRootFn();
+  const skillNames = await listSkillNames(packageRoot);
+  if (skillNames.length === 0) {
+    return { priorMode: null, affectedHosts: [], entries: [] };
+  }
+
+  const cliConfiguredHosts = [];
+  for (const hostName of cliCandidateHosts) {
+    // eslint-disable-next-line no-await-in-loop
+    if (
+      await hostHasBundledSkillArtifacts({
+        hostName,
+        scope,
+        cwd,
+        skillNames,
+        resolveInstalledSkillDir,
+      })
+    ) {
+      cliConfiguredHosts.push(hostName);
+    }
+  }
+
+  // Prior CLI installs have no MCP entry to remove; the reconcile path only
+  // needs host + scope. Surface empty serverNames so callers can branch on it.
+  const entries = sortHosts(cliConfiguredHosts).map((hostName) => ({
+    hostName,
+    serverNames: [],
+  }));
+  return {
+    priorMode: entries.length > 0 ? "cli" : null,
+    affectedHosts: entries.map((entry) => entry.hostName),
+    entries,
+  };
+}

package/src/setup/shared/skill.mjs

@@ -0,0 +1,12 @@
+import {
+  formatSupportedInstallSkillHosts,
+  partitionInstallSkillHosts,
+} from "../../skill-installer.mjs";
+
+export function partitionSkillHosts(hostNames) {
+  return partitionInstallSkillHosts(hostNames);
+}
+
+export function getSupportedSkillHostsText() {
+  return formatSupportedInstallSkillHosts();
+}