@mercury-fw/cli 0.38.0 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @mercury-fw/cli
 
+## 0.39.0
+
+### Minor Changes
+
+- 881835c: A CLI's login is set up inside the app's container, no longer carried in the env file.
+
+  - A plugin declares in `mercury.cliCredentials` the commands that set its CLI's login up (`setup`, required), check it (`check`) and log an identity out (`logout`), each a binary followed by its arguments.
+  - `mfw credentials setup <plugin>` runs the declared setup in a one-off container on your terminal, so the CLI writes its login straight onto the credentials volume; `mfw credentials check <plugin>` runs the declared check.
+  - `mfw credentials reset <plugin> [--user <key>]` runs the declared logout, of the identity Mercury runs as or of one person, instead of deleting the CLI's folder.
+  - `mfw credentials set` is removed, and the core no longer unpacks `*_CONFIG_TAR_B64` variables at startup: it reports a declared login that isn't set up yet, and still links a login kept outside `~/.config` to the volume.
+  - A command the model writes with `--user` is refused: which person a CLI acts as is never the model's to pick.
+  - `cliUserId` (`@mercury-fw/utils`) maps a user key to the id a CLI knows a person by.
+  - plugin-jira and plugin-bitbucket pin their CLIs at 2.1.0, which keep the service identity and each person apart and refuse the old login folder. After updating, remove the plugin's `*_CONFIG_TAR_B64` line from the env file and run `mfw credentials setup` once; on Jira, Mercury now runs as an Atlassian Service Account.
+  - plugin-atlassian-admin keeps its CLI at 0.1.2, whose `init` doesn't prompt for the organization key: until it does, write the key from `mfw shell` with `atlassian-admin init --api-key <KEY> --org-id <ORG_ID>` (the plugin's README says so).
+
+### Patch Changes
+
+- Updated dependencies [881835c]
+  - @mercury-fw/core@0.39.0
+  - @mercury-fw/utils@0.39.0
+
+## 0.38.1
+
+### Patch Changes
+
+- 972a17f: - `mfw local-packages` and `mfw create --local-packages` name each tarball in `.packs/` after its content, so a package repacked at the same version is installed anew instead of kept from Bun's cache or refused by the lockfile's integrity check
+  - @mercury-fw/core@0.38.1
+  - @mercury-fw/utils@0.38.1
+
 ## 0.38.0
 
 ### Minor Changes

package/README.md

@@ -17,8 +17,9 @@
   - [`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)
+  - [`mfw credentials setup <plugin>`](#mfw-credentials-setup-plugin)
+  - [`mfw credentials check <plugin>`](#mfw-credentials-check-plugin)
+  - [`mfw credentials reset <plugin> [--user <key>]`](#mfw-credentials-reset-plugin---user-key)
   - [`mfw google-chat set-key <key-file> [--subscription <name>]`](#mfw-google-chat-set-key-key-file---subscription-name)
   - [`mfw local-packages <folder>` / `mfw local-packages --off`](#mfw-local-packages-folder--mfw-local-packages---off)
   - [`mfw e2e [tests...] [--repeat N]`](#mfw-e2e-tests---repeat-n)
@@ -185,24 +186,44 @@ mfw reset wiki
 
 Useful for clearing out test data; the other layer isn't touched.
 
-### `mfw credentials set <plugin> [--from <dir>] [--print]`
+### `mfw credentials setup <plugin>`
 
-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.
+Sets up a plugin's CLI 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`, with the commands that set the login up, check it and log an identity out, each a binary on the container's PATH followed by its arguments:
 
-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.
+```json
+"mercury": {
+  "cliCredentials": {
+    "folder": "jira-cli",
+    "setup": ["jira", "init"],
+    "check": ["jira", "doctor"],
+    "logout": ["jira", "auth", "logout"]
+  }
+}
+```
+
+`folder` is under `~/.config`, the usual place; `{ "path": ".aws" }` declares one anywhere else under the home. `setup` is required, `check` and `logout` aren't. `<plugin>` names the declaration by the plugin's package or by its folder; a name the app doesn't have is an error listing the ones it has.
+
+`setup` runs the declared setup in a one-off container of the app (`docker compose run --rm --no-deps mercury jira init`) on your terminal, so the CLI asks you for what it needs and writes the login straight onto the credentials volume, mounted on `~/.config`. A login declared elsewhere in the home lives on the volume under `~/.config/mercury-home`, and its usual place is linked there first (the app makes the same link at every start). What the CLI writes back while running, like a refreshed token or a person's login, stays on the volume across redeploys. This sets up the identity Mercury itself runs as; people log in on their own, through Mercury. Nothing goes in the env file, and nothing is carried between machines: each environment sets up its own. 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 setup @mercury-fw/plugin-jira
+```
+
+### `mfw credentials check <plugin>`
+
+Runs the check the plugin declares (the CLI's `doctor`, for the first-party plugins) in a one-off container, and exits with its code.
 
 ```bash
-mfw credentials set jira-cli
-mfw credentials set @mercury-fw/plugin-bitbucket --from ~/work/bitbucket-login
-mfw credentials set jira-cli --print
+mfw credentials check jira-cli
 ```
 
-### `mfw credentials reset <plugin>`
+### `mfw credentials reset <plugin> [--user <key>]`
 
-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`).
+Runs the logout the plugin declares in a one-off container, after you type the name it's declared by (its folder). Without `--user` it logs out the identity Mercury runs as, which then needs `mfw credentials setup` again; with `--user` it logs out one person, by their user key (`<provider>:<id>`), who logs in again through Mercury the next time they need it. The CLI only forgets the login: the tokens aren't revoked at the service.
 
 ```bash
 mfw credentials reset jira-cli
+mfw credentials reset jira-cli --user oidc:312345678901234567
 ```
 
 ### `mfw google-chat set-key <key-file> [--subscription <name>]`
