@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/dist/lib/platform/pull-requests.js

@@ -0,0 +1,338 @@
+import fs from 'node:fs';
+import { parseTaskFrontmatter } from '../task/frontmatter.js';
+import { resolveTaskRef } from '../task/resolve-ref.js';
+import { extractSection } from '../task/sections.js';
+import { captureTaskWriteMetadata, writeTask } from '../task/write.js';
+import { resolvePlatformContext } from './context.js';
+import { createGitHubClient } from './github-client.js';
+import { inspectPlatformIssue } from './issues.js';
+import { planPullRequestMetadata } from './pull-request-metadata.js';
+import { platformResult } from './types.js';
+function result(status, taskId, issueNumber, prNumber, overrides = {}) {
+    return {
+        ...platformResult(status),
+        task: { id: taskId, issueNumber, prNumber },
+        pullRequest: null,
+        ...overrides
+    };
+}
+function normalizePullRequest(remote, repository) {
+    const number = Number(remote.number);
+    const headRepository = remote.head?.repo?.full_name;
+    const baseRepository = remote.base?.repo?.full_name;
+    if (!Number.isInteger(number) || number <= 0 || !remote.node_id || !remote.html_url ||
+        !remote.head?.ref || !remote.head.sha || !headRepository || !remote.base?.ref || !baseRepository)
+        return null;
+    return {
+        repository,
+        number,
+        nodeId: remote.node_id,
+        url: remote.html_url,
+        state: remote.state === 'closed' ? 'closed' : 'open',
+        title: remote.title || '',
+        body: remote.body || '',
+        draft: Boolean(remote.draft),
+        head: { repository: headRepository, ref: remote.head.ref, sha: remote.head.sha },
+        base: { repository: baseRepository, ref: remote.base.ref },
+        labels: (remote.labels || []).map((label) => typeof label === 'string' ? label : label.name || '').filter(Boolean).sort(),
+        assignees: (remote.assignees || []).map((assignee) => assignee.login || '').filter(Boolean).sort(),
+        milestone: remote.milestone?.title || null
+    };
+}
+function expectedHead(repository, head) {
+    const colon = head.indexOf(':');
+    if (colon === -1)
+        return { repository, ref: head };
+    const repoName = repository.split('/')[1] || '';
+    return { repository: `${head.slice(0, colon)}/${repoName}`, ref: head.slice(colon + 1) };
+}
+function selectPullRequest(remotes, repository, head, base) {
+    const wanted = expectedHead(repository, head);
+    const matches = remotes.flatMap((remote) => {
+        const normalized = normalizePullRequest(remote, repository);
+        return normalized && normalized.state === 'open' && normalized.head.repository === wanted.repository &&
+            normalized.head.ref === wanted.ref && normalized.base.repository === repository && normalized.base.ref === base
+            ? [normalized] : [];
+    });
+    if (matches.length === 1)
+        return { status: 'resolved', pullRequest: matches[0] };
+    return { status: matches.length === 0 ? 'missing' : 'ambiguous', pullRequest: null };
+}
+function resolvedContext(taskRef, options) {
+    const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+    if (!resolved.ok)
+        return { ok: false, output: result('failed', resolved.taskId, null, null, {
+                error: { code: resolved.code, message: resolved.message, retryable: false }
+            }) };
+    const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    const frontmatter = parseTaskFrontmatter(content);
+    const issue = Number(frontmatter.issue_number);
+    const pr = Number(frontmatter.pr_number);
+    const issueNumber = Number.isInteger(issue) && issue > 0 ? issue : null;
+    const prNumber = Number.isInteger(pr) && pr > 0 ? pr : null;
+    const client = options.client || createGitHubClient();
+    const context = resolvePlatformContext({ cwd: resolved.repoRoot, client });
+    const usable = (context.status === 'no-op' || context.status === 'degraded') && context.platform.repository;
+    if (!usable)
+        return { ok: false, output: result(context.status, resolved.taskId, issueNumber, prNumber, {
+                platform: context.platform, capabilities: context.capabilities, operations: context.operations, error: context.error
+            }) };
+    return { ok: true, resolved, content, frontmatter, issueNumber, prNumber, client, context };
+}
+function inspectGitHubPullRequest(client, repository, number, cwd) {
+    const fetched = client.json(['api', `repos/${repository}/pulls/${number}`], { cwd });
+    if (!fetched.ok)
+        return fetched;
+    const pullRequest = normalizePullRequest(fetched.value, repository);
+    return pullRequest
+        ? { ok: true, value: pullRequest }
+        : { ok: false, error: { code: 'PR_IDENTITY_INVALID', message: 'Remote resource is not a valid pull request', retryable: false } };
+}
+function locatePullRequest(base, head, target) {
+    const repository = base.context.platform.repository;
+    const listed = base.client.json([
+        'api', `repos/${repository}/pulls?state=open&base=${encodeURIComponent(target)}&per_page=100`
+    ], { cwd: base.resolved.repoRoot });
+    if (!listed.ok)
+        return listed;
+    const selected = selectPullRequest(listed.value, repository, head, target);
+    return selected.status === 'resolved'
+        ? { ok: true, value: selected.pullRequest }
+        : { ok: false, error: {
+                code: selected.status === 'ambiguous' ? 'PR_IDENTITY_AMBIGUOUS' : 'PR_NOT_FOUND',
+                message: selected.status === 'ambiguous' ? 'Multiple pull requests match the exact head/base identity' : 'No pull request matches the exact head/base identity',
+                retryable: false
+            } };
+}
+function inspectPlatformPullRequest(taskRef, options = {}) {
+    const base = resolvedContext(taskRef, options);
+    if (!base.ok)
+        return base.output;
+    if (!base.prNumber)
+        return result('no-op', base.resolved.taskId, base.issueNumber, null, {
+            platform: base.context.platform, capabilities: base.context.capabilities,
+            error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false }
+        });
+    const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository, base.prNumber, base.resolved.repoRoot);
+    if (!fetched.ok)
+        return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform, capabilities: base.context.capabilities,
+            resource: { kind: 'pull-request', number: base.prNumber }, error: fetched.error
+        });
+    return result('no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+        platform: base.context.platform, capabilities: base.context.capabilities,
+        resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value, error: null
+    });
+}
+function appendActivity(content, line) {
+    const body = extractSection(content, ['活动日志', 'Activity Log']);
+    return `${body.replace(/\s+$/, '')}${body.trim() ? '\n' : ''}${line}`;
+}
+function writeCreateStarted(base, agent) {
+    const starts = (base.content.match(/\*\*Create PR \[started\]\*\*/g) || []).length;
+    const dones = (base.content.match(/\*\*Create PR\*\*/g) || []).length;
+    if (starts > dones)
+        return { status: 'no-op' };
+    const metadata = captureTaskWriteMetadata();
+    return writeTask({
+        taskRef: base.resolved.taskId,
+        expectedState: 'active',
+        mutations: [{ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(base.content, `- ${metadata.timestamp} — **Create PR [started]** by ${agent} — started`) }]
+    }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+}
+function bindIdentity(base, pullRequest, agent, dryRun = false) {
+    if (base.prNumber && base.prNumber !== pullRequest.number)
+        return { status: 'failed', error: {
+                code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${base.prNumber}`
+            } };
+    if (base.prNumber === pullRequest.number)
+        return { status: 'no-op', error: null };
+    const current = fs.readFileSync(base.resolved.taskMdPath, 'utf8');
+    const metadata = captureTaskWriteMetadata();
+    return writeTask({
+        taskRef: base.resolved.taskId,
+        expectedState: 'active',
+        dryRun,
+        mutations: [
+            { kind: 'frontmatter', set: { pr_number: pullRequest.number, pr_status: 'created', assigned_to: agent } },
+            { kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: '活动日志', body: appendActivity(current, `- ${metadata.timestamp} — **Create PR** by ${agent} — PR #${pullRequest.number} created → ${pullRequest.url}`) }
+        ]
+    }, { repoRoot: base.resolved.repoRoot, metadataProvider: () => metadata });
+}
+function bindPlatformPullRequest(taskRef, options) {
+    const base = resolvedContext(taskRef, options);
+    if (!base.ok)
+        return base.output;
+    if (!Number.isInteger(options.pr) || options.pr <= 0)
+        return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+        });
+    if (base.prNumber && base.prNumber !== options.pr)
+        return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            error: { code: 'PR_BIND_CONFLICT', message: `Task is already bound to PR #${base.prNumber}`, retryable: false }
+        });
+    const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository, options.pr, base.resolved.repoRoot);
+    if (!fetched.ok)
+        return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { error: fetched.error });
+    const written = bindIdentity(base, fetched.value, options.agent, options.dryRun);
+    if (written.status === 'failed')
+        return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            pullRequest: fetched.value, error: { code: written.error.code, message: written.error.message, retryable: false }
+        });
+    return result(options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', base.resolved.taskId, base.issueNumber, options.dryRun ? base.prNumber : fetched.value.number, {
+        changed: !options.dryRun && written.status === 'applied', platform: base.context.platform, capabilities: base.context.capabilities,
+        resource: { kind: 'pull-request', number: fetched.value.number }, pullRequest: fetched.value,
+        operations: [{ name: 'task:bind-pr', status: options.dryRun ? 'planned' : written.status === 'no-op' ? 'no-op' : 'applied', reasonCode: null }], error: null
+    });
+}
+function createPlatformPullRequest(taskRef, options) {
+    const base = resolvedContext(taskRef, options);
+    if (!base.ok)
+        return base.output;
+    if (!options.base || !options.head || !options.title.trim() || !options.body.trim())
+        return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            error: { code: 'PR_PAYLOAD_INVALID', message: 'base, head, title and body are required', retryable: false }
+        });
+    if (base.prNumber)
+        return inspectPlatformPullRequest(taskRef, options);
+    const located = locatePullRequest(base, options.head, options.base);
+    if (!located.ok && located.error.code === 'PR_IDENTITY_AMBIGUOUS')
+        return result('failed', base.resolved.taskId, base.issueNumber, null, {
+            platform: base.context.platform, capabilities: base.context.capabilities, error: located.error
+        });
+    if (options.dryRun)
+        return result('planned', base.resolved.taskId, base.issueNumber, null, {
+            platform: base.context.platform, capabilities: base.context.capabilities,
+            operations: [{ name: located.ok ? 'pr:reuse' : 'pr:create', status: 'planned', reasonCode: null }], error: null
+        });
+    const started = writeCreateStarted(base, options.agent);
+    if (started.status === 'failed')
+        return result('failed', base.resolved.taskId, base.issueNumber, null, {
+            error: { code: started.error.code, message: started.error.message, retryable: false }
+        });
+    let pullRequest = located.ok ? located.value : null;
+    let created = false;
+    if (!pullRequest) {
+        const repository = base.context.platform.repository;
+        const response = base.client.json(['api', `repos/${repository}/pulls`, '-X', 'POST', '--input', '-'], {
+            cwd: base.resolved.repoRoot,
+            method: 'POST',
+            input: JSON.stringify({ title: options.title, body: options.body, head: options.head, base: options.base, draft: Boolean(options.draft) })
+        });
+        if (response.ok)
+            pullRequest = normalizePullRequest(response.value, repository);
+        else if (response.error.retryable) {
+            const recovered = locatePullRequest(base, options.head, options.base);
+            if (recovered.ok)
+                pullRequest = recovered.value;
+            else
+                return result('blocked', base.resolved.taskId, base.issueNumber, null, {
+                    platform: base.context.platform, capabilities: base.context.capabilities,
+                    operations: [{ name: 'pr:create', status: 'failed', reasonCode: 'PR_CREATE_OUTCOME_UNKNOWN' }],
+                    error: { code: 'PR_CREATE_OUTCOME_UNKNOWN', message: response.error.message, retryable: true }
+                });
+        }
+        else
+            return result('failed', base.resolved.taskId, base.issueNumber, null, {
+                platform: base.context.platform, capabilities: base.context.capabilities,
+                operations: [{ name: 'pr:create', status: 'failed', reasonCode: response.error.code }], error: response.error
+            });
+        if (!pullRequest)
+            return result('failed', base.resolved.taskId, base.issueNumber, null, {
+                error: { code: 'PR_CREATE_RESPONSE_INVALID', message: 'PR create response lacks validated identity', retryable: false }
+            });
+        created = true;
+    }
+    const refreshed = resolvedContext(taskRef, options);
+    if (!refreshed.ok)
+        return result('failed', base.resolved.taskId, base.issueNumber, null, {
+            pullRequest, error: { code: 'PR_CREATED_BIND_FAILED', message: pullRequest.url, retryable: false }
+        });
+    const bound = bindIdentity(refreshed, pullRequest, options.agent);
+    if (bound.status === 'failed')
+        return result('failed', base.resolved.taskId, base.issueNumber, null, {
+            platform: base.context.platform, capabilities: base.context.capabilities,
+            resource: { kind: 'pull-request', number: pullRequest.number }, pullRequest,
+            operations: [{ name: created ? 'pr:create' : 'pr:reuse', status: 'applied', reasonCode: null }, { name: 'task:bind-pr', status: 'failed', reasonCode: bound.error.code }],
+            error: { code: 'PR_CREATED_BIND_FAILED', message: `${pullRequest.url}: ${bound.error.message}`, retryable: false }
+        });
+    return result('applied', base.resolved.taskId, base.issueNumber, pullRequest.number, {
+        changed: true, platform: base.context.platform, capabilities: base.context.capabilities,
+        resource: { kind: 'pull-request', number: pullRequest.number }, pullRequest,
+        operations: [{ name: created ? 'pr:create' : 'pr:reuse', status: created ? 'applied' : 'no-op', reasonCode: null }, { name: 'task:bind-pr', status: 'applied', reasonCode: null }], error: null
+    });
+}
+function syncPlatformPullRequest(taskRef, options) {
+    const base = resolvedContext(taskRef, options);
+    if (!base.ok)
+        return base.output;
+    if (!base.prNumber)
+        return result('failed', base.resolved.taskId, base.issueNumber, null, {
+            error: { code: 'PR_NOT_LINKED', message: 'Task has no valid pr_number', retryable: false }
+        });
+    const fetched = inspectGitHubPullRequest(base.client, base.context.platform.repository, base.prNumber, base.resolved.repoRoot);
+    if (!fetched.ok)
+        return result(fetched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { error: fetched.error });
+    if (!options.metadata && !options.closingIssue)
+        return result('failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            error: { code: 'PR_PAYLOAD_INVALID', message: 'sync requires a desired-state option', retryable: false }
+        });
+    if (!base.issueNumber)
+        return result('degraded', base.resolved.taskId, null, base.prNumber, {
+            pullRequest: fetched.value, error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no linked Issue to copy metadata from', retryable: false }
+        });
+    const issue = inspectPlatformIssue(taskRef, { cwd: base.resolved.repoRoot, client: base.client });
+    if (!issue.issue)
+        return result(issue.status, base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: fetched.value, error: issue.error
+        });
+    const planned = planPullRequestMetadata({
+        pullRequest: fetched.value,
+        issue: issue.issue,
+        taskType: base.frontmatter.type || 'task',
+        issueNumber: base.issueNumber,
+        capabilities: base.context.capabilities
+    }).operations.filter((operation) => options.metadata || operation.name === 'closing-issue')
+        .filter((operation) => options.closingIssue || operation.name !== 'closing-issue');
+    const operations = planned.map(({ name, status, reasonCode }) => ({ name, status, reasonCode }));
+    if (options.dryRun)
+        return result(planned.some((operation) => operation.status === 'planned') ? 'planned' : 'no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform, capabilities: base.context.capabilities, pullRequest: fetched.value, operations, error: null
+        });
+    const payload = {};
+    for (const operation of planned) {
+        if (operation.status !== 'planned')
+            continue;
+        if (operation.name === 'labels')
+            payload.labels = operation.value;
+        if (operation.name === 'assignees')
+            payload.assignees = operation.value;
+        if (operation.name === 'closing-issue')
+            payload.body = operation.value;
+        if (operation.name === 'milestone') {
+            const milestones = base.client.json(['api', '--paginate', '--slurp', `repos/${base.context.platform.repository}/milestones?state=open&per_page=100`], { cwd: base.resolved.repoRoot });
+            if (!milestones.ok)
+                return result(milestones.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { pullRequest: fetched.value, operations, error: milestones.error });
+            const flat = milestones.value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]);
+            payload.milestone = flat.find((entry) => entry.title === operation.value)?.number ?? null;
+        }
+    }
+    if (Object.keys(payload).length === 0) {
+        const degraded = planned.some((operation) => operation.status === 'skipped');
+        return result(degraded ? 'degraded' : 'no-op', base.resolved.taskId, base.issueNumber, base.prNumber, {
+            platform: base.context.platform, capabilities: base.context.capabilities, resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value, operations, error: null
+        });
+    }
+    const patched = base.client.json(['api', `repos/${base.context.platform.repository}/issues/${base.prNumber}`, '-X', 'PATCH', '--input', '-'], {
+        cwd: base.resolved.repoRoot, method: 'PATCH', input: JSON.stringify(payload)
+    });
+    if (!patched.ok)
+        return result(patched.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, { pullRequest: fetched.value, operations, error: patched.error });
+    return result(planned.some((operation) => operation.status === 'skipped') ? 'degraded' : 'applied', base.resolved.taskId, base.issueNumber, base.prNumber, {
+        changed: true, platform: base.context.platform, capabilities: base.context.capabilities,
+        resource: { kind: 'pull-request', number: base.prNumber }, pullRequest: fetched.value,
+        operations: operations.map((operation) => operation.status === 'planned' ? { ...operation, status: 'applied' } : operation), error: null
+    });
+}
+export { bindPlatformPullRequest, createPlatformPullRequest, inspectGitHubPullRequest, inspectPlatformPullRequest, normalizePullRequest, selectPullRequest, syncPlatformPullRequest };
+//# sourceMappingURL=pull-requests.js.map

