@mercury-fw/plugin-bitbucket 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @mercury-fw/plugin-bitbucket
+
+Gives a [Mercury](https://github.com/lucabro81/mercury-fw) agent read-only access to Bitbucket pull requests (listing them, reading one), through the `bitbucket` CLI. The pinned binary downloads when the package installs.
+
+```bash
+bun add @mercury-fw/plugin-bitbucket
+```
+
+In the app: list it in `trustedDependencies` (or Bun skips the install script that downloads the binary), add `bitbucket` to `MERCURY_CLIS`, and declare it in `mercury.config.ts`:
+
+```ts
+import { bitbucketPlugin } from "@mercury-fw/plugin-bitbucket";
+
+plugins: [bitbucketPlugin],
+```
+
+## Credentials
+
+The CLI keeps its login under `~/.config/bitbucket-cli`, which in a container lives on the `cli-credentials` volume. Log in with the CLI's own setup (see [CLI-monorepo](https://github.com/lucabro81/CLI-monorepo)), then bring that folder into the volume; doing it from the env file is planned ([#57](https://github.com/lucabro81/mercury-fw/issues/57)).
+
+MIT

package/bitbucket.json

@@ -0,0 +1,12 @@
+{
+  "binary": "bitbucket",
+  "commands": [
+    { "prefix": ["pr", "list"], "confirm": false, "mutating": false },
+    { "prefix": ["pr", "get"], "confirm": false, "mutating": false },
+    { "prefix": ["doctor"], "confirm": false, "mutating": false },
+    { "prefix": ["auth", "whoami"], "confirm": false, "mutating": false }
+  ],
+  "globalFlags": [
+    { "flag": "--select", "takesValue": true }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The Bitbucket plugin — the minimal CLI-based plugin. Read-only (pr list/get,
+ * doctor, auth whoami — no mutating or confirm-gated commands), no result
+ * post-processing, no post-turn guard, no prompt block of its own (the
+ * `--help`-driven discovery in the system prompt covers it).
+ *
+ * Like Jira, it works only through a CLI, so it owns its tool: it depends on
+ * `@mercury-fw/cli-engine` and, in `build()`, validates its own allowlist and
+ * builds its `bitbucketCommand` tool from it. Its allowlist (`bitbucket.json`)
+ * and its pinned CLI binary (via the package's postinstall, using
+ * `@mercury-fw/utils`) travel with the package.
+ */
+import { type Plugin } from "@mercury-fw/plugin-types";
+/** The raw, unvalidated allowlist object. The plugin validates it itself through
+ * `@mercury-fw/cli-engine`'s loader, so nothing reaches the model's executable
+ * surface unvalidated. */
+export declare const bitbucketCliConfig: unknown;
+export declare const bitbucketPlugin: Plugin;

package/index.ts

@@ -0,0 +1,62 @@
+/**
+ * The Bitbucket plugin — the minimal CLI-based plugin. Read-only (pr list/get,
+ * doctor, auth whoami — no mutating or confirm-gated commands), no result
+ * post-processing, no post-turn guard, no prompt block of its own (the
+ * `--help`-driven discovery in the system prompt covers it).
+ *
+ * Like Jira, it works only through a CLI, so it owns its tool: it depends on
+ * `@mercury-fw/cli-engine` and, in `build()`, validates its own allowlist and
+ * builds its `bitbucketCommand` tool from it. Its allowlist (`bitbucket.json`)
+ * and its pinned CLI binary (via the package's postinstall, using
+ * `@mercury-fw/utils`) travel with the package.
+ */
+import { PLUGIN_API_VERSION, type Plugin } from "@mercury-fw/plugin-types";
+import { runCli, createCliTool, parseCliConfig, createCliStatusDescriber } from "@mercury-fw/cli-engine";
+import rawConfig from "./bitbucket.json";
+
+/** The raw, unvalidated allowlist object. The plugin validates it itself through
+ * `@mercury-fw/cli-engine`'s loader, so nothing reaches the model's executable
+ * surface unvalidated. */
+export const bitbucketCliConfig: unknown = rawConfig;
+
+/** Reads the command string off a `bitbucketCommand` call's input for the status
+ * label; a missing/non-string command falls back to the generic label. */
+function commandOf(input: unknown): string | undefined {
+  if (typeof input === "object" && input !== null && "command" in input) {
+    const command = (input as { command: unknown }).command;
+    if (typeof command === "string") return command;
+  }
+  return undefined;
+}
+
+export const bitbucketPlugin: Plugin = {
+  apiVersion: PLUGIN_API_VERSION,
+  name: "bitbucket",
+  build: (ctx) => {
+    // Schema-only validation — the pinned binary is co-shipped, so no
+    // `--version` check (see the Jira plugin / `parseCliConfig`).
+    const loaded = parseCliConfig(bitbucketCliConfig);
+    if (!loaded.ok) {
+      ctx.log(`bitbucket allowlist failed to load, bitbucket tool not contributed: ${loaded.reason}`);
+      return {};
+    }
+    const configs = { [loaded.binary]: loaded.config };
+    const describeCli = createCliStatusDescriber(configs, {});
+
+    return {
+      sessionTools: (sctx) => {
+        const { runCommand } = createCliTool(runCli, configs, {
+          stageConfirmation: sctx.stageConfirmation,
+          stashDisplay: sctx.stashDisplay,
+        });
+        return { bitbucketCommand: runCommand };
+      },
+      toolStatusDescribers: {
+        bitbucketCommand: (input) => {
+          const command = commandOf(input);
+          return command !== undefined ? describeCli(command) : "esecuzione di un comando";
+        },
+      },
+    };
+  },
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mercury-fw/plugin-bitbucket",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "packages/tools/plugin-bitbucket"
+  },
+  "files": [
+    "*.ts",
+    "dist",
+    "bitbucket.json",
+    "scripts",
+    "CHANGELOG.md",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@mercury-fw/cli-engine": ">=0.24.0 <1.0.0",
+    "@mercury-fw/plugin-types": ">=0.24.0 <1.0.0",
+    "@mercury-fw/utils": ">=0.24.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@mercury-fw/cli-engine": "0.25.0",
+    "@mercury-fw/plugin-types": "0.25.0",
+    "@mercury-fw/typescript-config": "*",
+    "@mercury-fw/utils": "0.25.0",
+    "@types/bun": "^1.4.0",
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": {
+      "mercury-fw-source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./index.ts"
+    }
+  },
+  "scripts": {
+    "postinstall": "bun run scripts/install-bitbucket-cli.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "mercury": {
+    "cliBinary": {
+      "repo": "lucabro81/CLI-monorepo",
+      "crate": "bitbucket",
+      "version": "0.6.0"
+    }
+  }
+}

package/scripts/install-bitbucket-cli.ts

@@ -0,0 +1,12 @@
+/**
+ * postinstall hook for @mercury-fw/plugin-bitbucket: downloads the pinned bitbucket
+ * CLI binary for the current platform into this package's `bin/`. Identical in
+ * shape to the Jira plugin's — the mechanism lives in `@mercury-fw/utils`; this
+ * script only names the pin (its own package.json's `mercury.cliBinary`) and
+ * where to write it (`import.meta.url`). The Dockerfile symlinks the downloaded
+ * binary onto PATH so `runCommand` can spawn `bitbucket` by name.
+ */
+import { downloadPinnedBinary } from "@mercury-fw/utils";
+import pkg from "../package.json";
+
+await downloadPinnedBinary(pkg, import.meta.url);