@mercury-fw/cli 0.53.1 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @mercury-fw/cli
 
+## 0.54.0
+
+### Minor Changes
+
+- ebde9e2: The texts a person sees can be in their language. The core's own fixed texts (the refusal of someone the agent doesn't know, the account-linking replies, the login errors, the tool status lines, the terminal's own lines) are English, each under a key (`core.access.unknown`, …), and an app adds a language with a file of its own: `i18n: { defaultLocale, locales: { it } }` in `mercury.config.ts`, each file mapping keys to texts. A person picks their language by asking the agent, which saves it with `set_preferred_language` (only the languages the app ships; not offered when it ships English alone) and answers in it from then on. Whoever hasn't picked one gets `defaultLocale`, then English. A key a language's file lacks shows as the key itself, and the log names the missing keys at startup. `GET /me` on the HTTP channel also says the caller's language.
+
+  The texts that were in Italian (tool status lines, the terminal's lines) are now English by default, and the language is no longer one of the facts inferred from conversations.
+
+  An existing app keeps working, with these changes:
+
+  1. `access.unknownMessage` is gone. To keep a custom refusal, put it in `locales/en.json` as `{ "core.access.unknown": "…" }`, and in `mercury.config.ts` import it (`import en from "./locales/en.json";`) and set `i18n: { locales: { en } }`.
+  2. To keep the status and terminal lines in Italian, add `locales/it.json` with the `core.` keys translated (start it as `{}`: the log lists the missing keys at startup), and in `mercury.config.ts` import it (`import it from "./locales/it.json";`) and set `i18n: { defaultLocale: "it", locales: { it } }` (`locales: { en, it }` when you did step 1 too).
+  3. Whenever the config imports a file from `locales/` (steps 1 and 2), the image needs the folder: add `COPY --chown=mercury:mercury locales ./locales` after the `mercury.config.ts` line of the `Dockerfile`, or the app fails at startup.
+  4. For the terminal (`mfw repl`) to follow the language too, add `texts: app.texts,` to `createTerminalProvider({ … })` in `src/repl.ts`; without it the terminal's own lines stay English.
+
+- 5015642: The plugins' texts a person sees come out in their language, like the core's. Plugin contract version 5:
+
+  - A plugin declares its texts in English in `messages`, every key under its own name (`web-search.choice.once`); the core refuses a plugin with a key outside it (and a plugin named `core` or `app`, whose keys are the core's and the app's), and the app's language files translate them. The startup log names the missing keys of the plugins too.
+  - While a turn runs, a plugin gets the texts of its person as `t`: in `SessionToolContext.t`, as the second argument of a status describer (`toolStatusDescribers`, `StatusDescriber`), the third of a post-processor (`CliPostProcessor`), and in a post-turn guard, whose `statusLabel` is now `(t) => string` and whose `run` gets `t` as its third argument. `Messages`, `Params` and `Translate` are part of the contract.
+  - The default status line of a CLI command is the core's `core.status.command` ("Running jira issue search"), `core.status.command-bare` without a subcommand ("Running jira"), and an unreadable command's is `core.status.command-unknown`. `createCliTool` (`@mercury-fw/cli-engine`) takes the turn's `t` among its options, handed to the post-processor: a CLI plugin passes `sctx.t`; `createCliStatusDescriber`'s describer takes it as its second argument.
+  - The formatter hands a rule `t` as its second argument, and an `empty` text can be `(t) => string`; existing rules keep working as they are. An app's own texts go under `app.`, in its `locales/en.json`, which declares them (the startup log no longer lists them as unknown); `mfw create` writes the Jira rule's empty text as `app.jira.no-issues`.
+  - Web search: the two choices ("Only this time", "Always for \<host\>"), the status lines and the sources heading ("Sources") are `web-search.*` texts, English by default; a list of sources the model writes under the heading in the person's language, or the English one, is still replaced by the plugin's.
+
+  The first-party plugins released with this change are written for contract 5 and need the core released with it: an older core skips them and says why in the log. A plugin written for contract 4 isn't loaded by this core either, and the log says why: rebuild it against `PLUGIN_API_VERSION` 5 (a status describer, a guard's `statusLabel` and `run`, a post-processor take the new `t`). An app that wants the web search and status lines back in Italian adds their keys to `locales/it.json` (the log lists the missing ones at startup).
+
+### Patch Changes
+
+- Updated dependencies [e00ff73]
+- Updated dependencies [ebde9e2]
+- Updated dependencies [5015642]
+  - @mercury-fw/core@0.54.0
+  - @mercury-fw/utils@0.54.0
+
+## 0.53.2
+
+### Patch Changes
+
+- 4a9a528: `mfw create` writes the whole persona inside `mercury.config.ts`: the assistant's name once, as a `const`, referred to by the identity and by the tone, which is written out in full, one string per line. There are no `persona/identity.md` and `persona/tone.md` files anymore, no `markdown.d.ts`, and the Dockerfile no longer copies them.
+
+  An existing app keeps working as it is. To move it to the new layout:
+
+  1. In `mercury.config.ts`, drop the two `import … from "./persona/…md"` lines, add `const name = "<the assistant's name>";` and set `persona: { name, identity: "…", tone: "…" }` with the text of the two files (`${name}` in a template literal where they say `{{assistant}}`, or keep `{{assistant}}`: the core still replaces it).
+  2. Delete `persona/` and `markdown.d.ts`.
+  3. In the `Dockerfile`, change `COPY --chown=mercury:mercury mercury.config.ts markdown.d.ts ./` to `COPY --chown=mercury:mercury mercury.config.ts ./` and delete `COPY --chown=mercury:mercury persona ./persona`.
+
+  - @mercury-fw/core@0.53.2
+  - @mercury-fw/utils@0.53.2
+
 ## 0.53.1
 
 ### Patch Changes

