@mercury-fw/cli-engine 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @mercury-fw/cli-engine
 
+## 0.41.0
+
+### Patch Changes
+
+- @mercury-fw/plugin-types@0.41.0
+- @mercury-fw/utils@0.41.0
+
+## 0.40.0
+
+### Minor Changes
+
+- 0739f77: A plugin acts as the person Mercury is talking to, who logs in to the service through Mercury.
+
+  - Plugin contract version 4: a plugin declares `actsAs: "person" | "mercury"`, and one acting as the person contributes a `login`; its tools get the turn's `person` and `requireLogin` in their context.
+  - A person is offered only the plugins acting as the person: their prompt fragments, skills and tools. A plugin acting as Mercury, or declaring nothing, is offered on the terminal only until people can be allowed to make Mercury act as itself; the startup log names it.
+  - `createCliTool` adds `--user` with the person's id to every command, staged confirmations included, and when the CLI exits with code 3 (not logged in) returns their login instead. `createCliPersonLogin` builds a plugin's `login` on a CLI's two-step remote login. A failed `runCli` carries `exitCode`.
+  - Channel contract version 4: channels get `logins` (`accept` a callback URL, `complete` a login) and `detectLoginRequired`.
+  - The HTTP channel, with `HTTP_SURFACE_PUBLIC_URL` set, streams a `login` event with the link to open and takes the person back at `GET /login/callback`, public and protected by the single-use state.
+  - `mercury.cliCredentials` can declare `userSetup`, run by `mfw credentials setup <plugin> --user-app`: the app people log in through, set up without logging anyone in.
+  - plugin-jira and plugin-bitbucket act as the person, on CLIs 2.3.0: set up their people's app with `--user-app` and register `<HTTP_SURFACE_PUBLIC_URL>/login/callback` on it. Jira's skill now says `currentUser()` is the person.
+  - plugin-atlassian-admin acts as Mercury, on CLI 0.2.0, whose `init` asks for the key without echoing it: until permissions exist it's available on the terminal only.
+  - A third-party plugin needs `apiVersion: 4` to load, and `actsAs: "person"` with a `login` to be offered to people.
+
+### Patch Changes
+
+- Updated dependencies [0739f77]
+  - @mercury-fw/plugin-types@0.40.0
+  - @mercury-fw/utils@0.40.0
+
 ## 0.39.0
 
 ### Minor Changes

package/cli-executor.ts

@@ -25,6 +25,12 @@
 import type { CliResult } from "@mercury-fw/plugin-types";
 export type { CliResult };
 
