@muggleai/works 4.12.2 → 4.12.4

package/plugin/skills/muggle-test-prepare/steps/check-running.md

@@ -0,0 +1,31 @@
+# Check what's already running
+
+Run port detection and (when an app declares a backend URL) backend-health probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md). Cross-reference hits against selected service directories.
+
+> "**backend-api** is already listening on port 3001 (PID 54321) — looks good."
+
+If **all** required services are running, skip straight to [smoke-test](./smoke-test.md) — don't trust port-listening alone.
+
+If some are running, acknowledge and continue to [start-commands](./start-commands.md) only for the missing ones. For already-running services:
+- Option 1: "It's fine, keep it"
+- Option 2: "Restart it"
+
+Mark kept services as `external: true` in the tracking file so cleanup leaves them alone.
+
+## Port already held
+
+When the user wants a port held by a process they did **not** select (typically a stale dev server from a sibling worktree):
+
+> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
+
+- Option 1: "Use the next available port" (recommended — non-destructive)
+- Option 2: "Force-kill PID 87421 and claim port 3999"
+- Option 3: "Abort"
+
+**Option 1**: probe `3999 + N` for `N = 1, 2, …` until nothing listens. Record the new port and any env file edit (`PORT=` in `.env.local` etc.). Dev server may need restart to pick up.
+
+**Option 2 — force-kill (destructive):**
+- **Windows PowerShell:** `Get-NetTCPConnection -LocalPort <port> -ErrorAction SilentlyContinue | ForEach-Object { try { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue } catch { } }`
+- **POSIX:** `lsof -ti:<port> 2>/dev/null | xargs -r kill -9`
+
+Re-verify the port is free before continuing.

package/plugin/skills/muggle-test-prepare/steps/env-file.md

@@ -0,0 +1,18 @@
+# Environment file sanity
+
+The env file is **per-repo** — don't hardcode `.env.local`. Detect by scanning `package.json` `scripts/*` for `.env*` literals and known port vars (`PORT=`, `VITE_PORT=`); check framework config (`next.config.*`, `vite.config.*`).
+
+When a dependency on an env file exists:
+
+1. Check `<cwd>/<envfile>` exists — if yes, no-op.
+2. If absent, `git worktree list --porcelain` and check each sibling for the same filename.
+3. If found:
+
+   > "`<envfile>` is missing in this worktree but exists at `<sibling>/<envfile>`. Copy it before starting services?"
+
+   - Option 1: "Yes — copy from `<sibling>`"
+   - Option 2: "No — I'll provide it another way"
+
+4. If not found anywhere, report and ask.
+
+Skip silently when no env file is referenced.

package/plugin/skills/muggle-test-prepare/steps/fresh-install.md

