@magland/mochi 0.3.1

package/dist/cli/admin-cmd.js

@@ -0,0 +1,324 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.adminCommands = void 0;
+const cli_api_1 = require("../cli-api");
+const exit_1 = require("./exit");
+const output_1 = require("./output");
+const target_1 = require("./target");
+// The rest of administration: reading and removing users, listing and revoking
+// their tokens, removing an empty collection, and the vault's own settings.
+const YES_OPTION = {
+    name: 'yes',
+    type: 'boolean',
+    summary: 'Required: confirm that this cannot be undone',
+};
+exports.adminCommands = [
+    {
+        path: ['user', 'view'],
+        summary: "Show one user's standing and the tokens they hold",
+        description: `Never a token, and never a token's hash: only a SHA-256 hash is stored, so there
+is nothing to show even if it were a good idea. What comes back is the id
+revocation takes, when the token was minted, and any scope of its own.`,
+        args: [{ name: 'username', required: true }],
+        options: [output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'GET', `/api/users/${encodeURIComponent(inv.args[0])}`);
+            const tokens = (data.tokens ?? []);
+            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.name} @ ${target.host}`);
+            console.log(`  ${data.siteAdmin ? 'site admin' : `owns collection '${data.name}' by name`}`);
+            console.log('');
+            if (tokens.length === 0) {
+                console.log('No tokens, so this user cannot sign in or push.');
+                return;
+            }
+            (0, output_1.printTable)(tokens.map((t) => [
+                String(t.id),
+                (0, output_1.shortDate)(t.created) || '(unknown date)',
+                t.scope ? `restricted to: ${t.scope.join(', ')}` : '',
+            ]));
+        },
+    },
+    {
+        path: ['user', 'delete'],
+        summary: 'Remove a user and every token they hold',
+        args: [{ name: 'username', required: true }],
+        options: [YES_OPTION, output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            if (!inv.bool('yes'))
+                throw new exit_1.CliError('Removing a user cannot be undone. Pass --yes.', exit_1.EXIT_USAGE);
+            const name = inv.args[0];
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `/api/users/${encodeURIComponent(name)}?confirm=${encodeURIComponent(name)}`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Removed ${data.deleted}`);
+        },
+    },
+    {
+        path: ['user', 'token', 'list'],
+        summary: "List a user's tokens, by the id revocation takes",
+        args: [{ name: 'username', required: true }],
+        options: [output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'GET', `/api/users/${encodeURIComponent(inv.args[0])}/tokens`);
+            const tokens = (data.tokens ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ tokens: (0, output_1.pickFields)(tokens, json.fields) });
+                return;
+            }
+            if (tokens.length === 0) {
+                console.log('No tokens');
+                return;
+            }
+            (0, output_1.printTable)(tokens.map((t) => [
+                String(t.id),
+                (0, output_1.shortDate)(t.created) || '(unknown date)',
+                t.scope ? `restricted to: ${t.scope.join(', ')}` : '',
+            ]));
+        },
+    },
+    {
+        path: ['user', 'token', 'revoke'],
+        summary: 'Revoke one token, leaving the user and their other tokens',
+        description: `Revoking the token you are using is allowed and is reported rather than refused:
+locking yourself out is your business, and vault.json remains hand-editable.`,
+        args: [
+            { name: 'username', required: true },
+            { name: 'token-id', required: true },
+        ],
+        options: [YES_OPTION, output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            if (!inv.bool('yes'))
+                throw new exit_1.CliError('Revoking a token cannot be undone. Pass --yes.', exit_1.EXIT_USAGE);
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `/api/users/${encodeURIComponent(inv.args[0])}/tokens/${encodeURIComponent(inv.args[1])}`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Revoked ${data.revoked}; ${data.remaining} token${data.remaining === 1 ? '' : 's'} left.`);
+            if (data.wasThisToken)
+                console.log('That was the token this command authenticated with, so it will not work again.');
+        },
+    },
+    {
+        path: ['collection', 'rename'],
+        summary: 'Rename a collection, with every repository in it',
+        description: `Everything the collection holds moves with it: the repositories, their issues,
+pull requests, releases, sites, run histories, and LFS objects. Requests for
+the old address are redirected to the new one, so links and existing clones
+keep working, until something else is created under that name. Token scopes
+naming the old collection are the exception: they cover nothing afterwards and
+have to be granted again under the new name.
+
+Takes ownership of the collection; the owners travel with it. No --yes: a
+rename is undone by renaming back.`,
+        args: [
+            { name: 'name', required: true },
+            { name: 'new-name', required: true },
+        ],
+        options: [output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'POST', `/api/collections/${encodeURIComponent(inv.args[0])}/rename`, {
+                name: inv.args[1],
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            // A rename to the name it already has is a success with nothing done,
+            // which the API answers as changed:false rather than as an error.
+            if (data.changed === false) {
+                console.log(String(data.message ?? 'Nothing changed.'));
+                return;
+            }
+            const repos = Number(data.repos ?? 0);
+            console.log(`Now ${data.name}, with ${repos} ${repos === 1 ? 'repository' : 'repositories'} in it`);
+            console.log('Remotes pointing at the old name, and token scopes naming it, need changing.');
+        },
+    },
+    {
+        path: ['collection', 'delete'],
+        summary: 'Remove an empty collection',
+        description: `A collection is a directory, so this is an rmdir: one holding anything at all is
+refused rather than emptied.`,
+        args: [{ name: 'name', required: true }],
+        options: [YES_OPTION, output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            if (!inv.bool('yes'))
+                throw new exit_1.CliError('Removing a collection cannot be undone. Pass --yes.', exit_1.EXIT_USAGE);
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `/api/collections/${encodeURIComponent(inv.args[0])}`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Removed ${data.deleted}`);
+        },
+    },
+    {
+        path: ['config', 'view'],
+        summary: "Show the vault's settings",
+        options: [output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'GET', '/api/config');
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            const ci = (data.ci ?? {});
+            const sites = (data.sites ?? {});
+            const network = (data.network ?? {});
+            const limits = (data.limits ?? {});
+            (0, output_1.printTable)([
+                ['theme', String(data.theme)],
+                ['ci.runs', String(ci.runs)],
+                ['ci.days', String(ci.days)],
+                ['ci.artifactMb', String(ci.artifactMb)],
+                ['sites.host', String(sites.host || '(none; sites are sandboxed on the forge host)')],
+                ['network.trustProxy', String(network.trustProxy)],
+                ['limits.requestsPerMinute', String(limits.requestsPerMinute)],
+                ['limits.authFailures', String(limits.authFailures)],
+                [
+                    'limits.egressGbPerDay',
+                    Number(limits.egressGbPerDay) > 0 ? String(limits.egressGbPerDay) : '0 (no daily limit on outgoing bytes)',
+                ],
+            ]);
+            console.log('');
+            console.log(`themes: ${data.themes.join(', ')}`);
+            // Saying which of these a write can reach saves a caller discovering it by
+            // being refused.
+            console.log('theme, ci, sites.host, and limits.egressGbPerDay can be set with `mochi config set`.');
+            console.log('network and the rest of limits are read once at startup: edit config.json in the vault and restart.');
+            console.log('`mochi api /api/egress` shows what has gone out today, per repository.');
+        },
+    },
+    {
+        path: ['config', 'set'],
+        summary: 'Change the theme, the sites hostname, or the CI retention settings',
+        description: `Writes config.json in the vault, so a hosted vault is configured the same way as
+one on your desk and there is no reason to reach its disk by hand.
+
+--sites-host gives each repository's static site an origin of its own at
+<repo>--<collection>.<host>, in place of the sandbox they are served under on the
+vault's own hostname. Set it only once that hostname resolves to this vault and a
+wildcard certificate covers it, since sites stop being served anywhere else the
+moment it is set. --sites-host '' puts them back.
+
+--egress-gb-per-day caps the bytes the vault may send in one UTC day, over
+everything. Once a day's total reaches it, ordinary requests are refused with a
+503 until 00:00 UTC; administration and signing in keep working, so the cap can
+be raised from the vault itself. 0 sends without a limit. It is read per request,
+so a change is in force immediately.
+
+network.trustProxy and the rest of the limits block are not here. They are read
+once when the server starts, so a command that changed them would report a change
+the running server had not made. Edit config.json in the vault and restart.`,
+        options: [
+            { name: 'theme', type: 'string', value: '<t>', summary: 'Theme name' },
+            {
+                name: 'sites-host',
+                type: 'string',
+                value: '<host>',
+                summary: "Hostname whose subdomains serve sites; '' to serve them sandboxed on the forge host",
+            },
+            { name: 'ci-runs', type: 'int', value: '<n>', summary: 'Completed runs to keep per repository' },
+            { name: 'ci-days', type: 'int', value: '<n>', summary: 'Also drop runs older than this; 0 disables' },
+            { name: 'ci-artifact-mb', type: 'int', value: '<n>', summary: 'Largest artifact a job may upload' },
+            {
+                name: 'egress-gb-per-day',
+                type: 'string',
+                value: '<gb>',
+                summary: 'Gigabytes the vault may send per UTC day; 0 for no limit',
+            },
+            output_1.JSON_OPTION,
+            ...target_1.TARGET_OPTIONS,
+        ],
+        async run(inv) {
+            const theme = inv.str('theme');
+            // An empty string is a value here rather than an absence: it is how the
+            // sites hostname is cleared, and str() returns null only when the option
+            // was not given at all.
+            const sitesHost = inv.str('sites-host');
+            const runs = inv.int('ci-runs');
+            const days = inv.int('ci-days');
+            const artifactMb = inv.int('ci-artifact-mb');
+            // Taken as a string and parsed here rather than declared as an int: half a
+            // gigabyte is a reasonable budget to give a vault, and the option parser
+            // has no float type.
+            const egressRaw = inv.str('egress-gb-per-day');
+            let egressGbPerDay = null;
+            if (egressRaw !== null) {
+                const gb = Number(egressRaw.trim());
+                if (egressRaw.trim() === '' || !Number.isFinite(gb) || gb < 0) {
+                    throw new exit_1.CliError('--egress-gb-per-day takes a number of gigabytes, or 0 for no limit.', exit_1.EXIT_USAGE);
+                }
+                egressGbPerDay = gb;
+            }
+            if (theme === null &&
+                sitesHost === null &&
+                runs === null &&
+                days === null &&
+                artifactMb === null &&
+                egressGbPerDay === null) {
+                throw new exit_1.CliError('Nothing to change. Pass --theme, --sites-host, --ci-runs, --ci-days, --ci-artifact-mb, or --egress-gb-per-day.', exit_1.EXIT_USAGE);
+            }
+            const target = await (0, target_1.targetFrom)(inv);
+            // The CI block is written whole, so the fields not named have to come from
+            // what is there now rather than from a default.
+            let ci;
+            if (runs !== null || days !== null || artifactMb !== null) {
+                const current = (await (0, cli_api_1.api)(target, 'GET', '/api/config')).ci;
+                ci = {
+                    runs: runs ?? current.runs,
+                    days: days ?? current.days,
+                    artifactMb: artifactMb ?? current.artifactMb,
+                };
+            }
+            const data = await (0, cli_api_1.api)(target, 'PATCH', '/api/config', {
+                theme: theme ?? undefined,
+                ci,
+                sites: sitesHost === null ? undefined : { host: sitesHost },
+                // The route merges this into the block it is part of, since the rest of
+                // it is not writable from here.
+                limits: egressGbPerDay === null ? undefined : { egressGbPerDay },
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`theme: ${data.theme}`);
+            const saved = data.ci;
+            console.log(`ci: keep ${saved.runs} runs, ${saved.days} days, artifacts up to ${saved.artifactMb} MB`);
+            const host = String((data.sites ?? {}).host ?? '');
+            console.log(host
+                ? `sites: served from <repo>--<collection>.${host}`
+                : "sites: served sandboxed on the vault's own hostname");
+            // Every reader of this setting calls loadConfig per request, so there is
+            // nothing further to do; saying so is worth a line, because the settings
+            // next to it in the same file do need a restart.
+            const gb = Number((data.limits ?? {}).egressGbPerDay ?? 0);
+            console.log(gb > 0 ? `egress: up to ${gb} GB per UTC day` : 'egress: no daily limit');
+            if (sitesHost !== null || egressGbPerDay !== null)
+                console.log('In effect now; no restart needed.');
+        },
+    },
+];

