@magland/mochi 0.3.1

package/dist/cli/exit.js

@@ -0,0 +1,69 @@
+"use strict";
+// Exit codes and the error type that carries them. A person reads the message
+// on stderr; a program reads the code, so the codes are part of the CLI's
+// contract and are documented in docs/cli.md and docs/agents.md. The two that
+// pay for themselves are 4 and 5: "does this exist" and "did someone else get
+// there first" are the questions a retrying caller asks, and both used to be
+// indistinguishable from every other failure.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnreachableError = exports.CliError = exports.EXIT_CONFLICT = exports.EXIT_NOTFOUND = exports.EXIT_AUTH = exports.EXIT_USAGE = exports.EXIT_FAIL = exports.EXIT_OK = void 0;
+exports.exitCodeForStatus = exitCodeForStatus;
+exports.setJsonErrors = setJsonErrors;
+exports.jsonErrorsWanted = jsonErrorsWanted;
+exports.EXIT_OK = 0;
+/** Generic failure, including a 4xx or 5xx from the vault with no code of its own. */
+exports.EXIT_FAIL = 1;
+/** Unknown command, unknown flag, missing argument. */
+exports.EXIT_USAGE = 2;
+/** No token, or the vault rejected the one given. */
+exports.EXIT_AUTH = 3;
+/** The vault answered 404 for the addressed resource. */
+exports.EXIT_NOTFOUND = 4;
+/** The vault answered 409, or an operation was refused because of state. */
+exports.EXIT_CONFLICT = 5;
+class CliError extends Error {
+    code;
+    constructor(message, code = exports.EXIT_FAIL) {
+        super(message);
+        this.code = code;
+    }
+}
+exports.CliError = CliError;
+/**
+ * The vault could not be reached at all: DNS, the connection, or the TLS
+ * handshake, rather than anything the vault said. It is an ordinary failure to
+ * anything that just reports it, but a polling command wants to tell it apart,
+ * because one dropped request in the middle of a watch is not a reason to
+ * abandon a run that is still going.
+ */
+class UnreachableError extends CliError {
+    constructor(message) {
+        super(message, exports.EXIT_FAIL);
+    }
+}
+exports.UnreachableError = UnreachableError;
+/**
+ * The exit code an HTTP status from the vault maps to. 403 is deliberately a
+ * generic failure rather than 3: the token was accepted and is simply not
+ * allowed to do this, which is not something a caller fixes by logging in
+ * again.
+ */
+function exitCodeForStatus(status) {
+    if (status === 401)
+        return exports.EXIT_AUTH;
+    if (status === 404)
+        return exports.EXIT_NOTFOUND;
+    if (status === 409)
+        return exports.EXIT_CONFLICT;
+    return exports.EXIT_FAIL;
+}
+// Whether this run asked for JSON. Set by the parser, because a failure can
+// happen before the command reaches its own output code, and a caller that
+// passed --json expects {"error": "..."} either way.
+let jsonRequested = false;
+function setJsonErrors(on) {
+    jsonRequested = on;
+}
+function jsonErrorsWanted() {
+    return jsonRequested;
+}

package/dist/cli/input.js

@@ -0,0 +1,64 @@
+"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.readStdin = readStdin;
+exports.readFileArg = readFileArg;
+const fs = __importStar(require("fs"));
+const exit_1 = require("./exit");
+// Reading input that is too long, too secret, or too awkward to be an argument.
+// A token in argv is in the process table and in shell history; an issue body
+// in argv is subject to whatever the shell does to it and to ARG_MAX. Both are
+// read from a file or from stdin instead.
+/** Everything on stdin, as text. */
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on('data', (c) => chunks.push(c));
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        process.stdin.on('error', reject);
+        process.stdin.resume();
+    });
+}
+/** A file's contents, or stdin when the path is '-'. */
+async function readFileArg(file) {
+    if (file === '-')
+        return await readStdin();
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        throw new exit_1.CliError(`Could not read ${file}: ${e instanceof Error ? e.message : String(e)}`, exit_1.EXIT_USAGE);
+    }
+}

