@knowttl/gitea-axi 0.0.0-stage → 0.1.1

package/dist/api.js

@@ -0,0 +1,195 @@
+import { readFileSync } from 'node:fs';
+import { Ajv } from 'ajv';
+import { CliError } from './error.js';
+const vendor = JSON.parse(readFileSync(new URL('../schemas/vendor.json', import.meta.url), 'utf8'));
+const routes = JSON.parse(readFileSync(new URL('../generated/routes.json', import.meta.url), 'utf8'));
+routes.sort((a, b) => b.path.replace(/\{[^}]+\}/g, '').length - a.path.replace(/\{[^}]+\}/g, '').length);
+const required = {
+    Issue: ['id', 'number', 'title', 'state'], PullRequest: ['id', 'number', 'title', 'state', 'head', 'base'],
+    Label: ['id', 'name', 'color'], Repository: ['id', 'full_name', 'default_branch'], User: ['id', 'login'],
+    Comment: ['id', 'body', 'user'], PullReview: ['id', 'user', 'state', 'body', 'commit_id'],
+    CommitStatus: ['id', 'context', 'status'], Milestone: ['id', 'title'],
+    PRBranchInfo: ['sha', 'ref'], CombinedStatus: ['sha', 'statuses', 'total_count'],
+    Branch: ['name', 'commit'], PayloadCommit: ['id'],
+    Release: ['id', 'tag_name', 'target_commitish', 'name', 'body', 'draft', 'prerelease'],
+    Tag: ['name', 'commit'], CommitMeta: ['sha'],
+    Secret: ['name'], ActionVariable: ['name', 'data'], Attachment: ['id', 'uuid', 'name', 'size'],
+    GitTreeResponse: ['tree', 'truncated'], GitEntry: ['path', 'mode', 'type', 'sha'],
+    ActionTask: ['id', 'name', 'status'], ActionTaskResponse: ['workflow_runs', 'total_count'],
+};
+for (const [name, fields] of Object.entries(required)) {
+    if (vendor.definitions[name])
+        vendor.definitions[name].required = fields;
+}
+// Gitea's Go pointer fields and nil slices serialize as null, which Swagger 2 cannot express.
+for (const definition of Object.values(vendor.definitions)) {
+    for (const [key, property] of Object.entries(definition.properties ?? {})) {
+        if (property.$ref && !['state', 'status'].includes(key) || property.type === 'array' || property.format === 'date-time') {
+            definition.properties[key] = { anyOf: [property, { type: 'null' }] };
+        }
+    }
+}
+const requestDefinitions = structuredClone(vendor.definitions);
+for (const [name, fields] of Object.entries({ PullRequest: ['merge_commit_sha'], ContentsResponse: ['submodule_git_url', 'target'] })) {
+    for (const field of fields) {
+        const properties = vendor.definitions[name].properties;
+        properties[field] = { anyOf: [properties[field], { type: 'null' }] };
+    }
+}
+const ajv = new Ajv({ strict: false, validateFormats: false });
+const validators = new Map();
+export function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new CliError('INVALID_RESPONSE', 'Expected an object from Gitea');
+    return value;
+}
+export function effectFor(method, path) {
+    path = canonicalPath(path);
+    return routes.find(route => route.method === method && new RegExp('^' + route.path.split(/(\{[^}]+\})/).map(part => /^\{[^}]+\}$/.test(part) ? '[^/]+' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('') + '$').test(path.split('?')[0]));
+}
+export function canonicalPath(path) {
+    const pathname = path.split('?')[0];
+    if (/%(?:2f|5c)/i.test(pathname))
+        throw new CliError('READ_ONLY', 'Encoded route separators are refused');
+    let decoded;
+    try {
+        decoded = decodeURIComponent(pathname);
+    }
+    catch {
+        throw new CliError('USAGE', 'Malformed API path', 2);
+    }
+    return decoded.split('/').map(encodeURIComponent).join('/');
+}
+export function validatePayload(method, path, payload) {
+    const route = effectFor(method, path);
+    if (!route || route.effect !== 'write')
+        throw new CliError('READ_ONLY', 'Only classified business writes may be enabled');
+    if (/\/actions\/secrets\//.test(path) && method === 'PUT' &&
+        (typeof object(payload).data !== 'string' || Object.keys(object(payload)).some(key => key !== 'data'))) {
+        throw new CliError('USAGE', 'Secret input requires only a string data field', 2);
+    }
+    const segments = canonicalPath(path).split('/');
+    for (const [index, segment] of route.path.split('/').entries()) {
+        if (route.integerParameters.some(name => segment === '{' + name + '}') && !/^(?:0|-?[1-9]\d*)$/.test(segments[index])) {
+            throw new CliError('USAGE', 'Integer route parameters require canonical decimal spelling', 2);
+        }
+    }
+    if (route.requestSchema && !ajv.compile({ ...route.requestSchema, definitions: requestDefinitions })(payload)) {
+        throw new CliError('USAGE', 'Invalid request fields for ' + route.operation, 2);
+    }
+    return route;
+}
+export function routeFor(path) {
+    const route = effectFor('GET', path);
+    if (route?.effect === 'admin')
+        throw new CliError('READ_ONLY', 'Administrative API routes are refused; only metadata reads are available');
+    if (route?.effect === 'credential')
+        throw new CliError('READ_ONLY', 'Credential-bearing API routes are refused; only metadata reads are available');
+    if (route?.effect === 'download')
+        throw new CliError('READ_ONLY', 'Text and binary download routes are refused; only JSON metadata reads are available');
+    if (!route || route.effect !== 'read')
+        throw new CliError('READ_ONLY', 'Only classified metadata reads are available');
+    return route;
+}
+export function validate(path, value) {
+    const route = routeFor(path);
+    if (route.schema) {
+        let validator = validators.get(route.path);
+        if (!validator) {
+            validator = ajv.compile({ ...route.schema, definitions: vendor.definitions });
+            validators.set(route.path, validator);
+        }
+        if (!validator(value))
+            throw new CliError('INVALID_RESPONSE', route.operation + ' returned invalid fields');
+    }
+    if (/\/actions\/secrets(?:\?|$)/.test(path) && Array.isArray(value)) {
+        return value.map(row => ({ name: object(row).name, ...(object(row).created_at ? { created_at: object(row).created_at } : {}) }));
+    }
+    return value;
+}
+export function rawPath(input, method = 'GET') {
+    if (/^[a-z]+:/i.test(input) || input.startsWith('//') || input.includes('#'))
+        throw new CliError('USAGE', 'Use a relative API path without traversal', 2);
+    const separator = input.indexOf('?');
+    const pathname = canonicalPath(separator < 0 ? input : input.slice(0, separator));
+    const query = separator < 0 ? '' : input.slice(separator + 1);
+    const decoded = decodeURIComponent(pathname);
+    if (/[\\#\s%]/.test(decoded) || decoded.split('/').some(part => part === '.' || part === '..'))
+        throw new CliError('USAGE', 'Use a relative API path without traversal', 2);
+    for (const key of new URLSearchParams(query).keys()) {
+        if (/token|secret|password|authorization|api.?key/i.test(key))
+            throw new CliError('USAGE', 'Secret query fields are refused', 2);
+    }
+    const path = pathname === '/swagger.v1.json' ? pathname : pathname?.startsWith('/api/v1/') ? pathname : '/api/v1/' + pathname?.replace(/^\//, '');
+    if (path !== '/swagger.v1.json' && method === 'GET')
+        routeFor(path);
+    else if (method !== 'GET' && !effectFor(method, path))
+        throw new CliError('READ_ONLY', 'Unclassified API route');
+    return path + (query ? '?' + query : '');
+}
+export async function read(client, path) {
+    routeFor(path.split('?')[0]);
+    const value = await client.get(path);
+    return validate(path.split('?')[0], value);
+}
+export async function resolveCommit(client, base, ref) {
+    const rows = await read(client, base + '/commits?sha=' + encodeURIComponent(ref) + '&limit=1');
+    if (!Array.isArray(rows) || rows.length !== 1)
+        throw new CliError('NOT_FOUND_OR_HIDDEN', 'The selected commit ref is missing or hidden');
+    const row = object(rows[0]);
+    if (typeof row.sha !== 'string' || !/^[a-f0-9]{40}$/.test(row.sha))
+        throw new CliError('INVALID_RESPONSE', 'Expected an immutable commit identity');
+    return row;
+}
+function nextPage(headers, path, origin) {
+    const target = headers.get('link')?.split(',').find(part => /rel="?next"?/.test(part))?.match(/<([^>]+)>/)?.[1];
+    if (!target)
+        return null;
+    const url = new URL(target, new URL(path, origin));
+    if (url.origin !== origin || url.pathname !== new URL(path, origin).pathname || url.username || url.password || url.hash) {
+        throw new CliError('UNSAFE_PAGINATION', 'Pagination must stay on the selected origin and collection');
+    }
+    return rawPath(url.pathname + url.search);
+}
+export async function rawRead(client, path) {
+    const response = await client.request(path);
+    const data = path === '/swagger.v1.json' ? response.data : validate(new URL(path, client.origin).pathname, response.data);
+    const count = response.headers.get('x-total-count');
+    return { data, total: count && /^\d+$/.test(count) ? Number(count) : null, next: nextPage(response.headers, path, client.origin), truncated: false };
+}
+export async function collect(client, path, envelope) {
+    let next = path + (path.includes('?') ? '&' : '?') + 'limit=50&page=1';
+    const seenPages = new Set();
+    const items = new Map();
+    let total = null;
+    while (next && seenPages.size < 20 && items.size < 1000 && Date.now() < client.deadline) {
+        if (seenPages.has(next))
+            throw new CliError('INVALID_RESPONSE', 'Gitea repeated a pagination URL');
+        seenPages.add(next);
+        const response = await client.request(next);
+        const data = validate(new URL(next, client.origin).pathname, response.data);
+        const rows = envelope ? object(data)[envelope] : data;
+        if (!Array.isArray(rows))
+            throw new CliError('INVALID_RESPONSE', 'Expected a Gitea list' + (envelope ? ' envelope ' + envelope : ''));
+        for (const value of rows) {
+            const row = object(value);
+            const id = /\/(?:tags|actions\/(?:secrets|variables))$/.test(path.split('?')[0]) ? row.name : row.id ?? row.number ?? row.sha ?? row.filename ?? (row.user && row.content ? String(object(row.user).id) + ':' + row.content : undefined);
+            if (typeof id !== 'number' && typeof id !== 'string')
+                throw new CliError('INVALID_RESPONSE', 'List record has no identity');
+            items.set(String(id), row);
+        }
+        const count = response.headers.get('x-total-count');
+        if (count && /^\d+$/.test(count))
+            total = Number(count);
+        if (envelope && typeof object(data).total_count === 'number')
+            total = object(data).total_count;
+        const link = response.headers.get('link');
+        next = nextPage(response.headers, path, client.origin);
+        if (!next && !link && rows.length >= 50) {
+            const url = new URL([...seenPages].at(-1), client.origin);
+            url.searchParams.set('page', String(Number(url.searchParams.get('page')) + 1));
+            next = url.pathname + url.search;
+        }
+    }
+    return { items: [...items.values()], total, next, truncated: next !== null };
+}

package/dist/attachments.js

@@ -0,0 +1,171 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, open, realpath, rename, rm } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { collect, object, read, validate } from './api.js';
+import { CliError } from './error.js';
+export const transferBytes = 10_000_000;
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function safeName(name) {
+    if (!name || name === '.' || name === '..' || /[\\/:*?"<>|\x00-\x1f\x7f]/.test(name) || /[. ]$/.test(name) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name))
+        throw new CliError('UNSAFE_PATH', 'Attachment requires a safe portable basename');
+    return name;
+}
+function attachment(value) {
+    const row = object(value);
+    if (!Number.isSafeInteger(row.id) || Number(row.id) <= 0 || typeof row.uuid !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(row.uuid) || typeof row.name !== 'string' || !Number.isSafeInteger(row.size) || Number(row.size) < 0)
+        throw new CliError('INVALID_RESPONSE', 'Attachment metadata has invalid identity or size');
+    safeName(row.name);
+    return row;
+}
+export async function assetPath(client, base, kind, selected) {
+    if (kind !== 'release') {
+        await read(client, base + (kind === 'pr' ? '/pulls/' : '/issues/') + selected);
+        return base + '/issues/' + selected + '/assets';
+    }
+    const page = await collect(client, base + '/releases');
+    if (page.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Release identity requires a complete collection');
+    const release = page.items.find(row => row.tag_name === selected);
+    if (!release || !Number.isSafeInteger(release.id) || Number(release.id) <= 0)
+        throw new CliError('NOT_FOUND_OR_HIDDEN', 'The selected release is missing or hidden');
+    return base + '/releases/' + release.id + '/assets';
+}
+async function uploadSteps(path, options) {
+    const paths = options.file ?? options.attach;
+    if (!paths)
+        throw new CliError('USAGE', 'Select at least one --file', 2);
+    const files = Array.isArray(paths) ? paths : [paths];
+    const names = new Set();
+    const steps = [];
+    for (const value of files) {
+        const filePath = String(value), name = safeName(basename(filePath));
+        if (names.has(name.toLowerCase()))
+            throw new CliError('UNSAFE_PATH', 'Duplicate attachment basenames are refused');
+        names.add(name.toLowerCase());
+        const info = await lstat(filePath);
+        if (!info.isFile() || info.isSymbolicLink() || await realpath(filePath) !== resolve(filePath))
+            throw new CliError('UNSAFE_PATH', 'Upload must be a regular file without symlinks');
+        const file = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const chunks = [];
+        let size = 0;
+        try {
+            if (!(await file.stat()).isFile())
+                throw new CliError('UNSAFE_PATH', 'Upload must be a regular file');
+            for await (const chunk of file.createReadStream({ autoClose: false })) {
+                size += chunk.length;
+                if (size > transferBytes)
+                    throw new CliError('TRANSFER_LIMIT', 'Upload exceeds 10000000 bytes');
+                chunks.push(chunk);
+            }
+        }
+        finally {
+            await file.close();
+        }
+        const bytes = Buffer.concat(chunks);
+        const type = String(options['content-type'] ?? 'application/octet-stream');
+        if (!/^[\w.+-]+\/[\w.+-]+$/.test(type))
+            throw new CliError('USAGE', 'Select a MIME content type', 2);
+        steps.push({ method: 'POST', path, upload: { name, type, size, base64: bytes.toString('base64'), sha256: hash(bytes) } });
+    }
+    return steps;
+}
+export async function uploadPlan(client, path, options) {
+    const page = await collect(client, path);
+    if (page.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Attachment identity requires a complete collection');
+    const before = page.items.map(attachment);
+    const steps = await uploadSteps(path, options);
+    if (steps.some(step => before.some(row => String(row.name).toLowerCase() === step.upload.name.toLowerCase())))
+        throw new CliError('ALREADY_EXISTS', 'An attachment has the same basename; choose a distinct name');
+    return { target: path, steps, reads: [path], preconditions: before, assets: { path, before } };
+}
+export async function attachToPlan(client, plan, operation, base, selected, options) {
+    if (!options.attach)
+        return plan;
+    const comment = operation.endsWith(' comment');
+    const created = operation.endsWith(' create') || comment;
+    if (created) {
+        const parent = comment ? plan.steps.findIndex(step => step.path.endsWith('/comments')) : 0;
+        const path = base + (comment ? '/issues/comments/0/assets' : operation.startsWith('release ') ? '/releases/0/assets' : '/issues/0/assets');
+        return { ...plan, steps: [...plan.steps, ...(await uploadSteps(path, options)).map(step => ({ ...step, assetParent: parent }))], assets: { path, before: [] } };
+    }
+    const uploads = await uploadPlan(client, await assetPath(client, base, operation.split(' ')[0], selected), options);
+    return { ...plan, steps: [...plan.steps, ...uploads.steps], reads: [...plan.reads, ...uploads.reads], preconditions: { ...object(plan.preconditions), attachments: uploads.preconditions }, assets: uploads.assets };
+}
+export function verifyUploads(plan, results, observations) {
+    const { path, before } = plan.assets;
+    const after = observations.find(row => row.path === path).data.map(attachment);
+    const uploads = plan.steps.flatMap((step, index) => step.upload ? [{ upload: step.upload, result: attachment(validate(path + '/' + object(results[index]).id, results[index])) }] : []);
+    if (after.length !== before.length + uploads.length || before.some(row => !after.some(item => item.id === row.id && item.uuid === row.uuid && item.name === row.name && item.size === row.size)) || uploads.some(({ upload, result }) => before.some(row => row.id === result.id) || !after.some(row => row.id === result.id && row.uuid === result.uuid && row.name === upload.name && row.size === upload.size)))
+        throw new CliError('READBACK_MISMATCH', 'Attachment metadata did not confirm the intended uploads');
+}
+export async function download(client, path, options) {
+    if (process.platform === 'win32')
+        throw new CliError('CONFIG_INSECURE', 'Native Windows download ACL protection is unavailable');
+    if (options['content-type'] !== undefined && !/^[\w.+-]+\/[\w.+-]+$/.test(String(options['content-type'])))
+        throw new CliError('USAGE', 'Select a MIME content type', 2);
+    if (options.output && options.dir)
+        throw new CliError('USAGE', 'Choose --output or --dir', 2);
+    if (options['asset-id'] !== undefined && !/^[1-9]\d*$/.test(String(options['asset-id'])))
+        throw new CliError('USAGE', 'Select one positive --asset-id', 2);
+    const page = await collect(client, path);
+    if (page.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Download selection requires a complete collection');
+    const patterns = options.pattern === undefined ? ['*'] : Array.isArray(options.pattern) ? options.pattern.map(String) : [String(options.pattern)];
+    const matches = patterns.map(pattern => new RegExp('^' + pattern.split(/([*?])/).map(part => part === '*' ? '.*' : part === '?' ? '.' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('') + '$'));
+    const selected = page.items.filter(row => (options['asset-id'] === undefined || String(row.id) === options['asset-id']) && matches.some(pattern => pattern.test(String(row.name)))).map(attachment);
+    if (!selected.length)
+        throw new CliError('NO_MATCHES', 'No attachments match the selected patterns');
+    if (new Set(selected.map(row => String(row.name).toLowerCase())).size !== selected.length)
+        throw new CliError('UNSAFE_PATH', 'Duplicate download basenames are refused');
+    if (options.sha256 !== undefined && (selected.length !== 1 || !/^[a-f0-9]{64}$/.test(String(options.sha256))))
+        throw new CliError('USAGE', '--sha256 requires exactly one selected file and a lowercase SHA-256 digest', 2);
+    if (options.output && selected.length !== 1)
+        throw new CliError('USAGE', '--output requires exactly one selected attachment', 2);
+    const directory = options.output ? dirname(resolve(String(options.output))) : resolve(String(options.dir ?? '.'));
+    if (!(await lstat(directory)).isDirectory() || await realpath(directory) !== directory)
+        throw new CliError('UNSAFE_PATH', 'Download directory must exist without symlinks');
+    const completed = [];
+    for (const selectedRow of selected) {
+        const temporary = join(directory, '.gitea-attachment-' + randomUUID() + '.tmp');
+        try {
+            const row = attachment(await read(client, path + '/' + selectedRow.id));
+            if (['id', 'uuid', 'name', 'size'].some(key => row[key] !== selectedRow[key]))
+                throw new CliError('INVALID_RESPONSE', 'Attachment identity changed before download');
+            if (Number(row.size) > transferBytes)
+                throw new CliError('TRANSFER_LIMIT', 'Download exceeds 10000000 bytes');
+            const destination = join(directory, options.output ? safeName(basename(String(options.output))) : String(row.name));
+            const previous = await lstat(destination).catch((error) => { if (error.code !== 'ENOENT')
+                throw error; return null; });
+            if (previous && (!options.clobber || previous.isSymbolicLink() || !previous.isFile()))
+                throw new CliError('UNSAFE_PATH', 'Destination exists; choose --clobber for a regular file');
+            const { bytes, type } = await client.attachment(String(row.uuid), options['content-type'] === undefined ? undefined : String(options['content-type']));
+            const sha256 = hash(bytes);
+            if (bytes.length !== row.size || options.sha256 && sha256 !== options.sha256)
+                throw new CliError('INTEGRITY_MISMATCH', 'Downloaded bytes differ from the selected size or digest');
+            const file = await open(temporary, 'wx', 0o600);
+            try {
+                await file.writeFile(bytes);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            if (options.clobber)
+                await rename(temporary, destination);
+            else
+                await link(temporary, destination);
+            completed.push({ id: row.id, name: row.name, bytes: bytes.length, sha256, content_type: type, path: destination });
+        }
+        catch (error) {
+            if (!completed.length)
+                throw error;
+            throw new CliError('PARTIAL_TRANSFER', 'Completed attachment IDs ' + completed.map(row => row.id).join(',') + '; remaining transfer failed: ' + (error instanceof CliError ? error.code : 'FILE_ERROR'));
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    return { downloads: completed };
+}

package/dist/catalogue.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { CliError } from './error.js';
+export const baseline = JSON.parse(readFileSync(new URL('../schemas/catalogue.json', import.meta.url), 'utf8')).commands;
+export function commandGap(path) {
+    if (/^(discussion|gist|project) /.test(path))
+        return 'No corresponding discussion, gist or Projects v2 API is documented in the retained Gitea 1.23.4 or 1.24.0 specifications';
+    if (/^issue (lock|unlock)$/.test(path))
+        return 'Gitea 1.23.4 has no documented issue lock contract; the retained 1.24.0 lock candidate is not commissioned';
+    if (/^issue (transfer|subissue )/.test(path))
+        return 'Gitea 1.23.4 and 1.24.0 provide no evidenced issue transfer or parent/child subissue contract; repository transfer and dependencies are different operations';
+    if (path === 'pr ready')
+        return 'Gitea 1.23.4 and 1.24.0 do not document a draft transition field in EditPullRequestOption';
+    if (path === 'setup hooks')
+        return 'C096: retained gh-axi 0.1.46 help does not specify supported agent paths, configuration schemas or repair semantics; hook installation remains pending';
+    if (path === 'update' || path === 'update --check')
+        return 'C122/C123: retained gh-axi 0.1.46 help does not establish the distribution, integrity or rollback contract; update and check-only remain pending';
+    if (path === 'api HEAD')
+        return 'Gitea 1.23.4 has no documented HEAD operation/effect contract; no GET substitution is performed';
+    if (path === 'pr review')
+        return 'Gitea 1.23.4 and 1.24.0 do not establish review event values or atomic stale-head rejection (CX-007); review posting remains pending';
+    if (path === 'dashboard')
+        return 'C121: exact gh-axi 0.1.46 sections and defaults are not captured; the owned bounded repository dashboard is not baseline parity';
+    if (path.startsWith('workflow ') || path.startsWith('run ') && path !== 'run list')
+        return 'Gitea 1.23.4 has task summaries only; retained 1.24.0 workflow/run candidates remain uncommissioned';
+    if (path === 'search code')
+        return 'Gitea 1.23.4 has no evidenced code search API/query contract';
+    if (path === 'stack submit')
+        return 'The required automatic merge scheduling contract remains pending';
+    return;
+}
+export function flagGap(path, name) {
+    if (name === 'jq' || name === 'template')
+        return '--' + name + ' compatibility is not implemented: no jq evaluator or template engine/grammar has been selected; Gitea 1.23.4 responses do not supply these local semantics';
+    return '--' + name + ' has no implemented compatibility contract for ' + path + ' on Gitea 1.23.4; see capabilities for the retained baseline outcome';
+}
+export function capabilityOutput(commands, fields, id) {
+    if (id && !baseline.some(row => row.id === id))
+        throw new CliError('USAGE', 'Select a catalogue ID C001 through C124', 2);
+    const rows = baseline.filter(row => !id || row.id === id).map(row => {
+        const path = row.path === 'update --check' ? 'update' : row.path.startsWith('api ') ? 'api' : row.path;
+        const command = commands.find(command => command.path.join(' ') === path);
+        const gap = commandGap(row.path) ?? command?.gap;
+        const flags = row.flags.map(flag => {
+            const name = flag.name === '-X' ? 'method' : flag.name.replace(/^--/, '');
+            const meta = command?.flags[name];
+            return { ...flag, status: !meta || meta.gap || gap ? 'gap' : 'available with owned semantics',
+                contract: gap ?? meta?.gap ?? 'Use command help; baseline semantic parity is not claimed by flag acceptance' };
+        });
+        return id ? { ...row, status: gap ? 'gap' : 'partial', gap: gap ?? null, flags } :
+            { id: row.id, command: 'gitea-axi ' + row.path, status: gap ? 'gap' : 'partial', flags: flags.length };
+    });
+    return { baseline: 'gh-axi 0.1.46', target: 'Gitea 1.23.4',
+        counts: { commands: baseline.length, commandFlags: baseline.reduce((count, row) => count + row.flags.length, 0), globals: 4, prFields: fields.length, fullParity: 0 },
+        commands: rows,
+        ...(id ? {} : { globals: [
+                { selector: '-R/--repo', contract: 'Explicit repository before matching local remote; stack rejects it and GH_REPO' },
+                { selector: '--hostname/GH_HOST', contract: 'Select exactly one matching configured profile by host and port; exact tokenOrigin binding applies before secret resolution' },
+                { selector: '--help', contract: 'Offline registry-derived help' },
+                { selector: '-v/-V/--version', contract: 'Offline packaged version' },
+            ], prFields: fields.map(field => ({ field, contract: field === 'id' ? 'gap: GraphQL node ID unavailable; fullDatabaseId is the numeric vendor ID' :
+                    field === 'statusCheckRollup' ? 'partial commit statuses only; excludes full check suites' :
+                        ['autoMergeRequest', 'closingIssuesReferences', 'mergeStateStatus', 'potentialMergeCommit', 'projectCards', 'projectItems', 'reviewDecision'].includes(field) ? 'gap: no evidenced Gitea 1.23.4 field contract' : 'owned normalized field; see pr view --fields' })) }),
+        help: id ? ['gitea-axi capabilities'] : ['gitea-axi capabilities C038'],
+    };
+}

package/dist/ci.js

@@ -0,0 +1,24 @@
+import { collect } from './api.js';
+import { CliError } from './error.js';
+import { continuationHelp, positive, selectedFields } from './reads.js';
+export const taskFields = ['id', 'name', 'display_title', 'workflow_id', 'head_branch', 'head_sha', 'event', 'status', 'run_number', 'url', 'created_at', 'updated_at', 'run_started_at'];
+export function validateTasks(options) {
+    positive(options.limit, 10, 1000);
+    selectedFields(options, taskFields, []);
+}
+export async function tasks(client, base, options) {
+    const page = await collect(client, base + '/actions/tasks', 'workflow_runs').catch((error) => {
+        if (error instanceof CliError && error.code === 'NOT_FOUND_OR_HIDDEN')
+            throw new CliError('CAPABILITY_GAP', 'Actions task reads are unavailable or hidden on this server; full workflow run APIs require Gitea 1.24 or later');
+        throw error;
+    });
+    const mapping = { workflow: 'workflow_id', branch: 'head_branch', status: 'status', event: 'event', commit: 'head_sha' };
+    const rows = page.items.filter(row => Object.entries(mapping).every(([flag, field]) => options[flag] === undefined || row[field] === options[flag]));
+    const limit = positive(options.limit, 10, 1000);
+    const fields = selectedFields(options, taskFields, []) ?? ['id', 'name', 'status'];
+    return { items: rows.slice(0, limit).map(row => Object.fromEntries(fields.map(field => [field, row[field] ?? null]))), count: Math.min(rows.length, limit),
+        total: page.truncated ? null : rows.length, unfiltered_total: page.total, next: page.next, truncated: page.truncated || rows.length > limit, continuation: page.truncated || rows.length > limit,
+        help: [...continuationHelp(page, rows.length, limit), ...(page.items.length === 0 ? ['No task summaries returned. Gitea older than 1.24 may return an empty task list even when workflow runs exist; this does not establish that there are no runs.'] : [])],
+        scope: 'Gitea 1.23.4 ActionTask summaries; task/run identity pending commissioning. Status does not establish job conclusions or terminal run results.',
+        pending: ['run details, watch, logs, artifacts and controls', '1.24.0 workflow routes require representative commissioning', 'mutations require the shared write gate'] };
+}

package/dist/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+const args = process.argv.slice(2);
+if (args.length === 1 && ['--version', '-v', '-V'].includes(args[0] ?? '')) {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(pkg.version);
+}
+else {
+    const { main } = await import('./main.js');
+    await main(args);
+}