@mercury-fw/cli 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @mercury-fw/cli
 
+## 0.41.0
+
+### Minor Changes
+
+- 2755f61: New plugin: ZITADEL through the `zitadel` CLI.
+
+  - New package `@mercury-fw/plugin-zitadel`. It reads users (by email, username or id), their project roles and identity provider links, organizations and projects, as the person Mercury is talking to, who logs in to ZITADEL through Mercury. Nothing it runs changes ZITADEL.
+  - The CLI is pinned at 2.6.0. `mfw credentials setup @mercury-fw/plugin-zitadel` sets up the service user the terminal runs as; with `--user-app` it sets up the Native app people log in through.
+  - `mfw create` offers it as `zitadel`.
+
+### Patch Changes
+
+- @mercury-fw/core@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/core@0.40.0
+  - @mercury-fw/utils@0.40.0
+
 ## 0.39.0
 
 ### Minor Changes

package/README.md

@@ -60,7 +60,7 @@ Then it runs `bun install` in the app and creates a git repository on `main` wit
 | `--assistant-name <name>` | The assistant's name (default `Mercury`). |
 | `--role <text>` | Completes "You are <name>, …" (default `an internal assistant`). |
 | `--channels <ids>` | Comma-separated: `google-chat`, `http`. |
-| `--plugins <ids>` | Comma-separated: `jira`, `bitbucket`, `atlassian-admin`. |
+| `--plugins <ids>` | Comma-separated: `jira`, `bitbucket`, `atlassian-admin`, `zitadel`. |
 | `--auth <id>` | The HTTP channel's auth provider, `oidc` or `static`: required with `http`, refused without it, since the channel doesn't start without one. The wizard asks for it once `http` is chosen. |
 | `--local-packages <folder>` | Installs the packages packed in `<folder>` (`bun pm pack`) instead of the registry's, as [`mfw local-packages`](#mfw-local-packages-folder--mfw-local-packages---off) does on an existing app: their versions come from the tarballs, so a package that isn't published yet works too, and no newer `mfw` is looked up on the registry. For trying unreleased packages in a new app; the test bed makes its apps this way. |
 | `--git-remote <url>` | The repository's `origin`, taken as typed. |

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.41.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,19 +41,20 @@
   "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.41.0",
+    "@mercury-fw/utils": "0.41.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.41.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/plugin-zitadel": "0.1.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" },
     ],
   },
   {
@@ -114,6 +115,13 @@ export const CATALOG: CatalogEntry[] = [
     exportName: "atlassianAdminPlugin",
     env: [],
   },
+  {
+    id: "zitadel",
+    kind: "tool",
+    package: "@mercury-fw/plugin-zitadel",
+    exportName: "zitadelPlugin",
+    env: [],
+  },
 ];
 
 /** The catalog entry of `kind` with `id`, or undefined when there is none. */

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")