@mercury-fw/cli 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mercury-fw/cli
 
+## 0.33.0
+
+### Minor Changes
+
+- a493d9b: - A plugin whose CLI keeps its login in a folder declares it in its `package.json` (`mercury.cliCredentials`): `{ folder }` under `~/.config`, the default, or `{ path }` anywhere else under the home. Any plugin's CLI gets the login mechanism, not only the first-party ones.
+  - The core unpacks each declared login from its env variable onto the credentials volume (`~/.config`) at startup, only when the folder isn't there yet, for the service and the REPL alike; a folder declared elsewhere in the home lives on the volume under `~/.config/mercury-home`, linked from its usual place. It warns about a declared folder with neither the folder nor the variable.
+  - `mfw credentials set|reset <plugin>` names the plugin by its package or its CLI's folder (`@mercury-fw/plugin-jira` or `jira-cli`), read from the app's installed plugins; the short name (`jira`) is no longer accepted, and reset asks for the folder's name.
+  - `mfw create` no longer writes `docker-entrypoint.sh` or the credentials variables in the env example, and always mounts the `cli-credentials` volume; an existing app's entrypoint keeps working alongside.
+  - The generated README explains how a plugin's CLI gets its login without listing plugins.
+  - jira, bitbucket and atlassian-admin declare their CLI's login folder; their READMEs point to `mfw credentials set`.
+
+### Patch Changes
+
+- Updated dependencies [a493d9b]
+  - @mercury-fw/utils@0.33.0
+  - @mercury-fw/core@0.33.0
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -185,22 +185,22 @@ Useful for clearing out test data; the other layer isn't touched.
 
 ### `mfw credentials set <plugin> [--from <dir>] [--print]`
 
-Hands a tool plugin's CLI its login. Every such CLI keeps it in a config folder of its own (`jira-cli`, `bitbucket-cli`, `atlassian-admin-cli`); log in with the CLI on your machine first, then this packs that folder (`~/.config/<cli>`, or `--from` when it lives elsewhere) into a base64 tar.gz and writes it as the plugin's variable in the app's `.env` (`JIRA_CLI_CONFIG_TAR_B64` and so on), replacing an older value and leaving the other lines alone. The value is never printed; `--print` prints the whole line instead and leaves `.env` alone, for pasting it into another host's.
+Hands a plugin's CLI its login, for a plugin whose CLI keeps it in a folder under the home and reads it from there at runtime. The plugin declares that folder in its `package.json` (`mercury.cliCredentials`: `{ "folder": "jira-cli" }` for `~/.config/jira-cli`, the usual place, or `{ "path": ".aws" }` for anywhere else under the home), and `<plugin>` names it by the plugin's package or by what it declares; a name the app doesn't have is an error listing the ones it has. Log in with the CLI on your machine first, then this packs the folder (where the plugin declares it, or `--from` when it lives elsewhere on your machine) into a base64 tar.gz and writes it into the app's `.env` as a variable named after the declaration (`jira-cli` goes in `JIRA_CLI_CONFIG_TAR_B64`, `.aws` in `AWS_CONFIG_TAR_B64`), replacing an older value and leaving the other lines alone. The value is never printed; `--print` prints the whole line instead and leaves `.env` alone, for pasting it into another host's.
 
-When the container starts, the app's `docker-entrypoint.sh` unpacks the variable onto the credentials volume, but only if that CLI's folder isn't there yet: what the CLI writes back while running, like a refreshed token, stays on the volume across redeploys, and an older value in `.env` never overwrites it. `<plugin>` has to be a tool plugin the app depends on.
+When the app starts, it unpacks the variable onto the credentials volume, but only if that CLI's folder isn't there yet: what the CLI writes back while running, like a refreshed token, stays on the volume across redeploys, and an older value in `.env` never overwrites it. The volume is mounted on `~/.config`; a folder declared elsewhere in the home lives on it under `~/.config/mercury-home`, and the app makes its usual place a link to it at every start. A CLI that authenticates any other way isn't covered by this, and neither is one that deletes its own folder and makes it again, since that replaces the link.
 
 ```bash
-mfw credentials set jira
-mfw credentials set bitbucket --from ~/work/bitbucket-login
-mfw credentials set jira --print
+mfw credentials set jira-cli
+mfw credentials set @mercury-fw/plugin-bitbucket --from ~/work/bitbucket-login
+mfw credentials set jira-cli --print
 ```
 
 ### `mfw credentials reset <plugin>`
 
