quidproquo-cli 0.1.18 → 0.1.20

package/lib/esm/commands/goDevApi.js

@@ -2,6 +2,10 @@
 // generates the dev-server entry, builds the rspack config, then runs rspack
 // in watch mode, restarting the server process on every successful rebuild.
 //
+// A restart is not instant: the server drains in-flight work and checkpoints
+// its stores on the way out (typically tens of ms, 5s worst case), and this
+// command waits for that before starting the replacement.
+//
 // The one thing NOT hot-reloaded is the qpq configs themselves: each service's
 // infrastructure.ts is evaluated once at launch and baked into the
 // `quidproquo-dynamic-loader` virtual module — config changes need a full
@@ -10,10 +14,13 @@ import { getAppServiceQpqConfigs, getDevServerRspackConfig } from 'quidproquo-de
 import { spawn } from 'child_process';
 import path from 'path';
 import { rspack } from '@rspack/core';
+import { hasArgFlag } from '../lib/args';
 import { primeDeployEnvFromConfig } from '../lib/deployEnv';
 import { writeDevServerEntry } from '../lib/devServerEntry';
 import { getRoot } from '../lib/discovery';
-import { killOtherQpqDevProcesses, killStaleListeners } from '../lib/killStaleListeners';
+import { KEEP_OTHER_DEV_SERVERS_FLAG } from '../lib/keepOtherDevServersFlag';
+import { killChildWithEscalation } from '../lib/killChildWithEscalation';
+import { killOtherQpqDevProcesses, killStaleListeners, reportPortHolders } from '../lib/killStaleListeners';
 import { resolveAppSelection } from '../lib/resolveAppSelection';
 // 8080/8888 are set in the generated entry; 3001 is the quidproquo-dev-server
 // file-storage (secure URL) default port.
@@ -25,11 +32,22 @@ export const goDevApiCommand = async (argv) => {
     process.env.QPQ_DEV_APP = appName;
     primeDeployEnvFromConfig(appName);
     console.log(`Dev server for app [${appName}]`);
-    // Catches a lingering watcher from a previous run even if its spawned
-    // child already exited (see killOtherQpqDevProcesses) — then the usual
-    // port-based sweep for anything else still bound to our ports.
-    killOtherQpqDevProcesses(root);
-    killStaleListeners(DEV_SERVER_PORTS, (command) => command.includes(DEV_SERVER_BUNDLE_PATH));
+    // The sweep matches on a RELATIVE bundle path, so every checkout's dev
+    // server looks like ours and a sibling worktree gets taken down with it.
+    // Opting out spares it, at the cost of this one not starting: the ports are
+    // the same either way, so what you get instead is EADDRINUSE. Report who
+    // holds them, or that failure says nothing about the cause.
+    if (hasArgFlag(argv, KEEP_OTHER_DEV_SERVERS_FLAG)) {
+        console.log(`${KEEP_OTHER_DEV_SERVERS_FLAG}: leaving other dev servers alone.`);
+        reportPortHolders(DEV_SERVER_PORTS);
+    }
+    else {
+        // Catches a lingering watcher from a previous run even if its spawned
+        // child already exited (see killOtherQpqDevProcesses) — then the usual
+        // port-based sweep for anything else still bound to our ports.
+        killOtherQpqDevProcesses(root);
+        killStaleListeners(DEV_SERVER_PORTS, (command) => command.includes(DEV_SERVER_BUNDLE_PATH));
+    }
     const qpqConfigs = getAppServiceQpqConfigs(root, appName);
     const entry = writeDevServerEntry(root, appName);
     const rspackConfig = getDevServerRspackConfig({ root, entry, qpqConfigs });
@@ -61,7 +79,10 @@ export const goDevApiCommand = async (argv) => {
             restartQueued = false;
             startServer();
         });
-        child.kill();
+        // Not a bare kill: the server drains in-flight work before it exits, so it
+        // needs asking properly and then a hard backstop if it wedges. Waiting for
+        // the exit is what keeps the ports free for the replacement.
+        void killChildWithEscalation(child);
     };
     console.log('Bundling dev server (watch mode)...');
     let lastHash;
@@ -85,10 +106,35 @@ export const goDevApiCommand = async (argv) => {
         console.log(child ? 'Rebuilt. Restarting dev server...' : 'Dev server bundled. Starting...');
         restartServer();
     });
-    process.on('SIGINT', () => {
+    // Wait for the server to finish draining before tearing the watcher down and
+    // exiting: closing the compiler first would exit the parent while the child
+    // is still writing, which is the race this whole path exists to close.
+    //
+    // SIGTERM as well as SIGINT, and it is load-bearing rather than symmetry for
+    // its own sake. This process is a WRAPPER: the dev server that handles
+    // signals and drains its work is the child it spawned. Without a handler
+    // here, SIGTERM (what `docker stop` sends, and what any script stopping this
+    // programmatically sends) kills the wrapper outright on the default
+    // disposition, the child never gets asked to stop, and every guarantee the
+    // dev server's shutdown sequence makes is bypassed. go:dev:web already
+    // handles both.
+    let shuttingDown = false;
+    const handleShutdownSignal = async () => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
         restartQueued = true; // suppress the crash log / rebuild-restart on our own kill
-        child?.kill();
+        if (child) {
+            await killChildWithEscalation(child);
+        }
         compiler.close(() => process.exit(0));
+    };
+    process.on('SIGINT', () => {
+        void handleShutdownSignal();
+    });
+    process.on('SIGTERM', () => {
+        void handleShutdownSignal();
     });
 };
 //# sourceMappingURL=goDevApi.js.map

package/lib/esm/commands/goDevApi.js.map

