@mercury-fw/cli-engine 0.53.1 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @mercury-fw/cli-engine
 
+## 0.54.0
+
+### Minor Changes
+
+- 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 [5015642]
+  - @mercury-fw/plugin-types@0.54.0
+  - @mercury-fw/utils@0.54.0
+
+## 0.53.2
+
+### Patch Changes
+
+- @mercury-fw/plugin-types@0.53.2
+- @mercury-fw/utils@0.53.2
+
 ## 0.53.1
 
 ### Patch Changes

package/README.md

@@ -15,6 +15,6 @@ The allowlist is a JSON file the plugin ships and validates when it loads:
 }
 ```
 
-A command runs when its arguments start with one of the `prefix`es (`--help` always runs); `confirm: true` stages it until the user sends the token back. In `build()` the plugin validates the file with `parseCliConfig` and builds its tool with `createCliTool(runCli, configs, …)`; [`@mercury-fw/plugin-bitbucket`](https://github.com/lucabro81/mercury-fw/tree/main/packages/tools/plugin-bitbucket/index.ts) does exactly that.
+A command runs when its arguments start with one of the `prefix`es (`--help` always runs); `confirm: true` stages it until the user sends the token back. In `build()` the plugin validates the file with `parseCliConfig` and builds its tool with `createCliTool(runCli, configs, …)`, passing the turn's texts it gets in its session context as `t` (`t: sctx.t`); the status describer `createCliStatusDescriber` builds takes the command and the same `t`; [`@mercury-fw/plugin-bitbucket`](https://github.com/lucabro81/mercury-fw/tree/main/packages/tools/plugin-bitbucket/index.ts) does exactly that.
 
 MIT

package/cli-status.ts

@@ -7,23 +7,24 @@
  * override it (and for file-based CLIs, which aren't plugins). The core no
  * longer classifies read vs write itself; it only transports whatever the
  * describer returns. This is CLI-specific, so it lives with the CLI mechanism,
- * not in the core session layer.
+ * not in the core session layer. Every label is worded in the turn's
+ * language (`t`).
  */
-import { defaultStatusLabel, type StatusDescriber } from "@mercury-fw/plugin-types";
+import { defaultStatusLabel, type StatusDescriber, type Translate } from "@mercury-fw/plugin-types";
 import { parseCommand } from "./command-parser.ts";
 import { matchCommand, type CliConfig } from "./cli-tool.ts";
 
 export function createCliStatusDescriber(
   configs: Record<string, CliConfig>,
   describers: Record<string, StatusDescriber>,
-): (command: string) => string {
-  return (command) => {
+): (command: string, t: Translate) => string {
+  return (command, t) => {
     const parsed = parseCommand(command);
-    if (!parsed.ok) return "esecuzione di un comando";
+    if (!parsed.ok) return t("core.status.command-unknown");
     const config = configs[parsed.binary];
     const match = config ? matchCommand(parsed.args, config) : undefined;
     const mutating = match !== undefined && match.kind !== "not-allowed" ? match.mutating : false;
     const describe = describers[parsed.binary] ?? defaultStatusLabel;
-    return describe({ binary: parsed.binary, args: parsed.args, mutating });
+    return describe({ binary: parsed.binary, args: parsed.args, mutating }, t);
   };
 }

package/cli-tool.ts

@@ -32,7 +32,7 @@ import { cliUserId } from "@mercury-fw/utils";
 // for the core callers that import it from this module. It runs after every
 // allowed command and is told which allowlist prefix matched, so the plugin
 // decides what to touch; cli-tool.ts never knows what it does.
-import type { CliPostProcessor } from "@mercury-fw/plugin-types";
+import type { CliPostProcessor, Translate } from "@mercury-fw/plugin-types";
 export type { CliPostProcessor };
 
 export type AllowedCommand = {
@@ -168,6 +168,8 @@ export function createCliTool(
      * allowed command's result with the matched prefix — `cli-tool.ts` itself
      * never knows what it does. */
     postProcess?: CliPostProcessor;
+    /** The texts of the turn's person (`SessionToolContext.t`), handed to the post-processor. */
+    t: Translate;
     /** Stashes a post-processor's rendered `display` artifact and returns a ref
      * the model can `present`. Pre-bound to this turn's session by the
      * composition root. Optional: with none wired the inline `display` is left
@@ -261,7 +263,7 @@ export function createCliTool(
         return opts.requireLogin();
       }
       const processed = opts.postProcess
-        ? opts.postProcess({ binary: parsed.binary, args: parsed.args, prefix: match.prefix }, result)
+        ? opts.postProcess({ binary: parsed.binary, args: parsed.args, prefix: match.prefix }, result, opts.t)
         : result;
 
       // A rendered display artifact is stashed, not returned to be

package/dist/cli-status.d.ts

@@ -7,8 +7,9 @@
  * override it (and for file-based CLIs, which aren't plugins). The core no
  * longer classifies read vs write itself; it only transports whatever the
  * describer returns. This is CLI-specific, so it lives with the CLI mechanism,
- * not in the core session layer.
+ * not in the core session layer. Every label is worded in the turn's
+ * language (`t`).
  */
-import { type StatusDescriber } from "@mercury-fw/plugin-types";
+import { type StatusDescriber, type Translate } from "@mercury-fw/plugin-types";
 import { type CliConfig } from "./cli-tool.ts";
-export declare function createCliStatusDescriber(configs: Record<string, CliConfig>, describers: Record<string, StatusDescriber>): (command: string) => string;
+export declare function createCliStatusDescriber(configs: Record<string, CliConfig>, describers: Record<string, StatusDescriber>): (command: string, t: Translate) => string;

package/dist/cli-tool.d.ts

@@ -1,6 +1,6 @@
 import { type runCli } from "./cli-executor.ts";
 import type { StageConfirmation, ExecutableTool, LoginRequired } from "@mercury-fw/plugin-types";
-import type { CliPostProcessor } from "@mercury-fw/plugin-types";
+import type { CliPostProcessor, Translate } from "@mercury-fw/plugin-types";
 export type { CliPostProcessor };
 export type AllowedCommand = {
     prefix: string[];
@@ -97,6 +97,8 @@ export declare function createCliTool(runCliFn: typeof runCli, configs: Record<s
      * allowed command's result with the matched prefix — `cli-tool.ts` itself
      * never knows what it does. */
     postProcess?: CliPostProcessor;
+    /** The texts of the turn's person (`SessionToolContext.t`), handed to the post-processor. */
+    t: Translate;
     /** Stashes a post-processor's rendered `display` artifact and returns a ref
      * the model can `present`. Pre-bound to this turn's session by the
      * composition root. Optional: with none wired the inline `display` is left

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli-engine",
-  "version": "0.53.1",
+  "version": "0.54.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,8 +23,8 @@
     }
   },
   "dependencies": {
-    "@mercury-fw/plugin-types": "0.53.1",
-    "@mercury-fw/utils": "0.53.1",
+    "@mercury-fw/plugin-types": "0.54.0",
+    "@mercury-fw/utils": "0.54.0",
     "ai": "^7.0.126",
     "shell-quote": "^1.11.0",
     "zod": "^4.6.5"