@paradigma-inc/flywheel 0.1.95 → 0.1.99

package/src/update/install-state.mjs

@@ -0,0 +1,135 @@
+import { access } from "node:fs/promises";
+
+import {
+  ALL_HOST_NAMES,
+  SERVER_NAME,
+  getHost as defaultGetHost,
+  isSkillOnlyHost,
+} from "../agents.mjs";
+import { resolveRuntimeConfigPath } from "../runtime/runtime-config.mjs";
+import {
+  resolveFlywheelInstalledMarkerPath,
+  SUPPORTED_INSTALL_SKILL_HOSTS,
+} from "../skill-installer.mjs";
+import { findFlywheelMcpEntries as defaultFindFlywheelMcpEntries } from "../setup/shared/prior-mode-detect.mjs";
+
+const DEFAULT_SERVER_URL = "https://flywheel.paradigma.inc/mcp-server";
+
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function baseUrlFromServerUrl(serverUrl) {
+  try {
+    return new URL(serverUrl).origin;
+  } catch {
+    return "https://flywheel.paradigma.inc";
+  }
+}
+
+function originOf(url) {
+  try {
+    return new URL(url).origin.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function sortArtifacts(artifacts) {
+  return artifacts.sort((left, right) => {
+    const byHost = left.hostName.localeCompare(right.hostName);
+    if (byHost !== 0) return byHost;
+    const byScope = left.scope.localeCompare(right.scope);
+    if (byScope !== 0) return byScope;
+    return String(left.serverName || "").localeCompare(
+      String(right.serverName || ""),
+    );
+  });
+}
+
+export async function discoverInstalledFlywheelState({
+  cwd = process.cwd(),
+  env = process.env,
+  hostNames = ALL_HOST_NAMES,
+  scopes = ["project", "global"],
+  serverUrl = DEFAULT_SERVER_URL,
+  getHost = defaultGetHost,
+  findFlywheelMcpEntries = defaultFindFlywheelMcpEntries,
+  markerPathForHost = resolveFlywheelInstalledMarkerPath,
+  runtimeConfigPath = resolveRuntimeConfigPath({ env }),
+  pathExistsFn = pathExists,
+} = {}) {
+  const targetOrigin = originOf(serverUrl);
+  const mcpArtifacts = [];
+  const cliArtifacts = [];
+  const seenCli = new Set();
+  const runtimeConfigExists = await pathExistsFn(runtimeConfigPath);
+
+  for (const hostName of hostNames) {
+    let host;
+    try {
+      host = getHost(hostName);
+    } catch {
+      continue;
+    }
+
+    for (const scope of scopes) {
+      if (!isSkillOnlyHost(host)) {
+        // eslint-disable-next-line no-await-in-loop
+        const entries = await findFlywheelMcpEntries({
+          hostName,
+          scope,
+          cwd,
+          targetOrigin,
+          trustedServerNames: [SERVER_NAME],
+          getHost,
+        });
+        for (const entry of entries) {
+          mcpArtifacts.push({
+            hostName,
+            scope,
+            serverName: entry.serverName,
+            serverUrl: entry.serverUrl,
+            baseUrl: baseUrlFromServerUrl(entry.serverUrl),
+          });
+        }
+      }
+
+      if (!SUPPORTED_INSTALL_SKILL_HOSTS.includes(hostName)) {
+        continue;
+      }
+      let markerPath;
+      try {
+        markerPath = markerPathForHost(cwd, hostName, scope);
+      } catch {
+        continue;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      const markerExists = await pathExistsFn(markerPath);
+      if (!markerExists) {
+        continue;
+      }
+      const key = `${hostName}\0${scope}`;
+      if (seenCli.has(key)) {
+        continue;
+      }
+      seenCli.add(key);
+      cliArtifacts.push({
+        hostName,
+        scope,
+        runtimeConfigExists,
+        markerPath,
+      });
+    }
+  }
+
+  return {
+    mcpArtifacts: sortArtifacts(mcpArtifacts),
+    cliArtifacts: sortArtifacts(cliArtifacts),
+  };
+}

package/src/update/refresh.mjs

@@ -0,0 +1,393 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { load as loadYaml } from "js-yaml";
+
+import {
+  ALL_HOST_NAMES,
+  SERVER_NAME,
+  getHost,
+  isSkillOnlyHost,
+} from "../agents.mjs";
+import {
+  installBundledSkillForHosts as defaultInstallBundledSkillForHosts,
+  listBundledSkills as defaultListBundledSkills,
+  resolveInstalledSkillDir,
+  resolvePackageRoot,
+  SUPPORTED_INSTALL_SKILL_HOSTS,
+} from "../skill-installer.mjs";
+import { runMcpModeCommand as defaultRunMcpModeCommand } from "../setup/modes/mcp-command.mjs";
+import { resolveFlywheelBinaryOnPath as defaultResolveFlywheelBinaryOnPath } from "../setup/modes/cli.mjs";
+import { resolveSetupBaseUrl } from "../setup/base-url.mjs";
+import { discoverInstalledFlywheelState } from "./install-state.mjs";
+
+const DEFAULT_SERVER_URL = "https://flywheel.paradigma.inc/mcp-server";
+const INSTALL_NEXT_STEP =
+  "curl -fsSL https://flywheel.paradigma.inc/install | sh";
+const OPENAI_AGENT_METADATA_RELATIVE_PATH = path.join("agents", "openai.yaml");
+
+function sortByHostScope(values) {
+  return [...values].sort((left, right) => {
+    const byHost = left.hostName.localeCompare(right.hostName);
+    if (byHost !== 0) return byHost;
+    return left.scope.localeCompare(right.scope);
+  });
+}
+
+function normalizeBaseUrl(value) {
+  const normalized = String(value || "").trim();
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(normalized);
+  } catch {
+    throw new Error("Base URL must be a valid absolute URL.");
+  }
+
+  if (parsedUrl.pathname !== "/" || parsedUrl.search || parsedUrl.hash) {
+    throw new Error(
+      "Base URL must be a public Flywheel origin without a path, query, or hash.",
+    );
+  }
+
+  return parsedUrl.origin;
+}
+
+export function resolveDiscoveryServerUrl({ env }) {
+  return `${normalizeBaseUrl(resolveSetupBaseUrl({ env }))}/mcp-server`;
+}
+
+function readMcpTargetFromOpenAiMetadata(metadataRaw) {
+  const metadata = loadYaml(metadataRaw);
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return null;
+  }
+  const dependencies = metadata.dependencies;
+  if (
+    !dependencies ||
+    typeof dependencies !== "object" ||
+    Array.isArray(dependencies)
+  ) {
+    return null;
+  }
+  const tools = dependencies.tools;
+  if (!Array.isArray(tools)) {
+    return null;
+  }
+  for (const tool of tools) {
+    if (!tool || typeof tool !== "object" || Array.isArray(tool)) {
+      continue;
+    }
+    if (tool.type !== "mcp") {
+      continue;
+    }
+    const serverName =
+      typeof tool.value === "string" ? tool.value.trim() : "";
+    const serverUrl = typeof tool.url === "string" ? tool.url.trim() : "";
+    if (!serverName && !serverUrl) {
+      continue;
+    }
+    return {
+      serverName: serverName || SERVER_NAME,
+      serverUrl: serverUrl || DEFAULT_SERVER_URL,
+    };
+  }
+  return null;
+}
+
+async function readInstalledSkillMcpTarget({
+  artifact,
+  cwd,
+  skillNames,
+}) {
+  for (const skillName of skillNames) {
+    const metadataPath = path.join(
+      resolveInstalledSkillDir(
+        cwd,
+        artifact.hostName,
+        artifact.scope,
+        skillName,
+      ),
+      OPENAI_AGENT_METADATA_RELATIVE_PATH,
+    );
+    let metadataRaw;
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      metadataRaw = await readFile(metadataPath, "utf8");
+    } catch (error) {
+      if (["ENOENT", "ENOTDIR"].includes(error?.code)) {
+        continue;
+      }
+      throw errorWithStep(
+        `cli-skill-target:${artifact.hostName}:${artifact.scope}`,
+        `Unable to read installed CLI skill MCP target at ${metadataPath}.`,
+      );
+    }
+    try {
+      const target = readMcpTargetFromOpenAiMetadata(metadataRaw);
+      if (target) {
+        return target;
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw errorWithStep(
+        `cli-skill-target:${artifact.hostName}:${artifact.scope}`,
+        `Unable to parse installed CLI skill MCP target at ${metadataPath}: ${message}`,
+      );
+    }
+  }
+  return null;
+}
+
+async function resolveCliArtifactMcpTarget({
+  artifact,
+  cwd,
+  skillNames,
+}) {
+  const target = await readInstalledSkillMcpTarget({
+    artifact,
+    cwd,
+    skillNames,
+  });
+  if (target) {
+    return target;
+  }
+  return {
+    serverName: SERVER_NAME,
+    serverUrl: DEFAULT_SERVER_URL,
+  };
+}
+
+function hostScopeKey(artifact) {
+  return `${artifact.hostName}\0${artifact.scope}`;
+}
+
+async function resolveMcpSkillTargets({ mcpArtifacts, cwd, skillNames }) {
+  const targets = new Map();
+  const seen = new Set();
+  for (const artifact of mcpArtifacts) {
+    if (!SUPPORTED_INSTALL_SKILL_HOSTS.includes(artifact.hostName)) {
+      continue;
+    }
+    const key = hostScopeKey(artifact);
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    // eslint-disable-next-line no-await-in-loop
+    const target = await readInstalledSkillMcpTarget({
+      artifact,
+      cwd,
+      skillNames,
+    });
+    if (target) {
+      targets.set(key, target);
+    }
+  }
+  return targets;
+}
+
+function mcpSkillTargetMatchesArtifact(target, artifact) {
+  return (
+    target?.serverName === artifact.serverName &&
+    target?.serverUrl === artifact.serverUrl
+  );
+}
+
+async function groupCliArtifactsByScopeAndTarget({
+  cliArtifacts,
+  cwd,
+  skillNames,
+}) {
+  const groups = new Map();
+  for (const artifact of cliArtifacts) {
+    // eslint-disable-next-line no-await-in-loop
+    const target = await resolveCliArtifactMcpTarget({
+      artifact,
+      cwd,
+      skillNames,
+    });
+    const key = JSON.stringify([
+      artifact.scope,
+      target.serverName,
+      target.serverUrl,
+    ]);
+    if (!groups.has(key)) {
+      groups.set(key, {
+        scope: artifact.scope,
+        hostNames: [],
+        serverName: target.serverName,
+        serverUrl: target.serverUrl,
+      });
+    }
+    groups.get(key).hostNames.push(artifact.hostName);
+  }
+  return [...groups.values()].map((group) => ({
+    ...group,
+    hostNames: [...new Set(group.hostNames)].sort(),
+  }));
+}
+
+function errorWithStep(stepName, message) {
+  const error = new Error(message);
+  error.stepName = stepName;
+  return error;
+}
+
+function cliArtifactsRequireBinaryPath(cliArtifacts) {
+  return cliArtifacts.some((artifact) => {
+    try {
+      return !isSkillOnlyHost(getHost(artifact.hostName));
+    } catch {
+      return true;
+    }
+  });
+}
+
+export function renderRefreshPlan({
+  state,
+  prefix,
+  packageInstallCommand = `npm install -g --prefix ${prefix} @paradigma-inc/flywheel@latest`,
+} = {}) {
+  const lines = [`Package update: ${packageInstallCommand}`];
+  const mcpArtifacts = sortByHostScope(state?.mcpArtifacts || []);
+  const cliArtifacts = sortByHostScope(state?.cliArtifacts || []);
+
+  for (const artifact of mcpArtifacts) {
+    lines.push(
+      `MCP refresh: ${artifact.hostName} ${artifact.scope} ${artifact.serverName} (${artifact.serverUrl})`,
+    );
+  }
+  for (const artifact of cliArtifacts) {
+    lines.push(`CLI skill refresh: ${artifact.hostName} ${artifact.scope}`);
+  }
+  if (mcpArtifacts.length === 0 && cliArtifacts.length === 0) {
+    lines.push(
+      `No local setup artifacts detected. Next step: ${INSTALL_NEXT_STEP}`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export async function refreshExistingSetup({
+  cwd = process.cwd(),
+  env = process.env,
+  hostNames = ALL_HOST_NAMES,
+  scopes = ["project", "global"],
+  stdout = process.stdout,
+  stderr = process.stderr,
+  discoverInstalledState = discoverInstalledFlywheelState,
+  runMcpModeCommand = defaultRunMcpModeCommand,
+  installBundledSkillForHosts = defaultInstallBundledSkillForHosts,
+  listBundledSkills = defaultListBundledSkills,
+  resolveFlywheelBinaryOnPath = defaultResolveFlywheelBinaryOnPath,
+} = {}) {
+  const state = await discoverInstalledState({
+    cwd,
+    env,
+    hostNames,
+    scopes,
+    serverUrl: resolveDiscoveryServerUrl({ env }),
+  });
+  const mcpArtifacts = sortByHostScope(state.mcpArtifacts || []);
+  const cliArtifacts = sortByHostScope(state.cliArtifacts || []);
+
+  if (mcpArtifacts.length === 0 && cliArtifacts.length === 0) {
+    stdout.write(
+      `No existing Flywheel setup artifacts were detected to refresh.\nNext step: ${INSTALL_NEXT_STEP}\n`,
+    );
+    return 0;
+  }
+
+  const needsSkillNames =
+    cliArtifacts.length > 0 ||
+    mcpArtifacts.some((artifact) =>
+      SUPPORTED_INSTALL_SKILL_HOSTS.includes(artifact.hostName),
+    );
+  const skillNames = needsSkillNames
+    ? await listBundledSkills(resolvePackageRoot())
+    : [];
+  let mcpSkillTargets = new Map();
+  if (skillNames.length > 0) {
+    mcpSkillTargets = await resolveMcpSkillTargets({
+      mcpArtifacts,
+      cwd,
+      skillNames,
+    });
+  }
+
+  for (const artifact of mcpArtifacts) {
+    const supportsSkillInstall = SUPPORTED_INSTALL_SKILL_HOSTS.includes(
+      artifact.hostName,
+    );
+    const shouldInstallSkill =
+      supportsSkillInstall &&
+      mcpSkillTargetMatchesArtifact(
+        mcpSkillTargets.get(hostScopeKey(artifact)),
+        artifact,
+      );
+    const options = {
+      [artifact.hostName]: true,
+      project: artifact.scope === "project",
+      name: artifact.serverName,
+      baseUrl: artifact.baseUrl,
+      yes: true,
+      ...(shouldInstallSkill
+        ? { installSkill: true }
+        : {
+            skipSkill: true,
+            ...(!supportsSkillInstall
+              ? { allowUnsupportedSkillInstall: true }
+              : {}),
+          }),
+    };
+    // Validate host names before dispatching so failures name the refresh step
+    // instead of surfacing as a generic object-shape error downstream.
+    getHost(artifact.hostName);
+    // eslint-disable-next-line no-await-in-loop
+    const result = await runMcpModeCommand(options, { force: true });
+    const exitCode = Number(result?.exitCode || 0);
+    if (exitCode !== 0) {
+      throw errorWithStep(
+        `mcp:${artifact.hostName}:${artifact.scope}:${artifact.serverName}`,
+        `MCP refresh failed for ${artifact.hostName} ${artifact.scope} ${artifact.serverName}.`,
+      );
+    }
+  }
+
+  if (cliArtifacts.length > 0) {
+    if (skillNames.length === 0) {
+      throw errorWithStep("cli-skills", "No bundled Flywheel skills found.");
+    }
+    const cliGroups = await groupCliArtifactsByScopeAndTarget({
+      cliArtifacts,
+      cwd,
+      skillNames,
+    });
+    for (const group of cliGroups) {
+      // eslint-disable-next-line no-await-in-loop
+      await installBundledSkillForHosts({
+        projectRoot: cwd,
+        hostNames: group.hostNames,
+        scope: group.scope,
+        serverName: group.serverName,
+        serverUrl: group.serverUrl,
+        skillNames,
+        cliMode: true,
+      });
+    }
+    if (cliArtifactsRequireBinaryPath(cliArtifacts)) {
+      const binaryPath = await resolveFlywheelBinaryOnPath({ env });
+      if (!binaryPath) {
+        throw errorWithStep(
+          "cli-binary-path",
+          "flywheel binary is not on PATH after CLI skill refresh.",
+        );
+      }
+      stderr.write(`Verified flywheel binary on PATH at ${binaryPath}.\n`);
+    }
+  }
+
+  return 0;
+}
+
+export { INSTALL_NEXT_STEP };

package/src/update/registry.mjs

@@ -0,0 +1,35 @@
+export const FLYWHEEL_REGISTRY_URL =
+  "https://registry.npmjs.org/@paradigma-inc%2Fflywheel";
+export const UPDATE_CHECK_TIMEOUT_MS = 1000;
+
+export async function fetchLatestVersionFromRegistry({
+  fetchImpl = globalThis.fetch,
+  registryUrl = FLYWHEEL_REGISTRY_URL,
+  timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
+} = {}) {
+  if (typeof fetchImpl !== "function") {
+    throw new Error("Unable to check latest @paradigma-inc/flywheel version.");
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(registryUrl, {
+      signal: controller.signal,
+      headers: { accept: "application/json" },
+    });
+    if (!response || response.ok !== true) {
+      throw new Error("registry request failed");
+    }
+    const payload = await response.json();
+    const latest = payload?.["dist-tags"]?.latest;
+    if (typeof latest !== "string" || latest.trim().length === 0) {
+      throw new Error("registry latest dist-tag missing");
+    }
+    return latest.trim();
+  } catch {
+    throw new Error("Unable to check latest @paradigma-inc/flywheel version.");
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/update/version.mjs

@@ -0,0 +1,59 @@
+import semver from "semver";
+
+export const FLYWHEEL_PACKAGE_NAME = "@paradigma-inc/flywheel";
+
+export function normalizeVersion(value) {
+  const cleaned = semver.clean(String(value ?? "").trim());
+  if (!cleaned || !semver.valid(cleaned)) {
+    return null;
+  }
+  return cleaned;
+}
+
+export function isPrereleaseVersion(value) {
+  const normalized = normalizeVersion(value);
+  return normalized ? semver.prerelease(normalized) !== null : false;
+}
+
+export function compareInstalledToLatest({ currentVersion, latestVersion }) {
+  const current = normalizeVersion(currentVersion);
+  const latest = normalizeVersion(latestVersion);
+  if (!current || !latest) {
+    throw new Error(`Invalid ${FLYWHEEL_PACKAGE_NAME} version metadata.`);
+  }
+
+  if (semver.gt(current, latest)) {
+    return {
+      currentVersion: current,
+      latestVersion: latest,
+      status: "installed version is newer than npm latest",
+      stale: false,
+    };
+  }
+
+  if (semver.gt(latest, current)) {
+    const latestIsPrerelease = semver.prerelease(latest) !== null;
+    const currentIsPrerelease = semver.prerelease(current) !== null;
+    if (latestIsPrerelease && !currentIsPrerelease) {
+      return {
+        currentVersion: current,
+        latestVersion: latest,
+        status: "current",
+        stale: false,
+      };
+    }
+    return {
+      currentVersion: current,
+      latestVersion: latest,
+      status: "update available",
+      stale: true,
+    };
+  }
+
+  return {
+    currentVersion: current,
+    latestVersion: latest,
+    status: "current",
+    stale: false,
+  };
+}