@knowttl/gitea-axi 0.1.0 → 0.1.1

package/dist/local-workflows.js

@@ -0,0 +1,222 @@
+import { existsSync } from 'node:fs';
+import { mkdir, open, readdir, realpath, rm } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { Git } from './git.js';
+import { CliError } from './error.js';
+import { collect, object, read, resolveCommit } from './api.js';
+import { repoPath, repositoryPlan, validateRepositoryWorkflow } from './repo-workflows.js';
+import { verifyPull } from './pulls.js';
+import { readPrivateFile, writePrivateFile } from './private-file.js';
+import { write } from './writes.js';
+import { stackWorkflow } from './stacks.js';
+export const usage = (message) => { throw new CliError('USAGE', message, 2); };
+export const gap = (message) => { throw new CliError('CAPABILITY_GAP', message); };
+export const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+export function isLocal(operation, options) {
+    return operation.startsWith('stack ') || ['repo clone', 'pr checkout', 'pr revert'].includes(operation) ||
+        ['repo create', 'repo fork'].includes(operation) && ['source', 'push', 'remote', 'clone', 'workspace'].some(key => options[key] !== undefined);
+}
+export function validateLocal(operation, options) {
+    if (process.env.GITEA_AXI_HOST_WRITE_OPERATIONS !== undefined || process.env.GITEA_AXI_CREDENTIAL_REVISION !== undefined) {
+        throw new CliError('READ_ONLY', 'Workspace workflows are standalone only');
+    }
+    if (operation.startsWith('stack ') && (options.repo || process.env.GH_REPO))
+        usage('Stack commands reject -R/--repo and GH_REPO; use the explicit local workspace');
+    if (typeof options.workspace !== 'string' || !isAbsolute(options.workspace))
+        usage('--workspace requires an explicit absolute path');
+    if (options.config !== undefined && !isAbsolute(String(options.config)))
+        usage('--config must be absolute');
+}
+export async function localEffect(client, identity, operation, options, git, preconditions, payload, execute, api) {
+    const step = { method: 'LOCAL', path: git.cwd, local: 'gitea.local.' + operation, payload };
+    const plan = api ? { ...api, steps: [...api.steps, step], preconditions: { api: api.preconditions, workspace: preconditions } } :
+        { target: git.cwd, steps: [step], reads: [], preconditions };
+    // Keep API verification preconditions in their original shape for the existing verifier.
+    if (api)
+        plan.preconditions = { ...object(api.preconditions), localWorkspace: preconditions };
+    return write(client, identity, plan, options, execute);
+}
+export async function localWorkflow(client, identity, operation, args, options) {
+    if (operation.startsWith('stack '))
+        return stackWorkflow(client, identity, operation.slice(6), args, options);
+    const workspace = await realpath(String(options.workspace));
+    const git = new Git(workspace, identity.origin, identity.token);
+    if (operation === 'repo clone') {
+        if (args.length !== 1)
+            usage('Select one OWNER/NAME to clone');
+        const name = args[0];
+        const url = git.url(name);
+        const destination = join(workspace, name.split('/')[1]);
+        if (existsSync(destination))
+            usage('Clone destination already exists');
+        const repo = object(await read(client, repoPath(name)));
+        if (repo.full_name !== name)
+            throw new CliError('INVALID_RESPONSE', 'Repository identity differs from the selected clone target');
+        const expected = await resolveCommit(client, repoPath(name), String(repo.default_branch));
+        const preconditions = { parent: workspace, contents: await readdir(workspace), repository: repo, commit: expected.sha };
+        return localEffect(client, identity, 'clone', options, git, preconditions, { url, destination }, async () => {
+            if (existsSync(destination) || !same(await readdir(workspace), preconditions.contents))
+                throw new CliError('CONFIRMATION_MISMATCH', 'Clone parent changed');
+            await git.run(['clone', '--no-checkout', '--', url, destination]);
+            const clone = await new Git(destination, identity.origin, identity.token).workspace();
+            await clone.run(['checkout', '--detach', String(expected.sha)]);
+            if (await clone.tip() !== expected.sha)
+                throw new CliError('READBACK_MISMATCH', 'Clone head differs from the previewed default commit');
+            return { workspace: destination, head: expected.sha, remote: await clone.remote('origin') };
+        });
+    }
+    if (operation === 'repo create' || operation === 'repo fork') {
+        if (args.length > 1)
+            usage('Select at most one repository');
+        if (operation === 'repo create' && (options.push || options.remote) && !options.source || options.push && !options.source)
+            usage('--push and repository creation --remote require --source');
+        if (options.source && options.clone)
+            usage('Choose --source or --clone');
+        const apiOptions = { ...options };
+        for (const key of ['source', 'push', 'remote', 'clone', 'workspace'])
+            delete apiOptions[key];
+        validateRepositoryWorkflow(operation, apiOptions);
+        const api = await repositoryPlan(client, operation, args[0], apiOptions);
+        const destinationName = String(api.workflow.expected.full_name);
+        const url = git.url(destinationName);
+        let source;
+        let preconditions;
+        const remote = String(options.remote ?? 'origin');
+        if (!/^[A-Za-z0-9_-]+$/.test(remote))
+            usage('Select a simple remote name');
+        const destination = join(workspace, destinationName.split('/')[1]);
+        if (options.source || operation === 'repo fork' && options.remote && !options.clone) {
+            const sourcePath = String(options.source ?? workspace);
+            if (!isAbsolute(sourcePath))
+                usage('--source requires an absolute native repository root');
+            source = await new Git(await realpath(sourcePath), identity.origin, identity.token).workspace();
+            if (source.cwd !== workspace)
+                usage('--source must equal the explicit --workspace');
+            await source.clean();
+            if (options.push && !await source.run(['symbolic-ref', '--quiet', '--short', 'HEAD'], [0, 1]))
+                usage('Publishing requires a named source branch');
+            if ((await source.run(['remote'])).split('\n').includes(remote))
+                usage('Selected remote already exists; choose another --remote');
+            preconditions = await source.snapshot();
+        }
+        else if (options.clone) {
+            if (existsSync(destination))
+                usage('Clone destination already exists');
+            preconditions = { parent: workspace, contents: await readdir(workspace) };
+        }
+        else
+            usage('Workspace composite requires --source or --clone');
+        return localEffect(client, identity, 'composite', options, git, preconditions, { source: source?.cwd, remote, url, clone: Boolean(options.clone), push: Boolean(options.push) }, async () => {
+            if (source) {
+                if (!same(await source.snapshot(), preconditions))
+                    throw new CliError('CONFIRMATION_MISMATCH', 'Source changed after API creation; repository created, local publication stopped');
+                await source.run(['remote', 'add', remote, url]);
+                if (options.push) {
+                    const branch = await source.run(['symbolic-ref', '--short', 'HEAD']);
+                    await source.run(['push', '--', url, 'refs/heads/' + branch + ':refs/heads/' + branch]);
+                    if (!(await source.run(['ls-remote', '--', url, 'refs/heads/' + branch])).startsWith(await source.tip()))
+                        throw new CliError('READBACK_MISMATCH', 'Published head was not confirmed');
+                }
+                return { workspace, remote, published: Boolean(options.push), head: await source.tip() };
+            }
+            if (existsSync(destination))
+                throw new CliError('CONFIRMATION_MISMATCH', 'Clone destination appeared; API repository was created');
+            await git.run(['clone', '--origin', remote, '--', url, destination]);
+            return { workspace: destination, remote };
+        }, api);
+    }
+    await git.workspace();
+    await git.clean();
+    if (args.length !== 1 || !/^[1-9]\d*$/.test(args[0]))
+        usage('Select one positive PR number');
+    const remote = await git.remote('origin');
+    if (options.repo && options.repo !== remote.repository)
+        usage('--repo must match the workspace origin remote');
+    const base = repoPath(remote.repository);
+    const pull = object(await read(client, base + '/pulls/' + args[0]));
+    const snapshot = await git.snapshot();
+    if (operation === 'pr checkout') {
+        const head = object(pull.head);
+        const headRepository = object(head.repo);
+        const url = git.url(String(headRepository.full_name));
+        if (!/^[a-f0-9]{40}$/.test(String(head.sha)))
+            throw new CliError('INVALID_RESPONSE', 'PR head requires an exact commit SHA');
+        await git.branch(String(head.ref));
+        return localEffect(client, identity, 'checkout', options, git, { snapshot, pull, remote }, { url, ref: head.ref, sha: head.sha }, async () => {
+            if (!same(snapshot, await git.snapshot()))
+                throw new CliError('CONFIRMATION_MISMATCH', 'Workspace changed');
+            await git.run(['fetch', '--no-tags', '--', url, 'refs/heads/' + head.ref]);
+            if (await git.tip('FETCH_HEAD') !== head.sha)
+                throw new CliError('STALE_HEAD', 'Fetched PR branch differs from the previewed head; checkout stopped');
+            await git.run(['checkout', '--detach', String(head.sha)]);
+            return { workspace, head: await git.tip() };
+        });
+    }
+    if (pull.merged !== true || !/^[a-f0-9]{40}$/.test(String(pull.merge_commit_sha)))
+        usage('Revert requires a merged PR with an exact merge commit');
+    const branch = 'revert-' + args[0] + '-' + String(pull.merge_commit_sha).slice(0, 12);
+    const baseBranch = await git.branch(String(object(pull.base).ref));
+    const recordPath = join(await git.run(['rev-parse', '--path-format=absolute', '--git-common-dir']), 'gitea-axi', branch + '.json');
+    if ((await git.run(['for-each-ref', '--format=%(refname:short)', 'refs/heads/' + branch])) === branch) {
+        if (snapshot.branch !== branch)
+            usage('Check out the generated revert branch before previewing its publication');
+        if (!existsSync(recordPath))
+            usage('The branch has no recorded revert provenance; inspect the existing branch before publication');
+        const record = object(await load(recordPath));
+        if (record.merge !== pull.merge_commit_sha || record.head !== snapshot.head || record.repository !== remote.repository || record.origin !== identity.origin) {
+            throw new CliError('CONFIRMATION_MISMATCH', 'The generated revert branch or its origin-bound provenance changed');
+        }
+        const pulls = await collect(client, base + '/pulls?state=all');
+        if (pulls.truncated)
+            throw new CliError('INCOMPLETE_READ', 'Revert publication requires a complete PR collection');
+        if (pulls.items.some(item => object(item.head).ref === branch))
+            usage('The revert branch already has a PR; inspect it before repeating');
+        const payload = { title: 'Revert "' + String(pull.title) + '"', body: 'Reverts #' + args[0], head: branch, base: baseBranch };
+        const local = { method: 'LOCAL', path: workspace, local: 'gitea.local.revert' };
+        const plan = { target: base + '/pulls', reads: [],
+            preconditions: { snapshot, pull, remote, pulls: pulls.items },
+            steps: [{ ...local, payload: { phase: 'push', branch, sha: snapshot.head } },
+                { method: 'POST', path: base + '/pulls', payload }, { ...local, payload: { phase: 'verify', payload } }] };
+        return write(client, identity, plan, options, async (step, results) => {
+            if (object(step.payload).phase === 'push') {
+                if (!same(snapshot, await git.snapshot()))
+                    throw new CliError('CONFIRMATION_MISMATCH', 'Revert branch changed');
+                await git.run(['push', '--', remote.url, 'refs/heads/' + branch + ':refs/heads/' + branch]);
+                return { branch, head: snapshot.head };
+            }
+            const created = object(results[1]);
+            const actual = object(await read(client, base + '/pulls/' + created.number));
+            if (actual.id !== created.id || object(actual.head).sha !== snapshot.head || object(actual.head).ref !== branch ||
+                object(actual.base).ref !== baseBranch || actual.title !== payload.title || actual.body !== payload.body) {
+                throw new CliError('READBACK_MISMATCH', 'Revert PR did not confirm its exact branch and generated commit');
+            }
+            return { pull: actual, branch, head: snapshot.head };
+        });
+    }
+    const preconditions = { snapshot, pull, remote };
+    return localEffect(client, identity, 'revert', options, git, preconditions, { branch, baseBranch, merge: pull.merge_commit_sha }, async () => {
+        await git.run(['fetch', '--no-tags', '--', remote.url, 'refs/heads/' + baseBranch]);
+        await git.run(['checkout', '-b', branch, 'FETCH_HEAD']);
+        const parents = (await git.run(['rev-list', '--parents', '-n', '1', String(pull.merge_commit_sha)])).split(' ');
+        if (parents.length !== 3)
+            gap('Revert currently requires a two-parent merge commit; branch retained without a revert');
+        await git.run(['revert', '--no-edit', '-m', '1', String(pull.merge_commit_sha)]);
+        await save(recordPath, { merge: pull.merge_commit_sha, head: await git.tip(), repository: remote.repository, origin: identity.origin });
+        return { branch, head: await git.tip(), state: 'local revert prepared',
+            next: 'Repeat pr revert ' + args[0] + ' with --preview to bind publication of the generated commit and creation of its revert PR' };
+    });
+}
+export async function lock(directory) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, 'lock');
+    const file = await open(path, 'wx', 0o600).catch(() => { throw new CliError('STACK_LOCKED', 'Stack mutation is locked; inspect the owning process before manual recovery'); });
+    return async () => { await file.close(); await rm(path); };
+}
+export async function verifyPlannedPull(client, plan, result) {
+    const observations = [];
+    for (const path of plan.reads)
+        observations.push({ path, data: await read(client, path) });
+    await verifyPull(client, plan, [result], observations);
+}
+export async function save(path, value) { await writePrivateFile(path, JSON.stringify(value)); }
+export async function load(path) { return JSON.parse(await readPrivateFile(path, true, 1_000_000)); }