@@ -1 +1 @@
-{"version":3,"file":"goDevApi.js","sourceRoot":"","sources":["../../../src/commands/goDevApi.ts"],"names":[],"mappings":"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","sourcesContent":["// `qpq go:dev:api` — boots the QPQ local dev server. Resolves the app,\n// generates the dev-server entry, builds the rspack config, then runs rspack\n// in watch mode, restarting the server process on every successful rebuild.\n//\n// The one thing NOT hot-reloaded is the qpq configs themselves: each service's\n// infrastructure.ts is evaluated once at launch and baked into the\n// `quidproquo-dynamic-loader` virtual module — config changes need a full\n// `go:dev:api` restart.\nimport { getAppServiceQpqConfigs, getDevServerRspackConfig } from 'quidproquo-deploy-rspack';\n\nimport { ChildProcess, spawn } from 'child_process';\nimport fs from 'fs';\nimport path from 'path';\nimport { rspack } from '@rspack/core';\n\nimport { primeDeployEnvFromConfig } from '../lib/deployEnv';\nimport { writeDevServerEntry } from '../lib/devServerEntry';\nimport { getRoot } from '../lib/discovery';\nimport { killOtherQpqDevProcesses, killStaleListeners } from '../lib/killStaleListeners';\nimport { resolveAppSelection } from '../lib/resolveAppSelection';\n\n// 8080/8888 are set in the generated entry; 3001 is the quidproquo-dev-server\n// file-storage (secure URL) default port.\nconst DEV_SERVER_PORTS = [8080, 8888, 3001];\nconst DEV_SERVER_BUNDLE_PATH = path.join('dist', 'qpq', 'dev-server', 'main.js');\n\nexport const goDevApiCommand = async (argv: string[]): Promise<void> => {\n  const root = getRoot();\n  const appName = await resolveAppSelection({ argv, envVar: 'QPQ_DEV_APP' });\n  process.env.QPQ_DEV_APP = appName;\n  primeDeployEnvFromConfig(appName);\n  console.log(`Dev server for app [${appName}]`);\n\n  // Catches a lingering watcher from a previous run even if its spawned\n  // child already exited (see killOtherQpqDevProcesses) — then the usual\n  // port-based sweep for anything else still bound to our ports.\n  killOtherQpqDevProcesses(root);\n  killStaleListeners(DEV_SERVER_PORTS, (command) => command.includes(DEV_SERVER_BUNDLE_PATH));\n\n  const qpqConfigs = getAppServiceQpqConfigs(root, appName);\n  const entry = writeDevServerEntry(root, appName);\n  const rspackConfig = getDevServerRspackConfig({ root, entry, qpqConfigs });\n  const bundlePath = path.join(root, DEV_SERVER_BUNDLE_PATH);\n  const env = { ...process.env, QPQ_DEV_APP: appName };\n\n  // The long-lived server process (HTTP 8080 / WS 8888), restarted per rebuild.\n  let child: ChildProcess | null = null;\n  let restartQueued = false;\n\n  const startServer = (): void => {\n    child = spawn('node', [bundlePath], { stdio: 'inherit', env });\n    child.on('exit', (code) => {\n      child = null;\n      if (!restartQueued) {\n        // Crashed (or exited) on its own — leave it down; the next successful\n        // rebuild (i.e. the next file save) brings it back up.\n        console.log(`Dev server exited with code ${code}. Save a file to restart it.`);\n      }\n    });\n  };\n\n  const restartServer = (): void => {\n    if (restartQueued) return;\n    if (!child) {\n      startServer();\n      return;\n    }\n    restartQueued = true;\n    child.once('exit', () => {\n      restartQueued = false;\n      startServer();\n    });\n    child.kill();\n  };\n\n  console.log('Bundling dev server (watch mode)...');\n  let lastHash: string | null | undefined;\n  const compiler = rspack(rspackConfig);\n  compiler.watch({ aggregateTimeout: 200 }, (err, stats) => {\n    if (err) {\n      console.error(err);\n      return;\n    }\n    if (stats?.hasErrors()) {\n      console.error(stats.toString({ colors: true, chunks: false, modules: false }));\n      console.log('Build failed — dev server not restarted. Fix the error and save again.');\n      return;\n    }\n    // Skip no-op rebuilds (e.g. the virtual-module-triggered second compile at\n    // startup): only restart when the output actually changed.\n    if (stats?.hash === lastHash && child) {\n      return;\n    }\n    lastHash = stats?.hash;\n    console.log(child ? 'Rebuilt. Restarting dev server...' : 'Dev server bundled. Starting...');\n    restartServer();\n  });\n\n  process.on('SIGINT', () => {\n    restartQueued = true; // suppress the crash log / rebuild-restart on our own kill\n    child?.kill();\n    compiler.close(() => process.exit(0));\n  });\n};\n"]}
+{"version":3,"file":"goDevApi.js","sourceRoot":"","sources":["../../../src/commands/goDevApi.ts"],"names":[],"mappings":"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","sourcesContent":["// `qpq go:dev:api` — boots the QPQ local dev server. Resolves the app,\n// generates the dev-server entry, builds the rspack config, then runs rspack\n// in watch mode, restarting the server process on every successful rebuild.\n//\n// A restart is not instant: the server drains in-flight work and checkpoints\n// its stores on the way out (typically tens of ms, 5s worst case), and this\n// command waits for that before starting the replacement.\n//\n// The one thing NOT hot-reloaded is the qpq configs themselves: each service's\n// infrastructure.ts is evaluated once at launch and baked into the\n// `quidproquo-dynamic-loader` virtual module — config changes need a full\n// `go:dev:api` restart.\nimport { getAppServiceQpqConfigs, getDevServerRspackConfig } from 'quidproquo-deploy-rspack';\n\nimport { ChildProcess, spawn } from 'child_process';\nimport fs from 'fs';\nimport path from 'path';\nimport { rspack } from '@rspack/core';\n\nimport { hasArgFlag } from '../lib/args';\nimport { primeDeployEnvFromConfig } from '../lib/deployEnv';\nimport { writeDevServerEntry } from '../lib/devServerEntry';\nimport { getRoot } from '../lib/discovery';\nimport { KEEP_OTHER_DEV_SERVERS_FLAG } from '../lib/keepOtherDevServersFlag';\nimport { killChildWithEscalation } from '../lib/killChildWithEscalation';\nimport { killOtherQpqDevProcesses, killStaleListeners, reportPortHolders } from '../lib/killStaleListeners';\nimport { resolveAppSelection } from '../lib/resolveAppSelection';\n\n// 8080/8888 are set in the generated entry; 3001 is the quidproquo-dev-server\n// file-storage (secure URL) default port.\nconst DEV_SERVER_PORTS = [8080, 8888, 3001];\nconst DEV_SERVER_BUNDLE_PATH = path.join('dist', 'qpq', 'dev-server', 'main.js');\n\nexport const goDevApiCommand = async (argv: string[]): Promise<void> => {\n  const root = getRoot();\n  const appName = await resolveAppSelection({ argv, envVar: 'QPQ_DEV_APP' });\n  process.env.QPQ_DEV_APP = appName;\n  primeDeployEnvFromConfig(appName);\n  console.log(`Dev server for app [${appName}]`);\n\n  // The sweep matches on a RELATIVE bundle path, so every checkout's dev\n  // server looks like ours and a sibling worktree gets taken down with it.\n  // Opting out spares it, at the cost of this one not starting: the ports are\n  // the same either way, so what you get instead is EADDRINUSE. Report who\n  // holds them, or that failure says nothing about the cause.\n  if (hasArgFlag(argv, KEEP_OTHER_DEV_SERVERS_FLAG)) {\n    console.log(`${KEEP_OTHER_DEV_SERVERS_FLAG}: leaving other dev servers alone.`);\n    reportPortHolders(DEV_SERVER_PORTS);\n  } else {\n    // Catches a lingering watcher from a previous run even if its spawned\n    // child already exited (see killOtherQpqDevProcesses) — then the usual\n    // port-based sweep for anything else still bound to our ports.\n    killOtherQpqDevProcesses(root);\n    killStaleListeners(DEV_SERVER_PORTS, (command) => command.includes(DEV_SERVER_BUNDLE_PATH));\n  }\n\n  const qpqConfigs = getAppServiceQpqConfigs(root, appName);\n  const entry = writeDevServerEntry(root, appName);\n  const rspackConfig = getDevServerRspackConfig({ root, entry, qpqConfigs });\n  const bundlePath = path.join(root, DEV_SERVER_BUNDLE_PATH);\n  const env = { ...process.env, QPQ_DEV_APP: appName };\n\n  // The long-lived server process (HTTP 8080 / WS 8888), restarted per rebuild.\n  let child: ChildProcess | null = null;\n  let restartQueued = false;\n\n  const startServer = (): void => {\n    child = spawn('node', [bundlePath], { stdio: 'inherit', env });\n    child.on('exit', (code) => {\n      child = null;\n      if (!restartQueued) {\n        // Crashed (or exited) on its own — leave it down; the next successful\n        // rebuild (i.e. the next file save) brings it back up.\n        console.log(`Dev server exited with code ${code}. Save a file to restart it.`);\n      }\n    });\n  };\n\n  const restartServer = (): void => {\n    if (restartQueued) return;\n    if (!child) {\n      startServer();\n      return;\n    }\n    restartQueued = true;\n    child.once('exit', () => {\n      restartQueued = false;\n      startServer();\n    });\n\n    // Not a bare kill: the server drains in-flight work before it exits, so it\n    // needs asking properly and then a hard backstop if it wedges. Waiting for\n    // the exit is what keeps the ports free for the replacement.\n    void killChildWithEscalation(child);\n  };\n\n  console.log('Bundling dev server (watch mode)...');\n  let lastHash: string | null | undefined;\n  const compiler = rspack(rspackConfig);\n  compiler.watch({ aggregateTimeout: 200 }, (err, stats) => {\n    if (err) {\n      console.error(err);\n      return;\n    }\n    if (stats?.hasErrors()) {\n      console.error(stats.toString({ colors: true, chunks: false, modules: false }));\n      console.log('Build failed — dev server not restarted. Fix the error and save again.');\n      return;\n    }\n    // Skip no-op rebuilds (e.g. the virtual-module-triggered second compile at\n    // startup): only restart when the output actually changed.\n    if (stats?.hash === lastHash && child) {\n      return;\n    }\n    lastHash = stats?.hash;\n    console.log(child ? 'Rebuilt. Restarting dev server...' : 'Dev server bundled. Starting...');\n    restartServer();\n  });\n\n  // Wait for the server to finish draining before tearing the watcher down and\n  // exiting: closing the compiler first would exit the parent while the child\n  // is still writing, which is the race this whole path exists to close.\n  //\n  // SIGTERM as well as SIGINT, and it is load-bearing rather than symmetry for\n  // its own sake. This process is a WRAPPER: the dev server that handles\n  // signals and drains its work is the child it spawned. Without a handler\n  // here, SIGTERM (what `docker stop` sends, and what any script stopping this\n  // programmatically sends) kills the wrapper outright on the default\n  // disposition, the child never gets asked to stop, and every guarantee the\n  // dev server's shutdown sequence makes is bypassed. go:dev:web already\n  // handles both.\n  let shuttingDown = false;\n\n  const handleShutdownSignal = async (): Promise<void> => {\n    if (shuttingDown) {\n      return;\n    }\n    shuttingDown = true;\n\n    restartQueued = true; // suppress the crash log / rebuild-restart on our own kill\n\n    if (child) {\n      await killChildWithEscalation(child);\n    }\n\n    compiler.close(() => process.exit(0));\n  };\n\n  process.on('SIGINT', () => {\n    void handleShutdownSignal();\n  });\n\n  process.on('SIGTERM', () => {\n    void handleShutdownSignal();\n  });\n};\n"]}

