@dooer/dooer-test-env 1.9.0 → 1.11.0

package/lib/command/customer.js

@@ -1,3 +1,4 @@
+const fs = require('fs')
 const chalk = require('chalk')
 const engine = require('../engine/seed')
 const { purge } = require('../engine/purge')
@@ -14,8 +15,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)
@@ -28,14 +35,44 @@ function toEngineArgv(argv) {
   return a
 }
 
+// Resolve which orgs to copy: exactly one of --source / --sourcefile. A source FILE is inherently a batch,
+// so --name and --target (which describe ONE target org) are rejected with it. (Jimmy 2026-09-03.)
+function readSources(argv) {
+  if (argv.source && argv.sourcefile) throw new Error('pass either --source or --sourcefile, not both')
+  if (!argv.source && !argv.sourcefile) throw new Error('missing --source <uuid> or --sourcefile <path>')
+  if (!argv.sourcefile) return [argv.source]
+  if (argv.name || argv.target) {
+    throw new Error(
+      '--name and --target describe a single target org, so they cannot be combined with --sourcefile; ' +
+        'each copied org keeps its own source name'
+    )
+  }
+  const raw = fs.readFileSync(argv.sourcefile, 'utf8')
+  const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+  const lines = raw
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'))
+  const bad = lines.filter((l) => !uuid.test(l))
+  if (bad.length) throw new Error(`${argv.sourcefile}: not org uuids: ${bad.slice(0, 3).join(', ')}`)
+  if (!lines.length) throw new Error(`${argv.sourcefile} contains no org uuids`)
+  return [...new Set(lines)]
+}
+
 const copyOptions = (y) =>
   y
-    .option('source', { type: 'string', demandOption: true, describe: 'org (companies_pk) to copy FROM' })
+    .option('source', { type: 'string', describe: 'org (companies_pk) to copy FROM' })
+    .option('sourcefile', {
+      type: 'string',
+      describe: 'file with one source org uuid per line — copies each in turn (no --name / --target)',
+    })
     .option('target', { type: 'string', describe: 'existing org to copy INTO' })
     .option('name', { type: 'string', describe: 'create a NEW target org with this name (needs --owner-user)' })
     .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'],
