@gachlab/devup 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@ 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.4.0] — 2026-05-21
+
+Polish + standalone CLI release. Eight focused improvements landed as a single PR with one commit per issue.
+
+### Added
+- **`devup --version` / `-v` and `devup --help` / `-h`** (#6). Both short-circuit before any config loading and exit `0`. Version is read from `package.json` at runtime so dev (via tsx) and the published tarball both report the right number.
+- **Standalone subcommands** (#17): `devup logs <service> [--follow|-f]`, `devup install`, `devup status`, `devup help [<subcommand>]`. Reuse the persistent log files and the health-check primitives without launching the TUI. `logs --follow` tails new lines via `watchFile` and exits cleanly on SIGINT. `install` runs `npm install` across every service.cwd in parallel (max 4 at a time), skipping ones whose `.install-stamp` matches. `status` probes each service's healthCheck and prints a table.
+- **Pre-flight check for `--watch-path` arguments** (#5). Before spawning a service, devup scans its args for `--watch` / `--watch-path` (both `--flag value` and `--flag=value` forms) and verifies every referenced path exists relative to the service's `cwd`. Missing paths mark the service `crashed` with one grouped error line instead of letting Node 22 die with a cryptic message after a rebase that renamed directories.
+- **Browser open respects proxy + TLS** (#10). Pressing `o` in the TUI now opens `https://<sub>.<domain>` when `--proxy` is active and the service has a route. Falls back to `http://localhost:<port>` otherwise. Honors `proxy.tls: false` by using `http://` on the subdomain.
+- **Crash-loop badge** (#11). Services that exhausted their auto-restart budget (`status === 'crashed' && restarts >= MAX_RESTARTS`) now render with `✖` (red, bold), status label `looping`, and a `⚠ N need attention` counter in the stats panel header. Easy to spot in a long service list.
+- **Fuzzy filter in `ServiceList` modal** (#18). All three picker modals (`f`, `r`, `o`) now accept typed characters to filter the list in real time. Backspace removes a character. First Esc clears the filter, second Esc closes the modal. Sub-second selection on stacks with 30+ services.
+- **Contextual tips** (#22). At teachable moments the TUI shows a dim one-liner in the header bar (e.g. "tip: press / to search in logs" once logs exceed 1000 lines, or "tip: press r to restart" when a service crash-loops). Each tip shows at most once per session and auto-clears after 12 s. Priority order favors actionable tips (crash → search → filter).
+
+### Changed
+- **`npm pkg fix` cleanup** (#7). `bin.devup` normalised to `dist/index.js` (no leading `./`), `repository.url` to `git+https://...`. New `prepack` script runs `npm pkg fix` on every publish so the warnings from 0.2.0 don't reappear.
+- `ServiceList` footer hint updated: `type to filter  ↑↓ navigate  Enter select  Esc clear/close`.
+- README gets a new "CLI subcommands" section and additions to the Features list ("Pre-flight validation", "Subcommands").
+
+### Fixed
+- Reordering inside the TUI key-binding handler so `Ctrl+F` (PgDn) never falls through to the filter modal (`f`). Same fix applied to other `Ctrl`-modified bindings.
+
+### Internals
+- Exported `extractWatchPaths(args)` from `process/manager.ts` (handles `--watch X`, `--watch-path X`, `--watch=X`, `--watch-path=X`; ignores `--watch-path` followed by another flag; doesn't match unrelated flags like `--watcher`).
+- Exported `isCrashLooped(st)` + `MAX_RESTARTS` constant from `tui/StatsPanel.tsx` for test reuse and to drive the crash-loop banner.
+- Exported `buildServiceUrl(name, port, proxyActive, proxyOpts)` from `tui/App.tsx` for testability.
+- New `src/tui/tips.ts` with a pure `pickTip(state)` function — easy to extend by appending to the priority list.
+- New `src/orchestrator/subcommands.ts` with `detectSubcommand`, `runLogs`, `runInstall`, `runStatus`, `runHelp`.
+- Test suite grown to ~274.
+
+## [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
@@ -77,6 +135,8 @@ Initial release.
 - 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.2.0]: https://github.com/gachlab/devup/releases/tag/v0.2.0
-[0.1.1]: https://github.com/gachlab/devup/releases/tag/v0.1.1
-[0.1.0]: https://github.com/gachlab/devup/releases/tag/v0.1.0
+[0.4.0]: https://github.com/gachlab/devup/releases/tag/0.4.0
+[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

@@ -20,6 +20,8 @@ Built with TypeScript 6, Ink (React for terminals), and zero test dependencies (
 - **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; 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
+- **Pre-flight validation** — `--watch-path` arguments are checked against disk before spawn so a stale config after a rebase fails loudly instead of silently
+- **Subcommands** — `devup logs <svc>`, `devup install`, `devup status` work without launching the TUI
 
 ## Quick start
 
@@ -85,6 +87,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`
 
@@ -98,11 +119,12 @@ 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`
 
@@ -122,6 +144,81 @@ npx devup
 { 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`
 
 | Field | Type | Required | Description |
@@ -144,6 +241,20 @@ When lazy mode is active (default), services not in `alwaysOn` start a TCP proxy
 
 The proxy config is only generated when `--proxy` is passed on the CLI. Only services with `health === 'up'` are included in the generated config.
 
+## CLI subcommands
+
+```
+devup                              # launch the interactive TUI (default)
+devup logs <service> [--follow]    # print the persisted log file
+devup install                      # parallel npm install across services
+devup status                       # health-check every service in config
+devup help [<subcommand>]          # show usage
+devup --version                    # print version
+devup --help                       # print flag summary
+```
+
+All subcommands need the project's `devup.config.ts` to be resolvable (use `--config <path>` to override).
+
 ## CLI flags
 
 ```
@@ -157,6 +268,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 |
 

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;
@@ -17,6 +18,7 @@ export interface CliArgs {
     logFile: boolean;
     logDir?: string;
 }
+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\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): 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;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,CAyCpD;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,eAAO,MAAM,KAAK,8gDAqC+C,CAAC;AAElE,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

@@ -12,6 +12,11 @@ export interface ServiceConfig {
     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. */
@@ -37,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;
@@ -45,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;IAClC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;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,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;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,CAoGrF;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":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,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"}