package/dist/lib/platform/releases.js

@@ -0,0 +1,82 @@
+import { createGitHubClient } from './github-client.js';
+import { resolvePlatformContext } from './context.js';
+import { platformResult } from './types.js';
+function flattenPages(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => Array.isArray(entry) ? entry : [entry]).filter((entry) => Boolean(entry) && typeof entry === 'object');
+}
+function inspectPlatformRelease(tag, options = {}) {
+    const client = options.client ?? createGitHubClient();
+    const context = resolvePlatformContext({ cwd: options.cwd, client });
+    if (!context.platform.repository)
+        return { ...platformResult(context.status), platform: context.platform, release: null, workflows: [], error: context.error };
+    const result = client.json(['release', 'view', tag, '--repo', context.platform.repository, '--json', 'tagName,isDraft,url'], { cwd: options.cwd });
+    if (!result.ok) {
+        if (result.error.code === 'RESOURCE_NOT_FOUND')
+            return { ...platformResult('no-op'), platform: context.platform, release: null, workflows: [], error: null };
+        return { ...platformResult(result.error.retryable ? 'blocked' : 'failed'), platform: context.platform, release: null, workflows: [], error: result.error };
+    }
+    const release = { tag: String(result.value.tagName || tag), published: !Boolean(result.value.isDraft), draft: Boolean(result.value.isDraft), url: result.value.url ? String(result.value.url) : null };
+    const runs = client.json(['run', 'list', '--repo', context.platform.repository, '--limit', '100', '--json', 'name,headBranch,status,conclusion,url'], { cwd: options.cwd });
+    return { ...platformResult(runs.ok ? 'no-op' : runs.error.retryable ? 'blocked' : 'degraded'), platform: context.platform, release, workflows: runs.ok ? runs.value : [], error: runs.ok ? null : runs.error };
+}
+function upsertPlatformRelease(input, options = {}) {
+    const inspected = inspectPlatformRelease(input.tag, options);
+    if (inspected.release?.published)
+        return { ...inspected, status: 'no-op', changed: false, operations: [] };
+    if (inspected.status === 'blocked' || inspected.status === 'failed')
+        return { ...inspected, changed: false, operations: [] };
+    if (!inspected.platform.repository)
+        return { ...inspected, status: 'no-op', changed: false, operations: [] };
+    const client = options.client ?? createGitHubClient();
+    const args = ['release', 'create', input.tag, '--repo', inspected.platform.repository, '--title', input.title ?? input.tag];
+    if (input.notesFile)
+        args.push('--notes-file', input.notesFile);
+    else
+        args.push('--generate-notes');
+    const created = client.text(args, { cwd: options.cwd, method: 'POST' });
+    if (!created.ok)
+        return { ...inspected, status: created.error.retryable ? 'blocked' : 'failed', changed: false, operations: [{ name: 'create-release', status: 'failed' }], error: created.error };
+    return { ...inspectPlatformRelease(input.tag, options), status: 'applied', changed: true, operations: [{ name: 'create-release', status: 'applied' }] };
+}
+function reconcileReleaseMilestones(version, options = {}) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match)
+        return { status: 'failed', changed: false, operations: [], error: { code: 'RELEASE_VERSION_INVALID', message: `Invalid version '${version}'` } };
+    const client = options.client ?? createGitHubClient();
+    const context = resolvePlatformContext({ cwd: options.cwd, client });
+    if (!context.platform.repository)
+        return { ...platformResult(context.status), changed: false, operations: [], error: context.error };
+    const listed = client.json(['api', '--paginate', '--slurp', `repos/${context.platform.repository}/milestones?state=all&per_page=100`], { cwd: options.cwd });
+    if (!listed.ok)
+        return { ...platformResult(listed.error.retryable ? 'blocked' : 'failed'), changed: false, operations: [], error: listed.error };
+    const milestones = flattenPages(listed.value).map((item) => ({ title: String(item.title || ''), number: Number(item.number), state: String(item.state || '') }));
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    const ensure = [`${major}.${minor}.${patch + 1}`, `${major}.${minor}.x`];
+    if (patch === 0)
+        ensure.push(`${major}.${minor + 1}.0`, `${major}.${minor + 1}.x`);
+    const operations = [];
+    const current = milestones.find((item) => item.title === version);
+    if (current && current.state !== 'closed') {
+        const closed = client.json(['api', '--method', 'PATCH', `repos/${context.platform.repository}/milestones/${current.number}`, '-f', 'state=closed'], { cwd: options.cwd });
+        operations.push({ name: 'close-milestone', title: version, status: closed.ok ? 'applied' : 'failed' });
+    }
+    else
+        operations.push({ name: 'close-milestone', title: version, status: 'no-op' });
+    for (const title of ensure) {
+        if (milestones.some((item) => item.title === title))
+            operations.push({ name: 'ensure-milestone', title, status: 'no-op' });
+        else {
+            const created = client.json(['api', '--method', 'POST', `repos/${context.platform.repository}/milestones`, '-f', `title=${title}`], { cwd: options.cwd });
+            operations.push({ name: 'ensure-milestone', title, status: created.ok ? 'applied' : 'failed' });
+        }
+    }
+    const failed = operations.some((operation) => operation.status === 'failed');
+    const changed = operations.some((operation) => operation.status === 'applied');
+    return { status: failed ? 'failed' : changed ? 'applied' : 'no-op', changed, operations, error: failed ? { code: 'MILESTONE_RECONCILE_FAILED', message: 'One or more milestone operations failed' } : null };
+}
+export { inspectPlatformRelease, reconcileReleaseMilestones, upsertPlatformRelease };
+//# sourceMappingURL=releases.js.map

