@1aboveio/skills 0.19.2 → 0.20.1

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

@@ -1,449 +0,0 @@
-#!/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

@@ -1,21 +0,0 @@
-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

@@ -1,60 +0,0 @@
-# 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.