package/dist/cli/issue-cmd.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.issueCommands = void 0;
+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");
+// The issue commands, named as gh names them, because that is the point: someone
+// who knows gh should guess right.
+const COMMON = [repo_1.REPO_OPTION, ...target_1.TARGET_OPTIONS];
+const BODY_OPTIONS = [
+    { name: 'body', type: 'string', value: '<b>', summary: 'Body text' },
+    { name: 'body-file', type: 'string', value: '<f>', summary: "Read the body from a file, or '-' for stdin" },
+];
+/**
+ * The body a command was given. An issue body is frequently longer than a shell
+ * argument should be, so --body-file exists alongside --body, and asking for
+ * both is a mistake rather than a precedence question.
+ */
+async function bodyOf(inv, required = false) {
+    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);
+    if (file !== null)
+        return await (0, input_1.readFileArg)(file);
+    if (inline !== null)
+        return inline;
+    if (required)
+        throw new exit_1.CliError('A body is required: pass --body <text> or --body-file <path>.', exit_1.EXIT_USAGE);
+    return undefined;
+}
+function issueRef(inv) {
+    const raw = inv.args[0] ?? '';
+    if (!/^[1-9][0-9]*$/.test(raw))
+        throw new exit_1.CliError(`'${raw}' is not an issue number`, exit_1.EXIT_USAGE);
+    return parseInt(raw, 10);
+}
+exports.issueCommands = [
+    {
+        path: ['issue', 'list'],
+        summary: 'List issues',
+        options: [
+            { name: 'state', type: 'string', value: '<s>', summary: 'open (default), closed, or all' },
+            { name: 'label', type: 'string', value: '<l>', summary: 'Only issues carrying this label' },
+            { name: 'author', type: 'string', value: '<a>', summary: 'Only issues opened by this user' },
+            { name: 'search', type: 'string', value: '<q>', summary: 'Only issues matching this text' },
+            { name: 'sort', type: 'string', value: '<s>', summary: 'newest, oldest, updated, or comments' },
+            { 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 ref = await (0, repo_1.resolveRepo)(inv, target);
+            const query = new URLSearchParams();
+            for (const [flag, key] of [
+                ['state', 'state'],
+                ['label', 'label'],
+                ['author', 'author'],
+                ['sort', 'sort'],
+                ['search', 'q'],
+            ]) {
+                const v = inv.str(flag);
+                if (v !== null)
+                    query.set(key, v);
+            }
+            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)(ref)}/issues?${query.toString()}`);
+            const issues = (data.issues ?? []);
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)({ issues: (0, output_1.pickFields)(issues, json.fields) });
+                return;
+            }
+            if (issues.length === 0) {
+                console.log(`No issues in ${ref.collection}/${ref.repo}`);
+                return;
+            }
+            (0, output_1.printTable)(issues.map((i) => [
+                `#${i.number}`,
+                String(i.state),
+                String(i.title),
+                String(i.author),
+                (0, output_1.shortDate)(i.updated),
+                i.labels.join(','),
+            ]));
+        },
+    },
+    {
+        path: ['issue', 'view'],
+        summary: 'Show one issue, with its comments',
+        args: [{ name: 'number', required: true }],
+        options: [
+            { name: 'comments', type: 'boolean', summary: 'Print the comments in full (implied by --json)' },
+            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)}/issues/${issueRef(inv)}`);
+            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.title}`);
+            console.log(`${data.state} - opened by ${data.author} on ${(0, output_1.shortDate)(data.created)}`);
+            if (data.labels.length)
+                console.log(`labels: ${data.labels.join(', ')}`);
+            console.log('');
+            console.log(String(data.body ?? '').trimEnd());
+            const comments = (data.commentList ?? []);
+            if (comments.length && inv.bool('comments')) {
+                for (const c of comments) {
+                    console.log('');
+                    console.log(`--- ${c.author} on ${(0, output_1.shortDate)(c.created)}`);
+                    console.log(String(c.body ?? '').trimEnd());
+                }
+            }
+            else if (comments.length) {
+                console.log('');
+                console.log(`(${comments.length} comment${comments.length === 1 ? '' : 's'}; --comments shows them)`);
+            }
+        },
+    },
+    {
+        path: ['issue', 'create'],
+        summary: 'Open an issue',
+        options: [
+            { name: 'title', type: 'string', value: '<t>', summary: 'Title' },
+            ...BODY_OPTIONS,
+            { name: 'label', type: 'string[]', value: '<l>', summary: 'Label to attach' },
+            output_1.JSON_OPTION,
+            ...COMMON,
+        ],
+        async run(inv) {
+            const title = inv.str('title');
+            if (title === null)
+                throw new exit_1.CliError('--title is required', exit_1.EXIT_USAGE);
+            const target = await (0, target_1.targetFrom)(inv);
+            const ref = await (0, repo_1.resolveRepo)(inv, target);
+            const labels = inv.list('label');
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(ref)}/issues`, {
+                title,
+                body: (await bodyOf(inv)) ?? '',
+                labels: labels.length ? labels : 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}/${ref.collection}/${ref.repo}/issues/${data.number}`);
+        },
+    },
+    {
+        path: ['issue', 'edit'],
+        summary: 'Change an issue title, body, or labels',
+        description: `--label replaces the whole set, which is what the API does; --add-label keeps what is
+there and adds to it, which means reading the issue first.`,
+        args: [{ name: 'number', required: true }],
+        options: [
+            { name: 'title', type: 'string', value: '<t>', summary: 'New title' },
+            ...BODY_OPTIONS,
+            { name: 'label', type: 'string[]', value: '<l>', summary: 'Replace the labels with these' },
+            { name: 'add-label', type: 'string[]', value: '<l>', summary: 'Keep the existing labels and add these' },
+            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 n = issueRef(inv);
+            const title = inv.str('title');
+            const body = await bodyOf(inv);
+            const set = inv.list('label');
+            const add = inv.list('add-label');
+            if (set.length && add.length)
+                throw new exit_1.CliError('Pass either --label or --add-label, not both.', exit_1.EXIT_USAGE);
+            let labels = set.length ? set : undefined;
+            if (add.length) {
+                const current = await (0, cli_api_1.api)(target, 'GET', `${(0, repo_1.repoPath)(ref)}/issues/${n}`);
+                labels = [...new Set([...(current.labels ?? []), ...add])];
+            }
+            if (title === null && body === undefined && labels === undefined) {
+                throw new exit_1.CliError('Nothing to change. Pass --title, --body, --body-file, --label, or --add-label.', exit_1.EXIT_USAGE);
+            }
+            const data = await (0, cli_api_1.api)(target, 'PATCH', `${(0, repo_1.repoPath)(ref)}/issues/${n}`, { title: title ?? undefined, body, labels });
+            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 #${n}`);
+        },
+    },
+    {
+        path: ['issue', 'comment'],
+        summary: 'Add a comment to an issue',
+        args: [{ name: 'number', required: true }],
+        options: [...BODY_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 n = issueRef(inv);
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(ref)}/issues/${n}/comments`, {
+                body: await bodyOf(inv, true),
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`Commented on #${n}`);
+        },
+    },
+    ...['close', 'reopen'].map((verb) => ({
+        path: ['issue', verb],
+        summary: verb === 'close' ? 'Close an issue' : 'Reopen a closed issue',
+        args: [{ name: 'number', required: true }],
+        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 n = issueRef(inv);
+            const data = await (0, cli_api_1.api)(target, 'POST', `${(0, repo_1.repoPath)(ref)}/issues/${n}/state`, {
+                state: verb === 'close' ? 'closed' : 'open',
+            });
+            const json = (0, output_1.jsonMode)(inv);
+            if (json.enabled) {
+                (0, output_1.printJson)((0, output_1.pickObject)(data, json.fields));
+                return;
+            }
+            console.log(`#${n} is now ${data.state}`);
+        },
+    })),
+];

