@mercury-fw/cli 0.34.0 → 0.35.0

package/src/catalog.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.
@@ -9,12 +9,13 @@
  * example: `value` is the example value, empty when the deployer must fill it. */
 export type EnvVar = { name: string; 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[];
@@ -55,10 +56,32 @@ export const CATALOG: CatalogEntry[] = [
     package: "@mercury-fw/channel-http",
     exportName: "httpChannel",
     env: [
-      { name: "HTTP_SURFACE_PORT", comment: "Port of the HTTP surface (no authentication: keep it off the public network)", value: "4100" },
+      { name: "HTTP_SURFACE_PORT", comment: "Port of the HTTP surface", value: "4100" },
       { name: "HTTP_SURFACE_CORS_ORIGIN", comment: "Origin allowed to call the HTTP surface from a browser, if any" },
     ],
   },
+  {
+    id: "oidc",
+    kind: "auth",
+    package: "@mercury-fw/auth-oidc",
+    exportName: "oidcAuth",
+    env: [
+      { name: "OIDC_ISSUER", comment: "Required: the OpenID Connect issuer's URL, as tokens carry it in iss (https://<instance>.zitadel.cloud)" },
+      { name: "OIDC_AUDIENCE", comment: "Required: the client id the UI calling the HTTP surface is registered with on the issuer (tokens carry it in aud)" },
+    ],
+  },
+  {
+    id: "static",
+    kind: "auth",
+    package: "@mercury-fw/auth-static",
+    exportName: "staticAuth",
+    env: [
+      {
+        name: "AUTH_STATIC_TOKENS",
+        comment: 'Required: JSON from bearer token to user, test tokens only: {"<token>": {"id": "alice", "displayName": "Alice"}}',
+      },
+    ],
+  },
   {
     id: "jira",
     kind: "tool",

package/src/e2e/define.ts

@@ -1,16 +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. */
-export type Turn = TurnData & { seconds: number };
+/** 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 = { turns: Turn[]; last: Turn };
@@ -42,11 +48,22 @@ export type Expect = {
   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. */
@@ -58,6 +75,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/src/e2e/http-session.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 { Call, 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;
+};
+
+/** Every `event:`/`data:` pair in an SSE body, in order. */
+function events(body: string): Array<{ name: string; data: Record<string, unknown> }> {
+  return body
+    .split("\n\n")
+    .map((block) => {
+      const name = /^event: (.*)$/m.exec(block)?.[1];
+      const data = /^data: (.*)$/m.exec(block)?.[1];
+      return name === undefined || data === undefined ? undefined : { name, data: JSON.parse(data) as Record<string, unknown> };
+    })
+    .filter((e) => e !== undefined);
+}
+
+/** 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 function turnFromSse(body: string): TurnData {
+  const calls: Array<Call & { id: unknown }> = [];
+  // A pending event's output, waiting for its call's tool_finish when it came first.
+  const unclaimed: unknown[] = [];
+  let answer: string | undefined;
+  for (const { name, data } of events(body)) {
+    if (name === "tool" && typeof data.name === "string") {
+      // A tool event with no name is Mercury saving to memory, not a call.
+      calls.push({ id: data.toolCallId, tool: data.name, input: data.detail, output: undefined, ok: false, pending: false });
+    } else if (name === "tool_finish") {
+      const call = calls.find((c) => c.id === data.toolCallId);
+      if (call === undefined) continue;
+      call.pending = data.outcome === "pending";
+      call.ok = data.outcome === "success" || call.pending;
+      if (call.pending && unclaimed.length > 0) call.output = unclaimed.shift();
+    } else if (name === "pending") {
+      const output = { pendingConfirmation: true, token: data.token, summary: data.command };
+      const call = calls.findLast((c) => c.pending && c.output === undefined);
+      if (call !== undefined) call.output = output;
+      else unclaimed.push(output);
+    } else if (name === "final") {
+      answer = String(data.text ?? "");
+    } else if (name === "error") {
+      throw new Error(`the turn failed in the app: ${String(data.message)}`);
+    }
+  }
+  if (answer === undefined) throw new Error("the stream ended without a final event");
+  return { calls: calls.map(({ id: _, ...call }) => call), answer };
+}
+
+/** Opens a session on the surface at `opts.baseUrl`: nothing is sent until the first turn. */
+export async function openHttpSession(opts: HttpSessionOptions): Promise<Session<HttpReply>> {
+  const conversationId = `e2e-${crypto.randomUUID()}`;
+  const url = `${opts.baseUrl.replace(/\/+$/, "")}/turn`;
+  return {
+    turn: async (text, token) => {
+      const signal = AbortSignal.timeout(opts.timeoutMs);
+      let res: Response;
+      let body: string;
+      try {
+        res = await fetch(url, {
+          method: "POST",
+          headers: { "content-type": "application/json", ...(token !== undefined ? { authorization: `Bearer ${token}` } : {}) },
+          body: JSON.stringify({ text, conversationId }),
+          signal,
+        });
+        body = await res.text();
+      } catch (err) {
+        if (signal.aborted) throw new Error(`no reply within ${opts.timeoutMs / 1000} s`);
+        throw new Error(`can't reach the HTTP surface at ${opts.baseUrl}: is the app running (mfw start)? (${err instanceof Error ? err.message : String(err)})`);
+      }
+      if (res.status !== 200) {
+        let error = body;
+        try {
+          error = String((JSON.parse(body) as { error?: unknown }).error ?? body);
+        } catch {
+          /* not JSON: the body as it is */
+        }
+        return { turn: { calls: [], answer: error }, status: res.status };
+      }
+      return { turn: turnFromSse(body), status: res.status };
+    },
+    close: async () => {},
+  };
+}
+
+/** 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 function surfaceUrlFromPs(output: string, service: string): string | undefined {
+  type Row = { Service?: unknown; Publishers?: Array<{ PublishedPort?: unknown; Protocol?: unknown }> };
+  const rows = output.split("\n").flatMap((line): Row[] => {
+    try {
+      const parsed = JSON.parse(line) as Row | Row[];
+      return Array.isArray(parsed) ? parsed : [parsed];
+    } catch {
+      return [];
+    }
+  });
+  const port = rows
+    .filter((r) => r.Service === service)
+    .flatMap((r) => r.Publishers ?? [])
+    .find((p) => typeof p.PublishedPort === "number" && p.PublishedPort > 0 && (p.Protocol ?? "tcp") === "tcp")?.PublishedPort;
+  return port === undefined ? undefined : `http://localhost:${port}`;
+}

package/src/e2e/runner.ts

@@ -1,25 +1,34 @@
 /**
  * Runs e2e tests against an app: for each case (as many times as it
- * repeats), a fresh REPL session gets the case's turns, the checks run on
- * what each turn did, and every check is printed; the exit code says whether
- * every case passed enough runs. The session, the container commands and the
- * report's destination are injected (`session.ts` and `commands.ts` hold the
- * real ones), so the tests drive the runner with scripted turns.
+ * repeats), a fresh session (the REPL, or one conversation on the HTTP
+ * surface) gets the case's turns, the checks run on what each turn did, and
+ * every check is printed; the exit code says whether every case passed enough
+ * runs. The sessions, the container commands and the report's destination are
+ * injected (`session.ts`, `http-session.ts` and `commands.ts` hold the real
+ * ones), so the tests drive the runner with scripted turns.
  */
 import { CATALOG } from "../catalog.ts";
 import type { Context, E2eCase, E2eTest, Run, Turn } from "./define.ts";
-import { turnFromDump } from "./dump.ts";
+import { turnFromDump, type TurnData } from "./dump.ts";
 import { createExpect, 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>;
@@ -43,9 +52,11 @@ function answerFromOutput(output: string): string {
 
 /** The test's plugins and channels the app doesn't depend on, as a message, or undefined. */
 function missing(test: E2eTest, packages: Record<string, string>): string | undefined {
+  // A case on the HTTP surface needs the channel, listed or not.
+  const channels = new Set([...(test.channels ?? []), ...(test.cases.some((c) => c.channel === "http") ? ["http"] : [])]);
   const wanted = [
     ...(test.plugins ?? []).map((id) => ({ id, kind: "tool" as const, word: "plugin" })),
-    ...(test.channels ?? []).map((id) => ({ id, kind: "channel" as const, word: "channel" })),
+    ...[...channels].map((id) => ({ id, kind: "channel" as const, word: "channel" })),
   ];
   const lacking = wanted.flatMap(({ id, kind, word }) => {
     const pkg = CATALOG.find((e) => e.kind === kind && e.id === id)?.package;
@@ -74,7 +85,7 @@ export async function runE2e(
       continue;
     }
     for (const c of test.cases) {
-      const result = await runCase(c, opts.repeat, deps);
+      const result = await runCase(c, test.users ?? {}, opts.repeat, deps);
       report.push({ file, case: c.name, ...result });
       if (!result.passed) code = 1;
     }
@@ -84,14 +95,19 @@ export async function runE2e(
 }
 
 /** Runs one case as many times as it repeats, printing each run's checks and the verdict. */
-async function runCase(c: E2eCase, repeatOverride: number | undefined, deps: RunnerDeps): Promise<{ passed: boolean; runs: RunReport[] }> {
+async function runCase(
+  c: E2eCase,
+  users: Record<string, string>,
+  repeatOverride: number | undefined,
+  deps: RunnerDeps,
+): Promise<{ passed: boolean; runs: RunReport[] }> {
   const repeat = repeatOverride ?? c.repeat ?? 1;
   const minPasses = Math.min(c.minPasses ?? repeat, repeat);
   deps.print(`  ${c.name}`);
   const runs: RunReport[] = [];
   for (let i = 1; i <= repeat; i++) {
     if (repeat > 1) deps.print(`    run ${i}/${repeat}`);
-    const run = await runOnce(c, deps);
+    const run = await runOnce(c, users, deps);
     const indent = repeat > 1 ? "      " : "    ";
     for (const check of run.checks) {
       deps.print(`${indent}${check.ok ? "✓" : "✗"} ${check.label}${check.ok || check.detail === undefined ? "" : `: ${check.detail}`}`);
@@ -108,23 +124,47 @@ async function runCase(c: E2eCase, repeatOverride: number | undefined, deps: Run
   return { passed, runs };
 }
 
+/** The token a turn is sent with: none on the REPL, its user's (the turn's
+ * own, or the case's) on HTTP; throws when that doesn't add up. */
+function tokenFor(channel: Channel, user: string | undefined, users: Record<string, string>): string | undefined {
+  if (channel === "repl") {
+    if (user !== undefined) throw new Error('"as" goes with channel "http"');
+    return undefined;
+  }
+  if (user === undefined) throw new Error('an HTTP turn needs a user: "as" on the case or on the turn');
+  const token = users[user];
+  if (token === undefined) throw new Error(`unknown user "${user}" (the test's users: ${Object.keys(users).join(", ") || "none"})`);
+  return token;
+}
+
 /** One run of a case in a fresh session: `before`, the turns, the checks, `after`. */
-async function runOnce(c: E2eCase, deps: RunnerDeps): Promise<RunReport> {
+async function runOnce(c: E2eCase, users: Record<string, string>, deps: RunnerDeps): Promise<RunReport> {
+  const channel: Channel = c.channel ?? "repl";
   const ctx: Context = { cli: deps.cli };
   const turns: Turn[] = [];
   let checks: Check[] = [];
   try {
     await c.before?.(ctx);
-    const session = await deps.openSession();
+    // Every turn's user is settled before the session opens, so a case that
+    // doesn't add up costs nothing.
+    const planned = c.turns.map((next) => {
+      const { text, as } = typeof next === "object" ? next : { text: next, as: undefined };
+      return { text, token: tokenFor(channel, as ?? c.as, users) };
+    });
+    const session = await deps.openSession(channel);
     try {
-      for (const next of c.turns) {
-        const line = typeof next === "string" ? next : next(turns.at(-1)!);
-        if (line.includes("\n")) throw new Error("a turn must be one line (the REPL reads one line per turn)");
+      for (const { text, token } of planned) {
+        const line = typeof text === "string" ? text : text(turns.at(-1)!);
+        if (channel === "repl" && line.includes("\n")) throw new Error("a turn must be one line (the REPL reads one line per turn)");
         const start = deps.now();
-        const { dump, output } = await session.turn(line);
+        const reply = await session.turn(line, token);
         const seconds = (deps.now() - start) / 1000;
-        const data = turnFromDump(dump);
-        const answer = data.calls.length === 0 && data.answer === "" ? answerFromOutput(output) : data.answer;
+        if ("status" in reply) {
+          turns.push({ ...reply.turn, seconds, status: reply.status });
+          continue;
+        }
+        const data = turnFromDump(reply.dump);
+        const answer = data.calls.length === 0 && data.answer === "" ? answerFromOutput(reply.output) : data.answer;
         turns.push({ calls: data.calls, answer, seconds });
       }
     } finally {

package/src/e2e/session.ts

@@ -9,7 +9,7 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import type { Session } from "./runner.ts";
+import type { ReplReply, Session } from "./runner.ts";
 
 export type ReplSessionOptions = {
   /** The command that starts the REPL. */
@@ -27,7 +27,7 @@ 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 async function openReplSession(opts: ReplSessionOptions): Promise<Session> {
+export async function openReplSession(opts: ReplSessionOptions): Promise<Session<ReplReply>> {
   const proc = Bun.spawn(opts.argv, { cwd: opts.cwd, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
   let stdout = "";
   let stderr = "";

package/src/main.ts

@@ -5,15 +5,16 @@
  * commands operate an existing app from inside its folder (see
  * `app/commands.ts`). The command line itself is declared in `program.ts`.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import type { CreateArgs } from "./args.ts";
 import { CATALOG } from "./catalog.ts";
 import { kebabCase } from "./naming.ts";
 import { runProgram } from "./program.ts";
-import { renderApp, selectionError } from "./render.ts";
+import { pairingError, renderApp, selectionError } from "./render.ts";
 import { appVersions, cliVersion, newerCli, registryFrom } from "./versions.ts";
 import { appCommands, terminalDeps, type AppDeps } from "./app/commands.ts";
+import { copyPacks, readPacks, withLocalOverrides } from "./app/local-packages.ts";
 import { findApp, type App } from "./app/find-app.ts";
 import { askAnswers, DEFAULT_ASSISTANT_NAME, DEFAULT_ROLE, type Answers } from "./wizard.ts";
 import { finishApp, finishMessage, spawnRun, type Run } from "./finish.ts";
@@ -27,6 +28,7 @@ function answersFromFlags(args: CreateArgs, defaultName: string): Answers {
     role: args.role ?? DEFAULT_ROLE,
     channels: args.channels ?? [],
     plugins: args.plugins ?? [],
+    ...(args.auth !== undefined ? { auth: args.auth } : {}),
     ...(args.gitRemote !== undefined ? { gitRemote: args.gitRemote } : {}),
   };
 }
@@ -104,8 +106,12 @@ function remoteError(args: CreateArgs): string | undefined {
 /** `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, globalInstall: boolean, run: Run): Promise<number> {
-  const relaunched = await relaunchIfStale(rawArgs, relaunch, globalInstall);
-  if (relaunched !== undefined) return relaunched;
+  // An app made on local tarballs is made by this CLI, whatever the registry
+  // has: that's the point of packing them.
+  if (args.localPackages === undefined) {
+    const relaunched = await relaunchIfStale(rawArgs, relaunch, globalInstall);
+    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);
@@ -115,23 +121,38 @@ async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch, g
   }
   const dir = join(dirname(typed), folder);
   // What the command line already settles is checked before any question, so
-  // the wizard is never answered for nothing.
+  // the wizard is never answered for nothing. The HTTP channel and its auth
+  // provider are paired here with --yes, or when the flags give both;
+  // otherwise the wizard asks.
+  const pairedByFlags = args.yes || (args.channels !== undefined && args.auth !== undefined);
   const early =
     targetError(dir) ??
-    selectionError(args.channels ?? [], args.plugins ?? []) ??
+    selectionError(args.channels ?? [], args.plugins ?? [], args.auth) ??
+    (pairedByFlags ? pairingError(args.channels ?? [], args.auth) : undefined) ??
     remoteError(args);
   if (early !== undefined) {
     throw new Error(early);
   }
+  const packs = args.localPackages === undefined ? undefined : await readPacks(args.localPackages, dir);
   const answers = args.yes ? answersFromFlags(args, folder) : await askAnswers(args, dir);
   if (answers === undefined) {
     return 1;
   }
-  const chosen = CATALOG.filter(
-    (e) => (e.kind === "channel" ? answers.channels : answers.plugins).includes(e.id),
+  const chosen = CATALOG.filter((e) =>
+    e.kind === "auth" ? e.id === answers.auth : (e.kind === "channel" ? answers.channels : answers.plugins).includes(e.id),
   ).map((e) => e.package);
-  const versions = await appVersions(chosen, { registry: registryFrom(process.env.MFW_REGISTRY) });
+  const versions = await appVersions(chosen, {
+    registry: registryFrom(process.env.MFW_REGISTRY),
+    ...(packs !== undefined ? { local: Object.fromEntries(packs.map((p) => [p.name, p.version])) } : {}),
+  });
   writeApp(dir, renderApp({ ...answers, versions }));
+  if (packs !== undefined && args.localPackages !== undefined) {
+    // What `mfw local-packages` does, before the install sees the manifest.
+    const manifestPath = join(dir, "package.json");
+    const manifest = withLocalOverrides(JSON.parse(readFileSync(manifestPath, "utf-8")) as Record<string, unknown>, packs);
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    copyPacks(args.localPackages, dir, packs);
+  }
   const none = (ids: string[]) => (ids.length > 0 ? ids.join(", ") : "none");
   const report = await finishApp(
     dir,
@@ -141,7 +162,7 @@ async function create(args: CreateArgs, rawArgs: string[], relaunch: Relaunch, g
       ...(answers.gitRemote !== undefined ? { remote: answers.gitRemote } : {}),
       commitMessage: [
         `Scaffold with mfw create ${cliVersion()}`,
-        `Channels: ${none(answers.channels)}\nPlugins: ${none(answers.plugins)}`,
+        `Channels: ${none(answers.channels)}\nPlugins: ${none(answers.plugins)}${answers.auth !== undefined ? `\nAuth: ${answers.auth}` : ""}`,
       ],
     },
     run,

package/src/program.ts

@@ -52,7 +52,7 @@ function buildProgram(handlers: ProgramHandlers, result: { code: number }): Comm
     .command("create")
     .summary("writes a new Mercury app")
     .description(
-      "Writes a new Mercury app into <folder>, which has to be missing or empty (its own name is turned into kebab case). Without options it asks for the app name, the assistant's name and role, and which channels and tool plugins to include; then it writes mercury.config.ts for that selection, the persona (persona/identity.md, persona/tone.md), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the app reads. Then it runs bun install, and creates a git repository on main with a first commit, adding the origin when given (nothing is pushed).",
+      "Writes a new Mercury app into <folder>, which has to be missing or empty (its own name is turned into kebab case). Without options it asks for the app name, the assistant's name and role, and which channels (with the HTTP channel's auth provider) and tool plugins to include; then it writes mercury.config.ts for that selection, the persona (persona/identity.md, persona/tone.md), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the app reads. Then it runs bun install, and creates a git repository on main with a first commit, adding the origin when given (nothing is pushed).",
     )
     .argument("<folder>", "where to write the app")
     .option("--name <name>", "app name, as in package.json (default: the folder's name)")
@@ -63,7 +63,15 @@ function buildProgram(handlers: ProgramHandlers, result: { code: number }): Comm
       `comma-separated: ${CATALOG.filter((e) => e.kind === "channel").map((e) => e.id).join(", ")}`,
     )
     .option("--plugins <ids>", `comma-separated: ${CATALOG.filter((e) => e.kind === "tool").map((e) => e.id).join(", ")}`)
+    .option(
+      "--auth <id>",
+      `the HTTP channel's auth provider, required with it: ${CATALOG.filter((e) => e.kind === "auth").map((e) => e.id).join(", ")}`,
+    )
     .option("--git-remote <url>", "the repository's origin, taken as typed (default: none)")
+    .option(
+      "--local-packages <folder>",
+      "install the packages packed in <folder> (bun pm pack) instead of the registry's, taking their versions from the tarballs, as mfw local-packages does",
+    )
     .option("--no-install", "don't run bun install")
     .option("--no-git", "don't create the git repository")
     .option("-y, --yes", "don't ask: use the flags and the defaults")
@@ -75,7 +83,7 @@ its latest on the registry (https://registry.npmjs.org, or MFW_REGISTRY).
 
 Examples:
   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`,
     )
     .action(async (folder: string, opts: CreateOptions) => {
       result.code = await handlers.create(toCreateArgs(folder, opts));