rn-iso 0.3.3 → 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 |
@@ -48,6 +55,7 @@ All commands below take the same `npx rn-iso` prefix.
 | `reserve [ios\|android]` | Lock a manually-started sim/emulator to the current project (no build) |
 | `unreserve [ios\|android]` | Drop the current project's lock without shutting the sim down |
 | `release [<port>\|<shortcut>\|<path>] [--platform <p>] [--shutdown]` | Free a project's assignment. Target can be a Metro port (`8083`), a shortcut (label or unique basename), or an absolute path. `--shutdown` also stops the sim. |
+| `config [<key> [<value>]] [--unset] [--project <target>]` | Get / set a per-project setting (`packageManager`, `ios.script`, `android.script`). |
 
 ## How it works
 
@@ -71,6 +79,25 @@ npx rn-iso unreserve                   # drop the lock without shutting the sim
 
 Reserve binds the sim to the current project the same way `ios` / `android` would, but without running a build. If the sim is already held by another project, the picker prompts you to take it over.
 
+## Per-project settings (`rn-iso config`)
+
+A few options can be persisted per project so you don't have to repeat the same flags every run. Resolution order:
+
+1. CLI flag (`--script`, `--pm`)
+2. Stored project setting (this section)
+3. Default inferred from the project (`ios` / `android` script if present, package manager from lockfile)
+
+```bash
+npx rn-iso config packageManager bun
+npx rn-iso config ios.script dev:ios
+npx rn-iso config android.script "dev:android --variant=debug"
+npx rn-iso config                 # list current project's settings
+npx rn-iso config ios.script      # print one
+npx rn-iso config ios.script --unset
+```
+
+Allowed keys today: `packageManager` (one of `npm|yarn|pnpm|bun`), `ios.script`, `android.script`. Settings live in `~/.rn-iso/config.json` under the project's entry.
+
 ## Project shortcuts (--label)
 
 Each registered project has a "shortcut" you can pass to `stop` / `release` instead of the full path. The first time you run `ios`, `android`, or `reserve` interactively you'll be prompted for one (the directory basename is the default — hit enter to accept). Override any time with `--label <name>`:

package/bin/cli.js

@@ -10,6 +10,7 @@ import statusCommand from '../src/commands/status.js';
 import releaseCommand from '../src/commands/release.js';
 import reserveCommand from '../src/commands/reserve.js';
 import unreserveCommand from '../src/commands/unreserve.js';
+import configCommand from '../src/commands/config.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 
@@ -28,5 +29,6 @@ statusCommand(program);
 releaseCommand(program);
 reserveCommand(program);
 unreserveCommand(program);
