laracrew 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -17,6 +17,34 @@ 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.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
@@ -198,7 +226,8 @@ 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/vidux/laracrew/compare/v0.2.2...HEAD
+[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

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
 
@@ -467,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
@@ -499,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
@@ -507,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.
@@ -519,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
@@ -581,7 +609,7 @@ project, `LARACREW_PROJECT=<key>`.
 
 ## Status
 
-**v0.2.2 — 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
@@ -621,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, 248 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
@@ -639,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