@@ -222,7 +243,7 @@ Makes the app install `@mercury-fw/*` packages from local tarballs instead of th
 
 Overrides, and not the dependencies themselves, because a packed package names the packages it depends on by version, and the registry has those versions too: only an override sends them to the tarballs as well (a packed `@mercury-fw/core` depends on `@mercury-fw/plugin-types`, for example). The Dockerfile `mfw create` writes copies `.packs/` before installing, so the image gets the same packages (an app created before 0.31.0 needs `COPY --chown=mercury:mercury .pack[s] ./.packs/` added after the line copying `package.json`); `.gitignore` leaves it out of the repository.
 
-Run it again after packing anew: it replaces the tarballs and the overrides of the previous run, and leaves alone the overrides you wrote yourself. `--off` takes the app back to the registry: the overrides it wrote and `.packs/` go, then `bun install`. After either, `mfw start` rebuilds the image with the packages now installed.
+Run it again after packing anew: it replaces the tarballs and the overrides of the previous run, and leaves alone the overrides you wrote yourself. In `.packs/` each tarball is named after its content (`mercury-fw-core-0.38.0-1a2b3c4d.tgz`): Bun doesn't look again at a tarball whose override didn't change, it keeps what its lockfile and its cache hold, so a repack at the same version needs a new name to be installed. `--off` takes the app back to the registry: the overrides it wrote and `.packs/` go, then `bun install`. After either, `mfw start` rebuilds the image with the packages now installed.
 
 ```bash
 mfw local-packages ../mercury-fw/apps/testbed/.packs

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

@@ -56,17 +56,19 @@ 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 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;
+    /** Runs the plugin's declared setup in a one-off container on the user's
+     * terminal (without `-T`, compose attaches a TTY whenever stdin is one),
+     * so the CLI asks what it needs and writes its login straight onto the
+     * credentials volume. */
+    credentialsSetup: (plugin: string) => Promise<number>;
+    /** Runs the plugin's declared check in a one-off container. */
+    credentialsCheck: (plugin: string) => Promise<number>;
+    /** Runs the plugin's declared logout, of the service identity or of the
+     * person whose user key is `user`, once the user types the declared name.
+     * A wrong answer runs nothing. */
+    credentialsReset: (plugin: string, { user }: {
+        user?: string;
     }) => Promise<number>;
-    /** Deletes the plugin's CLI folder from the credentials volume once 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
      * at `keyFile`) into the app's env file, and the Pub/Sub subscription when
      * given. Everything is checked before anything is written; the key is

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

@@ -1,8 +1,3 @@
-/** `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

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

@@ -4,7 +4,10 @@
  * which the image copies before `bun install`. Overrides, and not the
  * dependencies themselves, because a packed package names its siblings by
  * version, which the registry has too: only an override sends those
