@knowttl/gitea-axi 0.1.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) knowttl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -97,6 +97,12 @@ gitea-axi config path
 gitea-axi doctor
 ```
 
+Raw `api GET` contents reads support root and nested directories, returning directory arrays (including empty arrays) or individual file, symlink and submodule objects under `data`.
+Nullable contents and link fields are accepted while non-null values retain their schema type checks.
+Use literal slashes for nested paths such as `repos/OWNER/NAME/contents/src/main.ts`, `repos/OWNER/NAME/editorconfig/src/main.ts` and Git ref filters such as `repos/OWNER/NAME/git/refs/heads/main`.
+This multi-segment support applies only to those GET routes; other route parameters and raw writes retain single-segment matching.
+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.
@@ -107,10 +113,13 @@ An explicit repository wins over a matching local origin remote; a remote never
 `-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.
 Hosted repository reads require an explicit repository.
-Lists default to 30 returned records, except `run list` and `release list` default to 10; collection scans are bounded to 20 pages or 1000 unique records.
+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.
+Unpaginated collections, including inline review comments and attachment metadata, are complete unless the server supplies a continuation link or the collection exceeds the record bound; a response of 50 records alone does not imply another page.
 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.
+List output distinguishes unknown totals from known totals and reports continuation and truncation.
+For an unpaginated collection without a continuation link, a missing server total is inferred from the unique records received.
 Issue, PR and run lists expose `unfiltered_total` as the server count before client-side filtering; `total` is the filtered count when the bounded read is complete, otherwise null.
 Truncated output includes guidance to raise `--limit` (maximum 1000), or use raw API pagination when the bounded read is incomplete.
 The dashboard shows a compact repository projection (ID, full name, visibility, default branch, open issue and PR counts, and update time), plus up to five issues, PRs, labels, releases and task summaries per section.
@@ -253,6 +262,7 @@ gitea-axi label create --repo OWNER/NAME --name bug --color ff0000 --allow-write
 The preview identifies the exact operations, payload and current preconditions without sending a mutation.
 Confirmation binds the credential revision, origin, target, operations, canonical payload and preconditions.
 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.
 Pin changes verify the complete expected pin membership; deletion verifies absence of the selected identity and preservation of all remaining records.
 A mismatched or failed verification reports an unknown outcome.
@@ -273,7 +283,8 @@ API timeouts, interrupted requests and partial failures return `WRITE_OUTCOME_UN
 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.
 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 and repository name case variants as the same identity.
+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.
 Keep its private receipts until the outcome has been investigated.
 Native Windows write protection and live write commissioning remain unverified; Windows writes are refused.
 
@@ -301,6 +312,7 @@ See [the credential schema](axi-credential.schema.json) for profile fields and e
 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.
+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`.
 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.
@@ -412,4 +424,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution rules.
 
 ## License
 
-No license file is published in this repository yet; licensing is pending.
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

package/dist/api.js

@@ -30,7 +30,11 @@ for (const definition of Object.values(vendor.definitions)) {
     }
 }
 const requestDefinitions = structuredClone(vendor.definitions);