package/lib/esm/commands/goDevWeb.js

@@ -13,9 +13,11 @@ import http from 'http';
 import { rspack } from '@rspack/core';
 import { RspackDevServer } from '@rspack/dev-server';
 import { getArgValue } from '../lib/args';
+import { hasArgFlag } from '../lib/args';
 import { primeDeployEnvFromConfig } from '../lib/deployEnv';
 import { getRoot } from '../lib/discovery';
-import { isQpqCliCommand, killStaleListeners } from '../lib/killStaleListeners';
+import { KEEP_OTHER_DEV_SERVERS_FLAG } from '../lib/keepOtherDevServersFlag';
+import { isQpqCliCommand, killStaleListeners, reportPortHolders } from '../lib/killStaleListeners';
 import { resolveAppSelection } from '../lib/resolveAppSelection';
 export const goDevWebCommand = async (argv, options = {}) => {
     const root = getRoot();
@@ -33,7 +35,13 @@ export const goDevWebCommand = async (argv, options = {}) => {
         console.error('No views projects found.');
         process.exit(1);
     }
-    killStaleListeners(views.map((v) => v.port), isQpqCliCommand);
+    // See goDevApi for why this is opt-out rather than always-on.
+    if (hasArgFlag(argv, KEEP_OTHER_DEV_SERVERS_FLAG)) {
+        reportPortHolders(views.map((v) => v.port));
+    }
+    else {
+        killStaleListeners(views.map((v) => v.port), isQpqCliCommand);
+    }
     // Every RspackDevServer.start() registers its own SIGINT/SIGTERM handler on
     // process — with a dozen views servers in one process that trips node's
     // default 10-listener warning. Size the limit to the fleet.

package/lib/esm/commands/goDevWeb.js.map

@@ -1 +1 @@
-{"version":3,"file":"goDevWeb.js","sourceRoot":"","sources":["../../../src/commands/goDevWeb.ts"],"names":[],"mappings":"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","sourcesContent":["// `qpq go:dev:web` — boots every views microfrontend's Rspack dev server\n// in-process (shell is the MF host app, plus all remotes on their own ports).\n// Everything is served dynamically; remotes resolve at runtime via\n// mf-manifest.json on localhost ports. Programmatic — no per-views\n// rspack.config.ts or npm serve script needed.\n//\n// Usage:\n//   qpq go:dev:web\n//   qpq go:dev:web --only shell,design\n//   qpq go:dev:web --app <name>\nimport { getAllViews, getViewsRspackConfig } from 'quidproquo-deploy-rspack';\n\nimport http from 'http';\nimport { rspack } from '@rspack/core';\nimport { RspackDevServer } from '@rspack/dev-server';\n\nimport { getArgValue } from '../lib/args';\nimport { primeDeployEnvFromConfig } from '../lib/deployEnv';\nimport { getRoot } from '../lib/discovery';\nimport { isQpqCliCommand, killStaleListeners } from '../lib/killStaleListeners';\nimport { resolveAppSelection } from '../lib/resolveAppSelection';\n\nexport type GoDevWebOptions = {\n  // The in-place \"(started)\" chip rewrite assumes this command owns the\n  // terminal; when stdout is shared with the API dev server (combined\n  // `qpq go:dev`) the cursor math breaks. The plain-line fallback is just a\n  // wall of \"  auth started\" noise interleaved with the API output, so drop\n  // the ready status altogether there.\n  hideStartedStatus?: boolean;\n};\n\nexport const goDevWebCommand = async (argv: string[], options: GoDevWebOptions = {}): Promise<void> => {\n  const root = getRoot();\n  const appName = await resolveAppSelection({ argv, envVar: 'QPQ_DEV_APP' });\n\n  process.env.LOCAL_DEV_SERVER = 'true';\n  process.env.NODE_ENV = 'development';\n  primeDeployEnvFromConfig(appName);\n\n  const only = getArgValue(argv, '--only')\n    ?.split(',')\n    .map((s) => s.trim());\n\n  let views = getAllViews(root, appName);\n  if (only) views = views.filter((v) => only.includes(v.service));\n  if (views.length === 0) {\n    console.error('No views projects found.');\n    process.exit(1);\n  }\n\n  killStaleListeners(\n    views.map((v) => v.port),\n    isQpqCliCommand,\n  );\n\n  // Every RspackDevServer.start() registers its own SIGINT/SIGTERM handler on\n  // process — with a dozen views servers in one process that trips node's\n  // default 10-listener warning. Size the limit to the fleet.\n  process.setMaxListeners(Math.max(process.getMaxListeners(), views.length * 2 + 10));\n\n  // Service names are padded to a common width so the \"(started)\" chips align.\n  const serviceColumnWidth = Math.max(...views.map((v) => v.service.length));\n\n  console.log(`Starting ${views.length} views dev servers for [${appName}]:`);\n  for (const v of views) console.log(`  http://localhost:${v.port}  ${v.service.padEnd(serviceColumnWidth)}`);\n\n  const servers: RspackDevServer[] = [];\n  let shuttingDown = false;\n\n  const shutdown = (code: number): void => {\n    if (shuttingDown) return;\n    shuttingDown = true;\n    Promise.allSettled(servers.map((server) => server.stop())).then(() => process.exit(code));\n  };\n\n  // The URL list above gets a yellow \"(started)\" chip appended in place as\n  // each dev server begins answering HTTP. The in-place rewrite moves the\n  // cursor up past everything printed since the list, so every line printed\n  // below it MUST go through logBelowList to keep the offset accurate.\n  let linesBelowList = 0;\n\n  const logBelowList = (line: string): void => {\n    console.log(line);\n    linesBelowList += 1;\n  };\n\n  const markStarted = (index: number): void => {\n    const v = views[index];\n    if (!process.stdout.isTTY) {\n      logBelowList(`  ${v.service} started`);\n      return;\n    }\n    const line = `  http://localhost:${v.port}  ${v.service.padEnd(serviceColumnWidth)}  \\x1b[33m(started)\\x1b[0m`;\n    const up = linesBelowList + (views.length - index);\n    process.stdout.write(`\\x1b[${up}F\\x1b[2K${line}\\x1b[${up}E`);\n  };\n\n  const pollUntilStarted = (index: number): void => {\n    const attempt = (): void => {\n      if (shuttingDown) return;\n      const req = http.get(\n        {\n          host: 'localhost',\n          port: views[index].port,\n          path: '/',\n          timeout: 1000,\n        },\n        (res) => {\n          res.resume();\n          markStarted(index);\n        },\n      );\n      req.on('error', () => setTimeout(attempt, 500));\n      req.on('timeout', () => req.destroy());\n    };\n    attempt();\n  };\n\n  for (const [index, view] of views.entries()) {\n    const config = getViewsRspackConfig(view.viewsDir);\n    const compiler = rspack(config);\n    const server = new RspackDevServer(config.devServer || { port: view.port }, compiler);\n    servers.push(server);\n\n    try {\n      await server.start();\n    } catch (e) {\n      logBelowList(`  [${view.service}] failed to start: ${(e as Error).message} — shutting down all views servers.`);\n      shutdown(1);\n      return;\n    }\n\n    // markStarted is the only consumer of the ready signal, so there is\n    // nothing to poll for when the status is hidden.\n    if (!options.hideStartedStatus) pollUntilStarted(index);\n  }\n\n  process.on('SIGINT', () => shutdown(0));\n  process.on('SIGTERM', () => shutdown(0));\n};\n"]}
+{"version":3,"file":"goDevWeb.js","sourceRoot":"","sources":["../../../src/commands/goDevWeb.ts"],"names":[],"mappings":"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","sourcesContent":["// `qpq go:dev:web` — boots every views microfrontend's Rspack dev server\n// in-process (shell is the MF host app, plus all remotes on their own ports).\n// Everything is served dynamically; remotes resolve at runtime via\n// mf-manifest.json on localhost ports. Programmatic — no per-views\n// rspack.config.ts or npm serve script needed.\n//\n// Usage:\n//   qpq go:dev:web\n//   qpq go:dev:web --only shell,design\n//   qpq go:dev:web --app <name>\nimport { getAllViews, getViewsRspackConfig } from 'quidproquo-deploy-rspack';\n\nimport http from 'http';\nimport { rspack } from '@rspack/core';\nimport { RspackDevServer } from '@rspack/dev-server';\n\nimport { getArgValue } from '../lib/args';\nimport { hasArgFlag } from '../lib/args';\nimport { primeDeployEnvFromConfig } from '../lib/deployEnv';\nimport { getRoot } from '../lib/discovery';\nimport { KEEP_OTHER_DEV_SERVERS_FLAG } from '../lib/keepOtherDevServersFlag';\nimport { isQpqCliCommand, killStaleListeners, reportPortHolders } from '../lib/killStaleListeners';\nimport { resolveAppSelection } from '../lib/resolveAppSelection';\n\nexport type GoDevWebOptions = {\n  // The in-place \"(started)\" chip rewrite assumes this command owns the\n  // terminal; when stdout is shared with the API dev server (combined\n  // `qpq go:dev`) the cursor math breaks. The plain-line fallback is just a\n  // wall of \"  auth started\" noise interleaved with the API output, so drop\n  // the ready status altogether there.\n  hideStartedStatus?: boolean;\n};\n\nexport const goDevWebCommand = async (argv: string[], options: GoDevWebOptions = {}): Promise<void> => {\n  const root = getRoot();\n  const appName = await resolveAppSelection({ argv, envVar: 'QPQ_DEV_APP' });\n\n  process.env.LOCAL_DEV_SERVER = 'true';\n  process.env.NODE_ENV = 'development';\n  primeDeployEnvFromConfig(appName);\n\n  const only = getArgValue(argv, '--only')\n    ?.split(',')\n    .map((s) => s.trim());\n\n  let views = getAllViews(root, appName);\n  if (only) views = views.filter((v) => only.includes(v.service));\n  if (views.length === 0) {\n    console.error('No views projects found.');\n    process.exit(1);\n  }\n\n  // See goDevApi for why this is opt-out rather than always-on.\n  if (hasArgFlag(argv, KEEP_OTHER_DEV_SERVERS_FLAG)) {\n    reportPortHolders(views.map((v) => v.port));\n  } else {\n    killStaleListeners(\n      views.map((v) => v.port),\n      isQpqCliCommand,\n    );\n  }\n\n  // Every RspackDevServer.start() registers its own SIGINT/SIGTERM handler on\n  // process — with a dozen views servers in one process that trips node's\n  // default 10-listener warning. Size the limit to the fleet.\n  process.setMaxListeners(Math.max(process.getMaxListeners(), views.length * 2 + 10));\n\n  // Service names are padded to a common width so the \"(started)\" chips align.\n  const serviceColumnWidth = Math.max(...views.map((v) => v.service.length));\n\n  console.log(`Starting ${views.length} views dev servers for [${appName}]:`);\n  for (const v of views) console.log(`  http://localhost:${v.port}  ${v.service.padEnd(serviceColumnWidth)}`);\n\n  const servers: RspackDevServer[] = [];\n  let shuttingDown = false;\n\n  const shutdown = (code: number): void => {\n    if (shuttingDown) return;\n    shuttingDown = true;\n    Promise.allSettled(servers.map((server) => server.stop())).then(() => process.exit(code));\n  };\n\n  // The URL list above gets a yellow \"(started)\" chip appended in place as\n  // each dev server begins answering HTTP. The in-place rewrite moves the\n  // cursor up past everything printed since the list, so every line printed\n  // below it MUST go through logBelowList to keep the offset accurate.\n  let linesBelowList = 0;\n\n  const logBelowList = (line: string): void => {\n    console.log(line);\n    linesBelowList += 1;\n  };\n\n  const markStarted = (index: number): void => {\n    const v = views[index];\n    if (!process.stdout.isTTY) {\n      logBelowList(`  ${v.service} started`);\n      return;\n    }\n    const line = `  http://localhost:${v.port}  ${v.service.padEnd(serviceColumnWidth)}  \\x1b[33m(started)\\x1b[0m`;\n    const up = linesBelowList + (views.length - index);\n    process.stdout.write(`\\x1b[${up}F\\x1b[2K${line}\\x1b[${up}E`);\n  };\n\n  const pollUntilStarted = (index: number): void => {\n    const attempt = (): void => {\n      if (shuttingDown) return;\n      const req = http.get(\n        {\n          host: 'localhost',\n          port: views[index].port,\n          path: '/',\n          timeout: 1000,\n        },\n        (res) => {\n          res.resume();\n          markStarted(index);\n        },\n      );\n      req.on('error', () => setTimeout(attempt, 500));\n      req.on('timeout', () => req.destroy());\n    };\n    attempt();\n  };\n\n  for (const [index, view] of views.entries()) {\n    const config = getViewsRspackConfig(view.viewsDir);\n    const compiler = rspack(config);\n    const server = new RspackDevServer(config.devServer || { port: view.port }, compiler);\n    servers.push(server);\n\n    try {\n      await server.start();\n    } catch (e) {\n      logBelowList(`  [${view.service}] failed to start: ${(e as Error).message} — shutting down all views servers.`);\n      shutdown(1);\n      return;\n    }\n\n    // markStarted is the only consumer of the ready signal, so there is\n    // nothing to poll for when the status is hidden.\n    if (!options.hideStartedStatus) pollUntilStarted(index);\n  }\n\n  process.on('SIGINT', () => shutdown(0));\n  process.on('SIGTERM', () => shutdown(0));\n};\n"]}

package/lib/esm/commands/setup.d.ts

@@ -0,0 +1 @@
+export declare const setupCommand: (argv: string[]) => Promise<void>;

package/lib/esm/commands/setup.js

@@ -0,0 +1,88 @@
+// `qpq setup` — takes a cloud environment from empty to deployed, in order, with
+// every step checked first so the menu shows what is already in place and a
+// rerun on a half-set-up account is safe. The platform (from the environment's
+// entry in deploy.config.json) contributes the steps.
+//   --check      print each step's status and exit, run nothing
+//   --yes        run every step without the menu
+//   --only a,b   run only the named step ids (no menu)
+import { getArgValue } from '../lib/args';
+import { resolveDeployEnvironment } from '../lib/deployEnv';
+import { promptCheckbox } from '../lib/prompts';
+import { resolveAppSelection } from '../lib/resolveAppSelection';
+import { getPlatformDriver } from '../platforms';
+const statusLabel = (result) => (result === null ? '?' : result.done ? 'done' : 'todo');
+const printChecklist = (checked) => {
+    for (const { step, result } of checked) {
+        const detail = result?.detail ? `  ${result.detail}` : '';
+        console.log(`  [${statusLabel(result).padEnd(4)}] ${step.name}${detail}`);
+    }
+};
+const checkAll = async (steps) => {
+    const checked = [];
+    for (const step of steps) {
+        try {
+            checked.push({ step, result: await step.check() });
+        }
+        catch (error) {
+            checked.push({ step, result: { done: false, detail: `check failed: ${error instanceof Error ? error.message : String(error)}` } });
+        }
+    }
+    return checked;
+};
+// Steps not yet done are preselected; done ones can still be picked to rerun.
+const chooseSteps = async (checked) => {
+    const chosen = await promptCheckbox('Setup steps to run (space toggles, enter runs in order)', checked.map(({ step, result }) => ({
+        name: `[${statusLabel(result).padEnd(4)}] ${step.name}`,
+        value: step,
+        checked: !result?.done,
+        description: result?.detail,
+    })));
+    // Always run in checklist order, whatever order they were ticked in.
+    return checked.map(({ step }) => step).filter((step) => chosen.includes(step));
+};
+const selectFromArgs = (steps, argv) => {
+    if (argv.includes('--yes')) {
+        return steps;
+    }
+    const only = getArgValue(argv, '--only');
+    if (!only) {
+        return null;
+    }
+    const ids = only.split(',').map((id) => id.trim());
+    const unknown = ids.filter((id) => !steps.some((step) => step.id === id));
+    if (unknown.length > 0) {
+        console.error(`Unknown setup step id(s): ${unknown.join(', ')}. Known: ${steps.map((step) => step.id).join(', ')}`);
+        process.exit(1);
+    }
+    return steps.filter((step) => ids.includes(step.id));
+};
+export const setupCommand = async (argv) => {
+    const appName = await resolveAppSelection({ argv, envVar: 'DEPLOY_APP_NAME' });
+    const { environment, platform } = await resolveDeployEnvironment(argv, appName);
+    const driver = getPlatformDriver(platform);
+    if (!driver.setupSteps) {
+        console.log(`The '${platform}' platform has nothing to set up for environment '${environment}'.`);
+        return;
+    }
+    const steps = await driver.setupSteps(appName, environment);
+    console.log(`\nSetup for app '${appName}', environment '${environment}' (${platform})\n`);
+    const checked = await checkAll(steps);
+    printChecklist(checked);
+    console.log('');
+    if (argv.includes('--check')) {
+        return;
+    }
+    const toRun = selectFromArgs(steps, argv) ?? (await chooseSteps(checked));
+    if (toRun.length === 0) {
+        console.log('Nothing selected.');
+        return;
+    }
+    for (const step of toRun) {
+        console.log(`\n== ${step.name}\n`);
+        await step.run();
+    }
+    console.log('\nSetup complete. Final state:\n');
+    printChecklist(await checkAll(steps));
+    console.log(`\nNext: deploy the services with  npx qpq go:docker all all --app ${appName} --env ${environment}`);
+};
+//# sourceMappingURL=setup.js.map

package/lib/esm/commands/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../src/commands/setup.ts"],"names":[],"mappings":"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","sourcesContent":["// `qpq setup` — takes a cloud environment from empty to deployed, in order, with\n// every step checked first so the menu shows what is already in place and a\n// rerun on a half-set-up account is safe. The platform (from the environment's\n// entry in deploy.config.json) contributes the steps.\n//   --check      print each step's status and exit, run nothing\n//   --yes        run every step without the menu\n//   --only a,b   run only the named step ids (no menu)\nimport { getArgValue } from '../lib/args';\nimport { resolveDeployEnvironment } from '../lib/deployEnv';\nimport { promptCheckbox } from '../lib/prompts';\nimport { resolveAppSelection } from '../lib/resolveAppSelection';\nimport { SetupCheckResult, SetupStep } from '../lib/setupStep';\nimport { getPlatformDriver } from '../platforms';\n\ntype CheckedStep = { step: SetupStep; result: SetupCheckResult | null };\n\nconst statusLabel = (result: SetupCheckResult | null): string => (result === null ? '?' : result.done ? 'done' : 'todo');\n\nconst printChecklist = (checked: CheckedStep[]): void => {\n  for (const { step, result } of checked) {\n    const detail = result?.detail ? `  ${result.detail}` : '';\n    console.log(`  [${statusLabel(result).padEnd(4)}] ${step.name}${detail}`);\n  }\n};\n\nconst checkAll = async (steps: SetupStep[]): Promise<CheckedStep[]> => {\n  const checked: CheckedStep[] = [];\n  for (const step of steps) {\n    try {\n      checked.push({ step, result: await step.check() });\n    } catch (error) {\n      checked.push({ step, result: { done: false, detail: `check failed: ${error instanceof Error ? error.message : String(error)}` } });\n    }\n  }\n  return checked;\n};\n\n// Steps not yet done are preselected; done ones can still be picked to rerun.\nconst chooseSteps = async (checked: CheckedStep[]): Promise<SetupStep[]> => {\n  const chosen = await promptCheckbox(\n    'Setup steps to run (space toggles, enter runs in order)',\n    checked.map(({ step, result }) => ({\n      name: `[${statusLabel(result).padEnd(4)}] ${step.name}`,\n      value: step,\n      checked: !result?.done,\n      description: result?.detail,\n    })),\n  );\n\n  // Always run in checklist order, whatever order they were ticked in.\n  return checked.map(({ step }) => step).filter((step) => chosen.includes(step));\n};\n\nconst selectFromArgs = (steps: SetupStep[], argv: string[]): SetupStep[] | null => {\n  if (argv.includes('--yes')) {\n    return steps;\n  }\n\n  const only = getArgValue(argv, '--only');\n  if (!only) {\n    return null;\n  }\n\n  const ids = only.split(',').map((id) => id.trim());\n  const unknown = ids.filter((id) => !steps.some((step) => step.id === id));\n  if (unknown.length > 0) {\n    console.error(`Unknown setup step id(s): ${unknown.join(', ')}. Known: ${steps.map((step) => step.id).join(', ')}`);\n    process.exit(1);\n  }\n\n  return steps.filter((step) => ids.includes(step.id));\n};\n\nexport const setupCommand = async (argv: string[]): Promise<void> => {\n  const appName = await resolveAppSelection({ argv, envVar: 'DEPLOY_APP_NAME' });\n  const { environment, platform } = await resolveDeployEnvironment(argv, appName);\n  const driver = getPlatformDriver(platform);\n\n  if (!driver.setupSteps) {\n    console.log(`The '${platform}' platform has nothing to set up for environment '${environment}'.`);\n    return;\n  }\n\n  const steps = await driver.setupSteps(appName, environment);\n\n  console.log(`\\nSetup for app '${appName}', environment '${environment}' (${platform})\\n`);\n  const checked = await checkAll(steps);\n  printChecklist(checked);\n  console.log('');\n\n  if (argv.includes('--check')) {\n    return;\n  }\n\n  const toRun = selectFromArgs(steps, argv) ?? (await chooseSteps(checked));\n  if (toRun.length === 0) {\n    console.log('Nothing selected.');\n    return;\n  }\n\n  for (const step of toRun) {\n    console.log(`\\n== ${step.name}\\n`);\n    await step.run();\n  }\n\n  console.log('\\nSetup complete. Final state:\\n');\n  printChecklist(await checkAll(steps));\n  console.log(`\\nNext: deploy the services with  npx qpq go:docker all all --app ${appName} --env ${environment}`);\n};\n"]}

package/lib/esm/lib/args.d.ts

@@ -1,2 +1,3 @@
 export declare const getArgValue: (argv: string[], flag: string) => string | undefined;
+export declare const hasArgFlag: (argv: string[], flag: string) => boolean;
 export declare const getPositionalArgs: (argv: string[], valueFlags: string[]) => string[];

package/lib/esm/lib/args.js

@@ -6,6 +6,15 @@ export const getArgValue = (argv, flag) => {
     const idx = argv.indexOf(flag);
     return idx >= 0 ? argv[idx + 1] : undefined;
 };
+// A presence-only flag: `--foo`. `--foo=false` is honoured as off, so a
+// wrapper script can pass the flag through with a computed value rather than
+// having to conditionally omit it.
+export const hasArgFlag = (argv, flag) => {
+    const eq = argv.find((a) => a.startsWith(`${flag}=`));
+    if (eq)
+        return eq.slice(`${flag}=`.length) !== 'false';
+    return argv.includes(flag);
+};
 // Positional args = non-flag args, skipping values consumed by known flags.
 export const getPositionalArgs = (argv, valueFlags) => argv.filter((arg, index) => {
     if (arg.startsWith('--'))

package/lib/esm/lib/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/lib/args.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAc,EAAE,IAAY,EAAsB,EAAE;IAC9E,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IACtD,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAc,EAAE,UAAoB,EAAY,EAAE,CAClF,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;IACzB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,CAAC,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AACtD,CAAC,CAAC,CAAC","sourcesContent":["// Flag parsing over the command's argv (everything after the command name).\nexport const getArgValue = (argv: string[], flag: string): string | undefined => {\n  const eq = argv.find((a) => a.startsWith(`${flag}=`));\n  if (eq) return eq.slice(`${flag}=`.length);\n  const idx = argv.indexOf(flag);\n  return idx >= 0 ? argv[idx + 1] : undefined;\n};\n\n// Positional args = non-flag args, skipping values consumed by known flags.\nexport const getPositionalArgs = (argv: string[], valueFlags: string[]): string[] =>\n  argv.filter((arg, index) => {\n    if (arg.startsWith('--')) return false;\n    const previous = argv[index - 1];\n    return !(previous && valueFlags.includes(previous));\n  });\n"]}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../../src/lib/args.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAc,EAAE,IAAY,EAAsB,EAAE;IAC9E,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IACtD,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC,CAAC;AAEF,wEAAwE;AACxE,6EAA6E;AAC7E,mCAAmC;AACnC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAc,EAAE,IAAY,EAAW,EAAE;IAClE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;IACtD,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC;IAEvD,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAc,EAAE,UAAoB,EAAY,EAAE,CAClF,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;IACzB,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,CAAC,QAAQ,IAAI,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AACtD,CAAC,CAAC,CAAC","sourcesContent":["// Flag parsing over the command's argv (everything after the command name).\nexport const getArgValue = (argv: string[], flag: string): string | undefined => {\n  const eq = argv.find((a) => a.startsWith(`${flag}=`));\n  if (eq) return eq.slice(`${flag}=`.length);\n  const idx = argv.indexOf(flag);\n  return idx >= 0 ? argv[idx + 1] : undefined;\n};\n\n// A presence-only flag: `--foo`. `--foo=false` is honoured as off, so a\n// wrapper script can pass the flag through with a computed value rather than\n// having to conditionally omit it.\nexport const hasArgFlag = (argv: string[], flag: string): boolean => {\n  const eq = argv.find((a) => a.startsWith(`${flag}=`));\n  if (eq) return eq.slice(`${flag}=`.length) !== 'false';\n\n  return argv.includes(flag);\n};\n\n// Positional args = non-flag args, skipping values consumed by known flags.\nexport const getPositionalArgs = (argv: string[], valueFlags: string[]): string[] =>\n  argv.filter((arg, index) => {\n    if (arg.startsWith('--')) return false;\n    const previous = argv[index - 1];\n    return !(previous && valueFlags.includes(previous));\n  });\n"]}

package/lib/esm/lib/keepOtherDevServersFlag.d.ts

@@ -0,0 +1 @@
+export declare const KEEP_OTHER_DEV_SERVERS_FLAG = "--keep-other-dev-servers";

package/lib/esm/lib/keepOtherDevServersFlag.js

@@ -0,0 +1,8 @@
+// Opt out of the pre-start sweep that kills anything already holding the dev
+// ports, including a dev server belonging to a different checkout of the same
+// repo. Off by default, so the existing behaviour is unchanged.
+//
+// One flag rather than one per command: `go:dev` hands the same argv to both
+// `go:dev:api` and `go:dev:web`, so declaring it once covers all three.
+export const KEEP_OTHER_DEV_SERVERS_FLAG = '--keep-other-dev-servers';
+//# sourceMappingURL=keepOtherDevServersFlag.js.map

package/lib/esm/lib/keepOtherDevServersFlag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keepOtherDevServersFlag.js","sourceRoot":"","sources":["../../../src/lib/keepOtherDevServersFlag.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,MAAM,CAAC,MAAM,2BAA2B,GAAG,0BAA0B,CAAC","sourcesContent":["// Opt out of the pre-start sweep that kills anything already holding the dev\n// ports, including a dev server belonging to a different checkout of the same\n// repo. Off by default, so the existing behaviour is unchanged.\n//\n// One flag rather than one per command: `go:dev` hands the same argv to both\n// `go:dev:api` and `go:dev:web`, so declaring it once covers all three.\nexport const KEEP_OTHER_DEV_SERVERS_FLAG = '--keep-other-dev-servers';\n"]}

package/lib/esm/lib/killChildWithEscalation.d.ts

@@ -0,0 +1,10 @@
+import { ChildProcess } from 'child_process';
+/**
+ * SIGTERM the child, resolve once it has actually exited, and SIGKILL it if it
+ * has not gone within the grace window.
+ *
+ * Resolves rather than rejects on escalation: the caller's next move is the
+ * same either way (start the replacement), and a rejection would only give
+ * every call site a catch to write.
+ */
+export declare const killChildWithEscalation: (child: ChildProcess, graceMs?: number) => Promise<void>;

package/lib/esm/lib/killChildWithEscalation.js

@@ -0,0 +1,29 @@
+// Above the dev server's 5s worst-case shutdown budget, below docker's 10s
+// default stop grace, so a container stop still exits cleanly rather than
+// being SIGKILLed by docker mid-escalation.
+const DEFAULT_KILL_GRACE_MS = 6000;
+/**
+ * SIGTERM the child, resolve once it has actually exited, and SIGKILL it if it
+ * has not gone within the grace window.
+ *
+ * Resolves rather than rejects on escalation: the caller's next move is the
+ * same either way (start the replacement), and a rejection would only give
+ * every call site a catch to write.
+ */
+export const killChildWithEscalation = (child, graceMs = DEFAULT_KILL_GRACE_MS) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            console.warn(`Dev server did not exit within ${graceMs}ms — sending SIGKILL.`);
+            child.kill('SIGKILL');
+        }, graceMs);
+        child.once('exit', () => {
+            clearTimeout(timer);
+            resolve();
+        });
+        child.kill('SIGTERM');
+    });
+};
+//# sourceMappingURL=killChildWithEscalation.js.map

