@knowttl/gitea-axi 0.1.0 → 0.1.2

package/dist/pulls.js

@@ -0,0 +1,299 @@
+import { collect, object, read } from './api.js';
+import { CliError } from './error.js';
+const usage = (message) => { throw new CliError('USAGE', message, 2); };
+const gap = (message) => { throw new CliError('CAPABILITY_GAP', message); };
+const names = (value) => value === undefined ? [] : [...new Set((Array.isArray(value) ? value : [value]).map(String))];
+const sorted = (values) => [...values].sort();
+const equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const delta = (previous, add, remove) => [...new Set([...previous.map(String), ...names(add)])].filter(value => !names(remove).includes(value));
+const members = (pull, field, key) => (pull[field] ?? []).map(row => object(row)[key]);
+export function validatePull(operation, options) {
+    if (operation === 'pr review') {
+        if (['approve', 'request-changes', 'comment'].filter(key => options[key]).length !== 1)
+            usage('Choose exactly one of --approve, --request-changes or --comment');
+        gap('C043 unresolved: review wire events and atomic stale-head refusal lack vendor evidence; no review will be posted, including with --match-head-commit');
+    }
+    if (operation === 'pr merge') {
+        const styles = ['merge', 'squash', 'rebase'].filter(key => options[key]);
+        if (styles.length + Number(options.method !== undefined) !== 1)
+            usage('Choose exactly one of --method, --merge, --squash or --rebase');
+        if (!['merge', 'squash', 'rebase'].includes(String(options.method ?? styles[0])))
+            usage('Supported merge methods: merge, squash, rebase');
+        if (!/^[a-f0-9]{40}$/.test(String(options['match-head-commit'] ?? '')))
+            usage('--match-head-commit requires the full 40-character head SHA');
+    }
+}
+function fields(pull) {
+    return { title: pull.title, body: pull.body ?? '', state: pull.state, head: object(pull.head).ref, base: object(pull.base).ref,
+        assignees: sorted(members(pull, 'assignees', 'login')), labels: sorted(members(pull, 'labels', 'id')),
+        milestone: pull.milestone == null ? null : object(pull.milestone).id,
+        reviewers: sorted(members(pull, 'requested_reviewers', 'login')), teams: sorted(members(pull, 'requested_reviewers_teams', 'name')) };
+}
+export async function pullPlan(client, operation, base, number, options) {
+    const action = operation.split(' ')[1];
+    const path = base + '/pulls' + (number ? '/' + number : '');
+    const steps = [];
+    const preconditions = {};
+    const reads = new Set();
+    const snapshot = async (path, list = false) => {
+        let value;
+        if (list) {
+            const page = await collect(client, path);
+            if (page.truncated)
+                throw new CliError('INCOMPLETE_READ', 'A complete collection is required before writing');
+            value = page.items;
+        }
+        else
+            value = await read(client, path);
+        preconditions[path] = value;
+        reads.add(path);
+        return value;
+    };
+    const add = (method, path, payload) => steps.push({ method, path, ...(payload === undefined ? {} : { payload }) });
+    const before = action === 'create' ? undefined : object(await snapshot(path));
+    const expected = before ? { id: before.id, number: before.number, ...fields(before), merged: before.merged ?? false, headSHA: object(before.head).sha } :
+        { title: '', body: '', state: 'open', merged: false, assignees: [], labels: [], milestone: null, reviewers: [], teams: [] };
+    if (action === 'create')
+        await snapshot(path + '?state=all', true);
+    if (action === 'create' || action === 'edit') {
+        for (const [flag, collection, key] of [['assignee', 'assignees', 'login'], ['team-reviewer', 'teams', 'name']]) {
+            const requested = action === 'create' ? names(options[flag]) : [...names(options['add-' + flag]), ...names(options['remove-' + flag])];
+            if (!requested.length)
+                continue;
+            const available = await snapshot(base + '/' + collection, true);
+            for (const name of requested) {
+                const selected = available.find(row => row[key] === name);
+                if (!selected)
+                    usage('Unknown exact ' + flag + ' name: ' + name);
+            }
+        }
+        const addedReviewers = names(action === 'create' ? options.reviewer : options['add-reviewer']);
+        const requestedReviewers = [...new Set([...addedReviewers, ...names(options['remove-reviewer'])])];
+        if (requestedReviewers.length) {
+            const author = object(action === 'create' ? await snapshot('/api/v1/user') : before.user);
+            for (const name of requestedReviewers) {
+                let reviewer;
+                try {
+                    reviewer = object(await snapshot('/api/v1/users/' + encodeURIComponent(name)));
+                }
+                catch (error) {
+                    if (error instanceof CliError && error.code === 'NOT_FOUND_OR_HIDDEN')
+                        usage('Unknown exact reviewer name: ' + name);
+                    throw error;
+                }
+                if (reviewer.login !== name)
+                    usage('Unknown exact reviewer name: ' + name);
+                if (addedReviewers.includes(name) && reviewer.id === author.id)
+                    usage('The PR author cannot be requested as a reviewer');
+            }
+        }
+        const payload = {};
+        for (const field of ['title', 'body', 'base'])
+            if (options[field] !== undefined)
+                payload[field] = options[field];
+        if (action === 'create') {
+            for (const field of ['title', 'base', 'head'])
+                if (!options[field])
+                    usage('--' + field + ' is required');
+            if (String(options.head).includes(':'))
+                gap('Cross-repository PR creation requires separate head repository verification');
+            payload.head = options.head;
+            payload.assignees = names(options.assignee);
+            expected.reviewers = sorted(addedReviewers);
+            expected.teams = sorted(names(options['team-reviewer']));
+            const head = object(await snapshot(base + '/branches/' + encodeURIComponent(String(options.head))));
+            expected.headSHA = object(head.commit).id;
+        }
+        else {
+            if (options['add-assignee'] !== undefined || options['remove-assignee'] !== undefined)
+                payload.assignees = delta(expected.assignees, options['add-assignee'], options['remove-assignee']);
+        }
+        if (options.base !== undefined)
+            await snapshot(base + '/branches/' + encodeURIComponent(String(options.base)));
+        if (options.milestone !== undefined) {
+            const list = await snapshot(base + '/milestones?state=all', true);
+            const selected = list.find(row => row.title === options.milestone);
+            if (!selected)
+                usage('Unknown exact milestone title');
+            payload.milestone = selected.id;
+        }
+        if (options.label !== undefined || options['add-label'] !== undefined || options['remove-label'] !== undefined) {
+            const labels = await snapshot(base + '/labels', true);
+            const ids = (value) => names(value).map(name => {
+                const label = labels.find(row => row.name === name);
+                if (!label)
+                    return usage('Unknown exact label name: ' + name);
+                return label.id;
+            });
+            payload.labels = action === 'create' ? ids(options.label) : [...new Set([...expected.labels, ...ids(options['add-label'])])].filter(id => !ids(options['remove-label']).includes(id));
+        }
+        for (const field of ['title', 'body', 'base', 'head', 'assignees', 'labels', 'milestone'])
+            if (payload[field] !== undefined)
+                expected[field] = payload[field];
+        if (action === 'create') {
+            add('POST', path, payload);
+            if (addedReviewers.length || names(options['team-reviewer']).length)
+                steps.push({ method: 'POST', path: path + '/0/requested_reviewers',
+                    payload: { reviewers: addedReviewers, team_reviewers: names(options['team-reviewer']) }, createdPull: true });
+        }
+        else {
+            for (const [flag, field, wire] of [['reviewer', 'reviewers', 'reviewers'], ['team-reviewer', 'teams', 'team_reviewers']]) {
+                const previous = expected[field];
+                const next = delta(previous, options['add-' + flag], options['remove-' + flag]);
+                const added = next.filter(name => !previous.includes(name));
+                const removed = previous.filter(name => !next.includes(String(name)));
+                if (added.length)
+                    add('POST', path + '/requested_reviewers', { [wire]: added });
+                if (removed.length)
+                    add('DELETE', path + '/requested_reviewers', { [wire]: removed });
+                expected[field] = next;
+            }
+            if (Object.keys(payload).length)
+                add('PATCH', path, payload);
+        }
+        if (!steps.length && !options.attach)
+            usage('Choose a PR field or membership to edit');
+    }
+    else if (action === 'close' || action === 'reopen') {
+        expected.state = action === 'close' ? 'closed' : 'open';
+        add('PATCH', path, { state: expected.state });
+    }
+    else if (action === 'merge') {
+        if (expected.headSHA !== options['match-head-commit'])
+            throw new CliError('STALE_HEAD', 'Selected PR head differs from --match-head-commit');
+        if (before.state !== 'open' || before.merged)
+            usage('Select an open unmerged PR');
+        const style = options.method ?? ['merge', 'squash', 'rebase'].find(key => options[key]);
+        const payload = { Do: style, head_commit_id: options['match-head-commit'] };
+        if (options.subject !== undefined)
+            payload.MergeTitleField = options.subject;
+        if (options.body !== undefined)
+            payload.MergeMessageField = options.body;
+        if (style === 'rebase')
+            await snapshot(path + '/commits', true);
+        await snapshot(base + '/branches/' + encodeURIComponent(String(expected.base)));
+        add('POST', path + '/merge', payload);
+        expected.state = 'closed';
+    }
+    else if (action === 'update-branch') {
+        await snapshot(base + '/branches/' + encodeURIComponent(String(expected.base)));
+        add('POST', path + '/update');
+    }
+    if (action === 'comment' || action === 'close' && options.comment !== undefined) {
+        const body = action === 'comment' ? options.body : options.comment;
+        if (body === undefined || body === '')
+            usage('--body is required');
+        const comments = base + '/issues/' + number + '/comments';
+        await snapshot(comments, true);
+        add('POST', comments, { body });
+    }
+    return { target: path, steps, reads: [...reads], preconditions, pull: { expected, action, repository: base } };
+}
+export async function verifyPull(client, plan, results, observations) {
+    const { expected, action, repository: base } = plan.pull;
+    const before = object(plan.preconditions);
+    const mismatch = () => { throw new CliError('READBACK_MISMATCH', 'PR read-back did not confirm identity, requested fields or commit graph'); };
+    const observation = (path) => observations.find(row => row.path === path)?.data;
+    let pull;
+    if (action === 'create') {
+        const result = object(results[0]);
+        pull = observation(plan.target + '?state=all').find(row => row.id === result.id && row.number === result.number) ?? mismatch();
+        if (before[plan.target + '?state=all'].some(row => row.id === pull.id || row.number === pull.number))
+            mismatch();
+    }
+    else {
+        pull = object(observation(plan.target));
+        if (pull.id !== expected.id || pull.number !== expected.number)
+            mismatch();
+    }
+    const actual = fields(pull);
+    for (const field of Object.keys(actual)) {
+        const value = ['assignees', 'labels', 'reviewers', 'teams'].includes(field) ? sorted(expected[field]) : expected[field];
+        if (!equal(actual[field], value))
+            mismatch();
+    }
+    if (action !== 'update-branch' && object(pull.head).sha !== expected.headSHA)
+        mismatch();
+    if (action !== 'merge' && (pull.merged ?? false) !== expected.merged)
+        mismatch();
+    for (const [index, step] of plan.steps.entries()) {
+        if (!step.path.endsWith('/comments'))
+            continue;
+        const comments = observation(step.path);
+        const previous = before[step.path];
+        const id = object(results[index]).id;
+        const added = comments.filter(row => !previous.some(old => old.id === row.id));
+        if (added.length !== 1 || added[0].id !== id || added[0].body !== object(step.payload).body || previous.some(old => !comments.some(row => equal(row, old))))
+            mismatch();
+    }
+    if (action !== 'merge' && action !== 'update-branch')
+        return;
+    const branchPath = base + '/branches/' + encodeURIComponent(String(expected.base));
+    const baseSHA = object(object(before[branchPath]).commit).id;
+    const commit = async (sha) => {
+        if (typeof sha !== 'string' || !/^[a-f0-9]{40}$/.test(sha))
+            return mismatch();
+        const path = base + '/git/commits/' + sha;
+        const data = object(await read(client, path));
+        if (data.sha !== sha || !Array.isArray(data.parents))
+            mismatch();
+        observations.push({ path, data });
+        return data;
+    };
+    if (action === 'update-branch') {
+        const head = await commit(object(pull.head).sha);
+        const pending = [head], visited = new Set();
+        while (pending.length && visited.size < 1000) {
+            const current = pending.pop();
+            if (visited.has(current.sha))
+                continue;
+            visited.add(current.sha);
+            if (visited.has(baseSHA) && visited.has(expected.headSHA))
+                return;
+            for (const parent of members(current, 'parents', 'sha')) {
+                if (!visited.has(parent))
+                    pending.push(await commit(parent));
+            }
+        }
+        mismatch();
+    }
+    if (pull.merged !== true || !pull.merge_commit_sha)
+        mismatch();
+    const finalSHA = object(object(observation(branchPath)).commit).id;
+    if (finalSHA !== pull.merge_commit_sha)
+        mismatch();
+    const final = await commit(finalSHA);
+    const style = object(plan.steps[0].payload).Do;
+    if (style === 'merge') {
+        if (!equal(members(final, 'parents', 'sha'), [baseSHA, expected.headSHA]))
+            mismatch();
+    }
+    else if (style === 'squash') {
+        if (!equal(members(final, 'parents', 'sha'), [baseSHA]) || finalSHA === expected.headSHA)
+            mismatch();
+    }
+    else {
+        const originals = before[plan.target + '/commits'];
+        if (!originals.length)
+            mismatch();
+        const bySHA = new Map(originals.map(row => [row.sha, row]));
+        let original = bySHA.get(expected.headSHA);
+        let current = final;
+        for (let index = 0; index < originals.length; index++) {
+            const parents = members(current, 'parents', 'sha');
+            if (!original || parents.length !== 1 || object(current.commit).message !== object(original.commit).message)
+                mismatch();
+            if (index === originals.length - 1) {
+                if (parents[0] !== baseSHA)
+                    mismatch();
+            }
+            else {
+                const originalParents = members(original, 'parents', 'sha');
+                if (originalParents.length !== 1)
+                    mismatch();
+                original = bySHA.get(originalParents[0]);
+                current = await commit(parents[0]);
+            }
+        }
+    }
+}

