laracrew 0.1.1

package/examples/README.md

@@ -0,0 +1,79 @@
+# Examples
+
+Five working stacks. Only one of them is Laravel — laracrew supervises processes, and it does
+not care what language wrote them.
+
+Each example is self-contained: projects are declared inline, so there is nothing to wire up in
+`projects.yaml` first. Copy one, change the paths at the top, and run it.
+
+```bash
+cp -r examples/node-api-and-web ~/.laracrew/stacks/
+$EDITOR ~/.laracrew/stacks/node-api-and-web/stack.yaml   # fix the paths
+laracrew doctor node-api-and-web
+laracrew up node-api-and-web
+```
+
+Each stack declares a `command:`, so `laracrew link <name>` turns it into a single global word
+you can type from anywhere.
+
+| Example | Stack | What it is |
+|---|---|---|
+| [laravel-dual](laravel-dual/stack.yaml) | `dual` | Two interconnected Laravel apps: queues, Redis stream listeners, schedulers, Vite |
+| [node-api-and-web](node-api-and-web/stack.yaml) | `web` | TypeScript API, Vite frontend, BullMQ worker, Postgres and Redis |
+| [django-celery](django-celery/stack.yaml) | `django` | Django, a Celery worker, beat, and the optional extras |
+| [polyglot-microservices](polyglot-microservices/stack.yaml) | `micro` | Go, Rust, Node and Python behind a gateway, with Docker Compose for infrastructure |
+| [frontend-monorepo](frontend-monorepo/stack.yaml) | `fe` | The smallest useful stack: tsc, Tailwind, Storybook and docs watchers in one repo |
+
+## What each one is there to teach
+
+**laravel-dual** — the case laracrew was built for. Graceful worker shutdown through
+`php artisan queue:restart`, so a job is never killed mid-flight; the portal waiting on a real
+HTTP 200 from the API rather than a sleep; profiles to skip Vite when you are only touching the
+backend.
+
+**node-api-and-web** — no PHP anywhere. A one-shot `types:build` that everything else depends on,
+readiness by log output for tools that announce themselves (`Local: http://…`), per-service
+environment variables, and a secret read from your own shell with `${env:VAR:fallback}` instead
+of being committed.
+
+**django-celery** — migrations that must finish before the web server starts, `PYTHONUNBUFFERED`
+so the log pane is not empty, a `SIGTERM` graceful stop for Celery instead of an artisan command,
+and a second worker plus Flower left dormant behind `autostart: false`.
+
+**polyglot-microservices** — the ordering problem at full size. `docker compose up` supervised as
+an ordinary process so it stops with everything else; a gateway that starts only once all three
+services answer `/health`; a generous gate on the Rust service because a cold `cargo build` is
+slow, rather than a boot that fails at 30 seconds.
+
+**frontend-monorepo** — proof that a "stack" needs neither multiple apps nor a server. Watchers
+in one repository, ordered so types build before Storybook consumes them, with `vitest --watch`
+and `lint:fix` sitting idle until you press `s`.
+
+## Patterns worth stealing
+
+**Gate on reality, not on time.** `ready: { http: … }` or `{ tcp: … }` beats a sleep. When a
+build is genuinely slow, raise `timeoutMs` rather than removing the gate.
+
+```yaml
+ready: { http: "http://127.0.0.1:8002/health", timeoutMs: 300000, intervalMs: 2000 }
+```
+
+**Keep the occasional things in the stack, just not running.** A backfill command, a database
+UI, a test watcher — define them with `autostart: false` so they are documented and one keypress
+away, instead of living in your shell history.
+
+**Let laracrew own Docker Compose too.** It is a long-running process like any other. Supervised
+here, it stops when the rest of the stack stops.
+
+```yaml
+- name: infra
+  cmd: ["docker", "compose", "up"]
+  ready: { tcp: "127.0.0.1:5432", timeoutMs: 120000, intervalMs: 1000 }
+  stop: { graceMs: 30000 }
+```
+
+**Use the argv form when arguments get interesting.** `cmd: ["npm", "run", "dev"]` cannot
+mis-split on a path containing spaces the way a shell string can.
+
+**A gate with nothing to start is fine.** An `external: true` service is just a health check, so
+it can stand in as a named wait step — see `kafka-wait` in the microservices example.

