@mercury-fw/cli 0.25.1 → 0.27.0

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/app/find-app.ts

@@ -0,0 +1,25 @@
+/**
+ * Finds the Mercury app the app commands (`mfw start`, `mfw vault`, …) act
+ * on: the nearest folder, from `from` upwards, holding `mercury.config.ts`.
+ * Its `package.json` name is the app's name (what `mfw reset` asks to type).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export type App = { dir: string; name: string };
+
+/** The app containing `from`; throws when there's none, or when its manifest has no name. */
+export function findApp(from: string): App {
+  const start = resolve(from);
+  for (let dir = start; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "mercury.config.ts"))) {
+      const manifest = join(dir, "package.json");
+      const name = existsSync(manifest) ? (JSON.parse(readFileSync(manifest, "utf-8")) as { name?: unknown }).name : undefined;
+      if (typeof name !== "string" || name === "") throw new Error(`${manifest} has no name`);
+      return { dir, name };
+    }
+    if (dirname(dir) === dir) {
+      throw new Error(`Not inside a Mercury app: no mercury.config.ts in ${start} or any folder above it`);
+    }
+  }
+}

package/src/args.ts

@@ -1,10 +1,10 @@
 /**
- * Parses `mfw create`'s command line: one target folder plus the answers
- * that can be given as flags, either to skip the wizard (`--yes`) or to
- * pre-fill it. No validation of the answers themselves here: `renderApp` owns
- * that, so the wizard and the flags go through the same checks.
+ * `mfw create`'s answers as the command line gives them: the target folder
+ * plus what can be given as flags, either to skip the wizard (`--yes`) or to
+ * pre-fill it. The command line itself is parsed in `program.ts`; no
+ * validation of the answers here: `renderApp` owns that, so the wizard and the
+ * flags go through the same checks.
  */
-import { parseArgs } from "node:util";
 
 /** What the command line says. An answer left out is asked by the wizard, or
  * takes its default with `yes`. */
@@ -18,6 +18,16 @@ export type CreateArgs = {
   yes: boolean;
 };
 
+/** `create`'s options as commander hands them over. */
+export type CreateOptions = {
+  name?: string;
+  assistantName?: string;
+  role?: string;
+  channels?: string;
+  plugins?: string;
+  yes?: boolean;
+};
+
 /** A comma-separated list, trimmed, empty items dropped. */
 const list = (value: string): string[] =>
   value
@@ -25,33 +35,13 @@ const list = (value: string): string[] =>
     .map((s) => s.trim())
     .filter(Boolean);
 
