@knowttl/gitea-axi 0.0.0-stage → 0.1.1

package/dist/writes.js

@@ -0,0 +1,547 @@
+import { createHash, createHmac, randomBytes, randomUUID } from 'node:crypto';
+import { constants, existsSync } from 'node:fs';
+import { mkdir, open, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { canonicalPath, collect, effectFor, object, read, validate, validatePayload } from './api.js';
+import { CliError } from './error.js';
+import { readPrivateFile, writePrivateFile } from './private-file.js';
+import { verifyPull } from './pulls.js';
+import { verifyWorkflow } from './repo-workflows.js';
+import { actionValues, valuePlan, verifyValue } from './action-values.js';
+import { verifyUploads } from './attachments.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => JSON.stringify(key) + ':' + canonical(item)).join(',') + '}';
+    return JSON.stringify(value) ?? 'null';
+}
+const digest = (value) => createHash('sha256').update(canonical(value)).digest('hex');
+const usage = (message) => { throw new CliError('USAGE', message, 2); };
+const logPath = () => process.env.GITEA_AXI_WRITE_LOG ?? join(process.platform === 'win32' ? process.env.LOCALAPPDATA ?? homedir() : process.env.XDG_STATE_HOME ?? join(homedir(), '.local/state'), 'gitea-axi', 'writes.log');
+const directory = () => join(dirname(logPath()), 'write-receipts');
+const command = (id, options) => 'gitea-axi write reconcile ' + id +
+    (options.config ? ' --config ' + shell(String(options.config)) : '') + (options.profile ? ' --profile ' + shell(String(options.profile)) : '') +
+    (options.origin ? ' --origin ' + shell(String(options.origin)) : '') + (options['allow-insecure-http'] ? ' --allow-insecure-http' : '');
+function shell(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
+async function key(root) {
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const path = join(root, 'key');
+    try {
+        const file = await open(path, 'wx', 0o600);
+        try {
+            await file.writeFile(randomBytes(32).toString('hex'));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (!(error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+    return readPrivateFile(path, true);
+}
+export async function reconcile(client, id) {
+    if (!/^[a-f0-9-]{36}$/.test(id))
+        usage('Select the exact confirmation ID');
+    const receipt = JSON.parse(await readPrivateFile(join(directory(), id + '.json'), true));
+    if (receipt.origin !== client.origin)
+        throw new CliError('CONFIRMATION_MISMATCH', 'Reconciliation origin differs from the attempted write');
+    const observations = await observe(client, receipt.reads);
+    return { confirmation: id, operations: receipt.operations, states: receipt.states, observations,
+        help: 'Inspect the exact identity and requested fields in these reads before authorizing any new attempt' };
+}
+async function observe(client, paths) {
+    const observations = [];
+    for (const path of paths) {
+        if (/\/actions\/(?:secrets|variables)$/.test(path)) {
+            observations.push({ path, data: await actionValues(client, path) });
+            continue;
+        }
+        const data = await read(client, path);
+        if (Array.isArray(data)) {
+            const page = await collect(client, path);
+            if (page.truncated)
+                throw new CliError('INCOMPLETE_READ', 'Reconciliation requires a complete collection');
+            observations.push({ path, data: page.items });
+        }
+        else
+            observations.push({ path, data });
+    }
+    return observations;
+}
+function verifyNamed(plan, results, observations) {
+    const mismatch = () => { throw new CliError('READBACK_MISMATCH', 'Verification did not confirm the requested fields'); };
+    const collection = (path) => {
+        const data = observations.find(row => row.path.split('?')[0] === path)?.data;
+        if (!Array.isArray(data))
+            return mismatch();
+        return data.map(object);
+    };
+    const before = object(plan.preconditions);
+    const issueFields = (issue) => ({
+        title: issue.title, body: issue.body ?? '', state: issue.state,
+        assignees: (issue.assignees ?? []).map(row => object(row).login).sort(),
+        labels: (issue.labels ?? []).map(row => object(row).id).sort(),
+        milestone: issue.milestone == null ? null : object(issue.milestone).id,
+    });
+    const expectedIssues = new Map();
+    for (const [path, value] of Object.entries(before)) {
+        if (/\/issues\/\d+$/.test(path) && !plan.steps.some(step => step.path === path && step.method === 'DELETE')) {
+            const issue = object(value);
+            expectedIssues.set(path, { id: issue.id, number: issue.number, ...issueFields(issue) });
+        }
+    }
+    for (const [index, step] of plan.steps.entries()) {
+        if (/\/issues$/.test(step.path) && step.method === 'POST') {
+            const result = object(results[index]);
+            const actual = collection(step.path).find(row => row.id === result.id && row.number === result.number);
+            if (!actual || before[step.path + '?state=all&type=issues'].some(row => row.id === result.id || row.number === result.number))
+                mismatch();
+            const expected = { title: '', body: '', state: 'open', assignees: [], labels: [], milestone: null, ...object(step.payload) };
+            expected.assignees = [...expected.assignees].sort();
+            expected.labels = [...expected.labels].sort();
+            if (canonical(issueFields(actual)) !== canonical(expected))
+                mismatch();
+        }
+        const expected = expectedIssues.get(step.path);
+        if (expected && step.method === 'PATCH')
+            Object.assign(expected, object(step.payload));
+        const membership = /^(.*\/issues\/\d+)\/labels(?:\/(\d+))?$/.exec(step.path);
+        if (membership) {
+            const issue = expectedIssues.get(membership[1]);
+            const ids = new Set(issue.labels);
+            if (step.method === 'POST')
+                for (const id of object(step.payload).labels)
+                    ids.add(id);
+            else
+                for (const id of ids)
+                    if (String(id) === membership[2])
+                        ids.delete(id);
+            issue.labels = [...ids];
+        }
+    }
+    for (const [path, expected] of expectedIssues) {
+        const actual = object(observations.find(row => row.path === path)?.data);
+        const { id, number, ...fields } = expected;
+        fields.assignees = [...fields.assignees].sort();
+        fields.labels = [...fields.labels].sort();
+        if (actual.id !== id || actual.number !== number || canonical(issueFields(actual)) !== canonical(fields))
+            mismatch();
+    }
+    for (const [index, step] of plan.steps.entries()) {
+        if (step.upload)
+            continue;
+        const pin = /^(.*\/issues)\/(\d+)\/pin$/.exec(step.path);
+        if (pin) {
+            const pins = collection(pin[1] + '/pinned');
+            const expected = new Set(object(plan.preconditions)[pin[1] + '/pinned'].map(row => String(row.number)));
+            if (step.method === 'POST')
+                expected.add(pin[2]);
+            else
+                expected.delete(pin[2]);
+            if (canonical(pins.map(row => String(row.number)).sort()) !== canonical([...expected].sort()))
+                mismatch();
+            continue;
+        }
+        const membership = /^(.*\/issues\/\d+)\/labels(?:\/(\d+))?$/.exec(step.path);
+        if (membership)
+            continue;
+        const deletion = /^(.*\/(?:issues|labels))\/(\d+)$/.exec(step.path);
+        if (step.method === 'DELETE' && deletion) {
+            const field = deletion[1].endsWith('/issues') ? 'number' : 'id';
+            const actual = collection(deletion[1]);
+            const previous = Object.entries(before).find(([path]) => path.split('?')[0] === deletion[1])?.[1];
+            const remaining = previous.filter(row => String(row[field]) !== deletion[2]);
+            if (actual.some(row => String(row[field]) === deletion[2]) || actual.length !== remaining.length ||
+                remaining.some(row => canonical(actual.find(item => item.id === row.id)) !== canonical(row)))
+                mismatch();
+            continue;
+        }
+        if (/\/issues(?:\/\d+)?$/.test(step.path))
+            continue;
+        const result = object(results[index]);
+        const listPath = step.method === 'POST' ? step.path : step.path.replace(/\/\d+$/, '');
+        const id = step.method === 'PATCH' ? before[listPath].find(row => String(row.id) === step.path.split('/').at(-1)).id : result.id;
+        const actual = collection(listPath).find(row => row.id === id);
+        if (!actual || actual.id !== id) {
+            mismatch();
+            continue;
+        }
+        for (const [field, value] of Object.entries(object(step.payload))) {
+            if (canonical(actual[field]) !== canonical(value))
+                mismatch();
+        }
+    }
+}
+export async function write(client, identity, plan, options, executeLocal) {
+    if (process.env.GITEA_AXI_READ_ONLY !== undefined && process.env.GITEA_AXI_READ_ONLY !== 'false')
+        throw new CliError('READ_ONLY', 'Host or native read-only policy refuses writes');
+    if (Boolean(options.preview) === Boolean(options.confirm))
+        usage('Choose exactly --preview or --confirm <confirmation>');
+    const localOperation = (step) => {
+        if (!executeLocal || !/^gitea\.local\.(?:clone|checkout|revert|composite|stack\.(?:init|add|checkout|push|submit|sync|rebase|continue|abort|link|unstack|merge))$/.test(step.local ?? '')) {
+            throw new CliError('READ_ONLY', 'Unclassified local effect');
+        }
+        if (process.env.GITEA_AXI_HOST_WRITE_OPERATIONS !== undefined || process.env.GITEA_AXI_CREDENTIAL_REVISION !== undefined) {
+            throw new CliError('READ_ONLY', 'Workspace effects are standalone only');
+        }
+        return { operation: step.local };
+    };
+    const routes = plan.steps.map(step => step.local ? localOperation(step) : validatePayload(step.method, step.path, step.payload));
+    const operations = routes.map(route => route.operation);
+    const allowed = String(options['allow-write'] ?? '').split(',');
+    const hosted = process.env.GITEA_AXI_HOST_WRITE_OPERATIONS;
+    for (const operation of operations) {
+        if (!allowed.includes(operation) || (hosted !== undefined && !hosted.split(',').includes(operation)) ||
+            (identity.writes && (!identity.writes.allowWrites || !identity.writes.operations.includes(operation)))) {
+            throw new CliError('READ_ONLY', 'Write policy must explicitly allow ' + operation);
+        }
+    }
+    if (!isAbsolute(logPath()))
+        usage('GITEA_AXI_WRITE_LOG must be absolute');
+    const root = directory();
+    const secret = await key(root);
+    const recoveries = [];
+    for (const previous of plan.recoverLocal ?? []) {
+        if (!/^[a-f0-9-]{36}$/.test(previous) || !plan.steps.every(step => /^gitea\.local\.stack\.(?:continue|abort|sync)$/.test(step.local ?? ''))) {
+            throw new CliError('READ_ONLY', 'Only a verified stack rebase recovery can resolve local attempts');
+        }
+        const receipt = JSON.parse(await readPrivateFile(join(root, previous + '.json'), true));
+        if (receipt.origin !== client.origin || receipt.localTarget !== plan.target ||
+            !receipt.operations.every(operation => /^gitea\.local\.stack\.(?:rebase|continue|abort|push|sync)$/.test(operation)) ||
+            !receipt.localGuards?.every(guard => /^[a-f0-9]{64}$/.test(guard)))
+            throw new CliError('READ_ONLY', 'Recovery receipt is not a workspace-bound local rebase');
+        recoveries.push({ id: previous, receipt });
+    }
+    const binding = createHmac('sha256', secret).update(canonical({ identity, revision: process.env.GITEA_AXI_CREDENTIAL_REVISION, origin: client.origin, plan })).digest('hex');
+    // Exclude credential revision and preconditions from the attempt key so rotating a credential
+    // or changing the remote record cannot bypass an unresolved dispatched effect.
+    const effectStep = (step) => {
+        if (step.local)
+            return { method: step.method, path: step.path, payload: step.payload, local: localOperation(step).operation };
+        const route = validatePayload(step.method, step.path, step.payload);
+        const segments = canonicalPath(step.path).split('/');
+        if (/\{(?:template_)?repo\}/.test(route.path)) {
+            for (const [index, segment] of route.path.split('/').entries()) {
+                if (/^\{(?:owner|repo|org|template_owner|template_repo)\}$/.test(segment)) {
+                    segments[index] = encodeURIComponent(decodeURIComponent(segments[index]).toLowerCase());
+                }
+            }
+        }
+        return { method: step.method, path: segments.join('/'), ...(step.payload === undefined ? {} : { payload: step.payload }), ...(step.upload ? { upload: step.upload } : {}) };
+    };
+    const effectSteps = plan.steps.map(effectStep);
+    const effectDigest = (value) => plan.sensitive ? createHmac('sha256', secret).update(canonical(value)).digest('hex') : digest(value);
+    const attempt = effectDigest({ origin: client.origin, steps: effectSteps });
+    const guards = [...new Set(effectSteps.filter((_, index) => !plan.steps[index].createdPull).map(step => join(root, effectDigest({ origin: client.origin, step }) + '.attempt')))];
+    for (const guard of guards) {
+        if (existsSync(guard)) {
+            const previous = await readPrivateFile(guard, true);
+            throw new CliError('WRITE_OUTCOME_UNKNOWN', 'An attempt already exists; reconcile with ' + command(previous, options));
+        }
+    }
+    if (options.preview) {
+        const id = randomUUID();
+        const receipt = { binding, origin: client.origin, reads: plan.reads, states: plan.steps.map(() => 'pending'), operations, attempt,
+            ...(plan.steps.every(step => step.local) ? { localTarget: plan.target, localGuards: guards.map(path => path.slice(root.length + 1, -8)) } : {}) };
+        await writePrivateFile(join(root, id + '.json'), JSON.stringify(receipt));
+        return { confirmation: id, origin: client.origin, target: plan.target, operations, steps: plan.steps.map(({ upload, ...step }) => ({ ...step, ...(plan.sensitive && step.payload !== undefined ? { payload: '[REDACTED]' } : {}), ...(upload ? { upload: { name: upload.name, type: upload.type, size: upload.size, sha256: upload.sha256 } } : {}) })), preconditions: plan.preconditions,
+            ...(plan.notes ? { notes: plan.notes } : {}), help: 'Repeat the same command with --confirm ' + id + ' instead of --preview' };
+    }
+    const id = String(options.confirm);
+    if (!/^[a-f0-9-]{36}$/.test(id))
+        usage('Use the confirmation ID returned by --preview');
+    const path = join(root, id + '.json');
+    const receipt = JSON.parse(await readPrivateFile(path, true));
+    if (receipt.states.some(state => state !== 'pending'))
+        throw new CliError('WRITE_OUTCOME_UNKNOWN', 'Confirmation was already dispatched; reconcile with ' + command(id, options));
+    if (receipt.binding !== binding)
+        throw new CliError('CONFIRMATION_MISMATCH', 'Credential revision, origin, target, operation, payload or preconditions changed; preview again');
+    const reserved = [];
+    const reserve = async (guard) => {
+        const file = await open(guard, 'wx', 0o600);
+        reserved.push(guard);
+        try {
+            await file.writeFile(id);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    };
+    for (const guard of guards) {
+        try {
+            await reserve(guard);
+        }
+        catch (error) {
+            await Promise.all(reserved.map(path => rm(path)));
+            if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
+                throw new CliError('WRITE_OUTCOME_UNKNOWN', 'Concurrent attempt refused; reconcile with ' + command(await readPrivateFile(guard, true), options));
+            }
+            throw error;
+        }
+    }
+    const results = [];
+    const outcome = () => 'steps=' + receipt.states.join(',') + (receipt.createdPull ? '; created PR id=' + receipt.createdPull.id + ' number=' + receipt.createdPull.number : '') + (receipt.createdParent ? '; existing parent id=' + receipt.createdParent.id + (receipt.createdParent.number ? ' number=' + receipt.createdParent.number : '') : '') + '; reconcile with ' + command(id, options);
+    for (const [index, step] of plan.steps.entries()) {
+        try {
+            let dispatched = step;
+            if (step.assetParent !== undefined) {
+                const parent = object(results[step.assetParent]);
+                const field = /\/issues\/0\/assets$/.test(step.path) ? 'number' : 'id';
+                if (!Number.isSafeInteger(parent[field]) || Number(parent[field]) <= 0)
+                    throw new CliError('INVALID_RESPONSE', 'Parent creation returned no usable identity');
+                dispatched = { ...step, path: step.path.replace('/0/assets', '/' + parent[field] + '/assets') };
+                if (validatePayload(dispatched.method, dispatched.path, dispatched.payload).operation !== operations[index])
+                    throw new CliError('READ_ONLY', 'Resolved attachment operation differs from the approved plan');
+                if (!receipt.reads.includes(dispatched.path))
+                    receipt.reads.push(dispatched.path);
+                plan.assets.path = dispatched.path;
+                const guard = join(root, effectDigest({ origin: client.origin, step: effectStep(dispatched) }) + '.attempt');
+                if (!guards.includes(guard)) {
+                    await reserve(guard);
+                    guards.push(guard);
+                }
+            }
+            if (step.createdPull) {
+                if (plan.pull?.action !== 'create' || index !== 1 || step.method !== 'POST' || step.path !== plan.target + '/0/requested_reviewers' || !receipt.createdPull)
+                    throw new CliError('INVALID_RESPONSE', 'Cannot resolve the created PR for reviewer changes');
+                dispatched = { method: step.method, path: plan.target + '/' + receipt.createdPull.number + '/requested_reviewers', payload: step.payload };
+                if (validatePayload(dispatched.method, dispatched.path, dispatched.payload).operation !== operations[index])
+                    throw new CliError('READ_ONLY', 'Resolved operation differs from the approved plan');
+                const guard = join(root, digest({ origin: client.origin, step: effectStep(dispatched) }) + '.attempt');
+                if (!guards.includes(guard)) {
+                    await reserve(guard);
+                    guards.push(guard);
+                }
+            }
+            receipt.states[index] = 'dispatched';
+            await writePrivateFile(path, JSON.stringify(receipt));
+            const journal = await open(logPath(), constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            try {
+                const stat = await journal.stat();
+                if (!stat.isFile() || stat.uid !== process.getuid() || (stat.mode & 0o077) !== 0)
+                    throw new CliError('CONFIG_INSECURE', 'Write journal must be an owned private file');
+                await journal.writeFile(JSON.stringify({ confirmation: id, operation: operations[index], attempt, step: index, state: 'dispatched' }) + '\n');
+                await journal.sync();
+            }
+            finally {
+                await journal.close();
+            }
+            const result = dispatched.local ? await executeLocal(dispatched, results, id) :
+                (await client.request(dispatched.path, false, { ...dispatched, ...(plan.sensitive ? { sensitive: true } : {}) })).data;
+            results.push(result);
+            if (plan.steps.some(step => step.assetParent === index)) {
+                const parent = object(result);
+                if (!Number.isSafeInteger(parent.id) || Number(parent.id) <= 0)
+                    throw new CliError('INVALID_RESPONSE', 'Parent creation returned no identity');
+                receipt.createdParent = { id: Number(parent.id), ...(typeof parent.number === 'number' ? { number: parent.number } : {}) };
+            }
+            if (index === 0 && plan.steps.some(step => step.createdPull)) {
+                const created = object(result);
+                if (!Number.isSafeInteger(created.id) || Number(created.id) <= 0 || !Number.isSafeInteger(created.number) || Number(created.number) <= 0)
+                    throw new CliError('INVALID_RESPONSE', 'Creation did not return a PR identity');
+                validate(plan.target + '/' + created.number, created);
+                if (object(plan.preconditions)[plan.target + '?state=all'].some(row => row.id === created.id || row.number === created.number) ||
+                    object(created.head).ref !== plan.pull.expected.head || object(created.base).ref !== plan.pull.expected.base)
+                    throw new CliError('INVALID_RESPONSE', 'Creation did not return the intended new PR');
+                receipt.createdPull = { id: Number(created.id), number: Number(created.number) };
+                receipt.reads = [...receipt.reads, plan.target + '/' + created.number];
+            }
+            receipt.states[index] = 'completed';
+            await writePrivateFile(path, JSON.stringify(receipt));
+        }
+        catch (error) {
+            if (step.local && index === 0 && error instanceof CliError && ['STACK_LOCKED', 'CONFIRMATION_MISMATCH'].includes(error.code)) {
+                receipt.states[index] = 'refused';
+                await writePrivateFile(path, JSON.stringify(receipt));
+                await Promise.all(guards.map(path => rm(path)));
+                throw error;
+            }
+            if (step.local && error instanceof CliError)
+                throw new CliError(error.code, error.message + '; ' + outcome());
+            throw new CliError('WRITE_OUTCOME_UNKNOWN', 'Write may have applied; ' + outcome());
+        }
+    }
+    let observations;
+    try {
+        observations = await observe(client, receipt.reads);
+        if (plan.pull)
+            await verifyPull(client, plan, results, observations);
+        if (plan.named)
+            verifyNamed(plan, results, observations);
+        if (plan.workflow)
+            await verifyWorkflow(client, plan, results, observations);
+        if (plan.value)
+            verifyValue(plan, observations);
+        if (plan.assets)
+            verifyUploads(plan, results, observations);
+    }
+    catch {
+        throw new CliError('WRITE_OUTCOME_UNKNOWN', 'Write dispatched but verification failed; ' + outcome());
+    }
+    await Promise.all(guards.map(path => rm(path)));
+    for (const { id: previous, receipt: recovered } of recoveries) {
+        for (const name of recovered.localGuards) {
+            const guard = join(root, name + '.attempt');
+            if (existsSync(guard) && await readPrivateFile(guard, true) === previous)
+                await rm(guard);
+        }
+        recovered.states = recovered.states.map(state => state === 'completed' ? state : 'recovered');
+        await writePrivateFile(join(root, previous + '.json'), JSON.stringify(recovered));
+    }
+    return { confirmation: id, states: receipt.states, results, observations, ...(plan.notes ? { notes: plan.notes } : {}), reconcile: command(id, options) };
+}
+export async function rawWritePlan(client, method, path, payload) {
+    const route = validatePayload(method, path, payload);
+    if (/\/actions\/secrets\//.test(path)) {
+        const base = path.slice(0, path.lastIndexOf('/'));
+        return valuePlan(client, base, decodeURIComponent(path.slice(path.lastIndexOf('/') + 1)), method === 'DELETE' ? 'delete' : 'set', method === 'PUT' ? String(object(payload).data) : undefined);
+    }
+    let verification = path.split('?')[0];
+    if (method === 'DELETE' || route.operation === 'repoMergePullRequest')
+        verification = verification.slice(0, verification.lastIndexOf('/'));
+    while (!effectFor('GET', verification) || effectFor('GET', verification)?.effect !== 'read') {
+        verification = verification.slice(0, verification.lastIndexOf('/'));
+        if (!verification.startsWith('/api/v1/'))
+            usage('No metadata reconciliation read is available for this route');
+    }
+    if (verification.endsWith('/issues'))
+        verification += '?state=all&type=issues';
+    const preconditions = await observe(client, [verification]);
+    return { target: path, steps: [{ method, path, ...(payload === undefined ? {} : { payload }) }], reads: [verification], preconditions };
+}
+const names = (value) => [...new Set(Array.isArray(value) ? value.map(String) : [String(value)])];
+export async function issueLabelPlan(client, operation, base, number, options) {
+    const [kind, action] = operation.split(' ');
+    const steps = [];
+    const reads = new Set();
+    const preconditions = {};
+    const snapshot = async (path) => {
+        const data = await read(client, path);
+        preconditions[path] = data;
+        reads.add(path);
+        return data;
+    };
+    const fullList = async (path) => {
+        const page = await collect(client, path);
+        if (page.truncated)
+            throw new CliError('INCOMPLETE_READ', 'A complete collection is required before writing');
+        preconditions[path] = page.items;
+        reads.add(path);
+        return page.items;
+    };
+    const add = (method, path, payload) => steps.push({ method, path, ...(payload === undefined ? {} : { payload }) });
+    if (kind === 'label') {
+        const labels = await fullList(base + '/labels');
+        const selected = action === 'create' ? undefined : labels.find(label => label.name === number || String(label.id) === number);
+        if (action !== 'create' && !selected)
+            usage('Select an existing exact label name or ID');
+        if (action === 'delete' && labels.length < 2)
+            usage('Deletion requires a remaining control label');
+        const path = base + '/labels' + (selected ? '/' + selected.id : '');
+        const payload = {};
+        if (options.name !== undefined)
+            payload.name = options.name;
+        if (action === 'create' && !payload.name)
+            usage('--name is required');
+        if (options.description !== undefined)
+            payload.description = options.description;
+        if (options.color !== undefined) {
+            const color = String(options.color).replace(/^#/, '').toLowerCase();
+            if (!/^[a-f0-9]{6}$/.test(color))
+                usage('--color requires six hexadecimal digits');
+            payload.color = color;
+        }
+        if (action === 'create' && !payload.color)
+            usage('--color is required');
+        if (action === 'edit' && !Object.keys(payload).length)
+            usage('Choose a label field to edit');
+        add(action === 'delete' ? 'DELETE' : action === 'create' ? 'POST' : 'PATCH', path, action === 'delete' ? undefined : payload);
+    }
+    else {
+        const path = base + '/issues' + (number ? '/' + number : '');
+        if (number)
+            await snapshot(path);
+        else
+            await fullList(base + '/issues?state=all&type=issues');
+        if (action === 'create' || action === 'edit') {
+            const payload = {};
+            for (const field of ['title', 'body'])
+                if (options[field] !== undefined)
+                    payload[field] = options[field];
+            if (action === 'create' && !payload.title)
+                usage('--title is required');
+            if (options.assignee !== undefined)
+                payload.assignees = names(options.assignee);
+            if (options['add-assignee'] !== undefined || options['remove-assignee'] !== undefined) {
+                const assignees = new Set((object(preconditions[path]).assignees ?? []).map(value => String(object(value).login)));
+                if (options['add-assignee'] !== undefined)
+                    for (const name of names(options['add-assignee']))
+                        assignees.add(name);
+                if (options['remove-assignee'] !== undefined)
+                    for (const name of names(options['remove-assignee']))
+                        assignees.delete(name);
+                payload.assignees = [...assignees];
+            }
+            if (options.milestone !== undefined) {
+                const milestones = await fullList(base + '/milestones?state=all');
+                const milestone = milestones.find(row => row.title === options.milestone);
+                if (!milestone)
+                    return usage('Unknown exact milestone title');
+                payload.milestone = milestone.id;
+            }
+            const labelIds = async (value) => {
+                const labels = await fullList(base + '/labels');
+                return names(value).map(name => {
+                    const label = labels.find(row => row.name === name);
+                    if (!label)
+                        return usage('Unknown exact label name: ' + name);
+                    return label.id;
+                });
+            };
+            if (options.label !== undefined)
+                payload.labels = await labelIds(options.label);
+            if (options['add-label'] !== undefined)
+                add('POST', path + '/labels', { labels: await labelIds(options['add-label']) });
+            if (options['remove-label'] !== undefined) {
+                await snapshot(path + '/labels');
+                for (const id of await labelIds(options['remove-label']))
+                    add('DELETE', path + '/labels/' + id);
+            }
+            if (Object.keys(payload).length)
+                steps.unshift({ method: action === 'create' ? 'POST' : 'PATCH', path, payload });
+            if (!steps.length && !options.attach)
+                usage('Choose an issue field to edit');
+        }
+        else if (action === 'close' || action === 'reopen') {
+            add('PATCH', path, { state: action === 'close' ? 'closed' : 'open' });
+            if (options.comment !== undefined) {
+                await snapshot(path + '/comments');
+                add('POST', path + '/comments', { body: options.comment });
+            }
+        }
+        else if (action === 'comment') {
+            if (!options.body)
+                usage('--body is required');
+            await snapshot(path + '/comments');
+            add('POST', path + '/comments', { body: options.body });
+        }
+        else if (action === 'delete') {
+            const issues = await fullList(base + '/issues?state=all&type=issues');
+            if (!issues.some(issue => String(issue.number) !== number))
+                usage('Deletion requires a remaining control issue');
+            add('DELETE', path);
+            reads.delete(path);
+        }
+        else {
+            await fullList(base + '/issues/pinned');
+            add(action === 'pin' ? 'POST' : 'DELETE', path + '/pin');
+        }
+    }
+    return { target: base + '/' + kind + (number ? '/' + number : ''), steps, reads: [...reads], preconditions, named: true };
+}