@mercury-fw/cli 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @mercury-fw/cli
 
+## 0.36.0
+
+### Patch Changes
+
+- Updated dependencies [521db42]
+  - @mercury-fw/core@0.36.0
+  - @mercury-fw/utils@0.36.0
+
+## 0.35.0
+
+### Minor Changes
+
+- 8d3e5af: Authentication for the HTTP surface.
+
+  - An app declares an auth provider as `auth` in `mercury.config.ts`. The core builds it and hands channels `ctx.authenticate`. A provider that fails to load leaves the channel without it, so the surface stays closed.
+  - New contract in `@mercury-fw/channel-types`: `AuthPlugin`, `AUTH_API_VERSION` and `Authenticate`. `PrincipalProvider` gains `oidc` and `static`.
+  - New package `@mercury-fw/auth-oidc` verifies an OpenID Connect bearer token against the issuer's keys and checks `iss`, `aud` and expiry. It reads `OIDC_ISSUER` and `OIDC_AUDIENCE`.
+  - New package `@mercury-fw/auth-static` maps fixed test tokens from `AUTH_STATIC_TOKENS` to users, for test apps and e2e tests.
+  - Breaking, `@mercury-fw/channel-http`: the channel doesn't start without an auth provider.
+  - `@mercury-fw/channel-http`: every route except `GET /openapi.yaml` and the `OPTIONS` preflights needs `Authorization: Bearer <token>`, and a missing or refused token gets `401` before anything runs.
+  - Breaking, `@mercury-fw/channel-http`: a conversation belongs to whoever opened it. The session key is `<caller id>:<conversationId>`, so the same id from someone else is a conversation of their own. Existing HTTP conversations stay readable but can't be continued.
+  - `@mercury-fw/channel-http`: a confirmation token is checked against the caller's own session, so it can't be confirmed from someone else's.
+  - `@mercury-fw/channel-http`: authenticated callers get their own episodic memory and wiki area.
+  - `@mercury-fw/channel-http`: the read routes (`/conversations`, `/conversation`, `/wiki/*`, `/memory/scroll`, `/tool-log`, `/confirmations`) need an authenticated caller, but still show every person's data. Scoping them per person comes next, so don't give the surface to people who shouldn't see each other's conversations yet. Confirmation tokens are never listed.
+  - The HTTP `tool` event carries the name of the tool the model called. `TurnSink.onToolStart` gets it as an optional fourth argument.
+  - `mfw create` pairs the HTTP channel with an auth provider: `--auth oidc|static`, which the wizard asks for once HTTP is chosen.
+  - `mfw e2e` runs cases on the HTTP surface (`channel: "http"`) as one of the test's `users`, each a token the app accepts. A turn can name its own user, and it reports the response's status.
+  - `mfw create --local-packages <folder>` makes an app on packed tarballs, as `mfw local-packages` does on an existing one. Versions come from the tarballs, so a package that isn't published yet works too.
+
+### Patch Changes
+
+- Updated dependencies [8d3e5af]
+  - @mercury-fw/core@0.35.0
+  - @mercury-fw/utils@0.35.0
+
 ## 0.34.0
 
 ### Patch Changes

package/README.md

@@ -60,6 +60,8 @@ Then it runs `bun install` in the app and creates a git repository on `main` wit
 | `--role <text>` | Completes "You are <name>, …" (default `an internal assistant`). |
 | `--channels <ids>` | Comma-separated: `google-chat`, `http`. |
 | `--plugins <ids>` | Comma-separated: `jira`, `bitbucket`, `atlassian-admin`. |
+| `--auth <id>` | The HTTP channel's auth provider, `oidc` or `static`: required with `http`, refused without it, since the channel doesn't start without one. The wizard asks for it once `http` is chosen. |
+| `--local-packages <folder>` | Installs the packages packed in `<folder>` (`bun pm pack`) instead of the registry's, as [`mfw local-packages`](#mfw-local-packages-folder--mfw-local-packages---off) does on an existing app: their versions come from the tarballs, so a package that isn't published yet works too, and no newer `mfw` is looked up on the registry. For trying unreleased packages in a new app; the test bed makes its apps this way. |
 | `--git-remote <url>` | The repository's `origin`, taken as typed. |
 | `--no-install` | Don't run `bun install`. |
 | `--no-git` | Don't create the repository. |