-for (const [name, fields] of Object.entries({ PullRequest: ['merge_commit_sha'], ContentsResponse: ['submodule_git_url', 'target'] })) {
+for (const [name, fields] of Object.entries({
+    PullRequest: ['merge_commit_sha'],
+    ContentsResponse: ['submodule_git_url', 'target', 'content', 'encoding', 'download_url', 'html_url', 'git_url'],
+    FileLinksResponse: ['git', 'html'],
+})) {
     for (const field of fields) {
         const properties = vendor.definitions[name].properties;
         properties[field] = { anyOf: [properties[field], { type: 'null' }] };
@@ -45,7 +49,11 @@ export function object(value) {
 }
 export function effectFor(method, path) {
     path = canonicalPath(path);
-    return routes.find(route => route.method === method && new RegExp('^' + route.path.split(/(\{[^}]+\})/).map(part => /^\{[^}]+\}$/.test(part) ? '[^/]+' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('') + '$').test(path.split('?')[0]));
+    return routes.find(route => route.method === method && new RegExp('^' + route.path.split(/(\{[^}]+\})/).map(part => {
+        if (/^\{[^}]+\}$/.test(part))
+            return route.multiSegmentParameters?.includes(part.slice(1, -1)) ? '[^/]+(?:/[^/]+)*' : '[^/]+';
+        return part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }).join('') + '$').test(path.split('?')[0]));
 }
 export function canonicalPath(path) {
     const pathname = path.split('?')[0];
@@ -96,7 +104,8 @@ export function validate(path, value) {
     if (route.schema) {
         let validator = validators.get(route.path);
         if (!validator) {
-            validator = ajv.compile({ ...route.schema, definitions: vendor.definitions });
+            const schema = route.operation === 'repoGetContents' ? { anyOf: [route.schema, { type: 'array', items: route.schema }] } : route.schema;
+            validator = ajv.compile({ ...schema, definitions: vendor.definitions });
             validators.set(route.path, validator);
         }
         if (!validator(value))
@@ -158,7 +167,8 @@ export async function rawRead(client, path) {
     return { data, total: count && /^\d+$/.test(count) ? Number(count) : null, next: nextPage(response.headers, path, client.origin), truncated: false };
 }
 export async function collect(client, path, envelope) {
-    let next = path + (path.includes('?') ? '&' : '?') + 'limit=50&page=1';
+    const paginated = routeFor(path).paginated;
+    let next = paginated ? path + (path.includes('?') ? '&' : '?') + 'limit=50&page=1' : path;
     const seenPages = new Set();
     const items = new Map();
     let total = null;
@@ -185,11 +195,11 @@ export async function collect(client, path, envelope) {
             total = object(data).total_count;
         const link = response.headers.get('link');
         next = nextPage(response.headers, path, client.origin);
-        if (!next && !link && rows.length >= 50) {
+        if (paginated && !next && !link && rows.length >= 50) {
             const url = new URL([...seenPages].at(-1), client.origin);
             url.searchParams.set('page', String(Number(url.searchParams.get('page')) + 1));
             next = url.pathname + url.search;
         }
     }
-    return { items: [...items.values()], total, next, truncated: next !== null };
+    return { items: [...items.values()].slice(0, 1000), total: total ?? (!paginated && !next ? items.size : null), next, truncated: next !== null || items.size > 1000 };
 }

package/dist/credentials.js

@@ -35,6 +35,11 @@ function validateProfile(profile) {
 const secrets = [];
 export function registerSecret(value) { if (value)
     secrets.push(value); }
+const controls = new Set();
+export function controlText(value) {
+    controls.add(value);
+    return value;
+}
 export function redact(value) {
     if (Array.isArray(value))
         return value.map(redact);
@@ -43,6 +48,10 @@ export function redact(value) {
             /^(?:token|access_token|refresh_token|password|secret|authorization|private_key)$/i.test(key) ? '[REDACTED]' : redact(item)]));
     if (typeof value !== 'string')
         return value;
+    // Callers register only generated control text, never payloads or upstream response text.
+    const preserved = [...controls].filter(text => value.includes(text)).sort((a, b) => b.length - a.length);
+    if (preserved.length)
+        return value.split(new RegExp('(' + preserved.map(text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|') + ')')).map(part => controls.has(part) ? part : redact(part)).join('');
     let output = value;
     for (const secret of secrets) {
         for (const form of [secret, JSON.stringify(secret).slice(1, -1), encodeURIComponent(secret)]) {

package/dist/writes.js

@@ -1,6 +1,6 @@
 import { createHash, createHmac, randomBytes, randomUUID } from 'node:crypto';
 import { constants, existsSync } from 'node:fs';
-import { mkdir, open, rm } from 'node:fs/promises';
+import { mkdir, open, readdir, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join } from 'node:path';
 import { canonicalPath, collect, effectFor, object, read, validate, validatePayload } from './api.js';
@@ -10,6 +10,7 @@ import { verifyPull } from './pulls.js';
 import { verifyWorkflow } from './repo-workflows.js';
 import { actionValues, valuePlan, verifyValue } from './action-values.js';
 import { verifyUploads } from './attachments.js';
+import { controlText } from './credentials.js';
 function canonical(value) {
     if (Array.isArray(value))
         return '[' + value.map(canonical).join(',') + ']';
@@ -21,9 +22,9 @@ const digest = (value) => createHash('sha256').update(canonical(value)).digest('
 const usage = (message) => { throw new CliError('USAGE', message, 2); };
 const logPath = () => process.env.GITEA_AXI_WRITE_LOG ?? join(process.platform === 'win32' ? process.env.LOCALAPPDATA ?? homedir() : process.env.XDG_STATE_HOME ?? join(homedir(), '.local/state'), 'gitea-axi', 'writes.log');
 const directory = () => join(dirname(logPath()), 'write-receipts');
-const command = (id, options) => 'gitea-axi write reconcile ' + id +
-    (options.config ? ' --config ' + shell(String(options.config)) : '') + (options.profile ? ' --profile ' + shell(String(options.profile)) : '') +
-    (options.origin ? ' --origin ' + shell(String(options.origin)) : '') + (options['allow-insecure-http'] ? ' --allow-insecure-http' : '');
+const command = (id, options) => controlText('gitea-axi write reconcile ' + id) +
+    (options.config ? controlText(' --config ') + shell(String(options.config)) : '') + (options.profile ? controlText(' --profile ') + shell(String(options.profile)) : '') +
+    (options.origin ? controlText(' --origin ') + shell(String(options.origin)) : '') + (options['allow-insecure-http'] ? controlText(' --allow-insecure-http') : '');
 function shell(value) { return "'" + value.replaceAll("'", "'\\''") + "'"; }
 async function key(root) {
     await mkdir(root, { recursive: true, mode: 0o700 });
@@ -51,6 +52,7 @@ export async function reconcile(client, id) {
     if (receipt.origin !== client.origin)
         throw new CliError('CONFIRMATION_MISMATCH', 'Reconciliation origin differs from the attempted write');
     const observations = await observe(client, receipt.reads);
+    controlText(id);
     return { 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' };
 }
@@ -225,11 +227,9 @@ export async function write(client, identity, plan, options, executeLocal) {
             return { method: step.method, path: step.path, payload: step.payload, local: localOperation(step).operation };
         const route = validatePayload(step.method, step.path, step.payload);
         const segments = canonicalPath(step.path).split('/');
-        if (/\{(?:template_)?repo\}/.test(route.path)) {
-            for (const [index, segment] of route.path.split('/').entries()) {
-                if (/^\{(?:owner|repo|org|template_owner|template_repo)\}$/.test(segment)) {
-                    segments[index] = encodeURIComponent(decodeURIComponent(segments[index]).toLowerCase());
-                }
+        for (const [index, segment] of route.path.split('/').entries()) {
+            if (/^\{(?:owner|repo|org|template_owner|template_repo)\}$/.test(segment)) {
+                segments[index] = encodeURIComponent(decodeURIComponent(segments[index]).toLowerCase());
             }
         }
         return { method: step.method, path: segments.join('/'), ...(step.payload === undefined ? {} : { payload: step.payload }), ...(step.upload ? { upload: step.upload } : {}) };
@@ -238,6 +238,25 @@ export async function write(client, identity, plan, options, executeLocal) {
     const effectDigest = (value) => plan.sensitive ? createHmac('sha256', secret).update(canonical(value)).digest('hex') : digest(value);
     const attempt = effectDigest({ origin: client.origin, steps: effectSteps });
     const guards = [...new Set(effectSteps.filter((_, index) => !plan.steps[index].createdPull).map(step => join(root, effectDigest({ origin: client.origin, step }) + '.attempt')))];
+    const organization = (path) => /^\/api\/v1\/orgs\/([^/?]+)/.exec(canonicalPath(path))?.[1];
+    const organizations = new Set(effectSteps.map(step => organization(step.path)).filter(value => value !== undefined));
+    if (organizations.size) {
+        for (const name of await readdir(root)) {
+            if (!/^[a-f0-9]{64}\.attempt$/.test(name))
+                continue;
+            const previous = await readPrivateFile(join(root, name), true);
+            if (!/^[a-f0-9-]{36}$/.test(previous))
+                usage('Invalid persisted confirmation ID');
+            const receipt = JSON.parse(await readPrivateFile(join(root, previous + '.json'), true));
+            if (receipt.guardVersion !== 2 && receipt.origin === client.origin &&
+                receipt.reads.some(path => {
+                    const org = organization(path);
+                    return org !== undefined && organizations.has(encodeURIComponent(decodeURIComponent(org).toLowerCase()));
+                })) {
+                throw new CliError('WRITE_OUTCOME_UNKNOWN', 'An attempt already exists; reconcile with ' + command(previous, options));
+            }
+        }
+    }
     for (const guard of guards) {
         if (existsSync(guard)) {
             const previous = await readPrivateFile(guard, true);
@@ -245,18 +264,19 @@ export async function write(client, identity, plan, options, executeLocal) {
         }
     }
     if (options.preview) {
-        const id = randomUUID();
-        const receipt = { binding, origin: client.origin, reads: plan.reads, states: plan.steps.map(() => 'pending'), operations, attempt,
+        const id = controlText(randomUUID());
+        const receipt = { binding, origin: client.origin, reads: plan.reads, states: plan.steps.map(() => 'pending'), operations, attempt, guardVersion: 2,
             ...(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 { 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: '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') };
     }
     const id = String(options.confirm);
     if (!/^[a-f0-9-]{36}$/.test(id))
         usage('Use the confirmation ID returned by --preview');
     const path = join(root, id + '.json');
     const receipt = JSON.parse(await readPrivateFile(path, true));
+    controlText(id);
     if (receipt.states.some(state => state !== 'pending'))
         throw new CliError('WRITE_OUTCOME_UNKNOWN', 'Confirmation was already dispatched; reconcile with ' + command(id, options));
     if (receipt.binding !== binding)
@@ -285,6 +305,7 @@ export async function write(client, identity, plan, options, executeLocal) {
             throw error;
         }
     }
+    receipt.guardVersion = 2;
     const results = [];
     const outcome = () => 'steps=' + receipt.states.join(',') + (receipt.createdPull ? '; created PR id=' + receipt.createdPull.id + ' number=' + receipt.createdPull.number : '') + (receipt.createdParent ? '; existing parent id=' + receipt.createdParent.id + (receipt.createdParent.number ? ' number=' + receipt.createdParent.number : '') : '') + '; reconcile with ' + command(id, options);
     for (const [index, step] of plan.steps.entries()) {