@knowttl/gitea-axi 0.1.0 → 0.1.1

package/dist/releases.js

@@ -0,0 +1,145 @@
+import { collect, object, read, resolveCommit } from './api.js';
+import { CliError } from './error.js';
+import { boundedList, positive } from './reads.js';
+const usage = (message) => { throw new CliError('USAGE', message, 2); };
+export const releaseListFields = ['id', 'tag_name', 'name', 'draft', 'prerelease', 'published_at'];
+async function completeCollection(client, path) {
+    const page = await collect(client, path);
+    if (page.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Exact identity lookup requires a complete collection');
+    return page.items;
+}
+async function readTag(client, base, tag) {
+    return (await completeCollection(client, base + '/tags')).find(row => row.name === tag) ?? null;
+}
+export function validateRelease(options) {
+    if (options['notes-start-tag'] && !options['generate-notes'])
+        usage('--notes-start-tag requires --generate-notes');
+    if (options['fail-on-no-commits'] && !options['generate-notes'])
+        usage('--fail-on-no-commits requires --generate-notes');
+    if (options.notes !== undefined && options.body !== undefined || options['notes-file'] !== undefined && options['body-file'] !== undefined)
+        usage('Choose one notes input');
+    if (options['notes-from-tag'] && (options['generate-notes'] || options.notes !== undefined || options.body !== undefined || options['notes-file'] !== undefined || options['body-file'] !== undefined))
+        usage('--notes-from-tag cannot combine with another notes input');
+}
+export async function releaseRead(client, operation, base, tag, options) {
+    if (operation === 'release list') {
+        const page = await collect(client, base + '/releases');
+        const items = page.items.filter(row => !(options['exclude-drafts'] && row.draft) && !(options['exclude-pre-releases'] && row.prerelease));
+        return boundedList({ ...page, items, total: options['exclude-drafts'] || options['exclude-pre-releases'] ? page.truncated ? null : items.length : page.total }, positive(options.limit, 10, 1000), releaseListFields);
+    }
+    const selected = (await completeCollection(client, base + '/releases')).find(row => row.tag_name === tag);
+    if (!selected)
+        throw new CliError('NOT_FOUND_OR_HIDDEN', 'The selected release is missing or hidden');
+    const release = object(await read(client, base + '/releases/' + selected.id));
+    if (release.tag_name !== tag)
+        throw new CliError('INVALID_RESPONSE', 'Release tag identity differs from the selected tag');
+    const body = String(release.body ?? ''), limit = options.full ? 80_000 : 1500;
+    return { release: { ...release, body: body.slice(0, limit) }, chars: body.length, truncated: body.length > limit,
+        ...(body.length > limit ? { help: 'Use gitea-axi release view ' + tag + ' --repo ' + base.split('/').slice(-2).join('/') + ' --full within the output ceiling' } : {}) };
+}
+async function generatedNotes(client, base, target, start) {
+    const cache = new Map();
+    const commit = async (ref) => {
+        const row = cache.get(ref) ?? object(await read(client, base + '/git/commits/' + encodeURIComponent(ref)));
+        if (typeof row.sha !== 'string' || !Array.isArray(row.parents) || typeof object(row.commit).message !== 'string')
+            throw new CliError('INVALID_RESPONSE', 'Notes require commit identities, parents and messages');
+        return row;
+    };
+    const end = await resolveCommit(client, base, target);
+    const history = await collect(client, base + '/commits?sha=' + encodeURIComponent(String(end.sha)));
+    if (history.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Notes require the complete target commit history; narrow the release target');
+    for (const row of history.items)
+        cache.set(String(row.sha), row);
+    const begin = start ? await readTag(client, base, start) : null;
+    if (start && !begin)
+        usage('--notes-start-tag must select an existing tag');
+    const startSHA = begin ? String(object(object(begin).commit).sha) : null;
+    const walk = async (sha) => {
+        const found = new Map(), pending = [sha];
+        while (pending.length) {
+            const next = pending.pop();
+            if (found.has(next))
+                continue;
+            if (found.size >= 1000)
+                throw new CliError('INCOMPLETE_READ', 'Notes exceed the 1000 commit boundary; select a nearer --notes-start-tag');
+            const row = await commit(next);
+            if (row.sha !== next)
+                throw new CliError('INVALID_RESPONSE', 'Commit identity differs from the requested boundary');
+            found.set(next, row);
+            pending.push(...row.parents.map(parent => String(object(parent).sha)));
+        }
+        return found;
+    };
+    const all = await walk(String(end.sha));
+    if (startSHA && !all.has(startSHA))
+        usage('--notes-start-tag must be an ancestor of the target');
+    const excluded = startSHA ? await walk(startSHA) : new Map();
+    const commits = [...all.values()].filter(row => !excluded.has(String(row.sha))).map(row => ({ sha: row.sha, message: String(object(row.commit).message).split('\n')[0] }));
+    return { kind: 'local-composite', from: startSHA, to: end.sha, commits,
+        body: commits.map(row => '- ' + row.message + ' (' + row.sha + ')').join('\n') };
+}
+export async function releasePlan(client, operation, base, tag, options) {
+    const path = base + '/releases';
+    const releases = await completeCollection(client, path);
+    const current = releases.find(row => row.tag_name === tag) ?? null;
+    const detail = current ? path + '/' + current.id : path;
+    const before = { release: current };
+    if (operation === 'release create' && current !== null)
+        throw new CliError('ALREADY_EXISTS', 'A release already exists for the selected tag; use release edit');
+    if (operation !== 'release create' && current === null)
+        throw new CliError('NOT_FOUND_OR_HIDDEN', 'The selected release is missing or hidden');
+    if (operation === 'release delete') {
+        before.releases = releases;
+        const tagState = await readTag(client, base, tag);
+        before.tag = tagState;
+        return { target: detail, steps: [{ method: 'DELETE', path: detail }], reads: [path, base + '/tags'], preconditions: before,
+            workflow: { path, expected: { tag_name: tag }, absentId: object(current).id, remaining: releases.filter(row => row.id !== object(current).id), tag: { path: base + '/tags', before: tagState } } };
+    }
+    const payload = {};
+    for (const [flag, field] of [['title', 'name'], ['body', 'body'], ['draft', 'draft'], ['prerelease', 'prerelease'], ['target', 'target_commitish']]) {
+        if (options[flag] !== undefined)
+            payload[field] = options[flag];
+    }
+    let notes;
+    if (operation === 'release create') {
+        Object.assign(payload, { tag_name: tag, name: payload.name ?? tag, body: payload.body ?? '', draft: payload.draft ?? false, prerelease: payload.prerelease ?? false });
+        const repo = object(await read(client, base));
+        before.repository = repo;
+        const existingTag = await readTag(client, base, tag);
+        before.tag = existingTag;
+        if (options['verify-tag'] && !existingTag)
+            usage('--verify-tag requires an existing tag');
+        if (options['notes-from-tag']) {
+            if (!existingTag)
+                usage('--notes-from-tag requires an existing tag');
+            payload.body = object(existingTag).message ?? '';
+        }
+        payload.target_commitish ??= repo.default_branch;
+        if (options['generate-notes']) {
+            let start = typeof options['notes-start-tag'] === 'string' ? options['notes-start-tag'] : undefined;
+            if (!start) {
+                const releases = await collect(client, path);
+                if (releases.truncated)
+                    throw new CliError('INCOMPLETE_READ', 'Notes require a complete previous-release list');
+                const latest = releases.items.filter(row => !row.draft).sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)))[0];
+                if (latest)
+                    start = String(latest.tag_name);
+                before.releases = releases.items;
+            }
+            notes = await generatedNotes(client, base, existingTag ? String(object(object(existingTag).commit).sha) : String(payload.target_commitish), start);
+            if (options['fail-on-no-commits'] && notes.commits.length === 0)
+                usage('No commits exist after the selected notes boundary');
+            payload.body = [payload.body, notes.body].filter(Boolean).join('\n\n');
+            if (!existingTag)
+                payload.target_commitish = notes.to;
+            before.notes = notes;
+        }
+    }
+    else if (!Object.keys(payload).length && !options.attach)
+        usage('Select at least one release field to edit');
+    const expected = current ? { ...Object.fromEntries(['id', 'tag_name', 'name', 'body', 'draft', 'prerelease', 'target_commitish'].map(key => [key, object(current)[key]])), ...payload } : payload;
+    return { target: detail, steps: Object.keys(payload).length ? [{ method: operation === 'release create' ? 'POST' : 'PATCH', path: current ? path + '/' + object(current).id : path, payload }] : [],
+        reads: [detail], preconditions: before, workflow: { path: detail, expected, created: current === null }, ...(notes ? { notes } : {}) };
+}

