@gachlab/devup 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to `@gachlab/devup` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.0] — 2026-05-22
+
+Pre-boot port-conflict resolution. When devup detects another process already holding a port it needs, it now offers to take it over instead of silently marking the service as crashed.
+
+### Added
+- **Pre-boot port conflict scan.** Before mounting the TUI or starting the daemon, devup checks every API-typed service's port. Any conflict is shown to the user with the PID and process name (via `lsof`):
+  ```
+  ⚠ Port conflicts detected on the following services:
+
+    :3002   authorization-api  pid=12345  process=node
+    :3013   files-api          pid=99999  process=docker-proxy
+
+  Kill these processes and continue? [y/N]:
+  ```
+  Three flavours of resolution:
+  - **Interactive TTY** → y/N prompt (default).
+  - **`--kill-port-conflicts` flag** → auto-kill, no prompt. Required for `devup up -d`, `--once`, and any non-TTY context (CI).
+  - **Non-interactive without the flag** → fail fast with the conflict list as instructions.
+- **`devup up -d` runs the scan in the parent** before forking the daemon child, so the user gets the prompt (or the error) in their terminal, not buried in `~/.devup/<project>.boot-error`.
+
+### Internals
+- New `src/process/port-conflicts.ts` houses the scan, the lsof-based holder lookup (`findPortHolder`), the resolution flow (`resolvePortConflicts`), and the SIGTERM-then-SIGKILL helper (`killHolder`). Linux + macOS only — Windows holder detection (netstat / Get-NetTCPConnection) is deferred until daemon mode itself supports Windows.
+- Test suite: 372 → 384 (+12). New: 4 scan tests, 2 killHolder tests, 4 resolution-flow tests, 1 CLI flag test, 1 lsof-output parser test.
+
+### Notes
+- Webs are intentionally skipped from the scan — their dev servers (Vite, Angular CLI, etc.) often handle port reuse themselves, and the user's editor / preview tabs hold web ports far more often than stale dev processes do.
+
 ## [0.8.1] — 2026-05-22
 
 Patch focused on two real-world footguns surfaced as soon as 0.8.0 hit users.

package/README.md

