@magland/mochi 0.3.1

package/dist/cli/repo.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPO_OPTION = void 0;
+exports.resolveRepo = resolveRepo;
+exports.repoPath = repoPath;
+const child_process_1 = require("child_process");
+const exit_1 = require("./exit");
+// Which repository a command is about.
+//
+// This matters more than it looks, because a caller working inside a clone should
+// not have to be told twice where it is: an agent that has just cloned a
+// repository and is standing in it knows the answer, and so does git.
+exports.REPO_OPTION = {
+    name: 'repo',
+    type: 'string',
+    value: '<c/r>',
+    summary: 'Repository as collection/repo; otherwise the git remote in this directory',
+};
+/** collection/repo, and nothing else: not a URL, not a bare name. */
+function parseRef(given, where) {
+    const parts = given.replace(/^\/+|\/+$/g, '').split('/');
+    if (parts.length !== 2 || parts[0] === '' || parts[1] === '') {
+        throw new exit_1.CliError(`${where} should be <collection>/<repo>, not '${given}'`, exit_1.EXIT_USAGE);
+    }
+    return { collection: parts[0], repo: parts[1].replace(/\.git$/, '') };
+}
+function git(args) {
+    return new Promise((resolve) => {
+        (0, child_process_1.execFile)('git', args, { maxBuffer: 1024 * 1024 }, (err, stdout) => {
+            resolve(err ? null : String(stdout));
+        });
+    });
+}
+/**
+ * The repository named by the git remotes here that points at the vault we are
+ * talking to, preferring origin. A remote for some other host is not an answer:
+ * a clone of a GitHub repository standing in this directory must not be read as
+ * naming a repository in this vault.
+ */
+async function fromGitRemotes(host) {
+    let vaultHost;
+    try {
+        vaultHost = new URL(host).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+    const config = await git(['config', '--get-regexp', '^remote\\..*\\.url']);
+    if (!config)
+        return null;
+    const candidates = [];
+    for (const line of config.split('\n')) {
+        const space = line.indexOf(' ');
+        if (space === -1)
+            continue;
+        const key = line.slice(0, space);
+        const url = line.slice(space + 1).trim();
+        const name = key.slice('remote.'.length, -'.url'.length);
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.host.toLowerCase() !== vaultHost)
+            continue;
+        const segments = parsed.pathname.replace(/^\/+|\/+$/g, '').split('/');
+        if (segments.length < 2)
+            continue;
+        const tail = segments.slice(-2);
+        candidates.push({ name, ref: { collection: tail[0], repo: tail[1].replace(/\.git$/, '') } });
+    }
+    if (candidates.length === 0)
+        return null;
+    return (candidates.find((c) => c.name === 'origin') ?? candidates[0]).ref;
+}
+/**
+ * Resolve the repository a command is about, in order: the argument or --repo,
+ * then MOCHI_REPO, then the git remote here that points at this vault.
+ * Failing all three, say so and name all three.
+ */
+async function resolveRepo(inv, target, positional = null) {
+    if (positional)
+        return parseRef(positional, 'a repository');
+    const flag = inv.str('repo');
+    if (flag)
+        return parseRef(flag, '--repo');
+    const env = process.env.MOCHI_REPO?.trim();
+    if (env)
+        return parseRef(env, 'MOCHI_REPO');
+    const remote = await fromGitRemotes(target.host);
+    if (remote)
+        return remote;
+    throw new exit_1.CliError(`Which repository? Name it as <collection>/<repo>, pass --repo <collection>/<repo>, set MOCHI_REPO,\n` +
+        `or run this inside a clone whose remote points at ${target.host}.`, exit_1.EXIT_USAGE);
+}
+/** The path prefix for a repository's API routes. */
+function repoPath(ref) {
+    return `/api/repos/${encodeURIComponent(ref.collection)}/${encodeURIComponent(ref.repo)}`;
+}

package/dist/cli/run-cmd.js

