@mercury-fw/cli 0.28.3 → 0.28.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mercury-fw/cli
 
+## 0.28.4
+
+### Patch Changes
+
+- 65e78fe: `mfw create` (and `bun create mercury-agent`) checks the registry for a newer `@mercury-fw/cli` first, and when it's behind, as a copy left in Bun's bunx cache can be, it runs the same command through the newer version instead of writing an outdated app.
+  - @mercury-fw/core@0.28.4
+
 ## 0.28.3
 
 ### Patch Changes

package/README.md

@@ -60,6 +60,8 @@ bunx @mercury-fw/cli create my-agent --assistant-name Hermes --channels http --p
 
 The framework packages get the CLI's own version (they're released together); each chosen plugin or channel gets its latest version on the registry, `https://registry.npmjs.org` unless `MFW_REGISTRY` names another.
 
+Before anything else it asks the registry for the latest `@mercury-fw/cli`: a newer one than itself means it's a stale copy (Bun keeps the `create-mercury-agent` that `bun create` ran last in its cache, a release behind), so it says so and runs the same command through the newer version (`bunx @mercury-fw/cli@<newer> create …`), which writes the app instead. A registry that doesn't answer within a few seconds, or a newer version that can't be installed yet, is only a warning, and the CLI carries on with itself. Only CLIs from 0.28.4 on do this: a copy older than that, still in Bun's cache, needs one last `bun pm cache rm`, run from any folder with a `package.json` (Bun refuses it elsewhere).
+
 ### `mfw start [--no-cache]`
 
 Builds the app's image and starts the app and Qdrant in the background (`docker compose up -d --build`). Docker's cache means only what changed gets rebuilt, and a running container is recreated only if its image or configuration changed, so it's also the command to run after changing a dependency, the Dockerfile or `.env`. `--no-cache` rebuilds everything from scratch (`docker compose build --no-cache`, then `up -d`), which is what refetches a tool plugin's CLI binary when a new release is out: a normal build keeps the cached one.

package/dist/src/main.d.ts

@@ -1,9 +1,13 @@
 import { type AppDeps } from "./app/commands.ts";
