@open-mercato/starter 0.6.5

package/src/__tests__/starter.test.mjs

@@ -0,0 +1,359 @@
+import assert from 'node:assert/strict'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { test } from 'node:test'
+
+import { parseComposePsOutput, resolveRepoRoot } from '../compose.mjs'
+import { hostTrustEnv, summarizeProbeResults, writeCaBundle } from '../certs.mjs'
+import { DEFAULT_OPENCODE_BASE_IMAGE, DEFAULT_PORTS, resolveStackPorts } from '../constants.mjs'
+import { addEnvValue, readEnvValue, setEnvValue } from '../env-file.mjs'
+import { ensureLlmProvider, syncProviderConfigToAppEnv } from '../providers.mjs'
+import { ensureWindowsUtf8Console, resolveSpawnCommand } from '../spawn.mjs'
+import { StepBlocked, buildToolchainStep, clearConvergenceState, listMigrationModules, migrationsFingerprint, readAppliedMigrationModules, resolveOpencodeBaseImage, runSteps } from '../steps.mjs'
+import { checkBuildToolchain } from '../doctor.mjs'
+
+function makeTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix))
+}
+
+function makeFakeRepo() {
+  const dir = makeTempDir('om-starter-repo-')
+  fs.mkdirSync(path.join(dir, 'starters', 'docker'), { recursive: true })
+  fs.writeFileSync(path.join(dir, 'starters', 'docker', 'compose.infra.yml'), 'services: {}\n')
+  return dir
+}
+
+test('ensureWindowsUtf8Console switches the console code page only on win32 and never throws', () => {
+  const calls = []
+  const fakeSpawnSync = (command, args) => {
+    calls.push({ command, args })
+    return { status: 0 }
+  }
+
+  assert.equal(ensureWindowsUtf8Console({ platform: 'linux', spawnSyncImpl: fakeSpawnSync }), false)
+  assert.equal(calls.length, 0)
+
+  assert.equal(ensureWindowsUtf8Console({ platform: 'win32', spawnSyncImpl: fakeSpawnSync, systemRoot: 'C:\\Windows' }), true)
+  assert.equal(calls.length, 1)
+  assert.deepEqual(calls[0].args, ['65001'])
+  assert.ok(calls[0].command.endsWith(path.join('System32', 'chcp.com')))
+
+  const throwingSpawnSync = () => {
+    throw new Error('no console attached')
+  }
+  assert.equal(ensureWindowsUtf8Console({ platform: 'win32', spawnSyncImpl: throwingSpawnSync }), false)
+})
+
+test('resolveRepoRoot walks up to the compose marker and returns null outside a repo', () => {
+  const repo = makeFakeRepo()
+  const nested = path.join(repo, 'packages', 'starter', 'src')
+  fs.mkdirSync(nested, { recursive: true })
+  assert.equal(resolveRepoRoot(nested), repo)
+  const outside = makeTempDir('om-starter-outside-')
+  assert.equal(resolveRepoRoot(outside), null)
+})
+
+test('parseComposePsOutput accepts both NDJSON and array formats', () => {
+  const ndjson = '{"Service":"postgres","State":"running"}\n{"Service":"redis","State":"exited"}'
+  assert.equal(parseComposePsOutput(ndjson).length, 2)
+  const array = '[{"Service":"postgres","State":"running"}]'
+  assert.equal(parseComposePsOutput(array)[0].Service, 'postgres')
+  assert.deepEqual(parseComposePsOutput(''), [])
+})
+
+test('addEnvValue is fill-missing-only and replaceEmpty fills bare placeholders', () => {
+  const dir = makeTempDir('om-starter-env-')
+  const envPath = path.join(dir, '.env')
+  fs.writeFileSync(envPath, 'EXISTING=keep\nEMPTY=\n')
+  assert.equal(addEnvValue(envPath, 'EXISTING', 'overwrite'), false)
+  assert.equal(readEnvValue(envPath, 'EXISTING'), 'keep')
+  assert.equal(addEnvValue(envPath, 'EMPTY', 'filled', { replaceEmpty: true }), true)
+  assert.equal(readEnvValue(envPath, 'EMPTY'), 'filled')
+  assert.equal(addEnvValue(envPath, 'NEW', 'value'), true)
+  assert.equal(readEnvValue(envPath, 'NEW'), 'value')
+})
+
+test('setEnvValue overwrites existing lines and appends missing ones', () => {
+  const dir = makeTempDir('om-starter-setenv-')
+  const envPath = path.join(dir, '.env')
+  fs.writeFileSync(envPath, 'OM_AI_PROVIDER=openai\nOTHER=keep\n')
+  assert.equal(setEnvValue(envPath, 'OM_AI_PROVIDER', 'azure'), true)
+  assert.equal(readEnvValue(envPath, 'OM_AI_PROVIDER'), 'azure')
+  assert.equal(readEnvValue(envPath, 'OTHER'), 'keep')
+  assert.equal(setEnvValue(envPath, 'OM_AI_MODEL', 'my-deployment'), true)
+  assert.equal(readEnvValue(envPath, 'OM_AI_MODEL'), 'my-deployment')
+})
+
+test('syncProviderConfigToAppEnv mirrors root AI config into the app env without rotating keys', () => {
+  const dir = makeTempDir('om-starter-llm-sync-')
+  const rootEnv = path.join(dir, '.env')
+  const appEnv = path.join(dir, 'app.env')
+  fs.writeFileSync(rootEnv, 'OM_AI_PROVIDER=azure\nOM_AI_MODEL=my-deployment\nAZURE_OPENAI_API_KEY=root-secret\nAZURE_OPENAI_BASE_URL=https://example.azure.com\n')
+  fs.writeFileSync(appEnv, 'OM_AI_PROVIDER=openai\nOM_AI_MODEL=gpt-5-mini\nAZURE_OPENAI_API_KEY=\nAZURE_OPENAI_BASE_URL=\n')
+
+  syncProviderConfigToAppEnv({ rootEnv, appEnv }, () => {})
+
+  assert.equal(readEnvValue(appEnv, 'OM_AI_PROVIDER'), 'azure')
+  assert.equal(readEnvValue(appEnv, 'OM_AI_MODEL'), 'my-deployment')
+  assert.equal(readEnvValue(appEnv, 'AZURE_OPENAI_API_KEY'), 'root-secret')
+  assert.equal(readEnvValue(appEnv, 'AZURE_OPENAI_BASE_URL'), 'https://example.azure.com')
+
+  fs.writeFileSync(appEnv, 'OM_AI_PROVIDER=azure\nAZURE_OPENAI_API_KEY=manually-rotated\n')
+  syncProviderConfigToAppEnv({ rootEnv, appEnv }, () => {})
+  assert.equal(readEnvValue(appEnv, 'AZURE_OPENAI_API_KEY'), 'manually-rotated')
+
+  syncProviderConfigToAppEnv({ rootEnv, appEnv: path.join(dir, 'missing.env') }, () => {})
+  syncProviderConfigToAppEnv({ rootEnv, appEnv: null }, () => {})
+})
+
+test('ensureLlmProvider syncs the app env when the root env is already configured', async () => {
+  const dir = makeTempDir('om-starter-llm-configured-')
+  const rootEnv = path.join(dir, '.env')
+  const appEnv = path.join(dir, 'app.env')
+  fs.writeFileSync(rootEnv, 'OM_AI_PROVIDER=azure\nOM_AI_MODEL=my-deployment\nAZURE_OPENAI_API_KEY=root-secret\n')
+  fs.writeFileSync(appEnv, 'OM_AI_PROVIDER=openai\nAZURE_OPENAI_API_KEY=\n')
+
+  const outcome = await ensureLlmProvider({ rootEnv, appEnv }, { log: () => {}, warn: () => {} })
+
+  assert.equal(outcome, 'configured')
+  assert.equal(readEnvValue(appEnv, 'OM_AI_PROVIDER'), 'azure')
+  assert.equal(readEnvValue(appEnv, 'OM_AI_MODEL'), 'my-deployment')
+  assert.equal(readEnvValue(appEnv, 'AZURE_OPENAI_API_KEY'), 'root-secret')
+})
+
+test('hostTrustEnv wires CA bundle, system CA flag, and corepack proxy fix', () => {
+  const env = hostTrustEnv('/tmp/bundle.pem', { NODE_OPTIONS: '--max-old-space-size=2048', HTTPS_PROXY: 'http://proxy:8080' })
+  assert.equal(env.NODE_EXTRA_CA_CERTS, '/tmp/bundle.pem')
+  assert.ok(env.NODE_OPTIONS.includes('--use-system-ca'))
+  assert.ok(env.NODE_OPTIONS.includes('--max-old-space-size=2048'))
+  assert.equal(env.NODE_USE_ENV_PROXY, '1')
+  const noProxy = hostTrustEnv(null, {})
+  assert.equal(noProxy.NODE_EXTRA_CA_CERTS, undefined)
+  assert.equal(noProxy.NODE_USE_ENV_PROXY, undefined)
+  assert.ok(noProxy.NODE_OPTIONS.includes('--use-system-ca'))
+})
+
+test('writeCaBundle merges company bundles and captured certs, returns null when empty', () => {
+  const repo = makeFakeRepo()
+  const companyBundle = path.join(repo, 'company-ca.pem')
+  fs.writeFileSync(companyBundle, '-----BEGIN CERTIFICATE-----\nAAA\n-----END CERTIFICATE-----\n')
+  const bundlePath = writeCaBundle(repo, {
+    companyBundles: [companyBundle],
+    capturedPems: [{ fingerprint: 'FP', subject: 'Test Interception CA', pem: '-----BEGIN CERTIFICATE-----\nBBB\n-----END CERTIFICATE-----\n' }],
+  })
+  const content = fs.readFileSync(bundlePath, 'utf8')
+  assert.ok(content.includes('AAA'))
+  assert.ok(content.includes('BBB'))
+  assert.ok(content.includes('Test Interception CA'))
+  assert.equal(writeCaBundle(repo, { companyBundles: [], capturedPems: [] }), null)
+})
+
+test('summarizeProbeResults buckets probe outcomes', () => {
+  const summary = summarizeProbeResults([
+    { host: 'a', status: 'ok' },
+    { host: 'b', status: 'intercepted' },
+    { host: 'c', status: 'unreachable' },
+  ])
+  assert.equal(summary.clean.length, 1)
+  assert.equal(summary.intercepted[0].host, 'b')
+  assert.equal(summary.unreachable[0].host, 'c')
+})
+
+test('resolveStackPorts honors env overrides and falls back to defaults', () => {
+  const repo = makeFakeRepo()
+  const ports = resolveStackPorts(repo, { POSTGRES_PORT: '5433', APP_PORT: 'not-a-number' })
+  assert.equal(ports.postgres, 5433)
+  assert.equal(ports.app, DEFAULT_PORTS.app)
+  assert.equal(ports.mcp, DEFAULT_PORTS.mcp)
+})
+
+test('resolveSpawnCommand leaves real executables and unix platforms shell-free', () => {
+  assert.deepEqual(resolveSpawnCommand('docker', ['compose', 'version'], { platform: 'win32' }), {
+    command: 'docker',
+    args: ['compose', 'version'],
+    spawnOptions: {},
+  })
+  assert.deepEqual(resolveSpawnCommand('yarn', ['install'], { platform: 'linux' }), {
+    command: 'yarn',
+    args: ['install'],
+    spawnOptions: {},
+  })
+})
+
+test('resolveSpawnCommand hands cmd.exe one pre-quoted command line for Windows shims', () => {
+  const plain = resolveSpawnCommand('yarn', ['--version'], { platform: 'win32' })
+  assert.equal(plain.command, 'yarn --version')
+  assert.deepEqual(plain.args, [])
+  assert.equal(plain.spawnOptions.shell, true)
+
+  const quoted = resolveSpawnCommand('corepack', ['prepare', 'yarn@4.12.0', '--activate'], { platform: 'win32' })
+  assert.equal(quoted.command, 'corepack prepare yarn@4.12.0 --activate')
+
+  const spaced = resolveSpawnCommand('yarn.cmd', ['run', 'a b'], { platform: 'win32' })
+  assert.equal(spaced.command, 'yarn.cmd run "a b"')
+})
+
+test('resolveSpawnCommand rejects cmd metacharacters instead of degrading into injection', () => {
+  assert.throws(() => resolveSpawnCommand('yarn', ['%TEMP%'], { platform: 'win32' }))
+  assert.throws(() => resolveSpawnCommand('yarn', ['a&whoami'], { platform: 'win32' }))
+  assert.throws(() => resolveSpawnCommand('npm', ['pkg|rm'], { platform: 'win32' }))
+})
+
+function quietCtx(overrides = {}) {
+  return { log: () => {}, flags: {}, company: { steps: { disable: [], extra: [] } }, ...overrides }
+}
+
+test('runSteps skips satisfied steps, applies unsatisfied ones, and stops on StepBlocked with guidance', async () => {
+  const order = []
+  const steps = [
+    { id: 'done', title: 'Done', async check() { order.push('check:done'); return { ok: true, detail: 'ok' } }, async apply() { order.push('apply:done') } },
+    { id: 'todo', title: 'Todo', async check() { return { ok: false, detail: '' } }, async apply() { order.push('apply:todo') } },
+    { id: 'skipped', title: 'Skipped', appliesTo: () => false, async check() { order.push('check:skipped'); return { ok: false } } },
+  ]
+  const outcome = await runSteps(steps, quietCtx())
+  assert.equal(outcome.ok, true)
+  assert.deepEqual(order, ['check:done', 'apply:todo'])
+
+  const blocked = await runSteps([
+    { id: 'gate', title: 'Gate', async check() { throw new StepBlocked('gate', ['install the thing']) } },
+    { id: 'never', title: 'Never', async check() { order.push('check:never'); return { ok: true } } },
+  ], quietCtx())
+  assert.equal(blocked.ok, false)
+  assert.equal(blocked.blockedStep, 'gate')
+  assert.ok(!order.includes('check:never'))
+})
+
+test('runSteps reports step failures without throwing', async () => {
+  const outcome = await runSteps([
+    { id: 'boom', title: 'Boom', async check() { return { ok: false } }, async apply() { throw new Error('exploded') } },
+  ], quietCtx())
+  assert.equal(outcome.ok, false)
+  assert.equal(outcome.failedStep, 'boom')
+})
+
+test('migrationsFingerprint tracks Migration*.ts files and ignores snapshot dot-files', () => {
+  const repo = makeFakeRepo()
+  const migrationsDir = path.join(repo, 'packages', 'core', 'src', 'modules', 'demo', 'migrations')
+  fs.mkdirSync(migrationsDir, { recursive: true })
+  fs.writeFileSync(path.join(migrationsDir, 'Migration20260101000000.ts'), 'export class M {}\n')
+  const initial = migrationsFingerprint(repo)
+
+  fs.writeFileSync(path.join(migrationsDir, '.snapshot-open-mercato.json'), '{"changed":true}\n')
+  assert.equal(migrationsFingerprint(repo), initial)
+
+  fs.writeFileSync(path.join(migrationsDir, 'Migration20260102000000.ts'), 'export class M2 {}\n')
+  assert.notEqual(migrationsFingerprint(repo), initial)
+
+  const appMigrations = path.join(repo, 'apps', 'mercato', 'src', 'modules', 'local', 'migrations')
+  fs.mkdirSync(appMigrations, { recursive: true })
+  const withApp = migrationsFingerprint(repo)
+  fs.writeFileSync(path.join(appMigrations, 'Migration20260103000000.ts'), 'export class M3 {}\n')
+  assert.notEqual(migrationsFingerprint(repo), withApp)
+})
+
+test('clearConvergenceState removes markers but keeps mode and db-initialized state', () => {
+  const repo = makeFakeRepo()
+  const stateDir = path.join(repo, '.mercato', 'starter')
+  fs.mkdirSync(stateDir, { recursive: true })
+  fs.writeFileSync(path.join(stateDir, 'mode'), 'hybrid\n')
+  fs.writeFileSync(path.join(stateDir, 'install.hash'), 'abc\n')
+  fs.writeFileSync(path.join(stateDir, 'db-initialized-cafe01'), 'when\n')
+  fs.writeFileSync(path.join(stateDir, 'db-migrations-cafe01'), 'hash\n')
+
+  const cleared = clearConvergenceState(repo)
+  assert.deepEqual(cleared.sort(), ['db-migrations-cafe01', 'install.hash'])
+  assert.deepEqual(fs.readdirSync(stateDir).sort(), ['db-initialized-cafe01', 'mode'])
+  assert.deepEqual(clearConvergenceState(path.join(repo, 'nope')), [])
+})
+
+test('listMigrationModules names every module that ships Migration files', () => {
+  const repo = makeFakeRepo()
+  const orchestratorDir = path.join(repo, 'packages', 'enterprise', 'src', 'modules', 'agent_orchestrator', 'migrations')
+  const customersDir = path.join(repo, 'packages', 'core', 'src', 'modules', 'customers', 'migrations')
+  const emptyDir = path.join(repo, 'packages', 'core', 'src', 'modules', 'no_migrations', 'migrations')
+  fs.mkdirSync(orchestratorDir, { recursive: true })
+  fs.mkdirSync(customersDir, { recursive: true })
+  fs.mkdirSync(emptyDir, { recursive: true })
+  fs.writeFileSync(path.join(orchestratorDir, 'Migration20260101000000_agent_orchestrator.ts'), 'x')
+  fs.writeFileSync(path.join(customersDir, 'Migration20260101000000_customers.ts'), 'x')
+  fs.writeFileSync(path.join(emptyDir, '.snapshot-open-mercato.json'), '{}')
+
+  const modules = listMigrationModules(repo)
+  assert.deepEqual([...modules].sort(), ['agent_orchestrator', 'customers'])
+})
+
+test('readAppliedMigrationModules parses psql bookkeeping tables and returns null when the probe fails', () => {
+  const repo = makeFakeRepo()
+  fs.mkdirSync(path.join(repo, 'apps', 'mercato'), { recursive: true })
+  fs.writeFileSync(path.join(repo, 'apps', 'mercato', '.env'), 'DATABASE_URL=postgres://postgres:pw@127.0.0.1:5432/open-mercato\n')
+  const ctx = { repoRoot: repo }
+
+  let seenArgs = null
+  const okCompose = (repoRoot, args) => {
+    seenArgs = args
+    return { status: 0, stdout: 'mikro_orm_migrations_customers\nmikro_orm_migrations_agent_orchestrator\n\n' }
+  }
+  const applied = readAppliedMigrationModules(ctx, { runComposeImpl: okCompose })
+  assert.deepEqual([...applied].sort(), ['agent_orchestrator', 'customers'])
+  assert.ok(seenArgs.includes('open-mercato'))
+
+  assert.equal(readAppliedMigrationModules(ctx, { runComposeImpl: () => ({ status: 1, stdout: '' }) }), null)
+  assert.equal(readAppliedMigrationModules(ctx, { runComposeImpl: () => { throw new Error('compose missing') } }), null)
+})
+
+test('resolveOpencodeBaseImage: env wins, then .env, then the pinned default', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'om-starter-opencode-'))
+  try {
+    assert.equal(
+      resolveOpencodeBaseImage(root, {}),
+      DEFAULT_OPENCODE_BASE_IMAGE,
+    )
+    fs.writeFileSync(path.join(root, '.env'), 'OPENCODE_BASE_IMAGE=registry.corp/opencode-base:1.18.3\n')
+    assert.equal(
+      resolveOpencodeBaseImage(root, {}),
+      'registry.corp/opencode-base:1.18.3',
+    )
+    assert.equal(
+      resolveOpencodeBaseImage(root, { OPENCODE_BASE_IMAGE: 'override/base:2' }),
+      'override/base:2',
+    )
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('checkBuildToolchain is a no-op off Windows and the gate only applies to hybrid+win32', () => {
+  if (process.platform !== 'win32') {
+    assert.equal(checkBuildToolchain(), null)
+  }
+  // The converge gate never runs off Windows, and never in docker mode.
+  assert.equal(buildToolchainStep.appliesTo({ mode: 'hybrid' }), process.platform === 'win32')
+  assert.equal(buildToolchainStep.appliesTo({ mode: 'docker' }), false)
+})
+
+test('buildToolchainStep warns instead of blocking when the workspace install already converged', async () => {
+  const repo = makeFakeRepo()
+  const missingToolchain = () => ({ level: 'fail', guide: ['install VC++'] })
+  const ctx = { repoRoot: repo, log: () => {}, checkBuildToolchainImpl: missingToolchain }
+
+  // No node_modules, no install marker: an install is pending — hard block.
+  await assert.rejects(() => buildToolchainStep.check(ctx), (error) => error instanceof StepBlocked)
+
+  // Converged workspace (node_modules + matching install.hash): warn, no block.
+  fs.mkdirSync(path.join(repo, 'node_modules'), { recursive: true })
+  fs.mkdirSync(path.join(repo, '.mercato', 'starter'), { recursive: true })
+  const currentHash = crypto.createHash('sha256')
+    .update('yarn.lock').update(Buffer.alloc(0))
+    .update('package.json').update(Buffer.alloc(0))
+    .digest('hex')
+  fs.writeFileSync(path.join(repo, '.mercato', 'starter', 'install.hash'), `${currentHash}\n`)
+  const outcome = await buildToolchainStep.check(ctx)
+  assert.equal(outcome.ok, true)
+  assert.match(outcome.detail, /already converged/)
+
+  // A pending lockfile change re-arms the hard block.
+  fs.writeFileSync(path.join(repo, 'yarn.lock'), 'changed\n')
+  await assert.rejects(() => buildToolchainStep.check(ctx), (error) => error instanceof StepBlocked)
+})

package/src/certs.mjs

@@ -0,0 +1,266 @@
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import tls from 'node:tls'
+
+import { CAPTURED_CA_BUNDLE, DOCKER_CERTS_DIR, OPENCODE_CERTS_DIR, TLS_PROBE_HOSTS } from './constants.mjs'
+
+// Corporate TLS interception handling. Managed devices (Zscaler, Netskope,
+// Palo Alto, ...) resign every TLS connection with a company root CA that the
+// OS trusts but Node/yarn/docker builds do not. The strategy:
+//   detect  — probe well-known hosts with Node's default trust store
+//   capture — export the interception root(s) from the presented chain
+//   provision — drop the bundle everywhere the stack needs it:
+//     * NODE_EXTRA_CA_CERTS for every host-side child process (yarn, corepack,
+//       node scripts)
+//     * docker/certs/ + docker/opencode/certs/ (baked into image builds and
+//       runtime container trust by the existing Dockerfiles)
+//   guide  — engine-level trust (Docker Desktop reads the Windows cert store;
+//     Rancher Desktop needs the CA inside its WSL distro) is reported by the
+//     doctor with exact commands, since it touches machine state we do not own.
+
+const PROBE_TIMEOUT_MS = 5000
+
+const INTERCEPTION_ERROR_CODES = new Set([
+  'UNABLE_TO_GET_ISSUER_CERT',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'CERT_UNTRUSTED',
+])
+
+function connectOnce(host, { rejectUnauthorized }) {
+  return new Promise((resolve) => {
+    const socket = tls.connect({
+      host,
+      port: 443,
+      servername: host,
+      rejectUnauthorized,
+      // Only the platform trust matters for classification — an inherited
+      // NODE_EXTRA_CA_CERTS would mask the interception we are looking for,
+      // but Node bakes it in at process start, so run detection before we
+      // inject the bundle into our own environment (see provisionHostTrust).
+      timeout: PROBE_TIMEOUT_MS,
+    })
+    const finish = (result) => {
+      socket.destroy()
+      resolve(result)
+    }
+    socket.once('secureConnect', () => {
+      finish({ host, status: 'ok', authorized: socket.authorized, peer: socket.getPeerCertificate(true) })
+    })
+    socket.once('timeout', () => finish({ host, status: 'unreachable', reason: 'timeout' }))
+    socket.once('error', (error) => {
+      const code = error?.code ?? ''
+      if (INTERCEPTION_ERROR_CODES.has(code)) {
+        finish({ host, status: 'intercepted', reason: code })
+      } else {
+        finish({ host, status: 'unreachable', reason: code || String(error?.message ?? 'unknown error') })
+      }
+    })
+  })
+}
+
+// Classify egress per host: 'ok' | 'intercepted' | 'unreachable'.
+export async function probeTlsInterception(hosts = TLS_PROBE_HOSTS) {
+  const results = []
+  for (const host of hosts) {
+    const strict = await connectOnce(host, { rejectUnauthorized: true })
+    if (strict.status !== 'intercepted') {
+      results.push({ host, status: strict.status, reason: strict.reason ?? '' })
+      continue
+    }
+    results.push({ host, status: 'intercepted', reason: strict.reason ?? '' })
+  }
+  return results
+}
+
+function derToPem(raw) {
+  const base64 = Buffer.from(raw).toString('base64')
+  const lines = base64.match(/.{1,64}/g) ?? []
+  return `-----BEGIN CERTIFICATE-----\n${lines.join('\n')}\n-----END CERTIFICATE-----\n`
+}
+
+function walkToRoots(peer) {
+  // The presented chain ends at the interception root (self-signed: the cert
+  // whose issuerCertificate points at itself). Collect every CA cert above the
+  // leaf — proxies often present an intermediate + root and both are needed.
+  const collected = []
+  const seen = new Set()
+  let current = peer
+  let hops = 0
+  while (current && typeof current === 'object' && hops < 10) {
+    hops += 1
+    const isSelfIssued = current.issuerCertificate === current
+    const fingerprint = current.fingerprint256 ?? current.fingerprint ?? ''
+    const isCa = current.ca === true || isSelfIssued
+    if (isCa && fingerprint && !seen.has(fingerprint)) {
+      seen.add(fingerprint)
+      collected.push({ fingerprint, subject: current.subject?.CN ?? current.subject?.O ?? 'unknown', raw: current.raw })
+    }
+    if (isSelfIssued) break
+    current = current.issuerCertificate
+  }
+  return collected
+}
+
+// Capture the interception CA chain from every intercepted host, deduped by
+// fingerprint. Returns [{ fingerprint, subject, pem }].
+export async function captureInterceptionCas(hosts) {
+  const captured = new Map()
+  for (const host of hosts) {
+    const relaxed = await connectOnce(host, { rejectUnauthorized: false })
+    if (relaxed.status !== 'ok' || !relaxed.peer) continue
+    for (const cert of walkToRoots(relaxed.peer)) {
+      if (!cert.raw || captured.has(cert.fingerprint)) continue
+      captured.set(cert.fingerprint, { fingerprint: cert.fingerprint, subject: cert.subject, pem: derToPem(cert.raw) })
+    }
+  }
+  return [...captured.values()]
+}
+
+function readBundleText(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
+// Netskope agents ship a ready-made combined PEM on disk — the cheapest and
+// most reliable source when present.
+// https://community.netskope.com/next-gen-swg-2/configuring-cli-based-tools-and-development-frameworks-to-work-with-netskope-ssl-interception-7015
+export function findVendorCaBundles() {
+  if (process.platform !== 'win32') return []
+  const programData = process.env.ProgramData ?? 'C:\\ProgramData'
+  return [
+    path.join(programData, 'Netskope', 'STAgent', 'data', 'nscacert_combined.pem'),
+    path.join(programData, 'Netskope', 'STAgent', 'download', 'nscacert_combined.pem'),
+  ].filter((candidate) => fs.existsSync(candidate))
+}
+
+const WINDOWS_INTERCEPTION_SUBJECT_PATTERN = 'Zscaler|Netskope|Palo Alto|Blue Coat|Forcepoint|Fortinet|McAfee Web|SSL Inspection|TLS Inspection|Decryption'
+
+// Harvest GPO-deployed interception roots from the Windows certificate store
+// (readable without admin; CurrentUser\Root inherits the machine store). The
+// interception root often is NOT sent on the wire — the store is the only
+// place to get it. Cmdlet-only PowerShell, safe under Constrained Language.
+export function harvestWindowsStoreCas() {
+  if (process.platform !== 'win32') return []
+  const script = [
+    `$pattern = '${WINDOWS_INTERCEPTION_SUBJECT_PATTERN}'`,
+    "Get-ChildItem Cert:\\CurrentUser\\Root | Where-Object { $_.Subject -match $pattern } | ForEach-Object {",
+    "  'FINGERPRINT:' + $_.Thumbprint",
+    "  'SUBJECT:' + $_.Subject",
+    "  '-----BEGIN CERTIFICATE-----'",
+    "  [Convert]::ToBase64String($_.RawData, [Base64FormattingOptions]::InsertLineBreaks)",
+    "  '-----END CERTIFICATE-----'",
+    '}',
+  ].join('; ')
+  const run = spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], { encoding: 'utf8', timeout: 30000, windowsHide: true })
+  if (run.error || run.status !== 0) return []
+  const certs = []
+  const blocks = String(run.stdout ?? '').split('FINGERPRINT:').slice(1)
+  for (const block of blocks) {
+    const [fingerprint] = block.split(/\r?\n/, 1)
+    const subject = block.match(/SUBJECT:(.*)/)?.[1]?.trim() ?? 'unknown'
+    const pemMatch = block.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/)
+    if (!pemMatch) continue
+    certs.push({ fingerprint: fingerprint.trim(), subject, pem: `${pemMatch[0].replace(/\r\n/g, '\n')}\n` })
+  }
+  return certs
+}
+
+// Build the effective CA bundle from company-provided files plus captured CAs
+// and write it to .mercato/certs/corporate-ca.pem. Returns the bundle path or
+// null when there is nothing to trust.
+export function writeCaBundle(repoRoot, { companyBundles = [], capturedPems = [] } = {}) {
+  const sections = []
+  for (const bundlePath of companyBundles) {
+    const text = readBundleText(bundlePath)
+    if (text) sections.push(`# source: ${bundlePath}\n${text}`)
+  }
+  for (const cert of capturedPems) {
+    sections.push(`# captured interception CA: ${cert.subject} (${cert.fingerprint})\n${cert.pem.trim()}`)
+  }
+  if (sections.length === 0) return null
+  const bundlePath = path.join(repoRoot, CAPTURED_CA_BUNDLE)
+  fs.mkdirSync(path.dirname(bundlePath), { recursive: true })
+  fs.writeFileSync(bundlePath, `${sections.join('\n\n')}\n`)
+  return bundlePath
+}
+
+// Copy the bundle into the gitignored image-build drop zones. The root
+// Dockerfile and docker/opencode/Dockerfile append everything in these dirs to
+// the container trust store (build-time AND runtime egress).
+export function provisionDockerCerts(repoRoot, bundlePath) {
+  const targets = [
+    path.join(repoRoot, DOCKER_CERTS_DIR, 'corporate-root-ca.crt'),
+    path.join(repoRoot, OPENCODE_CERTS_DIR, 'corporate-root-ca.crt'),
+  ]
+  const written = []
+  for (const target of targets) {
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    const next = fs.readFileSync(bundlePath, 'utf8')
+    const current = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null
+    if (current !== next) fs.writeFileSync(target, next)
+    written.push(target)
+  }
+  return written
+}
+
+// Environment for host-side child processes so node/yarn/corepack trust the
+// corporate CA and traverse the corporate proxy:
+//   * NODE_EXTRA_CA_CERTS — additive to Node's bundled roots (safe everywhere)
+//   * --use-system-ca (Node >= 24) — additively trusts the OS store, which on
+//     managed Windows contains the GPO-deployed interception root; this makes
+//     host tooling work even when nothing could be captured
+//   * NODE_USE_ENV_PROXY=1 — corepack 0.35+ (bundled since Node 24.16) dropped
+//     its own proxy handling; without this flag HTTP(S)_PROXY is ignored
+export function hostTrustEnv(bundlePath, baseEnv = process.env) {
+  const env = { ...baseEnv }
+  if (bundlePath) env.NODE_EXTRA_CA_CERTS = bundlePath
+  const nodeOptions = String(env.NODE_OPTIONS ?? '')
+  if (!nodeOptions.includes('--use-system-ca')) {
+    env.NODE_OPTIONS = `${nodeOptions} --use-system-ca`.trim()
+  }
+  const hasProxy = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].some((key) => env[key])
+  if (hasProxy && !env.NODE_USE_ENV_PROXY) env.NODE_USE_ENV_PROXY = '1'
+  return env
+}
+
+// Rancher Desktop imports Windows-store CAs into its WSL distro on start, but
+// the mechanism is undocumented and has regressed more than once — the
+// documented, deterministic channel is a provisioning script that runs as root
+// inside the distro BEFORE dockerd starts. It must use LF line endings.
+// https://docs.rancherdesktop.io/how-to-guides/provisioning-scripts
+export function provisionRancherDesktopCa(repoRoot, bundlePath) {
+  if (process.platform !== 'win32') return null
+  const localAppData = process.env.LOCALAPPDATA
+  if (!localAppData || !fs.existsSync(path.join(localAppData, 'rancher-desktop'))) return null
+  const provisioningDir = path.join(localAppData, 'rancher-desktop', 'provisioning')
+  const scriptPath = path.join(provisioningDir, 'open-mercato-corp-ca.start')
+  // /mnt/c/... path of the bundle as seen from inside the WSL distro.
+  const driveMatch = /^([A-Za-z]):[\\/](.*)$/.exec(bundlePath)
+  if (!driveMatch) return null
+  const wslBundlePath = `/mnt/${driveMatch[1].toLowerCase()}/${driveMatch[2].replace(/\\/g, '/')}`
+  const script = [
+    '#!/bin/sh',
+    '# Written by the Open Mercato starter: trust the corporate CA before dockerd starts.',
+    `cp "${wslBundlePath}" /usr/local/share/ca-certificates/open-mercato-corp-ca.crt && update-ca-certificates`,
+    '',
+  ].join('\n')
+  fs.mkdirSync(provisioningDir, { recursive: true })
+  const current = fs.existsSync(scriptPath) ? fs.readFileSync(scriptPath, 'utf8') : null
+  if (current !== script) fs.writeFileSync(scriptPath, script)
+  return scriptPath
+}
+
+export function summarizeProbeResults(results) {
+  return {
+    intercepted: results.filter((entry) => entry.status === 'intercepted'),
+    unreachable: results.filter((entry) => entry.status === 'unreachable'),
+    clean: results.filter((entry) => entry.status === 'ok'),
+  }
+}