-Deletes the plugin's CLI folder from the credentials volume, so the variable in `.env` is unpacked again at the next start: what to run after correcting a variable whose folder is already on the volume, since the entrypoint never touches an existing folder. It asks you to type the plugin's name first, because a token the CLI refreshed on the volume goes too (and with a CLI that rotates its refresh token, the one in `.env` may no longer work). Once confirmed it stops the app, removes the folder in a one-off container of the app's own image, and starts the app again (`docker compose stop mercury`, `run --rm --no-deps -T mercury rm -rf …`, `up -d mercury`).
+Deletes the plugin's CLI folder from the credentials volume, so the variable in `.env` is unpacked again at the next start: what to run after correcting a variable whose folder is already on the volume, since the app never touches an existing folder. It asks you to type the folder's name first, because a token the CLI refreshed on the volume goes too (and with a CLI that rotates its refresh token, the one in `.env` may no longer work). Once confirmed it stops the app, removes the folder in a one-off container of the app's own image, and starts the app again (`docker compose stop mercury`, `run --rm --no-deps -T mercury rm -rf …`, `up -d mercury`).
 
 ```bash
-mfw credentials reset jira
+mfw credentials reset jira-cli
 ```
 
 ### `mfw google-chat set-key <key-file> [--subscription <name>]`

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

@@ -56,15 +56,15 @@ export declare function appCommands(app: App, deps: AppDeps): {
      * brings its service back up on an empty volume. The volume's real name
      * comes from the compose file, and a wrong answer deletes nothing. */
     reset: (target: ResetTarget) => Promise<number>;
-    /** Packs the plugin's CLI config folder (`from`, by default
-     * `~/.config/<folder>`) into its credentials variable, written into the
-     * app's env file, or printed with `print`. */
+    /** Packs the plugin's CLI login folder (`from`, by default where the
+     * plugin declares it under the home) into its credentials variable,
+     * written into the app's env file, or printed with `print`. */
     credentialsSet: (plugin: string, { from, print }: {
         from?: string;
         print: boolean;
     }) => Promise<number>;
     /** Deletes the plugin's CLI folder from the credentials volume once the
-     * user types the plugin's name, so its variable is unpacked again at the
+     * user types the folder's name, so its variable is unpacked again at the
      * next start. A wrong answer deletes nothing. */
     credentialsReset: (plugin: string) => Promise<number>;
     /** Writes the Google Chat channel's service account key (the JSON file

package/dist/src/catalog.d.ts

@@ -21,19 +21,10 @@ export type CatalogEntry = {
     exportName: string;
     env: EnvVar[];
     formatter?: FormatterExample;
-    credentials?: CliCredentials;
     /** Dependencies whose install scripts Bun must run for this entry (Bun runs
      * none it isn't told to trust), on top of a tool plugin's own package. */
     trusts?: string[];
 };
-/** Where a tool plugin's CLI keeps its login: `folder` under the CLI user's
- * `~/.config`, and the env variable that carries that folder into the
- * container (a base64 tar.gz with the folder at its root), materialized on
- * the credentials volume the first time the folder isn't there. */
-export type CliCredentials = {
-    folder: string;
-    variable: string;
-};
 /** Starting formatter rules for a plugin that hands the user lists: without a
  * rule a kind of list isn't shown, so the scaffolded config wraps the plugin
  * with these. `displaysType` is the type the plugin exports for its kinds,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,16 +41,17 @@
   "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.32.0",
+    "@mercury-fw/core": "0.33.0",
+    "@mercury-fw/utils": "0.33.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
     "@mercury-fw/channel-google-chat": "0.1.3",
     "@mercury-fw/channel-http": "0.1.1",
-    "@mercury-fw/formatter": "0.32.0",
-    "@mercury-fw/plugin-atlassian-admin": "0.1.1",
-    "@mercury-fw/plugin-bitbucket": "0.1.1",
-    "@mercury-fw/plugin-jira": "0.4.2",
+    "@mercury-fw/formatter": "0.33.0",
+    "@mercury-fw/plugin-atlassian-admin": "0.1.2",
+    "@mercury-fw/plugin-bitbucket": "0.1.2",
+    "@mercury-fw/plugin-jira": "0.4.3",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"

package/src/app/commands.ts

@@ -7,8 +7,8 @@
  */
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, relative, resolve } from "node:path";
-import { CATALOG, type CliCredentials } from "../catalog.ts";
+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";
@@ -127,13 +127,13 @@ export function appCommands(app: App, deps: AppDeps) {
       }
       return 0;
     },