+/** Runs `argv` with stdio inherited and `env` on top of this process's
+ * environment; returns its exit code. */
+export type Relaunch = (argv: string[], env: Record<string, string>) => Promise<number>;
 /** Runs `mfw` with `argv` (the arguments after the command name) and returns
  * the exit code, printing to stdout/stderr. `bin.ts` and `create-mercury-agent`
  * both call it; the app commands look for the app from `cwd` and run docker
- * through `deps`. */
-export declare function main(argv: string[], { cwd, deps }?: {
+ * through `deps`; `relaunch` is how `create` hands over to a newer CLI. */
+export declare function main(argv: string[], { cwd, deps, relaunch }?: {
     cwd?: string;
     deps?: AppDeps;
+    relaunch?: Relaunch;
 }): Promise<number>;

package/dist/src/versions.d.ts

@@ -14,3 +14,14 @@ export declare function appVersions(packages: string[], opts: {
     registry: string;
     fetchFn?: typeof fetch;
 }): Promise<Record<string, string>>;
+/** The registry's `latest` `@mercury-fw/cli` when it's newer than `current`
+ * (this CLI's version by default), nothing otherwise: a CLI run from Bun's
+ * bunx cache can be behind the release it was meant to be. Rejects like
+ * `appVersions` when the registry can't answer, within `timeoutMs` (5s by
+ * default: this check runs on every create, also one needing no network). */
+export declare function newerCli(opts: {
+    registry: string;
+    fetchFn?: typeof fetch;
+    current?: string;
+    timeoutMs?: number;
+}): Promise<string | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.28.3",
+  "version": "0.28.4",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -36,13 +36,13 @@
   "comment:shape": "The Mercury CLI (`mfw`). `mfw create <dir>` writes a new Mercury app from the template. The framework packages move in lockstep with it, so a new app gets them at the CLI's own version; plugins and channels at the registry's latest. The plugin and channel packages are devDependencies only for the catalog test. `main(argv)` is exported for create-mercury-agent.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@mercury-fw/core": "0.28.3",
+    "@mercury-fw/core": "0.28.4",
     "commander": "^15.0.0"
   },
   "devDependencies": {
     "@mercury-fw/channel-google-chat": "0.1.2",
     "@mercury-fw/channel-http": "0.1.0",
-    "@mercury-fw/formatter": "0.28.3",
+    "@mercury-fw/formatter": "0.28.4",
     "@mercury-fw/plugin-atlassian-admin": "0.1.0",
     "@mercury-fw/plugin-bitbucket": "0.1.0",
     "@mercury-fw/plugin-jira": "0.1.1",

package/src/main.ts

@@ -11,7 +11,7 @@ import { CATALOG } from "./catalog.ts";
 import { kebabCase } from "./naming.ts";
 import { runProgram } from "./program.ts";
 import { renderApp, selectionError } from "./render.ts";
-import { appVersions, registryFrom } from "./versions.ts";
+import { appVersions, cliVersion, newerCli, registryFrom } from "./versions.ts";
 import { appCommands, terminalDeps, type AppDeps } from "./app/commands.ts";
 import { findApp } from "./app/find-app.ts";
 import { askAnswers, DEFAULT_ASSISTANT_NAME, DEFAULT_ROLE, type Answers } from "./wizard.ts";
@@ -28,8 +28,55 @@ function answersFromFlags(args: CreateArgs, defaultName: string): Answers {
   };
 }
 
-/** `mfw create`: returns the exit code. */
-async function create(args: CreateArgs): Promise<number> {
+/** Runs `argv` with stdio inherited and `env` on top of this process's
+ * environment; returns its exit code. */
+export type Relaunch = (argv: string[], env: Record<string, string>) => Promise<number>;
+
+/** The real relaunch: a child process on the user's terminal. */
+const spawnRelaunch: Relaunch = async (argv, env) => {
+  const proc = Bun.spawn(argv, { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: { ...process.env, ...env } });
+  return await proc.exited;
+};
+
+/** When the registry has a newer `@mercury-fw/cli` than this one (a stale copy
+ * out of Bun's bunx cache), installs it (`bunx … --version`), then runs
+ * `create` again through it with the same arguments as typed and returns its
+ * exit code, whatever it is (a cancelled wizard included). `undefined` means
+ * carry on here: no newer CLI, a check skipped inside a relaunch
+ * (`MFW_SELF_UPDATED`), a registry that can't answer, or a newer CLI that
+ * can't be installed; the last two with a warning. */
+async function relaunchIfStale(rawArgs: string[], relaunch: Relaunch): Promise<number | undefined> {
+  if (process.env.MFW_SELF_UPDATED) return undefined;
+  const registry = registryFrom(process.env.MFW_REGISTRY).replace(/\/+$/, "");
+  let newer: string | undefined;
+  try {
+    newer = await newerCli({ registry });
+  } catch (err) {
+    console.error(`couldn't check for a newer mfw: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+  if (newer === undefined) return undefined;
+  const cli = `@mercury-fw/cli@${newer}`;
+  const env = { MFW_SELF_UPDATED: newer, NPM_CONFIG_REGISTRY: registry };
+  let installed: number;
+  try {
+    installed = await relaunch(["bunx", cli, "--version"], env);
+  } catch {
+    installed = -1;
+  }
+  if (installed !== 0) {
+    console.error(`mfw ${cliVersion()} is behind the registry's ${newer}, which couldn't be installed: creating with ${cliVersion()}.`);
+    return undefined;
+  }
+  console.error(`mfw ${cliVersion()} is behind the registry's ${newer}: running ${newer} instead.`);
+  return relaunch(["bunx", cli, "create", ...rawArgs], env);
+}
+
+/** `mfw create`: returns the exit code. `rawArgs` are the arguments after
+ * `create` as typed, for a relaunch. */
+async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch): Promise<number> {
+  const relaunched = await relaunchIfStale(rawArgs, relaunch);
+  if (relaunched !== undefined) return relaunched;
   // The folder is created in kebab case, only its own name: the parent path is
   // taken as typed. Its name is also the app name's default.
   const typed = resolve(args.dir);
@@ -66,13 +113,14 @@ Next:
 /** Runs `mfw` with `argv` (the arguments after the command name) and returns
  * the exit code, printing to stdout/stderr. `bin.ts` and `create-mercury-agent`
  * both call it; the app commands look for the app from `cwd` and run docker
- * through `deps`. */
+ * through `deps`; `relaunch` is how `create` hands over to a newer CLI. */
 export async function main(
   argv: string[],
-  { cwd = process.cwd(), deps }: { cwd?: string; deps?: AppDeps } = {},
+  { cwd = process.cwd(), deps, relaunch = spawnRelaunch }: { cwd?: string; deps?: AppDeps; relaunch?: Relaunch } = {},
 ): Promise<number> {
+  const rawCreateArgs = argv.slice(argv.indexOf("create") + 1);
   return runProgram(argv, {
-    create,
+    create: (args) => create(args, rawCreateArgs, relaunch),
     app: () => appCommands(findApp(cwd), deps ?? terminalDeps()),
   });
 }

package/src/versions.ts

@@ -23,6 +23,32 @@ export function cliVersion(): string {
   return pkg.version;
 }
 
+/** The registry's `latest` version of `name`. Rejects naming the package the
+ * registry doesn't have, or saying the registry can't be reached (also when
+ * it hasn't answered within `timeoutMs`, if given). */
+async function latestVersion(
+  name: string,
+  opts: { registry: string; fetchFn?: typeof fetch; timeoutMs?: number },
+): Promise<string> {
+  const registry = opts.registry.replace(/\/+$/, "");
+  const fetchFn = opts.fetchFn ?? fetch;
+  let res: Response;
+  try {
+    const signal = opts.timeoutMs === undefined ? undefined : AbortSignal.timeout(opts.timeoutMs);
+    res = await fetchFn(`${registry}/${name.replace("/", "%2F")}/latest`, { signal });
+  } catch {
+    throw new Error(`Can't reach ${registry} to look up ${name}`);
+  }
+  if (!res.ok) {
+    throw new Error(`${name} is not on ${registry}`);
+  }
+  const body = (await res.json().catch(() => undefined)) as { version?: unknown } | undefined;
+  if (typeof body?.version !== "string") {
+    throw new Error(`${registry} gave no version for ${name}`);
+  }
+  return body.version;
+}
+
 /** Maps the framework packages to the CLI's version and each of `packages`
  * (plugins and channels) to the registry's `latest`. Rejects naming the
  * package the registry doesn't have, or saying the registry can't be reached. */
@@ -30,29 +56,25 @@ export async function appVersions(
   packages: string[],
   opts: { registry: string; fetchFn?: typeof fetch },
 ): Promise<Record<string, string>> {
-  const registry = opts.registry.replace(/\/+$/, "");
-  const fetchFn = opts.fetchFn ?? fetch;
   const versions: Record<string, string> = Object.fromEntries(FRAMEWORK_PACKAGES.map((p) => [p, cliVersion()]));
-  const latest = await Promise.all(
-    packages.map(async (name) => {
-      let res: Response;
-      try {
-        res = await fetchFn(`${registry}/${name.replace("/", "%2F")}/latest`);
-      } catch {
-        throw new Error(`Can't reach ${registry} to look up ${name}`);
-      }
-      if (!res.ok) {
-        throw new Error(`${name} is not on ${registry}`);
-      }
-      const body = (await res.json().catch(() => undefined)) as { version?: unknown } | undefined;
-      if (typeof body?.version !== "string") {
-        throw new Error(`${registry} gave no version for ${name}`);
-      }
-      return [name, body.version] as const;
-    }),
-  );
+  const latest = await Promise.all(packages.map(async (name) => [name, await latestVersion(name, opts)] as const));
   for (const [name, version] of latest) {
     versions[name] = version;
   }
   return versions;
 }
+
+/** The registry's `latest` `@mercury-fw/cli` when it's newer than `current`
+ * (this CLI's version by default), nothing otherwise: a CLI run from Bun's
+ * bunx cache can be behind the release it was meant to be. Rejects like
+ * `appVersions` when the registry can't answer, within `timeoutMs` (5s by
+ * default: this check runs on every create, also one needing no network). */
+export async function newerCli(opts: {
+  registry: string;
+  fetchFn?: typeof fetch;
+  current?: string;
+  timeoutMs?: number;
+}): Promise<string | undefined> {
+  const latest = await latestVersion("@mercury-fw/cli", { ...opts, timeoutMs: opts.timeoutMs ?? 5000 });
+  return Bun.semver.order(latest, opts.current ?? cliVersion()) === 1 ? latest : undefined;
+}