@knowttl/gitea-axi 0.1.3 → 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.
 
@@ -107,7 +107,9 @@ 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.
@@ -197,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
 
@@ -329,7 +330,7 @@ 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`.
@@ -348,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.

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/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,7 +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 } from './output.js';
+import { diffOutput, maxOutputChars, render } from './output.js';
 async function input(path) {
     if (path !== '-')
         return readPrivateFile(path, true, 1_000_000);
@@ -33,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) {
@@ -47,8 +48,9 @@ export async function main(args) {
             [...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);
@@ -81,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)
@@ -119,7 +122,7 @@ 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));
+            const rendered = render(output, json);
             if (rendered.length > maxOutputChars)
                 throw new CliError('OUTPUT_LIMIT', 'Rendered output exceeds 100000 characters');
             console.log(rendered);
@@ -262,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']), {
@@ -284,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);
@@ -360,17 +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);
-                output = diffOutput(text, Boolean(options.full));
+                output = diffOutput(text, Boolean(options.full), json);
             }
         }
-        const rendered = encode(redact(output));
+        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

@@ -1,8 +1,12 @@
 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) => encode(redact(value)).length < maxOutputChars;
+const fits = (value, json) => render(value, json).length < maxOutputChars;
 function summary(value) {
     if (Array.isArray(value))
         return { summary: true, total_items: value.length };
@@ -13,12 +17,12 @@ function summary(value) {
     }
     return typeof value === 'string' ? { summary: true, total_chars: value.length } : value;
 }
-export function writeOutput(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))
+        if (fits(displayed, json))
             return displayed;
         if (!(field in value))
             continue;
@@ -39,15 +43,15 @@ export function writeOutput(value) {
     }
     return displayed;
 }
-export function diffOutput(text, full) {
+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)))
+    if (fits(candidate(high), json))
         return candidate(high);
     while (low < high) {
         const middle = Math.ceil((low + high) / 2);
-        if (fits(candidate(middle)))
+        if (fits(candidate(middle), json))
             low = middle;
         else
             high = middle - 1;

package/dist/registry.js

@@ -22,6 +22,7 @@ export const command = {
 };
 export const limits = { timeoutMs: 30_000, responseBytes: 2_000_000 };
 const globalFlags = {
+    json: { type: 'boolean', description: 'Emit JSON instead of TOON; help follows this format, version remains plain text' },
     origin: command.flags.origin, 'allow-insecure-http': command.flags['allow-insecure-http'], help: command.flags.help,
     config: { type: 'string', description: 'Absolute configuration path' },
     profile: { type: 'string', description: 'Select one file profile' },
@@ -144,7 +145,7 @@ for (const command of commands) {
     if (['repo create', 'repo fork'].includes(command.path.join(' ')))
         Object.assign(command.flags, workspace);
 }
-commands.push({ path: ['capabilities'], description: 'Inspect all baseline command IDs, flags, globals and PR fields without claiming full parity', flags: { help: globalFlags.help }, effect: 'local-read' });
+commands.push({ path: ['capabilities'], description: 'Inspect all baseline command IDs, flags, globals and PR fields without claiming full parity', flags: { help: globalFlags.help, json: globalFlags.json }, effect: 'local-read' });
 const refusedFlags = [
     ['repo create', ['internal']],
     ['release create', ['latest', 'discussion-category']],

package/dist/search.js

@@ -9,7 +9,7 @@ export function validateSearch(kind, query, options) {
     const allowed = kind === 'issues' || kind === 'prs' ? ['owner', 'state', 'label', 'assignee', 'author', 'sort', 'order', 'limit', 'fields', ...(kind === 'prs' ? ['draft'] : [])] :
         kind === 'repos' ? ['owner', 'sort', 'order', 'limit', 'language', 'stars', 'fields'] : ['author', 'sort', 'order', 'limit', 'revision', 'fields'];
     for (const key of Object.keys(options)) {
-        if (!['origin', 'allow-insecure-http', 'config', 'profile', 'hostname', 'repo'].includes(key) && !allowed.includes(key))
+        if (!['origin', 'allow-insecure-http', 'config', 'profile', 'hostname', 'repo', 'json'].includes(key) && !allowed.includes(key))
             throw new CliError('CAPABILITY_GAP', '--' + key + ' is not evidenced for search ' + kind);
     }
     positive(options.limit, 1000, 1000);

package/dist/writes.js

@@ -46,7 +46,7 @@ async function key(root) {
     }
     return readPrivateFile(path, true);
 }
-export async function reconcile(client, id) {
+export async function reconcile(client, id, json = false) {
     if (!/^[a-f0-9-]{36}$/.test(id))
         usage('Select the exact confirmation ID');
     const receipt = JSON.parse(await readPrivateFile(join(directory(), id + '.json'), true));
@@ -55,7 +55,7 @@ export async function reconcile(client, id) {
     const observations = await observe(client, receipt.reads);
     controlText(id);
     return writeOutput({ confirmation: id, operations: receipt.operations, states: receipt.states, observations,
-        help: 'Inspect the exact identity and requested fields in these reads before authorizing any new attempt' });
+        help: 'Inspect the exact identity and requested fields in these reads before authorizing any new attempt' }, json);
 }
 async function observe(client, paths) {
     const observations = [];
@@ -270,7 +270,7 @@ export async function write(client, identity, plan, options, executeLocal) {
             ...(plan.steps.every(step => step.local) ? { localTarget: plan.target, localGuards: guards.map(path => path.slice(root.length + 1, -8)) } : {}) };
         await writePrivateFile(join(root, id + '.json'), JSON.stringify(receipt));
         return writeOutput({ confirmation: id, origin: client.origin, target: plan.target, operations, steps: plan.steps.map(({ upload, ...step }) => ({ ...step, ...(plan.sensitive && step.payload !== undefined ? { payload: '[REDACTED]' } : {}), ...(upload ? { upload: { name: upload.name, type: upload.type, size: upload.size, sha256: upload.sha256 } } : {}) })), preconditions: plan.preconditions,
-            ...(plan.notes ? { notes: plan.notes } : {}), help: controlText('Repeat the same command with --confirm ' + id + ' instead of --preview') });
+            ...(plan.notes ? { notes: plan.notes } : {}), help: controlText('Repeat the same command with --confirm ' + id + ' instead of --preview') }, Boolean(options.json));
     }
     const id = String(options.confirm);
     if (!/^[a-f0-9-]{36}$/.test(id))
@@ -429,7 +429,7 @@ export async function write(client, identity, plan, options, executeLocal) {
         recovered.states = recovered.states.map(state => state === 'completed' ? state : 'recovered');
         await writePrivateFile(join(root, previous + '.json'), JSON.stringify(recovered));
     }
-    return writeOutput({ confirmation: id, states: receipt.states, results, observations, ...(plan.notes ? { notes: plan.notes } : {}), reconcile: command(id, options) });
+    return writeOutput({ confirmation: id, states: receipt.states, results, observations, ...(plan.notes ? { notes: plan.notes } : {}), reconcile: command(id, options) }, Boolean(options.json));
 }
 export async function rawWritePlan(client, method, path, payload) {
     const route = validatePayload(method, path, payload);