@open-mercato/starter 0.6.5 → 0.7.1-develop.7195.1.b5efd1d51a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/starter",
-  "version": "0.6.5",
+  "version": "0.7.1-develop.7195.1.b5efd1d51a",
   "description": "One-command, cross-platform bootstrap for Open Mercato dev environments: prerequisite doctor, corporate TLS trust, idempotent setup steps, and a supervised hybrid or fully containerized stack.",
   "license": "MIT",
   "type": "module",
@@ -23,5 +23,6 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/starter"
-  }
-}
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/starter.test.mjs

@@ -11,8 +11,10 @@ import { DEFAULT_OPENCODE_BASE_IMAGE, DEFAULT_PORTS, resolveStackPorts } from '.
 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'
+import { StepBlocked, buildToolchainStep, clearConvergenceState, databaseIsInitialized, listMigrationModules, migrationsFingerprint, probePostgresCredentials, readAppliedMigrationModules, resolveOpencodeBaseImage, runSteps } from '../steps.mjs'
+import { ensureEnvFiles } from '../env-setup.mjs'
+import { removeLeftoverComposeResources } from '../infra.mjs'
+import { checkBuildToolchain, defenderExclusionCovers, detectHostGateway, hostIpCandidates } from '../doctor.mjs'
 
 function makeTempDir(prefix) {
   return fs.mkdtempSync(path.join(os.tmpdir(), prefix))
@@ -357,3 +359,176 @@ test('buildToolchainStep warns instead of blocking when the workspace install al
   fs.writeFileSync(path.join(repo, 'yarn.lock'), 'changed\n')
   await assert.rejects(() => buildToolchainStep.check(ctx), (error) => error instanceof StepBlocked)
 })