package/lib/esm/lib/killChildWithEscalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"killChildWithEscalation.js","sourceRoot":"","sources":["../../../src/lib/killChildWithEscalation.ts"],"names":[],"mappings":"AAWA,2EAA2E;AAC3E,0EAA0E;AAC1E,4CAA4C;AAC5C,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,KAAmB,EAAE,OAAO,GAAG,qBAAqB,EAAiB,EAAE;IAC7G,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QACzD,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,OAAO,CAAC,IAAI,CAAC,kCAAkC,OAAO,uBAAuB,CAAC,CAAC;YAC/E,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,CAAC,EAAE,OAAO,CAAC,CAAC;QAEZ,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC","sourcesContent":["// Stopping the dev server child, with a hard backstop.\n//\n// The dev server now runs an ordered shutdown on SIGTERM (drain in-flight\n// work, then checkpoint the stores) instead of dying instantly. That is the\n// point - it is what stops a save-triggered restart eating a queue message\n// mid-story - but it means a bare `child.kill()` followed by waiting for exit\n// can now wait forever if a teardown wedges. Without escalation this would\n// trade a data-loss bug for a hung-restart bug, and the next launch would find\n// its ports still held.\nimport { ChildProcess } from 'child_process';\n\n// Above the dev server's 5s worst-case shutdown budget, below docker's 10s\n// default stop grace, so a container stop still exits cleanly rather than\n// being SIGKILLed by docker mid-escalation.\nconst DEFAULT_KILL_GRACE_MS = 6000;\n\n/**\n * SIGTERM the child, resolve once it has actually exited, and SIGKILL it if it\n * has not gone within the grace window.\n *\n * Resolves rather than rejects on escalation: the caller's next move is the\n * same either way (start the replacement), and a rejection would only give\n * every call site a catch to write.\n */\nexport const killChildWithEscalation = (child: ChildProcess, graceMs = DEFAULT_KILL_GRACE_MS): Promise<void> => {\n  if (child.exitCode !== null || child.signalCode !== null) {\n    return Promise.resolve();\n  }\n\n  return new Promise<void>((resolve) => {\n    const timer = setTimeout(() => {\n      console.warn(`Dev server did not exit within ${graceMs}ms — sending SIGKILL.`);\n      child.kill('SIGKILL');\n    }, graceMs);\n\n    child.once('exit', () => {\n      clearTimeout(timer);\n      resolve();\n    });\n\n    child.kill('SIGTERM');\n  });\n};\n"]}

