@dooer/dooer-test-env 1.9.0 → 1.10.0

package/lib/command/customer.js

@@ -14,8 +14,14 @@ function toEngineArgv(argv) {
   flag('target', argv.target)
   flag('name', argv.name)
   flag('owner-user', argv.ownerUser)
-  flag('source-namespace', argv.sourceNamespace)
-  flag('target-namespace', argv.targetNamespace)
+  // `local` is a first-class TARGET/SOURCE, not a k8s namespace — --source-local / --target-local keep the
+  // two ideas separate rather than overloading --*-namespace (Jimmy 2026-09-03). The engine addresses the
+  // local stack through the pseudo-namespace `local` internally.
+  if (argv.sourceNamespace === 'local' || argv.targetNamespace === 'local') {
+    throw new Error('use --source-local / --target-local for the local env, not --*-namespace local')
+  }
+  flag('source-namespace', argv.sourceLocal ? 'local' : argv.sourceNamespace)
+  flag('target-namespace', argv.targetLocal ? 'local' : argv.targetNamespace)
   flag('email', argv.email)
   flag('if-target-nonempty', argv.ifTargetNonempty)
   flag('salt', argv.salt)
@@ -36,6 +42,8 @@ const copyOptions = (y) =>
     .option('owner-user', { type: 'string', describe: 'existing user (users_pk) to own a newly-created org' })
     .option('source-namespace', { type: 'string', default: 'dooer-staging', describe: 'k8s namespace to read from' })
     .option('target-namespace', { type: 'string', describe: 'k8s namespace to write to (default = source)' })
+    .option('source-local', { type: 'boolean', describe: 'read from the LOCAL env instead of a k8s namespace' })
+    .option('target-local', { type: 'boolean', describe: 'write to the LOCAL env instead of a k8s namespace' })
     .option('email', { type: 'string', describe: 'address to scrub emails to (default testcustomer@dooer.com)' })
     .option('if-target-nonempty', {
       choices: ['refuse', 'insert'],
@@ -67,13 +75,14 @@ module.exports = {
           y2
             .option('org', { type: 'string', demandOption: true, describe: 'org (companies_pk) to delete' })
             .option('namespace', { type: 'string', default: 'dooer-staging', describe: 'k8s namespace' })
+            .option('local', { type: 'boolean', describe: 'purge from the LOCAL env instead of a k8s namespace' })
             .option('skip-files', { type: 'boolean', describe: 'do not delete the org’s S3 objects' })
             .option('confirm-production', { type: 'boolean', describe: 'REQUIRED to delete from dooer-production' })
             .option('execute', { type: 'boolean', default: false, describe: 'actually delete (default: dry-run)' }),
         handler: (argv) =>
           purge({
             org: argv.org,
-            namespace: argv.namespace,
+            namespace: argv.local ? 'local' : argv.namespace,
             skipFiles: argv.skipFiles,
             confirmProduction: argv.confirmProduction,
             execute: argv.execute,

package/lib/command/service.js

@@ -1,5 +1,4 @@
 const fs = require('fs')
-const os = require('os')
 const path = require('path')
 const yaml = require('js-yaml')
 const chalk = require('chalk')
@@ -7,7 +6,7 @@ const rt = require('../runtime')
 const discovery = require('../discovery/client')
 const bankid = require('../bankid')
 const { imageFor, listServices } = require('../compose/manifests')
-const { serviceHostPortMap } = require('../compose/generate')
+const { serviceHostPortMap, KAFKA_HOST_PORT } = require('../compose/generate')
 
 // 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
@@ -71,27 +70,35 @@ function localEnv(name, port) {
   // the host process, but that name does not resolve ON the host (service-accounts →
   // /api/v1/token-invalidation/all → ENOTFOUND, which broke every HQ navigation query).
   env[`DOOER_HOST_${name.toUpperCase().replace(/-/g, '_')}`] = `localhost:${port}`
-  // @dooer/logging: `logMode = DOOER_LOG || (process.stdout.isTTY ? 'pretty' : 'none')`. We redirect the
-  // host process to a log FILE, so stdout is not a TTY and it would log NOTHING — the images bake
-  // DOOER_LOG=json, which the manifests don't carry, so set it here too or `service local` runs blind.
-  env.DOOER_LOG = env.DOOER_LOG || 'json'
+  // @dooer/logging: `logMode = DOOER_LOG || (process.stdout.isTTY ? 'pretty' : 'none')`. On a terminal it
+  // picks human-readable 'pretty' by itself; when the output is piped/redirected it would log NOTHING, so
+  // fall back to json there (the images bake DOOER_LOG=json, which the manifests don't carry).
+  if (!env.DOOER_LOG && !process.stdout.isTTY) env.DOOER_LOG = 'json'
+  // Kafka: containers use the INTERNAL listener (advertised as kafka:9092, unresolvable here); a host
+  // process must bootstrap against the EXTERNAL one or it reconnects to `kafka` and fails.
+  if (env.DOOER_KAFKA_BOOTSTRAP_BROKER) env.DOOER_KAFKA_BOOTSTRAP_BROKER = `localhost:${KAFKA_HOST_PORT}`
   return env
 }
 
-// Where a service's checked-out code lives. Nothing here is machine-specific: an explicit path wins, then
-// the ~/dooer/<service> convention, then the CURRENT directory if you happen to be standing in that
-// service's checkout (so `cd ~/src/service-ledger && … service local service-ledger` works too).
-function repoPath(name, given) {
-  if (given) return path.resolve(given)
-  const conventional = path.join(os.homedir(), 'dooer', name)
-  if (fs.existsSync(path.join(conventional, 'package.json'))) return conventional
+// Where the code runs from: an explicit path if given, otherwise the CURRENT directory — you `cd` to your
+// checkout and run the command there. Deliberately NOT a ~/dooer/<service> convention; everyone lays their
+// checkouts out differently (Jimmy 2026-09-03).
+function repoPath(given) {
+  return path.resolve(given || process.cwd())
+}
+
+// Service name: the argument if given, else the package.json name in the checkout (scope stripped), so
+// `cd service-ledger && … service local` just works.
+function serviceNameFor(given, cwd) {
+  if (given) return given
   try {
-    const pkgName = require(path.join(process.cwd(), 'package.json')).name || ''
-    if (pkgName.replace(/^@[^/]+\//, '') === name) return process.cwd()
+    const pkgName = require(path.join(cwd, 'package.json')).name || ''
+    const name = pkgName.replace(/^@[^/]+\//, '')
+    if (name) return name
   } catch (_) {
-    /* no readable package.json in cwd */
+    /* no readable package.json */
   }
-  return conventional
+  throw new Error(`cannot tell which service this is — run inside a service checkout or pass its name`)
 }
 
 module.exports = {
@@ -150,31 +157,45 @@ module.exports = {
         },
       })
       .command({
-        command: 'local <name> [repoPath]',
-        describe: 'run a service from locally checked-out code instead of its image',
+        command: 'local [name] [repoPath]',
+        describe: 'run THIS checkout instead of the container image (run it from your checkout; Ctrl-C restores)',
         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)
+          const cwd = repoPath(a.repoPath)
           if (!fs.existsSync(path.join(cwd, 'package.json')))
-            throw new Error(`no package.json at ${cwd} (pass the repo path)`)
+            throw new Error(`no package.json in ${cwd} — cd to the service checkout, or pass its path`)
+          const name = serviceNameFor(a.name, cwd)
           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 })
+          rt.dc(['stop', name]) // free the container so only this process serves
+          await discovery.setTarget(rt.ROUTER_URL, name, { address: 'host.docker.internal', port })
           const st = rt.readState()
-          st.local[a.name] = { pid, port, cwd }
+          st.local[name] = { pid: process.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`
-              )}`
-            )
+            chalk.green(`${name} now serves from ${cwd} on port ${port}; router repointed.`) +
+              chalk.gray('  Ctrl-C to stop and restore the container.\n')
           )
+          // Foreground: the service's own logs stream to THIS terminal (no log file to go hunting for).
+          rt.spawnForeground('yarn', [a.script], {
+            cwd,
+            env: localEnv(name, port),
+            onExit: (code) => {
+              const s2 = rt.readState()
+              delete s2.local[name]
+              rt.writeState(s2)
+              discovery
+                .clearTarget(rt.ROUTER_URL, name)
+                .catch(() => {})
+                .then(() => {
+                  console.log(chalk.gray(`\nrestoring ${name} container…`))
+                  rt.dc(['up', '-d', name])
+                  process.exit(code)
+                })
+            },
+          })
         },
       })
       .command({

package/lib/compose/generate.js

@@ -284,12 +284,15 @@ function infraServices() {
         '--node-id',
         '0',
         '--check=false',
+        // TWO listeners. A Kafka client connects to the bootstrap address, then reconnects to whatever the
+        // broker ADVERTISES — so a single `kafka:9092` advertisement breaks host processes (`service local`
+        // hit `getaddrinfo ENOTFOUND kafka`). INTERNAL is for containers, EXTERNAL for the host.
         '--kafka-addr',
-        'PLAINTEXT://0.0.0.0:9092',
+        'INTERNAL://0.0.0.0:9092,EXTERNAL://0.0.0.0:19092',
         '--advertise-kafka-addr',
-        'PLAINTEXT://kafka:9092',
+        `INTERNAL://kafka:9092,EXTERNAL://localhost:${KAFKA_HOST_PORT}`,
       ],
-      ports: ['9092:9092'],
+      ports: ['9092:9092', `${KAFKA_HOST_PORT}:19092`],
       volumes: ['kafka_data:/var/lib/redpanda/data'],
       logging: LOGGING,
       restart: 'unless-stopped',
@@ -343,6 +346,8 @@ const GRAPHQL_HOST_PORT = 4001 // service-graphql (direct access; frontends go t
 // Docker Desktop doesn't route on macOS) — so without this a locally-run service can call itself but not
 // its peers. `service local` turns this map into DOOER_HOST_<NAME> overrides. (Jimmy 2026-09-03.)
 const SERVICE_HOST_PORT_BASE = 21000
+// Kafka's host-facing (EXTERNAL) listener — see the kafka block for why a second listener is required.
+const KAFKA_HOST_PORT = 19092
 
 // {service name → published host port}, stable because listServices() is sorted by filename.
 function serviceHostPortMap(services) {
@@ -510,6 +515,7 @@ function generateCompose({ profile, servicesDir, out, outputValidation = false }
 
 module.exports = {
   BOOKING_PROFILE_SERVICES,
+  KAFKA_HOST_PORT,
   serviceHostPortMap,
   VALIDATION_ENV,
   GLOBAL_OVERRIDES,

package/lib/runtime.js

@@ -60,17 +60,30 @@ function dcCapture(rest, { profile, env: extraEnv } = {}) {
 }
 
 // spawn a detached host process (for `service local`), return its pid. Logs to RUN_DIR/<name>.local.log.
-function spawnDetached(name, command, cmdArgs, { cwd, env }) {
-  ensureRunDir()
-  const out = fs.openSync(path.join(RUN_DIR, `${name}.local.log`), 'a')
-  const child = spawn(command, cmdArgs, {
-    cwd,
-    env: { ...process.env, ...env },
-    detached: true,
-    stdio: ['ignore', out, out],
-  })
-  child.unref()
-  return child.pid
+// Run a service from a checkout in the FOREGROUND, streaming its logs straight to this terminal, so it
+// behaves like `yarn start` — Ctrl-C stops it and the caller restores the container. `onExit` fires once,
+// however the process ends.
+function spawnForeground(command, cmdArgs, { cwd, env, onExit }) {
+  const child = spawn(command, cmdArgs, { cwd, env: { ...process.env, ...env }, stdio: 'inherit' })
+  let finished = false
+  const finish = (code) => {
+    if (finished) return
+    finished = true
+    onExit(code)
+  }
+  child.on('exit', (code, signal) => finish(signal ? 1 : code || 0))
+  child.on('error', () => finish(1))
+  // Forward interrupts to the child; its exit then triggers our cleanup.
+  const forward = (sig) => () => {
+    try {
+      child.kill(sig)
+    } catch (_) {
+      /* already gone */
+    }
+  }
+  process.on('SIGINT', forward('SIGINT'))
+  process.on('SIGTERM', forward('SIGTERM'))
+  return child
 }
 
 function isAlive(pid) {
@@ -96,6 +109,6 @@ module.exports = {
   writeState,
   dc,
   dcCapture,
-  spawnDetached,
+  spawnForeground,
   isAlive,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dooer/dooer-test-env",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Run the whole Dooer backend locally (staging DB minus customers), copy/purge customers between environments, and shred — one CLI.",
   "license": "UNLICENSED",
   "repository": "Dooer/cli-dooer-test-env",

package/readme.md

@@ -54,19 +54,21 @@ Everything that writes is **dry-run by default**; add `--execute`. Run any comma
 ## Use cases
 
 Everything below runs from **any directory** (`npx` resolves the published CLI). Nothing is tied to a
-particular machine: checkouts default to `~/dooer/<service>`, state lives in `~/.dooer-test-env`.
+particular machine — you `cd` to your own checkouts, and state lives in `~/.dooer-test-env`.
 
 ### Where things are served
 
 | | |
 | --- | --- |
-| `http://localhost:4000` | **public-facade** — the browser-facing entrypoint (GraphQL + REST passthrough) |
-| `http://localhost:4001` | service-graphql (direct; frontends go via the facade) |
-| `http://localhost:8080` | frontend-hq |
-| `http://localhost:8082` | frontend-back-office-neue (GraphiQL at `/tools/graphiql`) |
-| `http://localhost:8089` | frontend-sumify-neue |
-| `localhost:55432` | Postgres (`dooer`/`dooer`) · `localhost:9001` MinIO console |
-| `localhost:21000+` | every backend service, one host port each (so host processes can reach them) |
+| [localhost:4000](http://localhost:4000) | **public-facade** — the browser-facing entrypoint (GraphQL + REST passthrough) |
+| [localhost:4001](http://localhost:4001) | service-graphql (direct; frontends go via the facade) |
+| [localhost:8080](http://localhost:8080) | frontend-hq |
+| [localhost:8082/tools/graphiql](http://localhost:8082/tools/graphiql) | frontend-back-office-neue — handy GraphiQL console |
+| [localhost:8089](http://localhost:8089) | frontend-sumify-neue |
+| [localhost:8090](http://localhost:8090) · [8092](http://localhost:8092) · [8081](http://localhost:8081) | frontend-tasks · frontend-xrays · frontend-ai-data-studio |
+| [localhost:9001](http://localhost:9001) | MinIO console (`minioadmin` / `minioadmin`) |
+| `localhost:55432` | Postgres (`dooer` / `dooer`) |
+| `localhost:21000`+ | every backend service, one host port each (so host processes can reach them) |
 
 ### Spin up an empty, ready-to-use customer
 
@@ -91,8 +93,8 @@ WHERE fk_user_roles_at_dooer_pk = 'customer' AND inactivated_at IS NULL LIMIT 5;
 
 ### Copy a real customer into the local env
 
-`--target-namespace local` addresses this stack (Postgres on 55432 + MinIO); source can be any k8s
-namespace. Reading production needs no confirmation — only *writing* to it does. Emails are always
+`--target-local` addresses this stack (Postgres on 55432 + MinIO); the source can be any k8s namespace
+(`--source-local` goes the other way). Reading production needs no confirmation — only *writing* to it does. Emails are always
 anonymized. Dry-run by default; add `--execute`.
 
 ```bash
@@ -100,7 +102,7 @@ anonymized. Dry-run by default; add `--execute`.
 npx @dooer/dooer-test-env@latest customer copy \
   --source e45a3bc4-1b61-4f55-9bd6-de2705420cc2 \
   --source-namespace dooer-production \
-  --target-namespace local \
+  --target-local \
   --name "Ghost inspector (live)" \
   --owner-user <local-customer-users_pk> \
   --execute
@@ -109,7 +111,7 @@ npx @dooer/dooer-test-env@latest customer copy \
 npx @dooer/dooer-test-env@latest shred --execute
 
 # undo: delete that org again (rows + its S3 objects), dry-run first
-npx @dooer/dooer-test-env@latest customer purge --org <orgId> --namespace local --execute
+npx @dooer/dooer-test-env@latest customer purge --org <orgId> --local --execute
 ```
 
 It scans all ~336 tables in the source before writing, so expect a few minutes on a production source.
@@ -120,23 +122,32 @@ It scans all ~336 tables in the source before writing, so expect a few minutes o
 discovery router so **containers call your process**. Your process reaches the containerized services
 through their published host ports, so traffic flows **both ways**.
 
-The checkout is resolved as: explicit path → `~/dooer/<service>` → the current directory if you are standing
-in that service's checkout. So you do **not** need to `cd` anywhere:
+**`cd` to your checkout** — wherever you keep it — and run it there. The service name is read from that
+repo's `package.json`, and it runs in the foreground with its **logs streaming to your terminal**; Ctrl-C
+stops it and restores the container.
 
 ```bash
-npx @dooer/dooer-test-env@latest service local service-ledger              # uses ~/dooer/service-ledger
-npx @dooer/dooer-test-env@latest service local service-ledger ~/src/ledger # or an explicit path
-npx @dooer/dooer-test-env@latest service version service-ledger            # LOCAL code or which image?
-npx @dooer/dooer-test-env@latest service unlocal service-ledger            # back to the container image
+cd ~/wherever/service-ledger
+npx @dooer/dooer-test-env@latest service local          # name inferred from package.json
 ```
 
-Logs go to `~/.dooer-test-env/<service>.local.log`.
+```bash
+# or name/point it explicitly from anywhere
+npx @dooer/dooer-test-env@latest service local service-ledger ~/wherever/service-ledger
+npx @dooer/dooer-test-env@latest service version service-ledger   # LOCAL code, or which image?
+npx @dooer/dooer-test-env@latest service unlocal service-ledger   # back to the container image
+```
 
 **Several services at once** — e.g. test a gateway change together with a backend change, no image builds:
 
+Each one holds its own terminal, so use two:
+
 ```bash
-npx @dooer/dooer-test-env@latest service local service-accounts   # start the backend first…
-npx @dooer/dooer-test-env@latest service local service-graphql    # …then the gateway
+# terminal 1 — the backend, started FIRST
+cd ~/wherever/service-accounts && npx @dooer/dooer-test-env@latest service local
+
+# terminal 2 — the gateway
+cd ~/wherever/service-graphql  && npx @dooer/dooer-test-env@latest service local
 ```
 
 Order matters: a local process learns its peers' addresses at startup, so start the service **being called**