@paradigma-inc/flywheel 0.1.93 → 0.1.99

package/src/runtime/vendor/flywheel-cli-dist/generatedProductTelemetryContract.js.map

@@ -1 +1 @@
-{"version":3,"file":"generatedProductTelemetryContract.js","sourceRoot":"","sources":["../src/generatedProductTelemetryContract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generatedProductTelemetryContract.js","sourceRoot":"","sources":["../src/generatedProductTelemetryContract.ts"],"names":[],"mappings":"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"}

package/src/runtime/vendor/manifest.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommit": "ae7d207c5a0e787e36307094ce25ad2bf18700ff",
+  "sourceCommit": "8c6b8edcadb0b2513c57e53ddcfbceca76c1c2c4",
   "files": [
     "auth/active-key-id.d.ts",
     "auth/active-key-id.js",

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

@@ -123,7 +123,34 @@ function isFlywheelMcpUrl(url, targetOrigin) {
   return targetOrigin !== null && parsed.origin.toLowerCase() === targetOrigin;
 }
 
-async function findFlywheelTomlEntryNames(filePath, targetOrigin) {
+function isMcpServerUrl(url) {
+  if (typeof url !== "string" || url.trim().length === 0) {
+    return false;
+  }
+  try {
+    return new URL(url).pathname === "/mcp-server";
+  } catch {
+    return false;
+  }
+}
+
+function shouldTreatAsFlywheelMcpEntry({
+  serverName,
+  serverUrl,
+  targetOrigin,
+  trustedServerNames,
+}) {
+  return (
+    isFlywheelMcpUrl(serverUrl, targetOrigin) ||
+    (trustedServerNames.has(serverName) && isMcpServerUrl(serverUrl))
+  );
+}
+
+async function findFlywheelTomlEntries(
+  filePath,
+  targetOrigin,
+  trustedServerNames,
+) {
   let raw;
   try {
     raw = await readFile(filePath, "utf8");
@@ -139,9 +166,14 @@ async function findFlywheelTomlEntryNames(filePath, targetOrigin) {
     if (
       currentServerName !== null &&
       currentUrl !== null &&
-      isFlywheelMcpUrl(currentUrl, targetOrigin)
+      shouldTreatAsFlywheelMcpEntry({
+        serverName: currentServerName,
+        serverUrl: currentUrl,
+        targetOrigin,
+        trustedServerNames,
+      })
     ) {
-      matches.push(currentServerName);
+      matches.push({ serverName: currentServerName, serverUrl: currentUrl });
     }
     currentServerName = null;
     currentUrl = null;
@@ -176,26 +208,48 @@ async function findFlywheelTomlEntryNames(filePath, targetOrigin) {
   }
   commitCurrent();
 
-  return unique(matches);
+  return uniqueEntries(matches);
+}
+
+function uniqueEntries(entries = []) {
+  const seen = new Set();
+  const out = [];
+  for (const entry of entries) {
+    const key = `${entry.serverName}\0${entry.serverUrl}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(entry);
+  }
+  return out.sort((left, right) => {
+    const byName = left.serverName.localeCompare(right.serverName);
+    if (byName !== 0) return byName;
+    return left.serverUrl.localeCompare(right.serverUrl);
+  });
 }
 
-export async function findFlywheelMcpEntryNames({
+export async function findFlywheelMcpEntries({
   hostName,
   scope,
   cwd = process.cwd(),
   targetOrigin = null,
+  trustedServerNames = [],
   getHost = defaultGetHost,
   resolveMcpPath = defaultResolveMcpPath,
   readJsonConfig = defaultReadJsonConfig,
   readYamlConfig = defaultReadYamlConfig,
 }) {
+  const trustedServerNameSet = new Set(trustedServerNames);
   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);
+      return await findFlywheelTomlEntries(
+        filePath,
+        targetOrigin,
+        trustedServerNameSet,
+      );
     }
 
     const config =
@@ -223,16 +277,29 @@ export async function findFlywheelMcpEntryNames({
     const matches = [];
     for (const [entryName, entry] of Object.entries(section)) {
       const entryUrl = readEntryServerUrl(entry);
-      if (entryUrl !== null && isFlywheelMcpUrl(entryUrl, targetOrigin)) {
-        matches.push(entryName);
+      if (
+        entryUrl !== null &&
+        shouldTreatAsFlywheelMcpEntry({
+          serverName: entryName,
+          serverUrl: entryUrl,
+          targetOrigin,
+          trustedServerNames: trustedServerNameSet,
+        })
+      ) {
+        matches.push({ serverName: entryName, serverUrl: entryUrl });
       }
     }
-    return unique(matches);
+    return uniqueEntries(matches);
   } catch {
     return [];
   }
 }
 
+export async function findFlywheelMcpEntryNames(options) {
+  const entries = await findFlywheelMcpEntries(options);
+  return entries.map((entry) => entry.serverName);
+}
+
 /**
  * Determine whether a truly skill-only host's ownership marker is present at
  * the skills-root that `hostName` would write into. The two destination

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