@hixumo/hive 0.0.0-stage → 0.0.1

package/dist/callers.js

@@ -0,0 +1,89 @@
+import { ApiError, HiveApi } from "./api.js";
+import { apiOrigin, readConfig } from "./config.js";
+import { CliError, UsageError } from "./output.js";
+/**
+ * Who is calling, in this order: an access token in HIVE_TOKEN (servers, CI); else a GitHub
+ * Actions run that may ask GitHub for a token (`permissions: id-token: write`), which GitHub
+ * vouches for (github-actions.ts); else this computer's sign-in from `hive login`. The first one
+ * there is used and the others are ignored.
+ */
+export const NOT_SIGNED_IN = 'Run `hive login` first, or set HIVE_TOKEN.';
+export const NEEDS_ID_TOKEN = 'Add `permissions: id-token: write` to this workflow (or job) so Hive can check who is running it.';
+const SERVICE_TOKEN_PREFIX = 'hive_st_';
+export function callerOf(env) {
+    const token = serviceTokenOf(env);
+    if (token)
+        return { kind: 'token', token };
+    const request = oidcRequestOf(env);
+    if (request)
+        return { kind: 'github', request };
+    // In GitHub Actions there is no sign-in to fall back on: what is missing is the permission.
+    if (env.GITHUB_ACTIONS === 'true')
+        throw new UsageError(NEEDS_ID_TOKEN);
+    return { kind: 'signed-in' };
+}
+/** Both variables, or none: GitHub sets them together, only for a job with `id-token: write`. */
+export function oidcRequestOf(env) {
+    const url = env.ACTIONS_ID_TOKEN_REQUEST_URL?.trim();
+    const token = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN?.trim();
+    return url && token ? { url, token } : undefined;
+}
+/** HIVE_TOKEN when it is set; refused before it is sent anywhere when it is not an access token. */
+export function serviceTokenOf(env) {
+    const token = env.HIVE_TOKEN?.trim();
+    if (!token)
+        return undefined;
+    if (!token.startsWith(SERVICE_TOKEN_PREFIX)) {
+        throw new CliError(`HIVE_TOKEN is not a Hive access token (those start with ${SERVICE_TOKEN_PREFIX}). Make one in the project's Machine access tab.`);
+    }
+    return token;
+}
+export function tokenApi(ctx, token) {
+    return new HiveApi({ origin: apiOrigin(ctx.env), token });
+}
+/**
+ * This computer's sign-in, sent only to the Hive it was made with: each token is saved with its
+ * own API origin and loaded only for it, so a HIVE_API_URL (or a config.json) pointing elsewhere
+ * finds nothing to send.
+ */
+export async function signedIn(ctx) {
+    const origin = apiOrigin(ctx.env);
+    const { apiUrl, account } = readConfig(ctx.configDir);
+    const token = await ctx.credentials.load(origin);
+    if (!token) {
+        if (apiUrl && apiUrl !== origin) {
+            throw new CliError(`You are signed in to Hive at ${apiUrl}, but this run uses ${origin} (HIVE_API_URL). Run \`hive login\` to sign in there.`);
+        }
+        throw new CliError(NOT_SIGNED_IN);
+    }
+    // config.json says who signed in last from this folder; it is only theirs if it names this Hive.
+    return { api: new HiveApi({ origin, token }), origin, account: apiUrl === origin ? account : undefined };
+}
+/** For the commands that work only with the person's own sign-in. */
+export function refuseServiceToken(ctx, what) {
+    if (ctx.env.HIVE_TOKEN?.trim()) {
+        throw new CliError(`${what} uses your own sign-in from \`hive login\`, not HIVE_TOKEN. Unset HIVE_TOKEN to use it.`);
+    }
+}
+/** The API's sentence for a refusal, and what to do about it. */
+export function explain(error) {
+    switch (error.code) {
+        case 'not_signed_in':
+            return "This computer's Hive sign-in has ended (signed out, revoked, or unused for 90 days). Run `hive login` to sign in again.";
+        case 'token_invalid':
+            return `${error.message} Make a new token in the project's Machine access tab and set it as HIVE_TOKEN.`;
+        case 'accounts_unreachable':
+            return `${error.message} Try again in a minute.`;
+        case 'not_for_cli':
+            return `${error.message} Do this on the Hive website.`;
+    }
+    if (error.status === 0)
+        return `${error.message} Check your connection, or HIVE_API_URL.`;
+    if (error.status === 429)
+        return `${error.message} Wait a minute and try again.`;
+    return error.message;
+}
+/** An ApiError as the CliError that says it; anything else unchanged. */
+export function asCliError(error) {
+    return error instanceof ApiError ? new CliError(explain(error)) : error;
+}