package/dist/repo-workflows.js

@@ -0,0 +1,147 @@
+import { object, read, resolveCommit } from './api.js';
+import { CliError } from './error.js';
+import { repository } from './reads.js';
+const usage = (message) => { throw new CliError('USAGE', message, 2); };
+export const repoPath = (name) => '/api/v1/repos/' + name.split('/').map(encodeURIComponent).join('/');
+export function validateRepositoryWorkflow(operation, options) {
+    if ((options.push || options.remote) && !options.source)
+        usage('--push and --remote require --source');
+    if (['source', 'push', 'remote', 'clone'].some(key => options[key] !== undefined)) {
+        throw new CliError('CAPABILITY_GAP', 'Workspace options require the deferred local workspace workflow; use API-only arguments');
+    }
+    if (options.visibility === 'internal')
+        throw new CliError('CAPABILITY_GAP', 'Internal visibility is unsupported by the Gitea contract');
+    if (operation === 'repo create' && Boolean(options.public) === Boolean(options.private))
+        usage('Choose exactly --public or --private');
+    if (options.visibility !== undefined && !['public', 'private'].includes(String(options.visibility)))
+        usage('--visibility must be public or private');
+}
+export async function optionalRead(client, path) {
+    try {
+        return await read(client, path);
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === 'NOT_FOUND_OR_HIDDEN')
+            return null;
+        throw error;
+    }
+}
+export async function repositoryPlan(client, operation, selection, options) {
+    const before = {};
+    const action = operation.split(' ')[1];
+    if (selection && options.repo)
+        usage('Choose a positional repository or --repo once');
+    const selected = selection ?? (typeof options.repo === 'string' ? options.repo : undefined);
+    if (action === 'edit') {
+        const base = repoPath(repository(selected, client.origin));
+        const current = object(await read(client, base));
+        const payload = {};
+        for (const [flag, field] of [['description', 'description'], ['default-branch', 'default_branch'], ['enable-issues', 'has_issues'], ['enable-wiki', 'has_wiki']]) {
+            if (options[flag] !== undefined)
+                payload[field] = options[flag];
+        }
+        if (options.visibility !== undefined)
+            payload.private = options.visibility === 'private';
+        if (!Object.keys(payload).length)
+            usage('Select at least one repository field to edit');
+        return { target: base, steps: [{ method: 'PATCH', path: base, payload }], reads: [base], preconditions: current,
+            workflow: { path: base, expected: { id: current.id, full_name: current.full_name, ...payload } } };
+    }
+    const user = object(await read(client, '/api/v1/user'));
+    let owner = String(user.login), name, source, sourcePath;
+    if (action === 'fork') {
+        sourcePath = repoPath(repository(selected, client.origin));
+        source = object(await read(client, sourcePath));
+        before[sourcePath] = source;
+        name = String(source.full_name).split('/')[1];
+        if (options.org)
+            owner = String(options.org);
+    }
+    else {
+        if (!selected)
+            usage('Select the new repository name or OWNER/NAME');
+        const full = selected.includes('/') ? selected : owner + '/' + selected;
+        repository(full, client.origin);
+        [owner, name] = full.split('/');
+        if (options.template) {
+            sourcePath = repoPath(repository(String(options.template), client.origin));
+            source = object(await read(client, sourcePath));
+            if (source.template !== true)
+                usage('--template must select a template repository');
+            before[sourcePath] = source;
+        }
+    }
+    repository(owner + '/' + name, client.origin);
+    const base = repoPath(owner + '/' + name);
+    if (await optionalRead(client, base) !== null)
+        throw new CliError('ALREADY_EXISTS', 'The selected destination repository already exists');
+    before[base] = null;
+    if (owner !== user.login)
+        before.owner = await read(client, '/api/v1/orgs/' + encodeURIComponent(owner));
+    else
+        before.owner = user;
+    let path, payload;
+    let expected;
+    let content;
+    if (action === 'fork') {
+        path = sourcePath + '/forks';
+        payload = owner === user.login ? {} : { organization: owner };
+        expected = { full_name: owner + '/' + name, private: source.private, description: source.description, fork: true, parent: { id: source.id } };
+    }
+    else {
+        payload = { name: name, private: Boolean(options.private), description: options.description ?? '' };
+        expected = { full_name: owner + '/' + name, private: payload.private, description: payload.description };
+        if (source) {
+            path = sourcePath + '/generate';
+            Object.assign(payload, { owner, git_content: true });
+            const commit = await resolveCommit(client, sourcePath, String(source.default_branch));
+            const tree = object(await read(client, sourcePath + '/git/trees/' + commit.sha + '?recursive=true'));
+            if (tree.truncated !== false || !Array.isArray(tree.tree))
+                throw new CliError('INCOMPLETE_READ', 'Template content requires a complete tree');
+            if (tree.tree.some(item => object(item).path === '.gitea/template'))
+                throw new CliError('CAPABILITY_GAP', 'Transforming templates not yet supported');
+            before.content = tree;
+            content = { base, ref: String(source.default_branch), expected: treeEntries(tree.tree) };
+            expected.default_branch = source.default_branch;
+            payload.default_branch = source.default_branch;
+        }
+        else
+            path = owner === user.login ? '/api/v1/user/repos' : '/api/v1/orgs/' + encodeURIComponent(owner) + '/repos';
+    }
+    expected.owner = { login: owner };
+    return { target: base, steps: [{ method: 'POST', path, payload }], reads: [base], preconditions: before,
+        workflow: { path: base, expected, created: true, ...(content ? { content } : {}) } };
+}
+function treeEntries(value) {
+    if (!Array.isArray(value))
+        throw new CliError('INVALID_RESPONSE', 'Expected a complete Git tree');
+    return value.map(item => { const row = object(item); return { path: row.path, mode: row.mode, type: row.type, sha: row.sha }; }).sort((a, b) => String(a.path).localeCompare(String(b.path)));
+}
+export async function verifyWorkflow(client, plan, results, observations) {
+    const verification = plan.workflow;
+    const mismatch = () => { throw new CliError('READBACK_MISMATCH', 'Readback did not confirm the selected identity and requested fields'); };
+    const data = observations.find(row => row.path === verification.path)?.data;
+    if (verification.absentId !== undefined) {
+        if (!Array.isArray(data) || data.some(value => object(value).id === verification.absentId || object(value).tag_name === verification.expected.tag_name))
+            mismatch();
+        const rows = data;
+        if (rows.length !== verification.remaining.length || verification.remaining.some(row => JSON.stringify(rows.find(item => item.id === row.id)) !== JSON.stringify(row)))
+            mismatch();
+        const tags = observations.find(row => row.path === verification.tag.path)?.data;
+        if (!Array.isArray(tags) || JSON.stringify(tags.find(row => object(row).name === verification.expected.tag_name) ?? null) !== JSON.stringify(verification.tag.before))
+            mismatch();
+        return;
+    }
+    const actual = object(Array.isArray(data) ? data.find(row => object(row).tag_name === verification.expected.tag_name) : data);
+    const matches = (actual, expected) => Object.entries(expected).every(([key, value]) => value !== null && typeof value === 'object' && !Array.isArray(value) ? matches(object(actual[key]), object(value)) : JSON.stringify(actual[key]) === JSON.stringify(value));
+    if (!matches(actual, verification.expected))
+        mismatch();
+    if (verification.created && (actual.id !== object(results[0]).id || !Number.isSafeInteger(actual.id) || Number(actual.id) <= 0))
+        mismatch();
+    if (verification.content) {
+        const commit = await resolveCommit(client, verification.content.base, verification.content.ref);
+        const tree = object(await read(client, verification.content.base + '/git/trees/' + commit.sha + '?recursive=true'));
+        if (tree.truncated !== false || JSON.stringify(treeEntries(tree.tree)) !== JSON.stringify(verification.content.expected))
+            mismatch();
+    }
+}