+configCommand(program);
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-iso",
-  "version": "0.3.3",
+  "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:
@@ -83,6 +84,7 @@ Reserve binds the sim to the current project the same way `ios` does, but skips
 - `npx rn-iso start` — start Metro detached on the project's assigned port WITHOUT building/installing. Useful to keep Metro alive across builds.
 - `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.
+- `npx rn-iso config [<key> [<value>]] [--unset] [--project <target>]` — persist per-project settings. Allowed keys: `packageManager` (npm|yarn|pnpm|bun), `ios.script`, `android.script`. Resolution order on `ios`/`android`: CLI flag > stored setting > inferred default. Useful when a project's build script is named differently (`dev:ios` instead of `ios`) or when a different package manager is used than the lockfile suggests.
 
 ### Project shortcuts (--label)
 

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: android)', 'android')
+    .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: detected from lockfile)')
+    .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).'));
@@ -142,9 +143,12 @@ export default function androidCommand(program) {
       console.log(chalk.dim(`adb reverse tcp:${proj.metroPort} configured for ${serial}`));
 
       if (opts.install !== false) {
-        const packageManager = opts.pm || detectPackageManager(root);
+        const settings = proj.settings || {};
+        const packageManager = opts.pm ?? settings.packageManager ?? detectPackageManager(root);
         const useScript = opts.script !== false;
-        const scriptName = useScript ? (typeof opts.script === 'string' ? opts.script : 'android') : null;
+        const scriptName = useScript
+          ? (typeof opts.script === 'string' ? opts.script : (settings.android?.script ?? 'android'))
+          : null;
         const cmd = buildAndroidCommand({
           projectRoot: root,
           packageManager,
@@ -154,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/config.js

@@ -0,0 +1,102 @@
+// src/commands/config.js
+import chalk from 'chalk';
+import {
+  findProjectRoot,
+  resolveRegisteredProject,
+  detectIsExpo,
+  detectBundleId,
+  detectAndroidPackage,
+} from '../project.js';
+import {
+  getProject,
+  upsertProject,
+  getProjectSettings,
+  getProjectSetting,
+  setProjectSetting,
+  unsetProjectSetting,
+} from '../config.js';
+
+const ALLOWED_KEYS = ['packageManager', 'ios.script', 'android.script'];
+const PM_VALUES = ['npm', 'yarn', 'pnpm', 'bun'];
+
+export default function configCommand(program) {
+  program
+    .command('config [key] [value]')
+    .description(
+      'Get or set a per-project setting. Allowed keys: ' + ALLOWED_KEYS.join(', ') +
+      '. With no args, lists current settings.'
+    )
+    .option('--unset', 'Remove the value for <key>')
+    .option('--project <target>', 'Run against another project (label / unique basename / absolute path) instead of cwd')
+    .action((key, value, opts) => {
+      const found = resolveTarget(opts.project);
+
+      if (!key) {
+        const settings = getProjectSettings(found);
+        if (Object.keys(settings).length === 0) {
+          console.log(chalk.dim(`No settings for ${found}.`));
+          return;
+        }
+        console.log(found);
+        for (const k of ALLOWED_KEYS) {
+          const v = getProjectSetting(found, k);
+          if (v !== undefined) console.log(`  ${k} = ${chalk.cyan(v)}`);
+        }
+        return;
+      }
+
+      if (!ALLOWED_KEYS.includes(key)) {
+        console.error(chalk.red(`Unknown key "${key}". Allowed: ${ALLOWED_KEYS.join(', ')}.`));
+        process.exit(1);
+      }
+
+      if (opts.unset) {
+        const removed = unsetProjectSetting(found, key);
+        if (removed) console.log(chalk.green(`Unset ${key} for ${found}.`));
+        else console.log(chalk.dim(`${key} was already unset.`));
+        return;
+      }
+
+      if (value === undefined) {
+        const cur = getProjectSetting(found, key);
+        if (cur === undefined) console.log(chalk.dim('(unset)'));
+        else console.log(cur);
+        return;
+      }
+
+      if (key === 'packageManager' && !PM_VALUES.includes(value)) {
+        console.error(chalk.red(`Invalid packageManager "${value}". Must be one of: ${PM_VALUES.join(', ')}.`));
+        process.exit(1);
+      }
+
+      setProjectSetting(found, key, value);
+      console.log(chalk.green(`Set ${key} = ${value} for ${found}.`));
+    });
+}
+
+// `--project` targets an existing registered project; without it we fall
+// back to the cwd and auto-register if needed (so users can configure a
+// project before running `ios` / `android` for the first time).
+function resolveTarget(projectArg) {
+  if (projectArg) {
+    const { found, error } = resolveRegisteredProject(projectArg);
+    if (!found) {
+      console.error(chalk.red(error));
+      process.exit(1);
+    }
+    return found;
+  }
+  const root = findProjectRoot(process.cwd());
+  if (!root) {
+    console.error(chalk.red('Not in a React Native project (no package.json found).'));
+    process.exit(1);
+  }
+  if (!getProject(root)) {
+    upsertProject(root, {
+      bundleId: detectBundleId(root),
+      androidPackage: detectAndroidPackage(root),
+      isExpo: detectIsExpo(root),
+    });
+  }
+  return root;
+}

package/src/commands/ios.js

@@ -12,16 +12,17 @@ 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)')
     .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: ios)', 'ios')
+    .option('--script <name>', 'package.json script to invoke for build/install (default: project setting `ios.script`, else `ios`)')
     .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: detected from lockfile)')
+    .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).'));
@@ -144,9 +145,12 @@ export default function iosCommand(program) {
       // (without build/install), use `rn-iso start`.
 
       if (opts.install !== false) {
-        const packageManager = opts.pm || detectPackageManager(root);
+        const settings = proj.settings || {};
+        const packageManager = opts.pm ?? settings.packageManager ?? detectPackageManager(root);
         const useScript = opts.script !== false;
-        const scriptName = useScript ? (typeof opts.script === 'string' ? opts.script : 'ios') : null;
+        const scriptName = useScript
+          ? (typeof opts.script === 'string' ? opts.script : (settings.ios?.script ?? 'ios'))
+          : null;
         const cmd = buildIosCommand({
           projectRoot: root,
           packageManager,
@@ -155,6 +159,7 @@ export default function iosCommand(program) {
           udid,
           port: proj.metroPort,
           useScript,
+          extras,
         });
         console.log(chalk.dim(`> ${cmd}`));
         const exec = getExecutor();

package/src/config.js

@@ -88,6 +88,70 @@ export function clearDevice(projectPath, platform) {
   saveConfig(cfg);
 }
 
+// --- Per-project settings (scripts, package manager, ...) ---
+
+export function getProjectSettings(projectPath) {
+  return getProject(projectPath)?.settings || {};
+}
+
+export function getProjectSetting(projectPath, dottedKey) {
+  return readNested(getProjectSettings(projectPath), dottedKey);
+}
+
+export function setProjectSetting(projectPath, dottedKey, value) {
+  const cfg = ensureConfig();
+  const proj = cfg.projects[projectPath];
+  if (!proj) throw new Error(`Project not registered: ${projectPath}`);
+  proj.settings = proj.settings || {};
+  writeNested(proj.settings, dottedKey, value);
+  saveConfig(cfg);
+}
+
+export function unsetProjectSetting(projectPath, dottedKey) {
+  const cfg = loadConfig();
+  const proj = cfg?.projects?.[projectPath];
+  if (!proj?.settings) return false;
+  const removed = deleteNested(proj.settings, dottedKey);
+  if (removed) saveConfig(cfg);
+  return removed;
+}
+
+function readNested(obj, dottedKey) {
+  if (!obj) return undefined;
+  const keys = dottedKey.split('.');
+  let cur = obj;
+  for (const k of keys) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = cur[k];
+  }
+  return cur;
+}
+
+function writeNested(obj, dottedKey, value) {
+  const keys = dottedKey.split('.');
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (typeof cur[keys[i]] !== 'object' || cur[keys[i]] === null) {
+      cur[keys[i]] = {};
+    }
+    cur = cur[keys[i]];
+  }
+  cur[keys[keys.length - 1]] = value;
+}
+
+function deleteNested(obj, dottedKey) {
+  const keys = dottedKey.split('.');
+  let cur = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (cur[keys[i]] == null || typeof cur[keys[i]] !== 'object') return false;
+    cur = cur[keys[i]];
+  }
+  const leaf = keys[keys.length - 1];
+  if (!(leaf in cur)) return false;
+  delete cur[leaf];
+  return true;
+}
+
 export function allMetroPorts() {
   const cfg = loadConfig();
   if (!cfg?.projects) return [];

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 }) {