@open-mercato/starter 0.6.5

package/src/cli.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+// Open Mercato starter CLI — the single cross-platform brain behind the three
+// platform entry scripts (start.sh, start.ps1, start.cmd). The entries only
+// guarantee Node 24 exists, then hand every command off to this file.
+//
+//   up      (default) idempotent converge + start: prerequisites -> corporate
+//           TLS trust -> env/secrets -> install -> infra -> database -> dev
+//   stop    stop host processes and/or containers
+//   status  processes, containers, health, URLs
+//   logs    tail the newest dev log (--follow)
+//   doctor  read-only audit with remediation + a "hand this to IT" sheet
+//   reset   destructive cleanup (asks first)
+//   infra   up/down for just the infra containers
+//
+// Modes: --mode hybrid (default; app + MCP on the host, services in
+// containers) or --mode docker (everything containerized — for machines where
+// running Node workloads on the host is not allowed). The chosen mode is
+// remembered in .mercato/starter/mode.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import readline from 'node:readline'
+
+import { detectDocker, resolveRepoRoot, runCompose, runStreamingSync, spawnStreaming } from './compose.mjs'
+import { FULLAPP_DEV_COMPOSE_FILE, STARTER_STATE_DIR, resolveStackPorts, stackUrls } from './constants.mjs'
+import { loadCompanyConfig } from './company.mjs'
+import { printDoctorReport, runDoctor } from './doctor.mjs'
+import { infraDown, infraUp, ensureMcpSharedDir } from './infra.mjs'
+import { buildUpSteps, clearConvergenceState, createStepContext, ensureOpencodeImage, runSteps, yarnInvocation } from './steps.mjs'
+import { collectStatus, printStatus, readRunState, isPidAlive, startDetached, stopDetached, tailLogs } from './supervise.mjs'
+import { ensureWindowsUtf8Console } from './spawn.mjs'
+import { color, guideBox, printBanner, statusLine } from './ui.mjs'
+import { waitForHealthyServices, waitForHttp } from './waits.mjs'
+
+ensureWindowsUtf8Console()
+
+const repoRoot = resolveRepoRoot()
+if (!repoRoot) {
+  console.error('❌ No Open Mercato checkout found above the current directory.')
+  console.error('   Run `npx @open-mercato/starter` (it clones for you) or cd into a clone first.')
+  process.exit(2)
+}
+
+function parseArgs(argv) {
+  const commands = new Set(['up', 'stop', 'status', 'logs', 'doctor', 'reset', 'infra'])
+  const args = [...argv]
+  const command = commands.has(args[0]) ? args.shift() : 'up'
+  const flags = {
+    mode: null,
+    detach: false,
+    follow: false,
+    nonInteractive: false,
+    skipLlmPrompt: false,
+    skipDb: false,
+    noInfra: false,
+    rebuild: false,
+    clean: false,
+    volumes: false,
+    yes: false,
+    keepInfra: false,
+    profiles: [],
+    passthrough: [],
+    infraAction: null,
+  }
+  while (args.length > 0) {
+    const arg = args.shift()
+    if (arg === '--') {
+      flags.passthrough = args.splice(0)
+      break
+    }
+    switch (arg) {
+      case '--mode':
+        flags.mode = args.shift() ?? null
+        break
+      case '--detach':
+      case '-d':
+        flags.detach = true
+        break
+      case '--follow':
+      case '-f':
+        flags.follow = true
+        break
+      case '--non-interactive':
+        flags.nonInteractive = true
+        break
+      case '--skip-llm-prompt':
+        flags.skipLlmPrompt = true
+        break
+      case '--skip-db':
+        flags.skipDb = true
+        break
+      case '--no-infra':
+        flags.noInfra = true
+        break
+      case '--rebuild':
+        flags.rebuild = true
+        break
+      case '--clean':
+        flags.clean = true
+        break
+      case '--volumes':
+        flags.volumes = true
+        break
+      case '--yes':
+        flags.yes = true
+        break
+      case '--keep-infra':
+        flags.keepInfra = true
+        break
+      case '--profile':
+        if (args[0]) flags.profiles.push(args.shift())
+        break
+      case 'up':
+      case 'down':
+        if (command === 'infra') flags.infraAction = arg
+        break
+      default:
+        console.error(`Unknown option: ${arg} (see starters/README.md)`)
+        process.exit(1)
+    }
+  }
+  if (!process.stdin.isTTY || process.env.CI === 'true') flags.nonInteractive = true
+  return { command, flags }
+}
+
+function modeStatePath() {
+  return path.join(repoRoot, STARTER_STATE_DIR, 'mode')
+}
+
+function resolveMode(flagMode) {
+  if (flagMode) {
+    if (!['hybrid', 'docker'].includes(flagMode)) {
+      console.error(`Unknown --mode '${flagMode}' — use hybrid or docker.`)
+      process.exit(1)
+    }
+    fs.mkdirSync(path.dirname(modeStatePath()), { recursive: true })
+    fs.writeFileSync(modeStatePath(), `${flagMode}\n`)
+    return flagMode
+  }
+  try {
+    const saved = fs.readFileSync(modeStatePath(), 'utf8').trim()
+    if (['hybrid', 'docker'].includes(saved)) return saved
+  } catch {
+    // fall through to default
+  }
+  return 'hybrid'
+}
+
+async function confirm(question, { nonInteractive }) {
+  if (nonInteractive) return false
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve))
+  rl.close()
+  return /^y/i.test(answer.trim())
+}
+
+async function commandUp(flags) {
+  const mode = resolveMode(flags.mode)
+  if (flags.clean) {
+    // Full re-converge: drop the completed-step markers (keeps the mode, all
+    // data, and the one-time initialize state — `reset` is the destructive
+    // variant) and rebuild the OpenCode service image.
+    flags.rebuild = true
+    const cleared = clearConvergenceState(repoRoot)
+    console.log(color.dim(`  --clean: cleared ${cleared.length} convergence marker(s) — install, build, and migrations will re-run (data untouched).`))
+  }
+  const ctx = await createStepContext(repoRoot, { mode, flags })
+  printBanner(`dev environment starter — mode: ${mode}${ctx.company.name ? ` — company profile: ${ctx.company.name}` : ''}`)
+  console.log(color.dim(`  Repo: ${repoRoot}`))
+  console.log(color.dim('  Every step is idempotent — re-running always resumes where it stopped.'))
+
+  if (mode === 'docker') return commandUpDocker(ctx, flags)
+
+  const outcome = await runSteps(buildUpSteps(ctx), ctx)
+  if (!outcome.ok) {
+    guideBox('Setup stopped', [
+      'Fix the item above and re-run the same command — completed steps are skipped.',
+      'Full environment audit with an IT handout:  yarn om doctor   (or: npx @open-mercato/starter doctor)',
+    ])
+    process.exit(2)
+  }
+
+  const ports = resolveStackPorts(repoRoot)
+  const urls = stackUrls(ports)
+  console.log('')
+  console.log(color.bold(color.green('Environment ready — starting the dev runtime')) + color.dim(' (app + queue workers + scheduler + MCP server)'))
+  console.log(`  App:      ${color.cyan(urls.app)}   ${color.dim('(login page appears once the app finishes booting)')}`)
+  console.log(`  MCP:      ${color.cyan(urls.mcp)}`)
+  console.log(`  OpenCode: ${color.cyan(`http://127.0.0.1:${ports.opencode}`)}`)
+  console.log(color.dim('  Superadmin credentials: OM_INIT_SUPERADMIN_EMAIL / OM_INIT_SUPERADMIN_PASSWORD in .env'))
+  console.log(color.dim('  Stop: Ctrl+C (infra containers keep running; `stop` shuts everything down)'))
+  console.log('')
+
+  if (flags.detach) {
+    startDetached(repoRoot, flags.passthrough, { env: ctx.env })
+    console.log('Manage it with the status / logs / stop subcommands.')
+    return
+  }
+  const dev = yarnInvocation(ctx, ['dev', ...flags.passthrough])
+  const child = spawnStreaming(dev.command, dev.args, { cwd: repoRoot, env: ctx.env })
+  child.on('close', (code) => process.exit(code ?? 0))
+  child.on('error', (error) => {
+    console.error(`❌ Could not start yarn dev: ${error.message}`)
+    process.exit(1)
+  })
+}
+
+async function commandUpDocker(ctx, flags) {
+  // Containerized mode: converge trust/env, then let compose own the stack.
+  const steps = buildUpSteps(ctx).filter((step) => ['prerequisites', 'container-runtime', 'corporate-certs', 'env-files', 'llm-provider'].includes(step.id))
+  const outcome = await runSteps(steps, ctx)
+  if (!outcome.ok) process.exit(2)
+
+  ensureMcpSharedDir(repoRoot)
+  ensureOpencodeImage(ctx)
+  const composeFile = FULLAPP_DEV_COMPOSE_FILE
+  const upArgs = ['up', '-d']
+  if (flags.rebuild) upArgs.push('--build')
+  console.log('')
+  console.log('── Starting the containerized stack (this builds the app image on the first run) ──')
+  const up = runCompose(repoRoot, upArgs, { composeFile })
+  if ((up.status ?? 1) !== 0) {
+    console.error('❌ docker compose up failed — see above. TLS errors inside builds usually mean the corporate CA changed: re-run with --rebuild.')
+    process.exit(up.status ?? 1)
+  }
+
+  const ports = resolveStackPorts(repoRoot)
+  const urls = stackUrls(ports)
+  console.log(color.dim('  Startup order: infra healthy -> app serving -> MCP -> OpenCode -> end-to-end wiring check.'))
+  const infraOk = await waitForHealthyServices(repoRoot, composeFile, ['postgres', 'redis', 'meilisearch'], { log: console.log })
+  if (!infraOk.ok) process.exit(1)
+  console.log(color.dim('  First boot runs migrations + seed inside the app container — expect several minutes.'))
+  if (!(await waitForHttp(urls.app, { label: `app ${urls.app}`, timeoutMs: 30 * 60 * 1000 }))) process.exit(1)
+  const mcpOk = await waitForHttp(urls.mcpHealth, { label: 'MCP /health' })
+  const opencodeOk = await waitForHttp(urls.opencodeHealth, { label: 'OpenCode /global/health' })
+  if (mcpOk && opencodeOk) {
+    await waitForHttp(urls.opencodeMcpStatus, {
+      label: 'OpenCode <-> MCP wiring',
+      timeoutMs: 2 * 60 * 1000,
+      validate: (body) => body.includes('connected'),
+    })
+  }
+  console.log('')
+  console.log(color.bold(color.green('Stack is up.')))
+  console.log(`  App:      ${color.cyan(urls.app)}  ${color.dim('(superadmin credentials: OM_INIT_SUPERADMIN_EMAIL / _PASSWORD in .env)')}`)
+  console.log(`  OpenCode: ${color.cyan(`http://127.0.0.1:${ports.opencode}`)}`)
+  console.log(color.dim('  Manage it with the stop / status / logs subcommands.'))
+}
+
+async function commandStop(flags) {
+  const mode = resolveMode(flags.mode)
+  if (flags.volumes && !flags.yes) {
+    console.error('❌ --volumes DELETES all database/search data. Re-run with --yes to confirm.')
+    process.exit(1)
+  }
+  if (mode === 'docker') {
+    const down = runCompose(repoRoot, ['down', ...(flags.volumes ? ['--volumes'] : [])], { composeFile: FULLAPP_DEV_COMPOSE_FILE })
+    process.exit(down.status ?? 1)
+  }
+  await stopDetached(repoRoot)
+  if (!flags.keepInfra) {
+    const docker = detectDocker()
+    if (docker.ok) {
+      const status = infraDown(repoRoot, { volumes: flags.volumes })
+      if (status === 0) console.log(flags.volumes ? '✅ Infra containers stopped and volumes deleted.' : '✅ Infra containers stopped (data preserved).')
+      process.exit(status)
+    }
+  }
+  console.log('ℹ️ Infra containers left running (--keep-infra or no docker). Foreground `yarn dev` sessions stop with Ctrl+C.')
+}
+
+async function commandStatus(flags) {
+  const mode = resolveMode(flags.mode)
+  const status = await collectStatus(repoRoot, {
+    runCompose: (root, args, opts) => runCompose(root, args, { ...opts, composeFile: mode === 'docker' ? FULLAPP_DEV_COMPOSE_FILE : undefined }),
+  })
+  printStatus(status)
+}
+
+async function commandDoctor(flags) {
+  const company = await loadCompanyConfig(repoRoot)
+  const runState = readRunState(repoRoot)
+  const stackRunning = Boolean(runState && isPidAlive(runState.pid))
+  const mode = resolveMode(flags?.mode)
+  const checks = await runDoctor(repoRoot, { company, stackRunning, includeContainerProbe: true, mode })
+  const ok = printDoctorReport(checks, { company })
+  process.exit(ok ? 0 : 2)
+}
+
+async function commandReset(flags) {
+  const mode = resolveMode(flags.mode)
+  console.log('Reset stops the stack, removes containers + volumes (ALL LOCAL DATA), and clears starter state.')
+  const confirmed = flags.yes || (await confirm('Continue?', flags))
+  if (!confirmed) {
+    console.log('Aborted.')
+    return
+  }
+  await stopDetached(repoRoot)
+  const docker = detectDocker()
+  if (docker.ok) {
+    runCompose(repoRoot, ['down', '--volumes'], { composeFile: mode === 'docker' ? FULLAPP_DEV_COMPOSE_FILE : undefined })
+  }
+  fs.rmSync(path.join(repoRoot, STARTER_STATE_DIR), { recursive: true, force: true })
+  console.log('✅ Reset complete. Run the starter again for a fresh environment.')
+}
+
+async function commandInfra(flags) {
+  const docker = detectDocker()
+  if (!docker.ok) {
+    console.error(`❌ Docker is not available (${docker.reason}). Run the doctor subcommand for guided setup.`)
+    process.exit(2)
+  }
+  if (flags.infraAction === 'down') {
+    if (flags.volumes && !flags.yes) {
+      console.error('❌ --volumes DELETES all database/search data. Re-run with --yes to confirm.')
+      process.exit(1)
+    }
+    process.exit(infraDown(repoRoot, { volumes: flags.volumes }))
+  }
+  ensureMcpSharedDir(repoRoot)
+  ensureOpencodeImage({ repoRoot, env: process.env, flags: { rebuild: flags.rebuild }, log: console.log })
+  const status = infraUp(repoRoot, { profiles: flags.profiles })
+  if (status === 0) {
+    const ports = resolveStackPorts(repoRoot)
+    console.log('')
+    console.log(`✅ Infra containers are up (opencode :${ports.opencode}, postgres :${ports.postgres}, redis :${ports.redis}, meilisearch :${ports.meilisearch}).`)
+    console.log('   Next: yarn dev (starts the app and the MCP server on this machine)')
+  }
+  process.exit(status)
+}
+
+async function main() {
+  const { command, flags } = parseArgs(process.argv.slice(2))
+  switch (command) {
+    case 'up':
+      return commandUp(flags)
+    case 'stop':
+      return commandStop(flags)
+    case 'status':
+      return commandStatus(flags)
+    case 'logs':
+      return tailLogs(repoRoot, { follow: flags.follow })
+    case 'doctor':
+      return commandDoctor(flags)
+    case 'reset':
+      return commandReset(flags)
+    case 'infra':
+      return commandInfra(flags)
+    default:
+      console.error(`Unknown command: ${command}`)
+      process.exit(1)
+  }
+}
+
+await main()

package/src/company.mjs

@@ -0,0 +1,80 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+// Company overlay: lets an organization tailor the starter without forking it.
+// Resolution order (later wins per key):
+//   1. built-in defaults below
+//   2. starters/company/config.mjs        (committed, per-company policy)
+//   3. starters/company/config.local.mjs  (gitignored, per-machine override)
+// Each file default-exports a plain object matching COMPANY_DEFAULTS' shape.
+
+export const COMPANY_DEFAULTS = {
+  name: '',
+  // Where users are sent when a prerequisite needs IT. Shown verbatim in the
+  // doctor's "hand this to IT" sheet.
+  itContact: '',
+  mirrors: {
+    // e.g. https://registry.example.com/npm — applied via COREPACK_NPM_REGISTRY
+    // and yarn's npmRegistryServer for installs run by the starter.
+    npmRegistry: '',
+    // Forwarded into image builds as the ALPINE_MIRROR build arg.
+    alpineMirror: '',
+    // Base URL that mirrors https://nodejs.org/dist (used by start.sh/start.ps1).
+    nodeDist: '',
+  },
+  certs: {
+    // Extra PEM bundles (absolute or repo-relative) trusted in addition to any
+    // captured interception CA. Point this at the corporate root bundle when IT
+    // can provide one — capture is the fallback, not the preferred source.
+    bundles: [],
+    // Set false to disable active TLS-interception capture (audit-sensitive
+    // fleets); provisioning then relies solely on `bundles`.
+    capture: true,
+  },
+  // Extra doctor checks: [{ id, title, run: async (ctx) => ({ level, detail, guide? }) }]
+  checks: [],
+  // Step tweaks for `up`: ids listed in `disable` are skipped; `extra` steps
+  // (same shape as steps.mjs entries) run after the built-ins, before launch.
+  steps: { disable: [], extra: [] },
+  // Env defaults merged into generated .env files (never overwrite existing).
+  env: {},
+}
+
+function mergeConfig(base, overlay) {
+  if (!overlay || typeof overlay !== 'object') return base
+  const merged = { ...base, ...overlay }
+  merged.mirrors = { ...base.mirrors, ...(overlay.mirrors ?? {}) }
+  merged.certs = { ...base.certs, ...(overlay.certs ?? {}) }
+  merged.steps = {
+    disable: [...base.steps.disable, ...(overlay.steps?.disable ?? [])],
+    extra: [...base.steps.extra, ...(overlay.steps?.extra ?? [])],
+  }
+  merged.checks = [...base.checks, ...(overlay.checks ?? [])]
+  merged.env = { ...base.env, ...(overlay.env ?? {}) }
+  return merged
+}
+
+export async function loadCompanyConfig(repoRoot, { warn = console.warn } = {}) {
+  let config = COMPANY_DEFAULTS
+  for (const candidate of ['config.mjs', 'config.local.mjs']) {
+    const filePath = path.join(repoRoot, 'starters', 'company', candidate)
+    if (!fs.existsSync(filePath)) continue
+    try {
+      const module = await import(pathToFileURL(filePath).href)
+      config = mergeConfig(config, module.default)
+    } catch (error) {
+      warn(`⚠️ Ignoring starters/company/${candidate} — it failed to load: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  return config
+}
+
+export function resolveCompanyCertBundles(repoRoot, company) {
+  const bundles = []
+  for (const entry of company.certs.bundles) {
+    const resolved = path.isAbsolute(entry) ? entry : path.join(repoRoot, entry)
+    if (fs.existsSync(resolved)) bundles.push(resolved)
+  }
+  return bundles
+}

package/src/compose.mjs

@@ -0,0 +1,144 @@
+import { spawn, spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { resolveSpawnCommand } from './spawn.mjs'
+
+export const INFRA_COMPOSE_FILE = path.join('starters', 'docker', 'compose.infra.yml')
+
+function isOpenMercatoRoot(dir) {
+  // Works for the monorepo AND for standalone apps scaffolded by create-app:
+  // both carry the starters/docker compose layout at their root.
+  if (fs.existsSync(path.join(dir, INFRA_COMPOSE_FILE))) return true
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'))
+    return pkg?.name === 'open-mercato'
+  } catch {
+    return false
+  }
+}
+
+// The starter can run from anywhere (npx, package bin inside node_modules, a
+// subdirectory of the clone) — never assume a location relative to this file.
+export function resolveRepoRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir)
+  while (true) {
+    if (isOpenMercatoRoot(dir)) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+// Canonical invocation: --project-directory anchors .env interpolation and
+// every relative path in the compose file at the repo root, keeping the
+// compose project identity identical to the pre-starters layout.
+export function composeArgs(repoRoot, extraArgs, composeFile = INFRA_COMPOSE_FILE) {
+  return ['compose', '--project-directory', repoRoot, '-f', path.join(repoRoot, composeFile), ...extraArgs]
+}
+
+export function runCompose(repoRoot, extraArgs, { composeFile, stdio = 'inherit' } = {}) {
+  const result = spawnSync('docker', composeArgs(repoRoot, extraArgs, composeFile), {
+    cwd: repoRoot,
+    stdio,
+    encoding: 'utf8',
+  })
+  if (result.error) {
+    throw new Error(`docker compose could not be executed: ${result.error.message}`)
+  }
+  return result
+}
+
+export function detectDocker() {
+  const cli = spawnSync('docker', ['--version'], { stdio: 'ignore' })
+  if (cli.error || cli.status !== 0) {
+    return { ok: false, reason: 'docker CLI not found' }
+  }
+  const composePlugin = spawnSync('docker', ['compose', 'version'], { stdio: 'ignore' })
+  if (composePlugin.error || composePlugin.status !== 0) {
+    return { ok: false, reason: 'docker compose v2 plugin not found' }
+  }
+  const engine = spawnSync('docker', ['info', '--format', '{{.ServerVersion}}'], { stdio: 'ignore' })
+  if (engine.error || engine.status !== 0) {
+    return { ok: false, reason: 'docker engine not running' }
+  }
+  return { ok: true }
+}
+
+// `compose ps --format json` prints NDJSON on compose >= 2.21 and a JSON array
+// on older releases — tolerate both.
+export function parseComposePsOutput(raw) {
+  const trimmed = String(raw ?? '').trim()
+  if (!trimmed) return []
+  if (trimmed.startsWith('[')) {
+    try {
+      return JSON.parse(trimmed)
+    } catch {
+      return []
+    }
+  }
+  const entries = []
+  for (const line of trimmed.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      entries.push(JSON.parse(line))
+    } catch {
+      // Ignore non-JSON noise lines.
+    }
+  }
+  return entries
+}
+
+export function summarizeServiceStates(entries) {
+  const states = {}
+  for (const entry of entries) {
+    const service = entry?.Service
+    if (!service) continue
+    states[service] = {
+      state: entry.State ?? 'unknown',
+      health: entry.Health ?? '',
+    }
+  }
+  return states
+}
+
+// Both helpers route through resolveSpawnCommand (spawn.mjs): it validates
+// command + args and only enables the cmd.exe shell for the .cmd shims
+// (yarn/npm/corepack) that Node >= 18.20 cannot spawn directly on Windows.
+export function spawnStreaming(command, commandArgs, { cwd, env } = {}) {
+  const resolved = resolveSpawnCommand(command, commandArgs)
+  return spawn(resolved.command, resolved.args, {
+    cwd: cwd ?? process.cwd(),
+    env: env ?? process.env,
+    stdio: 'inherit',
+    ...resolved.spawnOptions,
+  })
+}
+
+// Capture-mode sibling of runStreamingSync for probes that need the output
+// (version checks, registry queries). Same Windows shim handling.
+export function runCaptureSync(command, commandArgs, { cwd, env, timeout = 15000 } = {}) {
+  const resolved = resolveSpawnCommand(command, commandArgs)
+  return spawnSync(resolved.command, resolved.args, {
+    cwd: cwd ?? process.cwd(),
+    env: env ?? process.env,
+    encoding: 'utf8',
+    timeout,
+    windowsHide: true,
+    ...resolved.spawnOptions,
+  })
+}
+
+export function runStreamingSync(command, commandArgs, { cwd, env } = {}) {
+  const resolved = resolveSpawnCommand(command, commandArgs)
+  const result = spawnSync(resolved.command, resolved.args, {
+    cwd: cwd ?? process.cwd(),
+    env: env ?? process.env,
+    stdio: 'inherit',
+    ...resolved.spawnOptions,
+  })
+  if (result.error) {
+    throw new Error(`${command} could not be executed: ${result.error.message}`)
+  }
+  return result.status ?? 1
+}

package/src/constants.mjs

@@ -0,0 +1,85 @@
+import path from 'node:path'
+
+import { readEnvValue } from './env-file.mjs'
+
+// Single source of truth for the local stack topology. Every consumer (steps,
+// doctor, status, supervision) resolves ports through here so a port override
+// in the root .env is honored everywhere at once.
+
+export const DEFAULT_PORTS = {
+  app: 3000,
+  mcp: 3001,
+  splash: 4000,
+  opencode: 4096,
+  localstack: 4566,
+  verdaccio: 4873,
+  postgres: 5432,
+  redis: 6379,
+  meilisearch: 7700,
+  keycloak: 8080,
+}
+
+const PORT_ENV_KEYS = {
+  app: 'APP_PORT',
+  mcp: 'MCP_PORT',
+  splash: 'OM_DEV_SPLASH_PORT',
+  opencode: 'OPENCODE_PORT',
+  localstack: 'LOCALSTACK_PORT',
+  verdaccio: 'VERDACCIO_PORT',
+  postgres: 'POSTGRES_PORT',
+  redis: 'REDIS_PORT',
+  meilisearch: 'MEILISEARCH_PORT',
+  keycloak: 'KEYCLOAK_PORT',
+}
+
+export function resolveStackPorts(repoRoot, env = process.env) {
+  const rootEnvPath = path.join(repoRoot, '.env')
+  const ports = {}
+  for (const [service, fallback] of Object.entries(DEFAULT_PORTS)) {
+    const key = PORT_ENV_KEYS[service]
+    const raw = env[key] ?? readEnvValue(rootEnvPath, key) ?? ''
+    const parsed = Number.parseInt(String(raw).trim(), 10)
+    ports[service] = Number.isInteger(parsed) && parsed > 0 && parsed < 65536 ? parsed : fallback
+  }
+  return ports
+}
+
+// Host-side probes deliberately use 127.0.0.1, never `localhost`: on modern
+// Windows (and some macOS setups) `localhost` resolves to ::1 first while the
+// services listen on IPv4, which turns every health probe into a coin flip.
+export const LOOPBACK_HOST = '127.0.0.1'
+
+export function stackUrls(ports) {
+  return {
+    app: `http://${LOOPBACK_HOST}:${ports.app}`,
+    appLogin: `http://${LOOPBACK_HOST}:${ports.app}/backend/login`,
+    splash: `http://${LOOPBACK_HOST}:${ports.splash}`,
+    mcpHealth: `http://${LOOPBACK_HOST}:${ports.mcp}/health`,
+    mcp: `http://${LOOPBACK_HOST}:${ports.mcp}/mcp`,
+    opencodeHealth: `http://${LOOPBACK_HOST}:${ports.opencode}/global/health`,
+    opencodeMcpStatus: `http://${LOOPBACK_HOST}:${ports.opencode}/mcp`,
+  }
+}
+
+// TLS-interception probe targets: one per critical egress class (yarn
+// registry, git hosting, container registry). Probing several hosts matters —
+// interception proxies keep per-host bypass lists, so a single clean probe
+// proves nothing.
+export const TLS_PROBE_HOSTS = ['registry.yarnpkg.com', 'github.com', 'registry-1.docker.io']
+
+export const STARTER_STATE_DIR = path.join('.mercato', 'starter')
+export const RUN_STATE_DIR = path.join('.mercato', 'run')
+export const CAPTURED_CA_BUNDLE = path.join('.mercato', 'certs', 'corporate-ca.pem')
+export const DOCKER_CERTS_DIR = path.join('docker', 'certs')
+export const OPENCODE_CERTS_DIR = path.join('docker', 'opencode', 'certs')
+export const DEV_LOG_DIR = path.join('.mercato', 'logs')
+
+export const FULLAPP_DEV_COMPOSE_FILE = path.join('starters', 'docker', 'compose.fullapp.dev.yml')
+
+// The published OpenCode image is a BASE (binary + non-root user, no
+// entrypoint/agents — docker/opencode/BASE_IMAGE.md). The runnable service
+// image is the thin local build FROM it, tagged opencode-mvp. Keep the default
+// tag in sync with the compose files' OPENCODE_BASE_IMAGE default and the
+// docker/opencode/Dockerfile ARG.
+export const DEFAULT_OPENCODE_BASE_IMAGE = 'docker.io/openmercatocom/open-mercato-opencode:1.18.3'
+export const OPENCODE_SERVICE_IMAGE = 'opencode-mvp'