@knowttl/gitea-axi 0.0.0-stage → 0.1.1

package/dist/registry.js

@@ -0,0 +1,189 @@
+import { baseline, commandGap, flagGap } from './catalogue.js';
+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', short: 'R', 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' },
+    hostname: { type: 'string', description: 'Select exactly one matching configured host:port; otherwise GH_HOST' },
+};
+const repo = { repo: { type: 'string', short: 'R', 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 writeFlags = {
+    'allow-write': { type: 'string', description: 'Comma-separated exact vendor operation IDs authorized for this workflow' },
+    preview: { type: 'boolean', description: 'Preview and bind this exact write without dispatch' },
+    confirm: { type: 'string', description: 'Execute the unchanged preview confirmation ID once' },
+};
+const text = { type: 'string' };
+const repeated = { type: 'string', multiple: true };
+const issueBody = { body: text, 'body-file': { type: 'string', description: 'Body from an owned file or - for bounded stdin' } };
+const issueEdit = { title: text, ...issueBody, milestone: text };
+const mutationDefinitions = [
+    ['issue upload', { file: repeated, 'content-type': text }], ['pr upload', { file: repeated, 'content-type': text }], ['release upload', { file: repeated, 'content-type': text }],
+    ['secret set', { org: text, input: { ...text, description: 'Protected value file or - for stdin; values never accepted in argv' } }],
+    ['secret delete', { org: text }],
+    ['variable set', { org: text, body: text, input: { ...text, description: 'Value file or - for stdin; preserves empty values' } }],
+    ['variable delete', { org: text }],
+    ['repo create', { public: { type: 'boolean' }, private: { type: 'boolean' }, internal: { type: 'boolean' }, description: text, template: text,
+            source: text, push: { type: 'boolean' }, remote: text, clone: { type: 'boolean' } }],
+    ['repo edit', { description: text, visibility: text, 'default-branch': text, 'enable-issues': { type: 'boolean' }, 'enable-wiki': { type: 'boolean' } }],
+    ['repo fork', { org: text, clone: { type: 'boolean' }, remote: text, source: text, push: { type: 'boolean' } }],
+    ['release create', { attach: repeated, 'content-type': text, title: { ...text, short: 't' }, notes: { ...text, short: 'n' }, 'notes-file': { ...text, short: 'F' }, ...issueBody,
+            draft: { type: 'boolean', short: 'd' }, prerelease: { type: 'boolean', short: 'p' }, target: text,
+            'generate-notes': { type: 'boolean' }, 'notes-start-tag': text, 'notes-from-tag': { type: 'boolean' }, 'verify-tag': { type: 'boolean' },
+            'fail-on-no-commits': { type: 'boolean' }, latest: { type: 'boolean' }, 'discussion-category': text }],
+    ['release edit', { attach: repeated, 'content-type': text, title: text, notes: { ...text, short: 'n' }, 'notes-file': { ...text, short: 'F' }, ...issueBody, draft: { type: 'boolean' }, prerelease: { type: 'boolean' }, latest: { type: 'boolean' } }],
+    ['release delete', {}],
+    ['pr create', { ...issueEdit, attach: repeated, 'content-type': text, base: text, head: text, assignee: repeated, label: repeated, reviewer: repeated, 'team-reviewer': repeated }],
+    ['pr edit', { ...issueEdit, attach: repeated, 'content-type': text, base: text, 'add-label': repeated, 'remove-label': repeated, 'add-assignee': repeated, 'remove-assignee': repeated, 'add-reviewer': repeated, 'remove-reviewer': repeated, 'add-team-reviewer': repeated, 'remove-team-reviewer': repeated }],
+    ['pr close', { comment: text }], ['pr reopen', {}], ['pr comment', { ...issueBody, attach: repeated, 'content-type': text }],
+    ['pr update-branch', {}],
+    ['pr merge', { method: text, merge: { type: 'boolean' }, squash: { type: 'boolean' }, rebase: { type: 'boolean' }, 'match-head-commit': text,
+            auto: { type: 'boolean' }, admin: { type: 'boolean' }, 'delete-branch': { type: 'boolean' }, subject: text, ...issueBody }],
+    ['pr review', { approve: { type: 'boolean' }, 'request-changes': { type: 'boolean' }, comment: { type: 'boolean' }, 'match-head-commit': text, ...issueBody }],
+    ['issue create', { ...issueEdit, attach: repeated, 'content-type': text, assignee: repeated, label: repeated }],
+    ['issue edit', { ...issueEdit, attach: repeated, 'content-type': text, 'add-label': repeated, 'remove-label': repeated, 'add-assignee': repeated, 'remove-assignee': repeated }],
+    ['issue close', { comment: text }], ['issue reopen', {}], ['issue comment', { ...issueBody, attach: repeated, 'content-type': text }],
+    ['issue delete', {}], ['issue pin', {}], ['issue unpin', {}],
+    ['label create', { name: text, color: text, description: text }],
+    ['label edit', { name: text, color: text, description: text }], ['label delete', {}],
+];
+const definitions = [
+    ['issue download', { ...repo, dir: text, output: text, 'asset-id': text, pattern: repeated, sha256: text, 'content-type': text, clobber: { type: 'boolean' } }],
+    ['pr download', { ...repo, dir: text, output: text, 'asset-id': text, pattern: repeated, sha256: text, 'content-type': text, clobber: { type: 'boolean' } }],
+    ['release download', { ...repo, dir: text, output: text, 'asset-id': text, pattern: repeated, sha256: text, 'content-type': text, clobber: { type: 'boolean' } }],
+    ['secret list', { ...repo, org: text, limit: list.limit }], ['variable list', { ...repo, org: text, limit: list.limit }],
+    ['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 }],
+    ['release list', { ...repo, limit: list.limit, 'exclude-drafts': { type: 'boolean' }, 'exclude-pre-releases': { type: 'boolean' } }],
+    ['release view', { ...repo, full: detail.full }], ['api', { ...writeFlags,
+            method: { type: 'string', short: 'X', description: 'HTTP method; cannot combine with a positional method' },
+            field: { type: 'string', multiple: true, description: 'Repeatable key=value; numbers, booleans and null become JSON values' },
+            'raw-field': { type: 'string', multiple: true, description: 'Repeatable key=value string' },
+            input: { type: 'string', description: 'Protected JSON request file; use - for stdin' } }],
+    ['write reconcile', {}],
+];
+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: name.endsWith(' download') ? 'download' : 'read' })),
+    ...mutationDefinitions.map(([name, flags]) => ({ path: name.split(' '), description: name === 'pr review' ? 'pr review (unresolved vendor events and atomic stale-head refusal; no posting)' : name,
+        flags: { ...globalFlags, ...repo, ...writeFlags, ...flags }, effect: 'write' })),
+];
+const strings = (...names) => Object.fromEntries(names.map(name => [name, { type: 'string' }]));
+const booleans = (...names) => Object.fromEntries(names.map(name => [name, { type: 'boolean' }]));
+const stageFive = [
+    ['run list', strings('workflow', 'branch', 'status', 'event', 'user', 'commit', 'limit', 'fields'), 'read'],
+    ['run view', { ...strings('job', 'conclusion'), ...booleans('log', 'verbose', 'log-failed') }, 'read'],
+    ['run watch', strings('timeout', 'interval'), 'read'],
+    ['run rerun', { ...strings('job'), ...booleans('failed', 'debug') }, 'pending-write'],
+    ['run cancel', {}, 'pending-write'], ['run delete', {}, 'pending-write'],
+    ['run download', strings('name', 'dir'), 'download'],
+    ['workflow list', { ...strings('limit'), ...booleans('all') }, 'read'],
+    ['workflow view', booleans('yaml'), 'read'],
+    ['workflow run', strings('ref', 'field'), 'pending-write'],
+    ['workflow enable', {}, 'pending-write'], ['workflow disable', {}, 'pending-write'],
+    ...['issues', 'prs', 'repos', 'commits', 'code'].map((kind) => [
+        'search ' + kind,
+        { ...strings('owner', 'state', 'label', 'assignee', 'author', 'sort', 'order', 'limit', 'fields', 'review', 'language', 'stars', 'revision'), ...booleans('draft') },
+        'read',
+    ]),
+];
+commands.push(...stageFive.map(([name, flags, effect]) => ({ path: name.split(' '), description: name + (effect === 'pending-write' ? ' (pending shared write gate)' : ''), flags: { ...globalFlags, ...repo, ...flags }, effect })));
+const workspace = { workspace: { ...text, description: 'Absolute native Git repository root; clone uses an existing absolute parent directory' } };
+const stackDefinitions = [
+    ['view', {}], ['init', strings('base')], ['add', { ...strings('message'), ...booleans('all', 'update') }],
+    ['checkout', {}], ['push', strings('remote')], ['submit', { ...strings('remote'), ...booleans('open') }],
+    ['sync', { ...strings('remote'), ...booleans('prune') }],
+    ['rebase', { ...strings('remote'), ...booleans('downstack', 'upstack', 'no-trunk', 'continue', 'abort', 'committer-date-is-author-date', 'preserve-dates') }],
+    ['link', { ...strings('base', 'remote'), ...booleans('open') }], ['unstack', booleans('local')],
+    ['merge', { ...strings('merge-method'), ...booleans('merge', 'squash', 'rebase') }],
+    ...['up', 'down', 'top', 'bottom', 'trunk'].map((name) => [name, {}]),
+];
+commands.push(...stackDefinitions.map(([name, flags]) => ({ path: ['stack', name], description: 'Owned local stack ' + name,
+    flags: { ...globalFlags, ...workspace, ...writeFlags, ...flags }, effect: name === 'view' ? 'local-read' : 'local-write' })));
+commands.push(...['repo clone', 'pr checkout', 'pr revert'].map(name => ({ path: name.split(' '), description: name + ' in an explicit standalone workspace',
+    flags: { ...globalFlags, ...repo, ...workspace, ...writeFlags }, effect: 'local-write' })));
+for (const command of commands) {
+    if (['repo create', 'repo fork'].includes(command.path.join(' ')))
+        Object.assign(command.flags, workspace);
+}
+commands.push({ path: ['capabilities'], description: 'Inspect all baseline command IDs, flags, globals and PR fields without claiming full parity', flags: { help: globalFlags.help }, effect: 'local-read' });
+const refusedFlags = [
+    ['repo create', ['internal']],
+    ['release create', ['latest', 'discussion-category']],
+    ['release edit', ['latest']],
+    ['pr merge', ['auto', 'admin', 'delete-branch']],
+    ['run list', ['user']],
+    ['search issues', ['review', 'language', 'stars', 'revision', 'draft']],
+    ['search prs', ['review', 'language', 'stars', 'revision']],
+    ['search repos', ['state', 'label', 'assignee', 'author', 'review', 'revision', 'draft']],
+    ['search commits', ['owner', 'state', 'label', 'assignee', 'review', 'language', 'stars', 'draft']],
+    ['stack rebase', ['preserve-dates']],
+    ['stack link', ['open']],
+    ['stack submit', ['open']],
+];
+for (const [path, names] of refusedFlags) {
+    const command = commands.find(command => command.path.join(' ') === path);
+    for (const name of names)
+        command.flags[name] = { ...command.flags[name], gap: flagGap(path, name) };
+}
+// Retain unsupported leaves and options in the same registry that owns help and admission metadata.
+const booleanFlags = new Set(['comments', 'full', 'public', 'secret', 'files', 'raw', 'web', 'no-type', 'draft', 'failed', 'fail-fast', 'patch', 'undo', 'all', 'prune', 'open', 'local', 'merge', 'squash', 'rebase', 'downstack', 'upstack', 'no-trunk', 'continue', 'abort', 'committer-date-is-author-date', 'preserve-dates', 'check', 'closed', 'clear', 'remove']);
+for (const row of baseline) {
+    if (row.path === '--version' || row.path.startsWith('api ') || row.path === 'update --check')
+        continue;
+    if (!commands.some(command => command.path.join(' ') === row.path)) {
+        const gap = commandGap(row.path);
+        if (!gap)
+            throw new Error('Missing capability decision for ' + row.id);
+        commands.push({ path: row.path.split(' '), description: row.path + ' (compatibility gap)', flags: { ...globalFlags, ...repo }, effect: 'gap', gap });
+    }
+}
+for (const row of baseline) {
+    const path = row.path.startsWith('api ') ? 'api' : row.path === 'update --check' ? 'update' : row.path;
+    const command = commands.find(command => command.path.join(' ') === path);
+    if (!command)
+        continue;
+    for (const flag of row.flags) {
+        const name = flag.name === '-X' ? 'method' : flag.name.replace(/^--/, '');
+        if (!command.flags[name])
+            command.flags[name] = { type: booleanFlags.has(name) ? 'boolean' : 'string', description: 'Compatibility gap: ' + flagGap(path, name), gap: flagGap(path, name) };
+    }
+}

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/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,
+        },
+    };
+}