@@ -67,10 +69,10 @@ Then it runs `bun install` in the app and creates a git repository on `main` wit
 
 ```bash
 mfw create my-agent
-mfw create my-agent --assistant-name Hermes --channels http --plugins jira --yes
+mfw create my-agent --assistant-name Hermes --channels http --auth oidc --plugins jira --yes
 ```
 
-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.
+The framework packages get the CLI's own version (they're released together); each chosen plugin, channel or auth provider 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).
 
@@ -229,7 +231,7 @@ mfw local-packages --off
 
 ### `mfw e2e [tests...] [--repeat N]`
 
-Runs end-to-end tests against the app's real model: each test case sends its turns to the app's REPL in the container, as `mfw repl` would, and checks what each turn did, the tool calls with their inputs and results, and the answer. It's how you find out whether the model actually uses a plugin the way its skill says, at the first try, with the app's own model, configuration, wiki and credentials. That's also why it doesn't belong in CI: the results depend on the model, on what's in the vault and in Qdrant, and on accounts a CI runner shouldn't have.
+Runs end-to-end tests against the app's real model: each test case sends its turns to the app's REPL in the container, as `mfw repl` would, or to its HTTP surface as one of the test's users, and checks what each turn did, the tool calls with their inputs and results, and the answer. It's how you find out whether the model actually uses a plugin the way its skill says, at the first try, with the app's own model, configuration, wiki and credentials. That's also why it doesn't belong in CI: the results depend on the model, on what's in the vault and in Qdrant, and on accounts a CI runner shouldn't have.
 
 Without arguments it runs every `e2e/*.e2e.ts` in the app; with files, those (they can live anywhere). It prints every check of every run, keeps everything (each turn's calls and answer, each check) in `e2e/results/<time>/`, which `.gitignore` leaves out, and exits 1 when a case didn't pass. The app must be built and its `.env` filled in, as for `mfw repl`. `--repeat N` runs each case N times, overriding its own `repeat`.
 
@@ -283,13 +285,44 @@ The call helpers look at every turn of the run, the answer helpers at the last o
 
 A turn can be a function of the one before, for a follow-up or a confirmation: `(previous) => …` returns the next message from `previous.calls` and `previous.answer` (an irreversible command comes back as a call whose output holds the pending confirmation's token, and sending the token as the next turn confirms it). Each turn is one line, as the REPL reads them.
 
+#### On the HTTP surface
+
+A case with `channel: "http"` sends its turns to the app's HTTP surface instead, as one of the test's `users`: each is a name and a token the app's auth provider accepts (with `static`, one of `AUTH_STATIC_TOKENS`). The app's service has to be running (`mfw start`); the surface's URL is the port compose publishes. A turn can name its own user, so one case can stage an action as Alice and try to confirm it as Bob in the same conversation id:
+
+```ts
+export default e2e({
+  users: { alice: "alice-test-token", bob: "bob-test-token", stranger: "not-a-token" },
+  cases: [
+    {
+      name: "no token, no turn",
+      channel: "http",
+      as: "stranger",
+      turns: ["hi"],
+      check: (run, expect) => expect.that("refused with 401", run.last.status === 401),
+    },
+    {
+      name: "Bob can't confirm what Alice staged",
+      channel: "http",
+      as: "alice",
+      turns: [
+        "Delete the issue SUP-1 on Jira",
+        { text: (previous) => (previous.calls.find((c) => c.pending)?.output as { token: string }).token, as: "bob" },
+      ],
+      check: (run, expect) => expect.answerNot("Confermato"),
+    },
+  ],
+});
+```
+
+Each run of an HTTP case is a conversation of its own. A turn also has the response's `status` (200, or 401 for a refused token). The event stream carries no tool results, so on HTTP a call's `input` is the line the surface shows for it (the command, for a CLI tool) and its `output` is there only for a call staged for confirmation, with the token, as on the REPL. A turn may span several lines.
+
 `before`, `after` and `check` also get `cli(command)`, which runs `sh -c command` in the app's container, outside the model, and resolves to its exit code and output: to prepare data (an issue to work on, a note in the wiki with the vault CLI), to check what a turn changed (`jira issue get KEY --select fields.assignee.displayName` after an assignment), to clean up. `after` runs even when the run or the check failed. A test that changes an external system has to clean up after itself, so start from read-only ones.
 
 #### What it can and can't test
 
 It can test how the model uses a plugin through its skill (the commands and flags it picks, rejected or failed calls, how many calls it takes), what the answer says or must not say, what a turn changed in an external system, the confirmation of an irreversible command, conversations over several turns, several plugins working together, and what the wiki and memory make of a conversation.
 
-It can't test how a channel shows a turn (Google Chat's cards, the HTTP channel's events: the REPL runs the same turn, without them), the background jobs (the nightly wiki review, idle-session capture), or the exact wording of an answer: checks look for properties, and `repeat` with `minPasses` says how steady the behaviour is. Durations are in the report and in `e2e/results/`, never a check.
+It can't test how Google Chat shows a turn (its cards), the background jobs (the nightly wiki review, idle-session capture), or the exact wording of an answer: checks look for properties, and `repeat` with `minPasses` says how steady the behaviour is. Durations are in the report and in `e2e/results/`, never a check.
 
 ```bash
 mfw e2e

package/dist/src/app/commands.d.ts

@@ -80,8 +80,9 @@ export declare function appCommands(app: App, deps: AppDeps): {
      * Everything is checked before anything is written. */
     localPackages: (from: string) => Promise<number>;
     /** Runs e2e tests (`tests`, or the app's `e2e/*.e2e.ts`) against the app's
-     * REPL in its container, keeping the turns and checks in
-     * `e2e/results/<time>/`; returns 1 when a case didn't pass. */
+     * REPL in its container, or against its running service's HTTP surface for
+     * a case on `http`, keeping the turns and checks in `e2e/results/<time>/`;
+     * returns 1 when a case didn't pass. */
     e2e: (tests: string[], { repeat }: {
         repeat?: number;
     }) => Promise<number>;

package/dist/src/app/local-packages.d.ts

@@ -1,5 +1,5 @@
 /**
- * What `mfw local-packages` writes: the app's `package.json` with `overrides`
+ * What `mfw local-packages` (and `mfw create --local-packages`) writes: the app's `package.json` with `overrides`
  * pointing packages at local tarballs (`bun pm pack`) copied into `.packs/`,
  * which the image copies before `bun install`. Overrides, and not the
  * dependencies themselves, because a packed package names its siblings by
@@ -20,7 +20,22 @@ export declare function withLocalOverrides(pkg: Manifest, packs: Array<{
 /** `pkg` without the overrides this command writes; without `overrides` at
  * all when none of the user's own is left. */
 export declare function withoutLocalOverrides(pkg: Manifest): Manifest;
-/** The package name in a `bun pm pack` tarball, read from its
+/** A local tarball: its file name in the folder, and the package it holds. */
+export type Pack = {
+    file: string;
+    name: string;
+    version: string;
+};
+/** The package name and version in a `bun pm pack` tarball, read from its
  * `package/package.json`. */
-export declare function packageNameOf(tarball: string): Promise<string>;
+export declare function packageOf(tarball: string): Promise<{
+    name: string;
+    version: string;
+}>;
+/** The tarballs in `from`, in file-name order, each with the package it
+ * holds, for an app in `appDir`. Throws when `from` doesn't exist, holds no
+ * tarball, or is the app's own `.packs/` (which the copy replaces). */
+export declare function readPacks(from: string, appDir: string): Promise<Pack[]>;
+/** Copies `packs` from `from` into the app's `.packs/`, in place of whatever was there. */
+export declare function copyPacks(from: string, appDir: string, packs: Pack[]): void;
 export {};

package/dist/src/args.d.ts

@@ -14,8 +14,12 @@ export type CreateArgs = {
     role?: string;
     channels?: string[];
     plugins?: string[];
+    /** The auth provider, which goes with the HTTP channel. */
+    auth?: string;
     /** The repository's origin, taken as typed. */
     gitRemote?: string;
+    /** A folder of packed tarballs the app installs instead of the registry's packages. */
+    localPackages?: string;
     yes: boolean;
     /** Run `bun install` after writing (`--no-install` turns it off). */
     install: boolean;
@@ -29,7 +33,9 @@ export type CreateOptions = {
     role?: string;
     channels?: string;
     plugins?: string;
+    auth?: string;
     gitRemote?: string;
+    localPackages?: string;
     yes?: boolean;
     install?: boolean;
     git?: boolean;

package/dist/src/catalog.d.ts

@@ -1,5 +1,5 @@
 /**
- * The channels and tool plugins `mfw create` can put in a new app. Written
+ * The channels, auth providers and tool plugins `mfw create` can put in a new app. Written
  * by hand for now: once the packages are published, each plugin will describe
  * itself (kind, export, env vars) and this list goes away. `catalog.test.ts`
  * checks every entry against the real package until then.
@@ -11,12 +11,13 @@ export type EnvVar = {
     comment: string;
     value?: string;
 };
-/** A channel or tool plugin the app can include. `id` is the plugin's own
- * `name` (what the logs and `dependsOn` call it), `exportName` the value the
- * app's config imports from `package`. */
+/** A channel, auth provider or tool plugin the app can include. `id` is the
+ * plugin's own `name` (what the logs and `dependsOn` call it), `exportName` the
+ * value the app's config imports from `package`. An auth provider goes with the
+ * HTTP channel, which doesn't start without one. */
 export type CatalogEntry = {
     id: string;
-    kind: "channel" | "tool";
+    kind: "channel" | "auth" | "tool";
     package: string;
     exportName: string;
     env: EnvVar[];

package/dist/src/e2e/define.d.ts

@@ -1,15 +1,22 @@
 /**
  * The shape of an e2e test, as a test file imports it
  * (`import { e2e } from "@mercury-fw/cli/e2e"`): the plugins and channels the
- * app must have, and cases of turns sent to the app's real model through its
- * REPL, each with checks on the calls it made and the answer it gave.
- * `mfw e2e` runs them (`runner.ts`).
+ * app must have, and cases of turns sent to the app's real model, each with
+ * checks on the calls it made and the answer it gave. A case talks to the
+ * app's REPL, or to its HTTP surface as one of the test's users (each a token
+ * the app's auth provider knows). `mfw e2e` runs them (`runner.ts`).
  */
 import type { Call, TurnData } from "./dump.ts";
 export type { Call } from "./dump.ts";
-/** One turn as a check sees it: its calls, its answer, how long it took. */
+/** One turn as a check sees it: its calls, its answer, how long it took, and
+ * on HTTP the response's status (200, or 401 for a token the app refused).
+ * On HTTP a call's `input` is the detail line the surface shows (the command,
+ * for a CLI tool) and its `output` is there only for a call staged for
+ * confirmation (`{ pendingConfirmation, token, summary }`): the stream carries
+ * no tool results. */
 export type Turn = TurnData & {
     seconds: number;
+    status?: number;
 };
 /** A case's run: every turn in order, and the last one. */
 export type Run = {
@@ -48,11 +55,24 @@ export type Expect = {
     /** Anything else. */
     that(label: string, condition: boolean): void;
 };
-/** One case: the turns sent, in one REPL session, and the checks on them. */
+/** A turn's text: a message, or a function of the turn before (a follow-up, a confirmation token). */
+export type TurnText = string | ((previous: Turn) => string);
+/** One case: the turns sent, in one session (one REPL, or one HTTP
+ * conversation), and the checks on them. */
 export type E2eCase = {
     name: string;
-    /** A message, or a function of the turn before (a follow-up, a confirmation token). */
-    turns: Array<string | ((previous: Turn) => string)>;
+    /** Where the turns go: the REPL (the default) or the HTTP surface, which
+     * must be running (`mfw start`). */
+    channel?: "repl" | "http";
+    /** On HTTP, the user (one of the test's `users`) the turns are sent as. */
+    as?: string;
+    /** The turns; on HTTP one can name its own user, so a case can stage an
+     * action as one person and try to confirm it as another, in the same
+     * conversation id. */
+    turns: Array<TurnText | {
+        text: TurnText;
+        as: string;
+    }>;
     /** How many times to run it (the model isn't deterministic); default 1. */
     repeat?: number;
     /** How many runs must pass; default every one. */
@@ -63,6 +83,9 @@ export type E2eCase = {
 };
 /** An e2e test: what the app must have, and its cases. */
 export type E2eTest = {
+    /** The users the HTTP cases send their turns as: a name and the token the
+     * app's auth provider accepts for it (a test token, like `static`'s). */
+    users?: Record<string, string>;
     /** Catalog ids of the tool plugins the app must have (`jira`, …). */
     plugins?: string[];
     /** Catalog ids of the channels the app must have (`http`, …). */

package/dist/src/e2e/http-session.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The HTTP session `mfw e2e` drives for a case on the HTTP surface: one
+ * conversation (a `conversationId` of its own), each turn a `POST /turn` with
+ * the user's token, read off the event stream into the calls and the answer
+ * a check looks at. The app's service must be running (`mfw start`); the
+ * surface's URL comes from `commands.ts`.
+ *
+ * The stream carries no tool results, so a call has its tool's name, the
+ * detail line the surface shows as input, and an output only when it was
+ * staged for confirmation (the `pending` event's token), shaped like the one
+ * a REPL dump has, so a confirmation turn reads the token the same way.
+ */
+import type { TurnData } from "./dump.ts";
+import type { HttpReply, Session } from "./runner.ts";
+export type HttpSessionOptions = {
+    /** The surface's base URL, e.g. `http://localhost:4100`. */
+    baseUrl: string;
+    /** How long one turn may take. */
+    timeoutMs: number;
+};
+/** The calls and the answer in the body of a `/turn` stream; throws on an
+ * `error` event, or when the stream has no `final` one. */
+export declare function turnFromSse(body: string): TurnData;
+/** Opens a session on the surface at `opts.baseUrl`: nothing is sent until the first turn. */
+export declare function openHttpSession(opts: HttpSessionOptions): Promise<Session<HttpReply>>;
+/** The surface's URL on this host, from `docker compose ps --format json`
+ * (one object per line, or an array on older compose; any line that isn't
+ * JSON, like a warning on stderr, skipped): the first TCP port `service`
+ * publishes, on localhost. Undefined when it isn't running or publishes nothing. */
+export declare function surfaceUrlFromPs(output: string, service: string): string | undefined;

package/dist/src/e2e/runner.d.ts

@@ -1,16 +1,26 @@
 import type { Context, E2eTest, Turn } from "./define.ts";
+import { type TurnData } from "./dump.ts";
 import { type Check } from "./expect.ts";
-/** A REPL session in the app: `turn` sends one line and resolves with what
- * `/dump` wrote for it and what the REPL printed meanwhile. */
-export type Session = {
-    turn: (line: string) => Promise<{
-        dump: unknown;
-        output: string;
-    }>;
+/** What a REPL turn gives back: what `/dump` wrote for it and what the REPL printed meanwhile. */
+export type ReplReply = {
+    dump: unknown;
+    output: string;
+};
+/** What an HTTP turn gives back: the turn read off its stream, and the response's status. */
+export type HttpReply = {
+    turn: TurnData;
+    status: number;
+};
+/** A session in the app: `turn` sends one turn (on HTTP with the user's
+ * token) and resolves with what came back. */
+export type Session<Reply extends ReplReply | HttpReply = ReplReply | HttpReply> = {
+    turn: (line: string, token?: string) => Promise<Reply>;
     close: () => Promise<void>;
 };
+/** Where a case's turns go. */
+export type Channel = "repl" | "http";
 export type RunnerDeps = {
-    openSession: () => Promise<Session>;
+    openSession: (channel: Channel) => Promise<Session>;
     cli: Context["cli"];
     /** The app's dependencies, to check the test's plugins and channels against. */
     appPackages: Record<string, string>;

package/dist/src/e2e/session.d.ts

@@ -1,4 +1,4 @@
-import type { Session } from "./runner.ts";
+import type { ReplReply, Session } from "./runner.ts";
 export type ReplSessionOptions = {
     /** The command that starts the REPL. */
     argv: string[];
@@ -14,4 +14,4 @@ export type ReplSessionOptions = {
 /** Starts the REPL and returns the session over it once the REPL is ready
  * (its first prompt is out), so a turn's time is only the turn's; throws
  * when the REPL exits or doesn't get there in time. */
-export declare function openReplSession(opts: ReplSessionOptions): Promise<Session>;
+export declare function openReplSession(opts: ReplSessionOptions): Promise<Session<ReplReply>>;

package/dist/src/render.d.ts

@@ -6,6 +6,8 @@ export type RenderInput = {
     role: string;
     channels: string[];
     plugins: string[];
+    /** The HTTP channel's auth provider: required with it, refused without it. */
+    auth?: string;
     versions: Record<string, string>;
 };
 /** Builds every file of the new app. Throws on an invalid app name, an empty
@@ -15,7 +17,12 @@ export declare function renderApp(input: RenderInput): Map<string, string>;
 /** Why `name` can't be an app name, or undefined when it can. Shared with the
  * wizard, which checks the name as it's typed. */
 export declare function appNameError(name: string): string | undefined;
-/** Names the first channel or plugin id the catalog doesn't have, with the
- * valid ones, or undefined when all are known. Shared with the command, which
- * checks the flags before asking anything. */
-export declare function selectionError(channels: string[], plugins: string[]): string | undefined;
+/** Names the first channel, plugin or auth provider id the catalog doesn't
+ * have, with the valid ones, or undefined when all are known. Shared with the
+ * command, which checks the flags before asking anything. */
+export declare function selectionError(channels: string[], plugins: string[], auth?: string): string | undefined;
+/** What's wrong with pairing the HTTP channel and the auth provider: it
+ * doesn't start without one, and one without it has nothing to authenticate.
+ * Undefined when they go together. Shared with the command, which checks it
+ * before writing when nothing will ask (`--yes`). */
+export declare function pairingError(channels: string[], auth?: string): string | undefined;

package/dist/src/versions.d.ts

@@ -8,11 +8,15 @@ export declare function registryFrom(value: string | undefined): string;
 /** This CLI's version, which is the framework's. */
 export declare function cliVersion(): string;
 /** 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. */
+ * (plugins, channels, auth providers) to the registry's `latest`. A package
+ * in `local` (packed tarballs, `--local-packages`) takes that version instead,
+ * a framework one included, and the registry isn't asked for it. Rejects
+ * naming the package the registry doesn't have, or saying the registry can't
+ * be reached. */
 export declare function appVersions(packages: string[], opts: {
     registry: string;
     fetchFn?: typeof fetch;
+    local?: Record<string, string>;
 }): 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

package/dist/src/wizard.d.ts

@@ -7,6 +7,8 @@ export type Answers = {
     role: string;
     channels: string[];
     plugins: string[];
+    /** The HTTP channel's auth provider, there exactly when that channel is. */
+    auth?: string;
     gitRemote?: string;
 };
 export declare const DEFAULT_ASSISTANT_NAME = "Mercury";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,14 +41,16 @@
   "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.34.0",
-    "@mercury-fw/utils": "0.34.0",
+    "@mercury-fw/core": "0.36.0",
+    "@mercury-fw/utils": "0.36.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-google-chat": "0.2.0",
-    "@mercury-fw/channel-http": "0.2.0",
-    "@mercury-fw/formatter": "0.34.0",
+    "@mercury-fw/channel-google-chat": "0.3.0",
+    "@mercury-fw/channel-http": "0.4.0",
+    "@mercury-fw/auth-oidc": "0.1.0",
+    "@mercury-fw/auth-static": "0.1.0",
+    "@mercury-fw/formatter": "0.36.0",
     "@mercury-fw/plugin-atlassian-admin": "0.1.2",
     "@mercury-fw/plugin-bitbucket": "0.1.2",
     "@mercury-fw/plugin-jira": "0.4.3",

package/src/app/commands.ts

@@ -5,16 +5,17 @@
  * and validated before any of this runs (`program.ts`); what runs a command is
  * injected (`AppDeps`), which is how the tests see the exact calls.
  */
-import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, relative, resolve } from "node:path";
 import { appCliCredentials, volumePath, type CliCredentials } from "@mercury-fw/utils";
 import { packCredentials, readServiceAccountKey, setEnvVar } from "./credentials.ts";
 import type { App } from "./find-app.ts";
-import { LOCAL_PACKS_DIR, packageNameOf, withLocalOverrides, withoutLocalOverrides } from "./local-packages.ts";
+import { copyPacks, LOCAL_PACKS_DIR, readPacks, withLocalOverrides, withoutLocalOverrides } from "./local-packages.ts";
 import { findTests, loadTest } from "../e2e/load.ts";
 import { runE2e } from "../e2e/runner.ts";
 import { openReplSession } from "../e2e/session.ts";
+import { openHttpSession, surfaceUrlFromPs } from "../e2e/http-session.ts";
 
 export type AppDeps = {
   /** Runs `argv` in `cwd` on the user's terminal (stdin, stdout, stderr) and returns its exit code. */
@@ -193,24 +194,17 @@ export function appCommands(app: App, deps: AppDeps) {
      * image copies too), overridden in the manifest, then installed.
      * Everything is checked before anything is written. */
     localPackages: async (from: string) => {
-      const source = resolve(from);
-      const target = join(app.dir, LOCAL_PACKS_DIR);
-      if (source === target) throw new Error(`${source} is the app's own .packs/: give the folder the tarballs were packed into.`);
-      if (!existsSync(source)) throw new Error(`${source} doesn't exist.`);
-      const files = readdirSync(source).filter((f) => f.endsWith(".tgz")).sort();
-      if (files.length === 0) throw new Error(`No .tgz in ${source}: pack the packages there first (bun pm pack).`);
-      const packs = await Promise.all(files.map(async (file) => ({ name: await packageNameOf(join(source, file)), file })));
+      const packs = await readPacks(from, app.dir);
       const manifest = withLocalOverrides(readManifest(), packs);
-      rmSync(target, { recursive: true, force: true });
-      mkdirSync(target);
-      for (const { file } of packs) cpSync(join(source, file), join(target, file));
+      copyPacks(from, app.dir, packs);
       writeManifest(manifest);
-      deps.print(`${packs.length} local packages in ${target}: ${packs.map((p) => p.name).join(", ")}.`);
+      deps.print(`${packs.length} local packages in ${join(app.dir, LOCAL_PACKS_DIR)}: ${packs.map((p) => p.name).join(", ")}.`);
       return deps.run(["bun", "install"], { cwd: app.dir });
     },
     /** Runs e2e tests (`tests`, or the app's `e2e/*.e2e.ts`) against the app's
-     * REPL in its container, keeping the turns and checks in
-     * `e2e/results/<time>/`; returns 1 when a case didn't pass. */
+     * REPL in its container, or against its running service's HTTP surface for
+     * a case on `http`, keeping the turns and checks in `e2e/results/<time>/`;
+     * returns 1 when a case didn't pass. */
     e2e: async (tests: string[], { repeat }: { repeat?: number }) => {
       const files = findTests(tests, { appDir: app.dir, cwd: process.cwd() });
       const loaded = await Promise.all(files.map(async (file) => ({ file: relative(process.cwd(), file) || file, test: await loadTest(file) })));
@@ -221,15 +215,23 @@ export function appCommands(app: App, deps: AppDeps) {
       chmodSync(results, 0o777);
       let sessions = 0;
       return runE2e(loaded, repeat === undefined ? {} : { repeat }, {
-        openSession: async () =>
-          openReplSession({
+        openSession: async (channel) => {
+          if (channel === "http") {
+            // Where the running service publishes the surface, as compose reports it.
+            const ps = await captureCode([...COMPOSE, "ps", "--format", "json", SERVICE], app.dir);
+            const baseUrl = ps.code === 0 ? surfaceUrlFromPs(ps.output, SERVICE) : undefined;
+            if (baseUrl === undefined) throw new Error("the app's service isn't running or publishes no HTTP port: mfw start");
+            return openHttpSession({ baseUrl, timeoutMs: E2E_TURN_TIMEOUT_MS });
+          }
+          return openReplSession({
             argv: [...COMPOSE, "run", "--rm", "-T", "-v", `${results}:/e2e`, SERVICE, "bun", "run", "repl"],
             cwd: app.dir,
             hostDir: results,
             replDir: "/e2e",
             name: `run-${++sessions}`,
             timeoutMs: E2E_TURN_TIMEOUT_MS,
-          }),
+          });
+        },
         cli: (command) => captureCode([...COMPOSE, "run", "--rm", "-T", "--no-deps", SERVICE, "sh", "-c", command], app.dir),
         appPackages: (readManifest() as { dependencies?: Record<string, string> }).dependencies ?? {},
         print: deps.print,

package/src/app/local-packages.ts

@@ -1,5 +1,5 @@
 /**
- * What `mfw local-packages` writes: the app's `package.json` with `overrides`
+ * What `mfw local-packages` (and `mfw create --local-packages`) writes: the app's `package.json` with `overrides`
  * pointing packages at local tarballs (`bun pm pack`) copied into `.packs/`,
  * which the image copies before `bun install`. Overrides, and not the
  * dependencies themselves, because a packed package names its siblings by
@@ -7,6 +7,9 @@
  * transitive dependencies to the tarballs as well.
  */
 
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+
 /** The tarballs' folder inside the app, as the Dockerfile copies it. */
 export const LOCAL_PACKS_DIR = ".packs";
 
@@ -35,17 +38,43 @@ export function withoutLocalOverrides(pkg: Manifest): Manifest {
   return Object.keys(own).length > 0 ? { ...rest, overrides: own } : rest;
 }
 
-/** The package name in a `bun pm pack` tarball, read from its
+/** A local tarball: its file name in the folder, and the package it holds. */
+export type Pack = { file: string; name: string; version: string };
+
+/** The package name and version in a `bun pm pack` tarball, read from its
  * `package/package.json`. */
-export async function packageNameOf(tarball: string): Promise<string> {
+export async function packageOf(tarball: string): Promise<{ name: string; version: string }> {
   const proc = Bun.spawn(["tar", "-xOzf", tarball, "package/package.json"], { stdout: "pipe", stderr: "pipe" });
   const [manifest, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
   try {
     if (code !== 0) throw new Error(`tar exited with ${code}`);
-    const name = (JSON.parse(manifest) as { name?: unknown }).name;
+    const { name, version } = JSON.parse(manifest) as { name?: unknown; version?: unknown };
     if (typeof name !== "string") throw new Error("no name in its package.json");
-    return name;
+    if (typeof version !== "string") throw new Error("no version in its package.json");
+    return { name, version };
   } catch (err) {
     throw new Error(`${tarball} isn't a package tarball: ${err instanceof Error ? err.message : String(err)}`);
   }
 }
+
+/** The tarballs in `from`, in file-name order, each with the package it
+ * holds, for an app in `appDir`. Throws when `from` doesn't exist, holds no
+ * tarball, or is the app's own `.packs/` (which the copy replaces). */
+export async function readPacks(from: string, appDir: string): Promise<Pack[]> {
+  const source = resolve(from);
+  if (source === join(resolve(appDir), LOCAL_PACKS_DIR)) {
+    throw new Error(`${source} is the app's own .packs/: give the folder the tarballs were packed into.`);
+  }
+  if (!existsSync(source)) throw new Error(`${source} doesn't exist.`);
+  const files = readdirSync(source).filter((f) => f.endsWith(".tgz")).sort();
+  if (files.length === 0) throw new Error(`No .tgz in ${source}: pack the packages there first (bun pm pack).`);
+  return Promise.all(files.map(async (file) => ({ file, ...(await packageOf(join(source, file))) })));
+}
+
+/** Copies `packs` from `from` into the app's `.packs/`, in place of whatever was there. */
+export function copyPacks(from: string, appDir: string, packs: Pack[]): void {
+  const target = join(appDir, LOCAL_PACKS_DIR);
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(target);
+  for (const { file } of packs) cpSync(join(resolve(from), file), join(target, file));
+}

package/src/args.ts

@@ -15,8 +15,12 @@ export type CreateArgs = {
   role?: string;
   channels?: string[];
   plugins?: string[];
+  /** The auth provider, which goes with the HTTP channel. */
+  auth?: string;
   /** The repository's origin, taken as typed. */
   gitRemote?: string;
+  /** A folder of packed tarballs the app installs instead of the registry's packages. */
+  localPackages?: string;
   yes: boolean;
   /** Run `bun install` after writing (`--no-install` turns it off). */
   install: boolean;
@@ -31,7 +35,9 @@ export type CreateOptions = {
   role?: string;
   channels?: string;
   plugins?: string;
+  auth?: string;
   gitRemote?: string;
+  localPackages?: string;
   yes?: boolean;
   install?: boolean;
   git?: boolean;
@@ -52,6 +58,8 @@ export function toCreateArgs(folder: string, opts: CreateOptions): CreateArgs {
   if (opts.role !== undefined) args.role = opts.role;
   if (opts.channels !== undefined) args.channels = list(opts.channels);
   if (opts.plugins !== undefined) args.plugins = list(opts.plugins);
+  if (opts.auth !== undefined && opts.auth.trim() !== "") args.auth = opts.auth.trim();
+  if (opts.localPackages !== undefined) args.localPackages = opts.localPackages;
   // Blank is none, as in the wizard.
   if (opts.gitRemote !== undefined && opts.gitRemote.trim() !== "") args.gitRemote = opts.gitRemote.trim();
   return args;