package/dist/choose.js

@@ -0,0 +1,137 @@
+import { createInterface, emitKeypressEvents } from 'node:readline';
+import { CliError, EXIT } from "./output.js";
+/** What one key does to a picker at `index` of `count` lines. */
+export function keyStep(key, index, count) {
+    if ((key.ctrl && key.name === 'c') || key.name === 'escape')
+        return { stop: true };
+    switch (key.name) {
+        case 'return':
+        case 'enter':
+            return { pick: index };
+        case 'up':
+        case 'k':
+            return { move: (index - 1 + count) % count };
+        case 'down':
+        case 'j':
+        case 'tab':
+            return { move: (index + 1) % count };
+    }
+    const number = key.sequence?.length === 1 ? Number(key.sequence) : NaN;
+    return number >= 1 && number <= count ? { move: number - 1 } : undefined;
+}
+const stopped = () => new CliError('Stopped.', EXIT.stopped);
+/**
+ * Reads lines until `read` takes one, asking again with `retry` otherwise. Lines are read through
+ * the interface's iterator, which keeps the ones that arrive together, typed or piped. Ctrl+C
+ * stops the command; the input running out is a stop as well.
+ */
+async function askUntil(io, prompt, read, retry) {
+    // The prompt is readline's own, so it redraws it (not its default "> ") while a line is edited.
+    const terminal = io.output.isTTY === true;
+    const lines = createInterface({ input: io.input, output: io.output, terminal, prompt });
+    let interrupted = false;
+    let closed = false;
+    lines.on('SIGINT', () => {
+        interrupted = true;
+        lines.close();
+    });
+    lines.on('close', () => (closed = true));
+    // Piped answers that have all arrived close the interface while its lines are still read.
+    const ask = () => (closed ? io.output.write(prompt) : lines.prompt());
+    try {
+        ask();
+        for await (const line of lines) {
+            const answer = read(line);
+            if (answer !== undefined)
+                return answer;
+            io.output.write(`${retry}\n`);
+            ask();
+        }
+    }
+    finally {
+        lines.close();
+    }
+    if (interrupted)
+        throw stopped();
+    throw new CliError('No answer was given.');
+}
+export function askYesNo(io, question, defaultYes) {
+    return askUntil(io, `${question} ${defaultYes ? '(Y/n)' : '(y/N)'} `, (line) => {
+        const answer = line.trim().toLowerCase();
+        if (answer === '')
+            return defaultYes;
+        if (answer === 'y' || answer === 'yes')
+            return true;
+        if (answer === 'n' || answer === 'no')
+            return false;
+        return undefined;
+    }, 'Type y or n.');
+}
+/** The picker as a numbered list: for a terminal that cannot draw one (TERM=dumb). */
+export async function chooseByNumber(io, title, choices) {
+    const list = choices.map(({ label, hint }, index) => `  ${index + 1}) ${label}${hint ? `  ${hint}` : ''}`);
+    io.output.write(`${title}\n${list.join('\n')}\n`);
+    const picked = await askUntil(io, `Number (1-${choices.length}): `, (line) => {
+        const number = Number(line.trim());
+        return Number.isInteger(number) && number >= 1 && number <= choices.length ? number : undefined;
+    }, `Type a number from 1 to ${choices.length}.`);
+    return choices[picked - 1].value;
+}
+/** The arrow-key picker. Leaves one line in place of the list: the title and what was picked. */
+export function chooseWithKeys({ input, output, paint }, title, choices) {
+    let index = 0;
+    let drawn = 0;
+    // One screen line per choice: a wrapped line would throw the redraw off by one.
+    const width = Math.max((output.columns || 80) - 4, 10);
+    const fit = (text) => (text.length > width ? `${text.slice(0, width - 1)}…` : text);
+    const lineOf = ({ label, hint }, current) => {
+        const full = hint ? `${label}  ${hint}` : label;
+        const name = current ? paint.cyan(label) : label;
+        if (full.length > width)
+            return fit(full);
+        return hint ? `${name}  ${paint.dim(hint)}` : name;
+    };
+    const draw = () => {
+        if (drawn)
+            output.write(`\u001b[${drawn}A\u001b[0J`);
+        const lines = [
+            `${paint.bold(fit(title))} ${paint.dim('(↑/↓, Enter)')}`,
+            ...choices.map((choice, at) => `${at === index ? paint.cyan('❯') : ' '} ${lineOf(choice, at === index)}`),
+        ];
+        output.write(`${lines.join('\n')}\n`);
+        drawn = lines.length;
+    };
+    return new Promise((resolve, reject) => {
+        const wasRaw = input.isRaw;
+        const finish = () => {
+            input.off('keypress', onKey);
+            input.setRawMode(wasRaw);
+            input.pause();
+            output.write(`\u001b[${drawn}A\u001b[0J\u001b[?25h`);
+        };
+        const onKey = (_text, key) => {
+            const step = keyStep(key ?? {}, index, choices.length);
+            if (!step)
+                return;
+            if ('stop' in step) {
+                finish();
+                reject(stopped());
+            }
+            else if ('move' in step) {
+                index = step.move;
+                draw();
+            }
+            else {
+                finish();
+                output.write(`${fit(title)}: ${paint.cyan(choices[index].label)}\n`);
+                resolve(choices[index].value);
+            }
+        };
+        emitKeypressEvents(input);
+        input.setRawMode(true);
+        input.resume();
+        output.write('\u001b[?25l');
+        draw();
+        input.on('keypress', onKey);
+    });
+}

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { realContext } from "./context.js";
+import { main } from "./main.js";
+// A reader that went away (`hive sessions | head -1`) is not an error worth a stack.
+process.stdout.on('error', (error) => {
+    if (error.code === 'EPIPE')
+        process.exit(process.exitCode ?? 0);
+    throw error;
+});
+process.exitCode = await main(process.argv.slice(2), realContext());

