@open-mercato/starter 0.6.5

package/src/supervise.mjs

@@ -0,0 +1,220 @@
+import { spawn, spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { DEV_LOG_DIR, RUN_STATE_DIR, resolveStackPorts, stackUrls } from './constants.mjs'
+import { color, icons } from './ui.mjs'
+
+// Detached ("PM2-like") lifecycle for the host processes. `yarn dev` is the
+// actual supervisor (it restarts the app and the MCP server with backoff);
+// this module only detaches it, tracks the pid, and exposes stop/status/logs.
+
+const PID_FILE = 'dev.json'
+
+function runStatePath(repoRoot) {
+  return path.join(repoRoot, RUN_STATE_DIR, PID_FILE)
+}
+
+export function readRunState(repoRoot) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(runStatePath(repoRoot), 'utf8'))
+    return typeof parsed?.pid === 'number' ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+export function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // EPERM means the process exists but belongs to someone else — count it
+    // as alive so we never clobber a foreign pid.
+    return error?.code === 'EPERM'
+  }
+}
+
+export function startDetached(repoRoot, devArgs = [], { env = process.env, log = console.log } = {}) {
+  const existing = readRunState(repoRoot)
+  if (existing && isPidAlive(existing.pid)) {
+    log(`✅ Dev runtime already running (pid ${existing.pid}). Use \`status\` / \`logs\` / \`stop\`.`)
+    return existing.pid
+  }
+  fs.mkdirSync(path.join(repoRoot, RUN_STATE_DIR), { recursive: true })
+  fs.mkdirSync(path.join(repoRoot, DEV_LOG_DIR), { recursive: true })
+  const logFile = path.join(repoRoot, DEV_LOG_DIR, 'detached-dev.log')
+  const outFd = fs.openSync(logFile, 'a')
+  const child = spawn(process.execPath, [path.join(repoRoot, 'scripts', 'dev.mjs'), ...devArgs], {
+    cwd: repoRoot,
+    detached: true,
+    stdio: ['ignore', outFd, outFd],
+    env: {
+      ...env,
+      // Headless: no browser popup, no interactive assumptions.
+      OM_DEV_AUTO_OPEN: '0',
+      FORCE_COLOR: '0',
+    },
+  })
+  fs.closeSync(outFd)
+  child.unref()
+  fs.writeFileSync(runStatePath(repoRoot), JSON.stringify({ pid: child.pid, startedAt: new Date().toISOString(), args: devArgs, logFile }, null, 2))
+  log(`✅ Dev runtime started in the background (pid ${child.pid}).`)
+  log(`   logs:   ${path.relative(repoRoot, logFile)}  (or \`logs --follow\`)`)
+  return child.pid
+}
+
+function killTree(pid) {
+  if (process.platform === 'win32') {
+    // Windows never propagates signals to grandchildren — kill the whole tree.
+    spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
+    return
+  }
+  // detached:true made the child a process-group leader; signal the group so
+  // yarn -> turbo -> next descendants all get SIGTERM.
+  try {
+    process.kill(-pid, 'SIGTERM')
+  } catch {
+    try {
+      process.kill(pid, 'SIGTERM')
+    } catch {
+      // already gone
+    }
+  }
+}
+
+export async function stopDetached(repoRoot, { log = console.log, graceMs = 8000 } = {}) {
+  const state = readRunState(repoRoot)
+  if (!state || !isPidAlive(state.pid)) {
+    if (state) fs.rmSync(runStatePath(repoRoot), { force: true })
+    log('ℹ️ No detached dev runtime is running.')
+    return true
+  }
+  log(`Stopping dev runtime (pid ${state.pid}) ...`)
+  killTree(state.pid)
+  const deadline = Date.now() + graceMs
+  while (Date.now() < deadline && isPidAlive(state.pid)) {
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+  if (isPidAlive(state.pid) && process.platform !== 'win32') {
+    try {
+      process.kill(-state.pid, 'SIGKILL')
+    } catch {
+      // gone
+    }
+  }
+  const stopped = !isPidAlive(state.pid)
+  if (stopped) {
+    fs.rmSync(runStatePath(repoRoot), { force: true })
+    log('✅ Dev runtime stopped.')
+  } else {
+    log(`❌ Process ${state.pid} survived SIGKILL — inspect it manually.`)
+  }
+  return stopped
+}
+
+async function fetchJson(url, timeoutMs = 3000) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) })
+    if (!response.ok) return null
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
+async function probeHttp(url, timeoutMs = 3000) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) })
+    return response.ok
+  } catch {
+    return false
+  }
+}
+
+export async function collectStatus(repoRoot, { runCompose }) {
+  const ports = resolveStackPorts(repoRoot)
+  const urls = stackUrls(ports)
+  const state = readRunState(repoRoot)
+  const detachedAlive = state ? isPidAlive(state.pid) : false
+
+  const [appUp, mcpUp, opencodeUp, splash] = await Promise.all([
+    probeHttp(urls.app),
+    probeHttp(urls.mcpHealth),
+    probeHttp(urls.opencodeHealth),
+    fetchJson(`${urls.splash}/status`),
+  ])
+
+  let containers = []
+  try {
+    const psResult = runCompose(repoRoot, ['ps', '--format', 'json'], { stdio: 'pipe' })
+    const { parseComposePsOutput } = await import('./compose.mjs')
+    containers = parseComposePsOutput(psResult.stdout).map((entry) => ({
+      service: entry.Service ?? entry.Name ?? 'unknown',
+      state: entry.State ?? 'unknown',
+      health: entry.Health ?? '',
+    }))
+  } catch {
+    containers = []
+  }
+
+  return { ports, urls, detached: state && detachedAlive ? state : null, appUp, mcpUp, opencodeUp, splash, containers }
+}
+
+export function printStatus(status, { log = console.log } = {}) {
+  log('')
+  log(color.bold('Open Mercato — stack status'))
+  log('')
+  const flag = (up) => (up ? `${icons.ok} up  ` : `${icons.fail} down`)
+  log(`  app        ${flag(status.appUp)}   ${color.cyan(status.urls.app)}`)
+  log(`  mcp        ${flag(status.mcpUp)}   ${color.cyan(status.urls.mcpHealth)}`)
+  log(`  opencode   ${flag(status.opencodeUp)}   ${color.cyan(status.urls.opencodeHealth)}`)
+  if (status.detached) log(`  supervisor ${icons.ok} detached (pid ${status.detached.pid}, since ${status.detached.startedAt})`)
+  else log(`  supervisor ${icons.info} not detached (foreground \`yarn dev\` or stopped)`)
+  if (status.splash?.phase || status.splash?.activity) {
+    log(`  runtime    ${status.splash.phase ?? ''}${status.splash.activity ? ` — ${status.splash.activity}` : ''}`)
+  }
+  log('')
+  if (status.containers.length === 0) {
+    log(`  containers: none running ${color.dim('(start them with `up`)')}`)
+  } else {
+    for (const container of status.containers) {
+      const health = container.health ? ` (${container.health})` : ''
+      const healthy = container.state === 'running' && (!container.health || container.health === 'healthy')
+      log(`  container  ${healthy ? icons.ok : icons.warn} ${container.service.padEnd(14)} ${container.state}${health}`)
+    }
+  }
+  log('')
+}
+
+export function tailLogs(repoRoot, { follow = false, lines = 60, log = console.log } = {}) {
+  const logDir = path.join(repoRoot, DEV_LOG_DIR)
+  let files = []
+  try {
+    files = fs.readdirSync(logDir)
+      .filter((name) => name.endsWith('.log'))
+      .map((name) => ({ name, file: path.join(logDir, name), mtime: fs.statSync(path.join(logDir, name)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime)
+  } catch {
+    files = []
+  }
+  if (files.length === 0) {
+    log(`ℹ️ No logs yet under ${path.relative(repoRoot, logDir)} — start the stack first.`)
+    return
+  }
+  const newest = files[0]
+  const printTail = (fromSize = null) => {
+    const content = fs.readFileSync(newest.file, 'utf8')
+    const slice = fromSize === null
+      ? content.split('\n').slice(-lines).join('\n')
+      : content.slice(fromSize)
+    if (slice.trim()) log(slice.replace(/\n$/, ''))
+    return content.length
+  }
+  log(`── ${path.relative(repoRoot, newest.file)} ──`)
+  let size = printTail()
+  if (!follow) return
+  fs.watchFile(newest.file, { interval: 500 }, () => {
+    size = printTail(size)
+  })
+}

package/src/ui.mjs

@@ -0,0 +1,122 @@
+// Console UX for the starter: colors, banner, staged progress, spinners.
+// Node stdlib only. Honors NO_COLOR and degrades cleanly when not a TTY
+// (CI logs get plain, timestamped lines instead of animations).
+
+const isTty = Boolean(process.stdout.isTTY)
+const colorEnabled = isTty && !process.env.NO_COLOR && process.env.TERM !== 'dumb'
+
+function paint(code) {
+  return (text) => (colorEnabled ? `[${code}m${text}` : String(text))
+}
+
+export const color = {
+  bold: paint('1'),
+  dim: paint('2'),
+  red: paint('31'),
+  green: paint('32'),
+  yellow: paint('33'),
+  blue: paint('34'),
+  magenta: paint('35'),
+  cyan: paint('36'),
+}
+
+// The Open Mercato two-tone wordmark (carried over from the retired Windows
+// launcher). Pure 7-bit ASCII on purpose: conhost and OEM code pages on
+// managed Windows machines mangle box-drawing characters.
+const LOGO_LEFT = [
+  '  ___  ____  _____ _   _ ',
+  ' / _ \\|  _ \\| ____| \\ | |',
+  '| | | | |_) |  _| |  \\| |',
+  '| |_| |  __/| |___| |\\  |',
+  ' \\___/|_|   |_____|_| \\_|',
+]
+
+const LOGO_RIGHT = [
+  ' __  __ _____ ____   ____    _  _____ ___',
+  '|  \\/  | ____|  _ \\ / ___|  / \\|_   _/ _ \\',
+  '| |\\/| |  _| | |_) | |     / _ \\ | || | | |',
+  '| |  | | |___|  _ <| |___ / ___ \\| || |_| |',
+  '|_|  |_|_____|_| \\_\\\\____/_/   \\_\\_| \\___/',
+]
+
+export function printBanner(subtitle, { log = console.log } = {}) {
+  log('')
+  for (let index = 0; index < LOGO_LEFT.length; index++) {
+    log(`   ${color.dim(color.cyan(LOGO_LEFT[index]))}  ${color.cyan(LOGO_RIGHT[index])}`)
+  }
+  log('')
+  if (subtitle) log(color.dim(`   ${subtitle}`))
+  log('')
+}
+
+export function stepHeader(index, total, title, expectation, { log = console.log } = {}) {
+  log('')
+  log(`${color.bold(color.blue(`── Step ${index}/${total}`))} ${color.bold(title)}`)
+  if (expectation) log(color.dim(`   Expected: ${expectation}`))
+}
+
+export const icons = {
+  ok: color.green('OK'),
+  warn: color.yellow('!!'),
+  fail: color.red('XX'),
+  info: color.cyan('--'),
+}
+
+export function statusLine(kind, message, { log = console.log } = {}) {
+  log(`   ${icons[kind] ?? icons.info} ${message}`)
+}
+
+// Framed remediation guide so "what do I do next" never drowns in output.
+export function guideBox(title, lines, { log = console.log } = {}) {
+  log('')
+  log(color.yellow(color.bold(`   ${title}`)))
+  for (const line of lines) {
+    log(line === '' ? '' : color.yellow(`   | `) + line)
+  }
+  log('')
+}
+
+const SPINNER_FRAMES = ['|', '/', '-', '\\']
+
+// Spinner for long waits that produce no streamed output. In non-TTY contexts
+// it prints the label once and then only meaningful updates via update().
+export function createSpinner(label) {
+  let frame = 0
+  let currentLabel = label
+  let timer = null
+  const startedAt = Date.now()
+
+  const render = () => {
+    const elapsed = Math.round((Date.now() - startedAt) / 1000)
+    process.stdout.write(`\r   ${color.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length])} ${currentLabel} ${color.dim(`(${elapsed}s)`)}   `)
+    frame += 1
+  }
+
+  if (isTty) {
+    timer = setInterval(render, 120)
+    render()
+  } else {
+    console.log(`   ... ${label}`)
+  }
+
+  return {
+    update(nextLabel) {
+      if (nextLabel === currentLabel) return
+      currentLabel = nextLabel
+      if (!isTty) console.log(`   ... ${nextLabel}`)
+    },
+    stop(kind = null, message = null) {
+      if (timer) {
+        clearInterval(timer)
+        process.stdout.write('\r' + ' '.repeat(100) + '\r')
+      }
+      if (kind && message) statusLine(kind, message)
+    },
+  }
+}
+
+export function formatDuration(ms) {
+  const totalSeconds = Math.round(ms / 1000)
+  if (totalSeconds < 60) return `${totalSeconds}s`
+  return `${Math.floor(totalSeconds / 60)}m ${totalSeconds % 60}s`
+}

package/src/waits.mjs

@@ -0,0 +1,102 @@
+import { parseComposePsOutput, runCompose } from './compose.mjs'
+import { createSpinner } from './ui.mjs'
+
+// Health-wait loops for the fully containerized mode, ported from the retired
+// Windows launcher (start-dev.ps1) so every platform gets the same sequencing:
+//   infra healthy -> app serving -> mcp + opencode healthy -> e2e MCP wiring.
+// Crash-loop detection beats compose healthchecks here: the generous
+// start_periods keep a wedged service "starting" for minutes, while a service
+// stuck in restarting/exited flips visibly within three polls.
+
+const POLL_INTERVAL_MS = 5000
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function serviceStates(repoRoot, composeFile) {
+  const ps = runCompose(repoRoot, ['ps', '-a', '--format', 'json'], { composeFile, stdio: 'pipe' })
+  const states = {}
+  for (const entry of parseComposePsOutput(ps.stdout ?? '')) {
+    if (!entry?.Service) continue
+    states[entry.Service] = { state: entry.State ?? 'unknown', health: entry.Health ?? '', exitCode: entry.ExitCode }
+  }
+  return states
+}
+
+function dumpServiceLogs(repoRoot, composeFile, service, log) {
+  log(`── last 40 log lines of '${service}' ──`)
+  runCompose(repoRoot, ['logs', '--tail', '40', service], { composeFile, stdio: 'inherit' })
+}
+
+export async function waitForHealthyServices(repoRoot, composeFile, services, { timeoutMs = 5 * 60 * 1000, log = console.log } = {}) {
+  const crashTicks = {}
+  const deadline = Date.now() + timeoutMs
+  const spinner = createSpinner(`waiting for ${services.join(', ')}`)
+  try {
+    while (Date.now() < deadline) {
+      const states = serviceStates(repoRoot, composeFile)
+      const pending = []
+      for (const service of services) {
+        const entry = states[service]
+        if (!entry) {
+          pending.push(`${service} (not created)`)
+          continue
+        }
+        const crashed = entry.state === 'restarting' || (entry.state === 'exited' && Number(entry.exitCode ?? 0) !== 0)
+        crashTicks[service] = crashed ? (crashTicks[service] ?? 0) + 1 : 0
+        if (crashTicks[service] >= 3) {
+          spinner.stop('fail', `Service '${service}' is crash-looping (${entry.state}).`)
+          dumpServiceLogs(repoRoot, composeFile, service, log)
+          return { ok: false, failed: service }
+        }
+        const healthy = entry.health ? entry.health === 'healthy' : entry.state === 'running'
+        if (!healthy) pending.push(`${service} (${entry.health || entry.state})`)
+      }
+      if (pending.length === 0) {
+        spinner.stop('ok', `${services.join(', ')} healthy`)
+        return { ok: true }
+      }
+      spinner.update(`waiting for ${pending.join(', ')}`)
+      await sleep(POLL_INTERVAL_MS)
+    }
+  } finally {
+    spinner.stop()
+  }
+  return { ok: false, failed: 'timeout' }
+}
+
+export async function waitForHttp(url, { timeoutMs = 10 * 60 * 1000, label = url, log = console.log, validate = null } = {}) {
+  const deadline = Date.now() + timeoutMs
+  let lastError = ''
+  const spinner = createSpinner(`waiting for ${label}`)
+  try {
+    while (Date.now() < deadline) {
+      try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(5000) })
+        if (response.ok) {
+          if (!validate) {
+            spinner.stop('ok', `${label} ready`)
+            return true
+          }
+          const body = await response.text()
+          if (validate(body)) {
+            spinner.stop('ok', `${label} ready`)
+            return true
+          }
+          lastError = 'endpoint up, validation pending'
+        } else {
+          lastError = `HTTP ${response.status}`
+        }
+      } catch (error) {
+        lastError = error?.cause?.code ?? error?.name ?? 'unreachable'
+      }
+      spinner.update(`waiting for ${label} (${lastError})`)
+      await sleep(POLL_INTERVAL_MS)
+    }
+  } finally {
+    spinner.stop()
+  }
+  log(`Timed out waiting for ${label} (${lastError})`)
+  return false
+}