@mercury-fw/cli-engine 0.25.0

package/CHANGELOG.md

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

package/README.md

@@ -0,0 +1,20 @@
+# @mercury-fw/cli-engine
+
+For [Mercury](https://github.com/lucabro81/mercury-fw) plugins that work through a command-line tool: it turns the command line the model writes into an argv array of its own (never a shell), runs it only when it matches the plugin's allowlist, and stages the commands the allowlist marks as needing confirmation behind a one-time token instead of running them.
+
+The allowlist is a JSON file the plugin ships and validates when it loads:
+
+```json
+{
+  "binary": "bitbucket",
+  "commands": [
+    { "prefix": ["pr", "list"], "confirm": false, "mutating": false },
+    { "prefix": ["pr", "merge"], "confirm": true, "mutating": true }
+  ],
+  "globalFlags": [{ "flag": "--select", "takesValue": true }]
+}
+```
+
+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.
+
+MIT

package/cli-config-loader.ts

@@ -0,0 +1,73 @@
+/**
+ * Validates a maintainer-authored CLI allowlist into the internal `CliConfig`
+ * that `cli-tool.ts` consumes. A plugin owns its allowlist as data and hands
+ * the already-parsed object over (via `loadCliConfigFromObject` or the
+ * synchronous `parseCliConfig`); the safety barrier is a strict Zod schema and,
+ * when `minVersion` is declared, a `--version` check. Every failure mode is
+ * fail-closed: a schema violation or an unmet `minVersion` returns
+ * `{ ok: false, reason }`, never a thrown exception or a partially-applied
+ * config. The maintainer who declares a plugin is already fully trusted with
+ * the machine, so the config is data to validate, not a policy to second-guess
+ * beyond schema/version checks.
+ */
+import { CliConfigFileSchema, type CliConfigFile } from "./cli-config-schema.ts";
+import { checkCliVersion } from "./cli-version-check.ts";
+import type { runCli } from "./cli-executor.ts";
+import type { CliConfig } from "./cli-tool.ts";
+
+/** Maps the external file shape into the internal runtime `CliConfig`
+ * shape `src/tools/cli-tool.ts` consumes. */
+export function toCliConfig(raw: CliConfigFile): CliConfig {
+  return {
+    allowedPrefixes: raw.commands.map((c) => ({ prefix: c.prefix, confirm: c.confirm, mutating: c.mutating })),
+    globalFlags: raw.globalFlags,
+  };
+}
+
+export type CliConfigFromObjectResult =
+  | { ok: true; binary: string; config: CliConfig }
+  | { ok: false; reason: string };
+
+/**
+ * Validates a plugin's already-parsed allowlist object: the same `.strict()` Zod
+ * schema and, when `minVersion` is declared, a `--version` check, so a plugin's
+ * config reaches `runCommand`'s allowlist through the full validation. No
+ * requested-vs-declared binary match: the plugin declares its own binary and
+ * there's no separate name to reconcile it against, so the validated `binary` is
+ * returned for the caller to key its map by. Never throws.
+ */
+export async function loadCliConfigFromObject(
+  raw: unknown,
+  opts: { runCliFn: typeof runCli },
+): Promise<CliConfigFromObjectResult> {
+  const validated = CliConfigFileSchema.safeParse(raw);
+  if (!validated.success) {
+    const issues = validated.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    return { ok: false, reason: `plugin config does not match the expected schema: ${issues}` };
+  }
+
+  if (validated.data.minVersion) {
+    const versionResult = await checkCliVersion(validated.data.binary, validated.data.minVersion, opts.runCliFn);
+    if (!versionResult.ok) {
+      return { ok: false, reason: versionResult.reason };
+    }
+  }
+
+  return { ok: true, binary: validated.data.binary, config: toCliConfig(validated.data) };
+}
+
+/**
+ * The synchronous, no-spawn sibling of `loadCliConfigFromObject`: schema
+ * validation only, skipping the `minVersion` `--version` check. It's what a
+ * plugin uses on its own allowlist in `build()` — a plugin ships its pinned CLI
+ * binary alongside its allowlist, so the two are co-versioned by construction
+ * and the runtime version check earns nothing there. Never throws.
+ */
+export function parseCliConfig(raw: unknown): CliConfigFromObjectResult {
+  const validated = CliConfigFileSchema.safeParse(raw);
+  if (!validated.success) {
+    const issues = validated.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    return { ok: false, reason: `plugin config does not match the expected schema: ${issues}` };
+  }
+  return { ok: true, binary: validated.data.binary, config: toCliConfig(validated.data) };
+}

package/cli-config-schema.ts

@@ -0,0 +1,44 @@
+/**
+ * Zod schema for the externally-configured, maintainer-authored CLI
+ * config file (e.g. `cli-configs/jira.json`), consumed by
+ * `src/tools/cli-config-loader.ts`. Kept in its own module, separate
+ * from the loader, so the schema itself is unit-testable without any
+ * file I/O.
+ *
+ * `.strict()` on every object level: a maintainer typo (e.g.
+ * `"prefixes"` instead of `"prefix"`) must fail validation loudly, not
+ * silently pass through as an ignored extra key — the whole point of
+ * this schema is to be the one thing standing between a maintainer's
+ * config and what the model can execute, so silent tolerance of
+ * malformed input is exactly what it must not do.
+ */
+import { z } from "zod";
+
+export const CliCommandSchema = z
+  .object({
+    prefix: z.array(z.string().min(1)).min(1),
+    confirm: z.boolean(),
+    /** Whether this command changes state on the external service (Jira,
+     * etc.) rather than just reading it — distinct from `confirm`: a
+     * command can mutate without requiring confirmation (e.g. create). */
+    mutating: z.boolean(),
+  })
+  .strict();
+
+export const CliGlobalFlagSchema = z
+  .object({
+    flag: z.string().min(1),
+    takesValue: z.boolean(),
+  })
+  .strict();
+
+export const CliConfigFileSchema = z
+  .object({
+    binary: z.string().min(1),
+    minVersion: z.string().min(1).optional(),
+    commands: z.array(CliCommandSchema).min(1),
+    globalFlags: z.array(CliGlobalFlagSchema).optional(),
+  })
+  .strict();
+
+export type CliConfigFile = z.infer<typeof CliConfigFileSchema>;

package/cli-executor.ts

@@ -0,0 +1,83 @@
+/**
+ * Generic subprocess runner for the external CLI binaries Mercury talks
+ * to (jira, google-chat, ...). Every external integration is a separate
+ * CLI binary invoked as a subprocess — never an arbitrary shell string,
+ * never MCP. This file is the one and only place that spawns a process,
+ * in the one shape Mercury needs: a one-shot command that exits and
+ * produces a single parsed output (`runCli`).
+ *
+ * Nothing imports `runCli` to call it directly except the composition root:
+ * every consumer declares it as a `typeof runCli` dependency and receives
+ * it injected, so a test can supply a fake without spawning a subprocess.
+ * `cli-tool.ts` (`runCommand`'s `execute`) and
+ * `@mercury-fw/confirm-engine`'s `confirm-flow.ts` (the second half of the confirm
+ * flow) are the two that actually run model-requested commands; the rest use it for
+ * version checks and diagnostics. The registered
+ * Google Chat provider (`@mercury-fw/channel-google-chat`) does not use this module at all — it talks to
+ * the Chat REST API and Pub/Sub directly over HTTPS, never through a CLI
+ * subprocess (see `google-chat-app-client.ts`).
+ */
+
+// `CliResult` is part of the plugin contract (a post-processor receives and
+// returns one), so it lives in `@mercury-fw/plugin-types` and is re-exported here
+// for the many core callers that import it from this module. Never throws —
+// callers branch on `ok` instead of catching.
+import type { CliResult } from "@mercury-fw/plugin-types";
+export type { CliResult };
+
+/**
+ * Thin wrapper around `Bun.spawn` with both stdout and stderr piped.
+ * Extracted into its own function (rather than calling `Bun.spawn`
+ * inline in `runCli`) so its return type carries the literal `"pipe"`
+ * option through to the caller — assigning the spawn call to a
+ * pre-declared `ReturnType<typeof Bun.spawn>` variable would otherwise
+ * widen `stdout`/`stderr` to a generic union TypeScript can't narrow.
+ */
+function spawnPiped(binary: string, args: string[]) {
+  return Bun.spawn([binary, ...args], { stdout: "pipe", stderr: "pipe" });
+}
+
+/**
+ * Runs `binary` with `args`, waits for it to exit, and parses its
+ * stdout as JSON when possible.
+ *
+ * Resolves to `{ ok: false, error }` — never rejects/throws — for the
+ * binary not existing on `PATH` or a non-zero exit code (the error
+ * includes the exit code and stderr). Success is exit code 0, full stop:
+ * if stdout happens to be valid JSON it's parsed into `data`, otherwise
+ * the raw trimmed text is `data` instead. Non-JSON stdout on a 0 exit is
+ * not a parse failure — `--help` output is exactly this shape (plain
+ * text, exit 0), and treating it as `ok: false` meant the model saw a
+ * "failed" tool call for what was actually a successful discovery call —
+ * observed live to send it into a confused, apologetic retry spiral.
+ */
+export async function runCli(
+  binary: string,
+  args: string[],
+): Promise<CliResult> {
+  let proc: ReturnType<typeof spawnPiped>;
+  try {
+    proc = spawnPiped(binary, args);
+  } catch (err) {
+    return { ok: false, error: `failed to spawn ${binary}: ${String(err)}` };
+  }
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  if (exitCode !== 0) {
+    return {
+      ok: false,
+      error: `${binary} exited with code ${exitCode}: ${stderr.trim()}`,
+    };
+  }
+
+  try {
+    return { ok: true, data: JSON.parse(stdout) };
+  } catch {
+    return { ok: true, data: stdout.trim() };
+  }
+}

package/cli-status.ts

@@ -0,0 +1,29 @@
+/**
+ * Builds the `runCommand` status describer the composition root injects into
+ * the core's tool-start hook. It parses the command, computes whether it
+ * mutates from the same allowlist that gates execution (via `matchCommand`, so
+ * the label can never drift from what actually runs), and hands that to the
+ * command's plugin describer — or `defaultStatusLabel` when the plugin doesn't
+ * 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.
+ */
+import { defaultStatusLabel, type StatusDescriber } 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) => {
+    const parsed = parseCommand(command);
+    if (!parsed.ok) return "esecuzione di un comando";
+    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 });
+  };
+}

