@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/watch-candidate-delivery.mjs

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+
+// Bounded, observation-only watcher for an RC-triggered Cloud Run candidate delivery.
+// stdout is exactly one terminal JSON verdict; stderr is one NDJSON heartbeat per poll.
+
+import { execFileSync } from 'node:child_process'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { evaluateAttest, evaluateLocate, parseTraffic, shaMatches } from './candidate-identity.mjs'
+
+export const DEFAULT_INTERVAL_SECONDS = 30
+export const DEFAULT_MAX_MINUTES = 30
+export const MAX_MINUTES_CEILING = 60
+export const DEFAULT_READ_TIMEOUT_SECONDS = 30
+
+const RC_TAG_RE = /^v\d+\.\d+\.\d+-rc\.\d+$/
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i
+const BUILD_ACTIVE = new Set(['QUEUED', 'PENDING', 'WORKING'])
+const BUILD_FAILED = new Set(['FAILURE', 'INTERNAL_ERROR', 'TIMEOUT', 'CANCELLED', 'EXPIRED'])
+const CANDIDATE_IDENTITY_CONTRADICTIONS = new Set([
+  'candidate-identity-refused',
+  'candidate-revision-mismatch',
+  'candidate-health-mismatch',
+  'candidate-image-mismatch',
+])
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const nonEmpty = (value) => typeof value === 'string' && value.trim() !== ''
+const asArray = (value) => Array.isArray(value) ? value : []
+
+function parseJson(text) {
+  try {
+    return { value: JSON.parse(text) }
+  } catch {
+    return { error: 'provider returned invalid JSON' }
+  }
+}
+
+export function runRead(command, args, timeoutMs) {
+  try {
+    const stdout = execFileSync(command, args, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    })
+    const parsed = parseJson(stdout)
+    return parsed.error
+      ? { readable: false, error: parsed.error }
+      : { readable: true, value: parsed.value }
+  } catch (error) {
+    return {
+      readable: false,
+      error: error.stderr?.toString?.().trim() || error.message || `${command} failed`,
+    }
+  }
+}
+
+function buildIdentityValues(build) {
+  const substitutions = build?.substitutions && typeof build.substitutions === 'object'
+    ? build.substitutions
+    : {}
+  const resolved = build?.sourceProvenance?.resolvedRepoSource ?? {}
+  const source = build?.source?.repoSource ?? {}
+  return {
+    tags: [
+      substitutions.TAG_NAME,
+      substitutions._TAG_NAME,
+      resolved.tagName,
+      source.tagName,
+    ].filter(nonEmpty),
+    shas: [
+      substitutions.COMMIT_SHA,
+      substitutions._COMMIT_SHA,
+      resolved.commitSha,
+      source.commitSha,
+    ].filter(nonEmpty),
+  }
+}
+
+function receipt(build) {
+  return {
+    id: build?.id ?? null,
+    status: nonEmpty(build?.status) ? build.status.toUpperCase() : null,
+    createTime: build?.createTime ?? null,
+    finishTime: build?.finishTime ?? null,
+    logUrl: build?.logUrl ?? null,
+  }
+}
+
+export function inspectBuilds(value, { rcTag, selectedSha }) {
+  if (!Array.isArray(value)) {
+    return { readable: false, matchingReceipts: 0, receipt: null, error: 'build list is not an array' }
+  }
+  const matching = value
+    .filter((build) => {
+      const identity = buildIdentityValues(build)
+      return identity.tags.includes(rcTag) && identity.shas.some((sha) => shaMatches(sha, selectedSha))
+    })
+    .sort((left, right) => String(right.createTime ?? '').localeCompare(String(left.createTime ?? '')))
+
+  return {
+    readable: true,
+    listedReceipts: value.length,
+    matchingReceipts: matching.length,
+    receipt: matching.length > 0 ? receipt(matching[0]) : null,
+  }
+}
+
+function readyCondition(revision) {
+  const conditions = asArray(revision?.status?.conditions)
+  const ready = conditions.find((condition) => condition?.type === 'Ready')
+  return ready
+    ? { status: ready.status ?? null, reason: ready.reason ?? null, message: ready.message ?? null }
+    : { status: null, reason: null, message: null }
+}
+
+function healthUrl(candidateUrl, healthPath) {
+  return `${candidateUrl.replace(/\/$/, '')}/${healthPath.replace(/^\//, '')}`
+}
+
+function baseCandidate(locate) {
+  return {
+    failed: locate.failed ?? [],
+    tag: locate.evidence?.candidate?.tag ?? null,
+    url: locate.evidence?.candidate?.url ?? null,
+    revision: locate.evidence?.candidate?.revision ?? null,
+    percent: locate.evidence?.candidate?.percent ?? null,
+    identity: null,
+    ready: null,
+  }
+}
+
+export function observeCandidate({ serviceRead, revisionRead, healthRead, selectedSha }) {
+  if (!serviceRead.readable) {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'service-unreadable',
+      candidate: { failed: ['e:service-unreadable'], error: serviceRead.error },
+    }
+  }
+  const traffic = parseTraffic(JSON.stringify(serviceRead.value))
+  if (traffic.error) {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'service-traffic-unreadable',
+      candidate: { failed: ['e:service-traffic-unreadable'], error: traffic.error },
+    }
+  }
+  const locate = evaluateLocate({ sha: selectedSha, traffic })
+  if (locate.failed?.length === 1 && locate.failed[0] === 'e:candidate-absent') {
+    return { state: 'absent', terminal: false, reason: 'candidate-not-observed', candidate: baseCandidate(locate) }
+  }
+  if (locate.decision !== 'accept') {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'candidate-identity-refused',
+      candidate: baseCandidate(locate),
+    }
+  }
+
+  const candidate = baseCandidate(locate)
+  if (!revisionRead?.readable) {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'candidate-revision-unreadable',
+      candidate: { ...candidate, failed: ['e:candidate-revision-unreadable'], error: revisionRead?.error },
+    }
+  }
+  if (revisionRead.value?.metadata?.name && revisionRead.value.metadata.name !== candidate.revision) {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'candidate-revision-mismatch',
+      candidate: { ...candidate, failed: ['e:candidate-revision-mismatch'] },
+    }
+  }
+  candidate.ready = readyCondition(revisionRead.value)
+  if (candidate.ready.status === 'False') {
+    return { state: 'failed', terminal: true, reason: 'candidate-not-ready', candidate }
+  }
+  if (candidate.ready.status !== 'True') {
+    return { state: 'building', terminal: false, reason: 'candidate-readiness-pending', candidate }
+  }
+
+  if (!healthRead?.readable) {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'candidate-health-unreadable',
+      candidate: { ...candidate, failed: ['e:candidate-health-unreadable'], error: healthRead?.error },
+    }
+  }
+  const attested = evaluateAttest({
+    sha: selectedSha,
+    locate,
+    health: healthRead.value,
+  })
+  if (attested.decision !== 'accept') {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'candidate-health-mismatch',
+      candidate: { ...candidate, failed: attested.failed ?? [] },
+    }
+  }
+
+  const revisionDigest = revisionRead.value?.status?.imageDigest
+  if (nonEmpty(revisionDigest) && revisionDigest.toLowerCase() !== attested.identity.imageDigest.toLowerCase()) {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'candidate-image-mismatch',
+      candidate: { ...candidate, failed: ['e:digest-mismatch'] },
+    }
+  }
+  return {
+    state: 'ready-at-0',
+    terminal: true,
+    reason: 'candidate-ready-and-attested',
+    candidate: { ...candidate, failed: [], identity: attested.identity },
+  }
+}
+
+function classifyPoll({ build, candidate }) {
+  // Candidate delivery is authoritative success even when the build API omits identity fields.
+  if (candidate.state === 'ready-at-0') return candidate
+  // Definitive candidate failure and identity contradictions are stronger than build receipts.
+  if (candidate.state === 'failed' || CANDIDATE_IDENTITY_CONTRADICTIONS.has(candidate.reason)) {
+    return candidate
+  }
+
+  const status = build.receipt?.status ?? null
+  // An exact terminal receipt is stronger than ambiguity caused only by unreadable provider data.
+  if (BUILD_FAILED.has(status)) {
+    return { state: 'failed', terminal: true, reason: 'build-failed', candidate: candidate.candidate }
+  }
+  if (candidate.terminal) return candidate
+  if (!build.readable) {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'build-and-candidate-inconclusive',
+      candidate: candidate.candidate,
+    }
+  }
+  if (build.receipt && status !== null && !BUILD_ACTIVE.has(status) && status !== 'SUCCESS') {
+    return {
+      state: 'ambiguous',
+      terminal: true,
+      reason: 'unknown-build-status',
+      candidate: candidate.candidate,
+    }
+  }
+  if (BUILD_ACTIVE.has(status) || status === 'SUCCESS' || candidate.state === 'building') {
+    return { state: 'building', terminal: false, reason: 'delivery-in-progress', candidate: candidate.candidate }
+  }
+  return { state: 'not-triggered', terminal: false, reason: 'no-exact-build-or-candidate', candidate: candidate.candidate }
+}
+
+export function parseArgs(argv) {
+  const args = {
+    intervalSeconds: DEFAULT_INTERVAL_SECONDS,
+    maxMinutes: DEFAULT_MAX_MINUTES,
+    readTimeoutSeconds: DEFAULT_READ_TIMEOUT_SECONDS,
+    healthPath: '/health',
+  }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--rc-tag') args.rcTag = argv[++index]
+    else if (arg === '--sha') args.selectedSha = argv[++index]
+    else if (arg === '--service') args.service = argv[++index]
+    else if (arg === '--region') args.region = argv[++index]
+    else if (arg === '--build-region') args.buildRegion = argv[++index]
+    else if (arg === '--interval-seconds') args.intervalSeconds = Number(argv[++index])
+    else if (arg === '--max-minutes') args.maxMinutes = Number(argv[++index])
+    else if (arg === '--read-timeout-seconds') args.readTimeoutSeconds = Number(argv[++index])
+    else if (arg === '--health-path') args.healthPath = argv[++index]
+    else if (arg === '--help' || arg === '-h') args.help = true
+    else args.unknown = arg
+  }
+  args.buildRegion ??= args.region
+  return args
+}
+
+const USAGE = `watch-candidate-delivery --rc-tag <vX.Y.Z-rc.N> --sha <40-hex-sha> --service <name> --region <region> [options]
+
+Observe one RC-triggered candidate delivery. The immutable release identity is the exact RC tag
+plus selected SHA. Build receipts are matched locally when their identity fields are readable;
+an exactly SHA-keyed Cloud Run candidate at 0%, Ready, and health-attested is authoritative even
+when build substitutions are absent.
+
+Options:
+  --build-region <region>       Cloud Build region; defaults to --region
+  --interval-seconds <n>        Poll interval; default 30
+  --max-minutes <n>             Absolute watch bound; default 30, hard maximum 60
+  --read-timeout-seconds <n>    Per-provider-read timeout; default 30
+  --health-path <path>          Candidate identity health path; default /health
+
+States: not-triggered, building, ready-at-0, failed, timed-out, ambiguous.
+
+Output:
+  stdout  exactly one terminal JSON verdict
+  stderr  one NDJSON heartbeat per poll, including the terminal poll
+
+Exit codes: 0 ready-at-0; 4 failed, timed-out, or ambiguous; 2 usage error.
+
+The watcher observes only. It never creates or moves a tag, changes traffic, writes release
+state, closes an attempt lease, deploys, deletes, retries, or invokes a mutating provider API.`
+
+function validateArgs(args) {
+  if (args.help) return null
+  if (args.unknown) return `unknown option: ${args.unknown}`
+  if (!RC_TAG_RE.test(args.rcTag ?? '')) return 'RC tag must match vX.Y.Z-rc.N'
+  if (!FULL_SHA_RE.test(args.selectedSha ?? '')) return 'selected SHA must be 40 hexadecimal characters'
+  for (const field of ['service', 'region', 'buildRegion', 'healthPath']) {
+    if (!nonEmpty(args[field])) return `${field} is required`
+  }
+  for (const field of ['intervalSeconds', 'maxMinutes', 'readTimeoutSeconds']) {
+    if (!Number.isFinite(args[field]) || args[field] <= 0) return `${field} must be a positive number`
+  }
+  if (args.maxMinutes > MAX_MINUTES_CEILING) {
+    return `maxMinutes exceeds the ${MAX_MINUTES_CEILING}-minute hard ceiling`
+  }
+  return null
+}
+
+function heartbeat(payload) {
+  return JSON.stringify({ ...payload, progress: true, terminal: false, at: new Date().toISOString() })
+}
+
+export async function runCli(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    console.log(USAGE)
+    return 0
+  }
+  const invalid = validateArgs(args)
+  if (invalid) {
+    console.error(`watch-candidate-delivery: ${invalid}\n\n${USAGE}`)
+    return 2
+  }
+
+  const releaseIdentity = { rcTag: args.rcTag, selectedSha: args.selectedSha.toLowerCase() }
+  const startedMs = Date.now()
+  const deadlineMs = startedMs + args.maxMinutes * 60_000
+  const configuredReadTimeoutMs = args.readTimeoutSeconds * 1000
+  let observations = 0
+  let lastPayload = null
+
+  for (;;) {
+    const remainingBeforePollMs = deadlineMs - Date.now()
+    if (lastPayload && remainingBeforePollMs < 1_000) {
+      console.log(JSON.stringify({
+        ...lastPayload,
+        state: 'timed-out',
+        outcome: 'timed-out',
+        terminal: true,
+        reason: 'max-minutes',
+        elapsedMs: Date.now() - startedMs,
+      }, null, 2))
+      return 4
+    }
+    observations += 1
+    // A poll makes at most four external reads. Giving each only its share of the
+    // remaining watch time keeps a hung child inside the absolute ceiling.
+    let readsRemaining = 4
+    const readTimeoutMs = () => Math.max(1, Math.min(
+      configuredReadTimeoutMs,
+      Math.floor(Math.max(1, deadlineMs - Date.now()) / readsRemaining--),
+    ))
+    const buildRead = runRead('gcloud', [
+      'builds', 'list', '--region', args.buildRegion,
+      '--sort-by=~createTime', '--limit=50', '--format=json',
+    ], readTimeoutMs())
+    const build = buildRead.readable
+      ? inspectBuilds(buildRead.value, releaseIdentity)
+      : { readable: false, matchingReceipts: 0, receipt: null, error: buildRead.error }
+
+    const serviceRead = runRead('gcloud', [
+      'run', 'services', 'describe', args.service,
+      '--region', args.region, '--format=json',
+    ], readTimeoutMs())
+
+    let revisionRead = null
+    let healthRead = null
+    if (serviceRead.readable) {
+      const traffic = parseTraffic(JSON.stringify(serviceRead.value))
+      const locate = traffic.error ? null : evaluateLocate({ sha: releaseIdentity.selectedSha, traffic })
+      const located = locate?.decision === 'accept' ? locate.evidence.candidate : null
+      if (located) {
+        revisionRead = runRead('gcloud', [
+          'run', 'revisions', 'describe', located.revision,
+          '--region', args.region, '--format=json',
+        ], readTimeoutMs())
+        if (revisionRead.readable && readyCondition(revisionRead.value).status === 'True') {
+          healthRead = runRead('curl', [
+            '--fail', '--silent', '--show-error',
+            '--max-time', String(args.readTimeoutSeconds),
+            healthUrl(located.url, args.healthPath),
+          ], readTimeoutMs())
+        }
+      }
+    }
+
+    const candidate = observeCandidate({
+      serviceRead,
+      revisionRead,
+      healthRead,
+      selectedSha: releaseIdentity.selectedSha,
+    })
+    const classified = classifyPoll({ build, candidate })
+    const elapsedMs = Date.now() - startedMs
+    const deadlineInconclusive = new Set([
+      'service-unreadable',
+      'candidate-revision-unreadable',
+      'candidate-health-unreadable',
+      'build-and-candidate-inconclusive',
+    ])
+    const effective = Date.now() >= deadlineMs &&
+      (!classified.terminal || deadlineInconclusive.has(classified.reason))
+      ? { ...classified, state: 'timed-out', terminal: true, reason: 'max-minutes' }
+      : classified
+    const payload = {
+      state: effective.state,
+      releaseIdentity,
+      reason: effective.reason,
+      observations,
+      elapsedMs,
+      build,
+      candidate: effective.candidate,
+    }
+    lastPayload = payload
+    console.error(heartbeat(payload))
+
+    if (effective.terminal) {
+      console.log(JSON.stringify({ ...payload, outcome: effective.state, terminal: true }, null, 2))
+      return effective.state === 'ready-at-0' ? 0 : 4
+    }
+    const remainingMs = deadlineMs - Date.now()
+    if (remainingMs > 0) await sleep(Math.min(args.intervalSeconds * 1000, remainingMs))
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  runCli(process.argv.slice(2)).then((code) => { process.exitCode = code })
+}