package/dist/lib/platform/types.js

@@ -0,0 +1,22 @@
+const EMPTY_CAPABILITIES = {
+    authenticated: false,
+    comment: false,
+    triage: false,
+    push: false,
+    admin: false
+};
+function platformResult(status, overrides = {}) {
+    return {
+        status,
+        changed: status === 'applied',
+        platform: { type: null, repository: null, currentUser: null },
+        resource: { kind: 'repository', number: null },
+        capabilities: { ...EMPTY_CAPABILITIES },
+        operations: [],
+        comment: null,
+        error: null,
+        ...overrides
+    };
+}
+export { EMPTY_CAPABILITIES, platformResult };
+//# sourceMappingURL=types.js.map

package/dist/lib/platform/verification-required.js

@@ -0,0 +1,78 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { inspectRequiredChecks } from "./pr-checks.js";
+import { resolvePlatformContext } from "./context.js";
+const CHECK_TYPE = "required-checks";
+const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+function validPrNumber(value) {
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0;
+}
+function readPrFlow(repoRoot) {
+    try {
+        const config = JSON.parse(fs.readFileSync(path.join(repoRoot, ".agents", ".airc.json"), "utf8"));
+        return config.prFlow;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readHead(repoRoot) {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], { cwd: repoRoot, encoding: "utf8" }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function evaluateRequiredChecks(context, shared) {
+    const { metadata, localHead, inspection, prFlow } = context;
+    if (prFlow === "disabled" || metadata.pr_status === "skipped" || !validPrNumber(metadata.pr_number)) {
+        return shared.passResult(CHECK_TYPE, "Skipped: required checks are not applicable to this task");
+    }
+    const reviewedHead = String(metadata.last_reviewed_commit || "");
+    if (!localHead || !SHA_PATTERN.test(localHead)) {
+        return shared.blockedResult(CHECK_TYPE, "Unable to resolve the local HEAD", "dependency_error");
+    }
+    if (!SHA_PATTERN.test(reviewedHead)) {
+        return shared.failResult(CHECK_TYPE, "Task has no valid last_reviewed_commit", "check_failed");
+    }
+    if (!inspection || inspection.status === "blocked") {
+        return shared.blockedResult(CHECK_TYPE, inspection?.error?.message || "Required checks are unavailable", "network_error");
+    }
+    if (inspection.status === "failed") {
+        return shared.failResult(CHECK_TYPE, inspection.error?.message || "Required checks are unavailable", "check_failed");
+    }
+    const prHead = inspection.pullRequest?.headSha;
+    if (!prHead || localHead !== reviewedHead || localHead !== prHead) {
+        return shared.failResult(CHECK_TYPE, "Local HEAD, last reviewed commit, and PR head must match", "check_failed");
+    }
+    const state = inspection.checks?.state;
+    if (state === "passed" || state === "no-required") {
+        return shared.passResult(CHECK_TYPE, `Required checks are ${state} for PR head ${prHead}`);
+    }
+    if (state === "pending") {
+        return shared.blockedResult(CHECK_TYPE, inspection.error?.message || "Required checks are pending", "check_pending");
+    }
+    return shared.failResult(CHECK_TYPE, inspection.error?.message || `Required checks are ${state || "unavailable"}`, "check_failed");
+}
+export function check({ taskDir }, shared) {
+    const task = shared.loadTask(taskDir);
+    if (!task.ok)
+        return shared.failResult(CHECK_TYPE, task.message);
+    const platform = resolvePlatformContext({ cwd: shared.repoRoot });
+    if (platform.platform.type !== "github") {
+        return shared.passResult(CHECK_TYPE, "Skipped: this code platform does not provide required checks");
+    }
+    const prFlow = readPrFlow(shared.repoRoot);
+    if (prFlow === "disabled" || task.metadata.pr_status === "skipped" || !validPrNumber(task.metadata.pr_number)) {
+        return evaluateRequiredChecks({ metadata: task.metadata, localHead: null, inspection: null, prFlow }, shared);
+    }
+    const localHead = readHead(shared.repoRoot);
+    if (!localHead)
+        return evaluateRequiredChecks({ metadata: task.metadata, localHead, inspection: null, prFlow }, shared);
+    const inspection = inspectRequiredChecks(task.metadata.id, { cwd: shared.repoRoot });
+    return evaluateRequiredChecks({ metadata: task.metadata, localHead, inspection, prFlow }, shared);
+}
+//# sourceMappingURL=verification-required.js.map