@dooer/dooer-test-env 1.0.0

package/lib/command/logs.js

@@ -0,0 +1,143 @@
+const path = require('path')
+const { spawn, spawnSync } = require('child_process')
+const chalk = require('chalk')
+const rt = require('../runtime')
+
+// Fetch one container's logs since `since`, merging stdout+stderr (docker logs uses both). Resolves to the
+// text (never rejects) so one bad container can't sink the whole parallel sweep. A hard timeout guards
+// against `docker logs` blocking indefinitely on a container that is mid-restart (observed with the
+// excluded institution-browser) — we kill it and return whatever we captured.
+function fetchLogs(name, since, timeoutMs = 10000) {
+  return new Promise((resolve) => {
+    const p = spawn('docker', ['logs', '--since', since, name])
+    let out = ''
+    let done = false
+    const finish = () => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      resolve(out)
+    }
+    const timer = setTimeout(() => {
+      try {
+        p.kill('SIGKILL')
+      } catch (_) {
+        /* already gone */
+      }
+      finish()
+    }, timeoutMs)
+    p.stdout.on('data', (d) => (out += d))
+    p.stderr.on('data', (d) => (out += d))
+    p.on('close', finish)
+    p.on('error', finish)
+  })
+}
+
+// Search logs across EVERY service in the local env at once — e.g. find a transactionId or an error string
+// wherever it surfaced. `docker logs` is per-container, so we fan out over the compose project's containers
+// and grep each. See ENVIRONMENT-PLAN.md.
+
+// The compose project name docker derives from the run dir (leading dot + odd chars stripped, lowercased).
+function projectName() {
+  return path
+    .basename(rt.RUN_DIR)
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, '')
+    .replace(/^dooertestenv$/, 'dooer-test-env') // basename ".dooer-test-env" → docker project "dooer-test-env"
+}
+
+// Containers in this project (running by default; all with --all). Returns [{ name, short }].
+function listContainers({ all }) {
+  const args = [
+    'ps',
+    all ? '-a' : null,
+    '--filter',
+    `label=com.docker.compose.project=${projectName()}`,
+    '--format',
+    '{{.Names}}',
+  ].filter(Boolean)
+  const r = spawnSync('docker', args, { encoding: 'utf8' })
+  const names = (r.stdout || '')
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  const prefix = `${projectName()}-`
+  return names
+    .map((name) => ({ name, short: name.replace(prefix, '').replace(/-1$/, '') }))
+    .sort((a, b) => a.short.localeCompare(b.short))
+}
+
+module.exports = {
+  command: 'logs <pattern>',
+  aliases: ['search'],
+  describe: 'search logs across all local services for a pattern (e.g. a transactionId or error text)',
+  builder: (y) =>
+    y
+      .positional('pattern', { type: 'string', describe: 'JS regular expression to match against each log line' })
+      .option('since', {
+        type: 'string',
+        default: '5m',
+        describe: 'how far back to search (docker duration, e.g. 30m, 2h)',
+      })
+      .option('service', {
+        alias: 's',
+        type: 'string',
+        describe: 'only search services whose name contains this substring',
+      })
+      .option('ignore-case', { alias: 'i', type: 'boolean', describe: 'case-insensitive match' })
+      .option('all', { type: 'boolean', describe: 'include stopped containers too' })
+      .option('context', {
+        alias: 'C',
+        type: 'number',
+        default: 0,
+        describe: 'lines of context to print around each match',
+      }),
+  handler: async (argv) => {
+    let re
+    try {
+      re = new RegExp(argv.pattern, argv.ignoreCase ? 'i' : '')
+    } catch (e) {
+      throw new Error(`invalid pattern: ${e.message}`)
+    }
+    let containers = listContainers({ all: argv.all })
+    if (argv.service) containers = containers.filter((c) => c.short.includes(argv.service))
+    if (!containers.length) {
+      console.log(chalk.yellow('no matching local containers (is the env up?)'))
+      return
+    }
+
+    // Fetch every container's logs concurrently, then print in stable (sorted) container order.
+    const fetched = await Promise.all(containers.map((c) => fetchLogs(c.name, argv.since).then((out) => ({ c, out }))))
+
+    let totalMatches = 0
+    const hitServices = []
+    for (const { c, out } of fetched) {
+      const lines = out.split('\n')
+      const matchIdx = []
+      lines.forEach((line, i) => {
+        if (re.test(line)) matchIdx.push(i)
+      })
+      if (!matchIdx.length) continue
+      hitServices.push(c.short)
+      totalMatches += matchIdx.length
+      const printed = new Set()
+      matchIdx.forEach((i) => {
+        const lo = Math.max(0, i - argv.context)
+        const hi = Math.min(lines.length - 1, i + argv.context)
+        for (let j = lo; j <= hi; j++) {
+          if (printed.has(j)) continue
+          printed.add(j)
+          const tag = chalk.cyan(c.short.padEnd(28))
+          const text = lines[j]
+          console.log(`${tag} ${j === i ? text : chalk.gray(text)}`) // matched line plain, context greyed
+        }
+      })
+    }
+    console.log(
+      chalk.bold(
+        `\n${totalMatches} match(es) across ${hitServices.length} service(s)` +
+          (hitServices.length ? `: ${hitServices.join(', ')}` : '')
+      )
+    )
+  },
+}