- * transitive dependencies to the tarballs as well.
+ * transitive dependencies to the tarballs as well. Each tarball is named
+ * after its content there: Bun takes a `file:` tarball whose spec didn't
+ * change for the one in its lockfile, so a repack at the same version needs
+ * another name to be installed.
  */
 /** The tarballs' folder inside the app, as the Dockerfile copies it. */
 export declare const LOCAL_PACKS_DIR = ".packs";
@@ -20,8 +23,10 @@ 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;
-/** A local tarball: its file name in the folder, and the package it holds. */
+/** A local tarball: its file name in the folder (`source`), its name in the
+ * app's `.packs/` (`file`), and the package it holds. */
 export type Pack = {
+    source: string;
     file: string;
     name: string;
     version: string;
@@ -33,9 +38,10 @@ export declare function packageOf(tarball: string): Promise<{
     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). */
+ * holds and its name after its content, 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. */
+/** Copies `packs` from `from` into the app's `.packs/` under their content names, in place of whatever was there. */
 export declare function copyPacks(from: string, appDir: string, packs: Pack[]): void;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,8 @@
   "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.38.0",
-    "@mercury-fw/utils": "0.38.0",
+    "@mercury-fw/core": "0.39.0",
+    "@mercury-fw/utils": "0.39.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
@@ -50,10 +50,10 @@
     "@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.38.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/formatter": "0.39.0",
+    "@mercury-fw/plugin-atlassian-admin": "0.2.0",
+    "@mercury-fw/plugin-bitbucket": "0.2.0",
+    "@mercury-fw/plugin-jira": "0.5.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"

package/src/app/commands.ts

@@ -7,9 +7,9 @@
  */
 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 { join, relative, resolve } from "node:path";
+import { appCliCredentials, cliUserId, volumePath, type CliCredentials } from "@mercury-fw/utils";
+import { readServiceAccountKey, setEnvVar } from "./credentials.ts";
 import type { App } from "./find-app.ts";
 import { copyPacks, LOCAL_PACKS_DIR, readPacks, withLocalOverrides, withoutLocalOverrides } from "./local-packages.ts";
 import { findTests, loadTest } from "../e2e/load.ts";
@@ -128,38 +128,43 @@ export function appCommands(app: App, deps: AppDeps) {
       }
       return 0;
     },
-    /** 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 { 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;
-      }
-      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 ${name} folder yet; if it has one, run mfw credentials reset ${name} first.`,
-      );
-      return 0;
+    /** Runs the plugin's declared setup in a one-off container on the user's
+     * terminal (without `-T`, compose attaches a TTY whenever stdin is one),
+     * so the CLI asks what it needs and writes its login straight onto the
+     * credentials volume. */
+    credentialsSetup: async (plugin: string) => {
+      const declared = credentialsOf(app, plugin);
+      const code = await deps.run([...COMPOSE, "run", "--rm", "--no-deps", SERVICE, ...inContainer(declared, declared.setup)], {
+        cwd: app.dir,
+      });
+      if (code === 0 && declared.check !== undefined) deps.print(`Next: mfw credentials check ${declared.package}`);
+      return code;
     },