@@ -58,7 +95,33 @@ module.exports = {
         command: 'copy',
         describe: 'copy one org into another (dry-run by default; emails anonymized)',
         builder: copyOptions,
-        handler: (argv) => engine.main(engine.parseArgs(toEngineArgv(argv))),
+        handler: async (argv) => {
+          const sources = readSources(argv)
+          if (sources.length === 1) {
+            await engine.main(engine.parseArgs(toEngineArgv({ ...argv, source: sources[0] })))
+            return
+          }
+          // Batch: each org is a full independent copy (the engine scans the source per org). One bad uuid
+          // must not abandon the rest, so failures are collected and reported at the end.
+          console.log(chalk.bold(`\ncopying ${sources.length} organizations from ${argv.sourcefile}\n`))
+          const failed = []
+          for (let i = 0; i < sources.length; i++) {
+            console.log(chalk.cyan(`\n──── [${i + 1}/${sources.length}] ${sources[i]} ────`))
+            try {
+              await engine.main(engine.parseArgs(toEngineArgv({ ...argv, source: sources[i] })))
+            } catch (e) {
+              failed.push({ source: sources[i], error: e.message })
+              console.log(chalk.red(`  FAILED: ${e.message}`))
+            }
+          }
+          console.log(
+            chalk.bold(
+              `\n${sources.length - failed.length}/${sources.length} organizations copied` + (failed.length ? ':' : '')
+            )
+          )
+          failed.forEach((f) => console.log(chalk.red(`  ${f.source}: ${f.error}`)))
+          if (failed.length) process.exitCode = 1
+        },
       })
       .command({
         command: 'purge',
@@ -67,13 +130,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/engine/seed.js

@@ -457,8 +457,12 @@ async function main(passedArgs) {
   const args = passedArgs || parseArgs(process.argv.slice(2))
   if (args.help) return void console.log(HELP)
   if (!args.source) throw new Error('missing --source')
-  if (!args.target && !args.name) throw new Error('provide --target <uuid>, or --name to create a new target org')
-  if (!args.target && !args.ownerUser) throw new Error('creating a new target org requires --owner-user')
+  // --name is OPTIONAL: with neither --target nor --name we create a new org and inherit the SOURCE org's
+  // name (resolved in createTargetOrg, which already has the source row). (Jimmy 2026-09-03.)
+  if (!args.target && !args.ownerUser)
+    throw new Error(
+      'creating a new target org requires --owner-user (or pass --target <uuid> to copy into an existing org)'
+    )
   if (args.targetNamespace === 'dooer-production' && args.execute && !args.confirmProduction)
     throw new Error('refusing to WRITE to dooer-production without --confirm-production')
 
@@ -468,7 +472,11 @@ async function main(passedArgs) {
 
   console.log(`\n=== seed-test-account · ${mode} ===`)
   console.log(`source: ${args.source}  @ ${args.sourceNamespace}`)
-  console.log(`target: ${args.target || `(create "${args.name}", owner ${args.ownerUser})`}  @ ${args.targetNamespace}`)
+  console.log(
+    `target: ${
+      args.target || `(create ${args.name ? `"${args.name}"` : "with the source's own name"}, owner ${args.ownerUser})`
+    }  @ ${args.targetNamespace}`
+  )
   console.log(
     `email scrub: ${args.emailScrub}  · copy tables: ${copyTables.length} · if-target-nonempty: ${args.ifTargetNonempty}\n`
   )
@@ -798,7 +806,12 @@ async function main(passedArgs) {
     await tgt.client.query("SET session_replication_role = 'origin'")
     await tgt.client.query('COMMIT')
     console.log(`\nEXECUTE complete — ${written} rows written to ${targetOrg} @ ${args.targetNamespace}.`)
-    if (createdOrg) console.log(`Created org ${targetOrg} ("${args.name}") with owner ${args.ownerUser} (role Owner).`)
+    if (createdOrg)
+      console.log(
+        `Created org ${targetOrg}${args.name ? ` ("${args.name}")` : ' (name inherited from the source)'} with owner ${
+          args.ownerUser
+        } (role Owner).`
+      )
     // copy the actual files (S3) for every copied blob row — on by default (skip with --skip-files)
     if (!args.skipFiles) await copyFiles(src, args, map, remapUuid)
     else
@@ -860,15 +873,17 @@ async function createTargetOrg(src, tgt, args, targetOrg) {
     )
   ).rows[0]
   if (!row) throw new Error(`source companies row ${args.source} not found`)
+  // No --name given → keep the source org's own name (short_name still gets a unique suffix below).
+  const name = args.name || row.company_name || 'Copied organization'
   const slug =
-    args.name
+    name
       .toLowerCase()
       .replace(/[^a-z0-9]+/g, '-')
       .replace(/^-|-$/g, '')
       .slice(0, 40) || 'org'
   const overrides = {
     companies_pk: targetOrg,
-    company_name: args.name,
+    company_name: name,
     short_name: `${slug}-${newUuid().slice(0, 8)}`, // short_name is UNIQUE
     api_uuid: newUuid(),
   }

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.11.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,10 +111,36 @@ 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.
+Naming: with **neither `--name` nor `--target`** the copy creates a new org that **keeps the source org's
+own name** (its `short_name` still gets a unique suffix). Pass `--name` to rename it, or `--target <uuid>`
+to copy into an org that already exists.
+
+**Many orgs at once** — `--sourcefile` takes a file with one org uuid per line (`#` comments and blank
+lines ignored, duplicates collapsed). Each org is copied in turn and keeps its own name, so `--name` and
+`--target` (which describe a single target) are rejected with it:
+
+```bash
+cat > orgs.txt <<'IDS'
+e45a3bc4-1b61-4f55-9bd6-de2705420cc2
+0391c6ba-2c41-458b-95d2-a2d555117833
+IDS
+
+npx @dooer/dooer-test-env@latest customer copy \
+  --sourcefile orgs.txt \
+  --source-namespace dooer-production \
+  --target-local \
+  --owner-user <local-customer-users_pk> \
+  --execute
+```
+
+One failure does not abandon the batch: failures are collected and summarised at the end (and the command
+exits non-zero).
+
+It scans all ~336 tables in the source before writing, so expect a few minutes per org on a production
+source.
 
 ### Run your own code — one service, or several at once
 
@@ -120,23 +148,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**