@knowttl/gitea-axi 0.1.0 → 0.1.2

package/dist/api.js

@@ -10,6 +10,12 @@ const required = {
     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])
@@ -23,6 +29,17 @@ for (const definition of Object.values(vendor.definitions)) {
         }
     }
 }
+const requestDefinitions = structuredClone(vendor.definitions);
+for (const [name, fields] of Object.entries({
+    PullRequest: ['merge_commit_sha'],
+    ContentsResponse: ['submodule_git_url', 'target', 'content', 'encoding', 'download_url', 'html_url', 'git_url'],
+    FileLinksResponse: ['git', 'html'],
+})) {
+    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) {
@@ -30,8 +47,48 @@ export function object(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 => {
+        if (/^\{[^}]+\}$/.test(part))
+            return route.multiSegmentParameters?.includes(part.slice(1, -1)) ? '[^/]+(?:/[^/]+)*' : '[^/]+';
+        return 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 = routes.find(route => new RegExp('^' + route.path.replace(/[.]/g, '\\.').replace(/\{[^}]+\}/g, '[^/]+') + '$').test(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')
@@ -47,39 +104,52 @@ export function validate(path, value) {
     if (route.schema) {
         let validator = validators.get(route.path);
         if (!validator) {
-            validator = ajv.compile({ ...route.schema, definitions: vendor.definitions });
+            const schema = route.operation === 'repoGetContents' ? { anyOf: [route.schema, { type: 'array', items: route.schema }] } : route.schema;
+            validator = ajv.compile({ ...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) {
-    let decoded;
-    try {
-        decoded = decodeURIComponent(input);
-    }
-    catch {
-        throw new CliError('USAGE', 'Malformed API path', 2);
-    }
-    if (/^[a-z]+:/i.test(input) || input.startsWith('//') || /[\\#\s]/.test(decoded) || decoded.includes('%') ||
-        decoded.split(/[/?]/).some(part => part === '.' || part === '..'))
+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);
-    const [pathname, query = ''] = input.split('?');
     for (const key of new URLSearchParams(query).keys()) {
         if (/token|secret|password|authorization|api.?key/i.test(key))
-            throw new CliError('CONFIG_INVALID', 'Secret query fields are refused');
+            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')
+    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)
@@ -97,7 +167,8 @@ export async function rawRead(client, path) {
     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 paginated = routeFor(path).paginated;
+    let next = paginated ? path + (path.includes('?') ? '&' : '?') + 'limit=50&page=1' : path;
     const seenPages = new Set();
     const items = new Map();
     let total = null;
@@ -112,7 +183,7 @@ export async function collect(client, path, envelope) {
             throw new CliError('INVALID_RESPONSE', 'Expected a Gitea list' + (envelope ? ' envelope ' + envelope : ''));
         for (const value of rows) {
             const row = object(value);
-            const id = row.id ?? row.number ?? row.sha ?? row.filename ?? (row.user && row.content ? String(object(row.user).id) + ':' + row.content : undefined);
+            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);
@@ -124,11 +195,11 @@ export async function collect(client, path, envelope) {
             total = object(data).total_count;
         const link = response.headers.get('link');
         next = nextPage(response.headers, path, client.origin);
-        if (!next && !link && rows.length >= 50) {
+        if (paginated && !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 };
+    return { items: [...items.values()].slice(0, 1000), total: total ?? (!paginated && !next ? items.size : null), next, truncated: next !== null || items.size > 1000 };
 }

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/credentials.js

@@ -1,12 +1,45 @@
 import { readFileSync, existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
 import { Ajv } from 'ajv';
 import { CliError } from './error.js';
 import { readPrivateFile } from './private-file.js';
 const schema = JSON.parse(readFileSync(new URL('../axi-credential.schema.json', import.meta.url), 'utf8'));
-const validate = new Ajv({ strict: false }).compile(schema);
+const validate = new Ajv({ strict: false, allErrors: true }).compile(schema);
+function validateProfile(profile) {
+    if (validate(profile))
+        return;
+    const value = profile && typeof profile === 'object' ? profile : undefined;
+    const token = value && 'token' in value ? value.token : undefined;
+    const branch = token && typeof token === 'object' ? 'env' in token ? '0' : 'file' in token ? '1' : undefined : undefined;
+    const http = value && 'origin' in value && typeof value.origin === 'string' && value.origin.startsWith('http:');
+    const errors = (validate.errors ?? []).filter(error => {
+        const alternative = error.schemaPath.match(/^#\/properties\/token\/oneOf\/(\d+)\//)?.[1];
+        return (!alternative || alternative === branch) && (!error.schemaPath.startsWith('#/then/') || http) && error.keyword !== 'if' && error.keyword !== 'oneOf';
+    });
+    const priority = { required: 0, additionalProperties: 1 };
+    const error = errors.find(error => error.schemaPath === '#/required') ?? errors.sort((a, b) => (priority[a.keyword] ?? 2) - (priority[b.keyword] ?? 2) || b.instancePath.split('/').length - a.instancePath.split('/').length)[0] ?? validate.errors?.find(error => error.keyword === 'oneOf');
+    const property = error?.keyword === 'required' ? error.params.missingProperty : error?.keyword === 'additionalProperties' ? error.params.additionalProperty : undefined;
+    const field = [...(error?.instancePath.split('/').slice(1) ?? []), ...(property ? [String(property)] : [])].join('.');
+    if (field === 'allowInsecureHttp' && error?.schemaPath.startsWith('#/then/'))
+        throw new CliError('CONFIG_INVALID', 'HTTP requires allowInsecureHttp: true on the selected profile');
+    const correction = error?.keyword === 'additionalProperties' ? 'remove this unknown field' :
+        field === 'token.file' ? 'set an absolute local file path' :
+            field === 'token.env' ? 'set a valid environment variable name' :
+                field === 'token' ? 'set exactly one of env (an environment variable name) or file (an absolute local path)' :
+                    field === 'allowInsecureHttp' ? 'set true or false' :
+                        error?.keyword === 'required' ? 'set this required field' : 'use a value matching the credential profile schema';
+    throw new CliError('CONFIG_INVALID', 'Invalid profile field: ' + (field || 'profile') + '; ' + correction);
+}
 const secrets = [];
+export function registerSecret(value) { if (value)
+    secrets.push(value); }
+const controls = new Set();
+export function controlText(value) {
+    controls.add(value);
+    return value;
+}
 export function redact(value) {
     if (Array.isArray(value))
         return value.map(redact);
@@ -15,6 +48,10 @@ export function redact(value) {
             /^(?:token|access_token|refresh_token|password|secret|authorization|private_key)$/i.test(key) ? '[REDACTED]' : redact(item)]));
     if (typeof value !== 'string')
         return value;
+    // Callers register only generated control text, never payloads or upstream response text.
+    const preserved = [...controls].filter(text => value.includes(text)).sort((a, b) => b.length - a.length);
+    if (preserved.length)
+        return value.split(new RegExp('(' + preserved.map(text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|') + ')')).map(part => controls.has(part) ? part : redact(part)).join('');
     let output = value;
     for (const secret of secrets) {
         for (const form of [secret, JSON.stringify(secret).slice(1, -1), encodeURIComponent(secret)]) {
@@ -69,11 +106,31 @@ export function canonicalOrigin(value) {
 export async function credentials(override, allowHttp, options = {}) {
     const path = configPath(options.config);
     const selected = options.profile ?? process.env.GITEA_AXI_PROFILE;
+    const hostname = options.hostname ?? (selected === 'artium' ? undefined : process.env.GH_HOST);
+    if (hostname === '')
+        throw new CliError('USAGE', '--hostname/GH_HOST requires a nonempty host', 2);
+    const matchesHost = (origin) => {
+        const url = new URL(canonicalOrigin(origin));
+        if (!hostname || /[\s\\/?#@]/.test(hostname))
+            throw new CliError('USAGE', '--hostname/GH_HOST requires a host with optional port', 2);
+        let host;
+        try {
+            host = new URL(url.protocol + '//' + hostname);
+        }
+        catch {
+            throw new CliError('USAGE', '--hostname/GH_HOST requires a host with optional port', 2);
+        }
+        return url.host === host.host;
+    };
     const fields = ['ORIGIN', 'TOKEN_ORIGIN', 'TOKEN', 'ALLOW_INSECURE_HTTP'];
     const hasEnv = fields.some(field => process.env['GITEA_AXI_' + field] !== undefined);
     let profile;
     let profileName = 'environment';
+    let revision = 'environment';
     if (!selected && hasEnv) {
+        const missing = ['ORIGIN', 'TOKEN_ORIGIN', 'TOKEN'].filter(field => !process.env['GITEA_AXI_' + field]);
+        if (missing.length)
+            throw new CliError('CONFIG_INVALID', 'Set missing environment variables: ' + missing.map(field => 'GITEA_AXI_' + field).join(', '));
         let token;
         try {
             token = JSON.parse(process.env.GITEA_AXI_TOKEN ?? 'null');
@@ -87,18 +144,30 @@ export async function credentials(override, allowHttp, options = {}) {
     }
     else if (existsSync(path)) {
         const config = await readConfig(path);
-        const names = Object.keys(config.profiles);
-        const name = selected ?? config.defaultProfile ?? (names.length === 1 ? names[0] : undefined);
+        const names = Object.keys(config.profiles).filter(name => {
+            if (!hostname)
+                return true;
+            const profile = config.profiles[name];
+            validateProfile(profile);
+            return matchesHost(profile.origin);
+        });
+        if (hostname && !selected && !names.length)
+            throw new CliError('PROFILE_NOT_FOUND', 'No configured profile matches --hostname/GH_HOST');
+        const name = selected ?? (hostname ? names.length === 1 ? names[0] : undefined : config.defaultProfile ?? (names.length === 1 ? names[0] : undefined));
         if (!name)
             throw new CliError(names.length ? 'PROFILE_AMBIGUOUS' : 'PROFILE_REQUIRED', 'Select a profile');
         if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name) || !Object.hasOwn(config.profiles, name))
             throw new CliError('PROFILE_NOT_FOUND', 'Selected profile was not found');
         profile = config.profiles[name];
         profileName = name;
+        revision = process.env.GITEA_AXI_CREDENTIAL_REVISION ?? String((await stat(path, { bigint: true })).mtimeNs);
     }
     else if (selected || options.config || process.env.GITEA_AXI_CONFIG) {
         throw new CliError('PROFILE_NOT_FOUND', 'Selected profile configuration was not found');
     }
+    else if (hostname) {
+        throw new CliError('PROFILE_NOT_FOUND', '--hostname/GH_HOST requires a matching configured profile');
+    }
     else if (override) {
         const origin = canonicalOrigin(override);
         if (origin.startsWith('http:') && !allowHttp)
@@ -108,9 +177,10 @@ export async function credentials(override, allowHttp, options = {}) {
     else {
         throw new CliError('AUTH_REQUIRED', 'Select a configured profile or an explicit anonymous --origin');
     }
-    if (!validate(profile))
-        throw new CliError('CONFIG_INVALID', 'Invalid profile field: ' + (validate.errors?.[0]?.instancePath || 'token/origin'));
+    validateProfile(profile);
     const origin = canonicalOrigin(profile.origin);
+    if (hostname && !matchesHost(origin))
+        throw new CliError('AUTH_BINDING_MISMATCH', 'Selected profile does not match --hostname/GH_HOST');
     if (origin !== canonicalOrigin(profile.tokenOrigin) || (override && canonicalOrigin(override) !== origin)) {
         throw new CliError('AUTH_BINDING_MISMATCH', 'origin must match tokenOrigin before resolving token');
     }
@@ -123,11 +193,13 @@ export async function credentials(override, allowHttp, options = {}) {
         if (!isAbsolute(profile.token.file) || /^\\\\/.test(profile.token.file))
             throw new CliError('CONFIG_INVALID', 'token file must be an absolute local path');
         token = (await readPrivateFile(profile.token.file, true)).replace(/^\uFEFF/, '').trimEnd();
+        revision += ':' + String((await stat(profile.token.file, { bigint: true })).mtimeNs);
     }
     if (!token)
         throw new CliError('AUTH_REQUIRED', 'token reference is empty');
     secrets.push(token);
     if (/[\r\n]/.test(token))
         throw new CliError('CONFIG_INVALID', 'token must be a single line');
-    return { origin, token, profile: profileName, source: 'env' in profile.token ? 'env:' + profile.token.env : 'file:' + profile.token.file };
+    return { origin, token, profile: profileName, revision, source: 'env' in profile.token ? 'env:' + profile.token.env : 'file:' + profile.token.file,
+        ...(profile.writes ? { writes: profile.writes } : {}) };
 }