laracrew 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -17,6 +17,96 @@ Planned, in order — see `.claude/PLAN.md`:
 - `laracrew run <task>` for one-shot cross-project sequences
 - Background daemon: `up --detach`, `attach`, `status`, `logs -f`
 
+## [0.2.1] — 2026-09-20
+
+### Added
+
+- **A stack builder**, [`docs/stack-builder.html`](docs/stack-builder.html) — a single self-contained
+  page that writes a `stack.yaml` from projects and process commands as you fill them in. It
+  encodes the rules the config resolver enforces, so it catches the mistakes before laracrew does:
+  a service with no command, `stop.artisan` on a service with no project, a `needs:` pointing at
+  nothing, an auto-started service depending on one you have to start by hand, a dependency cycle.
+  It also shows the boot order the `needs:` graph produces, level by level.
+
+  Open it from disk or serve `docs/` with GitHub Pages. It is not part of the npm package — no
+  runtime dependencies, no build step, nothing to install.
+
+## [0.2.0] — 2026-09-20
+
+Graceful shutdown for any process, not only Laravel queue workers, and a `doctor` that only
+applies its Laravel checks to Laravel.
+
+laracrew has always been able to *run* anything — the supervisor takes a command and knows
+nothing about the language behind it. But the two things that made it more than a process
+runner, the graceful stop and the pre-flight checks, both assumed PHP. This release closes that
+gap. Existing stack files keep working unchanged.
+
+### Added
+
+- **`stop.exec`** — any command as the first step of the stop ladder. It runs in the service's
+  `cwd`, with the service's environment, and laracrew waits `graceMs` for the process to exit by
+  itself before escalating to the signal and the tree kill. A Celery worker, a BullMQ consumer or
+  a Compose project now shuts down as carefully as a queue worker:
+
+  ```yaml
+  stop: { exec: ["celery", "-A", "app", "control", "shutdown"], graceMs: 25000 }
+  stop: { exec: "npm run drain", graceMs: 10000 }
+  stop: { exec: ["docker", "compose", "stop"], graceMs: 30000 }
+  ```
+
+- **`doctor` checks external dependencies.** Every `external: true` service is probed through the
+  `tcp` or `http` gate it already declares, so a stack's Postgres, RabbitMQ or HTTP dependency is
+  verified before boot — whatever the stack is written in.
+- `doctor` reads `REDIS_URL` when a project sets it instead of `REDIS_HOST` / `REDIS_PORT`.
+
+### Changed
+
+- **`stop.artisan` is now shorthand for `stop.exec`.** It resolves to `<project php> artisan
+  <command>`, run from the project root even when the service sets its own `cwd`. Behaviour for
+  existing Laravel stacks is unchanged; a service may declare one or the other, not both. A
+  service that declares its own graceful step now replaces an inherited one in either direction,
+  so a stack can default to `artisan: queue:restart` and still give one service its own `exec`.
+- **`doctor` applies each check only where it means something.** It works out which projects run
+  PHP (from their commands and from `stop.artisan`) and which talk to Redis (from their `.env`
+  and their commands). A stack with no PHP in it gets no PHP findings; a stack with no Redis gets
+  no Redis findings. Laravel stacks see exactly what they saw before.
+- A Redis address already covered by an `external: true` service's gate is no longer probed a
+  second time from the project's `.env`.
+- `laracrew --help` and the generated `projects.yaml` no longer describe projects as Laravel-only.
+  `php:` is documented as what it is: the binary the `stop.artisan` shorthand runs.
+
+### Fixed
+
+- **`laracrew --version` reported `0.1.0` on every release.** The version was a hardcoded
+  constant that nobody bumped, so `0.1.1` and `0.1.2` both identified themselves as `0.1.0`. It is
+  now baked in from `package.json` at build time, with a test that fails if the two ever disagree.
+- **`stop.artisan` on a service with no project was silently ignored** — the graceful step was
+  skipped and nothing said so. It is now a config error that names `stop.exec` as the way out.
+- **`doctor` failed on a machine without PHP** for a stack that contains no PHP: `php --version`
+  ran for every declared project and a missing binary was a blocking `✖` with exit code 1.
+- **False Redis collision between projects that never touch Redis.** Two projects with no `.env`
+  both resolved to the same synthesized default namespace and were reported as sharing it.
+- The "no `artisan` file" and "`.env` is missing or empty" warnings no longer fire for projects
+  that are not PHP projects.
+
+### Notes
+
+- 244 tests. The graceful stop step had no coverage before this release; it now has unit tests
+  for both outcomes (the process exits by itself, and the ladder escalating when it does not),
+  plus tests for every new config error.
+- The npm description and `laracrew --help` now say "your projects" rather than "your Laravel
+  projects". The README still leads with the Laravel story, which is what the tool was built for.
+
+## [0.1.2] — 2026-09-20
+
+### Added
+
+- `repository`, `homepage` and `bugs` metadata, so the npm page links back to the source.
+
+## [0.1.1] — 2026-09-20
+
+First release published to npm. No code changes from `0.1.0`.
+
 ## [0.1.0] — 2026-09-19
 
 First release. Boots and supervises the long-running processes of several Laravel projects at
