vibeview 0.29.0 → 0.30.0

package/dist/{chunk-T6EQQV6E.js → chunk-NOZGZT3G.js}

@@ -13,7 +13,7 @@ import {
   resolveArtifact,
   resolveAuth,
   uploadAppBuild
-} from "./chunk-PBMB6TG4.js";
+} from "./chunk-ZZK7YQSP.js";
 
 // src/lib/dev-config.ts
 import { readFileSync, renameSync, rmSync, writeFileSync } from "fs";
@@ -479,6 +479,108 @@ async function checkMetro(port, timeoutMs = 1500) {
   }
 }
 
+// src/lib/local-config.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync as renameSync2, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join3 } from "path";
+var DIR = ".vibeview";
+var FILE2 = "local.json";
+function localConfigPath(cwd) {
+  return join3(cwd, DIR, FILE2);
+}
+function loadLocalDevConfig(cwd) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync3(localConfigPath(cwd), "utf-8"));
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+  const raw = parsed;
+  const out = {};
+  if (isDevPlatform(raw.defaultPlatform)) out.defaultPlatform = raw.defaultPlatform;
+  if (raw.platforms && typeof raw.platforms === "object") {
+    for (const [key, value] of Object.entries(raw.platforms)) {
+      if (!isDevPlatform(key) || !value || typeof value !== "object") continue;
+      const v = value;
+      const entry = {};
+      if (typeof v.appId === "string" && v.appId) entry.appId = v.appId;
+      if (typeof v.deviceCategory === "string" && v.deviceCategory) {
+        entry.deviceCategory = v.deviceCategory;
+      }
+      if (typeof v.metroPort === "number" && Number.isInteger(v.metroPort) && v.metroPort > 0) {
+        entry.metroPort = v.metroPort;
+      }
+      if (Object.keys(entry).length) (out.platforms ??= {})[key] = entry;
+    }
+  }
+  return out;
+}
+function prune(cfg) {
+  const out = {};
+  if (cfg.defaultPlatform) out.defaultPlatform = cfg.defaultPlatform;
+  for (const [key, entry] of Object.entries(cfg.platforms ?? {})) {
+    const kept = Object.fromEntries(
+      Object.entries(entry ?? {}).filter(([, v]) => v !== void 0)
+    );
+    if (Object.keys(kept).length) (out.platforms ??= {})[key] = kept;
+  }
+  return out;
+}
+function saveLocalDevConfig(cwd, cfg) {
+  const pruned = prune(cfg);
+  const target = localConfigPath(cwd);
+  if (!pruned.defaultPlatform && !pruned.platforms) {
+    rmSync3(target, { force: true });
+    return;
+  }
+  mkdirSync2(join3(cwd, DIR), { recursive: true });
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync3(tmp, JSON.stringify(pruned, null, 2) + "\n");
+    renameSync2(tmp, target);
+  } catch (err) {
+    rmSync3(tmp, { force: true });
+    throw err;
+  }
+  ensureGitignored(cwd);
+}
+function effectiveDevConfig(committed, local) {
+  if (!committed && !local.defaultPlatform && !local.platforms) return null;
+  const base = committed ? { ...committed, platforms: { ...committed.platforms } } : { defaultPlatform: local.defaultPlatform ?? "ios", platforms: {} };
+  if (local.defaultPlatform) base.defaultPlatform = local.defaultPlatform;
+  for (const [key, entry] of Object.entries(local.platforms ?? {})) {
+    const platform = key;
+    const merged = { ...base.platforms[platform] };
+    if (entry?.appId) merged.appId = entry.appId;
+    if (entry?.deviceCategory) merged.deviceCategory = entry.deviceCategory;
+    if (entry?.metroPort !== void 0) merged.metroPort = entry.metroPort;
+    base.platforms[platform] = merged;
+  }
+  return base;
+}
+function describeLocalChanges(before, after) {
+  const changes = [];
+  const a = prune(before);
+  const b = prune(after);
+  if (a.defaultPlatform !== b.defaultPlatform) {
+    changes.push(
+      b.defaultPlatform ? `defaultPlatform ${b.defaultPlatform}` : `defaultPlatform (removed, was ${a.defaultPlatform})`
+    );
+  }
+  const keys = /* @__PURE__ */ new Set([...Object.keys(a.platforms ?? {}), ...Object.keys(b.platforms ?? {})]);
+  for (const key of keys) {
+    const pa = a.platforms?.[key] ?? {};
+    const pb = b.platforms?.[key] ?? {};
+    for (const field of ["appId", "deviceCategory", "metroPort"]) {
+      if (pa[field] === pb[field]) continue;
+      changes.push(
+        pb[field] === void 0 ? `${key}.${field} (removed, was ${String(pa[field])})` : `${key}.${field} ${String(pb[field])}`
+      );
+    }
+  }
+  return changes;
+}
+
 // src/commands/build.ts
 import { spawn as spawn2 } from "child_process";
 import { createInterface } from "readline";
@@ -490,12 +592,12 @@ import chalk2 from "chalk";
 import { input, select } from "@inquirer/prompts";
 
 // src/lib/project-detect.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3, readdirSync, statSync } from "fs";
