@hixumo/hive 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+Hixumo Hive CLI
+Copyright (c) 2026 Hixumo. All rights reserved.
+
+This software (the Hixumo Hive command-line tool, published on npm as @hixumo/hive) is made
+available by Hixumo for one purpose: to work with the Hixumo Hive service.
+
+You may install and run this software, unchanged, on any computer, server or build system
+(including continuous integration), to use the Hixumo Hive service.
+
+You may not, without Hixumo's written permission:
+
+  1. copy, modify, adapt or translate this software, or make works based on it;
+  2. sell, rent, sublicense, redistribute or publish this software, in whole or in part,
+     other than by pointing to its official package on npm;
+  3. remove or change this notice or any notice of ownership in the software.
+
+Hixumo keeps all rights in the software that this licence does not expressly grant. Your use
+of the Hixumo Hive service itself is governed by its own terms.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL HIXUMO BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,321 @@
-# Temporary Holding Version
+# @hixumo/hive
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Hixumo Hive CLI: run a project with its environment's values from Hixumo Hive, without a
+`.env` file. Sign in once per computer, link a folder to a project, and `hive run` the rest. In
+GitHub Actions, GitHub vouches for the run and no token is kept anywhere; on other servers and in
+other CI, an access token in `HIVE_TOKEN` does the same with no sign-in.
+
+Needs Node 22 or newer.
+
+## Install
+
+Nothing to install:
+
+```sh
+npx @hixumo/hive login
+npx @hixumo/hive run -- npm run dev
+```
+
+Or keep it in a project (`npm install --save-dev @hixumo/hive`, then `npx hive …`), or for every
+folder (`npm install --global @hixumo/hive`, then `hive …`). The examples below say `hive`.
+
+## On a laptop
+
+```sh
+hive login                      # once per computer: a code, the browser, Approve
+cd client-a-app
+hive link                       # pick space → project → environment; writes .hive.json
+hive run -- npm run dev         # this folder's values, no .env file
+hive run --env staging -- npm test
+hive pull                       # a .env file, when a tool needs one (asks first)
+hive whoami
+hive logout
+```
+
+## Commands
+
+### `hive login [--no-browser]`
+
+Signs this computer in, as `gh auth login` does: it shows a one-time code (`WDJB-MJHT`) and opens
+the Hive website, where you check the code matches and approve ("Confirm it is you" first).
+`--no-browser` only prints the address, for a computer without one.
+
+One sign-in per computer for each Hive (each Hive API address). Signed in to this Hive already,
+it says as whom and asks before replacing it (the replaced one is ended at Hive); a sign-in to
+another Hive is left as it is. It lasts until `hive logout`, until it is ended from another
+computer or the website, or until it is 90 days unused. It needs a terminal: on servers, use
+`HIVE_TOKEN`.
+
+### `hive logout`
+
+Ends this computer's sign-in to this Hive at Hive, then forgets it here. When Hive cannot be
+reached it is still forgotten here, and the CLI says so: end it later with `hive sessions revoke`
+from another computer, or on the website's "Your sign-ins" page. When the system keychain will
+not let it be removed, the CLI says that instead, with the entry to remove by hand, and exits 1.
+
+### `hive whoami [--env <name>]`
+
+The account signed in on this computer, and the Hive it talks to. With `HIVE_TOKEN` set: the
+token's space, project and environment, and when it expires. In GitHub Actions: the repository and
+what its run may read, as in "GitHub Actions (hixumo/hixumo-backend) reads production of
+hixumo-backend, in Hixumo." (the access it takes for this is ended at once). There `--env` names
+the environment to check, else `HIVE_ENV`, else `.hive.json`; elsewhere it is not used.
+
+### `hive link [--project <id>] [--env <name>] [--yes]`
+
+Pick the space, the project and the environment with the arrow keys (a single choice is taken
+without asking). Your personal space comes first, its name followed by "(personal)", then every
+organization you are in by name, with your role there (owner, admin or member) dimmed after it; a
+paused space is not offered. Then `.hive.json` is written in this folder:
+
+```json
+{
+  "project": "7f3a9c2e-1b2c-4d5e-8f90-123456789abc",
+  "environment": "development"
+}
+```
+
+It holds no secret: a project id opens nothing by itself. Commit it, so everyone on the project
+runs with the same project. `environment` is the default environment's name. A folder already
+linked is replaced only after you say yes; `--yes` replaces it without asking, and is needed for
+that without a terminal. With both `--project` and `--env` it asks nothing.
+
+### `hive run [--env <name>] -- <command…>`
+
+Reads the values and starts the command with them added to its environment. Hive's values win
+over the shell's. `HIVE_TOKEN` is taken out of the command's environment: the command gets the
+values, not the key to them. The command gets the terminal as it is (its output is never touched;
+the CLI's own messages go to stderr), Ctrl+C and other signals reach it once (at a terminal,
+Ctrl+C comes from the terminal itself, so the CLI does not send it again), and `hive run` exits
+with its exit code (130 when it stopped on Ctrl+C). No file is written.
+
+Everything after `--` is the command, its own options included: `hive run -- npm test -- --watch`.
+
+### `hive pull [--env <name>] [--out <file>] [--yes]`
+
+Writes the values as a `.env` file (`--out`, default `.env` in this folder), readable only by you
+(mode 0600), in the same form as the website's "Copy as .env". It asks before replacing a file,
+and when no `.gitignore` line covers the file it warns and offers to add one (it reads and writes
+`.gitignore` files only; it never runs git). The line goes beside `.hive.json`, or in the
+repository root's `.gitignore` when `.hive.json` is above the repository, where git would not
+read it. Without a terminal it needs `--yes`, which answers yes to both.
+
+Prefer `hive run`: a `.env` file is one more copy of the values.
+
+### `hive sessions [--json]`
+
+Every sign-in of yours, numbered: the CLI on each computer and the website in each browser.
+
+```
+CLI sign-ins (2)
+  1  MacBook-Pro (this computer)  made 2 Nov   last used just now    from 39.45.10.21
+  2  office-pc                    made 28 Oct  last used 3 days ago  from 182.180.4.9
+
+Website sign-ins (1)
+  3  Chrome on macOS  started 2 hours ago  ends in 29 days  from 39.45.10.21
+```
+
+`--json` prints the same with each sign-in's id, for scripts.
+
+### `hive sessions revoke <number or id> [--yes]`
+
+Ends one of them, after showing which and asking (`--yes` skips the question, and is needed
+without a terminal). The number is the one `hive sessions` showed; the id from `--json` works as
+well. A CLI sign-in is refused from its next request; a website one is signed out, and its
+browser is sent to sign in. This computer's own sign-in is ended with `hive logout`.
+
+Ending a sign-in needs "Confirm it is you" within the last 10 minutes, so a stolen CLI sign-in
+cannot keep its owner out. When it is older, the CLI opens the browser to confirm, then ends the
+sign-in. Without a terminal it stops and says so: run it in a terminal, or end the sign-in on the
+website's "Your sign-ins" page.
+
+### `hive help [command]`, `hive --version`
+
+`hive <command> --help` works too.
+
+## Choosing what to read
+
+- **`HIVE_TOKEN` set:** the token decides the project and the environment; any sign-in on the
+  computer is ignored, and no `.hive.json` is needed. A committed `.hive.json`'s environment is
+  ignored (it is the developers' default; a deploy's token is production's). The run stops with a
+  sentence when `.hive.json` names another project (the wrong token in this repository), or when
+  `--env` or `HIVE_ENV` names another environment than the token's. A `.hive.json` that cannot be
+  read, or is not a link file, is left out with one warning.
+- **Else, in GitHub Actions with `permissions: id-token: write`:** GitHub vouches for the run (see
+  below). The project comes from `HIVE_PROJECT`, else the nearest `.hive.json`; the environment
+  from `--env`, else `HIVE_ENV`, else `.hive.json`.
+- **Otherwise:** this computer's sign-in, the nearest `.hive.json` (this folder, then each one
+  above it), and the environment from `--env`, else `HIVE_ENV`, else `.hive.json`. Names match
+  ignoring case (`--env Production` finds `production`).
+
+Not signed in and no token: "Run `hive login` first, or set HIVE_TOKEN." In GitHub Actions without
+the permission: "Add `permissions: id-token: write` to this workflow (or job) so Hive can check who
+is running it."
+
+### Protected environments
+
+Reading a protected environment (production, by default) with your own sign-in needs "Confirm it
+is you" within the last 10 minutes, as on the website. The CLI opens the browser for it and
+carries on by itself. Without a terminal it stops: "production is protected. Use an access token
+on servers, or run this in a terminal." An access token never asks.
+
+## In GitHub Actions: no token at all
+
+GitHub signs a short token for each run that says which repository, branch or tag, GitHub
+environment and workflow it is (OpenID Connect, as GitHub does for AWS). Hive checks it against
+the project's GitHub Actions rules, and a run one of them allows gets a workflow access: one
+environment, read only, 5 minutes at most. The CLI ends it as soon as the values are read, before
+your command starts. Nothing is stored in GitHub, and neither GitHub's token nor the access is
+ever printed or given to the command.
+
+1. Once per GitHub account: the space's **Connections** tab on the Hive website →
+   **Connect GitHub account**.
+2. Per environment: the project's **Machine access** tab → GitHub Actions → **Add rule** (the
+   repository, its GitHub environment, a branch or tag, and optionally the workflow file).
+3. The workflow:
+
+   ```yaml
+   name: Deploy
+   on:
+     release:
+       types: [published]
+   permissions:
+     id-token: write
+     contents: read
+   jobs:
+     deploy:
+       runs-on: ubuntu-latest
+       environment: production
+       steps:
+         - uses: actions/checkout@v4
+         - run: npx @hixumo/hive run --env production -- npm run build
+   ```
+
+   The project comes from the committed `.hive.json` (or `HIVE_PROJECT`, the project's id, set in
+   the workflow). `npx @hixumo/hive whoami --env production` in a step says what the run may read.
+
+Only `push`, `release`, `workflow_dispatch`, `schedule` and `deployment` runs are let in; pull
+requests never are. A run no rule allows is refused with what GitHub said about it:
+
+```
+Error: No GitHub Actions rule of production allows this. Add one in the project's Machine access tab.
+This run, as GitHub describes it:
+  repository   hixumo/hixumo-backend
+  ref          refs/heads/main
+  environment  production
+  event        push
+  workflow     .github/workflows/deploy.yml
+```
+
+`HIVE_TOKEN`, when it is set, is used instead.
+
+## On other servers and in other CI: `HIVE_TOKEN`
+
+Make an access token in the project's Machine access tab on the Hive website (one project, one
+environment, read only), and keep it as a secret. Protected environments (production) have
+access tokens off until an Owner or Admin turns them on there.
+
+```yaml
+- run: npx @hixumo/hive run -- npm run build
+  env:
+    HIVE_TOKEN: ${{ secrets.HIVE_TOKEN }}
+```
+
+Any server: `HIVE_TOKEN=hive_st_… npx @hixumo/hive run -- node server.js`.
+`hive whoami` says what a token reads. A token that is revoked or has expired is refused with a
+sentence that says which; the CLI never prints the token.
+
+## Where things are kept
+
+| What | Where |
+|---|---|
+| The sign-in's token | The system keychain (macOS Keychain, Windows Credential Manager, the Linux Secret Service), service `hixumo-hive`, account the Hive API's address (like `https://hive-api.example.com`): one entry per Hive. Where there is none, `credentials.json` in the config folder, `{ "apiUrl", "token" }`, readable only by you, with a warning when it is saved; it keeps one sign-in, so signing in to another Hive there replaces it (and ends it at its Hive). |
+| The account's name and email, and which Hive it is for | `config.json` in the config folder. Never the token. |
+| The config folder | `$XDG_CONFIG_HOME/hixumo-hive`, else `~/.config/hixumo-hive`; `%APPDATA%\hixumo-hive` on Windows. |
+| A folder's project | `.hive.json`, committed. |
+
+Each token is saved with the Hive API address it was made with, and only ever sent there: a
+`HIVE_API_URL` pointing elsewhere later finds no sign-in until you `hive login` there, and signing
+in to one Hive (from any config folder) never replaces another Hive's sign-in in the keychain.
+
+## Settings
+
+| Variable | Does |
+|---|---|
+| `HIVE_TOKEN` | An access token (`hive_st_…`): use it instead of the sign-in. |
+| `HIVE_ENV` | The environment, for one shell (`--env` wins over it). |
+| `HIVE_PROJECT` | GitHub Actions only: the project's id, instead of the one in `.hive.json`. |
+| `HIVE_API_URL` | The Hive API's address (an origin, https), instead of the one built in. |
+| `HIVE_CONFIG_DIR` | Another config folder. |
+| `HIVE_KEYRING=off` | Do not use the keychain: `credentials.json` only. |
+| `NO_COLOR` | No colour. (Colour is only ever used on a terminal.) |
+
+Exit codes: 0 done, 1 refused or failed (or answered "no"), 2 wrong usage, 130 stopped with
+Ctrl+C. `hive run` exits with its command's own.
+
+Messages go to stderr; what you asked for (`whoami`, `sessions`) goes to stdout. Nothing the CLI
+prints ever holds a value or a token.
+
+## Developing
+
+Building and testing need Node 22.18 or newer (the tests run the TypeScript sources directly).
+
+```sh
+npm ci
+HIVE_API_URL=http://localhost:8200 npm run build   # dist/, for the local Hive API
+npm run typecheck
+npm test
+node dist/cli.js help
+```
+
+- The address built in comes from `HIVE_API_URL` in the environment, else from this repository's
+  `.env` (see `.env.example`). `scripts/write-build-info.mjs` writes it to `src/build-info.ts`
+  (not committed) and refuses an address that is not https, except localhost. No address is
+  written in the source.
+- The tests play the Hive API with a small server of their own (`tests/fake-hive.ts`), run the
+  commands in their process and the real CLI as a child, and keep every file they write in a
+  temporary folder: `HIVE_TEST_TMP` when it is set, else the system's. They set
+  `HIVE_CONFIG_DIR` and `HIVE_KEYRING=off`, so nothing reaches the home folder or the keychain.
+  For a local run against a real Hive, do the same:
+  `HIVE_CONFIG_DIR=<a scratch folder> HIVE_KEYRING=off HIVE_API_URL=http://localhost:8200 node dist/cli.js login`.
+
+## Releasing
+
+The CLI repository's GitHub environment `production` holds the variable `HIVE_API_URL`, the Hive
+API's public address; `publish.yml` runs in that environment and builds with it. Pull requests'
+CI builds with a placeholder (`https://hive-api.example.com`): it never gets the environment. `prepublishOnly` refuses to publish a build made for anything but a
+public https address.
+
+A push to `main` that changes the CLI (`src/`, `scripts/`, `package.json`, the lock file,
+`tsconfig.build.json` or the workflow) publishes the next version by itself, then tags it
+`v<version>` and makes its GitHub Release with the changes since the last one. Nobody edits a
+version number: each digit goes from 0 to 9, then the one before it goes up
+(`0.2.0 → 0.2.1 → … → 0.2.9 → 0.3.0 → … → 0.9.9 → 1.0.0`, `scripts/next-version.mjs`). The
+first publish is `package.json`'s version as it is; for a jump (like `1.0.0`), raise
+`package.json` past the newest tag by hand. The version is set on the runner only, so
+`package.json` in the repository keeps its first version and nothing is pushed back to `main`.
+A push that only changes docs publishes nothing.
+
+1. Create the `hixumo` organization on npmjs.com.
+2. The first version (npm sets up trusted publishing only on a package that already exists):
+   on npmjs.com make a granular access token (Bypass two-factor authentication on, since a
+   workflow can't type a 2FA code; packages and scopes: read and write; organizations: no
+   access; expiring in a few days), and put it in this repository's `production`
+   environment as the secret `NPM_TOKEN`. Push to `main` (or run the workflow from the Actions
+   tab): it publishes `package.json`'s version with it.
+3. On the package's settings page on npmjs.com, add this repository's `publish.yml` as its
+   trusted publisher, with the environment `production`, and allow direct publishing
+   (`npm publish`): the workflow publishes directly. npm drops a configuration that hasn't
+   published within 2 days, so push (or re-run the workflow) soon after. Then delete the `NPM_TOKEN` secret,
+   and the token on npmjs.com.
+4. From then on: push to `main`. Each push that changes the CLI publishes the next version,
+   tags it and makes its Release. No npm token is stored anywhere.
+
+The package is public on npm while this repository stays private. npm makes a provenance
+statement only for a public repository, so `publish.yml` publishes without one; if the
+repository is ever made public, add `--provenance` there.
+
+## Licence
+
+Not open source. The CLI may be installed and run, unchanged, to use Hixumo Hive; copying,
+changing or redistributing it needs Hixumo's permission. See `LICENSE`.

