theslopmachine 0.6.2 → 0.7.0

package/assets/slopmachine/scaffold-playbooks/laravel-default.md

@@ -0,0 +1,216 @@
+# Laravel Default Scaffold Playbook
+
+Use this playbook when the prompt explicitly asks for a Laravel/PHP baseline and does not need product-specific feature work.
+
+## Goal
+
+Ship a concrete Laravel baseline that is:
+
+- bootstrapped from the official Laravel path
+- Docker-first
+- safe by default
+- wired to a real database path without `.env`
+- verified with real Laravel tests
+- limited to baseline infrastructure only
+
+Verified lab:
+
+- `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/laravel-baseline`
+
+## Official bootstrap path
+
+Use the official Composer create-project flow:
+
+```bash
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab:/workspace" -w /workspace composer:2.8 create-project --prefer-dist laravel/laravel="^12.0" laravel-baseline
+```
+
+Observed bootstrap result for the verified lab:
+
+- `laravel/laravel v12.12.2`
+- `laravel/framework v12.56.0`
+- `phpunit/phpunit v11.5.55`
+
+## Safe pinned defaults
+
+- Docker base image: `php:8.4-cli-bookworm`
+- Composer image: `composer:2.8`
+- Laravel skeleton: `laravel/laravel v12.12.2`
+- Lockfile-pinned framework: `laravel/framework v12.56.0`
+- Lockfile-pinned test runner: `phpunit/phpunit v11.5.55`
+- database default: SQLite file in a Docker-managed volume
+
+The lockfile is the real dependency pin. Keep it committed.
+
+## No-`.env` rule
+
+- do not commit `.env`
+- do not require users to create `.env` before startup
+- point Laravel at a committed empty environment stub instead of `.env`
+- load runtime app/database values from a generated runtime config file in a Docker-managed volume
+
+Verified lab pattern:
+
+- `bootstrap/runtime-environment.stub` is the environment file Laravel loads
+- `bootstrap/runtime-config.php` loads JSON from `APP_CONFIG_PATH`
+- `scripts/bootstrap_runtime.sh` generates the JSON config and SQLite path
+
+## Database pattern
+
+- default to SQLite for the baseline
+- place the SQLite file in `/runtime/database/app.sqlite`
+- keep `/runtime` on a named Docker volume
+- run migrations from a single entrypoint script before app start and inside test execution
+- expose one real persistence-backed endpoint so DB wiring is proven, not implied
+
+Verified lab surface:
+
+- `GET /health`
+- `POST /api/items`
+- `GET /api/items`
+
+## Runtime contract
+
+Required commands:
+
+- `docker compose up --build`
+- `./run_tests.sh`
+
+Helpful extra command:
+
+- `./init_db.sh`
+
+All three commands are real in the verified lab.
+
+## Docker / Compose pattern
+
+- use `compose.yaml`
+- one app service published to loopback only with a random host port
+- one tester service behind a `test` profile
+- named volume for runtime state
+- healthcheck against `/health`
+- same image for runtime and tests
+
+Verified lab details:
+
+- host bind example during detached verification: `127.0.0.1:32786->8000`
+- host bind example during interactive verification: `127.0.0.1:32788->8000`
+
+## Testing baseline
+
+Minimum real Laravel/PHP test floor:
+
+- one unit test that proves runtime config defaults select SQLite without `.env`
+- one feature test for health/database readiness
+- one feature test for persistence-backed create/list behavior
+- containerized `./run_tests.sh` that performs both HTTP smoke checks and `php artisan test`
+
+Verified lab test files:
+
+- `tests/Unit/RuntimeConfigTest.php`
+- `tests/Feature/BaselineApiTest.php`
+
+Verified lab test result:
+
+- `3 passed (10 assertions)`
+
+## README requirements
+
+The README must honestly state:
+
+- this is a baseline, not a feature app
+- exact stack and pins used
+- exact runtime command: `docker compose up --build`
+- exact broad test command: `./run_tests.sh`
+- no `.env` requirement
+- safe database/config pattern
+- what is intentionally excluded
+- exact verification commands and observed results
+
+## Commands actually run for the verified lab
+
+All commands below were executed in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/laravel-baseline`.
+
+```bash
+docker compose config
+
+docker compose up --build -d
+
+docker compose ps
+
+docker compose port app 8000
+
+curl -fsS "http://127.0.0.1:32786/health"
+
+curl -fsS -X POST "http://127.0.0.1:32786/api/items" -H "content-type: application/json" -d '{"name":"manual-smoke-item"}'
+
+curl -fsS "http://127.0.0.1:32786/api/items"
+
+docker compose down --volumes --remove-orphans
+
+./run_tests.sh
+
+./init_db.sh
+
+python3 - <<'PY'
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+cwd = "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/laravel-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+error = None
+try:
+    deadline = time.time() + 180
+    while time.time() < deadline:
+        try:
+            port = subprocess.check_output(["docker", "compose", "port", "app", "8000"], cwd=cwd, text=True).strip().rsplit(":", 1)[-1]
+            with urlopen(f"http://127.0.0.1:{port}/health", timeout=2) as response:
+                if response.status == 200:
+                    print(f"health reached while docker compose up --build was active on port {port}")
+                    break
+        except Exception as exc:
+            error = exc
+        time.sleep(2)
+    else:
+        raise RuntimeError(f"health never became ready: {error}")
+finally:
+    proc.send_signal(signal.SIGINT)
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=30)
+    subprocess.run(["docker", "compose", "down", "--volumes", "--remove-orphans"], cwd=cwd, check=True)
+PY
+```
+
+## Observed results
+
+- `docker compose config` resolved cleanly
+- `docker compose up --build -d` started the app and `docker compose port app 8000` returned `127.0.0.1:32786`
+- `curl -fsS "http://127.0.0.1:32786/health"` returned `{"status":"ok","database":"ready"}`
+- `curl -fsS -X POST "http://127.0.0.1:32786/api/items" ...` returned `{"data":{"name":"manual-smoke-item",...,"id":1}}`
+- `curl -fsS "http://127.0.0.1:32786/api/items"` returned `{"data":[{"id":1,"name":"manual-smoke-item",...}]}`
+- `./run_tests.sh` passed and ended with `3 passed (10 assertions)`
+- `./init_db.sh` passed and ran the `2026_04_15_000000_create_items_table` migration in Docker
+- the interactive `docker compose up --build` path reached `/health` successfully and printed `health reached while docker compose up --build was active on port 32788`
+
+## Acceptance checklist
+
+Baseline is acceptable when:
+
+- official Laravel bootstrap path is used
+- dependencies are pinned by lockfile and explicit Docker image tags
+- runtime does not rely on `.env`
+- database defaults are safe and real
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- minimal real Laravel tests are present and passing
+- README is honest about included versus excluded scope
+- the lab stops at baseline infrastructure
+
+## Experimental verification status
+
+Yes. This playbook is based on an experimentally verified lab, not a hypothetical template.

package/assets/slopmachine/scaffold-playbooks/livewire-default.md

@@ -0,0 +1,265 @@
+# Laravel Livewire Default Scaffold Playbook
+
+Use this playbook when the prompt explicitly asks for a Laravel Livewire baseline and does not need product-specific feature work.
+
+This playbook follows the shared Docker contract in:
+
+- `/Users/yohannesakd/code/eaglepoint/demonstration/slopmachine-0.3/assets/slopmachine/scaffold-playbooks/docker-shared-contract.md`
+
+## Goal
+
+Ship a concrete Laravel Livewire baseline that is:
+
+- bootstrapped from the official Laravel path
+- upgraded with a real Livewire package install
+- Docker-first
+- Tailwind-preferred without pretending a richer design system exists
+- safe by default
+- wired to a real database path without `.env`
+- verified with real Livewire page/component tests inside containers
+- limited to baseline infrastructure only
+
+Verified lab:
+
+- `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline`
+
+## Official bootstrap path
+
+Use the official Composer create-project flow, then install Livewire in the created app:
+
+```bash
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab:/workspace" -w /workspace composer:2.8 create-project --prefer-dist laravel/laravel="^12.0" livewire-baseline
+
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline:/app" -w /app composer:2.8 require livewire/livewire
+```
+
+Observed bootstrap result for the verified lab:
+
+- `laravel/laravel v12.12.2`
+- `laravel/framework v12.56.0`
+- `livewire/livewire v4.2.4`
+- `phpunit/phpunit v11.5.55`
+
+## Safe pinned defaults
+
+- Docker runtime image: `php:8.4-cli-bookworm`
+- Node asset build image: `node:22-bookworm-slim`
+- Composer image: `composer:2.8`
+- Laravel skeleton: `laravel/laravel v12.12.2`
+- lockfile-pinned Livewire package: `livewire/livewire v4.2.4`
+- lockfile-pinned test runner: `phpunit/phpunit v11.5.55`
+- database default: SQLite file in a Docker-managed volume
+- frontend styling default: Tailwind via Vite build during image creation
+
+The lockfiles are the real dependency pins. Keep them committed.
+
+## No-`.env` rule
+
+- do not commit `.env`
+- do not require users to create `.env` before startup
+- point Laravel at a committed empty environment stub instead of `.env`
+- load runtime app/database values from a generated runtime config file in a Docker-managed volume
+
+Verified lab pattern:
+
+- `bootstrap/runtime-environment.stub` is the environment file Laravel loads
+- `bootstrap/runtime-config.php` loads JSON from `APP_CONFIG_PATH`
+- `scripts/bootstrap_runtime.sh` generates the JSON config and SQLite path
+
+## Livewire baseline pattern
+
+- use a full-page Livewire component as the baseline surface
+- use `Route::livewire('/', App\Livewire\ShoppingListPage::class)` for the root page
+- provide a real layout with `@vite`, `@livewireStyles`, and `@livewireScripts`
+- keep the UI honest: Tailwind-styled baseline only, not a product-grade feature set
+- back the component with one real persistence path so Livewire behavior and DB wiring are both proven
+
+Verified lab surface:
+
+- `GET /health`
+- `GET /`
+
+Verified lab component flow:
+
+- add an item from the full-page Livewire form
+- persist it into SQLite
+- rerender the saved list
+
+## Runtime contract
+
+Required commands:
+
+- `docker compose up --build`
+- `./run_tests.sh`
+
+Both commands are real in the verified lab.
+
+## Docker / Compose pattern
+
+- use `compose.yaml`
+- one app service published to loopback only with a random host port
+- one tester service behind a `test` profile
+- named volume for runtime state
+- healthcheck against `/health`
+- same application image for runtime and tests
+- multi-stage Dockerfile: Composer dependency stage, Node/Tailwind asset stage, PHP runtime stage
+
+Verified lab details:
+
+- detached verification host bind: `127.0.0.1:32800->8000`
+- interactive verification host bind: `127.0.0.1:32801->8000`
+
+## Tailwind stance
+
+- Tailwind is preferred and used here
+- build Tailwind assets ahead of runtime with Vite
+- do not pretend there is a live Vite dev-server contract when the Docker baseline serves built assets from `public/build`
+
+Verified lab files:
+
+- `resources/css/app.css`
+- `resources/views/layouts/app.blade.php`
+- `resources/views/livewire/shopping-list-page.blade.php`
+
+## Testing baseline
+
+Minimum real Livewire/Laravel test floor:
+
+- one unit test that proves runtime config defaults select SQLite without `.env`
+- one feature test for health/database readiness
+- one page-render test that proves the root Livewire page responds and includes Livewire markup
+- one Livewire component test that mutates state, saves data, and proves persistence
+- containerized `./run_tests.sh` that performs HTTP smoke checks plus `php artisan test`
+
+Verified lab test files:
+
+- `tests/Unit/RuntimeConfigTest.php`
+- `tests/Feature/LivewireBaselineTest.php`
+- `tests/Feature/ShoppingListPageTest.php`
+
+Verified lab test result:
+
+- `4 passed (13 assertions)`
+
+## README requirements
+
+The README must honestly state:
+
+- this is a baseline, not a feature app
+- exact stack and pins used
+- exact runtime command: `docker compose up --build`
+- exact broad test command: `./run_tests.sh`
+- no `.env` requirement
+- safe database/config pattern
+- Tailwind/Vite build boundary
+- what is intentionally excluded
+- exact verification commands and observed results
+
+## Commands actually run for the verified lab
+
+All commands below were executed in `/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline` unless otherwise noted.
+
+Bootstrap and dependency commands:
+
+```bash
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab:/workspace" -w /workspace composer:2.8 create-project --prefer-dist laravel/laravel="^12.0" livewire-baseline
+
+docker run --rm -u "$(id -u):$(id -g)" -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline:/app" -w /app composer:2.8 require livewire/livewire
+
+docker run --rm -u "$(id -u):$(id -g)" -e npm_config_cache=/app/.npm-cache -v "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline:/app" -w /app node:22-bookworm-slim npm install
+```
+
+Verification commands:
+
+```bash
+docker compose config
+
+docker compose up --build -d
+
+docker compose ps
+
+docker compose port app 8000
+
+curl -fsS "http://127.0.0.1:32800/health"
+
+python3 - <<'PY'
+from urllib.request import urlopen
+html = urlopen('http://127.0.0.1:32800/', timeout=10).read().decode()
+print('title=', 'Livewire baseline' in html)
+print('snapshot=', 'wire:snapshot' in html)
+print('saved_items=', 'Saved items' in html)
+PY
+
+docker compose down --volumes --remove-orphans
+
+./run_tests.sh
+
+python3 - <<'PY'
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+cwd = "/Users/yohannesakd/code/eaglepoint/demonstration/scaffold-lab/livewire-baseline"
+proc = subprocess.Popen(["docker", "compose", "up", "--build"], cwd=cwd)
+last_error = None
+try:
+    deadline = time.time() + 240
+    while time.time() < deadline:
+        try:
+            port_line = subprocess.check_output(["docker", "compose", "port", "app", "8000"], cwd=cwd, text=True).strip()
+            if not port_line:
+                raise RuntimeError("port not published yet")
+            port = port_line.rsplit(":", 1)[-1]
+            with urlopen(f"http://127.0.0.1:{port}/health", timeout=3) as response:
+                health_body = response.read().decode()
+            root_html = urlopen(f"http://127.0.0.1:{port}/", timeout=3).read().decode()
+            if 'Livewire baseline' in root_html and 'wire:snapshot' in root_html:
+                print(f"interactive docker compose up --build reached /health and / on port {port}")
+                print(health_body)
+                break
+            raise RuntimeError("root page missing Livewire markers")
+        except Exception as exc:
+            last_error = exc
+            time.sleep(2)
+    else:
+        raise RuntimeError(f"interactive compose never became ready: {last_error}")
+finally:
+    proc.send_signal(signal.SIGINT)
+    try:
+        proc.wait(timeout=30)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=30)
+    subprocess.run(["docker", "compose", "down", "--volumes", "--remove-orphans"], cwd=cwd, check=True)
+PY
+```
+
+## Observed results
+
+- `docker compose config` resolved cleanly
+- `docker compose up --build -d` started the app and `docker compose port app 8000` returned `127.0.0.1:32800`
+- `docker compose ps` reported `Up ... (healthy)`
+- `curl -fsS "http://127.0.0.1:32800/health"` returned `{"status":"ok","database":"ready"}`
+- the root page marker script printed `title= True`, `snapshot= True`, and `saved_items= True`
+- `./run_tests.sh` passed and ended with `4 passed (13 assertions)`
+- the interactive `docker compose up --build` path reached both `/health` and `/` successfully and printed `interactive docker compose up --build reached /health and / on port 32801`
+
+## Acceptance checklist
+
+Baseline is acceptable when:
+
+- official Laravel bootstrap path is used
+- Livewire is installed for real and pinned by lockfile
+- Tailwind is used honestly as the default styling layer
+- runtime does not rely on `.env`
+- database defaults are safe and real
+- `docker compose up --build` works
+- `./run_tests.sh` works
+- minimal real Livewire page/component tests are present and passing
+- README is honest about included versus excluded scope
+- the lab stops at baseline infrastructure
+
+## Experimental verification status
+
+Yes. This playbook is based on an experimentally verified lab, not a hypothetical template.

package/assets/slopmachine/scaffold-playbooks/overlay-module-matrix.md

@@ -0,0 +1,130 @@
+# Overlay / Module Matrix for Scaffold Composition
+
+Use this after selecting the scaffold root playbook. The root establishes the primary runtime and honest baseline contract; overlays add predictable non-root capabilities that recur across many prompts.
+
+## Core rule
+
+- **scaffold root:** the minimum stack needed to boot, run, test, and explain the chosen platform honestly
+- **overlay module:** a repeatable capability that is common enough to standardize but not universal enough to force into every root
+- **later prompt-specific development:** product/domain behavior, provider-specific integrations, and feature depth that depends on the actual app brief
+
+## Root vs overlay vs later work
+
+| Concern | Put in scaffold root when | Put in overlay when | Defer to later prompt-specific work when |
+| --- | --- | --- | --- |
+| Runtime/framework | it defines how the app starts and is built | almost never | never |
+| Minimal testing | one real test path is required for honesty | extra test layers are requested or predictably valuable | the test only exists for a future feature |
+| Config/secrets | the app cannot start safely without it | advanced secret/auth/policy layers are needed | provider-specific secret rotation or cloud policy details are unknown |
+| Logging/validation | tiny baseline wiring is obviously required by the stack | structured, reusable cross-cutting policy is needed | domain-specific rules and business validations are not known yet |
+| UI system | only a tiny shell/layout needed to prove the frontend runs | reusable design system, theme, component primitives, or form layer are wanted | product-specific screens and workflows are not yet defined |
+| Database | a minimal persistence path is required to prove the backend honestly | network DB, ORM, migrations, cache, or multi-service persistence is needed | schema-heavy product models are not yet known |
+| Jobs/search/export/reporting | rarely | when the prompt already implies platform support for them | when reports, indexes, or jobs depend on product logic not yet defined |
+
+## Overlay matrix
+
+| Overlay family | Typical module contents | Apply to | Keep out of root by default because |
+| --- | --- | --- | --- |
+| Testing overlays | browser E2E harness, API integration test container, contract-test wiring, visual regression setup | frontend, backend, fullstack, mobile, desktop | roots only need one honest baseline test path; deeper test stacks are optional cost |
+| Auth / security / config overlays | session/JWT wiring, user model stub, RBAC shell, CORS/CSRF/rate-limit policy, secret-file/config loader, secure cookie defaults | backend, fullstack, frontend shells with protected routes | many scaffolds do not need auth yet, and provider choice is often prompt-specific |
+| Logging / validation overlays | structured logger, request IDs, error envelope, schema validation, input parsing, shared DTO/schema package | backend, fullstack, API-heavy frontend | baseline roots can survive with light defaults; standardized policy is reusable but not universal |
+| UI system overlays | design tokens, theme switch, component primitives, layout shell, form helpers, icon setup, toast/notification shell | frontend, fullstack, desktop, some mobile | not every scaffold needs a reusable design system on day one |
+| Database overlays | Postgres/MySQL service, ORM module, migrations tool, seed path, DB admin helper, cache/Redis sidecar when persistence model requires it | backend, fullstack | some roots only need a very small default persistence story; network DB choice should stay modular |
+| Queue / job / scheduler overlays | worker service, queue broker, retry policy, cron/scheduler entrypoint, job health metrics | backend, fullstack | background processing is expensive to add and often unused in simple scaffolds |
+| Search / export / reporting overlays | search engine service stub, export pipeline shell, report generation worker, storage/export directory contract | backend, fullstack, admin-heavy frontend/fullstack | these usually depend on real domain models, so only scaffold them when the prompt already signals the need |
+
+## Reusable overlay guidance by category
+
+### Testing overlays
+
+- keep **one real baseline test path in the root**
+- add overlays for:
+  - browser E2E
+  - API integration/container tests
+  - contract testing
+  - visual regression or snapshot systems
+- do **not** pre-add heavyweight E2E browsers to every root
+
+### Auth / security / config overlays
+
+- keep **safe config loading and no-secret defaults in the root**
+- use overlays for:
+  - local auth stub or session/JWT baseline
+  - RBAC/permission shell
+  - hardened API security middleware
+  - provider-ready secret/config abstraction
+- defer:
+  - OAuth provider specifics
+  - enterprise SSO details
+  - tenant-specific policy logic
+
+### Logging / validation overlays
+
+- root may include very light logging/validation when the framework already exposes it naturally
+- overlay should standardize:
+  - structured logs
+  - correlation/request IDs
+  - shared validation schemas
+  - normalized error responses
+- defer domain validation rules that depend on real business entities
+
+### UI system overlays
+
+- root should only prove the frontend can render and be tested
+- overlay is the right place for:
+  - theme tokens
+  - reusable components
+  - navigation shell
+  - form system
+  - notification primitives
+- defer product screens, dashboards, and specialized flows
+
+### Database overlays
+
+- **yes, database modules belong in this matrix** when they are a reusable composition choice beyond the minimal root persistence story
+- keep in root:
+  - only the smallest honest persistence needed for the selected backend/fullstack scaffold
+- use overlay for:
+  - network DB service selection
+  - ORM/migrations package
+  - seed/reset helpers
+  - caching sidecars closely tied to persistence shape
+- defer schema-rich domain modeling and app-specific query logic
+
+### Queue / job / scheduler overlays
+
+- add only when the prompt already implies async work, scheduled work, ingestion, notifications, or heavy exports
+- overlay should own:
+  - separate worker runtime
+  - queue/broker service
+  - retry/dead-letter defaults
+  - scheduler entrypoint
+- defer actual business jobs until features are defined
+
+### Search / export / reporting overlays
+
+- include at scaffold time only when these are clearly part of the platform ask, such as admin/reporting systems, catalog/search products, or export-heavy back offices
+- overlay may establish:
+  - search service wiring
+  - export job shell
+  - report generation/storage contracts
+- defer report definitions, search ranking rules, and domain-specific exports
+
+## Composition examples
+
+| Composition | When it fits | Notes |
+| --- | --- | --- |
+| frontend root + UI system overlay + testing overlay | product asks for a polished web UI but feature scope is still open | keep domain pages out; ship reusable shell and stronger frontend verification |
+| backend root + database overlay + logging/validation overlay | API scaffold needs production-shaped persistence and cross-cutting API quality | root proves API baseline; overlays add Postgres/ORM/migrations plus structured request handling |
+| frontend root + backend root + database overlay + auth overlay | fullstack app with real accounts and persistent data | roots define separate runtime surfaces; overlays add shared auth and stronger persistence |
+| frontend root + backend root + database overlay + queue overlay + reporting overlay | admin/back-office or workflow app with async exports/reports | only do this when the prompt already signals jobs/reports early |
+| mobile/desktop root + backend root + auth overlay + logging/validation overlay | client app depends on API-backed identity and reusable service policy | keep platform runtime separate; centralize auth/API policy in overlays |
+
+## Decision shortcuts
+
+- if the item is required for **every** app of that root family to start honestly, keep it in the root
+- if the item is **common but optional** across many apps, make it an overlay
+- if the item depends on domain nouns, product workflows, or provider selection not yet in evidence, defer it to later development
+
+## Practical stop rule
+
+After root selection, layer only the overlays already justified by the prompt or clearly implied platform category. Stop before product-specific implementation begins.