@@ -90,5 +180,9 @@ once, from one command.
 - Accepted by the schema but not yet acted on: `watch`, `metrics` (read by `doctor` only), and
   `hooks`. Stack files written today stay valid.
 
-[Unreleased]: https://github.com/OWNER/laracrew/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/OWNER/laracrew/releases/tag/v0.1.0
+[Unreleased]: https://github.com/vidux/laracrew/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/vidux/laracrew/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/vidux/laracrew/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/vidux/laracrew/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/vidux/laracrew/releases/tag/v0.1.1
+[0.1.0]: https://github.com/vidux/laracrew/releases/tag/v0.1.0

package/README.md

@@ -90,8 +90,9 @@ they're holding before they exit, and nothing is left behind.
 
 Those run processes. laracrew knows what the processes *are*.
 
-- **It stops workers the Laravel way.** `php artisan queue:restart` first, wait for the current
-  job to finish, *then* terminate. Never a job killed mid-flight.
+- **It stops workers on their own terms.** `php artisan queue:restart` for Laravel,
+  `celery control shutdown` for Celery, any command you name — run first, wait for the process to
+  finish the job it is holding, *then* terminate. Never a job killed mid-flight.
 - **It kills whole process trees.** `php artisan serve` spawns a child PHP server; `npm run dev`
   spawns Vite. Killing the parent orphans them and the port stays bound. Every stop is a tree kill
   (`taskkill /T /F` on Windows, process-group kill on POSIX).
@@ -110,11 +111,15 @@ npm install -g laracrew
 laracrew init --examples
 ```
 
-> Not published to npm yet. Until it is, install from source:
-> `git clone https://github.com/vidux/laracrew && cd laracrew && npm install && npm run build && npm link`
+Or from source:
+
+```bash
+git clone https://github.com/vidux/laracrew && cd laracrew
+npm install && npm run build && npm link
+```
 
 Requires **Node 20+**. Works on Windows, macOS and Linux. PHP is only needed for the projects
-laracrew runs, not for laracrew itself.
+laracrew runs, not for laracrew itself — and only if those projects are PHP.
 
 ## Quick start
 