package/cli-tool.ts

@@ -0,0 +1,254 @@
+/**
+ * The generic, cross-CLI model-invocable tool for the experimental
+ * command-string execution model: the model writes an entire CLI
+ * invocation as one free-text string (see `src/tools/command-parser.ts`
+ * for how that string becomes a binary + argv), and this module validates
+ * it — first that the binary is one this Mercury instance actually has a
+ * config for, then that the argv shape matches that binary's own
+ * allowed-prefix allowlist — before ever executing anything.
+ *
+ * `CliConfig` is built from a maintainer-authored external config file
+ * (see `src/tools/cli-config-loader.ts`), not hand-written TypeScript —
+ * `allowedPrefixes` is the default-deny prefix-matching data (each entry
+ * also declares whether it needs a confirmation step that doesn't exist
+ * yet, see `matchCommand` below), and `globalFlags` is declarative data
+ * for CLI-specific pre-processing (e.g. jira's global `--select` flag,
+ * which can appear before the subcommand) consumed generically by
+ * `stripGlobalFlags` — no more hand-written per-CLI stripping function.
+ *
+ * Used by: `src/index.ts` (wiring), which builds the `Record<string,
+ * CliConfig>` (via `cli-config-loader.ts`) from whichever CLIs are
+ * enabled on a given instance and passes it into `createCliTool`
+ * alongside the real `runCli`.
+ */
+import { tool, type JSONValue } from "ai";
+import { z } from "zod";
+import { parseCommand } from "./command-parser.ts";
+import type { runCli, CliResult } from "./cli-executor.ts";
+import type { StageConfirmation, ExecutableTool } from "@mercury-fw/plugin-types";
+
+// `CliPostProcessor` is part of the plugin contract (a plugin's `build()`
+// returns one) — it lives in `@mercury-fw/plugin-types` and is re-exported here
+// 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";
+export type { CliPostProcessor };
+
+export type AllowedCommand = {
+  prefix: string[];
+  confirm: boolean;
+  mutating: boolean;
+};
+export type GlobalFlag = { flag: string; takesValue: boolean };
+
+export type CliConfig = {
+  allowedPrefixes: AllowedCommand[];
+  /** Optional declarative global flags (can appear anywhere in argv, not
+   * just after the prefix) to strip before prefix-matching. */
+  globalFlags?: GlobalFlag[];
+};
+
+/**
+ * Removes every occurrence of any flag listed in `globalFlags` from
+ * `args` (and its value too, if `takesValue`), wherever it appears —
+ * generic replacement for what used to be a hand-written per-CLI
+ * function (jira's old `stripSelectFlag`). Used only to build a
+ * throwaway copy for prefix-matching in `matchCommand`; the original
+ * `args` (flags included) is always what actually gets executed.
+ */
+export function stripGlobalFlags(args: string[], globalFlags: GlobalFlag[]): string[] {
+  const result: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const match = globalFlags.find((gf) => gf.flag === args[i]);
+    if (match) {
+      if (match.takesValue) i++; // also skip its value
+      continue;
+    }
+    result.push(args[i] as string);
+  }
+  return result;
+}
+
+export type CommandMatch =
+  | { kind: "allowed"; prefix: string[]; mutating: boolean }
+  | { kind: "confirm-required"; prefix: string[]; mutating: boolean }
+  | { kind: "not-allowed" };
+
+/**
+ * Classifies `args` under `config`: `--help` is always `allowed`
+ * (discovery, not execution); otherwise `args` (after `config.globalFlags`
+ * stripping, if any) is matched positionally against `config.allowedPrefixes`
+ * — no match is `not-allowed`, a match with `confirm: false` is `allowed`,
+ * a match with `confirm: true` is `confirm-required` (the shape is
+ * recognized, but there's no confirmation mechanism to gate it on yet).
+ * `mutating` is carried through independently of `confirm` — a command can
+ * change external state (Jira, etc.) without requiring confirmation (e.g.
+ * create), so the two flags are never derived from one another. An allowed
+ * match reports the prefix it matched (`[]` for `--help`), which is what a
+ * plugin's post-processor decides on.
+ */
+export function matchCommand(args: string[], config: CliConfig): CommandMatch {
+  if (args[args.length - 1] === "--help") {
+    return { kind: "allowed", prefix: [], mutating: false };
+  }
+  const stripped = config.globalFlags ? stripGlobalFlags(args, config.globalFlags) : args;
+  const match = config.allowedPrefixes.find((c) => c.prefix.every((part, i) => stripped[i] === part));
+  if (!match) {
+    return { kind: "not-allowed" };
+  }
+  return match.confirm
+    ? { kind: "confirm-required", prefix: match.prefix, mutating: match.mutating }
+    : { kind: "allowed", prefix: match.prefix, mutating: match.mutating };
+}
+
+/** Renders a list of prefixes as a comma-separated string for a
+ * model-readable rejection message, e.g. `"issue search, issue get"`. */
+export function formatPrefixes(prefixes: string[][]): string {
+  return prefixes.map((p) => p.join(" ")).join(", ");
+}
+
+/**
+ * Removes the top-level `display` channel (see `ToolDisplay`) from a tool
+ * result before it reaches the model. `display` is the user-facing channel —
+ * a deterministic artifact stashed in the display store and shown only when the
+ * model calls `present` (see `display-store.ts`/`present-tool.ts`), never
+ * something the model needs to read or reproduce. The model channel is `data`
+ * plus the `displayRef` pointer (kept, so the model can `present` it), so this
+ * is a structural drop of one known top-level key — not a heuristic removal of
+ * a field nested inside `data`. Model-facing notes a plugin adds inside `data`
+ * (e.g. `formattedListNote`, telling the model why formatting couldn't happen
+ * and how to retry) are on the model channel and pass through.
+ */
+export function omitDisplayForModel(output: unknown): unknown {
+  if (typeof output !== "object" || output === null || !("display" in output)) return output;
+  const { display: _display, ...rest } = output as Record<string, unknown>;
+  return rest;
+}
+
+/**
+ * Builds the `runCommand` tool: the model writes a whole CLI invocation as
+ * one string, `execute` parses it (`parseCommand`), checks the binary
+ * against `configs`, then classifies the argv via `matchCommand` — each
+ * failure mode (unparseable / unknown binary / confirm-required /
+ * not-allowed) gets a distinct, self-correctable error message — before
+ * ever calling `runCliFn`. `runCliFn` is injected (defaulting to the real
+ * `runCli` in production) so tests can supply a fake without spawning a
+ * real subprocess.
+ *
+ * `opts.stageConfirmation` scopes the confirm-required branch: a confirm-gated
+ * command is staged (see `confirmation-staging.ts`) instead of running, and the
+ * result carries a structured `token` — how the user is actually told to
+ * confirm is channel-specific (a card button on Google Chat, a bare token typed
+ * on the terminal), not dictated here or by the model (see `confirm-flow.ts` for
+ * the other half — actually running it once that token comes back). Staging is
+ * inherently per-session (the closure is bound to one sessionKey), so callers
+ * must build a fresh tool per turn, scoped to that turn's own session — not a
+ * tool meant to be built once and reused across sessions.
+ */
+export function createCliTool(
+  runCliFn: typeof runCli,
+  configs: Record<string, CliConfig>,
+  opts: {
+    /** Stages a confirm-required command's execution behind a token, and writes
+     * its paper-trail note (see `StageConfirmation`). Pre-bound to this turn's
+     * session/user by the composition root — `cli-tool.ts` never touches the
+     * confirmation store or the wiki itself. */
+    stageConfirmation: StageConfirmation;
+    /** The plugin's post-processor (see `CliPostProcessor`), run on every
+     * allowed command's result with the matched prefix — `cli-tool.ts` itself
+     * never knows what it does. */
+    postProcess?: CliPostProcessor;
+    /** 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
+     * untouched and no `displayRef` is minted. */
+    stashDisplay?: (artifact: string) => string;
+  },
+): { runCommand: ExecutableTool } {
+  // Anchor the example on a binary actually enabled on this instance rather than
+  // a hardcoded one: a fixed `jira …` example misleads the model on an instance
+  // without Jira. The concrete, CLI-specific example (real subcommand + flags)
+  // belongs to that CLI's own skill, not to this plugin-agnostic tool.
+  const exampleBinary = Object.keys(configs)[0] ?? "<binary>";
+  const runCommand = tool({
+    description:
+      "Run a CLI command. Write the whole invocation as one string, exactly as you would type it in a terminal, " +
+      `e.g. \`${exampleBinary} <subcommand> --flag value\`. Quote values that contain spaces.`,
+    inputSchema: z.object({ command: z.string().min(1) }),
+    execute: async ({ command }) => {
+      const parsed = parseCommand(command);
+      if (!parsed.ok) {
+        return { ok: false, error: `could not parse "${command}": ${parsed.error}` };
+      }
+
+      const config = configs[parsed.binary];
+      if (!config) {
+        const known = Object.keys(configs).join(", ") || "(none configured)";
+        return {
+          ok: false,
+          error: `unknown or disabled CLI "${parsed.binary}" on this Mercury instance. Available: ${known}.`,
+        };
+      }
+
+      const match = matchCommand(parsed.args, config);
+      if (match.kind === "not-allowed") {
+        const validPrefixes = formatPrefixes(
+          config.allowedPrefixes.filter((c) => !c.confirm).map((c) => c.prefix),
+        );
+        return {
+          ok: false,
+          error: `not permitted on this Mercury instance. Valid commands: ${validPrefixes}. If "${parsed.args.join(" ")}" doesn't match one of these, it's not a recognized command shape — try again with the right prefix, or run --help to check.`,
+        };
+      }
+      if (match.kind === "confirm-required") {
+        // The underlying CLI has its own, separate --confirm safety flag
+        // (jira-cli/google-chat-cli both refuse a delete without it) —
+        // independent of Mercury's own token. Once a human confirms
+        // through Mercury, that flag must actually be there when the
+        // staged args run, regardless of whether the model remembered to
+        // include it on the first attempt (observed live: it usually
+        // doesn't).
+        const argsToStage = parsed.args.includes("--confirm") ? parsed.args : [...parsed.args, "--confirm"];
+        // Stage the doing as an opaque thunk — the core confirmation subsystem
+        // never learns this is a CLI command. `describe` (the normalized argv)
+        // is the paper-trail text; `summary` on the result (the raw command the
+        // model wrote) is what a channel shows in its confirmation UI.
+        const token = await opts.stageConfirmation({
+          run: () => runCliFn(parsed.binary, argsToStage),
+          describe: [parsed.binary, ...argsToStage].join(" "),
+        });
+        return {
+          ok: false,
+          pendingConfirmation: true,
+          token,
+          summary: command,
+          error: `"${match.prefix.join(" ")}" is irreversible and requires explicit confirmation before it can run. Tell the user this action is staged and awaiting their confirmation. Never mention the token value in your reply, in any form — do not tell them how to confirm it, the channel handles that on its own.`,
+        };
+      }
+
+      const result = await runCliFn(parsed.binary, parsed.args);
+      const processed = opts.postProcess
+        ? opts.postProcess({ binary: parsed.binary, args: parsed.args, prefix: match.prefix }, result)
+        : result;
+
+      // A rendered display artifact is stashed, not returned to be
+      // force-appended: the model gets only a `displayRef` and decides whether
+      // to `present` it. Only string items (what the formatter renders) are
+      // showable; a display still carrying structured items (no formatter
+      // applied) has nothing to stash. With no `stashDisplay` wired, the result
+      // is left exactly as-is.
+      if (opts.stashDisplay && processed.ok && processed.display) {
+        const stringItems = processed.display.items.filter((i): i is string => typeof i === "string");
+        if (stringItems.length > 0) {
+          const displayRef = opts.stashDisplay(stringItems.join("\n\n"));
+          return { ...processed, displayRef };
+        }
+      }
+      return processed;
+    },
+    toModelOutput: ({ output }) => ({ type: "json", value: omitDisplayForModel(output) as JSONValue }),
+  });
+
+  return { runCommand };
+}