-import { join as join3 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync4, readdirSync, statSync } from "fs";
+import { join as join4 } from "path";
 import ignore from "ignore";
 function readJson(cwd, name) {
   try {
-    return JSON.parse(readFileSync3(join3(cwd, name), "utf-8"));
+    return JSON.parse(readFileSync4(join4(cwd, name), "utf-8"));
   } catch {
     return null;
   }
@@ -510,19 +612,19 @@ function isFile(path) {
 function detectFlavor(cwd) {
   let deps = {};
   try {
-    const pkg = JSON.parse(readFileSync3(join3(cwd, "package.json"), "utf-8"));
+    const pkg = JSON.parse(readFileSync4(join4(cwd, "package.json"), "utf-8"));
     deps = { ...pkg.dependencies, ...pkg.devDependencies };
   } catch {
   }
   if ("expo" in deps) return "expo";
-  if (existsSync2(join3(cwd, "android", "gradlew")) || iosWorkspaceName(cwd)) return "bare-rn";
-  if (isFile(join3(cwd, "manifest"))) return "roku";
+  if (existsSync2(join4(cwd, "android", "gradlew")) || iosWorkspaceName(cwd)) return "bare-rn";
+  if (isFile(join4(cwd, "manifest"))) return "roku";
   return "unknown";
 }
 function nativeDirShipped(cwd, dir) {
-  if (!existsSync2(join3(cwd, dir))) return false;
+  if (!existsSync2(join4(cwd, dir))) return false;
   try {
-    const ig = ignore().add(readFileSync3(join3(cwd, ".gitignore"), "utf-8"));
+    const ig = ignore().add(readFileSync4(join4(cwd, ".gitignore"), "utf-8"));
     return !ig.ignores(`${dir}/`);
   } catch {
     return true;
@@ -538,7 +640,7 @@ function isManagedExpo(cwd, platform) {
 }
 function iosWorkspaceName(cwd) {
   try {
-    const found = readdirSync(join3(cwd, "ios")).find((f) => f.endsWith(".xcworkspace"));
+    const found = readdirSync(join4(cwd, "ios")).find((f) => f.endsWith(".xcworkspace"));
     return found ? found.replace(/\.xcworkspace$/, "") : null;
   } catch {
     return null;
@@ -547,9 +649,9 @@ function iosWorkspaceName(cwd) {
 var IOS_ARTIFACT = "ios/build/Build/Products/Debug-iphonesimulator/*.app";
 var ANDROID_ARTIFACT = "android/app/build/outputs/apk/debug/*.apk";
 function installCommand(cwd) {
-  if (existsSync2(join3(cwd, "yarn.lock"))) return "yarn install --immutable";
-  if (existsSync2(join3(cwd, "pnpm-lock.yaml"))) return "pnpm install --frozen-lockfile";
-  if (existsSync2(join3(cwd, "package-lock.json"))) return "npm ci";
+  if (existsSync2(join4(cwd, "yarn.lock"))) return "yarn install --immutable";
+  if (existsSync2(join4(cwd, "pnpm-lock.yaml"))) return "pnpm install --frozen-lockfile";
+  if (existsSync2(join4(cwd, "package-lock.json"))) return "npm ci";
   return "yarn install --immutable";
 }
 function managedExpoAndroidCommand(cwd) {
@@ -563,7 +665,7 @@ var ROKU_ZIP_COMMAND = "zip -r out/channel.zip manifest source components images
 function rokuDefaults(cwd) {
   const pkg = readJson(cwd, "package.json");
   const scripts = pkg?.scripts ?? {};
-  const runner = existsSync2(join3(cwd, "yarn.lock")) ? "yarn" : "npm run";
+  const runner = existsSync2(join4(cwd, "yarn.lock")) ? "yarn" : "npm run";
   const packageScript = Object.entries(scripts).find(
     ([name, body]) => !name.startsWith("deploy") && (name.startsWith("package") || body.includes("--package-only") || body.includes("zipPackage"))
   );
@@ -621,7 +723,7 @@ function expoSanitizedName(name) {
   return name.replace(/[\W_]+/g, "").normalize("NFD").replace(/[\u0300-\u036f]/g, "");
 }
 function managedExpoIosName(cwd) {
-  if (existsSync2(join3(cwd, "app.config.js")) || existsSync2(join3(cwd, "app.config.ts"))) {
+  if (existsSync2(join4(cwd, "app.config.js")) || existsSync2(join4(cwd, "app.config.ts"))) {
     return null;
   }
   const raw = readJson(cwd, "app.config.json") ?? readJson(cwd, "app.json");
@@ -766,9 +868,9 @@ async function promptMetroCommand(cwd, platform) {
 
 // src/lib/source-pack.ts
 import { execFile, spawn } from "child_process";
-import { lstatSync, mkdtempSync, readFileSync as readFileSync4, rmSync as rmSync3, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
+import { lstatSync, mkdtempSync, readFileSync as readFileSync5, rmSync as rmSync4, statSync as statSync2, writeFileSync as writeFileSync4 } from "fs";
 import { tmpdir } from "os";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import ignore2 from "ignore";
 var NotAGitRepoError = class extends Error {
   constructor(message) {
@@ -794,15 +896,15 @@ async function listSourceFiles(projectRoot) {
   const stdout = await runGitLsFiles(projectRoot);
   const rawPaths = stdout.length ? stdout.split("\0").filter((p) => p.length > 0) : [];
   let filtered = rawPaths;
-  const vvignorePath = join4(projectRoot, ".vvignore");
+  const vvignorePath = join5(projectRoot, ".vvignore");
   if (statOrNull(vvignorePath)?.isFile()) {
-    const ig = ignore2().add(readFileSync4(vvignorePath, "utf-8"));
+    const ig = ignore2().add(readFileSync5(vvignorePath, "utf-8"));
     filtered = filtered.filter((p) => !ig.ignores(p));
   }
   const result = [];
   for (const relPath of filtered) {
     if (isForceExcluded(relPath)) continue;
-    const st = statOrNull(join4(projectRoot, relPath));
+    const st = statOrNull(join5(projectRoot, relPath));
     if (!st) continue;
     result.push(relPath);
   }
@@ -852,7 +954,7 @@ async function packSource(projectRoot, files, opts = {}) {
   let totalBytes = 0;
   const sized = [];
   for (const relPath of files) {
-    const bytes = lstatSync(join4(projectRoot, relPath)).size;
+    const bytes = lstatSync(join5(projectRoot, relPath)).size;
     totalBytes += bytes;
     sized.push({ path: relPath, bytes });
   }
@@ -863,14 +965,14 @@ async function packSource(projectRoot, files, opts = {}) {
       largest
     );
   }
-  const tmpDir = mkdtempSync(join4(tmpdir(), "vibeview-source-pack-"));
-  const cleanup = () => rmSync3(tmpDir, { recursive: true, force: true });
+  const tmpDir = mkdtempSync(join5(tmpdir(), "vibeview-source-pack-"));
+  const cleanup = () => rmSync4(tmpDir, { recursive: true, force: true });
   try {
     const supportsNull = await probeTarNullSupport();
-    const tarPath = join4(tmpDir, "source.tgz");
+    const tarPath = join5(tmpDir, "source.tgz");
     if (supportsNull) {
-      const listPath = join4(tmpDir, "files.list");
-      writeFileSync3(listPath, files.map((f) => `${f}\0`).join(""));
+      const listPath = join5(tmpDir, "files.list");
+      writeFileSync4(listPath, files.map((f) => `${f}\0`).join(""));
       await runTar(["-czf", tarPath, "-C", projectRoot, "--null", "-T", listPath]);
     } else {
       const badName = files.find((f) => f.includes("\n"));
@@ -879,8 +981,8 @@ async function packSource(projectRoot, files, opts = {}) {
           `cannot pack source: filename contains a newline (${JSON.stringify(badName)}) and the installed tar doesn't support --null -T; rename the file or install a tar that supports --null`
         );
       }
-      const listPath = join4(tmpDir, "files.list");
-      writeFileSync3(listPath, files.map((f) => `${f}
+      const listPath = join5(tmpDir, "files.list");
+      writeFileSync4(listPath, files.map((f) => `${f}
 `).join(""));
       await runTar(["-czf", tarPath, "-C", projectRoot, "-T", listPath]);
     }
@@ -900,12 +1002,12 @@ var nullSupportCache = null;
 function probeTarNullSupport() {
   if (!nullSupportCache) {
     nullSupportCache = new Promise((resolve) => {
-      const tmp = mkdtempSync(join4(tmpdir(), "vibeview-tar-probe-"));
-      const listPath = join4(tmp, "empty.list");
-      writeFileSync3(listPath, "");
-      const out = join4(tmp, "probe.tgz");
+      const tmp = mkdtempSync(join5(tmpdir(), "vibeview-tar-probe-"));
+      const listPath = join5(tmp, "empty.list");
+      writeFileSync4(listPath, "");
+      const out = join5(tmp, "probe.tgz");
       execFile("tar", ["-czf", out, "-C", tmp, "--null", "-T", listPath], (err) => {
-        rmSync3(tmp, { recursive: true, force: true });
+        rmSync4(tmp, { recursive: true, force: true });
         resolve(!err);
       });
     });
@@ -1777,7 +1879,7 @@ your build command must produce a zip \u2014 use the package/zip step, not deplo
 
 // src/commands/dev.ts
 import { spawn as spawn4 } from "child_process";
-import { createWriteStream, mkdirSync as mkdirSync3 } from "fs";
+import { createWriteStream, mkdirSync as mkdirSync4 } from "fs";
 import { dirname as dirname4 } from "path";
 import { createInterface as createInterface3 } from "readline";
 import { select as select3 } from "@inquirer/prompts";
@@ -1973,15 +2075,15 @@ import { spawn as spawn3 } from "child_process";
 import { createInterface as createInterface2 } from "readline";
 
 // src/lib/metro-state.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync5, rmSync as rmSync4, writeFileSync as writeFileSync4 } from "fs";
-import { dirname as dirname2, join as join5 } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync6, rmSync as rmSync5, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname2, join as join6 } from "path";
 var STATE_DIR2 = ".vibeview";
 var STATE_FILE2 = "metro-state.json";
 function statePath2(cwd) {
-  return join5(cwd, STATE_DIR2, STATE_FILE2);
+  return join6(cwd, STATE_DIR2, STATE_FILE2);
 }
 function metroLogPath(cwd) {
-  return join5(cwd, STATE_DIR2, "metro.log");
+  return join6(cwd, STATE_DIR2, "metro.log");
 }
 function isPidAlive2(pid) {
   try {
@@ -1993,13 +2095,13 @@ function isPidAlive2(pid) {
 }
 function writeMetroState(cwd, state) {
   const path = statePath2(cwd);
-  mkdirSync2(dirname2(path), { recursive: true });
-  writeFileSync4(path, JSON.stringify(state, null, 2) + "\n");
+  mkdirSync3(dirname2(path), { recursive: true });
+  writeFileSync5(path, JSON.stringify(state, null, 2) + "\n");
 }
 function readMetroState(cwd) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync5(statePath2(cwd), "utf-8"));
+    parsed = JSON.parse(readFileSync6(statePath2(cwd), "utf-8"));
   } catch {
     return null;
   }
@@ -2011,7 +2113,7 @@ function readMetroState(cwd) {
 }
 function clearMetroState(cwd) {
   const path = statePath2(cwd);
-  if (existsSync3(path)) rmSync4(path, { force: true });
+  if (existsSync3(path)) rmSync5(path, { force: true });
 }
 function killOwnedMetro(cwd) {
   const state = readMetroState(cwd);
@@ -2524,17 +2626,19 @@ function requireNonInteractive(json, message) {
 }
 async function ensureConfig(api, opts) {
   const existing = loadDevConfig(process.cwd());
+  const local = loadLocalDevConfig(process.cwd());
+  const effective = effectiveDevConfig(existing, local);
   if (opts.platform && !isDevPlatform(opts.platform)) {
     console.error(chalk4.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}`));
     process.exit(2);
   }
-  if (!opts.platform && !existing?.defaultPlatform) {
+  if (!opts.platform && !effective?.defaultPlatform) {
     requireNonInteractive(
       opts.json,
       `--platform is required (no vibeview.json default yet) \u2014 pass --platform <${DEV_PLATFORMS.join("|")}>, or run once interactively to set a default.`
     );
   }
-  const platform = opts.platform || existing?.defaultPlatform || await select3({
+  const platform = opts.platform || effective?.defaultPlatform || await select3({
     message: "Platform to run on",
     choices: platformChoices(process.cwd())
   });
@@ -2571,7 +2675,7 @@ async function ensureConfig(api, opts) {
       }
     }
   }
-  const entry = existing?.platforms?.[platform];
+  const entry = effective?.platforms?.[platform];
   let allApps;
   try {
     allApps = await api.listApps();
@@ -2591,6 +2695,7 @@ ${hint}`);
     process.exit(2);
   }
   let appId = choice.appId;
+  const appFromFlag = Boolean(opts.app) && appId === opts.app;
   let builtThisRun = false;
   if (choice.staleCached) {
     console.error(
@@ -2663,22 +2768,51 @@ ${hint}`);
     });
   }
   const deviceCategory = isTv ? "tv" : opts.deviceCategory || entry?.deviceCategory || "phone";
-  const metroResolved = resolveMetro(
-    existing,
-    platform,
-    opts.metroPort ? parseInt(opts.metroPort, 10) : void 0
-  );
+  const metroPortFlag = opts.metroPort ? parseInt(opts.metroPort, 10) : void 0;
+  const metroResolved = resolveMetro(effective, platform, metroPortFlag);
+  const committedEntry = existing?.platforms?.[platform];
+  const nextLocal = JSON.parse(JSON.stringify(local));
+  const localEntry = (nextLocal.platforms ??= {})[platform] ??= {};
+  let committedAppId = committedEntry?.appId;
+  if (!committedAppId) {
+    committedAppId = appId;
+  } else if (appId !== committedAppId) {
+    if (appFromFlag || local.platforms?.[platform]?.appId !== void 0) {
+      localEntry.appId = appId;
+    } else {
+      committedAppId = appId;
+    }
+  }
+  if (appId === committedAppId) delete localEntry.appId;
+  let committedCategory = committedEntry?.deviceCategory;
+  if (!isTv) {
+    if (!committedCategory) committedCategory = deviceCategory;
+    if (deviceCategory !== committedCategory) localEntry.deviceCategory = deviceCategory;
+    else delete localEntry.deviceCategory;
+  }
+  const committedDefault = existing?.defaultPlatform ?? platform;
+  if (opts.platform) {
+    if (platform !== committedDefault) nextLocal.defaultPlatform = platform;
+    else delete nextLocal.defaultPlatform;
+  }
   const cfg = buildSavedConfig({
     existing,
     platform,
-    appId,
-    deviceCategory,
+    appId: committedAppId,
+    deviceCategory: committedCategory ?? deviceCategory,
     isTv,
-    metroPortFlag: opts.metroPort,
+    // Never the flag: vibeview.json keeps (or, on the first run, seeds) the
+    // shared default; the flag's port is saved locally below.
+    metroPortFlag: void 0,
     isFirstRun,
     firstRunMetro,
     firstRunBuild
   });
+  cfg.defaultPlatform = committedDefault;
+  if (metroPortFlag !== void 0 && PLATFORM_NEEDS_METRO[platform]) {
+    if (metroPortFlag !== resolveMetro(cfg, platform).port) localEntry.metroPort = metroPortFlag;
+    else delete localEntry.metroPort;
+  }
   const commitConfig = () => {
     updateDevConfig(process.cwd(), platform, (fresh) => {
       applyConfigChanges(fresh, existing, cfg);
@@ -2689,6 +2823,15 @@ ${hint}`);
         console.error(chalk4.dim(`Updated vibeview.json: ${changes.join(", ")}`));
       }
     }
+    const localChanges = describeLocalChanges(local, nextLocal);
+    if (localChanges.length) {
+      saveLocalDevConfig(process.cwd(), nextLocal);
+      console.error(
+        chalk4.dim(
+          `Saved to .vibeview/local.json (yours only, not committed): ${localChanges.join(", ")}`
+        )
+      );
+    }
     if (isFirstRun) {
       console.error(chalk4.dim(`Created vibeview.json (platform: ${platform}, app: ${appId}).`));
       const hint = fillLaterHint(
@@ -2698,7 +2841,7 @@ ${hint}`);
       if (hint) console.error(chalk4.dim(hint));
     }
   };
-  const finalMetro = isFirstRun ? resolveMetro(cfg, platform, opts.metroPort ? parseInt(opts.metroPort, 10) : void 0) : metroResolved;
+  const finalMetro = isFirstRun ? resolveMetro(effectiveDevConfig(cfg, nextLocal), platform, metroPortFlag) : metroResolved;
   return {
     platform,
     appId,
@@ -2793,12 +2936,21 @@ async function runDevInProcess(opts) {
         (l) => console.error(chalk4.dim(l))
       );
       cfg.appId = result.public_id;
-      updateDevConfig(process.cwd(), cfg.platform, (fresh) => {
-        const entry = fresh.platforms[cfg.platform];
-        if (!entry || entry.appId === result.public_id) return false;
-        entry.appId = result.public_id;
-        return true;
-      });
+      const localNow = loadLocalDevConfig(process.cwd());
+      const localApp = localNow.platforms?.[cfg.platform];
+      if (localApp?.appId !== void 0) {
+        const committedApp = loadDevConfig(process.cwd())?.platforms?.[cfg.platform]?.appId;
+        if (result.public_id === committedApp) delete localApp.appId;
+        else localApp.appId = result.public_id;
+        saveLocalDevConfig(process.cwd(), localNow);
+      } else {
+        updateDevConfig(process.cwd(), cfg.platform, (fresh) => {
+          const entry = fresh.platforms[cfg.platform];
+          if (!entry || entry.appId === result.public_id) return false;
+          entry.appId = result.public_id;
+          return true;
+        });
+      }
     } catch (err) {
       const message = err.message;
       console.error(chalk4.red(`error: ${message}`));
@@ -2824,7 +2976,7 @@ async function runDevInProcess(opts) {
       const captureMetroLine = (line) => {
         try {
           if (!metroLogStream) {
-            mkdirSync3(dirname4(metroLogPath(process.cwd())), { recursive: true });
+            mkdirSync4(dirname4(metroLogPath(process.cwd())), { recursive: true });
             metroLogStream = createWriteStream(metroLogPath(process.cwd()), { flags: "w" });
           }
           metroLogStream.write(line.replace(/^\[metro\] /, "") + "\n");
@@ -3807,7 +3959,7 @@ function agentExitCode(env) {
 }
 
 // src/commands/agent.ts
-import { writeFileSync as writeFileSync5 } from "fs";
+import { writeFileSync as writeFileSync6 } from "fs";
 var REF_RE = /^@?(e\d+)$/;
 var COORDS_RE = /^(-?\d+),\s*(-?\d+)$/;
 var FlagError = class extends Error {
@@ -4017,7 +4169,7 @@ async function runAgentVerb(cmd, positionals, opts) {
 `);
       process.exit(1);
     }
-    writeFileSync5(outPath, imageBytes);
+    writeFileSync6(outPath, imageBytes);
     if (opts.json) {
       console.log(JSON.stringify(envelope));
     } else {
@@ -4040,8 +4192,10 @@ export {
   DEV_PLATFORMS,
   PLATFORM_NEEDS_METRO,
   isDevPlatform,
+  platformLabel,
   platformWithArticle,
   loadDevConfig,
+  resolveMetro,
   parseBuildId,
   checkDevBuild,
   buildRows,
@@ -4052,6 +4206,8 @@ export {
   readMetroState,
   killOwnedMetro,
   checkMetro,
+  loadLocalDevConfig,
+  effectiveDevConfig,
   buildCommand,
   formatDuration,
   BUILD_TERMINAL_STATUSES,

package/dist/{chunk-PBMB6TG4.js → chunk-ZZK7YQSP.js}

@@ -74,6 +74,25 @@ var AuthError = class extends Error {
     this.name = "AuthError";
   }
 };
+var TokenScopeError = class extends AuthError {
+  constructor(message) {
+    super(message);
+    this.name = "TokenScopeError";
+  }
+};
+var SCOPE_REFUSAL_PREFIX = "This API token has the 'ci' scope";
+function credentialError(status, text) {
+  const detail = extractDetail(text);
+  if (status === 401) {
+    return detail && /expired/i.test(detail) ? new AuthError(detail) : new AuthError();
+  }
+  if (status === 403 && detail?.startsWith(SCOPE_REFUSAL_PREFIX)) {
+    return new TokenScopeError(
+      `${detail} Set VIBEVIEW_API_TOKEN (or --token) to a full-access token for this command.`
+    );
+  }
+  return void 0;
+}
 function errorExitCode(err, otherwise = 1) {
   return err instanceof AuthError ? 2 : otherwise;
 }
@@ -168,7 +187,8 @@ var ApiClient = class {
     });
     if (!resp.ok) {
       const text = await resp.text().catch(() => "");
-      if (resp.status === 401) throw new AuthError();
+      const credErr = credentialError(resp.status, text);
+      if (credErr) throw credErr;
       if (resp.status === 404) throw new NotFoundError(`Not found: ${extractDetail(text) ?? path}`);
       throw new ApiStatusError(
         resp.status,
@@ -197,7 +217,9 @@ var ApiClient = class {
       device_category: options?.device ? void 0 : options?.deviceCategory,
       device_id: options?.device,
       build_id: options?.build,
-      metadata: options?.metadata
+      metadata: options?.metadata,
+      platform: options?.platform,
+      app_id: options?.app
     });
   }
   async runTest(testId, options) {
@@ -210,7 +232,9 @@ var ApiClient = class {
       device_category: options?.device ? void 0 : options?.deviceCategory,
       device_id: options?.device,
       build_id: options?.build,
-      metadata: options?.metadata
+      metadata: options?.metadata,
+      platform: options?.platform,
+      app_id: options?.app
     });
   }
   /** Cancel a still-queued CI run by its queue entry id. Idempotent best-effort. */
@@ -244,7 +268,8 @@ var ApiClient = class {
     });
     if (!resp.ok) {
       const text = await resp.text().catch(() => "");
-      if (resp.status === 401) throw new AuthError();
+      const credErr = credentialError(resp.status, text);
+      if (credErr) throw credErr;
       if (resp.status === 404) throw new NotFoundError(`Not found: ${extractDetail(text) ?? path}`);
       throw new ApiStatusError(
         resp.status,
@@ -267,7 +292,8 @@ var ApiClient = class {
     });
     if (!resp.ok) {
       const text = await resp.text().catch(() => "");
-      if (resp.status === 401) throw new AuthError();
+      const credErr = credentialError(resp.status, text);
+      if (credErr) throw credErr;
       if (resp.status === 404) throw new NotFoundError(`Not found: ${extractDetail(text) ?? path}`);
       throw new ApiStatusError(
         resp.status,
@@ -429,7 +455,8 @@ var ApiClient = class {
     const resp = await this.fetchOrExplain(url, { method: "GET", headers });
     if (!resp.ok) {
       const text = await resp.text().catch(() => "");
-      if (resp.status === 401) throw new AuthError();
+      const credErr = credentialError(resp.status, text);
+      if (credErr) throw credErr;
       if (resp.status === 404)
         throw new NotFoundError(`Not found: ${extractDetail(text) ?? `/builds/${id}/artifact`}`);
       throw new ApiStatusError(

package/dist/cli.js

@@ -15,6 +15,7 @@ import {
   listBuilds,
   loadDevConfig,
   newTransitionState,
+  platformLabel,
   platformWithArticle,
   pressButtonsHelp,
   printOutcomeLine,
@@ -22,7 +23,7 @@ import {
   readDevState,
   readMetroState,
   runAgentVerb
-} from "./chunk-T6EQQV6E.js";
+} from "./chunk-NOZGZT3G.js";
 import {
   ApiClient,
   ApiStatusError,
@@ -43,7 +44,7 @@ import {
   resolveAuth,
   saveConfig,
   uploadApp
-} from "./chunk-PBMB6TG4.js";
+} from "./chunk-ZZK7YQSP.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -570,6 +571,29 @@ function mapExitCode(status) {
   return EXIT_INFRA_ERROR;
 }
 
+// src/lib/run-target.ts
+var RUN_PLATFORMS = ["ios", "android", "tvos", "androidtv"];
+function parseRunPlatform(value) {
+  if (value === void 0) return void 0;
+  if (!RUN_PLATFORMS.includes(value)) {
+    throw new Error(`--platform must be one of ${RUN_PLATFORMS.join(", ")}, got "${value}"`);
+  }
+  return value;
+}
+function describeRunTarget(response, options) {
+  const asked = Boolean(options.platform || options.app);
+  if (!response.app_id) {
+    if (asked) {
+      throw new Error(
+        "this VibeView server does not support --platform/--app on test runs yet; the run was stopped rather than run on the test\u2019s own platform"
+      );
+    }
+    return null;
+  }
+  if (!asked) return null;
+  return `${response.app_id} (${platformLabel(response.platform ?? "")})`;
+}
+
 // src/commands/run-suite.ts
 async function runSuite(suiteId, options) {
   const { token, baseUrl } = resolveAuth(options);
@@ -635,14 +659,18 @@ ${signal} received.
       deviceCategory: options.deviceCategory,
       device: options.device,
       build: options.build,
-      metadata: options.metadata
+      metadata: options.metadata,
+      platform: options.platform,
+      app: options.app
     });
     sessionId = response.session_id;
     runId = response.run_id;
+    const target = describeRunTarget(response, options);
     spinner.stop();
     process.stderr.write(
       `${chalk3.dim("Suite:")} ${suiteId}
-${chalk3.dim("Run:")} ${response.run_id}
+` + (target ? `${chalk3.dim("App:")} ${target}
+` : "") + `${chalk3.dim("Run:")} ${response.run_id}
 ` + (sessionId ? `${chalk3.dim("Session:")} ${sessionId}
 ` : "")
     );
@@ -1009,16 +1037,20 @@ ${signal} received.
       deviceCategory: options.deviceCategory,
       device: options.device,
       build: options.build,
-      metadata: options.metadata
+      metadata: options.metadata,
+      platform: options.platform,
+      app: options.app
     });
     sessionId = response.session_id;
     runId = response.run_id;
+    const target = describeRunTarget(response, options);
     spinner.stop();
     process.stderr.write(
       `${chalk5.dim("Session:")} ${sessionId || "unknown"}
 ${chalk5.dim("Device:")} ${response.device_name || "allocating..."}
 ${chalk5.dim("Test:")} ${testId}
-${chalk5.dim("Run:")} ${response.run_id}
+` + (target ? `${chalk5.dim("App:")} ${target}
+` : "") + `${chalk5.dim("Run:")} ${response.run_id}
 `
     );
     spinner.start("Waiting for device...");
@@ -3568,11 +3600,24 @@ program.command("run-suite <suite-id>").description("Run all test cases in a sui
 ).option(
   "--device <device_id>",
   "Pin run to a specific device (use `vibeview list-devices` to find one). Conflicts with --device-category."
+).option(
+  "--platform <platform>",
+  "Run the suite on another platform (ios, android, tvos, androidtv): runs your app there with the same bundle id / package"
+).option(
+  "--app <app-id>",
+  "Run the suite against this app instead of its own (e.g. another platform build with a different bundle id)"
 ).option("--build <id>", "Specific AppBuild id to run against (defaults to latest)").option("--metadata <json>", "JSON object passed through to webhooks (e.g. PR context)").option("--metadata-file <path>", "Read JSON object from a file (use for nested JSON in CI)").action((suiteId, opts) => {
   if (opts.device && opts.deviceCategory) {
     process.stderr.write("error: --device cannot be combined with --device-category\n");
     process.exit(2);
   }
+  try {
+    parseRunPlatform(opts.platform);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}
+`);
+    process.exit(2);
+  }
   const metadata = resolveMetadata(opts);
   return runSuite(suiteId, {
     ...opts,
@@ -3601,6 +3646,13 @@ program.command("run-suites").description("Run all suites matching a tag filter"
     process.stderr.write("error: --device cannot be combined with --device-category\n");
     process.exit(2);
   }
+  try {
+    parseRunPlatform(opts.platform);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}
+`);
+    process.exit(2);
+  }
   const metadata = resolveMetadata(opts);
   return runSuites({
     ...opts,
@@ -3616,11 +3668,24 @@ program.command("run-test <test-id>").description("Run a single test case").opti
 ).option(
   "--device <device_id>",
   "Pin run to a specific device (use `vibeview list-devices` to find one). Conflicts with --device-category."
+).option(
+  "--platform <platform>",
+  "Run the test on another platform (ios, android, tvos, androidtv): runs your app there with the same bundle id / package"
+).option(
+  "--app <app-id>",
+  "Run the test against this app instead of its own (e.g. another platform build with a different bundle id)"
 ).option("--build <id>", "Specific AppBuild id to run against (defaults to latest)").option("--metadata <json>", "JSON object passed through to webhooks (e.g. PR context)").option("--metadata-file <path>", "Read JSON object from a file (use for nested JSON in CI)").action((testId, opts) => {
   if (opts.device && opts.deviceCategory) {
     process.stderr.write("error: --device cannot be combined with --device-category\n");
     process.exit(2);
   }
+  try {
+    parseRunPlatform(opts.platform);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}
+`);
+    process.exit(2);
+  }
   const metadata = resolveMetadata(opts);
   return runTest(testId, {
     ...opts,
@@ -3669,7 +3734,10 @@ program.command("dev").description(
 ).option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").option("--web-url <url>", "Dashboard URL if different from the API URL (local dev)").option(
   "--platform <platform>",
   "ios, android, tvos, androidtv, or roku (first run is interactive otherwise)"
-).option("--app <app_id>", "Uploaded debug build to run (see `vibeview list-apps`)").option("--metro-port <port>", "Local Metro port (default: 8081, remembered in vibeview.json)").option(
+).option("--app <app_id>", "Uploaded debug build to run (see `vibeview list-apps`)").option(
+  "--metro-port <port>",
+  "Local Metro port (default: 8081, or vibeview.json); remembered for you in .vibeview/local.json"
+).option(
   "--device-category <category>",
   "phone or tablet (default: phone; TV platforms always use tv)",
   parseDeviceCategory
@@ -3831,7 +3899,7 @@ program.command("dev-reload").description(
 program.command("mcp").description(
   "Run an MCP stdio server exposing the agent verbs (tap, swipe, type, ...) plus dev_start/dev_stop/dev_reload as tools"
 ).option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").action(async (opts) => {
-  const { runMcpServer } = await import("./server-IGY2VPYT.js");
+  const { runMcpServer } = await import("./server-2JNYWF5L.js");
   await runMcpServer({ ...opts, version: pkg.version });
 });
 program.command("agent-setup").description(

package/dist/{server-IGY2VPYT.js → server-2JNYWF5L.js}

@@ -11,22 +11,25 @@ import {
   checkMetro,
   createRokuPush,
   decodeScreenshotResult,
+  effectiveDevConfig,
   filterDeviceModels,
   formatBuildRowsHuman,
   formatDeviceModelsHuman,
   isDevPlatform,
   loadDevConfig,
+  loadLocalDevConfig,
   parseBuildId,
   platformWithArticle,
   readDevState,
   renderEnvelope,
+  resolveMetro,
   startDevSession
-} from "./chunk-T6EQQV6E.js";
+} from "./chunk-NOZGZT3G.js";
 import {
   ApiClient,
   NotFoundError,
   resolveAuth
-} from "./chunk-PBMB6TG4.js";
+} from "./chunk-ZZK7YQSP.js";
 
 // src/mcp/server.ts
 import { writeFileSync } from "fs";
@@ -539,7 +542,7 @@ async function handleUploadApp(args, deps) {
   }
   const name = typeof args.name === "string" && args.name ? args.name : void 0;
   const upload = deps.uploadApp ?? (async (f, n) => {
-    const { uploadAppBuild } = await import("./upload-app-FEZG23NU.js");
+    const { uploadAppBuild } = await import("./upload-app-2LVG4LMB.js");
     const { result: result2 } = await uploadAppBuild(f, { ...deps.auth, name: n });
     return result2;
   });
@@ -624,6 +627,7 @@ function createDevSessionController(auth, webUrl) {
       } catch {
         devConfig = null;
       }
+      devConfig = effectiveDevConfig(devConfig, loadLocalDevConfig(process.cwd()));
       const entry = devConfig?.platforms?.[cfg.platform];
       const appId = cfg.app || entry?.appId;
       if (!appId) {
@@ -649,7 +653,7 @@ function createDevSessionController(auth, webUrl) {
       }
       const standalone = cfg.standalone === true;
       const usesMetro = PLATFORM_NEEDS_METRO[cfg.platform] && !standalone;
-      const metroPort = cfg.metroPort ?? devConfig?.metroPort ?? 8081;
+      const metroPort = resolveMetro(devConfig, cfg.platform, cfg.metroPort).port;
       if (usesMetro) {
         const metro = await checkMetro(metroPort);
         if (metro === "down") {

package/dist/{upload-app-FEZG23NU.js → upload-app-2LVG4LMB.js}

@@ -3,7 +3,7 @@ import {
   describeBuild,
   uploadApp,
   uploadAppBuild
-} from "./chunk-PBMB6TG4.js";
+} from "./chunk-ZZK7YQSP.js";
 export {
   describeBuild,
   uploadApp,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeview",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "VibeView CLI -- run your app on cloud iOS simulators, Android emulators, Apple TV, Android TV and Roku (beta) devices: a React Native dev loop, device control for you or your coding agent (CLI or MCP), and tests from CI",
   "mcpName": "io.github.vibeview/vibeview",
   "type": "module",

package/skills/vibeview-agent/SKILL.md

@@ -64,11 +64,15 @@ https://vibeview.io/docs/preparing-your-build.
    the page is `https://vibeview.io/sandbox/<session_id>`.)
 
 Running `dev` writes two things into the project root: a `.vibeview/`
-directory (live session state — local machine state, never commit) and a
-`vibeview.json` (your platform/app/build choices, which teammates DO want).
-Make sure `.vibeview/` is in the project's `.gitignore`, adding it if
-missing. Leave `vibeview.json` tracked, but tell the developer you created
-it rather than letting it appear unexplained in their `git status`.
+directory (live session state, plus `local.json` with this developer's own
+flag overrides such as `--metro-port` — local machine state, never commit)
+and a `vibeview.json` (the platform/app/build setup, which teammates DO
+want). Flags never rewrite a value `vibeview.json` already has; they are
+saved to `.vibeview/local.json` instead, and the CLI prints what it saved.
+Make sure the project's `.gitignore` has `.vibeview/*` and
+`!.vibeview/test-spec.json`, adding them if missing. Leave `vibeview.json`
+tracked, but tell the developer you created it rather than letting it
+appear unexplained in their `git status`.
 
 ## 3. Verifying