@@ -150,6 +155,11 @@ laracrew doctor dual
 laracrew up dual
 ```
 
+**Prefer not to write YAML by hand?** Open [`docs/stack-builder.html`](docs/stack-builder.html) in
+a browser. Add your projects and the commands that run under them, and it writes the `stack.yaml`
+as you go — checking the same rules laracrew does, so a stack that looks right there boots. No
+install, no build step; it is one file.
+
 ---
 
 ## One command per project set
@@ -433,7 +443,7 @@ profiles:
 | `ready` | `tcp`, `http`, `logMatch` (regex over output) or `delayMs`, plus `timeoutMs` (default 30000) and `intervalMs` (default 250). Without it, "spawned" means ready. |
 | `restart` | `never` · `on-failure` (default) · `always`. |
 | `backoff` | `initialMs`, `maxMs`, `factor`, `maxRestarts`, `resetAfterMs`. Delay is `min(initialMs × factor^n, maxMs)`; the counter resets after the service stays up for `resetAfterMs`. |
-| `stop` | `artisan` (a graceful command such as `queue:restart` or `horizon:terminate`), `signal`, `graceMs`. |
+| `stop` | `exec` (any graceful shutdown command), `artisan` (sugar for one that runs artisan, such as `queue:restart` or `horizon:terminate`), `signal`, `graceMs`. |
 | `url` | Recorded for the service; `laracrew open` is not built yet. |
 | `external` | Health-checked but never spawned — Redis, MySQL, a Docker service. |
 | `autostart` | `false` defines the service without launching it. It shows as **idle** in the tree; select it and press `s` when you need it. |
@@ -500,6 +510,24 @@ laracrew up dual --json | jq 'select(.type=="service:exit")'
 
 Exit code is 1 when anything is at `✖`, so it drops straight into a pre-flight script.
 
+**Every Laravel-specific check is skipped on a stack that isn't Laravel.** `doctor` works out
+which projects actually run PHP — from the commands they declare and from `stop.artisan` — and
+only those get the `php --version` check and the "no `artisan` file" warning. The same goes for
+Redis: a project is only checked for namespace collisions and reachability if its `.env` or its
+commands say it talks to Redis. Run `doctor` on a Django or Node stack and you get the checks
+that apply to it, not a wall of PHP complaints:
+
+```
+✔ stack "django-celery" is valid — 8 services
+✔ port 8000 is free
+✔ postgres is reachable — tcp 127.0.0.1:5432
+▲ redis is not reachable — tcp 127.0.0.1:6379 (ECONNREFUSED)
+  laracrew never starts an external service; anything that needs it will wait at its gate
+```
+
+Services marked `external: true` are checked through the gate they already declare, so whatever
+your stack depends on — Postgres, RabbitMQ, an HTTP service — gets verified before boot.
+
 ---
 
 ## How shutdown works
@@ -507,9 +535,8 @@ Exit code is 1 when anything is at `✖`, so it drops straight into a pre-flight
 This is where most process managers leave a mess, so it's worth stating exactly. Each step runs
 only if the previous one timed out:
 
-1. **Laravel graceful** — if the service declares `stop.artisan`, run it (`php artisan
-   queue:restart`, `horizon:terminate`) and wait up to `graceMs` for the worker to exit on its own,
-   having finished the job it was holding.
+1. **Graceful** — if the service declares `stop.exec`, run it and wait up to `graceMs` for the
+   process to exit on its own, having finished whatever it was holding.
 2. **Signal** — `SIGTERM` to the process group. Skipped on Windows, which has no equivalent.
 3. **Tree kill** — `taskkill /pid <pid> /T /F` on Windows, `kill(-pid)` on POSIX. This is what
    catches the child PHP server behind `artisan serve` and the Vite process behind `npm run dev`.
@@ -518,6 +545,19 @@ only if the previous one timed out:
 Stacks come down in reverse dependency order, parallel within a level. A second Ctrl-C escalates
 immediately and says so.
 
+Step 1 is any command, so every worker gets the same treatment your queue workers do:
+
+```yaml
+stop: { exec: ["celery", "-A", "app", "control", "shutdown"], graceMs: 20000 }
+stop: { exec: "npm run drain", graceMs: 5000 }
+stop: { exec: ["docker", "compose", "stop"], graceMs: 30000 }
+stop: { artisan: "queue:restart", graceMs: 15000 }   # shorthand for `<php> artisan queue:restart`
+```
+
+`artisan` is the Laravel shorthand: it runs through the project's PHP binary, from the project
+root, even when the service sets its own `cwd`. It needs a `project`; anything else uses `exec`.
+Without either, the ladder starts at the signal.
+
 If a readiness gate fails during boot, laracrew rolls back everything it already started before
 exiting non-zero — you never get a half-booted stack you have to clean up by hand.
 
@@ -540,12 +580,15 @@ project, `LARACREW_PROJECT=<key>`.
 
 ## Status
 
-**v0.1.0 — supervisor and full-screen view are built and tested.**
+**v0.2.1 — supervisor and full-screen view are built and tested.**
 
 Working now: config pipeline, dependency-ordered boot with readiness gates, restart policies with
-exponential backoff, the Laravel-aware stop ladder, the full-screen process tree with per-process
-log inspection, logs persisted to disk with `laracrew logs` to read them back, plain and JSON
-renderers, per-stack global commands (`link` / `unlink`), `doctor`, `init`, `ls`.
+exponential backoff, the graceful stop ladder — `stop.exec` for any process, `stop.artisan` as the
+Laravel shorthand — the full-screen process tree with per-process log inspection, logs persisted to
+disk with `laracrew logs` to read them back, plain and JSON renderers, per-stack global commands
+(`link` / `unlink`), `doctor`, `init`, `ls`.
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed in each release.
 
 Accepted by the config schema but **not yet acted on** — they validate, so your stack files are
 future-proof, but nothing happens yet:
@@ -577,7 +620,7 @@ The full plan lives in [.claude/PLAN.md](.claude/PLAN.md), with the design in
 npm install
 npm run dev -- up example     # tsx, no build step
 npm run build                 # tsup -> dist/index.js
-npm test                      # vitest, 226 tests
+npm test                      # vitest, 244 tests
 npm run typecheck
 npm link                      # put `laracrew` on PATH while hacking on it
 ```

