@paradigma-inc/flywheel 0.1.93 → 0.1.99

package/src/update/command.mjs

@@ -0,0 +1,438 @@
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { loadPackageVersion } from "../public-command-metadata.mjs";
+import { resolveFlywheelBinaryOnPath as defaultResolveFlywheelBinaryOnPath } from "../setup/modes/cli.mjs";
+import { discoverInstalledFlywheelState } from "./install-state.mjs";
+import { fetchLatestVersionFromRegistry } from "./registry.mjs";
+import {
+  renderRefreshPlan,
+  refreshExistingSetup,
+  resolveDiscoveryServerUrl,
+} from "./refresh.mjs";
+import {
+  compareInstalledToLatest,
+  FLYWHEEL_PACKAGE_NAME,
+} from "./version.mjs";
+
+const PACKAGE_SPEC = `${FLYWHEEL_PACKAGE_NAME}@latest`;
+const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";
+const PUBLIC_NPM_REGISTRY_ARGS = [
+  `--registry=${PUBLIC_NPM_REGISTRY}`,
+  `--@paradigma-inc:registry=${PUBLIC_NPM_REGISTRY}`,
+];
+const POSIX_MANUAL_INSTALL_COMMAND =
+  'npm install -g --prefix "${FLYWHEEL_INSTALL_PREFIX:-$HOME/.local}" --registry=https://registry.npmjs.org/ --@paradigma-inc:registry=https://registry.npmjs.org/ @paradigma-inc/flywheel@latest';
+const WINDOWS_MANUAL_INSTALL_COMMAND =
+  '$prefix = if ($env:FLYWHEEL_INSTALL_PREFIX) { $env:FLYWHEEL_INSTALL_PREFIX } else { "$env:USERPROFILE\\.local" }; npm install -g --prefix $prefix --registry=https://registry.npmjs.org/ --@paradigma-inc:registry=https://registry.npmjs.org/ @paradigma-inc/flywheel@latest';
+
+function isWindowsCommandShim(filePath, platform) {
+  return (
+    platform === "win32" &&
+    [".bat", ".cmd"].includes(path.extname(filePath).toLowerCase())
+  );
+}
+
+function shouldUseWindowsCommandShell(filePath, platform) {
+  return (
+    platform === "win32" &&
+    (path.extname(filePath) === "" || isWindowsCommandShim(filePath, platform))
+  );
+}
+
+function quoteWindowsCommandArgument(value) {
+  return `"${String(value).replaceAll('"', '""')}"`;
+}
+
+function resolveWindowsCommandShell(env) {
+  return env.ComSpec || env.COMSPEC || "cmd.exe";
+}
+
+function buildWindowsCommandLine(file, args) {
+  return `"${[
+    quoteWindowsCommandArgument(file),
+    ...args.map((arg) => quoteWindowsCommandArgument(arg)),
+  ].join(" ")}"`;
+}
+
+function buildSpawnFileInvocation({ file, args, env, platform }) {
+  if (!shouldUseWindowsCommandShell(file, platform)) {
+    return { command: file, args };
+  }
+  return {
+    command: resolveWindowsCommandShell(env),
+    args: ["/d", "/s", "/c", buildWindowsCommandLine(file, args)],
+  };
+}
+
+async function defaultSpawnFile(file, args, options = {}) {
+  const {
+    env = process.env,
+    platform = process.platform,
+    ...spawnOptions
+  } = options;
+  const invocation = buildSpawnFileInvocation({ file, args, env, platform });
+  return await new Promise((resolve, reject) => {
+    const child = spawn(invocation.command, invocation.args, {
+      stdio: "inherit",
+      env,
+      ...spawnOptions,
+    });
+    child.on("error", reject);
+    child.on("close", (code, signal) => {
+      resolve({
+        exitCode: typeof code === "number" ? code : signal ? 1 : 0,
+        signal,
+      });
+    });
+  });
+}
+
+function manualInstallCommand(platform) {
+  return platform === "win32"
+    ? WINDOWS_MANUAL_INSTALL_COMMAND
+    : POSIX_MANUAL_INSTALL_COMMAND;
+}
+
+async function pathExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function stripTrailingSlash(filePath) {
+  const parsed = path.parse(filePath);
+  let normalized = filePath;
+  while (
+    normalized.length > parsed.root.length &&
+    /[/\\]$/.test(normalized)
+  ) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+function normalizeInstallPrefix(rawPrefix, { cwd, homeDir }) {
+  const raw = String(rawPrefix || "").trim();
+  if (raw === "~") {
+    return homeDir;
+  }
+  if (raw.startsWith(`~${path.sep}`) || raw.startsWith("~/")) {
+    return stripTrailingSlash(path.join(homeDir, raw.slice(2)));
+  }
+  const resolved = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+  return stripTrailingSlash(resolved);
+}
+
+function parseFlags(argv) {
+  const flags = {
+    check: false,
+    dryRun: false,
+    yes: false,
+    help: false,
+    refreshExistingSetup: false,
+  };
+  const unknown = [];
+  for (const token of argv) {
+    if (token === "--check") flags.check = true;
+    else if (token === "--dry-run") flags.dryRun = true;
+    else if (token === "--yes") flags.yes = true;
+    else if (token === "--help" || token === "-h") flags.help = true;
+    else if (token === "--refresh-existing-setup") {
+      flags.refreshExistingSetup = true;
+    } else {
+      unknown.push(token);
+    }
+  }
+  return { flags, unknown };
+}
+
+function renderUpdateHelp() {
+  return [
+    "Usage: flywheel update [--check] [--dry-run] [--yes]",
+    "",
+    "Update the local Flywheel CLI package and refresh local setup artifacts.",
+    "",
+    "Options:",
+    "  --check    Print installed/latest version status without changing files.",
+    "  --dry-run  Print planned package, MCP, and skill refresh steps.",
+    "  --yes      Run prompt-free for agent execution.",
+    "  -h, --help Show this help.",
+    "",
+  ].join("\n");
+}
+
+function deriveManagedPrefixFromFlywheelBinaryPath({
+  binaryPath,
+  platform = process.platform,
+}) {
+  if (!binaryPath) {
+    return null;
+  }
+  const basename = path.basename(binaryPath).toLowerCase();
+  if (
+    platform === "win32" &&
+    ["flywheel", "flywheel.cmd", "flywheel.bat", "flywheel.exe"].includes(
+      basename,
+    )
+  ) {
+    return path.dirname(binaryPath);
+  }
+  if (basename !== "flywheel") {
+    return null;
+  }
+  const binDir = path.dirname(binaryPath);
+  if (path.basename(binDir).toLowerCase() !== "bin") {
+    return null;
+  }
+  return path.dirname(binDir);
+}
+
+async function resolveUpdatePrefix({
+  cwd = process.cwd(),
+  env = process.env,
+  homeDir = os.homedir(),
+  currentExecPath,
+  platform = process.platform,
+  resolveFlywheelBinaryOnPath = defaultResolveFlywheelBinaryOnPath,
+} = {}) {
+  const explicitPrefix = String(env.FLYWHEEL_INSTALL_PREFIX || "").trim();
+  if (explicitPrefix) {
+    return normalizeInstallPrefix(explicitPrefix, { cwd, homeDir });
+  }
+  const currentPrefix = deriveManagedPrefixFromFlywheelBinaryPath({
+    binaryPath: currentExecPath,
+    platform,
+  });
+  if (currentPrefix) {
+    return currentPrefix;
+  }
+  const pathBinary = await resolveFlywheelBinaryOnPath({ env, platform });
+  const pathPrefix = deriveManagedPrefixFromFlywheelBinaryPath({
+    binaryPath: pathBinary,
+    platform,
+  });
+  return pathPrefix || path.join(homeDir, ".local");
+}
+
+function resolveFlywheelBinaryInPrefix({ prefix, platform = process.platform }) {
+  if (platform === "win32") {
+    return path.join(prefix, "flywheel.cmd");
+  }
+  return path.join(prefix, "bin", "flywheel");
+}
+
+function isPathWithin(childPath, parentPath) {
+  const relative = path.relative(
+    path.resolve(parentPath),
+    path.resolve(childPath),
+  );
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+async function canUseManagedPrefix({
+  prefix,
+  currentExecPath,
+  flywheelBinaryPath,
+  pathExistsFn = pathExists,
+}) {
+  if (currentExecPath && isPathWithin(currentExecPath, prefix)) {
+    return true;
+  }
+  return await pathExistsFn(flywheelBinaryPath);
+}
+
+function statusLines(comparison) {
+  return [
+    `Installed ${FLYWHEEL_PACKAGE_NAME}: ${comparison.currentVersion}`,
+    `Latest ${FLYWHEEL_PACKAGE_NAME}: ${comparison.latestVersion}`,
+    `Status: ${comparison.status}`,
+    "",
+  ].join("\n");
+}
+
+function packageInstallArgs(prefix) {
+  return [
+    "install",
+    "-g",
+    "--prefix",
+    prefix,
+    ...PUBLIC_NPM_REGISTRY_ARGS,
+    PACKAGE_SPEC,
+  ];
+}
+
+function packageInstallCommand(prefix) {
+  return ["npm", ...packageInstallArgs(prefix)].join(" ");
+}
+
+async function runCheck({
+  currentVersion,
+  fetchLatestVersion,
+  stdout,
+  stderr,
+}) {
+  try {
+    const latestVersion = await fetchLatestVersion();
+    const comparison = compareInstalledToLatest({
+      currentVersion,
+      latestVersion,
+    });
+    stdout.write(statusLines(comparison));
+    return 0;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(
+      `Unable to check latest ${FLYWHEEL_PACKAGE_NAME} version: ${message}\n`,
+    );
+    return 1;
+  }
+}
+
+export async function runUpdateCommand(argv = [], deps = {}) {
+  const {
+    cwd = process.cwd(),
+    env = process.env,
+    homeDir = os.homedir(),
+    platform = process.platform,
+    stdout = process.stdout,
+    stderr = process.stderr,
+    currentExecPath = process.argv[1],
+    currentVersion = await loadPackageVersion(),
+    fetchLatestVersion = () => fetchLatestVersionFromRegistry(),
+    spawnFile = defaultSpawnFile,
+    discoverInstalledState = discoverInstalledFlywheelState,
+    refreshSetup = refreshExistingSetup,
+    pathExistsFn = pathExists,
+    resolveFlywheelBinaryOnPath = defaultResolveFlywheelBinaryOnPath,
+  } = deps;
+  const { flags, unknown } = parseFlags(argv);
+
+  if (flags.help) {
+    stdout.write(renderUpdateHelp());
+    return 0;
+  }
+  if (unknown.length > 0) {
+    stderr.write(`unknown update option: ${unknown[0]}\n`);
+    return 1;
+  }
+
+  if (flags.check) {
+    return await runCheck({
+      currentVersion,
+      fetchLatestVersion,
+      stdout,
+      stderr,
+    });
+  }
+
+  const prefix = await resolveUpdatePrefix({
+    cwd,
+    env,
+    homeDir,
+    currentExecPath,
+    platform,
+    resolveFlywheelBinaryOnPath,
+  });
+  const flywheelBinaryPath = resolveFlywheelBinaryInPrefix({ prefix, platform });
+
+  if (flags.dryRun) {
+    const state = await discoverInstalledState({
+      cwd,
+      env,
+      serverUrl: resolveDiscoveryServerUrl({ env }),
+    });
+    stdout.write(
+      renderRefreshPlan({
+        state,
+        prefix,
+        packageInstallCommand: packageInstallCommand(prefix),
+      }),
+    );
+    return 0;
+  }
+
+  if (flags.refreshExistingSetup) {
+    try {
+      return await refreshSetup({
+        cwd,
+        env,
+        stdout,
+        stderr,
+      });
+    } catch (error) {
+      const stepName = error?.stepName || "refresh-existing-setup";
+      const message = error instanceof Error ? error.message : String(error);
+      stderr.write(
+        `Failed refresh-existing-setup step ${stepName}: ${message}\n`,
+      );
+      return Number(error?.exitCode || 1);
+    }
+  }
+
+  if (
+    !(await canUseManagedPrefix({
+      prefix,
+      currentExecPath,
+      flywheelBinaryPath,
+      pathExistsFn,
+    }))
+  ) {
+    stderr.write(
+      [
+        `Unable to update ${FLYWHEEL_PACKAGE_NAME}: no managed Flywheel binary was found under ${prefix}.`,
+        `Manual command: ${manualInstallCommand(platform)}`,
+        "",
+      ].join("\n"),
+    );
+    return 2;
+  }
+
+  stderr.write(`Updating ${FLYWHEEL_PACKAGE_NAME} with npm.\n`);
+  let npmResult;
+  try {
+    npmResult = await spawnFile(
+      "npm",
+      packageInstallArgs(prefix),
+      { env, platform },
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`Failed to update ${FLYWHEEL_PACKAGE_NAME}: ${message}\n`);
+    return 1;
+  }
+  const npmExitCode = Number(npmResult?.exitCode || 0);
+  if (npmExitCode !== 0) {
+    stderr.write(`Failed to update ${FLYWHEEL_PACKAGE_NAME}.\n`);
+    return npmExitCode;
+  }
+
+  stderr.write("Refreshing local Flywheel setup artifacts.\n");
+  let refreshResult;
+  try {
+    refreshResult = await spawnFile(
+      flywheelBinaryPath,
+      ["update", "--refresh-existing-setup", "--yes"],
+      { env, platform },
+    );
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    stderr.write(`Failed refresh-existing-setup step spawn: ${message}\n`);
+    return 1;
+  }
+  const refreshExitCode = Number(refreshResult?.exitCode || 0);
+  if (refreshExitCode !== 0) {
+    stderr.write("Failed refresh-existing-setup step updated-binary.\n");
+    return refreshExitCode;
+  }
+
+  return 0;
+}

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