@mercury-fw/utils 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @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.
+
 ## 0.39.0
 
 ### Minor Changes

package/cli-credentials.ts

@@ -18,12 +18,14 @@ import { join } from "node:path";
 /** What a plugin declares: `name` as it was declared (the folder, or the
  * path), which `mfw credentials` takes; `path` relative to the home; and the
  * commands, each a binary on the container's PATH and its arguments: `setup`
- * sets up the service identity, `check` reports on the login, `logout`
- * removes one identity's login (the service's, or a person's with `--user`). */
+ * sets up the service identity, `userSetup` the app people log in through
+ * (no person logged in), `check` reports on the login, `logout` removes one
+ * identity's login (the service's, or a person's with `--user`). */
 export type DeclaredCredentials = {
   name: string;
   path: string;
   setup: string[];
+  userSetup?: string[];
   check?: string[];
   logout?: string[];
 };
@@ -50,7 +52,7 @@ const BINARY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const ELSEWHERE = ".config/mercury-home";
 
 const INVALID =
-  "invalid mercury.cliCredentials in package.json: expected { folder } with a single folder name under ~/.config, or { path } relative to the home and outside ~/.config, with setup (and optionally check, logout) as a binary name followed by its arguments, e.g. [\"jira\", \"init\"]";
+  "invalid mercury.cliCredentials in package.json: expected { folder } with a single folder name under ~/.config, or { path } relative to the home and outside ~/.config, with setup (and optionally userSetup, check, logout) as a binary name followed by its arguments, e.g. [\"jira\", \"init\"]";
 
 /** Whether `path` is a usable home-relative path for a login: inside the
  * home and outside `~/.config`, the volume, where a login is a `folder`. */
@@ -85,11 +87,15 @@ export function readCliCredentials(pkg: unknown): DeclaredCredentials | undefine
   if (!("cliCredentials" in mercury)) return undefined;
   const declared = (mercury as { cliCredentials?: unknown }).cliCredentials;
   if (typeof declared !== "object" || declared === null) throw new Error(INVALID);
-  const { folder, path, setup, check, logout } = declared as Record<string, unknown>;
-  if (!isCommand(setup) || (check !== undefined && !isCommand(check)) || (logout !== undefined && !isCommand(logout))) {
+  const { folder, path, setup, userSetup, check, logout } = declared as Record<string, unknown>;
+  const optional = { userSetup, check, logout };
+  if (!isCommand(setup) || Object.values(optional).some((c) => c !== undefined && !isCommand(c))) {
     throw new Error(INVALID);
   }
-  const commands = { setup, ...(check === undefined ? {} : { check }), ...(logout === undefined ? {} : { logout }) };
+  const commands: Pick<DeclaredCredentials, "setup" | "userSetup" | "check" | "logout"> = { setup };
+  for (const [field, command] of Object.entries(optional) as [keyof typeof optional, string[] | undefined][]) {
+    if (command !== undefined) commands[field] = command;
+  }
   if (folder !== undefined && path === undefined && typeof folder === "string" && FOLDER.test(folder)) {
     return { name: folder, path: `.config/${folder}`, ...commands };
   }

package/dist/cli-credentials.d.ts

@@ -1,12 +1,14 @@
 /** What a plugin declares: `name` as it was declared (the folder, or the
  * path), which `mfw credentials` takes; `path` relative to the home; and the
  * commands, each a binary on the container's PATH and its arguments: `setup`
- * sets up the service identity, `check` reports on the login, `logout`
- * removes one identity's login (the service's, or a person's with `--user`). */
+ * sets up the service identity, `userSetup` the app people log in through
+ * (no person logged in), `check` reports on the login, `logout` removes one
+ * identity's login (the service's, or a person's with `--user`). */
 export type DeclaredCredentials = {
     name: string;
     path: string;
     setup: string[];
+    userSetup?: string[];
     check?: string[];
     logout?: string[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/utils",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "license": "MIT",
   "repository": {
     "type": "git",