@knowttl/gitea-axi 0.0.0-stage → 0.1.0

package/dist/reads.js

@@ -0,0 +1,230 @@
+import { execFileSync } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { CliError } from './error.js';
+import { collect, object, read } from './api.js';
+const scalarFields = {
+    additions: 'additions', body: 'body', changedFiles: 'changed_files', closedAt: 'closed_at', createdAt: 'created_at',
+    deletions: 'deletions', fullDatabaseId: 'id', isDraft: 'draft', maintainerCanModify: 'allow_maintainer_edit',
+    mergedAt: 'merged_at', number: 'number', title: 'title', updatedAt: 'updated_at', url: 'html_url',
+};
+const gaps = ['autoMergeRequest', 'closingIssuesReferences', 'id', 'mergeStateStatus', 'potentialMergeCommit', 'projectCards', 'projectItems', 'reviewDecision'];
+export const prFields = [...Object.keys(scalarFields), ...gaps, 'assignees', 'author', 'baseRefName', 'baseRefOid', 'closed', 'comments', 'commits', 'files',
+    'headRefName', 'headRefOid', 'headRepository', 'headRepositoryOwner', 'isCrossRepository', 'labels', 'latestReviews', 'mergeCommit',
+    'mergeable', 'mergedBy', 'milestone', 'reactionGroups', 'reviewRequests', 'reviews', 'state', 'statusCheckRollup'];
+export const issueFields = ['number', 'title', 'state', 'body', 'author', 'assignees', 'labels', 'milestone', 'createdAt', 'updatedAt', 'url'];
+export function selectedFields(options, allowed) {
+    if (typeof options.fields !== 'string')
+        return;
+    const fields = options.fields.split(',');
+    if (fields.some(field => !allowed.includes(field)) || new Set(fields).size !== fields.length)
+        throw new CliError('USAGE', 'Unknown or repeated field; choose ' + allowed.join(','), 2);
+    const gap = fields.find(field => gaps.includes(field));
+    if (gap)
+        throw new CliError('CAPABILITY_GAP', gap + ' has no evidenced Gitea equivalent');
+    if (options.full || options.comments || options.reviews || options.checks)
+        throw new CliError('USAGE', '--fields cannot combine with --full, --comments, --reviews or --checks', 2);
+    return fields;
+}
+export function positive(value, fallback, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'string' || !/^\d+$/.test(value) || Number(value) < 1 || Number(value) > maximum)
+        throw new CliError('USAGE', 'Expected a positive integer up to ' + maximum, 2);
+    return Number(value);
+}
+export function repository(explicit, origin) {
+    if (typeof explicit === 'string') {
+        if (!/^[A-Za-z0-9_][A-Za-z0-9_.-]*\/[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(explicit))
+            throw new CliError('USAGE', '--repo must be OWNER/NAME', 2);
+        return explicit;
+    }
+    if (process.env.GITEA_AXI_PROFILE === 'artium')
+        throw new CliError('USAGE', 'Hosted calls require --repo OWNER/NAME', 2);
+    let remote;
+    try {
+        remote = execFileSync('git', ['config', '--get', 'remote.origin.url'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        throw new CliError('USAGE', 'Select --repo OWNER/NAME or a matching origin remote', 2);
+    }
+    let url;
+    try {
+        url = new URL(remote.replace(/^git@([^:]+):(.+)$/, 'ssh://git@$1/$2'));
+    }
+    catch {
+        throw new CliError('USAGE', 'Remote must identify a Gitea host; use --repo', 2);
+    }
+    const target = new URL(origin);
+    if (url.hostname !== target.hostname || (url.port && url.port !== target.port))
+        throw new CliError('USAGE', 'Remote host does not match the selected credential origin; use --repo', 2);
+    return repository(url.pathname.slice(1).replace(/\.git$/, ''), origin);
+}
+const user = (value) => value == null ? null : { login: object(value).login, name: object(value).full_name ?? null };
+const users = (value) => value == null ? [] : value.map(user);
+const label = (value) => { const row = object(value); return { name: row.name, color: row.color, description: row.description ?? null }; };
+function preview(body, full) {
+    const text = typeof body === 'string' ? body : '';
+    return full || text.length <= 1000 ? text : text.slice(0, 1000) + `... (truncated, ${text.length} chars total; use --full)`;
+}
+export function issue(row, full = false) {
+    return { number: row.number, title: row.title, state: row.state, body: preview(row.body, full), author: user(row.user),
+        assignees: users(row.assignees), labels: (row.labels ?? []).map(label), milestone: row.milestone == null ? null : { title: object(row.milestone).title },
+        createdAt: row.created_at ?? null, updatedAt: row.updated_at ?? null, url: row.html_url ?? null };
+}
+export function listOptions(options) {
+    const limit = positive(options.limit, 30, 1000);
+    if (options.state !== undefined && !['open', 'closed', 'all'].includes(String(options.state)))
+        throw new CliError('USAGE', '--state must be open, closed or all', 2);
+    if (options.sort !== undefined && !['created', 'updated', 'number', 'comments'].includes(String(options.sort)))
+        throw new CliError('USAGE', 'Unsupported --sort', 2);
+    if (options.order !== undefined && !['asc', 'desc'].includes(String(options.order)))
+        throw new CliError('USAGE', '--order must be asc or desc', 2);
+    return limit;
+}
+export async function listIssues(client, base, kind, options) {
+    const limit = listOptions(options);
+    const fields = selectedFields(options, kind === 'pr' ? issueFields.concat(['isDraft', 'headRefName', 'baseRefName']) : issueFields) ?? ['number', 'title', 'state'];
+    let milestone;
+    if (typeof options.milestone === 'string') {
+        const page = await collect(client, base + '/milestones?state=all');
+        milestone = page.items.find(row => row.title === options.milestone)?.id;
+        if (milestone === undefined)
+            throw new CliError('USAGE', 'Unknown milestone name', 2);
+    }
+    const page = await collect(client, base + (kind === 'pr' ? '/pulls' : '/issues') + '?state=all' + (kind === 'issue' ? '&type=issues' : ''));
+    const rows = page.items.filter(row => (kind !== 'issue' || !row.pull_request) &&
+        (options.state === 'all' || row.state === (options.state ?? 'open')) &&
+        (!options.author || (row.user && object(row.user).login === options.author)) &&
+        (!options.assignee || (row.assignees ?? []).some(item => item.login === options.assignee)) &&
+        (!options.label || (row.labels ?? []).some(item => item.name === options.label)) &&
+        (milestone === undefined || (row.milestone && object(row.milestone).id === milestone)));
+    const sort = options.sort === 'number' ? 'number' : options.sort === 'comments' ? 'comments' : options.sort === 'updated' ? 'updated_at' : 'created_at';
+    rows.sort((a, b) => {
+        const left = a[sort] ?? '', right = b[sort] ?? '';
+        const comparison = typeof left === 'number' && typeof right === 'number' ? left - right : String(left).localeCompare(String(right));
+        return (comparison || Number(a.number) - Number(b.number)) * (options.order === 'asc' ? 1 : -1);
+    });
+    return { items: rows.slice(0, limit).map(row => {
+            const projection = { ...issue(row), isDraft: row.draft ?? null, headRefName: row.head ? object(row.head).ref : null, baseRefName: row.base ? object(row.base).ref : null };
+            return Object.fromEntries(fields.map(field => [field, projection[field]]));
+        }), count: Math.min(rows.length, limit), total: page.truncated ? null : rows.length, vendor_total: page.total,
+        truncated: page.truncated || rows.length > limit, next: page.next, continuation: page.truncated || rows.length > limit,
+        help: `gitea-axi ${kind} view <number> --repo ${base.split('/').slice(-2).join('/')}` };
+}
+async function complete(client, path) {
+    const page = await collect(client, path);
+    if (page.truncated)
+        throw new CliError('RESPONSE_LIMIT', 'Related collection exceeds the bounded read; use the raw API to page explicitly');
+    return page.items;
+}
+async function reviews(client, path, full) {
+    const rows = await complete(client, path + '/reviews');
+    const result = [];
+    for (const row of rows) {
+        const comments = await complete(client, path + '/reviews/' + row.id + '/comments');
+        result.push({ id: row.id, author: user(row.user), state: row.state, dismissed: row.dismissed ?? false, stale: row.stale ?? false, body: preview(row.body, full), commit: { oid: row.commit_id },
+            submittedAt: row.submitted_at ?? null, comments: comments.map(comment => ({ id: comment.id, body: preview(comment.body, full), path: comment.path, position: comment.position, commit: { oid: comment.commit_id } })) });
+    }
+    return result;
+}
+export async function checks(client, base, sha) {
+    const combined = object(await read(client, base + '/commits/' + encodeURIComponent(sha) + '/status'));
+    if (combined.sha !== sha)
+        throw new CliError('INVALID_RESPONSE', 'Check response does not match the pull request head SHA');
+    const statuses = await complete(client, base + '/commits/' + encodeURIComponent(sha) + '/statuses');
+    statuses.sort((a, b) => Number(b.id) - Number(a.id));
+    const latest = new Map();
+    for (const status of statuses)
+        if (!latest.has(status.context))
+            latest.set(status.context, status);
+    const items = [...latest.values()].map(row => ({ name: row.context, state: row.status, description: row.description ?? null, url: row.target_url ?? null }));
+    const passed = items.filter(row => row.state === 'success').length;
+    const failed = items.filter(row => ['failure', 'error'].includes(String(row.state))).length;
+    const pending = items.length - passed - failed;
+    return { head: sha, items, passed, failed, pending, exitCode: !items.length || failed ? 1 : pending ? 8 : 0 };
+}
+export async function watchChecks(client, base, number, options) {
+    const seconds = positive(options.timeout, 30, 3600);
+    const interval = positive(options.interval, 5, 60) * 1000;
+    const stop = Date.now() + seconds * 1000;
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    try {
+        while (true) {
+            const pull = object(await read(client, base + '/pulls/' + number));
+            const sha = object(pull.head).sha;
+            if (typeof sha !== 'string' || !sha)
+                throw new CliError('INVALID_RESPONSE', 'Pull request head SHA is missing');
+            const result = await checks(client, base, sha);
+            if (!options.watch || !result.pending || result.failed || Date.now() >= stop || controller.signal.aborted)
+                return { ...result, cancelled: controller.signal.aborted };
+            await delay(Math.min(interval, Math.max(1, stop - Date.now())), undefined, { signal: controller.signal }).catch(error => {
+                if (!controller.signal.aborted)
+                    throw error;
+            });
+            if (Date.now() >= stop || controller.signal.aborted)
+                return { ...result, cancelled: controller.signal.aborted };
+        }
+    }
+    finally {
+        process.removeListener('SIGINT', cancel);
+        process.removeListener('SIGTERM', cancel);
+    }
+}
+export async function view(client, base, kind, number, options) {
+    const fields = selectedFields(options, kind === 'pr' ? prFields : issueFields);
+    const path = base + (kind === 'pr' ? '/pulls/' : '/issues/') + number;
+    const row = object(await read(client, path));
+    if (row.number !== Number(number))
+        throw new CliError('INVALID_RESPONSE', 'Response number does not match the selected item');
+    const result = issue(row, Boolean(options.full || fields));
+    const requested = new Set(fields ?? []);
+    if (options.comments || requested.has('comments'))
+        result.comments = (await complete(client, base + '/issues/' + number + '/comments')).map(comment => ({ id: comment.id, author: user(comment.user), body: preview(comment.body, Boolean(options.full || fields)), createdAt: comment.created_at ?? null }));
+    if (kind === 'pr') {
+        const head = object(row.head), tail = object(row.base);
+        if (typeof head.sha !== 'string' || !head.sha)
+            throw new CliError('INVALID_RESPONSE', 'Pull request head SHA is missing');
+        Object.assign(result, { headRefOid: head.sha, headRefName: head.ref ?? null, baseRefOid: tail.sha ?? null, baseRefName: tail.ref ?? null, isDraft: row.draft ?? null });
+        if (fields) {
+            for (const [field, key] of Object.entries(scalarFields))
+                if (requested.has(field))
+                    result[field] = row[key] ?? null;
+            Object.assign(result, { closed: row.state === 'closed' || row.merged === true, state: row.merged ? 'MERGED' : String(row.state).toUpperCase(),
+                headRepository: head.repo == null ? null : { name: object(head.repo).name, nameWithOwner: object(head.repo).full_name },
+                headRepositoryOwner: head.repo == null ? null : user(object(head.repo).owner), isCrossRepository: head.repo_id == null || tail.repo_id == null ? null : head.repo_id !== tail.repo_id,
+                mergeCommit: row.merge_commit_sha ? { oid: row.merge_commit_sha } : null, mergedBy: user(row.merged_by),
+                mergeable: row.mergeable == null ? 'UNKNOWN' : row.mergeable ? 'MERGEABLE' : 'CONFLICTING', reviewRequests: users(row.requested_reviewers) });
+        }
+        if (options.reviews || requested.has('reviews') || requested.has('latestReviews')) {
+            const all = await reviews(client, path, Boolean(options.full || fields));
+            result.reviews = all;
+            if (requested.has('latestReviews')) {
+                const latest = new Map();
+                for (const review of [...all].sort((a, b) => Number(a.id) - Number(b.id)))
+                    latest.set(review.author?.login, review);
+                result.latestReviews = [...latest.values()];
+            }
+        }
+        if (options.checks || requested.has('statusCheckRollup'))
+            result.statusCheckRollup = await checks(client, base, head.sha);
+        if (requested.has('commits'))
+            result.commits = (await complete(client, path + '/commits')).map(commit => ({ oid: commit.sha, message: object(commit.commit).message }));
+        if (requested.has('files'))
+            result.files = (await complete(client, path + '/files')).map(file => ({ path: file.filename, additions: file.additions, deletions: file.deletions, status: file.status }));
+        if (requested.has('reactionGroups')) {
+            const groups = new Map();
+            for (const reaction of await complete(client, base + '/issues/' + number + '/reactions'))
+                groups.set(reaction.content, [...(groups.get(reaction.content) ?? []), reaction]);
+            result.reactionGroups = [...groups].map(([content, reactions]) => ({ content, users: { totalCount: reactions.length } }));
+        }
+    }
+    return fields ? Object.fromEntries(fields.map(field => [field, result[field] ?? null])) : result;
+}
+export function boundedList(page, limit, fields) {
+    return { items: page.items.slice(0, limit).map(row => Object.fromEntries(fields.map(key => [key, row[key] ?? null]))),
+        count: Math.min(page.items.length, limit), total: page.total, next: page.next,
+        truncated: page.truncated || page.items.length > limit, continuation: page.truncated || page.items.length > limit };
+}

package/dist/registry.js

@@ -0,0 +1,55 @@
+export const command = {
+    path: ['repo', 'view'],
+    description: 'Read repository identity and default branch with server contract metadata.',
+    commandIds: ['C075'],
+    operations: ['OP-001', 'OP-002', 'OP-004'],
+    outcomes: ['AC-001', 'AC-002', 'AC-004'],
+    effect: 'read',
+    flags: {
+        repo: { type: 'string', default: 'matching local origin remote', description: 'Repository as OWNER/NAME' },
+        origin: { type: 'string', default: 'selected profile', description: 'Gitea origin; HTTPS by default' },
+        'allow-insecure-http': {
+            type: 'boolean', default: false,
+            description: 'Allow HTTP only for the explicitly selected origin',
+        },
+        help: { type: 'boolean', default: false, description: 'Show command help' },
+    },
+    examples: [
+        'gitea-axi repo view --repo sample-owner/sample-repo --origin https://gitea.example.test',
+        'gitea-axi repo view --help',
+    ],
+};
+export const limits = { timeoutMs: 30_000, responseBytes: 2_000_000 };
+const globalFlags = {
+    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' },
+};
+const repo = { repo: { type: 'string', description: 'OWNER/NAME; otherwise a matching local origin remote' } };
+const list = {
+    limit: { type: 'string', description: 'Maximum returned records, default 30, maximum 1000' },
+    state: { type: 'string', description: 'open, closed or all; default open' },
+    sort: { type: 'string', description: 'created, updated or number; default created' },
+    order: { type: 'string', description: 'asc or desc; default desc' },
+    fields: { type: 'string', description: 'Comma-separated selected fields' },
+};
+const detail = {
+    fields: list.fields, full: { type: 'boolean', description: 'Full body within response ceiling' },
+    comments: { type: 'boolean', description: 'Include comments' },
+};
+const definitions = [
+    ['dashboard', repo], ['auth status', {}], ['profile list', {}], ['config path', {}], ['doctor', {}],
+    ['repo list', { limit: list.limit, org: { type: 'string', description: 'List repositories belonging to this organization' } }],
+    ['org view', {}], ['issue list', { ...repo, ...list, assignee: { type: 'string' }, author: { type: 'string' }, label: { type: 'string' }, milestone: { type: 'string' } }],
+    ['issue view', { ...repo, ...detail }], ['label list', { ...repo, limit: list.limit }],
+    ['pr list', { ...repo, ...list, assignee: { type: 'string' }, author: { type: 'string' }, label: { type: 'string' }, milestone: { type: 'string' } }],
+    ['pr view', { ...repo, ...detail, reviews: { type: 'boolean' }, checks: { type: 'boolean' } }],
+    ['pr checks', { ...repo, watch: { type: 'boolean' }, timeout: { type: 'string', description: 'Watch deadline seconds, required with --watch' }, interval: { type: 'string', description: 'Watch interval seconds, default 5' } }],
+    ['pr diff', { ...repo, full: detail.full }], ['run list', { ...repo, limit: list.limit }],
+    ['release list', { ...repo, limit: list.limit }], ['api', {}],
+];
+export const commands = [
+    { ...command, flags: { ...command.flags, ...globalFlags } },
+    ...definitions.map(([name, flags]) => ({ path: name.split(' '), description: name === 'dashboard' ? 'Bounded repository dashboard with explicit partial results' : name,
+        flags: { ...globalFlags, ...flags }, effect: 'read' })),
+];

package/dist/repository.js

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { Ajv } from 'ajv';
+import { routes } from './vendor.generated.js';
+import { get } from './transport.js';
+import { CliError } from './error.js';
+const schemas = JSON.parse(readFileSync(new URL('../schemas/responses.json', import.meta.url), 'utf8'));
+const ajv = new Ajv();
+const validateRepository = ajv.compile(schemas.Repository);
+const validateVersion = ajv.compile(schemas.ServerVersion);
+const validateSpecification = ajv.compile(schemas.Specification);
+export async function readRepository(origin, repo, token) {
+    const version = await get(origin, routes.version, token);
+    if (!validateVersion(version))
+        throw new CliError('INVALID_RESPONSE', 'Gitea version response is invalid');
+    const specification = await get(origin, routes.specification, token);
+    if (!validateSpecification(specification)) {
+        throw new CliError('INVALID_RESPONSE', 'Gitea specification response is invalid');
+    }
+    const [owner, name] = repo.split('/');
+    const path = routes.repository.replace('{owner}', encodeURIComponent(owner)).replace('{repo}', encodeURIComponent(name));
+    const repository = await get(origin, path, token);
+    if (!validateRepository(repository) || repository.full_name !== repo || !repository.default_branch) {
+        throw new CliError('INVALID_RESPONSE', 'Gitea repository identity or default branch is invalid');
+    }
+    return {
+        server: {
+            version: version.version,
+            specification_version: specification.info.version,
+            specification_paths: Object.keys(specification.paths).length,
+        },
+        repository: {
+            id: repository.id,
+            full_name: repository.full_name,
+            default_branch: repository.default_branch,
+        },
+    };
+}

package/dist/transport.js

@@ -0,0 +1,65 @@
+import { limits } from './registry.js';
+import { CliError } from './error.js';
+export class Client {
+    origin;
+    token;
+    deadline;
+    constructor(origin, token, timeoutMs = limits.timeoutMs) {
+        this.origin = origin;
+        this.token = token;
+        this.deadline = Date.now() + timeoutMs;
+    }
+    async request(path, text = false) {
+        const url = new URL(path, this.origin);
+        if (url.origin !== this.origin || !path.startsWith('/') || path.startsWith('//'))
+            throw new CliError('UNSAFE_PATH', 'Request must stay within the selected origin');
+        try {
+            const response = await fetch(url, {
+                headers: { accept: text ? 'text/plain' : 'application/json', ...(this.token ? { authorization: 'token ' + this.token } : {}) },
+                redirect: 'error',
+                signal: AbortSignal.timeout(Math.max(1, this.deadline - Date.now())),
+            });
+            if (response.ok && !text && !response.headers.get('content-type')?.includes('application/json')) {
+                await response.body?.cancel();
+                throw new CliError('INVALID_RESPONSE', 'Gitea did not return JSON');
+            }
+            const chunks = [];
+            let bytes = 0;
+            for await (const chunk of response.body ?? []) {
+                bytes += chunk.byteLength;
+                if (bytes > limits.responseBytes) {
+                    throw new CliError('RESPONSE_LIMIT', 'Gitea response exceeded the byte limit');
+                }
+                chunks.push(chunk);
+            }
+            const body = Buffer.concat(chunks).toString('utf8');
+            if (!response.ok) {
+                let reason = '';
+                if (response.headers.get('content-type')?.includes('application/json')) {
+                    try {
+                        const error = JSON.parse(body);
+                        if (error && typeof error === 'object' && 'message' in error && typeof error.message === 'string')
+                            reason = ': ' + error.message.slice(0, 1000);
+                    }
+                    catch { /* HTTP status remains authoritative for malformed errors. */ }
+                }
+                const retry = response.headers.get('retry-after');
+                const code = response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'PERMISSION_DENIED' :
+                    response.status === 404 ? 'NOT_FOUND_OR_HIDDEN' : response.status === 429 ? 'RATE_LIMITED' : 'HTTP_ERROR';
+                throw new CliError(code, `${path.split('?')[0]} returned HTTP ${response.status}${reason}${retry ? '; retry-after ' + retry : ''}`);
+            }
+            return { data: text ? body : JSON.parse(body), headers: response.headers };
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            if (error instanceof SyntaxError)
+                throw new CliError('INVALID_RESPONSE', 'Gitea returned malformed JSON');
+            throw new CliError('TRANSPORT_ERROR', 'Gitea request failed; check the selected origin and connection');
+        }
+    }
+    async get(path) { return (await this.request(path)).data; }
+}
+export async function get(origin, path, token) {
+    return new Client(origin, token).get(path);
+}

package/dist/vendor.generated.js

@@ -0,0 +1,5 @@
+export const routes = {
+    "version": "/api/v1/version",
+    "repository": "/api/v1/repos/{owner}/{repo}",
+    "specification": "/swagger.v1.json"
+};

package/generated/help.txt

@@ -0,0 +1,11 @@
+command: gitea-axi repo view
+description: Read repository identity and default branch with server contract metadata.
+flags[4]{flag,type,requirement,description}:
+  "--repo",string,default matching local origin remote,Repository as OWNER/NAME
+  "--origin",string,default selected profile,Gitea origin; HTTPS by default
+  "--allow-insecure-http",boolean,default false,Allow HTTP only for the explicitly selected origin
+  "--help",boolean,default false,Show command help
+limits:
+  timeoutMs: 30000
+  responseBytes: 2000000
+examples[2]: "gitea-axi repo view --repo sample-owner/sample-repo --origin https://gitea.example.test",gitea-axi repo view --help