rn-iso 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/janicduplessis/Developer/rn-iso remote -v)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,178 @@
+# rn-iso — agent guide
+
+Quick orientation for AI assistants working in this repo.
+
+## What this is
+
+A Node.js CLI that gives each React Native / Expo project (or git worktree)
+its own Metro server and dedicated simulator/emulator, so multiple agents can
+work on different projects in parallel without device or port collisions.
+
+State lives in `~/.rn-iso/config.json`, keyed by absolute project path. The
+`RN_ISO_HOME` env var redirects this for tests.
+
+## Architecture conventions
+
+- **ESM only.** `"type": "module"`, no transpiler, Node 20+ directly. No
+  CommonJS, no `require()`.
+- **Single exec wrapper.** All `child_process` calls go through
+  `src/exec.js` (`getExecutor()`). Tests inject a mock via `setExecutor()`.
+  Anywhere outside `exec.js` that imports `child_process` directly is a bug.
+- **Pure parsing separate from invocation.** Functions like `parseSimctlList`,
+  `parseAdbDevices`, `selectIosDevice`, `sortSims` are pure and unit-tested;
+  the I/O wrappers around them are thin.
+- **ASCII in source files.** No em dashes, smart quotes, or check marks in
+  `src/`, `bin/`, `test/`. Markdown files (README, SKILL, this file) may use
+  them. The hooks have flagged this before.
+
+## File layout
+
+```
+bin/cli.js              # commander entry, registers each command module
+src/
+  exec.js               # mockable child_process wrapper
+  config.js             # config CRUD, reservations, sim-usage tracking
+  project.js            # project root walk, bundle-id detection (incl. native fallbacks)
+  ports.js              # Metro port allocation + reclamation
+  runner.js             # script-vs-CLI dispatch, package-manager detection (walks up for monorepos)
+  metro.js              # detached Metro spawn, PID + log lifecycle
+  sim/
+    ios.js              # simctl wrappers, sim selection, sortSims, parseRuntimeVersion
+    android.js          # adb/emulator wrappers, AVD selection
+  commands/
+    ios.js android.js   # the main user-facing commands
+    start.js stop.js logs.js
+    status.js
+    device.js           # `rn-iso device --json` -> agent-device target
+    release.js shutdown.js prune.js
+    reserve.js unreserve.js
+test/
+  *.test.js             # `node --test` (no framework)
+skill/SKILL.md          # the agent-facing skill
+```
+
+## Particularities to remember
+
+### 1. Update `skill/SKILL.md` whenever user-facing behavior changes
+
+The skill is what installed AI agents read to learn how to use the CLI. When
+you add a command, change a flag, change picker UX, or alter defaults — open
+`skill/SKILL.md` and update the relevant section in the same change. Quick
+checklist:
+
+- New command? Add it under "Other useful commands" or its own section if
+  meaty (like `reserve`).
+- New / changed flag on `ios` or `android`? Update "Core workflow" and
+  "Critical rules" if the flag matters for non-interactive agent use.
+- Behavior change (e.g., picker now does X)? Update both the
+  description and the "When things go wrong" section.
+
+The skill is shipped to users via the curl line in the README; staleness
+breaks agent guidance.
+
+### 2. Don't auto-create simulators
+
+`selectIosDevice` returns `needsBoot` only when no unclaimed sim exists at
+all. `commands/ios.js` then errors unless `--device-type` is passed. We do
+NOT prompt and create on the user's behalf — that was the original UX and
+was removed because it accumulated junk sims. The picker only chooses among
+EXISTING sims (booted or shutdown). When you change device-selection logic,
+preserve this invariant.
+
+### 3. The post-install verification step is intentionally absent
+
+Earlier versions ran `xcrun simctl install/launch` after the build CLI to
+work around a wrong-sim bug in `@expo/cli` (since fixed in 54.0.24). That
+step caused double-launches and was removed. If you find yourself wanting
+to add it back, the upstream bug is the right place to fix things —
+`patch-package` for stuck users, not workaround code in `commands/ios.js`.
+
+### 3b. `rn-iso ios` / `android` do NOT spawn Metro
+
+The build CLI (`expo run:ios` / `react-native run-ios`) starts Metro
+itself on the `--port` we pass. We used to also pre-spawn a detached
+Metro before the build, which led to two Metros on the same port.
+Removed.
+
+`rn-iso start` is still around for the explicit "I just want Metro" case
+— it spawns Metro detached and tracks the PID + log file. The build
+commands rely on the build CLI's Metro; `rn-iso stop` looks up the PID
+by port (via `lsof`) so it works regardless of who started Metro.
+
+### 4. Reservations are first-class claims
+
+`allClaimedDevices()` returns BOTH project-claimed AND reservation-claimed
+devices. If you add a new claim source (e.g., a new section in config.json),
+extend `allClaimedDevices` AND `iosClaims` so the picker greys it out with a
+useful label. Don't filter at any one call site — keep the policy in
+`config.js`.
+
+### 5. Package-manager / script detection
+
+`runner.js` prefers the project's `ios` / `android` script over a direct
+`expo run:ios` / `react-native run-ios` invocation. Reasons: respects user
+flags, picks the right CLI, works with non-standard setups (rainbow has
+`expo` in deps but uses `react-native run-ios`).
+
+`detectScriptCli` regex-matches the script body to decide flag names
+(`--device <UDID>` for Expo, `--udid <UDID>` for RN). If you ever need a
+new flag, update both the script-path branch and the direct fallback.
+
+`detectPackageManager` walks up from the project root looking for a
+lockfile (monorepo support). Don't single-directory-check.
+
+### 6. `RN_ISO_HOME` is the test redirect
+
+All config + log paths derive from `getConfigDir()`, which respects
+`RN_ISO_HOME`. Every config-touching test does:
+
+```js
+beforeEach(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), 'rn-iso-test-'));
+  process.env.RN_ISO_HOME = tmpHome;
+});
+afterEach(() => {
+  rmSync(tmpHome, { recursive: true, force: true });
+  delete process.env.RN_ISO_HOME;
+});
+```
+
+If you add new state-touching code, follow this pattern.
+
+### 7. `findProjectRoot` uses `realpath`
+
+So symlinked worktrees collapse to the same canonical key as the
+non-symlinked path. Don't add code that compares paths without
+canonicalizing first.
+
+## Local development
+
+```bash
+npm install         # one-time
+npm test            # node --test test/*.test.js
+npm link            # symlink rn-iso onto your PATH for live testing
+```
+
+After `npm link`, edits to `src/` are picked up immediately by the linked
+`rn-iso` command.
+
+## Commit conventions
+
+- GPG signing is enabled globally — commits sign automatically. Don't pass
+  `--no-gpg-sign`. If you need to re-sign an existing commit (e.g.,
+  someone forgot signing), `git commit --amend --no-edit -S` works.
+- Conventional-style prefixes are used (`feat:`, `fix:`, `docs:`,
+  `chore:`, `revert:`). Keep titles under ~70 chars; details in the body.
+- One commit per logical change. The post-install removal and the
+  script-based runner came in as separate commits even though they shipped
+  in the same session.
+
+## Things explicitly out of scope (for now)
+
+- Locking / mutex around device usage. The whole premise is dedicated sims.
+- Auto-shutdown of sims after N hours of inactivity.
+- Cross-platform support beyond macOS (iOS) + macOS/Linux (Android).
+- Multi-app projects (one repo, multiple Expo apps via `--variant`).
+- A daemon or TUI dashboard.
+
+If a request edges into these, raise it instead of building it.

