@1aboveio/skills 0.10.0

package/skills/engineering/resolve-release/scripts/revalidate-candidate.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+// One-shot recovery from a stale prod-preview verdict.
+//
+// Between 4a and the traffic shift, the credential can expire and the verdict can age out of
+// the envelope's freshness window. The correct recovery is not to paper over the window or
+// to shift on stale evidence; it is to re-probe the credential, re-run the prod-preview
+// deployment verifier, write a fresh verdict artifact, and run `green-gate.mjs shift` to
+// confirm the fresh evidence is still within the window.
+//
+// This script performs exactly that sequence, fail-closed at each step:
+//   1. credential liveness (reprobe-credentials semantics)
+//   2. verifier command (e.g. smoke.mjs verdict --profile prod-preview --out smoke-verdict.json)
+//   3. load the verdict artifact the verifier wrote
+//   4. run green-gate's shift evaluation against the run manifest
+//
+// Exit 0 means the candidate is re-validated and the shift gate would fire. Exit 1 means hold
+// — credential blocked, verifier did not produce a verdict, or the shift gate holds. Exit 2
+// means usage / unreadable manifest.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { classifyCredential, DEFAULT_CREDENTIAL_COMMAND, sh } from './preflight-probes.mjs'
+import { evaluateShift } from './green-gate.mjs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url))
+
+export function evaluateCredential(command = DEFAULT_CREDENTIAL_COMMAND, timeout = 60_000) {
+  const result = sh(command, timeout)
+  return classifyCredential(result)
+}
+
+function takeValue(argv, i, flagName, args, key) {
+  const val = argv[++i]
+  if (val === undefined || val.startsWith('-')) {
+    if (val !== undefined) i-- // push flag-like token back so it is parsed as a flag/unknown
+    args.missing.push(flagName)
+    return i
+  }
+  args[key] = val
+  return i
+}
+
+function takeNumber(argv, i, flagName, args, key) {
+  const val = argv[++i]
+  if (val === undefined || val.startsWith('-')) {
+    if (val !== undefined) i--
+    args.missing.push(flagName)
+    return i
+  }
+  const n = Number(val)
+  if (!Number.isFinite(n)) {
+    args.missing.push(flagName)
+    return i
+  }
+  args[key] = n
+  return i
+}
+
+function parseArgs(argv) {
+  const args = { credentialTimeoutSeconds: 60, verifierTimeoutSeconds: 300, unknown: [], missing: [] }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--manifest') i = takeValue(argv, i, '--manifest', args, 'manifest')
+    else if (a === '--verifier') i = takeValue(argv, i, '--verifier', args, 'verifier')
+    else if (a === '--verdict') i = takeValue(argv, i, '--verdict', args, 'verdict')
+    else if (a === '--credential-command') i = takeValue(argv, i, '--credential-command', args, 'credentialCommand')
+    else if (a === '--credential-timeout') i = takeNumber(argv, i, '--credential-timeout', args, 'credentialTimeoutSeconds')
+    else if (a === '--verifier-timeout') i = takeNumber(argv, i, '--verifier-timeout', args, 'verifierTimeoutSeconds')
+    else if (a === '--json') args.json = true
+    else if (a === '--help' || a === '-h') args.help = true
+    else if (a !== undefined) args.unknown.push(a)
+  }
+  return args
+}
+
+function help() {
+  return `revalidate-candidate — one-shot recovery from a stale prod-preview verdict.
+
+Usage:
+  revalidate-candidate --manifest <run-manifest.json> --verifier "<command>" --verdict <path>
+
+Options:
+  --manifest <file>             resolve-release run manifest (required)
+  --verifier  <command>         shell command that re-runs the prod-preview deployment verifier
+                                and writes the verdict artifact (required)
+  --verdict <path>              path to the verdict artifact the verifier produces (required)
+  --credential-command <cmd>    credential liveness probe (default: ${DEFAULT_CREDENTIAL_COMMAND})
+  --credential-timeout <sec>    credential probe timeout (default: 60)
+  --verifier-timeout <sec>      verifier timeout (default: 300)
+  --json                        machine-readable summary
+
+Exit codes:
+  0  re-validation passes — fresh ALIVE verdict on the candidate URL, noMutations, in window
+  1  HOLD — credential blocked/unknown, verifier did not produce a verdict, or green-gate shift holds
+  2  usage / unreadable manifest
+
+The verifier command is expected to write the verdict artifact to --verdict. A non-zero
+verifier exit is allowed (e.g. a DEAD/EMPTY smoke verdict still writes the artifact), but if
+the artifact is missing after the command finishes the run is a HOLD.`
+}
+
+function loadManifest(file) {
+  if (!file) return { error: 'usage: --manifest <run-manifest.json> is required' }
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch (e) {
+    return { error: `manifest not readable: ${file} — ${e.message}` }
+  }
+  let manifest
+  try {
+    manifest = JSON.parse(raw)
+  } catch (e) {
+    return { error: `manifest is not valid JSON: ${file} — ${e.message}` }
+  }
+  if (!manifest || typeof manifest !== 'object' || !manifest.envelope) {
+    return { error: `not a resolve-release run manifest (no authorization envelope): ${file}` }
+  }
+  return { manifest }
+}
+
+function loadVerdict(file) {
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+  } catch (e) {
+    return { error: `verdict artifact not readable: ${file} — ${e.message}` }
+  }
+  try {
+    return { verdict: JSON.parse(raw) }
+  } catch (e) {
+    return { error: `verdict artifact is not valid JSON: ${file} — ${e.message}` }
+  }
+}
+
+export function main(argv) {
+  const args = parseArgs(argv)
+  if (args.help) {
+    console.log(help())
+    return 0
+  }
+  if (args.unknown.length > 0) {
+    console.error(`revalidate-candidate: unknown argument(s): ${args.unknown.join(', ')}`)
+    return 2
+  }
+  if (args.missing.length > 0) {
+    console.error(`revalidate-candidate: missing or invalid value for: ${args.missing.join(', ')}`)
+    return 2
+  }
+  if (!args.manifest || !args.verifier || !args.verdict) {
+    console.error('revalidate-candidate: usage: --manifest <file> --verifier <command> --verdict <path>')
+    return 2
+  }
+  if (!Number.isFinite(args.credentialTimeoutSeconds) || args.credentialTimeoutSeconds <= 0) {
+    console.error('revalidate-candidate: --credential-timeout must be a positive number')
+    return 2
+  }
+  if (!Number.isFinite(args.verifierTimeoutSeconds) || args.verifierTimeoutSeconds <= 0) {
+    console.error('revalidate-candidate: --verifier-timeout must be a positive number')
+    return 2
+  }
+
+  const manifestLoad = loadManifest(args.manifest)
+  if (manifestLoad.error) {
+    console.error(`revalidate-candidate: ${manifestLoad.error}`)
+    return 2
+  }
+
+  // 1. Re-probe the credential first.
+  const credential = evaluateCredential(args.credentialCommand || DEFAULT_CREDENTIAL_COMMAND, args.credentialTimeoutSeconds * 1000)
+  if (credential.state !== 'ok') {
+    const output = {
+      credential: { state: credential.state, id: credential.id, detail: credential.detail, remedy: credential.remedy },
+      decision: 'hold',
+      reason: 'credential-not-ok',
+    }
+    if (args.json) {
+      console.log(JSON.stringify(output, null, 2))
+    } else {
+      console.error(`revalidate-candidate: credential ${credential.state}: ${credential.detail}`)
+      if (credential.remedy) console.error(`remedy: ${credential.remedy}`)
+    }
+    return 1
+  }
+
+  // 2. Run the verifier. Remove the requested verdict path first so that any verdict
+  //    loaded afterwards must have been produced by this verifier invocation; a stale
+  //    artifact left from a previous run cannot be mistaken for fresh evidence.
+  try { fs.unlinkSync(args.verdict) } catch (e) { if (e.code !== 'ENOENT') throw e }
+  const verifierResult = sh(args.verifier, args.verifierTimeoutSeconds * 1000)
+
+  // 3. Load the verdict the verifier wrote in this invocation.
+  const verdictLoad = loadVerdict(args.verdict)
+  if (verdictLoad.error) {
+    const output = {
+      credential: { state: credential.state, id: credential.id },
+      decision: 'hold',
+      reason: 'verdict-missing',
+      verifier: { ok: verifierResult.ok, stdout: verifierResult.stdout, stderr: verifierResult.stderr },
+      error: verdictLoad.error,
+    }
+    if (args.json) {
+      console.log(JSON.stringify(output, null, 2))
+    } else {
+      console.error(`revalidate-candidate: ${verdictLoad.error}`)
+      if (!verifierResult.ok) {
+        console.error('verifier output:')
+        if (verifierResult.stdout) console.error(verifierResult.stdout)
+        if (verifierResult.stderr) console.error(verifierResult.stderr)
+      }
+    }
+    return 1
+  }
+
+  // 4. Run the green-gate shift evaluation against the fresh verdict.
+  const shift = evaluateShift(manifestLoad.manifest, verdictLoad.verdict)
+  const output = {
+    credential: { state: credential.state, id: credential.id },
+    decision: shift.decision,
+    phase: shift.phase,
+    failed: shift.failed,
+    evidence: shift.evidence,
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(output, null, 2))
+  } else if (shift.decision === 'fire') {
+    console.log('revalidate-candidate: FIRE — fresh prod-preview verdict, shift gate passes')
+  } else {
+    console.error(`revalidate-candidate: HOLD — ${shift.failed.join(', ')}`)
+  }
+  return shift.decision === 'fire' ? 0 : 1
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2))
+}