package/dist/commands/link.js

@@ -0,0 +1,79 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { refuseServiceToken, signedIn } from "../callers.js";
+import { assertReadable, environmentNamed, mayRead, projectOf } from "../environments.js";
+import { isProjectId, LINK_FILE, writeLink } from "../link-file.js";
+import { CliError, EXIT, plain, UsageError } from "../output.js";
+/**
+ * `hive link [--project <id>] [--env <name>] [--yes]`: picks space → project → environment and
+ * writes `.hive.json` in this folder. With both flags it asks nothing, so it works without a
+ * terminal; `--yes` replaces a `.hive.json` already here without asking.
+ */
+export async function link(ctx, options) {
+    const { ui } = ctx;
+    refuseServiceToken(ctx, 'hive link');
+    if (options.project !== undefined && !isProjectId(options.project)) {
+        throw new UsageError("--project takes a project's id, like 7f3a9c2e-1b2c-4d5e-8f90-123456789abc.");
+    }
+    if (!ui.interactive && (!options.project || !options.env)) {
+        throw new UsageError('Without a terminal to pick in, hive link needs both --project <id> and --env <name>.');
+    }
+    // Asked before anything is picked, so a "no" wastes nobody's time.
+    if (existsSync(join(ctx.cwd, LINK_FILE)) && !options.yes) {
+        if (!ui.interactive) {
+            throw new CliError(`This folder is already linked (${LINK_FILE}). Pass --yes to replace it, or run hive link in a terminal.`);
+        }
+        if (!(await ui.ask(`This folder is already linked (${LINK_FILE}). Replace it?`, false))) {
+            ui.say(`Left ${LINK_FILE} as it was.`);
+            return EXIT.failed;
+        }
+    }
+    const { api } = await signedIn(ctx);
+    const project = options.project ? await projectOf(api, options.project, '--project') : await pickProject(ctx, api);
+    const environment = options.env ? environmentNamed(project, options.env) : await pickEnvironment(ctx, project);
+    assertReadable(project, environment);
+    writeLink(ctx.cwd, { project: project.id, environment: environment.name });
+    ui.say(`${ui.paint.green('✓')} Linked this folder to ${plain(environment.name)} of ${plain(project.name)}. ${LINK_FILE} holds no secret: commit it.`);
+    return EXIT.done;
+}
+async function pickProject(ctx, api) {
+    const me = await api.me();
+    // A paused space is closed to its people until the Super Admin resumes it.
+    const spaces = me.spaces.filter(({ status }) => status === 'active');
+    if (spaces.length === 0) {
+        throw new CliError("You are in no active space. Make a project on the Hive website, or ask a space's Owner to add you.");
+    }
+    // In the order GET /me gives: the personal space first, then each organization by name.
+    const space = await pickOne(ctx, 'Space', 'Space', spaces.map(spaceChoice));
+    const { projects } = await api.projects(space.id);
+    if (projects.length === 0) {
+        throw new CliError(`${plain(space.name)} has no project you can use. Make one on the Hive website, or ask the space's Owner or an Admin.`);
+    }
+    const card = await pickOne(ctx, `Project in ${plain(space.name)}`, 'Project', projects.map((card) => ({ label: plain(card.name), value: card })));
+    return api.project(card.id);
+}
+/** A personal space by its name with "(personal)" after it; an organization by its name, the person's role dimmed. */
+function spaceChoice(space) {
+    if (space.kind === 'personal')
+        return { label: `${plain(space.name)} (personal)`, value: space };
+    return { label: plain(space.name), hint: space.role, value: space };
+}
+async function pickEnvironment(ctx, project) {
+    const readable = project.environments.filter(mayRead);
+    if (readable.length === 0) {
+        throw new CliError(`You can't read the values of any environment of ${plain(project.name)}. Ask the space's Owner or an Admin.`);
+    }
+    return pickOne(ctx, `Environment of ${plain(project.name)}`, 'Environment', readable.map((environment) => ({
+        label: plain(environment.name),
+        hint: environment.protected ? 'protected' : undefined,
+        value: environment,
+    })));
+}
+/** One choice is taken without asking, and said. */
+async function pickOne(ctx, title, noun, choices) {
+    if (choices.length === 1) {
+        ctx.ui.say(`${noun}: ${choices[0].label}`);
+        return choices[0].value;
+    }
+    return ctx.ui.choose(title, choices);
+}