@@ -0,0 +1,20 @@
+# Fresh install (clean-start default)
+
+Detect stack by indicator file, decide if install is missing/stale, run automatically (notify, don't ask). Only opt-out is aborting the skill.
+
+| Indicator | Stack | Stale check | Install command |
+|:----------|:------|:------------|:----------------|
+| `package.json` | Node | `node_modules/` missing OR `package-lock.json` newer than `node_modules/.package-lock.json` | `npm install --prefer-offline --no-audit --no-fund` |
+| `pyproject.toml` w/ `[tool.poetry]` | Poetry | `poetry.lock` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `poetry install --no-interaction` |
+| `pyproject.toml` (PEP 621) + `uv.lock` | uv | `uv.lock` newer than `.venv/pyvenv.cfg` | `uv sync` |
+| `requirements.txt` | pip | `requirements.txt` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `pip install -r requirements.txt` |
+| `Gemfile` | Bundler | `Gemfile.lock` newer than `vendor/bundle/` mtime | `bundle install` |
+| `composer.json` | Composer | `composer.lock` newer than `vendor/autoload.php` | `composer install --no-interaction` |
+| `pom.xml` | Maven | always (heavy — opt-in via `AskUserQuestion`) | `mvn -DskipTests install` |
+| `build.gradle*` | Gradle | always (heavy — opt-in via `AskUserQuestion`) | `gradle build -x test` |
+| `go.mod` | Go | skip — `go run`/`go build` handle deps |  |
+| `Cargo.toml` | Rust | skip — `cargo run`/`cargo build` handle deps |  |
+
+Notify one-liner: `Installing <service-name> (<stack>: <missing|stale>)…`.
+
+**Never symlink dep dirs** (`node_modules/`, `.venv/`, `vendor/bundle/`) from a sibling worktree — webpack rewrites paths via `resolve.symlinks: true` and Python/Ruby tooling has analogous issues. Run a real per-worktree install.

package/plugin/skills/muggle-test-prepare/steps/identify-services.md

@@ -0,0 +1,28 @@
+# Identify required services & startup mode
+
+List folder names in the **parent directory** of the current working directory:
+
+```bash
+ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}
+```
+
+Present folder names only (not contents). `AskUserQuestion` with `multiSelect: true`:
+
+> "Which of these need to be running for your tests?"
+
+Pre-check the ones matching the testing scope from [scope](./scope.md). Always include:
+- "Just the current project (no other services needed)"
+- "None of these — I'll tell you what I need"
+
+Include the current working directory as a candidate. If the user provides manual paths, verify they exist.
+
+**Immediately after selection**, ask startup mode:
+
+> "How do you want to handle these?"
+
+- Option 1: "Check what's running, start what's missing for me"
+- Option 2: "I'll start them myself — just verify they're up when I'm done"
+
+**Option 2**: skip [start-commands](./start-commands.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md). Wait for ready signal, then [check-running](./check-running.md), run [smoke-test](./smoke-test.md) against everything (the user-started case is exactly where the smoke test matters most), then [readiness-report](./readiness-report.md).
+
+**Option 1**: proceed through the normal flow.

package/plugin/skills/muggle-test-prepare/steps/readiness-report.md

@@ -0,0 +1,26 @@
+# Final readiness report
+
+Only after every service passes [smoke-test](./smoke-test.md) or is skipped.
+
+```
+Service              PID      Port     Status         Smoke Test
+─────────────────────────────────────────────────────────────────
+backend-api          12345    3001     Running        ✓
+auth-service         12346    8080     Running        ✓
+frontend             12347    3000     Running        ✓
+─────────────────────────────────────────────────────────────────
+All services verified. Ready for E2E.
+```
+
+Surface skipped services so the caller knows the gap:
+
+```
+Skipped: payment-gateway — HTTP 500 on /
+```
+
+If you launched the services:
+
+```
+Logs: /tmp/muggle-prepare-*.log
+Cleanup: say "stop services" or re-invoke this skill.
+```

package/plugin/skills/muggle-test-prepare/steps/rebase-check.md

@@ -0,0 +1,3 @@
+# Rebase check
+
+Gated by `autoRebase`. Fire per [`../../_shared/rebase-before-e2e.md`](../../_shared/rebase-before-e2e.md) when `behind > 0`. Otherwise skip silently.

package/plugin/skills/muggle-test-prepare/steps/scope.md

@@ -0,0 +1,11 @@
+# Scope (what are you testing?)
+
+`AskUserQuestion`:
+
+> "What are you testing locally?"
+
+- Option 1: "A frontend feature — I need the UI and its backend dependencies running"
+- Option 2: "A backend API — I just need the API server running"
+- Option 3: "The full stack — everything needs to be up"
+
+Scopes the rest of the workflow. Record under `testing_scope` in the tracking file. Use it later to pre-check matching service candidates in [identify-services](./identify-services.md).

package/plugin/skills/muggle-test-prepare/steps/smoke-test.md

@@ -0,0 +1,26 @@
+# Comprehensive smoke test
+
+Runs for **every** service in the tracking file, including `external: true`. Port-listening is not proof a service works — a stale dev server binds and returns 200 with a webpack error overlay.
+
+All three probes must pass:
+
+1. **HTTP** — `GET <serviceUrl>`, 3 s timeout, accept `2xx`/`3xx` (one redirect).
+2. **Body sniff** — match response body against broken-build markers in [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) → "Body sniff patterns".
+3. **Log tail** — scan last 200 lines of `/tmp/muggle-prepare-<service-name>.log` for failure patterns after the latest ready signal. Skip for `external: true` (no log).
+
+Use the primitives in `dev-server-readiness.md`. Don't re-implement.
+
+## Diagnose-and-fix loop
+
+On failure, show the concrete signal (HTTP code, sniff hit, or log line) and `AskUserQuestion`:
+
+> "**<service-name>** isn't healthy: `<signal>`. How do you want to proceed?"
+
+- Option 1: **Clean restart** (Recommended) — kill + [fresh-install](./fresh-install.md) + [start-services](./start-services.md) + re-run this step
+- Option 2: **Restart only** — kill + start-services + re-run this step
+- Option 3: **I'll fix it manually** — pause; re-run on user signal
+- Option 4: **Skip** — append to `excluded_services` with reason, continue
+
+Loop per service until pass or skip. Cap at **3 iterations** — then force a manual-intervention pause.
+
+For `external: true`, only Options 3 and 4 apply.

package/plugin/skills/muggle-test-prepare/steps/start-commands.md

@@ -0,0 +1,29 @@
+# Determine start commands
+
+For each required service not already running, figure out how to start it. Read **only** the indicator file that exists.
+
+| Indicator | Stack | Default command | What to check |
+|:----------|:------|:----------------|:--------------|
+| `package.json` | Node.js | `npm run dev` | Read `scripts`: prefer `dev` > `start` > `serve` |
+| `Makefile` | Various | `make dev` | Existence; propose `make dev` or `make run` |
+| `Cargo.toml` | Rust | `cargo run` | Existence |
+| `go.mod` | Go | `go run .` | Existence |
+| `pyproject.toml` | Python | Check for framework | Read `[project.scripts]` or `[tool.poetry.scripts]` if present |
+| `requirements.txt` | Python | `python app.py` | Existence |
+| `docker-compose.yml` | Docker | `docker compose up` | Existence |
+
+If no indicator found, ask the user for the start command.
+
+Present all commands in a single summary:
+
+```
+Service              Directory                          Command
+────────────────────────────────────────────────────────────────
+backend-api          ~/Github/backend-api               npm run dev
+auth-service         ~/Github/auth-service              go run .
+frontend             ~/Github/frontend                  npm run dev
+────────────────────────────────────────────────────────────────
+```
+
+- Option 1: "Looks good, start them"
+- Option 2: "I need to edit some commands"

package/plugin/skills/muggle-test-prepare/steps/start-services.md

@@ -0,0 +1,21 @@
+# Start services
+
+For each service, launch in the background:
+
+```bash
+cd "<service-dir>" && nohup <command> > /tmp/muggle-prepare-<service-name>.log 2>&1 &
+echo $!
+```
+
+Capture the PID. Write all service entries to `/tmp/muggle-test-prepare.json`.
+
+**Startup verification** — confirm PID alive (`kill -0 <pid> 2>/dev/null`), then run the two-stage readiness probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) against the log. Cap log-tail at 60 s. Halt on whatever surfaces.
+
+If a PID dies immediately, show the last 20 log lines:
+
+> "**backend-api** exited right after starting. Here's the tail of its log:"
+
+- Option 1: "Skip it and continue with the others"
+- Option 2: "Let me fix it — I'll re-invoke later"
+
+**Port discovery** — if the port wasn't known upfront, re-scan listening ports after startup. Record in tracking file. If not found within ~10 s, mark port unknown.

package/plugin/skills/muggle-test-prepare/steps/viability-check.md

@@ -0,0 +1,21 @@
+# Viability check
+
+Some services can't run on a developer's machine by design — production secrets, HSMs, specific certificates, cloud-only infra. Don't waste time trying to start them.
+
+If the user volunteered this in their initial message, acknowledge and skip the question. Otherwise:
+
+> "Are there any services in your stack that **can't** run locally? (e.g., needs production secrets, specific certificates, or cloud-only infra)"
+
+- Option 1: "All my services can run locally"
+- Option 2: "Some can't — I'll tell you which"
+
+If option 2, collect names and exclude from discovery.
+
+If an excluded service is a hard dependency for the app under test, suggest remote testing:
+
+> "Since **payment-gateway** can't run locally, you might get better coverage by merging and running `/muggle-test` against your preview environment. Want to continue with a partial local setup, or switch to remote testing?"
+
+- Option 1: "Continue locally — I'll work around the missing service"
+- Option 2: "Switch to remote — I'll merge and test on preview"
+
+If remote, hand off to `/muggle-test` in remote mode and exit.