@mercury-fw/formatter 0.53.2 → 0.55.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @mercury-fw/formatter
 
+## 0.55.0
+
+### Patch Changes
+
+- Updated dependencies [eac72fa]
+  - @mercury-fw/plugin-types@0.55.0
+
+## 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
+
 ## 0.53.2
 
 ### Patch Changes

package/README.md

@@ -21,7 +21,7 @@ export default defineMercuryConfig({
 });
 ```
 
-- `formatter<D>(rules)` takes one rule per kind of list, keyed by the kinds the plugin declares (`D`, e.g. `JiraDisplays`), so a kind it doesn't emit or a rule for the wrong item shape fails the typecheck. A rule is the line for each item, or `{ item, empty }` when an empty list needs a text of its own. Items are joined with a blank line.
+- `formatter<D>(rules)` takes one rule per kind of list, keyed by the kinds the plugin declares (`D`, e.g. `JiraDisplays`), so a kind it doesn't emit or a rule for the wrong item shape fails the typecheck. A rule is the line for each item, or `{ item, empty }` when an empty list needs a text of its own. Items are joined with a blank line. A rule also gets `t`, the texts of the person the turn is for, as its second argument (`(issue, t) => …`), and `empty` can be a function of it (`(t) => t("app.jira.no-issues")`, the key in the app's `locales/en.json` and its other language files), so an app that speaks several languages writes its lists in each person's.
 - `formatterPlugin(plugin, handler)` wraps a plugin so every list it hands over goes through the rules; everything else the plugin contributes passes through untouched.
 
 MIT

package/dist/index.d.ts

@@ -11,16 +11,17 @@
  *   its post-processor emits goes through the handler; everything else the
  *   plugin contributes passes through untouched.
  */
-import type { Plugin, ToolDisplay } from "@mercury-fw/plugin-types";
-/** Renders one display into the single text block shown to the user, or
- * returns `undefined` when there is nothing to show (no rule for its kind, or
- * an empty list with no empty text). */
-export type DisplayHandler = (display: ToolDisplay) => string | undefined;
+import type { Plugin, ToolDisplay, Translate } from "@mercury-fw/plugin-types";
+/** Renders one display into the single text block shown to the user, in the
+ * turn's language (`t`), or returns `undefined` when there is nothing to show
+ * (no rule for its kind, or an empty list with no empty text). */
+export type DisplayHandler = (display: ToolDisplay, t: Translate) => string | undefined;
 /** How one kind of list is rendered: the line for each item, or that plus the
- * text to show when the list is empty. */
-export type FormatterRule<T> = ((item: T) => string) | {
-    item: (item: T) => string;
-    empty?: string;
+ * text to show when the list is empty. Both may use `t`, the texts of the
+ * person the turn is for (an app's own keys in its language files). */
+export type FormatterRule<T> = ((item: T, t: Translate) => string) | {
+    item: (item: T, t: Translate) => string;
+    empty?: string | ((t: Translate) => string);
 };
 /**
  * Builds a handler from the instance's rules. `D` is the data plugin's map of

package/index.ts

@@ -11,16 +11,19 @@
  *   its post-processor emits goes through the handler; everything else the
  *   plugin contributes passes through untouched.
  */
-import type { Plugin, CliPostProcessor, CliResult, ToolDisplay } from "@mercury-fw/plugin-types";
+import type { Plugin, CliPostProcessor, CliResult, ToolDisplay, Translate } from "@mercury-fw/plugin-types";
 
-/** Renders one display into the single text block shown to the user, or
- * returns `undefined` when there is nothing to show (no rule for its kind, or
- * an empty list with no empty text). */
-export type DisplayHandler = (display: ToolDisplay) => string | undefined;
+/** Renders one display into the single text block shown to the user, in the
+ * turn's language (`t`), or returns `undefined` when there is nothing to show
+ * (no rule for its kind, or an empty list with no empty text). */
+export type DisplayHandler = (display: ToolDisplay, t: Translate) => string | undefined;
 
 /** How one kind of list is rendered: the line for each item, or that plus the
- * text to show when the list is empty. */
-export type FormatterRule<T> = ((item: T) => string) | { item: (item: T) => string; empty?: string };
+ * text to show when the list is empty. Both may use `t`, the texts of the
+ * person the turn is for (an app's own keys in its language files). */
+export type FormatterRule<T> =
+  | ((item: T, t: Translate) => string)
+  | { item: (item: T, t: Translate) => string; empty?: string | ((t: Translate) => string) };
 
 /** Items are rendered one per block, separated by a blank line. */
 const ITEM_SEPARATOR = "\n\n";
@@ -33,16 +36,16 @@ const ITEM_SEPARATOR = "\n\n";
  */
 export function formatter<D>(rules: { [K in keyof D]?: FormatterRule<D[K]> }): DisplayHandler {
   const byKind = rules as Record<string, FormatterRule<unknown> | undefined>;
-  return (display) => {
+  return (display, t) => {
     const rule = byKind[display.type];
     if (rule === undefined) {
       return undefined;
     }
     const { item, empty } = typeof rule === "function" ? { item: rule, empty: undefined } : rule;
     if (display.items.length === 0) {
-      return empty;
+      return typeof empty === "function" ? empty(t) : empty;
     }
-    return display.items.map((i) => item(i)).join(ITEM_SEPARATOR);
+    return display.items.map((i) => item(i, t)).join(ITEM_SEPARATOR);
   };
 }
 
@@ -51,11 +54,17 @@ export function formatter<D>(rules: { [K in keyof D]?: FormatterRule<D[K]> }): D
  * non-empty list with no rule stays structured (so it isn't shown) and is
  * reported through `log`. Non-ok results and results with no display are
  * returned as they are, without calling the handler. */
-function renderDisplay(result: CliResult, handler: DisplayHandler, log: (m: string) => void, pluginName: string): CliResult {
+function renderDisplay(
+  result: CliResult,
+  handler: DisplayHandler,
+  t: Translate,
+  log: (m: string) => void,
+  pluginName: string,
+): CliResult {
   if (!result.ok || !result.display) {
     return result;
   }
-  const text = handler(result.display);
+  const text = handler(result.display, t);
   if (text !== undefined) {
     return { ...result, display: { ...result.display, items: [text] } };
   }
@@ -81,7 +90,7 @@ export function formatterPlugin(plugin: Plugin, handler: DisplayHandler): Plugin
       const inner = plugin.build ? plugin.build(ctx) : {};
       const proc = inner.postProcess;
       const wrapped: CliPostProcessor | undefined = proc
-        ? (cmd, result) => renderDisplay(proc(cmd, result), handler, ctx.log, plugin.name)
+        ? (cmd, result, t) => renderDisplay(proc(cmd, result, t), handler, t, ctx.log, plugin.name)
         : undefined;
       return { ...inner, postProcess: wrapped };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/formatter",
-  "version": "0.53.2",
+  "version": "0.55.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@mercury-fw/plugin-types": "0.53.2"
+    "@mercury-fw/plugin-types": "0.55.0"
   },
   "devDependencies": {
     "@mercury-fw/typescript-config": "*",