package/dist/index.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli/program.ts
+import { readFileSync as readFileSync4 } from "fs";
+import path11 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 
 // src/core/config/errors.ts
@@ -137,8 +140,15 @@ var backoffSchema = z.object({
   /** Stay up this long and the attempt counter resets, so a slow leak can't exhaust it. */
   resetAfterMs: z.number().int().positive().default(6e4)
 }).strict();
+var commandSchema = z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]);
 var stopPolicySchema = z.object({
-  /** Laravel-native graceful shutdown, e.g. "queue:restart" or "horizon:terminate". */
+  /**
+   * Step 1 of the stop ladder: any command that asks the process to finish what it is
+   * holding and exit by itself — `celery control shutdown`, `docker compose stop`, a
+   * drain script. Runs in the service's cwd; laracrew waits `graceMs` for the exit.
+   */
+  exec: commandSchema.optional(),
+  /** Sugar for `exec` on a Laravel project: runs `<php> artisan <this>` from its root. */
   artisan: z.string().optional(),
   signal: z.string().default("SIGTERM"),
   graceMs: z.number().int().positive().default(1e4)
@@ -153,7 +163,6 @@ var metricsSchema = z.object({
   queues: z.array(z.string()).default([]),
   streams: z.array(z.object({ key: z.string(), group: z.string() }).strict()).default([])
 }).strict();
-var commandSchema = z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]);
 var serviceSchema = z.object({
   name: z.string().min(1),
   project: z.string().optional(),
@@ -719,10 +728,35 @@ var mergeService = (raw, stack, projects, ports, processEnv, colorIndex) => {
     throw error;
   }
   const cwd = service.cwd ? path4.resolve(project?.path ?? stack.dir, service.cwd) : project?.path ?? stack.dir;
+  const inheritedStop = { ...defaults.stop };
+  const ownStop = service.stop ?? {};
+  if (ownStop.exec !== void 0) delete inheritedStop.artisan;
+  if (ownStop.artisan !== void 0) delete inheritedStop.exec;
+  const stop = stopPolicySchema.parse({ ...inheritedStop, ...ownStop });
+  if (stop.exec !== void 0 && stop.artisan !== void 0) {
+    throw new ConfigError(
+      `service "${service.name}" declares both \`stop.exec\` and \`stop.artisan\``,
+      { file: stack.file, details: ["keep one \u2014 `artisan` is only shorthand for an `exec` that runs artisan"] }
+    );
+  }
+  if (stop.artisan !== void 0 && !project) {
+    throw new ConfigError(
+      `service "${service.name}" declares \`stop.artisan\` but belongs to no project`,
+      {
+        file: stack.file,
+        details: ["`artisan` runs `<project php> artisan ...`, so it needs a project", "for any other command use `stop.exec`"]
+      }
+    );
+  }
+  const graceful = stop.exec ? { command: toCommand(stop.exec), cwd } : stop.artisan && project ? (
+    // artisan must run from the Laravel root even when the service sets its own cwd.
+    { command: { kind: "argv", file: project.php, args: ["artisan", ...stop.artisan.split(/\s+/)] }, cwd: project.path }
+  ) : void 0;
   return {
     name: service.name,
     ...project ? { project } : {},
     ...service.cmd ? { command: toCommand(service.cmd) } : {},
+    ...graceful ? { graceful } : {},
     cwd,
     env: { ...service.env },
     groups: service.groups,
@@ -730,7 +764,7 @@ var mergeService = (raw, stack, projects, ports, processEnv, colorIndex) => {
     ...service.ready ? { ready: service.ready } : {},
     restart: service.restart ?? defaults.restart,
     backoff: backoffSchema.parse({ ...defaults.backoff, ...service.backoff ?? {} }),
-    stop: stopPolicySchema.parse({ ...defaults.stop, ...service.stop ?? {} }),
+    stop,
     ...service.watch ? { watch: service.watch } : {},
     ...service.metrics ? { metrics: service.metrics } : {},
     ...service.url ? { url: service.url } : {},
@@ -1385,15 +1419,17 @@ var ManagedProcess = class {
     }, delayMs);
     this.#backoffTimer.unref?.();
   }
-  /** The Laravel-native graceful shutdown, when the service declares one. */
+  /**
+   * Step 1 of the stop ladder: ask the process to finish what it is holding and exit by
+   * itself. What that command is — `queue:restart`, `celery control shutdown`, a drain
+   * script — was decided in `resolve.ts`; this only runs it.
+   */
   #graceful() {
-    const artisan = this.service.stop.artisan;
-    const project = this.service.project;
-    if (!artisan || !project) return void 0;
+    const graceful = this.service.graceful;
+    if (!graceful) return void 0;
     return async () => {
-      const command = { kind: "argv", file: project.php, args: ["artisan", ...artisan.split(/\s+/)] };
-      this.#log(`stop: ${describeCommand(command)}`);
-      await runOnce(command, { cwd: project.path, env: this.#env, timeoutMs: 15e3 });
+      this.#log(`stop: ${describeCommand(graceful.command)}`);
+      await runOnce(graceful.command, { cwd: graceful.cwd, env: this.#env, timeoutMs: 15e3 });
     };
   }
   async stop() {
@@ -2496,36 +2532,88 @@ var waitUntilIdle = (supervisor, stopRequested) => new Promise((resolve) => {
 
 // src/cli/commands/doctor.ts
 var PORT_IN_COMMAND = /--port[= ](\d{2,5})/g;
+var commandLine = (service) => {
+  if (!service.command) return "";
+  return service.command.kind === "shell" ? service.command.line : [service.command.file, ...service.command.args].join(" ");
+};
+var PHP_BINARY = /(^|[\\/\s"'])php[\d.]*(\.exe)?(\s|$)/i;
+var phpProjects = (stack) => {
+  const keys = /* @__PURE__ */ new Set();
+  for (const service of stack.services) {
+    const key = service.project?.key;
+    if (!key) continue;
+    const line = commandLine(service);
+    const php = stack.projects[key]?.php;
+    if (service.stop.artisan || PHP_BINARY.test(line) || php !== void 0 && line.startsWith(php)) {
+      keys.add(key);
+    }
+  }
+  return keys;
+};
+var REDIS_DRIVER_KEYS = [
+  "QUEUE_CONNECTION",
+  "CACHE_STORE",
+  "CACHE_DRIVER",
+  "SESSION_DRIVER",
+  "BROADCAST_CONNECTION",
+  "BROADCAST_DRIVER"
+];
+var redisProjects = (stack) => {
+  const keys = /* @__PURE__ */ new Set();
+  for (const [key, project] of Object.entries(stack.projects)) {
+    const declared = Object.keys(project.env).some((name) => name.startsWith("REDIS_"));
+    const driver = REDIS_DRIVER_KEYS.some((name) => project.env[name]?.toLowerCase() === "redis");
+    if (declared || driver) keys.add(key);
+  }
+  for (const service of stack.services) {
+    const key = service.project?.key;
+    if (!key) continue;
+    if (service.metrics || /\b(redis|horizon)\b/i.test(commandLine(service))) keys.add(key);
+  }
+  return keys;
+};
 var declaredPorts = (stack) => {
   const ports = new Set(stack.ports);
   for (const service of stack.services) {
-    const line = service.command?.kind === "shell" ? service.command.line : service.command ? [service.command.file, ...service.command.args].join(" ") : "";
-    for (const match of line.matchAll(PORT_IN_COMMAND)) {
+    for (const match of commandLine(service).matchAll(PORT_IN_COMMAND)) {
       const port = Number(match[1]);
       if (Number.isInteger(port)) ports.add(port);
     }
   }
   return [...ports].sort((a, b) => a - b);
 };
-var redisTargetOf = (project) => `${project.env.REDIS_HOST ?? "127.0.0.1"}:${project.env.REDIS_PORT ?? "6379"}`;
+var parseRedisUrl = (url) => {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname ? { host: parsed.hostname, port: parsed.port || "6379" } : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var redisTargetOf = (project) => {
+  const url = project.env.REDIS_URL ? parseRedisUrl(project.env.REDIS_URL) : void 0;
+  const host = project.env.REDIS_HOST ?? url?.host ?? "127.0.0.1";
+  const port = project.env.REDIS_PORT ?? url?.port ?? "6379";
+  return `${host}:${port}`;
+};
 var slug = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
 var redisPrefixOf = (project) => project.env.REDIS_PREFIX ?? `${slug(project.env.APP_NAME ?? "laravel")}_database_`;
 var redisNamespaceOf = (project) => `${redisTargetOf(project)}/${project.env.REDIS_DB ?? "0"}#${redisPrefixOf(project)}`;
-var checkProjects = (stack) => {
+var checkProjects = (stack, php, redis) => {
   const findings = [];
   for (const project of Object.values(stack.projects)) {
     if (!existsSync4(project.path)) {
       findings.push({ level: "error", message: `project "${project.key}": path does not exist \u2014 ${project.path}` });
       continue;
     }
-    if (!existsSync4(path7.join(project.path, "artisan"))) {
+    if (php.has(project.key) && !existsSync4(path7.join(project.path, "artisan"))) {
       findings.push({
         level: "warn",
         message: `project "${project.key}": no \`artisan\` file in ${project.path}`,
         hint: "laracrew will still run the commands, but this does not look like a Laravel root"
       });
     }
-    if (Object.keys(project.env).length === 0) {
+    if (Object.keys(project.env).length === 0 && (php.has(project.key) || redis.has(project.key))) {
       findings.push({
         level: "warn",
         message: `project "${project.key}": ${project.envFile} is missing or empty`,
@@ -2535,9 +2623,9 @@ var checkProjects = (stack) => {
   }
   return findings;
 };
-var checkRedisCollisions = (stack) => {
+var checkRedisCollisions = (stack, redis) => {
   const findings = [];
-  const projects = Object.values(stack.projects);
+  const projects = Object.values(stack.projects).filter((project) => redis.has(project.key));
   const byNamespace = /* @__PURE__ */ new Map();
   for (const project of projects) {
     const namespace = redisNamespaceOf(project);
@@ -2611,8 +2699,7 @@ var checkQueueConnections = (stack) => {
   const workerProjects = new Set(
     stack.services.filter((service) => {
       if (!service.autostart) return false;
-      const line = service.command?.kind === "shell" ? service.command.line : service.command ? [service.command.file, ...service.command.args].join(" ") : "";
-      return /\b(queue:work|queue:listen|horizon)\b/.test(line);
+      return /\b(queue:work|queue:listen|horizon)\b/.test(commandLine(service));
     }).map((service) => service.project?.key).filter((key) => Boolean(key))
   );
   for (const key of workerProjects) {
@@ -2630,8 +2717,10 @@ var checkQueueConnections = (stack) => {
   }
   return findings;
 };
-var checkPhp = async (stack) => {
-  const binaries = new Set(Object.values(stack.projects).map((project) => project.php));
+var checkPhp = async (stack, php) => {
+  const binaries = new Set(
+    Object.values(stack.projects).filter((project) => php.has(project.key)).map((project) => project.php)
+  );
   const findings = [];
   for (const binary of binaries) {
     try {
@@ -2669,8 +2758,29 @@ var checkPorts = async (stack) => {
   }
   return findings;
 };
-var checkRedisReachable = async (stack) => {
-  const targets = new Set(Object.values(stack.projects).map(redisTargetOf));
+var checkExternalServices = async (stack) => {
+  const external = stack.services.filter((service) => service.external && (service.ready?.tcp ?? service.ready?.http));
+  return Promise.all(
+    external.map(async (service) => {
+      const probe = service.ready;
+      const label = describeProbe(probe);
+      const result = probe.http ? await httpProbe(probe.http, 2e3) : await tcpProbe(probe.tcp, 2e3);
+      return result.ok ? { level: "ok", message: `${service.name} is reachable \u2014 ${label}` } : {
+        level: "warn",
+        message: `${service.name} is not reachable \u2014 ${label}${result.detail ? ` (${result.detail})` : ""}`,
+        hint: "laracrew never starts an external service; anything that needs it will wait at its gate"
+      };
+    })
+  );
+};
+var externalTcpTargets = (stack) => new Set(
+  stack.services.filter((service) => service.external && service.ready?.tcp).map((service) => service.ready.tcp)
+);
+var checkRedisReachable = async (stack, redis) => {
+  const covered = externalTcpTargets(stack);
+  const targets = new Set(
+    Object.values(stack.projects).filter((project) => redis.has(project.key)).map(redisTargetOf).filter((target) => !covered.has(target))
+  );
   const findings = [];
   for (const target of targets) {
     const result = await tcpProbe(target, 2e3);
@@ -2688,13 +2798,20 @@ var runDoctor = async (stackName, env = process.env) => {
     if (error instanceof ConfigError) return [{ level: "error", message: error.format() }];
     throw error;
   }
+  const php = phpProjects(stack);
+  const redis = redisProjects(stack);
   const findings = [
     { level: "ok", message: `stack "${stack.name}" is valid \u2014 ${stack.services.length} services` },
-    ...checkProjects(stack),
+    ...checkProjects(stack, php, redis),
     ...checkQueueConnections(stack),
-    ...checkRedisCollisions(stack)
+    ...checkRedisCollisions(stack, redis)
   ];
-  const async = await Promise.all([checkPhp(stack), checkPorts(stack), checkRedisReachable(stack)]);
+  const async = await Promise.all([
+    checkPhp(stack, php),
+    checkPorts(stack),
+    checkExternalServices(stack),
+    checkRedisReachable(stack, redis)
+  ]);
   return [...findings, ...async.flat()];
 };
 var doctorCommand = async (stackName, env = process.env) => {
@@ -2728,8 +2845,11 @@ metricsIntervalMs: 2000
 # The stack \`laracrew up\` boots when you don't name one.
 # defaultStack: dual
 `;
-var PROJECTS_YAML = `# Your Laravel projects, referenced by key from any stack.
+var PROJECTS_YAML = `# Your projects, referenced by key from any stack. A project is just a root directory
+# plus the defaults its services inherit \u2014 cwd, .env and colour. Any language.
 # Paths may use forward slashes on Windows.
+#
+# Declaring projects here is optional: a service can carry its own \`cwd\` instead.
 projects: {}
 
 # Example \u2014 delete the \`{}\` above and uncomment:
@@ -2737,12 +2857,11 @@ projects: {}
 # projects:
 #   api:
 #     path: D:/work/api
-#     php: php            # or an absolute path to a specific PHP build
-#     envFile: .env       # read for QUEUE_CONNECTION, REDIS_*, APP_URL, DB_*
+#     php: php            # only used by \`stop: { artisan: ... }\`; ignore it for non-PHP projects
+#     envFile: .env       # read for \${project.env:KEY} tokens, and by \`doctor\`
 #     color: cyan
-#   portal:
-#     path: D:/work/portal
-#     php: php
+#   web:
+#     path: D:/work/web
 #     envFile: .env
 #     color: magenta
 `;
@@ -3436,7 +3555,7 @@ ${paint("bold", "TASKS")}`);
 };
 
 // src/cli/program.ts
-var VERSION = "0.1.0";
+var VERSION = true ? "0.2.1" : versionFromPackageJson();
 var resolveStackName = (explicit, env = process.env) => {
   if (explicit) return explicit;
   const configured = loadGlobalConfig(env).defaultStack;
@@ -3454,7 +3573,7 @@ var resolveStackName = (explicit, env = process.env) => {
 var collect = (value, previous) => [...previous, value];
 var buildProgram = () => {
   const program = new Command();
-  program.name("laracrew").description("Boot and supervise all the long-running processes of your Laravel projects with one command.").version(VERSION, "-v, --version").showHelpAfterError();
+  program.name("laracrew").description("Boot and supervise all the long-running processes of your projects with one command.").version(VERSION, "-v, --version").showHelpAfterError();
   program.command("init").description("create ~/.laracrew").option("--examples", "also write a runnable demo stack and a two-project template").action((options) => {
     initCommand({ examples: options.examples ?? false });
   });