@magland/mochi 0.3.1

package/dist/cli/repo-cmd.js

@@ -0,0 +1,763 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.repoCommands = void 0;
+const child_process_1 = require("child_process");
+const cli_api_1 = require("../cli-api");
+const exit_1 = require("./exit");
+const input_1 = require("./input");
+const output_1 = require("./output");
+const repo_1 = require("./repo");
+const target_1 = require("./target");
+// Reading a repository from the command line: what is in it, what one file says,
+// what changed, and where something appears. Between them these are what let a
+// caller work on a repository without cloning it.
+const COMMON = [repo_1.REPO_OPTION, ...target_1.TARGET_OPTIONS];
+const REF_OPTION = {
+    name: 'ref',
+    type: 'string',
+    value: '<r>',
+    summary: 'Branch, tag, or commit; the default branch otherwise',
+};
+// Every destructive command takes --yes and refuses without it, rather than
+// prompting. A prompt is no use to a caller that is not a person, and a command
+// that prompts is a command that hangs in a container.
+const YES_OPTION = {
+    name: 'yes',
+    type: 'boolean',
+    summary: 'Required: confirm that this cannot be undone',
+};
+function requireYes(inv, what) {
+    if (!inv.bool('yes'))
+        throw new exit_1.CliError(`${what} cannot be undone. Pass --yes to go ahead.`, exit_1.EXIT_USAGE);
+}
+function refQuery(ref, extra = {}) {
+    const q = new URLSearchParams(extra);
+    if (ref !== null)
+        q.set('ref', ref);
+    const s = q.toString();
+    return s ? `?${s}` : '';
+}
+exports.repoCommands = [
+    {
+        path: ['repo', 'list'],
+        summary: 'List the repositories in the vault',
+        args: [{ name: 'collection' }],
+        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/repos');
+            const only = inv.args[0] ?? null;
+            const repos = (data.repos ?? []).filter((r) => only === null || r.collection === only);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ repos: (0, output_1.pickFields)(repos, json.fields) });
+                return;
+            }
+            if (repos.length === 0) {
+                console.log(only ? `No repositories in ${only}` : `No repositories on ${target.host}`);
+                return;
+            }
+            (0, output_1.printTable)(repos.map((r) => [
+                `${r.collection}/${r.name}${r.private ? ' (private)' : ''}`,
+                String(r.description ?? ''),
+            ]));
+        },
+    },
+    {
+        path: ['repo', 'view'],
+        summary: 'Show one repository: its default branch, counts, and whether it has a site',
+        args: [{ name: 'repo' }],
+        options: [output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const ref = await (0, repo_1.resolveRepo)(inv, target, inv.args[0] ?? null);
+            const data = await (0, cli_api_1.api)(target, 'GET', (0, repo_1.repoPath)(ref));
+            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.collection}/${data.name}`);
+            if (data.description)
+                console.log(String(data.description));
+            if (data.forkedFrom) {
+                const from = data.forkedFrom;
+                console.log(`forked from ${from.collection}/${from.repo}`);
+            }
+            (0, output_1.printTable)([
+                ['visibility', data.private ? 'private' : 'public'],
+                ['default branch', String(data.defaultBranch ?? '(none)')],
+                ['last updated', (0, output_1.shortDate)(data.updated)],
+                ['branches', String(data.branches)],
+                ['tags', String(data.tags)],
+                ['releases', String(data.releases)],
+                ['open issues', String(data.openIssues)],
+                ['open pull requests', String(data.openPulls)],
+                ['site', data.hasSite ? 'yes' : 'no'],
+            ]);
+        },
+    },
+    {
+        path: ['repo', 'create'],
+        summary: 'Create an empty repository, or one with a README in it',
+        args: [{ name: 'collection/name', required: true }],
+        options: [
+            { name: 'description', type: 'string', value: '<d>', summary: 'One-line description' },
+            { name: 'readme', type: 'boolean', summary: 'Add a first commit with a README.md' },
+            { name: 'private', type: 'boolean', summary: 'Visible only to collaborators, owners, and site admins' },
+            output_1.JSON_OPTION,
+            ...target_1.TARGET_OPTIONS,
+        ],
+        async run(inv) {
+            const parts = inv.args[0].split('/');
+            if (parts.length !== 2 || !parts[0] || !parts[1]) {
+                throw new exit_1.CliError('name the repository as <collection>/<name>', exit_1.EXIT_USAGE);
+            }
+            const target = await (0, target_1.targetFrom)(inv);
+            const data = await (0, cli_api_1.api)(target, 'POST', '/api/repos', {
+                collection: parts[0],
+                name: parts[1],
+                description: inv.str('description') ?? undefined,
+                initReadme: inv.bool('readme'),
+                private: inv.bool('private') || 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(`${target.host}/${data.collection}/${data.name}`);
+        },
+    },
+    {
+        path: ['repo', 'fork'],
+        summary: 'Copy a repository into another collection',
+        args: [
+            { name: 'repo', required: true },
+            { name: 'collection[/name]', required: true },
+        ],
+        options: [output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const source = await (0, repo_1.resolveRepo)(inv, target, inv.args[0]);
+            const parts = inv.args[1].split('/');
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(source)}/fork`, {
+                collection: parts[0],
+                name: parts[1] ?? 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(`${target.host}/${data.collection}/${data.name}`);
+        },
+    },
+    {
+        path: ['repo', 'edit'],
+        summary: 'Change a repository description, default branch, or visibility',
+        args: [{ name: 'repo' }],
+        options: [
+            { name: 'description', type: 'string', value: '<d>', summary: 'New description' },
+            { name: 'default-branch', type: 'string', value: '<b>', summary: 'New default branch' },
+            { name: 'private', type: 'boolean', summary: 'Make the repository private (takes the admin role)' },
+            { name: 'public', type: 'boolean', summary: 'Make the repository public' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const description = inv.str('description');
+            const defaultBranch = inv.str('default-branch');
+            if (inv.bool('private') && inv.bool('public')) {
+                throw new exit_1.CliError('Pass --private or --public, not both.', exit_1.EXIT_USAGE);
+            }
+            const priv = inv.bool('private') ? true : inv.bool('public') ? false : undefined;
+            if (description === null && defaultBranch === null && priv === undefined) {
+                throw new exit_1.CliError('Nothing to change. Pass --description, --default-branch, --private, or --public.', exit_1.EXIT_USAGE);
+            }
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target, inv.args[0] ?? null);
+            const data = await (0, cli_api_1.api)(target, 'PATCH', (0, repo_1.repoPath)(repo), {
+                description: description ?? undefined,
+                defaultBranch: defaultBranch ?? undefined,
+                private: priv,
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Updated ${data.collection}/${data.name}`);
+        },
+    },
+    {
+        path: ['repo', 'rename'],
+        summary: 'Rename a repository, or move it to another collection',
+        description: `A repository is a bare repository plus the directories it keeps beside it, for
+its issues, pull requests, releases, site, and run history. All of them move
+together.`,
+        args: [
+            { name: 'repo', required: true },
+            { name: 'new-name', required: true },
+        ],
+        options: [
+            { name: 'collection', type: 'string', value: '<c>', summary: 'Move it to this collection as well' },
+            output_1.JSON_OPTION,
+            ...target_1.TARGET_OPTIONS,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target, inv.args[0]);
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(repo)}/rename`, {
+                name: inv.args[1],
+                collection: inv.str('collection') ?? undefined,
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            // As for a collection: asking for the name it already has is answered as
+            // changed:false, and printing "Now undefined/undefined" for it would be
+            // a report of something that did not happen.
+            if (data.changed === false) {
+                console.log(String(data.message ?? 'Nothing changed.'));
+                return;
+            }
+            console.log(`Now ${data.collection}/${data.name}`);
+        },
+    },
+    {
+        path: ['repo', 'delete'],
+        summary: 'Delete a repository and everything beside it',
+        args: [{ name: 'repo', required: true }],
+        options: [YES_OPTION, output_1.JSON_OPTION, ...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            requireYes(inv, 'Deleting a repository');
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target, inv.args[0]);
+            const full = `${repo.collection}/${repo.repo}`;
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `${(0, repo_1.repoPath)(repo)}?confirm=${encodeURIComponent(full)}`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Deleted ${full}`);
+        },
+    },
+    {
+        path: ['repo', 'clone'],
+        summary: 'git clone, with the vault URL filled in',
+        description: `A thin wrapper over git clone. The URL is otherwise assembled by hand from the
+login, and the credential arrangement is already in place, so this saves the
+assembling and nothing else.`,
+        args: [{ name: 'repo', required: true }, { name: 'directory' }],
+        options: [...target_1.TARGET_OPTIONS],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target, inv.args[0]);
+            const url = `${target.host}/${repo.collection}/${repo.repo}`;
+            const args = ['clone', url, ...(inv.args[1] ? [inv.args[1]] : [])];
+            const code = await new Promise((resolve) => {
+                const child = (0, child_process_1.spawn)('git', args, { stdio: 'inherit' });
+                child.on('error', () => resolve(exit_1.EXIT_FAIL));
+                child.on('close', (c) => resolve(c ?? exit_1.EXIT_FAIL));
+            });
+            if (code !== 0)
+                process.exit(code);
+        },
+    },
+    {
+        path: ['branch', 'list'],
+        summary: 'List branches',
+        options: [output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const ref = await (0, repo_1.resolveRepo)(inv, target);
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(ref)}/branches`);
+            const branches = (data.branches ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ branches: (0, output_1.pickFields)(branches, json.fields), defaultBranch: data.defaultBranch });
+                return;
+            }
+            (0, output_1.printTable)(branches.map((b) => [
+                b.name === data.defaultBranch ? `* ${b.name}` : `  ${b.name}`,
+                String(b.sha).slice(0, 10),
+                (0, output_1.shortDate)(b.date),
+                String(b.subject ?? ''),
+            ]));
+        },
+    },
+    {
+        path: ['branch', 'create'],
+        summary: 'Create a branch at a ref',
+        args: [{ name: 'name', required: true }, { name: 'from' }],
+        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 from = inv.args[1] ?? null;
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(repo)}/branches`, {
+                name: inv.args[0],
+                // No `from` means from the default branch, which is what a caller
+                // starting a branch almost always means.
+                from: from ?? (await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/branches`)).defaultBranch,
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Created ${data.name} at ${String(data.sha).slice(0, 10)}`);
+        },
+    },
+    {
+        path: ['branch', 'delete'],
+        summary: 'Delete a branch',
+        args: [{ name: 'name', required: true }],
+        options: [YES_OPTION, output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            requireYes(inv, 'Deleting a branch');
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `${(0, repo_1.repoPath)(repo)}/branches/${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(`Deleted ${data.deleted}`);
+        },
+    },
+    {
+        path: ['tag', 'list'],
+        summary: 'List tags',
+        options: [output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const ref = await (0, repo_1.resolveRepo)(inv, target);
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(ref)}/tags`);
+            const tags = (data.tags ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ tags: (0, output_1.pickFields)(tags, json.fields) });
+                return;
+            }
+            if (tags.length === 0) {
+                console.log('No tags');
+                return;
+            }
+            (0, output_1.printTable)(tags.map((t) => [String(t.name), String(t.sha).slice(0, 10), (0, output_1.shortDate)(t.date), String(t.subject ?? '')]));
+        },
+    },
+    {
+        path: ['tag', 'create'],
+        summary: 'Create a tag at a ref',
+        args: [{ name: 'name', required: true }, { name: 'at' }],
+        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 at = inv.args[1] ?? null;
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(repo)}/tags`, {
+                name: inv.args[0],
+                at: at ?? (await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/branches`)).defaultBranch,
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Created ${data.name} at ${String(data.sha).slice(0, 10)}`);
+        },
+    },
+    {
+        path: ['tag', 'delete'],
+        summary: 'Delete a tag',
+        args: [{ name: 'name', required: true }],
+        options: [YES_OPTION, output_1.JSON_OPTION, ...COMMON],
+        async run(inv) {
+            requireYes(inv, 'Deleting a tag');
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `${(0, repo_1.repoPath)(repo)}/tags/${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(`Deleted ${data.deleted}`);
+        },
+    },
+    {
+        path: ['file', 'list'],
+        summary: 'List a directory, or every path in the tree',
+        description: `With no path this lists the repository root. --all lists every path in the tree
+instead, which is the listing a caller looking for a file wants.`,
+        args: [{ name: 'path' }],
+        options: [
+            REF_OPTION,
+            { name: 'all', type: 'boolean', summary: 'Every path in the tree, recursively' },
+            { name: 'commits', type: 'boolean', summary: 'Add the last commit for each entry (one git log each)' },
+            { name: 'limit', type: 'int', value: '<n>', summary: 'With --all, at most this many paths' },
+            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 json = (0, output_1.jsonMode)(inv);
+            if (inv.bool('all')) {
+                const limit = inv.int('limit');
+                const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/paths${refQuery(ref, limit !== null ? { limit: String(limit) } : {})}`);
+                if (json.enabled) {
+                    (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                    return;
+                }
+                for (const p of (data.paths ?? []))
+                    console.log(p);
+                if (data.truncated)
+                    console.error('(the list was capped by the server; ask for fewer paths)');
+                return;
+            }
+            const dir = (inv.args[0] ?? '').replace(/^\/+/, '');
+            const query = refQuery(ref, inv.bool('commits') ? { commits: '1' } : {});
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/tree/${dir}${query}`);
+            const entries = (data.entries ?? []);
+            if (json.enabled) {
+                (0, output_1.printJson)({ ref: data.ref, path: data.path, entries: (0, output_1.pickFields)(entries, json.fields) });
+                return;
+            }
+            (0, output_1.printTable)(entries.map((e) => {
+                const last = e.lastCommit;
+                const row = [String(e.type), String(e.name), e.size === null ? '' : String(e.size)];
+                return last ? [...row, (0, output_1.shortDate)(last.date), String(last.subject ?? '')] : row;
+            }));
+        },
+    },
+    {
+        path: ['file', 'view'],
+        summary: 'Print one file',
+        description: `Text is printed as text. A binary file is refused rather than written to a
+terminal, unless --raw is given, which streams the bytes exactly as the vault
+serves them. A Git LFS pointer is reported as one rather than handed over as if it
+were the file, since the bytes are elsewhere.`,
+        args: [{ name: 'path', required: true }],
+        options: [
+            REF_OPTION,
+            { name: 'raw', type: 'boolean', summary: 'The bytes, unchanged, whatever they are' },
+            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 filePath = inv.args[0].replace(/^\/+/, '');
+            if (inv.bool('raw')) {
+                const r = await (0, cli_api_1.request)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/raw/${filePath}${refQuery(ref)}`);
+                if (!r.ok) {
+                    process.stderr.write(r.body.endsWith('\n') ? r.body : r.body + '\n');
+                    process.exit((0, exit_1.exitCodeForStatus)(r.status));
+                }
+                process.stdout.write(r.body);
+                return;
+            }
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/contents/${filePath}${refQuery(ref)}`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            if (data.encoding === 'lfs-pointer') {
+                const lfs = data.lfs;
+                console.error(`${filePath} is a Git LFS pointer (oid ${lfs.oid}, ${lfs.size} bytes).`);
+                console.error('Fetch it with a clone that has git-lfs, or with --raw.');
+                process.exit(exit_1.EXIT_USAGE);
+            }
+            if (data.encoding === 'base64') {
+                console.error(`${filePath} is binary (${data.size} bytes). Pass --raw to write the bytes out.`);
+                process.exit(exit_1.EXIT_USAGE);
+            }
+            process.stdout.write(String(data.content ?? ''));
+        },
+    },
+    {
+        path: ['file', 'write'],
+        summary: 'Create or replace a file, committing the change',
+        description: `The content comes from --body-file, or from --body, or from stdin when neither is
+given, so a generated file can be piped straight in.
+
+--expected-sha is the commit the caller last saw. Given one, a branch that has
+moved since is a conflict (exit 5) rather than a silent overwrite, which is what a
+caller that reads, thinks, and then writes wants. 'mochi file view <path>
+--json=commit' is where that value comes from.`,
+        args: [{ name: 'path', required: true }],
+        options: [
+            { name: 'branch', type: 'string', value: '<b>', summary: 'Branch to commit on; the default branch otherwise' },
+            { name: 'new-branch', type: 'string', value: '<b>', summary: 'Create this branch and commit there instead' },
+            { name: 'message', type: 'string', value: '<m>', summary: 'Commit message' },
+            { name: 'body', type: 'string', value: '<t>', summary: 'The file content' },
+            { name: 'body-file', type: 'string', value: '<f>', summary: "Read the content from a file, or '-' for stdin" },
+            { name: 'expected-sha', type: 'string', value: '<s>', summary: 'The commit the caller last saw at the branch tip' },
+            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 inline = inv.str('body');
+            const file = inv.str('body-file');
+            if (inline !== null && file !== null) {
+                throw new exit_1.CliError('Pass either --body or --body-file, not both.', exit_1.EXIT_USAGE);
+            }
+            const content = inline !== null ? inline : await (0, input_1.readFileArg)(file ?? '-');
+            const data = await (0, cli_api_1.api)(target, 'PUT', `${(0, repo_1.repoPath)(repo)}/contents/${inv.args[0].replace(/^\/+/, '')}`, {
+                branch: inv.str('branch') ?? (await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/branches`)).defaultBranch ?? 'main',
+                newBranch: inv.str('new-branch') ?? undefined,
+                message: inv.str('message') ?? undefined,
+                expectedSha: inv.str('expected-sha') ?? undefined,
+                content,
+            });
+            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.created ? 'Created' : 'Updated'} ${data.path} on ${data.branch} as ${String(data.sha).slice(0, 10)}`);
+        },
+    },
+    {
+        path: ['file', 'delete'],
+        summary: 'Delete a file, committing the change',
+        args: [{ name: 'path', required: true }],
+        options: [
+            { name: 'branch', type: 'string', value: '<b>', summary: 'Branch to commit on; the default branch otherwise' },
+            { name: 'message', type: 'string', value: '<m>', summary: 'Commit message' },
+            { name: 'expected-sha', type: 'string', value: '<s>', summary: 'The commit the caller last saw at the branch tip' },
+            YES_OPTION,
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            requireYes(inv, 'Deleting a file');
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `${(0, repo_1.repoPath)(repo)}/contents/${inv.args[0].replace(/^\/+/, '')}`, {
+                branch: inv.str('branch') ?? (await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/branches`)).defaultBranch ?? 'main',
+                message: inv.str('message') ?? undefined,
+                expectedSha: inv.str('expected-sha') ?? 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(`Deleted ${data.path} on ${data.branch} as ${String(data.sha).slice(0, 10)}`);
+        },
+    },
+    {
+        path: ['commit', 'list'],
+        summary: 'List commits',
+        options: [
+            REF_OPTION,
+            { name: 'path', type: 'string', value: '<p>', summary: 'Only commits touching this path' },
+            { 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 extra = {};
+            const filePath = inv.str('path');
+            if (filePath !== null)
+                extra.path = filePath;
+            const limit = inv.int('limit');
+            if (limit !== null)
+                extra.limit = String(limit);
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/commits${refQuery(inv.str('ref'), extra)}`);
+            const commits = (data.commits ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ ref: data.ref, commits: (0, output_1.pickFields)(commits, json.fields) });
+                return;
+            }
+            (0, output_1.printTable)(commits.map((c) => [String(c.sha).slice(0, 10), (0, output_1.shortDate)(c.date), String(c.author), String(c.subject)]));
+        },
+    },
+    {
+        path: ['commit', 'view'],
+        summary: 'Show one commit',
+        args: [{ name: 'sha', required: true }],
+        options: [
+            { name: 'patch', type: 'boolean', summary: 'Print the patch instead of the summary' },
+            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 sha = inv.args[0];
+            if (inv.bool('patch')) {
+                const r = await (0, cli_api_1.request)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/commits/${encodeURIComponent(sha)}/patch`);
+                if (!r.ok) {
+                    process.stderr.write(r.body.endsWith('\n') ? r.body : r.body + '\n');
+                    process.exit((0, exit_1.exitCodeForStatus)(r.status));
+                }
+                process.stdout.write(r.body);
+                return;
+            }
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/commits/${encodeURIComponent(sha)}`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`commit ${data.sha}`);
+            console.log(`author ${data.author} <${data.email ?? ''}>`);
+            console.log(`date   ${data.date}`);
+            if (data.parents?.length)
+                console.log(`parents ${data.parents.join(' ')}`);
+            console.log('');
+            console.log(String(data.message ?? '').trimEnd());
+        },
+    },
+    {
+        path: ['diff'],
+        summary: 'Compare two refs, as <base>...<head>',
+        args: [{ name: 'range', required: true }],
+        options: [
+            { name: 'stat', type: 'boolean', summary: 'Only the counts and the commit list' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const range = inv.args[0];
+            if (!range.includes('...'))
+                throw new exit_1.CliError("ask for a comparison as <base>...<head>", exit_1.EXIT_USAGE);
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target);
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/compare/${range}`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            if (inv.bool('stat')) {
+                console.log(`${data.ahead} ahead, ${data.behind} behind`);
+                (0, output_1.printTable)((data.commits ?? []).map((c) => [String(c.sha).slice(0, 10), String(c.subject)]));
+                return;
+            }
+            process.stdout.write(String(data.patch ?? ''));
+        },
+    },
+    {
+        path: ['search'],
+        summary: 'Search a repository for literal text',
+        args: [{ name: 'query', required: true }],
+        options: [REF_OPTION, 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 = refQuery(inv.str('ref'), { q: inv.args[0] });
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/search${query}`);
+            const hits = (data.hits ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ ref: data.ref, query: data.query, hits: (0, output_1.pickFields)(hits, json.fields), truncated: data.truncated });
+                return;
+            }
+            if (hits.length === 0) {
+                console.log('No matches');
+                return;
+            }
+            for (const h of hits)
+                console.log(`${h.path}:${h.line}: ${String(h.text ?? '').trim()}`);
+            if (data.truncated)
+                console.error('(the server capped the results)');
+        },
+    },
+    // ---- collaborators ----
+    //
+    // All three take the admin role on the repository, as the API routes behind
+    // them do: who may see or write a repository is decided by the people who
+    // administer it.
+    {
+        path: ['collab', 'list'],
+        summary: "Show a repository's collaborators, and the owners standing over them",
+        args: [{ name: 'repo' }],
+        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, inv.args[0] ?? null);
+            const data = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(repo)}/collaborators`);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`${repo.collection}/${repo.repo} is ${data.private ? 'private' : 'public'}`);
+            const collaborators = (data.collaborators ?? []);
+            if (collaborators.length === 0)
+                console.log('No collaborators.');
+            else
+                (0, output_1.printTable)(collaborators.map((c) => [c.username, c.role]));
+            const owners = (data.owners ?? []);
+            console.log(`Owners of ${repo.collection} hold the admin role without being listed: ` +
+                `${[repo.collection, ...owners].join(', ')} (the first by bearing the collection's name).`);
+        },
+    },
+    {
+        path: ['collab', 'add'],
+        summary: 'Give a user a role on a repository',
+        description: `read may see a private repository; write may also push and edit; admin may also
+change its settings, visibility, and collaborators. Adding a user who already
+has a role replaces it.`,
+        args: [
+            { name: 'repo', required: true },
+            { name: 'username', required: true },
+        ],
+        options: [
+            { name: 'role', type: 'string', value: '<r>', summary: 'read, write (the default), or admin' },
+            output_1.JSON_OPTION,
+            ...target_1.TARGET_OPTIONS,
+        ],
+        async run(inv) {
+            const target = await (0, target_1.targetFrom)(inv);
+            const repo = await (0, repo_1.resolveRepo)(inv, target, inv.args[0]);
+            const data = await (0, cli_api_1.api)(target, 'PUT', `${(0, repo_1.repoPath)(repo)}/collaborators/${encodeURIComponent(inv.args[1])}`, {
+                role: inv.str('role') ?? 'write',
+            });
+            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.username} now has the ${data.role} role on ${repo.collection}/${repo.repo}`);
+        },
+    },
+    {
+        path: ['collab', 'remove'],
+        summary: "Remove a user's role on a repository",
+        args: [
+            { name: 'repo', required: true },
+            { 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 repo = await (0, repo_1.resolveRepo)(inv, target, inv.args[0]);
+            const data = await (0, cli_api_1.api)(target, 'DELETE', `${(0, repo_1.repoPath)(repo)}/collaborators/${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(`Removed ${data.removed} from ${repo.collection}/${repo.repo}`);
+        },
+    },
+];