+
+test('removeLeftoverComposeResources sweeps fixed-name containers and volumes down cannot see', () => {
+  const calls = []
+  const runComposeImpl = () => ({
+    status: 0,
+    stdout: JSON.stringify({
+      services: { postgres: { container_name: 'mercato-postgres' } },
+      volumes: { postgres_data: { name: 'mercato-postgres-data' } },
+    }),
+  })
+  const runCaptureImpl = (command, args) => {
+    const key = args.join(' ')
+    calls.push(key)
+    if (key === 'ps -a --format {{.Names}}') return { status: 0, stdout: 'mercato-postgres\nunrelated-container\n' }
+    if (key === 'volume ls --format {{.Name}}') return { status: 0, stdout: 'mercato-postgres-data\nunrelated-volume\n' }
+    return { status: 0, stdout: '' }
+  }
+  const clean = removeLeftoverComposeResources('/repo', { runComposeImpl, runCaptureImpl, log: () => {}, warn: () => {} })
+  assert.equal(clean, true)
+  assert.ok(calls.includes('rm -f mercato-postgres'))
+  assert.ok(calls.includes('volume rm mercato-postgres-data'))
+  assert.ok(!calls.some((key) => key.includes('unrelated')))
+})
+
+test('removeLeftoverComposeResources reports in-use volumes with their holders and returns false', () => {
+  const warnings = []
+  const runComposeImpl = () => ({
+    status: 0,
+    stdout: JSON.stringify({ services: {}, volumes: { postgres_data: { name: 'mercato-postgres-data' } } }),
+  })
+  const runCaptureImpl = (command, args) => {
+    const key = args.join(' ')
+    if (key === 'ps -a --format {{.Names}}') return { status: 0, stdout: '' }
+    if (key === 'volume ls --format {{.Name}}') return { status: 0, stdout: 'mercato-postgres-data\n' }
+    if (key === 'volume rm mercato-postgres-data') return { status: 1, stderr: 'volume is in use' }
+    if (key.startsWith('ps -a --filter')) return { status: 0, stdout: 'old-checkout-postgres\n' }
+    return { status: 0, stdout: '' }
+  }
+  const clean = removeLeftoverComposeResources('/repo', { runComposeImpl, runCaptureImpl, log: () => {}, warn: (line) => warnings.push(line) })
+  assert.equal(clean, false)
+  assert.ok(warnings.some((line) => line.includes('old-checkout-postgres')))
+})
+
+test('detectHostGateway prefers the default pin, falls back to host IPs, and reports unreachable', () => {
+  const pinOk = detectHostGateway(3001, { probeImpl: () => ({ ran: true, mcpAnswered: true, output: '{"status":"ok"}' }), candidates: [] })
+  assert.deepEqual(pinOk, { status: 'pin-ok' })
+
+  const probes = []
+  const secondCandidateWins = detectHostGateway(3001, {
+    probeImpl: (port, addHost) => {
+      probes.push(addHost)
+      return { ran: true, mcpAnswered: addHost === 'host.docker.internal:172.20.0.1', output: '' }
+    },
+    candidates: ['192.168.1.10', '172.20.0.1'],
+  })
+  assert.deepEqual(secondCandidateWins, { status: 'use-ip', ip: '172.20.0.1' })
+  assert.deepEqual(probes, ['host.docker.internal:host-gateway', 'host.docker.internal:192.168.1.10', 'host.docker.internal:172.20.0.1'])
+
+  const unreachable = detectHostGateway(3001, { probeImpl: () => ({ ran: true, mcpAnswered: false, output: '' }), candidates: ['192.168.1.10'] })
+  assert.deepEqual(unreachable, { status: 'unreachable' })
+
+  const pullBlocked = detectHostGateway(3001, {
+    probeImpl: () => ({ ran: true, mcpAnswered: false, output: 'Unable to find image busybox:1.37 locally' }),
+    candidates: ['192.168.1.10'],
+  })
+  assert.deepEqual(pullBlocked, { status: 'skip' })
+})
+
+test('hostIpCandidates lists external IPv4s with WSL adapters first', () => {
+  const candidates = hostIpCandidates({
+    'Ethernet': [{ family: 'IPv4', internal: false, address: '192.168.1.10' }],
+    'vEthernet (WSL (Hyper-V firewall))': [{ family: 'IPv4', internal: false, address: '172.20.0.1' }],
+    'Loopback Pseudo-Interface 1': [{ family: 'IPv4', internal: true, address: '127.0.0.1' }],
+  })
+  assert.deepEqual(candidates, ['172.20.0.1', '192.168.1.10'])
+})
+
+test('defenderExclusionCovers matches the repo or an ancestor, case-insensitively', () => {
+  assert.equal(defenderExclusionCovers('C:\\dev\\open-mercato', ['C:\\dev']), true)
+  assert.equal(defenderExclusionCovers('C:\\dev\\open-mercato', ['c:\\DEV\\open-mercato\\']), true)
+  assert.equal(defenderExclusionCovers('C:\\dev\\open-mercato', ['C:/dev/open-mercato']), true)
+  assert.equal(defenderExclusionCovers('C:\\dev\\open-mercato', ['C:\\dev\\open']), false)
+  assert.equal(defenderExclusionCovers('C:\\dev\\open-mercato', ['D:\\other', null, '']), false)
+  assert.equal(defenderExclusionCovers('C:\\dev\\open-mercato', []), false)
+})
+
+function makeFakeAppRepo() {
+  const repo = makeFakeRepo()
+  fs.mkdirSync(path.join(repo, 'apps', 'mercato'), { recursive: true })
+  fs.writeFileSync(
+    path.join(repo, 'apps', 'mercato', '.env.example'),
+    'DATABASE_URL=postgres://postgres:postgres@localhost:5432/open-mercato\nJWT_SECRET=change-me\nAUTH_SECRET=change-me\nLOOKUP_HASH_PEPPER=change-me\n',
+  )
+  return repo
+}
+
+test('ensureEnvFiles writes the documented dev credentials and threads them into DATABASE_URL', () => {
+  const repo = makeFakeAppRepo()
+  ensureEnvFiles(repo, { log: () => {}, warn: () => {} })
+  assert.equal(readEnvValue(path.join(repo, '.env'), 'POSTGRES_PASSWORD'), 'postgres')
+  assert.equal(readEnvValue(path.join(repo, '.env'), 'OM_INIT_SUPERADMIN_PASSWORD'), 'secret')
+  assert.equal(readEnvValue(path.join(repo, 'apps', 'mercato', '.env'), 'OM_INIT_SUPERADMIN_PASSWORD'), 'secret')
+  // The .env.example default says localhost, which breaks on Windows (::1).
+  assert.equal(
+    readEnvValue(path.join(repo, 'apps', 'mercato', '.env'), 'DATABASE_URL'),
+    'postgres://postgres:postgres@127.0.0.1:5432/open-mercato',
+  )
+})
+
+test('ensureEnvFiles never overwrites credentials already present in .env', () => {
+  const repo = makeFakeAppRepo()
+  fs.writeFileSync(path.join(repo, '.env'), 'POSTGRES_PASSWORD=custom-pass\nOM_INIT_SUPERADMIN_PASSWORD=custom-admin\n')
+  ensureEnvFiles(repo, { log: () => {}, warn: () => {} })
+  assert.equal(readEnvValue(path.join(repo, '.env'), 'POSTGRES_PASSWORD'), 'custom-pass')
+  assert.equal(readEnvValue(path.join(repo, '.env'), 'OM_INIT_SUPERADMIN_PASSWORD'), 'custom-admin')
+  assert.equal(readEnvValue(path.join(repo, 'apps', 'mercato', '.env'), 'OM_INIT_SUPERADMIN_PASSWORD'), 'custom-admin')
+  assert.equal(
+    readEnvValue(path.join(repo, 'apps', 'mercato', '.env'), 'DATABASE_URL'),
+    'postgres://postgres:custom-pass@127.0.0.1:5432/open-mercato',
+  )
+})
+
+test('probePostgresCredentials probes the container IP (not loopback) and classifies password mismatches', () => {
+  const repo = makeFakeRepo()
+  fs.mkdirSync(path.join(repo, 'apps', 'mercato'), { recursive: true })
+  fs.writeFileSync(
+    path.join(repo, 'apps', 'mercato', '.env'),
+    "DATABASE_URL=postgres://app:s3c%40ret@127.0.0.1:5432/open-mercato\n",
+  )
+  const ctx = { repoRoot: repo }
+
+  let seenArgs
+  const okCompose = (root, args) => {
+    seenArgs = args
+    return { status: 0, stdout: '1\n', stderr: '' }
+  }
+  assert.equal(probePostgresCredentials(ctx, { runComposeImpl: okCompose }), 'ok')
+  // Credentials ride in -e env vars (URL-decoded), never in the shell string.
+  assert.ok(seenArgs.includes('PGPASSWORD=s3c@ret'))
+  assert.ok(seenArgs.includes('PGUSER=app'))
+  const shellCmd = seenArgs[seenArgs.length - 1]
+  assert.match(shellCmd, /hostname -i/)
+  assert.doesNotMatch(shellCmd, /127\.0\.0\.1/)
+  assert.doesNotMatch(shellCmd, /s3c@ret/)
+
+  const authFailCompose = () => ({ status: 2, stdout: '', stderr: 'psql: error: FATAL:  password authentication failed for user "app"' })
+  assert.equal(probePostgresCredentials(ctx, { runComposeImpl: authFailCompose }), 'auth-failed')
+
+  const downCompose = () => ({ status: 1, stdout: '', stderr: 'service "postgres" is not running' })
+  assert.equal(probePostgresCredentials(ctx, { runComposeImpl: downCompose }), null)
+
+  const throwingCompose = () => {
+    throw new Error('docker compose could not be executed')
+  }
+  assert.equal(probePostgresCredentials(ctx, { runComposeImpl: throwingCompose }), null)
+
+  // No app .env at all: no verdict, never a block.
+  assert.equal(probePostgresCredentials({ repoRoot: makeFakeRepo() }, { runComposeImpl: okCompose }), null)
+})
+
+test('databaseIsInitialized reads the seeded-users probe and tolerates a missing table or a down probe', () => {
+  const repo = makeFakeRepo()
+  fs.mkdirSync(path.join(repo, 'apps', 'mercato'), { recursive: true })
+  fs.writeFileSync(path.join(repo, 'apps', 'mercato', '.env'), 'DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/open-mercato\n')
+  const ctx = { repoRoot: repo }
+
+  assert.equal(databaseIsInitialized(ctx, { runComposeImpl: () => ({ status: 0, stdout: '3\n' }) }), true)
+  assert.equal(databaseIsInitialized(ctx, { runComposeImpl: () => ({ status: 0, stdout: '0\n' }) }), false)
+  // to_regclass guard returns -1 when the users table does not exist yet.
+  assert.equal(databaseIsInitialized(ctx, { runComposeImpl: () => ({ status: 0, stdout: '-1\n' }) }), false)
+  assert.equal(databaseIsInitialized(ctx, { runComposeImpl: () => ({ status: 1, stdout: '' }) }), null)
+  assert.equal(databaseIsInitialized(ctx, { runComposeImpl: () => { throw new Error('down') } }), null)
+})

