rn-iso 0.5.0 → 0.6.1

package/README.md

@@ -51,6 +51,7 @@ All commands below take the same `npx rn-iso` prefix.
 | `start` | Start Metro detached, no platform action |
 | `stop [<port>\|<shortcut>\|<path>]` | Kill Metro. No arg = current project; pass a port (e.g. 8083), a project shortcut (label or unique basename), or an absolute path. |
 | `logs [<port>\|<shortcut>\|<path>] [-n <lines>] [--follow]` | Print the managed Metro log (bundle progress, resolution errors, client logs). |
+| `prune` | Remove entries for deleted project directories, freeing their devices and ports. |
 | `device [--platform ios\|android] [--json]` | Print the assigned device target |
 | `status` | Show all projects' state |
 | `reserve [ios\|android]` | Lock a manually-started sim/emulator to the current project (no build) |

package/bin/cli.js

@@ -7,6 +7,7 @@ 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 pruneCommand from '../src/commands/prune.js';
 import statusCommand from '../src/commands/status.js';
 import releaseCommand from '../src/commands/release.js';
 import reserveCommand from '../src/commands/reserve.js';
@@ -28,6 +29,7 @@ androidCommand(program);
 startCommand(program);
 stopCommand(program);
 logsCommand(program);
+pruneCommand(program);
 statusCommand(program);
 releaseCommand(program);
 reserveCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-iso",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Isolated React Native dev environments per project/worktree",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -77,7 +77,7 @@ Reserve binds the sim to the current project the same way `ios` does, but skips
 ## When things go wrong
 
 - **"No rn-iso assignment for project"** — run `npx rn-iso ios` (or android) first.
-- **"All iOS simulators are claimed by other rn-iso projects"** (under `--auto`) — every existing sim is held by another project. Options: free another project (`npx rn-iso release` from there), pass `--device-type "iPhone 17 Pro"` to create a new sim, or re-run without `--auto` (in a real TTY) and ask the user before confirming the take-over prompt.
+- **"All iOS simulators are claimed by other rn-iso projects"** (under `--auto`) — every existing sim is held by another project. Claims from deleted worktrees don't count (they're auto-reclaimed), so these are all live projects. Options: `npx rn-iso prune` if you suspect stale state, free another project (`npx rn-iso release` from there), pass `--device-type "iPhone 17 Pro"` to create a new sim, or re-run without `--auto` (in a real TTY) and ask the user before confirming the take-over prompt.
 - **"All Android AVDs are claimed by other rn-iso projects"** — same situation on Android. Free another project or re-run interactively to take one over.
 - **Wrong sim got the app** — older `@expo/cli` (< 54.0.24) had a bug where the launch ignored `--device`. Bump expo to 54.0.34+ if on SDK 54.
 - **Blank screen / app installed but nothing renders** — check `npx rn-iso status`. Metro `stopped` almost always means the build ran WITHOUT `--managed-metro`, so Metro died with the shell that ran it: recover with `npx rn-iso start`, then relaunch the app (`xcrun simctl launch <UDID> <bundleId>`), and pass the flag next time. If Metro IS running, read `npx rn-iso logs -n 50` for bundle/resolution errors (a stale `node_modules` after a branch switch is a classic — reinstall deps, then `npx rn-iso stop` + `start`).