package/examples/django-celery/stack.yaml

@@ -0,0 +1,94 @@
+# Django with Celery: web server, worker, beat scheduler, and the optional extras.
+#
+# Demonstrates: reading values out of the project's own .env with ${project.env:...},
+#               a virtualenv interpreter, autostart:false for tools you open occasionally,
+#               and a worker whose graceful stop is a signal rather than an artisan command.
+#
+# Setup: edit the path and the interpreter, then
+#   cp -r django-celery ~/.laracrew/stacks/
+#   laracrew up django-celery
+name: django-celery
+description: Django + Celery worker + beat
+command: django
+
+projects:
+  app:
+    path: ~/code/bookstore
+    envFile: .env # DJANGO_SETTINGS_MODULE, REDIS_URL, DB_*
+    color: green
+
+defaults:
+  restart: on-failure
+  backoff: { initialMs: 1000, maxMs: 20000, factor: 2, maxRestarts: 10 }
+  # Celery handles SIGTERM properly: it stops accepting work and drains what it holds.
+  stop: { signal: SIGTERM, graceMs: 20000 }
+
+services:
+  - name: redis
+    external: true
+    ready: { tcp: "127.0.0.1:6379", timeoutMs: 10000 }
+
+  - name: postgres
+    external: true
+    ready: { tcp: "127.0.0.1:5432", timeoutMs: 10000 }
+
+  # Migrations run to completion before anything that touches the database starts.
+  - name: migrate
+    project: app
+    cmd: [".venv/bin/python", "manage.py", "migrate", "--noinput"]
+    groups: [setup]
+    needs: [postgres]
+    restart: never
+    ready: { logMatch: "No migrations to apply|Applying|OK", timeoutMs: 120000 }
+
+  - name: web
+    project: app
+    cmd: [".venv/bin/python", "manage.py", "runserver", "0.0.0.0:${port:8000}"]
+    groups: [http]
+    needs: [postgres, redis, migrate]
+    env:
+      PYTHONUNBUFFERED: "1" # without this, output is buffered and the log pane stays empty
+      DJANGO_SETTINGS_MODULE: bookstore.settings.local
+    ready: { http: "http://127.0.0.1:8000/healthz", timeoutMs: 30000 }
+    url: http://127.0.0.1:8000
+    stop: { graceMs: 5000 }
+
+  - name: celery:worker
+    project: app
+    cmd: [".venv/bin/celery", "-A", "bookstore", "worker", "--loglevel=info", "--concurrency=4"]
+    groups: [workers]
+    needs: [redis, migrate]
+    env:
+      PYTHONUNBUFFERED: "1"
+    ready: { logMatch: "ready\\.$|celery@.* ready", timeoutMs: 30000 }
+
+  - name: celery:beat
+    project: app
+    cmd: [".venv/bin/celery", "-A", "bookstore", "beat", "--loglevel=info"]
+    groups: [scheduler]
+    needs: [redis, celery:worker]
+    env:
+      PYTHONUNBUFFERED: "1"
+
+  # A second worker for a queue that only matters during imports.
+  - name: celery:imports
+    project: app
+    cmd: [".venv/bin/celery", "-A", "bookstore", "worker", "--queues=imports", "--concurrency=1"]
+    groups: [workers]
+    needs: [redis]
+    autostart: false
+    env:
+      PYTHONUNBUFFERED: "1"
+
+  # Monitoring UI — useful, but not something you need running all day.
+  - name: flower
+    project: app
+    cmd: [".venv/bin/celery", "-A", "bookstore", "flower", "--port=5555"]
+    groups: [tooling]
+    needs: [redis]
+    autostart: false
+    url: http://127.0.0.1:5555
+
+profiles:
+  no-scheduler: { except: [scheduler] }
+  workers-only: { only: [workers, redis, migrate, postgres] }

