@mercury-fw/cli 0.25.1 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @mercury-fw/cli
 
+## 0.27.0
+
+### Minor Changes
+
+- d2a6be5: - A scaffolded app with tool plugins gets a `docker-entrypoint.sh`: at the first start without a CLI's config folder on the credentials volume, it unpacks that CLI's variable from the env file there, then starts the service. What the CLI refreshes afterwards stays on the volume.
+  - The scaffolded env example lists each tool plugin's credentials variable, and the README explains the flow.
+  - `mfw credentials set <plugin>` packs a CLI's config folder (`~/.config/<cli>`, or `--from <dir>`) into its variable in the app's env file, never printing it; `--print` prints the line to paste elsewhere.
+  - `mfw credentials reset <plugin>` clears a CLI's folder from the credentials volume after you type the plugin's name, so a corrected variable is unpacked at the next start.
+
+### Patch Changes
+
+- @mercury-fw/core@0.27.0
+
+## 0.26.0
+
+### Minor Changes
+
+- 8b92abb: - `mfw` operates an app from inside its folder: `start`, `stop` and `restart` (with `--no-cache`), `logs`, `repl`, `shell`, all as `docker compose` calls.
+  - `mfw vault` maintains the wiki vault (`list`, `read`, `grep`, `write-curated`, `write-raw`) in a one-off container.
+  - `mfw memory list` and `mfw memory read <collection>` read the memory on Qdrant, newest first where the collection has a timestamp index.
+  - `mfw reset memory` and `mfw reset wiki` delete a memory volume after you type the app's name, then bring the service back up empty; after a memory reset a running app is restarted, so it sets up its collections again.
+  - The command line is declared with commander: `--help` at every level, a suggestion for a mistyped command, and every argument checked before anything runs.
+  - A scaffolded app lists `@mercury-fw/cli` among its devDependencies, at the framework's version, and its README runs it through `bunx mfw`.
+  - A scaffolded app's `@types/bun` and `typescript` use caret ranges instead of exact versions.
+  - The core ships a read-only memory CLI (`src/memory/memory-cli.ts`) next to the vault one, which is what `mfw memory` runs.
+  - The vault CLI says so when asked to read a note that doesn't exist, instead of printing a stack trace.
+
+### Patch Changes
+
+- Updated dependencies [8b92abb]
+  - @mercury-fw/core@0.26.0
+
 ## 0.25.1
 
 ### Patch Changes

package/README.md

@@ -1,18 +1,39 @@
 # @mercury-fw/cli
 
