rn-iso 0.4.0 → 0.4.1

package/README.md

@@ -27,6 +27,13 @@ Both run side by side. For non-interactive / agent use, pass `--auto` to skip th
 npx rn-iso ios --auto
 ```
 
+Forward extra flags to the underlying build command with `--`:
+
+```bash
+npx rn-iso ios -- --variant=release
+npx rn-iso android -- --mode=diaRelease --terminal=Ghostty
+```
+
 For AI coding agents, install the skill so the agent knows how to drive the CLI:
 
 ```bash
@@ -39,8 +46,8 @@ All commands below take the same `npx rn-iso` prefix.
 
 | Command | Purpose |
 |---|---|
-| `ios [--auto] [--device-type <name>] [--runtime <ver>] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Ensure iOS sim + Metro + build/install |
-| `android [--auto] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Same for Android |
+| `ios [--auto] [--device-type <name>] [--runtime <ver>] [--script <name>] [--pm <name>] [--no-script] [--no-install] [-- <extras...>]` | Ensure iOS sim + Metro + build/install. Extras after `--` are forwarded to the build command. |
+| `android [--auto] [--script <name>] [--pm <name>] [--no-script] [--no-install] [-- <extras...>]` | Same for Android. |
 | `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. |
 | `device [--platform ios\|android] [--json]` | Print the assigned device target |

package/package.json

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

package/skill/SKILL.md

@@ -30,6 +30,7 @@ From the project root (or any subdirectory):
 ## CRITICAL rules
 
 - **Pass `--auto` for non-interactive use** of `ios` or `android`. Without it, the command will prompt with an arrow-key picker if multiple unclaimed sims/AVDs exist. `--auto` is also implied automatically when stdin isn't a TTY (e.g., when an agent pipes the command), so under most agent harnesses you don't have to remember the flag — but passing it explicitly is harmless and clearer.
+- **Forward extra flags to the build CLI with `--`.** `npx rn-iso ios -- --variant=release` (or `android -- --mode=diaRelease`) appends those flags to the underlying `react-native run-*` / `expo run:*` invocation. Useful for release-mode builds, custom terminals, etc. Last-wins semantics, so extras can override defaults rn-iso set earlier in the command.
 - **`--auto` will NOT take over a claimed sim/AVD.** If every device is claimed by other rn-iso projects, `--auto` errors. To take one over, run the command interactively (no `--auto`, with a real TTY) and confirm at the prompt — only do this if the user explicitly asks.
 - **Always use `npx rn-iso device` to discover your target.** Never assume `booted` is your sim — another project's simulator might be booted too.
 - **Always pass the UDID/serial explicitly** to `xcrun simctl` and `adb -s`. Examples:

package/src/commands/android.js

@@ -20,14 +20,15 @@ import { resolveLabel } from '../labels.js';
 export default function androidCommand(program) {
   program
     .command('android')
-    .description('Ensure a dedicated Android emulator + Metro for the current project; build/install if needed')
+    .description('Ensure a dedicated Android emulator + Metro for the current project; build/install if needed. Pass extra flags to the build CLI after `--`, e.g. `rn-iso android -- --mode=diaRelease`.')
+    .argument('[extras...]', 'Flags forwarded as-is to the underlying build command (after `--`)')
     .option('--auto', 'Non-interactive: pick the first unclaimed AVD without prompting (also implied when stdin is not a TTY)')
     .option('--label <name>', 'Optional shortcut name; refer to the project as <name> in stop / release / etc.')
     .option('--script <name>', 'package.json script to invoke for build/install (default: project setting `android.script`, else `android`)')
     .option('--no-script', 'Skip the package.json script lookup; run expo/react-native CLI directly')
     .option('--pm <name>', 'Package manager: npm, yarn, pnpm, bun (default: project setting `packageManager`, else detected from lockfile)')
     .option('--no-install', 'Skip the build/install step')
-    .action(async (opts) => {
+    .action(async (extras, opts) => {
       const root = findProjectRoot(process.cwd());
       if (!root) {
         console.error(chalk.red('Not in a React Native project (no package.json found).'));
@@ -157,6 +158,7 @@ export default function androidCommand(program) {
           serial,
           port: proj.metroPort,
           useScript,
+          extras,
         });
         console.log(chalk.dim(`> ${cmd}`));
         const exec = getExecutor();

package/src/commands/ios.js

@@ -12,7 +12,8 @@ import { resolveLabel } from '../labels.js';
 export default function iosCommand(program) {
   program
     .command('ios')
-    .description('Ensure a dedicated iOS simulator + Metro server for the current project; build/install if needed')
+    .description('Ensure a dedicated iOS simulator + Metro server for the current project; build/install if needed. Pass extra flags to the build CLI after `--`, e.g. `rn-iso ios -- --variant=release`.')
+    .argument('[extras...]', 'Flags forwarded as-is to the underlying build command (after `--`)')
     .option('--device-type <name>', 'Explicit opt-in: create a NEW sim of this device type (e.g. "iPhone 17 Pro")')
     .option('--runtime <version>', 'iOS runtime version when creating a new sim (e.g. "26.2"); defaults to latest')
     .option('--auto', 'Non-interactive: pick the first unclaimed sim without prompting (also implied when stdin is not a TTY)')
@@ -21,7 +22,7 @@ export default function iosCommand(program) {
     .option('--no-script', 'Skip the package.json script lookup; run expo/react-native CLI directly')
     .option('--pm <name>', 'Package manager: npm, yarn, pnpm, bun (default: project setting `packageManager`, else detected from lockfile)')
     .option('--no-install', 'Skip the build/install step (assume app is already installed)')
-    .action(async (opts) => {
+    .action(async (extras, opts) => {
       const root = findProjectRoot(process.cwd());
       if (!root) {
         console.error(chalk.red('Not in a React Native project (no package.json found).'));
@@ -158,6 +159,7 @@ export default function iosCommand(program) {
           udid,
           port: proj.metroPort,
           useScript,
+          extras,
         });
         console.log(chalk.dim(`> ${cmd}`));
         const exec = getExecutor();

package/src/runner.js

@@ -79,7 +79,10 @@ export function detectScriptCli(scriptBody) {
 // iOS run command. Prefers the project's `ios` script if present (the most
 // reliable: respects user customization, picks the right CLI). Falls back to
 // expo run:ios / react-native run-ios when no script exists or --no-script.
-export function buildIosCommand({ projectRoot, packageManager, scriptName, isExpo, udid, port, useScript = true }) {
+// Any `extras` are appended last so they can override earlier flags (CLIs
+// using commander/yargs are last-wins on repeated options).
+export function buildIosCommand({ projectRoot, packageManager, scriptName, isExpo, udid, port, useScript = true, extras = [] }) {
+  const tail = (extras || []).map(shQuote);
   if (useScript && scriptName) {
     const script = getProjectScript(projectRoot, scriptName);
     if (script) {
@@ -89,16 +92,19 @@ export function buildIosCommand({ projectRoot, packageManager, scriptName, isExp
       return buildScriptCommand(packageManager, scriptName, [
         deviceFlag,
         `--port ${port}`,
+        ...tail,
       ]);
     }
   }
+  const tailStr = tail.length ? ' ' + tail.join(' ') : '';
   if (isExpo) {
-    return `npx expo run:ios --device ${udid} --port ${port}`;
+    return `npx expo run:ios --device ${udid} --port ${port}${tailStr}`;
   }
-  return `npx react-native run-ios --udid ${udid} --port ${port}`;
+  return `npx react-native run-ios --udid ${udid} --port ${port}${tailStr}`;
 }
 
-export function buildAndroidCommand({ projectRoot, packageManager, scriptName, isExpo, avdName, serial, port, useScript = true }) {
+export function buildAndroidCommand({ projectRoot, packageManager, scriptName, isExpo, avdName, serial, port, useScript = true, extras = [] }) {
+  const tail = (extras || []).map(shQuote);
   if (useScript && scriptName) {
     const script = getProjectScript(projectRoot, scriptName);
     if (script) {
@@ -108,13 +114,24 @@ export function buildAndroidCommand({ projectRoot, packageManager, scriptName, i
       return buildScriptCommand(packageManager, scriptName, [
         deviceFlag,
         `--port ${port}`,
+        ...tail,
       ]);
     }
   }
+  const tailStr = tail.length ? ' ' + tail.join(' ') : '';
   if (isExpo) {
-    return `npx expo run:android --device "${avdName}" --port ${port}`;
+    return `npx expo run:android --device "${avdName}" --port ${port}${tailStr}`;
   }
-  return `RCT_METRO_PORT=${port} npx react-native run-android --deviceId ${serial}`;
+  return `RCT_METRO_PORT=${port} npx react-native run-android --deviceId ${serial}${tailStr}`;
+}
+
+// POSIX-safe single-quote shell escape. Leaves "safe" tokens (alnum and a
+// few harmless punctuation marks like `=`, `.`, `,`, `:`, `/`, `-`, `@`,
+// `+`, `_`, `%`) alone, single-quotes everything else.
+export function shQuote(s) {
+  if (s === '') return "''";
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(s)) return s;
+  return "'" + s.replace(/'/g, "'\\''") + "'";
 }
 
 export function buildMetroCommand({ isExpo, port }) {