vibeview 0.23.0 → 0.25.0

package/dist/{chunk-E2LZSLRF.js → chunk-GEKYHEWU.js}

@@ -6,7 +6,99 @@ import {
   loadConfig,
   resolveAuth,
   uploadAppBuild
-} from "./chunk-PSFXVUHG.js";
+} from "./chunk-RFFCCPGZ.js";
+
+// src/lib/dev-build.ts
+function parseBuildId(raw) {
+  const text = typeof raw === "number" ? String(raw) : typeof raw === "string" ? raw.trim() : "";
+  if (!/^\d+$/.test(text) || Number(text) < 1) {
+    throw new Error(
+      `--build expects a build id (a positive number, see \`vibeview list-builds <app>\`), got "${String(raw)}"`
+    );
+  }
+  return Number(text);
+}
+function buildKind(isDebug) {
+  if (isDebug === true) return "debug";
+  if (isDebug === false) return "release";
+  return "unknown";
+}
+function checkDevBuild(app, buildId, platform) {
+  if (platform === "roku") {
+    throw new Error(
+      "a build id cannot be pinned on roku \u2014 `vibeview dev` packages and sideloads the channel itself"
+    );
+  }
+  if (app.platform !== platform) {
+    throw new Error(`app ${app.public_id} is a ${app.platform} app, not ${platform}`);
+  }
+  const build = app.builds.find((b) => b.id === buildId);
+  if (!build) {
+    throw new Error(
+      `build ${buildId} is not a build of app ${app.public_id} \u2014 see \`vibeview list-builds ${app.public_id}\``
+    );
+  }
+  if (build.is_debug !== true) {
+    const why = build.is_debug === false ? "it runs standalone (a release build, or one with an embedded JS bundle)" : "it could not be identified as a Metro debug build";
+    throw new Error(
+      `build ${buildId} is not a debug build \u2014 ${why}. \`vibeview dev\` needs a ${platform} debug simulator/emulator build without an embedded JS bundle (see \`vibeview list-builds ${app.public_id}\`)`
+    );
+  }
+  return build;
+}
+
+// src/commands/list-builds.ts
+import chalk from "chalk";
+function buildRows(app) {
+  return app.builds.map((b) => ({
+    id: b.id,
+    version: b.version ?? null,
+    build_number: b.build_number ?? null,
+    platform: app.platform,
+    kind: buildKind(b.is_debug),
+    is_debug: b.is_debug ?? null,
+    uploaded_at: b.uploaded_at ?? null,
+    note: b.note ?? null
+  }));
+}
+var HEADERS = ["ID", "VERSION", "PLATFORM", "KIND", "UPLOADED", "NOTE"];
+function formatBuildRowsHuman(app, rows) {
+  if (rows.length === 0) {
+    return `No builds uploaded for ${app.name} (${app.public_id}) \u2014 upload one with \`vibeview upload-app\`.
+`;
+  }
+  const cells = rows.map((r) => [
+    String(r.id),
+    r.version ? `${r.version}${r.build_number ? ` (${r.build_number})` : ""}` : r.build_number ?? "",
+    r.platform,
+    r.kind,
+    r.uploaded_at ?? "",
+    (r.note ?? "").split("\n")[0]
+  ]);
+  const widths = HEADERS.map((h, i) => Math.max(h.length, ...cells.map((c) => c[i].length)));
+  const pad = (row) => row.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+  const lines = [chalk.bold(pad(HEADERS)), ...cells.map(pad)];
+  return lines.join("\n") + "\n";
+}
+async function listBuilds(appId, opts, deps) {
+  const { token, baseUrl } = resolveAuth(opts);
+  const d = deps ?? { getApp: (id) => new ApiClient(baseUrl, token).getApp(id) };
+  try {
+    const app = await d.getApp(appId);
+    const rows = buildRows(app);
+    if (opts.json) {
+      console.log(JSON.stringify(rows, null, 2));
+    } else {
+      process.stdout.write(formatBuildRowsHuman(app, rows));
+    }
+    process.exitCode = 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) console.log(JSON.stringify({ event: "error", message }));
+    console.error(chalk.red(`error: ${message}`));
+    process.exitCode = 1;
+  }
+}
 
 // src/lib/dev-state.ts
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
@@ -267,7 +359,7 @@ async function checkMetro(port, timeoutMs = 1500) {
 import { spawn as spawn2 } from "child_process";
 import { createInterface } from "readline";
 import { select as select2 } from "@inquirer/prompts";
-import chalk2 from "chalk";
+import chalk3 from "chalk";
 
 // src/lib/artifact.ts
 import { existsSync as existsSync2, mkdtempSync, readdirSync, rmSync as rmSync2, statSync } from "fs";
@@ -327,7 +419,7 @@ function prepareUploadArtifact(path) {
 }
 
 // src/lib/dev-setup.ts
-import chalk from "chalk";
+import chalk2 from "chalk";
 import { input, select } from "@inquirer/prompts";
 
 // src/lib/project-detect.ts
@@ -556,7 +648,7 @@ async function promptBuildConfig(cwd, platform) {
     return { command: defaults.buildCommand, artifact: defaults.artifact };
   }
   console.log(
-    chalk.dim(
+    chalk2.dim(
       "  Tip: include your install step \u2014 dependencies are not uploaded.\n       e.g. `yarn install --immutable && yarn build:android`"
     )
   );
@@ -582,7 +674,7 @@ async function promptProductionBuildConfig(cwd, platform) {
     };
   }
   console.log(
-    chalk.dim(
+    chalk2.dim(
       "  Tip: include your install step \u2014 dependencies are not uploaded.\n       e.g. `yarn install --immutable && cd android && ./gradlew bundleRelease`"
     )
   );
@@ -831,7 +923,7 @@ function runShell(command, cwd, log) {
 }
 async function resolveBarePlatform(cwd, cfg, opts) {
   if (opts.platform && !isDevPlatform(opts.platform)) {
-    console.error(chalk2.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}`));
+    console.error(chalk3.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}`));
     process.exit(2);
   }
   let platform = opts.platform || cfg?.defaultPlatform;
@@ -946,9 +1038,9 @@ async function buildCommand(opts, cloudDeps) {
       platform,
       build,
       opts,
-      (l) => console.error(chalk2.dim(l))
+      (l) => console.error(chalk3.dim(l))
     );
-    for (const w of result.warnings ?? []) console.error(chalk2.yellow(`\u26A0 ${w}`));
+    for (const w of result.warnings ?? []) console.error(chalk3.yellow(`\u26A0 ${w}`));
     persistUploadedAppId(cwd, cfg, platform, build, result.public_id);
     if (opts.json) {
       console.log(
@@ -956,8 +1048,8 @@ async function buildCommand(opts, cloudDeps) {
       );
     } else {
       console.error(
-        chalk2.green(`\u2713 built and uploaded ${result.name}`) + `
-  ${chalk2.cyan(result.public_id)}  ${chalk2.dim(`[${result.platform}]`)}`
+        chalk3.green(`\u2713 built and uploaded ${result.name}`) + `
+  ${chalk3.cyan(result.public_id)}  ${chalk3.dim(`[${result.platform}]`)}`
       );
     }
   } catch (err) {
@@ -969,7 +1061,7 @@ async function buildCommand(opts, cloudDeps) {
 }
 function printFailure(opts, message, code) {
   if (opts.json) console.log(JSON.stringify({ event: "error", code, message }));
-  console.error(chalk2.red(`error: ${message}`));
+  console.error(chalk3.red(`error: ${message}`));
 }
 function fail(opts, message, code) {
   printFailure(opts, message, code);
@@ -992,7 +1084,7 @@ async function resolveCloudPlatforms(cwd, cfgRef, opts) {
           for (const p of unsupported) {
             const reason = productionUnsupportedReason(p);
             emitCloud(opts.json, { event: "skipped", platform: p, reason });
-            if (!opts.json) console.error(chalk2.yellow(`\u26A0 skipping ${p}: ${reason}`));
+            if (!opts.json) console.error(chalk3.yellow(`\u26A0 skipping ${p}: ${reason}`));
           }
           chosenPlatforms = chosenPlatforms.filter((p) => !unsupported.includes(p));
         }
@@ -1033,7 +1125,7 @@ async function resolveCloudPlatforms(cwd, cfgRef, opts) {
 function validateExplicitPlatform(raw) {
   if (!isDevPlatform(raw)) {
     console.error(
-      chalk2.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}, or "all"`)
+      chalk3.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}, or "all"`)
     );
     process.exit(2);
   }
@@ -1093,7 +1185,7 @@ async function resolveCloudAppIds(cwd, cfgRef, platforms, opts, listApps) {
       createFromArtifact.add(platform);
       if (!opts.json) {
         console.error(
-          chalk2.dim(
+          chalk3.dim(
             opts.production ? `no ${platform} apps yet \u2014 production builds aren't linked to an app; the signed artifact will be available from the build itself` : `no ${platform} apps yet \u2014 this build will create one from the artifact`
           )
         );
@@ -1270,7 +1362,7 @@ ${offenders}`);
       const autoIncrement = build.autoIncrement === true;
       if (autoIncrement && !production && !opts.json) {
         console.error(
-          chalk2.yellow(
+          chalk3.yellow(
             `note: platforms.${p}.build.autoIncrement only applies to production builds (--production) \u2014 ignoring it for this simulator build`
           )
         );
@@ -1307,7 +1399,7 @@ ${offenders}`);
     }
     if (!opts.json) {
       for (const b of created) {
-        console.error(`  ${chalk2.cyan(b.id)}  ${chalk2.dim(`[${b.platform}]`)}`);
+        console.error(`  ${chalk3.cyan(b.id)}  ${chalk3.dim(`[${b.platform}]`)}`);
       }
     }
     const shouldWait = opts.wait !== false || opts.download;
@@ -1332,7 +1424,7 @@ ${offenders}`);
             path: result.path
           });
           if (!opts.json) {
-            console.error(chalk2.green(`\u2713 saved ${result.filename}`));
+            console.error(chalk3.green(`\u2713 saved ${result.filename}`));
           }
         } catch (err) {
           downloadFailed = true;
@@ -1341,7 +1433,7 @@ ${offenders}`);
             event: "error",
             message: `error downloading ${b.id}: ${message}`
           });
-          if (!opts.json) console.error(chalk2.red(`error downloading ${b.id}: ${message}`));
+          if (!opts.json) console.error(chalk3.red(`error downloading ${b.id}: ${message}`));
         }
       }
     }
