vibeview 0.8.0 → 0.9.0

package/README.md

@@ -46,6 +46,14 @@ vibeview tap @e5            # act — the response says what changed
 vibeview screenshot --out ./check.png
 ```
 
+One command makes it discoverable to your agent — it installs the bundled
+`vibeview-agent` skill where Claude Code finds it automatically and offers
+to register the MCP server:
+
+```bash
+vibeview agent-setup
+```
+
 Every command works over MCP too, for agents without shell access:
 
 ```bash
@@ -53,7 +61,7 @@ claude mcp add vibeview -- vibeview mcp
 ```
 
 Other MCP clients (Cursor, Claude Desktop, VS Code Copilot) run command
-`vibeview` with args `["mcp"]`. The package also ships a ready-made skill at
+`vibeview` with args `["mcp"]`. The package also ships the skill at
 `skills/vibeview-agent/SKILL.md` describing the whole workflow.
 
 [Agent control docs →](https://vibeview.io/docs/agent-control)
@@ -84,6 +92,7 @@ Output formats: `human`, `json`, and `junit` for any CI system. The exit code re
 | `vibeview dev` | Live development on a cloud device |
 | `vibeview build` | Build your app and upload it |
 | `vibeview dev-status` / `dev-stop` | Check on, or stop, a backgrounded dev session |
+| `vibeview agent-setup` | Make VibeView discoverable to your coding agent (skill + MCP) |
 | `vibeview mcp` | Run the MCP server so an agent can drive the device |
 | `vibeview ui-tree` | The current screen's elements, each with a ref to act on |
 | `vibeview screenshot` | Capture the screen to a PNG |

package/dist/{chunk-NZ4G3JKV.js → chunk-WG2XR45H.js}

@@ -866,6 +866,11 @@ async function startDevSession(cfg, onEvent = () => {
     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);
@@ -890,6 +895,22 @@ async function pollUntilTunnelReady(api, sessionId, timeoutMs, intervalMs = 2e3)
     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 },

package/dist/cli.js

@@ -8,7 +8,7 @@ import {
   readDevState,
   readMetroState,
   runAgentVerb
-} from "./chunk-NZ4G3JKV.js";
+} from "./chunk-WG2XR45H.js";
 import {
   ApiClient,
   EXIT_INFRA_ERROR,
@@ -1205,6 +1205,104 @@ function readMetadataFile(path) {
   return parsed;
 }
 
+// src/commands/agent-setup.ts
+import { copyFileSync, existsSync as existsSync2, mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { spawnSync } from "child_process";
+import { confirm } from "@inquirer/prompts";
+import chalk11 from "chalk";
+function resolveShippedSkillPath(fromDir) {
+  for (const rel of ["..", join("..", "..")]) {
+    const candidate = join(fromDir, rel, "skills", "vibeview-agent", "SKILL.md");
+    if (existsSync2(candidate)) return candidate;
+  }
+  return null;
+}
+function skillInstallDir(project, cwd, home) {
+  const base = project ? cwd : home;
+  return join(base, ".claude", "skills", "vibeview-agent");
+}
+function installSkill(shippedPath, targetDir) {
+  const target = join(targetDir, "SKILL.md");
+  const existed = existsSync2(target);
+  mkdirSync(targetDir, { recursive: true });
+  copyFileSync(shippedPath, target);
+  return existed ? "updated" : "installed";
+}
+var CLAUDE_MD_SUGGESTION = "After changing UI or app behavior, verify it on a live device with the `vibeview` CLI \u2014 the vibeview-agent skill covers the workflow.";
+function claudeCliAvailable() {
+  return spawnSync("claude", ["--version"], { stdio: "ignore" }).error === void 0;
+}
+function registerMcp() {
+  const res = spawnSync("claude", ["mcp", "add", "vibeview", "--", "vibeview", "mcp"], {
+    encoding: "utf8"
+  });
+  if (res.status === 0) {
+    console.log(chalk11.green("\u2713 MCP server registered with Claude Code (claude mcp add vibeview)"));
+    return;
+  }
+  const out = `${res.stderr ?? ""}${res.stdout ?? ""}`;
+  if (out.includes("already exists")) {
+    console.log(chalk11.dim("MCP server already registered with Claude Code \u2014 nothing to do"));
+    return;
+  }
+  console.error(chalk11.yellow(`\u26A0 could not register the MCP server: ${out.trim() || res.error}`));
+  console.error(chalk11.yellow("  register it manually: claude mcp add vibeview -- vibeview mcp"));
+}
+async function agentSetup(opts) {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const shipped = resolveShippedSkillPath(moduleDir);
+  if (!shipped) {
+    console.error(
+      chalk11.red(
+        "error: could not find the packaged skill (skills/vibeview-agent/SKILL.md) \u2014 is this a complete install of the vibeview package?"
+      )
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const targetDir = skillInstallDir(opts.project ?? false, process.cwd(), homedir());
+  const result = installSkill(shipped, targetDir);
+  console.log(chalk11.green(`\u2713 vibeview-agent skill ${result}: ${join(targetDir, "SKILL.md")}`));
+  console.log(
+    chalk11.dim(
+      opts.project ? "  Claude Code discovers it automatically for anyone working in this project." : "  Claude Code discovers it automatically in every project on this machine."
+    )
+  );
+  if (opts.mcp !== false) {
+    if (!claudeCliAvailable()) {
+      if (opts.mcp === true) {
+        console.error(
+          chalk11.yellow(
+            "\u26A0 claude CLI not found \u2014 install Claude Code, then run: claude mcp add vibeview -- vibeview mcp"
+          )
+        );
+      }
+    } else if (opts.mcp === true || process.stdin.isTTY && await confirm({
+      message: "Register the MCP server with Claude Code? (claude mcp add vibeview)",
+      default: true
+    })) {
+      registerMcp();
+    }
+  }
+  console.log(
+    `
+Suggested line for your project's ${chalk11.bold("CLAUDE.md")} (or ${chalk11.bold(
+      "AGENTS.md"
+    )} for other agents):
+`
+  );
+  console.log(`  ${CLAUDE_MD_SUGGESTION}
+`);
+  console.log(
+    chalk11.dim(
+      "Other agents (Cursor, Copilot, Codex, ...): point them at the skill file above, or\nadd the MCP server per client \u2014 see https://vibeview.io/docs/agent-control"
+    )
+  );
+}
+
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
@@ -1350,9 +1448,12 @@ program.command("dev-stop").description("Stop a `vibeview dev --detach` session
 program.command("mcp").description(
   "Run an MCP stdio server exposing the agent verbs (tap, swipe, type, ...) plus dev_start/dev_stop as tools"
 ).option("--token <token>", "API token (or set VIBEVIEW_API_TOKEN)").action(async (opts) => {
-  const { runMcpServer } = await import("./server-JZAEEHZT.js");
+  const { runMcpServer } = await import("./server-S3D724K3.js");
   await runMcpServer(opts);
 });
+program.command("agent-setup").description(
+  "Make VibeView discoverable to your coding agent: install the vibeview-agent skill (and optionally register the MCP server with Claude Code)"
+).option("--project", "Install into this project's .claude/skills/ instead of ~/.claude/skills/").option("--mcp", "Register the MCP server with Claude Code without asking").option("--no-mcp", "Skip MCP registration").action((opts) => agentSetup(opts));
 for (const cmd of AGENT_COMMANDS) {
   const positionalParams = cmd.params.filter((p) => p.cli === "positional");
   const flagParams = cmd.params.filter((p) => p.cli !== "positional");

package/dist/{server-JZAEEHZT.js → server-S3D724K3.js}

@@ -10,7 +10,7 @@ import {
   readDevState,
   renderEnvelope,
   startDevSession
-} from "./chunk-NZ4G3JKV.js";
+} from "./chunk-WG2XR45H.js";
 import {
   ApiClient,
   resolveAuth
@@ -55,7 +55,7 @@ function toolDefFromCommand(cmd) {
 }
 var DEV_START_DEF = {
   name: "dev_start",
-  description: "Start a VibeView dev-loop session (device + tunnel) held in-process by this MCP server, and use it as the default session for every other tool call until dev_stop.",
+  description: "Start a VibeView dev-loop session (device + tunnel) held in-process by this MCP server, and use it as the default session for every other tool call until dev_stop. Returns once the session accepts commands (device up, app installed) \u2014 call ui_tree right away, no readiness polling needed.",
   mutating: true,
   properties: {
     session_id: SESSION_ID_PROPERTY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeview",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "VibeView CLI -- run mobile tests from CI/CD pipelines",
   "type": "module",
   "bin": {

package/skills/vibeview-agent/SKILL.md

@@ -46,9 +46,10 @@ https://vibeview.io/docs/preparing-your-build.
    ```json
    {"event":"session_ready","session_id":"...","url":"...","pid":1234}
    ```
-   Use `session_id` as `--session <id>` on every verb below. If the app
-   ships no native changes since the last run, skip step 1 and just do
-   steps 2–4.
+   Use `session_id` as `--session <id>` on every verb below. The event
+   fires once the session accepts commands (device up, app installed) —
+   no need to poll `dev-status` first. If the app ships no native changes
+   since the last run, skip step 1 and just do steps 2–4.
 
 Running `dev` writes two things into the project root: a `.vibeview/`
 directory (live session state — local machine state, never commit) and a
@@ -64,6 +65,10 @@ it rather than letting it appear unexplained in their `git status`.
   ```bash
   vibeview ui-tree --session <id>
   ```
+  An empty or near-empty first tree usually means the app is still booting
+  (splash screen, fetching remote config) — NOT a broken session. Take a
+  screenshot to confirm, `wait`, and fetch the tree again before concluding
+  anything is wrong.
 - Act on the screen using refs from the tree:
   ```bash
   vibeview tap @e5 --session <id>