package/lib/command/measure.js

@@ -0,0 +1,81 @@
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawnSync } = require('child_process')
+const chalk = require('chalk')
+const rt = require('../runtime')
+
+// Measure resource usage of the running env (CPU/RAM per container + totals + disk) so we can publish
+// concrete dev-machine requirements (ENVIRONMENT-PLAN.md §6). Samples `docker stats` N times and reports
+// the peak per container. Writes a Markdown report.
+
+function docker(args) {
+  const r = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 })
+  return r.status === 0 ? r.stdout : ''
+}
+
+// parse a memory string like "1.23GiB" / "512MiB" / "900KiB" → MiB
+function toMiB(s) {
+  const m = /([\d.]+)\s*([KMGT]i?B)/i.exec(s || '')
+  if (!m) return 0
+  const v = parseFloat(m[1])
+  const u = m[2].toUpperCase()
+  const mult = { KIB: 1 / 1024, KB: 1 / 1024, MIB: 1, MB: 1, GIB: 1024, GB: 1024, TIB: 1024 * 1024, TB: 1024 * 1024 }
+  return v * (mult[u] || 1)
+}
+
+module.exports = {
+  command: 'measure',
+  describe: 'sample docker stats for the running env and write a resource report (CPU/RAM/disk)',
+  builder: (y) =>
+    y
+      .option('samples', { type: 'number', default: 5, describe: 'number of stats samples' })
+      .option('interval', { type: 'number', default: 5, describe: 'seconds between samples' })
+      .option('out', { type: 'string', describe: 'report path (default: ~/.dooer-test-env/resource-report.md)' }),
+  handler: async (argv) => {
+    const peak = {} // name -> { cpu, memMiB }
+    for (let i = 0; i < argv.samples; i++) {
+      const raw = docker(['stats', '--no-stream', '--format', '{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'])
+      raw
+        .split('\n')
+        .filter((l) => l.includes('dooer-test-env'))
+        .forEach((l) => {
+          const [name, cpu, mem] = l.split('\t')
+          const cpuN = parseFloat(cpu) || 0
+          const memN = toMiB((mem || '').split('/')[0])
+          if (!peak[name] || cpuN + memN > peak[name].cpu + peak[name].memMiB) peak[name] = { cpu: cpuN, memMiB: memN }
+        })
+      if (i < argv.samples - 1) await new Promise((r) => setTimeout(r, argv.interval * 1000))
+      process.stderr.write(`\rsampled ${i + 1}/${argv.samples}`)
+    }
+    process.stderr.write('\n')
+
+    const rows = Object.entries(peak)
+      .map(([name, p]) => ({
+        name: name.replace(/^dooer-test-env-/, '').replace(/-\d+$/, ''),
+        cpu: p.cpu,
+        memMiB: p.memMiB,
+      }))
+      .sort((a, b) => b.memMiB - a.memMiB)
+    const totCpu = rows.reduce((s, r) => s + r.cpu, 0)
+    const totMem = rows.reduce((s, r) => s + r.memMiB, 0)
+    const df = docker(['system', 'df'])
+
+    const gib = (m) => (m / 1024).toFixed(2)
+    const md =
+      `# dooer-test-env — resource usage\n\n` +
+      `Host: ${os.cpus().length} logical CPUs, ${(os.totalmem() / 1024 ** 3).toFixed(0)} GB RAM. ` +
+      `Samples: ${argv.samples} @ ${argv.interval}s (peak per container).\n\n` +
+      `**Containers:** ${rows.length} · **Total CPU:** ${totCpu.toFixed(0)}% (of ${os.cpus().length * 100}%) · ` +
+      `**Total RAM:** ${gib(totMem)} GiB\n\n` +
+      `| container | peak CPU % | peak RAM (MiB) |\n|---|---:|---:|\n` +
+      rows.map((r) => `| ${r.name} | ${r.cpu.toFixed(1)} | ${r.memMiB.toFixed(0)} |`).join('\n') +
+      `\n\n## docker system df\n\n\`\`\`\n${df}\`\`\`\n`
+
+    const out = argv.out || path.join(rt.RUN_DIR, 'resource-report.md')
+    rt.ensureRunDir()
+    fs.writeFileSync(out, md)
+    console.log(chalk.green(`\n${rows.length} containers · ${totCpu.toFixed(0)}% CPU · ${gib(totMem)} GiB RAM`))
+    console.log(`report: ${out}`)
+  },
+}

