vibeview 0.25.0 → 0.27.0

package/dist/{chunk-GEKYHEWU.js → chunk-46X7UN6Y.js}

@@ -1,170 +1,19 @@
 #!/usr/bin/env node
 import {
   ApiClient,
+  AuthError,
+  NotFoundError,
   UsageError,
   createSpinner,
+  errorExitCode,
   loadConfig,
   resolveAuth,
   uploadAppBuild
-} 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";
-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 });
-  }
-}
+} from "./chunk-U7FCGMWG.js";
 
 // src/lib/dev-config.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { readFileSync, writeFileSync } from "fs";
+import { join } from "path";
 var DEV_PLATFORMS = ["ios", "android", "tvos", "androidtv", "roku"];
 var ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 var PLATFORM_NEEDS_METRO = {
@@ -178,10 +27,25 @@ var FILE = "vibeview.json";
 function isDevPlatform(p) {
   return typeof p === "string" && DEV_PLATFORMS.includes(p);
 }
+var PLATFORM_LABELS = {
+  ios: "iOS",
+  android: "Android",
+  tvos: "tvOS",
+  androidtv: "Android TV",
+  roku: "Roku"
+};
+function platformLabel(platform) {
+  return isDevPlatform(platform) ? PLATFORM_LABELS[platform] : platform;
+}
+function platformWithArticle(platform) {
+  const label = platformLabel(platform);
+  const article = /^[aeiou]/i.test(label) ? "an" : "a";
+  return `${article} ${label}`;
+}
 function loadDevConfig(cwd) {
   let raw;
   try {
-    raw = readFileSync2(join2(cwd, FILE), "utf-8");
+    raw = readFileSync(join(cwd, FILE), "utf-8");
   } catch {
     return null;
   }
@@ -298,7 +162,7 @@ function validateBuildEnv(env, platformKey) {
   }
 }
 function saveDevConfig(cwd, cfg) {
-  writeFileSync2(join2(cwd, FILE), JSON.stringify(cfg, null, 2) + "\n");
+  writeFileSync(join(cwd, FILE), JSON.stringify(cfg, null, 2) + "\n");
 }
 function resolveMetro(cfg, platform, portFlag) {
   const entry = cfg?.platforms?.[platform];
@@ -342,6 +206,173 @@ function buildSavedConfig(input2) {
   };
 }
 
+// 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 ${platformWithArticle(app.platform)} app, not ${platformLabel(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 ${platformWithArticle(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";
+
+// src/lib/formatters/time.ts
+function formatUtcTimestamp(iso) {
+  if (!iso) return "";
+  const hasZone = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(iso);
+  const d = new Date(hasZone ? iso : `${iso}Z`);
+  if (Number.isNaN(d.getTime())) return iso;
+  return `${d.toISOString().slice(0, 19).replace("T", " ")} UTC`;
+}
+
+// src/commands/list-builds.ts
+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,
+    formatUtcTimestamp(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 = errorExitCode(err);
+  }
+}
+
+// src/lib/dev-state.ts
+import { existsSync, mkdirSync, readFileSync as readFileSync2, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+var STATE_DIR = ".vibeview";
+var STATE_FILE = "dev-state.json";
+function statePath(cwd) {
+  return join2(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 = join2(cwd, ".gitignore");
+    if (!existsSync(gitignore)) return;
+    const content = readFileSync2(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" : "";
+    writeFileSync2(gitignore, `${content}${prefix}
+# VibeView local session state
+.vibeview/
+`);
+  } catch {
+  }
+}
+function writeDevState(cwd, state) {
+  const path = statePath(cwd);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync2(path, JSON.stringify(state, null, 2) + "\n");
+  ensureGitignored(cwd);
+}
+function readDevState(cwd) {
+  let raw;
+  try {
+    raw = readFileSync2(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/metro-check.ts
 async function checkMetro(port, timeoutMs = 1500) {
   try {
@@ -871,7 +902,7 @@ function runTar(args) {
 var CLOUD_PLATFORMS = ["ios", "android", "tvos", "androidtv"];
 var PRODUCTION_SIGNING_PLATFORMS = ["ios", "android", "androidtv", "tvos"];
 function productionUnsupportedReason(platform) {
-  return `--production doesn't support ${platform} \u2014 production signing supports ${PRODUCTION_SIGNING_PLATFORMS.join(", ")}`;
+  return `--production doesn't support ${platformLabel(platform)} \u2014 production signing supports ${PRODUCTION_SIGNING_PLATFORMS.join(", ")}`;
 }
 function isCloudPlatform(p) {
   return CLOUD_PLATFORMS.includes(p);
@@ -898,7 +929,7 @@ async function runBuildForPlatform(cwd, platform, build, opts, log, deps = { upl
     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`
+        `you built ${platformWithArticle(result.platform)} app (${result.name}) but the target platform is ${platformLabel(platform)} \u2014 check platforms.${platform}.build in vibeview.json`
       );
     }
     return result;
@@ -1056,7 +1087,7 @@ async function buildCommand(opts, cloudDeps) {
     if (!(err instanceof BuildFailError)) {
       printFailure(opts, err instanceof Error ? err.message : String(err));
     }
-    process.exitCode = 1;
+    process.exitCode = errorExitCode(err);
   }
 }
 function printFailure(opts, message, code) {
@@ -1135,7 +1166,7 @@ function requireCloudCapable(opts, platform) {
   if (!isCloudPlatform(platform)) {
     fail(
       opts,
-      `cloud builds don't support ${platform} \u2014 pass one of ${CLOUD_PLATFORMS.join(", ")}`
+      `cloud builds don't support ${platformLabel(platform)} \u2014 pass one of ${CLOUD_PLATFORMS.join(", ")}`
     );
   }
 }
@@ -2393,13 +2424,13 @@ function buildAppStrategy(apps, buildFlag, json, isTTY) {
   if (json || !isTTY) return "pick";
   return "ask";
 }
-function requireNonInteractive(json) {
+function noBuildConfigMessage(platform, interactive) {
+  const addKey = `add platforms.${platform}.build {command, artifact} to vibeview.json`;
+  return interactive ? `no build config for ${platform}: ${addKey}, or run \`vibeview build --platform ${platform}\` once to set it up` : `no build config for ${platform}: ${addKey}`;
+}
+function requireNonInteractive(json, message) {
   if (!json) return;
-  emit(json, {
-    event: "error",
-    code: "config_required",
-    message: "pass --platform and run once interactively, or commit vibeview.json"
-  });
+  emit(json, { event: "error", code: "config_required", message });
   process.exit(1);
 }
 async function ensureConfig(api, opts) {
@@ -2409,7 +2440,10 @@ async function ensureConfig(api, opts) {
     process.exit(2);
   }
   if (!opts.platform && !existing?.defaultPlatform) {
-    requireNonInteractive(opts.json);
+    requireNonInteractive(
+      opts.json,
+      `--platform is required (no vibeview.json default yet) \u2014 pass --platform <${DEV_PLATFORMS.join("|")}>, or run once interactively to set a default.`
+    );
   }
   const platform = opts.platform || existing?.defaultPlatform || await select3({
     message: "Platform to run on",
@@ -2441,9 +2475,7 @@ async function ensureConfig(api, opts) {
   let isFirstRun = false;
   if (!existing) {
     isFirstRun = true;
-    if (opts.json) {
-      requireNonInteractive(opts.json);
-    } else if (process.stdin.isTTY) {
+    if (!opts.json && process.stdin.isTTY) {
       firstRunBuild = await promptBuildConfig(process.cwd(), platform);
       if (PLATFORM_NEEDS_METRO[platform]) {
         firstRunMetro = await promptMetroCommand(process.cwd(), platform);
@@ -2524,7 +2556,10 @@ Run \`vibeview dev\` without --app to pick from the list.`
       emit(opts.json, { event: "error", code: "app_deleted", message });
       process.exit(1);
     }
-    requireNonInteractive(opts.json);
+    requireNonInteractive(
+      opts.json,
+      `--app is required \u2014 no app configured for ${platform} yet; pass --app <id> (see \`vibeview list-apps\`), or run interactively to pick one.`
+    );
     if (!process.stdin.isTTY) {
       console.error(
         chalk4.red(
@@ -2557,14 +2592,17 @@ Run \`vibeview dev\` without --app to pick from the list.`
     firstRunMetro,
     firstRunBuild
   });
-  saveDevConfig(process.cwd(), cfg);
-  if (isFirstRun) {
-    const hint = fillLaterHint(
-      { build: !firstRunBuild, metro: PLATFORM_NEEDS_METRO[platform] && !firstRunMetro },
-      platform
-    );
-    if (hint) console.error(chalk4.dim(hint));
-  }
+  const commitConfig = () => {
+    saveDevConfig(process.cwd(), cfg);
+    if (isFirstRun) {
+      console.error(chalk4.dim(`Created vibeview.json (platform: ${platform}, app: ${appId}).`));
+      const hint = fillLaterHint(
+        { build: !firstRunBuild, metro: PLATFORM_NEEDS_METRO[platform] && !firstRunMetro },
+        platform
+      );
+      if (hint) console.error(chalk4.dim(hint));
+    }
+  };
   const finalMetro = isFirstRun ? resolveMetro(cfg, platform, opts.metroPort ? parseInt(opts.metroPort, 10) : void 0) : metroResolved;
   return {
     platform,
@@ -2574,7 +2612,9 @@ Run \`vibeview dev\` without --app to pick from the list.`
     metroPort: finalMetro.port,
     metroCommand: finalMetro.command,
     platformHasMetroOverride: finalMetro.platformHasOverride,
-    builtThisRun
+    builtThisRun,
+    savedConfig: cfg,
+    commitConfig
   };
 }
 async function runDevInProcess(opts) {
@@ -2623,11 +2663,20 @@ async function runDevInProcess(opts) {
       process.exit(1);
     }
   }
+  const interactive = !opts.json && Boolean(process.stdin.isTTY);
+  const plannedBuild = cfg.savedConfig.platforms?.[cfg.platform]?.build;
+  if (!plannedBuild && (opts.build === true && !cfg.builtThisRun || !PLATFORM_NEEDS_METRO[cfg.platform])) {
+    const message = noBuildConfigMessage(cfg.platform, interactive);
+    console.error(chalk4.red(`error: ${message}`));
+    emit(opts.json, { event: "error", code: "config_required", message });
+    process.exit(1);
+  }
+  cfg.commitConfig();
   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`;
+      const message = noBuildConfigMessage(cfg.platform, interactive);
       console.error(chalk4.red(`error: ${message}`));
       emit(opts.json, { event: "error", code: "config_required", message });
       process.exit(1);
@@ -2700,7 +2749,7 @@ async function runDevInProcess(opts) {
     rokuBuild = rokuEntry?.build;
     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`;
+      const message = noBuildConfigMessage(cfg.platform, interactive);
       console.error(chalk4.red(`error: ${message}`));
       emit(opts.json, { event: "error", code: "config_required", message });
       process.exit(1);
@@ -2708,7 +2757,7 @@ async function runDevInProcess(opts) {
   }
   console.error(
     chalk4.dim(
-      `Starting a ${cfg.platform} dev session for ${cfg.appId}${pinnedBuildId !== void 0 ? ` (build ${pinnedBuildId})` : ""}...`
+      `Starting ${platformWithArticle(cfg.platform)} dev session for ${cfg.appId}${pinnedBuildId !== void 0 ? ` (build ${pinnedBuildId})` : ""}...`
     )
   );
   let stopping = false;
@@ -3038,6 +3087,26 @@ function formatDeviceModelsHuman(models) {
 }
 
 // src/agent/registry.ts
+var PRESS_BUTTONS_BY_PLATFORM = [
+  ["iPhone / iPad", ["home", "back", "lock", "siri"]],
+  ["Android phone / tablet", ["home", "back", "lock"]],
+  [
+    "Apple TV / Android TV",
+    ["dpad_up", "dpad_down", "dpad_left", "dpad_right", "dpad_center", "back", "home"]
+  ],
+  [
+    "Roku (beta)",
+    ["up", "down", "left", "right", "select", "back", "(dpad_* also work; home is not forwarded)"]
+  ]
+];
+function pressButtonsHelp() {
+  return [
+    "Valid buttons:",
+    ...PRESS_BUTTONS_BY_PLATFORM.map(
+      ([platform, buttons]) => `  ${platform}: ${buttons.join(", ")}`
+    )
+  ].join("\n");
+}
 var AGENT_COMMANDS = [
   {
     verb: "ui-tree",
@@ -3071,7 +3140,7 @@ var AGENT_COMMANDS = [
   {
     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.",
+    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. On a phone or tablet its pixels are the coordinates `tap`/`drag` take, so a point read off it can be tapped as is.",
     mutating: false,
     params: [
       {
@@ -3306,7 +3375,7 @@ var AGENT_COMMANDS = [
         cli: "positional",
         type: "string",
         required: true,
-        description: "Text to type into the focused field."
+        description: "Text to type into the focused field. On a phone or tablet a line break presses Enter, which submits the field (bash: $'query\\n'); `press enter` does the same."
       }
     ]
   },
@@ -3332,7 +3401,7 @@ var AGENT_COMMANDS = [
         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."
+        description: "Button to press. iPhone/iPad: home, back, lock, siri. Android: home, back, lock. Apple TV / Android TV: dpad_up, dpad_down, dpad_left, dpad_right, dpad_center, back, home. Roku: up, down, left, right, select, back (dpad_* also work; home is not forwarded)."
       }
     ]
   },
@@ -3340,7 +3409,7 @@ var AGENT_COMMANDS = [
     // tools.py open_url: { url: string }.
     verb: "open-url",
     tool: "open_url",
-    summary: "Open a deep link or URL in the app under test.",
+    summary: "Open a deep link or URL in the app under test. The link goes to that app only; one it has no screen for fails rather than opening a browser.",
     mutating: true,
     params: [
       {
@@ -3360,7 +3429,7 @@ var AGENT_COMMANDS = [
     // Foldable devices only.
     verb: "set-posture",
     tool: "set_posture",
-    summary: "Fold or unfold a foldable device (iPhone Duo): a preset (closed, partial, open) or an exact hinge angle in degrees (--angle 0-180) \u2014 pass exactly one. Reports the posture it settled in, the angle, and which screen is lit. Errors on a device without a hinge.",
+    summary: "Fold or unfold a foldable device (form factor `foldable` in `list-devices --models` \u2014 the iPhone Duo, Android foldables such as the Pixel 9 Pro Fold): a preset (closed, partial, open) or an exact hinge angle in degrees (--angle 0-180) \u2014 pass exactly one. Reports the posture it settled in, the angle, and which screen is lit. Errors on a device without a hinge.",
     mutating: true,
     params: [
       {
@@ -3386,7 +3455,7 @@ var AGENT_COMMANDS = [
     // portrait <-> landscape and accepts only 90. Refused on TV devices.
     verb: "rotate",
     tool: "rotate",
-    summary: "Rotate the device. A phone toggles between portrait and landscape; a foldable (iPhone Duo) turns a quarter clockwise, or by --degrees 180/270. Reports the new orientation. Not available on TV devices.",
+    summary: "Rotate the device. A phone (and an Android foldable) toggles between portrait and landscape; the iPhone Duo turns a quarter clockwise, or by --degrees 180/270. Reports the new orientation. Not available on TV devices.",
     mutating: true,
     params: [
       {
@@ -3394,7 +3463,7 @@ var AGENT_COMMANDS = [
         cli: "--degrees",
         type: "number",
         required: false,
-        description: "Foldable only: 90 (default, a quarter turn clockwise), 180, or 270 (a quarter turn back). A phone accepts only 90."
+        description: "iPhone Duo only: 90 (default, a quarter turn clockwise), 180, or 270 (a quarter turn back). Other devices accept only 90."
       }
     ]
   },
@@ -3769,13 +3838,13 @@ async function runAgentVerb(cmd, positionals, opts) {
   } 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;
+      const code = err instanceof AuthError ? "auth_failed" : err instanceof NotFoundError ? "not_found" : void 0;
       console.log(JSON.stringify({ event: "error", code, message }));
     } else {
       process.stderr.write(`error: ${message}
 `);
     }
-    process.exit(1);
+    process.exit(errorExitCode(err));
   }
   if (cmd.verb === "screenshot" && envelope.ok && envelope.result) {
     const outPath = opts.out || defaultScreenshotPath();
@@ -3801,13 +3870,20 @@ async function runAgentVerb(cmd, positionals, opts) {
     console.log(JSON.stringify(envelope));
   } else {
     console.log(renderEnvelope(envelope));
+    if (cmd.verb === "press" && !envelope.ok) process.stderr.write(pressButtonsHelp() + "\n");
   }
   process.exit(agentExitCode(envelope));
 }
 
 export {
+  DEV_PLATFORMS,
+  PLATFORM_NEEDS_METRO,
+  isDevPlatform,
+  platformWithArticle,
+  loadDevConfig,
   parseBuildId,
   checkDevBuild,
+  formatUtcTimestamp,
   buildRows,
   formatBuildRowsHuman,
   listBuilds,
@@ -3815,10 +3891,6 @@ export {
   clearDevState,
   readMetroState,
   killOwnedMetro,
-  DEV_PLATFORMS,
-  PLATFORM_NEEDS_METRO,
-  isDevPlatform,
-  loadDevConfig,
   checkMetro,
   buildCommand,
   formatDuration,
@@ -3835,6 +3907,7 @@ export {
   formatDevicesHuman,
   filterDeviceModels,
   formatDeviceModelsHuman,
+  pressButtonsHelp,
   AGENT_COMMANDS,
   renderEnvelope,
   buildToolCall,