code-foundry 1.10.1 → 1.12.0

package/src/commands/cloudflare-delivery.mjs

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import {
+  bindingPolicy,
+  deploymentVersions,
+  digestBuild,
+  httpsUrl,
+  inspectBindings,
+  parseArgv,
+  parseUpload,
+  pinnedWrangler,
+  validateRollback,
+  versionId,
+} from '../lib/cloudflare-delivery.mjs'
+
+/** @param {NodeJS.ProcessEnv} env @param {string} key */
+function required(env, key) {
+  const value = env[key]
+  if (!value || /[\r\n\0]/.test(value)) throw new Error(`Missing or invalid ${key}`)
+  return value
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {string} name @param {unknown} value */
+function output(env, name, value) {
+  const text = String(value)
+  if (/[\r\n\0]/.test(text)) throw new Error(`Invalid output ${name}`)
+  if (env.GITHUB_OUTPUT) appendFileSync(env.GITHUB_OUTPUT, `${name}=${text}\n`)
+}
+
+/** @param {string} url @param {string} token @param {unknown} [body] @param {typeof fetch} [request] */
+export async function requestJson(url, token, body, request = fetch) {
+  const response = await request(url, {
+    method: body === undefined ? 'GET' : 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'User-Agent': 'code-foundry',
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(30000),
+    redirect: 'error',
+  })
+  if (!response.ok) throw new Error(`Deployment API request failed (${response.status})`)
+  const json = /** @type {any} */ (await response.json())
+  if (json.success === false) throw new Error('Cloudflare rejected the deployment API request')
+  return json
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {string} suffix @param {unknown} [body] */
+async function cloudflare(env, suffix, body) {
+  const account = encodeURIComponent(required(env, 'CLOUDFLARE_ACCOUNT_ID'))
+  const worker = encodeURIComponent(required(env, 'FOUNDRY_WORKER'))
+  const response = await requestJson(
+    `https://api.cloudflare.com/client/v4/accounts/${account}/workers/scripts/${worker}/${suffix}`,
+    required(env, 'CLOUDFLARE_API_TOKEN'),
+    body
+  )
+  if (response.success !== true || !Object.hasOwn(response, 'result'))
+    throw new Error('Invalid Cloudflare API envelope')
+  return response.result
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {string} suffix @param {unknown} [body] */
+async function github(env, suffix, body) {
+  const repository = required(env, 'GITHUB_REPOSITORY')
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repository)) throw new Error('Invalid GitHub repository')
+  return requestJson(
+    `https://api.github.com/repos/${repository}/${suffix}`,
+    required(env, 'GH_TOKEN'),
+    body
+  )
+}
+
+/** @param {any} result */
+export function latestDeployment(result) {
+  if (!Array.isArray(result?.deployments)) throw new Error('Invalid deployments response')
+  if (!result.deployments.length) return null
+  const deployments = [...result.deployments]
+  if (deployments.some((item) => !Number.isFinite(Date.parse(item.created_on))))
+    throw new Error('Deployment timestamp is missing')
+  // Sorting this copy leaves API input untouched.
+  // oxlint-disable-next-line unicorn/no-array-sort
+  deployments.sort((a, b) => Date.parse(b.created_on) - Date.parse(a.created_on))
+  return deployments[0]
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {any} state */
+async function assertCurrent(env, state) {
+  const branch = required(env, 'FOUNDRY_DEFAULT_BRANCH')
+  if (env.GITHUB_REF !== `refs/heads/${branch}`)
+    throw new Error('Production delivery requires the default branch')
+  const latest = await github(env, `git/ref/heads/${encodeURIComponent(branch)}`)
+  if (latest?.object?.sha !== state.sourceSha)
+    throw new Error('A newer source commit exists; refusing stale deployment')
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {any} state @param {number} percentage */
+async function activate(env, state, percentage) {
+  if (state.candidateVerified !== true || !state.bindingInspection)
+    throw new Error('Candidate verification is required before promotion')
+  const version = await cloudflare(env, `versions/${versionId(state.versionId)}`)
+  if (version.id !== state.versionId) throw new Error('Candidate version identity changed')
+  state.bindingInspection = inspectBindings(
+    version,
+    bindingPolicy(process.cwd(), env.BINDING_POLICY_FILE ?? ''),
+    'production'
+  )
+  const current = latestDeployment(await cloudflare(env, 'deployments'))
+  if (!Object.hasOwn(state, 'previous')) state.previous = current?.versions ?? []
+  else if (state.cloudflareDeploymentId && current?.id !== state.cloudflareDeploymentId)
+    throw new Error('Another deployment replaced this rollout; refusing to overwrite it')
+  const versions = deploymentVersions(state.versionId, percentage, state.previous)
+  const result = await cloudflare(env, 'deployments', {
+    strategy: 'percentage',
+    versions,
+    annotations: { 'workers/message': `Code Foundry ${state.sourceSha} (${percentage}%)` },
+  })
+  state.cloudflareDeploymentId = versionId(result.id, 'deployment ID')
+  state.percentage = percentage
+  output(env, 'cloudflare-deployment-id', state.cloudflareDeploymentId)
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {any} state */
+async function rollback(env, state) {
+  if (env.AUTO_ROLLBACK !== 'true')
+    throw new Error(
+      'Automatic rollback is disabled; use the recorded prior versions for manual recovery'
+    )
+  if (state.bindingInspection?.rollbackSafe !== true)
+    throw new Error('Automatic rollback is restricted to stateless Workers')
+  if (!state.cloudflareDeploymentId) throw new Error('This run has not activated a deployment')
+  const current = latestDeployment(await cloudflare(env, 'deployments'))
+  if (current?.id !== state.cloudflareDeploymentId)
+    throw new Error('Current deployment changed; refusing to roll back another rollout')
+  const versions = validateRollback(state.previous)
+  for (const previous of versions) {
+    const version = await cloudflare(env, `versions/${previous.version_id}`)
+    const inspection = inspectBindings(
+      version,
+      bindingPolicy(process.cwd(), env.BINDING_POLICY_FILE ?? ''),
+      'production'
+    )
+    if (!inspection.stateless)
+      throw new Error('The previous version is stateful; automatic rollback is unsafe')
+  }
+  const result = await cloudflare(env, 'deployments', {
+    strategy: 'percentage',
+    versions,
+    annotations: {
+      'workers/message': `Code Foundry rollback after failed verification of ${state.sourceSha}`,
+    },
+  })
+  state.rollbackDeploymentId = versionId(result.id, 'rollback deployment ID')
+  state.rolledBack = true
+}
+
+/** @param {NodeJS.ProcessEnv} env @param {any} state */
+async function verify(env, state) {
+  if (!Array.isArray(state.bindingInspection?.bindings))
+    throw new Error('Binding inspection is required before verification')
+  const phase = env.FOUNDRY_PHASE ?? 'candidate'
+  if (!['candidate', 'canary', 'production'].includes(phase))
+    throw new Error('Invalid verification phase')
+  const url = httpsUrl(phase === 'candidate' ? state.url : required(env, 'PRODUCTION_URL'))
+  const argv = parseArgv(required(env, 'VERIFY_COMMAND'), 'verify-command')
+  const smokePath = env.SMOKE_PATH ?? '/'
+  if (!smokePath.startsWith('/') || smokePath.startsWith('//'))
+    throw new Error('smoke-path must be an origin-relative path')
+  const target = new URL(smokePath, url)
+  if (target.origin !== new URL(url).origin)
+    throw new Error('smoke-path must remain on the deployment origin')
+  let healthy = false
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const response = await fetch(target, {
+        redirect: 'manual',
+        signal: AbortSignal.timeout(10000),
+      })
+      await response.body?.cancel()
+      healthy = response.ok
+    } catch {
+      healthy = false
+    }
+    if (healthy) break
+    if (attempt < 2) await new Promise((done) => setTimeout(done, 2000))
+  }
+  if (!healthy) throw new Error(`${phase} HTTP smoke check failed`)
+  /** @type {NodeJS.ProcessEnv} */
+  const childEnv = {
+    ...env,
+    BASE_URL: url,
+    FOUNDRY_DEPLOYMENT_PHASE: phase,
+    FOUNDRY_EXPECTED_VERSION_ID: state.versionId,
+    FOUNDRY_DEPLOYMENT_ID: state.cloudflareDeploymentId ?? '',
+    FOUNDRY_CANARY_PERCENTAGE: phase === 'canary' ? String(state.percentage ?? '') : '',
+  }
+  delete childEnv.CLOUDFLARE_API_TOKEN
+  delete childEnv.GH_TOKEN
+  delete childEnv.GITHUB_TOKEN
+  const result = spawnSync(argv[0], argv.slice(1), {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    env: childEnv,
+    timeout: 600000,
+  })
+  if (result.error) throw result.error
+  if (result.status !== 0)
+    throw new Error(`${phase} verification command failed (${result.status ?? result.signal})`)
+  state.verifications ??= []
+  state.verifications.push({ phase, status: 'passed', completedAt: new Date().toISOString() })
+  if (phase === 'candidate') {
+    state.candidateVerified = true
+    output(env, 'verified', 'true')
+  }
+}
+
+/** @param {string} command @param {NodeJS.ProcessEnv} [env] */
+export async function deliveryCommand(command, env = process.env) {
+  const file = required(env, 'FOUNDRY_STATE_FILE')
+  /** @type {any} */
+  const state = existsSync(file)
+    ? JSON.parse(readFileSync(file, 'utf8'))
+    : {
+        schemaVersion: 1,
+        kind: 'code-foundry-cloudflare-delivery',
+        sourceSha: required(env, 'GITHUB_SHA'),
+        worker: required(env, 'FOUNDRY_WORKER'),
+      }
+  if (
+    !/^[0-9a-f]{40}$/i.test(state.sourceSha) ||
+    state.sourceSha !== env.GITHUB_SHA ||
+    state.worker !== env.FOUNDRY_WORKER
+  )
+    throw new Error('Delivery state does not match the checked-out source and Worker')
+  try {
+    if (command === 'init-production') {
+      if (env.CANDIDATE_VERIFIED !== 'true')
+        throw new Error('Upstream candidate verification did not pass')
+      if (env.CANDIDATE_SOURCE_SHA !== state.sourceSha)
+        throw new Error('Candidate source SHA mismatch')
+      state.versionId = versionId(env.CANDIDATE_VERSION_ID)
+      state.url = httpsUrl(required(env, 'CANDIDATE_URL'))
+      state.artifactDigest = required(env, 'CANDIDATE_ARTIFACT_DIGEST')
+      if (!/^sha256:[0-9a-f]{64}$/.test(state.artifactDigest))
+        throw new Error('Invalid build artifact digest')
+      state.candidateVerified = true
+      state.bindingInspection = {}
+    } else if (command === 'upload') {
+      if (!['preview', 'production'].includes(env.FOUNDRY_MODE ?? ''))
+        throw new Error('Unsupported delivery mode')
+      const event = env.GITHUB_EVENT_NAME
+      if (event === 'pull_request_target')
+        throw new Error('Privileged pull_request_target execution is not supported')
+      state.artifactDigest = digestBuild(process.cwd(), required(env, 'ARTIFACT_PATH'))
+      const outputFile = `${file}.wrangler.ndjson`
+      writeFileSync(outputFile, '')
+      const argv = pinnedWrangler(env.WRANGLER_VERSION ?? 'local')
+      argv.push('versions', 'upload', '--message', `Code Foundry ${state.sourceSha}`)
+      if (env.WRANGLER_ENVIRONMENT) argv.push('--env', env.WRANGLER_ENVIRONMENT)
+      if (env.WRANGLER_CONFIG) argv.push('--config', env.WRANGLER_CONFIG)
+      const result = spawnSync(argv[0], argv.slice(1), {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        env: {
+          ...env,
+          WRANGLER_OUTPUT_FILE_PATH: outputFile,
+          WRANGLER_SEND_METRICS: 'false',
+          NO_COLOR: '1',
+        },
+      })
+      if (result.error) throw result.error
+      if (result.status !== 0)
+        throw new Error(`Wrangler upload failed (${result.status ?? result.signal})`)
+      if (digestBuild(process.cwd(), required(env, 'ARTIFACT_PATH')) !== state.artifactDigest)
+        throw new Error('Build artifacts changed during upload; disable duplicate custom builds')
+      Object.assign(state, parseUpload(readFileSync(outputFile, 'utf8'), state.worker))
+      output(env, 'url', state.url)
+      output(env, 'version-id', state.versionId)
+      output(env, 'artifact-digest', state.artifactDigest)
+      output(env, 'source-sha', state.sourceSha)
+    } else if (command === 'inspect') {
+      const version = await cloudflare(env, `versions/${versionId(state.versionId)}`)
+      if (version.id !== state.versionId) throw new Error('Version API identity mismatch')
+      const mode = env.FOUNDRY_MODE === 'production' ? 'production' : 'preview'
+      state.bindingInspection = inspectBindings(
+        version,
+        bindingPolicy(process.cwd(), env.BINDING_POLICY_FILE ?? ''),
+        mode
+      )
+    } else if (command === 'verify') await verify(env, state)
+    else if (command === 'assert-current') await assertCurrent(env, state)
+    else if (command === 'activate')
+      await activate(env, state, Number(env.DEPLOY_PERCENTAGE ?? '100'))
+    else if (command === 'rollback') await rollback(env, state)
+    else if (command === 'record-start') {
+      const production = env.FOUNDRY_PHASE === 'production'
+      const deployment = await github(env, 'deployments', {
+        ref: state.sourceSha,
+        environment: required(env, 'DEPLOYMENT_ENVIRONMENT'),
+        auto_merge: false,
+        required_contexts: [],
+        production_environment: production,
+        transient_environment: !production,
+        task: 'code-foundry-delivery',
+      })
+      if (!Number.isSafeInteger(deployment.id)) throw new Error('GitHub returned no deployment ID')
+      state.githubDeploymentId = deployment.id
+      output(env, 'github-deployment-id', deployment.id)
+      await github(env, `deployments/${deployment.id}/statuses`, {
+        state: 'in_progress',
+        auto_inactive: false,
+      })
+    } else if (command === 'record-finish') {
+      if (!state.githubDeploymentId) return
+      const status = env.DEPLOYMENT_STATUS === 'success' ? 'success' : 'failure'
+      state.status = status
+      await github(env, `deployments/${state.githubDeploymentId}/statuses`, {
+        state: status,
+        auto_inactive: false,
+        environment_url:
+          env.FOUNDRY_PHASE === 'production'
+            ? httpsUrl(required(env, 'PRODUCTION_URL'))
+            : (state.url ?? ''),
+        description: state.rolledBack
+          ? 'Verification failed; stateless rollback completed'
+          : `Code Foundry delivery ${status}`,
+      })
+    } else throw new Error(`Unknown Cloudflare delivery command: ${command}`)
+  } catch (error) {
+    state.lastError = error instanceof Error ? error.message : String(error)
+    throw error
+  } finally {
+    state.updatedAt = new Date().toISOString()
+    writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`)
+  }
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) {
+  try {
+    await deliveryCommand(process.argv[2])
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}

package/src/commands/sync.mjs

@@ -1288,7 +1288,11 @@ function createDefaultConfig(root, source, configuredWorkflow) {
     prune_standard: 'false',
     cache_packages: 'auto',
     cache_build: 'auto',
+    required_capabilities: '',
+    coverage_enforcement: 'auto',
     coverage_minimum: '80',
+    coverage_metrics: 'lines',
+    coverage_report: '',
     turbo_remote: 'auto',
     release_type: detectPackageManager(root) === 'none' ? 'auto' : 'node',
     npm_publish: 'false',

package/src/lib/cloudflare-delivery.mjs

@@ -0,0 +1,233 @@
+// @ts-check
+
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs'
+import { relative, resolve, sep } from 'node:path'
+
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** @param {unknown} value @param {string} label */
+export function versionId(value, label = 'version ID') {
+  if (typeof value !== 'string' || !uuid.test(value)) throw new Error(`Invalid ${label}`)
+  return value
+}
+
+/** @param {string} value */
+export function httpsUrl(value) {
+  const url = new URL(value)
+  if (url.protocol !== 'https:' || url.username || url.password || url.hash)
+    throw new Error('Deployment URLs must be HTTPS without credentials or fragments')
+  return url.href
+}
+
+/** @param {string} content @param {string} worker */
+export function parseUpload(content, worker) {
+  const entries = content
+    .split(/\r?\n/)
+    .filter((line) => line.trim())
+    .map((line) => JSON.parse(line))
+  if (entries.some((entry) => entry.type === 'command-failed'))
+    throw new Error('Wrangler reported command-failed')
+  const uploads = entries.filter((entry) => entry.type === 'version-upload')
+  if (uploads.length !== 1) throw new Error('Expected exactly one structured version-upload record')
+  const upload = uploads[0]
+  if (upload.version !== 1 || upload.worker_name !== worker)
+    throw new Error('Unsupported Wrangler output schema or unexpected Worker name')
+  const url = httpsUrl(upload.preview_url)
+  if (!new URL(url).hostname.endsWith('.workers.dev'))
+    throw new Error('Expected a Workers version preview URL')
+  return { worker, versionId: versionId(upload.version_id), url }
+}
+
+/** @param {string} value */
+export function pinnedWrangler(value) {
+  if (value === 'local') return ['bunx', '--bun', '--no-install', 'wrangler']
+  if (!/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(value))
+    throw new Error('wrangler-version must be local or an exact version, never latest or a range')
+  return ['npx', '--yes', `wrangler@${value}`]
+}
+
+/** @param {string} value @param {string} label */
+export function parseArgv(value, label) {
+  const argv = JSON.parse(value)
+  if (
+    !Array.isArray(argv) ||
+    !argv.length ||
+    argv.some((arg) => typeof arg !== 'string' || !arg.length || arg.includes('\0'))
+  )
+    throw new Error(`${label} must be a non-empty JSON argv array`)
+  return /** @type {string[]} */ (argv)
+}
+
+/** Hash a declared build tree, refusing symlinks rather than following external files.
+ * @param {string} root @param {string} directory
+ */
+export function digestBuild(root, directory) {
+  const base = resolve(root)
+  const target = resolve(base, directory)
+  const location = relative(base, target)
+  if (!location || location === '..' || location.startsWith(`..${sep}`))
+    throw new Error('artifact-path must identify a build subdirectory inside the checkout')
+  let ancestor = base
+  for (const part of location.split(sep)) {
+    ancestor = resolve(ancestor, part)
+    if (lstatSync(ancestor).isSymbolicLink())
+      throw new Error('Build tree must not contain symlinks')
+  }
+  const hash = createHash('sha256')
+  let files = 0
+  /** @param {string} currentDirectory */
+  function visit(currentDirectory) {
+    // Sorting a fresh directory listing does not mutate shared state.
+    // oxlint-disable-next-line unicorn/no-array-sort
+    const entries = readdirSync(currentDirectory).sort()
+    for (const name of entries) {
+      const file = resolve(currentDirectory, name)
+      const stat = lstatSync(file)
+      if (stat.isSymbolicLink()) throw new Error('Build tree must not contain symlinks')
+      if (stat.isDirectory()) visit(file)
+      else if (stat.isFile()) {
+        const content = readFileSync(file)
+        hash
+          .update(`${relative(target, file).split(sep).join('/')}\0${content.length}\0`)
+          .update(content)
+        files += 1
+      } else throw new Error('Build tree contains a non-regular file')
+    }
+  }
+  visit(target)
+  if (!files) throw new Error('Build tree is empty')
+  return `sha256:${hash.digest('hex')}`
+}
+
+/**
+ * Inspect the actual uploaded version, never log binding values or secret material.
+ * Read-only declarations are reviewed test policy, not a sandbox for Worker code.
+ * @param {any} version @param {any} policy @param {'preview'|'production'} mode
+ */
+export function inspectBindings(version, policy, mode) {
+  const bindings = version?.resources?.bindings
+  if (
+    Object.values(version?.resources?.script_runtime?.exports ?? {}).some(
+      (entry) => /** @type {any} */ (entry)?.type === 'durable-object'
+    )
+  )
+    throw new Error(
+      'Durable Object exports require a repository-specific preview and migration workflow'
+    )
+  if (!Array.isArray(bindings)) throw new Error('Version API did not return binding metadata')
+  if (policy.schemaVersion !== 1) throw new Error('Unsupported binding policy schema')
+  if (
+    !Array.isArray(policy.readOnlyBindings ?? []) ||
+    !Array.isArray(policy.isolatedBindings ?? [])
+  )
+    throw new Error('Binding policy lists must be arrays')
+  const safeTypes = new Set([
+    'plain_text',
+    'secret_text',
+    'json',
+    'assets',
+    'version_metadata',
+    'wasm_module',
+    'text_blob',
+    'data_blob',
+  ])
+  let stateless = true
+  /** @type {{name: string, type: string, policy: string}[]} */
+  const result = []
+  for (const binding of bindings) {
+    if (typeof binding.name !== 'string' || typeof binding.type !== 'string')
+      throw new Error('Malformed binding metadata')
+    if (binding.type === 'durable_object_namespace')
+      throw new Error(
+        'Durable Objects require a repository-specific preview and migration workflow'
+      )
+    if (safeTypes.has(binding.type)) {
+      result.push({ name: binding.name, type: binding.type, policy: 'stateless' })
+      continue
+    }
+    stateless = false
+    const isolated = (policy.isolatedBindings ?? []).find(
+      (/** @type {any} */ entry) => entry.name === binding.name && entry.type === binding.type
+    )
+    if (isolated) {
+      if (mode !== 'preview')
+        throw new Error('Isolated preview bindings must never be promoted into production')
+      const expected = isolated.expected ?? {}
+      const production = isolated.production ?? {}
+      const keys = Object.keys(expected)
+      if (
+        !keys.length ||
+        keys.some(
+          (key) =>
+            ['type', 'name'].includes(key) ||
+            typeof expected[key] !== 'string' ||
+            typeof production[key] !== 'string'
+        )
+      )
+        throw new Error('Isolated bindings require expected and production resource identifiers')
+      if (!keys.some((key) => expected[key] !== production[key]))
+        throw new Error('Preview binding reuses production resource identifiers')
+      if (keys.some((key) => binding[key] !== expected[key]))
+        throw new Error(`Isolated resource mismatch for ${binding.name}`)
+      result.push({ name: binding.name, type: binding.type, policy: 'isolated' })
+      continue
+    }
+    const reviewed = (policy.readOnlyBindings ?? []).some(
+      (/** @type {any} */ entry) => entry.name === binding.name && entry.type === binding.type
+    )
+    if (!reviewed) throw new Error(`Unreviewed stateful binding: ${binding.name} (${binding.type})`)
+    result.push({ name: binding.name, type: binding.type, policy: 'reviewed-read-only' })
+  }
+  return { stateless, rollbackSafe: stateless && policy.rollbackSafe === true, bindings: result }
+}
+
+/** @param {string} candidate @param {number} percentage @param {any[]} previous */
+export function deploymentVersions(candidate, percentage, previous = []) {
+  versionId(candidate)
+  if (
+    !Number.isFinite(percentage) ||
+    percentage < 0.01 ||
+    percentage > 100 ||
+    (percentage < 100 && percentage > 99.99)
+  )
+    throw new Error('Canary percentage must be greater than zero and at most 100')
+  if (percentage === 100) return [{ version_id: candidate, percentage: 100 }]
+  if (previous.length !== 1 || previous[0].percentage !== 100)
+    throw new Error('A canary requires exactly one baseline version serving 100%')
+  const baseline = versionId(previous[0].version_id)
+  if (baseline === candidate) throw new Error('Canary and baseline must be different versions')
+  return [
+    { version_id: candidate, percentage },
+    { version_id: baseline, percentage: 100 - percentage },
+  ]
+}
+
+/** @param {any} previous */
+export function validateRollback(previous) {
+  if (!Array.isArray(previous) || previous.length < 1 || previous.length > 2)
+    throw new Error('No valid rollback deployment is available')
+  let total = 0
+  const seen = new Set()
+  for (const entry of previous) {
+    versionId(entry.version_id)
+    if (seen.has(entry.version_id)) throw new Error('Duplicate rollback version')
+    seen.add(entry.version_id)
+    if (!Number.isFinite(entry.percentage) || entry.percentage <= 0 || entry.percentage > 100)
+      throw new Error('Invalid rollback percentage')
+    total += entry.percentage
+  }
+  if (Math.abs(total - 100) > 1e-8) throw new Error('Rollback percentages must total 100')
+  return previous.map((entry) => ({ version_id: entry.version_id, percentage: entry.percentage }))
+}
+
+/** @param {string} root @param {string} file */
+export function bindingPolicy(root, file) {
+  if (!file) return { schemaVersion: 1, readOnlyBindings: [], isolatedBindings: [] }
+  const path = resolve(root, file)
+  const location = relative(resolve(root), path)
+  if (location === '..' || location.startsWith(`..${sep}`))
+    throw new Error('Binding policy escapes checkout')
+  if (!existsSync(path)) throw new Error('Binding policy file is missing')
+  return JSON.parse(readFileSync(path, 'utf8'))
+}