package/cli-version-check.ts

@@ -0,0 +1,88 @@
+/**
+ * Checks an installed CLI binary's version against a maintainer-declared
+ * `minVersion` (from an externally-configured CLI config file, see
+ * `src/tools/cli-config-loader.ts`). No version-check convention existed
+ * anywhere in this codebase before this — confirmed by searching
+ * `scripts/install-clis.sh` (only resolves GitHub release *tags* to pick
+ * a download asset, never validates an already-installed binary) and the
+ * rest of `src/`.
+ *
+ * Assumes `--version` is the right flag to invoke — the CLIs are
+ * Rust/clap-based, and `--version` is clap's near-universal default, but
+ * this isn't verified against the real CLI-monorepo binaries from here.
+ * If wrong, the failure mode is still safe: `checkCliVersion` fails
+ * closed (that CLI just never activates), not silently permissive.
+ *
+ * Version comparison is hand-rolled rather than a new dependency —
+ * comparing well-formed `X.Y.Z` triples numerically isn't the kind of
+ * genuinely tricky parsing problem that justified pulling in
+ * `shell-quote` for command tokenizing.
+ */
+import { runCli } from "./cli-executor.ts";
+
+export type ParsedVersion = { major: number; minor: number; patch: number };
+
+const VERSION_PATTERN = /(\d+)\.(\d+)\.(\d+)/;
+
+/** Extracts the first `major.minor.patch` triple found in `text`, or
+ * `null` if none is present. */
+export function parseVersion(text: string): ParsedVersion | null {
+  const match = VERSION_PATTERN.exec(text);
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+}
+
+/** Numeric major/minor/patch comparison: -1 if `a` < `b`, 0 if equal, 1
+ * if `a` > `b`. */
+export function compareVersions(a: ParsedVersion, b: ParsedVersion): -1 | 0 | 1 {
+  if (a.major !== b.major) return a.major > b.major ? 1 : -1;
+  if (a.minor !== b.minor) return a.minor > b.minor ? 1 : -1;
+  if (a.patch !== b.patch) return a.patch > b.patch ? 1 : -1;
+  return 0;
+}
+
+export type VersionCheckResult = { ok: true } | { ok: false; reason: string };
+
+/**
+ * Runs `<binary> --version` (via the injected `runCliFn`) and checks the
+ * result against `minVersion`. Never throws — every failure mode
+ * (malformed `minVersion`, the CLI invocation failing, unparseable
+ * output, a version below the minimum) resolves to `{ ok: false, reason
+ * }` instead.
+ */
+export async function checkCliVersion(
+  binary: string,
+  minVersion: string,
+  runCliFn: typeof runCli,
+): Promise<VersionCheckResult> {
+  const required = parseVersion(minVersion);
+  if (!required) {
+    return { ok: false, reason: `configured minVersion "${minVersion}" is not a valid version` };
+  }
+
+  const result = await runCliFn(binary, ["--version"]);
+  if (!result.ok) {
+    return { ok: false, reason: `could not determine ${binary}'s version: ${result.error}` };
+  }
+
+  const output = typeof result.data === "string" ? result.data : String(result.data);
+  const installed = parseVersion(output);
+  if (!installed) {
+    return { ok: false, reason: `could not parse a version number out of "${output}"` };
+  }
+
+  if (compareVersions(installed, required) < 0) {
+    return {
+      ok: false,
+      reason: `${binary} version ${output.trim()} is below the required minVersion ${minVersion}`,
+    };
+  }
+
+  return { ok: true };
+}