@@ -41,6 +41,7 @@ Built with TypeScript 6, Ink (React for terminals), and zero test dependencies (
 - **Subcommands** — `devup logs <svc> [--follow]`, `devup install`, `devup status`, `devup help` work without launching the TUI.
 - **CI-ready** — `--dry-run` prints the resolved boot plan; `--once` boots, waits for readiness, exits `0/1` without a TUI.
 - **Daemon mode** — `devup up -d` boots the stack detached (like `docker compose up -d`) so you can keep using the same terminal. `devup down` stops it. Linux + macOS.
+- **Port-conflict takeover** — when something else is already on a configured port, devup shows you the holder (PID + process name) and offers to kill it. `--kill-port-conflicts` for non-interactive runs.
 - **`devup ctl`** — CLI client for the control plane: `ping`, `status [--follow]`, `logs <svc> [--follow]`, `restart`, `stop`.
 - **Reverse-proxy config** — generate Traefik, Nginx, or Caddy config from running services; health-aware.
 - **Unix-socket control plane** — local JSON-RPC at `~/.devup/sock-<project>.sock` (chmod 0600); `status`, `restart`, `stop`, `logs.tail`, `logs.follow`, `status.follow`, `ping`.

package/dist/config/cli.d.ts

@@ -18,8 +18,9 @@ export interface CliArgs {
     logFile: boolean;
     logDir?: string;
     watchConfig: boolean;
+    killPortConflicts: boolean;
 }
-export declare const USAGE = "devup \u2014 terminal UI dev stack runner\n\nUsage: devup [options]\n\nService selection:\n  --only apis | webs       Start only APIs or only webs\n  --services a,b,c         Start only the named services\n  --profile <name>         Start the services in a named profile (see ROADMAP)\n  --skip a,b,c             Start everything except these\n  --config <path>          Use a custom config file\n\nLazy mode:\n  --lazy                   Enable lazy mode (default)\n  --no-lazy                Start every service immediately\n  --timeout <minutes>      Idle timeout for lazy services. Default: 10\n\nReverse proxy:\n  --proxy                  Enable proxy config generation\n  --proxy-host <host>      Override the target host (Docker/local)\n  --proxy-conf <path>      Override the generated config file path\n  --proxy-tls              Enable TLS in the generated config (default)\n  --no-proxy-tls           Disable TLS\n  --proxy-entrypoint <n>   Override entrypoint name (Traefik only)\n\nCI / scripting:\n  --dry-run                Print the resolved boot plan and exit\n  --once                   Boot, wait for readiness, exit 0/1 (no TUI)\n  --once-timeout <s>       Max seconds to wait in --once mode. Default: 90\n\nLog files:\n  --no-log-file            Disable persistent log files\n  --log-dir <path>         Override log root (default: ~/.devup/logs)\n\nHot reload:\n  --watch-config           Watch devup.config.* and apply add/remove/restart\n                           service changes without exiting the TUI\n\nOther:\n  -h, --help               Show this help and exit\n  -v, --version            Show version and exit\n\nSee https://github.com/gachlab/devup for the full documentation.";
+export declare const USAGE = "devup \u2014 terminal UI dev stack runner\n\nUsage: devup [options]\n\nService selection:\n  --only apis | webs       Start only APIs or only webs\n  --services a,b,c         Start only the named services\n  --profile <name>         Start the services in a named profile (see ROADMAP)\n  --skip a,b,c             Start everything except these\n  --config <path>          Use a custom config file\n\nLazy mode:\n  --lazy                   Enable lazy mode (default)\n  --no-lazy                Start every service immediately\n  --timeout <minutes>      Idle timeout for lazy services. Default: 10\n\nReverse proxy:\n  --proxy                  Enable proxy config generation\n  --proxy-host <host>      Override the target host (Docker/local)\n  --proxy-conf <path>      Override the generated config file path\n  --proxy-tls              Enable TLS in the generated config (default)\n  --no-proxy-tls           Disable TLS\n  --proxy-entrypoint <n>   Override entrypoint name (Traefik only)\n\nCI / scripting:\n  --dry-run                Print the resolved boot plan and exit\n  --once                   Boot, wait for readiness, exit 0/1 (no TUI)\n  --once-timeout <s>       Max seconds to wait in --once mode. Default: 90\n\nLog files:\n  --no-log-file            Disable persistent log files\n  --log-dir <path>         Override log root (default: ~/.devup/logs)\n\nHot reload:\n  --watch-config           Watch devup.config.* and apply add/remove/restart\n                           service changes without exiting the TUI\n\nPort conflicts:\n  --kill-port-conflicts    Kill any processes already holding a configured\n                           port before boot. Interactive prompt without it;\n                           required for non-TTY (daemon, --once, CI)\n\nOther:\n  -h, --help               Show this help and exit\n  -v, --version            Show version and exit\n\nSee https://github.com/gachlab/devup for the full documentation.";
 export declare function parseCliArgs(argv: string[]): CliArgs;
 export declare function filterServices(services: ServiceConfig[], args: CliArgs, config?: Pick<DevStackConfig, 'profiles'>): ServiceConfig[];
 //# sourceMappingURL=cli.d.ts.map

package/dist/config/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/config/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,OAAO;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAKD,eAAO,MAAM,KAAK,+qDAyC+C,CAAC;AAElE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CA4CpD;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,EAAE,EACzB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,GACxC,aAAa,EAAE,CA6BjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/config/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,OAAO;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAKD,eAAO,MAAM,KAAK,i6DA8C+C,CAAC;AAElE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CA8CpD;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,EAAE,EACzB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,GACxC,aAAa,EAAE,CA6BjB"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChG,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChG,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -296,6 +296,11 @@ Hot reload:
   --watch-config           Watch devup.config.* and apply add/remove/restart
                            service changes without exiting the TUI
 
+Port conflicts:
+  --kill-port-conflicts    Kill any processes already holding a configured
+                           port before boot. Interactive prompt without it;
+                           required for non-TTY (daemon, --once, CI)
+
 Other:
   -h, --help               Show this help and exit
   -v, --version            Show version and exit
@@ -313,7 +318,8 @@ function parseCliArgs(argv) {
     once: false,
     onceTimeout: DEFAULT_ONCE_TIMEOUT,
     logFile: true,
-    watchConfig: false
+    watchConfig: false,
+    killPortConflicts: false
   };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -390,6 +396,9 @@ function parseCliArgs(argv) {
       case "--watch-config":
         args.watchConfig = true;
         break;
+      case "--kill-port-conflicts":
+        args.killPortConflicts = true;
+        break;
     }
   }
   return args;
@@ -2525,6 +2534,122 @@ function runHelp(argv, opts = {}) {
   return 0;
 }
 