package/dist/commands/login.js

@@ -0,0 +1,69 @@
+import { HiveApi } from "../api.js";
+import { apiOriginOf } from "../api-address.js";
+import { apiOrigin, readConfig, writeConfig } from "../config.js";
+import { approveInBrowser } from "../device-flow.js";
+import { CliError, EXIT, plain } from "../output.js";
+/**
+ * `hive login [--no-browser]`: one sign-in per computer for each Hive, approved in the Hive
+ * website (spec section 9). Hive hands the token over once; it goes to the keychain under this
+ * Hive's address (or the 0600 file, with that address), and config.json keeps who it is and which
+ * Hive it was made with.
+ */
+export async function login(ctx, options) {
+    const { ui } = ctx;
+    if (!ui.interactive) {
+        throw new CliError('hive login needs a terminal: it shows a code and waits for you to approve it in the browser. On servers and in CI, set HIVE_TOKEN to an access token instead.');
+    }
+    const origin = apiOrigin(ctx.env);
+    // Only this Hive's sign-in is replaced; another Hive's keeps its own place.
+    const previous = await ctx.credentials.load(origin);
+    const saved = readConfig(ctx.configDir);
+    if (previous) {
+        const known = saved.apiUrl === origin ? saved.account : undefined;
+        const who = known ? `${plain(known.name)} (${plain(known.email)})` : 'someone';
+        if (!(await ui.ask(`You are signed in as ${who}. Sign in again, replacing it?`, false))) {
+            ui.say('Kept the current sign-in.');
+            return EXIT.failed;
+        }
+    }
+    const api = new HiveApi({ origin });
+    const start = await api.startLogin(deviceNameOf(ctx.hostname()));
+    const approved = (await approveInBrowser(ctx, start, (deviceCode) => api.pollLogin(deviceCode), options));
+    if (typeof approved.token !== 'string' || !approved.token.startsWith('hive_cli_')) {
+        throw new CliError('Hive approved the sign-in but sent no token. Run `hive login` again.');
+    }
+    const replaced = await ctx.credentials.save(origin, approved.token);
+    const { id, email, name } = approved.account;
+    writeConfig(ctx.configDir, { account: { id, email, name }, apiUrl: origin });
+    if (previous)
+        await endQuietly(previous, origin);
+    if (replaced) {
+        // credentials.json holds one sign-in, so the one for another Hive had to go.
+        const ended = await endQuietly(replaced.token, replaced.apiUrl);
+        ui.say(`Your sign-in to Hive at ${plain(replaced.apiUrl)} was replaced, as credentials.json keeps one${ended ? ', and ended there' : '; it could not be ended there, and ends by itself after 90 days unused'}. Use another HIVE_CONFIG_DIR to keep one for each Hive.`);
+    }
+    ui.say(`${ui.paint.green('✓')} Signed in as ${plain(name)} (${plain(email)}).`);
+    if (ctx.env.HIVE_TOKEN?.trim()) {
+        ui.warn('HIVE_TOKEN is set in this shell, so commands here use it instead of this sign-in.');
+    }
+    return EXIT.done;
+}
+/** "MacBook-Pro", as the sign-ins list shows it: without macOS's `.local`, at most 100 characters. */
+function deviceNameOf(hostname) {
+    return hostname.replace(/\.local$/i, '').slice(0, 100) || 'Unknown computer';
+}
+/**
+ * A replaced sign-in, ended at the Hive it was made with, so it does not stay live unused for
+ * 90 days. The new one is saved already; a failure here changes nothing for the person.
+ */
+async function endQuietly(token, origin) {
+    try {
+        // The address is read back from a file: held to the rule every address the CLI uses keeps.
+        await new HiveApi({ origin: apiOriginOf(origin), token }).logout();
+        return true;
+    }
+    catch {
+        // It ends by itself after 90 days unused, and is listed in `hive sessions` until then.
+        return false;
+    }
+}

