@hixumo/hive 0.0.0-stage → 0.0.1

package/dist/github-actions.js

@@ -0,0 +1,142 @@
+import { ApiError, HiveApi } from "./api.js";
+import { explain } from "./callers.js";
+import { apiOrigin } from "./config.js";
+import { CliError, plain } from "./output.js";
+import { USER_AGENT } from "./version.js";
+/**
+ * GitHub Actions without a stored token (phase 2c). A job with `permissions: id-token: write`
+ * gets two variables from GitHub's runner; with them the CLI asks GitHub for an OIDC token for
+ * this run, meant for this Hive (its audience is the API's origin), trades it at
+ * `POST /github/access` for a workflow access (`hive_gh_…`: one environment, read only, 5
+ * minutes), reads with it as an access token reads, and ends it at `POST /token/end` as soon as
+ * the read is done, whether it worked or not. The command `hive run` starts never runs while the
+ * access is alive.
+ *
+ * Neither GitHub's token nor the access is ever printed, written down or passed to the command.
+ */
+const WORKFLOW_ACCESS_PREFIX = 'hive_gh_';
+const TIMEOUT_MS = 20_000;
+const RETRY_DELAY_MS = 500;
+const THIS_COMPUTER = new Set(['localhost', '127.0.0.1', '[::1]']);
+/**
+ * Trades GitHub's token for a workflow access, gives it to `read`, and ends it right after, also
+ * when `read` throws. Every refusal comes back as a CliError that says what to do.
+ */
+export async function withWorkflowAccess(ctx, request, target, read) {
+    const origin = apiOrigin(ctx.env);
+    try {
+        const githubToken = await githubTokenFor(ctx, request, origin);
+        const answer = await new HiveApi({ origin }).githubAccess({ githubToken, ...target });
+        if (typeof answer?.token !== 'string' || !answer.token.startsWith(WORKFLOW_ACCESS_PREFIX)) {
+            throw new CliError(`Hive answered with something that is not a workflow access, so nothing was read. Check HIVE_API_URL (${origin}).`);
+        }
+        const api = new HiveApi({ origin, token: answer.token });
+        try {
+            return await read(api);
+        }
+        finally {
+            await end(ctx, api);
+        }
+    }
+    catch (error) {
+        throw explainGithub(error, target, origin);
+    }
+}
+/** Ending a workflow access that cannot be ended stops nothing: it runs out by itself. */
+async function end(ctx, api) {
+    try {
+        await api.endToken();
+    }
+    catch (error) {
+        const why = error instanceof ApiError ? ` ${error.message}` : '';
+        ctx.ui.warn(`Could not end the workflow access at Hive.${why} It runs out by itself within 5 minutes.`);
+    }
+}
+/**
+ * GitHub's OIDC token for this run (`{ value }`), asked of the runner's address with its bearer,
+ * for the audience Hive checks. Its answer is never shown: only its status, when it refuses.
+ */
+async function githubTokenFor(ctx, request, audience) {
+    let url;
+    try {
+        url = new URL(request.url);
+    }
+    catch {
+        throw new CliError('ACTIONS_ID_TOKEN_REQUEST_URL is not an address. It is set by GitHub Actions; leave it as GitHub sets it.');
+    }
+    // The runner's bearer goes with the request: never in the clear, except to this computer.
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && THIS_COMPUTER.has(url.hostname))) {
+        throw new CliError('ACTIONS_ID_TOKEN_REQUEST_URL must be an https address. It is set by GitHub Actions; leave it as GitHub sets it.');
+    }
+    url.searchParams.set('audience', audience);
+    let response;
+    let text;
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            response = await fetch(url, {
+                headers: { Authorization: `bearer ${request.token}`, Accept: 'application/json', 'User-Agent': USER_AGENT },
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            text = await response.text();
+            break;
+        }
+        catch (error) {
+            if (attempt === 1 && error instanceof TypeError) {
+                await ctx.sleep(RETRY_DELAY_MS);
+                continue;
+            }
+            const timedOut = error?.name === 'TimeoutError';
+            throw new CliError(timedOut
+                ? `GitHub did not give a token for this run within ${TIMEOUT_MS / 1000} seconds. Run the job again.`
+                : 'Could not reach GitHub to get a token for this run. Run the job again.');
+        }
+    }
+    if (!response.ok) {
+        throw new CliError(`GitHub did not give a token for this run (${response.status}). Check that the workflow (or job) has \`permissions: id-token: write\`.`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text).value;
+    }
+    catch {
+        // Not JSON: said below.
+    }
+    if (typeof value !== 'string' || value === '') {
+        throw new CliError("GitHub's answer held no token for this run. Run the job again.");
+    }
+    return value;
+}
+/** A refusal as the sentence for a GitHub Actions run; anything else as callers.ts says it. */
+function explainGithub(error, target, origin) {
+    if (!(error instanceof ApiError))
+        return error;
+    switch (error.code) {
+        case 'github_not_allowed':
+            return new CliError([
+                `No GitHub Actions rule of ${plain(target.environment)} allows this. Add one in the project's Machine access tab.`,
+                ...claimLines(error.claims),
+            ].join('\n'));
+        case 'github_token_invalid':
+            if (error.reason === 'audience') {
+                return new CliError(`${error.message} The CLI asked GitHub for a token meant for ${origin}: check that HIVE_API_URL is Hive's public API address.`);
+            }
+            return new CliError(error.reason === 'expired' || error.reason === 'reused' ? `${error.message} Run the job again.` : error.message);
+        case 'token_invalid':
+            return new CliError(`${error.message} A workflow access lasts 5 minutes; run the job again.`);
+    }
+    return new CliError(explain(error));
+}
+/** The run as GitHub described it, one claim a line; text from the API, so plain. */
+function claimLines(claims) {
+    if (!claims)
+        return [];
+    const shown = (value) => (typeof value === 'string' && value !== '' ? plain(value) : '(none)');
+    const rows = [
+        ['repository', claims.repository],
+        ['ref', claims.ref],
+        ['environment', claims.environment],
+        ['event', claims.event],
+        ['workflow', claims.workflow],
+    ];
+    return ['This run, as GitHub describes it:', ...rows.map(([name, value]) => `  ${name.padEnd(13)}${shown(value)}`)];
+}