package/dist/cli/api-cmd.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiCommand = void 0;
+exports.normalizeApiPath = normalizeApiPath;
+const cli_api_1 = require("../cli-api");
+const exit_1 = require("./exit");
+const input_1 = require("./input");
+const target_1 = require("./target");
+// The escape hatch. Every route the vault has is reachable the day it lands,
+// whether or not a typed command has been written for it, which is what keeps a
+// gap in the command set an inconvenience rather than a blocker. The shape
+// follows `gh api` closely enough that someone who knows that one needs no
+// second explanation.
+const FIELD_OPTIONS = [
+    {
+        name: 'method',
+        type: 'string',
+        value: '<m>',
+        short: 'X',
+        summary: 'HTTP method; defaults to GET, or POST when a body is given',
+    },
+    {
+        name: 'field',
+        type: 'string[]',
+        value: '<k=v>',
+        summary: 'JSON body field; true, false, null, and whole numbers are coerced',
+    },
+    { name: 'raw-field', type: 'string[]', value: '<k=v>', summary: 'JSON body field, always a string' },
+    { name: 'input', type: 'string', value: '<f>', summary: "Send this file as the body; '-' reads stdin" },
+    { name: 'include', type: 'boolean', short: 'i', summary: 'Print the status line and headers before the body' },
+];
+/**
+ * A path as typed becomes a path as sent. All four of these name the same
+ * route, because remembering which one this CLI wanted is not a good use of
+ * anyone's attention:
+ *
+ *   repos/demo/proj    /repos/demo/proj    api/repos/demo/proj    /api/repos/demo/proj
+ */
+function normalizeApiPath(given) {
+    let p = given.trim();
+    if (/^https?:\/\//i.test(p)) {
+        // A full URL is accepted for its path only: the host comes from the login,
+        // so that a token is never sent somewhere the caller did not configure.
+        try {
+            const u = new URL(p);
+            p = u.pathname + u.search;
+        }
+        catch {
+            throw new exit_1.CliError(`not a URL: ${given}`, exit_1.EXIT_USAGE);
+        }
+    }
+    p = p.replace(/^\/+/, '');
+    if (!p.startsWith('api/') && p !== 'api')
+        p = `api/${p}`;
+    return `/${p}`;
+}
+function coerce(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === 'null')
+        return null;
+    if (/^-?\d+$/.test(value))
+        return Number(value);
+    return value;
+}
+function splitField(pair, flag) {
+    const i = pair.indexOf('=');
+    if (i <= 0)
+        throw new exit_1.CliError(`--${flag} takes key=value, not '${pair}'`, exit_1.EXIT_USAGE);
+    return [pair.slice(0, i), pair.slice(i + 1)];
+}
+async function bodyFor(inv) {
+    const input = inv.str('input');
+    const fields = inv.list('field');
+    const rawFields = inv.list('raw-field');
+    if (input && (fields.length || rawFields.length)) {
+        throw new exit_1.CliError('Pass either --input or --field/--raw-field, not both.', exit_1.EXIT_USAGE);
+    }
+    if (input)
+        return await (0, input_1.readFileArg)(input);
+    if (!fields.length && !rawFields.length)
+        return undefined;
+    const body = {};
+    for (const pair of fields) {
+        const [k, v] = splitField(pair, 'field');
+        body[k] = coerce(v);
+    }
+    for (const pair of rawFields) {
+        const [k, v] = splitField(pair, 'raw-field');
+        body[k] = v;
+    }
+    return JSON.stringify(body);
+}
+exports.apiCommand = {
+    path: ['api'],
+    summary: 'Call any route of the vault JSON API and print what it answers',
+    description: `The path may be written with or without a leading slash and with or without the
+'api/' prefix, so 'repos/demo/proj' and '/api/repos/demo/proj' are the same
+route. The response body is printed verbatim on stdout, whatever its type; a
+non-2xx status prints the body on stderr instead and exits non-zero, with the
+same exit codes every other command uses (4 for 404, 5 for 409).
+
+  mochi api repos/demo/proj/issues
+  mochi api repos/demo/proj/issues -X POST --field title=Bug --field 'body=It broke'
+  mochi api repos/demo/proj/issues/1/state -X POST --field state=closed
+  mochi api repos/demo/proj/contents/README.md --input patch.json -X PUT`,
+    args: [{ name: 'path', required: true }],
+    options: [...FIELD_OPTIONS, ...target_1.TARGET_OPTIONS],
+    async run(inv) {
+        const target = await (0, target_1.targetFrom)(inv);
+        const pathname = normalizeApiPath(inv.args[0]);
+        const body = await bodyFor(inv);
+        const method = (inv.str('method') ?? (body === undefined ? 'GET' : 'POST')).toUpperCase();
+        const r = await (0, cli_api_1.request)(target, method, pathname, { body });
+        if (inv.bool('include')) {
+            process.stderr.write(`HTTP ${r.status}\n`);
+            if (r.contentType)
+                process.stderr.write(`content-type: ${r.contentType}\n\n`);
+        }
+        if (!r.ok) {
+            process.stderr.write(r.body.endsWith('\n') || r.body === '' ? r.body : r.body + '\n');
+            process.exit((0, exit_1.exitCodeForStatus)(r.status));
+        }
+        process.stdout.write(r.body.endsWith('\n') || r.body === '' ? r.body : r.body + '\n');
+    },
+};