package/lib/esm/lib/killStaleListeners.d.ts

@@ -1,3 +1,17 @@
 export declare const isQpqCliCommand: (command: string) => boolean;
 export declare const killOtherQpqDevProcesses: (root: string) => void;
+/**
+ * Say what is holding these ports, without touching it.
+ *
+ * The other half of --keep-other-dev-servers: sparing a sibling checkout's dev
+ * server means this one cannot bind, and an unexplained EADDRINUSE is a worse
+ * experience than the silent kill it replaces. Naming the pid and the command
+ * turns "it just died" into something you can act on.
+ *
+ * Worded as a prediction, not a fact, because it IS one: this runs before the
+ * bundle step, so by the time anything binds - seconds later - the holder may
+ * well have gone. Stating "port in use" and then starting cleanly reads like
+ * the warning was wrong.
+ */
+export declare const reportPortHolders: (ports: number[]) => void;
 export declare const killStaleListeners: (ports: number[], isOurs: (command: string) => boolean) => void;

package/lib/esm/lib/killStaleListeners.js

@@ -33,17 +33,36 @@ export const isQpqCliCommand = (command) => command
 // one (a real child can sit as a zombie answering `kill(pid, 0)` until this
 // process's own event loop reaps it, which a tight sync loop would starve;
 // doesn't apply to a process we didn't spawn).