@@ -1398,7 +1490,7 @@ async function waitForCloudBuilds(builds, opts, deps) {
   const giveUpLocally = (id, message) => {
     abandoned.add(id);
     emitCloud(opts.json, { event: "error", message });
-    if (!opts.json) console.error(chalk2.red(message));
+    if (!opts.json) console.error(chalk3.red(message));
   };
   const pollAndProcess = async (build) => {
     const offset = offsets.get(build.id) ?? 0;
@@ -1559,21 +1651,21 @@ function printTransition(id, platform, status, state, json, printLine) {
     if (json) {
       emitCloud(json, { event: "status", id, status: "queued" });
     } else {
-      printLine(id, platform, chalk2.dim("\u23F3 queued \u2014 waiting for a build slot"));
+      printLine(id, platform, chalk3.dim("\u23F3 queued \u2014 waiting for a build slot"));
     }
   } else if (status === "running" && !state.printedRunning) {
     state.printedRunning = true;
     if (json) {
       emitCloud(json, { event: "status", id, status: "running" });
     } else {
-      printLine(id, platform, `${chalk2.cyan("\u25B6")} building`);
+      printLine(id, platform, `${chalk3.cyan("\u25B6")} building`);
     }
   }
 }
 function printOutcomeLine(build, multi) {
   const prefix = multi ? `[${build.platform}] ` : "";
   const ok = build.status === "succeeded";
-  const mark = ok ? chalk2.green("\u2713") : chalk2.red("\u2717");
+  const mark = ok ? chalk3.green("\u2713") : chalk3.red("\u2717");
   const duration = formatDuration(build.started_at, build.finished_at);
   let line = `${prefix}${mark} ${build.status}`;
   if (duration) line += ` (${duration})`;
@@ -1620,7 +1712,7 @@ import { createWriteStream, mkdirSync as mkdirSync3 } from "fs";
 import { dirname as dirname5 } from "path";
 import { createInterface as createInterface3 } from "readline";
 import { select as select3 } from "@inquirer/prompts";
-import chalk3 from "chalk";
+import chalk4 from "chalk";
 import openBrowser from "open";
 
 // src/lib/tunnel-client.ts
@@ -1646,6 +1738,26 @@ function decodeFrame(data) {
   return { type, streamId: data.readUInt32BE(1), payload: data.subarray(HEADER_LEN) };
 }
 
+// src/lib/redact.ts
+var SECRET_PARAMS = /* @__PURE__ */ new Set([
+  "token",
+  "access_token",
+  "refresh_token",
+  "api_key",
+  "apikey",
+  "key",
+  "secret",
+  "signature",
+  "sig",
+  "jwt"
+]);
+function redactSecrets(text) {
+  return text.replace(
+    /\b([A-Za-z_]+)=([^&\s"'#]+)/g,
+    (match, name) => SECRET_PARAMS.has(name.toLowerCase()) ? `${name}=[redacted]` : match
+  );
+}
+
 // src/lib/tunnel-client.ts
 var FATAL_CLOSE_CODES = /* @__PURE__ */ new Set([4008, 4009]);
 var MAX_BACKOFF_MS = 8e3;
@@ -1665,7 +1777,7 @@ var TunnelClient = class {
   url;
   connCount = 0;
   debug(msg) {
-    this.opts.onDebug?.(msg);
+    this.opts.onDebug?.(redactSecrets(msg));
   }
   start() {
     this.connect();
@@ -2158,7 +2270,8 @@ function devSessionCreateBody(cfg) {
     app_id: cfg.appId,
     // Roku has no JS bundle to serve, so there is nothing to tunnel.
     tunnel: PLATFORM_NEEDS_METRO[cfg.platform],
-    ...cfg.model ? { model: cfg.model } : {}
+    ...cfg.model ? { model: cfg.model } : {},
+    ...cfg.buildId ? { build_id: cfg.buildId } : {}
   };
 }
 function resolveDeviceModel(pools, platform, model) {
@@ -2292,7 +2405,7 @@ function requireNonInteractive(json) {
 async function ensureConfig(api, opts) {
   const existing = loadDevConfig(process.cwd());
   if (opts.platform && !isDevPlatform(opts.platform)) {
-    console.error(chalk3.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}`));
+    console.error(chalk4.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}`));
     process.exit(2);
   }
   if (!opts.platform && !existing?.defaultPlatform) {
@@ -2305,21 +2418,21 @@ async function ensureConfig(api, opts) {
   const isTv = PLATFORM_DEVICE[platform].tv;
   if (isTv && opts.deviceCategory) {
     console.error(
-      chalk3.red(`error: --device-category does not apply to ${platform} (always a tv device)`)
+      chalk4.red(`error: --device-category does not apply to ${platform} (always a tv device)`)
     );
     process.exit(2);
   }
   if (!isTv && opts.deviceCategory === "tv") {
-    console.error(chalk3.red(`error: use --platform tvos or --platform androidtv for TV devices`));
+    console.error(chalk4.red(`error: use --platform tvos or --platform androidtv for TV devices`));
     process.exit(2);
   }
   if (opts.model !== void 0 && opts.deviceCategory) {
-    console.error(chalk3.red("error: pass --model or --device-category, not both"));
+    console.error(chalk4.red("error: pass --model or --device-category, not both"));
     process.exit(2);
   }
   if (opts.model !== void 0 && !opts.model.trim()) {
     console.error(
-      chalk3.red("error: --model needs a model name (see `vibeview list-devices --models`)")
+      chalk4.red("error: --model needs a model name (see `vibeview list-devices --models`)")
     );
     process.exit(2);
   }
@@ -2343,7 +2456,7 @@ async function ensureConfig(api, opts) {
     allApps = await api.listApps();
   } catch (err) {
     const message = `could not fetch your app list \u2014 ${err instanceof Error ? err.message : String(err)}`;
-    console.error(chalk3.red(`error: ${message}`));
+    console.error(chalk4.red(`error: ${message}`));
     emit(opts.json, { event: "error", message });
     process.exit(1);
   }
@@ -2352,7 +2465,7 @@ async function ensureConfig(api, opts) {
   if (choice.staleFlag) {
     const message = `app "${choice.staleFlag}" not found \u2014 it may have been deleted.`;
     console.error(
-      chalk3.red(`error: ${message}`) + `
+      chalk4.red(`error: ${message}`) + `
 Run \`vibeview dev\` without --app to pick from the list.`
     );
     emit(opts.json, { event: "error", message });
@@ -2362,12 +2475,12 @@ Run \`vibeview dev\` without --app to pick from the list.`
   let builtThisRun = false;
   if (choice.staleCached) {
     console.error(
-      chalk3.yellow(`\u26A0 app "${choice.staleCached}" no longer exists \u2014 pick your debug build again`)
+      chalk4.yellow(`\u26A0 app "${choice.staleCached}" no longer exists \u2014 pick your debug build again`)
     );
   }
   const buildConfig = firstRunBuild ?? entry?.build ?? null;
-  if (!appId && buildConfig) {
-    const strategy = buildAppStrategy(apps, Boolean(opts.build), opts.json, process.stdin.isTTY);
+  if (!appId && buildConfig && typeof opts.build !== "string") {
+    const strategy = buildAppStrategy(apps, opts.build === true, opts.json, process.stdin.isTTY);
     let action = strategy === "ask" ? "pick" : strategy;
     if (strategy === "ask") {
       action = await select3({
@@ -2379,20 +2492,20 @@ Run \`vibeview dev\` without --app to pick from the list.`
       });
     }
     if (action === "build") {
-      console.error(chalk3.dim(`Building ${platform}...`));
+      console.error(chalk4.dim(`Building ${platform}...`));
       try {
         const result = await runBuildForPlatform(
           process.cwd(),
           platform,
           buildConfig,
           opts,
-          (l) => console.error(chalk3.dim(l))
+          (l) => console.error(chalk4.dim(l))
         );
         appId = result.public_id;
         builtThisRun = true;
       } catch (err) {
         const message = err.message;
-        console.error(chalk3.red(`error: ${message}`));
+        console.error(chalk4.red(`error: ${message}`));
         emit(opts.json, { event: "error", message });
         process.exit(1);
       }
@@ -2401,20 +2514,20 @@ Run \`vibeview dev\` without --app to pick from the list.`
   if (!appId) {
     if (apps.length === 0) {
       const message = noAppsMessage(platform, entry?.build !== void 0);
-      console.error(chalk3.red(message));
+      console.error(chalk4.red(message));
       emit(opts.json, { event: "error", code: "no_apps", message });
       process.exit(1);
     }
     if (choice.staleCached) {
       const message = `app "${choice.staleCached}" for ${platform} no longer exists \u2014 pass --app <id> (see \`vibeview list-apps\`) or run interactively to pick one.`;
-      console.error(chalk3.red(`error: ${message}`));
+      console.error(chalk4.red(`error: ${message}`));
       emit(opts.json, { event: "error", code: "app_deleted", message });
       process.exit(1);
     }
     requireNonInteractive(opts.json);
     if (!process.stdin.isTTY) {
       console.error(
-        chalk3.red(
+        chalk4.red(
           `error: no valid app configured for ${platform} \u2014 run interactively to pick one, or pass --app <id>`
         )
       );
@@ -2450,7 +2563,7 @@ Run \`vibeview dev\` without --app to pick from the list.`
       { build: !firstRunBuild, metro: PLATFORM_NEEDS_METRO[platform] && !firstRunMetro },
       platform
     );
-    if (hint) console.error(chalk3.dim(hint));
+    if (hint) console.error(chalk4.dim(hint));
   }
   const finalMetro = isFirstRun ? resolveMetro(cfg, platform, opts.metroPort ? parseInt(opts.metroPort, 10) : void 0) : metroResolved;
   return {
@@ -2470,10 +2583,21 @@ async function runDevInProcess(opts) {
     watchSeconds = parseWatchSeconds(opts.watch);
   } catch (err) {
     const message = err.message;
-    console.error(chalk3.red(`error: ${message}`));
+    console.error(chalk4.red(`error: ${message}`));
     emit(opts.json, { event: "error", code: "invalid_flag", message });
     process.exit(2);
   }
+  let pinnedBuildId;
+  if (typeof opts.build === "string") {
+    try {
+      pinnedBuildId = parseBuildId(opts.build);
+    } catch (err) {
+      const message = err.message;
+      console.error(chalk4.red(`error: ${message}`));
+      emit(opts.json, { event: "error", code: "invalid_flag", message });
+      process.exit(2);
+    }
+  }
   if (opts.json) {
     const hasToken = !!(opts.token || process.env.VIBEVIEW_API_TOKEN || loadConfig().token);
     if (!hasToken) {
@@ -2486,26 +2610,36 @@ async function runDevInProcess(opts) {
     }
   }
   const { token, baseUrl } = resolveAuth(opts);
-  console.error(chalk3.dim(`Using ${baseUrl}`));
+  console.error(chalk4.dim(`Using ${baseUrl}`));
   const api = new ApiClient(baseUrl, token);
   const cfg = await ensureConfig(api, opts);
-  if (opts.build && !cfg.builtThisRun) {
+  if (pinnedBuildId !== void 0) {
+    try {
+      checkDevBuild(await api.getApp(cfg.appId), pinnedBuildId, cfg.platform);
+    } catch (err) {
+      const message = err.message;
+      console.error(chalk4.red(`error: ${message}`));
+      emit(opts.json, { event: "error", code: "invalid_build", message });
+      process.exit(1);
+    }
+  }
+  if (opts.build === true && !cfg.builtThisRun) {
     const reloaded = loadDevConfig(process.cwd());
     const build = reloaded?.platforms?.[cfg.platform]?.build;
     if (!build) {
       const message = `no build config for ${cfg.platform} \u2014 run vibeview build once to set it up`;
-      console.error(chalk3.red(`error: ${message}`));
+      console.error(chalk4.red(`error: ${message}`));
       emit(opts.json, { event: "error", code: "config_required", message });
       process.exit(1);
     }
-    console.error(chalk3.dim(`Building ${cfg.platform}...`));
+    console.error(chalk4.dim(`Building ${cfg.platform}...`));
     try {
       const result = await runBuildForPlatform(
         process.cwd(),
         cfg.platform,
         build,
         { token, baseUrl },
-        (l) => console.error(chalk3.dim(l))
+        (l) => console.error(chalk4.dim(l))
       );
       cfg.appId = result.public_id;
       if (reloaded && reloaded.platforms[cfg.platform] && reloaded.platforms[cfg.platform].appId !== result.public_id) {
@@ -2514,7 +2648,7 @@ async function runDevInProcess(opts) {
       }
     } catch (err) {
       const message = err.message;
-      console.error(chalk3.red(`error: ${message}`));
+      console.error(chalk4.red(`error: ${message}`));
       emit(opts.json, { event: "error", message });
       process.exit(1);
     }
@@ -2536,7 +2670,7 @@ async function runDevInProcess(opts) {
           metroLogStream.write(line.replace(/^\[metro\] /, "") + "\n");
         } catch {
         }
-        if (shouldEchoMetroLine(line, opts.debug === true)) console.error(chalk3.dim(line));
+        if (shouldEchoMetroLine(line, opts.debug === true)) console.error(chalk4.dim(line));
       };
       metroResult = await ensureMetro(
         process.cwd(),
@@ -2549,15 +2683,15 @@ async function runDevInProcess(opts) {
       );
     } catch (err) {
       const message = err.message;
-      console.error(chalk3.red(`error: ${message}`));
+      console.error(chalk4.red(`error: ${message}`));
       emit(opts.json, { event: "error", code: "metro_down", message });
       process.exit(1);
     }
-    for (const w of metroResult.warnings) console.error(chalk3.yellow(`\u26A0 ${w}`));
+    for (const w of metroResult.warnings) console.error(chalk4.yellow(`\u26A0 ${w}`));
     if (metroResult.status === "spawned" || metroResult.status === "respawned") {
-      console.error(chalk3.green(`\u2713 started Metro (${cfg.metroCommand})`));
+      console.error(chalk4.green(`\u2713 started Metro (${cfg.metroCommand})`));
       console.error(
-        chalk3.dim(`  full Metro output: ${metroLogPath(process.cwd())} (--debug echoes it here)`)
+        chalk4.dim(`  full Metro output: ${metroLogPath(process.cwd())} (--debug echoes it here)`)
       );
     }
     metroOwnedThisRun = metroResult.status === "spawned" || metroResult.status === "respawned";
@@ -2567,19 +2701,23 @@ async function runDevInProcess(opts) {
     watchIgnore = rokuEntry?.watchIgnore ?? [];
     if (!rokuBuild) {
       const message = `no build config for ${cfg.platform} \u2014 run \`vibeview build --platform ${cfg.platform}\` once to set it up`;
-      console.error(chalk3.red(`error: ${message}`));
+      console.error(chalk4.red(`error: ${message}`));
       emit(opts.json, { event: "error", code: "config_required", message });
       process.exit(1);
     }
   }
-  console.error(chalk3.dim(`Starting a ${cfg.platform} dev session for ${cfg.appId}...`));
+  console.error(
+    chalk4.dim(
+      `Starting a ${cfg.platform} dev session for ${cfg.appId}${pinnedBuildId !== void 0 ? ` (build ${pinnedBuildId})` : ""}...`
+    )
+  );
   let stopping = false;
   let handle = null;
   let reloadLoop = null;
   const stopSession = async (code) => {
     if (stopping) return;
     stopping = true;
-    console.error(chalk3.dim("\nStopping session..."));
+    console.error(chalk4.dim("\nStopping session..."));
     reloadLoop?.stop();
     await handle?.stop();
     if (metroOwnedThisRun) killOwnedMetro(process.cwd());
@@ -2602,6 +2740,7 @@ async function runDevInProcess(opts) {
         appId: cfg.appId,
         deviceCategory: cfg.deviceCategory,
         model: cfg.model,
+        buildId: pinnedBuildId,
         metroPort: cfg.metroPort ?? 8081,
         // startDevSession's own browser-open happens before we've written the
         // state file / emitted session_ready — open it ourselves afterward
@@ -2613,26 +2752,26 @@ async function runDevInProcess(opts) {
         if (evt.event === "warning") {
           if (nextWarningIsMetroUnreachable) {
             nextWarningIsMetroUnreachable = false;
-            console.error(chalk3.red(`\u2717 ${evt.message}`));
+            console.error(chalk4.red(`\u2717 ${evt.message}`));
           } else {
-            console.error(chalk3.yellow(`\u26A0 ${evt.message}`));
+            console.error(chalk4.yellow(`\u26A0 ${evt.message}`));
           }
         } else if (evt.event === "queued") {
           const where = evt.position ? ` (position ${evt.position})` : "";
           console.error(
-            chalk3.yellow(
+            chalk4.yellow(
               `\u23F3 every device is busy \u2014 waiting in the queue${where}, Ctrl-C to give up`
             )
           );
         } else if (evt.event === "tunnel_connected") {
           everConnected = true;
-          console.error(chalk3.green("\u2713 tunnel connected \u2014 edit away, Fast Refresh is live"));
+          console.error(chalk4.green("\u2713 tunnel connected \u2014 edit away, Fast Refresh is live"));
         } else if (evt.event === "installing") {
           console.error(
-            chalk3.dim("  Putting the channel on the Roku \u2014 the link appears once it is up.")
+            chalk4.dim("  Putting the channel on the Roku \u2014 the link appears once it is up.")
           );
         } else if (evt.event === "session_ended" && !stopping && handle) {
-          console.error(chalk3.red("tunnel closed by server \u2014 session ended"));
+          console.error(chalk4.red("tunnel closed by server \u2014 session ended"));
           stopping = true;
           endedEmitted = true;
           emit(opts.json, evt);
@@ -2651,20 +2790,20 @@ async function runDevInProcess(opts) {
             if (!waitingPrinted) {
               waitingPrinted = true;
               console.error(
-                chalk3.dim("\u2026 waiting for the device to come up (tunnel not ready yet)")
+                chalk4.dim("\u2026 waiting for the device to come up (tunnel not ready yet)")
               );
             }
             return;
           }
-          console.error(chalk3.yellow("\u2026 tunnel dropped, reconnecting"));
+          console.error(chalk4.yellow("\u2026 tunnel dropped, reconnecting"));
         } else if (s === "metro-unreachable") {
           nextWarningIsMetroUnreachable = true;
         }
       }
     );
-    const keysLine = rokuBuild ? `Press ${chalk3.bold("r")} to reload the channel, ${chalk3.bold("q")} or Ctrl-C to end the session.` : "Ctrl-C to end the session.";
+    const keysLine = rokuBuild ? `Press ${chalk4.bold("r")} to reload the channel, ${chalk4.bold("q")} or Ctrl-C to end the session.` : "Ctrl-C to end the session.";
     console.error(`
-  Watch and interact: ${chalk3.cyan(handle.pageUrl)}
+  Watch and interact: ${chalk4.cyan(handle.pageUrl)}
   ${keysLine}
 `);
     writeDevState(process.cwd(), {
@@ -2696,13 +2835,13 @@ async function runDevInProcess(opts) {
           // Build output and loop notices are human output, so they go to
           // stderr like every other line this command prints — stdout stays
           // reserved for the `--json` event stream.
-          log: (line) => console.error(chalk3.dim(line))
+          log: (line) => console.error(chalk4.dim(line))
         }),
-        log: (line) => console.error(chalk3.yellow(line)),
+        log: (line) => console.error(chalk4.yellow(line)),
         // A failed reload is an error, not a notice — same red as every other
         // failure this command prints, so it doesn't read like the yellow
         // "already reloading" line.
-        logError: (line) => console.error(chalk3.red(`\u2717 ${line}`)),
+        logError: (line) => console.error(chalk4.red(`\u2717 ${line}`)),
         ...watchSeconds !== void 0 ? {
           watchSeconds,
           watch: watchProjectFiles(process.cwd(), rokuBuild.artifact, watchIgnore)
@@ -2710,7 +2849,7 @@ async function runDevInProcess(opts) {
       });
       if (watchSeconds !== void 0) {
         console.error(
-          chalk3.dim(`  Watching for changes \u2014 reloading after ${watchSeconds}s of quiet.`)
+          chalk4.dim(`  Watching for changes \u2014 reloading after ${watchSeconds}s of quiet.`)
         );
       }
       if (process.stdin.isTTY) {
@@ -2745,7 +2884,7 @@ async function runDevInProcess(opts) {
             }
             const verdict = sessionLivenessVerdict(info);
             if (verdict.end && !stopping) {
-              console.error(chalk3.red(verdict.message));
+              console.error(chalk4.red(verdict.message));
               emit(opts.json, { event: "session_ended", session_id: sessionId, code: 1 });
               endedEmitted = true;
               await stopSession(1);
@@ -2754,7 +2893,7 @@ async function runDevInProcess(opts) {
             const warningVerdict = lateWarningVerdict(info, reportedWarnings);
             for (const w of warningVerdict.toReport) {
               reportedWarnings.add(w);
-              console.error(chalk3.yellow(`\u26A0 ${w}`));
+              console.error(chalk4.yellow(`\u26A0 ${w}`));
               emit(opts.json, { event: "warning", message: w });
             }
             if (warningVerdict.blocking && !stopping) {
@@ -2772,7 +2911,7 @@ async function runDevInProcess(opts) {
     }
   } catch (err) {
     const message = err.message;
-    console.error(chalk3.red(`error: ${message}`));
+    console.error(chalk4.red(`error: ${message}`));
     emit(opts.json, { event: "error", message });
     await stopSession(1);
   }
@@ -2802,12 +2941,12 @@ async function dev(opts) {
         if (opts.json) {
           console.log(JSON.stringify(parsed));
         } else {
-          console.error(chalk3.dim(`Using ${resolveAuth(opts).baseUrl}`));
-          console.error(chalk3.green(`\u2713 dev session started in the background (pid ${parsed.pid})`));
+          console.error(chalk4.dim(`Using ${resolveAuth(opts).baseUrl}`));
+          console.error(chalk4.green(`\u2713 dev session started in the background (pid ${parsed.pid})`));
           console.error(`
-  Watch and interact: ${chalk3.cyan(parsed.url)}`);
-          console.error(chalk3.dim(`  vibeview dev-status  \u2014 check on it`));
-          console.error(chalk3.dim(`  vibeview dev-stop    \u2014 end it
+  Watch and interact: ${chalk4.cyan(parsed.url)}`);
+          console.error(chalk4.dim(`  vibeview dev-status  \u2014 check on it`));
+          console.error(chalk4.dim(`  vibeview dev-stop    \u2014 end it
 `));
         }
         child.unref();
@@ -2817,13 +2956,13 @@ async function dev(opts) {
         settled = true;
         rl.close();
         emit(opts.json, parsed);
-        if (!opts.json) console.error(chalk3.red(`error: ${parsed.message}`));
+        if (!opts.json) console.error(chalk4.red(`error: ${parsed.message}`));
         reject(new Error(parsed.message));
       } else if (parsed.event === "warning") {
         if (opts.json) {
           console.log(JSON.stringify(parsed));
         } else {
-          console.error(chalk3.yellow(`\u26A0 ${parsed.message}`));
+          console.error(chalk4.yellow(`\u26A0 ${parsed.message}`));
         }
       }
     });
@@ -2832,14 +2971,14 @@ async function dev(opts) {
       rl.close();
       const message = `dev session exited before starting (code ${code ?? "unknown"})`;
       emit(opts.json, { event: "error", message });
-      if (!opts.json) console.error(chalk3.red(`error: ${message}`));
+      if (!opts.json) console.error(chalk4.red(`error: ${message}`));
       reject(new Error(message));
     });
     child.on("error", (err) => {
       if (settled) return;
       rl.close();
       emit(opts.json, { event: "error", message: err.message });
-      if (!opts.json) console.error(chalk3.red(`error: ${err.message}`));
+      if (!opts.json) console.error(chalk4.red(`error: ${err.message}`));
       reject(err);
     });
   }).catch(() => {
@@ -2850,8 +2989,8 @@ async function dev(opts) {
 }
 
 // src/lib/formatters/devices.ts
-import chalk4 from "chalk";
-var HEADERS = ["DEVICE_ID", "NAME", "TYPE", "CATEGORY", "OS", "STATUS"];
+import chalk5 from "chalk";
+var HEADERS2 = ["DEVICE_ID", "NAME", "TYPE", "CATEGORY", "OS", "STATUS"];
 function formatDevicesHuman(devices) {
   if (devices.length === 0) {
     return "No devices registered.\n";
@@ -2864,11 +3003,11 @@ function formatDevicesHuman(devices) {
     d.os_version,
     d.status
   ]);
-  const widths = HEADERS.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const widths = HEADERS2.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
   const fmt = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
-  const lines = [chalk4.bold(fmt(HEADERS))];
+  const lines = [chalk5.bold(fmt(HEADERS2))];
   for (const row of rows.sort(rowSort)) {
-    const statusColored = row[5] === "available" ? chalk4.green(row[5]) : row[5] === "busy" ? chalk4.yellow(row[5]) : chalk4.dim(row[5]);
+    const statusColored = row[5] === "available" ? chalk5.green(row[5]) : row[5] === "busy" ? chalk5.yellow(row[5]) : chalk5.dim(row[5]);
     lines.push(fmt([row[0], row[1], row[2], row[3], row[4], statusColored]));
   }
   return lines.join("\n") + "\n";
@@ -2895,7 +3034,7 @@ function formatDeviceModelsHuman(models) {
   );
   const widths = MODEL_HEADERS.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
   const fmt = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
-  return [chalk4.bold(fmt(MODEL_HEADERS)), ...rows.map(fmt)].join("\n") + "\n";
+  return [chalk5.bold(fmt(MODEL_HEADERS)), ...rows.map(fmt)].join("\n") + "\n";
 }
 
 // src/agent/registry.ts
@@ -3350,18 +3489,18 @@ var AGENT_COMMANDS = [
 ];
 
 // src/agent/render.ts
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 function renderEnvelope(env) {
   const lines = [];
   if (env.ok) {
-    lines.push(chalk5.green(`ok`) + chalk5.dim(` (${env.tool})`));
+    lines.push(chalk6.green(`ok`) + chalk6.dim(` (${env.tool})`));
   } else {
-    lines.push(chalk5.red(`error`) + chalk5.dim(` (${env.tool})`));
+    lines.push(chalk6.red(`error`) + chalk6.dim(` (${env.tool})`));
   }
   lines.push(...resultLines(env.result));
   if (env.observation) {
     if (env.observation.kind === "unavailable") {
-      lines.push(chalk5.yellow(`warning: ${env.observation.text}`));
+      lines.push(chalk6.yellow(`warning: ${env.observation.text}`));
     } else {
       lines.push(env.observation.text);
     }
@@ -3374,17 +3513,17 @@ function resultLines(result) {
   const lines = [];
   if (Array.isArray(r.entries) && typeof r.cursor === "number") {
     if (r.entries.length === 0) {
-      lines.push(chalk5.dim("(no log lines)"));
+      lines.push(chalk6.dim("(no log lines)"));
     }
     for (const e of r.entries) {
       if (!e || typeof e !== "object") continue;
       const entry = e;
       const ts = typeof entry.timestamp === "number" ? new Date(entry.timestamp).toISOString().slice(11, 23) : "??:??:??.???";
       const level = typeof entry.level === "string" ? entry.level : "info";
-      const levelTag = level === "error" ? chalk5.red(level) : level === "warn" ? chalk5.yellow(level) : chalk5.dim(level);
-      lines.push(`${chalk5.dim(ts)} ${levelTag} ${String(entry.message ?? "")}`);
+      const levelTag = level === "error" ? chalk6.red(level) : level === "warn" ? chalk6.yellow(level) : chalk6.dim(level);
+      lines.push(`${chalk6.dim(ts)} ${levelTag} ${String(entry.message ?? "")}`);
     }
-    lines.push(chalk5.dim(`cursor: ${r.cursor}`));
+    lines.push(chalk6.dim(`cursor: ${r.cursor}`));
   }
   if (r.found === true && typeof r.ref === "string" && r.ref) {
     let found = `found: @${r.ref}`;
@@ -3396,14 +3535,14 @@ function resultLines(result) {
         const text = typeof a.text === "string" && a.text ? ` ${JSON.stringify(a.text)}` : "";
         return `${ref}${text}`;
       });
-      if (alts.length > 0) lines.push(chalk5.dim(`alternatives: ${alts.join(", ")}`));
+      if (alts.length > 0) lines.push(chalk6.dim(`alternatives: ${alts.join(", ")}`));
     }
   }
   if (r.action === "posture_set" || r.action === "rotated") {
     const state = deviceStateLine(r);
     if (state) lines.push(state);
   }
-  if (typeof r.note === "string" && r.note) lines.push(chalk5.dim(r.note));
+  if (typeof r.note === "string" && r.note) lines.push(chalk6.dim(r.note));
   if (typeof r.message === "string" && r.message) lines.push(r.message);
   if (typeof r.warning === "string" && r.warning) lines.push(r.warning);
   return lines;
@@ -3412,9 +3551,9 @@ function deviceStateLine(r) {
   const parts = [];
   if (r.action === "rotated") {
     if (typeof r.device_orientation === "string") {
-      let o = `orientation: ${r.device_orientation}`;
+      let o = `device held ${r.device_orientation}`;
       if (typeof r.screen_orientation === "string" && r.screen_orientation !== r.device_orientation) {
-        o += ` (screen shows ${r.screen_orientation})`;
+        o += ` (picture on the lit screen: ${r.screen_orientation})`;
       }
       parts.push(o);
     }
@@ -3667,15 +3806,20 @@ async function runAgentVerb(cmd, positionals, opts) {
 }
 
 export {
+  parseBuildId,
+  checkDevBuild,
+  buildRows,
+  formatBuildRowsHuman,
+  listBuilds,
   readDevState,
   clearDevState,
+  readMetroState,
+  killOwnedMetro,
   DEV_PLATFORMS,
   PLATFORM_NEEDS_METRO,
   isDevPlatform,
   loadDevConfig,
   checkMetro,
-  readMetroState,
-  killOwnedMetro,
   buildCommand,
   formatDuration,
   BUILD_TERMINAL_STATUSES,