package/dist/api-address.js

@@ -0,0 +1,24 @@
+/**
+ * The Hive API's address, as an origin (scheme, host and port); the CLI adds `/api/v1` itself.
+ * One rule for the address built in (scripts/write-build-info.mjs) and for HIVE_API_URL when the
+ * CLI runs: every request carries a token, so it only ever goes over https, except to this
+ * computer.
+ */
+const THIS_COMPUTER = new Set(['localhost', '127.0.0.1', '[::1]']);
+export function apiOriginOf(address) {
+    let url;
+    try {
+        url = new URL(address.trim());
+    }
+    catch {
+        throw new Error("HIVE_API_URL must be the Hive API's address, like https://hive-api.example.com.");
+    }
+    const local = url.protocol === 'http:' && THIS_COMPUTER.has(url.hostname);
+    if (url.protocol !== 'https:' && !local) {
+        throw new Error('HIVE_API_URL must start with https:// (plain http only for localhost): every request carries a token.');
+    }
+    if (url.pathname !== '/' || url.search || url.hash || url.username || url.password) {
+        throw new Error(`HIVE_API_URL must be an origin, like ${url.origin}, without a path: the CLI adds /api/v1.`);
+    }
+    return url.origin;
+}

package/dist/api.js

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { plain } from "./output.js";
+import { USER_AGENT } from "./version.js";
+/** A call the API refused, or that never reached it (`status` 0). */
+export class ApiError extends Error {
+    status;
+    /** The word to act on, when the API gave one: "reauth_required", "token_invalid". */
+    code;
+    /** `github_token_invalid`: which check GitHub's token failed ("audience", "expired", …). */
+    reason;
+    /** `github_not_allowed`: the run as GitHub's token describes it. */
+    claims;
+    constructor(status, message, code, details = {}) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.code = code;
+        this.reason = details.reason;
+        this.claims = details.claims;
+    }
+}
+export const API_PREFIX = '/api/v1';
+const TIMEOUT_MS = 20_000;
+const RETRY_DELAY_MS = 500;
+const WORKFLOW_ACCESS_PREFIX = 'hive_gh_';
+export class HiveApi {
+    origin;
+    token;
+    send;
+    timeoutMs;
+    retryDelayMs;
+    constructor(options) {
+        this.origin = options.origin;
+        this.token = options.token;
+        this.send = options.fetch ?? ((...args) => fetch(...args));
+        this.timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+        this.retryDelayMs = options.retryDelayMs ?? RETRY_DELAY_MS;
+    }
+    me() {
+        return this.request('GET', '/me');
+    }
+    projects(spaceId) {
+        return this.request('GET', `/spaces/${segment(spaceId)}/projects`);
+    }
+    project(projectId) {
+        return this.request('GET', `/projects/${segment(projectId)}`);
+    }
+    reveal(environmentId) {
+        return this.request('POST', `/environments/${segment(environmentId)}/reveal`);
+    }
+    tokenInfo() {
+        return this.request('GET', '/token');
+    }
+    tokenValues() {
+        return this.request('GET', '/token/values');
+    }
+    /** GitHub's OIDC token for this run, traded for a workflow access (no Hive token is sent). */
+    githubAccess(body) {
+        return this.request('POST', '/github/access', body);
+    }
+    /** Ends this workflow access at Hive (204). Only ever sent with one: never with an access token. */
+    async endToken() {
+        if (!this.token?.startsWith(WORKFLOW_ACCESS_PREFIX))
+            throw new Error('Only a workflow access is ended.');
+        await this.request('POST', '/token/end');
+    }
+    startLogin(deviceName) {
+        return this.request('POST', '/cli/login', { deviceName });
+    }
+    pollLogin(deviceCode) {
+        return this.request('POST', '/cli/login/poll', { deviceCode });
+    }
+    startConfirm() {
+        return this.request('POST', '/cli/confirm');
+    }
+    pollConfirm(deviceCode) {
+        return this.request('POST', '/cli/confirm/poll', { deviceCode });
+    }
+    logout() {
+        return this.request('POST', '/cli/logout');
+    }
+    signIns() {
+        return this.request('GET', '/me/sign-ins');
+    }
+    revokeCliSignIn(id) {
+        return this.request('POST', `/me/sign-ins/cli/${segment(id)}/revoke`);
+    }
+    endWebsiteSignIn(id) {
+        return this.request('POST', `/me/sign-ins/website/${segment(id)}/end`);
+    }
+    /** The `data` of a successful answer; an ApiError for anything else. */
+    async request(method, path, body) {
+        const text = body === undefined ? undefined : JSON.stringify(body);
+        const headers = { Accept: 'application/json', 'User-Agent': USER_AGENT };
+        if (this.token)
+            headers['X-Hive-Token'] = this.token;
+        if (text !== undefined)
+            headers['Content-Type'] = 'application/json';
+        if (method !== 'GET')
+            headers['x-amz-content-sha256'] = createHash('sha256').update(text ?? '').digest('hex');
+        const url = `${this.origin}${API_PREFIX}${path}`;
+        let response;
+        let answer;
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                response = await this.send(url, {
+                    method,
+                    headers,
+                    body: text,
+                    redirect: 'manual',
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+                answer = await response.text();
+                break;
+            }
+            catch (error) {
+                if (method === 'GET' && attempt === 1 && error instanceof TypeError) {
+                    await new Promise((resolve) => setTimeout(resolve, this.retryDelayMs));
+                    continue;
+                }
+                throw this.unreached(error);
+            }
+        }
+        if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400)) {
+            throw new ApiError(response.status, `Hive answered with a redirect, which hive never follows. Check HIVE_API_URL (${this.origin}).`);
+        }
+        // Done, with nothing to say (`POST /token/end`).
+        if (response.status === 204)
+            return undefined;
+        let envelope;
+        try {
+            envelope = JSON.parse(answer);
+        }
+        catch {
+            // Not JSON: an error page from something in front of the API.
+        }
+        if (response.ok && envelope?.success === true) {
+            return envelope.data;
+        }
+        const claims = envelope?.claims;
+        throw new ApiError(response.status, messageOf(envelope?.message) ?? `Hive could not answer (${response.status}).`, typeof envelope?.code === 'string' ? envelope.code : undefined, {
+            reason: typeof envelope?.reason === 'string' ? envelope.reason : undefined,
+            claims: typeof claims === 'object' && claims !== null && !Array.isArray(claims) ? claims : undefined,
+        });
+    }
+    unreached(error) {
+        if (error?.name === 'TimeoutError') {
+            return new ApiError(0, `Hive did not answer within ${this.timeoutMs / 1000} seconds.`);
+        }
+        const code = error?.cause?.code;
+        return new ApiError(0, `Could not reach Hive at ${this.origin}${typeof code === 'string' ? ` (${code})` : ''}.`);
+    }
+}
+/** An id as one path segment: `../me` stays inside the route it was meant for. */
+function segment(id) {
+    return encodeURIComponent(id);
+}
+function messageOf(message) {
+    if (typeof message === 'string' && message)
+        return plain(message);
+    if (Array.isArray(message) && message.length)
+        return plain(message.join('; '));
+    return undefined;
+}