package/src/cli.mjs

@@ -22,10 +22,11 @@ import path from 'node:path'
 import readline from 'node:readline'
 
 import { detectDocker, resolveRepoRoot, runCompose, runStreamingSync, spawnStreaming } from './compose.mjs'
+import { readEnvValue } from './env-file.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 { infraDown, infraUp, ensureMcpSharedDir, removeLeftoverComposeResources } 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'
@@ -187,7 +188,7 @@ async function commandUp(flags) {
   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(`  Superadmin sign-in: ${readEnvValue(path.join(repoRoot, '.env'), 'OM_INIT_SUPERADMIN_EMAIL')?.trim() || 'superadmin@acme.com'} / ${readEnvValue(path.join(repoRoot, '.env'), 'OM_INIT_SUPERADMIN_PASSWORD')?.trim() || 'secret'}`))
   console.log(color.dim('  Stop: Ctrl+C (infra containers keep running; `stop` shuts everything down)'))
   console.log('')
 
@@ -242,7 +243,9 @@ async function commandUpDocker(ctx, flags) {
   }
   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)')}`)
+  const superEmail = readEnvValue(path.join(repoRoot, '.env'), 'OM_INIT_SUPERADMIN_EMAIL')?.trim() || 'superadmin@acme.com'
+  const superPassword = readEnvValue(path.join(repoRoot, '.env'), 'OM_INIT_SUPERADMIN_PASSWORD')?.trim() || 'secret'
+  console.log(`  App:      ${color.cyan(urls.app)}  ${color.dim(`(sign in: ${superEmail} / ${superPassword})`)}`)
   console.log(`  OpenCode: ${color.cyan(`http://127.0.0.1:${ports.opencode}`)}`)
   console.log(color.dim('  Manage it with the stop / status / logs subcommands.'))
 }
@@ -295,12 +298,30 @@ async function commandReset(flags) {
     console.log('Aborted.')
     return
   }
+  // Kept env files can disagree with the recreated database (a stale
+  // POSTGRES_PASSWORD / DATABASE_URL from a previous volume), but they also
+  // hold the pasted LLM provider API key — so removal stays an explicit
+  // opt-in and --yes alone never deletes them.
+  const removeEnvFiles = flags.yes
+    ? false
+    : await confirm('Also remove the generated env files (.env, apps/mercato/.env)? They are regenerated with dev defaults on the next run, but the saved LLM API key goes with them.', flags)
   await stopDetached(repoRoot)
   const docker = detectDocker()
   if (docker.ok) {
-    runCompose(repoRoot, ['down', '--volumes'], { composeFile: mode === 'docker' ? FULLAPP_DEV_COMPOSE_FILE : undefined })
+    const composeFile = mode === 'docker' ? FULLAPP_DEV_COMPOSE_FILE : undefined
+    runCompose(repoRoot, ['down', '--volumes'], { composeFile })
+    // down only sees THIS project's resources; fixed-name containers/volumes
+    // created by another checkout of the repo survive it — sweep by name.
+    if (!removeLeftoverComposeResources(repoRoot, { composeFile })) {
+      console.warn('⚠️ Some volumes could not be removed — the next run would reuse the old data. Fix the items above and re-run reset.')
+    }
   }
   fs.rmSync(path.join(repoRoot, STARTER_STATE_DIR), { recursive: true, force: true })