package/command-parser.ts

@@ -0,0 +1,117 @@
+/**
+ * Parses a single free-text command string (as the model would type it in
+ * a terminal, e.g. `jira issue search --jql "project = KAN"`) into a
+ * binary name and an argv array, for the experimental command-string
+ * execution model (see `src/tools/cli-tool.ts`, which consumes this).
+ *
+ * Quoting/escaping itself is delegated to `shell-quote`'s `parse()` — a
+ * widely used, actively maintained tokenizer — rather than hand-rolled,
+ * since getting POSIX-ish quote handling right from scratch is exactly the
+ * kind of finicky, security-relevant code better left to a library with
+ * far more scrutiny than this file would get on its own.
+ *
+ * `shell-quote` on its own isn't a safe-enough boundary by itself, though —
+ * confirmed empirically against the installed version:
+ * - It happily recognizes real shell syntax (`;`, `|`, `&&`, globs,
+ *   comments) and returns non-string entries for them; a naive "keep only
+ *   the strings" filter would silently drop the metacharacter and merge
+ *   the rest of the command as if it had been benign.
+ * - With no `env` argument it still interpolates `$VAR`/`${VAR}` against
+ *   an empty environment, silently resolving every variable to `""`
+ *   (`parse("echo $HOME")` -> `["echo", ""]`) instead of leaving the text
+ *   alone — quiet data loss inside what looked like a literal value.
+ * - It does not error on an unterminated quote; it silently treats the
+ *   rest of the string as if the quote had closed at end-of-input, which
+ *   for a missing closing quote around a multi-word value means it
+ *   silently reverts to word-splitting instead of failing loudly.
+ * - A trailing lone backslash is silently dropped rather than flagged.
+ *
+ * This module closes those gaps itself: reject unbalanced
+ * quotes/escapes and any literal `$` before ever calling `parse()`, then
+ * reject any non-string entry `parse()` returns.
+ */
+import { parse } from "shell-quote";
+
+export type ParsedCommand =
+  | { ok: true; binary: string; args: string[] }
+  | { ok: false; error: string };
+
+/**
+ * Walks `command` tracking quote state to find an unterminated quote or a
+ * dangling trailing escape — the failure modes `shell-quote`'s `parse()`
+ * doesn't itself surface as errors (see this file's header comment).
+ * Mirrors the quoting rules `parse()` actually implements (confirmed
+ * empirically): backslash escapes the next character outside quotes and
+ * inside double quotes, but is a literal character inside single quotes.
+ */
+function findUnbalancedQuoteOrEscape(command: string): string | null {
+  let state: "bare" | "single" | "double" = "bare";
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i];
+    if (state === "single") {
+      if (ch === "'") state = "bare";
+      continue;
+    }
+    if (ch === "\\") {
+      if (i === command.length - 1) {
+        return "command ends with a dangling escape character (\\)";
+      }
+      i++; // the escaped character is consumed as literal, whatever it is
+      continue;
+    }
+    if (state === "double") {
+      if (ch === '"') state = "bare";
+      continue;
+    }
+    // state === "bare"
+    if (ch === "'") state = "single";
+    else if (ch === '"') state = "double";
+  }
+  if (state === "single") return "command has an unterminated single quote (')";
+  if (state === "double") return 'command has an unterminated double quote (")';
+  return null;
+}
+
+/**
+ * Parses `command` into `{ binary, args }`. Never throws — every failure
+ * mode (unbalanced quoting, a `$`, a shell operator/glob/comment, or an
+ * empty result) resolves to `{ ok: false, error }` instead.
+ */
+export function parseCommand(command: string): ParsedCommand {
+  const quoteError = findUnbalancedQuoteOrEscape(command);
+  if (quoteError) {
+    return { ok: false, error: quoteError };
+  }
+
+  if (command.includes("$")) {
+    return {
+      ok: false,
+      error:
+        "variable interpolation ('$') is not supported in commands — shell-quote would silently resolve it to an empty string",
+    };
+  }
+
+  let entries: ReturnType<typeof parse>;
+  try {
+    entries = parse(command);
+  } catch (err) {
+    return { ok: false, error: `could not parse command: ${String(err)}` };
+  }
+
+  const tokens: string[] = [];
+  for (const entry of entries) {
+    if (typeof entry !== "string") {
+      return {
+        ok: false,
+        error: `shell operators, globs, and comments are not supported in commands (found ${JSON.stringify(entry)})`,
+      };
+    }
+    tokens.push(entry);
+  }
+
+  const [binary, ...args] = tokens;
+  if (!binary) {
+    return { ok: false, error: "empty command" };
+  }
+  return { ok: true, binary, args };
+}

