@mercury-fw/cli 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mercury-fw/cli
 
+## 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/core@0.40.0
+  - @mercury-fw/utils@0.40.0
+
 ## 0.39.0
 
 ### Minor Changes

package/dist/src/app/commands.d.ts

@@ -56,11 +56,13 @@ export declare function appCommands(app: App, deps: AppDeps): {
      * brings its service back up on an empty volume. The volume's real name
      * comes from the compose file, and a wrong answer deletes nothing. */
     reset: (target: ResetTarget) => Promise<number>;
-    /** Runs the plugin's declared setup in a one-off container on the user's
-     * terminal (without `-T`, compose attaches a TTY whenever stdin is one),
+    /** Runs the plugin's declared setup (with `userApp`, of the app people log
+     * in through) in a one-off container on the user's terminal (without `-T`, compose attaches a TTY whenever stdin is one),
      * so the CLI asks what it needs and writes its login straight onto the
      * credentials volume. */
-    credentialsSetup: (plugin: string) => Promise<number>;
+    credentialsSetup: (plugin: string, { userApp }?: {
+        userApp?: boolean;
+    }) => Promise<number>;
     /** Runs the plugin's declared check in a one-off container. */
     credentialsCheck: (plugin: string) => Promise<number>;
     /** Runs the plugin's declared logout, of the service identity or of the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,19 +41,19 @@
   "comment:shape": "The Mercury CLI (`mfw`). `mfw create <dir>` writes a new Mercury app from the template. The framework packages move in lockstep with it, so a new app gets them at the CLI's own version; plugins and channels at the registry's latest. The plugin and channel packages are devDependencies only for the catalog test. `main(argv)` is exported for create-mercury-agent.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@mercury-fw/core": "0.39.0",
-    "@mercury-fw/utils": "0.39.0",
+    "@mercury-fw/core": "0.40.0",
+    "@mercury-fw/utils": "0.40.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-google-chat": "0.3.0",
-    "@mercury-fw/channel-http": "0.4.0",
+    "@mercury-fw/channel-google-chat": "0.4.0",
+    "@mercury-fw/channel-http": "0.5.0",
     "@mercury-fw/auth-oidc": "0.1.0",
     "@mercury-fw/auth-static": "0.1.0",
-    "@mercury-fw/formatter": "0.39.0",
-    "@mercury-fw/plugin-atlassian-admin": "0.2.0",
-    "@mercury-fw/plugin-bitbucket": "0.2.0",
-    "@mercury-fw/plugin-jira": "0.5.0",
+    "@mercury-fw/formatter": "0.40.0",
+    "@mercury-fw/plugin-atlassian-admin": "0.3.0",
+    "@mercury-fw/plugin-bitbucket": "0.3.0",
+    "@mercury-fw/plugin-jira": "0.6.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"

package/src/app/commands.ts

@@ -128,13 +128,15 @@ export function appCommands(app: App, deps: AppDeps) {
       }
       return 0;
     },
-    /** Runs the plugin's declared setup in a one-off container on the user's
-     * terminal (without `-T`, compose attaches a TTY whenever stdin is one),
+    /** Runs the plugin's declared setup (with `userApp`, of the app people log
+     * in through) in a one-off container on the user's terminal (without `-T`, compose attaches a TTY whenever stdin is one),
      * so the CLI asks what it needs and writes its login straight onto the
      * credentials volume. */
-    credentialsSetup: async (plugin: string) => {
+    credentialsSetup: async (plugin: string, { userApp = false }: { userApp?: boolean } = {}) => {
       const declared = credentialsOf(app, plugin);
-      const code = await deps.run([...COMPOSE, "run", "--rm", "--no-deps", SERVICE, ...inContainer(declared, declared.setup)], {
+      const setup = userApp ? declared.userSetup : declared.setup;
+      if (setup === undefined) throw new Error(`${declared.package} declares no setup for an app people log in through: it doesn't act as the person.`);
+      const code = await deps.run([...COMPOSE, "run", "--rm", "--no-deps", SERVICE, ...inContainer(declared, setup)], {
         cwd: app.dir,
       });
       if (code === 0 && declared.check !== undefined) deps.print(`Next: mfw credentials check ${declared.package}`);

package/src/catalog.ts

@@ -58,6 +58,7 @@ export const CATALOG: CatalogEntry[] = [
     env: [
       { name: "HTTP_SURFACE_PORT", comment: "Port of the HTTP surface", value: "4100" },
       { name: "HTTP_SURFACE_CORS_ORIGIN", comment: "Origin allowed to call the HTTP surface from a browser, if any" },
+      { name: "HTTP_SURFACE_PUBLIC_URL", comment: "Address people's browsers reach the HTTP surface at, for logging in to the services plugins act on as them" },
     ],
   },
   {

package/src/program.ts

@@ -236,10 +236,13 @@ Examples:
     .command("setup")
     .summary("sets up a CLI's login in the app's container")
     .description(
-      "Runs the setup the plugin declares for its CLI's service identity (the identity Mercury acts as), in a one-off container on your terminal: the CLI asks for what it needs, and its login lands on the credentials volume. People log in on their own later, through Mercury.",
+      "Runs the setup the plugin declares for its CLI's service identity (the identity Mercury acts as), in a one-off container on your terminal: the CLI asks for what it needs, and its login lands on the credentials volume. People log in on their own later, through Mercury: for a plugin acting as the person, --user-app sets up the app they log in through.",
     )
     .argument("<plugin>", "the plugin's package (@mercury-fw/plugin-jira) or its CLI's folder as declared (jira-cli)")
-    .action(async (plugin: string) => inApp((app) => app.credentialsSetup(plugin))());
+    .option("--user-app", "set up instead the app people log in through, for a plugin acting as the person (logs nobody in)")
+    .action(async (plugin: string, opts: { userApp?: boolean }) =>
+      inApp((app) => app.credentialsSetup(plugin, opts.userApp ? { userApp: true } : {}))(),
+    );
   credentials
     .command("check")
     .summary("checks a CLI's login")