@gachlab/devup 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+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.3.0] — 2026-05-21
+
+### Added
+- **Profiles / scenarios** (#4). New `profiles: Record<string, string[]>` field on `DevStackConfig` plus a `--profile <name>` CLI flag. Lets you save common service-subset combinations under a name (e.g. `'check-in'`, `'pickup'`) and boot them with one short command instead of typing `--services` every time. Composable with `--skip`. Unknown profile names produce a friendly error listing what's available.
+- **`readyPattern` for instant up detection** (#13). New per-service field accepting a plain string or vim-style `/pattern/flags` regex. On the first matching stdout/stderr line devup flips the service to `up` immediately, short-circuiting the next 3-second health-check poll. Speeds up phase transitions when frameworks print recognisable boot lines (Vite's `ready in 423 ms`, Angular's `Compiled successfully`, Fastify's `server listening`). The periodic health-check still runs as a fallback.
+- **`preBuild` and `watchBuild` hooks** (#12). The fields existed in the type but were ignored. Now implemented properly:
+  - `preBuild` runs synchronously before the spawn through the platform shell (`sh -c` / `cmd /c`); non-zero exit marks the service `crashed` and skips the spawn.
+  - `watchBuild` is spawned as a sibling process and killed (kill-tree) on stop/restart/cleanup.
+  - Output is tagged `[build]` / `[watch]` in the logs panel and flows through the same line buffer + log sink pipeline.
+  - Replaces the awkward `sh -c 'npm run build && (npx tsup --watch &) && node ...'` workaround in projects with TypeScript services.
+- **`external` / pre hooks for external dependencies** (#14). New top-level `external: ExternalService[]` field for databases, queues, etc. Externals run **before phase 0** through the platform shell with optional `healthCheck` gating and `stopCmd` on shutdown. devup aborts the boot (and runs every `stopCmd`) if any external fails its healthCheck within `startTimeout` (default 60 s). Closes the "do `docker compose up -d` then run devup" loop. Logs are tagged `ext:<name>` and persisted to `~/.devup/logs/<proj>/ext_<name>.log`.
+
+### Changed
+- `filterServices()` now accepts an optional `config` arg to resolve `--profile`. Calls from `index.ts` updated.
+- `--dry-run` header now shows the active profile and a new `Externals (N):` section with each entry's healthCheck tag.
+- `ProcessState` gains an optional `watchProc` field tracking the `watchBuild` side-car.
+- `useProcessManager` exposes `pushLog()` so non-service log lines (externals, future side-cars) flow through the same pause buffer and log sink as regular service lines.
+
+### Fixed
+- Validator catches profile entries that reference unknown services or are empty arrays.
+- Validator catches invalid `readyPattern` regex and empty strings.
+- Validator catches empty `preBuild` / `watchBuild` strings.
+- Validator catches external dependencies with missing `cmd`, duplicate names, missing `port` when a healthCheck is set, or `http` healthCheck paths without a leading `/`.
+
+### Internals
+- New module `src/process/external.ts` (`startExternals` / `stopExternals`).
+- Test suite grown from 200 to ~237 — new suites: `ready-pattern`, `external` (Unix-only, follows the existing skip-on-Windows convention used by integration tests), validator coverage for every new field.
+- Shell-dependent `preBuild`/`watchBuild` integration tests skipped on Windows. The feature itself works on both platforms because the runtime code path already routes through `sh -c` / `cmd /c`; only writing a single test command that exercises spawn behaviour across both shells without per-platform branching is awkward.
+
+## [0.2.0] — 2026-05-21
+
+### Added
+- **HTTP health-checks per service.** New `healthCheck` config field on `ServiceConfig`. Supports `type: 'tcp'` (default) and `type: 'http'` with configurable `path`, `expect` (status code or list), `host`, and `timeoutMs`. Used by both the periodic in-TUI health poll and `--once`.
+- **Persistent log files.** Every line streamed to `~/.devup/logs/<project>/<service>.log`, prefixed with an ISO-8601 timestamp. On each launch the previous file is rotated to `<service>.log.prev`. New flags `--no-log-file` (disable) and `--log-dir <path>` (override root).
+- **`--dry-run`.** Prints the resolved boot plan — phases, commands with their final args/env, lazy proxies with their `realPort`, and the proxy YAML/conf that would be generated — then exits `0` without starting anything.
+- **`--once` (+ `--once-timeout N`).** Boots every service phase-by-phase without rendering the TUI, waits for each API to become healthy, and exits `0` (all up) or `1` (timeout). Default timeout: 90s. Built for CI smoke tests.
+- **Nginx proxy provider.** Generates one `server { }` block per healthy service, with TLS / non-TLS variants and WebSocket-upgrade headers wired by default.
+- **Caddy proxy provider.** Generates a Caddyfile with `reverse_proxy` directives; TLS provisioning is delegated to Caddy by default.
+- **Scroll indicators.** `[SCROLL]` badge appears in the Logs and Stats panel headers when the view is off the natural anchor (bottom for logs, top for stats).
+- **`fmtUptime` now formats days.** Services running longer than a day display as `2d3h` instead of `120h0m`.
+
+### Changed
+- **TUI scroll completely rewritten.** Logs now use a `bottomOffset` model (0 = follow latest, N = N lines back); Stats use a coherent `topOffset` model. Arrow keys, `[`/`]`, `Ctrl+B`/`Ctrl+F`, and `Ctrl+A`/`Ctrl+E` always move in the expected visual direction regardless of which panel is focused.
+- **Auto-pause when scrolling Logs.** New lines are buffered (capped at 5,000) while you're scrolled up, then replayed when you return to the bottom (`Ctrl+E`). The `p` key still works manually.
+- **`p` (pause logs) actually pauses.** Before, it only changed the header label while logs kept streaming.
+- **`c` (clear logs) actually clears.** Was a no-op; now properly cabled to `pm.clearLogs()`.
+- **Manual `r` (restart) resets the auto-restart counter to 0.** Lets the user grant a fresh budget after fixing a flapping service.
+- **`install()` accepts an explicit `colorIdx`.** Install logs no longer all appear in cyan; they match the service's tag color.
+- **`cleanup()` is now async** and the TUI awaits it before `process.exit(0)`. Ensures the SIGKILL fallback (3 s after SIGTERM) actually has time to run.
+- **`useProxySync` no longer recreates its interval on every state change** and skips writes when the generated content hasn't changed.
+- **Reverse proxy provider docs.** README now covers Traefik, Nginx, and Caddy each with a code snippet.
+
+### Fixed
+- **Lazy proxy idle timer respects active connections.** Long-lived connections (WebSockets, SSE, HTTP/2 keep-alive) no longer get the underlying service killed mid-flight. The timer only fires when there are no active connections and no recent activity.
+- **Lazy proxy fails cleanly when the on-demand start fails.** Pending connections are destroyed with a logged error instead of being piped to a dead target.
+- **Log lines are no longer split mid-message.** Per-stream line buffer (`lineBuffer`) reassembles partial chunks from stdout/stderr.
+- **`stderr` error count is no longer inflated.** Was counting blank lines from chunk splits; now counts one error per real line.
+- **Terminal resize is now respected.** `stdout.on('resize')` re-renders the layout. Before, the height was captured on first paint and never updated.
+- **Validator detects lazy-port collisions** between `service.port` and `otherService.port + 10000` and reports them at config-load time.
+- **Validator validates `healthCheck` shape.** Rejects unknown `type` values and paths without a leading `/`.
+- **Key bindings: `Ctrl+F` (page down) no longer triggers the filter modal.** Reordered handler so ctrl-modified keys are checked before single-letter shortcuts.
+
+### Removed
+- Dead `blessed`-style helpers from `utils.ts`: `highlightSearch`, `findSearchMatch`, `formatLogLine`, `shouldLogLine`, `buildLogsLabel`. The TUI is fully Ink-based and never used them.
+- `installBatch` from `installer.ts`. Unused, with a subtle race in its `Promise.race` cleanup.
+
+### Internals
+- Test suite grown from 122 to 200 (`+78`). New: `health.test.ts` HTTP cases, `log-sink.test.ts`, `dry-run.test.ts`, `once.test.ts` (integration), `nginx.test.ts`, `caddy.test.ts`.
+- New `src/orchestrator/` directory (`dry-run.ts`, `once.ts`) separates non-TUI flows from the React layer.
+
+## [0.1.1] — 2026-05-07
+
+### Added
+- TUI panel navigation: `Tab` to switch focus between Logs and Stats, with focused-border highlighting.
+
+### Fixed
+- Cross-platform glob quoting in `test:*` npm scripts (Windows).
+- Integration tests: more socket-error codes accepted (Windows), `os.tmpdir()` in validator test (Windows), longer timeouts on macOS CI, lifecycle test enabled on macOS while skipped on Windows.
+
+### CI / packaging
+- GitHub Actions workflow runs on Linux, macOS, and Windows.
+- Split unit (every branch, 3 OSes) and integration (main only, 3 OSes) jobs.
+- Upgraded actions to v5 / Node 24 runner.
+- Publish workflow added — triggered by GitHub Release, runs tests on 3 OSes, then publishes to npm using trusted publishing (OIDC, no `NPM_TOKEN`).
+
+## [0.1.0] — 2026-05-01
+
+Initial release.
+
+### Added
+- Phased startup of services with TCP port-readiness detection.
+- Lazy mode: on-demand start via a TCP proxy on the public port; service runs on `port + 10000`; idle timeout to stop the underlying process.
+- Cross-platform process management (Linux/macOS via `ps` + `kill -pid`; Windows via `wmic` + `taskkill /T /F`) and browser-opening (`xdg-open`, `open`, `cmd /c start`).
+- TUI dashboard built with Ink: live logs (filter, search, pause, timestamps), stats panel (CPU, memory, health, errors, restarts) with sort modes.
+- Reverse-proxy config generation: Traefik file provider (YAML), health-aware (only `health === 'up'` services routed).
+- Automatic dependency installation with hash-based stamps to skip redundant `npm install`s.
+- Auto-restart with exponential backoff (2s → 4s → 8s), capped at 3 attempts.
+- Port-in-use detection before starting a service.
+- Config file resolution order: `devup.config.ts` → `.js` → `.json`, with `--config <path>` override. TypeScript loaded via the `tsx` import hook.
+- CLI flags: `--only`, `--services`, `--skip`, `--lazy`/`--no-lazy`, `--timeout`, `--proxy`, `--proxy-host`, `--proxy-conf`, `--proxy-tls`/`--no-proxy-tls`, `--proxy-entrypoint`, `--config`.
+
+[0.3.0]: https://github.com/gachlab/devup/releases/tag/0.3.0
+[0.2.0]: https://github.com/gachlab/devup/releases/tag/0.2.0
+[0.1.1]: https://github.com/gachlab/devup/releases/tag/0.1.1
+[0.1.0]: https://github.com/gachlab/devup/releases/tag/0.1.0

package/README.md

@@ -9,14 +9,17 @@ Built with TypeScript 6, Ink (React for terminals), and zero test dependencies (
 ## Features
 
 - **Phased startup** — boot services in dependency order with automatic port readiness detection
-- **Lazy mode** — only start services when they receive traffic. Idle services shut down after a configurable timeout
-- **TUI dashboard** — live logs and process stats (CPU, memory, health, errors, restarts) in a split-panel terminal UI
+- **Lazy mode** — only start services when they receive traffic. Idle services shut down after a configurable timeout (respects active connections, no killing mid-WebSocket)
+- **TUI dashboard** — live logs and process stats (CPU, memory, health, errors, restarts) in a split-panel terminal UI with scrolling, search, filter, and auto-pause when you scroll up
 - **Cross-platform** — Linux, macOS, and Windows. Platform-specific process management, stats collection, and browser opening
-- **Reverse proxy config** — generate Traefik (or other) dynamic config from running services. Health-aware: only routes to healthy services
+- **HTTP or TCP health checks** — per-service `healthCheck` config: TCP probe (default) or HTTP GET with configurable path and status codes
+- **Reverse proxy config** — generate Traefik, Nginx, or Caddy config from running services. Health-aware: only routes to healthy services
+- **Persistent logs** — every line streamed to `~/.devup/logs/<project>/<svc>.log` with rotation on each launch
+- **CI-ready** — `--dry-run` prints the boot plan; `--once` boots, waits for readiness, exits `0/1` without a TUI
 - **Project-agnostic** — works with any Node.js monorepo. Your project defines a `devup.config.ts`, devup does the rest
 - **npm install management** — automatic dependency installation with hash-based stamps to skip redundant installs
-- **Auto-restart with backoff** — crashed services restart automatically with exponential backoff (2s → 4s → 8s), max 3 attempts
-- **Port conflict detection** — checks if a port is already in use before starting a service
+- **Auto-restart with backoff** — crashed services restart automatically with exponential backoff (2s → 4s → 8s), max 3 attempts; manual restart resets the counter
+- **Port conflict detection** — checks if a port is already in use before starting a service; also validates lazy `port + 10000` collisions at config-load time
 
 ## Quick start
 
@@ -82,6 +85,25 @@ npx devup
 | `services` | `ServiceConfig[]` | ✅ | List of services to manage |
 | `lazy` | `LazyConfig` | | Lazy mode configuration |
 | `proxy` | `ProxyConfig` | | Reverse proxy config generation |
+| `profiles` | `Record<string, string[]>` | | Named lists of services to boot. Select with `--profile <name>` |
+| `external` | `ExternalService[]` | | Dependencies started **before** phase 0 (databases, queues, etc.) |
+
+#### Profiles
+
+A profile is a named subset of `services`. Instead of memorising service names for `--services`, you give your common workflows a name:
+
+```typescript
+export default defineConfig({
+  // ...
+  profiles: {
+    'check-in':  ['configurations-api', 'authorization-api', 'app-api', 'check-in-api', 'app-web'],
+    'pickup':    ['configurations-api', 'pickup-api', 'pickup-drivers-web'],
+    'frontends': ['app-web', 'admin-web', 'staff-web'],
+  },
+});
+```
+
+Then `devup --profile check-in` boots that subset. Composable with `--skip`. The validator catches typos at config-load time. Unknown profile names produce a friendly error listing what's available.
 
 ### `ServiceConfig`
 
@@ -95,10 +117,105 @@ npx devup
 | `port` | `number` | ✅ | Port the service listens on. Must be unique |
 | `phase` | `number` | ✅ | Startup phase (0 = first). Services in the same phase start together; devup waits for all APIs in a phase to be ready before starting the next phase |
 | `maxMem` | `number` | | Max memory in MB. Injects `--max-old-space-size` for `node` commands, or `NODE_OPTIONS` for `npx` |
-| `preBuild` | `string` | | Command to run before starting (e.g., `npm run build`) |
-| `watchBuild` | `string` | | Watch command to run alongside the service (e.g., `npx tsup --watch`) |
+| `preBuild` | `string` | | Shell command run **before** the service starts. If it exits non-zero the service is marked `crashed` and skipped. Output is tagged `[build]` in the logs panel |
+| `watchBuild` | `string` | | Shell command spawned **alongside** the service (e.g. `npx tsup --watch`). Killed automatically when the service stops/restarts. Output is tagged `[watch]` in the logs panel |
 | `nodeArgs` | `string[]` | | Extra Node.js arguments |
 | `extraEnv` | `Record<string, string>` | | Extra environment variables for this service |
+| `healthCheck` | `HealthCheckConfig` | | Override the readiness check for this service. Default: TCP probe on `port` |
+| `readyPattern` | `string` | | Regex matched against stdout/stderr lines. On match, service is marked `up` immediately, short-circuiting the next health-check poll. Plain string or vim-style `/pattern/flags`. Case-insensitive by default |
+
+### `HealthCheckConfig`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `type` | `'tcp' \| 'http'` | ✅ | `tcp` (default) just opens a socket; `http` issues an HTTP GET and inspects the status code |
+| `path` | `string` | | HTTP-only request path. Default: `/`. Must start with `/` |
+| `expect` | `number \| number[]` | | HTTP-only acceptable status code(s). Default: any 2xx (200-299) |
+| `host` | `string` | | Override target host for the HTTP check. Default: `127.0.0.1` |
+| `timeoutMs` | `number` | | Per-check socket/request timeout in ms. Default: `2000` |
+
+```typescript
+// Wait for /healthz to return 200 before considering the service up
+{ name: 'api', /* ... */, healthCheck: { type: 'http', path: '/healthz' } }
+
+// Accept 200 or 204
+{ name: 'api', /* ... */, healthCheck: { type: 'http', path: '/health', expect: [200, 204] } }
+```
+
+#### readyPattern
+
+A regex matched against each line of the service's stdout/stderr. The first matching line flips the service to `up` immediately, without waiting for the next 3-second health-check poll. The periodic health-check still runs as a fallback. Useful for tools that print recognisable boot lines:
+
+```typescript
+// Vite: "ready in 423 ms"
+{ name: 'web', cmd: 'npx', args: ['vite'], readyPattern: 'ready in' }
+
+// Angular: "Compiled successfully"
+{ name: 'app', cmd: 'npx', args: ['ng', 'serve'], readyPattern: '/compiled successfully/i' }
+
+// Fastify: "Server listening at"
+{ name: 'api', cmd: 'node', args: ['index.js'], readyPattern: 'server listening' }
+```
+
+Both plain strings and vim-style `/pattern/flags` are accepted. Strings are case-insensitive by default.
+
+#### Build hooks: `preBuild` and `watchBuild`
+
+For TypeScript services or anything that needs a compile step, two hooks remove the usual `sh -c 'npm run build && (npx tsup --watch &) && node ...'` workaround:
+
+```typescript
+{
+  name: 'orders-api',
+  cwd: 'orders/api',
+  cmd: 'node', args: ['dist/index.js'],
+  type: 'api', port: 3031, phase: 1,
+  preBuild: 'npm run build',         // runs once, must succeed before the service starts
+  watchBuild: 'npx tsup --watch',    // runs in parallel; killed when the service stops
+}
+```
+
+- **`preBuild`** runs synchronously before the spawn. Non-zero exit marks the service as `crashed` (the spawn is skipped). Output is tagged `[build]` in the logs panel.
+- **`watchBuild`** runs as a sibling process. devup kills it when the service stops, restarts, or the TUI exits. Output is tagged `[watch]`.
+
+Both are passed through the platform shell (`sh -c` on Unix, `cmd /c` on Windows), so pipes and `&&` work.
+
+### `ExternalService`
+
+External dependencies (databases, message queues, etc.) launched **before** phase 0. devup waits for each `healthCheck` (when set) to pass before starting any service. Typical use: `docker compose up -d`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | ✅ | Friendly name shown in logs (logs use the prefix `ext:<name>`) |
+| `cmd` | `string` | ✅ | Shell command (passed through `sh -c` / `cmd /c`). Pipes and `&&` work |
+| `cwd` | `string` | | Working directory relative to the project root |
+| `extraEnv` | `Record<string, string>` | | Extra env vars merged on top of the project env |
+| `healthCheck` | `HealthCheckConfig` | | Readiness probe. devup waits for `up` before starting phase 0 |
+| `port` | `number` | when `healthCheck` is set | Port to probe |
+| `startTimeout` | `number` | | Max seconds to wait for healthCheck. Default: `60` |
+| `stopCmd` | `string` | | Shell command run on shutdown (e.g. `docker compose down`) |
+
+```typescript
+export default defineConfig({
+  // ...
+  external: [
+    {
+      name: 'mongo',
+      cmd: 'docker compose -f docker-compose.dev.yml up -d mongo',
+      port: 27017,
+      healthCheck: { type: 'tcp' },
+      stopCmd: 'docker compose -f docker-compose.dev.yml stop mongo',
+    },
+    {
+      name: 'redis',
+      cmd: 'docker compose -f docker-compose.dev.yml up -d redis',
+      port: 6379,
+      healthCheck: { type: 'tcp' },
+    },
+  ],
+});
+```
+
+If any external fails its healthCheck within `startTimeout` seconds, devup aborts the boot, runs each external's `stopCmd` (best-effort), and exits.
 
 ### `LazyConfig`
 
@@ -113,7 +230,7 @@ When lazy mode is active (default), services not in `alwaysOn` start a TCP proxy
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `provider` | `string` | ✅ | Proxy provider name. Currently: `'traefik'` |
+| `provider` | `string` | ✅ | Proxy provider name. One of: `'traefik'`, `'nginx'`, `'caddy'` |
 | `routes` | `Record<string, string>` | ✅ | Map of service name → subdomain. Empty string = root domain |
 | `confPath` | `string` | | Path to write the config file. Default: `~/.traefik/traefik_conf.yaml` |
 | `host` | `string` | | Target host for proxy URLs. Default: auto-detected per platform |
@@ -135,6 +252,7 @@ devup [options]
 | `--only apis` | Only start API services |
 | `--only webs` | Only start web services |
 | `--services api,web,auth` | Start only the named services |
+| `--profile <name>` | Start the services in the named profile (see `profiles` in the config) |
 | `--skip tasks-api,pickup-api` | Start everything except these |
 | `--config path/to/config.ts` | Use a custom config file |
 
@@ -155,7 +273,24 @@ devup [options]
 | `--proxy-conf /path/to/file` | Override config file path |
 | `--proxy-tls` | Enable TLS (default) |
 | `--no-proxy-tls` | Disable TLS |
-| `--proxy-entrypoint web` | Override entrypoint name |
+| `--proxy-entrypoint web` | Override entrypoint name (Traefik-only) |
+
+### CI / scripting
+
+| Flag | Description |
+|---|---|
+| `--dry-run` | Print the resolved boot plan (phases, commands, proxy YAML) and exit. Doesn't start any process |
+| `--once` | Boot services, wait until every API is healthy, then exit `0` (or `1` on timeout). Skips the TUI — meant for CI smoke tests |
+| `--once-timeout 60` | Max seconds to wait in `--once` mode. Default: `90` |
+
+### Log files
+
+| Flag | Description |
+|---|---|
+| `--no-log-file` | Disable persistent log files |
+| `--log-dir /path` | Override log root. Default: `~/.devup/logs/<project>/<service>.log` |
+
+devup writes a separate `.log` file per service to disk. Lines are prefixed with an ISO timestamp. On each fresh launch the previous file is rotated to `<service>.log.prev`, so you always have at most two runs of history per service.
 
 ## TUI keybindings
 
@@ -163,10 +298,13 @@ devup [options]
 |---|---|
 | `q` / `Ctrl+C` | Quit and stop all services |
 | `Tab` | Switch focus between Logs and Stats panels |
+| `↑` / `↓` | Scroll the focused panel by 1 line/row |
+| `[` / `]` (or `Ctrl+B` / `Ctrl+F`) | Page up / page down |
+| `Ctrl+A` / `Ctrl+E` | Jump to top / bottom of the focused panel |
 | `f` | Filter logs by service |
 | `a` | Show all logs (clear filter) |
 | `/` | Search in logs |
-| `p` | Pause/resume log output |
+| `p` | Pause/resume log output (auto-engaged when you scroll up) |
 | `t` | Toggle timestamps |
 | `c` | Clear logs |
 | `s` | Cycle sort mode (name → memory → errors) |
@@ -174,6 +312,8 @@ devup [options]
 | `o` | Open a web service in browser |
 | `T` | Toggle reverse proxy config sync |
 
+When you scroll the Logs panel up, devup auto-pauses the log stream so new lines don't push your reading position. New lines are buffered and replay when you return to the bottom (`Ctrl+E` or scroll all the way down).
+
 ## Config file formats
 
 devup looks for config files in this order:
@@ -227,7 +367,7 @@ Services listed in `lazy.alwaysOn` skip the proxy and start normally.
 
 ## Reverse proxy providers
 
-devup generates dynamic config for reverse proxies. Currently supported:
+devup generates dynamic config for reverse proxies. Three providers are built in: **Traefik**, **Nginx**, and **Caddy**. Only services with `health === 'up'` are included — flapping services are silently dropped from the generated config and re-added when they recover.
 
 ### Traefik
 
@@ -245,7 +385,39 @@ services:
 devup --proxy --proxy-host 172.17.0.1
 ```
 
-Adding a new provider (Nginx, Caddy, etc.) requires implementing the `ProxyConfigProvider` interface:
+### Nginx
+
+Generates an Nginx file with one `server { }` block per healthy service. Drop it into `/etc/nginx/conf.d/` (or `include` it from your main config) and reload Nginx — devup rewrites the file in place every 3 seconds.
+
+```typescript
+proxy: {
+  provider: 'nginx',
+  confPath: '/etc/nginx/conf.d/devup.conf',
+  routes: { 'app-web': '', 'api': 'api' },
+}
+```
+
+With `tls: true` (default) each block listens on `:443 ssl` and points to `/etc/nginx/certs/<server_name>.crt` and `.key`. With `tls: false` it listens on `:80`. WebSocket / HTTP-upgrade headers are forwarded by default.
+
+> **Note:** Nginx doesn't watch files automatically — you'll need `nginx -s reload` (or `nginx-reload` sidecar) to pick up devup's updates. For a watch-and-reload workflow, prefer Traefik or Caddy.
+
+### Caddy
+
+Generates a Caddyfile with one `reverse_proxy` directive per healthy service. Caddy auto-reloads its file on change (`caddy run --watch`), so devup's updates take effect without intervention.
+
+```typescript
+proxy: {
+  provider: 'caddy',
+  confPath: '/etc/caddy/devup.Caddyfile',
+  routes: { 'app-web': '', 'api': 'api' },
+}
+```
+
+With `tls: true` (default) Caddy provisions TLS automatically (Let's Encrypt or local CA). With `tls: false` each site is prefixed with `http://`.
+
+### Adding a custom provider
+
+Implement the `ProxyConfigProvider` interface and register it manually before calling `render(<App />)`:
 
 ```typescript
 interface ProxyConfigProvider {
@@ -323,7 +495,7 @@ git clone https://github.com/gachlab/devup.git
 cd devup
 npm install
 npm run build
-npm test              # 112 tests, node:test native
+npm test              # 200 tests, node:test native
 npm run test:coverage # coverage report
 ```
 

package/dist/config/cli.d.ts

@@ -1,9 +1,10 @@
-import type { ServiceConfig } from './types.js';
+import type { DevStackConfig, ServiceConfig } from './types.js';
 export interface CliArgs {
     configPath?: string;
     only?: string;
     skip: string[];
     services?: string[];
+    profile?: string;
     lazy: boolean;
     lazyTimeout: number;
     proxy: boolean;
@@ -11,7 +12,12 @@ export interface CliArgs {
     proxyConf?: string;
     proxyTls: boolean;
     proxyEntrypoint: string;
+    dryRun: boolean;
+    once: boolean;
+    onceTimeout: number;
+    logFile: boolean;
+    logDir?: string;
 }
 export declare function parseCliArgs(argv: string[]): CliArgs;
-export declare function filterServices(services: ServiceConfig[], args: CliArgs): ServiceConfig[];
+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,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,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,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;CACzB;AAID,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAgCpD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,aAAa,EAAE,CAoBxF"}
+{"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;CACjB;AAKD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CA0CpD;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/config/types.d.ts

@@ -11,6 +11,24 @@ export interface ServiceConfig {
     watchBuild?: string;
     nodeArgs?: string[];
     extraEnv?: Record<string, string>;
+    healthCheck?: HealthCheckConfig;
+    /** Case-insensitive regex. When a line of the service's stdout/stderr matches,
+     *  the service is immediately marked as `up` without waiting for the next
+     *  health-check poll. Speeds up phase transitions on cold boots.
+     *  Examples: '/ready in \\d+ ms/' (Vite), '/compiled successfully/' (Angular). */
+    readyPattern?: string;
+}
+export interface HealthCheckConfig {
+    /** 'tcp' (default) checks that the port accepts connections. 'http' makes an HTTP GET. */
+    type: 'tcp' | 'http';
+    /** HTTP-only: request path. Default: '/' */
+    path?: string;
+    /** HTTP-only: acceptable status code(s). Default: 200-299 */
+    expect?: number | number[];
+    /** Override host for the HTTP check. Default: 127.0.0.1 */
+    host?: string;
+    /** Per-check socket timeout in ms. Default: 2000 */
+    timeoutMs?: number;
 }
 export interface LazyConfig {
     alwaysOn: string[];
@@ -24,6 +42,24 @@ export interface ProxyConfig {
     tls?: boolean;
     entrypoint?: string;
 }
+export interface ExternalService {
+    /** Friendly name (used in logs and the stats panel). Must be unique within `external`. */
+    name: string;
+    /** Shell command to start. Will be passed through `sh -c` / `cmd /c`. */
+    cmd: string;
+    /** Optional working directory (relative to the project root). */
+    cwd?: string;
+    /** Extra env vars merged on top of the project env. */
+    extraEnv?: Record<string, string>;
+    /** Optional readiness probe. devup waits for this to return `up` before starting phase 0. */
+    healthCheck?: HealthCheckConfig;
+    /** Port to probe when `healthCheck` is set. Required for tcp checks. */
+    port?: number;
+    /** Max seconds to wait for healthCheck to pass before giving up. Default: 60. */
+    startTimeout?: number;
+    /** Optional shell command run on shutdown (e.g. `docker compose down`). */
+    stopCmd?: string;
+}
 export interface DevStackConfig {
     name: string;
     icon?: string;
@@ -32,6 +68,10 @@ export interface DevStackConfig {
     services: ServiceConfig[];
     lazy?: LazyConfig;
     proxy?: ProxyConfig;
+    /** Named lists of service names — selectable with --profile <name>. */
+    profiles?: Record<string, string[]>;
+    /** Optional external dependencies (DBs, queues) started before phase 0. */
+    external?: ExternalService[];
 }
 export declare function defineConfig(config: DevStackConfig): DevStackConfig;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAEnE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC;;;sFAGkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,6FAA6F;IAC7F,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAEnE"}

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

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/config/validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAuErF;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAExE"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/config/validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAwKrF;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAExE"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,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":"AAkBA,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"}