@knowttl/gitea-axi 0.1.0 → 0.1.1

package/dist/attachments.js

@@ -0,0 +1,171 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, open, realpath, rename, rm } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { collect, object, read, validate } from './api.js';
+import { CliError } from './error.js';
+export const transferBytes = 10_000_000;
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function safeName(name) {
+    if (!name || name === '.' || name === '..' || /[\\/:*?"<>|\x00-\x1f\x7f]/.test(name) || /[. ]$/.test(name) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name))
+        throw new CliError('UNSAFE_PATH', 'Attachment requires a safe portable basename');
+    return name;
+}
+function attachment(value) {
+    const row = object(value);
+    if (!Number.isSafeInteger(row.id) || Number(row.id) <= 0 || typeof row.uuid !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(row.uuid) || typeof row.name !== 'string' || !Number.isSafeInteger(row.size) || Number(row.size) < 0)
+        throw new CliError('INVALID_RESPONSE', 'Attachment metadata has invalid identity or size');
+    safeName(row.name);
+    return row;
+}
+export async function assetPath(client, base, kind, selected) {
+    if (kind !== 'release') {
+        await read(client, base + (kind === 'pr' ? '/pulls/' : '/issues/') + selected);
+        return base + '/issues/' + selected + '/assets';
+    }
+    const page = await collect(client, base + '/releases');
+    if (page.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Release identity requires a complete collection');
+    const release = page.items.find(row => row.tag_name === selected);
+    if (!release || !Number.isSafeInteger(release.id) || Number(release.id) <= 0)
+        throw new CliError('NOT_FOUND_OR_HIDDEN', 'The selected release is missing or hidden');
+    return base + '/releases/' + release.id + '/assets';
+}
+async function uploadSteps(path, options) {
+    const paths = options.file ?? options.attach;
+    if (!paths)
+        throw new CliError('USAGE', 'Select at least one --file', 2);
+    const files = Array.isArray(paths) ? paths : [paths];
+    const names = new Set();
+    const steps = [];
+    for (const value of files) {
+        const filePath = String(value), name = safeName(basename(filePath));
+        if (names.has(name.toLowerCase()))
+            throw new CliError('UNSAFE_PATH', 'Duplicate attachment basenames are refused');
+        names.add(name.toLowerCase());
+        const info = await lstat(filePath);
+        if (!info.isFile() || info.isSymbolicLink() || await realpath(filePath) !== resolve(filePath))
+            throw new CliError('UNSAFE_PATH', 'Upload must be a regular file without symlinks');
+        const file = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const chunks = [];
+        let size = 0;
+        try {
+            if (!(await file.stat()).isFile())
+                throw new CliError('UNSAFE_PATH', 'Upload must be a regular file');
+            for await (const chunk of file.createReadStream({ autoClose: false })) {
+                size += chunk.length;
+                if (size > transferBytes)
+                    throw new CliError('TRANSFER_LIMIT', 'Upload exceeds 10000000 bytes');
+                chunks.push(chunk);
+            }
+        }
+        finally {
+            await file.close();
+        }
+        const bytes = Buffer.concat(chunks);
+        const type = String(options['content-type'] ?? 'application/octet-stream');
+        if (!/^[\w.+-]+\/[\w.+-]+$/.test(type))
+            throw new CliError('USAGE', 'Select a MIME content type', 2);
+        steps.push({ method: 'POST', path, upload: { name, type, size, base64: bytes.toString('base64'), sha256: hash(bytes) } });
+    }
+    return steps;
+}
+export async function uploadPlan(client, path, options) {
+    const page = await collect(client, path);
+    if (page.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Attachment identity requires a complete collection');
+    const before = page.items.map(attachment);
+    const steps = await uploadSteps(path, options);
+    if (steps.some(step => before.some(row => String(row.name).toLowerCase() === step.upload.name.toLowerCase())))
+        throw new CliError('ALREADY_EXISTS', 'An attachment has the same basename; choose a distinct name');
+    return { target: path, steps, reads: [path], preconditions: before, assets: { path, before } };
+}
+export async function attachToPlan(client, plan, operation, base, selected, options) {
+    if (!options.attach)
+        return plan;
+    const comment = operation.endsWith(' comment');
+    const created = operation.endsWith(' create') || comment;
+    if (created) {
+        const parent = comment ? plan.steps.findIndex(step => step.path.endsWith('/comments')) : 0;
+        const path = base + (comment ? '/issues/comments/0/assets' : operation.startsWith('release ') ? '/releases/0/assets' : '/issues/0/assets');
+        return { ...plan, steps: [...plan.steps, ...(await uploadSteps(path, options)).map(step => ({ ...step, assetParent: parent }))], assets: { path, before: [] } };
+    }
+    const uploads = await uploadPlan(client, await assetPath(client, base, operation.split(' ')[0], selected), options);
+    return { ...plan, steps: [...plan.steps, ...uploads.steps], reads: [...plan.reads, ...uploads.reads], preconditions: { ...object(plan.preconditions), attachments: uploads.preconditions }, assets: uploads.assets };
+}
+export function verifyUploads(plan, results, observations) {
+    const { path, before } = plan.assets;
+    const after = observations.find(row => row.path === path).data.map(attachment);
+    const uploads = plan.steps.flatMap((step, index) => step.upload ? [{ upload: step.upload, result: attachment(validate(path + '/' + object(results[index]).id, results[index])) }] : []);
+    if (after.length !== before.length + uploads.length || before.some(row => !after.some(item => item.id === row.id && item.uuid === row.uuid && item.name === row.name && item.size === row.size)) || uploads.some(({ upload, result }) => before.some(row => row.id === result.id) || !after.some(row => row.id === result.id && row.uuid === result.uuid && row.name === upload.name && row.size === upload.size)))
+        throw new CliError('READBACK_MISMATCH', 'Attachment metadata did not confirm the intended uploads');
+}
+export async function download(client, path, options) {
+    if (process.platform === 'win32')
+        throw new CliError('CONFIG_INSECURE', 'Native Windows download ACL protection is unavailable');
+    if (options['content-type'] !== undefined && !/^[\w.+-]+\/[\w.+-]+$/.test(String(options['content-type'])))
+        throw new CliError('USAGE', 'Select a MIME content type', 2);
+    if (options.output && options.dir)
+        throw new CliError('USAGE', 'Choose --output or --dir', 2);
+    if (options['asset-id'] !== undefined && !/^[1-9]\d*$/.test(String(options['asset-id'])))
+        throw new CliError('USAGE', 'Select one positive --asset-id', 2);
+    const page = await collect(client, path);
+    if (page.truncated)
+        throw new CliError('INCOMPLETE_READ', 'Download selection requires a complete collection');
+    const patterns = options.pattern === undefined ? ['*'] : Array.isArray(options.pattern) ? options.pattern.map(String) : [String(options.pattern)];
+    const matches = patterns.map(pattern => new RegExp('^' + pattern.split(/([*?])/).map(part => part === '*' ? '.*' : part === '?' ? '.' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('') + '$'));
+    const selected = page.items.filter(row => (options['asset-id'] === undefined || String(row.id) === options['asset-id']) && matches.some(pattern => pattern.test(String(row.name)))).map(attachment);
+    if (!selected.length)
+        throw new CliError('NO_MATCHES', 'No attachments match the selected patterns');
+    if (new Set(selected.map(row => String(row.name).toLowerCase())).size !== selected.length)
+        throw new CliError('UNSAFE_PATH', 'Duplicate download basenames are refused');
+    if (options.sha256 !== undefined && (selected.length !== 1 || !/^[a-f0-9]{64}$/.test(String(options.sha256))))
+        throw new CliError('USAGE', '--sha256 requires exactly one selected file and a lowercase SHA-256 digest', 2);
+    if (options.output && selected.length !== 1)
+        throw new CliError('USAGE', '--output requires exactly one selected attachment', 2);
+    const directory = options.output ? dirname(resolve(String(options.output))) : resolve(String(options.dir ?? '.'));
+    if (!(await lstat(directory)).isDirectory() || await realpath(directory) !== directory)
+        throw new CliError('UNSAFE_PATH', 'Download directory must exist without symlinks');
+    const completed = [];
+    for (const selectedRow of selected) {
+        const temporary = join(directory, '.gitea-attachment-' + randomUUID() + '.tmp');
+        try {
+            const row = attachment(await read(client, path + '/' + selectedRow.id));
+            if (['id', 'uuid', 'name', 'size'].some(key => row[key] !== selectedRow[key]))
+                throw new CliError('INVALID_RESPONSE', 'Attachment identity changed before download');
+            if (Number(row.size) > transferBytes)
+                throw new CliError('TRANSFER_LIMIT', 'Download exceeds 10000000 bytes');
+            const destination = join(directory, options.output ? safeName(basename(String(options.output))) : String(row.name));
+            const previous = await lstat(destination).catch((error) => { if (error.code !== 'ENOENT')
+                throw error; return null; });
+            if (previous && (!options.clobber || previous.isSymbolicLink() || !previous.isFile()))
+                throw new CliError('UNSAFE_PATH', 'Destination exists; choose --clobber for a regular file');
+            const { bytes, type } = await client.attachment(String(row.uuid), options['content-type'] === undefined ? undefined : String(options['content-type']));
+            const sha256 = hash(bytes);
+            if (bytes.length !== row.size || options.sha256 && sha256 !== options.sha256)
+                throw new CliError('INTEGRITY_MISMATCH', 'Downloaded bytes differ from the selected size or digest');
+            const file = await open(temporary, 'wx', 0o600);
+            try {
+                await file.writeFile(bytes);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            if (options.clobber)
+                await rename(temporary, destination);
+            else
+                await link(temporary, destination);
+            completed.push({ id: row.id, name: row.name, bytes: bytes.length, sha256, content_type: type, path: destination });
+        }
+        catch (error) {
+            if (!completed.length)
+                throw error;
+            throw new CliError('PARTIAL_TRANSFER', 'Completed attachment IDs ' + completed.map(row => row.id).join(',') + '; remaining transfer failed: ' + (error instanceof CliError ? error.code : 'FILE_ERROR'));
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    return { downloads: completed };
+}

package/dist/catalogue.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { CliError } from './error.js';
+export const baseline = JSON.parse(readFileSync(new URL('../schemas/catalogue.json', import.meta.url), 'utf8')).commands;
+export function commandGap(path) {
+    if (/^(discussion|gist|project) /.test(path))
+        return 'No corresponding discussion, gist or Projects v2 API is documented in the retained Gitea 1.23.4 or 1.24.0 specifications';
+    if (/^issue (lock|unlock)$/.test(path))
+        return 'Gitea 1.23.4 has no documented issue lock contract; the retained 1.24.0 lock candidate is not commissioned';
+    if (/^issue (transfer|subissue )/.test(path))
+        return 'Gitea 1.23.4 and 1.24.0 provide no evidenced issue transfer or parent/child subissue contract; repository transfer and dependencies are different operations';
+    if (path === 'pr ready')
+        return 'Gitea 1.23.4 and 1.24.0 do not document a draft transition field in EditPullRequestOption';
+    if (path === 'setup hooks')
+        return 'C096: retained gh-axi 0.1.46 help does not specify supported agent paths, configuration schemas or repair semantics; hook installation remains pending';
+    if (path === 'update' || path === 'update --check')
+        return 'C122/C123: retained gh-axi 0.1.46 help does not establish the distribution, integrity or rollback contract; update and check-only remain pending';
+    if (path === 'api HEAD')
+        return 'Gitea 1.23.4 has no documented HEAD operation/effect contract; no GET substitution is performed';
+    if (path === 'pr review')
+        return 'Gitea 1.23.4 and 1.24.0 do not establish review event values or atomic stale-head rejection (CX-007); review posting remains pending';
+    if (path === 'dashboard')
+        return 'C121: exact gh-axi 0.1.46 sections and defaults are not captured; the owned bounded repository dashboard is not baseline parity';
+    if (path.startsWith('workflow ') || path.startsWith('run ') && path !== 'run list')
+        return 'Gitea 1.23.4 has task summaries only; retained 1.24.0 workflow/run candidates remain uncommissioned';
+    if (path === 'search code')
+        return 'Gitea 1.23.4 has no evidenced code search API/query contract';
+    if (path === 'stack submit')
+        return 'The required automatic merge scheduling contract remains pending';
+    return;
+}
+export function flagGap(path, name) {
+    if (name === 'jq' || name === 'template')
+        return '--' + name + ' compatibility is not implemented: no jq evaluator or template engine/grammar has been selected; Gitea 1.23.4 responses do not supply these local semantics';
+    return '--' + name + ' has no implemented compatibility contract for ' + path + ' on Gitea 1.23.4; see capabilities for the retained baseline outcome';
+}
+export function capabilityOutput(commands, fields, id) {
+    if (id && !baseline.some(row => row.id === id))
+        throw new CliError('USAGE', 'Select a catalogue ID C001 through C124', 2);
+    const rows = baseline.filter(row => !id || row.id === id).map(row => {
+        const path = row.path === 'update --check' ? 'update' : row.path.startsWith('api ') ? 'api' : row.path;
+        const command = commands.find(command => command.path.join(' ') === path);
+        const gap = commandGap(row.path) ?? command?.gap;
+        const flags = row.flags.map(flag => {
+            const name = flag.name === '-X' ? 'method' : flag.name.replace(/^--/, '');
+            const meta = command?.flags[name];
+            return { ...flag, status: !meta || meta.gap || gap ? 'gap' : 'available with owned semantics',
+                contract: gap ?? meta?.gap ?? 'Use command help; baseline semantic parity is not claimed by flag acceptance' };
+        });
+        return id ? { ...row, status: gap ? 'gap' : 'partial', gap: gap ?? null, flags } :
+            { id: row.id, command: 'gitea-axi ' + row.path, status: gap ? 'gap' : 'partial', flags: flags.length };
+    });
+    return { baseline: 'gh-axi 0.1.46', target: 'Gitea 1.23.4',
+        counts: { commands: baseline.length, commandFlags: baseline.reduce((count, row) => count + row.flags.length, 0), globals: 4, prFields: fields.length, fullParity: 0 },
+        commands: rows,
+        ...(id ? {} : { globals: [
+                { selector: '-R/--repo', contract: 'Explicit repository before matching local remote; stack rejects it and GH_REPO' },
+                { selector: '--hostname/GH_HOST', contract: 'Select exactly one matching configured profile by host and port; exact tokenOrigin binding applies before secret resolution' },
+                { selector: '--help', contract: 'Offline registry-derived help' },
+                { selector: '-v/-V/--version', contract: 'Offline packaged version' },
+            ], prFields: fields.map(field => ({ field, contract: field === 'id' ? 'gap: GraphQL node ID unavailable; fullDatabaseId is the numeric vendor ID' :
+                    field === 'statusCheckRollup' ? 'partial commit statuses only; excludes full check suites' :
+                        ['autoMergeRequest', 'closingIssuesReferences', 'mergeStateStatus', 'potentialMergeCommit', 'projectCards', 'projectItems', 'reviewDecision'].includes(field) ? 'gap: no evidenced Gitea 1.23.4 field contract' : 'owned normalized field; see pr view --fields' })) }),
+        help: id ? ['gitea-axi capabilities'] : ['gitea-axi capabilities C038'],
+    };
+}

package/dist/ci.js

@@ -0,0 +1,24 @@
+import { collect } from './api.js';
+import { CliError } from './error.js';
+import { continuationHelp, positive, selectedFields } from './reads.js';
+export const taskFields = ['id', 'name', 'display_title', 'workflow_id', 'head_branch', 'head_sha', 'event', 'status', 'run_number', 'url', 'created_at', 'updated_at', 'run_started_at'];
+export function validateTasks(options) {
+    positive(options.limit, 10, 1000);
+    selectedFields(options, taskFields, []);
+}
+export async function tasks(client, base, options) {
+    const page = await collect(client, base + '/actions/tasks', 'workflow_runs').catch((error) => {
+        if (error instanceof CliError && error.code === 'NOT_FOUND_OR_HIDDEN')
+            throw new CliError('CAPABILITY_GAP', 'Actions task reads are unavailable or hidden on this server; full workflow run APIs require Gitea 1.24 or later');
+        throw error;
+    });
+    const mapping = { workflow: 'workflow_id', branch: 'head_branch', status: 'status', event: 'event', commit: 'head_sha' };
+    const rows = page.items.filter(row => Object.entries(mapping).every(([flag, field]) => options[flag] === undefined || row[field] === options[flag]));
+    const limit = positive(options.limit, 10, 1000);
+    const fields = selectedFields(options, taskFields, []) ?? ['id', 'name', 'status'];
+    return { items: rows.slice(0, limit).map(row => Object.fromEntries(fields.map(field => [field, row[field] ?? null]))), count: Math.min(rows.length, limit),
+        total: page.truncated ? null : rows.length, unfiltered_total: page.total, next: page.next, truncated: page.truncated || rows.length > limit, continuation: page.truncated || rows.length > limit,
+        help: [...continuationHelp(page, rows.length, limit), ...(page.items.length === 0 ? ['No task summaries returned. Gitea older than 1.24 may return an empty task list even when workflow runs exist; this does not establish that there are no runs.'] : [])],
+        scope: 'Gitea 1.23.4 ActionTask summaries; task/run identity pending commissioning. Status does not establish job conclusions or terminal run results.',
+        pending: ['run details, watch, logs, artifacts and controls', '1.24.0 workflow routes require representative commissioning', 'mutations require the shared write gate'] };
+}

package/dist/credentials.js

@@ -1,12 +1,40 @@
 import { readFileSync, existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
 import { Ajv } from 'ajv';
 import { CliError } from './error.js';
 import { readPrivateFile } from './private-file.js';
 const schema = JSON.parse(readFileSync(new URL('../axi-credential.schema.json', import.meta.url), 'utf8'));
-const validate = new Ajv({ strict: false }).compile(schema);
+const validate = new Ajv({ strict: false, allErrors: true }).compile(schema);
+function validateProfile(profile) {
+    if (validate(profile))
+        return;
+    const value = profile && typeof profile === 'object' ? profile : undefined;
+    const token = value && 'token' in value ? value.token : undefined;
+    const branch = token && typeof token === 'object' ? 'env' in token ? '0' : 'file' in token ? '1' : undefined : undefined;
+    const http = value && 'origin' in value && typeof value.origin === 'string' && value.origin.startsWith('http:');
+    const errors = (validate.errors ?? []).filter(error => {
+        const alternative = error.schemaPath.match(/^#\/properties\/token\/oneOf\/(\d+)\//)?.[1];
+        return (!alternative || alternative === branch) && (!error.schemaPath.startsWith('#/then/') || http) && error.keyword !== 'if' && error.keyword !== 'oneOf';
+    });
+    const priority = { required: 0, additionalProperties: 1 };
+    const error = errors.find(error => error.schemaPath === '#/required') ?? errors.sort((a, b) => (priority[a.keyword] ?? 2) - (priority[b.keyword] ?? 2) || b.instancePath.split('/').length - a.instancePath.split('/').length)[0] ?? validate.errors?.find(error => error.keyword === 'oneOf');
+    const property = error?.keyword === 'required' ? error.params.missingProperty : error?.keyword === 'additionalProperties' ? error.params.additionalProperty : undefined;
+    const field = [...(error?.instancePath.split('/').slice(1) ?? []), ...(property ? [String(property)] : [])].join('.');
+    if (field === 'allowInsecureHttp' && error?.schemaPath.startsWith('#/then/'))
+        throw new CliError('CONFIG_INVALID', 'HTTP requires allowInsecureHttp: true on the selected profile');
+    const correction = error?.keyword === 'additionalProperties' ? 'remove this unknown field' :
+        field === 'token.file' ? 'set an absolute local file path' :
+            field === 'token.env' ? 'set a valid environment variable name' :
+                field === 'token' ? 'set exactly one of env (an environment variable name) or file (an absolute local path)' :
+                    field === 'allowInsecureHttp' ? 'set true or false' :
+                        error?.keyword === 'required' ? 'set this required field' : 'use a value matching the credential profile schema';
+    throw new CliError('CONFIG_INVALID', 'Invalid profile field: ' + (field || 'profile') + '; ' + correction);
+}
 const secrets = [];
+export function registerSecret(value) { if (value)
+    secrets.push(value); }
 export function redact(value) {
     if (Array.isArray(value))
         return value.map(redact);
@@ -69,11 +97,31 @@ export function canonicalOrigin(value) {
 export async function credentials(override, allowHttp, options = {}) {
     const path = configPath(options.config);
     const selected = options.profile ?? process.env.GITEA_AXI_PROFILE;
+    const hostname = options.hostname ?? (selected === 'artium' ? undefined : process.env.GH_HOST);
+    if (hostname === '')
+        throw new CliError('USAGE', '--hostname/GH_HOST requires a nonempty host', 2);
+    const matchesHost = (origin) => {
+        const url = new URL(canonicalOrigin(origin));
+        if (!hostname || /[\s\\/?#@]/.test(hostname))
+            throw new CliError('USAGE', '--hostname/GH_HOST requires a host with optional port', 2);
+        let host;
+        try {
+            host = new URL(url.protocol + '//' + hostname);
+        }
+        catch {
+            throw new CliError('USAGE', '--hostname/GH_HOST requires a host with optional port', 2);
+        }
+        return url.host === host.host;
+    };
     const fields = ['ORIGIN', 'TOKEN_ORIGIN', 'TOKEN', 'ALLOW_INSECURE_HTTP'];
     const hasEnv = fields.some(field => process.env['GITEA_AXI_' + field] !== undefined);
     let profile;
     let profileName = 'environment';
+    let revision = 'environment';
     if (!selected && hasEnv) {
+        const missing = ['ORIGIN', 'TOKEN_ORIGIN', 'TOKEN'].filter(field => !process.env['GITEA_AXI_' + field]);
+        if (missing.length)
+            throw new CliError('CONFIG_INVALID', 'Set missing environment variables: ' + missing.map(field => 'GITEA_AXI_' + field).join(', '));
         let token;
         try {
             token = JSON.parse(process.env.GITEA_AXI_TOKEN ?? 'null');
@@ -87,18 +135,30 @@ export async function credentials(override, allowHttp, options = {}) {
     }
     else if (existsSync(path)) {
         const config = await readConfig(path);
-        const names = Object.keys(config.profiles);
-        const name = selected ?? config.defaultProfile ?? (names.length === 1 ? names[0] : undefined);
+        const names = Object.keys(config.profiles).filter(name => {
+            if (!hostname)
+                return true;
+            const profile = config.profiles[name];
+            validateProfile(profile);
+            return matchesHost(profile.origin);
+        });
+        if (hostname && !selected && !names.length)
+            throw new CliError('PROFILE_NOT_FOUND', 'No configured profile matches --hostname/GH_HOST');
+        const name = selected ?? (hostname ? names.length === 1 ? names[0] : undefined : config.defaultProfile ?? (names.length === 1 ? names[0] : undefined));
         if (!name)
             throw new CliError(names.length ? 'PROFILE_AMBIGUOUS' : 'PROFILE_REQUIRED', 'Select a profile');
         if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name) || !Object.hasOwn(config.profiles, name))
             throw new CliError('PROFILE_NOT_FOUND', 'Selected profile was not found');
         profile = config.profiles[name];
         profileName = name;
+        revision = process.env.GITEA_AXI_CREDENTIAL_REVISION ?? String((await stat(path, { bigint: true })).mtimeNs);
     }
     else if (selected || options.config || process.env.GITEA_AXI_CONFIG) {
         throw new CliError('PROFILE_NOT_FOUND', 'Selected profile configuration was not found');
     }
+    else if (hostname) {
+        throw new CliError('PROFILE_NOT_FOUND', '--hostname/GH_HOST requires a matching configured profile');
+    }
     else if (override) {
         const origin = canonicalOrigin(override);
         if (origin.startsWith('http:') && !allowHttp)
@@ -108,9 +168,10 @@ export async function credentials(override, allowHttp, options = {}) {
     else {
         throw new CliError('AUTH_REQUIRED', 'Select a configured profile or an explicit anonymous --origin');
     }
-    if (!validate(profile))
-        throw new CliError('CONFIG_INVALID', 'Invalid profile field: ' + (validate.errors?.[0]?.instancePath || 'token/origin'));
+    validateProfile(profile);
     const origin = canonicalOrigin(profile.origin);
+    if (hostname && !matchesHost(origin))
+        throw new CliError('AUTH_BINDING_MISMATCH', 'Selected profile does not match --hostname/GH_HOST');
     if (origin !== canonicalOrigin(profile.tokenOrigin) || (override && canonicalOrigin(override) !== origin)) {
         throw new CliError('AUTH_BINDING_MISMATCH', 'origin must match tokenOrigin before resolving token');
     }
@@ -123,11 +184,13 @@ export async function credentials(override, allowHttp, options = {}) {
         if (!isAbsolute(profile.token.file) || /^\\\\/.test(profile.token.file))
             throw new CliError('CONFIG_INVALID', 'token file must be an absolute local path');
         token = (await readPrivateFile(profile.token.file, true)).replace(/^\uFEFF/, '').trimEnd();
+        revision += ':' + String((await stat(profile.token.file, { bigint: true })).mtimeNs);
     }
     if (!token)
         throw new CliError('AUTH_REQUIRED', 'token reference is empty');
     secrets.push(token);
     if (/[\r\n]/.test(token))
         throw new CliError('CONFIG_INVALID', 'token must be a single line');
-    return { origin, token, profile: profileName, source: 'env' in profile.token ? 'env:' + profile.token.env : 'file:' + profile.token.file };
+    return { origin, token, profile: profileName, revision, source: 'env' in profile.token ? 'env:' + profile.token.env : 'file:' + profile.token.file,
+        ...(profile.writes ? { writes: profile.writes } : {}) };
 }

package/dist/git.js

@@ -0,0 +1,89 @@
+import { spawn } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { CliError } from './error.js';
+import { createHash } from 'node:crypto';
+export class Git {
+    cwd;
+    origin;
+    token;
+    constructor(cwd, origin, token) {
+        this.cwd = cwd;
+        this.origin = origin;
+        this.token = token;
+    }
+    async run(args, allowed = [0]) {
+        const env = {
+            PATH: process.env.PATH, SystemRoot: process.env.SystemRoot,
+            GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
+            GIT_OPTIONAL_LOCKS: '0',
+            GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: '', GIT_EDITOR: 'true', GIT_SEQUENCE_EDITOR: 'true',
+            GIT_CONFIG_COUNT: this.token ? '1' : '0',
+            ...(this.token ? { GIT_CONFIG_KEY_0: 'http.' + this.origin + '/.extraHeader', GIT_CONFIG_VALUE_0: 'Authorization: token ' + this.token } : {}),
+        };
+        return new Promise((resolve, reject) => {
+            const child = spawn('git', ['-c', 'core.hooksPath=' + (process.platform === 'win32' ? 'NUL' : '/dev/null'),
+                '-c', 'core.fsmonitor=false', '-c', 'credential.helper=', '-c', 'http.followRedirects=false', '-c', 'protocol.allow=never',
+                '-c', 'protocol.http.allow=always', '-c', 'protocol.https.allow=always',
+                ...(args[0] === 'push' ? ['push', '--no-follow-tags', '--recurse-submodules=no', ...args.slice(1)] : args)], {
+                cwd: this.cwd, env, stdio: ['ignore', 'pipe', 'pipe'], timeout: 120_000,
+            });
+            let output = '', size = 0;
+            child.stdout.on('data', (bytes) => { size += bytes.length; if (size > 2_000_000)
+                child.kill();
+            else
+                output += bytes.toString(); });
+            child.stderr.on('data', () => { });
+            child.on('error', () => reject(new CliError('GIT_FAILED', 'Unable to start native Git')));
+            child.on('close', code => allowed.includes(code ?? -1) && size <= 2_000_000 ? resolve(output.trimEnd()) :
+                reject(new CliError('GIT_FAILED', 'Native Git ' + args[0] + ' stopped; inspect the workspace for conflicts before continuing')));
+        });
+    }
+    async workspace() {
+        if (!isAbsolute(this.cwd) || await realpath(this.cwd) !== this.cwd || await this.run(['rev-parse', '--show-toplevel']) !== this.cwd) {
+            throw new CliError('USAGE', '--workspace must be the absolute native repository root', 2);
+        }
+        const config = await this.run(['config', '--local', '--name-only', '--list']) + '\n' +
+            await this.run(['config', '--worktree', '--name-only', '--list']);
+        if (config.split('\n').some(key => /^(?:url\.|http\.|credential\.|include\.|includeif\.|filter\.|diff\.|core\.sshcommand$|remote\..*\.(?:proxy|uploadpack|receivepack|pushurl|vcs)$)/i.test(key))) {
+            throw new CliError('UNSAFE_GIT_CONFIG', 'Workspace transport overrides must be removed before using origin-bound Git');
+        }
+        return this;
+    }
+    async clean() {
+        if (await this.run(['status', '--porcelain=v1', '--untracked-files=all']))
+            throw new CliError('DIRTY_WORKSPACE', 'Commit or stash workspace changes before this operation');
+    }
+    async branch(name) {
+        if (!name || name.startsWith('-'))
+            throw new CliError('USAGE', 'Select a branch name', 2);
+        await this.run(['check-ref-format', '--branch', name]);
+        return name;
+    }
+    async tip(branch = 'HEAD') { return this.run(['rev-parse', '--verify', branch + '^{commit}']); }
+    async snapshot() {
+        const status = await this.run(['status', '--porcelain=v1', '--untracked-files=all']);
+        return { head: await this.tip(), branch: await this.run(['symbolic-ref', '--quiet', '--short', 'HEAD'], [0, 1]),
+            refs: await this.run(['for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads']), status,
+            diff: createHash('sha256').update(await this.run(['diff', '--no-ext-diff', '--no-textconv', '--binary', 'HEAD'])).digest('hex'),
+            index: createHash('sha256').update(await this.run(['diff', '--no-ext-diff', '--no-textconv', '--cached', '--binary', 'HEAD'])).digest('hex'),
+            worktrees: await this.run(['worktree', 'list', '--porcelain']) };
+    }
+    url(repository) {
+        if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || repository.split('/').some(part => part === '.' || part === '..')) {
+            throw new CliError('USAGE', 'Select OWNER/NAME', 2);
+        }
+        return this.origin + '/' + repository + '.git';
+    }
+    async remote(name) {
+        if (!/^[A-Za-z0-9_-]+$/.test(name))
+            throw new CliError('USAGE', 'Select a simple remote name', 2);
+        const urls = (await this.run(['remote', 'get-url', '--all', name])).split('\n');
+        const url = new URL(urls[0]);
+        if (urls.length !== 1 || url.origin !== this.origin || url.username || url.password || url.search || url.hash ||
+            !/^\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\.git$/.test(url.pathname)) {
+            throw new CliError('ORIGIN_MISMATCH', 'Selected remote must be one credential-free OWNER/NAME.git URL on the selected origin');
+        }
+        return { name, url: url.href, repository: url.pathname.slice(1, -4) };
+    }
+}