@mercury-fw/cli 0.28.2 → 0.28.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @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
+
+- 5175e10: An app created with the HTTP channel publishes the surface's port on the host (`HTTP_SURFACE_PORT`, 4100 when unset), so it's reachable from outside the container; its README says where it listens and that it has no authentication.
+  - @mercury-fw/core@0.28.3
+
 ## 0.28.2
 
 ### 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.2",
+  "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.2",
+    "@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.2",
+    "@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/render.ts

@@ -70,7 +70,7 @@ export function renderApp(input: RenderInput): Map<string, string> {
     [".gitignore", gitignore],
     ["Dockerfile", renderDockerfile(tools)],
     ["README.md", renderReadme(input.name, channels, tools)],
-    ["docker-compose.yml", renderCompose(input.name, tools.length > 0)],
+    ["docker-compose.yml", renderCompose(input.name, tools.length > 0, channels.some((c) => c.id === "http"))],
     ["markdown.d.ts", markdownDts],
     ["mercury.config.ts", renderConfig(channels, tools)],
     ["package.json", renderPackageJson(input.name, channels, tools, input.versions)],
@@ -318,8 +318,9 @@ function renderEnv(channels: CatalogEntry[], tools: CatalogEntry[]): string {
 }
 
 /** `docker-compose.yml`: the app and Qdrant, with named volumes prefixed by the
- * app's name; the CLI credentials volume only when a tool plugin was chosen. */
-function renderCompose(name: string, hasTools: boolean): string {
+ * app's name; the CLI credentials volume only when a tool plugin was chosen,
+ * the HTTP surface's port published on the host only with the HTTP channel. */
+function renderCompose(name: string, hasTools: boolean, hasHttp: boolean): string {
   const credentialsMount = hasTools
     ? [
         "      # The tool plugins' CLI credentials, on a volume so what a CLI writes back",
@@ -327,6 +328,13 @@ function renderCompose(name: string, hasTools: boolean): string {
         "      - cli-credentials:/home/mercury/.config",
       ]
     : [];
+  const httpPort = hasHttp
+    ? [
+        "    # The HTTP surface, on the host: no authentication, keep it off the public network.",
+        "    ports:",
+        '      - "${HTTP_SURFACE_PORT:-4100}:${HTTP_SURFACE_PORT:-4100}"',
+      ]
+    : [];
   const credentialsVolume = hasTools ? ["  cli-credentials:", `    name: ${name}_cli-credentials`] : [];
   return [
     "services:",
@@ -340,6 +348,7 @@ function renderCompose(name: string, hasTools: boolean): string {
     "    volumes:",
     "      - wiki-vault:/app/wiki-vault",
     ...credentialsMount,
+    ...httpPort,
     "    extra_hosts:",
     '      - "host.docker.internal:host-gateway"',
     "    depends_on:",
@@ -387,7 +396,18 @@ bunx mfw repl
 \`\`\`
 
 \`bun install\` here gives your editor, \`bun run typecheck\` and \`mfw\` the packages (tool plugins download their CLI binary as they install); the image installs its own copy when it builds. \`bunx mfw start\` builds the image and starts the app with Qdrant in the background, \`bunx mfw repl\` opens a terminal conversation with the assistant. \`bunx mfw --help\` lists the rest: stopping and restarting, logs, a shell in the container, the wiki and the memory, and resetting them.
-${renderCredentialsSection(withCredentials(tools))}`;
+${renderHttpSection(channels)}${renderCredentialsSection(withCredentials(tools))}`;
+}
+
+/** The README section on the HTTP surface, for an app with the HTTP channel;
+ * nothing without it. */
+function renderHttpSection(channels: CatalogEntry[]): string {
+  if (!channels.some((c) => c.id === "http")) return "";
+  return `
+## HTTP surface
+
+The HTTP channel listens on \`http://<host>:4100\`, the port in \`HTTP_SURFACE_PORT\` (the compose file publishes whatever port it holds on the host). It has no authentication: whoever reaches the port can talk to the assistant, so keep it on a network you trust.
+`;
 }
 
 /** The README section on CLI credentials, for an app with tool plugins;

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