@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/exact-head-github-provider.mjs

@@ -0,0 +1,332 @@
+// GitHub provider for exact-head-ci.mjs. Reads one operation as JSON on stdin and
+// writes one JSON response. It never exposes enqueue, approve, merge, review-write,
+// or queue-write operations.
+
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { providerWorkflowIdentityMatches } from '../../engineering-runtime/scripts/exact-head-artifact.mjs'
+
+const PROVIDER_HANDLERS = Object.freeze({
+  snapshot,
+  retarget: mutate,
+  'set-open': mutate,
+  'set-draft': mutate,
+  'set-labels': mutate,
+  'set-queue-inactive': deactivateQueue,
+  'dispatch-workflow': dispatch,
+  'read-workflow': readWorkflow,
+  'read-publish-only-checks': readPublishOnlyChecks,
+  'read-queue-execution': readQueueExecution,
+})
+
+export const PROVIDER_OPERATIONS = Object.freeze(Object.keys(PROVIDER_HANDLERS))
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function strings(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.trim())
+}
+
+export function validateProviderRequest(request) {
+  const errors = []
+  if (!isObject(request)) return { ok: false, errors: ['provider request must be an object'] }
+  if (!PROVIDER_OPERATIONS.includes(request.operation)) errors.push(`unsupported provider operation "${request.operation}"`)
+  if (typeof request.repository !== 'string' || !/^[^/\s]+\/[^/\s]+$/.test(request.repository)) errors.push('repository must be owner/name')
+  if (!Number.isInteger(request.pr) || request.pr < 1) errors.push('pr must be a positive integer')
+  const config = request.providerConfig
+  const readOnlyQueueExecution = request.operation === 'read-queue-execution'
+  const needsSnapshotConfig = ['snapshot', 'retarget', 'set-open', 'set-draft', 'set-labels', 'set-queue-inactive', 'read-publish-only-checks'].includes(request.operation)
+  const needsDeactivationConfig = request.operation === 'set-queue-inactive'
+  const needsDispatchConfig = request.operation === 'dispatch-workflow'
+  if (!readOnlyQueueExecution && !isObject(config)) errors.push('providerConfig must be an object')
+  if (!readOnlyQueueExecution && config?.ghCommand !== undefined && (typeof config.ghCommand !== 'string' || !config.ghCommand.trim())) errors.push('providerConfig.ghCommand must be a non-empty string')
+
+  if (needsSnapshotConfig) {
+    if (!strings(config?.queueActiveLabels)) errors.push('providerConfig.queueActiveLabels must be an array of strings (use [] when no label represents queue membership)')
+    if (typeof config?.queueProvider !== 'string' || !config.queueProvider.trim()) errors.push('providerConfig.queueProvider must be a non-empty string')
+  }
+
+  if (needsDeactivationConfig) {
+    const deactivateArgs = config?.queueDeactivateArgs
+    const deactivateBodyIndex = Array.isArray(deactivateArgs) ? deactivateArgs.indexOf('--body') : -1
+    const deactivateBody = deactivateBodyIndex >= 0 ? deactivateArgs[deactivateBodyIndex + 1] : ''
+    const nonDeactivationBody = typeof deactivateBody === 'string' ? deactivateBody.replace(/\b(?:dequeue|unqueue)\b/gi, '') : ''
+    const safeDeactivation = Array.isArray(deactivateArgs)
+      && deactivateArgs.length === 7
+      && deactivateArgs.slice(0, 6).every((arg, index) => arg === ['pr', 'comment', '{pr}', '--repo', '{repository}', '--body'][index])
+      && typeof deactivateBody === 'string'
+      && /\b(?:dequeue|unqueue)\b/i.test(deactivateBody)
+      && !/\b(?:queue|enqueue|approve|merge|review)\b/i.test(nonDeactivationBody)
+    if (!strings(deactivateArgs)) errors.push('providerConfig.queueDeactivateArgs must be an array of strings')
+    if (Array.isArray(config?.queueActiveLabels) && config.queueActiveLabels.length > 0 && Array.isArray(deactivateArgs) && deactivateArgs.length === 0) errors.push('providerConfig.queueDeactivateArgs cannot be empty when queueActiveLabels can detect active membership')
+    if (Array.isArray(config?.queueActiveLabels) && config.queueActiveLabels.length > 0 && !safeDeactivation) errors.push('providerConfig.queueDeactivateArgs must be a direct gh pr comment deactivation and cannot enqueue, approve, merge, or write reviews')
+  }
+
+  if (needsDispatchConfig) {
+    for (const field of ['creationTimeoutMs', 'creationPollIntervalMs']) {
+      if (!Number.isInteger(config?.[field]) || config[field] < 1) errors.push(`providerConfig.${field} must be a positive integer`)
+    }
+  }
+  if (request.operation === 'read-workflow') {
+    if (typeof request.runId !== 'string' && typeof request.runId !== 'number') errors.push('runId must identify the provider run')
+    if (typeof request.workflowId !== 'string' || !request.workflowId.trim()) errors.push('workflowId must identify the expected provider workflow')
+    if (typeof request.headSha !== 'string' || !/^[0-9a-f]{40}$/i.test(request.headSha)) errors.push('headSha must be a full 40-character commit SHA')
+  }
+  return { ok: errors.length === 0, errors }
+}
+
+const DEFAULT_BOUNDARY = Object.freeze({ execFileSync })
+
+function gh(request, args, boundary) {
+  return boundary.execFileSync(request.providerConfig?.ghCommand || 'gh', args, {
+    encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+  }).trim()
+}
+
+function ghJson(request, args, boundary) {
+  const text = gh(request, args, boundary)
+  return text ? JSON.parse(text) : null
+}
+
+function pause(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+export function snapshotFromView(view, config) {
+  const labels = (view.labels || []).map((label) => typeof label === 'string' ? label : label.name).filter(Boolean).sort()
+  const activeLabels = new Set(config.queueActiveLabels)
+  const matchingLabels = labels.filter((label) => activeLabels.has(label))
+  return {
+    base: view.baseRefName,
+    headSha: view.headRefOid,
+    open: view.state === 'OPEN',
+    draft: view.isDraft === true,
+    labels,
+    queue: {
+      provider: config.queueProvider,
+      state: matchingLabels.length ? 'active' : 'inactive',
+      active: matchingLabels.length > 0,
+      matchingLabels,
+    },
+    reviews: {
+      decision: view.reviewDecision || null,
+      latest: (view.latestReviews || []).map(({ id, author, state, submittedAt, commit }) => ({
+        id: id || null,
+        author: author?.login || null,
+        state: state || null,
+        submittedAt: submittedAt || null,
+        commitOid: commit?.oid || null,
+      })),
+    },
+  }
+}
+
+export function labelDelta(current, target) {
+  const have = new Set(current)
+  const want = new Set(target)
+  return {
+    add: [...want].filter((label) => !have.has(label)).sort(),
+    remove: [...have].filter((label) => !want.has(label)).sort(),
+  }
+}
+
+export function chooseCreatedRun(runs, { headSha, startedAt }) {
+  return (runs || [])
+    .filter((run) => run.headSha === headSha && Date.parse(run.createdAt) >= Date.parse(startedAt))
+    .sort((left, right) => Date.parse(left.createdAt) - Date.parse(right.createdAt))[0] || null
+}
+
+function snapshot(request, boundary) {
+  const view = ghJson(request, ['pr', 'view', String(request.pr), '--repo', request.repository, '--json', 'baseRefName,headRefOid,state,isDraft,labels,reviewDecision,latestReviews'], boundary)
+  return snapshotFromView(view, request.providerConfig)
+}
+
+function mutate(request, boundary) {
+  const base = ['--repo', request.repository]
+  const current = snapshot(request, boundary)
+  if (request.operation === 'retarget') {
+    if (current.base === request.base) return { ok: true, unchanged: true }
+    gh(request, ['pr', 'edit', String(request.pr), ...base, '--base', request.base], boundary)
+  } else if (request.operation === 'set-open') {
+    if (current.open === request.open) return { ok: true, unchanged: true }
+    gh(request, ['pr', request.open ? 'reopen' : 'close', String(request.pr), ...base], boundary)
+  } else if (request.operation === 'set-draft') {
+    if (current.draft === request.draft) return { ok: true, unchanged: true }
+    gh(request, request.draft
+      ? ['pr', 'ready', String(request.pr), ...base, '--undo']
+      : ['pr', 'ready', String(request.pr), ...base], boundary)
+  } else if (request.operation === 'set-labels') {
+    const delta = labelDelta(current.labels, request.labels)
+    for (const label of delta.remove) gh(request, ['pr', 'edit', String(request.pr), ...base, '--remove-label', label], boundary)
+    for (const label of delta.add) gh(request, ['pr', 'edit', String(request.pr), ...base, '--add-label', label], boundary)
+  }
+  return { ok: true }
+}
+
+function deactivateQueue(request, boundary) {
+  const current = snapshot(request, boundary)
+  if (!current.queue.active) return { ok: true, alreadyInactive: true }
+  const args = request.providerConfig.queueDeactivateArgs.map((arg) => arg
+    .replaceAll('{pr}', String(request.pr))
+    .replaceAll('{repository}', request.repository))
+  gh(request, args, boundary)
+  return { ok: true, alreadyInactive: false }
+}
+
+function dispatch(request, boundary) {
+  const startedAt = new Date().toISOString()
+  const args = ['workflow', 'run', request.workflow, '--repo', request.repository, '--ref', request.ref]
+  for (const [key, value] of Object.entries(request.inputs || {})) args.push('-f', `${key}=${String(value)}`)
+  gh(request, args, boundary)
+  const deadline = Date.now() + request.providerConfig.creationTimeoutMs
+  while (Date.now() <= deadline) {
+    const runs = ghJson(request, ['run', 'list', '--repo', request.repository, '--workflow', request.workflow, '--event', 'workflow_dispatch', '--limit', '100', '--json', 'databaseId,status,conclusion,headSha,createdAt'], boundary)
+    const run = chooseCreatedRun(runs, { headSha: request.headSha, startedAt })
+    if (run) return { runId: run.databaseId }
+    pause(request.providerConfig.creationPollIntervalMs)
+  }
+  throw new Error(`workflow-creation-failure: no ${request.workflow} run appeared at ${request.headSha} within ${request.providerConfig.creationTimeoutMs}ms`)
+}
+
+function readWorkflow(request, boundary) {
+  const run = ghJson(request, ['api', `repos/${request.repository}/actions/runs/${request.runId}`], boundary)
+  const workflow = { id: run?.workflow_id, name: run?.name, path: run?.path }
+  if (String(run?.id) !== String(request.runId)) throw new Error(`workflow run identity mismatch: expected run ${request.runId}, observed ${run?.id ?? 'missing'}`)
+  if (run?.head_sha !== request.headSha) throw new Error(`workflow head-drift: expected ${request.headSha}, observed ${run?.head_sha ?? 'missing'}`)
+  if (!providerWorkflowIdentityMatches(request.workflowId, workflow)) {
+    throw new Error(`workflow identity mismatch: expected ${request.workflowId}, observed ${workflow.name || workflow.path || workflow.id || 'missing'}`)
+  }
+  const pages = ghJson(request, ['api', '--paginate', '--slurp', `repos/${request.repository}/actions/runs/${request.runId}/jobs?per_page=100`], boundary) || []
+  const jobs = pages.flatMap((page) => page.jobs || []).map(({ id, name, status, conclusion }) => ({ id, name, status, conclusion }))
+  return { runId: run.id, workflow, status: run.status, conclusion: run.conclusion, headSha: run.head_sha, jobs }
+}
+const MERGIFY_PAYLOAD_RE = /-\*- Mergify Payload -\*-\s*\n(\{[\s\S]*?\})\s*\n-\*- Mergify Payload End -\*-/
+
+function mergedQueuePr(comments) {
+  const status = (comments || []).filter((comment) => comment?.author?.login === 'mergify' && /"state"\s*:\s*"merged"/.test(comment?.body || ''))
+  const ids = status.map((comment) => /Checks passed\s*[^#]*#(\d+)/i.exec(comment.body || '')?.[1]).filter(Boolean)
+  return ids.length === 1 ? Number(ids[0]) : null
+}
+
+function queuePrNumber(value) {
+  return Number.isInteger(value) && value > 0 ? value : null
+}
+
+function activeQueuePr(comments) {
+  let queuePr = null
+  for (const comment of Array.isArray(comments) ? comments : []) {
+    if (comment?.author?.login !== 'mergify') continue
+    const match = MERGIFY_PAYLOAD_RE.exec(comment?.body || '')
+    if (!match) continue
+    let payload
+    try { payload = JSON.parse(match[1]) } catch { continue }
+    const candidate = queuePrNumber(payload?.speculative_check_pr)
+    if (candidate) queuePr = candidate
+  }
+  return queuePr
+}
+
+function queueCheckState(run) {
+  const conclusion = String(run?.conclusion ?? '').toLowerCase()
+  if (conclusion === 'success') return 'success'
+  if (['failure', 'error', 'timed_out', 'cancelled', 'action_required', 'startup_failure'].includes(conclusion)) return 'failure'
+  if (['neutral', 'skipped'].includes(conclusion)) return conclusion
+  const status = String(run?.status ?? run?.state ?? '').toLowerCase()
+  if (['queued', 'requested', 'waiting', 'pending'].includes(status)) return 'queued'
+  if (['in_progress', 'running'].includes(status)) return 'running'
+  return 'queued'
+}
+
+function queueObservationStatus(checks, wantedCount) {
+  if (checks.some((check) => check.state === 'failure')) return 'failure'
+  if (checks.length === wantedCount && checks.every((check) => check.state === 'success')) return 'success'
+  if (checks.some((check) => check.state === 'running')) return 'running'
+  return 'queued'
+}
+
+function readQueueExecution(request, boundary) {
+  const source = ghJson(request, ['pr', 'view', String(request.pr), '--repo', request.repository, '--json', 'headRefOid,comments'], boundary)
+  if (source?.headRefOid !== request.prHeadSha) throw new Error(`queue-execution PR-head drift: expected ${request.prHeadSha}, observed ${source?.headRefOid ?? 'missing'}`)
+  const mergedPr = mergedQueuePr(source.comments)
+  const queuePr = mergedPr ?? activeQueuePr(source.comments)
+  if (!queuePr) throw new Error('queue-execution unavailable or ambiguous: Mergify status did not identify one synthetic draft PR')
+  const queue = ghJson(request, ['api', `repos/${request.repository}/pulls/${queuePr}`], boundary)
+  const queueHeadSha = queue?.head?.sha
+  if (typeof queueHeadSha !== 'string' || !/^[0-9a-f]{40}$/i.test(queueHeadSha) || queueHeadSha === request.prHeadSha) {
+    throw new Error('queue-execution unavailable: synthetic queue PR has no distinct full head SHA')
+  }
+  const pages = ghJson(request, ['api', '--paginate', '--slurp', `repos/${request.repository}/commits/${queueHeadSha}/check-runs?per_page=100`], boundary) || []
+  const wanted = new Set(request.names || [])
+  const runs = pages.flatMap((page) => page.check_runs || []).filter((run) => wanted.has(run.name))
+  const byName = new Map()
+  for (const run of runs) {
+    if (byName.has(run.name)) throw new Error(`queue-execution ambiguous: duplicate check run ${run.name} on synthetic head`)
+    byName.set(run.name, run)
+  }
+  if (mergedPr) {
+    if (byName.size !== wanted.size) throw new Error('queue-execution unavailable: one or more required queue-head checks are missing')
+    return {
+      version: 1, kind: 'queue-execution', repository: request.repository, pr: request.pr,
+      prHeadSha: request.prHeadSha, queuePr, queueHeadSha, provider: 'github',
+      checks: [...wanted].sort().map((name) => ({ name, provider: 'github', conclusion: byName.get(name).conclusion, headSha: queueHeadSha })),
+      status: 'pass',
+    }
+  }
+  const checks = [...wanted].sort().flatMap((name) => {
+    const run = byName.get(name)
+    return run ? [{
+      name, provider: 'github', status: run.status ?? null, conclusion: run.conclusion ?? null,
+      state: queueCheckState(run), headSha: queueHeadSha,
+    }] : []
+  })
+  return {
+    version: 1, kind: 'queue-execution-observation', repository: request.repository, pr: request.pr,
+    prHeadSha: request.prHeadSha, queuePr, queueHeadSha, provider: 'github', checks,
+    status: queueObservationStatus(checks, wanted.size),
+  }
+}
+
+function readPublishOnlyChecks(request, boundary) {
+  const live = snapshot(request, boundary)
+  if (live.headSha !== request.headSha) throw new Error(`publish-only head-drift: expected ${request.headSha}, observed ${live.headSha}`)
+  const pages = ghJson(request, ['api', '--paginate', '--slurp', `repos/${request.repository}/commits/${request.headSha}/check-runs?per_page=100`], boundary) || []
+  const checks = pages.flatMap((page) => page.check_runs || [])
+  const requested = new Set(request.names || [])
+  return {
+    checks: checks.filter((check) => requested.has(check.name)).map((check) => ({
+      name: check.name,
+      provider: 'github',
+      repository: request.repository,
+      pr: request.pr,
+      headSha: request.headSha,
+      conclusion: check.conclusion,
+    })),
+  }
+}
+
+
+export function handleProviderRequest(request, boundary = DEFAULT_BOUNDARY) {
+  const verdict = validateProviderRequest(request)
+  if (!verdict.ok) throw new Error(`invalid GitHub provider request: ${verdict.errors.join('; ')}`)
+  return PROVIDER_HANDLERS[request.operation](request, boundary)
+}
+
+function main() {
+  if (process.argv.includes('--help') || process.argv.includes('-h')) {
+    console.log('usage: exact-head-github-provider.mjs  # reads one exact-head provider operation as JSON on stdin')
+    return 0
+  }
+  try {
+    const request = JSON.parse(fs.readFileSync(0, 'utf8'))
+    process.stdout.write(`${JSON.stringify(handleProviderRequest(request))}\n`)
+    return 0
+  } catch (error) {
+    console.error(`exact-head-github-provider: ${String(error.message || error)}`)
+    return 1
+  }
+}
+
+if (isMainModule(import.meta.url)) process.exit(main())