package/dist/commands/logout.js

@@ -0,0 +1,54 @@
+import { ApiError, HiveApi } from "../api.js";
+import { explain } from "../callers.js";
+import { apiOrigin, readConfig, writeConfig } from "../config.js";
+import { EXIT } from "../output.js";
+/**
+ * `hive logout`: ends this Hive's sign-in at Hive (`POST /cli/logout`), then forgets it here. It
+ * is forgotten even when Hive cannot be reached, and the person is told it may still be live.
+ * When the keychain will not let it go, that is said plainly instead.
+ */
+export async function logout(ctx) {
+    const { ui } = ctx;
+    const origin = apiOrigin(ctx.env);
+    const saved = readConfig(ctx.configDir);
+    // Saved with the Hive it was made for, so it is only ever sent back there.
+    const token = await ctx.credentials.load(origin);
+    if (!token) {
+        ui.say(saved.apiUrl && saved.apiUrl !== origin
+            ? `You are not signed in to Hive at ${origin} on this computer. This folder's sign-in is for ${saved.apiUrl}: set HIVE_API_URL to it to sign out there.`
+            : 'You are not signed in on this computer.');
+        return EXIT.done;
+    }
+    let failure;
+    try {
+        await new HiveApi({ origin, token }).logout();
+    }
+    catch (error) {
+        const ended = error instanceof ApiError && error.code === 'not_signed_in';
+        if (!ended)
+            failure = error instanceof ApiError ? explain(error) : error.message;
+    }
+    let kept;
+    try {
+        await ctx.credentials.forget(origin);
+    }
+    catch (error) {
+        kept = error.message;
+    }
+    if (!kept && (!saved.apiUrl || saved.apiUrl === origin))
+        writeConfig(ctx.configDir, {});
+    if (failure && kept) {
+        ui.warn(`Could not end it at Hive: ${failure} It is still saved on this computer as well. ${kept} It stays live until it is 90 days unused, or until you end it with \`hive sessions revoke\` on another computer or on the website's "Your sign-ins" page.`);
+        return EXIT.failed;
+    }
+    if (failure) {
+        ui.warn(`Could not end it at Hive: ${failure} It is forgotten here, but stays live until it is 90 days unused, or until you end it with \`hive sessions revoke\` on another computer or on the website's "Your sign-ins" page.`);
+        return EXIT.failed;
+    }
+    if (kept) {
+        ui.warn(`The sign-in is ended at Hive, so it no longer works, but it is still saved on this computer. ${kept}`);
+        return EXIT.failed;
+    }
+    ui.say('Signed out: the sign-in is ended at Hive and forgotten on this computer.');
+    return EXIT.done;
+}

