@visa/cli 4.1.0-rc.31 → 4.1.0-rc.310

package/dist/managed-runtime/resolve-and-update.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+/** Resolve the server-authorized exact RC, then run one managed convergence transaction. */
+
+import { randomUUID } from 'node:crypto'
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { resolve } from 'node:path'
+import {
+  ManagedRuntimeUpdateError,
+  compareExactRc,
+  readCurrentRelease,
+  resolveManagedUpdateConfig,
+  runManagedRuntimeUpdate,
+} from './update-and-restart.mjs'
+
+const PREFIX = '[managed-runtime-converge]'
+const BOOTSTRAP_RC = '0.0.0-rc.0'
+const EXACT_RC_RE = /^\d+\.\d+\.\d+-rc\.\d+$/
+const DEFAULT_DISCOVERY_TIMEOUT_MS = 5_000
+const MAX_DISCOVERY_TIMEOUT_MS = 60_000
+
+function event(logger, name, fields = {}) {
+  logger.log(`${PREFIX} ${JSON.stringify({ event: name, ...fields })}`)
+}
+
+function positiveInteger(value, fallback, name) {
+  if (value === undefined || value === '') return fallback
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed <= 0 || parsed > MAX_DISCOVERY_TIMEOUT_MS) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_configuration',
+      `${name} must be a positive integer no greater than ${MAX_DISCOVERY_TIMEOUT_MS}`
+    )
+  }
+  return parsed
+}
+
+export function resolveReleaseSourceConfig(env = process.env) {
+  const raw = env.VISA_RUNTIME_RELEASE_SOURCE_URL?.trim() || ''
+  if (!raw) {
+    throw new ManagedRuntimeUpdateError(
+      'release_source_required',
+      'VISA_RUNTIME_RELEASE_SOURCE_URL must name the trusted Visa /v1/status endpoint'
+    )
+  }
+
+  let source
+  try {
+    source = new URL(raw)
+  } catch (error) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_configuration',
+      'VISA_RUNTIME_RELEASE_SOURCE_URL must be an absolute URL',
+      { cause: error }
+    )
+  }
+
+  const expectedEnvironment = env.VISA_RUNTIME_EXPECTED_ENVIRONMENT?.trim() || ''
+  const loopback = source.hostname === '127.0.0.1' || source.hostname === 'localhost'
+  if (
+    source.username ||
+    source.password ||
+    source.search ||
+    source.hash ||
+    (source.protocol !== 'https:' && !(expectedEnvironment === 'development' && loopback))
+  ) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_configuration',
+      'release source must be credential-free HTTPS (loopback HTTP is development-only) with no query or fragment'
+    )
+  }
+
+  return {
+    sourceUrl: source.toString(),
+    timeoutMs: positiveInteger(
+      env.VISA_RUNTIME_RELEASE_DISCOVERY_TIMEOUT_MS,
+      DEFAULT_DISCOVERY_TIMEOUT_MS,
+      'VISA_RUNTIME_RELEASE_DISCOVERY_TIMEOUT_MS'
+    ),
+  }
+}
+
+export async function discoverExactRc(env = process.env, dependencies = {}) {
+  const config = resolveReleaseSourceConfig(env)
+  const fetchImpl = dependencies.fetch ?? globalThis.fetch
+  const logger = dependencies.logger ?? console
+  const correlationId = dependencies.correlationId ?? randomUUID()
+  const currentVersion = dependencies.currentVersion ?? BOOTSTRAP_RC
+  if (!EXACT_RC_RE.test(currentVersion)) {
+    throw new ManagedRuntimeUpdateError(
+      'invalid_runtime_state',
+      'current managed runtime version must be an exact RC'
+    )
+  }
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), config.timeoutMs)
+  timer.unref?.()
+  const startedAt = Date.now()
+  event(logger, 'external_request', {
+    correlationId,
+    service: 'visa_release_authority',
+    operation: 'discover_exact_rc',
+    currentVersion,
+  })
+
+  try {
+    const response = await fetchImpl(config.sourceUrl, {
+      method: 'GET',
+      redirect: 'error',
+      signal: controller.signal,
+      headers: {
+        Accept: 'application/json',
+        'User-Agent': 'visa-managed-runtime-converge',
+        'X-Visa-CLI-Version': currentVersion,
+      },
+    })
+    const targetVersion = response.headers.get('x-latest-version')?.trim() || ''
+    const acceptedStatus = response.status === 200 || response.status === 401
+    await response.body?.cancel?.()
+    event(logger, 'external_response', {
+      correlationId,
+      service: 'visa_release_authority',
+      operation: 'discover_exact_rc',
+      ok: acceptedStatus && EXACT_RC_RE.test(targetVersion),
+      status: response.status,
+      durationMs: Date.now() - startedAt,
+    })
+    if (!acceptedStatus || !EXACT_RC_RE.test(targetVersion)) {
+      throw new ManagedRuntimeUpdateError(
+        'target_not_authorized',
+        'Visa release authority did not advertise an exact RC'
+      )
+    }
+    return { correlationId, targetVersion }
+  } catch (error) {
+    if (error instanceof ManagedRuntimeUpdateError) throw error
+    event(logger, 'external_response', {
+      correlationId,
+      service: 'visa_release_authority',
+      operation: 'discover_exact_rc',
+      ok: false,
+      status: null,
+      durationMs: Date.now() - startedAt,
+    })
+    throw new ManagedRuntimeUpdateError(
+      'release_source_unavailable',
+      'Visa release authority could not be reached',
+      { cause: error }
+    )
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Read the known-good release, tolerating the receipt-less `current` pointer an
+ * activation interrupted between `activateRelease()` and `writeReceipt()` leaves behind.
+ * `runManagedRuntimeUpdate` repairs exactly that state with `recoverInterruptedActivation()`
+ * under the update lock, so a scheduled convergence must reach the transaction instead of
+ * exiting non-zero on every invocation until a human intervenes.
+ */
+function readKnownGood(config, dependencies, logger, correlationId) {
+  const read = dependencies.readCurrentRelease ?? readCurrentRelease
+  try {
+    return read(config.managedDir)
+  } catch (error) {
+    if (!(error instanceof ManagedRuntimeUpdateError) || error.code !== 'invalid_runtime_state') {
+      throw error
+    }
+    event(logger, 'known_good_unreadable', {
+      correlationId,
+      reason: error.message,
+      repair: 'delegated_to_update_transaction',
+    })
+    return null
+  }
+}
+
+export async function runManagedRuntimeConvergence(env = process.env, dependencies = {}) {
+  const bootstrapConfig = resolveManagedUpdateConfig({
+    ...env,
+    VISA_CLI_EXACT_VERSION: BOOTSTRAP_RC,
+  })
+  const logger = dependencies.logger ?? console
+  const correlationId = dependencies.correlationId ?? randomUUID()
+  const current = readKnownGood(bootstrapConfig, dependencies, logger, correlationId)
+  if (current && current.receipt.targetEnvironment !== bootstrapConfig.expectedEnvironment) {
+    // Distinct from `invalid_runtime_state`: a mismatched environment always needs a human,
+    // where a wedged runtime state is repaired by the update transaction. On-call triages
+    // the two differently, so the exit codes must differ. Matches the updater's own code.
+    throw new ManagedRuntimeUpdateError(
+      'target_environment_mismatch',
+      `known-good runtime targets ${current.receipt.targetEnvironment}, expected ${bootstrapConfig.expectedEnvironment}`
+    )
+  }
+  const currentVersion = current?.receipt.version ?? BOOTSTRAP_RC
+  const discovery = await discoverExactRc(env, {
+    fetch: dependencies.fetch,
+    logger,
+    correlationId,
+    currentVersion,
+  })
+
+  if (current) {
+    const order = compareExactRc(discovery.targetVersion, currentVersion)
+    if (order <= 0) {
+      const status = order === 0 ? 'current' : 'ahead_of_recommendation'
+      event(logger, 'convergence_not_required', {
+        correlationId,
+        status,
+        currentVersion,
+        recommendedVersion: discovery.targetVersion,
+      })
+      return {
+        ok: true,
+        status,
+        correlationId,
+        version: currentVersion,
+        recommendedVersion: discovery.targetVersion,
+        updated: false,
+      }
+    }
+  }
+
+  const result = await (dependencies.runManagedRuntimeUpdate ?? runManagedRuntimeUpdate)(
+    {
+      ...env,
+      VISA_CLI_EXACT_VERSION: discovery.targetVersion,
+    },
+    {
+      ...dependencies.updateDependencies,
+      logger,
+      correlationId,
+    }
+  )
+  return {
+    ...result,
+    status: 'updated',
+    correlationId,
+    recommendedVersion: discovery.targetVersion,
+    updated: true,
+  }
+}
+
+async function main() {
+  try {
+    const result = await runManagedRuntimeConvergence(process.env)
+    process.stdout.write(`${JSON.stringify(result)}\n`)
+  } catch (error) {
+    const code = error instanceof ManagedRuntimeUpdateError ? error.code : 'convergence_failed'
+    process.stderr.write(`${JSON.stringify({ ok: false, code, message: error.message })}\n`)
+    process.exitCode = 1
+  }
+}
+
+function isDirectExecution() {
+  if (!process.argv[1]) return false
+  try {
+    return realpathSync(resolve(process.argv[1])) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return false
+  }
+}
+
+if (isDirectExecution()) {
+  void main()
+}

package/dist/managed-runtime/runtime-readiness.mjs

@@ -0,0 +1,126 @@
+export const DEFAULT_RUNTIME_READINESS_TIMEOUT_MS = 60_000
+const COMMERCE_RUNTIMES = new Set(['openclaw', 'hermes'])
+
+/** Fixed argv only: callers cannot substitute a package, command, or script path. */
+export function commerceSkillArgs(env = process.env, check = false) {
+  const runtime = env.VISA_COMMERCE_RUNTIME || ''
+  if (runtime && !COMMERCE_RUNTIMES.has(runtime)) {
+    throw new Error('VISA_COMMERCE_RUNTIME must be openclaw or hermes')
+  }
+  return [
+    'agent',
+    'skill',
+    '--commerce',
+    ...(runtime ? ['--runtime', runtime] : []),
+    ...(check ? ['--check'] : []),
+    '--format',
+    'json',
+  ]
+}
+
+function isPlainRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function buildFrom(value) {
+  if (!isPlainRecord(value)) return null
+  return value?.data?.build ?? value?.build ?? value
+}
+
+export function parseRuntimeReadiness(raw) {
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('runtime readiness command must emit one JSON document')
+  }
+
+  const build = buildFrom(parsed)
+  if (
+    !isPlainRecord(build) ||
+    typeof build.version !== 'string' ||
+    build.version.trim() === '' ||
+    typeof build.targetEnvironment !== 'string' ||
+    build.targetEnvironment.trim() === ''
+  ) {
+    throw new Error('runtime readiness JSON must include version and targetEnvironment')
+  }
+
+  return {
+    version: build.version,
+    targetEnvironment: build.targetEnvironment,
+    shopifyRuntime: isPlainRecord(build.shopifyRuntime)
+      ? build.shopifyRuntime
+      : isPlainRecord(parsed.shopifyRuntime)
+        ? parsed.shopifyRuntime
+        : null,
+  }
+}
+
+export function assertSameShopifyRuntime(actual, expected) {
+  if (!isPlainRecord(actual)) {
+    throw new Error('loaded runtime readiness must attest the named shopify-ucp MCP')
+  }
+  if (actual.serverName !== 'shopify-ucp') {
+    throw new Error('loaded runtime readiness did not attest the canonical shopify-ucp mount')
+  }
+  for (const field of ['installedVersion', 'toolSchemaFingerprint', 'command']) {
+    if (actual[field] !== expected[field]) {
+      throw new Error(`loaded Shopify UCP ${field} does not match the certified local runtime`)
+    }
+  }
+  if (
+    !Array.isArray(actual.args) ||
+    actual.args.length !== expected.args.length ||
+    !actual.args.every((value, index) => value === expected.args[index])
+  ) {
+    throw new Error('loaded Shopify UCP command arguments do not match the certified local runtime')
+  }
+  if (!Array.isArray(actual.blockedTools) || !actual.blockedTools.includes('checkout_complete')) {
+    throw new Error(
+      'loaded Shopify UCP runtime does not attest the checkout completion deny boundary'
+    )
+  }
+}
+
+export function resolveRuntimeUpdateConfig(env = process.env) {
+  const restartCommand = env.RUNTIME_RESTART_COMMAND || env.OPENCLAW_RESTART_COMMAND || ''
+  const readinessCommand = env.RUNTIME_READINESS_COMMAND || ''
+  if (restartCommand && !readinessCommand) {
+    throw new Error(
+      'RUNTIME_READINESS_COMMAND is required with a restart command so the loaded MCP build is verified'
+    )
+  }
+
+  let readinessTimeoutMs = DEFAULT_RUNTIME_READINESS_TIMEOUT_MS
+  if (env.RUNTIME_READINESS_TIMEOUT_MS !== undefined) {
+    const candidate = Number(env.RUNTIME_READINESS_TIMEOUT_MS)
+    if (!Number.isSafeInteger(candidate) || candidate <= 0) {
+      throw new Error('RUNTIME_READINESS_TIMEOUT_MS must be a positive integer')
+    }
+    readinessTimeoutMs = candidate
+  }
+
+  return { restartCommand, readinessCommand, readinessTimeoutMs }
+}
+
+export function runtimeReadinessExecOptions(timeout) {
+  return {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout,
+  }
+}
+
+export function assertSameRuntimeBuild(actual, expected) {
+  if (actual.version !== expected.version) {
+    throw new Error(
+      `loaded MCP version ${actual.version} does not match installed CLI ${expected.version}`
+    )
+  }
+  if (actual.targetEnvironment !== expected.targetEnvironment) {
+    throw new Error(
+      `loaded MCP environment ${actual.targetEnvironment} does not match installed CLI ${expected.targetEnvironment}`
+    )
+  }
+}