package/dist/main.js

@@ -4,34 +4,83 @@ import { encode } from '@toon-format/toon';
 import { commands } from './registry.js';
 import { CliError } from './error.js';
 import { readRepository } from './repository.js';
-import { configPath, credentials, profileList, redact } from './credentials.js';
+import { configPath, credentials, profileList, redact, registerSecret } from './credentials.js';
 import { Client } from './transport.js';
 import { collect, object, rawPath, rawRead, read } from './api.js';
 import { boundedList, issueFields, listIssues, listOptions, positive, prFields, repository, selectedFields, view, watchChecks } from './reads.js';
+import { tasks, validateTasks } from './ci.js';
+import { search, validateSearch } from './search.js';
+import { issueLabelPlan, rawWritePlan, reconcile, write } from './writes.js';
+import { readPrivateFile } from './private-file.js';
+import { pullPlan, validatePull } from './pulls.js';
+import { repositoryPlan, validateRepositoryWorkflow } from './repo-workflows.js';
+import { releaseListFields, releasePlan, releaseRead, validateRelease } from './releases.js';
+import { actionValues, valuePlan } from './action-values.js';
+import { assetPath, attachToPlan, download, uploadPlan } from './attachments.js';
+import { isLocal, localWorkflow, validateLocal } from './local-workflows.js';
+import { capabilityOutput, commandGap } from './catalogue.js';
+async function input(path) {
+    if (path !== '-')
+        return readPrivateFile(path, true, 1_000_000);
+    process.stdin.setEncoding('utf8');
+    let body = '';
+    for await (const chunk of process.stdin) {
+        body += String(chunk);
+        if (Buffer.byteLength(body) > 1_000_000)
+            throw new CliError('USAGE', 'Input exceeds 1000000 bytes', 2);
+    }
+    return body;
+}
 export async function main(args) {
-    let operation = 'dashboard';
+    let operation = args[0] && !args[0].startsWith('-') ? args[0] : 'dashboard';
     try {
+        for (const arg of args) {
+            const match = /^(?:--(?:raw-)?field=)?data=([\s\S]*)$/.exec(arg);
+            if (match)
+                registerSecret(match[1]);
+        }
         if (args.some(arg => /^--(?:token|api-key|password|authorization)(?:=|$)/i.test(arg))) {
             throw new CliError('CONFIG_INVALID', 'token and other secret arguments are not accepted');
         }
-        const path = args.length === 0 || args[0]?.startsWith('--') ? ['dashboard'] : args.slice(0, ['api', 'doctor', 'dashboard'].includes(args[0]) ? 1 : 2);
-        const command = commands.find(command => command.path.join(' ') === path.join(' '));
-        if (!command)
-            throw new CliError('USAGE', 'Unknown command; use gitea-axi --help', 2);
+        const command = args.length === 0 || args[0]?.startsWith('--') ? commands.find(command => command.path[0] === 'dashboard') :
+            [...commands].sort((a, b) => b.path.length - a.path.length).find(command => command.path.every((part, index) => args[index] === part));
+        if (!command) {
+            const children = commands.filter(command => command.path[0] === args[0]);
+            if (children.length && args.length === 2 && args[1] === '--help') {
+                console.log(encode({ command: 'gitea-axi ' + operation, commands: children.map(command => 'gitea-axi ' + command.path.join(' ')) }));
+                return;
+            }
+            throw new CliError('USAGE', children.length ? 'Choose a command: ' + children.map(command => 'gitea-axi ' + command.path.join(' ')).join(', ') : 'Unknown command; use gitea-axi --help', 2);
+        }
+        const path = command.path;
         operation = command.path.join(' ');
         const rest = args[0]?.startsWith('--') || !args.length ? args : args.slice(path.length);
         let parsed;
         try {
+            const options = Object.fromEntries(Object.entries(command.flags).map(([name, flag]) => [name, { type: flag.type,
+                    ...(flag.multiple ? { multiple: true } : {}), ...(flag.short ? { short: flag.short } : {}) }]));
+            const tokens = parseArgs({ args: rest, allowPositionals: true, strict: false, tokens: true, options }).tokens;
+            const normalized = tokens.map(token => {
+                if (token.kind === 'positional')
+                    return token.value;
+                if (token.kind === 'option-terminator')
+                    return '--';
+                const boolean = command.flags[token.name]?.type === 'boolean' && /^(true|false)$/.test(token.value ?? '');
+                return '--' + token.name + (token.value !== undefined && !boolean ? '=' + token.value : '');
+            });
             parsed = parseArgs({
-                args: rest, allowPositionals: true, strict: true, tokens: true,
-                options: Object.fromEntries(Object.entries(command.flags).map(([name, flag]) => [name, { type: flag.type }])),
+                args: normalized, allowPositionals: true, strict: true, tokens: true, options,
             });
+            for (const token of tokens) {
+                if (token.kind === 'option' && command.flags[token.name]?.type === 'boolean' && /^(true|false)$/.test(token.value ?? ''))
+                    parsed.values[token.name] = token.value === 'true';
+            }
         }
         catch {
             throw new CliError('USAGE', 'Invalid arguments; valid flags: ' + Object.keys(command.flags).map(f => '--' + f).join(', '), 2);
         }
         const { values, positionals } = parsed;
-        const names = parsed.tokens.filter(token => token.kind === 'option').map(token => token.name);
+        const names = parsed.tokens.flatMap(token => token.kind === 'option' && !command.flags[token.name]?.multiple ? [token.name] : []);
         if (new Set(names).size !== names.length) {
             throw new CliError('USAGE', 'Choose each flag only once; --repo requires exactly one selector', 2);
         }
@@ -44,15 +93,106 @@ export async function main(args) {
             return;
         }
         const options = values;
-        const takesNumber = ['issue view', 'pr view', 'pr checks', 'pr diff'].includes(operation);
+        if (operation === 'capabilities') {
+            if (positionals.length > 1)
+                throw new CliError('USAGE', 'Use capabilities [C001-C124]', 2);
+            console.log(encode(capabilityOutput(commands, prFields, positionals[0])));
+            return;
+        }
+        if (command.gap)
+            throw new CliError('CAPABILITY_GAP', command.gap);
+        for (const name of Object.keys(values)) {
+            if (command.flags[name]?.gap)
+                throw new CliError('CAPABILITY_GAP', command.flags[name].gap);
+        }
+        if (operation === 'api' && (options.method === 'HEAD' || positionals[0] === 'HEAD'))
+            throw new CliError('CAPABILITY_GAP', commandGap('api HEAD'));
+        if ((process.env.GITEA_AXI_PROFILE === 'artium' || process.env.GITEA_AXI_CREDENTIAL_REVISION !== undefined) &&
+            ['origin', 'profile', 'config', 'hostname', 'allow-insecure-http'].some(name => options[name] !== undefined)) {
+            throw new CliError('READ_ONLY', 'Hosted calls refuse credential and configuration overrides');
+        }
+        if (isLocal(operation, options)) {
+            validateLocal(operation, options);
+            const identity = await credentials(typeof options.origin === 'string' ? options.origin : undefined, Boolean(options['allow-insecure-http']), {
+                ...(typeof options.config === 'string' ? { config: options.config } : {}), ...(typeof options.profile === 'string' ? { profile: options.profile } : {}),
+                ...(typeof options.hostname === 'string' ? { hostname: options.hostname } : {}),
+            });
+            const output = await localWorkflow(new Client(identity.origin, identity.token, 300_000), identity, operation, positionals, options);
+            const rendered = encode(redact(output));
+            if (rendered.length > 100_000)
+                throw new CliError('OUTPUT_LIMIT', 'Rendered output exceeds 100000 characters');
+            console.log(rendered);
+            return;
+        }
+        const valuesCommand = operation.startsWith('secret ') || operation.startsWith('variable ');
+        const secretCommand = operation.startsWith('secret ');
+        let protectedValue;
+        if (valuesCommand) {
+            if (options.org && options.repo)
+                throw new CliError('USAGE', 'Choose --org or --repo', 2);
+            if (options.org && (!/^[A-Za-z0-9_.-]+$/.test(String(options.org)) || ['.', '..'].includes(String(options.org))))
+                throw new CliError('USAGE', 'Select an organization name', 2);
+            if (operation.endsWith(' set')) {
+                if (options.input !== undefined && options.body !== undefined || options.input === undefined && options.body === undefined)
+                    throw new CliError('USAGE', 'Choose exactly one value input', 2);
+                protectedValue = options.input !== undefined ? await input(String(options.input)) : String(options.body);
+                if (secretCommand)
+                    registerSecret(protectedValue);
+            }
+        }
+        const repositoryMutation = operation.startsWith('repo ') && command.effect === 'write';
+        const releasing = operation.startsWith('release ');
+        if (repositoryMutation)
+            validateRepositoryWorkflow(operation, options);
+        if (releasing) {
+            validateRelease(options);
+            if (options.notes !== undefined)
+                options.body = options.notes;
+            if (options['notes-file'] !== undefined)
+                options['body-file'] = options['notes-file'];
+        }
+        const transferring = /^(?:issue|pr|release) (?:upload|download)$/.test(operation);
+        if (operation.startsWith('pr ') && command.effect === 'write' && !transferring)
+            validatePull(operation, options);
+        if (operation.startsWith('workflow ') || operation.startsWith('run ') && operation !== 'run list') {
+            throw new CliError('CAPABILITY_GAP', operation + ' is pending: the 1.23.4 contract has task summaries only; 1.24.0 candidates require commissioning. Mutating controls also await the shared write gate');
+        }
+        const searching = operation.startsWith('search ');
+        if (searching) {
+            if (positionals.length !== 1)
+                throw new CliError('USAGE', 'Select exactly one quoted search query', 2);
+            validateSearch(path[1], positionals[0], options);
+        }
+        if (options['body-file'] !== undefined) {
+            if (options.body !== undefined)
+                throw new CliError('USAGE', 'Choose --body or --body-file', 2);
+            options.body = await input(String(options['body-file']));
+        }
+        const takesNumber = ['issue view', 'pr view', 'pr checks', 'pr diff', 'issue download', 'pr download'].includes(operation) ||
+            (command.effect === 'write' && (operation.startsWith('issue ') || operation.startsWith('pr ')) && !operation.endsWith(' create'));
         if (takesNumber && (positionals.length !== 1 || !/^[1-9]\d*$/.test(positionals[0])))
             throw new CliError('USAGE', 'Select exactly one positive item number', 2);
-        if (!takesNumber && operation !== 'api' && operation !== 'org view' && positionals.length)
+        const takesLabel = operation === 'label edit' || operation === 'label delete';
+        const takesValue = valuesCommand && !operation.endsWith(' list');
+        if (takesValue && (positionals.length !== 1 || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(positionals[0])))
+            throw new CliError('USAGE', 'Select one secret or variable name using letters, digits and underscores', 2);
+        if (takesLabel && positionals.length !== 1)
+            throw new CliError('USAGE', 'Select one exact label name or ID', 2);
+        const takesTag = releasing && operation !== 'release list';
+        if (takesTag && (positionals.length !== 1 || !positionals[0]))
+            throw new CliError('USAGE', 'Select exactly one release tag', 2);
+        if (repositoryMutation && positionals.length > 1)
+            throw new CliError('USAGE', 'Select at most one repository', 2);
+        if (!takesNumber && !takesLabel && !takesTag && !takesValue && !repositoryMutation && !searching && operation !== 'write reconcile' && operation !== 'api' && operation !== 'org view' && positionals.length)
             throw new CliError('USAGE', 'Unexpected positional argument', 2);
+        if (operation === 'write reconcile' && positionals.length !== 1)
+            throw new CliError('USAGE', 'Select one confirmation ID', 2);
         if (operation === 'org view' && (positionals.length !== 1 || !/^[A-Za-z0-9_.-]+$/.test(positionals[0])))
             throw new CliError('USAGE', 'Select one organization name', 2);
         if (operation.endsWith('list'))
             listOptions(options);
+        if (operation === 'run list')
+            validateTasks(options);
         if (operation === 'issue view' || operation === 'issue list')
             selectedFields(options, issueFields);
         if (operation === 'pr view')
@@ -68,12 +208,55 @@ export async function main(args) {
             positive(options.interval, 5, 60);
         }
         let apiPath;
+        let method = 'GET';
+        let payload;
         if (operation === 'api') {
-            if (positionals.length === 2 && positionals[0] !== 'GET')
-                throw new CliError('READ_ONLY', 'Only GET metadata reads are available');
+            if (options.method && positionals.length === 2)
+                throw new CliError('USAGE', 'Choose -X or a positional method once', 2);
+            method = positionals.length === 2 ? positionals[0] : String(options.method ?? 'GET');
+            if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method))
+                throw new CliError('USAGE', 'Use GET, POST, PUT, PATCH or DELETE', 2);
             if (positionals.length < 1 || positionals.length > 2)
                 throw new CliError('USAGE', 'Use gitea-axi api [GET] <relative-path>', 2);
-            apiPath = rawPath(positionals.at(-1));
+            apiPath = rawPath(positionals.at(-1), method);
+            const fields = parsed.tokens.filter(token => token.kind === 'option' && ['field', 'raw-field'].includes(token.name));
+            if (fields.length) {
+                if (options.input || method === 'GET')
+                    throw new CliError('USAGE', 'Request fields require a write method and cannot combine with --input', 2);
+                const body = {};
+                for (const token of fields) {
+                    if (token.kind !== 'option')
+                        continue;
+                    const match = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/.exec(token.value ?? '');
+                    if (!match || ['__proto__', 'prototype', 'constructor'].includes(match[1]) || Object.hasOwn(body, match[1]))
+                        throw new CliError('USAGE', 'Choose unique key=value request fields', 2);
+                    if (/secret|token|password|authorization|api.?key/i.test(match[1]) || /\/secrets\//.test(apiPath))
+                        throw new CliError('CONFIG_INVALID', 'Secret fields require protected --input');
+                    const value = match[2];
+                    body[match[1]] = token.name === 'field' && /^(?:true|false|null|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?)$/.test(value) ? JSON.parse(value) : value;
+                }
+                if (Buffer.byteLength(JSON.stringify(body)) > 1_000_000)
+                    throw new CliError('USAGE', 'Request exceeds 1000000 bytes', 2);
+                payload = body;
+            }
+            if (method !== 'GET' && (!options['allow-write'] || process.env.GITEA_AXI_READ_ONLY && process.env.GITEA_AXI_READ_ONLY !== 'false'))
+                throw new CliError('READ_ONLY', 'Writes require an exact operation grant and a writable policy');
+            if (options.input) {
+                if (method === 'GET')
+                    throw new CliError('USAGE', '--input requires a write method', 2);
+                const body = await input(String(options.input));
+                registerSecret(body);
+                if (Buffer.byteLength(body) > 1_000_000)
+                    throw new CliError('USAGE', 'Request exceeds 1000000 bytes', 2);
+                try {
+                    payload = JSON.parse(body);
+                }
+                catch {
+                    throw new CliError('USAGE', 'Request must be valid JSON', 2);
+                }
+                if (/\/actions\/secrets\//.test(apiPath) && typeof object(payload).data === 'string')
+                    registerSecret(String(object(payload).data));
+            }
         }
         if (options.config && (typeof options.config !== 'string' || !isAbsolute(options.config)))
             throw new CliError('USAGE', '--config must be absolute', 2);
@@ -87,17 +270,33 @@ export async function main(args) {
         }
         const identity = await credentials(typeof values.origin === 'string' ? values.origin : undefined, Boolean(values['allow-insecure-http']), {
             ...(typeof options.config === 'string' ? { config: options.config } : {}), ...(typeof options.profile === 'string' ? { profile: options.profile } : {}),
+            ...(typeof options.hostname === 'string' ? { hostname: options.hostname } : {}),
         });
         const client = new Client(identity.origin, identity.token, operation === 'pr checks' && options.watch ? positive(options.timeout, 30, 3600) * 1000 : 30_000);
         let output;
         if (operation === 'auth status')
             output = { profile: identity.profile ?? 'anonymous', origin: identity.origin, source: identity.source ?? 'anonymous', authenticated: Boolean(identity.token) };
-        else if (operation === 'doctor')
-            output = { origin: identity.origin, identity: await read(client, '/api/v1/user') };
+        else if (operation === 'doctor') {
+            const account = object(await read(client, '/api/v1/user'));
+            output = { origin: identity.origin, identity: { id: account.id, login: account.login } };
+        }
+        else if (searching)
+            output = await search(client, path[1], positionals[0], options);
+        else if (operation === 'write reconcile')
+            output = await reconcile(client, positionals[0]);
         else if (operation === 'api')
-            output = await rawRead(client, apiPath);
+            output = method === 'GET' ? await rawRead(client, apiPath) :
+                await write(client, identity, await rawWritePlan(client, method, apiPath, payload), options);
         else if (operation === 'org view')
             output = { organization: await read(client, '/api/v1/orgs/' + encodeURIComponent(positionals[0])) };
+        else if (valuesCommand) {
+            const scope = options.org ? '/api/v1/orgs/' + encodeURIComponent(String(options.org)) : '/api/v1/repos/' + repository(typeof options.repo === 'string' ? options.repo : undefined, identity.origin).split('/').map(encodeURIComponent).join('/');
+            const path = scope + '/actions/' + (secretCommand ? 'secrets' : 'variables');
+            output = operation.endsWith(' list') ? boundedList({ items: await actionValues(client, path), total: null, next: null, truncated: false }, positive(options.limit, 30, 1000), secretCommand ? ['name'] : ['name', 'data']) :
+                await write(client, identity, await valuePlan(client, path, positionals[0], operation.split(' ')[1], protectedValue), options);
+        }
+        else if (repositoryMutation)
+            output = await write(client, identity, await repositoryPlan(client, operation, positionals[0], options), options);
         else if (operation === 'repo list') {
             if (options.fields)
                 throw new CliError('USAGE', 'repo list supports its compact identity fields only', 2);
@@ -105,16 +304,35 @@ export async function main(args) {
             output = boundedList(await collect(client, path, options.org ? undefined : 'data'), positive(options.limit, 30, 1000), ['id', 'full_name', 'default_branch']);
         }
         else {
-            const repo = repository(values.repo, identity.origin);
+            if (command.effect === 'write' && (!options['allow-write'] || process.env.GITEA_AXI_READ_ONLY && process.env.GITEA_AXI_READ_ONLY !== 'false'))
+                throw new CliError('READ_ONLY', 'Writes require an exact operation grant and a writable policy');
+            const repo = repository(typeof values.repo === 'string' ? values.repo : undefined, identity.origin);
             const base = '/api/v1/repos/' + repo.split('/').map(encodeURIComponent).join('/');
-            if (operation === 'repo view')
+            if (transferring) {
+                const path = await assetPath(client, base, operation.split(' ')[0], positionals[0]);
+                output = operation.endsWith(' upload') ? await write(client, identity, await uploadPlan(client, path, options), options) : await download(client, path, options);
+            }
+            else if (releasing)
+                output = command.effect === 'write' ? await write(client, identity, await attachToPlan(client, await releasePlan(client, operation, base, positionals[0], options), operation, base, positionals[0], options), options) : await releaseRead(client, operation, base, positionals[0], options);
+            else if (command.effect === 'write')
+                output = await write(client, identity, await attachToPlan(client, await (operation.startsWith('pr ') ? pullPlan : issueLabelPlan)(client, operation, base, positionals[0], options), operation, base, positionals[0], options), options);
+            else if (operation === 'repo view')
                 output = await readRepository(identity.origin, repo, identity.token);
             else if (operation === 'dashboard') {
                 const sections = {};
-                for (const [name, path, envelope] of [['repository', base], ['issues', base + '/issues?state=open&type=issues'], ['pulls', base + '/pulls?state=open'], ['labels', base + '/labels'], ['releases', base + '/releases'], ['runs', base + '/actions/tasks', 'workflow_runs']]) {
+                for (const [name, path, listCommand] of [['repository', base], ['issues', base + '/issues?state=open&type=issues', 'issue'], ['pulls', base + '/pulls?state=open', 'pr'], ['labels', base + '/labels', 'label'], ['releases', base + '/releases', 'release'], ['runs', base + '/actions/tasks', 'run']]) {
                     try {
-                        sections[name] = name === 'repository' ? { status: 'ok', data: await read(client, path) } :
-                            { status: 'ok', ...boundedList(await collect(client, path, envelope), 5, name === 'labels' ? ['id', 'name', 'color'] : ['id', 'number', 'title', 'state']) };
+                        if (name === 'repository') {
+                            const row = object(await read(client, path));
+                            sections[name] = { status: 'ok', data: Object.fromEntries(['id', 'full_name', 'private', 'default_branch', 'open_issues_count', 'open_pr_counter', 'updated_at'].map(key => [key, row[key] ?? null])) };
+                        }
+                        else {
+                            const list = name === 'runs' ? await tasks(client, base, { limit: '5' }) : boundedList(await collect(client, path), 5, name === 'labels' ? ['id', 'name', 'color'] : name === 'releases' ? releaseListFields : ['id', 'number', 'title', 'state']);
+                            sections[name] = { status: 'ok', ...list, ...(list.truncated ? { help: [
+                                        `Run gitea-axi ${listCommand} list --repo ${repo} --limit 1000 to see more items.`,
+                                        ...(list.help ?? []).filter(hint => !hint.startsWith('Raise --limit')),
+                                    ] } : {}) };
+                        }
                     }
                     catch (error) {
                         if (!(error instanceof CliError))
@@ -129,8 +347,10 @@ export async function main(args) {
                 output = await listIssues(client, base, operation === 'pr list' ? 'pr' : 'issue', options);
             else if (operation === 'issue view' || operation === 'pr view')
                 output = await view(client, base, operation === 'pr view' ? 'pr' : 'issue', positionals[0], options);
-            else if (['label list', 'run list', 'release list'].includes(operation))
-                output = boundedList(await collect(client, base + (operation === 'label list' ? '/labels' : operation === 'release list' ? '/releases' : '/actions/tasks'), operation === 'run list' ? 'workflow_runs' : undefined), positive(options.limit, 30, 1000), operation === 'label list' ? ['id', 'name', 'color'] : ['id', 'name', 'status', 'conclusion']);
+            else if (operation === 'run list')
+                output = await tasks(client, base, options);
+            else if (operation === 'label list')
+                output = boundedList(await collect(client, base + '/labels'), positive(options.limit, 30, 1000), ['id', 'name', 'color']);
             else if (operation === 'pr checks') {
                 const result = await watchChecks(client, base, positionals[0], options);
                 process.exitCode = result.exitCode;
@@ -150,7 +370,7 @@ export async function main(args) {
     }
     catch (error) {
         const failure = error instanceof CliError ? error : new CliError('INTERNAL_ERROR', 'Unable to read the repository');
-        console.log(encode(redact({ error: { code: failure.code, operation, reason: failure.message }, help: 'gitea-axi ' + operation + ' --help' })));
+        console.log(encode(redact({ error: { code: failure.code, operation, reason: failure.message }, help: commands.some(command => command.path.join(' ') === operation || command.path[0] === operation) ? 'gitea-axi ' + operation + ' --help' : 'gitea-axi --help' })));
         process.exitCode = failure.exitCode;
     }
 }

package/dist/private-file.js

@@ -3,7 +3,7 @@ import { constants } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { CliError } from './error.js';
-export async function readPrivateFile(path, secret = false) {
+export async function readPrivateFile(path, secret = false, maxBytes) {
     if (secret && process.platform === 'win32')
         throw new CliError('CONFIG_INVALID', 'File SecretRef protection cannot be verified on Windows; use env SecretRefs');
     const info = await lstat(path).catch(() => { throw new CliError('CONFIG_INSECURE', 'Private file is unavailable'); });
@@ -14,6 +14,8 @@ export async function readPrivateFile(path, secret = false) {
     });
     try {
         const stat = await file.stat();
+        if (maxBytes !== undefined && stat.size > maxBytes)
+            throw new CliError('USAGE', 'Input exceeds ' + maxBytes + ' bytes', 2);
         if (!stat.isFile() || (process.platform !== 'win32' &&
             (stat.uid !== process.getuid() || (stat.mode & (secret ? 0o077 : 0o022)) !== 0))) {
             throw new CliError('CONFIG_INSECURE', 'Private file must be owned and protected; use chmod 600');