@knowttl/gitea-axi 0.1.2 → 0.1.4

package/README.md

@@ -8,7 +8,7 @@ Agent-facing Gitea CLI with private credential profiles, read-only by default.
 
 Agents need bounded, predictable output and explicit write controls instead of guessed API calls and unbounded responses.
 gitea-axi offers a bounded repository dashboard, detailed reads, Actions task summaries, bounded search, repository, release, issue, label and pull request mutations, and classified raw API requests.
-Output is compact TOON with structured errors.
+Output defaults to compact TOON, with optional JSON and structured errors.
 Reads are bounded, and writes require an exact operation grant, a preview and a matching confirmation.
 See [Limitations](#limitations) for verification scope.
 
@@ -71,6 +71,7 @@ Full workflow run APIs require Gitea 1.24 or later; the retained workflow, artif
 ### Search
 
 `search issues|prs|repos|commits "text"` searches at most 20 pages and 1000 candidates per collection, then filters, sorts and applies the total output limit (default 1000).
+Search sorts creation and update times chronologically across time zone offsets before applying the output limit.
 Issue and PR searches support exact arbitrary author and assignee names and comma-separated label ANY matching; an unknown label alone matches nothing.
 Use `--repo OWNER/NAME` for repository scope or `--owner OWNER` for issue, PR and repository searches.
 Repository search supports `--language` and integer `--stars` comparisons.
@@ -106,12 +107,15 @@ Encoded route separators and traversal remain refused.
 Anonymous reads require an explicit origin; repository selection follows the rules below.
 Anonymous HTTP reads require `--allow-insecure-http` for that selected origin.
 The tool follows no redirects and never imports tea or Git credentials.
-Output uses TOON; structured errors use stdout, with exit 1 for operational failures and exit 2 for usage errors.
+Output uses TOON by default; `--json` selects JSON for results, structured errors and help.
+Version aliases remain plain text when combined with `--json`.
+Structured errors use stdout, with exit 1 for operational failures and exit 2 for usage errors.
 Business reads share a 30-second deadline, except check watches use their explicit timeout; each request has a 2,000,000-byte response limit.
+The check-watch timeout includes initial repository reads; polling cannot extend the client's deadline.
 `repo view` instead gives each of its server version, specification and repository requests a separate 30-second timeout.
 An explicit repository wins over a matching local origin remote; a remote never changes the selected profile.
-`-R` aliases `--repo` after an explicit command, with the same duplicate-selector checks.
-For the default dashboard, use `gitea-axi --repo OWNER/NAME`; root-level `-R` remains unsupported.
+`-R` aliases `--repo`, with the same duplicate-selector checks.
+For the default dashboard, use `gitea-axi --repo OWNER/NAME` or `gitea-axi -R OWNER/NAME`.
 Hosted repository reads require an explicit repository.
 Lists default to 30 returned records, except `run list` and `release list` default to 10; collection scans stop at 20 pages or at least 1000 unique records and retain at most 1000.
 Automatic page queries apply only to routes whose retained Gitea specification declares a `page` parameter.
@@ -126,7 +130,10 @@ The dashboard shows a compact repository projection (ID, full name, visibility,
 Dashboard sections report permission failures as partial results and point truncated sections to the corresponding standalone list command with `--repo` and `--limit`.
 Issue and PR bodies default to 1000 characters, diffs to 10000 characters, and rendered output to 100000 characters.
 `--full` expands bodies and diffs within the response and output ceilings.
-`pr checks` exits 8 for pending checks and 1 for failed or absent checks; watches require an explicit deadline and accept cancellation.
+Diffs retain an unchanged source prefix sized to fit the serialized output, including escaping and metadata; `chars` reports the original length and `truncated` indicates omitted text.
+`pr checks` exits 8 for pending checks and 1 for failed or absent checks; watches require an explicit deadline.
+During check polling, SIGINT or SIGTERM aborts in-flight PR and status requests, including paginated responses, and returns `cancelled: true` with exit code 8.
+Cancellation preserves the last completed check result; before any completed result, it returns empty items and zero counts, with the head SHA if already read, otherwise null.
 Commits without statuses return an empty check result; watches continue waiting for checks to register until the deadline or cancellation.
 `--fields` refuses unknown names and fields without an evidenced Gitea equivalent, and cannot combine with detail expansion flags.
 PR statusCheckRollup explicitly identifies partial commit statuses, and `fullDatabaseId` is a numeric vendor ID rather than a GraphQL node ID.
@@ -154,8 +161,11 @@ Issue and label deletion require a complete collection and at least one remainin
 
 ### Pull requests
 
+`pr view` includes both user and team review requests in `reviewRequests`: users have `login` and `name`, while teams have `type: team`, `id` and `name`.
 Pull request mutations include `create`, `edit`, `close`, `reopen`, `comment`, `update-branch` and `merge`.
 Creation requires explicit `--title`, `--base` and `--head` branch names in the selected repository.
+PR creation, base edits, updates and merges support slash-containing branch names such as `work/topic` and `release/stable`, resolving exact Git refs rather than prefix matches.
+Branch resolution binds commit identities into preview and confirmation while preserving API path separator and traversal protections.
 Cross-repository heads, draft and project inputs remain unavailable.
 Create accepts repeatable `--reviewer` user names and `--team-reviewer` team names, plus issue-style assignees, labels and milestone selectors.
 Edit accepts `--base`, text fields and assignee/label deltas, plus repeatable `--add-reviewer`, `--remove-reviewer`, `--add-team-reviewer` and `--remove-team-reviewer` deltas.
@@ -167,6 +177,7 @@ If the reviewer step fails after creation, the error reports the created PR ID a
 Close with `--comment` records closure and comment as separate steps and reports partial outcomes without retrying.
 Successful writes verify the same PR identity, expected fields and memberships through fresh reads.
 Update-branch verifies that the resulting head contains both its previous head and base commits; conflicts never report completion.
+Verification stops once both commits are proven present, so older base history need not be traversed; it reads at most 1000 commits and refuses completion if that bound prevents proof.
 Merge requires exactly one of `--merge`, `--squash`, `--rebase` or `--method merge|squash|rebase`, and a full `--match-head-commit` SHA.
 It sends the vendor `head_commit_id` precondition and verifies the closed, merged PR, base branch tip and final commit topology.
 Merge commits retain the previous base and checked head as parents; squash uses one new commit on the previous base; rebase verifies the rewritten linear chain and original commit messages.
@@ -188,8 +199,7 @@ Boolean flags accept explicit `=true` and `=false`, including disabling issues o
 Fork takes a source through `--repo` or a positional OWNER/NAME and optionally `--org` for the destination.
 Verification checks the destination identity, requested fields and fork parent.
 Internal visibility refuses before mutation.
-Workspace flags (`--source`, `--push`, `--remote`, `--clone`) use the standalone Git workflows below and require explicit `--workspace` selection.
-Repository creation `--push` and `--remote` require `--source`.
+See [Local Git workflows and owned stacks](#local-git-workflows-and-owned-stacks) for supported workspace flag combinations and explicit `--workspace` selection.
 
 ### Releases
 
@@ -259,8 +269,14 @@ gitea-axi issue close 42 --repo OWNER/NAME --comment 'Resolved' --allow-write is
 gitea-axi label create --repo OWNER/NAME --name bug --color ff0000 --allow-write issueCreateLabel --preview
 ```
 
-The preview identifies the exact operations, payload and current preconditions without sending a mutation.
+The preview identifies the exact operations and payload without sending a mutation.
+To fit the rendered output ceiling, previews, write results and reconciliation output may summarize `preconditions`, then `observations`, then `results`, stopping as soon as the output fits.
+Summarized output sets `truncated: true` and lists affected fields in `truncated_fields`.
+Summaries report `summary: true` with `total_items`, `total_fields` or `total_chars`; object summaries retain numeric `id` and `number` when present.
+Summarized observations retain paths, and observations and results retain at most ten entries with their original counts in `observations_total` and `results_total`.
+Preview steps and requested payloads remain complete subject to credential redaction; output that still exceeds the ceiling fails with `OUTPUT_LIMIT`.
 Confirmation binds the credential revision, origin, target, operations, canonical payload and preconditions.
+Display summaries do not weaken confirmation binding or readback verification, which use the complete data.
 Changing any binding requires a fresh preview.
 Organization casing must match the preview exactly.
 For issues that remain present, successful named writes verify identity and the expected final title, body, assignees, labels, milestone and state through fresh reads.
@@ -282,6 +298,10 @@ Each attempt is persisted before dispatch.
 API timeouts, interrupted requests and partial failures return `WRITE_OUTCOME_UNKNOWN`, completed/pending step information and an exact `gitea-axi write reconcile CONFIRMATION_ID` command.
 Dispatched local Git failures retain their specific error code and include reconciliation information; stack recovery follows the [metadata and recovery contract](docs/local-stack-contract.md).
 Reconciliation performs complete metadata reads for inspection and never repeats a mutation.
+If its display is summarized as described above, use targeted reads to inspect the exact identity and requested fields before authorizing another attempt.
+Raw repository edits with a nonempty `name` verify and reconcile through the repository's immutable ID, so a rename does not depend on the old URL.
+Raw wiki edits use the returned escaped `sub_url` for verification and reconciliation; if the response is lost or its page identity is unusable, reconciliation reads the bounded wiki page list instead.
+These read targets preserve the original confirmation binding and attempted-effect identity.
 An unresolved dispatched attempt cannot be replayed by reusing its confirmation or obtaining another preview for the same effect.
 Replay guards also treat repository owner, repository name and organization name case variants as the same identity for named and raw writes.
 Unresolved organization attempts from older versions conservatively block all writes to the same organization at the same origin, including different names or payloads, and return the original attempt's reconciliation command.
@@ -303,14 +323,14 @@ Incomplete environment profiles report missing variables; profile schema errors
 For file profiles, an explicit profile must match; otherwise exactly one matching profile is required, ignoring `defaultProfile`.
 Without a host selector, file selection uses the explicit profile, otherwise the file's `defaultProfile` or its sole profile; multiple profiles without a selection or default are refused.
 A host selector cannot construct an anonymous origin, bypass tokenOrigin binding or enable HTTP.
-Search commands currently reject `--hostname`; use `GH_HOST` with a matching profile instead.
+Search commands support `--hostname` and `GH_HOST` with the same profile selection and credential binding checks.
 Hosted invocations refuse credential/configuration overrides and ignore ambient `GH_HOST` for the injected Artium profile.
 On Linux, the config file must be owned by the invoking account and must not be group- or world-writable.
 Config files and file SecretRefs must be regular files; symlinks are refused.
 See [the credential schema](axi-credential.schema.json) for profile fields and env/file SecretRef shapes.
 `origin` and `tokenOrigin` must identify the same canonical origin.
 Inline tokens and secret arguments are refused.
-Resolved credentials are redacted from response and error string values before TOON serialization, including their JSON-escaped and URL-encoded forms.
+Resolved credentials are redacted from response and error string values before TOON or JSON serialization, including their JSON-escaped and URL-encoded forms.
 Redaction also masks recognized secret fields, secret query values, URL credentials, JWTs, private keys and account keys.
 Generated confirmation IDs and fixed confirmation/reconciliation instructions remain intact when they overlap a protected value; payloads and upstream response text remain subject to redaction.
 The complete environment profile uses `GITEA_AXI_ORIGIN`, `GITEA_AXI_TOKEN_ORIGIN` and a JSON SecretRef in `GITEA_AXI_TOKEN`.
@@ -329,7 +349,9 @@ Local workflows require an explicit absolute `--workspace` and use native Git ar
 Select the native repository root, or an existing parent directory for cloning.
 `repo clone OWNER/NAME` clones into a new child directory of the selected parent and checks out the previewed default commit.
 `repo create --source /absolute/repo --push --remote NAME` publishes the current source branch with its complete history.
-`repo fork --clone` clones the verified fork, while `repo fork --remote NAME` configures a new remote in the workspace.
+Workspace repository creation requires both `--source` and `--push` and refuses `--clone`.
+`repo fork --clone` clones the verified fork; `--remote NAME` selects the clone's origin name.
+Workspace forks require `--clone` and refuse `--source` and `--push`.
 Existing remotes are never overwritten.
 Use a repository-local Git user name and email for workflows that create commits.
 Git credential helpers, hooks, transport rewrites and redirects are disabled or refused.
@@ -401,7 +423,7 @@ Set `GITEA_AXI_REPORT` to retain their reports at a chosen path.
 Their default reports go to unique files in the OS temporary directory; temporary installation files are removed.
 For S5, set `GITEA_AXI_REPORT_DIR` to an existing directory to retain `S5.1.json` or `S5.2.json`; otherwise only a console summary is emitted.
 
-`npm test` first runs the package-contract check in `scripts/verify-package.ts`, then the offline live-read regressions in `scripts/verify-live-reads.ts`, then the installed-package checks with local Gitea fakes for S1.1, S2.1 through S2.4, S3.1 through S3.5, S4.1 through S4.3, S5.1, S5.2 and S6.1 through S6.4 under an inherited outbound network guard.
+`npm test` first runs the package-contract check in `scripts/verify-package.ts`, then the native Git workspace checks in `scripts/verify-git.ts`, then the offline live-read regressions in `scripts/verify-live-reads.ts`, then the installed-package checks with local Gitea fakes for S1.1, S2.1 through S2.4, S3.1 through S3.5, S4.1 through S4.3, S5.1, S5.2 and S6.1 through S6.4 under an inherited outbound network guard.
 The package-contract check builds, packs and installs offline, validates the tarball file list and bin entry, smoke-tests the installed `--help` and `--version`, parses the consumed JSON artifacts and imports the modules Artium consumes from the installed package.
 Run it independently with `node --import ./scripts/deny-network.ts scripts/verify-package.ts`.
 Each S2 task also has an independent entrypoint, for example `node scripts/verify.mjs --task S2.3`.

package/dist/api.js

@@ -136,9 +136,9 @@ export function rawPath(input, method = 'GET') {
         throw new CliError('READ_ONLY', 'Unclassified API route');
     return path + (query ? '?' + query : '');
 }
-export async function read(client, path) {
+export async function read(client, path, signal) {
     routeFor(path.split('?')[0]);
-    const value = await client.get(path);
+    const value = await client.get(path, signal);
     return validate(path.split('?')[0], value);
 }
 export async function resolveCommit(client, base, ref) {
@@ -166,7 +166,7 @@ export async function rawRead(client, path) {
     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) {
+export async function collect(client, path, envelope, signal) {
     const paginated = routeFor(path).paginated;
     let next = paginated ? path + (path.includes('?') ? '&' : '?') + 'limit=50&page=1' : path;
     const seenPages = new Set();
@@ -176,14 +176,14 @@ export async function collect(client, path, envelope) {
         if (seenPages.has(next))
             throw new CliError('INVALID_RESPONSE', 'Gitea repeated a pagination URL');
         seenPages.add(next);
-        const response = await client.request(next);
+        const response = await client.request(next, false, undefined, signal);
         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);
+            const id = /\/(?:tags|actions\/(?:secrets|variables))$/.test(path.split('?')[0]) ? row.name : row.id ?? row.number ?? row.sha ?? row.ref ?? row.sub_url ?? 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);

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/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 versionArgs = args.filter(arg => !['--json', '--json=true', '--json=false'].includes(arg));
+if (args.length <= 2 && versionArgs.length === 1 && ['--version', '-v', '-V'].includes(versionArgs[0] ?? '')) {
     const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
     console.log(pkg.version);
 }

package/dist/git.js

@@ -43,9 +43,9 @@ export class Git {
         if (!isAbsolute(this.cwd) || await realpath(this.cwd) !== this.cwd || await this.run(['rev-parse', '--show-toplevel']) !== this.cwd) {
             throw new CliError('USAGE', '--workspace must be the absolute native repository root', 2);
         }
-        const config = await this.run(['config', '--local', '--name-only', '--list']) + '\n' +
-            await this.run(['config', '--worktree', '--name-only', '--list']);
-        if (config.split('\n').some(key => /^(?:url\.|http\.|credential\.|include\.|includeif\.|filter\.|diff\.|core\.sshcommand$|remote\..*\.(?:proxy|uploadpack|receivepack|pushurl|vcs)$)/i.test(key))) {
+        const config = await this.run(['config', '--no-includes', '--show-scope', '--name-only', '--list']);
+        // Inspect repository settings without requiring config.worktree or rejecting our command-scope transport settings.
+        if (config.split('\n').some(key => /^(?:local|worktree)\t(?:url\.|http\.|credential\.|include\.|includeif\.|filter\.|diff\.|core\.sshcommand$|remote\..*\.(?:proxy|uploadpack|receivepack|pushurl|vcs)$)/i.test(key))) {
             throw new CliError('UNSAFE_GIT_CONFIG', 'Workspace transport overrides must be removed before using origin-bound Git');
         }
         return this;

package/dist/local-workflows.js

@@ -20,6 +20,10 @@ 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 === 'repo create' && (!options.source || !options.push || options.clone))
+        usage('Workspace repository creation requires --source and --push without --clone');
+    if (operation === 'repo fork' && (!options.clone || options.source !== undefined || options.push))
+        usage('Workspace forks require --clone without --source or --push');
     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))
@@ -68,10 +72,7 @@ export async function localWorkflow(client, identity, operation, args, options)
     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 creating = operation === 'repo create';
         const apiOptions = { ...options };
         for (const key of ['source', 'push', 'remote', 'clone', 'workspace'])
             delete apiOptions[key];
@@ -85,39 +86,35 @@ export async function localWorkflow(client, identity, operation, args, options)
         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 (creating) {
+            const sourcePath = String(options.source);
             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]))
+            if (!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) {
+        else {
             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 () => {
+        return localEffect(client, identity, 'composite', options, git, preconditions, { source: source?.cwd, remote, url, clone: !creating, push: creating }, 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() };
+                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: true, head: await source.tip() };
             }
             if (existsSync(destination))
                 throw new CliError('CONFIRMATION_MISMATCH', 'Clone destination appeared; API repository was created');

package/dist/main.js

@@ -1,10 +1,9 @@
 import { parseArgs } from 'node:util';
 import { isAbsolute } from 'node:path';
-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, registerSecret } from './credentials.js';
+import { configPath, credentials, profileList, 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';
@@ -19,6 +18,7 @@ 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';
+import { diffOutput, maxOutputChars, render } from './output.js';
 async function input(path) {
     if (path !== '-')
         return readPrivateFile(path, true, 1_000_000);
@@ -32,6 +32,8 @@ async function input(path) {
     return body;
 }
 export async function main(args) {
+    let json = args.some(arg => arg === '--json' || arg === '--json=true');
+    const print = (value) => console.log(render(value, json));
     let operation = args[0] && !args[0].startsWith('-') ? args[0] : 'dashboard';
     try {
         for (const arg of args) {
@@ -42,19 +44,20 @@ export async function main(args) {
         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 command = args.length === 0 || args[0]?.startsWith('--') ? commands.find(command => command.path[0] === 'dashboard') :
+        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(' ')) }));
+            const helpArgs = args.filter(arg => arg !== '--json');
+            if (children.length && helpArgs.length === 2 && helpArgs[1] === '--help' && args.length <= 3) {
+                print({ 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);
+        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,
@@ -80,23 +83,24 @@ export async function main(args) {
             throw new CliError('USAGE', 'Invalid arguments; valid flags: ' + Object.keys(command.flags).map(f => '--' + f).join(', '), 2);
         }
         const { values, positionals } = parsed;
+        json = Boolean(values.json);
         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);
         }
         if (values.help) {
-            console.log(encode({ bin: process.argv[1], description: command.description, command: 'gitea-axi ' + operation,
+            print({ bin: process.argv[1], description: command.description, command: 'gitea-axi ' + operation,
                 flags: Object.entries(command.flags).map(([name, flag]) => ({ flag: '--' + name, ...flag })),
                 ...(operation === 'dashboard' ? { commands: commands.map(command => command.path.join(' ')) } : {}),
                 examples: operation === 'api' ? ['gitea-axi api GET repos/OWNER/NAME', 'gitea-axi api version'] :
-                    [`gitea-axi ${operation} --help`, `gitea-axi ${operation} --profile <name>`] }));
+                    [`gitea-axi ${operation} --help`, `gitea-axi ${operation} --profile <name>`] });
             return;
         }
         const options = values;
         if (operation === 'capabilities') {
             if (positionals.length > 1)
                 throw new CliError('USAGE', 'Use capabilities [C001-C124]', 2);
-            console.log(encode(capabilityOutput(commands, prFields, positionals[0])));
+            print(capabilityOutput(commands, prFields, positionals[0]));
             return;
         }
         if (command.gap)
@@ -118,8 +122,8 @@ export async function main(args) {
                 ...(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)
+            const rendered = render(output, json);
+            if (rendered.length > maxOutputChars)
                 throw new CliError('OUTPUT_LIMIT', 'Rendered output exceeds 100000 characters');
             console.log(rendered);
             return;
@@ -261,11 +265,11 @@ export async function main(args) {
         if (options.config && (typeof options.config !== 'string' || !isAbsolute(options.config)))
             throw new CliError('USAGE', '--config must be absolute', 2);
         if (operation === 'config path') {
-            console.log(encode({ path: configPath(options.config) }));
+            print({ path: configPath(options.config) });
             return;
         }
         if (operation === 'profile list') {
-            console.log(encode(await profileList(options.config)));
+            print(await profileList(options.config));
             return;
         }
         const identity = await credentials(typeof values.origin === 'string' ? values.origin : undefined, Boolean(values['allow-insecure-http']), {
@@ -283,7 +287,7 @@ export async function main(args) {
         else if (searching)
             output = await search(client, path[1], positionals[0], options);
         else if (operation === 'write reconcile')
-            output = await reconcile(client, positionals[0]);
+            output = await reconcile(client, positionals[0], json);
         else if (operation === 'api')
             output = method === 'GET' ? await rawRead(client, apiPath) :
                 await write(client, identity, await rawWritePlan(client, method, apiPath, payload), options);
@@ -359,18 +363,17 @@ export async function main(args) {
             else if (operation === 'pr diff') {
                 const response = await client.request(base + '/pulls/' + positionals[0] + '.diff', true);
                 const text = String(response.data);
-                const ceiling = options.full ? 100_000 : 10_000;
-                output = { diff: text.slice(0, ceiling), chars: text.length, truncated: text.length > ceiling, ...(text.length > ceiling ? { help: 'Use --full within the 100000 character diff ceiling' } : {}) };
+                output = diffOutput(text, Boolean(options.full), json);
             }
         }
-        const rendered = encode(redact(output));
-        if (rendered.length > 100_000)
+        const rendered = render(output, json);
+        if (rendered.length > maxOutputChars)
             throw new CliError('OUTPUT_LIMIT', 'Rendered output exceeds 100000 characters; select fewer fields or a lower --limit');
         console.log(rendered);
     }
     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: commands.some(command => command.path.join(' ') === operation || command.path[0] === operation) ? 'gitea-axi ' + operation + ' --help' : 'gitea-axi --help' })));
+        print({ 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/output.js

@@ -0,0 +1,60 @@
+import { encode } from '@toon-format/toon';
+import { redact } from './credentials.js';
+export const maxOutputChars = 100_000;
+export function render(value, json = false) {
+    const safe = redact(value);
+    return json ? JSON.stringify(safe) : encode(safe);
+}
+// Reserve the newline added by console.log.
+const fits = (value, json) => render(value, json).length < maxOutputChars;
+function summary(value) {
+    if (Array.isArray(value))
+        return { summary: true, total_items: value.length };
+    if (value && typeof value === 'object') {
+        const row = value;
+        return { summary: true, total_fields: Object.keys(row).length,
+            ...(typeof row.id === 'number' ? { id: row.id } : {}), ...(typeof row.number === 'number' ? { number: row.number } : {}) };
+    }
+    return typeof value === 'string' ? { summary: true, total_chars: value.length } : value;
+}
+export function writeOutput(value, json = false) {
+    const displayed = { ...value };
+    const truncated = [];
+    // Keep requested effects complete; project only their verification context.
+    for (const field of ['preconditions', 'observations', 'results']) {
+        if (fits(displayed, json))
+            return displayed;
+        if (!(field in value))
+            continue;
+        const context = value[field];
+        if (field === 'observations' && Array.isArray(context)) {
+            displayed[field] = context.slice(0, 10).map(row => ({ path: row.path, data: summary(row.data) }));
+            displayed.observations_total = context.length;
+        }
+        else if (field === 'results' && Array.isArray(context)) {
+            displayed[field] = context.slice(0, 10).map(summary);
+            displayed.results_total = context.length;
+        }
+        else
+            displayed[field] = summary(context);
+        truncated.push(field);
+        displayed.truncated = true;
+        displayed.truncated_fields = [...truncated];
+    }
+    return displayed;
+}
+export function diffOutput(text, full, json = false) {
+    const candidate = (length) => ({ diff: text.slice(0, length), chars: text.length, truncated: text.length > length,
+        ...(text.length > length ? { help: full ? 'Diff is bounded to the rendered output ceiling' : 'Use --full for a larger bounded diff' } : {}) });
+    let low = 0, high = Math.min(text.length, full ? maxOutputChars : 10_000);
+    if (fits(candidate(high), json))
+        return candidate(high);
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (fits(candidate(middle), json))
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return candidate(low);
+}

package/dist/pulls.js

@@ -7,7 +7,27 @@ const sorted = (values) => [...values].sort();
 const equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const delta = (previous, add, remove) => [...new Set([...previous.map(String), ...names(add)])].filter(value => !names(remove).includes(value));
 const members = (pull, field, key) => (pull[field] ?? []).map(row => object(row)[key]);
+function branchPath(base, branch) {
+    const segments = branch.split('/');
+    if (segments.some(segment => !segment || segment === '.' || segment === '..') || /[\s\\\x00-\x1f\x7f]/.test(branch))
+        usage('Select a branch without unsafe path segments');
+    return base + '/git/refs/heads/' + segments.map(encodeURIComponent).join('/');
+}
+function branchSHA(value, branch) {
+    if (!Array.isArray(value))
+        throw new CliError('INVALID_RESPONSE', 'Expected branch references');
+    const selected = value.map(object).find(row => row.ref === 'refs/heads/' + branch);
+    if (!selected)
+        throw new CliError('NOT_FOUND_OR_HIDDEN', 'The selected branch is missing or hidden');
+    const commit = object(selected.object);
+    if (commit.type !== 'commit' || typeof commit.sha !== 'string' || !/^[a-f0-9]{40}$/.test(commit.sha))
+        throw new CliError('INVALID_RESPONSE', 'Expected an immutable branch commit identity');
+    return commit.sha;
+}
 export function validatePull(operation, options) {
+    for (const ref of [options.head, options.base])
+        if (ref !== undefined)
+            branchPath('', String(ref));
     if (operation === 'pr review') {
         if (['approve', 'request-changes', 'comment'].filter(key => options[key]).length !== 1)
             usage('Choose exactly one of --approve, --request-changes or --comment');
@@ -49,6 +69,7 @@ export async function pullPlan(client, operation, base, number, options) {
         reads.add(path);
         return value;
     };
+    const snapshotBranch = async (branch) => branchSHA(await snapshot(branchPath(base, branch), true), branch);
     const add = (method, path, payload) => steps.push({ method, path, ...(payload === undefined ? {} : { payload }) });
     const before = action === 'create' ? undefined : object(await snapshot(path));
     const expected = before ? { id: before.id, number: before.number, ...fields(before), merged: before.merged ?? false, headSHA: object(before.head).sha } :
@@ -101,15 +122,14 @@ export async function pullPlan(client, operation, base, number, options) {
             payload.assignees = names(options.assignee);
             expected.reviewers = sorted(addedReviewers);
             expected.teams = sorted(names(options['team-reviewer']));
-            const head = object(await snapshot(base + '/branches/' + encodeURIComponent(String(options.head))));
-            expected.headSHA = object(head.commit).id;
+            expected.headSHA = await snapshotBranch(String(options.head));
         }
         else {
             if (options['add-assignee'] !== undefined || options['remove-assignee'] !== undefined)
                 payload.assignees = delta(expected.assignees, options['add-assignee'], options['remove-assignee']);
         }
         if (options.base !== undefined)
-            await snapshot(base + '/branches/' + encodeURIComponent(String(options.base)));
+            await snapshotBranch(String(options.base));
         if (options.milestone !== undefined) {
             const list = await snapshot(base + '/milestones?state=all', true);
             const selected = list.find(row => row.title === options.milestone);
@@ -171,12 +191,12 @@ export async function pullPlan(client, operation, base, number, options) {
             payload.MergeMessageField = options.body;
         if (style === 'rebase')
             await snapshot(path + '/commits', true);
-        await snapshot(base + '/branches/' + encodeURIComponent(String(expected.base)));
+        await snapshotBranch(String(expected.base));
         add('POST', path + '/merge', payload);
         expected.state = 'closed';
     }
     else if (action === 'update-branch') {
-        await snapshot(base + '/branches/' + encodeURIComponent(String(expected.base)));
+        await snapshotBranch(String(expected.base));
         add('POST', path + '/update');
     }
     if (action === 'comment' || action === 'close' && options.comment !== undefined) {
@@ -228,8 +248,8 @@ export async function verifyPull(client, plan, results, observations) {
     }
     if (action !== 'merge' && action !== 'update-branch')
         return;
-    const branchPath = base + '/branches/' + encodeURIComponent(String(expected.base));
-    const baseSHA = object(object(before[branchPath]).commit).id;
+    const baseBranchPath = branchPath(base, String(expected.base));
+    const baseSHA = branchSHA(before[baseBranchPath], String(expected.base));
     const commit = async (sha) => {
         if (typeof sha !== 'string' || !/^[a-f0-9]{40}$/.test(sha))
             return mismatch();
@@ -241,25 +261,29 @@ export async function verifyPull(client, plan, results, observations) {
         return data;
     };
     if (action === 'update-branch') {
-        const head = await commit(object(pull.head).sha);
-        const pending = [head], visited = new Set();
-        while (pending.length && visited.size < 1000) {
-            const current = pending.pop();
-            if (visited.has(current.sha))
+        const required = new Set([baseSHA, expected.headSHA]);
+        if ([...required].some(sha => typeof sha !== 'string' || !/^[a-f0-9]{40}$/.test(sha)))
+            mismatch();
+        const pending = [object(pull.head).sha], visited = new Set();
+        for (let cursor = 0; cursor < pending.length && visited.size < 1000; cursor++) {
+            const sha = pending[cursor];
+            if (visited.has(sha))
                 continue;
+            const current = await commit(sha);
             visited.add(current.sha);
-            if (visited.has(baseSHA) && visited.has(expected.headSHA))
+            required.delete(current.sha);
+            const parents = members(current, 'parents', 'sha');
+            for (const parent of parents)
+                required.delete(parent);
+            if (!required.size)
                 return;
-            for (const parent of members(current, 'parents', 'sha')) {
-                if (!visited.has(parent))
-                    pending.push(await commit(parent));
-            }
+            pending.push(...parents.filter(parent => !visited.has(parent)));
         }
         mismatch();
     }
     if (pull.merged !== true || !pull.merge_commit_sha)
         mismatch();
-    const finalSHA = object(object(observation(branchPath)).commit).id;
+    const finalSHA = branchSHA(observation(baseBranchPath), String(expected.base));
     if (finalSHA !== pull.merge_commit_sha)
         mismatch();
     const final = await commit(finalSHA);