package/lib/command/service.js

@@ -0,0 +1,166 @@
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const yaml = require('js-yaml')
+const chalk = require('chalk')
+const rt = require('../runtime')
+const discovery = require('../discovery/client')
+const { imageFor } = require('../compose/manifests')
+
+// Per-service control in a running env. `local`/`unlocal`/`deploy` update the discovery router so peers
+// pick up the change with no restarts (see ENVIRONMENT-PLAN.md §4/§6). Local host-process ports are
+// CLI-managed. All docker interaction goes through lib/runtime.
+
+// read a service's environment from the generated compose file, rewriting container-DNS infra hosts to
+// localhost so the same dev config works for a host process. Returns {} if the compose isn't generated.
+function localEnv(name, port) {
+  let env = {}
+  try {
+    const doc = yaml.safeLoad(fs.readFileSync(rt.COMPOSE_FILE, 'utf8'))
+    env = { ...((doc.services[name] && doc.services[name].environment) || {}) }
+  } catch (_) {
+    /* compose not generated yet — fall back to the minimum below */
+  }
+  const rw = (v) =>
+    String(v)
+      .replace(/\bpostgres:/g, 'localhost:')
+      .replace(/(^|@)postgres\b/g, `$1localhost`)
+      .replace(/\bredis:/g, 'localhost:')
+      .replace(/\bdiscovery-router:/g, 'localhost:')
+      .replace(/\bminio:/g, 'localhost:')
+      .replace(/\bkafka:/g, 'localhost:')
+  for (const k of Object.keys(env)) env[k] = rw(env[k])
+  // guaranteed minimum wiring (also covers the no-compose fallback)
+  env.DOOER_SQL_HOST = 'localhost'
+  env.DOOER_SQL_PORT = env.DOOER_SQL_PORT || '5432'
+  env.DOOER_SQL_DATABASE = env.DOOER_SQL_DATABASE || 'dooer'
+  env.DOOER_IS_ONEPLATFORMER = 'false'
+  env.CONSUL_HTTP_ADDR = 'localhost:8500'
+  env.DOOER_MICROSERVICE_PORT = String(port)
+  env.DOOER_SERVICE_NAME = env.DOOER_SERVICE_NAME || name
+  env.DOOER_ENVIRONMENT_NAME = env.DOOER_ENVIRONMENT_NAME || 'local'
+  env.NODE_ENV = env.NODE_ENV || 'development'
+  return env
+}
+
+function repoPath(name, given) {
+  return given || path.join(os.homedir(), 'dooer', name)
+}
+
+module.exports = {
+  command: 'service <command>',
+  describe: 'control a single service in the running env',
+  builder: (y) =>
+    y
+      .command({
+        command: 'start <name>',
+        describe: 'start a service container',
+        handler: (a) => {
+          process.exitCode = rt.dc(['up', '-d', a.name])
+        },
+      })
+      .command({
+        command: 'stop <name>',
+        describe: 'stop a service container',
+        handler: (a) => {
+          process.exitCode = rt.dc(['stop', a.name])
+        },
+      })
+      .command({
+        command: 'restart <name>',
+        describe: 'restart a service container',
+        handler: (a) => {
+          process.exitCode = rt.dc(['restart', a.name])
+        },
+      })
+      .command({
+        command: 'deploy <name> <version>',
+        describe: 'switch a service to a published registry version (upgrade/downgrade)',
+        handler: (a) => {
+          const base = imageFor(a.name, rt.SERVICES_DIR)
+          if (!base) throw new Error(`unknown service ${a.name} (no manifest image)`)
+          const image = `${base.replace(/:[^:/]+$/, '')}:${a.version}`
+          // merge into the override compose file
+          let ov = { services: {} }
+          if (fs.existsSync(rt.OVERRIDE_FILE))
+            ov = yaml.safeLoad(fs.readFileSync(rt.OVERRIDE_FILE, 'utf8')) || { services: {} }
+          ov.services = ov.services || {}
+          ov.services[a.name] = { image }
+          rt.ensureRunDir()
+          fs.writeFileSync(rt.OVERRIDE_FILE, yaml.safeDump(ov))
+          const st = rt.readState()
+          st.deploy[a.name] = image
+          rt.writeState(st)
+          console.log(chalk.gray(`pinned ${a.name} → ${image}`))
+          process.exitCode = rt.dc(['up', '-d', a.name])
+        },
+      })
+      .command({
+        command: 'local <name> [repoPath]',
+        describe: 'run a service from locally checked-out code instead of its image',
+        builder: (y2) =>
+          y2
+            .option('port', { type: 'number', describe: 'host port for the local process (default: auto)' })
+            .option('script', { type: 'string', default: 'start', describe: 'package.json script to run' }),
+        handler: async (a) => {
+          const cwd = repoPath(a.name, a.repoPath)
+          if (!fs.existsSync(path.join(cwd, 'package.json')))
+            throw new Error(`no package.json at ${cwd} (pass the repo path)`)
+          const port = a.port || 4000 + Math.floor((Date.now() % 1000) + Math.random() * 100) // CLI-managed
+          rt.dc(['stop', a.name]) // free the container so only the local process serves
+          const pid = rt.spawnDetached(a.name, 'yarn', [a.script], { cwd, env: localEnv(a.name, port) })
+          await discovery.setTarget(rt.ROUTER_URL, a.name, { address: 'host.docker.internal', port })
+          const st = rt.readState()
+          st.local[a.name] = { pid, port, cwd }
+          rt.writeState(st)
+          console.log(
+            chalk.green(
+              `${a.name} now runs from ${cwd} (pid ${pid}, port ${port}); router repointed. Logs: ${path.join(
+                rt.RUN_DIR,
+                `${a.name}.local.log`
+              )}`
+            )
+          )
+        },
+      })
+      .command({
+        command: 'unlocal <name>',
+        describe: 'switch a service back to its published image',
+        handler: async (a) => {
+          const st = rt.readState()
+          const info = st.local[a.name]
+          if (info && rt.isAlive(info.pid)) {
+            try {
+              process.kill(info.pid)
+            } catch (_) {
+              /* already gone */
+            }
+          }
+          delete st.local[a.name]
+          rt.writeState(st)
+          await discovery.clearTarget(rt.ROUTER_URL, a.name).catch(() => {})
+          rt.dc(['up', '-d', a.name]) // bring the container back
+          console.log(chalk.green(`${a.name} back on its container image; router reverted.`))
+        },
+      })
+      .command({
+        command: 'version <name>',
+        describe: 'report whether a service runs a published image (+tag) or local code',
+        handler: (a) => {
+          const st = rt.readState()
+          if (st.local[a.name] && rt.isAlive(st.local[a.name].pid)) {
+            console.log(
+              `${a.name}: LOCAL code — ${st.local[a.name].cwd} (pid ${st.local[a.name].pid}, port ${
+                st.local[a.name].port
+              })`
+            )
+            return
+          }
+          const image = (st.deploy && st.deploy[a.name]) || imageFor(a.name, rt.SERVICES_DIR) || '(unknown)'
+          console.log(`${a.name}: published image — ${image}`)
+        },
+      })
+      .demandCommand(1)
+      .strict(),
+  handler: () => {},
+}