+/** The exit code the CLIs Mercury's plugins run use when the identity a
+ * command runs as (the service, or the person `--user` names) has no login,
+ * or one that has to be made again: what tells it apart from any other
+ * failure. */
+export const CLI_NOT_LOGGED_IN_EXIT_CODE = 3;
+
 /**
  * Thin wrapper around `Bun.spawn` with both stdout and stderr piped.
  * Extracted into its own function (rather than calling `Bun.spawn`
@@ -43,7 +49,7 @@ function spawnPiped(binary: string, args: string[]) {
  *
  * 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:
+ * includes the exit code and stderr, and `exitCode` carries the code). 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
@@ -72,6 +78,7 @@ export async function runCli(
     return {
       ok: false,
       error: `${binary} exited with code ${exitCode}: ${stderr.trim()}`,
+      exitCode,
     };
   }
 

package/cli-tool.ts

@@ -23,8 +23,9 @@
 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";
+import { CLI_NOT_LOGGED_IN_EXIT_CODE, type runCli, type CliResult } from "./cli-executor.ts";
+import type { StageConfirmation, ExecutableTool, LoginRequired } from "@mercury-fw/plugin-types";
+import { cliUserId } from "@mercury-fw/utils";
 
 // `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
@@ -125,6 +126,15 @@ export function omitDisplayForModel(output: unknown): unknown {
   return rest;
 }
 
+/** Drops the link from a `loginRequired` result before it reaches the model:
+ * it carries the login's state, the only credential of the callback the
+ * person comes back to, so the channel shows it and the model never sees it. */
+function omitLoginLinkForModel(output: unknown): unknown {
+  if (typeof output !== "object" || output === null || (output as { loginRequired?: unknown }).loginRequired !== true) return output;
+  const { authorizeUrl: _url, ...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
@@ -163,8 +173,16 @@ export function createCliTool(
      * composition root. Optional: with none wired the inline `display` is left
      * untouched and no `displayRef` is minted. */
     stashDisplay?: (artifact: string) => string;
+    /** The person the turn is for (see `SessionToolContext.person`): every
+     * command runs as them, with `--user` and the id their CLI knows them by.
+     * Absent or `null`: the CLI's own service identity. */
+    person?: { key: string } | null;
+    /** What the tool hands back when the person's CLI says they aren't logged
+     * in (`CLI_NOT_LOGGED_IN_EXIT_CODE`): their login, started. */
+    requireLogin?: () => Promise<LoginRequired>;
   },
 ): { runCommand: ExecutableTool } {
+  const identity = opts.person ? ["--user", cliUserId(opts.person.key)] : [];
   // Anchor the example on a binary this tool actually runs 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)
@@ -218,7 +236,7 @@ export function createCliTool(
         // 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"];
+        const argsToStage = [...(parsed.args.includes("--confirm") ? parsed.args : [...parsed.args, "--confirm"]), ...identity];
         // 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
@@ -236,7 +254,12 @@ export function createCliTool(
         };
       }
 
-      const result = await runCliFn(parsed.binary, parsed.args);
+      const result = await runCliFn(parsed.binary, [...parsed.args, ...identity]);
+      // The person has no login (or an expired one) with this CLI's service:
+      // nothing to retry, they log in first.
+      if (!result.ok && result.exitCode === CLI_NOT_LOGGED_IN_EXIT_CODE && opts.person && opts.requireLogin) {
+        return opts.requireLogin();
+      }
       const processed = opts.postProcess
         ? opts.postProcess({ binary: parsed.binary, args: parsed.args, prefix: match.prefix }, result)
         : result;
@@ -256,7 +279,7 @@ export function createCliTool(
       }
       return processed;
     },
-    toModelOutput: ({ output }) => ({ type: "json", value: omitDisplayForModel(output) as JSONValue }),
+    toModelOutput: ({ output }) => ({ type: "json", value: omitLoginLinkForModel(omitDisplayForModel(output)) as JSONValue }),
   });
 
   return { runCommand };

package/dist/cli-executor.d.ts

@@ -19,13 +19,18 @@
  */
 import type { CliResult } from "@mercury-fw/plugin-types";
 export type { CliResult };
+/** The exit code the CLIs Mercury's plugins run use when the identity a
+ * command runs as (the service, or the person `--user` names) has no login,
+ * or one that has to be made again: what tells it apart from any other
+ * failure. */
+export declare const CLI_NOT_LOGGED_IN_EXIT_CODE = 3;
 /**
  * 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:
+ * includes the exit code and stderr, and `exitCode` carries the code). 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

package/dist/cli-tool.d.ts

@@ -1,5 +1,5 @@
-import type { runCli } from "./cli-executor.ts";
-import type { StageConfirmation, ExecutableTool } from "@mercury-fw/plugin-types";
+import { type runCli } from "./cli-executor.ts";
+import type { StageConfirmation, ExecutableTool, LoginRequired } from "@mercury-fw/plugin-types";
 import type { CliPostProcessor } from "@mercury-fw/plugin-types";
 export type { CliPostProcessor };
 export type AllowedCommand = {
@@ -102,6 +102,15 @@ export declare function createCliTool(runCliFn: typeof runCli, configs: Record<s
      * composition root. Optional: with none wired the inline `display` is left
      * untouched and no `displayRef` is minted. */
     stashDisplay?: (artifact: string) => string;
+    /** The person the turn is for (see `SessionToolContext.person`): every
+     * command runs as them, with `--user` and the id their CLI knows them by.
+     * Absent or `null`: the CLI's own service identity. */
+    person?: {
+        key: string;
+    } | null;
+    /** What the tool hands back when the person's CLI says they aren't logged
+     * in (`CLI_NOT_LOGGED_IN_EXIT_CODE`): their login, started. */
+    requireLogin?: () => Promise<LoginRequired>;
 }): {
     runCommand: ExecutableTool;
 };

package/dist/index.d.ts

@@ -7,12 +7,14 @@
  *
  * 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
