@mercury-fw/cli 0.27.1 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @mercury-fw/cli
 
+## 0.28.0
+
+### Minor Changes
+
+- 51bd439: `mfw google-chat set-key <key-file> [--subscription <name>]` writes the Google Chat channel's service account key (and its subscription) into the app's env file, the key on one line the way the channel reads it and never printed. The channel's setup uses it in place of the hand-written `sed`/`printf` step.
+
+### Patch Changes
+
+- @mercury-fw/core@0.28.0
+
 ## 0.27.1
 
 ### Patch Changes

package/README.md

@@ -19,6 +19,7 @@
   - [`mfw reset <memory|wiki>`](#mfw-reset-memorywiki)
   - [`mfw credentials set <plugin> [--from <dir>] [--print]`](#mfw-credentials-set-plugin---from-dir---print)
   - [`mfw credentials reset <plugin>`](#mfw-credentials-reset-plugin)
+  - [`mfw google-chat set-key <key-file> [--subscription <name>]`](#mfw-google-chat-set-key-key-file---subscription-name)
 - [Help](#help)
 
 ## Getting it
@@ -188,6 +189,17 @@ Deletes the plugin's CLI folder from the credentials volume, so the variable in
 bunx mfw credentials reset jira
 ```
 
+### `mfw google-chat set-key <key-file> [--subscription <name>]`
+
+Writes the Google Chat channel's credentials into the app's `.env`, from the service account's JSON key (the file `gcloud iam service-accounts keys create` writes): `GOOGLE_CHAT_APP_CLIENT_EMAIL`, and `GOOGLE_CHAT_APP_PRIVATE_KEY` on one line with literal `\n`, the way the channel reads it. With `--subscription` (`projects/<project>/subscriptions/<name>`) it sets `GOOGLE_CHAT_PUBSUB_SUBSCRIPTION` too; without it, that line stays as it is, which is what you want when only the key changes. Older values and the empty lines `mfw create` leaves are replaced, the other lines stay alone, and the key is never printed.
+
+It checks everything before writing: the app has to depend on `@mercury-fw/channel-google-chat`, the file has to be a service account key and the subscription has to have that shape, otherwise it exits 1 saying why and `.env` stays as it was. Delete the key file afterwards; `bunx mfw start` applies the change to a running app. The whole setup of the Chat app is in the [channel's README](https://github.com/lucabro81/mercury-fw/tree/main/packages/channels/channel-google-chat#setting-up-the-chat-app).
+
+```bash
+bunx mfw google-chat set-key key.json --subscription projects/my-project/subscriptions/mercury-chat-sub
+bunx mfw google-chat set-key new-key.json
+```
+
 ## Help
 
 `mfw --help` lists every command, and `--help` after any of them describes it, down to the subcommands (`mfw vault write-curated --help`). A mistyped command gets a suggestion (`mfw strat` → "Did you mean start?"). Every argument is checked before anything runs: a wrong one exits 1 saying why, with no container started.

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

@@ -67,6 +67,13 @@ export declare function appCommands(app: App, deps: AppDeps): {
      * user types the plugin's name, so its variable is unpacked again at the
      * next start. A wrong answer deletes nothing. */
     credentialsReset: (plugin: string) => Promise<number>;
+    /** Writes the Google Chat channel's service account key (the JSON file
+     * at `keyFile`) into the app's env file, and the Pub/Sub subscription when
+     * given. Everything is checked before anything is written; the key is
+     * never printed. */
+    googleChatSetKey: (keyFile: string, { subscription }: {
+        subscription?: string;
+    }) => Promise<number>;
 };
 /** The real deps: docker on the user's terminal, questions on `input`
  * (stdin by default). */

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

@@ -10,3 +10,12 @@ export declare function packCredentials(from: string, folder: string): Promise<s
  * keeping its permissions, so a failed write never leaves it half written; a
  * missing file is created readable by its owner only. */
 export declare function setEnvVar(file: string, name: string, value: string): void;
+/** The two values of a Google Cloud service account key file (the JSON
+ * `gcloud iam service-accounts keys create` writes) that an app needs: its
+ * email, and its private key on one line with literal `\n`, the form an env
+ * file holds and the Google Chat channel unescapes. Throws naming `file` when
+ * it's missing or isn't such a key. */
+export declare function readServiceAccountKey(file: string): {
+    clientEmail: string;
+    privateKey: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -36,13 +36,13 @@
   "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.27.1",
+    "@mercury-fw/core": "0.28.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-google-chat": "0.1.0",
+    "@mercury-fw/channel-google-chat": "0.1.1",
     "@mercury-fw/channel-http": "0.1.0",
-    "@mercury-fw/formatter": "0.27.1",
+    "@mercury-fw/formatter": "0.28.0",
     "@mercury-fw/plugin-atlassian-admin": "0.1.0",
     "@mercury-fw/plugin-bitbucket": "0.1.0",
     "@mercury-fw/plugin-jira": "0.1.0",

package/src/app/commands.ts

@@ -9,7 +9,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { CATALOG, type CliCredentials } from "../catalog.ts";
-import { packCredentials, setEnvVar } from "./credentials.ts";
+import { packCredentials, readServiceAccountKey, setEnvVar } from "./credentials.ts";
 import type { App } from "./find-app.ts";
 
 export type AppDeps = {
@@ -27,6 +27,9 @@ export type AppDeps = {
 
 const COMPOSE = ["docker", "compose"];
 
+/** The Google Chat channel's package, which `google-chat` commands require. */
+const GOOGLE_CHAT_PACKAGE = "@mercury-fw/channel-google-chat";
+
 /** The app's service, the one the image builds. */
 const SERVICE = "mercury";
 
@@ -143,6 +146,34 @@ export function appCommands(app: App, deps: AppDeps) {
       }
       return stopped(SERVICE, [[...COMPOSE, "run", "--rm", "--no-deps", "-T", SERVICE, "rm", "-rf", `/home/mercury/.config/${folder}`]]);
     },
+    /** Writes the Google Chat channel's service account key (the JSON file
+     * at `keyFile`) into the app's env file, and the Pub/Sub subscription when
+     * given. Everything is checked before anything is written; the key is
+     * never printed. */
+    googleChatSetKey: async (keyFile: string, { subscription }: { subscription?: string }) => {
+      const manifest = JSON.parse(readFileSync(join(app.dir, "package.json"), "utf-8")) as {
+        dependencies?: Record<string, string>;
+      };
+      if (manifest.dependencies?.[GOOGLE_CHAT_PACKAGE] === undefined) {
+        throw new Error(`${app.name} doesn't have the Google Chat channel (${GOOGLE_CHAT_PACKAGE}) among its dependencies.`);
+      }
+      if (subscription !== undefined && !/^projects\/[^/]+\/subscriptions\/[^/]+$/.test(subscription)) {
+        throw new Error(`--subscription takes projects/<project>/subscriptions/<name> (got "${subscription}").`);
+      }
+      const source = resolve(keyFile);
+      const { clientEmail, privateKey } = readServiceAccountKey(source);
+      const envFile = join(app.dir, ".env");
+      setEnvVar(envFile, "GOOGLE_CHAT_APP_CLIENT_EMAIL", clientEmail);
+      setEnvVar(envFile, "GOOGLE_CHAT_APP_PRIVATE_KEY", privateKey);
+      if (subscription !== undefined) setEnvVar(envFile, "GOOGLE_CHAT_PUBSUB_SUBSCRIPTION", subscription);
+      const written =
+        subscription === undefined
+          ? "GOOGLE_CHAT_APP_CLIENT_EMAIL and GOOGLE_CHAT_APP_PRIVATE_KEY"
+          : "GOOGLE_CHAT_APP_CLIENT_EMAIL, GOOGLE_CHAT_APP_PRIVATE_KEY and GOOGLE_CHAT_PUBSUB_SUBSCRIPTION";
+      deps.print(`${written} set in ${envFile}, from ${source}.`);
+      deps.print(`Delete ${source} now, the env file holds the key. bunx mfw start applies it to a running app.`);
+      return 0;
+    },
   };
 
   /** Stops `service`, runs `steps`, starts it again; stops at the first

package/src/app/credentials.ts

@@ -2,7 +2,8 @@
  * The two halves of `mfw credentials set`: packing a CLI's config folder into
  * its credentials variable (a base64 tar.gz with the folder at its root, what
  * the app's `docker-entrypoint.sh` unpacks into `~/.config` on the volume), and
- * writing that variable into the app's env file.
+ * writing that variable into the app's env file. Also reading a service
+ * account key file, for `mfw google-chat set-key`.
  */
 import {
   chmodSync,
@@ -80,3 +81,23 @@ export function setEnvVar(file: string, name: string, value: string): void {
   chmodSync(temporary, mode);
   renameSync(temporary, file);
 }
+
+/** The two values of a Google Cloud service account key file (the JSON
+ * `gcloud iam service-accounts keys create` writes) that an app needs: its
+ * email, and its private key on one line with literal `\n`, the form an env
+ * file holds and the Google Chat channel unescapes. Throws naming `file` when
+ * it's missing or isn't such a key. */
+export function readServiceAccountKey(file: string): { clientEmail: string; privateKey: string } {
+  const invalid = () => new Error(`${file} isn't a service account key: it needs "type": "service_account", "client_email" and "private_key".`);
+  let key: { type?: unknown; client_email?: unknown; private_key?: unknown };
+  try {
+    key = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`${file} doesn't exist.`);
+    throw invalid();
+  }
+  if (key?.type !== "service_account" || typeof key.client_email !== "string" || typeof key.private_key !== "string") {
+    throw invalid();
+  }
+  return { clientEmail: key.client_email, privateKey: key.private_key.replace(/\n/g, "\\n") };
+}

package/src/program.ts

@@ -228,6 +228,30 @@ Examples:
     .argument("<plugin>", "a tool plugin of the app")
     .action(async (plugin: string) => inApp((app) => app.credentialsReset(plugin))());
 
+  const googleChat = program
+    .command("google-chat")
+    .summary("the Google Chat channel's setup")
+    .description("Sets up the Google Chat channel of an app that has it.")
+    .helpCommand(false)
+    .addHelpText("after", INSIDE_AN_APP);
+  googleChat
+    .command("set-key")
+    .summary("writes the Chat app's key into the env file")
+    .description(
+      "Reads the service account key file gcloud iam service-accounts keys create writes, and sets GOOGLE_CHAT_APP_CLIENT_EMAIL and GOOGLE_CHAT_APP_PRIVATE_KEY in the app's env file (the key on one line), plus GOOGLE_CHAT_PUBSUB_SUBSCRIPTION with --subscription. Older values are replaced, the key is never printed. Delete the key file afterwards.",
+    )
+    .argument("<key-file>", "the service account's JSON key")
+    .option("--subscription <name>", "projects/<project>/subscriptions/<name>, the subscription the Chat app's events arrive on")
+    .addHelpText(
+      "after",
+      "\nExample:\n  mfw google-chat set-key key.json --subscription projects/my-project/subscriptions/mercury-chat-sub",
+    )
+    .action(async (keyFile: string, opts: { subscription?: string }) =>
+      inApp((app) =>
+        app.googleChatSetKey(keyFile, opts.subscription === undefined ? {} : { subscription: opts.subscription }),
+      )(),
+    );
+
   return program;
 }