package/dist/search.js

@@ -0,0 +1,111 @@
+import { collect, object, read } from './api.js';
+import { CliError } from './error.js';
+import { continuationHelp, issue, issueFields, positive, repository, selectedFields } from './reads.js';
+export function validateSearch(kind, query, options) {
+    if (!query.trim() || /\S+:\S*/.test(query))
+        throw new CliError('USAGE', 'Use plain search text and explicit flags; query qualifiers are unsupported', 2);
+    if (kind === 'code')
+        throw new CliError('CAPABILITY_GAP', 'Indexed code search is unresolved; repository contents are not indexed search');
+    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', 'repo'].includes(key) && !allowed.includes(key))
+            throw new CliError('CAPABILITY_GAP', '--' + key + ' is not evidenced for search ' + kind);
+    }
+    positive(options.limit, 1000, 1000);
+    if (options.state && !['open', 'closed', 'all'].includes(String(options.state)))
+        throw new CliError('USAGE', '--state must be open, closed or all', 2);
+    const sorts = kind === 'repos' ? ['name', 'created', 'updated', 'stars'] : kind === 'commits' ? ['created'] : ['created', 'updated', 'comments'];
+    if (options.sort && !sorts.includes(String(options.sort)))
+        throw new CliError('USAGE', 'Choose --sort ' + sorts.join(','), 2);
+    if (options.order && !['asc', 'desc'].includes(String(options.order)))
+        throw new CliError('USAGE', '--order must be asc or desc', 2);
+    if (options.stars && !/^(?:>=|<=|>|<|=)?\d+$/.test(String(options.stars)))
+        throw new CliError('USAGE', '--stars requires an integer comparison such as >100', 2);
+    selectedFields(options, kind === 'repos' ? ['id', 'full_name', 'description', 'language', 'stars_count'] : kind === 'commits' ? ['sha', 'message', 'author', 'created', 'url'] : issueFields.concat(['closedAt', 'commentsCount', 'isLocked', ...(kind === 'prs' ? ['isDraft'] : [])]), []);
+}
+export async function search(client, kind, query, options) {
+    const target = typeof options.repo === 'string' ? repository(options.repo, client.origin) : undefined;
+    const base = target ? '/api/v1/repos/' + target.split('/').map(encodeURIComponent).join('/') : undefined;
+    let page;
+    let revision = null;
+    if (kind === 'commits') {
+        if (!base)
+            throw new CliError('USAGE', 'Commit search requires --repo OWNER/NAME', 2);
+        const repo = object(await read(client, base));
+        const ref = String(options.revision ?? repo.default_branch);
+        const commit = object(await read(client, base + '/git/commits/' + encodeURIComponent(ref)));
+        if (typeof commit.sha !== 'string' || !commit.sha)
+            throw new CliError('INVALID_RESPONSE', 'Revision has no commit SHA');
+        revision = commit.sha;
+        page = await collect(client, base + '/commits?sha=' + encodeURIComponent(commit.sha));
+    }
+    else if (kind === 'repos') {
+        page = await collect(client, '/api/v1/repos/search?q=' + encodeURIComponent(query) + '&includeDesc=true', 'data');
+    }
+    else {
+        page = await collect(client, base ? base + (kind === 'prs' ? '/pulls' : '/issues') + '?state=all' + (kind === 'issues' ? '&type=issues' : '') :
+            '/api/v1/repos/issues/search?state=all&type=' + (kind === 'prs' ? 'pulls' : 'issues') + '&q=' + encodeURIComponent(query) + (options.owner ? '&owner=' + encodeURIComponent(String(options.owner)) : ''));
+    }
+    if (kind === 'prs' && !base) {
+        page.items = page.items.map(row => ({ ...row, draft: row.pull_request ? object(row.pull_request).draft : undefined }));
+    }
+    const needle = query.toLowerCase();
+    const rows = page.items.filter(row => {
+        const fullName = kind === 'repos' ? row.full_name : row.repository ? object(row.repository).full_name : target;
+        if (target && kind === 'repos' && fullName !== target)
+            return false;
+        if (options.owner && String(fullName).split('/')[0] !== options.owner)
+            return false;
+        if (kind === 'repos') {
+            if (!String(row.full_name ?? '').toLowerCase().includes(needle) && !String(row.description ?? '').toLowerCase().includes(needle))
+                return false;
+            if (options.language && String(row.language).toLowerCase() !== String(options.language).toLowerCase())
+                return false;
+            if (options.stars) {
+                const [, op, value] = /^(>=|<=|>|<|=)?(\d+)$/.exec(String(options.stars));
+                const count = Number(row.stars_count), expected = Number(value);
+                if (!(op === '>' ? count > expected : op === '<' ? count < expected : op === '>=' ? count >= expected : op === '<=' ? count <= expected : count === expected))
+                    return false;
+            }
+        }
+        else if (kind === 'commits') {
+            if (!String(object(row.commit).message).toLowerCase().includes(needle))
+                return false;
+            if (options.author && (!row.author || object(row.author).login !== options.author))
+                return false;
+        }
+        else {
+            if (kind === 'issues' && row.pull_request)
+                return false;
+            if (!(String(row.title) + '\n' + String(row.body ?? '')).toLowerCase().includes(needle))
+                return false;
+            if (options.state && options.state !== 'all' && row.state !== options.state)
+                return false;
+            if (options.author && (!row.user || object(row.user).login !== options.author))
+                return false;
+            if (options.assignee && !(row.assignees ?? []).some(user => user.login === options.assignee))
+                return false;
+            if (options.label && !(row.labels ?? []).some(label => String(options.label).split(',').includes(String(label.name))))
+                return false;
+            if (options.draft && row.draft !== true)
+                return false;
+        }
+        return true;
+    });
+    const key = options.sort === 'updated' ? 'updated_at' : options.sort === 'comments' ? 'comments' : options.sort === 'stars' ? 'stars_count' : options.sort === 'name' ? 'full_name' : kind === 'commits' ? 'created' : 'created_at';
+    rows.sort((a, b) => {
+        const left = a[key] ?? '', right = b[key] ?? '';
+        const compared = typeof left === 'number' && typeof right === 'number' ? left - right : String(left).localeCompare(String(right));
+        return (compared || String(a.id ?? a.sha).localeCompare(String(b.id ?? b.sha))) * (options.order === 'asc' ? 1 : -1);
+    });
+    const limit = positive(options.limit, 1000, 1000);
+    const fields = typeof options.fields === 'string' ? options.fields.split(',') : kind === 'repos' ? ['id', 'full_name', 'description'] : kind === 'commits' ? ['sha', 'message', 'author'] : ['number', 'title', 'state'];
+    return { items: rows.slice(0, limit).map(row => {
+            const projection = kind === 'repos' ? row : kind === 'commits' ? { sha: row.sha, message: object(row.commit).message, author: row.author, created: row.created, url: row.html_url } :
+                { ...issue(row, Boolean(options.fields)), closedAt: row.closed_at ?? null, commentsCount: row.comments ?? 0, isLocked: row.is_locked ?? false, isDraft: row.draft ?? null };
+            return { ...(kind === 'issues' || kind === 'prs' ? { repository: row.repository ? object(row.repository).full_name : target } : {}), ...Object.fromEntries(fields.map(field => [field, projection[field]])) };
+        }), count: Math.min(rows.length, limit), total: page.truncated ? null : rows.length, truncated: page.truncated || rows.length > limit, next: page.next,
+        scope: { repository: target ?? 'visible repositories', owner: options.owner ?? null, revision, pages: 'maximum 20 pages / 1000 candidates per collection', indexed: false },
+        continuation: page.truncated || rows.length > limit, help: continuationHelp(page, rows.length, limit) };
+}