maestro-manager 0.0.0 → 0.0.1

package/README.md

@@ -1 +1,178 @@
-# maestro-manager
+# Maestro Manager
+
+Daemonless iOS Maestro test runner with a shared simulator pool. The CLI creates
+named simulator slots, leases them to concurrent test runs, and records run
+state under the current pool prefix.
+
+## Prerequisites
+
+- macOS with Xcode command line tools and simulator support available through
+  `xcrun simctl`.
+- Bun `>=1.3.14` and Node.js `>=24.16.0`.
+- Maestro installed on `PATH` as `maestro`.
+- A built iOS `.app` bundle and Maestro flow YAML files.
+
+Install dependencies:
+
+```sh
+bun install
+```
+
+## Configuration
+
+Create `maestro-manager.config.json` at the repo root, pass it with
+`--config <path>`, or set `MAESTRO_MANAGER_CONFIG=<path>`. Without either
+override, the CLI walks up from the current directory until it finds the config.
+
+Minimal shape:
+
+```json
+{
+  "pool": {
+    "prefix": "my-project-e2e",
+    "deviceType": "iPhone 16",
+    "default": 2,
+    "max": 4
+  },
+  "app": {
+    "appId": "com.example.MyApp",
+    "glob": "~/Library/Developer/Xcode/DerivedData/*/Build/Products/*-iphonesimulator/*.app",
+    "searchDirs": ["~/Library/Developer/Xcode/DerivedData"]
+  },
+  "flowsDir": "maestro/flows",
+  "warmupDeepLink": "myapp://e2e/warmup",
+  "java": {
+    "home": null,
+    "autodetect": ["JAVA_HOME", "mise", "/usr/libexec/java_home"]
+  },
+  "recordingsDir": "recordings",
+  "hooks": {
+    "pruneAccounts": ""
+  }
+}
+```
+
+Notes:
+
+- `pool.prefix` becomes part of simulator names and the state path. Keep it
+  project-specific and safe: start with a letter or number, then use only
+  letters, numbers, dots, underscores, and hyphens.
+- `pool.default` is the normal warm pool size. `pool.max` is the hard concurrency
+  cap and must be `<= 8`. Keep `pool.max <= 4` until the downstream project has
+  proved its backend is stable at the higher concurrency.
+- `flowsDir`, `recordingsDir`, and entries in `app.searchDirs` resolve relative
+  to the config file directory, with `~` expanded.
+- App resolution order is `--app`, then `app.path`, then `app.glob`, then
+  scanning `app.searchDirs` for the newest `.app` matching `app.appId`.
+  `app.glob` supports `*` and `?` within path segments and `~` expansion.
+- `hooks.pruneAccounts` is an optional shell command run by
+  `clean --prune-accounts`.
+
+## Common Workflows
+
+Warm the default simulator pool:
+
+```sh
+maestro-manager up --app path/to/MyApp.app
+```
+
+By default, simulators boot headless: Maestro can run against them without
+opening Simulator.app. Use `--headed` when you want to watch the pool or a run:
+
+```sh
+maestro-manager up --headed --app path/to/MyApp.app
+maestro-manager test --headed --sims 2
+```
+
+`--headless` is also accepted explicitly and conflicts with `--headed`.
+
+Show pool slots, active leases, and recent runs:
+
+```sh
+maestro-manager status
+```
+
+Run all configured flows on two simulators:
+
+```sh
+maestro-manager test --sims 2
+```
+
+Stop this worktree's active leases but keep the pool:
+
+```sh
+maestro-manager stop
+```
+
+Reclaim stale leases and shut down idle simulators:
+
+```sh
+maestro-manager clean --idle-shutdown 30
+```
+
+`clean` runs a stateless reaper, even with no flags:
+
+- **Reap orphaned runs.** When a `test` worker is `SIGKILL`ed or crashes, no signal
+  trap fires, so its detached `maestro` process group — and the simulator's (often
+  hung) app — keep running and burning CPU. The stale-lease reclaim deliberately
+  refuses to reclaim such a slot while its `maestro` child is still alive (so it
+  never yanks a simulator a live run is driving). `clean` detects this case — owner
+  dead, heartbeat stale, `maestro` still alive — kills the orphaned `maestro` group,
+  shuts the simulator down (killing the hung app), and reclaims the slot.
+- **Reclaim stale leases** whose owner and `maestro` child are both dead, shutting
+  those simulators down too.
+
+Live-leased simulators (a live owner) are never touched.
+
+Add `--delete-unavailable` to also run `xcrun simctl delete unavailable`, removing
+broken-runtime CoreSimulator devices left behind by Xcode upgrades, removed
+runtimes, or other tools. This is **global** — it is NOT scoped to this pool's
+prefix — so it is opt-in and off by default:
+
+```sh
+maestro-manager clean --idle-shutdown 30 --delete-unavailable
+```
+
+Stop all leases, delete pool simulators, and clear pool state:
+
+```sh
+maestro-manager down
+```
+
+`test` runs all `.yaml` and `.yml` files in `flowsDir` when no flow paths are
+provided. Use `--include-tags` and `--exclude-tags` for manager-side tag
+selection, and put Maestro passthrough arguments after a literal `--`.
+
+## State And Logs
+
+State is scoped by `pool.prefix` under:
+
+```text
+~/.maestro-manager/<prefix>
+```
+
+Important paths include:
+
+- `config-snapshot.json` for the last config snapshot written by `up`.
+- `sims/<sim-name>/udid`, `lastused`, and `lease/record.json` for pool slots and
+  lease ownership.
+- `waiters/<runId>/ticket.json` for queued work.
+- `runs/index.json`, `runs/<runId>/run.json`, and `runs/<runId>/<flow>.log` for
+  run history and per-flow Maestro output.
+
+`maestro-manager down` runs `stop --all`, deletes all pool simulators it can
+resolve, then removes `~/.maestro-manager/<prefix>`.
+
+## Verification
+
+Run the full local check:
+
+```sh
+bun run check
+```
+
+Run the no-excuse audit baseline check:
+
+```sh
+bash scripts/check-no-excuse-baseline.sh src
+```

package/dist/build-info.json

@@ -0,0 +1,3 @@
+{
+  "commit": "271e32e"
+}