@@ -89,6 +89,7 @@ Reserve binds the sim to the current project the same way `ios` does, but skips
 
 - `npx rn-iso status` — show all projects, their assignments, and Metro state.
 - `npx rn-iso logs [<port>|<shortcut>|<path>] [-n <lines>] [--follow]` — print the managed Metro log (default: last 50 lines of the current project's). This is where bundle progress, module-resolution errors, and client console logs land. **Check this first on a blank screen or red box** — it's faster than screenshots.
+- `npx rn-iso prune` — remove entries for projects whose directory no longer exists (deleted worktrees), freeing their sims/emulators and ports, and killing any orphaned Metro. Live projects are never touched. Claims from deleted worktrees are also ignored automatically during device selection, so prune is housekeeping, not a prerequisite.
 - `npx rn-iso start [--reset-cache] [-- <extras...>]` — start Metro detached on the project's assigned port WITHOUT building/installing. `--reset-cache` clears Metro's transform cache. Other extras after `--` are forwarded to `expo start` / `react-native start`.
 - `npx rn-iso stop [<port>|<shortcut>|<path>]` — kill Metro. No arg = current project. Passing a port (e.g. `8083`) kills whatever is on it; a project shortcut (label or unique basename) or absolute path targets that project. Finds the process by port, so it works whether Metro was started by `npx rn-iso start` or by the build CLI.
 - `npx rn-iso release [<port>|<shortcut>|<path>] [--platform <p>] [--shutdown]` — free a project's sim assignment. Defaults to the current project. Target can also be a Metro port (`8083`) or a shortcut (label / unique basename). `--shutdown` also stops the sim/emulator.

package/src/commands/android.js

@@ -60,10 +60,11 @@ export default function androidCommand(program) {
       }
       // With --managed-metro, rn-iso owns Metro: detached so it survives the
       // invoking shell (agents run builds from finite shells), output to the
-      // per-project log file, and the build CLI gets --no-packager /
-      // --no-bundler so it cannot start a second Metro on the same port.
-      // Without the flag, the build CLI owns Metro as usual (interactive
-      // bundler UX for humans).
+      // per-project log file. The build CLI is then kept from starting its own:
+      // bare RN gets --no-packager; expo gets --port and reuses the Metro
+      // already listening on that port. ensureMetro waits for /status so the
+      // port is bound before the build's reuse check runs. Without the flag,
+      // the build CLI owns Metro as usual (interactive bundler UX for humans).
       if (opts.managedMetro) {
         const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
         if (metro.alreadyRunning) {
@@ -72,6 +73,9 @@ export default function androidCommand(program) {
           setMetro(root, proj.metroPort, metro.pid);
           console.log(chalk.dim(`Metro started detached (pid ${metro.pid}, port ${proj.metroPort})`));
           console.log(chalk.dim(`Metro log: ${logFileFor(root)}`));
+          if (!metro.ready) {
+            console.log(chalk.yellow(`Warning: Metro on port ${proj.metroPort} did not report ready; the build may start its own.`));
+          }
         }
       } else {
         const metroAlreadyUp = await isMetroRunning(proj.metroPort);

package/src/commands/ios.js

@@ -56,10 +56,11 @@ export default function iosCommand(program) {
       }
       // With --managed-metro, rn-iso owns Metro: detached so it survives the
       // invoking shell (agents run builds from finite shells), output to the
-      // per-project log file, and the build CLI gets --no-packager /
-      // --no-bundler so it cannot start a second Metro on the same port.
-      // Without the flag, the build CLI owns Metro as usual (interactive
-      // bundler UX for humans).
+      // per-project log file. The build CLI is then kept from starting its own:
+      // bare RN gets --no-packager; expo gets --port and reuses the Metro
+      // already listening on that port. ensureMetro waits for /status so the
+      // port is bound before the build's reuse check runs. Without the flag,
+      // the build CLI owns Metro as usual (interactive bundler UX for humans).
       if (opts.managedMetro) {
         const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
         if (metro.alreadyRunning) {
@@ -68,6 +69,9 @@ export default function iosCommand(program) {
           setMetro(root, proj.metroPort, metro.pid);
           console.log(chalk.dim(`Metro started detached (pid ${metro.pid}, port ${proj.metroPort})`));
           console.log(chalk.dim(`Metro log: ${logFileFor(root)}`));
+          if (!metro.ready) {
+            console.log(chalk.yellow(`Warning: Metro on port ${proj.metroPort} did not report ready; the build may start its own.`));
+          }
         }
       } else {
         const metroAlreadyUp = await isMetroRunning(proj.metroPort);

package/src/commands/prune.js

@@ -0,0 +1,44 @@
+// src/commands/prune.js
+import chalk from 'chalk';
+import { pruneDeadProjects } from '../config.js';
+import { findPidListeningOnPort } from '../metro.js';
+
+export default function pruneCommand(program) {
+  program
+    .command('prune')
+    .description('Remove entries for projects whose directory no longer exists (deleted worktrees), freeing their sims/emulators and Metro ports. Live projects are never touched.')
+    .action(() => {
+      const removed = pruneDeadProjects();
+      if (removed.length === 0) {
+        console.log(chalk.dim('Nothing to prune: every registered project path still exists.'));
+        return;
+      }
+
+      for (const { path, project } of removed) {
+        const freed = [];
+        const ios = project.platforms?.ios;
+        if (ios?.deviceUdid) freed.push(`ios sim ${ios.deviceUdid}`);
+        const android = project.platforms?.android;
+        if (android?.avdName) freed.push(`android avd ${android.avdName}`);
+        else if (android?.serial) freed.push(`android device ${android.serial}`);
+
+        console.log(chalk.green(`Pruned ${path}`));
+        if (freed.length) console.log(chalk.dim(`  freed: ${freed.join(', ')}`));
+
+        // A Metro started from the deleted directory can outlive it and squat
+        // on the port; kill it so the port is genuinely free.
+        if (typeof project.metroPort === 'number') {
+          const pid = findPidListeningOnPort(project.metroPort);
+          if (pid) {
+            try {
+              process.kill(pid, 'SIGTERM');
+              console.log(chalk.dim(`  killed orphaned Metro pid ${pid} on port ${project.metroPort}`));
+            } catch {
+              console.log(chalk.dim(`  could not kill pid ${pid} on port ${project.metroPort}`));
+            }
+          }
+        }
+      }
+      console.log(chalk.dim(`\n${removed.length} project entr${removed.length === 1 ? 'y' : 'ies'} removed.`));
+    });
+}

package/src/config.js

@@ -187,6 +187,10 @@ export function allClaimedDevices() {
   };
   if (!cfg) return result;
   for (const [path, proj] of Object.entries(cfg.projects || {})) {
+    // Claims from project paths that no longer exist on disk are orphaned --
+    // nothing can ever run from a deleted worktree again -- so pickers treat
+    // those devices as free. `prune` removes the dead entries themselves.
+    if (!existsSync(path)) continue;
     const label = path.split('/').pop() || path;
     const ios = proj.platforms?.ios;
     if (ios?.deviceUdid) {
@@ -218,6 +222,22 @@ export function allClaimedDevices() {
   return result;
 }
 
+// Remove project entries whose path no longer exists on disk (deleted
+// worktrees). Returns the removed entries so callers can report what was
+// freed and clean up any process still bound to their Metro ports.
+export function pruneDeadProjects() {
+  const cfg = loadConfig();
+  if (!cfg?.projects) return [];
+  const removed = [];
+  for (const [path, proj] of Object.entries(cfg.projects)) {
+    if (existsSync(path)) continue;
+    removed.push({ path, project: proj });
+    delete cfg.projects[path];
+  }
+  if (removed.length) saveConfig(cfg);
+  return removed;
+}
+
 export function recordSimUsage(platform, identifier) {
   if (platform !== 'ios' && platform !== 'android') return;
   const cfg = ensureConfig();

package/src/metro.js

@@ -25,8 +25,8 @@ export function buildMetroSpawnArgs({ isExpo, port, extras = [] }) {
   };
 }
 
-export async function ensureMetro({ projectPath, isExpo, port, extras = [], detach = true }) {
-  if (await isMetroRunning(port)) return { alreadyRunning: true, pid: null };
+export async function ensureMetro({ projectPath, isExpo, port, extras = [], detach = true, readyTimeoutMs = 30000 }) {
+  if (await isMetroRunning(port)) return { alreadyRunning: true, pid: null, ready: true };
 
   const log = logFileFor(projectPath);
   const fd = openSync(log, 'a');
@@ -40,7 +40,22 @@ export async function ensureMetro({ projectPath, isExpo, port, extras = [], deta
     env: { ...process.env, RCT_METRO_PORT: String(port) },
   });
   if (detach) child.unref();
-  return { alreadyRunning: false, pid: child.pid };
+
+  // Wait until the dev server answers /status. The build CLI's "a Metro is
+  // already on this port, reuse it" detection only fires once the port is
+  // bound, so returning before that races the build into spawning a second
+  // Metro. readyTimeoutMs <= 0 skips the wait.
+  const ready = readyTimeoutMs > 0 ? await waitForMetroReady(port, readyTimeoutMs) : false;
+  return { alreadyRunning: false, pid: child.pid, ready };
+}
+
+export async function waitForMetroReady(port, timeoutMs = 30000, intervalMs = 500) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isMetroRunning(port)) return true;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  return false;
 }
 
 export function killMetroByPid(pid) {

package/src/ports.js

@@ -1,4 +1,5 @@
 import { request } from 'http';
+import { existsSync } from 'fs';
 import { loadConfig, allMetroPorts, removeProject } from './config.js';
 
 export function isMetroRunning(port) {
@@ -29,6 +30,10 @@ export async function findReclaimablePort(excludeProjectPath, probe = isMetroRun
   const candidates = [];
   for (const [path, proj] of Object.entries(cfg.projects)) {
     if (path === excludeProjectPath) continue;
+    // Only projects whose path no longer exists are reclaimable: reclaiming
+    // removes the whole entry, and doing that to a live project would also
+    // drop its device claim out from under it.
+    if (existsSync(path)) continue;
     if (typeof proj.metroPort === 'number') {
       candidates.push({ port: proj.metroPort, ownerPath: path });
     }

package/src/runner.js

@@ -76,11 +76,17 @@ export function detectScriptCli(scriptBody) {
   return 'unknown';
 }
 
-// Flag that stops the build CLI from spawning its own packager. rn-iso owns
-// Metro (detached, log file, pid tracked), so the build must not start a
-// second one on the same port.
-function skipPackagerFlag(cli) {
-  return cli === 'expo' ? '--no-bundler' : '--no-packager';
+// Flags that stop the build CLI from spawning its own packager when rn-iso owns
+// Metro (detached, log file, pid tracked). Bare RN takes --no-packager. Expo
+// gets NO flag: `expo run` rejects --port together with --no-bundler, and
+// --no-bundler also pins the dev server to 8081 with no override. Instead we
+// pass --port <managed port> and rely on `expo run` detecting the Metro already
+// listening on that port and reusing it (reuseExistingPort) rather than
+// spawning its own. Callers must have the managed Metro listening before the
+// build runs (ensureMetro waits for /status).
+function noPackagerFlags(cli, noPackager) {
+  if (!noPackager) return [];
+  return cli === 'expo' ? [] : ['--no-packager'];
 }
 
 // iOS run command. Prefers the project's `ios` script if present (the most
@@ -99,15 +105,14 @@ export function buildIosCommand({ projectRoot, packageManager, scriptName, isExp
       return buildScriptCommand(packageManager, scriptName, [
         deviceFlag,
         `--port ${port}`,
-        ...(noPackager ? [skipPackagerFlag(cli)] : []),
+        ...noPackagerFlags(cli, noPackager),
         ...tail,
       ]);
     }
   }
   const tailStr = tail.length ? ' ' + tail.join(' ') : '';
   if (isExpo) {
-    const skip = noPackager ? ' --no-bundler' : '';
-    return `npx expo run:ios --device ${udid} --port ${port}${skip}${tailStr}`;
+    return `npx expo run:ios --device ${udid} --port ${port}${tailStr}`;
   }
   const skip = noPackager ? ' --no-packager' : '';
   return `npx react-native run-ios --udid ${udid} --port ${port}${skip}${tailStr}`;
@@ -128,15 +133,14 @@ export function buildAndroidCommand({ projectRoot, packageManager, scriptName, i
       return buildScriptCommand(packageManager, scriptName, [
         deviceFlag,
         `--port ${port}`,
-        ...(noPackager ? [skipPackagerFlag(cli)] : []),
+        ...noPackagerFlags(cli, noPackager),
         ...tail,
       ]);
     }
   }
   const tailStr = tail.length ? ' ' + tail.join(' ') : '';
   if (isExpo) {
-    const skip = noPackager ? ' --no-bundler' : '';
-    return `npx expo run:android --device "${expoDeviceArg}" --port ${port}${skip}${tailStr}`;
+    return `npx expo run:android --device "${expoDeviceArg}" --port ${port}${tailStr}`;
   }
   const skip = noPackager ? ' --no-packager' : '';
   return `RCT_METRO_PORT=${port} npx react-native run-android --device ${serial}${skip}${tailStr}`;