package/README.md

@@ -0,0 +1,90 @@
+# rn-iso
+
+Per-project Metro server and dedicated simulator/emulator for React Native / Expo, so multiple worktrees (or coding agents) can build the same app in parallel without port or device collisions.
+
+> **Experimental.** APIs, flags, and on-disk state may change. File issues if anything breaks.
+
+State lives in `~/.rn-iso/config.json`, keyed by absolute project path. Worktrees count as separate projects. There is no shared mutex — each project is pinned to its own port and its own sim.
+
+## Install
+
+```bash
+npm install -g rn-iso
+```
+
+To install the agent skill (so AI coding agents know how to drive the CLI):
+
+```bash
+npx skills add janicduplessis/rn-iso
+```
+
+## Quick start
+
+In any RN/Expo project directory:
+
+```bash
+rn-iso ios       # ensure sim, allocate port, build/install
+rn-iso device    # print the assigned UDID
+```
+
+In a different worktree of the same app:
+
+```bash
+rn-iso ios       # gets a different sim and Metro port
+```
+
+Both run side by side. For non-interactive / agent use, pass `--auto` to skip the picker:
+
+```bash
+rn-iso ios --auto
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `rn-iso ios [--auto] [--device-type <name>] [--runtime <ver>] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Ensure iOS sim + Metro + build/install |
+| `rn-iso android [--auto] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Same for Android |
+| `rn-iso start` | Start Metro detached, no platform action |
+| `rn-iso device [--platform ios\|android] [--json]` | Print the assigned device target |
+| `rn-iso status` | Show all projects' state and reservations |
+| `rn-iso reserve [<platform> <id>] [--label <name>] [--list]` | Mark an external sim/emulator as in-use so rn-iso skips it |
+| `rn-iso unreserve [<id\|label>] [--all]` | Release a reservation |
+| `rn-iso release [<project\|label\|udid>] [--platform <p>]` | Unbind a project assignment or reservation |
+| `rn-iso shutdown [--platform <p>]` | Release and shut down sims for current project |
+| `rn-iso prune [--shutdown]` | GC dead entries machine-wide |
+| `rn-iso logs` | Tail Metro log for current project |
+| `rn-iso stop` | Kill Metro for current project |
+
+## How it works
+
+- **Config** at `~/.rn-iso/config.json`, keyed by absolute project path. Symlinked worktrees collapse via `realpath`.
+- **Port allocation:** assigns 8082, 8083, 8084 etc., reclaiming dead ports on the way.
+- **Simulator pool:** prefers the project's existing assignment; otherwise picks any unclaimed booted sim, then any unclaimed shutdown sim (booting it). Does not auto-create new sims — pass `--device-type "iPhone 17 Pro" [--runtime 26.2]` to opt in.
+- **Build via your project's `ios` / `android` script** when present. Falls back to `npx expo run:ios` / `npx react-native run-ios --udid <UDID>` when no script exists. Override with `--script <name>` or skip with `--no-script`. Package manager is detected from your lockfile (walks up for monorepos); override with `--pm <npm|yarn|pnpm|bun>`.
+- **Metro is started by the build CLI** on the assigned port, not by rn-iso. `rn-iso start` is the standalone "I just want Metro" path. `rn-iso stop` finds Metro by port via `lsof`, so it works regardless of who started it.
+
+If you need a single shared sim with a mutex instead of one-per-project, see [`react-native-worktree`](https://github.com/aleqsio/react-native-worktree).
+
+## Reservations
+
+If you boot a sim outside rn-iso (Xcode, manual `simctl boot`, another tool), reserve it so rn-iso's allocator skips it:
+
+```bash
+rn-iso reserve ios <UDID> --label agent-1
+rn-iso reserve                # interactive multi-select picker
+rn-iso unreserve agent-1      # release by label, UDID, or serial
+```
+
+Reserved sims appear greyed-out as `[reserved]` in the picker.
+
+## Requirements
+
+- macOS (iOS); macOS or Linux (Android)
+- Node 20+
+- Xcode (iOS), Android SDK + at least one AVD (Android)
+- `expo` or `react-native` in the project's `package.json`
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import deviceCommand from '../src/commands/device.js';
+import iosCommand from '../src/commands/ios.js';
+import androidCommand from '../src/commands/android.js';
+import startCommand from '../src/commands/start.js';
+import stopCommand from '../src/commands/stop.js';
+import logsCommand from '../src/commands/logs.js';
+import statusCommand from '../src/commands/status.js';
+import releaseCommand from '../src/commands/release.js';
+import shutdownCommand from '../src/commands/shutdown.js';
+import pruneCommand from '../src/commands/prune.js';
+import reserveCommand from '../src/commands/reserve.js';
+import unreserveCommand from '../src/commands/unreserve.js';
+
+const program = new Command();
+program
+  .name('rn-iso')
+  .description('Isolated React Native dev environments per project/worktree')
+  .version('0.1.0');
+
+deviceCommand(program);
+iosCommand(program);
+androidCommand(program);
+startCommand(program);
+stopCommand(program);
+logsCommand(program);
+statusCommand(program);
+releaseCommand(program);
+shutdownCommand(program);
+pruneCommand(program);
+reserveCommand(program);
+unreserveCommand(program);
+
+program.parse();