@mercury-fw/plugin-atlassian-admin 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @mercury-fw/plugin-atlassian-admin
+
+Lets a [Mercury](https://github.com/lucabro81/mercury-fw) agent look up users in an Atlassian organization, through the `atlassian-admin` CLI (read-only). The pinned binary downloads when the package installs.
+
+```bash
+bun add @mercury-fw/plugin-atlassian-admin
+```
+
+In the app: list it in `trustedDependencies` (or Bun skips the install script that downloads the binary), add `atlassian-admin` to `MERCURY_CLIS`, and declare it in `mercury.config.ts`:
+
+```ts
+import { atlassianAdminPlugin } from "@mercury-fw/plugin-atlassian-admin";
+
+plugins: [atlassianAdminPlugin],
+```
+
+## Credentials
+
+The CLI keeps its login under `~/.config/atlassian-admin-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/atlassian-admin.json

@@ -0,0 +1,10 @@
+{
+  "binary": "atlassian-admin",
+  "commands": [
+    { "prefix": ["user", "get"], "confirm": false, "mutating": false },
+    { "prefix": ["doctor"], "confirm": false, "mutating": false }
+  ],
+  "globalFlags": [
+    { "flag": "--select", "takesValue": true }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The atlassian-admin plugin — a minimal read-only CLI plugin (user get,
+ * doctor; no mutating or confirm-gated commands, no result post-processing, no
+ * post-turn guard, no prompt block of its own). Like Jira/Bitbucket it works
+ * only through a CLI, so it owns its tool: in `build()` it validates its own
+ * allowlist and builds its `atlassianAdminCommand` tool from it. Its allowlist
+ * (`atlassian-admin.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 atlassianAdminCliConfig: unknown;
+export declare const atlassianAdminPlugin: Plugin;

package/index.ts

@@ -0,0 +1,56 @@
+/**
+ * The atlassian-admin plugin — a minimal read-only CLI plugin (user get,
+ * doctor; no mutating or confirm-gated commands, no result post-processing, no
+ * post-turn guard, no prompt block of its own). Like Jira/Bitbucket it works
+ * only through a CLI, so it owns its tool: in `build()` it validates its own
+ * allowlist and builds its `atlassianAdminCommand` tool from it. Its allowlist
+ * (`atlassian-admin.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 "./atlassian-admin.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 atlassianAdminCliConfig: unknown = rawConfig;
+
+/** Reads the command string off an `atlassianAdminCommand` 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 atlassianAdminPlugin: Plugin = {
+  apiVersion: PLUGIN_API_VERSION,
+  name: "atlassian-admin",
+  build: (ctx) => {
+    // Schema-only validation — the pinned binary is co-shipped, so no
+    // `--version` check (see the Jira/Bitbucket plugins / `parseCliConfig`).
+    const loaded = parseCliConfig(atlassianAdminCliConfig);
+    if (!loaded.ok) {
+      ctx.log(`atlassian-admin allowlist failed to load, 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 { atlassianAdminCommand: runCommand };
+      },
+      toolStatusDescribers: {
+        atlassianAdminCommand: (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-atlassian-admin",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "packages/tools/plugin-atlassian-admin"
+  },
+  "files": [
+    "*.ts",
+    "dist",
+    "atlassian-admin.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-atlassian-admin-cli.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "mercury": {
+    "cliBinary": {
+      "repo": "lucabro81/CLI-monorepo",
+      "crate": "atlassian-admin",
+      "version": "0.1.2"
+    }
+  }
+}

package/scripts/install-atlassian-admin-cli.ts

@@ -0,0 +1,11 @@
+/**
+ * postinstall hook for @mercury-fw/plugin-atlassian-admin: downloads the pinned
+ * atlassian-admin CLI binary for the current platform into this package's
+ * `bin/`. Identical in shape to the Jira/Bitbucket plugins' — 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`).
+ */
+import { downloadPinnedBinary } from "@mercury-fw/utils";
+import pkg from "../package.json";
+
+await downloadPinnedBinary(pkg, import.meta.url);