+// src/process/port-conflicts.ts
+import { exec } from "child_process";
+import { promisify } from "util";
+import { setTimeout as sleep2 } from "timers/promises";
+var execAsync = promisify(exec);
+var isUnix = process.platform === "linux" || process.platform === "darwin";
+async function findPortHolder(port) {
+  if (!isUnix) return null;
+  try {
+    const { stdout } = await execAsync(`lsof -nP -iTCP:${port} -sTCP:LISTEN -F pcn`);
+    return parseLsof(stdout);
+  } catch {
+    return null;
+  }
+}
+function parseLsof(stdout) {
+  let pid = null;
+  let cmd = "";
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const tag = line[0];
+    const value = line.slice(1);
+    if (tag === "p") {
+      if (pid != null) return { pid, command: cmd || "unknown" };
+      pid = Number(value);
+    } else if (tag === "c") {
+      cmd = value;
+    }
+  }
+  if (pid != null) return { pid, command: cmd || "unknown" };
+  return null;
+}
+async function scanPortConflicts(services) {
+  const apis = services.filter((s) => s.type === "api");
+  const conflicts = [];
+  for (const svc of apis) {
+    const bindable = await isPortBindable(svc.port);
+    if (bindable) continue;
+    const holder = await findPortHolder(svc.port);
+    conflicts.push({ service: svc.name, port: svc.port, holder });
+  }
+  return conflicts;
+}
+async function killHolder(pid, graceMs = 3e3) {
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    return false;
+  }
+  const deadline = Date.now() + graceMs;
+  while (Date.now() < deadline) {
+    if (!pidAlive2(pid)) return true;
+    await sleep2(100);
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch {
+  }
+  await sleep2(100);
+  return !pidAlive2(pid);
+}
+function pidAlive2(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolvePortConflicts(conflicts, opts) {
+  if (!conflicts.length) return true;
+  const { autoKill, out, prompt, isInteractive = process.stdin.isTTY ?? false } = opts;
+  out("\u26A0 Port conflicts detected on the following services:");
+  out("");
+  const maxName = Math.max(...conflicts.map((c) => c.service.length), 8);
+  for (const c of conflicts) {
+    const holder = c.holder ? `pid=${c.holder.pid}  process=${c.holder.command}` : `(unable to identify holder${isUnix ? "" : " \u2014 Windows not supported"})`;
+    out(`  :${String(c.port).padEnd(6)} ${c.service.padEnd(maxName)}  ${holder}`);
+  }
+  out("");
+  if (autoKill) {
+    return await killAll(conflicts, out);
+  }
+  if (!isInteractive || !prompt) {
+    out("Re-run with --kill-port-conflicts to take them over, or stop them yourself.");
+    return false;
+  }
+  const confirmed = await prompt();
+  if (!confirmed) {
+    out("Aborted \u2014 no processes killed.");
+    return false;
+  }
+  return await killAll(conflicts, out);
+}
+async function killAll(conflicts, out) {
+  let allOk = true;
+  for (const c of conflicts) {
+    if (!c.holder) {
+      out(`\u2717 :${c.port} ${c.service}: holder unknown, cannot kill \u2014 skipped`);
+      allOk = false;
+      continue;
+    }
+    const ok = await killHolder(c.holder.pid);
+    if (ok) {
+      out(`\u2713 :${c.port} ${c.service}: killed pid=${c.holder.pid}`);
+    } else {
+      out(`\u2717 :${c.port} ${c.service}: pid=${c.holder.pid} survived SIGKILL`);
+      allOk = false;
+    }
+  }
+  return allOk;
+}
+
+// src/index.ts
+import { createInterface as createInterface6 } from "readline";
+
 // src/platform/detect.ts
 async function detectPlatform() {
   switch (process.platform) {
@@ -3981,6 +4106,20 @@ ${formatValidationWarnings(warnings)}`);
   if (cliArgs.logFile) {
     logSink = new LogSink({ projectName: config.name, rootDir: cliArgs.logDir });
   }
+  if (process.env.DEVUP_DAEMON_CHILD !== "1") {
+    const conflicts = await scanPortConflicts(services);
+    if (conflicts.length) {
+      const resolved = await resolvePortConflicts(conflicts, {
+        autoKill: cliArgs.killPortConflicts,
+        out: (msg) => process.stderr.write(msg + "\n"),
+        prompt: () => askYesNo("Kill these processes and continue? [y/N]: ")
+      });
+      if (!resolved) {
+        await logSink?.close();
+        process.exit(1);
+      }
+    }
+  }
   if (cliArgs.once) {
     const code = await runOnce({
       config,
@@ -4041,6 +4180,19 @@ ${formatValidationWarnings(warnings)}`);
   );
   await waitUntilExit();
 }
+function askYesNo(question) {
+  return new Promise((resolve4) => {
+    if (!process.stdin.isTTY) {
+      resolve4(false);
+      return;
+    }
+    const rl = createInterface6({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve4(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
 main().catch((e) => {
   console.error(e);
   process.exit(1);