laracrew 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,188 +1,236 @@
-# Changelog
-
-All notable changes to this project are documented here.
-
-The format follows [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). While the version is
-below `1.0.0`, minor versions may contain breaking config changes; those are always listed
-under **Changed** with a migration note.
-
-## [Unreleased]
-
-Planned, in order — see `.claude/PLAN.md`:
-
-- `laracrew scan` to discover Laravel projects and scaffold a stack
-- Live queue depth and Redis stream consumer lag in the process tree
-- File watching with graceful `queue:restart`
-- `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
-once, from one command.
-
-### Added
-
-**Supervision**
-
-- Dependency-ordered boot (`needs:`), with independent services started in parallel.
-- Readiness gates before a dependent service starts: `tcp`, `http`, `logMatch`, `delayMs`.
-- Restart policies (`never`, `on-failure`, `always`) with exponential backoff, a restart
-  ceiling, and an attempt counter that resets after a service has been stable.
-- A Laravel-aware stop ladder: `php artisan queue:restart` (or `horizon:terminate`) first, wait
-  for the worker to finish the job it is holding, then terminate — and always as a process
-  tree, so `artisan serve`'s child PHP server and `npm run dev`'s Vite are never orphaned.
-- Rollback on a failed boot: a readiness gate that never opens stops everything that had
-  already started, instead of leaving a half-booted stack behind.
-- `external: true` for services laracrew health-checks but never starts, such as Redis.
-- `autostart: false` for services defined but not launched, started later on demand.
-
-**Interface**
-
-- A full-screen process tree as the default view, which renders no log output at all; logs are
-  opened one process at a time. Built on plain ANSI — no TUI framework.
-- Per-process log inspection, a merged log across all services, restart/stop/start, and help.
-- `external: true` dependencies are listed above the tree under their own heading rather than
-  numbered among the managed processes, so a digit key always selects something startable.
-- `--plain` prefixed interleaved logs, selected automatically when stdout is not a TTY.
-- `--json` newline-delimited events for scripting.
-- A broken pipe (`laracrew up --json | head`) shuts the stack down cleanly instead of crashing.
-
-**Logs**
-
-- Every line is written to `~/.laracrew/logs/<stack>/<service>.log`, on by default, rotated by
-  size. Plain text with a sortable local timestamp and no colour codes, so `grep` works.
-- `laracrew logs [service]` reads them back after the fact, with `-n`, `-f`, `--since 10m`,
-  `--all` to merge every service in time order, and `--list`.
-- Writes go through a held file descriptor rather than a stream, so a line reaches disk before
-  a crashing process can lose it, and rotation can close the handle deterministically — a
-  rename with an open handle fails outright on Windows.
-
-**Configuration**
-
-- `~/.laracrew/` home: `config.yaml`, `projects.yaml`, one folder per stack, tasks, fragments.
-- YAML stacks validated against a schema, with errors that name the file, the field, and a
-  spelling suggestion.
-- Interpolation: `${env:VAR}`, `${env:VAR:fallback}`, `${project.path}`, `${project.env:VAR}`,
-  `${stack.dir}`, `${port:N}`.
-- Groups, profiles, `--only` / `--except` filtering, and `services/*.yaml` fragments.
-
-**Commands**
-
-- `laracrew init [--examples]`, `ls`, `up`, `doctor`, `link`, `unlink`.
-- `laracrew link <stack>` installs a global command that boots one stack, so a project set is
-  one word to launch. Generated shims are marked, and laracrew refuses to overwrite files it
-  did not write or to shadow names like `npm` and `git`.
-
-**Checks (`laracrew doctor`)**
-
-- Two projects sharing a Redis database *and* a queue or stream name, computing the effective
-  prefix the way Laravel does (`REDIS_PREFIX`, else a slug of `APP_NAME`) so it does not report
-  a collision that isn't one.
-- `QUEUE_CONNECTION=sync` in a project that runs a queue worker.
-- Port clashes, missing project paths, an unreachable Redis, and a PHP binary that will not run.
-
-### Notes
-
-- Requires Node 20 or newer. Windows, macOS and Linux.
-- Runtime dependencies: `commander`, `yaml`, `zod`.
-- 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/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
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [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). While the version is
+below `1.0.0`, minor versions may contain breaking config changes; those are always listed
+under **Changed** with a migration note.
+
+## [Unreleased]
+
+Planned, in order — see `.claude/PLAN.md`:
+
+- `laracrew scan` to discover Laravel projects and scaffold a stack
+- Live queue depth and Redis stream consumer lag in the process tree
+- File watching with graceful `queue:restart`
+- `laracrew run <task>` for one-shot cross-project sequences
+- Background daemon: `up --detach`, `attach`, `status`, `logs -f`
+
+## [0.3.0] — 2026-09-30
+
+### Added
+
+- **`laracrew draft`: build a stack without writing YAML.** `laracrew draft dual` starts
+  `dual.laracrew.yaml` in the current folder. `laracrew draft add --project api --path D:/work/api
+  --command "php artisan queue:work"` appends a service; the project's path is remembered after
+  its first mention and defaults to the current folder. `--default-state stopped` defines a
+  service that stays idle until you press `s`. `laracrew draft` shows the draft (so does `laracrew draft <name>` once it exists), and
+  `laracrew draft publish` validates it with the real schema and installs it under
+  `~/.laracrew/stacks/`, with `--link` to also install the global command. Service names are
+  derived from the project and the command (`api:queue:work`); `--name` overrides. The draft
+  is a plain stack file that can be edited by hand and committed next to the code.
+
+### Changed
+
+- **The console got a polish.** Every command now shares one vocabulary of marks — `✔` done,
+  `✖` failed, `▲` worth a look, `▸` a next step — with ASCII stand-ins under `LARACREW_ASCII=1`
+  or `TERM=dumb`. `ls` counts and aligns its sections, `doctor` names the stack it checked and
+  ends with a one-line verdict, `init` and `link` report what they did as a checklist, config
+  errors separate the file, the message and the hints, and `--help` is coloured. `up --plain`
+  tells a clean exit (`▲ exited (code 0)`) from a crash (`✖ exited (code 1)`).
+- Colour comes from `chalk` 5 (44 KB, no dependencies) instead of the hand-rolled painter. The
+  decision stays laracrew's own: `NO_COLOR`, `FORCE_COLOR` and the TTY check behave as before,
+  and `FORCE_COLOR=0` now means off, as it does everywhere else.
+- `commander` 12 → 14 for the help styling hooks. One visible side effect: an extra positional
+  argument (`laracrew up dual extra`) is now an error instead of being ignored.
+
+## [0.2.2] — 2026-09-30
+
+### Added
+
+- **`R` restarts every running process** with one keypress, in dependency order, so a
+  dependency is back and ready before the services that need it are bounced. Only what is
+  `running` is touched: a service you stopped, one defined with `autostart: false`, one that
+  exited on its own and one that gave up all stay exactly as they are. Plain and JSON runs see
+  the usual stop and start events plus a notice naming the services.
+
+### Notes
+
+- Releases are now built and published by GitHub Actions. `test.yml` runs the suite and the
+  packed-tarball smoke test on Windows and Ubuntu for every push and pull request; `publish.yml`
+  is a manual release through npm trusted publishing, with a dry-run rehearsal as the default.
+- Three tests left a log file handle open, which made the suite's teardown fail on Windows with
+  Node 20. Fixed; 248 tests.
+
+## [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
+once, from one command.
+
+### Added
+
+**Supervision**
+
+- Dependency-ordered boot (`needs:`), with independent services started in parallel.
+- Readiness gates before a dependent service starts: `tcp`, `http`, `logMatch`, `delayMs`.
+- Restart policies (`never`, `on-failure`, `always`) with exponential backoff, a restart
+  ceiling, and an attempt counter that resets after a service has been stable.
+- A Laravel-aware stop ladder: `php artisan queue:restart` (or `horizon:terminate`) first, wait
+  for the worker to finish the job it is holding, then terminate — and always as a process
+  tree, so `artisan serve`'s child PHP server and `npm run dev`'s Vite are never orphaned.
+- Rollback on a failed boot: a readiness gate that never opens stops everything that had
+  already started, instead of leaving a half-booted stack behind.
+- `external: true` for services laracrew health-checks but never starts, such as Redis.
+- `autostart: false` for services defined but not launched, started later on demand.
+
+**Interface**
+
+- A full-screen process tree as the default view, which renders no log output at all; logs are
+  opened one process at a time. Built on plain ANSI — no TUI framework.
+- Per-process log inspection, a merged log across all services, restart/stop/start, and help.
+- `external: true` dependencies are listed above the tree under their own heading rather than
+  numbered among the managed processes, so a digit key always selects something startable.
+- `--plain` prefixed interleaved logs, selected automatically when stdout is not a TTY.
+- `--json` newline-delimited events for scripting.
+- A broken pipe (`laracrew up --json | head`) shuts the stack down cleanly instead of crashing.
+
+**Logs**
+
+- Every line is written to `~/.laracrew/logs/<stack>/<service>.log`, on by default, rotated by
+  size. Plain text with a sortable local timestamp and no colour codes, so `grep` works.
+- `laracrew logs [service]` reads them back after the fact, with `-n`, `-f`, `--since 10m`,
+  `--all` to merge every service in time order, and `--list`.
+- Writes go through a held file descriptor rather than a stream, so a line reaches disk before
+  a crashing process can lose it, and rotation can close the handle deterministically — a
+  rename with an open handle fails outright on Windows.
+
+**Configuration**
+
+- `~/.laracrew/` home: `config.yaml`, `projects.yaml`, one folder per stack, tasks, fragments.
+- YAML stacks validated against a schema, with errors that name the file, the field, and a
+  spelling suggestion.
+- Interpolation: `${env:VAR}`, `${env:VAR:fallback}`, `${project.path}`, `${project.env:VAR}`,
+  `${stack.dir}`, `${port:N}`.
+- Groups, profiles, `--only` / `--except` filtering, and `services/*.yaml` fragments.
+
+**Commands**
+
+- `laracrew init [--examples]`, `ls`, `up`, `doctor`, `link`, `unlink`.
+- `laracrew link <stack>` installs a global command that boots one stack, so a project set is
+  one word to launch. Generated shims are marked, and laracrew refuses to overwrite files it
+  did not write or to shadow names like `npm` and `git`.
+
+**Checks (`laracrew doctor`)**
+
+- Two projects sharing a Redis database *and* a queue or stream name, computing the effective
+  prefix the way Laravel does (`REDIS_PREFIX`, else a slug of `APP_NAME`) so it does not report
+  a collision that isn't one.
+- `QUEUE_CONNECTION=sync` in a project that runs a queue worker.
+- Port clashes, missing project paths, an unreachable Redis, and a PHP binary that will not run.
+
+### Notes
+
+- Requires Node 20 or newer. Windows, macOS and Linux.
+- Runtime dependencies: `commander`, `yaml`, `zod`.
+- 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/vidux/laracrew/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/vidux/laracrew/compare/v0.2.2...v0.3.0
+[0.2.2]: https://github.com/vidux/laracrew/compare/v0.2.1...v0.2.2
+[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

@@ -160,6 +160,23 @@ a browser. Add your projects and the commands that run under them, and it writes
 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.
 
+**Or build it from the command line**, one service at a time, from inside the project:
+
+```bash
+cd D:/work/api
+laracrew draft dual                                                      # starts ./dual.laracrew.yaml
+laracrew draft add --project api --command "php artisan queue:work"      # --path defaults to this folder
+laracrew draft add --project api --command "php artisan schedule:work"   # the path is remembered
+laracrew draft add --project portal --path D:/work/portal --command "php artisan queue:work"
+laracrew draft add --project portal --command "npm run dev" --default-state stopped   # idle until you press s
+laracrew draft publish                                                   # validates it, installs ~/.laracrew/stacks/dual
+```
+
+`laracrew draft` on its own shows what the draft holds. Service names come from the project and
+the command (`api:queue:work`, `portal:dev`); `--name` overrides. The draft is a plain
+`stack.yaml`: edit it by hand, keep it next to the code, commit it. `publish` checks it with the
+same rules as any other stack, and `--link` also installs the global command (`dual`).
+
 ---
 
 ## One command per project set
@@ -172,7 +189,7 @@ laracrew link dual
 ```
 
 ```
-created dual -> laracrew up dual
+✔ created dual → laracrew up dual
 
 in C:\Users\you\AppData\Roaming\npm
 
@@ -310,6 +327,7 @@ the stack with a message naming both services rather than hanging.
 | `esc` | Back to the tree |
 | `a` | Merged log across every service - the firehose, on demand |
 | `r` | Restart the selected process (graceful: `queue:restart` first) |
+| `R` | Restart every running process, in dependency order. Stopped, idle and failed ones stay as they are |
 | `s` | Stop it, or start it again if stopped |
 | `f` / `g` / `G` | Follow-pause tailing; jump to top or bottom |
 | `?` | Help |
@@ -466,6 +484,9 @@ profiles:
 
 ```bash
 laracrew init [--examples]         # create ~/.laracrew; --examples adds a demo stack + template
+laracrew draft [name]              # start a stack draft in this folder, or show it
+laracrew draft add --command "…" [--project key] [--path dir] [--name svc] [--default-state stopped]
+laracrew draft publish [--force] [--link]   # validate the draft and install it under ~/.laracrew
 laracrew ls [--json]               # list stacks, projects and tasks
 laracrew doctor [stack]            # check a stack before booting it
 laracrew up [stack] [options]      # boot the fleet and supervise it
@@ -498,6 +519,8 @@ laracrew up dual --json | jq 'select(.type=="service:exit")'
 ### What `doctor` checks
 
 ```
+doctor · dual
+
 ✔ stack "dual" is valid — 8 services
 ✔ php: PHP 8.3.11 (cli)
 ✖ api and portal share Redis 127.0.0.1:6379/0# AND queue(s): default
@@ -506,6 +529,8 @@ laracrew up dual --json | jq 'select(.type=="service:exit")'
   jobs run inline on dispatch, so the worker will sit idle forever — set it to redis or database
 ✖ port 8000 is already in use
 ▲ redis not reachable at 127.0.0.1:6380
+
+✖ 3 problems, 1 warning
 ```
 
 Exit code is 1 when anything is at `✖`, so it drops straight into a pre-flight script.
@@ -518,11 +543,15 @@ commands say it talks to Redis. Run `doctor` on a Django or Node stack and you g
 that apply to it, not a wall of PHP complaints:
 
 ```
+doctor · django-celery
+
 ✔ 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
+
+✔ no blocking problems, 1 warning
 ```
 
 Services marked `external: true` are checked through the gate they already declare, so whatever
@@ -580,13 +609,13 @@ project, `LARACREW_PROJECT=<key>`.
 
 ## Status
 
-**v0.2.1 — supervisor and full-screen view are built and tested.**
+**v0.3.0 — supervisor, full-screen view and `laracrew draft` are built and tested.**
 
 Working now: config pipeline, dependency-ordered boot with readiness gates, restart policies with
 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`.
+Laravel shorthand — the full-screen process tree with per-process log inspection and a one-key
+restart of everything running, 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.
 
@@ -620,15 +649,15 @@ 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, 244 tests
+npm test                      # vitest, 281 tests
 npm run typecheck
 npm link                      # put `laracrew` on PATH while hacking on it
 ```
 
-Runtime dependencies, in total: `commander`, `yaml`, `zod`. Process spawning, tree-killing and
-colour are hand-rolled — see [ARCHITECTURE.md §9](.claude/ARCHITECTURE.md) for why `execa`,
-`tree-kill` and `picocolors` were dropped. Startup time is a feature for a tool you run twenty
-times a day.
+Runtime dependencies, in total: `commander`, `yaml`, `zod` and `chalk`. Process spawning and
+tree-killing are hand-rolled — see [ARCHITECTURE.md §9](.claude/ARCHITECTURE.md) for why `execa`
+and `tree-kill` were dropped, and what `chalk` costs. Startup time is a feature for a tool you run
+twenty times a day.
 
 The test suite spawns real child processes, binds real ports and asserts that no pid survives a
 shutdown — including a deliberately spawned grandchild and a process that ignores `SIGTERM`. Every
@@ -638,6 +667,51 @@ Architectural rule worth knowing before you contribute: **nothing in `src/core/`
 `src/cli/`**. Core emits typed events; the plain renderer, the JSON renderer and the coming TUI are
 all just subscribers. That's what keeps `--plain`, `--detach` and the tests honest.
 
+### Try it without installing from npm
+
+Five steps from a fresh clone to a running stack, without touching your real `~/.laracrew`:
+
+1. **Clone and install.**
+
+   ```bash
+   git clone https://github.com/vidux/laracrew.git && cd laracrew && npm install
+   ```
+
+2. **Point it at a throwaway home.** Everything below reads and writes there, not your real config.
+
+   ```bash
+   export LARACREW_HOME=/tmp/laracrew-try            # PowerShell: $env:LARACREW_HOME = "$env:TEMP\laracrew-try"
+   ```
+
+3. **Run from source.** `npm run dev` runs `src/index.ts` through `tsx` — no build step, every edit is live.
+
+   ```bash
+   npm run dev -- init --examples
+   npm run dev -- doctor example
+   npm run dev -- up example                          # the full-screen view; q quits
+   npm run dev -- up example --plain                  # what a pipe or CI sees
+   ```
+
+4. **Run the real binary.** `laracrew link` needs the build, and this is what users get.
+
+   ```bash
+   npm run build && npm link                          # `laracrew` on your PATH -> this checkout's dist/
+   laracrew up example
+   npm unlink -g laracrew                             # when you are done
+   ```
+
+   Rebuild after each change: the link runs `dist/index.js`, not the TypeScript.
+
+5. **Test the exact tarball npm would publish.** The smoke test packs it, installs it into an empty
+   directory, runs the installed binary and checks that no child process survived:
+
+   ```bash
+   bash .claude/skills/prepare-for-publish/smoke-test.sh
+   ```
+
+   By hand: `npm pack`, then in an empty directory `npm install ../laracrew/laracrew-<version>.tgz`
+   and `npx laracrew --version`.
+
 ## License
 
 MIT