-`mfw`, the command-line tool of [Mercury](https://github.com/lucabro81/mercury-fw). For now it has one command, `mfw create`, which scaffolds a new app; operating an app (starting it, the REPL, memory maintenance) moves here next.
+`mfw`, the command-line tool of [Mercury](https://github.com/lucabro81/mercury-fw): it creates an app, then runs it. Every command except `create` works from inside an app, meaning its folder or any folder under it (the one holding `mercury.config.ts`), and wraps the `docker compose` calls that app needs, so you don't have to remember them; each section below says which calls those are. New commands get documented here as they're added.
 
-```bash
-bunx @mercury-fw/cli create my-agent
-```
+## Table of contents
+
+- [Getting it](#getting-it)
+- [Usage](#usage)
+  - [`mfw create <folder>`](#mfw-create-folder)
+  - [`mfw start [--no-cache]`](#mfw-start---no-cache)
+  - [`mfw stop`](#mfw-stop)
+  - [`mfw restart [--no-cache]`](#mfw-restart---no-cache)
+  - [`mfw logs [service]`](#mfw-logs-service)
+  - [`mfw repl`](#mfw-repl)
+  - [`mfw shell`](#mfw-shell)
+  - [`mfw vault <command>`](#mfw-vault-command)
+  - [`mfw memory list`](#mfw-memory-list)
+  - [`mfw memory read <collection> [--limit N]`](#mfw-memory-read-collection---limit-n)
+  - [`mfw reset <memory|wiki>`](#mfw-reset-memorywiki)
+  - [`mfw credentials set <plugin> [--from <dir>] [--print]`](#mfw-credentials-set-plugin---from-dir---print)
+  - [`mfw credentials reset <plugin>`](#mfw-credentials-reset-plugin)
+- [Help](#help)
 
-or, the same thing under the `create` convention:
+## Getting it
+
+A new app comes from `bun create mercury-agent`, which is `mfw create` under the `create` convention:
 
 ```bash
 bun create mercury-agent my-agent
 ```
 
-## `mfw create <folder>`
+The app it writes lists `@mercury-fw/cli` among its devDependencies, at the same version as the framework it depends on, so after `bun install` in the app every other command runs as `bunx mfw <command>`, with no global install.
+
+## Usage
+
+### `mfw create <folder>`
 
 Writes a new Mercury app into `<folder>`, which has to be missing or empty; the folder's own name is turned into kebab case (`My Agent` becomes `my-agent`, the path above it stays as typed). Without flags it asks:
 
@@ -32,9 +53,143 @@ It writes the `mercury.config.ts` for that selection, the persona, the service a
 | `-y`, `--yes` | No questions: the flags, and the defaults for the rest. |
 
 ```bash
-mfw create my-agent --assistant-name Hermes --channels http --plugins jira --yes
+bun create mercury-agent my-agent
+bunx @mercury-fw/cli create my-agent --assistant-name Hermes --channels http --plugins jira --yes
 ```
 
 The framework packages get the CLI's own version (they're released together); each chosen plugin or channel gets its latest version on the registry, `https://registry.npmjs.org` unless `MFW_REGISTRY` names another.
 
+### `mfw start [--no-cache]`
+
+Builds the app's image and starts the app and Qdrant in the background (`docker compose up -d --build`). Docker's cache means only what changed gets rebuilt, and a running container is recreated only if its image or configuration changed, so it's also the command to run after changing a dependency, the Dockerfile or `.env`. `--no-cache` rebuilds everything from scratch (`docker compose build --no-cache`, then `up -d`), which is what refetches a tool plugin's CLI binary when a new release is out: a normal build keeps the cached one.
+
+```bash
+bunx mfw start
+bunx mfw start --no-cache
+```
+
+### `mfw stop`
+
+Stops the app and Qdrant and removes their containers (`docker compose down`). The volumes stay, so memory, the wiki and the CLI credentials are all there on the next start.
+
+```bash
+bunx mfw stop
+```
+
+### `mfw restart [--no-cache]`
+
+Like `start`, but recreates the containers even when nothing changed (`--force-recreate`): a clean restart, for a process that got stuck. A changed `.env` doesn't need it, `start` already recreates what the change touches. `--no-cache` as in `start`.
+
+```bash
+bunx mfw restart
+bunx mfw restart --no-cache
+```
+
+### `mfw logs [service]`
+
+Follows the logs of every service, interleaved, or only of the one you name, `mercury` or `qdrant` (`docker compose logs -f`). One service at most. `Ctrl+C` stops following, the app keeps running.
+
+```bash
+bunx mfw logs
+bunx mfw logs mercury
+```
+
+### `mfw repl`
+
+Opens the dev REPL, a conversation with the assistant in the terminal, in a one-off container (`docker compose run --rm mercury bun run repl`). The REPL has no user identity by design, so what you try there never lands in anyone's memory; ending it (`Ctrl+D`) removes the one-off container and leaves a running app alone.
+
+```bash
+bunx mfw repl
+```
+
+### `mfw shell`
+
+Opens a shell in the app's container: the running one if the app is up (`docker compose exec mercury bash`), a one-off one otherwise (`docker compose run --rm mercury bash`). The tool plugins' CLIs are on `PATH` there with their credentials, so it's where you check that a command works before blaming the model.
+
+```bash
+bunx mfw shell
+```
+
+### `mfw vault <command>`
+
+Maintains the wiki vault, which lives on a Docker volume and not in the app's folder, so every command runs in a one-off container on that volume (`docker compose run --rm -T mercury bun …`). Paths are vault-relative, the way `list` prints them, `curated/` or `raw/` included.
+
+| Command | |
+|---|---|
+| `list` | Every note. |
+| `read <path>` | One note (a path that isn't one says so, exit 1). |
+| `grep <pattern>` | Every line matching `<pattern>`, a regular expression, as `path:line:text`. A pattern starting with `-` goes after `--` (`mfw vault grep -- -h`). |
+| `write-curated <path> [--author NAME]` | Writes a curated note, the body read from stdin. |
+| `write-raw <path>` | Writes raw material for the nightly review to triage, the body read from stdin. |
+
+```bash
+bunx mfw vault list
+bunx mfw vault read curated/standards/jira-fields.md
+bunx mfw vault grep "story points"
+cat note.md | bunx mfw vault write-curated curated/standards/new-note.md --author luca
+```
+
+There's no command writing inferred notes on purpose: those are the agent's own, written only by its consolidation.
+
+### `mfw memory list`
+
+Lists the collections of the memory on Qdrant with how many points each holds, in a one-off container that reaches Qdrant the way the app does. Read-only.
+
+```bash
+bunx mfw memory list
+```
+
+```
+episodic_memory  25 points
+semantic_facts  20 points
+tool_corrections  37 points
+verbatim_archive  0 points
+```
+
+### `mfw memory read <collection> [--limit N]`
+
+Prints a collection's points, each as its id followed by one line per payload field. Newest first where the collection has a timestamp index (episodic memory and the verbatim archive do); in Qdrant's own order otherwise, and it says so. `--limit` defaults to 20. Read-only.
+
+```bash
+bunx mfw memory read episodic_memory
+bunx mfw memory read semantic_facts --limit 5
+```
+
+### `mfw reset <memory|wiki>`
+
+Deletes for good what the assistant remembers: `memory` is every collection on Qdrant, `wiki` the whole vault. It reads the volume's real name from the compose file, tells you which one is about to go, and asks you to type the app's name (the `name` in `package.json`); anything else, an empty answer, a `y` or closing the input included, deletes nothing and exits 1. Once confirmed it stops the service using the volume, removes its container and the volume, and starts the service again on an empty one (`docker compose stop`, `rm -f`, `docker volume rm`, `up -d`). After `memory`, a running app is restarted too (`docker compose restart mercury`), since it sets up its collections only when it starts.
+
+If a step fails once the service is stopped (the volume still in use by a one-off container, say), it stops there and says the service is down: `bunx mfw start` brings it back.
+
+```bash
+bunx mfw reset memory
+bunx mfw reset wiki
+```
+
+Useful for clearing out test data; the other layer isn't touched.
+
+### `mfw credentials set <plugin> [--from <dir>] [--print]`
+
+Hands a tool plugin's CLI its login. Every such CLI keeps it in a config folder of its own (`jira-cli`, `bitbucket-cli`, `atlassian-admin-cli`); log in with the CLI on your machine first, then this packs that folder (`~/.config/<cli>`, or `--from` when it lives elsewhere) into a base64 tar.gz and writes it as the plugin's variable in the app's `.env` (`JIRA_CLI_CONFIG_TAR_B64` and so on), replacing an older value and leaving the other lines alone. The value is never printed; `--print` prints the whole line instead and leaves `.env` alone, for pasting it into another host's.
+
+When the container starts, the app's `docker-entrypoint.sh` unpacks the variable onto the credentials volume, but only if that CLI's folder isn't there yet: what the CLI writes back while running, like a refreshed token, stays on the volume across redeploys, and an older value in `.env` never overwrites it. `<plugin>` has to be a tool plugin the app depends on.
+
+```bash
+bunx mfw credentials set jira
+bunx mfw credentials set bitbucket --from ~/work/bitbucket-login
+bunx mfw credentials set jira --print
+```
+
+### `mfw credentials reset <plugin>`
+
+Deletes the plugin's CLI folder from the credentials volume, so the variable in `.env` is unpacked again at the next start: what to run after correcting a variable whose folder is already on the volume, since the entrypoint never touches an existing folder. It asks you to type the plugin's name first, because a token the CLI refreshed on the volume goes too (and with a CLI that rotates its refresh token, the one in `.env` may no longer work). Once confirmed it stops the app, removes the folder in a one-off container of the app's own image, and starts the app again (`docker compose stop mercury`, `run --rm --no-deps -T mercury rm -rf …`, `up -d mercury`).
+
+```bash
+bunx mfw credentials reset jira
+```
+
+## Help
+
+`mfw --help` lists every command, and `--help` after any of them describes it, down to the subcommands (`mfw vault write-curated --help`). A mistyped command gets a suggestion (`mfw strat` → "Did you mean start?"). Every argument is checked before anything runs: a wrong one exits 1 saying why, with no container started.
+
 MIT

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

@@ -0,0 +1,76 @@
+import type { App } from "./find-app.ts";
+export type AppDeps = {
+    /** Runs `argv` in `cwd` on the user's terminal (stdin, stdout, stderr) and returns its exit code. */
+    run: (argv: string[], opts: {
+        cwd: string;
+    }) => Promise<number>;
+    /** Runs `argv` in `cwd` and returns its stdout; throws when it fails. */
+    capture: (argv: string[], opts: {
+        cwd: string;
+    }) => Promise<string>;
+    /** Asks the user `question` and returns the answer as typed. */
+    ask: (question: string) => Promise<string>;
+    /** Tells the user something. */
+    print: (line: string) => void;
+    /** The user's home folder, where a CLI keeps its config (`~/.config/<cli>`). */
+    home: string;
+};
+/** The core's maintenance CLIs, from the container's working directory (the
+ * app's folder, where node_modules/@mercury-fw/core is). A path and not a bin:
+ * a monorepo image installs before copying the sources, and Bun doesn't link a
+ * bin whose file isn't there yet. The core moves in lockstep with this CLI. */
+export declare const VAULT_CLI = "node_modules/@mercury-fw/core/src/wiki/vault-cli.ts";
+export declare const MEMORY_CLI = "node_modules/@mercury-fw/core/src/memory/memory-cli.ts";
+/** What `mfw reset` can wipe: the compose service using the volume, the
+ * volume's key in the compose file, and how to say what's lost. */
+export declare const RESET_TARGETS: {
+    readonly memory: {
+        readonly service: "qdrant";
+        readonly volume: "qdrant-data";
+        readonly what: "Layer-3 memory (every Qdrant collection)";
+    };
+    readonly wiki: {
+        readonly service: "mercury";
+        readonly volume: "wiki-vault";
+        readonly what: "the wiki vault (every note)";
+    };
+};
+export type ResetTarget = keyof typeof RESET_TARGETS;
+/** The commands bound to `app`, each returning its exit code. */
+export declare function appCommands(app: App, deps: AppDeps): {
+    start: ({ noCache }: {
+        noCache: boolean;
+    }) => Promise<number>;
+    restart: ({ noCache }: {
+        noCache: boolean;
+    }) => Promise<number>;
+    stop: () => Promise<number>;
+    logs: (service?: string) => Promise<number>;
+    repl: () => Promise<number>;
+    shell: () => Promise<number>;
+    /** `args` is the vault CLI's own command line (`list`, `read <path>`, …). */
+    vault: (args: string[]) => Promise<number>;
+    /** `args` is the memory CLI's own command line (`list`, `read <collection>`, …). */
+    memory: (args: string[]) => Promise<number>;
+    /** Deletes `target`'s volume once the user types the app's name, then
+     * brings its service back up on an empty volume. The volume's real name
+     * comes from the compose file, and a wrong answer deletes nothing. */
+    reset: (target: ResetTarget) => Promise<number>;
+    /** Packs the plugin's CLI config folder (`from`, by default
+     * `~/.config/<folder>`) into its credentials variable, written into the
+     * app's env file, or printed with `print`. */
+    credentialsSet: (plugin: string, { from, print }: {
+        from?: string;
+        print: boolean;
+    }) => Promise<number>;
+    /** Deletes the plugin's CLI folder from the credentials volume once the
+     * user types the plugin's name, so its variable is unpacked again at the
+     * next start. A wrong answer deletes nothing. */
+    credentialsReset: (plugin: string) => Promise<number>;
+};
+/** The real deps: docker on the user's terminal, questions on `input`
+ * (stdin by default). */
+export declare function terminalDeps({ input, output, }?: {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}): AppDeps;

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

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

package/dist/src/app/find-app.d.ts

@@ -0,0 +1,6 @@
+export type App = {
+    dir: string;
+    name: string;
+};
+/** The app containing `from`; throws when there's none, or when its manifest has no name. */
+export declare function findApp(from: string): App;

package/dist/src/args.d.ts

@@ -1,3 +1,10 @@
+/**
+ * `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.
+ */
 /** What the command line says. An answer left out is asked by the wizard, or
  * takes its default with `yes`. */
 export type CreateArgs = {
@@ -9,6 +16,14 @@ export type CreateArgs = {
     plugins?: string[];
     yes: boolean;
 };
-/** Parses the arguments that follow `create`. Throws on a missing or extra
- * folder and on an unknown flag. */
-export declare function parseCreateArgs(argv: string[]): CreateArgs;
+/** `create`'s options as commander hands them over. */
+export type CreateOptions = {
+    name?: string;
+    assistantName?: string;
+    role?: string;
+    channels?: string;
+    plugins?: string;
+    yes?: boolean;
+};
+/** The answers in `folder` and `opts`, with only what was actually given. */
+export declare function toCreateArgs(folder: string, opts: CreateOptions): CreateArgs;

package/dist/src/catalog.d.ts

@@ -21,6 +21,15 @@ export type CatalogEntry = {
     exportName: string;
     env: EnvVar[];
     formatter?: FormatterExample;
+    credentials?: CliCredentials;
+};
+/** Where a tool plugin's CLI keeps its login: `folder` under the CLI user's
+ * `~/.config`, and the env variable that carries that folder into the
+ * container (a base64 tar.gz with the folder at its root), materialized on
+ * the credentials volume the first time the folder isn't there. */
+export type CliCredentials = {
+    folder: string;
+    variable: string;
 };
 /** Starting formatter rules for a plugin that hands the user lists: without a
  * rule a kind of list isn't shown, so the scaffolded config wraps the plugin

package/dist/src/main.d.ts

@@ -1,4 +1,9 @@
+import { type AppDeps } from "./app/commands.ts";
 /** 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 declare function main(argv: string[]): Promise<number>;
+ * both call it; the app commands look for the app from `cwd` and run docker
+ * through `deps`. */
+export declare function main(argv: string[], { cwd, deps }?: {
+    cwd?: string;
+    deps?: AppDeps;
+}): Promise<number>;

package/dist/src/program.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { type OutputConfiguration } from "commander";
+import { type CreateArgs } from "./args.ts";
+import { appCommands } from "./app/commands.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;
+};
+/** 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 declare function runProgram(argv: string[], handlers: ProgramHandlers, output?: OutputConfiguration): Promise<number>;

package/package.json

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

package/src/app/commands.ts

@@ -0,0 +1,214 @@
+/**
+ * The commands that operate an app (`mfw start`, `mfw vault`, …): each one is
+ * a short sequence of `docker compose` calls run from the app's folder, so the
+ * docker details live here and not in every app. The command line is parsed
+ * and validated before any of this runs (`program.ts`); what runs a command is
+ * injected (`AppDeps`), which is how the tests see the exact calls.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { CATALOG, type CliCredentials } from "../catalog.ts";
+import { packCredentials, setEnvVar } from "./credentials.ts";
+import type { App } from "./find-app.ts";
+
+export type AppDeps = {
+  /** Runs `argv` in `cwd` on the user's terminal (stdin, stdout, stderr) and returns its exit code. */
+  run: (argv: string[], opts: { cwd: string }) => Promise<number>;
+  /** Runs `argv` in `cwd` and returns its stdout; throws when it fails. */
+  capture: (argv: string[], opts: { cwd: string }) => Promise<string>;
+  /** Asks the user `question` and returns the answer as typed. */
+  ask: (question: string) => Promise<string>;
+  /** Tells the user something. */
+  print: (line: string) => void;
+  /** The user's home folder, where a CLI keeps its config (`~/.config/<cli>`). */
+  home: string;
+};
+
+const COMPOSE = ["docker", "compose"];
+
+/** The app's service, the one the image builds. */
+const SERVICE = "mercury";
+
+/** The core's maintenance CLIs, from the container's working directory (the
+ * app's folder, where node_modules/@mercury-fw/core is). A path and not a bin:
+ * a monorepo image installs before copying the sources, and Bun doesn't link a
+ * bin whose file isn't there yet. The core moves in lockstep with this CLI. */
+export const VAULT_CLI = "node_modules/@mercury-fw/core/src/wiki/vault-cli.ts";
+export const MEMORY_CLI = "node_modules/@mercury-fw/core/src/memory/memory-cli.ts";
+
+/** What `mfw reset` can wipe: the compose service using the volume, the
+ * volume's key in the compose file, and how to say what's lost. */
+export const RESET_TARGETS = {
+  memory: { service: "qdrant", volume: "qdrant-data", what: "Layer-3 memory (every Qdrant collection)" },
+  wiki: { service: SERVICE, volume: "wiki-vault", what: "the wiki vault (every note)" },
+} as const;
+export type ResetTarget = keyof typeof RESET_TARGETS;
+
+/** The compose calls that build and start the app; `recreate` restarts containers even when nothing changed. */
+function startCalls(noCache: boolean, recreate: boolean): string[][] {
+  const up = [...COMPOSE, "up", "-d", ...(noCache ? [] : ["--build"]), ...(recreate ? ["--force-recreate"] : [])];
+  return noCache ? [[...COMPOSE, "build", "--no-cache"], up] : [up];
+}
+
+/** The commands bound to `app`, each returning its exit code. */
+export function appCommands(app: App, deps: AppDeps) {
+  /** Runs `calls` in order from the app's folder, stopping at the first that fails; returns its exit code, 0 if none did. */
+  const runAll = async (calls: string[][]): Promise<number> => {
+    for (const argv of calls) {
+      const code = await deps.run(argv, { cwd: app.dir });
+      if (code !== 0) return code;
+    }
+    return 0;
+  };
+  const oneOff = (argv: string[]) => runAll([[...COMPOSE, "run", "--rm", "-T", SERVICE, ...argv]]);
+  /** The compose services running right now. */
+  const running = async (): Promise<string[]> =>
+    (await deps.capture([...COMPOSE, "ps", "--status", "running", "--services"], { cwd: app.dir }))
+      .split("\n")
+      .map((s) => s.trim());
+
+  return {
+    start: ({ noCache }: { noCache: boolean }) => runAll(startCalls(noCache, false)),
+    restart: ({ noCache }: { noCache: boolean }) => runAll(startCalls(noCache, true)),
+    stop: () => runAll([[...COMPOSE, "down"]]),
+    logs: (service?: string) => runAll([[...COMPOSE, "logs", "-f", ...(service === undefined ? [] : [service])]]),
+    repl: () => runAll([[...COMPOSE, "run", "--rm", SERVICE, "bun", "run", "repl"]]),
+    shell: async () => {
+      const shell = (await running()).includes(SERVICE) ? ["exec", SERVICE, "bash"] : ["run", "--rm", SERVICE, "bash"];
+      return runAll([[...COMPOSE, ...shell]]);
+    },
+    /** `args` is the vault CLI's own command line (`list`, `read <path>`, …). */
+    vault: (args: string[]) => oneOff(["bun", VAULT_CLI, ...args]),
+    /** `args` is the memory CLI's own command line (`list`, `read <collection>`, …). */
+    memory: (args: string[]) => oneOff(["bun", MEMORY_CLI, ...args]),
+    /** Deletes `target`'s volume once the user types the app's name, then
+     * 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: async (target: ResetTarget) => {
+      const { service, volume: key, what } = RESET_TARGETS[target];
+      const config = JSON.parse(
+        await deps.capture([...COMPOSE, "config", "--no-interpolate", "--format", "json"], { cwd: app.dir }),
+      ) as { volumes?: Record<string, { name?: string }> };
+      const volume = config.volumes?.[key]?.name;
+      if (volume === undefined) {
+        throw new Error(`The compose file has no "${key}" volume to reset`);
+      }
+      const answer = await deps.ask(`This deletes ${what} for good: volume ${volume}. Type the app's name (${app.name}) to confirm: `);
+      if (answer.trim() !== app.name) {
+        deps.print("Not confirmed: nothing deleted.");
+        return 1;
+      }
+      const code = await stopped(service, [
+        [...COMPOSE, "rm", "-f", service],
+        ["docker", "volume", "rm", volume],
+      ]);
+      if (code !== 0) return code;
+      // A running app sets up its Qdrant collections only when it starts.
+      if (target === "memory" && (await running()).includes(SERVICE)) {
+        return runAll([[...COMPOSE, "restart", SERVICE]]);
+      }
+      return 0;
+    },
+    /** Packs the plugin's CLI config folder (`from`, by default
+     * `~/.config/<folder>`) into its credentials variable, written into the
+     * app's env file, or printed with `print`. */
+    credentialsSet: async (plugin: string, { from, print }: { from?: string; print: boolean }) => {
+      const { folder, variable } = credentialsOf(app, plugin);
+      const source = resolve(from ?? join(deps.home, ".config", folder));
+      const value = await packCredentials(source, folder);
+      if (print) {
+        deps.print(`${variable}=${value}`);
+        return 0;
+      }
+      const envFile = join(app.dir, ".env");
+      setEnvVar(envFile, variable, value);
+      deps.print(`${variable} set in ${envFile}, from ${source}.`);
+      deps.print(
+        `The app unpacks it at its next start, if the volume has no ${folder} folder yet; if it has one, run bunx mfw credentials reset ${plugin} first.`,
+      );
+      return 0;
+    },
+    /** Deletes the plugin's CLI folder from the credentials volume once the
+     * user types the plugin's name, so its variable is unpacked again at the
+     * next start. A wrong answer deletes nothing. */
+    credentialsReset: async (plugin: string) => {
+      const { folder } = credentialsOf(app, plugin);
+      const answer = await deps.ask(
+        `This deletes ${folder}'s folder from the app's credentials volume, and any token the CLI refreshed since it was unpacked. Type the plugin's name (${plugin}) to confirm: `,
+      );
+      if (answer.trim() !== plugin) {
+        deps.print("Not confirmed: nothing deleted.");
+        return 1;
+      }
+      return stopped(SERVICE, [[...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, "rm", "-rf", `/home/mercury/.config/${folder}`]]);
+    },
+  };
+
+  /** Stops `service`, runs `steps`, starts it again; stops at the first
+   * failure and, once the service is stopped, says it's down and how to bring
+   * it back. Returns the exit code. */
+  async function stopped(service: string, steps: string[][]): Promise<number> {
+    const all = [[...COMPOSE, "stop", service], ...steps, [...COMPOSE, "up", "-d", service]];
+    for (const [i, argv] of all.entries()) {
+      const code = await deps.run(argv, { cwd: app.dir });
+      if (code === 0) continue;
+      if (i > 0) deps.print(`The ${service} service was stopped and not restarted: bunx mfw start brings it back.`);
+      return code;
+    }
+    return 0;
+  }
+}
+
+/** The credentials of the tool plugin `plugin`, which `app` must depend on;
+ * throws naming the ones it has otherwise. */
+function credentialsOf(app: App, plugin: string): CliCredentials {
+  const manifest = JSON.parse(readFileSync(join(app.dir, "package.json"), "utf-8")) as {
+    dependencies?: Record<string, string>;
+  };
+  const have = CATALOG.filter(
+    (e) => e.kind === "tool" && e.credentials !== undefined && manifest.dependencies?.[e.package] !== undefined,
+  );
+  const entry = have.find((e) => e.id === plugin);
+  if (entry?.credentials === undefined) {
+    throw new Error(
+      `${app.name} has no "${plugin}" tool plugin with CLI credentials. It has: ${have.map((e) => e.id).join(", ") || "none"}.`,
+    );
+  }
+  return entry.credentials;
+}
+
+/** The real deps: docker on the user's terminal, questions on `input`
+ * (stdin by default). */
+export function terminalDeps({
+  input = process.stdin,
+  output = process.stdout,
+}: { input?: NodeJS.ReadableStream; output?: NodeJS.WritableStream } = {}): AppDeps {
+  return {
+    run: async (argv, { cwd }) => {
+      const proc = Bun.spawn(argv, { cwd, stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+      return await proc.exited;
+    },
+    capture: async (argv, { cwd }) => {
+      const proc = Bun.spawn(argv, { cwd, stdin: "ignore", stdout: "pipe", stderr: "inherit" });
+      const [out, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+      if (code !== 0) throw new Error(`${argv.join(" ")} failed (exit ${code})`);
+      return out;
+    },
+    // Input closing before a line (Ctrl+D, `< /dev/null`) is an empty answer,
+    // never a question left waiting.
+    ask: async (question) => {
+      const { createInterface } = await import("node:readline");
+      const rl = createInterface({ input, output });
+      return await new Promise<string>((resolve) => {
+        rl.once("close", () => resolve(""));
+        rl.question(question, (answer) => {
+          resolve(answer);
+          rl.close();
+        });
+      });
+    },
+    print: (line) => console.log(line),
+    home: homedir(),
+  };
+}