+  if (removeEnvFiles) {
+    fs.rmSync(path.join(repoRoot, '.env'), { force: true })
+    fs.rmSync(path.join(repoRoot, 'apps', 'mercato', '.env'), { force: true })
+    console.log('   removed .env and apps/mercato/.env')
+  }
   console.log('✅ Reset complete. Run the starter again for a fresh environment.')
 }
 

package/src/doctor.mjs

@@ -313,6 +313,60 @@ export function checkClonePath(repoRoot) {
   })
 }
 
+function normalizeWindowsPath(value) {
+  return String(value ?? '').trim().replace(/\//g, '\\').replace(/\\+$/, '').toLowerCase()
+}
+
+export function defenderExclusionCovers(repoRoot, exclusionPaths) {
+  const repo = normalizeWindowsPath(repoRoot)
+  if (!repo) return false
+  return (exclusionPaths ?? []).some((entry) => {
+    const exclusion = normalizeWindowsPath(entry)
+    if (!exclusion) return false
+    return repo === exclusion || repo.startsWith(`${exclusion}\\`)
+  })
+}
+
+// EPERM renames during compilation and slow installs are almost always
+// Defender's real-time scan holding a handle on freshly written files. The
+// bootstrap only adds an exclusion when it can elevate, so audit it here.
+// Non-admin sessions may see exclusions redacted ("N/A: Must be an
+// administrator…") — surfaced as an unverifiable warn, not a pass.
+export function checkDefenderExclusion(repoRoot) {
+  if (process.platform !== 'win32') return null
+  const script =
+    "$ErrorActionPreference='Stop'; try { $status = Get-MpComputerStatus; $prefs = Get-MpPreference; @{ rtp = [bool]$status.RealTimeProtectionEnabled; exclusions = @($prefs.ExclusionPath | ForEach-Object { [string]$_ }) } | ConvertTo-Json -Compress } catch { exit 1 }"
+  const output = commandOutput('powershell', ['-NoProfile', '-NonInteractive', '-Command', script])
+  if (!output) return null
+  let parsed
+  try {
+    parsed = JSON.parse(output.trim())
+  } catch {
+    return null
+  }
+  if (!parsed.rtp) {
+    return result('defender', 'Microsoft Defender', 'pass', 'real-time protection is off (or another security product manages this device)')
+  }
+  const exclusions = Array.isArray(parsed.exclusions) ? parsed.exclusions : []
+  if (defenderExclusionCovers(repoRoot, exclusions)) {
+    return result('defender', 'Microsoft Defender', 'pass', 'repo is excluded from real-time scanning')
+  }
+  const addCommand = `Add-MpPreference -ExclusionPath '${repoRoot.replace(/'/g, "''")}'`
+  const redacted = exclusions.some((entry) => /administrator/i.test(String(entry)))
+  return result(
+    'defender',
+    'Microsoft Defender',
+    'warn',
+    redacted
+      ? 'real-time protection is on and the exclusion list is hidden from non-admins — cannot verify this repo is excluded (unexcluded checkouts hit EPERM renames during builds and slow installs)'
+      : 'real-time protection is on with no exclusion for this repo — the scanner locks freshly written build output mid-rename (EPERM) and slows installs',
+    {
+      guide: [`Exclude the repo (elevated PowerShell): ${addCommand}`],
+      it: [`Microsoft Defender exclusion for the dev checkout:  ${addCommand}`],
+    },
+  )
+}
+
 // Verifies a container can reach a host port through host.docker.internal —
 // the linchpin of the hybrid topology (OpenCode container -> host MCP). Two
 // probes: (1) with the same extra_hosts pin compose.infra.yml uses (unless
@@ -333,6 +387,36 @@ function probeContainerToHost(mcpPort, addHost) {
   }
 }
 
