vibeview 0.7.1 → 0.8.1

package/dist/chunk-WG2XR45H.js

@@ -0,0 +1,2011 @@
+#!/usr/bin/env node
+import {
+  ApiClient,
+  loadConfig,
+  resolveAuth,
+  uploadAppBuild
+} from "./chunk-YD2X6TQV.js";
+
+// src/lib/dev-state.ts
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var STATE_DIR = ".vibeview";
+var STATE_FILE = "dev-state.json";
+function statePath(cwd) {
+  return join(cwd, STATE_DIR, STATE_FILE);
+}
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function ensureGitignored(cwd) {
+  try {
+    const gitignore = join(cwd, ".gitignore");
+    if (!existsSync(gitignore)) return;
+    const content = readFileSync(gitignore, "utf-8");
+    const covered = content.split("\n").map((l) => l.trim()).some((l) => l === ".vibeview" || l === ".vibeview/" || l === "/.vibeview");
+    if (covered) return;
+    const prefix = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+    writeFileSync(gitignore, `${content}${prefix}
+# VibeView local session state
+.vibeview/
+`);
+  } catch {
+  }
+}
+function writeDevState(cwd, state) {
+  const path = statePath(cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(state, null, 2) + "\n");
+  ensureGitignored(cwd);
+}
+function readDevState(cwd) {
+  let raw;
+  try {
+    raw = readFileSync(statePath(cwd), "utf-8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed.pid !== "number" || !isPidAlive(parsed.pid)) {
+    return null;
+  }
+  return parsed;
+}
+function clearDevState(cwd) {
+  const path = statePath(cwd);
+  if (existsSync(path)) {
+    rmSync(path, { force: true });
+  }
+}
+
+// src/lib/dev-config.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+var DEV_PLATFORMS = ["ios", "android", "tvos", "androidtv"];
+var FILE = "vibeview.json";
+function isDevPlatform(p) {
+  return typeof p === "string" && DEV_PLATFORMS.includes(p);
+}
+function loadDevConfig(cwd) {
+  let raw;
+  try {
+    raw = readFileSync2(join2(cwd, FILE), "utf-8");
+  } catch {
+    return null;
+  }
+  const parsed = JSON.parse(raw);
+  if (!("platforms" in parsed) && typeof parsed.platform === "string") {
+    const legacy = parsed;
+    if (!isDevPlatform(legacy.platform)) {
+      throw new Error(
+        `vibeview.json: "platform" must be one of ${DEV_PLATFORMS.join(", ")}, got "${legacy.platform}"`
+      );
+    }
+    if (!legacy.appId || typeof legacy.appId !== "string") {
+      throw new Error('vibeview.json: "appId" is required \u2014 run `vibeview dev` to set it up');
+    }
+    return {
+      defaultPlatform: legacy.platform,
+      metroPort: legacy.metroPort,
+      platforms: {
+        [legacy.platform]: { appId: legacy.appId, deviceCategory: legacy.deviceCategory }
+      }
+    };
+  }
+  const cfg = parsed;
+  if (!isDevPlatform(cfg.defaultPlatform)) {
+    throw new Error(
+      `vibeview.json: "defaultPlatform" must be one of ${DEV_PLATFORMS.join(", ")}, got "${String(cfg.defaultPlatform)}"`
+    );
+  }
+  if (!cfg.platforms || typeof cfg.platforms !== "object") {
+    throw new Error(
+      'vibeview.json: "platforms" object is required \u2014 run `vibeview dev` to set it up'
+    );
+  }
+  for (const [key, entry] of Object.entries(cfg.platforms)) {
+    if (!isDevPlatform(key)) {
+      throw new Error(
+        `vibeview.json: unknown platform "${key}" (expected one of ${DEV_PLATFORMS.join(", ")})`
+      );
+    }
+    if (!entry || typeof entry.appId !== "string" || !entry.appId) {
+      throw new Error(`vibeview.json: platforms.${key}.appId is required`);
+    }
+    if (entry.build !== void 0) {
+      if (typeof entry.build !== "object" || entry.build === null) {
+        throw new Error(
+          `vibeview.json: platforms.${key}.build must be an object with command and artifact`
+        );
+      }
+      if (typeof entry.build.command !== "string" || !entry.build.command) {
+        throw new Error(`vibeview.json: platforms.${key}.build.command must be a non-empty string`);
+      }
+      if (typeof entry.build.artifact !== "string" || !entry.build.artifact) {
+        throw new Error(
+          `vibeview.json: platforms.${key}.build.artifact must be a non-empty string`
+        );
+      }
+    }
+    if (entry.metroCommand !== void 0 && (typeof entry.metroCommand !== "string" || !entry.metroCommand)) {
+      throw new Error(`vibeview.json: platforms.${key}.metroCommand must be a non-empty string`);
+    }
+  }
+  if (cfg.metroCommand !== void 0 && (typeof cfg.metroCommand !== "string" || !cfg.metroCommand)) {
+    throw new Error('vibeview.json: "metroCommand" must be a non-empty string');
+  }
+  return cfg;
+}
+function saveDevConfig(cwd, cfg) {
+  writeFileSync2(join2(cwd, FILE), JSON.stringify(cfg, null, 2) + "\n");
+}
+function resolveMetro(cfg, platform, portFlag) {
+  const entry = cfg?.platforms?.[platform];
+  return {
+    command: entry?.metroCommand ?? cfg?.metroCommand,
+    port: portFlag ?? entry?.metroPort ?? cfg?.metroPort ?? 8081,
+    platformHasOverride: entry?.metroCommand !== void 0 || entry?.metroPort !== void 0
+  };
+}
+function buildSavedConfig(input2) {
+  const {
+    existing,
+    platform,
+    appId,
+    deviceCategory,
+    isTv,
+    metroPortFlag,
+    isFirstRun,
+    firstRunMetro,
+    firstRunBuild
+  } = input2;
+  const topLevelMetroPort = metroPortFlag ? parseInt(metroPortFlag, 10) : existing?.metroPort ?? 8081;
+  return {
+    defaultPlatform: platform,
+    metroPort: topLevelMetroPort,
+    ...isFirstRun && firstRunMetro ? { metroCommand: firstRunMetro } : existing?.metroCommand ? { metroCommand: existing.metroCommand } : {},
+    platforms: {
+      ...existing?.platforms,
+      [platform]: {
+        appId,
+        deviceCategory: isTv ? void 0 : deviceCategory,
+        ...existing?.platforms?.[platform]?.build ? { build: existing.platforms[platform].build } : {},
+        ...isFirstRun && firstRunBuild ? { build: firstRunBuild } : {},
+        ...existing?.platforms?.[platform]?.metroCommand ? { metroCommand: existing.platforms[platform].metroCommand } : {},
+        ...existing?.platforms?.[platform]?.metroPort !== void 0 ? { metroPort: existing.platforms[platform].metroPort } : {}
+      }
+    }
+  };
+}
+
+// src/lib/metro-check.ts
+async function checkMetro(port, timeoutMs = 1500) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/status`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const body = await res.text().catch(() => "");
+    return body.includes("packager-status:running") ? "running" : "listening";
+  } catch {
+    return "down";
+  }
+}
+
+// src/commands/build.ts
+import { spawn } from "child_process";
+import { createInterface } from "readline";
+import { select as select2 } from "@inquirer/prompts";
+import chalk from "chalk";
+
+// src/lib/artifact.ts
+import { existsSync as existsSync2, mkdtempSync, readdirSync, rmSync as rmSync2, statSync } from "fs";
+import { spawnSync } from "child_process";
+import { tmpdir } from "os";
+import { basename, dirname as dirname2, isAbsolute, join as join3 } from "path";
+function resolveArtifact(cwd, pattern) {
+  const abs = isAbsolute(pattern) ? pattern : join3(cwd, pattern);
+  if (!basename(abs).includes("*")) {
+    if (!existsSync2(abs)) {
+      throw new Error(
+        `artifact not found: ${pattern} (looked at ${abs}) \u2014 did the build produce it?`
+      );
+    }
+    return abs;
+  }
+  const dir = dirname2(abs);
+  const re = new RegExp("^" + basename(abs).split("*").map(escapeRegExp).join(".*") + "$");
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    throw new Error(`artifact not found: ${pattern} (directory ${dir} does not exist)`);
+  }
+  const matches = entries.filter((e) => re.test(e)).map((e) => join3(dir, e)).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+  if (matches.length === 0) {
+    throw new Error(`artifact not found: no match for ${pattern} in ${dir}`);
+  }
+  return matches[0];
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function prepareUploadArtifact(path) {
+  if (!(statSync(path).isDirectory() && path.endsWith(".app"))) {
+    return { uploadPath: path, cleanup: () => {
+    } };
+  }
+  const tmp = mkdtempSync(join3(tmpdir(), "vibeview-zip-"));
+  const out = join3(tmp, `${basename(path)}.zip`);
+  const res = spawnSync("zip", ["-qry", out, basename(path)], { cwd: dirname2(path) });
+  if (res.error) {
+    rmSync2(tmp, { recursive: true, force: true });
+    const errorCode = res.error.code;
+    const errorMsg = res.error.message;
+    throw new Error(
+      `failed to zip ${path}: spawn zip ${errorCode} \u2014 ${errorMsg} \u2014 is the \`zip\` command installed?`
+    );
+  }
+  if (res.status !== 0) {
+    rmSync2(tmp, { recursive: true, force: true });
+    throw new Error(
+      `failed to zip ${path}: ${res.stderr?.toString().trim() || `zip exited ${res.status}`}`
+    );
+  }
+  return { uploadPath: out, cleanup: () => rmSync2(tmp, { recursive: true, force: true }) };
+}
+
+// src/lib/dev-setup.ts
+import { input, select } from "@inquirer/prompts";
+
+// src/lib/project-detect.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
+import { join as join4 } from "path";
+function detectFlavor(cwd) {
+  let deps = {};
+  try {
+    const pkg = JSON.parse(readFileSync3(join4(cwd, "package.json"), "utf-8"));
+    deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  } catch {
+  }
+  if ("expo" in deps) return "expo";
+  if (existsSync3(join4(cwd, "android", "gradlew")) || iosWorkspaceName(cwd)) return "bare-rn";
+  return "unknown";
+}
+function iosWorkspaceName(cwd) {
+  try {
+    const found = readdirSync2(join4(cwd, "ios")).find((f) => f.endsWith(".xcworkspace"));
+    return found ? found.replace(/\.xcworkspace$/, "") : null;
+  } catch {
+    return null;
+  }
+}
+var IOS_ARTIFACT = "ios/build/Build/Products/Debug-iphonesimulator/*.app";
+var ANDROID_ARTIFACT = "android/app/build/outputs/apk/debug/*.apk";
+function defaultsFor(cwd, platform) {
+  const flavor = detectFlavor(cwd);
+  if (flavor === "unknown") return {};
+  const metroCommand = flavor === "expo" ? "npx expo start" : "yarn start";
+  if (platform === "tvos" || platform === "androidtv") return { metroCommand };
+  if (platform === "android") {
+    return {
+      buildCommand: flavor === "expo" ? "npx expo run:android --variant debug" : "cd android && ./gradlew assembleDebug",
+      artifact: ANDROID_ARTIFACT,
+      metroCommand
+    };
+  }
+  if (flavor === "expo") {
+    return {
+      buildCommand: "npx expo run:ios --configuration Debug",
+      artifact: IOS_ARTIFACT,
+      metroCommand
+    };
+  }
+  const ws = iosWorkspaceName(cwd);
+  return {
+    buildCommand: ws ? `xcodebuild -workspace ios/${ws}.xcworkspace -scheme ${ws} -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build` : void 0,
+    artifact: IOS_ARTIFACT,
+    metroCommand
+  };
+}
+
+// src/lib/dev-setup.ts
+function firstRunAppStrategy(apps, buildConfigured) {
+  if (!buildConfigured) return "picker";
+  return apps.length === 0 ? "build_now" : "ask";
+}
+function fillLaterHint(skipped, platform) {
+  if (!skipped.build && !skipped.metro) return "";
+  const lines = ["You can enable one-command builds later \u2014 add to vibeview.json:"];
+  if (skipped.build) {
+    lines.push(
+      `  platforms.${platform}.build = { "command": "<your build command>", "artifact": "<path to .app/.apk>" }`
+    );
+  }
+  if (skipped.metro) {
+    lines.push('  "metroCommand": "<command that starts Metro>"');
+  }
+  return lines.join("\n");
+}
+async function commandSelect(message, detected) {
+  const choices = [];
+  if (detected) choices.push({ value: "default", name: `Use detected default: ${detected}` });
+  choices.push({ value: "custom", name: "Enter custom command" });
+  choices.push({ value: "skip", name: "Skip for now" });
+  return select({ message, choices });
+}
+async function promptBuildConfig(cwd, platform) {
+  const defaults = defaultsFor(cwd, platform);
+  const choice = await commandSelect(`Build command for ${platform}`, defaults.buildCommand);
+  if (choice === "skip") return null;
+  if (choice === "default") {
+    return { command: defaults.buildCommand, artifact: defaults.artifact };
+  }
+  const command = await input({ message: `Build command for ${platform}`, required: true });
+  const artifact = await input({
+    message: "Path to the built app it produces (.apk, or .app dir; * allowed)",
+    default: defaults.artifact,
+    required: true
+  });
+  return { command, artifact };
+}
+async function promptMetroCommand(cwd, platform) {
+  const defaults = defaultsFor(cwd, platform);
+  const choice = await commandSelect("Command that starts Metro", defaults.metroCommand);
+  if (choice === "skip") return null;
+  if (choice === "default") return defaults.metroCommand;
+  return input({ message: "Metro command", required: true });
+}
+
+// src/commands/build.ts
+var TAIL_LINES = 30;
+async function runBuildForPlatform(cwd, platform, build, opts, log, deps = { upload: uploadAppBuild }) {
+  const tail = await runShell(build.command, cwd, log);
+  if (tail.code !== 0) {
+    throw new Error(
+      `build command failed (exit ${tail.code}): ${build.command}
+` + (tail.lines.length ? `Last output:
+  ${tail.lines.join("\n  ")}` : "")
+    );
+  }
+  const artifactPath = resolveArtifact(cwd, build.artifact);
+  const { uploadPath, cleanup } = prepareUploadArtifact(artifactPath);
+  try {
+    const { result } = await deps.upload(uploadPath, opts);
+    if (result.platform !== platform) {
+      throw new Error(
+        `you built an ${result.platform} app (${result.name}) but the target platform is ${platform} \u2014 check platforms.${platform}.build in vibeview.json`
+      );
+    }
+    return result;
+  } finally {
+    cleanup();
+  }
+}
+function runShell(command, cwd, log) {
+  return new Promise((resolve) => {
+    const child = spawn(command, { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    const lines = [];
+    const onLine = (line) => {
+      lines.push(line);
+      if (lines.length > TAIL_LINES) lines.shift();
+      log(line);
+    };
+    createInterface({ input: child.stdout }).on("line", onLine);
+    createInterface({ input: child.stderr }).on("line", onLine);
+    child.on("close", (code) => resolve({ code: code ?? 1, lines }));
+    child.on("error", () => resolve({ code: 127, lines }));
+  });
+}
+async function buildCommand(opts) {
+  const cwd = process.cwd();
+  const cfg = loadDevConfig(cwd);
+  if (opts.platform && !isDevPlatform(opts.platform)) {
+    console.error(chalk.red(`error: --platform must be one of ${DEV_PLATFORMS.join(", ")}`));
+    process.exit(2);
+  }
+  let platform = opts.platform || cfg?.defaultPlatform;
+  if (!platform) {
+    if (opts.json || !process.stdin.isTTY) {
+      fail(
+        opts,
+        "no platform: pass --platform or run `vibeview dev` once to set up vibeview.json",
+        "config_required"
+      );
+      return;
+    }
+    platform = await select2({
+      message: "Platform to run on",
+      choices: [
+        { value: "ios", name: "iOS simulator" },
+        { value: "android", name: "Android emulator" },
+        { value: "tvos", name: "Apple TV simulator" },
+        { value: "androidtv", name: "Android TV emulator" }
+      ]
+    });
+  }
+  let build = cfg?.platforms?.[platform]?.build;
+  if (!build) {
+    if (opts.json || !process.stdin.isTTY) {
+      fail(
+        opts,
+        `no build config for ${platform}: add platforms.${platform}.build {command, artifact} to vibeview.json`,
+        "config_required"
+      );
+      return;
+    }
+    const answered = await promptBuildConfig(cwd, platform);
+    if (!answered) {
+      fail(opts, "build config is required to run vibeview build", "config_required");
+      return;
+    }
+    build = answered;
+    if (cfg?.platforms?.[platform]) {
+      cfg.platforms[platform].build = build;
+      saveDevConfig(cwd, cfg);
+    }
+  }
+  try {
+    const result = await runBuildForPlatform(
+      cwd,
+      platform,
+      build,
+      opts,
+      (l) => console.error(chalk.dim(l))
+    );
+    for (const w of result.warnings ?? []) console.error(chalk.yellow(`\u26A0 ${w}`));
+    const nextCfg = cfg ?? { defaultPlatform: platform, platforms: {} };
+    const entry = nextCfg.platforms[platform];
+    if (!entry) {
+      nextCfg.platforms[platform] = { appId: result.public_id, build };
+      saveDevConfig(cwd, nextCfg);
+    } else if (entry.appId !== result.public_id || !entry.build) {
+      entry.appId = result.public_id;
+      entry.build = build;
+      saveDevConfig(cwd, nextCfg);
+    }
+    if (opts.json) {
+      console.log(
+        JSON.stringify({ app_id: result.public_id, name: result.name, platform: result.platform })
+      );
+    } else {
+      console.error(
+        chalk.green(`\u2713 built and uploaded ${result.name}`) + `
+  ${chalk.cyan(result.public_id)}  ${chalk.dim(`[${result.platform}]`)}`
+      );
+    }
+  } catch (err) {
+    fail(opts, err instanceof Error ? err.message : String(err));
+  }
+}
+function fail(opts, message, code) {
+  if (opts.json) console.log(JSON.stringify({ event: "error", code, message }));
+  console.error(chalk.red(`error: ${message}`));
+  process.exit(1);
+}
+
+// src/commands/dev.ts
+import { spawn as spawn3 } from "child_process";
+import { createInterface as createInterface3 } from "readline";
+import { select as select3 } from "@inquirer/prompts";
+import chalk2 from "chalk";
+import openBrowser from "open";
+
+// src/lib/tunnel-client.ts
+import net from "net";
+import WebSocket from "ws";
+
+// src/lib/mux.ts
+var FRAME_OPEN = 1;
+var FRAME_DATA = 2;
+var FRAME_CLOSE = 3;
+var HEADER_LEN = 5;
+var KNOWN = /* @__PURE__ */ new Set([FRAME_OPEN, FRAME_DATA, FRAME_CLOSE]);
+function encodeFrame(type, streamId, payload = Buffer.alloc(0)) {
+  const header = Buffer.alloc(HEADER_LEN);
+  header.writeUInt8(type, 0);
+  header.writeUInt32BE(streamId, 1);
+  return Buffer.concat([header, payload]);
+}
+function decodeFrame(data) {
+  if (data.length < HEADER_LEN) throw new Error(`tunnel frame too short: ${data.length}`);
+  const type = data.readUInt8(0);
+  if (!KNOWN.has(type)) throw new Error(`unknown tunnel frame type: ${type}`);
+  return { type, streamId: data.readUInt32BE(1), payload: data.subarray(HEADER_LEN) };
+}
+
+// src/lib/tunnel-client.ts
+var FATAL_CLOSE_CODES = /* @__PURE__ */ new Set([4008, 4009]);
+var MAX_BACKOFF_MS = 8e3;
+var STABLE_MS = 2e3;
+var TunnelClient = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.url = opts.url;
+  }
+  ws = null;
+  sockets = /* @__PURE__ */ new Map();
+  stopped = false;
+  backoffMs = 1e3;
+  metroWarned = false;
+  reconnectTimer = null;
+  stableTimer = null;
+  url;
+  connCount = 0;
+  debug(msg) {
+    this.opts.onDebug?.(msg);
+  }
+  start() {
+    this.connect();
+  }
+  stop() {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.stableTimer) {
+      clearTimeout(this.stableTimer);
+      this.stableTimer = null;
+    }
+    this.stopped = true;
+    this.setState("closed");
+    this.ws?.close();
+    for (const s of this.sockets.values()) s.destroy();
+    this.sockets.clear();
+  }
+  setState(s) {
+    this.opts.onState?.(s);
+  }
+  connect() {
+    if (this.stopped) return;
+    this.setState("connecting");
+    const conn = ++this.connCount;
+    const openedAt = Date.now();
+    this.debug(`ws#${conn} connecting url=${this.url}`);
+    const ws = new WebSocket(this.url);
+    this.ws = ws;
+    ws.on("open", () => {
+      this.backoffMs = 1e3;
+      this.debug(`ws#${conn} open`);
+      this.stableTimer = setTimeout(() => {
+        this.stableTimer = null;
+        if (this.ws === ws && !this.stopped) this.setState("connected");
+      }, STABLE_MS);
+    });
+    ws.on("message", (data) => this.onFrame(data));
+    ws.on("error", (err) => {
+      this.debug(`ws#${conn} error: ${err.message}`);
+    });
+    ws.on("close", (code, reason) => {
+      if (this.ws !== ws) this.debug(`ws#${conn} close code=${code} \u2014 SUPERSEDED socket`);
+      const heldMs = Date.now() - openedAt;
+      const why = reason?.length ? ` reason="${reason.toString()}"` : "";
+      this.debug(`ws#${conn} close code=${code}${why} heldMs=${heldMs}`);
+      if (this.stableTimer) {
+        clearTimeout(this.stableTimer);
+        this.stableTimer = null;
+      }
+      for (const s of this.sockets.values()) s.destroy();
+      this.sockets.clear();
+      if (this.stopped || FATAL_CLOSE_CODES.has(code)) {
+        this.stopped = true;
+        this.setState("closed");
+        return;
+      }
+      this.setState("reconnecting");
+      const delay = this.backoffMs;
+      this.backoffMs = Math.min(this.backoffMs * 2, MAX_BACKOFF_MS);
+      this.debug(`ws#${conn} scheduling reconnect in ${delay}ms`);
+      this.reconnectTimer = setTimeout(() => {
+        this.reconnectTimer = null;
+        void this.reconnect();
+      }, delay);
+    });
+  }
+  async reconnect() {
+    if (this.stopped) return;
+    if (this.opts.refreshUrl) {
+      let fresh;
+      try {
+        fresh = await this.opts.refreshUrl();
+      } catch (err) {
+        this.debug(`refreshUrl threw: ${err.message}`);
+        fresh = null;
+      }
+      if (this.stopped) return;
+      if (!fresh) {
+        this.debug("refreshUrl returned null \u2014 session gone, closing");
+        this.stopped = true;
+        this.setState("closed");
+        return;
+      }
+      this.debug("refreshUrl ok \u2014 reconnecting with fresh url");
+      this.url = fresh;
+    }
+    this.connect();
+  }
+  onFrame(data) {
+    let frame;
+    try {
+      frame = decodeFrame(Buffer.isBuffer(data) ? data : Buffer.from(data));
+    } catch {
+      return;
+    }
+    if (frame.type === FRAME_OPEN) return this.openStream(frame.streamId);
+    const sock = this.sockets.get(frame.streamId);
+    if (!sock) return;
+    if (frame.type === FRAME_DATA) sock.write(frame.payload);
+    else if (frame.type === FRAME_CLOSE) sock.destroy();
+  }
+  openStream(id) {
+    const sock = net.createConnection({ port: this.opts.metroPort, host: "127.0.0.1" });
+    this.sockets.set(id, sock);
+    sock.on("data", (chunk) => this.ws?.send(encodeFrame(FRAME_DATA, id, chunk)));
+    sock.on("error", () => {
+      if (!this.metroWarned) {
+        this.metroWarned = true;
+        this.setState("metro-unreachable");
+      }
+    });
+    sock.on("close", () => {
+      if (this.sockets.delete(id) && this.ws?.readyState === WebSocket.OPEN) {
+        this.ws.send(encodeFrame(FRAME_CLOSE, id));
+      }
+    });
+  }
+};
+
+// src/lib/metro-manager.ts
+import { spawn as spawn2 } from "child_process";
+import { createInterface as createInterface2 } from "readline";
+
+// src/lib/metro-state.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync as rmSync3, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname3, join as join5 } from "path";
+var STATE_DIR2 = ".vibeview";
+var STATE_FILE2 = "metro-state.json";
+function statePath2(cwd) {
+  return join5(cwd, STATE_DIR2, STATE_FILE2);
+}
+function isPidAlive2(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function writeMetroState(cwd, state) {
+  const path = statePath2(cwd);
+  mkdirSync2(dirname3(path), { recursive: true });
+  writeFileSync3(path, JSON.stringify(state, null, 2) + "\n");
+}
+function readMetroState(cwd) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync4(statePath2(cwd), "utf-8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed.pid !== "number" || !isPidAlive2(parsed.pid)) {
+    clearMetroState(cwd);
+    return null;
+  }
+  return parsed;
+}
+function clearMetroState(cwd) {
+  const path = statePath2(cwd);
+  if (existsSync4(path)) rmSync3(path, { force: true });
+}
+function killOwnedMetro(cwd) {
+  const state = readMetroState(cwd);
+  clearMetroState(cwd);
+  if (!state) return false;
+  try {
+    process.kill(-state.pid, "SIGTERM");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/lib/metro-manager.ts
+var TAIL_LINES2 = 20;
+async function ensureMetro(cwd, metro, log, timeoutMs = 9e4) {
+  const warnings = [];
+  const status = await checkMetro(metro.port);
+  const own = readMetroState(cwd);
+  const ownHoldsPort = own !== null && own.port === metro.port;
+  if (status !== "down") {
+    if (ownHoldsPort && metro.command && own.command !== metro.command) {
+      killOwnedMetro(cwd);
+      await waitFor(async () => await checkMetro(metro.port) === "down", 1e4, 250);
+      await spawnMetro(cwd, metro.command, metro.port, log, timeoutMs);
+      return { status: "respawned", warnings };
+    }
+    if (ownHoldsPort) return { status: "reused-own", warnings };
+    if (status === "listening") {
+      warnings.push(
+        `something is listening on localhost:${metro.port} but it doesn't look like Metro \u2014 continuing anyway`
+      );
+    }
+    if (metro.platformHasOverride) {
+      warnings.push(
+        `a Metro we didn't start is already running on localhost:${metro.port} \u2014 using it; make sure it was started with the right command for this platform`
+      );
+    }
+    return { status: "reused-external", warnings };
+  }
+  if (!metro.command) {
+    throw new Error(
+      `Metro isn't running on localhost:${metro.port}.
+Start it in your project first (yarn start), then re-run vibeview dev.
+Or set "metroCommand" in vibeview.json and vibeview dev will start it for you.
+If Metro uses another port, pass --metro-port <port>.`
+    );
+  }
+  await spawnMetro(cwd, metro.command, metro.port, log, timeoutMs);
+  return { status: "spawned", warnings };
+}
+async function spawnMetro(cwd, command, port, log, timeoutMs) {
+  const child = spawn2(command, {
+    cwd,
+    shell: true,
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const tail = [];
+  const onLine = (line) => {
+    tail.push(line);
+    if (tail.length > TAIL_LINES2) tail.shift();
+    log(`[metro] ${line}`);
+  };
+  createInterface2({ input: child.stdout }).on("line", onLine);
+  createInterface2({ input: child.stderr }).on("line", onLine);
+  let exited = null;
+  child.on("exit", (code) => exited = code ?? 1);
+  writeMetroState(cwd, {
+    pid: child.pid,
+    command,
+    port,
+    started_at: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (exited !== null) {
+      killOwnedMetro(cwd);
+      throw new Error(
+        `Metro command exited (code ${exited}) before localhost:${port} came up.
+` + (tail.length ? `Last output:
+  ${tail.join("\n  ")}` : "")
+      );
+    }
+    if (await checkMetro(port, 1e3) === "running") return;
+    if (Date.now() > deadline) {
+      killOwnedMetro(cwd);
+      throw new Error(`timed out waiting for Metro on localhost:${port} (command: ${command})`);
+    }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+}
+async function waitFor(cond, timeoutMs, everyMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await cond()) return;
+    await new Promise((r) => setTimeout(r, everyMs));
+  }
+}
+
+// src/commands/dev.ts
+function emit(json, evt) {
+  if (json) console.log(JSON.stringify(evt));
+}
+async function startDevSession(cfg, onEvent = () => {
+}, onTunnelState) {
+  const api = new ApiClient(cfg.baseUrl, cfg.token);
+  const created = await api.createSession({
+    device_type: PLATFORM_DEVICE[cfg.platform].deviceType,
+    device_category: cfg.deviceCategory,
+    app_id: cfg.appId,
+    tunnel: true
+  });
+  const sessionId = created.session_id;
+  let stopping = false;
+  let tunnel = null;
+  const stopSession = async (code) => {
+    if (stopping) return;
+    stopping = true;
+    tunnel?.stop();
+    await api.stopSession(sessionId).catch(() => {
+    });
+    onEvent({ event: "session_ended", session_id: sessionId, code });
+  };
+  try {
+    await api.startSession(sessionId);
+    const ready = await pollUntilTunnelReady(api, sessionId, 18e4);
+    for (const w of ready.warnings ?? []) {
+      onEvent({ event: "warning", message: w });
+    }
+    const pageUrl = `${cfg.webUrl || cfg.baseUrl}/sandbox/${sessionId}`;
+    tunnel = new TunnelClient({
+      url: ready.tunnel_url,
+      metroPort: cfg.metroPort,
+      // Re-mint the URL on each reconnect: the tunnel token has a ~1h TTL and
+      // a worker restart drops the proxy registration, so the original URL
+      // eventually goes stale. Every authorized GET /sessions/{id} re-signs a
+      // fresh tunnel token. Null (session stopped/failed) ends the tunnel.
+      refreshUrl: async () => {
+        const info = await api.getSession(sessionId);
+        if (info.status === "stopped" || info.status === "failed") return null;
+        return info.tunnel_url ?? null;
+      },
+      onDebug: cfg.debug ? (msg) => onEvent({ event: "warning", message: `[tunnel] ${msg}` }) : void 0,
+      onState: (s) => {
+        onTunnelState?.(s);
+        if (s === "connected") {
+          onEvent({ event: "tunnel_connected", session_id: sessionId });
+        } else if (s === "metro-unreachable") {
+          onEvent({
+            event: "warning",
+            message: `can't reach Metro on localhost:${cfg.metroPort} \u2014 is it running? (yarn start)`
+          });
+        } else if (s === "closed" && !stopping) {
+          void stopSession(1);
+        }
+      }
+    });
+    tunnel.start();
+    if (cfg.open !== false) await openBrowser(pageUrl).catch(() => {
+    });
+    const active = await pollUntilActive(api, sessionId, 18e4);
+    const seen = new Set(ready.warnings ?? []);
+    for (const w of active.warnings ?? []) {
+      if (!seen.has(w)) onEvent({ event: "warning", message: w });
+    }
+    return { sessionId, pageUrl, stop: () => stopSession(0) };
+  } catch (err) {
+    await stopSession(1);
+    throw err;
+  }
+}
+var BLOCKING_WARNING_PREFIXES = ["No debug build", "App install failed", "App not found"];
+function findBlockingWarning(info) {
+  return (info.warnings ?? []).find((w) => BLOCKING_WARNING_PREFIXES.some((p) => w.includes(p)));
+}
+async function pollUntilTunnelReady(api, sessionId, timeoutMs, intervalMs = 2e3) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const info = await api.getSession(sessionId);
+    const blocking = findBlockingWarning(info);
+    if (blocking) throw new Error(blocking);
+    if (info.tunnel_url) return info;
+    if (info.status === "stopped" || info.status === "failed") {
+      throw new Error(`session ${info.status} before the tunnel came up`);
+    }
+    if (Date.now() > deadline) throw new Error("timed out waiting for the device to start");
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+async function pollUntilActive(api, sessionId, timeoutMs, intervalMs = 2e3) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const info = await api.getSession(sessionId);
+    const blocking = findBlockingWarning(info);
+    if (blocking) throw new Error(blocking);
+    if (info.status === "active") return info;
+    if (info.status === "stopped" || info.status === "failed") {
+      throw new Error(`session ${info.status} before it became active`);
+    }
+    if (Date.now() > deadline) {
+      throw new Error("timed out waiting for the session to become active");
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+}
+var PLATFORM_DEVICE = {
+  ios: { deviceType: "ios", tv: false },
+  android: { deviceType: "android", tv: false },
+  tvos: { deviceType: "ios", tv: true },
+  androidtv: { deviceType: "android", tv: true }
+};
+function appsForPlatform(apps, platform) {
+  return apps.filter((a) => a.platform === platform);
+}
+function validateAppChoice(requested, fromFlag, apps) {
+  if (!requested) return {};
+  if (apps.some((a) => a.public_id === requested)) return { appId: requested };
+  return fromFlag ? { staleFlag: requested } : { staleCached: requested };
+}
+function noAppsMessage(platform, hasBuildConfig) {
+  if (hasBuildConfig) {
+    return `No ${platform} apps found \u2014 run \`vibeview dev --build\` (or \`vibeview build\`) to build and upload one.`;
+  }
+  return `No ${platform} apps found. Run \`vibeview build --platform ${platform}\` to build and upload one (it will ask for your build command), or upload a build with \`vibeview upload-app\`.`;
+}
+function requireNonInteractive(json) {
+  if (!json) return;
+  emit(json, {
+    event: "error",
+    code: "config_required",
+    message: "pass --platform and run once interactively, or commit vibeview.json"
+  });
+  process.exit(1);
+}
+async function ensureConfig(api, opts) {
+  const existing = loadDevConfig(process.cwd());
+  if (opts.platform && !isDevPlatform(opts.platform)) {
+    console.error(chalk2.red(`error: --platform must be one of ios, android, tvos, androidtv`));
+    process.exit(2);
+  }
+  if (!opts.platform && !existing?.defaultPlatform) {
+    requireNonInteractive(opts.json);
+  }
+  const platform = opts.platform || existing?.defaultPlatform || await select3({
+    message: "Platform to run on",
+    choices: [
+      { value: "ios", name: "iOS simulator" },
+      { value: "android", name: "Android emulator" },
+      { value: "tvos", name: "Apple TV simulator" },
+      { value: "androidtv", name: "Android TV emulator" }
+    ]
+  });
+  const isTv = PLATFORM_DEVICE[platform].tv;
+  if (isTv && opts.deviceCategory) {
+    console.error(
+      chalk2.red(`error: --device-category does not apply to ${platform} (always a tv device)`)
+    );
+    process.exit(2);
+  }
+  if (!isTv && opts.deviceCategory === "tv") {
+    console.error(chalk2.red(`error: use --platform tvos or --platform androidtv for TV devices`));
+    process.exit(2);
+  }
+  let firstRunBuild = null;
+  let firstRunMetro = null;
+  let isFirstRun = false;
+  if (!existing) {
+    isFirstRun = true;
+    if (opts.json) {
+      requireNonInteractive(opts.json);
+    } else if (process.stdin.isTTY) {
+      firstRunBuild = await promptBuildConfig(process.cwd(), platform);
+      firstRunMetro = await promptMetroCommand(process.cwd(), platform);
+    }
+  }
+  const entry = existing?.platforms?.[platform];
+  let allApps;
+  try {
+    allApps = await api.listApps();
+  } catch (err) {
+    const message = `could not fetch your app list \u2014 ${err instanceof Error ? err.message : String(err)}`;
+    console.error(chalk2.red(`error: ${message}`));
+    emit(opts.json, { event: "error", message });
+    process.exit(1);
+  }
+  const apps = appsForPlatform(allApps, platform);
+  const choice = validateAppChoice(opts.app || entry?.appId, Boolean(opts.app), apps);
+  if (choice.staleFlag) {
+    const message = `app "${choice.staleFlag}" not found \u2014 it may have been deleted.`;
+    console.error(
+      chalk2.red(`error: ${message}`) + `
+Run \`vibeview dev\` without --app to pick from the list.`
+    );
+    emit(opts.json, { event: "error", message });
+    process.exit(2);
+  }
+  let appId = choice.appId;
+  let builtThisRun = false;
+  if (choice.staleCached) {
+    console.error(
+      chalk2.yellow(`\u26A0 app "${choice.staleCached}" no longer exists \u2014 pick your debug build again`)
+    );
+  }
+  if (isFirstRun && !appId) {
+    const strategy = firstRunAppStrategy(apps, firstRunBuild !== null);
+    let action = strategy === "build_now" ? "build" : "pick";
+    if (strategy === "ask") {
+      action = await select3({
+        message: "Run against which build?",
+        choices: [
+          { value: "build", name: "Build fresh now (runs your build command)" },
+          { value: "pick", name: "Use an already-uploaded app" }
+        ]
+      });
+    }
+    if (action === "build") {
+      console.error(chalk2.dim(`Building ${platform}...`));
+      try {
+        const result = await runBuildForPlatform(
+          process.cwd(),
+          platform,
+          firstRunBuild,
+          opts,
+          (l) => console.error(chalk2.dim(l))
+        );
+        appId = result.public_id;
+        builtThisRun = true;
+      } catch (err) {
+        const message = err.message;
+        console.error(chalk2.red(`error: ${message}`));
+        process.exit(1);
+      }
+    }
+  }
+  if (!appId) {
+    if (apps.length === 0) {
+      const message = noAppsMessage(platform, entry?.build !== void 0);
+      console.error(chalk2.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(chalk2.red(`error: ${message}`));
+      emit(opts.json, { event: "error", code: "app_deleted", message });
+      process.exit(1);
+    }
+    requireNonInteractive(opts.json);
+    if (!process.stdin.isTTY) {
+      console.error(
+        chalk2.red(
+          `error: no valid app configured for ${platform} \u2014 run interactively to pick one, or pass --app <id>`
+        )
+      );
+      process.exit(1);
+    }
+    appId = await select3({
+      message: "Which uploaded app is your debug build? (upload one with `vibeview upload-app`)",
+      // Platform suffix dropped: the picker is already filtered to one platform
+      // (appsForPlatform), so `(ios)` on every row is redundant noise.
+      choices: apps.map((a) => ({ value: a.public_id, name: a.name }))
+    });
+  }
+  const deviceCategory = isTv ? "tv" : opts.deviceCategory || entry?.deviceCategory || "phone";
+  const metroResolved = resolveMetro(
+    existing,
+    platform,
+    opts.metroPort ? parseInt(opts.metroPort, 10) : void 0
+  );
+  const cfg = buildSavedConfig({
+    existing,
+    platform,
+    appId,
+    deviceCategory,
+    isTv,
+    metroPortFlag: opts.metroPort,
+    isFirstRun,
+    firstRunMetro,
+    firstRunBuild
+  });
+  saveDevConfig(process.cwd(), cfg);
+  if (isFirstRun) {
+    const hint = fillLaterHint({ build: !firstRunBuild, metro: !firstRunMetro }, platform);
+    if (hint) console.error(chalk2.dim(hint));
+  }
+  const finalMetro = isFirstRun ? resolveMetro(cfg, platform, opts.metroPort ? parseInt(opts.metroPort, 10) : void 0) : metroResolved;
+  return {
+    platform,
+    appId,
+    deviceCategory,
+    metroPort: finalMetro.port,
+    metroCommand: finalMetro.command,
+    platformHasMetroOverride: finalMetro.platformHasOverride,
+    builtThisRun
+  };
+}
+async function runDevInProcess(opts) {
+  if (opts.json) {
+    const hasToken = !!(opts.token || process.env.VIBEVIEW_API_TOKEN || loadConfig().token);
+    if (!hasToken) {
+      emit(opts.json, {
+        event: "error",
+        code: "config_required",
+        message: "No API token found. Set VIBEVIEW_API_TOKEN, use --token, or run: vibeview login"
+      });
+      process.exit(1);
+    }
+  }
+  const { token, baseUrl } = resolveAuth(opts);
+  console.error(chalk2.dim(`Using ${baseUrl}`));
+  const api = new ApiClient(baseUrl, token);
+  const cfg = await ensureConfig(api, opts);
+  if (opts.build && !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(chalk2.red(`error: ${message}`));
+      emit(opts.json, { event: "error", code: "config_required", message });
+      process.exit(1);
+    }
+    console.error(chalk2.dim(`Building ${cfg.platform}...`));
+    try {
+      const result = await runBuildForPlatform(
+        process.cwd(),
+        cfg.platform,
+        build,
+        { token, baseUrl },
+        (l) => console.error(chalk2.dim(l))
+      );
+      cfg.appId = result.public_id;
+      if (reloaded && reloaded.platforms[cfg.platform] && reloaded.platforms[cfg.platform].appId !== result.public_id) {
+        reloaded.platforms[cfg.platform].appId = result.public_id;
+        saveDevConfig(process.cwd(), reloaded);
+      }
+    } catch (err) {
+      const message = err.message;
+      console.error(chalk2.red(`error: ${message}`));
+      emit(opts.json, { event: "error", message });
+      process.exit(1);
+    }
+  }
+  const metroPort = cfg.metroPort ?? 8081;
+  let metroResult;
+  try {
+    metroResult = await ensureMetro(
+      process.cwd(),
+      {
+        command: cfg.metroCommand,
+        port: metroPort,
+        platformHasOverride: cfg.platformHasMetroOverride
+      },
+      (line) => console.error(chalk2.dim(line))
+    );
+  } catch (err) {
+    const message = err.message;
+    console.error(chalk2.red(`error: ${message}`));
+    emit(opts.json, { event: "error", code: "metro_down", message });
+    process.exit(1);
+  }
+  for (const w of metroResult.warnings) console.error(chalk2.yellow(`\u26A0 ${w}`));
+  if (metroResult.status === "spawned" || metroResult.status === "respawned") {
+    console.error(chalk2.green(`\u2713 started Metro (${cfg.metroCommand})`));
+  }
+  const metroOwnedThisRun = metroResult.status === "spawned" || metroResult.status === "respawned";
+  console.error(chalk2.dim(`Starting a ${cfg.platform} dev session for ${cfg.appId}...`));
+  let stopping = false;
+  let handle = null;
+  const stopSession = async (code) => {
+    if (stopping) return;
+    stopping = true;
+    console.error(chalk2.dim("\nStopping session..."));
+    await handle?.stop();
+    if (metroOwnedThisRun) killOwnedMetro(process.cwd());
+    clearDevState(process.cwd());
+    process.exit(code);
+  };
+  process.on("SIGINT", () => void stopSession(0));
+  process.on("SIGTERM", () => void stopSession(0));
+  let everConnected = false;
+  let waitingPrinted = false;
+  let nextWarningIsMetroUnreachable = false;
+  try {
+    handle = await startDevSession(
+      {
+        token,
+        baseUrl,
+        webUrl: opts.webUrl || process.env.VIBEVIEW_WEB_URL,
+        platform: cfg.platform,
+        appId: cfg.appId,
+        deviceCategory: cfg.deviceCategory,
+        metroPort: cfg.metroPort ?? 8081,
+        // startDevSession's own browser-open happens before we've written the
+        // state file / emitted session_ready — open it ourselves afterward
+        // instead, preserving the original event order.
+        open: false,
+        debug: opts.debug
+      },
+      (evt) => {
+        if (evt.event === "warning") {
+          if (nextWarningIsMetroUnreachable) {
+            nextWarningIsMetroUnreachable = false;
+            console.error(chalk2.red(`\u2717 ${evt.message}`));
+          } else {
+            console.error(chalk2.yellow(`\u26A0 ${evt.message}`));
+          }
+        } else if (evt.event === "tunnel_connected") {
+          everConnected = true;
+          console.error(chalk2.green("\u2713 tunnel connected \u2014 edit away, Fast Refresh is live"));
+        } else if (evt.event === "session_ended" && !stopping && handle) {
+          console.error(chalk2.red("tunnel closed by server \u2014 session ended"));
+          stopping = true;
+          emit(opts.json, evt);
+          clearDevState(process.cwd());
+          process.exit(1);
+        }
+        emit(opts.json, evt);
+      },
+      (s) => {
+        if (s === "reconnecting") {
+          if (!everConnected) {
+            if (!waitingPrinted) {
+              waitingPrinted = true;
+              console.error(
+                chalk2.dim("\u2026 waiting for the device to come up (tunnel not ready yet)")
+              );
+            }
+            return;
+          }
+          console.error(chalk2.yellow("\u2026 tunnel dropped, reconnecting"));
+        } else if (s === "metro-unreachable") {
+          nextWarningIsMetroUnreachable = true;
+        }
+      }
+    );
+    console.error(
+      `
+  Watch and interact: ${chalk2.cyan(handle.pageUrl)}
+  Ctrl-C to end the session.
+`
+    );
+    writeDevState(process.cwd(), {
+      pid: process.pid,
+      session_id: handle.sessionId,
+      page_url: handle.pageUrl,
+      platform: cfg.platform,
+      app_id: cfg.appId,
+      metro_port: cfg.metroPort ?? 8081,
+      started_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    emit(opts.json, {
+      event: "session_ready",
+      session_id: handle.sessionId,
+      url: handle.pageUrl,
+      pid: process.pid
+    });
+    if (opts.open !== false) await openBrowser(handle.pageUrl).catch(() => {
+    });
+  } catch (err) {
+    const message = err.message;
+    console.error(chalk2.red(`error: ${message}`));
+    emit(opts.json, { event: "error", message });
+    await stopSession(1);
+  }
+}
+async function dev(opts) {
+  if (!opts.detach) {
+    return runDevInProcess(opts);
+  }
+  const rawArgs = process.argv.slice(2).filter((a) => a !== "--detach");
+  const child = spawn3(process.execPath, [process.argv[1], ...rawArgs, "--json", "--no-open"], {
+    detached: true,
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  const rl = createInterface3({ input: child.stdout });
+  let settled = false;
+  await new Promise((resolve, reject) => {
+    rl.on("line", (line) => {
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        return;
+      }
+      if (parsed.event === "session_ready") {
+        settled = true;
+        rl.close();
+        if (opts.json) {
+          console.log(JSON.stringify(parsed));
+        } else {
+          console.error(chalk2.dim(`Using ${resolveAuth(opts).baseUrl}`));
+          console.error(chalk2.green(`\u2713 dev session started in the background (pid ${parsed.pid})`));
+          console.error(`
+  Watch and interact: ${chalk2.cyan(parsed.url)}`);
+          console.error(chalk2.dim(`  vibeview dev-status  \u2014 check on it`));
+          console.error(chalk2.dim(`  vibeview dev-stop    \u2014 end it
+`));
+        }
+        child.unref();
+        child.stdout.destroy();
+        resolve();
+      } else if (parsed.event === "error") {
+        settled = true;
+        rl.close();
+        emit(opts.json, parsed);
+        if (!opts.json) console.error(chalk2.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(chalk2.yellow(`\u26A0 ${parsed.message}`));
+        }
+      }
+    });
+    child.on("exit", (code) => {
+      if (settled) return;
+      rl.close();
+      const message = `dev session exited before starting (code ${code ?? "unknown"})`;
+      emit(opts.json, { event: "error", message });
+      if (!opts.json) console.error(chalk2.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(chalk2.red(`error: ${err.message}`));
+      reject(err);
+    });
+  }).catch(() => {
+    process.exitCode = 1;
+    return;
+  });
+  if (process.exitCode === 1) return;
+}
+
+// src/agent/registry.ts
+var AGENT_COMMANDS = [
+  {
+    verb: "ui-tree",
+    tool: "ui_tree",
+    summary: "Fetch the ref-annotated UI tree for the current screen.",
+    mutating: false,
+    params: []
+  },
+  {
+    verb: "screenshot",
+    tool: "screenshot",
+    summary: "Capture a screenshot of the current screen. Use it to check how something LOOKS \u2014 the UI tree carries no colour, contrast, or stacking information, so a screen can pass every check the tree can express and still be visibly broken. Saved to disk; over MCP, pass inline: true to receive the image itself.",
+    mutating: false,
+    params: [
+      {
+        name: "out",
+        cli: "--out",
+        type: "string",
+        required: false,
+        description: "File path to write the PNG to (CLI-side only, not sent to the backend).",
+        cliOnly: true
+      }
+    ]
+  },
+  {
+    // Fans out to `tap` (wire arg: ref) when the target is an `@ref`, or
+    // `tap_coordinates` (wire args: x, y) when it's `x,y` — see tools.py
+    // `tap`/`tap_coordinates` schemas. Dispatch logic lives in buildToolCall
+    // (Task 4); this descriptor documents the shared surface.
+    verb: "tap",
+    tool: "tap",
+    summary: "Tap an element by ref (e.g. @e5), or raw coordinates (e.g. 100,200).",
+    mutating: true,
+    params: [
+      {
+        name: "target",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: 'Element ref (e.g. @e5 or e5) or "x,y" coordinates.'
+      }
+    ]
+  },
+  {
+    // tools.py long_press: { ref: string, duration_ms?: integer }. Only a
+    // ref target is supported (no raw-coordinate long-press tool exists),
+    // so the positional here always resolves to `ref`.
+    verb: "long-press",
+    tool: "long_press",
+    summary: "Long-press (touch and hold) an element by its ref.",
+    mutating: true,
+    params: [
+      {
+        name: "ref",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Element ref from the UI tree (e.g. @e5 or e5)."
+      },
+      {
+        name: "duration_ms",
+        cli: "--ms",
+        type: "number",
+        required: false,
+        description: "Hold duration in milliseconds (default: 800)."
+      }
+    ]
+  },
+  {
+    // tools.py swipe: { direction: "up"|"down"|"left"|"right", distance?: "short"|"medium"|"long" }.
+    // tool_dispatch.py's `swipe` branch reads ONLY args["direction"] (default
+    // "down") and args["distance"] (default "medium") — it does not accept
+    // x1/y1/x2/y2 or from/to coordinates. Raw two-point dragging is the
+    // separate `drag` verb below — the only precise two-point gesture on this
+    // surface.
+    verb: "swipe",
+    tool: "swipe",
+    summary: "Perform a scrollbar-semantic swipe gesture in one of four directions.",
+    mutating: true,
+    params: [
+      {
+        name: "direction",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Direction to reveal content: up, down, left, or right."
+      },
+      {
+        name: "distance",
+        cli: "--distance",
+        type: "string",
+        required: false,
+        description: "Swipe distance: short, medium, or long (default: medium)."
+      }
+    ]
+  },
+  {
+    // tools.py scroll_until_visible: { text (required), element_type?,
+    // direction?, max_scrolls? }. tool_dispatch.py's branch reads exactly
+    // args["text"], args["element_type"], args["max_scrolls"] (default 8) and
+    // args["direction"] — direction is scrollbar-semantic here and inverted to
+    // finger semantics inside the dispatcher, so pass up/down/left/right as the
+    // content you want revealed, same convention as `swipe`. Omitting direction
+    // is meaningful: the runner auto-detects it.
+    verb: "scroll-to",
+    tool: "scroll_until_visible",
+    summary: "Scroll until an element matching the given text becomes visible.",
+    mutating: true,
+    params: [
+      {
+        name: "text",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Case-insensitive substring matched against an element's label, value, or accessibility id."
+      },
+      {
+        name: "direction",
+        cli: "--direction",
+        type: "string",
+        required: false,
+        description: "Scroll direction in scrollbar semantics (up, down, left, right). Omit to auto-detect; required for horizontal searches."
+      },
+      {
+        name: "max_scrolls",
+        cli: "--max-scrolls",
+        type: "number",
+        required: false,
+        description: "Max swipe attempts before giving up (default: 8)."
+      },
+      {
+        name: "element_type",
+        cli: "--element-type",
+        type: "string",
+        required: false,
+        description: "iOS-only element type filter (Button, StaticText, TextField, SecureTextField, Cell, Image, Link, Switch, TextView, SearchField). Ignored on Android."
+      }
+    ]
+  },
+  {
+    // tools.py drag: { from_ref?, to_ref?, x?, y?, x2?, y2?, velocity?,
+    // press_duration?, hold_duration? } (nothing required in the schema; the
+    // dispatcher enforces "(from_ref or x/y) and (to_ref or x2/y2)"). Note
+    // tool_dispatch.py reads args["press_duration"] and passes it to the bridge
+    // as `duration_ms` — the WIRE name is press_duration, not duration_ms.
+    //
+    // Like `tap`, the CLI fans out: each positional accepts either an `@ref`
+    // (-> from_ref/to_ref) or `x,y` (-> x/y and x2/y2). The two ends are
+    // independent — `drag @e3 200,400` is valid. See buildToolCall.
+    verb: "drag",
+    tool: "drag",
+    summary: "Drag between two points, each an element ref (@e5) or raw coordinates (100,200).",
+    mutating: true,
+    params: [
+      {
+        name: "from",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: 'Drag start: element ref (e.g. @e5 or e5) or "x,y" coordinates.'
+      },
+      {
+        name: "to",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: 'Drag end: element ref (e.g. @e7 or e7) or "x,y" coordinates.'
+      },
+      {
+        name: "velocity",
+        cli: "--velocity",
+        type: "number",
+        required: false,
+        description: "Drag speed in points/sec (default: 500). 100-250 for slow/precise, 1000+ for fast."
+      },
+      {
+        name: "press_duration",
+        cli: "--press-ms",
+        type: "number",
+        required: false,
+        description: "Milliseconds to press before the drag starts (default: 60). Use 500+ for long-press reorder."
+      },
+      {
+        name: "hold_duration",
+        cli: "--hold-ms",
+        type: "number",
+        required: false,
+        description: "Milliseconds to hold at the destination after the drag (default: 0). Use 500+ for drop confirmation."
+      }
+    ]
+  },
+  {
+    // tools.py alert: { action (required, enum get|accept|dismiss), button? }.
+    // tool_dispatch.py reads args.get("action", "get") and args.get("button").
+    // iOS system alerts only.
+    verb: "alert",
+    tool: "alert",
+    summary: "Inspect or respond to a visible iOS system alert (get, accept, or dismiss).",
+    mutating: true,
+    params: [
+      {
+        name: "action",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "'get' returns the alert message and button labels; 'accept' taps a button (first by default); 'dismiss' taps a button (last by default)."
+      },
+      {
+        name: "button",
+        cli: "--button",
+        type: "string",
+        required: false,
+        description: "Specific button label to tap (case-insensitive). Omit to use the default for the action."
+      }
+    ]
+  },
+  {
+    // tools.py gesture_preset: { name: "scroll_up"|"scroll_down"|"scroll_left"|"scroll_right"|"back_swipe"|"pull_to_refresh" }.
+    // The CLI only exposes the four scroll_* presets under this verb; the
+    // positional direction is prefixed with "scroll_" to build the wire arg.
+    verb: "scroll",
+    tool: "gesture_preset",
+    summary: "Scroll the current view up, down, left, or right using a gesture preset.",
+    mutating: true,
+    params: [
+      {
+        name: "name",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: 'Scroll direction: up, down, left, or right (sent as gesture_preset "scroll_<direction>").'
+      }
+    ]
+  },
+  {
+    // tools.py type_text: { text: string }.
+    verb: "type",
+    tool: "type_text",
+    summary: "Type text into the currently focused input field.",
+    mutating: true,
+    params: [
+      {
+        name: "text",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Text to type into the focused field."
+      }
+    ]
+  },
+  {
+    // tools.py clear_text: {} (no params).
+    verb: "clear-text",
+    tool: "clear_text",
+    summary: "Clear the text in the currently focused input field.",
+    mutating: true,
+    params: []
+  },
+  {
+    // tools.py press_button: { button: enum }. The enum is the union of the
+    // iOS/Android/TV button sets across tools.py and the session-specific
+    // press_button_tool() builder.
+    verb: "press",
+    tool: "press_button",
+    summary: "Press a device button or perform a system gesture (home, back, d-pad, etc).",
+    mutating: true,
+    params: [
+      {
+        name: "button",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Button to press: home, back, lock, siri, dpad_up, dpad_down, dpad_left, dpad_right, or dpad_center."
+      }
+    ]
+  },
+  {
+    // tools.py open_url: { url: string }.
+    verb: "open-url",
+    tool: "open_url",
+    summary: "Open a deep link or URL in the app under test.",
+    mutating: true,
+    params: [
+      {
+        name: "url",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Full URI including scheme, e.g. 'myapp://settings' (max 2048 chars)."
+      }
+    ]
+  },
+  {
+    // tools.py wait: { seconds?: number } (default: 2). Note the wire arg is
+    // "seconds", NOT "ms" — tool_dispatch.py reads args.get("seconds", 2)
+    // and passes it straight to asyncio.sleep().
+    verb: "wait",
+    tool: "wait",
+    summary: "Wait for a specified number of seconds before continuing.",
+    mutating: false,
+    params: [
+      {
+        name: "seconds",
+        cli: "--ms",
+        type: "number",
+        required: false,
+        description: "How long to wait, in milliseconds on the CLI (--ms); the MCP tool takes seconds. Default: 2 seconds."
+      }
+    ]
+  },
+  {
+    // tools.py find_element: { text: string, below?: string, above?: string, near?: string }.
+    verb: "find",
+    tool: "find_element",
+    summary: "Find an element by text with optional spatial constraints (below/above/near).",
+    mutating: false,
+    params: [
+      {
+        name: "text",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Text of the target element."
+      },
+      {
+        name: "below",
+        cli: "--below",
+        type: "string",
+        required: false,
+        description: "Target must be below this element (optional)."
+      },
+      {
+        name: "above",
+        cli: "--above",
+        type: "string",
+        required: false,
+        description: "Target must be above this element (optional)."
+      },
+      {
+        name: "near",
+        cli: "--near",
+        type: "string",
+        required: false,
+        description: "Target must be near this element (optional)."
+      }
+    ]
+  },
+  {
+    // tools.py tap_focused_tv: { ref: string }. TV-only. Activates the
+    // element (presses SELECT), so this is mutating like `tap`.
+    verb: "tap-focused",
+    tool: "tap_focused_tv",
+    summary: "TV: move focus to an element and press SELECT in one step.",
+    mutating: true,
+    params: [
+      {
+        name: "ref",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Ref from the UI tree (e.g. @e5)."
+      }
+    ]
+  },
+  {
+    // tools.py focus_element_tv: { ref: string }. TV-only.
+    verb: "focus",
+    tool: "focus_element_tv",
+    summary: "TV: move focus to an element without activating it.",
+    mutating: false,
+    params: [
+      {
+        name: "ref",
+        cli: "positional",
+        type: "string",
+        required: true,
+        description: "Ref from the UI tree (e.g. @e5)."
+      }
+    ]
+  }
+];
+
+// src/agent/render.ts
+import chalk3 from "chalk";
+function renderEnvelope(env) {
+  const lines = [];
+  if (env.ok) {
+    lines.push(chalk3.green(`ok`) + chalk3.dim(` (${env.tool})`));
+  } else {
+    lines.push(chalk3.red(`error`) + chalk3.dim(` (${env.tool})`));
+  }
+  lines.push(...resultLines(env.result));
+  if (env.observation) {
+    if (env.observation.kind === "unavailable") {
+      lines.push(chalk3.yellow(`warning: ${env.observation.text}`));
+    } else {
+      lines.push(env.observation.text);
+    }
+  }
+  return lines.join("\n");
+}
+function resultLines(result) {
+  if (!result || typeof result !== "object") return [];
+  const r = result;
+  const lines = [];
+  if (r.found === true && typeof r.ref === "string" && r.ref) {
+    let found = `found: @${r.ref}`;
+    if (typeof r.text === "string" && r.text) found += ` ${JSON.stringify(r.text)}`;
+    lines.push(found);
+    if (Array.isArray(r.alternatives) && r.alternatives.length > 0) {
+      const alts = r.alternatives.filter((a) => !!a && typeof a === "object").map((a) => {
+        const ref = typeof a.ref === "string" && a.ref ? `@${a.ref}` : "?";
+        const text = typeof a.text === "string" && a.text ? ` ${JSON.stringify(a.text)}` : "";
+        return `${ref}${text}`;
+      });
+      if (alts.length > 0) lines.push(chalk3.dim(`alternatives: ${alts.join(", ")}`));
+    }
+  }
+  if (typeof r.note === "string" && r.note) lines.push(chalk3.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;
+}
+function agentExitCode(env) {
+  return env.ok ? 0 : 1;
+}
+
+// src/commands/agent.ts
+import { writeFileSync as writeFileSync4 } from "fs";
+var REF_RE = /^@?(e\d+)$/;
+var COORDS_RE = /^(-?\d+),\s*(-?\d+)$/;
+var FlagError = class extends Error {
+};
+function parseNumberFlag(raw, flagName) {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) {
+    throw new FlagError(`--${flagName} must be a number (got "${String(raw)}")`);
+  }
+  return n;
+}
+function stripRef(raw) {
+  return raw.startsWith("@") ? raw.slice(1) : raw;
+}
+function parseCoords(raw) {
+  const m = COORDS_RE.exec(raw);
+  if (!m) return null;
+  return { x: parseInt(m[1], 10), y: parseInt(m[2], 10) };
+}
+function flagKey(cli) {
+  const name = cli.replace(/^--/, "");
+  return name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function buildToolCall(cmd, positionals, opts) {
+  if (cmd.verb === "tap") {
+    const target = positionals[0];
+    if (!target) throw new Error('tap requires a target: an element ref (@e5) or "x,y"');
+    const coords = parseCoords(target);
+    if (coords) {
+      return { tool: "tap_coordinates", args: { x: coords.x, y: coords.y } };
+    }
+    if (target.includes(",")) {
+      throw new Error(`tap: "${target}" looks like coordinates but is not two integers "x,y"`);
+    }
+    if (!REF_RE.test(target)) {
+      throw new Error(`tap: "${target}" is not a valid ref (@e5) or "x,y" coordinate pair`);
+    }
+    return { tool: "tap", args: { ref: stripRef(target) } };
+  }
+  if (cmd.verb === "long-press") {
+    const target = positionals[0];
+    if (!target) throw new Error("long-press requires a ref, e.g. @e5");
+    if (parseCoords(target) || target.includes(",") && !REF_RE.test(target)) {
+      throw new Error(
+        `long-press only accepts an element ref (e.g. @e5) \u2014 "${target}" looks like coordinates, and there is no coordinate-based long-press tool`
+      );
+    }
+    const args2 = { ref: stripRef(target) };
+    if (opts.ms !== void 0) {
+      args2.duration_ms = parseNumberFlag(opts.ms, "ms");
+    }
+    return { tool: cmd.tool, args: args2 };
+  }
+  if (cmd.verb === "drag") {
+    const from = positionals[0];
+    const to = positionals[1];
+    if (!from || !to) {
+      throw new Error('drag requires two targets: <from> <to>, each an element ref (@e5) or "x,y"');
+    }
+    const args2 = {};
+    const endpoints = [
+      { raw: from, refArg: "from_ref", xArg: "x", yArg: "y" },
+      { raw: to, refArg: "to_ref", xArg: "x2", yArg: "y2" }
+    ];
+    for (const { raw, refArg, xArg, yArg } of endpoints) {
+      const coords = parseCoords(raw);
+      if (coords) {
+        args2[xArg] = coords.x;
+        args2[yArg] = coords.y;
+        continue;
+      }
+      if (raw.includes(",")) {
+        throw new Error(`drag: "${raw}" looks like coordinates but is not two integers "x,y"`);
+      }
+      if (!REF_RE.test(raw)) {
+        throw new Error(`drag: "${raw}" is not a valid ref (@e5) or "x,y" coordinate pair`);
+      }
+      args2[refArg] = stripRef(raw);
+    }
+    for (const param of cmd.params) {
+      if (param.cli === "positional") continue;
+      const raw = opts[flagKey(param.cli)];
+      if (raw === void 0 || raw === "") continue;
+      args2[param.name] = parseNumberFlag(raw, param.cli.replace(/^--/, ""));
+    }
+    return { tool: cmd.tool, args: args2 };
+  }
+  if (cmd.verb === "wait") {
+    const args2 = {};
+    if (opts.ms !== void 0) {
+      const ms = parseNumberFlag(opts.ms, "ms");
+      args2.seconds = ms / 1e3;
+    }
+    return { tool: cmd.tool, args: args2 };
+  }
+  if (cmd.verb === "scroll") {
+    const direction = positionals[0];
+    const valid = ["up", "down", "left", "right"];
+    if (!direction || !valid.includes(direction)) {
+      throw new Error(`scroll: direction must be one of ${valid.join(", ")}, got "${direction}"`);
+    }
+    return { tool: cmd.tool, args: { name: `scroll_${direction}` } };
+  }
+  if (cmd.verb === "swipe") {
+    const direction = positionals[0];
+    const valid = ["up", "down", "left", "right"];
+    if (!direction || !valid.includes(direction)) {
+      throw new Error(`swipe: direction must be one of ${valid.join(", ")}, got "${direction}"`);
+    }
+    const args2 = { direction };
+    if (opts.distance !== void 0) {
+      args2.distance = opts.distance;
+    }
+    return { tool: cmd.tool, args: args2 };
+  }
+  const args = {};
+  let positionalIndex = 0;
+  for (const param of cmd.params) {
+    let raw;
+    if (param.cli === "positional") {
+      raw = positionals[positionalIndex];
+      positionalIndex += 1;
+    } else {
+      const key = flagKey(param.cli);
+      raw = opts[key];
+    }
+    if (param.cliOnly) continue;
+    if (raw === void 0 || raw === "") {
+      if (param.required) {
+        throw new Error(
+          `${cmd.verb} requires ${param.cli === "positional" ? param.name : param.cli}`
+        );
+      }
+      continue;
+    }
+    if (param.name === "ref" && typeof raw === "string") {
+      args[param.name] = stripRef(raw);
+    } else if (param.type === "number") {
+      const flagName = param.cli === "positional" ? param.name : param.cli.replace(/^--/, "");
+      args[param.name] = parseNumberFlag(raw, flagName);
+    } else {
+      args[param.name] = raw;
+    }
+  }
+  return { tool: cmd.tool, args };
+}
+function defaultScreenshotPath() {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  return `./vibeview-screenshot-${ts}.png`;
+}
+function decodeScreenshotResult(result) {
+  if (typeof result !== "string" || result.length === 0) {
+    throw new Error("screenshot: backend returned no image data");
+  }
+  const b64 = result.startsWith("data:") ? result.split(",", 2)[1] : result;
+  if (!b64) {
+    throw new Error("screenshot: malformed data URL (no base64 payload after comma)");
+  }
+  return Buffer.from(b64, "base64");
+}
+async function runAgentVerb(cmd, positionals, opts) {
+  const { token, baseUrl } = resolveAuth(opts);
+  const sessionId = opts.session || readDevState(process.cwd())?.session_id;
+  if (!sessionId) {
+    process.stderr.write("error: no session \u2014 pass --session or run vibeview dev --detach\n");
+    process.exit(1);
+  }
+  let call;
+  try {
+    call = buildToolCall(cmd, positionals, opts);
+  } catch (err) {
+    process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(err instanceof FlagError ? 2 : 1);
+  }
+  const client = new ApiClient(baseUrl, token);
+  let envelope;
+  try {
+    envelope = await client.agentTool(sessionId, call.tool, call.args);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (opts.json) {
+      const code = /^authentication failed/i.test(message) ? "auth_failed" : /^not found:/i.test(message) ? "not_found" : void 0;
+      console.log(JSON.stringify({ event: "error", code, message }));
+    } else {
+      process.stderr.write(`error: ${message}
+`);
+    }
+    process.exit(1);
+  }
+  if (cmd.verb === "screenshot" && envelope.ok && envelope.result) {
+    const outPath = opts.out || defaultScreenshotPath();
+    let imageBytes;
+    try {
+      imageBytes = decodeScreenshotResult(envelope.result);
+    } catch (err) {
+      process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+    writeFileSync4(outPath, imageBytes);
+    if (opts.json) {
+      console.log(JSON.stringify(envelope));
+    } else {
+      process.stderr.write(renderEnvelope(envelope) + "\n");
+      console.log(outPath);
+    }
+    process.exit(agentExitCode(envelope));
+    return;
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(envelope));
+  } else {
+    console.log(renderEnvelope(envelope));
+  }
+  process.exit(agentExitCode(envelope));
+}
+
+export {
+  readDevState,
+  clearDevState,
+  isDevPlatform,
+  loadDevConfig,
+  checkMetro,
+  readMetroState,
+  killOwnedMetro,
+  buildCommand,
+  startDevSession,
+  PLATFORM_DEVICE,
+  dev,
+  AGENT_COMMANDS,
+  renderEnvelope,
+  buildToolCall,
+  decodeScreenshotResult,
+  runAgentVerb
+};