package/examples/frontend-monorepo/stack.yaml

@@ -0,0 +1,76 @@
+# The smallest useful stack: a handful of watchers in one repository. No servers,
+# no databases, no projects — just the processes you would otherwise keep in six tabs.
+#
+# Demonstrates: that a "stack" does not need multiple apps or any Laravel at all, and that
+#               `cwd` alone is enough when everything lives under one root.
+#
+# Setup: point `root` at your repository, then
+#   cp -r frontend-monorepo ~/.laracrew/stacks/
+#   laracrew up frontend-monorepo
+name: frontend-monorepo
+description: Type checking, bundling and docs for a pnpm workspace
+command: fe
+
+projects:
+  root:
+    path: ~/code/design-system
+    color: cyan
+
+defaults:
+  restart: on-failure
+  backoff: { initialMs: 1000, maxMs: 10000, factor: 2, maxRestarts: 5 }
+  stop: { graceMs: 3000 }
+
+services:
+  # Types first: everything else consumes the built declarations.
+  - name: types
+    project: root
+    cwd: packages/core # relative to the project path
+    cmd: ["pnpm", "exec", "tsc", "--watch", "--preserveWatchOutput"]
+    groups: [build]
+    ready: { logMatch: "Found 0 errors|Watching for file changes", timeoutMs: 120000 }
+
+  - name: tailwind
+    project: root
+    cwd: packages/ui
+    cmd: ["pnpm", "exec", "tailwindcss", "-i", "./src/index.css", "-o", "./dist/index.css", "--watch"]
+    groups: [build]
+    ready: { logMatch: "Done in|Rebuilding", timeoutMs: 60000 }
+
+  - name: storybook
+    project: root
+    cwd: packages/ui
+    cmd: ["pnpm", "run", "storybook"]
+    groups: [docs]
+    needs: [types, tailwind]
+    ready: { logMatch: "Storybook.*started|Local:", timeoutMs: 180000 }
+    url: http://127.0.0.1:6006
+
+  - name: docs
+    project: root
+    cwd: apps/docs
+    cmd: ["pnpm", "run", "dev"] # Astro, Docusaurus, Next — whatever you use
+    groups: [docs]
+    needs: [types]
+    ready: { logMatch: "Local:|ready in", timeoutMs: 60000 }
+    url: http://127.0.0.1:4321
+
+  # Noisy on every keystroke — start it when you are actually fixing tests.
+  - name: tests
+    project: root
+    cmd: ["pnpm", "exec", "vitest", "--watch"]
+    groups: [tooling]
+    autostart: false
+    restart: never
+
+  # One-shot: select it, press `s`, watch it finish, carry on.
+  - name: lint
+    project: root
+    cmd: ["pnpm", "run", "lint:fix"]
+    groups: [tooling]
+    autostart: false
+    restart: never
+
+profiles:
+  build-only: { only: [build] }
+  no-storybook: { except: [storybook] } # it is the slowest thing here

package/examples/laravel-dual/stack.yaml

