@mercury-fw/cli 0.25.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# @mercury-fw/cli
+
+## 0.25.0
+
+### Patch Changes
+
+- Updated dependencies [c114e34]
+  - @mercury-fw/core@0.25.0

package/README.md

@@ -0,0 +1,40 @@
+# @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.
+
+```bash
+bunx @mercury-fw/cli create my-agent
+```
+
+or, the same thing under the `create` convention:
+
+```bash
+bun create mercury-agent my-agent
+```
+
+## `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:
+
+- the app name (the `name` in `package.json`, defaulting to the folder's);
+- the assistant's name and role, which become `persona/identity.md` ("You are Hermes, the platform team's release assistant.") next to a `persona/tone.md` to edit;
+- which channels and which tool plugins to include (none is fine: the REPL always works).
+
+It writes the `mercury.config.ts` for that selection, the persona, the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the chosen pieces read. A plugin that hands over lists comes wrapped in the formatter with a starting rule, yours to change. Nothing is installed: run `bun install` in the new app.
+
+| Flag | |
+|---|---|
+| `--name <name>` | The app name. |
+| `--assistant-name <name>` | The assistant's name (default `Mercury`). |
+| `--role <text>` | Completes "You are <name>, …" (default `an internal assistant`). |
+| `--channels <ids>` | Comma-separated: `google-chat`, `http`. |
+| `--plugins <ids>` | Comma-separated: `jira`, `bitbucket`, `atlassian-admin`. |
+| `-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
+```
+
+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.
+
+MIT

package/dist/src/args.d.ts

@@ -0,0 +1,14 @@
+/** What the command line says. An answer left out is asked by the wizard, or
+ * takes its default with `yes`. */
+export type CreateArgs = {
+    dir: string;
+    name?: string;
+    assistantName?: string;
+    role?: string;
+    channels?: string[];
+    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;

package/dist/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/src/catalog.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The channels and tool plugins `mfw create` can put in a new app. Written
+ * by hand for now: once the packages are published, each plugin will describe
+ * itself (kind, export, env vars) and this list goes away. `catalog.test.ts`
+ * checks every entry against the real package until then.
+ */
+/** One environment variable an entry reads, as it appears in the app's env
+ * example: `value` is the example value, empty when the deployer must fill it. */
+export type EnvVar = {
+    name: string;
+    comment: string;
+    value?: string;
+};
+/** A channel or tool plugin the app can include. `id` is the plugin's own
+ * `name` (what MERCURY_CLIS lists for a tool plugin), `exportName` the value the
+ * app's config imports from `package`. */
+export type CatalogEntry = {
+    id: string;
+    kind: "channel" | "tool";
+    package: string;
+    exportName: string;
+    env: EnvVar[];
+    formatter?: FormatterExample;
+};
+/** 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,
+ * `helpers` the code the rules use (written above the config), `rules` the
+ * `kind: rule` lines. Once written, they're the app's to change. */
+export type FormatterExample = {
+    displaysType: string;
+    helpers: string;
+    rules: string[];
+};
+export declare const CATALOG: CatalogEntry[];
+/** The catalog entry of `kind` with `id`, or undefined when there is none. */
+export declare function findEntry(kind: CatalogEntry["kind"], id: string): CatalogEntry | undefined;

package/dist/src/main.d.ts

@@ -0,0 +1,4 @@
+/** 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>;

package/dist/src/naming.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Naming helpers for what the CLI turns into paths: the folder a new app is
+ * created in is always kebab case, whatever was typed.
+ */
+/** `text` in kebab case: accents dropped, camelCase split into words,
+ * lowercase, every run of anything but ASCII letters and digits turned into a
+ * single hyphen, no hyphen at either end. Empty when nothing usable is left. */
+export declare function kebabCase(text: string): string;

package/dist/src/render.d.ts

@@ -0,0 +1,21 @@
+/** What the new app is made of. `versions` maps each package the app depends
+ * on to the version its range is written against. */
+export type RenderInput = {
+    name: string;
+    assistantName: string;
+    role: string;
+    channels: string[];
+    plugins: string[];
+    versions: Record<string, string>;
+};
+/** Builds every file of the new app. Throws on an invalid app name, an empty
+ * assistant name or role, an id the catalog doesn't have, or a package with no
+ * version in `input.versions`. */
+export declare function renderApp(input: RenderInput): Map<string, string>;
+/** Why `name` can't be an app name, or undefined when it can. Shared with the
+ * wizard, which checks the name as it's typed. */
+export declare function appNameError(name: string): string | undefined;
+/** Names the first channel or plugin id the catalog doesn't have, with the
+ * valid ones, or undefined when all are known. Shared with the command, which
+ * checks the flags before asking anything. */
+export declare function selectionError(channels: string[], plugins: string[]): string | undefined;

package/dist/src/template.d.ts

@@ -0,0 +1,6 @@
+/** A template file (`template/**\/*.tpl`), imported as text so it ends up in the
+ * CLI's bundle instead of being read from disk at run time. */
+declare module "*.tpl" {
+  const text: string;
+  export default text;
+}

package/dist/src/versions.d.ts

@@ -0,0 +1,16 @@
+/** The framework packages a new app can depend on: always at the CLI's version. */
+export declare const FRAMEWORK_PACKAGES: string[];
+/** The registry asked when `MFW_REGISTRY` doesn't name another. */
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+/** The registry to ask: `value` (from `MFW_REGISTRY`) unless it's unset or
+ * blank, the default otherwise. */
+export declare function registryFrom(value: string | undefined): string;
+/** This CLI's version, which is the framework's. */
+export declare function cliVersion(): string;
+/** Maps the framework packages to the CLI's version and each of `packages`
+ * (plugins and channels) to the registry's `latest`. Rejects naming the
+ * package the registry doesn't have, or saying the registry can't be reached. */
+export declare function appVersions(packages: string[], opts: {
+    registry: string;
+    fetchFn?: typeof fetch;
+}): Promise<Record<string, string>>;

package/dist/src/wizard.d.ts

@@ -0,0 +1,15 @@
+import type { CreateArgs } from "./args.ts";
+/** The answers `renderApp` needs, apart from the package versions. */
+export type Answers = {
+    name: string;
+    assistantName: string;
+    role: string;
+    channels: string[];
+    plugins: string[];
+};
+export declare const DEFAULT_ASSISTANT_NAME = "Mercury";
+export declare const DEFAULT_ROLE = "an internal assistant";
+/** Asks every question, starting from `args`, for an app to be written into
+ * `dir` (already in kebab case, and the app name's default). Resolves to
+ * undefined when the user cancels (Ctrl+C) or doesn't confirm. */
+export declare function askAnswers(args: CreateArgs, dir: string): Promise<Answers | undefined>;

package/dist/src/write.d.ts

@@ -0,0 +1,8 @@
+/** Writes every `path → content` of `files` under `dir`, creating the folders
+ * they need. Throws, writing nothing, when `dir` is a file or a non-empty
+ * folder (hidden entries count). */
+export declare function writeApp(dir: string, files: Map<string, string>): void;
+/** Why `dir` can't receive a new app (a file, or a folder with something in
+ * it), or undefined when it's missing or empty. Shared with the command, which
+ * checks the target before asking anything. */
+export declare function targetError(dir: string): string | undefined;

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mercury-fw/cli",
+  "version": "0.25.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "apps/cli"
+  },
+  "files": [
+    "dist",
+    "src",
+    "template",
+    "CHANGELOG.md",
+    "!**/*.test.ts",
+    "!**/__fixtures__"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "mfw": "./src/bin.ts"
+  },
+  "exports": {
+    ".": {
+      "mercury-fw-source": "./src/main.ts",
+      "types": "./dist/src/main.d.ts",
+      "default": "./src/main.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "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.0"
+  },
+  "devDependencies": {
+    "@mercury-fw/channel-google-chat": "0.1.0",
+    "@mercury-fw/channel-http": "0.1.0",
+    "@mercury-fw/formatter": "0.25.0",
+    "@mercury-fw/plugin-atlassian-admin": "0.1.0",
+    "@mercury-fw/plugin-bitbucket": "0.1.0",
+    "@mercury-fw/plugin-jira": "0.1.0",
+    "@mercury-fw/typescript-config": "*",
+    "@types/bun": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/args.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+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`. */
+export type CreateArgs = {
+  dir: string;
+  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
+    .split(",")
+    .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);
+  return args;
+}

package/src/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env bun
+/** The `mfw` executable: runs the command line through `main`. */
+import { main } from "./main.ts";
+
+process.exit(await main(process.argv.slice(2)));

package/src/catalog.ts

@@ -0,0 +1,93 @@
+/**
+ * The channels and tool plugins `mfw create` can put in a new app. Written
+ * by hand for now: once the packages are published, each plugin will describe
+ * itself (kind, export, env vars) and this list goes away. `catalog.test.ts`
+ * checks every entry against the real package until then.
+ */
+
+/** One environment variable an entry reads, as it appears in the app's env
+ * example: `value` is the example value, empty when the deployer must fill it. */
+export type EnvVar = { name: string; comment: string; value?: string };
+
+/** A channel or tool plugin the app can include. `id` is the plugin's own
+ * `name` (what MERCURY_CLIS lists for a tool plugin), `exportName` the value the
+ * app's config imports from `package`. */
+export type CatalogEntry = {
+  id: string;
+  kind: "channel" | "tool";
+  package: string;
+  exportName: string;
+  env: EnvVar[];
+  formatter?: FormatterExample;
+};
+
+/** 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,
+ * `helpers` the code the rules use (written above the config), `rules` the
+ * `kind: rule` lines. Once written, they're the app's to change. */
+export type FormatterExample = { displaysType: string; helpers: string; rules: string[] };
+
+export const CATALOG: CatalogEntry[] = [
+  {
+    id: "google-chat",
+    kind: "channel",
+    package: "@mercury-fw/channel-google-chat",
+    exportName: "googleChatChannel",
+    env: [
+      {
+        name: "GOOGLE_CHAT_PUBSUB_SUBSCRIPTION",
+        comment: "Pub/Sub subscription the Chat app's events arrive on (projects/<p>/subscriptions/<s>); empty leaves Google Chat inert",
+      },
+      { name: "GOOGLE_CHAT_APP_CLIENT_EMAIL", comment: "Service account the Chat app authenticates as" },
+      { name: "GOOGLE_CHAT_APP_PRIVATE_KEY", comment: "That service account's private key (PEM)" },
+    ],
+  },
+  {
+    id: "http",
+    kind: "channel",
+    package: "@mercury-fw/channel-http",
+    exportName: "httpChannel",
+    env: [
+      { name: "HTTP_SURFACE_PORT", comment: "Port of the HTTP surface (no authentication: keep it off the public network)", value: "4100" },
+      { name: "HTTP_SURFACE_CORS_ORIGIN", comment: "Origin allowed to call the HTTP surface from a browser, if any" },
+    ],
+  },
+  {
+    id: "jira",
+    kind: "tool",
+    package: "@mercury-fw/plugin-jira",
+    exportName: "jiraPlugin",
+    env: [{ name: "JIRA_SITE_URL", comment: "Jira site the issue links point to (https://<site>.atlassian.net)" }],
+    formatter: {
+      displaysType: "JiraDisplays",
+      helpers: [
+        "/** One Jira issue in a search result: key, status in brackets when there is",
+        " * one, summary, and the browse link on its own line. A starting point: change",
+        " * it to change how Jira lists read. */",
+        'const jiraIssueLine = (issue: JiraDisplays["issue-list"]) =>',
+        '  `${issue.key} ${issue.status ? `[${issue.status}] ` : ""}${issue.summary}\\n${issue.url}`;',
+      ].join("\n"),
+      rules: ['"issue-list": { item: jiraIssueLine, empty: "No matching issues." },'],
+    },
+  },
+  {
+    id: "bitbucket",
+    kind: "tool",
+    package: "@mercury-fw/plugin-bitbucket",
+    exportName: "bitbucketPlugin",
+    env: [],
+  },
+  {
+    id: "atlassian-admin",
+    kind: "tool",
+    package: "@mercury-fw/plugin-atlassian-admin",
+    exportName: "atlassianAdminPlugin",
+    env: [],
+  },
+];
+
+/** The catalog entry of `kind` with `id`, or undefined when there is none. */
+export function findEntry(kind: CatalogEntry["kind"], id: string): CatalogEntry | undefined {
+  return CATALOG.find((e) => e.kind === kind && e.id === id);
+}

package/src/main.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+import { basename, dirname, join, resolve } from "node:path";
+import { parseCreateArgs, type CreateArgs } from "./args.ts";
+import { CATALOG } from "./catalog.ts";
+import { kebabCase } from "./naming.ts";
+import { renderApp, selectionError } from "./render.ts";
+import { appVersions, registryFrom } from "./versions.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 {
+    name: args.name ?? defaultName,
+    assistantName: args.assistantName ?? DEFAULT_ASSISTANT_NAME,
+    role: args.role ?? DEFAULT_ROLE,
+    channels: args.channels ?? [],
+    plugins: args.plugins ?? [],
+  };
+}
+
+/** `mfw create`: returns the exit code. */
+async function create(argv: string[]): Promise<number> {
+  const args = parseCreateArgs(argv);
+  // 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);
+  const folder = kebabCase(basename(typed));
+  if (folder === "") {
+    throw new Error(`"${basename(typed)}" has no letters or digits to name a folder with`);
+  }
+  const dir = join(dirname(typed), folder);
+  // What the command line already settles is checked before any question, so
+  // the wizard is never answered for nothing.
+  const early = targetError(dir) ?? selectionError(args.channels ?? [], args.plugins ?? []);
+  if (early !== undefined) {
+    throw new Error(early);
+  }
+  const answers = args.yes ? answersFromFlags(args, folder) : await askAnswers(args, dir);
+  if (answers === undefined) {
+    return 1;
+  }
+  const chosen = CATALOG.filter(
+    (e) => (e.kind === "channel" ? answers.channels : answers.plugins).includes(e.id),
+  ).map((e) => e.package);
+  const versions = await appVersions(chosen, { registry: registryFrom(process.env.MFW_REGISTRY) });
+  writeApp(dir, renderApp({ ...answers, versions }));
+  console.log(`Created ${answers.name} in ${dir}
+
+Next:
+  cd ${dir}
+  bun install
+  cp .env.example .env    # then fill it in
+  docker compose up --build`);
+  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;
+  }
+}

package/src/naming.ts

@@ -0,0 +1,18 @@
+/**
+ * Naming helpers for what the CLI turns into paths: the folder a new app is
+ * created in is always kebab case, whatever was typed.
+ */
+
+/** `text` in kebab case: accents dropped, camelCase split into words,
+ * lowercase, every run of anything but ASCII letters and digits turned into a
+ * single hyphen, no hyphen at either end. Empty when nothing usable is left. */
+export function kebabCase(text: string): string {
+  return text
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}

package/src/render.ts

@@ -0,0 +1,331 @@
+/// <reference path="./template.d.ts" />
+/**
+ * Turns the wizard's answers into the new app's files, as a `path → content`
+ * map, without touching the disk (`write.ts` does that). The static files come
+ * from `template/` imported as text, so they are bundled with the CLI; the
+ * config, the manifest, the env example, the compose file, the persona and the
+ * README are generated from the selection. Channels and plugins are always
+ * written in catalog order, whatever order they were chosen in.
+ */
+import { DEFAULT_PERSONA_TONE } from "@mercury-fw/core";
+import { CATALOG, type CatalogEntry, type EnvVar } from "./catalog.ts";
+import indexTs from "../template/src/index.ts.tpl" with { type: "text" };
+import replTs from "../template/src/repl.ts.tpl" with { type: "text" };
+import markdownDts from "../template/markdown.d.ts.tpl" with { type: "text" };
+import tsconfigJson from "../template/tsconfig.json.tpl" with { type: "text" };
+import gitignore from "../template/gitignore.tpl" with { type: "text" };
+import dockerignore from "../template/dockerignore.tpl" with { type: "text" };
+import dockerfile from "../template/Dockerfile.tpl" with { type: "text" };
+
+/** What the new app is made of. `versions` maps each package the app depends
+ * on to the version its range is written against. */
+export type RenderInput = {
+  name: string;
+  assistantName: string;
+  role: string;
+  channels: string[];
+  plugins: string[];
+  versions: Record<string, string>;
+};
+
+/** An app name that is a valid unscoped npm name and a valid prefix for the
+ * compose volume names. */
+const APP_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+const APP_NAME_MAX = 214;
+
+/** The variables the core reads, first in every app's env example. */
+const CORE_ENV: EnvVar[] = [
+  {
+    name: "OLLAMA_HOST",
+    comment: "Model endpoint (Ollama-compatible). Ollama running on the Docker host is host.docker.internal.",
+    value: "http://host.docker.internal:11434",
+  },
+  { name: "OLLAMA_MODEL", comment: "Chat model the assistant runs on" },
+  { name: "OLLAMA_EMBEDDING_MODEL", comment: "Embedding model for the episodic memory", value: "nomic-embed-text" },
+  { name: "QDRANT_URL", comment: "Qdrant, the compose service", value: "http://qdrant:6333" },
+  { name: "WIKI_VAULT_PATH", comment: "Wiki vault, the named volume's mount point", value: "/app/wiki-vault" },
+];
+
+const CONFIG_HEADER = `/**
+ * This app's composition: the tool plugins and channels it runs, how the lists
+ * its plugins hand over read, and the assistant's persona. The entrypoints
+ * (\`src/index.ts\`, \`src/repl.ts\`) hand this config to \`composeMercury\`.
+ *
+ * A tool plugin contributes only when it's also listed in MERCURY_CLIS; a
+ * channel is active as soon as it's declared here.
+ */`;
+
+/** Builds every file of the new app. Throws on an invalid app name, an empty
+ * assistant name or role, an id the catalog doesn't have, or a package with no
+ * version in `input.versions`. */
+export function renderApp(input: RenderInput): Map<string, string> {
+  validate(input);
+  const channels = selected("channel", input.channels);
+  const tools = selected("tool", input.plugins);
+  const assistantName = input.assistantName.trim();
+
+  return new Map([
+    [".dockerignore", dockerignore],
+    [".env.example", renderEnv(channels, tools)],
+    [".gitignore", gitignore],
+    ["Dockerfile", dockerfile],
+    ["README.md", renderReadme(input.name, channels, tools)],
+    ["docker-compose.yml", renderCompose(input.name, tools.length > 0)],
+    ["markdown.d.ts", markdownDts],
+    ["mercury.config.ts", renderConfig(channels, tools)],
+    ["package.json", renderPackageJson(input.name, channels, tools, input.versions)],
+    ["persona/identity.md", `You are ${assistantName}, ${input.role.trim().replace(/\.+$/, "")}.\n`],
+    // A replacer function, not a string: in a replacement string "$&" and the
+    // like are patterns, and the name must land verbatim.
+    ["persona/tone.md", `${DEFAULT_PERSONA_TONE.replaceAll("Mercury", () => assistantName)}\n`],
+    ["src/index.ts", indexTs],
+    ["src/repl.ts", replTs],
+    ["tsconfig.json", tsconfigJson],
+  ]);
+}
+
+/** Why `name` can't be an app name, or undefined when it can. Shared with the
+ * wizard, which checks the name as it's typed. */
+export function appNameError(name: string): string | undefined {
+  if (!APP_NAME.test(name) || name.length > APP_NAME_MAX) {
+    return `Invalid app name "${name}": lowercase letters, digits, ".", "_" and "-", starting with a letter or digit`;
+  }
+  return undefined;
+}
+
+/** Rejects what would produce a broken app, naming the valid choices. */
+function validate(input: RenderInput): void {
+  const nameError = appNameError(input.name);
+  if (nameError !== undefined) {
+    throw new Error(nameError);
+  }
+  if (!input.assistantName.trim()) {
+    throw new Error("The assistant name can't be empty");
+  }
+  if (!input.role.trim()) {
+    throw new Error("The assistant's role can't be empty");
+  }
+  if (/[\r\n]/.test(input.assistantName) || /[\r\n]/.test(input.role)) {
+    throw new Error("The assistant name and role must each be one line");
+  }
+  const selection = selectionError(input.channels, input.plugins);
+  if (selection !== undefined) {
+    throw new Error(selection);
+  }
+}
+
+/** Names the first channel or plugin id the catalog doesn't have, with the
+ * valid ones, or undefined when all are known. Shared with the command, which
+ * checks the flags before asking anything. */
+export function selectionError(channels: string[], plugins: string[]): string | undefined {
+  for (const [kind, ids] of [
+    ["channel", channels],
+    ["tool", plugins],
+  ] as const) {
+    const valid = CATALOG.filter((e) => e.kind === kind).map((e) => e.id);
+    const unknown = ids.find((id) => !valid.includes(id));
+    if (unknown !== undefined) {
+      const label = kind === "channel" ? "channel" : "plugin";
+      return `Unknown ${label} "${unknown}" (valid: ${valid.join(", ")})`;
+    }
+  }
+  return undefined;
+}
+
+/** The catalog entries of `kind` among `ids`, deduplicated, in catalog order. */
+function selected(kind: CatalogEntry["kind"], ids: string[]): CatalogEntry[] {
+  return CATALOG.filter((e) => e.kind === kind && ids.includes(e.id));
+}
+
+/** `mercury.config.ts`: imports, the formatter helpers of the plugins that have
+ * any, then the config with each plugin (wrapped in the formatter when it has
+ * starting rules) and channel. */
+function renderConfig(channels: CatalogEntry[], tools: CatalogEntry[]): string {
+  const withRules = tools.filter((t) => t.formatter);
+  const imports = ['import { defineMercuryConfig } from "@mercury-fw/core";'];
+  if (withRules.length > 0) {
+    imports.push('import { formatterPlugin, formatter } from "@mercury-fw/formatter";');
+  }
+  for (const t of tools) {
+    const names = t.formatter ? `${t.exportName}, type ${t.formatter.displaysType}` : t.exportName;
+    imports.push(`import { ${names} } from "${t.package}";`);
+  }
+  for (const c of channels) {
+    imports.push(`import { ${c.exportName} } from "${c.package}";`);
+  }
+  imports.push('import identity from "./persona/identity.md" with { type: "text" };');
+  imports.push('import tone from "./persona/tone.md" with { type: "text" };');
+
+  const helpers = withRules.map((t) => `${t.formatter?.helpers}\n\n`).join("");
+
+  const plugins =
+    tools.length === 0
+      ? "  plugins: [],"
+      : ["  plugins: [", ...tools.map(renderPluginEntry), "  ],"].join("\n");
+  const channelList = `  channels: [${channels.map((c) => c.exportName).join(", ")}],`;
+
+  return [
+    CONFIG_HEADER,
+    ...imports,
+    "",
+    `${helpers}export default defineMercuryConfig({`,
+    "  persona: { identity, tone },",
+    plugins,
+    channelList,
+    "});",
+    "",
+  ].join("\n");
+}
+
+/** One element of the config's `plugins` array. */
+function renderPluginEntry(t: CatalogEntry): string {
+  if (!t.formatter) {
+    return `    ${t.exportName},`;
+  }
+  return [
+    "    formatterPlugin(",
+    `      ${t.exportName},`,
+    `      formatter<${t.formatter.displaysType}>({`,
+    ...t.formatter.rules.map((r) => `        ${r}`),
+    "      }),",
+    "    ),",
+  ].join("\n");
+}
+
+/** `package.json`: the core, the formatter when a plugin is wrapped in it, the
+ * chosen packages, and every tool plugin trusted to run its postinstall (it
+ * downloads the plugin's CLI). */
+function renderPackageJson(
+  name: string,
+  channels: CatalogEntry[],
+  tools: CatalogEntry[],
+  versions: Record<string, string>,
+): string {
+  const packages = ["@mercury-fw/core", ...channels.map((c) => c.package), ...tools.map((t) => t.package)];
+  if (tools.some((t) => t.formatter)) {
+    packages.push("@mercury-fw/formatter");
+  }
+  const dependencies: Record<string, string> = {};
+  for (const pkg of packages.sort()) {
+    const version = versions[pkg];
+    if (version === undefined) {
+      throw new Error(`No version known for ${pkg}`);
+    }
+    dependencies[pkg] = `^${version}`;
+  }
+  const manifest: Record<string, unknown> = {
+    name,
+    version: "0.1.0",
+    type: "module",
+    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" },
+  };
+  if (tools.length > 0) {
+    manifest.trustedDependencies = tools.map((t) => t.package).sort();
+  }
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/** The env example: the core's variables, MERCURY_CLIS when a tool plugin was
+ * chosen, then a section per chosen entry that reads any variable. */
+function renderEnv(channels: CatalogEntry[], tools: CatalogEntry[]): string {
+  const block = (vars: EnvVar[]) => vars.map((v) => `# ${v.comment}\n${v.name}=${v.value ?? ""}`).join("\n");
+  const sections = [block(CORE_ENV)];
+  if (tools.length > 0) {
+    sections.push(
+      block([
+        {
+          name: "MERCURY_CLIS",
+          comment: "Tool plugins this instance enables (their ids, comma-separated)",
+          value: tools.map((t) => t.id).join(","),
+        },
+      ]),
+    );
+  }
+  for (const entry of [...channels, ...tools]) {
+    if (entry.env.length > 0) {
+      sections.push(`# --- ${entry.id}\n${block(entry.env)}`);
+    }
+  }
+  return `${sections.join("\n\n")}\n`;
+}
+
+/** `docker-compose.yml`: the app and Qdrant, with named volumes prefixed by the
+ * app's name; the CLI credentials volume only when a tool plugin was chosen. */
+function renderCompose(name: string, hasTools: boolean): string {
+  const credentialsMount = hasTools
+    ? [
+        "      # The tool plugins' CLI credentials, on a volume so what a CLI writes back",
+        "      # (refreshed tokens) survives a redeploy. It starts empty: see README.md.",
+        "      - cli-credentials:/home/mercury/.config",
+      ]
+    : [];
+  const credentialsVolume = hasTools ? ["  cli-credentials:", `    name: ${name}_cli-credentials`] : [];
+  return [
+    "services:",
+    "  mercury:",
+    "    build: .",
+    "    env_file:",
+    "      - path: .env",
+    "        required: false",
+    "    volumes:",
+    "      - wiki-vault:/app/wiki-vault",
+    ...credentialsMount,
+    "    extra_hosts:",
+    '      - "host.docker.internal:host-gateway"',
+    "    depends_on:",
+    "      - qdrant",
+    "",
+    "  qdrant:",
+    "    image: qdrant/qdrant:v1.19.0",
+    "    volumes:",
+    "      - qdrant-data:/qdrant/storage",
+    "",
+    "volumes:",
+    "  wiki-vault:",
+    `    name: ${name}_wiki-vault`,
+    "  qdrant-data:",
+    `    name: ${name}_qdrant-data`,
+    ...credentialsVolume,
+    "",
+  ].join("\n");
+}
+
+/** The app's README: what it was scaffolded with and how to run it. */
+function renderReadme(name: string, channels: CatalogEntry[], tools: CatalogEntry[]): string {
+  const list = (entries: CatalogEntry[]) => (entries.length > 0 ? entries.map((e) => e.id).join(", ") : "none");
+  return `# ${name}
+
+A Mercury app, scaffolded by \`mfw create\`.
+
+- Channels: ${list(channels)}
+- Tool plugins: ${list(tools)}
+
+## Layout
+
+- \`mercury.config.ts\`: what the app is made of (tool plugins, channels, how their lists read) and the assistant's persona.
+- \`persona/identity.md\`, \`persona/tone.md\`: who the assistant is and how it answers. Edit them freely.
+- \`src/index.ts\`: the service (channels, crons). \`src/repl.ts\`: an interactive terminal for trying things out.
+- \`.env.example\`: every variable the app reads. Copy it to \`.env\` and fill it in.
+
+## Running it
+
+\`\`\`bash
+bun install
+cp .env.example .env
+docker compose up --build
+docker compose run --rm mercury bun run 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.
+${tools.length > 0 ? CREDENTIALS_SECTION : ""}`;
+}
+
+/** The README section on CLI credentials, for an app with tool plugins. */
+const CREDENTIALS_SECTION = `
+## CLI credentials
+
+Each tool plugin runs its own CLI, and each CLI keeps its login under \`/home/mercury/.config\` in the container, on the \`cli-credentials\` volume. The volume starts empty: nothing in this app provisions it yet, so authenticate each CLI once inside the container (\`docker compose run --rm mercury <cli> --help\` lists its auth commands) or copy its config folder into the volume. What the CLIs write back afterwards, like refreshed tokens, stays on the volume across redeploys.
+`;

package/src/template.d.ts

@@ -0,0 +1,6 @@
+/** A template file (`template/**\/*.tpl`), imported as text so it ends up in the
+ * CLI's bundle instead of being read from disk at run time. */
+declare module "*.tpl" {
+  const text: string;
+  export default text;
+}

package/src/versions.ts

@@ -0,0 +1,58 @@
+/**
+ * The version each package of a new app is written against. The framework
+ * packages move in lockstep with this CLI, so they take its own version; a
+ * plugin or channel is versioned on its own, so it takes the registry's
+ * `latest` (asked only for the ones chosen).
+ */
+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"];
+
+/** The registry asked when `MFW_REGISTRY` doesn't name another. */
+export const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+
+/** The registry to ask: `value` (from `MFW_REGISTRY`) unless it's unset or
+ * blank, the default otherwise. */
+export function registryFrom(value: string | undefined): string {
+  return value?.trim() ? value.trim() : DEFAULT_REGISTRY;
+}
+
+/** This CLI's version, which is the framework's. */
+export function cliVersion(): string {
+  return pkg.version;
+}
+
+/** Maps the framework packages to the CLI's version and each of `packages`
+ * (plugins and channels) to the registry's `latest`. Rejects naming the
+ * package the registry doesn't have, or saying the registry can't be reached. */
+export async function appVersions(
+  packages: string[],
+  opts: { registry: string; fetchFn?: typeof fetch },
+): Promise<Record<string, string>> {
+  const registry = opts.registry.replace(/\/+$/, "");
+  const fetchFn = opts.fetchFn ?? fetch;
+  const versions: Record<string, string> = Object.fromEntries(FRAMEWORK_PACKAGES.map((p) => [p, cliVersion()]));
+  const latest = await Promise.all(
+    packages.map(async (name) => {
+      let res: Response;
+      try {
+        res = await fetchFn(`${registry}/${name.replace("/", "%2F")}/latest`);
+      } catch {
+        throw new Error(`Can't reach ${registry} to look up ${name}`);
+      }
+      if (!res.ok) {
+        throw new Error(`${name} is not on ${registry}`);
+      }
+      const body = (await res.json().catch(() => undefined)) as { version?: unknown } | undefined;
+      if (typeof body?.version !== "string") {
+        throw new Error(`${registry} gave no version for ${name}`);
+      }
+      return [name, body.version] as const;
+    }),
+  );
+  for (const [name, version] of latest) {
+    versions[name] = version;
+  }
+  return versions;
+}

package/src/wizard.ts

@@ -0,0 +1,88 @@
+/**
+ * The interactive side of `mfw create`: asks for the answers, pre-filled
+ * with whatever the flags already gave, shows a summary and asks to confirm.
+ * Only questions; building and writing the app is `index.ts`'s job.
+ */
+import { basename } from "node:path";
+import * as p from "@clack/prompts";
+import { CATALOG, type CatalogEntry } from "./catalog.ts";
+import { appNameError } from "./render.ts";
+import type { CreateArgs } from "./args.ts";
+
+/** The answers `renderApp` needs, apart from the package versions. */
+export type Answers = {
+  name: string;
+  assistantName: string;
+  role: string;
+  channels: string[];
+  plugins: string[];
+};
+
+export const DEFAULT_ASSISTANT_NAME = "Mercury";
+export const DEFAULT_ROLE = "an internal assistant";
+
+/** A text answer's default, shown greyed out and taken on a bare Enter; typing
+ * replaces it instead of appending to it. */
+const suggest = (value: string) => ({ placeholder: value, defaultValue: value });
+
+/** A multi-select over the catalog entries of `kind`; none selected is fine.
+ * Undefined when the user cancels. */
+async function pick(kind: CatalogEntry["kind"], message: string, initial: string[]): Promise<string[] | undefined> {
+  const picked = await p.multiselect({
+    message,
+    options: CATALOG.filter((e) => e.kind === kind).map((e) => ({ value: e.id, label: e.id, hint: e.package })),
+    initialValues: initial,
+    required: false,
+  });
+  return p.isCancel(picked) ? undefined : picked;
+}
+
+/** Asks every question, starting from `args`, for an app to be written into
+ * `dir` (already in kebab case, and the app name's default). Resolves to
+ * undefined when the user cancels (Ctrl+C) or doesn't confirm. */
+export async function askAnswers(args: CreateArgs, dir: string): Promise<Answers | undefined> {
+  p.intro("mfw create");
+  // A --name that isn't a valid app name isn't offered; then there's no
+  // default, and an empty answer is rejected.
+  const nameDefault = args.name ?? basename(dir);
+  const name = await p.text({
+    message: "App name",
+    ...(appNameError(nameDefault) === undefined ? suggest(nameDefault) : {}),
+    validate: (v) => (v ? appNameError(v) : appNameError(nameDefault)),
+  });
+  if (p.isCancel(name)) return cancelled();
+  const assistantName = await p.text({
+    message: "Assistant name",
+    ...suggest(args.assistantName ?? DEFAULT_ASSISTANT_NAME),
+    validate: (v) => (v === undefined || v === "" || v.trim() ? undefined : "The assistant needs a name"),
+  });
+  if (p.isCancel(assistantName)) return cancelled();
+  const role = await p.text({
+    message: `${assistantName} is… (completes "You are ${assistantName}, …")`,
+    ...suggest(args.role ?? DEFAULT_ROLE),
+    validate: (v) => (v === undefined || v === "" || v.trim() ? undefined : "The role can't be empty"),
+  });
+  if (p.isCancel(role)) return cancelled();
+  const channels = await pick("channel", "Channels (space to select, none is fine: the REPL always works)", args.channels ?? []);
+  if (channels === undefined) return cancelled();
+  const plugins = await pick("tool", "Tool plugins (space to select)", args.plugins ?? []);
+  if (plugins === undefined) return cancelled();
+
+  p.note(
+    [
+      `App: ${name}`,
+      `Assistant: You are ${assistantName}, ${role}.`,
+      `Channels: ${channels.length > 0 ? channels.join(", ") : "none"}`,
+      `Tool plugins: ${plugins.length > 0 ? plugins.join(", ") : "none"}`,
+    ].join("\n"),
+    "Summary",
+  );
+  const ok = await p.confirm({ message: `Create it in ${dir}?` });
+  if (p.isCancel(ok) || !ok) return cancelled();
+  return { name, assistantName, role, channels, plugins };
+}
+
+function cancelled(): undefined {
+  p.cancel("Nothing written.");
+  return undefined;
+}

package/src/write.ts

@@ -0,0 +1,38 @@
+/**
+ * Writes a rendered app (`render.ts`) to disk. The target must be missing or an
+ * empty folder: scaffolding never writes over an existing project, and the
+ * check happens before any file is written.
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Writes every `path → content` of `files` under `dir`, creating the folders
+ * they need. Throws, writing nothing, when `dir` is a file or a non-empty
+ * folder (hidden entries count). */
+export function writeApp(dir: string, files: Map<string, string>): void {
+  const error = targetError(dir);
+  if (error !== undefined) {
+    throw new Error(error);
+  }
+  for (const [path, content] of files) {
+    const target = join(dir, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, content);
+  }
+}
+
+/** Why `dir` can't receive a new app (a file, or a folder with something in
+ * it), or undefined when it's missing or empty. Shared with the command, which
+ * checks the target before asking anything. */
+export function targetError(dir: string): string | undefined {
+  if (!existsSync(dir)) {
+    return undefined;
+  }
+  if (!statSync(dir).isDirectory()) {
+    return `${dir} is not a folder`;
+  }
+  if (readdirSync(dir).length > 0) {
+    return `${dir} is not empty`;
+  }
+  return undefined;
+}

package/template/Dockerfile.tpl

@@ -0,0 +1,32 @@
+# Debian, not Alpine: the tool plugins' CLIs are glibc binaries.
+FROM oven/bun:1
+
+# ca-certificates: the CLIs verify TLS against the OS trust store.
+# git: the wiki vault is a git repository Mercury initializes at startup.
+RUN apt-get update && apt-get upgrade -y \
+  && apt-get install -y --no-install-recommends ca-certificates git \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN groupadd -r mercury && useradd -r -g mercury mercury
+
+WORKDIR /app
+
+# Each tool plugin downloads its pinned CLI in its postinstall (allowed by
+# package.json's trustedDependencies); the binaries go on PATH.
+COPY --chown=mercury:mercury package.json bun.lock* ./
+RUN bun install --production && chown -R mercury:mercury node_modules
+RUN find /app/node_modules -path '*/@mercury-fw/*/bin/*' -type f -exec ln -sf {} /usr/local/bin/ \;
+
+COPY --chown=mercury:mercury mercury.config.ts markdown.d.ts ./
+COPY --chown=mercury:mercury persona ./persona
+COPY --chown=mercury:mercury src ./src
+
+# Mount points of the named volumes, owned by the runtime user before a fresh
+# volume attaches (a new volume takes the ownership it finds here).
+RUN mkdir -p /app/wiki-vault /home/mercury/.config \
+  && chown mercury:mercury /app/wiki-vault \
+  && chown -R mercury:mercury /home/mercury
+
+USER mercury
+
+CMD ["bun", "src/index.ts"]

package/template/dockerignore.tpl

@@ -0,0 +1,6 @@
+node_modules
+.git
+.env
+.env.*
+!.env.example
+*.log

package/template/gitignore.tpl

@@ -0,0 +1,6 @@
+node_modules
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store

package/template/markdown.d.ts.tpl

@@ -0,0 +1,5 @@
+/** Markdown imported as text (`with { type: "text" }`), as the persona files are. */
+declare module "*.md" {
+  const text: string;
+  export default text;
+}

package/template/src/index.ts.tpl

@@ -0,0 +1,42 @@
+/**
+ * Service entrypoint: builds the app with `composeMercury`, fed
+ * `mercury.config.ts`, and starts what a long-running service runs: the
+ * declared channels, the admin panel (when enabled) and the memory crons.
+ * Headless; the interactive terminal is `bun run repl` (`repl.ts`).
+ *
+ * Stays alive on the channels' background resources and the cron intervals,
+ * and shuts down on SIGINT/SIGTERM (what `docker compose stop` sends).
+ */
+import { composeMercury, loadChannels, type LoadedChannel } from "@mercury-fw/core";
+import mercuryConfig from "../mercury.config.ts";
+
+const app = await composeMercury(mercuryConfig);
+
+const loadedChannels: LoadedChannel[] = loadChannels(app.channels, { runtime: app.channelRuntime });
+for (const { name, provider } of loadedChannels) {
+  await provider.start(app.handleTurn);
+  console.error(`[channel] ${name} started`);
+}
+
+const adminServer = app.startAdmin();
+const crons = app.startCrons();
+console.error("[service] up — channels and crons started; waiting for SIGINT/SIGTERM");
+
+// Release everything that holds the event loop open, then exit: the model and
+// Qdrant clients keep pooled sockets with no dispose. Guarded so a second
+// signal during teardown doesn't run it twice.
+let shuttingDown = false;
+async function shutdown(signal: string): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.error(`[shutdown] ${signal} received, releasing subsystems`);
+  crons.stop();
+  adminServer?.stop();
+  for (const { name, provider } of loadedChannels) {
+    await provider.stop?.();
+    console.error(`[shutdown] channel ${name} stopped`);
+  }
+  process.exit(0);
+}
+process.on("SIGINT", () => void shutdown("SIGINT"));
+process.on("SIGTERM", () => void shutdown("SIGTERM"));

package/template/src/repl.ts.tpl

@@ -0,0 +1,20 @@
+/**
+ * Dev REPL entrypoint (`bun run repl`): boots the same app the service runs and
+ * opens an interactive terminal on it. For trying things out and debugging, not
+ * a channel: no user identity (nothing goes to per-user memory), no channels,
+ * crons or admin panel.
+ */
+import { composeMercury, createTerminalProvider } from "@mercury-fw/core";
+import mercuryConfig from "../mercury.config.ts";
+
+const app = await composeMercury(mercuryConfig);
+
+await createTerminalProvider({
+  confirmDeps: app.confirmDeps,
+  ollamaHost: app.ollamaHost,
+  ollamaModel: app.ollamaModel,
+}).start(app.handleTurn);
+
+// The REPL ended (Ctrl+D); the model and Qdrant clients keep pooled sockets
+// open, so exit explicitly.
+process.exit(0);

package/template/tsconfig.json.tpl

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "allowJs": true,
+    "types": ["bun"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true
+  }
+}