package/lib/command/setup.js

@@ -0,0 +1,92 @@
+const fs = require('fs')
+const { spawnSync } = require('child_process')
+const chalk = require('chalk')
+const rt = require('../runtime')
+const registry = require('../registry')
+const bankid = require('../bankid')
+const { generateCompose } = require('../compose/generate')
+
+// `setup` makes a machine ready to run the env, entirely through the CLI — no manual docker/kubectl steps.
+// It checks prerequisites, logs docker into both private registries using the cluster's own pull secrets
+// (prompting only if creds truly can't be found), generates the compose file, and can pre-pull images.
+// See ENVIRONMENT-PLAN.md §6.
+
+function ok(b) {
+  return b ? chalk.green('✓') : chalk.red('✗')
+}
+function check(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' })
+  return r.status === 0
+}
+
+module.exports = {
+  command: 'setup',
+  describe: 'make this machine ready: check prerequisites, log in to the registries, generate compose',
+  builder: (y) =>
+    y
+      .option('namespace', {
+        type: 'string',
+        default: 'dooer-staging',
+        describe: 'namespace to read pull secrets from',
+      })
+      .option('pull', { type: 'boolean', describe: 'also pre-pull all service images (large)' })
+      .option('profile', { type: 'string', default: 'full', describe: 'profile to pre-pull when --pull' }),
+  handler: async (argv) => {
+    console.log(chalk.bold('\ndooer-test-env setup\n'))
+
+    const dockerOk = registry.have('docker') && check('docker', ['info'])
+    console.log(`${ok(dockerOk)} docker (installed + daemon running)`)
+    const kubectlOk = registry.have('kubectl')
+    console.log(`${ok(kubectlOk)} kubectl installed`)
+    // k8s reachable + access: `get ns <ns>` needs the API server (VPN) AND RBAC, so it proves both at once.
+    const nsOk = kubectlOk && check('kubectl', ['get', 'ns', argv.namespace, '--request-timeout=10s'])
+    console.log(`${ok(nsOk)} k8s cluster reachable + access to namespace ${argv.namespace} (needs VPN)`)
+    const secretsOk = nsOk && check('kubectl', ['auth', 'can-i', 'get', 'secrets', '-n', argv.namespace])
+    console.log(`${ok(secretsOk)} can read secrets (registry pull secrets + DB creds) in ${argv.namespace}`)
+    const dbOk =
+      nsOk && check('kubectl', ['get', 'svc', 'dooer-database', '-n', argv.namespace, '--request-timeout=10s'])
+    console.log(`${ok(dbOk)} can reach the dooer-database service in ${argv.namespace}`)
+    if (!dockerOk) throw new Error('docker is required (install Docker + start the daemon).')
+    if (!kubectlOk) throw new Error('kubectl is required.')
+    if (!nsOk)
+      throw new Error(
+        `cannot reach/access namespace ${argv.namespace} — connect the VPN and check your kubectl context/RBAC.`
+      )
+    if (!secretsOk) throw new Error(`no access to read secrets in ${argv.namespace} — needed for registry + DB creds.`)
+
+    // registry login (the part that used to be manual)
+    console.log('\nLogging in to the private registries…')
+    const logins = await registry.loginAll({ namespace: argv.namespace })
+    for (const l of logins) console.log(`  ${ok(l.ok)} ${l.host}  (${l.via})`)
+    if (logins.some((l) => !l.ok)) throw new Error('one or more registry logins failed')
+
+    // generate the compose file
+    rt.ensureRunDir()
+    const r = generateCompose({ servicesDir: rt.SERVICES_DIR, out: rt.COMPOSE_FILE })
+    console.log(`\n${ok(true)} generated ${rt.COMPOSE_FILE} (${(r && r.serviceCount) || '?'} services)`)
+
+    // BankID certs → keychain, so local login matches staging (production BankID). Idempotent; only pulls
+    // if not already stored. Non-fatal — the env still runs (test-mode BankID) without them.
+    if (bankid.status().every((s) => !s.present)) {
+      try {
+        const stored = bankid.pullAndStore({ namespace: argv.namespace })
+        console.log(`${ok(true)} BankID: pulled ${stored.length} secret(s) from staging → keychain`)
+      } catch (e) {
+        console.log(`${chalk.yellow('!')} BankID: skipped (${e.message}); local login stays in test mode`)
+      }
+    } else {
+      console.log(`${ok(true)} BankID: certs already in keychain`)
+    }
+
+    if (argv.pull) {
+      console.log(`\nPre-pulling images (profile: ${argv.profile})… this is large.`)
+      const code = rt.dc(['pull'], { profile: argv.profile })
+      console.log(`${ok(code === 0)} docker compose pull`)
+    }
+
+    console.log(
+      chalk.green('\nsetup complete.') + ' Next: `dooer-test-env up` then `dooer-test-env db pull --execute`.'
+    )
+    if (!fs.existsSync(rt.COMPOSE_FILE)) process.exitCode = 1
+  },
+}