-const waitForPidGone = (pid, timeoutMs = 3000) => {
+//
+// The default covers the dev server's graceful shutdown (drain in-flight work,
+// then checkpoint the stores) with room to spare — it used to be 3s, which was
+// fine when the server died instantly and is not now. Returns whether the pid
+// actually went, because a caller about to bind these ports has to escalate
+// rather than hope: giving up while the old server still holds 8080 is exactly
+// the EADDRINUSE this file exists to prevent.
+const waitForPidGone = (pid, timeoutMs = 8000) => {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         try {
             process.kill(pid, 0);
         }
         catch {
-            return; // throws once the pid no longer exists
+            return true; // throws once the pid no longer exists
         }
         execSync('sleep 0.05');
     }
+    return false;
+};
+// Last resort for a process that ignored, or wedged during, its graceful stop.
+const killPidHard = (pid) => {
+    console.warn(`Process ${pid} did not exit gracefully — sending SIGKILL.`);
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch {
+        return; // raced us and exited after all
+    }
+    waitForPidGone(pid, 2000);
 };
 // realpath'd: lsof reports the canonical path (e.g. /private/tmp on macOS,
 // where /tmp is a symlink), so comparing against a caller-supplied root
@@ -121,36 +140,66 @@ export const killOtherQpqDevProcesses = (root) => {
             continue;
         console.log(`Killing other qpq dev process for this repo (pid ${pid}): ${command}`);
         process.kill(pid, 'SIGINT');
-        waitForPidGone(pid);
+        if (!waitForPidGone(pid)) {
+            killPidHard(pid);
+        }
     }
 };