package/dist/commands/pull.js

@@ -0,0 +1,81 @@
+import { lstatSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { writeDotenv } from "../dotenv.js";
+import { codeOf, writePrivateFile } from "../files.js";
+import { addToGitignore, checkGitignore } from "../gitignore.js";
+import { findLink } from "../link-file.js";
+import { CliError, EXIT, UsageError } from "../output.js";
+import { readValues } from "../values.js";
+/**
+ * `hive pull [--env <name>] [--out <file>] [--yes]`: the values as a `.env` file, for a tool
+ * that needs one. Readable only by the person (0600). Asks before replacing a file, and offers to
+ * add it to .gitignore when no line there covers it. Without a terminal it needs `--yes`, which
+ * answers yes to both. In GitHub Actions the workflow access is ended by readValues, before the
+ * file is written.
+ */
+export async function pull(ctx, options) {
+    const { ui } = ctx;
+    if (!ui.interactive && !options.yes) {
+        throw new UsageError('hive pull writes a file of values; without a terminal to ask in, pass --yes.');
+    }
+    const shown = options.out ?? '.env';
+    const file = resolve(ctx.cwd, shown);
+    // Checked and asked before reading, so neither a missing folder nor a "no" leaves a record of
+    // values shown for nothing.
+    if (!exists(dirname(file))) {
+        throw new CliError(`There is no folder ${relative(ctx.cwd, dirname(file)) || dirname(file)} to write ${shown} in.`);
+    }
+    if (exists(file) && !options.yes && !(await ui.ask(`${shown} already exists. Replace it?`, false))) {
+        ui.say(`Left ${shown} as it was.`);
+        return EXIT.failed;
+    }
+    const read = await readValues(ctx, { env: options.env });
+    try {
+        writePrivateFile(file, writeDotenv(read.values));
+    }
+    catch (error) {
+        throw new CliError(`Could not write ${shown} (${codeOf(error)}).`);
+    }
+    const count = Object.keys(read.values).length;
+    const of = read.project ? `${read.environment} (${read.project})` : read.environment;
+    ui.say(`${ui.paint.green('✓')} Wrote ${count} value${count === 1 ? '' : 's'} of ${of} to ${shown}, readable only by you.`);
+    await offerGitignore(ctx, file, shown, options.yes);
+    return EXIT.done;
+}
+function exists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function offerGitignore(ctx, file, shown, yes) {
+    const { ui } = ctx;
+    let linkDir;
+    try {
+        linkDir = findLink(ctx.cwd)?.dir;
+    }
+    catch {
+        // A broken .hive.json: only HIVE_TOKEN gets this far with one, and reading the values has
+        // warned about it already. The line goes by the repository.
+    }
+    const check = checkGitignore(file, linkDir);
+    if (check.covered)
+        return;
+    const gitignore = relative(ctx.cwd, check.file) || check.file;
+    ui.warn(`${shown} is not in .gitignore, so git could commit it.`);
+    const add = yes || (ui.interactive && (await ui.ask(`Add ${check.line} to ${gitignore}?`, true)));
+    if (!add) {
+        ui.say(`Add ${check.line} to ${gitignore} before you commit.`);
+        return;
+    }
+    try {
+        addToGitignore(check);
+        ui.say(`Added ${check.line} to ${gitignore}.`);
+    }
+    catch (error) {
+        ui.warn(`Could not add it to ${gitignore} (${codeOf(error)}). Add ${check.line} there yourself.`);
+    }
+}

package/dist/commands/run.js

@@ -0,0 +1,82 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { codeOf } from "../files.js";
+import { CliError } from "../output.js";
+import { readValues } from "../values.js";
+/**
+ * `hive run [--env <name>] -- <command…>`: the command runs with the environment's values added
+ * to its own environment, Hive's winning, and its terminal untouched (stdin, stdout and stderr
+ * are its own). Signals sent to the CLI are passed on, and the CLI exits with the command's
+ * code; when a signal stopped it, 128 + the signal's number (130 for Ctrl+C), as a shell says.
+ * No file is written. In GitHub Actions the workflow access is ended by readValues, before the
+ * command starts: it never runs beside a live access, and never gets it.
+ */
+/**
+ * What a terminal, a process manager or a container sends to stop a program. One sent to the CLI
+ * alone (`kill`, `docker stop`) reaches the command only by being passed on.
+ */
+const PASSED_ON = process.platform === 'win32' ? ['SIGINT', 'SIGTERM', 'SIGBREAK'] : ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT', 'SIGUSR2'];
+/**
+ * The keys a terminal turns into a signal for every process of the job (Ctrl+C, Ctrl+\, and
+ * Ctrl+Break on Windows): the command has it already, so passing it on would deliver it twice,
+ * and a second Ctrl+C makes many programs skip their clean stop.
+ */
+const SENT_BY_THE_TERMINAL = new Set(['SIGINT', 'SIGQUIT', 'SIGBREAK']);
+export async function run(ctx, options) {
+    const { values } = await readValues(ctx, { env: options.env });
+    // Node would refuse it while starting the command, quoting the value in its message.
+    const unfit = Object.keys(values).find((key) => values[key].includes('\0'));
+    if (unfit) {
+        throw new CliError(`${unfit} holds a NUL character, which no environment variable can, so nothing was started.`);
+    }
+    // The command gets the values, not the key to them: the access token stays with the CLI. A
+    // HIVE_TOKEN among the environment's own values is one of those values, and is passed.
+    const { HIVE_TOKEN: _key, ...shell } = ctx.env;
+    return runCommand(options.command, { ...shell, ...values }, ctx.cwd, ctx.atTerminal);
+}
+function runCommand([file, ...args], env, cwd, atTerminal) {
+    return new Promise((resolve, reject) => {
+        const cannotStart = (error) => new CliError(`Could not start ${file}: ${codeOf(error) === 'ENOENT' ? 'no such command' : codeOf(error)}.`);
+        let child;
+        try {
+            child = process.platform === 'win32'
+                ? spawn(windowsCommandLine([file, ...args]), { stdio: 'inherit', env, cwd, shell: true })
+                : spawn(file, args, { stdio: 'inherit', env, cwd });
+        }
+        catch (error) {
+            reject(cannotStart(error));
+            return;
+        }
+        // The CLI stays up while the command decides what a signal means (a dev server may close
+        // its connections first); it learns the outcome from the command's exit. So every signal is
+        // caught, even the ones a terminal has already sent the command itself.
+        const passOn = (signal) => {
+            if (atTerminal && SENT_BY_THE_TERMINAL.has(signal))
+                return;
+            child.kill(signal);
+        };
+        for (const signal of PASSED_ON)
+            process.on(signal, passOn);
+        const stopPassing = () => {
+            for (const signal of PASSED_ON)
+                process.off(signal, passOn);
+        };
+        child.on('error', (error) => {
+            stopPassing();
+            reject(cannotStart(error));
+        });
+        child.on('exit', (code, signal) => {
+            stopPassing();
+            resolve(code ?? 128 + (signal ? (constants.signals[signal] ?? 0) : 0));
+        });
+    });
+}
+/**
+ * Windows starts `npm` and the like (`npm.cmd`) only through cmd, so the command goes as one
+ * line, each part quoted where cmd would split or read it.
+ */
+function windowsCommandLine(parts) {
+    return parts
+        .map((part) => (part === '' || /[\s"&|<>^()%!]/.test(part) ? `"${part.replace(/"/g, '""')}"` : part))
+        .join(' ');
+}