@mercury-fw/cli 0.25.1 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @mercury-fw/cli
 
+## 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,37 @@
 # @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)
+- [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 +51,123 @@ 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.
+
+## 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,70 @@
+/**
+ * The commands that operate an app (`mfw start`, `mfw vault`, …): each one is
+ * a short sequence of `docker compose` calls run from the app's folder, so the
+ * docker details live here and not in every app. The command line is parsed
+ * and validated before any of this runs (`program.ts`); what runs a command is
+ * injected (`AppDeps`), which is how the tests see the exact calls.
+ */
+import type { App } from "./find-app.ts";
+export type AppDeps = {
+    /** Runs `argv` in `cwd` on the user's terminal (stdin, stdout, stderr) and returns its exit code. */
+    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 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>;
+};
+/** 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/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/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.26.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.26.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.26.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,148 @@
+/**
+ * The commands that operate an app (`mfw start`, `mfw vault`, …): each one is
+ * a short sequence of `docker compose` calls run from the app's folder, so the
+ * docker details live here and not in every app. The command line is parsed
+ * and validated before any of this runs (`program.ts`); what runs a command is
+ * injected (`AppDeps`), which is how the tests see the exact calls.
+ */
+import type { App } from "./find-app.ts";
+
+export type AppDeps = {
+  /** Runs `argv` in `cwd` on the user's terminal (stdin, stdout, stderr) and returns its exit code. */
+  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;
+};
+
+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 steps = [
+        [...COMPOSE, "stop", service],
+        [...COMPOSE, "rm", "-f", service],
+        ["docker", "volume", "rm", volume],
+        [...COMPOSE, "up", "-d", service],
+      ];
+      for (const [i, argv] of steps.entries()) {
+        const code = await deps.run(argv, { cwd: app.dir });
+        if (code === 0) continue;
+        if (i > 0) deps.print(`The ${service} service was stopped and not restarted: bunx mfw start brings it back.`);
+        return code;
+      }
+      // 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;
+    },
+  };
+}
+
+/** 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),
+  };
+}

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/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,230 @@
+/**
+ * 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))());
+
+  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;
+  }
+}

package/src/render.ts

@@ -213,6 +213,10 @@ function renderPackageJson(
     }
     dependencies[pkg] = `^${version}`;
   }
+  const cli = versions["@mercury-fw/cli"];
+  if (cli === undefined) {
+    throw new Error("No version known for @mercury-fw/cli");
+  }
   const manifest: Record<string, unknown> = {
     name,
     version: "0.1.0",
@@ -220,7 +224,9 @@ function renderPackageJson(
     private: true,
     scripts: { start: "bun src/index.ts", repl: "bun src/repl.ts", typecheck: "tsc --noEmit" },
     dependencies,
-    devDependencies: { "@types/bun": "1.4.0", typescript: "6.0.3" },
+    // The CLI in the app itself, so `bunx mfw` runs the version that matches
+    // the framework the app depends on.
+    devDependencies: { "@mercury-fw/cli": `^${cli}`, "@types/bun": "^1.4.0", typescript: "^6.0.3" },
   };
   if (tools.length > 0) {
     manifest.trustedDependencies = tools.map((t) => t.package).sort();
@@ -317,11 +323,11 @@ A Mercury app, scaffolded by \`mfw create\`.
 \`\`\`bash
 bun install
 cp .env.example .env
-docker compose up --build
-docker compose run --rm mercury bun run repl
+bunx mfw start
+bunx mfw repl
 \`\`\`
 
-\`bun install\` here gives your editor and \`bun run typecheck\` the packages (tool plugins download their CLI binary as they install); the image installs its own copy when it builds.
+\`bun install\` here gives your editor, \`bun run typecheck\` and \`mfw\` the packages (tool plugins download their CLI binary as they install); the image installs its own copy when it builds. \`bunx mfw start\` builds the image and starts the app with Qdrant in the background, \`bunx mfw repl\` opens a terminal conversation with the assistant. \`bunx mfw --help\` lists the rest: stopping and restarting, logs, a shell in the container, the wiki and the memory, and resetting them.
 ${tools.length > 0 ? CREDENTIALS_SECTION : ""}`;
 }
 

package/src/versions.ts

@@ -7,7 +7,7 @@
 import pkg from "../package.json";
 
 /** The framework packages a new app can depend on: always at the CLI's version. */
-export const FRAMEWORK_PACKAGES = ["@mercury-fw/core", "@mercury-fw/formatter"];
+export const FRAMEWORK_PACKAGES = ["@mercury-fw/cli", "@mercury-fw/core", "@mercury-fw/formatter"];
 
 /** The registry asked when `MFW_REGISTRY` doesn't name another. */
 export const DEFAULT_REGISTRY = "https://registry.npmjs.org";