@@ -0,0 +1,438 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCommands = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const cli_api_1 = require("../cli-api");
+const exit_1 = require("./exit");
+const output_1 = require("./output");
+const repo_1 = require("./repo");
+const target_1 = require("./target");
+// Workflows and their runs. `run watch` is the command that turns "an agent can
+// start a workflow" into "an agent can act on the result", and `run view --log`
+// is what it reads when the result is a failure.
+const COMMON = [repo_1.REPO_OPTION, ...target_1.TARGET_OPTIONS];
+function runNumber(inv) {
+    const raw = inv.args[0] ?? '';
+    if (!/^[1-9][0-9]*$/.test(raw))
+        throw new exit_1.CliError(`'${raw}' is not a run number`, exit_1.EXIT_USAGE);
+    return parseInt(raw, 10);
+}
+function runRow(r) {
+    return [
+        `#${r.number}`,
+        String(r.status),
+        String(r.conclusion ?? ''),
+        String(r.workflowName ?? ''),
+        String(r.refName ?? r.ref ?? ''),
+        String(r.sha ?? '').slice(0, 10),
+        (0, output_1.shortDate)(r.createdAt),
+    ];
+}
+/** Print a job's log, which is what a caller looking at a failure came for. */
+async function printLog(target, repo, n, jobId, tail) {
+    const query = tail === null ? '' : `?tail=${tail}`;
+    const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/runs/${n}/jobs/${encodeURIComponent(jobId)}/log${query}`);
+    if (data.error) {
+        console.error(`job ${jobId} failed before it ran: ${data.error}`);
+        return;
+    }
+    for (const line of (data.lines ?? []))
+        console.log(line);
+    // Diagnostics go to stderr so that piping the log somewhere gets the log.
+    if (data.truncated) {
+        console.error(`(the last ${data.lines.length} of ${data.total} lines; --tail 0 for all of it)`);
+    }
+    if (data.capped)
+        console.error('(the server capped this log while it was being written)');
+}
+exports.runCommands = [
+    {
+        path: ['workflow', 'list'],
+        summary: 'List the workflows at a ref, with the inputs each takes',
+        options: [
+            { name: 'ref', type: 'string', value: '<r>', summary: 'Branch or tag; the default branch otherwise' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const ref = inv.str('ref');
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/workflows${ref ? `?ref=${encodeURIComponent(ref)}` : ''}`);
+            const workflows = (data.workflows ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ ref: data.ref, workflows: (0, output_1.pickFields)(workflows, json.fields) });
+                return;
+            }
+            if (workflows.length === 0) {
+                console.log(`No workflows at ${data.ref}`);
+                return;
+            }
+            (0, output_1.printTable)(workflows.map((w) => [
+                String(w.name),
+                String(w.path),
+                w.dispatch ? `dispatch: ${Object.keys(w.dispatch).join(',') || 'no inputs'}` : '',
+                w.error ? `error: ${w.error}` : '',
+            ]));
+        },
+    },
+    {
+        path: ['workflow', 'run'],
+        summary: 'Dispatch a workflow by hand',
+        description: `The workflow is named by its path, as 'workflow list' reports it. --field k=v
+supplies a workflow_dispatch input; the inputs a workflow takes are in the same
+listing.`,
+        args: [{ name: 'workflow', required: true }],
+        options: [
+            { name: 'ref', type: 'string', value: '<r>', summary: 'Branch to run on; the default branch otherwise' },
+            { name: 'field', type: 'string[]', value: '<k=v>', summary: 'A workflow_dispatch input' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const inputs = {};
+            for (const pair of inv.list('field')) {
+                const i = pair.indexOf('=');
+                if (i <= 0)
+                    throw new exit_1.CliError(`--field takes key=value, not '${pair}'`, exit_1.EXIT_USAGE);
+                inputs[pair.slice(0, i)] = pair.slice(i + 1);
+            }
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(repo)}/dispatches`, {
+                workflow: inv.args[0],
+                ref: inv.str('ref') ?? undefined,
+                inputs: Object.keys(inputs).length ? inputs : undefined,
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Started run #${data.number} of ${data.workflowName}`);
+            console.log(`  mochi run watch ${data.number} --repo ${repo.collection}/${repo.repo}`);
+        },
+    },
+    {
+        path: ['run', 'list'],
+        summary: 'List workflow runs, newest first',
+        options: [
+            { name: 'status', type: 'string', value: '<s>', summary: 'queued, running, or completed' },
+            { name: 'limit', type: 'int', value: '<n>', summary: 'At most this many' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const query = new URLSearchParams();
+            const status = inv.str('status');
+            if (status !== null)
+                query.set('status', status);
+            const limit = inv.int('limit');
+            if (limit !== null)
+                query.set('limit', String(limit));
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/runs?${query.toString()}`);
+            const runs = (data.runs ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ runs: (0, output_1.pickFields)(runs, json.fields) });
+                return;
+            }
+            if (runs.length === 0) {
+                console.log('No runs');
+                return;
+            }
+            (0, output_1.printTable)(runs.map(runRow));
+        },
+    },
+    {
+        path: ['run', 'view'],
+        summary: 'Show one run, its jobs, and optionally a job log',
+        description: `--log prints the log of the failed job, or of the only job, without needing to be
+told which. --job names one explicitly. The log comes back as its last 200 lines
+by default, because handing a caller the whole of a large log wastes its attention;
+--tail 0 asks for all of it.`,
+        args: [{ name: 'number', required: true }],
+        options: [
+            { name: 'job', type: 'string', value: '<j>', summary: 'A job id, as run view reports it' },
+            { name: 'log', type: 'boolean', summary: 'Print a job log as well' },
+            { name: 'tail', type: 'int', value: '<n>', summary: 'Log lines to keep from the end; 0 for all' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const n = runNumber(inv);
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/runs/${n}`);
+            const jobs = (data.jobs ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`#${data.number} ${data.workflowName} (${data.event}) on ${data.refName ?? data.ref}`);
+            console.log(`${data.status}${data.conclusion ? ` - ${data.conclusion}` : ''} at ${String(data.sha).slice(0, 10)}`);
+            if (data.error)
+                console.log(`workflow error: ${data.error}`);
+            if (jobs.length) {
+                console.log('');
+                (0, output_1.printTable)(jobs.map((j) => [String(j.id), String(j.status), String(j.conclusion ?? ''), String(j.name)]));
+            }
+            if (!inv.bool('log') && inv.str('job') === null)
+                return;
+            // The failed job is the one being asked about, when there is one; a run
+            // with a single job needs no naming either.
+            const named = inv.str('job');
+            const chosen = named ??
+                String((jobs.find((j) => j.conclusion === 'failure') ?? (jobs.length === 1 ? jobs[0] : undefined))?.id ?? '');
+            if (!chosen) {
+                console.error('Which job? Name one with --job; the ids are in the table above.');
+                process.exit(exit_1.EXIT_USAGE);
+            }
+            console.log('');
+            console.log(`--- ${chosen}`);
+            await printLog(target, repo, n, chosen, inv.int('tail'));
+        },
+    },
+    {
+        path: ['run', 'watch'],
+        summary: 'Wait for a run to finish, then report how it went',
+        description: `Polls until the run completes. --exit-status makes a failed run a non-zero exit,
+which is what a script wants; without it a finished run is a success whatever it
+concluded.
+
+Polling rather than streaming: the engine has no event channel and the vault reads
+its state off disk per request, so a five-second poll against a local process costs
+nothing and needs no protocol.`,
+        args: [{ name: 'number', required: true }],
+        options: [
+            { name: 'interval', type: 'int', value: '<s>', summary: 'Seconds between polls (default 5)' },
+            { name: 'timeout', type: 'int', value: '<s>', summary: 'Give up after this long (default 1800)' },
+            { name: 'exit-status', type: 'boolean', summary: 'Exit non-zero when the run did not succeed' },
+            { name: 'log', type: 'boolean', summary: 'Print the failed job log when it finishes' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const n = runNumber(inv);
+            const interval = Math.max(1, inv.int('interval') ?? 5) * 1000;
+            const timeout = Math.max(1, inv.int('timeout') ?? 1800) * 1000;
+            const json = (0, output_1.jsonMode)(inv);
+            const started = Date.now();
+            // A watch outlives any single request, so one that cannot reach the
+            // vault is not an answer about the run: a restart, a redeploy, or a
+            // dropped connection would otherwise abandon a run that is still going
+            // and report it as a failure. Keep polling and let the timeout, which is
+            // the caller's actual patience, decide when to stop; a vault that is
+            // still unreachable when it expires is reported then.
+            let unreachable = null;
+            // Null means the vault could not be reached this time, and the caller
+            // keeps whatever it last knew rather than treating silence as a change
+            // of state.
+            const poll = async () => {
+                try {
+                    const answer = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/runs/${n}`);
+                    if (unreachable !== null && !json.enabled)
+                        console.error(`${target.host} is answering again`);
+                    unreachable = null;
+                    return answer;
+                }
+                catch (e) {
+                    if (!(e instanceof exit_1.UnreachableError))
+                        throw e;
+                    if (unreachable === null && !json.enabled)
+                        console.error(`${e.message}; still watching run #${n}`);
+                    unreachable = e.message;
+                    return null;
+                }
+            };
+            let data = (await poll()) ?? { status: 'unknown' };
+            let last = '';
+            while (data.status !== 'completed') {
+                if (Date.now() - started > timeout) {
+                    const why = unreachable ?? `run #${n} is still ${data.status}`;
+                    const failure = JSON.stringify({ error: `timed out waiting for the run: ${why}` });
+                    if (json.enabled)
+                        process.stderr.write(failure + '\n');
+                    else
+                        console.error(`Gave up after ${Math.round(timeout / 1000)}s; ${why}.`);
+                    process.exit(exit_1.EXIT_FAIL);
+                }
+                // Progress on stderr, so that --json still puts one value on stdout.
+                const now = `${data.status}`;
+                if (!json.enabled && unreachable === null && now !== last) {
+                    console.error(`run #${n} is ${now}...`);
+                    last = now;
+                }
+                await new Promise((r) => setTimeout(r, interval));
+                data = (await poll()) ?? data;
+            }
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+            }
+            else {
+                console.log(`#${data.number} ${data.workflowName}: ${data.conclusion ?? 'completed'}`);
+                const jobs = (data.jobs ?? []);
+                if (jobs.length) {
+                    (0, output_1.printTable)(jobs.map((j) => [String(j.id), String(j.status), String(j.conclusion ?? ''), String(j.name)]));
+                }
+                if (inv.bool('log')) {
+                    const failed = jobs.find((j) => j.conclusion === 'failure') ?? (jobs.length === 1 ? jobs[0] : undefined);
+                    if (failed) {
+                        console.log('');
+                        console.log(`--- ${failed.id}`);
+                        await printLog(target, repo, n, String(failed.id), null);
+                    }
+                }
+            }
+            if (inv.bool('exit-status') && data.conclusion !== 'success')
+                process.exit(exit_1.EXIT_FAIL);
+        },
+    },
+    {
+        path: ['run', 'cancel'],
+        summary: 'Cancel a run that is queued or running',
+        args: [{ name: 'number', required: true }],
+        options: [output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const n = runNumber(inv);
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(repo)}/runs/${n}/cancel`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Cancelled run #${n}`);
+        },
+    },
+    {
+        path: ['run', 'rerun'],
+        summary: 'Run the same workflow at the same commit again',
+        args: [{ name: 'number', required: true }],
+        options: [output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const n = runNumber(inv);
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(repo)}/runs/${n}/rerun`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Started run #${data.number} of ${data.workflowName}`);
+        },
+    },
+    {
+        path: ['run', 'exec-command'],
+        summary: "Mint the command that runs a run's manual jobs on a machine of yours",
+        description: `A job with 'manual' in runs-on waits for a person rather than a runner. This
+mints the command to paste on the machine that should execute it, the same one
+the run page's "Run it yourself" button mints. The token in it is shown once,
+must be pasted within fifteen minutes, and works once.`,
+        args: [{ name: 'number', required: true }],
+        options: [output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const n = runNumber(inv);
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(repo)}/runs/${n}/exec-command`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log('Paste this on the machine that should run the manual jobs (shown once):');
+            console.log('');
+            console.log(`  ${data.command}`);
+            console.log('');
+            console.log(`It expires in ${data.expiresInMinutes} minutes and works once.`);
+        },
+    },
+    {
+        path: ['run', 'download'],
+        summary: "Download a run's artifacts",
+        description: `An artifact is a tar. Without --artifact every artifact of the run is downloaded;
+with it, just that one. They land in the current directory unless --dir says
+otherwise.`,
+        args: [{ name: 'number', required: true }],
+        options: [
+            { name: 'artifact', type: 'string', value: '<name>', summary: 'Only this artifact' },
+            { name: 'dir', type: 'string', value: '<d>', summary: 'Where to write them (default: here)' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const n = runNumber(inv);
+            const dir = inv.str('dir') ?? '.';
+            const only = inv.str('artifact');
+            const listed = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/runs/${n}/artifacts`);
+            const artifacts = (listed.artifacts ?? []).filter((a) => only === null || a.name === only);
+            if (artifacts.length === 0) {
+                throw new exit_1.CliError(only ? `run #${n} has no artifact named ${only}` : `run #${n} has no artifacts`, exit_1.EXIT_FAIL);
+            }
+            fs.mkdirSync(dir, { recursive: true });
+            const written = [];
+            for (const a of artifacts) {
+                const name = String(a.name);
+                const r = await (0, cli_api_1.requestBytes)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/runs/${n}/artifacts/${encodeURIComponent(name)}`);
+                if (!r.ok) {
+                    process.stderr.write(r.body.toString('utf8').trimEnd() + '\n');
+                    process.exit((0, exit_1.exitCodeForStatus)(r.status));
+                }
+                const file = path.join(dir, `${name}.tar`);
+                fs.writeFileSync(file, r.body);
+                written.push({ name, file, bytes: r.body.length });
+            }
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ artifacts: written });
+                return;
+            }
+            (0, output_1.printTable)(written.map((w) => [w.name, w.file, String(w.bytes)]));
+        },
+    },
+];

package/dist/cli/target.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TARGET_OPTIONS = void 0;
+exports.targetFrom = targetFrom;
+const cli_api_1 = require("../cli-api");
+const exit_1 = require("./exit");
+const input_1 = require("./input");
+// Which vault a command talks to, and with what token. Every command that
+// reaches a vault takes the same three options, declared once here so that they
+// are spelled and documented identically everywhere.
+exports.TARGET_OPTIONS = [
+    {
+        name: 'host',
+        type: 'string',
+        value: '<url>',
+        summary: 'Vault URL, ahead of MOCHI_HOST and the last login',
+    },
+    {
+        name: 'token',
+        type: 'string',
+        value: '<t>',
+        summary: "Token, ahead of MOCHI_TOKEN and git's credential store",
+    },
+    {
+        name: 'token-stdin',
+        type: 'boolean',
+        summary: 'Read the token from stdin, so it is in neither argv nor shell history',
+    },
+];
+/**
+ * The vault and token a command should use, from its options, the environment, or
+ * the login.
+ *
+ * `opts.host` is a fallback a command can supply from state of its own, and sits
+ * between the environment and the login: `mochi backup` records the vault a
+ * backup directory is a backup of, and that has to outrank the last login,
+ * because a machine that has since logged in to another vault must not quietly
+ * start filling one backup directory from a different vault.
+ */
+async function targetFrom(inv, opts = {}) {
+    let token = inv.str('token');
+    if (inv.bool('token-stdin')) {
+        // Two ways of saying where the token comes from is a usage error, as every
+        // other "not both" in the CLI is; an empty stdin below is not, because
+        // there the invocation was fine and the token is what is missing.
+        if (token)
+            throw new exit_1.CliError('Pass either --token or --token-stdin, not both.', exit_1.EXIT_USAGE);
+        token = (await (0, input_1.readStdin)()).trim();
+        if (!token)
+            throw new exit_1.CliError('--token-stdin was given but stdin was empty.', exit_1.EXIT_AUTH);
+    }
+    const host = inv.str('host') ?? process.env.MOCHI_HOST?.trim() ?? opts.host ?? null;
+    return await (0, cli_api_1.remoteTarget)({ host, token });
+}

package/dist/cli-api.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remoteTarget = remoteTarget;
+exports.request = request;
+exports.requestBytes = requestBytes;
+exports.apiTry = apiTry;
+exports.apiFailed = apiFailed;
+exports.api = api;
+const credentials_1 = require("./credentials");
+const exit_1 = require("./cli/exit");
+/** The vault a command works against: --host/--token, then the environment, then the last login. */
+async function remoteTarget(args) {
+    try {
+        return await (0, credentials_1.vaultTarget)(args);
+    }
+    catch (e) {
+        throw new exit_1.CliError(e instanceof Error ? e.message : String(e), exit_1.EXIT_AUTH);
+    }
+}
+/**
+ * One request, with the body left as text. `mochi api` prints it verbatim,
+ * and the routes that answer with a patch, a log, or an archive are not JSON at
+ * all.
+ */
+async function request(target, method, pathname, opts = {}) {
+    let resp;
+    try {
+        resp = await fetch(`${target.host}${pathname}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${target.token}`,
+                ...(opts.body !== undefined ? { 'content-type': opts.contentType ?? 'application/json' } : {}),
+            },
+            body: opts.body,
+        });
+    }
+    catch (e) {
+        throw new exit_1.UnreachableError(`Could not reach ${target.host}: ${e instanceof Error ? e.message : e}`);
+    }
+    return {
+        ok: resp.ok,
+        status: resp.status,
+        contentType: resp.headers.get('content-type') ?? '',
+        body: await resp.text(),
+    };
+}
+/**
+ * The same, with the body left as bytes. A tar or an archive is not text, and
+ * decoding it as UTF-8 to hand it back would corrupt it beyond recognition.
+ */
+async function requestBytes(target, method, pathname) {
+    let resp;
+    try {
+        resp = await fetch(`${target.host}${pathname}`, { method, headers: { authorization: `Bearer ${target.token}` } });
+    }
+    catch (e) {
+        throw new exit_1.UnreachableError(`Could not reach ${target.host}: ${e instanceof Error ? e.message : e}`);
+    }
+    return { ok: resp.ok, status: resp.status, body: Buffer.from(await resp.arrayBuffer()) };
+}
+/** One API call, with the status left to the caller: for the calls where a 404 is an answer rather than a failure. */
+async function apiTry(target, method, pathname, body) {
+    const r = await request(target, method, pathname, {
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    let data = null;
+    try {
+        data = JSON.parse(r.body);
+    }
+    catch {
+        data = null;
+    }
+    return { ok: r.ok, status: r.status, data: data ?? {} };
+}
+/** The vault refused: report what it said, with the exit code its status maps to. */
+function apiFailed(target, pathname, r) {
+    throw new exit_1.CliError(r.data.error ? String(r.data.error) : `HTTP ${r.status} from ${target.host}${pathname}`, (0, exit_1.exitCodeForStatus)(r.status));
+}
+async function api(target, method, pathname, body) {
+    const r = await apiTry(target, method, pathname, body);
+    if (!r.ok)
+        apiFailed(target, pathname, r);
+    return r.data;
+}