package/dist/browser.js

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+export function browserCommand(url, platform) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        return undefined;
+    // The address as the parser read it, never the text it came as: the parser drops spaces around
+    // it and line breaks and tabs inside it, which cmd would otherwise read as its own.
+    const address = parsed.href;
+    switch (platform) {
+        case 'darwin':
+            return { command: 'open', args: [address] };
+        case 'win32':
+            // `start` is part of cmd. In double quotes cmd takes & and | as text; a quote or a % (its
+            // variables) still could break out, and Hive's addresses have neither.
+            if (/["%]/.test(address))
+                return undefined;
+            return { command: 'cmd', args: ['/c', 'start', '""', `"${address}"`] };
+        default:
+            return { command: 'xdg-open', args: [address] };
+    }
+}
+export function openBrowser(url) {
+    const how = browserCommand(url, process.platform);
+    if (!how)
+        return;
+    try {
+        const child = spawn(how.command, how.args, {
+            stdio: 'ignore',
+            detached: true,
+            // The quotes above are cmd's; Node must not add its own around them.
+            windowsVerbatimArguments: process.platform === 'win32',
+        });
+        child.on('error', () => {
+            // No opener here: the address is printed.
+        });
+        child.unref();
+    }
+    catch {
+        // The same.
+    }
+}

package/dist/build-info.js

@@ -0,0 +1,3 @@
+// Written by scripts/write-build-info.mjs on every build; not committed (see .gitignore).
+/** The Hive API this build talks to, as an origin; HIVE_API_URL overrides it when the CLI runs. */
+export const BUILT_API_URL = 'https://hive-api.hixumo.com';