package/dist/cli/output.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JSON_OPTION = void 0;
+exports.jsonMode = jsonMode;
+exports.printJson = printJson;
+exports.pickFields = pickFields;
+exports.pickObject = pickObject;
+exports.printTable = printTable;
+exports.shortDate = shortDate;
+const exit_1 = require("./exit");
+// The output contract, which a program depends on more than a person does:
+// --json puts a single JSON value on stdout and nothing else, and every
+// diagnostic goes to stderr, so `mochi issue list --json | jq` never has to
+// filter anything out.
+exports.JSON_OPTION = {
+    name: 'json',
+    type: 'string?',
+    value: '[<fields>]',
+    summary: 'JSON on stdout; --json=<a,b> or --json <a,b> keeps only those fields',
+};
+function jsonMode(inv) {
+    const v = inv.optional('json');
+    if (v === false)
+        return { enabled: false, fields: null };
+    if (v === true)
+        return { enabled: true, fields: null };
+    const fields = v
+        .split(',')
+        .map((f) => f.trim())
+        .filter((f) => f.length > 0);
+    return { enabled: true, fields: fields.length ? fields : null };
+}
+/** One JSON value on stdout, with a trailing newline and nothing else. */
+function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + '\n');
+}
+/**
+ * Keep only the requested keys. Unknown names are an error naming the valid
+ * ones, since silently returning nothing for a misspelled field is the kind of
+ * failure a caller does not notice until much later.
+ */
+function pickFields(rows, fields) {
+    if (!fields)
+        return rows;
+    const valid = new Set();
+    for (const row of rows)
+        for (const k of Object.keys(row))
+            valid.add(k);
+    // An empty result set has no keys to check against, so nothing can be
+    // rejected; the filter is then a no-op over no rows anyway.
+    if (valid.size > 0) {
+        const unknown = fields.filter((f) => !valid.has(f));
+        if (unknown.length) {
+            throw new exit_1.CliError(`unknown field${unknown.length > 1 ? 's' : ''} ${unknown.join(', ')}. Valid: ${[...valid].sort().join(', ')}`, exit_1.EXIT_USAGE);
+        }
+    }
+    return rows.map((row) => {
+        const out = {};
+        for (const f of fields)
+            if (f in row)
+                out[f] = row[f];
+        return out;
+    });
+}
+/** The same, for a single object rather than a list. */
+function pickObject(row, fields) {
+    return pickFields([row], fields)[0];
+}
+/**
+ * A plain table for a human reader: columns padded to the widest cell, two
+ * spaces between. Nothing here is for a program, which asks for --json instead,
+ * so there is no colour, no box drawing, and no terminal width detection.
+ */
+function printTable(rows) {
+    if (rows.length === 0)
+        return;
+    const cells = rows.map((r) => r.map((c) => String(c)));
+    const widths = [];
+    for (const row of cells) {
+        row.forEach((c, i) => {
+            widths[i] = Math.max(widths[i] ?? 0, c.length);
+        });
+    }
+    for (const row of cells) {
+        // The last column is not padded, so a table does not carry trailing spaces.
+        const line = row.map((c, i) => (i === row.length - 1 ? c : c.padEnd(widths[i]))).join('  ');
+        process.stdout.write(line.replace(/\s+$/, '') + '\n');
+    }
+}
+/** An ISO timestamp as a date, which is what a table column has room for. */
+function shortDate(iso) {
+    return typeof iso === 'string' && iso.length >= 10 ? iso.slice(0, 10) : '';
+}