@@ -0,0 +1,107 @@
+# Two interconnected Laravel apps: queues, Redis stream listeners, schedulers, Vite.
+#
+# Demonstrates: artisan-aware graceful stop, readiness gates that order the boot,
+#               autostart:false for commands you run occasionally, groups and profiles.
+#
+# Setup: edit the two paths below, then
+#   cp -r laravel-dual ~/.laracrew/stacks/
+#   laracrew doctor laravel-dual && laracrew up laravel-dual
+name: laravel-dual
+description: API + Portal with queues, streams and schedulers
+command: dual
+
+# Projects are declared inline here so the example is self-contained. Move them to
+# ~/.laracrew/projects.yaml and use `use: [api, portal]` once you have several stacks.
+projects:
+  api:
+    path: D:/work/api
+    php: php # or an absolute path to a specific build
+    envFile: .env # read for QUEUE_CONNECTION, REDIS_*, APP_URL
+    color: cyan
+  portal:
+    path: D:/work/portal
+    php: php
+    color: magenta
+
+defaults:
+  restart: on-failure
+  backoff: { initialMs: 2000, maxMs: 30000, factor: 2, maxRestarts: 10 }
+  # Workers finish the job they are holding before laracrew terminates them.
+  stop: { artisan: "queue:restart", graceMs: 15000 }
+
+services:
+  - name: redis
+    external: true # health-checked, never started or stopped by laracrew
+    ready: { tcp: "127.0.0.1:6379", timeoutMs: 10000 }
+
+  # ---------------------------------------------------------------- api
+  - name: api:serve
+    project: api
+    cmd: php artisan serve --port=${port:8000}
+    groups: [http]
+    needs: [redis]
+    ready: { http: "http://127.0.0.1:8000/up", timeoutMs: 20000 }
+    url: http://127.0.0.1:8000
+    stop: { graceMs: 5000 } # a web server has no job to finish
+
+  - name: api:queue
+    project: api
+    cmd:
+      ["php", "artisan", "queue:work", "redis", "--queue=high,default", "--tries=3", "--timeout=90"]
+    groups: [workers]
+    needs: [redis]
+    metrics: { queues: [high, default] }
+
+  - name: api:streams
+    project: api
+    cmd: ["php", "artisan", "redis-stream:run", "orders_sync"]
+    groups: [workers, streams]
+    needs: [redis]
+    metrics:
+      streams:
+        - { key: orders_sync, group: api-consumers }
+
+  - name: api:schedule
+    project: api
+    cmd: ["php", "artisan", "schedule:work"] # schedule:run is one tick; :work is the daemon
+    groups: [scheduler]
+    needs: [redis]
+
+  - name: api:vite
+    project: api
+    cmd: npm run dev
+    groups: [assets]
+    ready: { logMatch: "ready in|Local:", timeoutMs: 30000 }
+    stop: { graceMs: 3000 }
+
+  # ---------------------------------------------------------------- portal
+  # Nothing here starts until the API is actually answering HTTP.
+  - name: portal:serve
+    project: portal
+    cmd: php artisan serve --port=${port:8001}
+    groups: [http]
+    needs: [redis, api:serve]
+    ready: { http: "http://127.0.0.1:8001/up", timeoutMs: 20000 }
+    url: http://127.0.0.1:8001
+    stop: { graceMs: 5000 }
+
+  - name: portal:queue
+    project: portal
+    cmd: ["php", "artisan", "queue:work", "redis", "--tries=3"]
+    groups: [workers]
+    needs: [redis, api:serve]
+    metrics: { queues: [default] }
+
+  # Defined but not launched — select it and press `s` when you need a backfill.
+  - name: portal:backfill
+    project: portal
+    cmd: ["php", "artisan", "portal:backfill-orders"]
+    groups: [maintenance]
+    needs: [redis]
+    autostart: false
+    restart: never
+
+profiles:
+  light: { except: [assets] } # skip Vite when you are only touching the backend
+  workers-only: { only: [workers, redis] }
+  api-only: { except: [portal:serve, portal:queue, portal:backfill] }

package/examples/node-api-and-web/stack.yaml