+ * dependencies are `@mercury-fw/plugin-types` (the shared contract),
+ * `@mercury-fw/utils` (the id a CLI knows a person by) 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 { runCli, CLI_NOT_LOGGED_IN_EXIT_CODE, type CliResult } from "./cli-executor.ts";
+export { createCliPersonLogin } from "./person-login.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";

package/dist/person-login.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A person's login through a CLI's two-step remote login, for a plugin acting
+ * as the person (`PersonLogin`): `auth login --user <id> --remote` prints the
+ * link the person opens and the `state` the provider sends back with the
+ * code; `auth login --user <id> --code <code> --state <state>` finishes it.
+ * The CLI keeps the pending login (verifier, state, expiry) itself, in the
+ * person's own folder, so nothing secret passes through here but the code.
+ */
+import type { PersonLogin } from "@mercury-fw/plugin-types";
+import type { runCli } from "./cli-executor.ts";
+/**
+ * Builds `binary`'s `PersonLogin`. `redirectUri`: whether the CLI takes the
+ * callback as `--redirect-uri` (jira, confluence, zitadel), or the provider
+ * always sends the person back to the one callback registered on the app
+ * (bitbucket), in which case that has to be Mercury's.
+ */
+export declare function createCliPersonLogin(runCliFn: typeof runCli, binary: string, { redirectUri }: {
+    redirectUri: boolean;
+}): PersonLogin;

package/index.ts

@@ -7,12 +7,14 @@
  *
  * 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
+ * dependencies are `@mercury-fw/plugin-types` (the shared contract),
+ * `@mercury-fw/utils` (the id a CLI knows a person by) 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 { runCli, CLI_NOT_LOGGED_IN_EXIT_CODE, type CliResult } from "./cli-executor.ts";
+export { createCliPersonLogin } from "./person-login.ts";
 export {
   createCliTool,
   matchCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli-engine",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -23,7 +23,8 @@
     }
   },
   "dependencies": {
-    "@mercury-fw/plugin-types": "0.39.0",
+    "@mercury-fw/plugin-types": "0.41.0",
+    "@mercury-fw/utils": "0.41.0",
     "ai": "^7.0.126",
     "shell-quote": "^1.11.0",
     "zod": "^4.6.5"

package/person-login.ts

@@ -0,0 +1,40 @@
+/**
+ * A person's login through a CLI's two-step remote login, for a plugin acting
+ * as the person (`PersonLogin`): `auth login --user <id> --remote` prints the
+ * link the person opens and the `state` the provider sends back with the
+ * code; `auth login --user <id> --code <code> --state <state>` finishes it.
+ * The CLI keeps the pending login (verifier, state, expiry) itself, in the
+ * person's own folder, so nothing secret passes through here but the code.
+ */
+import type { PersonLogin } from "@mercury-fw/plugin-types";
+import { cliUserId } from "@mercury-fw/utils";
+import type { runCli } from "./cli-executor.ts";
+
+/**
+ * Builds `binary`'s `PersonLogin`. `redirectUri`: whether the CLI takes the
+ * callback as `--redirect-uri` (jira, confluence, zitadel), or the provider
+ * always sends the person back to the one callback registered on the app
+ * (bitbucket), in which case that has to be Mercury's.
+ */
+export function createCliPersonLogin(
+  runCliFn: typeof runCli,
+  binary: string,
+  { redirectUri }: { redirectUri: boolean },
+): PersonLogin {
+  return {
+    start: async (personKey, callbackUrl) => {
+      const args = ["auth", "login", "--user", cliUserId(personKey), "--remote"];
+      const result = await runCliFn(binary, redirectUri ? [...args, "--redirect-uri", callbackUrl] : args);
+      if (!result.ok) return { ok: false, error: result.error };
+      const { authorize_url: authorizeUrl, state } = (result.data ?? {}) as { authorize_url?: unknown; state?: unknown };
+      if (typeof authorizeUrl !== "string" || typeof state !== "string") {
+        return { ok: false, error: `${binary} auth login --remote didn't print an authorize_url and a state` };
+      }
+      return { ok: true, authorizeUrl, state };
+    },
+    complete: async (personKey, code, state) => {
+      const result = await runCliFn(binary, ["auth", "login", "--user", cliUserId(personKey), "--code", code, "--state", state]);
+      return result.ok ? { ok: true } : { ok: false, error: result.error };
+    },
+  };
+}