-    /** Deletes the plugin's CLI folder from the credentials volume once 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 { name, path } = credentialsOf(app, plugin);
-      const answer = await deps.ask(
-        `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() !== name) {
-        deps.print("Not confirmed: nothing deleted.");
+    /** Runs the plugin's declared check in a one-off container. */
+    credentialsCheck: async (plugin: string) => {
+      const declared = credentialsOf(app, plugin);
+      if (declared.check === undefined) throw new Error(`${declared.package} declares no command to check its CLI's login.`);
+      return deps.run([...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, ...inContainer(declared, declared.check)], {
+        cwd: app.dir,
+      });
+    },
+    /** Runs the plugin's declared logout, of the service identity or of the
+     * person whose user key is `user`, once the user types the declared name.
+     * A wrong answer runs nothing. */
+    credentialsReset: async (plugin: string, { user }: { user?: string }) => {
+      const declared = credentialsOf(app, plugin);
+      if (declared.logout === undefined) throw new Error(`${declared.package} declares no command to log its CLI out.`);
+      const who =
+        user === undefined
+          ? `This logs the service identity of ${declared.package}'s CLI out: commands that run as it fail until mfw credentials setup ${declared.package}.`
+          : `This logs ${user} out of ${declared.package}'s CLI: they log in again the next time they need it.`;
+      const answer = await deps.ask(`${who} Type ${declared.name} to confirm: `);
+      if (answer.trim() !== declared.name) {
+        deps.print("Not confirmed: nobody logged out.");
         return 1;
       }
-      return stopped(SERVICE, [[...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, "rm", "-rf", `/home/mercury/${volumePath(path)}`]]);
+      const argv = user === undefined ? declared.logout : [...declared.logout, "--user", cliUserId(user)];
+      return deps.run([...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, ...inContainer(declared, argv)], { cwd: app.dir });
     },
     /** 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
@@ -276,6 +281,35 @@ export function appCommands(app: App, deps: AppDeps) {
   }
 }
 
+/** Links `$2` (the home path) to `$1` (its place on the volume) the way the
+ * core does at startup, never replacing something else at `$2`, then runs the
+ * rest of the arguments. */
+const LINK_THEN_RUN = [
+  'mkdir -p "$1" "$(dirname "$2")" || exit 1',
+  'if [ -L "$2" ] && [ "$(readlink "$2")" = "$1" ]; then :',
+  'elif [ -e "$2" ] || [ -L "$2" ]; then echo "$2 is already there and is not a link to the credentials volume" >&2; exit 1',
+  'else ln -s "$1" "$2" || exit 1; fi',
+  'shift 2',
+  'exec "$@"',
+].join("\n");
+
+/** `argv` as the app's container runs it for `declared`: as it is for a
+ * login under ~/.config, the volume's mount; for one kept elsewhere in the
+ * home, after linking that path to the volume, as the core does at startup,
+ * since a one-off container doesn't start the app. */
+function inContainer(declared: CliCredentials, argv: string[]): string[] {
+  if (volumePath(declared.path) === declared.path) return argv;
+  return [
+    "sh",
+    "-c",
+    LINK_THEN_RUN,
+    "sh",
+    `/home/mercury/${volumePath(declared.path)}`,
+    `/home/mercury/${declared.path}`,
+    ...argv,
+  ];
+}
+
 /** 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. */

package/src/app/credentials.ts

@@ -1,54 +1,9 @@
 /**
- * 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 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`.
+ * What `mfw google-chat set-key` needs: reading a service account key file,
+ * and writing a 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 });
-  }
-}
+import { chmodSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 /** Sets `name=value` in the env file at `file`. Every line that assigns
  * `name` (`export name=` and spaces around `=` included) gives way to one

package/src/app/local-packages.ts

@@ -4,10 +4,14 @@
  * which the image copies before `bun install`. Overrides, and not the
  * dependencies themselves, because a packed package names its siblings by
  * version, which the registry has too: only an override sends those
- * transitive dependencies to the tarballs as well.
+ * transitive dependencies to the tarballs as well. Each tarball is named
+ * after its content there: Bun takes a `file:` tarball whose spec didn't
+ * change for the one in its lockfile, so a repack at the same version needs
+ * another name to be installed.
  */
 
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 /** The tarballs' folder inside the app, as the Dockerfile copies it. */
@@ -38,8 +42,15 @@ export function withoutLocalOverrides(pkg: Manifest): Manifest {
   return Object.keys(own).length > 0 ? { ...rest, overrides: own } : rest;
 }
 
-/** A local tarball: its file name in the folder, and the package it holds. */
-export type Pack = { file: string; name: string; version: string };
+/** A local tarball: its file name in the folder (`source`), its name in the
+ * app's `.packs/` (`file`), and the package it holds. */
+export type Pack = { source: string; file: string; name: string; version: string };
+
+/** `file`'s name with the first 8 hex digits of `tarball`'s sha256 before `.tgz`. */
+function contentName(file: string, tarball: string): string {
+  const hash = createHash("sha256").update(readFileSync(tarball)).digest("hex").slice(0, 8);
+  return `${file.slice(0, -".tgz".length)}-${hash}.tgz`;
+}
 
 /** The package name and version in a `bun pm pack` tarball, read from its
  * `package/package.json`. */
@@ -58,8 +69,9 @@ export async function packageOf(tarball: string): Promise<{ name: string; versio
 }
 
 /** 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). */
+ * holds and its name after its content, 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)) {
@@ -68,13 +80,15 @@ export async function readPacks(from: string, appDir: string): Promise<Pack[]> {
   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))) })));