package/lib/command/shred.js

@@ -0,0 +1,60 @@
+const { Client } = require('pg')
+const chalk = require('chalk')
+const { shred } = require('../shred')
+const { auditPii } = require('../shred/audit')
+
+// Anonymize PII in the LOCAL Postgres (the shredder rules). DEV-FACING shred is LOCALHOST-ONLY — it has
+// no option to target a k8s DB (the in-cluster base build is the only context that shreds a non-local
+// scratch DB). See ENVIRONMENT-PLAN.md §5 (Safety rails) / §9.7.
+const LOCAL_HOSTS = ['127.0.0.1', 'localhost', '::1']
+
+module.exports = {
+  command: 'shred',
+  describe: 'anonymize PII in the LOCAL Postgres (localhost only; emails always anonymized)',
+  builder: (y) =>
+    y
+      .option('host', { type: 'string', default: '127.0.0.1', describe: 'DB host — must be localhost' })
+      .option('port', { type: 'number', default: 55432 })
+      .option('database', { type: 'string', default: 'dooer' })
+      .option('user', { type: 'string', default: 'dooer' })
+      .option('password', { type: 'string', default: 'dooer' })
+      .option('audit-only', { type: 'boolean', describe: 'only run the PII audit (no changes)' })
+      .option('execute', { type: 'boolean', default: false, describe: 'actually write (default: dry-run)' }),
+  handler: async (argv) => {
+    if (!LOCAL_HOSTS.includes(argv.host)) {
+      throw new Error(
+        `shred is localhost-only; refusing host "${argv.host}". (Only the in-cluster base build may shred a scratch DB.)`
+      )
+    }
+    const client = new Client({
+      host: argv.host,
+      port: argv.port,
+      database: argv.database,
+      user: argv.user,
+      password: argv.password,
+    })
+    await client.connect()
+    try {
+      if (argv.auditOnly) {
+        const a = await auditPii(client)
+        console.log(`PII audit: scanned ${a.scanned}, covered ${a.covered}, uncovered ${a.uncovered.length}`)
+        a.uncovered.forEach((u) => console.log(`  UNCOVERED ${u.category}: ${u.schema}.${u.table}.${u.column}`))
+        process.exitCode = a.uncovered.length ? 1 : 0
+        return
+      }
+      const res = await shred(client, { execute: argv.execute, verbose: true })
+      const a = await auditPii(client)
+      console.log(`\nPII audit: scanned ${a.scanned}, covered ${a.covered}, uncovered ${a.uncovered.length}`)
+      a.uncovered.forEach((u) =>
+        console.log(`  ${chalk.red('UNCOVERED')} ${u.category}: ${u.schema}.${u.table}.${u.column}`)
+      )
+      if (!argv.execute) console.log(chalk.gray('\n(dry-run — nothing written; re-run with --execute)'))
+      if (res && res.failed && res.failed.length) {
+        console.log(chalk.yellow(`\n${res.failed.length} script(s) had errors (schema drift?):`))
+        res.failed.forEach((f) => console.log(`  ${f.script}: ${f.error}`))
+      }
+    } finally {
+      await client.end()
+    }
+  },
+}

