@mercury-fw/cli 0.38.1 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @mercury-fw/cli
 
+## 0.40.0
+
+### Minor Changes
+
+- 0739f77: A plugin acts as the person Mercury is talking to, who logs in to the service through Mercury.
+
+  - Plugin contract version 4: a plugin declares `actsAs: "person" | "mercury"`, and one acting as the person contributes a `login`; its tools get the turn's `person` and `requireLogin` in their context.
+  - A person is offered only the plugins acting as the person: their prompt fragments, skills and tools. A plugin acting as Mercury, or declaring nothing, is offered on the terminal only until people can be allowed to make Mercury act as itself; the startup log names it.
+  - `createCliTool` adds `--user` with the person's id to every command, staged confirmations included, and when the CLI exits with code 3 (not logged in) returns their login instead. `createCliPersonLogin` builds a plugin's `login` on a CLI's two-step remote login. A failed `runCli` carries `exitCode`.
+  - Channel contract version 4: channels get `logins` (`accept` a callback URL, `complete` a login) and `detectLoginRequired`.
+  - The HTTP channel, with `HTTP_SURFACE_PUBLIC_URL` set, streams a `login` event with the link to open and takes the person back at `GET /login/callback`, public and protected by the single-use state.
+  - `mercury.cliCredentials` can declare `userSetup`, run by `mfw credentials setup <plugin> --user-app`: the app people log in through, set up without logging anyone in.
+  - plugin-jira and plugin-bitbucket act as the person, on CLIs 2.3.0: set up their people's app with `--user-app` and register `<HTTP_SURFACE_PUBLIC_URL>/login/callback` on it. Jira's skill now says `currentUser()` is the person.
+  - plugin-atlassian-admin acts as Mercury, on CLI 0.2.0, whose `init` asks for the key without echoing it: until permissions exist it's available on the terminal only.
+  - A third-party plugin needs `apiVersion: 4` to load, and `actsAs: "person"` with a `login` to be offered to people.
+
+### Patch Changes
+
+- Updated dependencies [0739f77]
+  - @mercury-fw/core@0.40.0
+  - @mercury-fw/utils@0.40.0
+
+## 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

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>]`

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

@@ -56,17 +56,21 @@ 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 (with `userApp`, of the app people log
+     * in through) 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, { userApp }?: {
+        userApp?: boolean;
+    }) => 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.38.1",
+  "version": "0.40.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,19 +41,19 @@
   "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.1",
-    "@mercury-fw/utils": "0.38.1",
+    "@mercury-fw/core": "0.40.0",
+    "@mercury-fw/utils": "0.40.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-google-chat": "0.3.0",
-    "@mercury-fw/channel-http": "0.4.0",
+    "@mercury-fw/channel-google-chat": "0.4.0",
+    "@mercury-fw/channel-http": "0.5.0",
     "@mercury-fw/auth-oidc": "0.1.0",
     "@mercury-fw/auth-static": "0.1.0",
-    "@mercury-fw/formatter": "0.38.1",
-    "@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.40.0",
+    "@mercury-fw/plugin-atlassian-admin": "0.3.0",
+    "@mercury-fw/plugin-bitbucket": "0.3.0",
+    "@mercury-fw/plugin-jira": "0.6.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,45 @@ 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 (with `userApp`, of the app people log
+     * in through) 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, { userApp = false }: { userApp?: boolean } = {}) => {
+      const declared = credentialsOf(app, plugin);
+      const setup = userApp ? declared.userSetup : declared.setup;
+      if (setup === undefined) throw new Error(`${declared.package} declares no setup for an app people log in through: it doesn't act as the person.`);
+      const code = await deps.run([...COMPOSE, "run", "--rm", "--no-deps", SERVICE, ...inContainer(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 +283,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/catalog.ts

@@ -58,6 +58,7 @@ export const CATALOG: CatalogEntry[] = [
     env: [
       { name: "HTTP_SURFACE_PORT", comment: "Port of the HTTP surface", value: "4100" },
       { name: "HTTP_SURFACE_CORS_ORIGIN", comment: "Origin allowed to call the HTTP surface from a browser, if any" },
+      { name: "HTTP_SURFACE_PUBLIC_URL", comment: "Address people's browsers reach the HTTP surface at, for logging in to the services plugins act on as them" },
     ],
   },
   {

package/src/program.ts

@@ -228,30 +228,38 @@ 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: for a plugin acting as the person, --user-app sets up the app they log in through.",
     )
     .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 }))(),
+    .option("--user-app", "set up instead the app people log in through, for a plugin acting as the person (logs nobody in)")
+    .action(async (plugin: string, opts: { userApp?: boolean }) =>
+      inApp((app) => app.credentialsSetup(plugin, opts.userApp ? { userApp: true } : {}))(),
     );
+  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.