+  return Promise.all(
+    files.map(async (file) => ({ source: file, file: contentName(file, join(source, file)), ...(await packageOf(join(source, file))) })),
+  );
 }
 
-/** Copies `packs` from `from` into the app's `.packs/`, in place of whatever was there. */
+/** Copies `packs` from `from` into the app's `.packs/` under their content names, 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));
+  for (const { source, file } of packs) cpSync(join(resolve(from), source), join(target, file));
 }

package/src/program.ts

@@ -228,30 +228,35 @@ Examples:
     .command("credentials")
     .summary("the login of a plugin's CLI")
     .description(
-      "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.",
+      "For a tool plugin whose CLI keeps its login in a folder (under ~/.config, or elsewhere in the home), and declares it with the commands that set it up (mercury.cliCredentials in its package.json): the commands run in a one-off container of the app, so the CLI writes its login straight onto the credentials volume, where it stays across redeploys. Every environment (development, production) sets up its own.",
     )
     .helpCommand(false)
     .addHelpText("after", INSIDE_AN_APP);
   credentials
-    .command("set")
-    .summary("packs a CLI's login folder into the env file")
+    .command("setup")
+    .summary("sets up a CLI's login in the app's container")
     .description(
-      "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.",
+      "Runs the setup the plugin declares for its CLI's service identity (the identity Mercury acts as), in a one-off container on your terminal: the CLI asks for what it needs, and its login lands on the credentials volume. People log in on their own later, through Mercury.",
     )
     .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 }))(),
-    );
+    .action(async (plugin: string) => inApp((app) => app.credentialsSetup(plugin))());
+  credentials
+    .command("check")
+    .summary("checks a CLI's login")
+    .description("Runs the check the plugin declares for its CLI's login (its doctor, for the first-party plugins), in a one-off container.")
+    .argument("<plugin>", "the plugin's package or its CLI's folder")
+    .action(async (plugin: string) => inApp((app) => app.credentialsCheck(plugin))());
   credentials
     .command("reset")
-    .summary("clears a CLI's folder from the volume")
+    .summary("logs an identity out of a CLI")
     .description(
-      "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.",
+      "Runs the logout the plugin declares for its CLI, after you type the name it's declared by: of the service identity, which then needs mfw credentials setup again, or with --user of one person, who logs in again through Mercury the next time they need it. Local only: the tokens aren't revoked at the service.",
     )
     .argument("<plugin>", "the plugin's package or its CLI's folder")
-    .action(async (plugin: string) => inApp((app) => app.credentialsReset(plugin))());
+    .option("--user <key>", "the person to log out, by their user key (<provider>:<id>, e.g. oidc:312345678901234567)")
+    .action(async (plugin: string, opts: { user?: string }) =>
+      inApp((app) => app.credentialsReset(plugin, opts.user === undefined ? {} : { user: opts.user }))(),
+    );
 
   const googleChat = program
     .command("google-chat")

package/src/render.ts

@@ -371,18 +371,19 @@ The HTTP channel listens on \`http://<host>:4100\`, the port in \`HTTP_SURFACE_P
 const CREDENTIALS_SECTION = `
 ## CLI credentials
 
-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:
+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, the plugin declares that folder and the commands that set it up (\`mercury.cliCredentials\` in its \`package.json\`: a folder under \`~/.config\`, or a path anywhere under the home), and the login is set up inside the app's container, on your terminal:
 
 \`\`\`bash
-mfw credentials set <plugin>
+mfw credentials setup <plugin>
+mfw credentials check <plugin>
 \`\`\`
 
-\`<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.
+\`<plugin>\` is the plugin's package or its CLI's folder; a name the app doesn't have lists the ones it has. \`setup\` runs the CLI's own setup in a one-off container, so it asks you for what it needs and writes the login straight 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). What the CLI writes back afterwards, like a refreshed token, stays on the volume across redeploys. Nothing goes in \`.env\`, and nothing is carried from one machine to another: every environment sets up its own, development with its credentials, production with its own.
 
-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:
+To log an identity out, the one Mercury runs as or, with \`--user\`, one person:
 
 \`\`\`bash
-mfw credentials reset <plugin>
+mfw credentials reset <plugin> [--user <key>]
 \`\`\`
 
 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.