package/dist/cli-config-loader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Validates a maintainer-authored CLI allowlist into the internal `CliConfig`
+ * that `cli-tool.ts` consumes. A plugin owns its allowlist as data and hands
+ * the already-parsed object over (via `loadCliConfigFromObject` or the
+ * synchronous `parseCliConfig`); the safety barrier is a strict Zod schema and,
+ * when `minVersion` is declared, a `--version` check. Every failure mode is
+ * fail-closed: a schema violation or an unmet `minVersion` returns
+ * `{ ok: false, reason }`, never a thrown exception or a partially-applied
+ * config. The maintainer who declares a plugin is already fully trusted with
+ * the machine, so the config is data to validate, not a policy to second-guess
+ * beyond schema/version checks.
+ */
+import { type CliConfigFile } from "./cli-config-schema.ts";
+import type { runCli } from "./cli-executor.ts";
+import type { CliConfig } from "./cli-tool.ts";
+/** Maps the external file shape into the internal runtime `CliConfig`
+ * shape `src/tools/cli-tool.ts` consumes. */
+export declare function toCliConfig(raw: CliConfigFile): CliConfig;
+export type CliConfigFromObjectResult = {
+    ok: true;
+    binary: string;
+    config: CliConfig;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a plugin's already-parsed allowlist object: the same `.strict()` Zod
+ * schema and, when `minVersion` is declared, a `--version` check, so a plugin's
+ * config reaches `runCommand`'s allowlist through the full validation. No
+ * requested-vs-declared binary match: the plugin declares its own binary and
+ * there's no separate name to reconcile it against, so the validated `binary` is
+ * returned for the caller to key its map by. Never throws.
+ */
+export declare function loadCliConfigFromObject(raw: unknown, opts: {
+    runCliFn: typeof runCli;
+}): Promise<CliConfigFromObjectResult>;
+/**
+ * The synchronous, no-spawn sibling of `loadCliConfigFromObject`: schema
+ * validation only, skipping the `minVersion` `--version` check. It's what a
+ * plugin uses on its own allowlist in `build()` — a plugin ships its pinned CLI
+ * binary alongside its allowlist, so the two are co-versioned by construction
+ * and the runtime version check earns nothing there. Never throws.
+ */
+export declare function parseCliConfig(raw: unknown): CliConfigFromObjectResult;

package/dist/cli-config-schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Zod schema for the externally-configured, maintainer-authored CLI
+ * config file (e.g. `cli-configs/jira.json`), consumed by
+ * `src/tools/cli-config-loader.ts`. Kept in its own module, separate
+ * from the loader, so the schema itself is unit-testable without any
+ * file I/O.
+ *
+ * `.strict()` on every object level: a maintainer typo (e.g.
+ * `"prefixes"` instead of `"prefix"`) must fail validation loudly, not
+ * silently pass through as an ignored extra key — the whole point of
+ * this schema is to be the one thing standing between a maintainer's
+ * config and what the model can execute, so silent tolerance of
+ * malformed input is exactly what it must not do.
+ */
+import { z } from "zod";
+export declare const CliCommandSchema: z.ZodObject<{
+    prefix: z.ZodArray<z.ZodString>;
+    confirm: z.ZodBoolean;
+    mutating: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const CliGlobalFlagSchema: z.ZodObject<{
+    flag: z.ZodString;
+    takesValue: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const CliConfigFileSchema: z.ZodObject<{
+    binary: z.ZodString;
+    minVersion: z.ZodOptional<z.ZodString>;
+    commands: z.ZodArray<z.ZodObject<{
+        prefix: z.ZodArray<z.ZodString>;
+        confirm: z.ZodBoolean;
+        mutating: z.ZodBoolean;
+    }, z.core.$strict>>;
+    globalFlags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        takesValue: z.ZodBoolean;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type CliConfigFile = z.infer<typeof CliConfigFileSchema>;

package/dist/cli-executor.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Generic subprocess runner for the external CLI binaries Mercury talks
+ * to (jira, google-chat, ...). Every external integration is a separate
+ * CLI binary invoked as a subprocess — never an arbitrary shell string,
+ * never MCP. This file is the one and only place that spawns a process,
+ * in the one shape Mercury needs: a one-shot command that exits and
+ * produces a single parsed output (`runCli`).
+ *
+ * Nothing imports `runCli` to call it directly except the composition root:
+ * every consumer declares it as a `typeof runCli` dependency and receives
+ * it injected, so a test can supply a fake without spawning a subprocess.
+ * `cli-tool.ts` (`runCommand`'s `execute`) and
+ * `@mercury-fw/confirm-engine`'s `confirm-flow.ts` (the second half of the confirm
+ * flow) are the two that actually run model-requested commands; the rest use it for
+ * version checks and diagnostics. The registered
+ * Google Chat provider (`@mercury-fw/channel-google-chat`) does not use this module at all — it talks to
+ * the Chat REST API and Pub/Sub directly over HTTPS, never through a CLI
+ * subprocess (see `google-chat-app-client.ts`).
+ */
+import type { CliResult } from "@mercury-fw/plugin-types";
+export type { CliResult };
+/**
+ * Runs `binary` with `args`, waits for it to exit, and parses its
+ * stdout as JSON when possible.
+ *
+ * Resolves to `{ ok: false, error }` — never rejects/throws — for the
+ * binary not existing on `PATH` or a non-zero exit code (the error
+ * includes the exit code and stderr). Success is exit code 0, full stop:
+ * if stdout happens to be valid JSON it's parsed into `data`, otherwise
+ * the raw trimmed text is `data` instead. Non-JSON stdout on a 0 exit is
+ * not a parse failure — `--help` output is exactly this shape (plain
+ * text, exit 0), and treating it as `ok: false` meant the model saw a
+ * "failed" tool call for what was actually a successful discovery call —
+ * observed live to send it into a confused, apologetic retry spiral.
+ */
+export declare function runCli(binary: string, args: string[]): Promise<CliResult>;

package/dist/cli-status.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Builds the `runCommand` status describer the composition root injects into
+ * the core's tool-start hook. It parses the command, computes whether it
+ * mutates from the same allowlist that gates execution (via `matchCommand`, so
+ * the label can never drift from what actually runs), and hands that to the
+ * command's plugin describer — or `defaultStatusLabel` when the plugin doesn't
+ * 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.
+ */
+import { type StatusDescriber } 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;

package/dist/cli-tool.d.ts

@@ -0,0 +1,107 @@
+import type { runCli } from "./cli-executor.ts";
+import type { StageConfirmation, ExecutableTool } from "@mercury-fw/plugin-types";
+import type { CliPostProcessor } from "@mercury-fw/plugin-types";
+export type { CliPostProcessor };
+export type AllowedCommand = {
+    prefix: string[];
+    confirm: boolean;
+    mutating: boolean;
+};
+export type GlobalFlag = {
+    flag: string;
+    takesValue: boolean;
+};
+export type CliConfig = {
+    allowedPrefixes: AllowedCommand[];
+    /** Optional declarative global flags (can appear anywhere in argv, not
+     * just after the prefix) to strip before prefix-matching. */
+    globalFlags?: GlobalFlag[];
+};
+/**
+ * Removes every occurrence of any flag listed in `globalFlags` from
+ * `args` (and its value too, if `takesValue`), wherever it appears —
+ * generic replacement for what used to be a hand-written per-CLI
+ * function (jira's old `stripSelectFlag`). Used only to build a
+ * throwaway copy for prefix-matching in `matchCommand`; the original
+ * `args` (flags included) is always what actually gets executed.
+ */
+export declare function stripGlobalFlags(args: string[], globalFlags: GlobalFlag[]): string[];
+export type CommandMatch = {
+    kind: "allowed";
+    prefix: string[];
+    mutating: boolean;
+} | {
+    kind: "confirm-required";
+    prefix: string[];
+    mutating: boolean;
+} | {
+    kind: "not-allowed";
+};
+/**
+ * Classifies `args` under `config`: `--help` is always `allowed`
+ * (discovery, not execution); otherwise `args` (after `config.globalFlags`
+ * stripping, if any) is matched positionally against `config.allowedPrefixes`
+ * — no match is `not-allowed`, a match with `confirm: false` is `allowed`,
+ * a match with `confirm: true` is `confirm-required` (the shape is
+ * recognized, but there's no confirmation mechanism to gate it on yet).
+ * `mutating` is carried through independently of `confirm` — a command can
+ * change external state (Jira, etc.) without requiring confirmation (e.g.
+ * create), so the two flags are never derived from one another. An allowed
+ * match reports the prefix it matched (`[]` for `--help`), which is what a
+ * plugin's post-processor decides on.
+ */
+export declare function matchCommand(args: string[], config: CliConfig): CommandMatch;
+/** Renders a list of prefixes as a comma-separated string for a
+ * model-readable rejection message, e.g. `"issue search, issue get"`. */
+export declare function formatPrefixes(prefixes: string[][]): string;
+/**
+ * Removes the top-level `display` channel (see `ToolDisplay`) from a tool
+ * result before it reaches the model. `display` is the user-facing channel —
+ * a deterministic artifact stashed in the display store and shown only when the
+ * model calls `present` (see `display-store.ts`/`present-tool.ts`), never
+ * something the model needs to read or reproduce. The model channel is `data`
+ * plus the `displayRef` pointer (kept, so the model can `present` it), so this
+ * is a structural drop of one known top-level key — not a heuristic removal of
+ * a field nested inside `data`. Model-facing notes a plugin adds inside `data`
+ * (e.g. `formattedListNote`, telling the model why formatting couldn't happen
+ * and how to retry) are on the model channel and pass through.
+ */
+export declare function omitDisplayForModel(output: unknown): unknown;
+/**
+ * Builds the `runCommand` tool: the model writes a whole CLI invocation as
+ * one string, `execute` parses it (`parseCommand`), checks the binary
+ * against `configs`, then classifies the argv via `matchCommand` — each
+ * failure mode (unparseable / unknown binary / confirm-required /
+ * not-allowed) gets a distinct, self-correctable error message — before
+ * ever calling `runCliFn`. `runCliFn` is injected (defaulting to the real
+ * `runCli` in production) so tests can supply a fake without spawning a
+ * real subprocess.
+ *
+ * `opts.stageConfirmation` scopes the confirm-required branch: a confirm-gated
+ * command is staged (see `confirmation-staging.ts`) instead of running, and the
+ * result carries a structured `token` — how the user is actually told to
+ * confirm is channel-specific (a card button on Google Chat, a bare token typed
+ * on the terminal), not dictated here or by the model (see `confirm-flow.ts` for
+ * the other half — actually running it once that token comes back). Staging is
+ * inherently per-session (the closure is bound to one sessionKey), so callers
+ * must build a fresh tool per turn, scoped to that turn's own session — not a
+ * tool meant to be built once and reused across sessions.
+ */
+export declare function createCliTool(runCliFn: typeof runCli, configs: Record<string, CliConfig>, opts: {
+    /** Stages a confirm-required command's execution behind a token, and writes
+     * its paper-trail note (see `StageConfirmation`). Pre-bound to this turn's
+     * session/user by the composition root — `cli-tool.ts` never touches the
+     * confirmation store or the wiki itself. */
+    stageConfirmation: StageConfirmation;
+    /** The plugin's post-processor (see `CliPostProcessor`), run on every
+     * allowed command's result with the matched prefix — `cli-tool.ts` itself
+     * never knows what it does. */
+    postProcess?: CliPostProcessor;
+    /** 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
+     * untouched and no `displayRef` is minted. */
+    stashDisplay?: (artifact: string) => string;
+}): {
+    runCommand: ExecutableTool;
+};

package/dist/cli-version-check.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Checks an installed CLI binary's version against a maintainer-declared
+ * `minVersion` (from an externally-configured CLI config file, see
+ * `src/tools/cli-config-loader.ts`). No version-check convention existed
+ * anywhere in this codebase before this — confirmed by searching
+ * `scripts/install-clis.sh` (only resolves GitHub release *tags* to pick
+ * a download asset, never validates an already-installed binary) and the
+ * rest of `src/`.
+ *
+ * Assumes `--version` is the right flag to invoke — the CLIs are
+ * Rust/clap-based, and `--version` is clap's near-universal default, but
+ * this isn't verified against the real CLI-monorepo binaries from here.
+ * If wrong, the failure mode is still safe: `checkCliVersion` fails
+ * closed (that CLI just never activates), not silently permissive.
+ *
+ * Version comparison is hand-rolled rather than a new dependency —
+ * comparing well-formed `X.Y.Z` triples numerically isn't the kind of
+ * genuinely tricky parsing problem that justified pulling in
+ * `shell-quote` for command tokenizing.
+ */
+import { runCli } from "./cli-executor.ts";
+export type ParsedVersion = {
+    major: number;
+    minor: number;
+    patch: number;
+};
+/** Extracts the first `major.minor.patch` triple found in `text`, or
+ * `null` if none is present. */
+export declare function parseVersion(text: string): ParsedVersion | null;
+/** Numeric major/minor/patch comparison: -1 if `a` < `b`, 0 if equal, 1
+ * if `a` > `b`. */
+export declare function compareVersions(a: ParsedVersion, b: ParsedVersion): -1 | 0 | 1;
+export type VersionCheckResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Runs `<binary> --version` (via the injected `runCliFn`) and checks the
+ * result against `minVersion`. Never throws — every failure mode
+ * (malformed `minVersion`, the CLI invocation failing, unparseable
+ * output, a version below the minimum) resolves to `{ ok: false, reason
+ * }` instead.
+ */
+export declare function checkCliVersion(binary: string, minVersion: string, runCliFn: typeof runCli): Promise<VersionCheckResult>;

package/dist/command-parser.d.ts

@@ -0,0 +1,14 @@
+export type ParsedCommand = {
+    ok: true;
+    binary: string;
+    args: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parses `command` into `{ binary, args }`. Never throws — every failure
+ * mode (unbalanced quoting, a `$`, a shell operator/glob/comment, or an
+ * empty result) resolves to `{ ok: false, error }` instead.
+ */
+export declare function parseCommand(command: string): ParsedCommand;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The CLI-execution plugin's public surface. It owns the whole "run a CLI
+ * command written as one free-text string, against a maintainer-authored
+ * allowlist" mechanism that used to sit in the core: the command parser, the
+ * subprocess executor, the allowlist schema/loader/version-check, the
+ * allowlist-matching `runCommand` tool, and the per-command status describer.
+ *
+ * The core imports what it needs from here; a CLI-based plugin (Jira,
+ * Bitbucket) rides on this one. Nothing here imports the app — its only
+ * dependencies are `@mercury-fw/plugin-types` (the shared contract) and the
+ * external `ai`/`zod`/`shell-quote` packages — so the mechanism is a self
+ * contained unit that an instance with no CLI plugin never pulls in.
+ */
+export { parseCommand, type ParsedCommand } from "./command-parser.ts";
+export { runCli, type CliResult } from "./cli-executor.ts";
+export { createCliTool, matchCommand, stripGlobalFlags, formatPrefixes, omitDisplayForModel, type CliConfig, type AllowedCommand, type GlobalFlag, type CommandMatch, type CliPostProcessor, } from "./cli-tool.ts";
+export { CliConfigFileSchema, type CliConfigFile } from "./cli-config-schema.ts";
+export { toCliConfig, loadCliConfigFromObject, parseCliConfig, type CliConfigFromObjectResult, } from "./cli-config-loader.ts";
+export { checkCliVersion, parseVersion, compareVersions, type ParsedVersion, type VersionCheckResult, } from "./cli-version-check.ts";
+export { createCliStatusDescriber } from "./cli-status.ts";

package/index.ts

@@ -0,0 +1,42 @@
+/**
+ * The CLI-execution plugin's public surface. It owns the whole "run a CLI
+ * command written as one free-text string, against a maintainer-authored
+ * allowlist" mechanism that used to sit in the core: the command parser, the
+ * subprocess executor, the allowlist schema/loader/version-check, the
+ * allowlist-matching `runCommand` tool, and the per-command status describer.
+ *
+ * The core imports what it needs from here; a CLI-based plugin (Jira,
+ * Bitbucket) rides on this one. Nothing here imports the app — its only
+ * dependencies are `@mercury-fw/plugin-types` (the shared contract) and the
+ * external `ai`/`zod`/`shell-quote` packages — so the mechanism is a self
+ * contained unit that an instance with no CLI plugin never pulls in.
+ */
+export { parseCommand, type ParsedCommand } from "./command-parser.ts";
+export { runCli, type CliResult } from "./cli-executor.ts";
+export {
+  createCliTool,
+  matchCommand,
+  stripGlobalFlags,
+  formatPrefixes,
+  omitDisplayForModel,
+  type CliConfig,
+  type AllowedCommand,
+  type GlobalFlag,
+  type CommandMatch,
+  type CliPostProcessor,
+} from "./cli-tool.ts";
+export { CliConfigFileSchema, type CliConfigFile } from "./cli-config-schema.ts";
+export {
+  toCliConfig,
+  loadCliConfigFromObject,
+  parseCliConfig,
+  type CliConfigFromObjectResult,
+} from "./cli-config-loader.ts";
+export {
+  checkCliVersion,
+  parseVersion,
+  compareVersions,
+  type ParsedVersion,
+  type VersionCheckResult,
+} from "./cli-version-check.ts";
+export { createCliStatusDescriber } from "./cli-status.ts";

package/package.json

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