-    /** Packs the plugin's CLI config folder (`from`, by default
-     * `~/.config/<folder>`) into its credentials variable, written into the
-     * app's env file, or printed with `print`. */
+    /** Packs the plugin's CLI login folder (`from`, by default where the
+     * plugin declares it under the home) into its credentials variable,
+     * written into the app's env file, or printed with `print`. */
     credentialsSet: async (plugin: string, { from, print }: { from?: string; print: boolean }) => {
-      const { folder, variable } = credentialsOf(app, plugin);
-      const source = resolve(from ?? join(deps.home, ".config", folder));
-      const value = await packCredentials(source, folder);
+      const { name, path, variable } = credentialsOf(app, plugin);
+      const source = resolve(from ?? join(deps.home, path));
+      const value = await packCredentials(source, basename(path));
       if (print) {
         deps.print(`${variable}=${value}`);
         return 0;
@@ -142,23 +142,23 @@ export function appCommands(app: App, deps: AppDeps) {
       setEnvVar(envFile, variable, value);
       deps.print(`${variable} set in ${envFile}, from ${source}.`);
       deps.print(
-        `The app unpacks it at its next start, if the volume has no ${folder} folder yet; if it has one, run mfw credentials reset ${plugin} first.`,
+        `The app unpacks it at its next start, if the volume has no ${name} folder yet; if it has one, run mfw credentials reset ${name} first.`,
       );
       return 0;
     },
     /** Deletes the plugin's CLI folder from the credentials volume once the
-     * user types the plugin's name, so its variable is unpacked again at the
+     * user types the folder's name, so its variable is unpacked again at the
      * next start. A wrong answer deletes nothing. */
     credentialsReset: async (plugin: string) => {
-      const { folder } = credentialsOf(app, plugin);
+      const { name, path } = credentialsOf(app, plugin);
       const answer = await deps.ask(
-        `This deletes ${folder}'s folder from the app's credentials volume, and any token the CLI refreshed since it was unpacked. Type the plugin's name (${plugin}) to confirm: `,
+        `This deletes the ${name} folder from the app's credentials volume, and any token the CLI refreshed since it was unpacked. Type the folder's name (${name}) to confirm: `,
       );
-      if (answer.trim() !== plugin) {
+      if (answer.trim() !== name) {
         deps.print("Not confirmed: nothing deleted.");
         return 1;
       }
-      return stopped(SERVICE, [[...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, "rm", "-rf", `/home/mercury/.config/${folder}`]]);
+      return stopped(SERVICE, [[...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, "rm", "-rf", `/home/mercury/${volumePath(path)}`]]);
     },
     /** Writes the Google Chat channel's service account key (the JSON file
      * at `keyFile`) into the app's env file, and the Pub/Sub subscription when
@@ -274,22 +274,18 @@ export function appCommands(app: App, deps: AppDeps) {
   }
 }
 
-/** The credentials of the tool plugin `plugin`, which `app` must depend on;
- * throws naming the ones it has otherwise. */
+/** The CLI credentials `plugin` names, by package or by folder, among those
+ * the app's dependencies declare; throws naming the ones it has otherwise,
+ * with the dependencies it couldn't read. */
 function credentialsOf(app: App, plugin: string): CliCredentials {
-  const manifest = JSON.parse(readFileSync(join(app.dir, "package.json"), "utf-8")) as {
-    dependencies?: Record<string, string>;
-  };
-  const have = CATALOG.filter(
-    (e) => e.kind === "tool" && e.credentials !== undefined && manifest.dependencies?.[e.package] !== undefined,
-  );
-  const entry = have.find((e) => e.id === plugin);
-  if (entry?.credentials === undefined) {
-    throw new Error(
-      `${app.name} has no "${plugin}" tool plugin with CLI credentials. It has: ${have.map((e) => e.id).join(", ") || "none"}.`,
-    );
+  const { declared, problems } = appCliCredentials(app.dir);
+  const found = declared.find((c) => c.package === plugin || c.name === plugin);
+  if (found === undefined) {
+    const have = declared.map((c) => `${c.package} (${c.name})`).join(", ") || "none";
+    const unread = problems.length > 0 ? ` Left out: ${problems.join("; ")}.` : "";
+    throw new Error(`${app.name} has no CLI credentials named "${plugin}". It has: ${have}.${unread}`);
   }
-  return entry.credentials;
+  return found;
 }
 
 /** The real deps: docker on the user's terminal, questions on `input`

package/src/app/credentials.ts

@@ -1,7 +1,7 @@
 /**
  * The two halves of `mfw credentials set`: packing a CLI's config folder into
  * its credentials variable (a base64 tar.gz with the folder at its root, what
- * the app's `docker-entrypoint.sh` unpacks into `~/.config` on the volume), and
+ * the core unpacks into `~/.config` on the volume at startup), and
  * writing that variable into the app's env file. Also reading a service
  * account key file, for `mfw google-chat set-key`.
  */

package/src/catalog.ts

@@ -19,18 +19,11 @@ export type CatalogEntry = {
   exportName: string;
   env: EnvVar[];
   formatter?: FormatterExample;
-  credentials?: CliCredentials;
   /** Dependencies whose install scripts Bun must run for this entry (Bun runs
    * none it isn't told to trust), on top of a tool plugin's own package. */
   trusts?: string[];
 };
 
-/** Where a tool plugin's CLI keeps its login: `folder` under the CLI user's
- * `~/.config`, and the env variable that carries that folder into the
- * container (a base64 tar.gz with the folder at its root), materialized on
- * the credentials volume the first time the folder isn't there. */
-export type CliCredentials = { folder: string; variable: string };
-
 /** Starting formatter rules for a plugin that hands the user lists: without a
  * rule a kind of list isn't shown, so the scaffolded config wraps the plugin
  * with these. `displaysType` is the type the plugin exports for its kinds,
@@ -71,7 +64,6 @@ export const CATALOG: CatalogEntry[] = [
     kind: "tool",
     package: "@mercury-fw/plugin-jira",
     exportName: "jiraPlugin",
-    credentials: { folder: "jira-cli", variable: "JIRA_CLI_CONFIG_TAR_B64" },
     env: [{ name: "JIRA_SITE_URL", comment: "Required: the Jira site the issue links point to (https://<site>.atlassian.net)" }],
     formatter: {
       displaysType: "JiraDisplays",
@@ -90,7 +82,6 @@ export const CATALOG: CatalogEntry[] = [
     kind: "tool",
     package: "@mercury-fw/plugin-bitbucket",
     exportName: "bitbucketPlugin",
-    credentials: { folder: "bitbucket-cli", variable: "BITBUCKET_CLI_CONFIG_TAR_B64" },
     env: [],
   },
   {
@@ -98,7 +89,6 @@ export const CATALOG: CatalogEntry[] = [
     kind: "tool",
     package: "@mercury-fw/plugin-atlassian-admin",
     exportName: "atlassianAdminPlugin",
-    credentials: { folder: "atlassian-admin-cli", variable: "ATLASSIAN_ADMIN_CLI_CONFIG_TAR_B64" },
     env: [],
   },
 ];

package/src/program.ts

@@ -218,20 +218,20 @@ Examples:
 
   const credentials = program
     .command("credentials")
-    .summary("the tool plugins' CLI credentials")
+    .summary("the login of a plugin's CLI")
     .description(
-      "Hands a tool plugin's CLI its login: the CLI's config folder travels in a variable of the env file, and the container unpacks it onto the credentials volume at the first start without that folder. What the CLI refreshes afterwards stays on the volume.",
+      "For a tool plugin whose CLI keeps its login in a folder (under ~/.config, or elsewhere in the home), and declares it (mercury.cliCredentials in its package.json): the folder travels in a variable of the env file, and the app unpacks it onto the credentials volume at the first start without that folder. What the CLI refreshes afterwards stays on the volume.",
     )
     .helpCommand(false)
     .addHelpText("after", INSIDE_AN_APP);
   credentials
     .command("set")
-    .summary("packs a CLI's config folder into the env file")
+    .summary("packs a CLI's login folder into the env file")
     .description(
-      "Packs the plugin's CLI config folder (~/.config/<cli> unless --from says otherwise) and writes it as the plugin's variable in the app's env file, replacing an older value. The value is never printed, unless --print asks for the line instead.",
+      "Packs the plugin's CLI login folder (where the plugin declares it, ~/.config/<folder> or another path under the home, unless --from says otherwise) and writes it as the plugin's variable in the app's env file, replacing an older value. The value is never printed, unless --print asks for the line instead.",
     )
-    .argument("<plugin>", "a tool plugin of the app: jira, bitbucket, atlassian-admin")
-    .option("--from <dir>", "the CLI's config folder, when it isn't ~/.config/<cli>")
+    .argument("<plugin>", "the plugin's package (@mercury-fw/plugin-jira) or its CLI's folder as declared (jira-cli)")
+    .option("--from <dir>", "the CLI's login folder, when it isn't where the plugin declares it")
     .option("--print", "print the line to paste elsewhere, and leave the env file alone")
     .action(async (plugin: string, opts: { from?: string; print?: boolean }) =>
       inApp((app) => app.credentialsSet(plugin, { ...(opts.from === undefined ? {} : { from: opts.from }), print: opts.print ?? false }))(),
@@ -240,9 +240,9 @@ Examples:
     .command("reset")
     .summary("clears a CLI's folder from the volume")
     .description(
-      "Deletes the plugin's CLI folder from the credentials volume, after you type the plugin's name, so its variable is unpacked again at the next start: what to run after correcting the variable. Any token the CLI refreshed on the volume goes with it.",
+      "Deletes the plugin's CLI folder from the credentials volume, after you type the folder's name, so its variable is unpacked again at the next start: what to run after correcting the variable. Any token the CLI refreshed on the volume goes with it.",
     )
-    .argument("<plugin>", "a tool plugin of the app")
+    .argument("<plugin>", "the plugin's package or its CLI's folder")
     .action(async (plugin: string) => inApp((app) => app.credentialsReset(plugin))());
 
   const googleChat = program

package/src/render.ts

@@ -8,7 +8,7 @@
  * written in catalog order, whatever order they were chosen in.
  */
 import { DEFAULT_PERSONA_TONE } from "@mercury-fw/core";
-import { CATALOG, type CatalogEntry, type CliCredentials, type EnvVar } from "./catalog.ts";
+import { CATALOG, type CatalogEntry, type EnvVar } from "./catalog.ts";
 import indexTs from "../template/src/index.ts.tpl" with { type: "text" };
 import replTs from "../template/src/repl.ts.tpl" with { type: "text" };
 import markdownDts from "../template/markdown.d.ts.tpl" with { type: "text" };
@@ -67,9 +67,9 @@ export function renderApp(input: RenderInput): Map<string, string> {
     [".dockerignore", dockerignore],
     [".env.example", renderEnv(channels, tools)],
     [".gitignore", gitignore],
-    ["Dockerfile", renderDockerfile(tools)],
+    ["Dockerfile", dockerfile],
     ["README.md", renderReadme(input.name, channels, tools)],
-    ["docker-compose.yml", renderCompose(input.name, tools.length > 0, channels.some((c) => c.id === "http"))],
+    ["docker-compose.yml", renderCompose(input.name, 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)],
@@ -80,60 +80,9 @@ export function renderApp(input: RenderInput): Map<string, string> {
     ["src/index.ts", indexTs],
     ["src/repl.ts", replTs],
     ["tsconfig.json", tsconfigJson],
-    ...(withCredentials(tools).length > 0
-      ? [["docker-entrypoint.sh", renderEntrypoint(withCredentials(tools))] as [string, string]]
-      : []),
   ]);
 }
 
-/** The chosen tool plugins whose CLI needs credentials, with them. */
-function withCredentials(tools: CatalogEntry[]): Array<CatalogEntry & { credentials: CliCredentials }> {
-  return tools.filter((t): t is CatalogEntry & { credentials: CliCredentials } => t.credentials !== undefined);
-}
-
-/** The template's Dockerfile; with CLI credentials to materialize, the service
- * starts through `docker-entrypoint.sh` instead of directly. */
-function renderDockerfile(tools: CatalogEntry[]): string {
-  if (withCredentials(tools).length === 0) return dockerfile;
-  const cmd = 'CMD ["bun", "src/index.ts"]\n';
-  if (!dockerfile.endsWith(cmd)) throw new Error("Dockerfile.tpl no longer ends with the service's CMD");
-  return `${dockerfile.slice(0, -cmd.length)}# Materializes the tool plugins' CLI credentials on the first start, then
-# starts the service.
-COPY --chown=mercury:mercury --chmod=755 docker-entrypoint.sh ./
-CMD ["./docker-entrypoint.sh"]
-`;
-}
-
-/** \`docker-entrypoint.sh\`: each plugin's credentials variable materialized
- * into its CLI's folder on the volume, only while that folder isn't there,
- * then the service. */
-function renderEntrypoint(tools: Array<CatalogEntry & { credentials: CliCredentials }>): string {
-  const lines = tools.map((t) => `materialize ${t.credentials.folder} ${t.credentials.variable}`).join("\n");
-  return `#!/usr/bin/env bash
-# Starts the service, first materializing each tool plugin's CLI credentials
-# onto the cli-credentials volume: its variable in the env file is the CLI's
-# config folder as a base64 tar.gz (mfw credentials set <plugin> writes
-# it). Only when that CLI's folder isn't on the volume yet: what a CLI writes
-# back while running, like a refreshed token, stays there across redeploys,
-# and an older value in the env file never overwrites it. mfw credentials
-# reset <plugin> clears one folder so its variable is materialized again.
-set -euo pipefail
-
-materialize() {
-  local folder="$1"
-  local variable="$2"
-  local value="\${!variable:-}"
-  if [[ -n "$value" && ! -d "/home/mercury/.config/$folder" ]]; then
-    echo "$value" | base64 -d | tar xzf - -C /home/mercury/.config
-  fi
-}
-
-${lines}
-
-exec bun src/index.ts
-`;
-}
-
 /** 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 function appNameError(name: string): string | undefined {
@@ -291,31 +240,18 @@ function renderEnv(channels: CatalogEntry[], tools: CatalogEntry[]): string {
   const block = (vars: EnvVar[]) => vars.map((v) => `# ${v.comment}\n${v.name}=${v.value ?? ""}`).join("\n");
   const sections = [block(CORE_ENV)];
   for (const entry of [...channels, ...tools]) {
-    const vars = [...entry.env];
-    if (entry.credentials !== undefined) {
-      vars.push({
-        name: entry.credentials.variable,
-        comment: `${entry.credentials.folder}'s config folder, packed: mfw credentials set ${entry.id} writes it; materialized on the credentials volume at the first start without that folder`,
-      });
-    }
-    if (vars.length > 0) {
-      sections.push(`# --- ${entry.id}\n${block(vars)}`);
+    if (entry.env.length > 0) {
+      sections.push(`# --- ${entry.id}\n${block(entry.env)}`);
     }
   }
   return `${sections.join("\n\n")}\n`;
 }
 
 /** `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,
- * 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",
-        "      # (refreshed tokens) survives a redeploy. docker-entrypoint.sh fills it: see README.md.",
-        "      - cli-credentials:/home/mercury/.config",
-      ]
-    : [];
+ * app's name, the CLI credentials one included whatever was chosen (a plugin
+ * with a CLI can come later); the HTTP surface's port published on the host
+ * only with the HTTP channel. */
+function renderCompose(name: string, hasHttp: boolean): string {
   const httpPort = hasHttp
     ? [
         "    # The HTTP surface, on the host: no authentication, keep it off the public network.",
@@ -323,7 +259,6 @@ function renderCompose(name: string, hasTools: boolean, hasHttp: boolean): strin
         '      - "${HTTP_SURFACE_PORT:-4100}:${HTTP_SURFACE_PORT:-4100}"',
       ]
     : [];
-  const credentialsVolume = hasTools ? ["  cli-credentials:", `    name: ${name}_cli-credentials`] : [];
   return [
     "services:",
     "  mercury:",
@@ -335,7 +270,9 @@ function renderCompose(name: string, hasTools: boolean, hasHttp: boolean): strin
     "        required: false",
     "    volumes:",
     "      - wiki-vault:/app/wiki-vault",
-    ...credentialsMount,
+    "      # The login of a plugin's CLI, on a volume so what the CLI writes back",
+    "      # (refreshed tokens) survives a redeploy: see README.md.",
+    "      - cli-credentials:/home/mercury/.config",
     ...httpPort,
     "    extra_hosts:",
     '      - "host.docker.internal:host-gateway"',
@@ -352,7 +289,8 @@ function renderCompose(name: string, hasTools: boolean, hasHttp: boolean): strin
     `    name: ${name}_wiki-vault`,
     "  qdrant-data:",
     `    name: ${name}_qdrant-data`,
-    ...credentialsVolume,
+    "  cli-credentials:",
+    `    name: ${name}_cli-credentials`,
     "",
   ].join("\n");
 }
@@ -392,7 +330,7 @@ mfw repl
 \`\`\`
 
 \`bun install\` here gives your editor, \`bun run typecheck\` and the app's own \`mfw\` (the one a global \`mfw\` runs inside the app) the packages (tool plugins download their CLI binary as they install); the image installs its own copy when it builds. \`mfw start\` builds the image and starts the app with Qdrant in the background, \`mfw repl\` opens a terminal conversation with the assistant. \`mfw --help\` lists the rest: stopping and restarting, logs, a shell in the container, the wiki and the memory, and resetting them.
-${renderHttpSection(channels)}${renderCredentialsSection(withCredentials(tools))}`;
+${renderHttpSection(channels)}${CREDENTIALS_SECTION}`;
 }
 
 /** The README section on the HTTP surface, for an app with the HTTP channel;
@@ -406,27 +344,25 @@ The HTTP channel listens on \`http://<host>:4100\`, the port in \`HTTP_SURFACE_P
 `;
 }
 
-/** The README section on CLI credentials, for an app with tool plugins;
- * nothing without one. */
-function renderCredentialsSection(tools: Array<CatalogEntry & { credentials: CliCredentials }>): string {
-  if (tools.length === 0) return "";
-  const first = tools[0] as CatalogEntry & { credentials: CliCredentials };
-  const list = tools.map((t) => `\`${t.id}\` (\`~/.config/${t.credentials.folder}\`)`).join(", ");
-  return `
+/** The README section on CLI credentials: how a plugin whose CLI keeps its
+ * login in a folder gets it into the container. Generic on purpose: a CLI is
+ * a feature of some plugins, from any author, not something to list here. */
+const CREDENTIALS_SECTION = `
 ## CLI credentials
 
-Each tool plugin runs its own CLI, and each CLI keeps its login in a folder of its own: ${list}. Log in with the CLI on your machine first (its own README says how), then hand that folder to the app:
+Some tool plugins run a CLI. When that CLI keeps its login in a folder under your home and reads it at runtime to authenticate, this is how the folder gets into the container: log in with the CLI on your machine first (its own README says how), then hand the folder to the app:
 
 \`\`\`bash
-mfw credentials set ${first.id}
+mfw credentials set <plugin>
 \`\`\`
 
-It packs the folder into its variable in \`.env\` (\`--from <folder>\` if it isn't where the CLI usually keeps it, \`--print\` to get the line to paste on another host instead). When the container starts, \`docker-entrypoint.sh\` unpacks it onto the \`cli-credentials\` volume, but only if that CLI's folder isn't there yet: what the CLI writes back afterwards, like a refreshed token, stays on the volume across redeploys, and the older value in \`.env\` never overwrites it.
+\`<plugin>\` is the plugin's package or its CLI's folder, which the plugin declares (\`mercury.cliCredentials\` in its \`package.json\`: a folder under \`~/.config\`, or a path anywhere under the home); \`mfw credentials set\` with a name the app doesn't have lists the ones it has. It packs the folder into its variable in \`.env\` (\`--from <folder>\` if it isn't where the CLI usually keeps it, \`--print\` to get the line to paste on another host instead). When the app starts, it unpacks the variable onto the \`cli-credentials\` volume (mounted on \`~/.config\`: a folder declared elsewhere in the home lives under \`~/.config/mercury-home\`, and its usual place links there), but only if that CLI's folder isn't there yet: what the CLI writes back afterwards, like a refreshed token, stays on the volume across redeploys, and the older value in \`.env\` never overwrites it.
 
 That same rule means a corrected variable does nothing while the old folder is on the volume. Clear it, and the next start unpacks the variable again:
 
 \`\`\`bash
-mfw credentials reset ${first.id}
+mfw credentials reset <plugin>
 \`\`\`
+
+A CLI that authenticates any other way isn't covered by this, and nothing guarantees it works in Mercury; neither does one that deletes its own folder and makes it again, since that replaces the link.
 `;
-}