package/skills/engineering/resolve-release/vendor/ACORN-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2012-2022 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/skills/engineering/resolve-release/vendor/README.md

@@ -0,0 +1,60 @@
+# Vendored adapter dependencies
+
+Installed `resolve-release` skills have no package-install step, so the checked adapter
+loader ships exact reviewed distribution artifacts instead of resolving mutable runtime
+packages.
+
+## Acorn
+
+`acorn.mjs` is the dependency-free ESM distribution artifact from Acorn 8.15.0.
+
+- Source package: `acorn@8.15.0`
+- Registry integrity: `sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==`
+- `acorn.mjs` SHA-256: `b4c8c70200e72bae33cf1085e0ecb1e792c1b6924ed50cab817caf14f51bb249`
+- License: MIT, retained in `ACORN-LICENSE`
+
+## QuickJS-WASM
+
+The isolated evaluator ships the minimal release-sync package graph at version 0.32.0:
+
+| Package | Registry integrity | Shipped directory |
+|---|---|---|
+| `quickjs-emscripten-core@0.32.0` | `sha512-QFnPfjFey8EqknSrSxe1hZrf1/8z7/6s1QzGOmKo6++02r7QRRX7ZoyNaZh7JuVjWsVW87KnQrbZqnHkOAzUyg==` | `quickjs/core` |
+| `@jitl/quickjs-wasmfile-release-sync@0.32.0` | `sha512-BKNDI/TPBfGlLNGYpLrhcDGXmIk4xHm4MRAisOBnOzpXVn9HZWsfmMAc9WMBrAHjvvds6HOikKeaOBKdPdpVrg==` | `quickjs/release-sync` |
+| `@jitl/quickjs-ffi-types@0.32.0` | `sha512-v9T+GQpmk43VDJ7d72sf0Nexhk+ArvtUihW27dy7lqAl0zBObFKtSBBIm5RBjwIhE8VwsPPm9PNuvPvNqLWUEg==` | `quickjs/ffi-types` |
+
+Registry tarball SHA-512 values, in the same order, are:
+
+- `4059cf7e315ecbc12a9274ab4b17b5859adfd7ff33effeacd50cc63a62a8ebefb4dabed04515fb668c8d69987b26e5635ac556f3b2a742b6d9aa71e4380cd4ca`
+- `04a34323f4cf05f1a52cd198a4bae1703197988938c479b8311022b0e0673b3a57567f47656b1f98c01cf56301ac01e3bef76ce873a290a79a38129d3dda55ae`
+- `bfd4fe190a66938dd50c9eddef6b1fd0d7b1864f80aefb548a15b6eddcbb96a025d3304e6c52ad4810489b94418f022113c570b0f3e6f4f36ebcfbcda8b59412`
+
+The package distributions are retained intact except for three transparent ESM resolution
+rewrites required by the package-manager-free skill layout:
+
+- `core/dist/index.mjs`: `@jitl/quickjs-ffi-types` -> `../../ffi-types/dist/index.mjs`
+- `core/dist/chunk-V2S4ZYJR.mjs`: `@jitl/quickjs-ffi-types` -> `../../ffi-types/dist/index.mjs`
+- `release-sync/dist/index.mjs`: package export -> `./emscripten-module.mjs`
+
+Post-rewrite SHA-256 values:
+
+- `core/dist/index.mjs`: `6fd846a7804a3835825dc385f7ac5969a4ec1421cbefc7c007c3c4d3d1ec217e`
+- `core/dist/chunk-V2S4ZYJR.mjs`: `29b79919fd8e49ae690c7f31671d0921b800f8d5cf5623784a96ec9fe5103a6b`
+- `release-sync/dist/index.mjs`: `b01acd6fcc4af5c841f961f76f5ca8fec1b1778b42c7d257b7903fd2fe466f23`
+- `release-sync/dist/emscripten-module.wasm`: `105c3bed22d457e43e3d1c3c1c6959fda62a8fe06f0fc8a985303c3a2be72232`
+
+Licenses are retained with each package. The core/FFI MIT license SHA-256 is
+`3c6040aa318612a234cc951609b640c0c63d85ae5a98a9330d3116f1553a79db`; the
+release-sync notice, which includes both quickjs-emscripten MIT and upstream QuickJS MIT,
+is `446a69ae534aa8612d8b16d3bfc670c5a5050597dca3ce9820441a60d5d04fbb`.
+
+The release-sync wrapper reads only its adjacent pinned WASM artifact during module
+initialization. Adapter bytes run in a fresh QuickJS runtime/heap with no module loader,
+no guest-callable host function, and no Node/Bun/Deno, filesystem, environment, stdio,
+network, timer, crypto, URL, messaging, or WebAssembly global. The host/guest boundary is
+JSON text plus validated plain metadata/results and deferred bounded file intents.
+
+The runtime is bounded to 32 MiB heap, 256 KiB stack, 250 ms execution, 1,024 pending
+jobs, 256 KiB request/config payloads, 1 MiB results/files, 32 configured files, depth 32,
+and 10,000 serialized nodes. Every context, handle, and runtime is disposed after
+inspection or execution.