@@ -0,0 +1,99 @@
+# A TypeScript API, a Vite frontend, a BullMQ worker and a database — no PHP anywhere.
+#
+# Demonstrates: logMatch readiness for tools that announce themselves, per-service env,
+#               a build step that must finish before anything else starts, argv-form
+#               commands so paths with spaces cannot mis-split.
+#
+# Setup: edit the paths, then
+#   cp -r node-api-and-web ~/.laracrew/stacks/
+#   laracrew up node-api-and-web
+name: node-api-and-web
+description: Node API + Vite web + BullMQ worker
+command: web
+
+projects:
+  api:
+    path: ~/code/shop/api
+    color: cyan
+  web:
+    path: ~/code/shop/web
+    color: magenta
+  shared:
+    path: ~/code/shop/packages/types
+    color: green
+
+defaults:
+  restart: on-failure
+  backoff: { initialMs: 1000, maxMs: 15000, factor: 2, maxRestarts: 10 }
+  stop: { graceMs: 5000 }
+
+services:
+  # Infrastructure this stack expects to already be running.
+  - name: postgres
+    external: true
+    ready: { tcp: "127.0.0.1:5432", timeoutMs: 10000 }
+
+  - name: redis
+    external: true
+    ready: { tcp: "127.0.0.1:6379", timeoutMs: 10000 }
+
+  # A one-shot build. `restart: never` means it is finished, not crashed, when it exits 0.
+  # Everything that imports the shared types waits for it.
+  - name: types:build
+    project: shared
+    cmd: ["npm", "run", "build"]
+    groups: [build]
+    restart: never
+    ready: { logMatch: "build (complete|succeeded)|Done in", timeoutMs: 120000 }
+
+  - name: api
+    project: api
+    cmd: ["npm", "run", "dev"] # e.g. tsx watch src/server.ts
+    groups: [backend]
+    needs: [postgres, redis, types:build]
+    env:
+      NODE_ENV: development
+      PORT: "3000"
+      # Pull a secret from your own shell rather than committing it.
+      STRIPE_KEY: ${env:STRIPE_TEST_KEY:sk_test_placeholder}
+    ready: { http: "http://127.0.0.1:3000/health", timeoutMs: 30000 }
+    url: http://127.0.0.1:3000
+
+  - name: api:worker
+    project: api
+    cmd: ["npm", "run", "worker"] # BullMQ / Bee-Queue consumer
+    groups: [backend, workers]
+    needs: [redis, types:build]
+    # Give an in-flight job a moment to settle before the process is taken down.
+    stop: { graceMs: 10000 }
+
+  - name: web
+    project: web
+    cmd: ["npm", "run", "dev"]
+    groups: [frontend]
+    needs: [api] # don't boot the UI against an API that isn't answering
+    env:
+      VITE_API_URL: http://127.0.0.1:3000
+    ready: { logMatch: "Local:\\s+http", timeoutMs: 30000 }
+    url: http://127.0.0.1:5173
+    stop: { graceMs: 3000 }
+
+  # Handy, but noisy — start it when you actually want it.
+  - name: web:test
+    project: web
+    cmd: ["npm", "run", "test:watch"]
+    groups: [tooling]
+    autostart: false
+    restart: never
+
+  - name: api:studio
+    project: api
+    cmd: ["npm", "run", "db:studio"] # Prisma Studio, Drizzle Studio, etc.
+    groups: [tooling]
+    needs: [postgres]
+    autostart: false
+    url: http://127.0.0.1:5555
+
+profiles:
+  backend-only: { only: [backend, postgres, redis, types:build] }
+  frontend-only: { only: [frontend, types:build] }

package/examples/polyglot-microservices/stack.yaml