-/** Parses the arguments that follow `create`. Throws on a missing or extra
- * folder and on an unknown flag. */
-export function parseCreateArgs(argv: string[]): CreateArgs {
-  const { values, positionals } = parseArgs({
-    args: argv,
-    allowPositionals: true,
-    strict: true,
-    options: {
-      name: { type: "string" },
-      "assistant-name": { type: "string" },
-      role: { type: "string" },
-      channels: { type: "string" },
-      plugins: { type: "string" },
-      yes: { type: "boolean", short: "y" },
-    },
-  });
-  if (positionals.length === 0) {
-    throw new Error("Missing the folder to create the app in");
-  }
-  if (positionals.length > 1) {
-    throw new Error(`Expected one folder, got ${positionals.length}: ${positionals.join(" ")}`);
-  }
-  const args: CreateArgs = { dir: positionals[0] as string, yes: values.yes ?? false };
-  if (values.name !== undefined) args.name = values.name;
-  if (values["assistant-name"] !== undefined) args.assistantName = values["assistant-name"];
-  if (values.role !== undefined) args.role = values.role;
-  if (values.channels !== undefined) args.channels = list(values.channels);
-  if (values.plugins !== undefined) args.plugins = list(values.plugins);
+/** The answers in `folder` and `opts`, with only what was actually given. */
+export function toCreateArgs(folder: string, opts: CreateOptions): CreateArgs {
+  const args: CreateArgs = { dir: folder, yes: opts.yes ?? false };
+  if (opts.name !== undefined) args.name = opts.name;
+  if (opts.assistantName !== undefined) args.assistantName = opts.assistantName;
+  if (opts.role !== undefined) args.role = opts.role;
+  if (opts.channels !== undefined) args.channels = list(opts.channels);
+  if (opts.plugins !== undefined) args.plugins = list(opts.plugins);
   return args;
 }

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/main.ts

@@ -1,47 +1,22 @@
 /**
- * The `mfw` command. One subcommand for now, `create <folder>`: writes a
- * new Mercury app from the template, asking what to put in it (or taking the
- * answers from flags with `--yes`). It writes the files; `bun install` in the
- * new app is left to the user.
+ * The `mfw` command. `create <folder>` writes a new Mercury app from the
+ * template, asking what to put in it (or taking the answers from flags with
+ * `--yes`); `bun install` in the new app is left to the user. The other
+ * commands operate an existing app from inside its folder (see
+ * `app/commands.ts`). The command line itself is declared in `program.ts`.
  */
 import { basename, dirname, join, resolve } from "node:path";
-import { parseCreateArgs, type CreateArgs } from "./args.ts";
+import type { CreateArgs } from "./args.ts";
 import { CATALOG } from "./catalog.ts";
 import { kebabCase } from "./naming.ts";
+import { runProgram } from "./program.ts";
 import { renderApp, selectionError } from "./render.ts";
 import { appVersions, registryFrom } from "./versions.ts";
+import { appCommands, terminalDeps, type AppDeps } from "./app/commands.ts";
+import { findApp } from "./app/find-app.ts";
 import { askAnswers, DEFAULT_ASSISTANT_NAME, DEFAULT_ROLE, type Answers } from "./wizard.ts";
 import { targetError, writeApp } from "./write.ts";
 
-const USAGE = `mfw, the Mercury command-line tool.
-
-Usage:
-  mfw create <folder> [options]
-
-mfw create writes a new Mercury app into <folder>, which has to be missing or
-empty (its own name is turned into kebab case). Without options it asks for the
-app name, the assistant's name and role, and which channels and tool plugins
-to include; then it writes mercury.config.ts for that selection, the persona
-(persona/identity.md, persona/tone.md), the service and REPL entrypoints, a
-Dockerfile, a compose file with Qdrant, and an env example listing every
-variable the app reads. Nothing is installed: run bun install in the new app.
-
-Options:
-  --name <name>              app name, as in package.json (default: the folder's name)
-  --assistant-name <name>    the assistant's name (default: ${DEFAULT_ASSISTANT_NAME})
-  --role <text>              completes "You are <name>, …" (default: ${DEFAULT_ROLE})
-  --channels <ids>           comma-separated: ${CATALOG.filter((e) => e.kind === "channel").map((e) => e.id).join(", ")}
-  --plugins <ids>            comma-separated: ${CATALOG.filter((e) => e.kind === "tool").map((e) => e.id).join(", ")}
-  -y, --yes                  don't ask: use the flags and the defaults
-
-Examples:
-  mfw create my-agent
-  mfw create my-agent --assistant-name Hermes --channels http --plugins jira --yes
-
-The framework packages get this CLI's version; each chosen plugin or channel
-its latest on the registry (https://registry.npmjs.org, or MFW_REGISTRY).
-`;
-
 /** The answers taken from the flags alone, defaults for the rest. */
 function answersFromFlags(args: CreateArgs, defaultName: string): Answers {
   return {
@@ -54,8 +29,7 @@ function answersFromFlags(args: CreateArgs, defaultName: string): Answers {
 }
 
 /** `mfw create`: returns the exit code. */
-async function create(argv: string[]): Promise<number> {
-  const args = parseCreateArgs(argv);
+async function create(args: CreateArgs): Promise<number> {
   // The folder is created in kebab case, only its own name: the parent path is
   // taken as typed. Its name is also the app name's default.
   const typed = resolve(args.dir);
@@ -85,35 +59,20 @@ Next:
   cd ${dir}
   bun install
   cp .env.example .env    # then fill it in
-  docker compose up --build`);
+  bunx mfw start`);
   return 0;
 }
 
 /** Runs `mfw` with `argv` (the arguments after the command name) and returns
  * the exit code, printing to stdout/stderr. `bin.ts` and `create-mercury-agent`
- * both call it. */
-export async function main(argv: string[]): Promise<number> {
-  const [command, ...rest] = argv;
-  if (command === "--help" || command === "-h") {
-    console.log(USAGE);
-    return 0;
-  }
-  if (command === undefined) {
-    console.error(USAGE);
-    return 1;
-  }
-  if (command === "create" && rest.some((a) => a === "--help" || a === "-h")) {
-    console.log(USAGE);
-    return 0;
-  }
-  if (command !== "create") {
-    console.error(`Unknown command "${command}"\n\n${USAGE}`);
-    return 1;
-  }
-  try {
-    return await create(rest);
-  } catch (err) {
-    console.error(err instanceof Error ? err.message : String(err));
-    return 1;
-  }
+ * both call it; the app commands look for the app from `cwd` and run docker
+ * through `deps`. */
+export async function main(
+  argv: string[],
+  { cwd = process.cwd(), deps }: { cwd?: string; deps?: AppDeps } = {},
+): Promise<number> {
+  return runProgram(argv, {
+    create,
+    app: () => appCommands(findApp(cwd), deps ?? terminalDeps()),
+  });
 }

package/src/program.ts

@@ -0,0 +1,259 @@
+/**
+ * The `mfw` command line, declared with commander: every command, its
+ * arguments and options, and the help for each level (`mfw --help`,
+ * `mfw vault --help`, `mfw vault write-curated --help`). Parsing and
+ * validation happen here, before anything runs; what a command does lives in
+ * `create` (passed in) and `app/commands.ts`.
+ */
+import { Argument, Command, CommanderError, InvalidArgumentError, Option, type OutputConfiguration } from "commander";
+import { toCreateArgs, type CreateArgs, type CreateOptions } from "./args.ts";
+import { appCommands, RESET_TARGETS, type ResetTarget } from "./app/commands.ts";
+import { CATALOG } from "./catalog.ts";
+import { cliVersion } from "./versions.ts";
+import { DEFAULT_ASSISTANT_NAME, DEFAULT_ROLE } from "./wizard.ts";
+
+/** The commands that operate an app, bound to it. */
+export type AppCommands = ReturnType<typeof appCommands>;
+
+export type ProgramHandlers = {
+  /** `mfw create`; returns the exit code. */
+  create: (args: CreateArgs) => Promise<number>;
+  /** The app the app commands act on; throws outside one. */
+  app: () => AppCommands;
+};
+
+/** `--limit`'s value: a positive whole number. */
+function positiveInt(value: string): string {
+  if (!/^\d+$/.test(value) || Number(value) < 1) {
+    throw new InvalidArgumentError(`--limit takes a positive whole number (got "${value}").`);
+  }
+  return value;
+}
+
+/** The help's closing paragraph for the commands that run inside an app. */
+const INSIDE_AN_APP = "\nRun it from the app's folder or any folder under it (the one holding mercury.config.ts).";
+
+/** Builds the `mfw` program; every action stores its exit code in `result`. */
+function buildProgram(handlers: ProgramHandlers, result: { code: number }): Command {
+  const program = new Command("mfw")
+    .description("The Mercury command-line tool: creates an app, then runs it.")
+    .version(cliVersion(), "-V, --version")
+    .showSuggestionAfterError()
+    .helpCommand(false);
+  const inApp = (run: (app: AppCommands) => Promise<number>) => async () => {
+    result.code = await run(handlers.app());
+  };
+
+  program
+    .command("create")
+    .summary("writes a new Mercury app")
+    .description(
+      "Writes a new Mercury app into <folder>, which has to be missing or empty (its own name is turned into kebab case). Without options it asks for the app name, the assistant's name and role, and which channels and tool plugins to include; then it writes mercury.config.ts for that selection, the persona (persona/identity.md, persona/tone.md), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the app reads. Nothing is installed: run bun install in the new app.",
+    )
+    .argument("<folder>", "where to write the app")
+    .option("--name <name>", "app name, as in package.json (default: the folder's name)")
+    .option("--assistant-name <name>", `the assistant's name (default: ${DEFAULT_ASSISTANT_NAME})`)
+    .option("--role <text>", `completes "You are <name>, …" (default: ${DEFAULT_ROLE})`)
+    .option(
+      "--channels <ids>",
+      `comma-separated: ${CATALOG.filter((e) => e.kind === "channel").map((e) => e.id).join(", ")}`,
+    )
+    .option("--plugins <ids>", `comma-separated: ${CATALOG.filter((e) => e.kind === "tool").map((e) => e.id).join(", ")}`)
+    .option("-y, --yes", "don't ask: use the flags and the defaults")
+    .addHelpText(
+      "after",
+      `
+The framework packages get this CLI's version; each chosen plugin or channel
+its latest on the registry (https://registry.npmjs.org, or MFW_REGISTRY).
+
+Examples:
+  mfw create my-agent
+  mfw create my-agent --assistant-name Hermes --channels http --plugins jira --yes`,
+    )
+    .action(async (folder: string, opts: CreateOptions) => {
+      result.code = await handlers.create(toCreateArgs(folder, opts));
+    });
+
+  // commander reads --no-cache as "cache: false"; the commands take noCache.
+  const cacheOff = (opts: { cache: boolean }) => ({ noCache: !opts.cache });
+
+  program
+    .command("start")
+    .summary("builds and starts the app")
+    .description(
+      "Builds the app's image and starts the app and Qdrant in the background. Only what changed is rebuilt, and only what changed (image, .env, compose file) is recreated.",
+    )
+    .addOption(new Option("--no-cache", "rebuild everything from scratch"))
+    .addHelpText("after", INSIDE_AN_APP)
+    .action(async (opts: { cache: boolean }) => inApp((app) => app.start(cacheOff(opts)))());
+
+  program
+    .command("stop")
+    .summary("stops the app")
+    .description("Stops the app and Qdrant and removes their containers. The volumes (memory, wiki, CLI credentials) stay.")
+    .addHelpText("after", INSIDE_AN_APP)
+    .action(inApp((app) => app.stop()));
+
+  program
+    .command("restart")
+    .summary("rebuilds and restarts the app")
+    .description("Like mfw start, but recreates the containers even when nothing changed: a clean restart.")
+    .addOption(new Option("--no-cache", "rebuild everything from scratch"))
+    .addHelpText("after", INSIDE_AN_APP)
+    .action(async (opts: { cache: boolean }) => inApp((app) => app.restart(cacheOff(opts)))());
+
+  program
+    .command("logs")
+    .summary("follows the logs")
+    .description("Follows the logs of every service, or only of [service].")
+    .argument("[service]", "mercury or qdrant")
+    .addHelpText("after", INSIDE_AN_APP)
+    .action(async (service: string | undefined) => inApp((app) => app.logs(service))());
+
+  program
+    .command("repl")
+    .summary("opens the dev REPL")
+    .description("Opens the dev REPL, a terminal conversation with the assistant, in a one-off container. A running app isn't touched.")
+    .addHelpText("after", INSIDE_AN_APP)
+    .action(inApp((app) => app.repl()));
+
+  program
+    .command("shell")
+    .summary("opens a shell in the app's container")
+    .description("Opens a shell in the app's container: the running one if the app is up, otherwise a one-off container.")
+    .addHelpText("after", INSIDE_AN_APP)
+    .action(inApp((app) => app.shell()));
+
+  const vault = program
+    .command("vault")
+    .summary("wiki vault maintenance")
+    .description(
+      "Maintains the wiki vault, in a one-off container on the vault's volume. Paths are vault-relative, as mfw vault list prints them (curated/…, raw/…).",
+    )
+    .helpCommand(false)
+    .addHelpText("after", INSIDE_AN_APP);
+  vault
+    .command("list")
+    .summary("every note")
+    .description("Lists every note.")
+    .action(async () => inApp((app) => app.vault(["list"]))());
+  vault
+    .command("read")
+    .summary("a note")
+    .description("Prints a note.")
+    .argument("<path>", "the note, vault-relative")
+    .action(async (path: string) => inApp((app) => app.vault(["read", path]))());
+  vault
+    .command("grep")
+    .summary("lines matching a pattern")
+    .description("Prints every line matching <pattern> (a regular expression) as path:line:text.")
+    .argument("<pattern>", "a regular expression; after --, one starting with - too")
+    .action(async (pattern: string) => inApp((app) => app.vault(["grep", pattern]))());
+  vault
+    .command("write-curated")
+    .summary("writes a curated note from stdin")
+    .description("Writes a curated note, the body read from stdin.")
+    .argument("<path>", "curated/…, vault-relative")
+    .option("--author <name>", "who wrote it")
+    .addHelpText("after", "\nExample:\n  cat note.md | mfw vault write-curated curated/standards/new-note.md --author luca")
+    .action(async (path: string, opts: { author?: string }) =>
+      inApp((app) => app.vault(["write-curated", path, ...(opts.author === undefined ? [] : ["--author", opts.author])]))(),
+    );
+  vault
+    .command("write-raw")
+    .summary("writes raw material from stdin")
+    .description("Writes raw material for the nightly review to triage, the body read from stdin.")
+    .argument("<path>", "raw/…, vault-relative")
+    .action(async (path: string) => inApp((app) => app.vault(["write-raw", path]))());
+
+  const memory = program
+    .command("memory")
+    .summary("reads Layer-3 memory")
+    .description("Reads Layer-3 memory on Qdrant, in a one-off container. Read-only.")
+    .helpCommand(false)
+    .addHelpText("after", INSIDE_AN_APP);
+  memory
+    .command("list")
+    .summary("the collections and their points")
+    .description("Lists the collections and how many points each holds.")
+    .action(async () => inApp((app) => app.memory(["list"]))());
+  memory
+    .command("read")
+    .summary("a collection's points")
+    .description(
+      "Prints a collection's points, each as its id and one line per payload field: newest first where the collection has a timestamp index, in Qdrant's own order otherwise.",
+    )
+    .argument("<collection>", "as mfw memory list prints it")
+    .option("--limit <n>", "how many points (default: 20)", positiveInt)
+    .action(async (collection: string, opts: { limit?: string }) =>
+      inApp((app) => app.memory(["read", collection, ...(opts.limit === undefined ? [] : ["--limit", opts.limit])]))(),
+    );
+
+  program
+    .command("reset")
+    .summary("deletes memory or the wiki, after confirmation")
+    .description(
+      "Deletes for good what the assistant remembers: memory is every Qdrant collection, wiki the whole vault. It asks you to type the app's name first (anything else deletes nothing), then brings the service back up empty.",
+    )
+    .addArgument(new Argument("<target>", "what to delete").choices(Object.keys(RESET_TARGETS)))
+    .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;
+}
+
+/** Runs `mfw` on `argv` (the arguments after the command name) and returns
+ * the exit code. Commander's own messages (help, errors) go to `output`, and
+ * so does the message of an error a command throws. */
+export async function runProgram(argv: string[], handlers: ProgramHandlers, output?: OutputConfiguration): Promise<number> {
+  const result = { code: 0 };
+  const program = buildProgram(handlers, result);
+  const writeErr = output?.writeErr ?? ((s: string) => process.stderr.write(s));
+  const configure = (cmd: Command): void => {
+    cmd.exitOverride();
+    if (output !== undefined) cmd.configureOutput(output);
+    cmd.commands.forEach(configure);
+  };
+  configure(program);
+  if (argv.length === 0) {
+    program.outputHelp({ error: true });
+    return 1;
+  }
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return result.code;
+  } catch (err) {
+    if (err instanceof CommanderError) return err.exitCode;
+    writeErr(`${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+}