+export function hostIpCandidates(interfaces = os.networkInterfaces()) {
+  const named = Object.entries(interfaces ?? {})
+  // WSL vEthernet adapters first — the usual winner on Rancher Desktop/WSL2.
+  named.sort(([a], [b]) => Number(/wsl/i.test(b)) - Number(/wsl/i.test(a)))
+  const ips = []
+  for (const [, addresses] of named) {
+    for (const address of addresses ?? []) {
+      const family = address?.family
+      if ((family === 'IPv4' || family === 4) && !address.internal) ips.push(address.address)
+    }
+  }
+  return [...new Set(ips)]
+}
+
+// Find a host.docker.internal mapping that actually reaches this machine:
+// the compose default pin first (correct on Docker Desktop and native Linux),
+// then every host IPv4. Callers must ensure something answers on mcpPort.
+export function detectHostGateway(mcpPort, { probeImpl = probeContainerToHost, candidates = hostIpCandidates() } = {}) {
+  const pinned = probeImpl(mcpPort, 'host.docker.internal:host-gateway')
+  if (!pinned.ran || /unable to find image|error response from daemon|cannot connect to the docker daemon/i.test(pinned.output ?? '')) {
+    return { status: 'skip' }
+  }
+  if (pinned.mcpAnswered) return { status: 'pin-ok' }
+  for (const ip of candidates) {
+    const probe = probeImpl(mcpPort, `host.docker.internal:${ip}`)
+    if (probe.mcpAnswered) return { status: 'use-ip', ip }
+  }
+  return { status: 'unreachable' }
+}
+
 export function checkContainerToHost(repoRoot, { mcpPort }) {
   const docker = detectDocker()
   if (!docker.ok) return null
@@ -387,6 +471,7 @@ export async function runDoctor(repoRoot, { company = null, stackRunning = false
     await checkTlsInterception(repoRoot),
     await checkPorts(repoRoot, { stackRunning }),
     checkClonePath(repoRoot),
+    checkDefenderExclusion(repoRoot),
   ]
   if (includeContainerProbe) checks.push(checkContainerToHost(repoRoot, { mcpPort: ports.mcp }))
   for (const custom of company?.checks ?? []) {

package/src/env-setup.mjs

@@ -1,31 +1,21 @@
 import fs from 'node:fs'
 import path from 'node:path'
-import { spawnSync } from 'node:child_process'
 
 import { addEnvValue, readEnvValue, replaceEnvLine, uncommentEnvLine, writeEnvFileText } from './env-file.mjs'
 import { secretFingerprint, secretHex } from './secrets.mjs'
 
 // Node port of the Windows launcher's Initialize-EnvFiles: fill-missing-only,
-// secrets are generated once and never overwritten on re-runs, and postgres
-// credentials are only generated while no initialized data volume exists yet
-// (changing them afterwards would break auth against the data inside it).
-
-function postgresVolumeExists() {
-  const result = spawnSync('docker', ['volume', 'ls', '--format', '{{.Name}}'], { encoding: 'utf8' })
-  if (result.error || result.status !== 0) return false
-  return String(result.stdout ?? '')
-    .split('\n')
-    .map((line) => line.trim())
-    .includes('mercato-postgres-data')
-}
+// machine-local secrets are generated once and never overwritten on re-runs.
+// Postgres and superadmin credentials deliberately stay on the documented dev
+// defaults (postgres/postgres, superadmin@acme.com/secret): the data volume
+// outlives .env, so generated credentials drift from the volume on every
+// re-clone or env regeneration, and the documented login stops working.
 
 export function ensureEnvFiles(repoRoot, { log = console.log, warn = console.warn, extraDefaults = {} } = {}) {
   const rootEnv = path.join(repoRoot, '.env')
   const appEnvExample = path.join(repoRoot, 'apps', 'mercato', '.env.example')
   const appEnv = path.join(repoRoot, 'apps', 'mercato', '.env')
 
-  const volumeExists = postgresVolumeExists()
-
   if (!fs.existsSync(rootEnv)) {
     writeEnvFileText(rootEnv, '# Open Mercato compose environment (generated by the hybrid starter)\n')
     log(`Created ${rootEnv}`)
@@ -50,22 +40,11 @@ export function ensureEnvFiles(repoRoot, { log = console.log, warn = console.war
   for (const [key, value] of Object.entries(extraDefaults)) {
     setValue(key, value)
   }
-
-  let postgresPassword = readEnvValue(rootEnv, 'POSTGRES_PASSWORD')?.trim() || ''
-  if (volumeExists) {
-    if (readEnvValue(rootEnv, 'OM_INIT_SUPERADMIN_PASSWORD') === null) {
-      warn('Existing postgres volume detected — keeping compose default credentials. Remove the mercato-postgres-data volume for a clean slate.')
-    }
-    if (!postgresPassword) {
-      warn('Existing postgres volume but no POSTGRES_PASSWORD in .env — the app will try the compose default (postgres), which only works if the volume was created with it.')
-    }
-  } else {
-    setSecret('OM_INIT_SUPERADMIN_PASSWORD', secretHex(8))
-    if (!postgresPassword) {
-      postgresPassword = secretHex(16)
-      setSecret('POSTGRES_PASSWORD', postgresPassword)
-    }
-  }
+  // Dev-default credentials, not secrets (see header). Set after extraDefaults
+  // so a company preset — like anything already in .env — wins.
+  setValue('OM_INIT_SUPERADMIN_PASSWORD', 'secret')
+  const postgresPassword = readEnvValue(rootEnv, 'POSTGRES_PASSWORD')?.trim() || 'postgres'
+  setValue('POSTGRES_PASSWORD', postgresPassword)
   // NOTE: MCP_SERVER_API_KEY is intentionally NOT generated here. `yarn dev`
   // provisions a real DB-backed key into .mercato/mcp-shared; a random env
   // value would shadow it and break OpenCode -> MCP authentication.
@@ -76,15 +55,13 @@ export function ensureEnvFiles(repoRoot, { log = console.log, warn = console.war
       content = replaceEnvLine(content, 'JWT_SECRET', jwtSecret)
       content = replaceEnvLine(content, 'AUTH_SECRET', secretHex(32))
       content = replaceEnvLine(content, 'LOOKUP_HASH_PEPPER', secretHex(16))
-      if (postgresPassword) {
-        // 127.0.0.1, never `localhost`: on modern Windows localhost resolves
-        // to ::1 first while the published container ports listen on IPv4.
-        content = replaceEnvLine(
-          content,
-          'DATABASE_URL',
-          `postgres://postgres:${postgresPassword}@127.0.0.1:5432/open-mercato`,
-        )
-      }
+      // 127.0.0.1, never `localhost`: on modern Windows localhost resolves
+      // to ::1 first while the published container ports listen on IPv4.
+      content = replaceEnvLine(
+        content,
+        'DATABASE_URL',
+        `postgres://postgres:${postgresPassword}@127.0.0.1:5432/open-mercato`,
+      )
       // The hybrid starter runs a meilisearch container, so point the app at it
       // (the example ships these commented out).
       content = uncommentEnvLine(content, 'MEILISEARCH_HOST', 'http://127.0.0.1:7700')
@@ -111,7 +88,7 @@ export function ensureEnvFiles(repoRoot, { log = console.log, warn = console.war
       log('  set OM_INIT_SUPERADMIN_EMAIL in apps/mercato/.env')
     }
     if (superPassword && addEnvValue(appEnv, 'OM_INIT_SUPERADMIN_PASSWORD', superPassword)) {
-      log('  set OM_INIT_SUPERADMIN_PASSWORD (sha256 …) in apps/mercato/.env')
+      log('  set OM_INIT_SUPERADMIN_PASSWORD in apps/mercato/.env')
     }
   }
 

package/src/infra.mjs

@@ -7,7 +7,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { detectDocker, resolveRepoRoot, runCompose } from './compose.mjs'
+import { detectDocker, resolveRepoRoot, runCompose, runCaptureSync } from './compose.mjs'
 
 export function ensureMcpSharedDir(repoRoot) {
   // Pre-create the bind-mount source so dockerd never creates it root-owned
@@ -35,6 +35,62 @@ export function infraDown(repoRoot, { volumes = false } = {}) {
   return runCompose(repoRoot ?? resolveRepoRoot(), ['down', ...(volumes ? ['--volumes'] : [])]).status ?? 1
 }
 
+export function composeResourceNames(repoRoot, { composeFile, runComposeImpl = runCompose } = {}) {
+  const config = runComposeImpl(repoRoot, ['config', '--format', 'json'], { composeFile, stdio: 'pipe' })
+  if ((config.status ?? 1) !== 0) return { containers: [], volumes: [] }
+  try {
+    const parsed = JSON.parse(String(config.stdout ?? ''))
+    return {
+      containers: Object.values(parsed.services ?? {}).map((service) => service?.container_name).filter(Boolean),
+      volumes: Object.values(parsed.volumes ?? {}).map((volume) => volume?.name).filter(Boolean),
+    }
+  } catch {
+    return { containers: [], volumes: [] }
+  }
+}
+
+// `docker compose down --volumes` only removes resources labeled with the
+// CURRENT project (named after the checkout directory). The fixed
+// container_name/volume names in the compose files mean a second checkout of
+// this repo reuses resources created by the first — down skips those
+// silently, so a reset would leave the old database volume (and its
+// incompatible secrets) alive. Sweep leftovers by their fixed names.
+export function removeLeftoverComposeResources(repoRoot, { composeFile, runComposeImpl = runCompose, runCaptureImpl = runCaptureSync, log = console.log, warn = console.warn } = {}) {
+  const { containers, volumes } = composeResourceNames(repoRoot, { composeFile, runComposeImpl })
+  const listNames = (args) => {
+    const run = runCaptureImpl('docker', args)
+    if (run.error || (run.status ?? 1) !== 0) return new Set()
+    return new Set(String(run.stdout ?? '').split('\n').map((line) => line.trim()).filter(Boolean))
+  }
+
+  const existingContainers = listNames(['ps', '-a', '--format', '{{.Names}}'])
+  for (const name of containers) {
+    if (!existingContainers.has(name)) continue
+    const removed = runCaptureImpl('docker', ['rm', '-f', name])
+    if ((removed.status ?? 1) === 0) log(`   removed leftover container ${name} (created by another checkout)`)
+    else warn(`   could not remove container ${name}: ${String(removed.stderr ?? '').trim()}`)
+  }
+
+  let clean = true
+  const existingVolumes = listNames(['volume', 'ls', '--format', '{{.Name}}'])
+  for (const name of volumes) {
+    if (!existingVolumes.has(name)) continue
+    const removed = runCaptureImpl('docker', ['volume', 'rm', name])
+    if ((removed.status ?? 1) === 0) {
+      log(`   removed leftover volume ${name} (created by another checkout)`)
+      continue
+    }
+    clean = false
+    warn(`   could not remove volume ${name}: ${String(removed.stderr ?? '').trim()}`)
+    const holders = runCaptureImpl('docker', ['ps', '-a', '--filter', `volume=${name}`, '--format', '{{.Names}}'])
+    const holderNames = String(holders.stdout ?? '').split('\n').map((line) => line.trim()).filter(Boolean)
+    if (holderNames.length > 0) {
+      warn(`   still mounted by: ${holderNames.join(', ')} — remove them (docker rm -f ${holderNames.join(' ')}) and re-run reset`)
+    }
+  }
+  return clean
+}
+
 function main() {
   const args = process.argv.slice(2)
   const action = args[0]

package/src/steps.mjs

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -7,9 +7,9 @@ import { detectDocker, parseComposePsOutput, runCaptureSync, runCompose, runStre
 import { captureInterceptionCas, findVendorCaBundles, harvestWindowsStoreCas, hostTrustEnv, probeTlsInterception, provisionDockerCerts, provisionRancherDesktopCa, summarizeProbeResults, writeCaBundle } from './certs.mjs'
 import { loadCompanyConfig, resolveCompanyCertBundles } from './company.mjs'
 import { CAPTURED_CA_BUNDLE, DEFAULT_OPENCODE_BASE_IMAGE, OPENCODE_SERVICE_IMAGE, STARTER_STATE_DIR, resolveStackPorts } from './constants.mjs'
-import { checkBuildToolchain, checkContainerRuntime, checkGit, checkNodeVersion, checkWsl2 } from './doctor.mjs'
+import { checkBuildToolchain, checkContainerRuntime, checkGit, checkNodeVersion, checkWsl2, detectHostGateway } from './doctor.mjs'
 import { ensureEnvFiles } from './env-setup.mjs'
-import { readEnvValue } from './env-file.mjs'
+import { addEnvValue, readEnvValue } from './env-file.mjs'
 import { ensureMcpSharedDir, infraUp } from './infra.mjs'
 import { ensureLlmProvider } from './providers.mjs'
 import { color, formatDuration, guideBox, statusLine, stepHeader } from './ui.mjs'
@@ -109,7 +109,7 @@ function walkMigrationModules(repoRoot) {
 }
 
 function listMigrationFiles(repoRoot) {
-  return [...walkMigrationModules(repoRoot).values()].flat().sort()
+  return [...walkMigrationModules(repoRoot).values()].flat().sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
 }
 
 export function listMigrationModules(repoRoot) {
@@ -152,6 +152,71 @@ export function readAppliedMigrationModules(ctx, { runComposeImpl = runCompose }
   )
 }
 
+// The compose healthcheck (pg_isready) never authenticates, so an existing
+// data volume whose password no longer matches the env files still reports
+// healthy — the volume keeps the password it was initialized with, and the
+// run would only die later inside `yarn db:migrate` with a raw FATAL.
+//
+// The postgres image trusts loopback (pg_hba: `host all all 127.0.0.1/32
+// trust`) and only demands a password via the catch-all
+// `host all all all scram-sha-256` rule — i.e. for NON-loopback source
+// addresses. The app hits that rule because it arrives from the docker
+// gateway, so the probe must too: connect to the container's OWN routable IP
+// (hostname -i), not 127.0.0.1, or the check trusts every password. User and
+// password go through `-e` env vars (libpq reads PGUSER/PGPASSWORD) so they
+// never enter the shell string — no injection even with `'`/`$` in a value.
+// Returns 'ok', 'auth-failed', or null when no verdict is possible (URL
+// unparsable, compose unavailable, postgres not managed here).
+export function probePostgresCredentials(ctx, { runComposeImpl = runCompose } = {}) {
+  const dbUrl = readEnvValue(path.join(ctx.repoRoot, 'apps', 'mercato', '.env'), 'DATABASE_URL') ?? ''
+  let parsed
+  try {
+    parsed = new URL(dbUrl)
+  } catch {
+    return null
+  }
+  const user = decodeURIComponent(parsed.username || 'postgres')
+  const password = decodeURIComponent(parsed.password || 'postgres')
+  let result
+  try {
+    result = runComposeImpl(ctx.repoRoot, [
+      'exec', '-T', '-e', `PGPASSWORD=${password}`, '-e', `PGUSER=${user}`, 'postgres',
+      'sh', '-c', `exec psql -h "$(hostname -i | awk '{print $1}')" -d postgres -t -A -c 'select 1'`,
+    ], { stdio: 'pipe' })
+  } catch {
+    return null
+  }
+  if (result.status === 0) return 'ok'
+  const output = `${result.stderr ?? ''}\n${result.stdout ?? ''}`
+  return /password authentication failed|role ".*" does not exist/i.test(output) ? 'auth-failed' : null
+}
+
+// Distinguishes "the data volume already carries a seeded database" from a
+// genuinely empty one. `yarn initialize` hard-aborts when it finds existing
+// users, so on a re-clone (fresh .mercato markers, old postgres volume) the
+// database step must adopt the volume instead of trying to seed it. Queries
+// over the trust-auth socket (no password needed) and guards the users table
+// existence in one round trip. Returns true (seeded), false (empty/no table),
+// or null when the probe cannot run.
+export function databaseIsInitialized(ctx, { runComposeImpl = runCompose } = {}) {
+  const dbUrl = readEnvValue(path.join(ctx.repoRoot, 'apps', 'mercato', '.env'), 'DATABASE_URL') ?? ''
+  const dbName = dbUrl.split('/').pop()?.split('?')[0]?.trim() || 'open-mercato'
+  let result
+  try {
+    result = runComposeImpl(ctx.repoRoot, [
+      'exec', '-T', 'postgres',
+      'psql', '-U', 'postgres', '-d', dbName, '-t', '-A', '-c',
+      "select case when to_regclass('public.users') is null then -1 else (select count(*) from users) end",
+    ], { stdio: 'pipe' })
+  } catch {
+    return null
+  }
+  if (result.status !== 0) return null
+  const value = Number.parseInt(String(result.stdout ?? '').trim(), 10)
+  if (!Number.isFinite(value) || value < 0) return false
+  return value > 0
+}
+
 // `--clean` support: drop the convergence markers (install/build/migrations)
 // so the next `up` re-runs those steps. Keeps the remembered mode AND the
 // db-initialized markers — --clean does not touch data, and `yarn initialize`
@@ -523,9 +588,28 @@ export const databaseStep = {
     if (initialized && migrated) {
       return { ok: true, detail: 'database initialized, no new migration files' }
     }
+    // Re-clone / wiped-markers with an old data volume still attached: the
+    // schema + seed are already there, so `initialize` would hard-abort on the
+    // existing users. Detect it here so apply adopts the volume (skips the
+    // seed) instead of failing. dbReinitialize (empty volume) is the opposite
+    // case and must still seed, so it is excluded above.
+    if (!initialized && databaseIsInitialized(ctx) === true) {
+      ctx.dbAlreadyInitialized = true
+      return { ok: false, detail: migrated
+        ? 'existing data volume already initialized — recording state, skipping seed'
+        : 'existing data volume already initialized — applying pending migrations, skipping seed' }
+    }
     return { ok: false, detail: initialized ? 'new migration files — applying pending migrations' : 'first run — migrate + initialize' }
   },
   async apply(ctx) {
+    if (probePostgresCredentials(ctx) === 'auth-failed') {
+      throw new Error([
+        'Postgres rejected the credentials from apps/mercato/.env (DATABASE_URL).',
+        'The data volume keeps the password it was initialized with — a regenerated or freshly cloned .env no longer matches it.',
+        'Either restore the original POSTGRES_PASSWORD in .env and in apps/mercato/.env (DATABASE_URL), then re-run,',
+        'or start over with a fresh database (DELETES all local data):  yarn om reset',
+      ].join('\n'))
+    }
     runYarn(ctx, ['db:migrate'])
     writeState(ctx.repoRoot, ctx.dbMigrationsMarker, ctx.migrationsFingerprint)
     const applied = readAppliedMigrationModules(ctx)
@@ -534,12 +618,82 @@ export const databaseStep = {
       writeState(ctx.repoRoot, `${ctx.dbMigrationsMarker}-absent`, stillAbsent.join(','))
     }
     if (readState(ctx.repoRoot, ctx.dbMarker) === null || ctx.dbReinitialize) {
-      runYarn(ctx, ['initialize'])
+      // Adopt an already-seeded volume instead of aborting on its users.
+      const alreadyInitialized = ctx.dbAlreadyInitialized ?? (!ctx.dbReinitialize && databaseIsInitialized(ctx) === true)
+      if (alreadyInitialized) {
+        ctx.log('   database already initialized (existing data volume) — recording state, skipping first-run seed')
+      } else {
+        runYarn(ctx, ['initialize'])
+      }
       writeState(ctx.repoRoot, ctx.dbMarker, new Date().toISOString())
     }
   },
 }
 
+function startHostProbeListener(port) {
+  const script = `require('node:http').createServer((req, res) => { res.setHeader('content-type', 'application/json'); res.end('{"status":"ok","probe":"open-mercato-starter"}') }).listen(${port}, '0.0.0.0', () => console.log('listening'))`
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, ['-e', script], { stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true })
+    // A busy port (the real MCP server from a running dev session) is fine —
+    // the probes then hit whatever already answers there.
+    const timer = setTimeout(() => resolve(child), 2000)
+    child.stdout?.on('data', (chunk) => {
+      if (String(chunk).includes('listening')) {
+        clearTimeout(timer)
+        resolve(child)
+      }
+    })
+    child.on('error', () => {
+      clearTimeout(timer)
+      resolve(null)
+    })
+  })
+}
+
+// Rancher Desktop/WSL2 can resolve host-gateway to the WSL distro instead of
+// the Windows host, silently breaking OpenCode -> host MCP. Probe BEFORE the
+// containers come up and pin a working IP into .env (compose feeds it to
+// extra_hosts; a changed pin makes compose recreate opencode on the next up).
+// A throwaway listener on the MCP port makes the probe exercise the exact
+// firewall path the real server will use.
+export const hostGatewayStep = {
+  id: 'host-gateway',
+  expectation: 'a few seconds of container→host probing (Windows only)',
+  title: 'Container → host networking (OM_HOST_GATEWAY)',
+  appliesTo: (ctx) => process.platform === 'win32' && !ctx.flags.noInfra,
+  async check(ctx) {
+    if (readEnvValue(path.join(ctx.repoRoot, '.env'), 'OM_HOST_GATEWAY')?.trim()) {
+      return { ok: true, detail: 'OM_HOST_GATEWAY already pinned in .env' }
+    }
+    if (readState(ctx.repoRoot, 'host-gateway') === 'pin-ok') {
+      return { ok: true, detail: 'default host-gateway mapping verified earlier' }
+    }
+    return { ok: false, detail: 'probing whether containers can reach this machine' }
+  },
+  async apply(ctx) {
+    const ports = resolveStackPorts(ctx.repoRoot)
+    const listener = await startHostProbeListener(ports.mcp)
+    try {
+      const outcome = detectHostGateway(ports.mcp)
+      if (outcome.status === 'pin-ok') {
+        writeState(ctx.repoRoot, 'host-gateway', 'pin-ok')
+        ctx.log('   default host-gateway mapping reaches this machine')
+      } else if (outcome.status === 'use-ip') {
+        addEnvValue(path.join(ctx.repoRoot, '.env'), 'OM_HOST_GATEWAY', outcome.ip)
+        ctx.log(`   host-gateway does not reach this machine (Rancher Desktop/WSL2) — pinned OM_HOST_GATEWAY=${outcome.ip} in .env`)
+      } else if (outcome.status === 'skip') {
+        ctx.log('   probe container could not run — skipping (run `yarn om doctor` for the full audit)')
+      } else {
+        ctx.log(`   ⚠️ containers cannot reach this machine on port ${ports.mcp} — Windows Firewall likely blocks the WSL adapter`)
+        ctx.log(`   ↳ allow it (elevated PowerShell): New-NetFirewallRule -DisplayName "Open Mercato MCP dev" -Direction Inbound -Action Allow -Protocol TCP -LocalPort ${ports.mcp} -Profile Any`)
+        ctx.log('   ↳ then re-run — OpenCode waits for the MCP server and recovers once the port answers')
+      }
+    } finally {
+      listener?.kill()
+    }
+  },
+}
+
 export function buildUpSteps(ctx) {
   const base = [
     prerequisitesStep,
@@ -550,6 +704,7 @@ export function buildUpSteps(ctx) {
     workspaceInstallStep,
     workspaceBuildStep,
     llmProviderStep,
+    hostGatewayStep,
     infraUpStep,
     databaseStep,
   ]