package/dist/reads.js

@@ -12,15 +12,15 @@ export const prFields = [...Object.keys(scalarFields), ...gaps, 'assignees', 'au
     'headRefName', 'headRefOid', 'headRepository', 'headRepositoryOwner', 'isCrossRepository', 'labels', 'latestReviews', 'mergeCommit',
     'mergeable', 'mergedBy', 'milestone', 'reactionGroups', 'reviewRequests', 'reviews', 'state', 'statusCheckRollup'];
 export const issueFields = ['number', 'title', 'state', 'body', 'author', 'assignees', 'labels', 'milestone', 'createdAt', 'updatedAt', 'url'];
-export function selectedFields(options, allowed) {
+export function selectedFields(options, allowed, unavailable = gaps) {
     if (typeof options.fields !== 'string')
         return;
     const fields = options.fields.split(',');
     if (fields.some(field => !allowed.includes(field)) || new Set(fields).size !== fields.length)
         throw new CliError('USAGE', 'Unknown or repeated field; choose ' + allowed.join(','), 2);
-    const gap = fields.find(field => gaps.includes(field));
+    const gap = fields.find(field => unavailable.includes(field));
     if (gap)
-        throw new CliError('CAPABILITY_GAP', gap + ' has no evidenced Gitea equivalent');
+        throw new CliError('CAPABILITY_GAP', gap + ' has no evidenced Gitea 1.23.4 equivalent' + (gap === 'id' ? '; fullDatabaseId is the numeric vendor ID, not a GraphQL node ID' : ''));
     if (options.full || options.comments || options.reviews || options.checks)
         throw new CliError('USAGE', '--fields cannot combine with --full, --comments, --reviews or --checks', 2);
     return fields;
@@ -107,9 +107,9 @@ export async function listIssues(client, base, kind, options) {
     return { items: rows.slice(0, limit).map(row => {
             const projection = { ...issue(row), isDraft: row.draft ?? null, headRefName: row.head ? object(row.head).ref : null, baseRefName: row.base ? object(row.base).ref : null };
             return Object.fromEntries(fields.map(field => [field, projection[field]]));
-        }), count: Math.min(rows.length, limit), total: page.truncated ? null : rows.length, vendor_total: page.total,
+        }), count: Math.min(rows.length, limit), total: page.truncated ? null : rows.length, unfiltered_total: page.total,
         truncated: page.truncated || rows.length > limit, next: page.next, continuation: page.truncated || rows.length > limit,
-        help: `gitea-axi ${kind} view <number> --repo ${base.split('/').slice(-2).join('/')}` };
+        help: [`gitea-axi ${kind} view <number> --repo ${base.split('/').slice(-2).join('/')}`, ...continuationHelp(page, rows.length, limit)] };
 }
 async function complete(client, path) {
     const page = await collect(client, path);
@@ -129,7 +129,7 @@ async function reviews(client, path, full) {
 }
 export async function checks(client, base, sha) {
     const combined = object(await read(client, base + '/commits/' + encodeURIComponent(sha) + '/status'));
-    if (combined.sha !== sha)
+    if (combined.sha !== sha && !(combined.sha === '' && combined.total_count === 0 && (combined.statuses === null || Array.isArray(combined.statuses) && !combined.statuses.length)))
         throw new CliError('INVALID_RESPONSE', 'Check response does not match the pull request head SHA');
     const statuses = await complete(client, base + '/commits/' + encodeURIComponent(sha) + '/statuses');
     statuses.sort((a, b) => Number(b.id) - Number(a.id));
@@ -158,7 +158,7 @@ export async function watchChecks(client, base, number, options) {
             if (typeof sha !== 'string' || !sha)
                 throw new CliError('INVALID_RESPONSE', 'Pull request head SHA is missing');
             const result = await checks(client, base, sha);
-            if (!options.watch || !result.pending || result.failed || Date.now() >= stop || controller.signal.aborted)
+            if (!options.watch || result.items.length > 0 && !result.pending || result.failed || Date.now() >= stop || controller.signal.aborted)
                 return { ...result, cancelled: controller.signal.aborted };
             await delay(Math.min(interval, Math.max(1, stop - Date.now())), undefined, { signal: controller.signal }).catch(error => {
                 if (!controller.signal.aborted)
@@ -209,7 +209,7 @@ export async function view(client, base, kind, number, options) {
             }
         }
         if (options.checks || requested.has('statusCheckRollup'))
-            result.statusCheckRollup = await checks(client, base, head.sha);
+            result.statusCheckRollup = { ...await checks(client, base, head.sha), source: 'commit-statuses', partial: true };
         if (requested.has('commits'))
             result.commits = (await complete(client, path + '/commits')).map(commit => ({ oid: commit.sha, message: object(commit.commit).message }));
         if (requested.has('files'))
@@ -223,8 +223,14 @@ export async function view(client, base, kind, number, options) {
     }
     return fields ? Object.fromEntries(fields.map(field => [field, result[field] ?? null])) : result;
 }
+export function continuationHelp(page, count, limit) {
+    if (!page.truncated && count <= limit)
+        return [];
+    return [page.truncated ? 'Use gitea-axi api GET "<collection>?limit=50&page=<page>" to page beyond the bounded read (maximum 1000 items).' : 'Raise --limit to see more items (maximum 1000).'];
+}
 export function boundedList(page, limit, fields) {
     return { items: page.items.slice(0, limit).map(row => Object.fromEntries(fields.map(key => [key, row[key] ?? null]))),
         count: Math.min(page.items.length, limit), total: page.total, next: page.next,
-        truncated: page.truncated || page.items.length > limit, continuation: page.truncated || page.items.length > limit };
+        truncated: page.truncated || page.items.length > limit, continuation: page.truncated || page.items.length > limit,
+        ...(continuationHelp(page, page.items.length, limit).length ? { help: continuationHelp(page, page.items.length, limit) } : {}) };
 }

package/dist/registry.js

@@ -1,3 +1,4 @@
+import { baseline, commandGap, flagGap } from './catalogue.js';
 export const command = {
     path: ['repo', 'view'],
     description: 'Read repository identity and default branch with server contract metadata.',
@@ -6,7 +7,7 @@ export const command = {
     outcomes: ['AC-001', 'AC-002', 'AC-004'],
     effect: 'read',
     flags: {
-        repo: { type: 'string', default: 'matching local origin remote', description: 'Repository as OWNER/NAME' },
+        repo: { type: 'string', short: 'R', default: 'matching local origin remote', description: 'Repository as OWNER/NAME' },
         origin: { type: 'string', default: 'selected profile', description: 'Gitea origin; HTTPS by default' },
         'allow-insecure-http': {
             type: 'boolean', default: false,
@@ -24,8 +25,9 @@ const globalFlags = {
     origin: command.flags.origin, 'allow-insecure-http': command.flags['allow-insecure-http'], help: command.flags.help,
     config: { type: 'string', description: 'Absolute configuration path' },
     profile: { type: 'string', description: 'Select one file profile' },
+    hostname: { type: 'string', description: 'Select exactly one matching configured host:port; otherwise GH_HOST' },
 };
-const repo = { repo: { type: 'string', description: 'OWNER/NAME; otherwise a matching local origin remote' } };
+const repo = { repo: { type: 'string', short: 'R', description: 'OWNER/NAME; otherwise a matching local origin remote' } };
 const list = {
     limit: { type: 'string', description: 'Maximum returned records, default 30, maximum 1000' },
     state: { type: 'string', description: 'open, closed or all; default open' },
@@ -37,7 +39,50 @@ const detail = {
     fields: list.fields, full: { type: 'boolean', description: 'Full body within response ceiling' },
     comments: { type: 'boolean', description: 'Include comments' },
 };
+const writeFlags = {
+    'allow-write': { type: 'string', description: 'Comma-separated exact vendor operation IDs authorized for this workflow' },
+    preview: { type: 'boolean', description: 'Preview and bind this exact write without dispatch' },
+    confirm: { type: 'string', description: 'Execute the unchanged preview confirmation ID once' },
+};
+const text = { type: 'string' };
+const repeated = { type: 'string', multiple: true };
+const issueBody = { body: text, 'body-file': { type: 'string', description: 'Body from an owned file or - for bounded stdin' } };
+const issueEdit = { title: text, ...issueBody, milestone: text };
+const mutationDefinitions = [
+    ['issue upload', { file: repeated, 'content-type': text }], ['pr upload', { file: repeated, 'content-type': text }], ['release upload', { file: repeated, 'content-type': text }],
+    ['secret set', { org: text, input: { ...text, description: 'Protected value file or - for stdin; values never accepted in argv' } }],
+    ['secret delete', { org: text }],
+    ['variable set', { org: text, body: text, input: { ...text, description: 'Value file or - for stdin; preserves empty values' } }],
+    ['variable delete', { org: text }],
+    ['repo create', { public: { type: 'boolean' }, private: { type: 'boolean' }, internal: { type: 'boolean' }, description: text, template: text,
+            source: text, push: { type: 'boolean' }, remote: text, clone: { type: 'boolean' } }],
+    ['repo edit', { description: text, visibility: text, 'default-branch': text, 'enable-issues': { type: 'boolean' }, 'enable-wiki': { type: 'boolean' } }],
+    ['repo fork', { org: text, clone: { type: 'boolean' }, remote: text, source: text, push: { type: 'boolean' } }],
+    ['release create', { attach: repeated, 'content-type': text, title: { ...text, short: 't' }, notes: { ...text, short: 'n' }, 'notes-file': { ...text, short: 'F' }, ...issueBody,
+            draft: { type: 'boolean', short: 'd' }, prerelease: { type: 'boolean', short: 'p' }, target: text,
+            'generate-notes': { type: 'boolean' }, 'notes-start-tag': text, 'notes-from-tag': { type: 'boolean' }, 'verify-tag': { type: 'boolean' },
+            'fail-on-no-commits': { type: 'boolean' }, latest: { type: 'boolean' }, 'discussion-category': text }],
+    ['release edit', { attach: repeated, 'content-type': text, title: text, notes: { ...text, short: 'n' }, 'notes-file': { ...text, short: 'F' }, ...issueBody, draft: { type: 'boolean' }, prerelease: { type: 'boolean' }, latest: { type: 'boolean' } }],
+    ['release delete', {}],
+    ['pr create', { ...issueEdit, attach: repeated, 'content-type': text, base: text, head: text, assignee: repeated, label: repeated, reviewer: repeated, 'team-reviewer': repeated }],
+    ['pr edit', { ...issueEdit, attach: repeated, 'content-type': text, base: text, 'add-label': repeated, 'remove-label': repeated, 'add-assignee': repeated, 'remove-assignee': repeated, 'add-reviewer': repeated, 'remove-reviewer': repeated, 'add-team-reviewer': repeated, 'remove-team-reviewer': repeated }],
+    ['pr close', { comment: text }], ['pr reopen', {}], ['pr comment', { ...issueBody, attach: repeated, 'content-type': text }],
+    ['pr update-branch', {}],
+    ['pr merge', { method: text, merge: { type: 'boolean' }, squash: { type: 'boolean' }, rebase: { type: 'boolean' }, 'match-head-commit': text,
+            auto: { type: 'boolean' }, admin: { type: 'boolean' }, 'delete-branch': { type: 'boolean' }, subject: text, ...issueBody }],
+    ['pr review', { approve: { type: 'boolean' }, 'request-changes': { type: 'boolean' }, comment: { type: 'boolean' }, 'match-head-commit': text, ...issueBody }],
+    ['issue create', { ...issueEdit, attach: repeated, 'content-type': text, assignee: repeated, label: repeated }],
+    ['issue edit', { ...issueEdit, attach: repeated, 'content-type': text, 'add-label': repeated, 'remove-label': repeated, 'add-assignee': repeated, 'remove-assignee': repeated }],
+    ['issue close', { comment: text }], ['issue reopen', {}], ['issue comment', { ...issueBody, attach: repeated, 'content-type': text }],
+    ['issue delete', {}], ['issue pin', {}], ['issue unpin', {}],
+    ['label create', { name: text, color: text, description: text }],
+    ['label edit', { name: text, color: text, description: text }], ['label delete', {}],
+];
 const definitions = [
+    ['issue download', { ...repo, dir: text, output: text, 'asset-id': text, pattern: repeated, sha256: text, 'content-type': text, clobber: { type: 'boolean' } }],
+    ['pr download', { ...repo, dir: text, output: text, 'asset-id': text, pattern: repeated, sha256: text, 'content-type': text, clobber: { type: 'boolean' } }],
+    ['release download', { ...repo, dir: text, output: text, 'asset-id': text, pattern: repeated, sha256: text, 'content-type': text, clobber: { type: 'boolean' } }],
+    ['secret list', { ...repo, org: text, limit: list.limit }], ['variable list', { ...repo, org: text, limit: list.limit }],
     ['dashboard', repo], ['auth status', {}], ['profile list', {}], ['config path', {}], ['doctor', {}],
     ['repo list', { limit: list.limit, org: { type: 'string', description: 'List repositories belonging to this organization' } }],
     ['org view', {}], ['issue list', { ...repo, ...list, assignee: { type: 'string' }, author: { type: 'string' }, label: { type: 'string' }, milestone: { type: 'string' } }],
@@ -45,11 +90,100 @@ const definitions = [
     ['pr list', { ...repo, ...list, assignee: { type: 'string' }, author: { type: 'string' }, label: { type: 'string' }, milestone: { type: 'string' } }],
     ['pr view', { ...repo, ...detail, reviews: { type: 'boolean' }, checks: { type: 'boolean' } }],
     ['pr checks', { ...repo, watch: { type: 'boolean' }, timeout: { type: 'string', description: 'Watch deadline seconds, required with --watch' }, interval: { type: 'string', description: 'Watch interval seconds, default 5' } }],
-    ['pr diff', { ...repo, full: detail.full }], ['run list', { ...repo, limit: list.limit }],
-    ['release list', { ...repo, limit: list.limit }], ['api', {}],
+    ['pr diff', { ...repo, full: detail.full }],
+    ['release list', { ...repo, limit: list.limit, 'exclude-drafts': { type: 'boolean' }, 'exclude-pre-releases': { type: 'boolean' } }],
+    ['release view', { ...repo, full: detail.full }], ['api', { ...writeFlags,
+            method: { type: 'string', short: 'X', description: 'HTTP method; cannot combine with a positional method' },
+            field: { type: 'string', multiple: true, description: 'Repeatable key=value; numbers, booleans and null become JSON values' },
+            'raw-field': { type: 'string', multiple: true, description: 'Repeatable key=value string' },
+            input: { type: 'string', description: 'Protected JSON request file; use - for stdin' } }],
+    ['write reconcile', {}],
 ];
 export const commands = [
     { ...command, flags: { ...command.flags, ...globalFlags } },
     ...definitions.map(([name, flags]) => ({ path: name.split(' '), description: name === 'dashboard' ? 'Bounded repository dashboard with explicit partial results' : name,
-        flags: { ...globalFlags, ...flags }, effect: 'read' })),
+        flags: { ...globalFlags, ...flags }, effect: name.endsWith(' download') ? 'download' : 'read' })),
+    ...mutationDefinitions.map(([name, flags]) => ({ path: name.split(' '), description: name === 'pr review' ? 'pr review (unresolved vendor events and atomic stale-head refusal; no posting)' : name,
+        flags: { ...globalFlags, ...repo, ...writeFlags, ...flags }, effect: 'write' })),
+];
+const strings = (...names) => Object.fromEntries(names.map(name => [name, { type: 'string' }]));
+const booleans = (...names) => Object.fromEntries(names.map(name => [name, { type: 'boolean' }]));
+const stageFive = [
+    ['run list', strings('workflow', 'branch', 'status', 'event', 'user', 'commit', 'limit', 'fields'), 'read'],
+    ['run view', { ...strings('job', 'conclusion'), ...booleans('log', 'verbose', 'log-failed') }, 'read'],
+    ['run watch', strings('timeout', 'interval'), 'read'],
+    ['run rerun', { ...strings('job'), ...booleans('failed', 'debug') }, 'pending-write'],
+    ['run cancel', {}, 'pending-write'], ['run delete', {}, 'pending-write'],
+    ['run download', strings('name', 'dir'), 'download'],
+    ['workflow list', { ...strings('limit'), ...booleans('all') }, 'read'],
+    ['workflow view', booleans('yaml'), 'read'],
+    ['workflow run', strings('ref', 'field'), 'pending-write'],
+    ['workflow enable', {}, 'pending-write'], ['workflow disable', {}, 'pending-write'],
+    ...['issues', 'prs', 'repos', 'commits', 'code'].map((kind) => [
+        'search ' + kind,
+        { ...strings('owner', 'state', 'label', 'assignee', 'author', 'sort', 'order', 'limit', 'fields', 'review', 'language', 'stars', 'revision'), ...booleans('draft') },
+        'read',
+    ]),
+];
+commands.push(...stageFive.map(([name, flags, effect]) => ({ path: name.split(' '), description: name + (effect === 'pending-write' ? ' (pending shared write gate)' : ''), flags: { ...globalFlags, ...repo, ...flags }, effect })));
+const workspace = { workspace: { ...text, description: 'Absolute native Git repository root; clone uses an existing absolute parent directory' } };
+const stackDefinitions = [
+    ['view', {}], ['init', strings('base')], ['add', { ...strings('message'), ...booleans('all', 'update') }],
+    ['checkout', {}], ['push', strings('remote')], ['submit', { ...strings('remote'), ...booleans('open') }],
+    ['sync', { ...strings('remote'), ...booleans('prune') }],
+    ['rebase', { ...strings('remote'), ...booleans('downstack', 'upstack', 'no-trunk', 'continue', 'abort', 'committer-date-is-author-date', 'preserve-dates') }],
+    ['link', { ...strings('base', 'remote'), ...booleans('open') }], ['unstack', booleans('local')],
+    ['merge', { ...strings('merge-method'), ...booleans('merge', 'squash', 'rebase') }],
+    ...['up', 'down', 'top', 'bottom', 'trunk'].map((name) => [name, {}]),
+];
+commands.push(...stackDefinitions.map(([name, flags]) => ({ path: ['stack', name], description: 'Owned local stack ' + name,
+    flags: { ...globalFlags, ...workspace, ...writeFlags, ...flags }, effect: name === 'view' ? 'local-read' : 'local-write' })));
+commands.push(...['repo clone', 'pr checkout', 'pr revert'].map(name => ({ path: name.split(' '), description: name + ' in an explicit standalone workspace',
+    flags: { ...globalFlags, ...repo, ...workspace, ...writeFlags }, effect: 'local-write' })));
+for (const command of commands) {
+    if (['repo create', 'repo fork'].includes(command.path.join(' ')))
+        Object.assign(command.flags, workspace);
+}
+commands.push({ path: ['capabilities'], description: 'Inspect all baseline command IDs, flags, globals and PR fields without claiming full parity', flags: { help: globalFlags.help }, effect: 'local-read' });
+const refusedFlags = [
+    ['repo create', ['internal']],
+    ['release create', ['latest', 'discussion-category']],
+    ['release edit', ['latest']],
+    ['pr merge', ['auto', 'admin', 'delete-branch']],
+    ['run list', ['user']],
+    ['search issues', ['review', 'language', 'stars', 'revision', 'draft']],
+    ['search prs', ['review', 'language', 'stars', 'revision']],
+    ['search repos', ['state', 'label', 'assignee', 'author', 'review', 'revision', 'draft']],
+    ['search commits', ['owner', 'state', 'label', 'assignee', 'review', 'language', 'stars', 'draft']],
+    ['stack rebase', ['preserve-dates']],
+    ['stack link', ['open']],
+    ['stack submit', ['open']],
 ];
+for (const [path, names] of refusedFlags) {
+    const command = commands.find(command => command.path.join(' ') === path);
+    for (const name of names)
+        command.flags[name] = { ...command.flags[name], gap: flagGap(path, name) };
+}
+// Retain unsupported leaves and options in the same registry that owns help and admission metadata.
+const booleanFlags = new Set(['comments', 'full', 'public', 'secret', 'files', 'raw', 'web', 'no-type', 'draft', 'failed', 'fail-fast', 'patch', 'undo', 'all', 'prune', 'open', 'local', 'merge', 'squash', 'rebase', 'downstack', 'upstack', 'no-trunk', 'continue', 'abort', 'committer-date-is-author-date', 'preserve-dates', 'check', 'closed', 'clear', 'remove']);
+for (const row of baseline) {
+    if (row.path === '--version' || row.path.startsWith('api ') || row.path === 'update --check')
+        continue;
+    if (!commands.some(command => command.path.join(' ') === row.path)) {
+        const gap = commandGap(row.path);
+        if (!gap)
+            throw new Error('Missing capability decision for ' + row.id);
+        commands.push({ path: row.path.split(' '), description: row.path + ' (compatibility gap)', flags: { ...globalFlags, ...repo }, effect: 'gap', gap });
+    }
+}
+for (const row of baseline) {
+    const path = row.path.startsWith('api ') ? 'api' : row.path === 'update --check' ? 'update' : row.path;
+    const command = commands.find(command => command.path.join(' ') === path);
+    if (!command)
+        continue;
+    for (const flag of row.flags) {
+        const name = flag.name === '-X' ? 'method' : flag.name.replace(/^--/, '');
+        if (!command.flags[name])
+            command.flags[name] = { type: booleanFlags.has(name) ? 'boolean' : 'string', description: 'Compatibility gap: ' + flagGap(path, name), gap: flagGap(path, name) };
+    }
+}