@mercury-fw/cli 0.26.0 → 0.27.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @mercury-fw/cli
 
+## 0.27.1
+
+### Patch Changes
+
+- Updated dependencies [2c0e020]
+  - @mercury-fw/core@0.27.1
+
+## 0.27.0
+
+### Minor Changes
+
+- d2a6be5: - A scaffolded app with tool plugins gets a `docker-entrypoint.sh`: at the first start without a CLI's config folder on the credentials volume, it unpacks that CLI's variable from the env file there, then starts the service. What the CLI refreshes afterwards stays on the volume.
+  - The scaffolded env example lists each tool plugin's credentials variable, and the README explains the flow.
+  - `mfw credentials set <plugin>` packs a CLI's config folder (`~/.config/<cli>`, or `--from <dir>`) into its variable in the app's env file, never printing it; `--print` prints the line to paste elsewhere.
+  - `mfw credentials reset <plugin>` clears a CLI's folder from the credentials volume after you type the plugin's name, so a corrected variable is unpacked at the next start.
+
+### Patch Changes
+
+- @mercury-fw/core@0.27.0
+
 ## 0.26.0
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,8 @@
   - [`mfw memory list`](#mfw-memory-list)
   - [`mfw memory read <collection> [--limit N]`](#mfw-memory-read-collection---limit-n)
   - [`mfw reset <memory|wiki>`](#mfw-reset-memorywiki)
+  - [`mfw credentials set <plugin> [--from <dir>] [--print]`](#mfw-credentials-set-plugin---from-dir---print)
+  - [`mfw credentials reset <plugin>`](#mfw-credentials-reset-plugin)
 - [Help](#help)
 
 ## Getting it
@@ -166,6 +168,26 @@ bunx mfw reset wiki
 
 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.
+
+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.
+
+```bash
+bunx mfw credentials set jira
+bunx mfw credentials set bitbucket --from ~/work/bitbucket-login
+bunx mfw credentials set jira --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`).
+
+```bash
+bunx mfw credentials reset jira
+```
+
 ## Help
 
 `mfw --help` lists every command, and `--help` after any of them describes it, down to the subcommands (`mfw vault write-curated --help`). A mistyped command gets a suggestion (`mfw strat` → "Did you mean start?"). Every argument is checked before anything runs: a wrong one exits 1 saying why, with no container started.

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

@@ -1,10 +1,3 @@
-/**
- * The commands that operate an app (`mfw start`, `mfw vault`, …): each one is
- * a short sequence of `docker compose` calls run from the app's folder, so the
- * docker details live here and not in every app. The command line is parsed
- * 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 type { App } from "./find-app.ts";
 export type AppDeps = {
     /** Runs `argv` in `cwd` on the user's terminal (stdin, stdout, stderr) and returns its exit code. */
@@ -19,6 +12,8 @@ export type AppDeps = {
     ask: (question: string) => Promise<string>;
     /** Tells the user something. */
     print: (line: string) => void;
+    /** The user's home folder, where a CLI keeps its config (`~/.config/<cli>`). */
+    home: string;
 };
 /** The core's maintenance CLIs, from the container's working directory (the
  * app's folder, where node_modules/@mercury-fw/core is). A path and not a bin:
@@ -61,6 +56,17 @@ 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`. */
+    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
+     * next start. A wrong answer deletes nothing. */
+    credentialsReset: (plugin: string) => Promise<number>;
 };
 /** The real deps: docker on the user's terminal, questions on `input`
  * (stdin by default). */

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

@@ -0,0 +1,12 @@
+/** `from` packed as `<folder>/…` into a base64 tar.gz on one line. The real
+ * folder behind `from` is archived through a symlink named `folder` and
+ * dereferenced (`-h`): whatever `from` is called, and even when it's itself a
+ * symlink (dotfiles), the archive holds the files under the CLI's folder name. */
+export declare function packCredentials(from: string, folder: string): Promise<string>;
+/** Sets `name=value` in the env file at `file`. Every line that assigns
+ * `name` (`export name=` and spaces around `=` included) gives way to one
+ * line, where the first was; with none, it's appended. Every other line stays
+ * as it was. The file is replaced whole through a temporary file next to it,
+ * keeping its permissions, so a failed write never leaves it half written; a
+ * missing file is created readable by its owner only. */
+export declare function setEnvVar(file: string, name: string, value: string): void;

package/dist/src/catalog.d.ts

@@ -21,6 +21,15 @@ export type CatalogEntry = {
     exportName: string;
     env: EnvVar[];
     formatter?: FormatterExample;
+    credentials?: CliCredentials;
+};
+/** 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

package/package.json

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

package/src/app/commands.ts

@@ -5,6 +5,11 @@
  * 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 { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { CATALOG, type CliCredentials } from "../catalog.ts";
+import { packCredentials, setEnvVar } from "./credentials.ts";
 import type { App } from "./find-app.ts";
 
 export type AppDeps = {
@@ -16,6 +21,8 @@ export type AppDeps = {
   ask: (question: string) => Promise<string>;
   /** Tells the user something. */
   print: (line: string) => void;
+  /** The user's home folder, where a CLI keeps its config (`~/.config/<cli>`). */
+  home: string;
 };
 
 const COMPOSE = ["docker", "compose"];
@@ -92,25 +99,83 @@ export function appCommands(app: App, deps: AppDeps) {
         deps.print("Not confirmed: nothing deleted.");
         return 1;
       }
-      const steps = [
-        [...COMPOSE, "stop", service],
+      const code = await stopped(service, [
         [...COMPOSE, "rm", "-f", service],
         ["docker", "volume", "rm", volume],
-        [...COMPOSE, "up", "-d", service],
-      ];
-      for (const [i, argv] of steps.entries()) {
-        const code = await deps.run(argv, { cwd: app.dir });
-        if (code === 0) continue;
-        if (i > 0) deps.print(`The ${service} service was stopped and not restarted: bunx mfw start brings it back.`);
-        return code;
-      }
+      ]);
+      if (code !== 0) return code;
       // A running app sets up its Qdrant collections only when it starts.
       if (target === "memory" && (await running()).includes(SERVICE)) {
         return runAll([[...COMPOSE, "restart", SERVICE]]);
       }
       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`. */
+    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);
+      if (print) {
+        deps.print(`${variable}=${value}`);
+        return 0;
+      }
+      const envFile = join(app.dir, ".env");
+      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 bunx mfw credentials reset ${plugin} 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
+     * next start. A wrong answer deletes nothing. */
+    credentialsReset: async (plugin: string) => {
+      const { folder } = 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: `,
+      );
+      if (answer.trim() !== plugin) {
+        deps.print("Not confirmed: nothing deleted.");
+        return 1;
+      }
+      return stopped(SERVICE, [[...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, "rm", "-rf", `/home/mercury/.config/${folder}`]]);
+    },
+  };
+
+  /** Stops `service`, runs `steps`, starts it again; stops at the first
+   * failure and, once the service is stopped, says it's down and how to bring
+   * it back. Returns the exit code. */
+  async function stopped(service: string, steps: string[][]): Promise<number> {
+    const all = [[...COMPOSE, "stop", service], ...steps, [...COMPOSE, "up", "-d", service]];
+    for (const [i, argv] of all.entries()) {
+      const code = await deps.run(argv, { cwd: app.dir });
+      if (code === 0) continue;
+      if (i > 0) deps.print(`The ${service} service was stopped and not restarted: bunx mfw start brings it back.`);
+      return code;
+    }
+    return 0;
+  }
+}
+
+/** The credentials of the tool plugin `plugin`, which `app` must depend on;
+ * throws naming the ones it has otherwise. */
+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"}.`,
+    );
+  }
+  return entry.credentials;
 }
 
 /** The real deps: docker on the user's terminal, questions on `input`
@@ -144,5 +209,6 @@ export function terminalDeps({
       });
     },
     print: (line) => console.log(line),
+    home: homedir(),
   };
 }

package/src/app/credentials.ts

@@ -0,0 +1,82 @@
+/**
+ * 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
+ * writing that variable into the app's env file.
+ */
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+/** `from` packed as `<folder>/…` into a base64 tar.gz on one line. The real
+ * folder behind `from` is archived through a symlink named `folder` and
+ * dereferenced (`-h`): whatever `from` is called, and even when it's itself a
+ * symlink (dotfiles), the archive holds the files under the CLI's folder name. */
+export async function packCredentials(from: string, folder: string): Promise<string> {
+  const source = resolve(from);
+  if (!existsSync(source) || !statSync(source).isDirectory()) {
+    throw new Error(`No folder at ${source}`);
+  }
+  const staging = mkdtempSync(join(tmpdir(), "mfw-credentials-"));
+  symlinkSync(realpathSync(source), join(staging, folder));
+  try {
+    // COPYFILE_DISABLE: macOS's tar would otherwise add ._ files for metadata.
+    const proc = Bun.spawn(["tar", "-czh", "--no-xattrs", "-f", "-", "-C", staging, folder], {
+      env: { ...process.env, COPYFILE_DISABLE: "1" },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [archive, stderr, code] = await Promise.all([
+      new Response(proc.stdout).arrayBuffer(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    if (code !== 0) throw new Error(`tar failed packing ${source}: ${stderr.trim()}`);
+    return Buffer.from(archive).toString("base64");
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+/** Sets `name=value` in the env file at `file`. Every line that assigns
+ * `name` (`export name=` and spaces around `=` included) gives way to one
+ * line, where the first was; with none, it's appended. Every other line stays
+ * as it was. The file is replaced whole through a temporary file next to it,
+ * keeping its permissions, so a failed write never leaves it half written; a
+ * missing file is created readable by its owner only. */
+export function setEnvVar(file: string, name: string, value: string): void {
+  const line = `${name}=${value}`;
+  if (!existsSync(file)) {
+    writeFileSync(file, `${line}\n`, { mode: 0o600 });
+    return;
+  }
+  const text = readFileSync(file, "utf-8");
+  const assigns = new RegExp(`^\\s*(export\\s+)?${name}\\s*=`);
+  const lines = text.split("\n");
+  const first = lines.findIndex((l) => assigns.test(l));
+  let next: string;
+  if (first === -1) {
+    next = `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}${line}\n`;
+  } else {
+    next = lines
+      .flatMap((l, i) => (i === first ? [line] : assigns.test(l) ? [] : [l]))
+      .join("\n");
+  }
+  const temporary = join(dirname(file), `.${name}.${process.pid}.tmp`);
+  const mode = statSync(file).mode & 0o777;
+  writeFileSync(temporary, next, { mode });
+  // The umask may have narrowed `mode` on creation.
+  chmodSync(temporary, mode);
+  renameSync(temporary, file);
+}

package/src/catalog.ts

@@ -19,8 +19,15 @@ export type CatalogEntry = {
   exportName: string;
   env: EnvVar[];
   formatter?: FormatterExample;
+  credentials?: CliCredentials;
 };
 
+/** 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,
@@ -58,6 +65,7 @@ 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: "Jira site the issue links point to (https://<site>.atlassian.net)" }],
     formatter: {
       displaysType: "JiraDisplays",
@@ -76,6 +84,7 @@ export const CATALOG: CatalogEntry[] = [
     kind: "tool",
     package: "@mercury-fw/plugin-bitbucket",
     exportName: "bitbucketPlugin",
+    credentials: { folder: "bitbucket-cli", variable: "BITBUCKET_CLI_CONFIG_TAR_B64" },
     env: [],
   },
   {
@@ -83,6 +92,7 @@ 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

@@ -199,6 +199,35 @@ Examples:
     .addHelpText("after", INSIDE_AN_APP)
     .action(async (target: ResetTarget) => inApp((app) => app.reset(target))());
 
+  const credentials = program
+    .command("credentials")
+    .summary("the tool plugins' CLI credentials")
+    .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.",
+    )
+    .helpCommand(false)
+    .addHelpText("after", INSIDE_AN_APP);
+  credentials
+    .command("set")
+    .summary("packs a CLI's config 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.",
+    )
+    .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>")
+    .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 }))(),
+    );
+  credentials
+    .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.",
+    )
+    .argument("<plugin>", "a tool plugin of the app")
+    .action(async (plugin: string) => inApp((app) => app.credentialsReset(plugin))());
+
   return 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 EnvVar } from "./catalog.ts";
+import { CATALOG, type CatalogEntry, type CliCredentials, 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" };
@@ -68,7 +68,7 @@ export function renderApp(input: RenderInput): Map<string, string> {
     [".dockerignore", dockerignore],
     [".env.example", renderEnv(channels, tools)],
     [".gitignore", gitignore],
-    ["Dockerfile", dockerfile],
+    ["Dockerfile", renderDockerfile(tools)],
     ["README.md", renderReadme(input.name, channels, tools)],
     ["docker-compose.yml", renderCompose(input.name, tools.length > 0)],
     ["markdown.d.ts", markdownDts],
@@ -81,9 +81,60 @@ 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 (bunx 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. bunx 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 {
@@ -251,8 +302,15 @@ function renderEnv(channels: CatalogEntry[], tools: CatalogEntry[]): string {
     );
   }
   for (const entry of [...channels, ...tools]) {
-    if (entry.env.length > 0) {
-      sections.push(`# --- ${entry.id}\n${block(entry.env)}`);
+    const vars = [...entry.env];
+    if (entry.credentials !== undefined) {
+      vars.push({
+        name: entry.credentials.variable,
+        comment: `${entry.credentials.folder}'s config folder, packed: bunx 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)}`);
     }
   }
   return `${sections.join("\n\n")}\n`;
@@ -264,7 +322,7 @@ function renderCompose(name: string, hasTools: boolean): string {
   const credentialsMount = hasTools
     ? [
         "      # The tool plugins' CLI credentials, on a volume so what a CLI writes back",
-        "      # (refreshed tokens) survives a redeploy. It starts empty: see README.md.",
+        "      # (refreshed tokens) survives a redeploy. docker-entrypoint.sh fills it: see README.md.",
         "      - cli-credentials:/home/mercury/.config",
       ]
     : [];
@@ -328,12 +386,30 @@ bunx mfw repl
 \`\`\`
 
 \`bun install\` here gives your editor, \`bun run typecheck\` and \`mfw\` the packages (tool plugins download their CLI binary as they install); the image installs its own copy when it builds. \`bunx mfw start\` builds the image and starts the app with Qdrant in the background, \`bunx mfw repl\` opens a terminal conversation with the assistant. \`bunx mfw --help\` lists the rest: stopping and restarting, logs, a shell in the container, the wiki and the memory, and resetting them.
-${tools.length > 0 ? CREDENTIALS_SECTION : ""}`;
+${renderCredentialsSection(withCredentials(tools))}`;
 }
 
-/** The README section on CLI credentials, for an app with tool plugins. */
-const CREDENTIALS_SECTION = `
+/** 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 `
 ## CLI credentials
 
-Each tool plugin runs its own CLI, and each CLI keeps its login under \`/home/mercury/.config\` in the container, on the \`cli-credentials\` volume. The volume starts empty: nothing in this app provisions it yet, so authenticate each CLI once inside the container (\`docker compose run --rm mercury <cli> --help\` lists its auth commands) or copy its config folder into the volume. What the CLIs write back afterwards, like refreshed tokens, stays on the volume across redeploys.
+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:
+
+\`\`\`bash
+bunx mfw credentials set ${first.id}
+\`\`\`
+
+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.
+
+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
+bunx mfw credentials reset ${first.id}
+\`\`\`
 `;
+}