@@ -0,0 +1,120 @@
+# Four services in four languages, plus their infrastructure in Docker.
+#
+# Demonstrates: laracrew managing `docker compose` itself as a supervised process,
+#               a strict boot order enforced by HTTP and TCP gates rather than sleeps,
+#               and a gateway that refuses to start before its dependencies answer.
+#
+# This is the case laracrew is really for: the ordering is the hard part, not the running.
+#
+# Setup: edit the paths, then
+#   cp -r polyglot-microservices ~/.laracrew/stacks/
+#   laracrew up polyglot-microservices
+name: polyglot-microservices
+description: Go gateway, Rust search, Node orders, Python pricing
+command: micro
+
+projects:
+  infra:
+    path: ~/code/platform/infra # holds docker-compose.yml
+    color: yellow
+  gateway:
+    path: ~/code/platform/gateway # Go
+    color: cyan
+  search:
+    path: ~/code/platform/search # Rust
+    color: red
+  orders:
+    path: ~/code/platform/orders # Node
+    color: magenta
+  pricing:
+    path: ~/code/platform/pricing # Python
+    color: green
+
+defaults:
+  restart: on-failure
+  backoff: { initialMs: 2000, maxMs: 30000, factor: 2, maxRestarts: 8 }
+  stop: { graceMs: 10000 }
+
+services:
+  # Docker Compose is just another long-running process. laracrew starts it, streams its
+  # output, and stops it with the rest of the stack — no separate terminal, no forgetting.
+  - name: infra
+    project: infra
+    cmd: ["docker", "compose", "up"]
+    groups: [infra]
+    # Ready when every port we depend on is actually accepting connections.
+    ready: { tcp: "127.0.0.1:5432", timeoutMs: 120000, intervalMs: 1000 }
+    # Compose needs time to stop its own containers cleanly.
+    stop: { graceMs: 30000 }
+
+  - name: kafka-wait
+    external: true # nothing to start; this row exists purely as a gate
+    needs: [infra]
+    ready: { tcp: "127.0.0.1:9092", timeoutMs: 120000, intervalMs: 1000 }
+
+  # ---------------------------------------------------------------- services
+  - name: pricing
+    project: pricing
+    cmd: ["uvicorn", "app.main:app", "--reload", "--port", "${port:8001}"]
+    groups: [services]
+    needs: [infra]
+    env:
+      PYTHONUNBUFFERED: "1"
+    ready: { http: "http://127.0.0.1:8001/health", timeoutMs: 60000 }
+    url: http://127.0.0.1:8001
+
+  - name: search
+    project: search
+    cmd: ["cargo", "watch", "-x", "run"]
+    groups: [services]
+    needs: [infra]
+    env:
+      RUST_LOG: info
+    # A cold cargo build is slow; give the gate room rather than failing the boot.
+    ready: { http: "http://127.0.0.1:8002/health", timeoutMs: 300000, intervalMs: 2000 }
+    url: http://127.0.0.1:8002
+
+  - name: orders
+    project: orders
+    cmd: ["npm", "run", "dev"]
+    groups: [services]
+    needs: [infra, kafka-wait]
+    env:
+      NODE_ENV: development
+      KAFKA_BROKERS: 127.0.0.1:9092
+    ready: { http: "http://127.0.0.1:8003/health", timeoutMs: 60000 }
+    url: http://127.0.0.1:8003
+
+  # The gateway proxies all three, so it starts last — by declaration, not by sleeping.
+  - name: gateway
+    project: gateway
+    cmd: ["go", "run", "./cmd/gateway"]
+    groups: [edge]
+    needs: [pricing, search, orders]
+    env:
+      PRICING_URL: http://127.0.0.1:8001
+      SEARCH_URL: http://127.0.0.1:8002
+      ORDERS_URL: http://127.0.0.1:8003
+    ready: { http: "http://127.0.0.1:8080/health", timeoutMs: 60000 }
+    url: http://127.0.0.1:8080
+
+  # ---------------------------------------------------------------- on demand
+  - name: orders:consumer
+    project: orders
+    cmd: ["npm", "run", "consumer"]
+    groups: [workers]
+    needs: [kafka-wait]
+    autostart: false
+
+  - name: seed
+    project: infra
+    cmd: ["./scripts/seed.sh"]
+    groups: [maintenance]
+    needs: [infra]
+    autostart: false
+    restart: never
+
+profiles:
+  # Work on the gateway against services you are not editing.
+  edge-only: { only: [edge, infra, kafka-wait] }
+  no-search: { except: [search] } # skip the slow Rust rebuild

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "laracrew",
+  "version": "0.1.1",
+  "description": "Boot and supervise all the long-running processes of your Laravel projects with one command.",
+  "keywords": [
+    "laravel",
+    "cli",
+    "tui",
+    "queue",
+    "horizon",
+    "redis",
+    "process-manager",
+    "dev-tools"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "laracrew": "./dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.5.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  },
+  "author": "viduranga <https://github.com/vidux>"
+}