@paradigma-inc/flywheel 0.1.93 → 0.1.99

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,
+  };
+}

package/src/update/warning.mjs

@@ -0,0 +1,109 @@
+import {
+  readFreshUpdateCache,
+  resolveUpdateCheckCachePath,
+  writeUpdateCacheAtomic,
+} from "./cache.mjs";
+import { fetchLatestVersionFromRegistry } from "./registry.mjs";
+import {
+  compareInstalledToLatest,
+  FLYWHEEL_PACKAGE_NAME,
+  isPrereleaseVersion,
+} from "./version.mjs";
+
+const VERSION_REQUEST_TOKENS = new Set(["--version", "-v", "version"]);
+
+function isTruthyEnvFlag(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized === "1" || normalized === "true";
+}
+
+export function shouldSuppressUpdateWarning({
+  argv = [],
+  env = process.env,
+} = {}) {
+  if (isTruthyEnvFlag(env.NO_UPDATE_NOTIFIER)) return true;
+  if (isTruthyEnvFlag(env.FLYWHEEL_DISABLE_UPDATE_NOTIFIER)) return true;
+  if (isTruthyEnvFlag(env.CI)) return true;
+  if (String(env.NODE_ENV || "").trim().toLowerCase() === "test") return true;
+  if (String(env.npm_lifecycle_event || "").trim() === "test") return true;
+  if (argv.length === 1 && VERSION_REQUEST_TOKENS.has(argv[0])) return true;
+  if (argv[0] === "update") return true;
+  return false;
+}
+
+export function renderUpdateWarning({ currentVersion, latestVersion }) {
+  return [
+    "",
+    `Flywheel CLI update available: ${currentVersion} -> ${latestVersion}.`,
+    `Run: flywheel update --yes`,
+    "Agent instruction: if you are acting for this user, run flywheel update --yes before continuing substantial Flywheel work.",
+    "Human note: this updates the local Flywheel CLI package and refreshes local setup artifacts.",
+    "",
+  ].join("\n");
+}
+
+export async function maybeRenderUpdateWarning({
+  argv = [],
+  currentVersion,
+  env = process.env,
+  cachePath = resolveUpdateCheckCachePath({ env }),
+  now = () => new Date(),
+  fetchLatestVersion = () => fetchLatestVersionFromRegistry(),
+} = {}) {
+  if (shouldSuppressUpdateWarning({ argv, env })) {
+    return null;
+  }
+  if (isPrereleaseVersion(currentVersion)) {
+    return null;
+  }
+
+  try {
+    const cached = await readFreshUpdateCache({ cachePath, now });
+    const latestVersion = cached?.latestVersion ?? (await fetchLatestVersion());
+    const comparison = compareInstalledToLatest({
+      currentVersion,
+      latestVersion,
+    });
+    if (!cached) {
+      await writeUpdateCacheAtomic({ cachePath, latestVersion, now });
+    }
+    if (!comparison.stale) {
+      return null;
+    }
+    return renderUpdateWarning(comparison);
+  } catch {
+    return null;
+  }
+}
+
+export async function runCommandWithDeferredUpdateWarning({
+  argv = [],
+  runCommand,
+  currentVersion,
+  env = process.env,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  cachePath,
+  now,
+  fetchLatestVersion,
+} = {}) {
+  if (typeof runCommand !== "function") {
+    throw new Error("runCommandWithDeferredUpdateWarning requires runCommand.");
+  }
+
+  const result = await runCommand({ stdout, stderr });
+  const warning = await maybeRenderUpdateWarning({
+    argv,
+    currentVersion,
+    env,
+    cachePath,
+    now,
+    fetchLatestVersion,
+  });
+  if (warning) {
+    stderr.write(warning);
+  }
+  return result;
+}
+
+export { FLYWHEEL_PACKAGE_NAME };