-export const killStaleListeners = (ports, isOurs) => {
-    for (const port of ports) {
-        let pids = [];
+// Whatever is currently listening on a port, as pid + command line. Empty when
+// the port is free, or when lsof is unavailable.
+const getPortListeners = (port) => {
+    let pids = [];
+    try {
+        pids = execSync(`lsof -t -iTCP:${port} -sTCP:LISTEN`, {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .split('\n')
+            .map((line) => Number(line.trim()))
+            .filter(Boolean);
+    }
+    catch {
+        return []; // lsof exits non-zero when nothing is listening
+    }
+    return pids.flatMap((pid) => {
         try {
-            pids = execSync(`lsof -t -iTCP:${port} -sTCP:LISTEN`, {
-                stdio: ['ignore', 'pipe', 'ignore'],
-            })
-                .toString()
-                .split('\n')
-                .map((line) => Number(line.trim()))
-                .filter(Boolean);
+            return [{ pid, command: execSync(`ps -p ${pid} -o command=`).toString().trim() }];
         }
         catch {
-            continue; // lsof exits non-zero when nothing is listening
+            return []; // already gone
         }
-        for (const pid of pids) {
-            let command = '';
-            try {
-                command = execSync(`ps -p ${pid} -o command=`).toString().trim();
-            }
-            catch {
-                continue; // already gone
-            }
+    });
+};
+/**
+ * Say what is holding these ports, without touching it.
+ *
+ * The other half of --keep-other-dev-servers: sparing a sibling checkout's dev
+ * server means this one cannot bind, and an unexplained EADDRINUSE is a worse
+ * experience than the silent kill it replaces. Naming the pid and the command
+ * turns "it just died" into something you can act on.
+ *
+ * Worded as a prediction, not a fact, because it IS one: this runs before the
+ * bundle step, so by the time anything binds - seconds later - the holder may
+ * well have gone. Stating "port in use" and then starting cleanly reads like
+ * the warning was wrong.
+ */
+export const reportPortHolders = (ports) => {
+    for (const port of ports) {
+        for (const { pid, command } of getPortListeners(port)) {
+            console.warn(`Port ${port} is currently held by pid ${pid}: ${command}`);
+            console.warn(`  Starting anyway. If it still holds port ${port} once this server binds, startup will fail with EADDRINUSE.`);
+        }
+    }
+};
+export const killStaleListeners = (ports, isOurs) => {
+    for (const port of ports) {
+        for (const { pid, command } of getPortListeners(port)) {
             if (isOurs(command)) {
                 console.log(`Killing stale dev server on port ${port} (pid ${pid})`);
                 process.kill(pid);
-                waitForPidGone(pid);
+                if (!waitForPidGone(pid)) {
+                    killPidHard(pid);
+                }
             }
             else {
                 console.warn(`Port ${port} is in use by an unrelated process (pid ${pid}: ${command}) — not killing it.`);