@paradigma-inc/flywheel 0.1.95 → 0.1.99

package/src/unified-cli.mjs

@@ -7,9 +7,12 @@ import {
 } from "./public-command-metadata.mjs";
 import { runRuntimeCli } from "./runtime/delegate.mjs";
 import { RUNTIME_ALIASES } from "./runtime/vendor/flywheel-cli-dist/commands/aliases.js";
+import { runUpdateCommand } from "./update/command.mjs";
+import { runCommandWithDeferredUpdateWarning } from "./update/warning.mjs";
 
 const ALIAS_RESERVED_COMMANDS = new Set([
   "setup",
+  "update",
   "uninstall",
   "completion",
   "help",
@@ -100,7 +103,14 @@ async function routeExplicitHelp(argv) {
   }
   const setupHelpArgv = setupHelpArgvFor(target, subcommand);
   if (setupHelpArgv) {
-    await runSetupCli(["node", "flywheel", ...setupHelpArgv]);
+    process.exitCode = await runSetupCli(
+      ["node", "flywheel", ...setupHelpArgv],
+      { exitOverride: true },
+    );
+    return;
+  }
+  if (target === "update") {
+    process.exitCode = await runUpdateCommand(["--help"]);
     return;
   }
   if (target === undefined) {
@@ -120,6 +130,17 @@ async function routeExplicitHelp(argv) {
   process.exitCode = exitCode;
 }
 
+async function runWithDeferredUpdateWarning(argv, runCommand) {
+  const exitCode = await runCommandWithDeferredUpdateWarning({
+    argv,
+    currentVersion: await loadPackageVersion(),
+    runCommand,
+  });
+  if (Number.isInteger(exitCode)) {
+    process.exitCode = exitCode;
+  }
+}
+
 export async function runUnifiedCli(argv = process.argv.slice(2)) {
   if (!Array.isArray(argv)) {
     throw new Error("runUnifiedCli expects an argv array.");
@@ -132,13 +153,14 @@ export async function runUnifiedCli(argv = process.argv.slice(2)) {
   }
 
   if (argv.length === 1 && USAGE_REQUEST_TOKENS.has(argv[0])) {
-    const publicPackageVersion = await loadPackageVersion();
-    const exitCode = await runRuntimeCli([
-      argv[0],
-      usageExtrasArg(),
-      usageVersionArg(publicPackageVersion),
-    ]);
-    process.exitCode = exitCode;
+    await runWithDeferredUpdateWarning(argv, async () => {
+      const publicPackageVersion = await loadPackageVersion();
+      return await runRuntimeCli([
+        argv[0],
+        usageExtrasArg(),
+        usageVersionArg(publicPackageVersion),
+      ]);
+    });
     return;
   }
 
@@ -164,8 +186,9 @@ export async function runUnifiedCli(argv = process.argv.slice(2)) {
       }
     }
     const passthrough = ["help", helpExtrasArg(), ...formatArgs];
-    const exitCode = await runRuntimeCli(passthrough);
-    process.exitCode = exitCode;
+    await runWithDeferredUpdateWarning(argv, async () =>
+      await runRuntimeCli(passthrough),
+    );
     return;
   }
 
@@ -178,8 +201,16 @@ export async function runUnifiedCli(argv = process.argv.slice(2)) {
   }
 
   const [command] = argv;
+  if (command === "update") {
+    process.exitCode = await runUpdateCommand(argv.slice(1));
+    return;
+  }
+
   if (command === "help") {
-    await routeExplicitHelp(argv);
+    await runWithDeferredUpdateWarning(argv, async () => {
+      await routeExplicitHelp(argv);
+      return process.exitCode ?? 0;
+    });
     return;
   }
 
@@ -188,16 +219,23 @@ export async function runUnifiedCli(argv = process.argv.slice(2)) {
     command === "uninstall" ||
     command === "completion"
   ) {
-    await runSetupCli(["node", "flywheel", ...argv]);
+    await runWithDeferredUpdateWarning(argv, async () => {
+      return await runSetupCli(["node", "flywheel", ...argv], {
+        exitOverride: true,
+      });
+    });
     return;
   }
 
   if (command.includes(":")) {
-    const exitCode = await runRuntimeCli(argv);
-    process.exitCode = exitCode;
+    await runWithDeferredUpdateWarning(argv, async () =>
+      await runRuntimeCli(argv),
+    );
     return;
   }
 
-  process.stderr.write(`unknown command: ${command}\n`);
-  process.exitCode = 1;
+  await runWithDeferredUpdateWarning(argv, async () => {
+    process.stderr.write(`unknown command: ${command}\n`);
+    return 1;
+  });
 }

package/src/update/cache.mjs

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { FLYWHEEL_PACKAGE_NAME } from "./version.mjs";
+
+export const UPDATE_CHECK_CACHE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export function resolveUpdateCheckCachePath({
+  env = process.env,
+  homeDir = os.homedir(),
+} = {}) {
+  const override = String(env.FLYWHEEL_UPDATE_CHECK_CACHE_PATH || "").trim();
+  if (override) {
+    return override;
+  }
+  return path.join(homeDir, ".flywheel", "update-check.json");
+}
+
+function parseCache(raw) {
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+  if (parsed.packageName !== FLYWHEEL_PACKAGE_NAME) {
+    return null;
+  }
+  if (typeof parsed.latestVersion !== "string" || !parsed.latestVersion.trim()) {
+    return null;
+  }
+  if (typeof parsed.nextCheckAt !== "string" || !parsed.nextCheckAt.trim()) {
+    return null;
+  }
+  const nextCheckAt = new Date(parsed.nextCheckAt);
+  if (Number.isNaN(nextCheckAt.getTime())) {
+    return null;
+  }
+  return parsed;
+}
+
+export async function readFreshUpdateCache({
+  cachePath = resolveUpdateCheckCachePath(),
+  now = () => new Date(),
+} = {}) {
+  let raw;
+  try {
+    raw = await readFile(cachePath, "utf8");
+  } catch {
+    return null;
+  }
+
+  try {
+    const parsed = parseCache(raw);
+    if (!parsed) return null;
+    if (new Date(parsed.nextCheckAt).getTime() <= now().getTime()) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+async function finalCacheIsValid(cachePath) {
+  try {
+    return parseCache(await readFile(cachePath, "utf8")) !== null;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeUpdateCacheAtomic({
+  cachePath = resolveUpdateCheckCachePath(),
+  latestVersion,
+  now = () => new Date(),
+  intervalMs = UPDATE_CHECK_CACHE_INTERVAL_MS,
+  pid = process.pid,
+  randomId = randomUUID,
+} = {}) {
+  const checkedAt = now();
+  const payload = {
+    packageName: FLYWHEEL_PACKAGE_NAME,
+    latestVersion,
+    checkedAt: checkedAt.toISOString(),
+    nextCheckAt: new Date(checkedAt.getTime() + intervalMs).toISOString(),
+  };
+  const tmpPath = `${cachePath}.${pid}.${randomId()}.tmp`;
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  await writeFile(tmpPath, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  try {
+    await rename(tmpPath, cachePath);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => {});
+    if (await finalCacheIsValid(cachePath)) {
+      return payload;
+    }
+    throw error;
+  }
+  return payload;
+}
+
+export async function getLatestVersionWithCache({
+  cachePath = resolveUpdateCheckCachePath(),
+  now = () => new Date(),
+  fetchLatestVersion,
+  intervalMs = UPDATE_CHECK_CACHE_INTERVAL_MS,
+} = {}) {
+  const cached = await readFreshUpdateCache({ cachePath, now });
+  if (cached) {
+    return cached.latestVersion;
+  }
+  const latestVersion = await fetchLatestVersion();
+  await writeUpdateCacheAtomic({
+    cachePath,
+    latestVersion,
+    now,
+    intervalMs,
+  });
+  return latestVersion;
+}

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