@mercury-fw/formatter 0.25.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @mercury-fw/formatter
+
+## 0.25.0
+
+### Patch Changes
+
+- @mercury-fw/plugin-types@0.25.0

package/README.md

@@ -0,0 +1,27 @@
+# @mercury-fw/formatter
+
+Turns the lists a [Mercury](https://github.com/lucabro81/mercury-fw) plugin hands the user into text, applying rules the app writes in its own config. It holds no format of its own: without a rule, a kind of list isn't shown (the model still gets the data, and the log says which rule is missing).
+
+```ts
+import { formatterPlugin, formatter } from "@mercury-fw/formatter";
+import { jiraPlugin, type JiraDisplays } from "@mercury-fw/plugin-jira";
+
+const jiraIssueLine = (issue: JiraDisplays["issue-list"]) =>
+  `${issue.key} ${issue.status ? `[${issue.status}] ` : ""}${issue.summary}\n${issue.url}`;
+
+export default defineMercuryConfig({
+  plugins: [
+    formatterPlugin(
+      jiraPlugin,
+      formatter<JiraDisplays>({
+        "issue-list": { item: jiraIssueLine, empty: "No matching issues." },
+      }),
+    ),
+  ],
+});
+```
+
+- `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.
+- `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

@@ -0,0 +1,41 @@
+/**
+ * The formatter: turns the structured lists a data plugin hands to the user
+ * (its `display` channel) into text, by applying a rule the instance writes in
+ * its own config. It holds no format knowledge of its own — every rule comes
+ * from the config, keyed by the display's kind — and it knows no plugin: a data
+ * plugin declares the kinds it emits as a type, which is what keeps the
+ * config's keys and item shapes checked at compile time.
+ *
+ * - `formatter(rules)` builds a `DisplayHandler` from a `kind → rule` map.
+ * - `formatterPlugin(plugin, handler)` wraps a data plugin so every display
+ *   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;
+/** 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;
+};
+/**
+ * Builds a handler from the instance's rules. `D` is the data plugin's map of
+ * the kinds it emits to their item shapes (e.g. `JiraDisplays`), so a key it
+ * doesn't declare, or a rule for the wrong item shape, fails the typecheck.
+ * Every rule is optional: a kind without one has nothing to show.
+ */
+export declare function formatter<D>(rules: {
+    [K in keyof D]?: FormatterRule<D[K]>;
+}): DisplayHandler;
+/**
+ * Wraps `plugin` so its post-processor's displays are rendered through
+ * `handler`. Returns a plugin identical to `plugin` except for a `build` that
+ * runs the inner `build` (passing the runtime context straight through) and
+ * wraps the post-processor it contributes; the wrapped one flows to the
+ * plugin's `sessionTools` factory, which the composition hands it to.
+ */
+export declare function formatterPlugin(plugin: Plugin, handler: DisplayHandler): Plugin;

package/index.ts

@@ -0,0 +1,89 @@
+/**
+ * The formatter: turns the structured lists a data plugin hands to the user
+ * (its `display` channel) into text, by applying a rule the instance writes in
+ * its own config. It holds no format knowledge of its own — every rule comes
+ * from the config, keyed by the display's kind — and it knows no plugin: a data
+ * plugin declares the kinds it emits as a type, which is what keeps the
+ * config's keys and item shapes checked at compile time.
+ *
+ * - `formatter(rules)` builds a `DisplayHandler` from a `kind → rule` map.
+ * - `formatterPlugin(plugin, handler)` wraps a data plugin so every display
+ *   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";
+
+/** 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;
+
+/** 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 };
+
+/** Items are rendered one per block, separated by a blank line. */
+const ITEM_SEPARATOR = "\n\n";
+
+/**
+ * Builds a handler from the instance's rules. `D` is the data plugin's map of
+ * the kinds it emits to their item shapes (e.g. `JiraDisplays`), so a key it
+ * doesn't declare, or a rule for the wrong item shape, fails the typecheck.
+ * Every rule is optional: a kind without one has nothing to show.
+ */
+export function formatter<D>(rules: { [K in keyof D]?: FormatterRule<D[K]> }): DisplayHandler {
+  const byKind = rules as Record<string, FormatterRule<unknown> | undefined>;
+  return (display) => {
+    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 display.items.map((i) => item(i)).join(ITEM_SEPARATOR);
+  };
+}
+
+/** Applies `handler` to an ok result's display. A rendered block replaces the
+ * structured items; an empty list with nothing to show drops the display; a
+ * 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 {
+  if (!result.ok || !result.display) {
+    return result;
+  }
+  const text = handler(result.display);
+  if (text !== undefined) {
+    return { ...result, display: { ...result.display, items: [text] } };
+  }
+  if (result.display.items.length === 0) {
+    const { display: _dropped, ...rest } = result;
+    return rest;
+  }
+  log(`[formatter] no rule for "${result.display.type}" lists from plugin "${pluginName}" — list not shown`);
+  return result;
+}
+
+/**
+ * Wraps `plugin` so its post-processor's displays are rendered through
+ * `handler`. Returns a plugin identical to `plugin` except for a `build` that
+ * runs the inner `build` (passing the runtime context straight through) and
+ * wraps the post-processor it contributes; the wrapped one flows to the
+ * plugin's `sessionTools` factory, which the composition hands it to.
+ */
+export function formatterPlugin(plugin: Plugin, handler: DisplayHandler): Plugin {
+  return {
+    ...plugin,
+    build: (ctx) => {
+      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)
+        : undefined;
+      return { ...inner, postProcess: wrapped };
+    },
+  };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mercury-fw/formatter",
+  "version": "0.25.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "packages/formatters/formatter"
+  },
+  "files": [
+    "*.ts",
+    "dist",
+    "CHANGELOG.md",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "mercury-fw-source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mercury-fw/plugin-types": "0.25.0"
+  },
+  "devDependencies": {
+    "@mercury-fw/typescript-config": "*",
+    "@types/bun": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}