package/lib/compose/README.md

@@ -0,0 +1,98 @@
+# `lib/compose` — docker-compose generator
+
+Translates the s-e032 (staging) k8s manifests into a docker-compose spec that runs
+the whole Dooer backend locally, wired together. This is the Phase-2 generator from
+`ENVIRONMENT-PLAN.md` §6.
+
+## Files
+
+- `manifests.js` — reads `service-*.yaml` Deployments. `listServices(dir)` →
+  `[{ name, image, env, secretEnv, port }]` (sorted, deterministic);
+  `imageFor(name, dir)` → the verbatim image ref for one service.
+- `generate.js` — `generateCompose({ profile, servicesDir, out })` builds the
+  compose object, writes YAML to `out`, and returns a summary
+  (`{ compose, yaml, out, dooerServiceCount, infraServiceCount, bookingProfileServices }`).
+
+## What maps to what
+
+Each `service-*.yaml` is a multi-doc manifest (Deployment + Service, sometimes an
+ObjectBucketClaim / CronJob / RBAC). We read the **Deployment's** `node` container:
+
+- **image** — taken **verbatim**. The fleet uses **two registries**
+  (`143848169226.dkr.ecr.eu-west-1.amazonaws.com` and `docker.roboten.com`); the
+  manifest already names the right one, so we never rewrite it.
+- **env** — plain `value` vars are reproduced as-is; `valueFrom` (secret) vars are
+  replaced with dev values (see below). Then the local overrides are applied last.
+- Files with **no Deployment** (the e2e-nightly and token CronJobs) are skipped —
+  they are not runnable services. That is why the generated file has ~73 dooer
+  services from 75 `service-*.yaml` files.
+
+### Env overrides (applied to every service)
+
+| var | local value | why |
+|---|---|---|
+| `DOOER_SQL_HOST` | `postgres` | local Postgres container |
+| `DOOER_SQL_PORT` / `DOOER_SQL_DATABASE` | `5432` / `dooer` | |
+| `DOOER_SQL_APPLICATION_USER` / `_PASSWORD` | `dooer` / `dooer` | static-password mode |
+| `DOOER_SQL_MIGRATION_USER` / `_PASSWORD` | `dooer` / `dooer` | `CMD-OPF.sh` runs `db-migrate` on boot |
+| `DOOER_IS_ONEPLATFORMER` | `false` | static-password (local) path |
+| `CONSUL_HTTP_ADDR` | `discovery-router:8500` | local mutable discovery router |
+| `DOOER_CONSUL_HOST` | `discovery-router` | (where present) |
+| `DOOER_HOST_REDIS` | `redis:6379` | plain redis, no sentinel |
+| `DOOER_REDIS_USE_TLS` | `false` | |
+| `DOOER_KAFKA_BOOTSTRAP_BROKER` | `kafka:9092` | local Redpanda broker |
+| `DOOER_STREAM_NAME` | `local-s01` | |
+| `AWS_ENDPOINT_URL_S3` | `http://minio:9000` | local MinIO |
+| `DOOER_MICROSERVICE_PORT` | `3000` | |
+| `NODE_ENV` / `DOOER_ENVIRONMENT_NAME` | `development` / `local` | |
+
+**Dropped:** `DOOER_REDIS_SENTINEL_MASTER` (a plain redis container has no sentinel).
+
+**Secret (`valueFrom`) vars** become dev values: `*ACCESS_KEY_ID` / `*SECRET_ACCESS_KEY`
+→ the MinIO creds (`minioadmin`/`minioadmin`); SQL passwords → `dooer`;
+`SECRET_DOOER_REDIS_PASSWORD` → empty. Everything else (LLM API keys, the service
+token, …) becomes a compose passthrough `${NAME:-}` so a dev can `export NAME=…`
+without editing the file. **Bucket names are kept from the manifest** (e.g.
+`file-storage-bucket`) — create them in MinIO before use (the `db pull` / copy tool,
+or `mc mb`).
+
+`depends_on` is `[postgres, redis, discovery-router]` for every dooer service, per
+the plan. Host ports are **not** published for the dooer services (all listen on
+3000 and would clash); reach them through the discovery router. Infra containers
+publish their ports (5432 / 6379 / 9092 / 9000 / 9001 / 8500).
+
+## Infra image choices
+
+| container | image | note |
+|---|---|---|
+| postgres | `postgres:14` | matches the Zalando PG14 in `database-cluster.yaml` |
+| redis | `redis:7-alpine` | single node, no auth/sentinel locally |
+| **kafka** | `docker.redpanda.com/redpandadata/redpanda:v24.1.7` | **single-node Redpanda** — Kafka-API compatible, **no ZooKeeper**, far lighter on a laptop than Strimzi Kafka+ZK. Advertises as `kafka:9092`. |
+| **minio** | `minio/minio:latest` | S3-compatible; `minioadmin`/`minioadmin`; console on 9001 |
+| discovery-router | `build: ../discovery-router` | repo-local image (owned by another agent); port 8500 |
+
+## Profiles — how the "all" vs "booking" selection works
+
+Docker Compose profiles are **additive**: a service with no `profiles:` always
+starts, and activating a profile only *adds* services — it cannot *exclude* them.
+So a single file cannot make a bare `docker compose up` start **all** services
+while a `booking` profile starts only a **subset**. We therefore:
+
+- put **all** dooer services in the `full` profile,
+- **also** put the 10 booking services in the `booking` profile,
+- leave the **infra** containers with no profile (always up).
+
+The CLI's `up` (default) activates `full` (`docker compose --profile full up` /
+`COMPOSE_PROFILES=full`) → **everything**. `up --profile booking`
+(`docker compose --profile booking up`) → the 10 booking services + infra. This is
+exactly the ENVIRONMENT-PLAN model (`up [--profile <name>]`, default = everything).
+
+`generateCompose({ profile })` also accepts a `profile` to *filter which services
+are written* into a smaller file, but the profile keys in the full file are the
+runtime mechanism.
+
+## Dependency
+
+`generate.js` / `manifests.js` `require('js-yaml')`. It is currently only a
+**transitive** dependency — **add `js-yaml` to `package.json` `dependencies`**
+(tested against `js-yaml@3.15.2`, whose `safeLoadAll` / `safeDump` API this uses).