package/README.md

@@ -47,11 +47,11 @@ Without a global install: `bun create mercury-agent my-agent` creates an app, an
 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: the name becomes `persona.name` in the config, the role `persona/identity.md` ("You are {{assistant}}, the platform team's release assistant.", the core putting the name in place of `{{assistant}}`), next to a `persona/tone.md` to edit;
+- the assistant's name and role: the whole persona goes in the config, the name written once as a `const` and referred to by the identity (`` `You are ${name}, the platform team's release assistant.` ``) and by the tone, written out in full to edit;
 - which channels and which tool plugins to include (none is fine: the REPL always works);
 - the git remote for `origin`, which you can leave empty (most of the time it doesn't exist yet when you scaffold).
 
-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.
+It writes the `mercury.config.ts` for that selection, the persona, a `locales/` folder with an `en.json` for the texts people see (empty, or the starting formatter rules' own texts: `app.jira.no-issues` with Jira), 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.
 
 Then it runs `bun install` in the app and creates a git repository on `main` with a first commit (`bun.lock` included), adding `origin` when you gave one; nothing is pushed. Each step is best effort and never undoes the ones before it: an install that fails still leaves the app committed, without the lockfile, and the closing message says what to run. The repository is skipped when the folder is already inside one (an app created in a monorepo belongs to it). Whether git can commit is git's call: when it refuses (no identity, a hook) or isn't installed, the message reports why and lists the commands to finish by hand. `bun install` prints its own output as it runs.
 
@@ -341,7 +341,7 @@ export default e2e({
         "Delete the issue SUP-1 on Jira",
         { text: (previous) => (previous.calls.find((c) => c.pending)?.output as { token: string }).token, as: "bob" },
       ],
-      check: (run, expect) => expect.answerNot("Confermato"),
+      check: (run, expect) => expect.answerNot("Confirmed"),
     },
   ],
 });

package/dist/src/catalog.d.ts

@@ -49,11 +49,14 @@ export type CatalogEntry = {
  * 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. */
+ * `kind: rule` lines, `messages` the English texts they show the person
+ * (`app.` keys, written into the app's `locales/en.json`). Once written,
+ * they're the app's to change. */
 export type FormatterExample = {
     displaysType: string;
     helpers: string;
     rules: string[];
+    messages?: Record<string, string>;
 };
 export declare const CATALOG: CatalogEntry[];
 /** The catalog entry of `kind` with `id`, or undefined when there is none. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.53.1",
+  "version": "0.54.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,22 +41,22 @@
   "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.53.1",
-    "@mercury-fw/utils": "0.53.1",
+    "@mercury-fw/core": "0.54.0",
+    "@mercury-fw/utils": "0.54.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
     "@mercury-fw/auth-oidc": "0.2.0",
     "@mercury-fw/auth-static": "0.2.1",
-    "@mercury-fw/channel-google-chat": "0.8.2",
-    "@mercury-fw/channel-http": "0.10.1",
+    "@mercury-fw/channel-google-chat": "0.9.0",
+    "@mercury-fw/channel-http": "0.11.0",
     "@mercury-fw/directory-static": "0.1.1",
-    "@mercury-fw/formatter": "0.53.1",
-    "@mercury-fw/plugin-atlassian-admin": "0.3.2",
-    "@mercury-fw/plugin-bitbucket": "0.4.1",
-    "@mercury-fw/plugin-jira": "0.6.5",
-    "@mercury-fw/plugin-web-search": "0.1.2",
-    "@mercury-fw/plugin-zitadel": "0.3.2",
+    "@mercury-fw/formatter": "0.54.0",
+    "@mercury-fw/plugin-atlassian-admin": "0.4.0",
+    "@mercury-fw/plugin-bitbucket": "0.5.0",
+    "@mercury-fw/plugin-jira": "0.7.0",
+    "@mercury-fw/plugin-web-search": "0.2.0",
+    "@mercury-fw/plugin-zitadel": "0.4.0",
     "@mercury-fw/typescript-config": "*",
     "@mercury-fw/web-search-searxng": "0.1.0",
     "@types/bun": "^1.4.2",

package/src/catalog.ts

@@ -55,8 +55,10 @@ search:
  * 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[] };
+ * `kind: rule` lines, `messages` the English texts they show the person
+ * (`app.` keys, written into the app's `locales/en.json`). Once written,
+ * they're the app's to change. */
+export type FormatterExample = { displaysType: string; helpers: string; rules: string[]; messages?: Record<string, string> };
 
 export const CATALOG: CatalogEntry[] = [
   {
@@ -125,7 +127,8 @@ export const CATALOG: CatalogEntry[] = [
         '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." },'],
+      rules: ['"issue-list": { item: jiraIssueLine, empty: (t) => t("app.jira.no-issues") },'],
+      messages: { "app.jira.no-issues": "No matching issues." },
     },
   },
   {

package/src/program.ts

@@ -52,7 +52,7 @@ function buildProgram(handlers: ProgramHandlers, result: { code: number }): Comm
     .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 (with the HTTP channel's auth provider) and tool plugins to include; then it writes mercury.config.ts for that selection, with the assistant's name as persona.name, the persona (persona/identity.md, persona/tone.md, which refer to the name as {{assistant}}), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the app reads. Then it runs bun install, and creates a git repository on main with a first commit, adding the origin when given (nothing is pushed).",
+      "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 (with the HTTP channel's auth provider) and tool plugins to include; then it writes mercury.config.ts for that selection, with the whole persona in it (the assistant's name, its role as the identity, and the default tone written out to edit), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the app reads. Then it runs bun install, and creates a git repository on main with a first commit, adding the origin when given (nothing is pushed).",
     )
     .argument("<folder>", "where to write the app")
     .option("--name <name>", "app name, as in package.json (default: the folder's name)")

package/src/render.ts

@@ -3,16 +3,15 @@
  * 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
+ * config (with the persona), the manifest, the env example, the compose file
+ * and the README are generated from the selection. Channels and plugins are always
  * written in catalog order, whatever order they were chosen in; the auth
  * provider, when there is one, after the channels.
  */
-import { DEFAULT_PERSONA_IDENTITY, DEFAULT_PERSONA_TONE, assistantNameOf } from "@mercury-fw/core";
+import { DEFAULT_PERSONA_TONE, assistantNameOf } 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" };
@@ -59,7 +58,8 @@ const CORE_ENV: EnvVar[] = [
 const CONFIG_HEADER = `/**
  * This app's composition: the tool plugins and channels it runs, the auth
  * provider when a channel needs one, how the lists its plugins hand over read,
- * and the assistant's persona. The entrypoints
+ * the assistant's persona and the languages it speaks (\`i18n\`: a file per
+ * language in \`locales/\`, \`en.json\` overriding the English texts). The entrypoints
  * (\`src/index.ts\`, \`src/repl.ts\`) hand this config to \`composeMercury\`.
  *
  * Every tool plugin and channel declared here is active.
@@ -86,12 +86,9 @@ export function renderApp(input: RenderInput): Map<string, string> {
     ["Dockerfile", dockerfile],
     ["README.md", renderReadme(input.name, channels, auth, tools, directory)],
     ["docker-compose.yml", renderCompose(input.name, channels.some((c) => c.id === "http"), services)],
-    ["markdown.d.ts", markdownDts],
-    ["mercury.config.ts", renderConfig(assistantName, channels, auth, tools, directory)],
+    ["locales/en.json", renderEnglish(tools)],
+    ["mercury.config.ts", renderConfig(assistantName, input.role, channels, auth, tools, directory)],
     ["package.json", renderPackageJson(input.name, channels, auth, tools, input.versions, directory)],
-    // The name is persona.name in the config; the persona files refer to it.
-    ["persona/identity.md", `You are {{assistant}}, ${input.role.trim().replace(/\.+$/, "")}.\n`],
-    ["persona/tone.md", `${DEFAULT_PERSONA_TONE}\n`],
     ["src/index.ts", indexTs],
     ["src/repl.ts", replTs],
     ["tsconfig.json", tsconfigJson],
@@ -169,18 +166,55 @@ 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. */
+/** What the core's persona texts write where the assistant's name goes. */
+const ASSISTANT = "{{assistant}}";
+
+/** `text` as the inside of a template literal: backslashes, backticks and `${` stay text. */
+function templateText(text: string): string {
+  return text.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+}
+
+/** One line of the persona as config source: a template literal referring to
+ * the config's `name` where the line names the assistant, a string otherwise. */
+function personaLine(line: string): string {
+  if (!line.includes(ASSISTANT)) return JSON.stringify(line);
+  return `\`${line.split(ASSISTANT).map(templateText).join("${name}")}\``;
+}
+
+/** The config's `persona`: the name, the role as the identity, and the core's
+ * default tone written out line by line, so the whole persona is there to edit. */
+function renderPersona(role: string): string[] {
+  return [
+    "  persona: {",
+    "    name,",
+    `    identity: ${personaLine(`You are ${ASSISTANT}, ${role.trim().replace(/\.+$/, "")}.`)},`,
+    "    tone: [",
+    ...DEFAULT_PERSONA_TONE.split("\n").map((line) => `      ${personaLine(line)},`),
+    '    ].join("\\n"),',
+    "  },",
+  ];
+}
+
+/** `locales/en.json`: the English texts of the chosen plugins' starting
+ * formatter rules (the app's own `app.` keys), `{}` when there are none. */
+function renderEnglish(tools: CatalogEntry[]): string {
+  const messages = Object.assign({}, ...tools.map((t) => t.formatter?.messages ?? {})) as Record<string, string>;
+  return Object.keys(messages).length === 0 ? "{}\n" : `${JSON.stringify(messages, null, 2)}\n`;
+}
+
+/** `mercury.config.ts`: imports, the assistant's name, the formatter helpers of
+ * the plugins that have any, then the config with the persona, each plugin
+ * (wrapped in the formatter when it has starting rules) and channel. */
 function renderConfig(
   assistantName: string,
+  role: string,
   channels: CatalogEntry[],
   auth: CatalogEntry | undefined,
   tools: CatalogEntry[],
   directory: CatalogEntry | undefined,
 ): string {
   const withRules = tools.filter((t) => t.formatter);
-  const imports = ['import { defineMercuryConfig } from "@mercury-fw/core";'];
+  const imports = ['import { defineMercuryConfig } from "@mercury-fw/core";', 'import en from "./locales/en.json";'];
   if (withRules.length > 0) {
     imports.push('import { formatterPlugin, formatter } from "@mercury-fw/formatter";');
   }
@@ -192,8 +226,6 @@ function renderConfig(
   for (const c of [...channels, ...(auth ? [auth] : []), ...(directory ? [directory] : [])]) {
     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("");
 
@@ -207,12 +239,16 @@ function renderConfig(
     CONFIG_HEADER,
     ...imports,
     "",
+    "/** The assistant's name: what the persona calls it, and every text the model reads. */",
+    `const name = ${JSON.stringify(assistantName)};`,
+    "",
     `${helpers}export default defineMercuryConfig({`,
-    `  persona: { name: ${JSON.stringify(assistantName)}, identity, tone },`,
+    ...renderPersona(role),
     plugins,
     channelList,
     ...(auth ? [`  auth: ${auth.exportName},`] : []),
     ...(directory ? [`  directory: ${directory.exportName},`] : []),
+    "  i18n: { locales: { en } },",
     "});",
     "",
   ].join("\n");
@@ -379,8 +415,8 @@ ${auth ? `- Auth: ${auth.id}\n` : ""}- Tool plugins: ${list(tools)}
 ${directory ? `- Directory: ${directory.id}\n` : ""}
 ## 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.
+- \`mercury.config.ts\`: what the app is made of (tool plugins, channels, how their lists read) and the assistant's persona: its name, who it is and how it answers. Edit them freely.
+- \`locales/\`: the texts people see, one file per language the assistant speaks. \`en.json\` overrides the English ones; add \`it.json\` (and \`it\` to \`i18n.locales\` in the config) for Italian, \`i18n.defaultLocale\` for the language people get when they haven't picked one. The app's own texts (a formatter rule's) are \`app.\` keys, written in English in \`en.json\` and translated in every other file. Mercury logs at startup the keys a file is missing.
 - \`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.
 

package/template/Dockerfile.tpl

@@ -20,8 +20,8 @@ COPY --chown=mercury:mercury .pack[s] ./.packs/
 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 mercury.config.ts ./
+COPY --chown=mercury:mercury locales ./locales
 COPY --chown=mercury:mercury src ./src
 
 # Mount points of the named volumes, owned by the runtime user before a fresh

package/template/src/repl.ts.tpl

@@ -13,6 +13,7 @@ await createTerminalProvider({
   confirmDeps: app.confirmDeps,
   ollamaHost: app.ollamaHost,
   ollamaModel: app.ollamaModel,
+  texts: app.texts,
 }).start(app.handleTurn);
 
 // The REPL ended (Ctrl+D); the model and Qdrant clients keep pooled sockets

package/template/markdown.d.ts.tpl

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