package/dist/gitignore.js

@@ -0,0 +1,169 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+/** The lines of one .gitignore as rules, comments and blank lines left out. */
+function rulesOf(lines) {
+    const rules = [];
+    for (const raw of lines) {
+        // Trailing spaces do not count unless escaped.
+        let line = raw.replace(/(?<!\\)\s+$/, '');
+        if (line === '' || line.startsWith('#'))
+            continue;
+        const negated = line.startsWith('!');
+        if (negated)
+            line = line.slice(1);
+        const foldersOnly = line.endsWith('/');
+        if (foldersOnly)
+            line = line.slice(0, -1);
+        const anchored = line.includes('/');
+        if (line.startsWith('/'))
+            line = line.slice(1);
+        if (line === '')
+            continue;
+        rules.push({ pattern: globToRegExp(line), negated, foldersOnly, anchored });
+    }
+    return rules;
+}
+function globToRegExp(glob) {
+    let source = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const char = glob[i];
+        if (char === '*') {
+            const atStart = i === 0 || glob[i - 1] === '/';
+            if (glob[i + 1] === '*' && atStart && (i + 2 === glob.length || glob[i + 2] === '/')) {
+                if (i + 2 === glob.length) {
+                    // `dir/**`: everything inside.
+                    source += '.*';
+                    i += 1;
+                }
+                else {
+                    // `**/`: any number of folders, none included.
+                    source += '(?:.*/)?';
+                    i += 2;
+                }
+                continue;
+            }
+            source += '[^/]*';
+            while (glob[i + 1] === '*')
+                i += 1;
+        }
+        else if (char === '?') {
+            source += '[^/]';
+        }
+        else if (char === '[' && glob.indexOf(']', i + 2) > 0) {
+            const end = glob.indexOf(']', i + 2);
+            let set = glob.slice(i + 1, end).replace(/\\/g, '\\\\');
+            if (set.startsWith('!'))
+                set = `^${set.slice(1)}`;
+            source += `[${set}]`;
+            i = end;
+        }
+        else if (char === '\\' && i + 1 < glob.length) {
+            i += 1;
+            source += escapeRegExp(glob[i]);
+        }
+        else {
+            source += escapeRegExp(char);
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+}
+/**
+ * Whether `path` (from the repository root, `/`-separated) is left out. Git does not look inside
+ * a folder it leaves out, so a file there cannot be taken back with `!`: each folder on the way
+ * is decided first, then the file; within that, a deeper .gitignore and a later line win.
+ */
+function leftOut(sets, path) {
+    const parts = path.split('/');
+    for (let length = 1; length <= parts.length; length += 1) {
+        const here = parts.slice(0, length).join('/');
+        const isFolder = length < parts.length;
+        let ignored = false;
+        for (const { base, rules } of sets) {
+            if (base && !here.startsWith(`${base}/`))
+                continue;
+            const local = base ? here.slice(base.length + 1) : here;
+            const name = local.slice(local.lastIndexOf('/') + 1);
+            for (const rule of rules) {
+                if (rule.foldersOnly && !isFolder)
+                    continue;
+                if (rule.pattern.test(rule.anchored ? local : name))
+                    ignored = !rule.negated;
+            }
+        }
+        if (ignored)
+            return true;
+    }
+    return false;
+}
+/** One .gitignore's lines against a path from its folder. */
+export function ignores(lines, path) {
+    return leftOut([{ base: '', rules: rulesOf(lines) }], path);
+}
+/**
+ * Reads every .gitignore from the file's folder up to the repository's root (the nearest folder
+ * with `.git`, a folder or, in a worktree or a submodule, a file; the filesystem root when there
+ * is none). The line, when one is needed, goes in the linked folder's .gitignore (`linkDir`,
+ * where `.hive.json` is) when the file is inside it and it is inside the repository, since git
+ * reads no .gitignore above the root; else the repository root's; with no repository, the
+ * linked folder's when the file is inside it, else the file's own folder's.
+ */
+export function checkGitignore(target, linkDir) {
+    const folders = [];
+    let root;
+    for (let dir = dirname(target);; dir = dirname(dir)) {
+        folders.push(dir);
+        // A file check only: git itself is never run.
+        if (existsSync(join(dir, '.git'))) {
+            root = dir;
+            break;
+        }
+        if (dirname(dir) === dir)
+            break;
+    }
+    const top = folders[folders.length - 1];
+    const sets = folders
+        .reverse()
+        .map((dir) => ({ dir, text: readIfThere(join(dir, '.gitignore')) }))
+        .filter(({ text }) => text !== undefined)
+        .map(({ dir, text }) => ({ base: posix(relative(top, dir)), rules: rulesOf(text.split(/\r?\n/)) }));
+    // A .hive.json above the repository (in a folder of several projects, say) is no place for it.
+    const home = linkDir && isInside(target, linkDir) && (root === undefined || within(linkDir, root))
+        ? linkDir
+        : (root ?? dirname(target));
+    return {
+        covered: leftOut(sets, posix(relative(top, target))),
+        file: join(home, '.gitignore'),
+        line: lineFor(posix(relative(home, target))),
+    };
+}
+export function addToGitignore(check) {
+    const text = readIfThere(check.file) ?? '';
+    const joiner = text === '' || text.endsWith('\n') ? '' : '\n';
+    writeFileSync(check.file, `${text}${joiner}${check.line}\n`);
+}
+function readIfThere(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function isInside(path, dir) {
+    const from = relative(dir, path);
+    return from !== '' && !from.startsWith('..') && !from.startsWith(sep) && !/^[A-Za-z]:/.test(from);
+}
+/** The folder itself, or one inside it. */
+function within(path, dir) {
+    return relative(dir, path) === '' || isInside(path, dir);
+}
+function posix(path) {
+    return path.split(sep).join('/');
+}
+/** The path as a .gitignore line: glob characters and a leading `#` or `!` taken literally. */
+function lineFor(path) {
+    return path.replace(/[*?[\\]/g, '\\$&').replace(/^[#!]/, '\\$&');
+}

package/dist/link-file.js

@@ -0,0 +1,67 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { codeOf } from "./files.js";
+import { CliError } from "./output.js";
+/**
+ * `.hive.json`: which project a folder runs with, and its default environment, by name (contract
+ * C4). It is committed and holds no secret: a project id opens nothing by itself.
+ */
+export const LINK_FILE = '.hive.json';
+const PROJECT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Project ids are UUIDs; anything else is refused before it can become part of a path. */
+export function isProjectId(text) {
+    return PROJECT_ID.test(text);
+}
+/** The nearest `.hive.json`: in this folder, then each one above it up to the filesystem root. */
+export function findLink(from) {
+    for (let dir = resolve(from);; dir = dirname(dir)) {
+        const path = join(dir, LINK_FILE);
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (error) {
+            const code = codeOf(error);
+            if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                throw new CliError(`Could not read ${path} (${code}).`);
+            }
+        }
+        if (text !== undefined)
+            return { path, dir, link: parseLink(text, path) };
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+function parseLink(text, path) {
+    const broken = (why) => new CliError(`${path} is not a Hive link file: ${why}. Run \`hive link\` to write it again.`);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw broken('it is not JSON');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw broken('it is not an object');
+    }
+    const { project, environment } = parsed;
+    if (typeof project !== 'string' || !isProjectId(project)) {
+        throw broken('"project" is not a project id');
+    }
+    if (typeof environment !== 'string' || environment.trim() === '') {
+        throw broken('"environment" is not an environment name');
+    }
+    return { project: project.toLowerCase(), environment: environment.trim() };
+}
+/** Writes `.hive.json` in `dir` (two fields, nothing else) and says where. */
+export function writeLink(dir, link) {
+    const path = join(dir, LINK_FILE);
+    const text = `${JSON.stringify({ project: link.project, environment: link.environment }, null, 2)}\n`;
+    try {
+        writeFileSync(path, text);
+    }
+    catch (error) {
+        throw new CliError(`Could not write ${path} (${codeOf(error)}).`);
+    }
+    return path;
+}

package/dist/main.js

@@ -0,0 +1,243 @@
+import { parseArgs } from 'node:util';
+import { ApiError } from "./api.js";
+import { explain } from "./callers.js";
+import { link } from "./commands/link.js";
+import { login } from "./commands/login.js";
+import { logout } from "./commands/logout.js";
+import { pull } from "./commands/pull.js";
+import { run } from "./commands/run.js";
+import { revokeSession, sessions } from "./commands/sessions.js";
+import { whoami } from "./commands/whoami.js";
+import { CliError, EXIT, UsageError } from "./output.js";
+import { VERSION } from "./version.js";
+const ENV_OPTION = { env: { type: 'string' } };
+const COMMANDS = {
+    login: {
+        usage: 'hive login [--no-browser]',
+        summary: 'Sign in on this computer, once, approving it in the browser',
+        details: [
+            'Shows a one-time code and opens the Hive website to approve it (--no-browser only prints',
+            'the address). The sign-in is kept in the system keychain and lasts until `hive logout`,',
+            'until it is ended from "Your sign-ins", or until it is 90 days unused.',
+        ].join('\n'),
+        options: { 'no-browser': { type: 'boolean' } },
+    },
+    logout: {
+        usage: 'hive logout',
+        summary: "End this computer's sign-in",
+        details: 'Ends the sign-in at Hive, then forgets it here (even when Hive cannot be reached).',
+        options: {},
+    },
+    whoami: {
+        usage: 'hive whoami [--env <name>]',
+        summary: 'Who is signed in, or what HIVE_TOKEN or GitHub Actions reads',
+        details: [
+            "With HIVE_TOKEN set: the token's space, project and environment. In GitHub Actions (with",
+            '`permissions: id-token: write`): the repository, and the environment, project and space its',
+            'run may read. There --env picks the environment to check (else HIVE_ENV, else .hive.json);',
+            'elsewhere it is not used.',
+        ].join('\n'),
+        options: ENV_OPTION,
+    },
+    link: {
+        usage: 'hive link [--project <id>] [--env <name>] [--yes]',
+        summary: 'Link this folder to a project and its default environment',
+        details: [
+            'Pick the space, the project and the environment, and .hive.json is written in this folder.',
+            'It holds no secret: commit it. With --project and --env it asks nothing. A .hive.json',
+            'already here is replaced only after you say yes; --yes replaces it without asking, and is',
+            'needed for that without a terminal.',
+        ].join('\n'),
+        options: { project: { type: 'string' }, ...ENV_OPTION, yes: { type: 'boolean' } },
+    },
+    run: {
+        usage: 'hive run [--env <name>] -- <command…>',
+        summary: "Run a command with the environment's values",
+        details: [
+            "The values are added to the command's environment (Hive's win over the shell's); no file is",
+            'written. The project comes from .hive.json (this folder or one above it), the environment',
+            'from --env, HIVE_ENV or .hive.json. With HIVE_TOKEN set, the token decides both; the',
+            'command gets the values, not HIVE_TOKEN itself.',
+            'In GitHub Actions, `permissions: id-token: write` replaces the token: GitHub vouches for the',
+            "run, one of the project's GitHub Actions rules must allow it, the project comes from",
+            'HIVE_PROJECT or .hive.json, and the access is ended before the command starts.',
+            'Example: hive run -- npm run dev',
+            'In a workflow: hive run --env production -- npm run build',
+        ].join('\n'),
+        options: ENV_OPTION,
+    },
+    pull: {
+        usage: 'hive pull [--env <name>] [--out <file>] [--yes]',
+        summary: 'Write the values to a .env file',
+        details: [
+            'Writes --out (default .env) readable only by you. Asks before replacing a file, and offers',
+            'to add it to .gitignore. Without a terminal, --yes is needed (it answers yes to both).',
+        ].join('\n'),
+        options: { ...ENV_OPTION, out: { type: 'string' }, yes: { type: 'boolean' } },
+    },
+    sessions: {
+        usage: 'hive sessions [--json]\n  hive sessions revoke <number or id> [--yes]',
+        summary: 'Every sign-in of yours, CLI and website; end one',
+        details: [
+            'Lists them numbered (--json: with their ids). `revoke` ends one after showing which and',
+            "asking (--yes skips the question). This computer's own is ended with `hive logout`.",
+        ].join('\n'),
+        options: { json: { type: 'boolean' }, yes: { type: 'boolean' } },
+    },
+};
+function isName(word) {
+    return Object.hasOwn(COMMANDS, word);
+}
+function helpText() {
+    const lines = [
+        ['hive login [--no-browser]', COMMANDS.login.summary],
+        ['hive logout', COMMANDS.logout.summary],
+        ['hive whoami [--env <name>]', COMMANDS.whoami.summary],
+        ['hive link [--project <id>] [--env <name>] [--yes]', COMMANDS.link.summary],
+        ['hive run [--env <name>] -- <command…>', COMMANDS.run.summary],
+        ['hive pull [--env <name>] [--out <file>] [--yes]', COMMANDS.pull.summary],
+        ['hive sessions [--json]', 'Every sign-in of yours, CLI and website'],
+        ['hive sessions revoke <number or id> [--yes]', 'End one of them'],
+        ['hive help [command]', 'Help for one command'],
+        ['hive --version', 'The version of this CLI'],
+    ];
+    const width = Math.max(...lines.map(([usage]) => usage.length));
+    return [
+        "hive: the Hixumo Hive CLI. Your project's environment values, without a .env file.",
+        '',
+        'Commands:',
+        ...lines.map(([usage, summary]) => `  ${usage.padEnd(width)}  ${summary}`),
+        '',
+        'In GitHub Actions, give the workflow `permissions: id-token: write`: no token to keep.',
+        'On other servers and in other CI, set HIVE_TOKEN to an access token instead of signing in.',
+        'Settings: HIVE_TOKEN, HIVE_ENV, HIVE_PROJECT, HIVE_API_URL, HIVE_CONFIG_DIR, HIVE_KEYRING=off,',
+        'NO_COLOR.',
+    ].join('\n');
+}
+function commandHelp(name) {
+    const { usage, summary, details } = COMMANDS[name];
+    return `Usage:\n  ${usage}\n\n${summary}.\n\n${details}`;
+}
+export async function main(argv, ctx) {
+    let name;
+    try {
+        const [first, ...rest] = argv;
+        if (first === undefined) {
+            ctx.ui.say(helpText());
+            return EXIT.usage;
+        }
+        if (first === '--version' || first === '-v') {
+            ctx.print(VERSION);
+            return EXIT.done;
+        }
+        if (first === 'help' || first === '--help' || first === '-h') {
+            return help(ctx, rest);
+        }
+        if (!isName(first))
+            throw new UsageError(`Unknown command "${first}".`);
+        name = first;
+        return await dispatch(ctx, name, rest);
+    }
+    catch (error) {
+        return report(ctx, error, name);
+    }
+}
+function help(ctx, rest) {
+    if (rest.length === 0) {
+        ctx.print(helpText());
+        return EXIT.done;
+    }
+    const [name, ...extra] = rest;
+    if (!isName(name) || extra.length)
+        throw new UsageError(`No help for "${rest.join(' ')}".`);
+    ctx.print(commandHelp(name));
+    return EXIT.done;
+}
+async function dispatch(ctx, name, rest) {
+    // Everything after `--` is the command `hive run` starts, its own options included.
+    let args = rest;
+    let command;
+    if (name === 'run') {
+        const end = rest.indexOf('--');
+        if (end >= 0) {
+            args = rest.slice(0, end);
+            command = rest.slice(end + 1);
+        }
+    }
+    const parsed = parse(args, COMMANDS[name].options);
+    const values = parsed.values;
+    const positionals = parsed.positionals;
+    if (values.help) {
+        ctx.print(commandHelp(name));
+        return EXIT.done;
+    }
+    const text = (key) => values[key];
+    const flag = (key) => values[key] === true;
+    const none = () => {
+        if (positionals.length)
+            throw new UsageError(`hive ${name} takes no arguments (got "${positionals.join(' ')}").`);
+    };
+    switch (name) {
+        case 'login':
+            none();
+            return login(ctx, { browser: !flag('no-browser') });
+        case 'logout':
+            none();
+            return logout(ctx);
+        case 'whoami':
+            none();
+            return whoami(ctx, { env: text('env') });
+        case 'link':
+            none();
+            return link(ctx, { project: text('project'), env: text('env'), yes: flag('yes') });
+        case 'run':
+            none();
+            if (!command?.length)
+                throw new UsageError('Put the command after --, as in: hive run -- npm run dev');
+            return run(ctx, { env: text('env'), command });
+        case 'pull':
+            none();
+            return pull(ctx, { env: text('env'), out: text('out'), yes: flag('yes') });
+        case 'sessions': {
+            if (positionals.length === 0)
+                return sessions(ctx, { json: flag('json') });
+            const [action, target, ...extra] = positionals;
+            if (action !== 'revoke')
+                throw new UsageError(`Unknown: "hive sessions ${action}".`);
+            if (!target || extra.length)
+                throw new UsageError('hive sessions revoke takes one number or id, from `hive sessions`.');
+            return revokeSession(ctx, { target, yes: flag('yes') });
+        }
+    }
+}
+function parse(args, options) {
+    try {
+        return parseArgs({
+            args,
+            options: { ...options, help: { type: 'boolean', short: 'h' } },
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (error) {
+        // parseArgs' own first sentence ("Unknown option '--x'"), without its advice about `--`.
+        const message = error.message.split(/\. /)[0].replace(/\.$/, '');
+        throw new UsageError(`${message}.`);
+    }
+}
+function report(ctx, error, name) {
+    const { ui } = ctx;
+    if (error instanceof CliError) {
+        ui.say(`${ui.paint.red('Error:')} ${error.message}`);
+        if (error.exitCode === EXIT.usage)
+            ui.say(`Run \`hive help${name ? ` ${name}` : ''}\` to see how to use it.`);
+        return error.exitCode;
+    }
+    if (error instanceof ApiError) {
+        ui.say(`${ui.paint.red('Error:')} ${explain(error)}`);
+        return EXIT.failed;
+    }
+    // A fault in the CLI itself. Its message only, never a stack full of state.
+    ui.say(`${ui.paint.red('Error:')} hive stopped unexpectedly: ${error?.message ?? String(error)}`);
+    return EXIT.failed;
+}

package/dist/output.js

@@ -0,0 +1,53 @@
+/**
+ * Exit codes, errors and colour. Messages go to stderr (so `hive run` leaves the command's stdout
+ * alone); what a command was asked for (a list, `whoami`) goes to stdout. Neither ever holds a
+ * value or a token.
+ */
+export const EXIT = {
+    done: 0,
+    /** Refused, failed, or answered "no". */
+    failed: 1,
+    usage: 2,
+    /** Stopped with Ctrl+C. */
+    stopped: 130,
+};
+/** A stop with a sentence for the person: what happened and what to do. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.failed) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+/** Wrong usage: a missing argument, an unknown option, a flag needed without a terminal. */
+export class UsageError extends CliError {
+    constructor(message) {
+        super(message, EXIT.usage);
+        this.name = 'UsageError';
+    }
+}
+const same = (text) => text;
+export const plainPaint = { bold: same, dim: same, red: same, green: same, yellow: same, cyan: same };
+/** Colour only on a terminal, never with NO_COLOR (any value but empty, as no-color.org says). */
+export function paintFor(isTerminal, env) {
+    if (!isTerminal || env.NO_COLOR || env.TERM === 'dumb')
+        return plainPaint;
+    const wrap = (open, close) => (text) => `\u001b[${open}m${text}\u001b[${close}m`;
+    return {
+        bold: wrap(1, 22),
+        dim: wrap(2, 22),
+        red: wrap(31, 39),
+        green: wrap(32, 39),
+        yellow: wrap(33, 39),
+        cyan: wrap(36, 39),
+    };
+}
+/**
+ * Text from the API (a device name, a project's name, a refusal) as one plain line: without
+ * control characters or direction overrides, so nothing it holds can move the cursor, recolour
+ * the terminal or make a line read as something else.
+ */
+export function plain(text) {
+    return String(text).replace(/[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, '');
+}