@knowttl/gitea-axi 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# gitea-axi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An agent CLI for Gitea repository, issue and pull request reads with private credential profiles.
+It includes a bounded repository dashboard, list and detail views, reviews, checks, diffs and classified raw GET requests.
+Verification uses offline fakes only; live Gitea access remains unverified.
+
+Use Node 24.14.0 (minimum 24.11.0) and npm 11.9.0.
+Dependencies are exact in `package.json` and transitive versions are locked in `package-lock.json`.
+Install the public npm package:
+
+```sh
+npm install -g @knowttl/gitea-axi
+gitea-axi --version
+```
+
+The executable is `gitea-axi`.
+To build from source:
+
+```sh
+npm ci --ignore-scripts
+npm run build
+node dist/cli.js repo view --help
+node scripts/verify.mjs --task S1.1
+```
+
+The verification driver builds and packs the CLI, installs that tarball into an empty temporary prefix and invokes its installed bin from outside the source tree.
+Dependency installation can access npm; Gitea requests use only local fakes.
+Only the local HTTP fake replaces the vendor boundary.
+The S1.1 driver checks AC-001, AC-002 and AC-004, package contents, registry freshness, type checking, linting and refusal cases.
+Its report contains exact process invocations, assertions, runtime pins and the package SHA-256.
+Each driver prints its report path.
+Set `GITEA_AXI_REPORT` to retain the report at a chosen path.
+The default report goes to a unique file in the OS temporary directory; temporary installation files are removed.
+
+Command syntax:
+
+```text
+gitea-axi repo view --repo OWNER/NAME --origin https://gitea.example.test
+gitea-axi --repo OWNER/NAME
+gitea-axi issue list --repo OWNER/NAME --state open --limit 2
+gitea-axi pr view 7 --repo OWNER/NAME --reviews --checks
+gitea-axi pr view 7 --repo OWNER/NAME --fields number,title,headRefOid
+gitea-axi pr checks 7 --repo OWNER/NAME --watch --timeout 30
+gitea-axi api GET repos/OWNER/NAME
+gitea-axi auth status
+gitea-axi profile list
+gitea-axi config path
+gitea-axi doctor
+```
+
+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.
+Business reads share a 30-second deadline, except check watches use their explicit timeout; each request has a 2,000,000-byte response limit.
+`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.
+Hosted repository reads require an explicit repository.
+Lists default to 30 returned records and bound collection scans to 20 pages or 1000 unique records.
+Issue and PR lists filter before globally sorting the collected records and applying the return limit.
+Milestone selectors use exact names, including numeric-looking names.
+List output distinguishes unknown vendor totals from known totals and reports continuation and truncation.
+Dashboard sections report permission failures as partial results.
+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.
+`--fields` refuses unknown names and fields without an evidenced Gitea equivalent, and cannot combine with detail expansion flags.
+Raw requests accept `api [GET] <relative-path>` for JSON metadata and refuse absolute URLs, traversal, secret query fields, credential-bearing routes, administrative routes, text or binary downloads and unclassified routes.
+HTTP 401, 403 and ambiguous 404 responses remain distinct failures, and rate-limit retry hints never cause automatic retries.
+
+`src/registry.ts` owns command metadata, help and the host inventory.
+`npm run generate` generates those artifacts plus the consumed response schemas, route types and classified raw-route registry from the retained Swagger.
+`npm run generate:check` rejects stale artifacts.
+`evidence/README.md` records retained source paths, provenance and hashes.
+Credentialed reads use the shipped `axi-credential.schema.json` contract.
+The config file is `$XDG_CONFIG_HOME/gitea-axi/config.json`, otherwise `~/.config/gitea-axi/config.json` on Linux, and `%APPDATA%\gitea-axi\config.json` on Windows.
+`--config` takes precedence over `GITEA_AXI_CONFIG`, and `--profile` takes precedence over `GITEA_AXI_PROFILE`.
+`--config` requires an absolute path.
+The config object contains `version: 1`, a `profiles` object keyed by profile name, and an optional `defaultProfile` name.
+Without `--profile` or `GITEA_AXI_PROFILE`, setting any environment-profile field selects the environment profile instead of the config file; incomplete profiles are refused.
+File selection uses the explicit profile, otherwise the file's `defaultProfile` or its sole profile.
+Multiple file profiles without a selection or default are refused.
+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.
+Redaction also masks recognized secret fields, secret query values, URL credentials, JWTs, private keys and account keys.
+The complete environment profile uses `GITEA_AXI_ORIGIN`, `GITEA_AXI_TOKEN_ORIGIN` and a JSON SecretRef in `GITEA_AXI_TOKEN`.
+Set `GITEA_AXI_ALLOW_INSECURE_HTTP=true` to permit HTTP for that environment profile; only the exact values `true` and `false` are accepted.
+HTTP requires `allowInsecureHttp: true` on that exact profile; a runtime origin override cannot reuse the token for another origin.
+Keep file references owned by the invoking account with mode 0600 on Linux.
+Windows file protection is PENDING; file SecretRefs are refused until native ACL verification is available.
+Use env SecretRefs on Windows.
+`auth status` resolves the selected credentials locally; its `authenticated` field reports token availability without checking the server.
+`doctor` checks the current identity through Gitea's `/api/v1/user` endpoint.
+
+Stock Artium support is not claimed.
+Full profile management and native Windows permission verification remain pending.
+
+`npm test` runs the installed-package checks with local Gitea fakes for S1.1 and S2.1 through S2.4.
+Each S2 task also has an independent entrypoint, for example `node scripts/verify.mjs --task S2.3`.
+The S2 fixtures contain synthetic non-empty records authored against the retained schemas, with independent expected projections for supported selected PR fields and explicit capability refusals for the remaining fields.
+Set `GITEA_AXI_ARTIUM_ROOT` to a built admission fixture containing this package's read inventory to repeat business reads through a real local Artium server, client, credential writer and runner.
+Set `GITEA_AXI_ARTIUM_MANIFEST` to that fixture's frozen manifest; the S2 proof records its revision and manifest digest alongside the tested source head and package digest.
+The S2 driver reports whether Artium was selected; a standalone pass does not establish hosted admission.
+Hosted CLI behavior scenarios must execute and match the expected exit code and standalone result; expected admission refusals are checked separately for their exact error code and recorded in `hostedRefusals`.
+The fixture must admit item positionals, raw GET paths and the declared read flags while continuing to block credential and endpoint overrides.

package/axi-credential.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Gitea profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["origin", "tokenOrigin", "token"],
+  "properties": {
+    "origin": { "type": "string", "pattern": "^https?://[^/@?#\\s]+$" },
+    "tokenOrigin": { "type": "string", "pattern": "^https?://[^/@?#\\s]+$" },
+    "token": {
+      "x-secret": true,
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["env"], "properties": { "env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
+        { "type": "object", "additionalProperties": false, "required": ["file"], "properties": { "file": { "type": "string", "pattern": "^(?:/|[A-Za-z]:[\\\\/])" } } }
+      ]
+    },
+    "allowInsecureHttp": { "type": "boolean", "default": false }
+  },
+  "if": { "properties": { "origin": { "pattern": "^http:" } } },
+  "then": { "required": ["allowInsecureHttp"], "properties": { "allowInsecureHttp": { "const": true } } }
+}

package/dist/api.js

@@ -0,0 +1,134 @@
+import { readFileSync } from 'node:fs';
+import { Ajv } from 'ajv';
+import { CliError } from './error.js';
+const vendor = JSON.parse(readFileSync(new URL('../schemas/vendor.json', import.meta.url), 'utf8'));
+const routes = JSON.parse(readFileSync(new URL('../generated/routes.json', import.meta.url), 'utf8'));
+routes.sort((a, b) => b.path.replace(/\{[^}]+\}/g, '').length - a.path.replace(/\{[^}]+\}/g, '').length);
+const required = {
+    Issue: ['id', 'number', 'title', 'state'], PullRequest: ['id', 'number', 'title', 'state', 'head', 'base'],
+    Label: ['id', 'name', 'color'], Repository: ['id', 'full_name', 'default_branch'], User: ['id', 'login'],
+    Comment: ['id', 'body', 'user'], PullReview: ['id', 'user', 'state', 'body', 'commit_id'],
+    CommitStatus: ['id', 'context', 'status'], Milestone: ['id', 'title'],
+    PRBranchInfo: ['sha', 'ref'], CombinedStatus: ['sha', 'statuses', 'total_count'],
+};
+for (const [name, fields] of Object.entries(required)) {
+    if (vendor.definitions[name])
+        vendor.definitions[name].required = fields;
+}
+// Gitea's Go pointer fields and nil slices serialize as null, which Swagger 2 cannot express.
+for (const definition of Object.values(vendor.definitions)) {
+    for (const [key, property] of Object.entries(definition.properties ?? {})) {
+        if (property.$ref && !['state', 'status'].includes(key) || property.type === 'array' || property.format === 'date-time') {
+            definition.properties[key] = { anyOf: [property, { type: 'null' }] };
+        }
+    }
+}
+const ajv = new Ajv({ strict: false, validateFormats: false });
+const validators = new Map();
+export function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new CliError('INVALID_RESPONSE', 'Expected an object from Gitea');
+    return value;
+}
+export function routeFor(path) {
+    const route = routes.find(route => new RegExp('^' + route.path.replace(/[.]/g, '\\.').replace(/\{[^}]+\}/g, '[^/]+') + '$').test(path));
+    if (route?.effect === 'admin')
+        throw new CliError('READ_ONLY', 'Administrative API routes are refused; only metadata reads are available');
+    if (route?.effect === 'credential')
+        throw new CliError('READ_ONLY', 'Credential-bearing API routes are refused; only metadata reads are available');
+    if (route?.effect === 'download')
+        throw new CliError('READ_ONLY', 'Text and binary download routes are refused; only JSON metadata reads are available');
+    if (!route || route.effect !== 'read')
+        throw new CliError('READ_ONLY', 'Only classified metadata reads are available');
+    return route;
+}
+export function validate(path, value) {
+    const route = routeFor(path);
+    if (route.schema) {
+        let validator = validators.get(route.path);
+        if (!validator) {
+            validator = ajv.compile({ ...route.schema, definitions: vendor.definitions });
+            validators.set(route.path, validator);
+        }
+        if (!validator(value))
+            throw new CliError('INVALID_RESPONSE', route.operation + ' returned invalid fields');
+    }
+    return value;
+}
+export function rawPath(input) {
+    let decoded;
+    try {
+        decoded = decodeURIComponent(input);
+    }
+    catch {
+        throw new CliError('USAGE', 'Malformed API path', 2);
+    }
+    if (/^[a-z]+:/i.test(input) || input.startsWith('//') || /[\\#\s]/.test(decoded) || decoded.includes('%') ||
+        decoded.split(/[/?]/).some(part => part === '.' || part === '..'))
+        throw new CliError('USAGE', 'Use a relative API path without traversal', 2);
+    const [pathname, query = ''] = input.split('?');
+    for (const key of new URLSearchParams(query).keys()) {
+        if (/token|secret|password|authorization|api.?key/i.test(key))
+            throw new CliError('CONFIG_INVALID', 'Secret query fields are refused');
+    }
+    const path = pathname === '/swagger.v1.json' ? pathname : pathname?.startsWith('/api/v1/') ? pathname : '/api/v1/' + pathname?.replace(/^\//, '');
+    if (path !== '/swagger.v1.json')
+        routeFor(path);
+    return path + (query ? '?' + query : '');
+}
+export async function read(client, path) {
+    const value = await client.get(path);
+    return validate(path.split('?')[0], value);
+}
+function nextPage(headers, path, origin) {
+    const target = headers.get('link')?.split(',').find(part => /rel="?next"?/.test(part))?.match(/<([^>]+)>/)?.[1];
+    if (!target)
+        return null;
+    const url = new URL(target, new URL(path, origin));
+    if (url.origin !== origin || url.pathname !== new URL(path, origin).pathname || url.username || url.password || url.hash) {
+        throw new CliError('UNSAFE_PAGINATION', 'Pagination must stay on the selected origin and collection');
+    }
+    return rawPath(url.pathname + url.search);
+}
+export async function rawRead(client, path) {
+    const response = await client.request(path);
+    const data = path === '/swagger.v1.json' ? response.data : validate(new URL(path, client.origin).pathname, response.data);
+    const count = response.headers.get('x-total-count');
+    return { data, total: count && /^\d+$/.test(count) ? Number(count) : null, next: nextPage(response.headers, path, client.origin), truncated: false };
+}
+export async function collect(client, path, envelope) {
+    let next = path + (path.includes('?') ? '&' : '?') + 'limit=50&page=1';
+    const seenPages = new Set();
+    const items = new Map();
+    let total = null;
+    while (next && seenPages.size < 20 && items.size < 1000 && Date.now() < client.deadline) {
+        if (seenPages.has(next))
+            throw new CliError('INVALID_RESPONSE', 'Gitea repeated a pagination URL');
+        seenPages.add(next);
+        const response = await client.request(next);
+        const data = validate(new URL(next, client.origin).pathname, response.data);
+        const rows = envelope ? object(data)[envelope] : data;
+        if (!Array.isArray(rows))
+            throw new CliError('INVALID_RESPONSE', 'Expected a Gitea list' + (envelope ? ' envelope ' + envelope : ''));
+        for (const value of rows) {
+            const row = object(value);
+            const id = row.id ?? row.number ?? row.sha ?? row.filename ?? (row.user && row.content ? String(object(row.user).id) + ':' + row.content : undefined);
+            if (typeof id !== 'number' && typeof id !== 'string')
+                throw new CliError('INVALID_RESPONSE', 'List record has no identity');
+            items.set(String(id), row);
+        }
+        const count = response.headers.get('x-total-count');
+        if (count && /^\d+$/.test(count))
+            total = Number(count);
+        if (envelope && typeof object(data).total_count === 'number')
+            total = object(data).total_count;
+        const link = response.headers.get('link');
+        next = nextPage(response.headers, path, client.origin);
+        if (!next && !link && rows.length >= 50) {
+            const url = new URL([...seenPages].at(-1), client.origin);
+            url.searchParams.set('page', String(Number(url.searchParams.get('page')) + 1));
+            next = url.pathname + url.search;
+        }
+    }
+    return { items: [...items.values()], total, next, truncated: next !== null };
+}

package/dist/cli.js

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

package/dist/credentials.js

@@ -0,0 +1,133 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { Ajv } from 'ajv';
+import { CliError } from './error.js';
+import { readPrivateFile } from './private-file.js';
+const schema = JSON.parse(readFileSync(new URL('../axi-credential.schema.json', import.meta.url), 'utf8'));
+const validate = new Ajv({ strict: false }).compile(schema);
+const secrets = [];
+export function redact(value) {
+    if (Array.isArray(value))
+        return value.map(redact);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key,
+            /^(?:token|access_token|refresh_token|password|secret|authorization|private_key)$/i.test(key) ? '[REDACTED]' : redact(item)]));
+    if (typeof value !== 'string')
+        return value;
+    let output = value;
+    for (const secret of secrets) {
+        for (const form of [secret, JSON.stringify(secret).slice(1, -1), encodeURIComponent(secret)]) {
+            output = output.replaceAll(form, '[REDACTED]');
+        }
+    }
+    return output.replace(/([?&](?:token|access_token|api_key|sig)=)[^&#\s]*/gi, '$1[REDACTED]')
+        .replace(/(https?:\/\/)[^/\s@]+@/gi, '$1[REDACTED]@')
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED]')
+        .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?-----END [^-]*PRIVATE KEY-----/g, '[REDACTED]')
+        .replace(/(AccountKey=)[^;\s]+/gi, '$1[REDACTED]');
+}
+export function configPath(explicit) {
+    const base = process.platform === 'win32' ? process.env.APPDATA : process.env.XDG_CONFIG_HOME;
+    return explicit ?? process.env.GITEA_AXI_CONFIG ?? join(base && isAbsolute(base) ? base : join(homedir(), '.config'), 'gitea-axi', 'config.json');
+}
+export async function profileList(explicit) {
+    const path = configPath(explicit);
+    if (!existsSync(path))
+        return { path, profiles: [] };
+    const config = await readConfig(path);
+    return { path, profiles: Object.keys(config.profiles).map(name => ({ name, default: name === config.defaultProfile })) };
+}
+async function readConfig(path) {
+    let config;
+    try {
+        config = JSON.parse(await readPrivateFile(path));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('CONFIG_INVALID', 'Invalid profile configuration');
+    }
+    if (!config || config.version !== 1 || !config.profiles || Array.isArray(config.profiles) || typeof config.profiles !== 'object' ||
+        Object.keys(config).some(key => !['version', 'profiles', 'defaultProfile'].includes(key)) ||
+        Object.keys(config.profiles).some(name => !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name))) {
+        throw new CliError('CONFIG_INVALID', 'Invalid profile configuration');
+    }
+    return config;
+}
+export function canonicalOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (!/^https?:\/\/[^\s\\/?#@]+\/?$/i.test(value) || !url.hostname || url.username || url.password)
+            throw new Error();
+        return url.origin;
+    }
+    catch {
+        throw new CliError('CONFIG_INVALID', 'origin must contain only HTTP or HTTPS scheme, host and port');
+    }
+}
+export async function credentials(override, allowHttp, options = {}) {
+    const path = configPath(options.config);
+    const selected = options.profile ?? process.env.GITEA_AXI_PROFILE;
+    const fields = ['ORIGIN', 'TOKEN_ORIGIN', 'TOKEN', 'ALLOW_INSECURE_HTTP'];
+    const hasEnv = fields.some(field => process.env['GITEA_AXI_' + field] !== undefined);
+    let profile;
+    let profileName = 'environment';
+    if (!selected && hasEnv) {
+        let token;
+        try {
+            token = JSON.parse(process.env.GITEA_AXI_TOKEN ?? 'null');
+        }
+        catch { /* Schema reports only the field name. */ }
+        const http = process.env.GITEA_AXI_ALLOW_INSECURE_HTTP;
+        if (http !== undefined && http !== 'true' && http !== 'false')
+            throw new CliError('CONFIG_INVALID', 'allowInsecureHttp must be true or false');
+        profile = { origin: process.env.GITEA_AXI_ORIGIN, tokenOrigin: process.env.GITEA_AXI_TOKEN_ORIGIN, token,
+            allowInsecureHttp: http === 'true' };
+    }
+    else if (existsSync(path)) {
+        const config = await readConfig(path);
+        const names = Object.keys(config.profiles);
+        const name = selected ?? config.defaultProfile ?? (names.length === 1 ? names[0] : undefined);
+        if (!name)
+            throw new CliError(names.length ? 'PROFILE_AMBIGUOUS' : 'PROFILE_REQUIRED', 'Select a profile');
+        if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name) || !Object.hasOwn(config.profiles, name))
+            throw new CliError('PROFILE_NOT_FOUND', 'Selected profile was not found');
+        profile = config.profiles[name];
+        profileName = name;
+    }
+    else if (selected || options.config || process.env.GITEA_AXI_CONFIG) {
+        throw new CliError('PROFILE_NOT_FOUND', 'Selected profile configuration was not found');
+    }
+    else if (override) {
+        const origin = canonicalOrigin(override);
+        if (origin.startsWith('http:') && !allowHttp)
+            throw new CliError('USAGE', 'HTTP requires --allow-insecure-http for the explicit --origin', 2);
+        return { origin };
+    }
+    else {
+        throw new CliError('AUTH_REQUIRED', 'Select a configured profile or an explicit anonymous --origin');
+    }
+    if (!validate(profile))
+        throw new CliError('CONFIG_INVALID', 'Invalid profile field: ' + (validate.errors?.[0]?.instancePath || 'token/origin'));
+    const origin = canonicalOrigin(profile.origin);
+    if (origin !== canonicalOrigin(profile.tokenOrigin) || (override && canonicalOrigin(override) !== origin)) {
+        throw new CliError('AUTH_BINDING_MISMATCH', 'origin must match tokenOrigin before resolving token');
+    }
+    if (origin.startsWith('http:') && !profile.allowInsecureHttp)
+        throw new CliError('CONFIG_INVALID', 'HTTP requires allowInsecureHttp on the selected profile');
+    let token;
+    if ('env' in profile.token)
+        token = process.env[profile.token.env] ?? '';
+    else {
+        if (!isAbsolute(profile.token.file) || /^\\\\/.test(profile.token.file))
+            throw new CliError('CONFIG_INVALID', 'token file must be an absolute local path');
+        token = (await readPrivateFile(profile.token.file, true)).replace(/^\uFEFF/, '').trimEnd();
+    }
+    if (!token)
+        throw new CliError('AUTH_REQUIRED', 'token reference is empty');
+    secrets.push(token);
+    if (/[\r\n]/.test(token))
+        throw new CliError('CONFIG_INVALID', 'token must be a single line');
+    return { origin, token, profile: profileName, source: 'env' in profile.token ? 'env:' + profile.token.env : 'file:' + profile.token.file };
+}

package/dist/error.js

@@ -0,0 +1,9 @@
+export class CliError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, exitCode = 1) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+    }
+}

package/dist/main.js

@@ -0,0 +1,156 @@
+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 } 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';
+export async function main(args) {
+    let operation = 'dashboard';
+    try {
+        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);
+        operation = command.path.join(' ');
+        const rest = args[0]?.startsWith('--') || !args.length ? args : args.slice(path.length);
+        let parsed;
+        try {
+            parsed = parseArgs({
+                args: rest, allowPositionals: true, strict: true, tokens: true,
+                options: Object.fromEntries(Object.entries(command.flags).map(([name, flag]) => [name, { type: flag.type }])),
+            });
+        }
+        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);
+        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,
+                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>`] }));
+            return;
+        }
+        const options = values;
+        const takesNumber = ['issue view', 'pr view', 'pr checks', 'pr diff'].includes(operation);
+        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)
+            throw new CliError('USAGE', 'Unexpected positional argument', 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 === 'issue view' || operation === 'issue list')
+            selectedFields(options, issueFields);
+        if (operation === 'pr view')
+            selectedFields(options, prFields);
+        if (operation === 'pr list')
+            selectedFields(options, issueFields.concat(['isDraft', 'headRefName', 'baseRefName']));
+        if (operation === 'pr checks') {
+            if ((options.interval || options.timeout) && !options.watch)
+                throw new CliError('USAGE', '--timeout and --interval require --watch', 2);
+            if (options.watch && !options.timeout)
+                throw new CliError('USAGE', '--watch requires --timeout seconds', 2);
+            positive(options.timeout, 30, 3600);
+            positive(options.interval, 5, 60);
+        }
+        let apiPath;
+        if (operation === 'api') {
+            if (positionals.length === 2 && positionals[0] !== 'GET')
+                throw new CliError('READ_ONLY', 'Only GET metadata reads are available');
+            if (positionals.length < 1 || positionals.length > 2)
+                throw new CliError('USAGE', 'Use gitea-axi api [GET] <relative-path>', 2);
+            apiPath = rawPath(positionals.at(-1));
+        }
+        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) }));
+            return;
+        }
+        if (operation === 'profile list') {
+            console.log(encode(await profileList(options.config)));
+            return;
+        }
+        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 } : {}),
+        });
+        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 === 'api')
+            output = await rawRead(client, apiPath);
+        else if (operation === 'org view')
+            output = { organization: await read(client, '/api/v1/orgs/' + encodeURIComponent(positionals[0])) };
+        else if (operation === 'repo list') {
+            if (options.fields)
+                throw new CliError('USAGE', 'repo list supports its compact identity fields only', 2);
+            const path = options.org ? '/api/v1/orgs/' + encodeURIComponent(String(options.org)) + '/repos' : '/api/v1/repos/search';
+            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);
+            const base = '/api/v1/repos/' + repo.split('/').map(encodeURIComponent).join('/');
+            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']]) {
+                    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']) };
+                    }
+                    catch (error) {
+                        if (!(error instanceof CliError))
+                            throw error;
+                        sections[name] = { status: 'error', code: error.code, reason: error.message };
+                    }
+                }
+                output = { bin: process.argv[1], description: 'Gitea repository reads', repository: repo, partial: Object.values(sections).some(section => object(section).status === 'error'), sections,
+                    help: [`gitea-axi issue list --repo ${repo}`, `gitea-axi pr list --repo ${repo}`, 'gitea-axi --help'] };
+            }
+            else if (operation === 'issue list' || operation === 'pr list')
+                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 === 'pr checks') {
+                const result = await watchChecks(client, base, positionals[0], options);
+                process.exitCode = result.exitCode;
+                output = result;
+            }
+            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' } : {}) };
+            }
+        }
+        const rendered = encode(redact(output));
+        if (rendered.length > 100_000)
+            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: 'gitea-axi ' + operation + ' --help' })));
+        process.exitCode = failure.exitCode;
+    }
+}

package/dist/private-file.js

@@ -0,0 +1,49 @@
+import { open, mkdir, chmod, rename, rm, lstat } from 'node:fs/promises';
+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) {
+    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'); });
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new CliError('CONFIG_INSECURE', 'Private file must be a regular owned file; use chmod 600');
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch(() => {
+        throw new CliError('CONFIG_INSECURE', 'Private file must be a regular owned file; use chmod 600');
+    });
+    try {
+        const stat = await file.stat();
+        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');
+        }
+        return await file.readFile('utf8');
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function writePrivateFile(path, content) {
+    if (process.platform === 'win32')
+        throw new CliError('CONFIG_INSECURE', 'Native Windows ACL writes are unavailable');
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid()) {
+        throw new CliError('CONFIG_INSECURE', 'Private directory must be owned and cannot be a symlink');
+    }
+    await chmod(directory, 0o700);
+    const temporary = join(directory, '.' + randomUUID() + '.tmp');
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(content, 'utf8');
+        await file.sync();
+        await file.close();
+        await rename(temporary, path);
+    }
+    finally {
+        await file.close();
+        await rm(temporary, { force: true });
+    }
+}