openuispec 0.2.8 → 0.2.10

package/mcp-server/index.ts

@@ -25,9 +25,9 @@ import { loadTargetDrift } from "../drift/index.js";
 import { readFileSync as fsReadFileSync, existsSync, readdirSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import YAML from "yaml";
-import { takeScreenshot } from "./screenshot.js";
-import { takeAndroidScreenshot } from "./screenshot-android.js";
-import { takeIOSScreenshot } from "./screenshot-ios.js";
+import { takeScreenshot, takeScreenshotBatch } from "./screenshot.js";
+import { takeAndroidScreenshot, takeAndroidScreenshotBatch } from "./screenshot-android.js";
+import { takeIOSScreenshot, takeIOSScreenshotBatch } from "./screenshot-ios.js";
 
 // ── resolve project cwd ──────────────────────────────────────────────
 
@@ -777,6 +777,97 @@ server.registerTool(
   }
 );
 
+// ── tool: openuispec_screenshot_web_batch ──────────────────────────────
+
+const webBatchCaptureSchema = z.object({
+  screen: z.string().describe("Screen name for metadata and filename"),
+  route: z.string().describe("Route path (e.g. '/home', '/settings')"),
+  selector: z.string().optional().describe("CSS selector to screenshot a specific element"),
+  full_page: z.boolean().optional().describe("Capture full scrollable page"),
+  wait_for: z.number().optional().describe("Per-capture wait time in ms"),
+});
+
+server.registerTool(
+  "openuispec_screenshot_web_batch",
+  {
+    description: "Take multiple web screenshots in a single server session. Starts the dev server once, then captures all routes in sequence. Much faster than calling screenshot for each route individually.",
+    inputSchema: {
+      captures: z.array(webBatchCaptureSchema).describe("Array of captures — each with screen name and route"),
+      viewport: z.object({ width: z.number().default(1280), height: z.number().default(800) }).optional().describe("Viewport dimensions for all captures"),
+      theme: z.enum(["light", "dark"]).optional().describe("Force color scheme for all captures"),
+      output_dir: z.string().optional().describe("Directory to save all PNGs (relative to web app root)"),
+    },
+  },
+  async ({ captures, viewport, theme, output_dir }) => {
+    try {
+      return await takeScreenshotBatch(projectCwd, { captures, viewport, theme, output_dir });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_screenshot_android_batch ─────────────────────────
+
+const androidBatchCaptureSchema = z.object({
+  screen: z.string().describe("Screen name for metadata and filename"),
+  route: z.string().optional().describe("Deep link URI to launch"),
+  nav: z.array(z.string()).optional().describe("UI tap steps after launch"),
+  wait_for: z.number().optional().describe("Per-capture wait time in ms"),
+});
+
+server.registerTool(
+  "openuispec_screenshot_android_batch",
+  {
+    description: "Take multiple Android screenshots in a single build+install cycle. Builds the APK once, installs once, then captures each screen in sequence via deep links or UI navigation. Much faster than calling screenshot_android for each screen individually.",
+    inputSchema: {
+      captures: z.array(androidBatchCaptureSchema).describe("Array of captures — each with screen name and optional route/nav"),
+      theme: z.enum(["light", "dark"]).optional().describe("Force light or dark mode for all captures"),
+      output_dir: z.string().optional().describe("Directory to save all PNGs (relative to Android project root)"),
+      project_dir: z.string().optional().describe("Direct path to Android project root"),
+      module: z.string().optional().describe("App module name (default: auto-detect)"),
+    },
+  },
+  async ({ captures, theme, output_dir, project_dir, module }) => {
+    try {
+      return await takeAndroidScreenshotBatch(projectCwd, { captures, theme, output_dir, project_dir, module });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
+// ── tool: openuispec_screenshot_ios_batch ──────────────────────────────
+
+const iosBatchCaptureSchema = z.object({
+  screen: z.string().describe("Screen name for metadata and filename"),
+  nav: z.array(z.string()).optional().describe("UI tap steps after launch"),
+  wait_for: z.number().optional().describe("Per-capture wait time in ms"),
+});
+
+server.registerTool(
+  "openuispec_screenshot_ios_batch",
+  {
+    description: "Take multiple iOS screenshots in a single build+install cycle. Builds the app once, then captures each screen — no-nav screens via simctl, nav screens batched into a single XCUITest run. Much faster than calling screenshot_ios for each screen individually.",
+    inputSchema: {
+      captures: z.array(iosBatchCaptureSchema).describe("Array of captures — each with screen name and optional nav steps"),
+      device: z.string().optional().describe("Simulator device name"),
+      theme: z.enum(["light", "dark"]).optional().describe("Force light or dark appearance for all captures"),
+      output_dir: z.string().optional().describe("Directory to save all PNGs (relative to iOS project root)"),
+      project_dir: z.string().optional().describe("Direct path to iOS project root"),
+      scheme: z.string().optional().describe("Xcode scheme name"),
+      bundle_id: z.string().optional().describe("App bundle identifier"),
+    },
+  },
+  async ({ captures, device, theme, output_dir, project_dir, scheme, bundle_id }) => {
+    try {
+      return await takeIOSScreenshotBatch(projectCwd, { captures, device, theme, output_dir, project_dir, scheme, bundle_id });
+    } catch (err) {
+      return toolError(err);
+    }
+  }
+);
+
 // ── start server ─────────────────────────────────────────────────────
 
 export async function startMcpServer() {

package/mcp-server/screenshot-android.ts

@@ -17,6 +17,7 @@ import {
 } from "./screenshot-shared.js";
 
 const exec = promisify(execCb);
+const androidScreenshotQueues = new Map<string, Promise<void>>();
 
 // ── types ───────────────────────────────────────────────────────────
 
@@ -31,6 +32,21 @@ export interface AndroidScreenshotOptions {
   module?: string;
 }
 
+export interface AndroidBatchCapture {
+  screen: string;
+  route?: string;
+  nav?: string[];
+  wait_for?: number;
+}
+
+export interface AndroidScreenshotBatchOptions {
+  captures: AndroidBatchCapture[];
+  theme?: "light" | "dark";
+  output_dir?: string;
+  project_dir?: string;
+  module?: string;
+}
+
 // ── constants ───────────────────────────────────────────────────────
 
 const ADB_SCREENSHOT_PATH = "/sdcard/openuispec_screenshot.png";
@@ -213,18 +229,14 @@ export async function adbExec(adb: string, serial: string, args: string): Promis
 // ── emulator storage cleanup ─────────────────────────────────────────
 
 export async function cleanEmulatorStorage(adb: string, serial: string): Promise<void> {
-  try {
-    // Clear package manager cache
-    await adbShell(adb, serial, `pm trim-caches 512M`);
-  } catch { /* may require root, skip */ }
-  try {
-    // Remove leftover screenshot/temp files
-    await adbShell(adb, serial, `rm -f /sdcard/openuispec_screenshot.png /sdcard/ui_dump.xml /sdcard/screenshot.png`);
-  } catch { /* ignore */ }
-  try {
-    // Clear temp files
-    await adbShell(adb, serial, `rm -rf /data/local/tmp/*.apk`);
-  } catch { /* ignore */ }
+  const cmds = [
+    `pm trim-caches 2G`,                    // aggressively trim package cache
+    `rm -rf /data/local/tmp/*.apk`,          // leftover APKs from previous installs
+    `rm -f /sdcard/openuispec_screenshot.png /sdcard/ui_dump.xml /sdcard/screenshot.png`,
+  ];
+  for (const cmd of cmds) {
+    try { await adbShell(adb, serial, cmd); } catch { /* ignore */ }
+  }
 }
 
 // ── build APK ───────────────────────────────────────────────────────
@@ -269,23 +281,41 @@ export async function installAndLaunch(
   appInfo: AppInfo,
   route?: string,
 ): Promise<void> {
-  // Install (replace existing)
-  await adbExec(adb, serial, `install -r "${apkPath}"`);
-
-  // Force-stop and clear saved navigation state
+  // Force-stop and uninstall to free storage + wipe saved nav state
   await adbShell(adb, serial, `am force-stop ${appInfo.applicationId}`);
+  try { await adbShell(adb, serial, `pm uninstall ${appInfo.applicationId}`); } catch { /* not installed */ }
 
-  // FLAG_ACTIVITY_NEW_TASK | FLAG_ACTIVITY_CLEAR_TASK = 0x10008000
-  // Clears saved navigation state so deep links route correctly
-  const clearFlags = `-f 0x10008000`;
+  // Install fresh (not -r replace, since we uninstalled)
+  await adbExec(adb, serial, `install "${apkPath}"`);
 
   if (route) {
     await adbShell(adb, serial,
-      `am start -W -a android.intent.action.VIEW -d "${route}" ${clearFlags} ` +
+      `am start -W -a android.intent.action.VIEW -d '${route}' ` +
       `${appInfo.applicationId}/${appInfo.launchActivity}`);
   } else {
     await adbShell(adb, serial,
-      `am start -W ${clearFlags} -n ${appInfo.applicationId}/${appInfo.launchActivity}`);
+      `am start -W -n ${appInfo.applicationId}/${appInfo.launchActivity}`);
+  }
+}
+
+export async function launchInstalledApp(
+  adb: string,
+  serial: string,
+  appInfo: AppInfo,
+  route?: string,
+): Promise<void> {
+  await adbShell(adb, serial, `am force-stop ${appInfo.applicationId}`);
+  // Clear saved nav state so deep links route correctly
+  try { await adbShell(adb, serial, `pm clear ${appInfo.applicationId}`); } catch { /* ignore */ }
+  if (route) {
+    await adbShell(
+      adb,
+      serial,
+      `am start -W -a android.intent.action.VIEW -d '${route}' ` +
+        `${appInfo.applicationId}/${appInfo.launchActivity}`,
+    );
+  } else {
+    await adbShell(adb, serial, `am start -W -n ${appInfo.applicationId}/${appInfo.launchActivity}`);
   }
 }
 
@@ -365,9 +395,12 @@ export async function captureScreenshot(
   serial: string,
   localPath: string,
 ): Promise<void> {
-  await adbShell(adb, serial, `screencap -p ${ADB_SCREENSHOT_PATH}`);
-  await adbExec(adb, serial, `pull ${ADB_SCREENSHOT_PATH} "${localPath}"`);
-  await adbShell(adb, serial, `rm ${ADB_SCREENSHOT_PATH}`);
+  try {
+    await exec(`${adb} -s ${serial} exec-out screencap -p > "${localPath}"`, { timeout: 60_000, shell: "/bin/bash" });
+  } catch (err: any) {
+    const output = ((err.stderr ?? "") + "\n" + (err.stdout ?? "")).trim();
+    throw new Error(`Android screenshot capture failed${output ? `:\n${output}` : "."}`);
+  }
 }
 
 // ── wait for app ready ──────────────────────────────────────────────
@@ -402,6 +435,47 @@ async function waitForAppReady(
   await new Promise(r => setTimeout(r, waitMs));
 }
 
+async function takeSingleAndroidCapture(
+  adb: string,
+  serial: string,
+  androidDir: string,
+  appInfo: AppInfo,
+  capture: AndroidBatchCapture,
+  theme: "light" | "dark" | undefined,
+  defaultOutputDir: string | undefined,
+): Promise<{ screen: string; path: string; data: string }> {
+  await launchInstalledApp(adb, serial, appInfo, capture.route);
+  await waitForAppReady(adb, serial, appInfo.applicationId, capture.wait_for ?? 3000);
+
+  if (capture.nav && capture.nav.length > 0) {
+    await navigateByTaps(adb, serial, capture.nav);
+  }
+
+  const themeLabel = theme ?? "default";
+  const filename = `${capture.screen}_${themeLabel}.png`;
+  const tmpPath = join(androidDir, `.openuispec-screenshot-${capture.screen}.png`);
+  await captureScreenshot(adb, serial, tmpPath);
+
+  let savedPath = filename;
+  if (defaultOutputDir) {
+    const outDir = resolve(androidDir, defaultOutputDir);
+    mkdirSync(outDir, { recursive: true });
+    savedPath = join(outDir, filename);
+    copyFileSync(tmpPath, savedPath);
+  }
+
+  try {
+    const data = readFileSync(tmpPath).toString("base64");
+    return {
+      screen: capture.screen,
+      path: savedPath,
+      data,
+    };
+  } finally {
+    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+}
+
 // ── main entry point ────────────────────────────────────────────────
 
 export async function takeAndroidScreenshot(
@@ -427,61 +501,121 @@ export async function takeAndroidScreenshot(
   const adb = findAdb();
   const serial = await getConnectedEmulator(adb);
 
-  // 3. Free emulator storage before build/install
-  await cleanEmulatorStorage(adb, serial);
+  const previousRun = androidScreenshotQueues.get(serial) ?? Promise.resolve();
+  let releaseQueue: (() => void) | undefined;
+  const currentRun = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  androidScreenshotQueues.set(serial, previousRun.then(() => currentRun));
 
-  // 4. Build APK
-  const apkPath = await buildApk(androidDir, appInfo.moduleName);
+  await previousRun;
 
-  // 5. Set theme if requested
-  if (theme) {
-    await setTheme(adb, serial, theme);
-  }
+  try {
+    // 3. Free emulator storage before build/install
+    await cleanEmulatorStorage(adb, serial);
 
-  // 6. Install and launch
-  await installAndLaunch(adb, serial, apkPath, appInfo, route);
+    // 4. Build APK
+    const apkPath = await buildApk(androidDir, appInfo.moduleName);
 
-  // 7. Wait for app to be ready and content to load
-  await waitForAppReady(adb, serial, appInfo.applicationId, wait_for);
+    // 5. Set theme if requested
+    if (theme) {
+      await setTheme(adb, serial, theme);
+    }
 
-  // 8. Navigate via UI taps if specified
-  if (nav && nav.length > 0) {
-    await navigateByTaps(adb, serial, nav);
-  }
+    // 6. Install fresh once, then capture
+    await installAndLaunch(adb, serial, apkPath, appInfo, route);
+
+    const snapshot = await takeSingleAndroidCapture(
+      adb,
+      serial,
+      androidDir,
+      appInfo,
+      { screen: screen ?? "main", route, nav, wait_for },
+      theme,
+      output_dir,
+    );
 
-  // 9. Capture screenshot
-  const screenLabel = screen ?? "main";
-  const themeLabel = theme ?? "default";
-  const filename = `${screenLabel}_${themeLabel}.png`;
-  const tmpPath = join(androidDir, ".openuispec-screenshot.png");
-  await captureScreenshot(adb, serial, tmpPath);
+    return buildScreenshotResponse([snapshot], (s) => ({
+      screen: s.screen,
+      path: snapshot.path ?? null,
+      emulator: serial,
+      theme: theme ?? "default",
+      applicationId: appInfo.applicationId,
+    }));
+  } finally {
+    releaseQueue?.();
+    if (androidScreenshotQueues.get(serial) === currentRun) {
+      androidScreenshotQueues.delete(serial);
+    }
+  }
+}
 
-  // 9. Save to output_dir if specified
-  let savedPath: string | undefined;
-  if (output_dir) {
-    const outDir = resolve(androidDir, output_dir);
-    mkdirSync(outDir, { recursive: true });
-    savedPath = join(outDir, filename);
-    copyFileSync(tmpPath, savedPath);
+export async function takeAndroidScreenshotBatch(
+  projectCwd: string,
+  options: AndroidScreenshotBatchOptions,
+): Promise<ScreenshotResult> {
+  const { captures, theme, output_dir, project_dir, module } = options;
+  if (captures.length === 0) {
+    return {
+      content: [{ type: "text", text: "No Android captures specified." }],
+      isError: true,
+    };
   }
 
-  // 10. Read and return
+  const androidDir = findAndroidAppDir(projectCwd, project_dir);
+  const appInfo = extractAppInfo(androidDir, module);
+  const adb = findAdb();
+  const serial = await getConnectedEmulator(adb);
+
+  const previousRun = androidScreenshotQueues.get(serial) ?? Promise.resolve();
+  let releaseQueue: (() => void) | undefined;
+  const currentRun = new Promise<void>((resolve) => {
+    releaseQueue = resolve;
+  });
+  androidScreenshotQueues.set(serial, previousRun.then(() => currentRun));
+
+  await previousRun;
+
   try {
-    const data = readFileSync(tmpPath).toString("base64");
-    const snapshots = [{
-      screen: screenLabel,
-      path: savedPath ?? filename,
-      data,
-    }];
+    await cleanEmulatorStorage(adb, serial);
+    const apkPath = await buildApk(androidDir, appInfo.moduleName);
 
-    return buildScreenshotResponse(snapshots, (s) => ({
-      screen: s.screen,
-      path: savedPath ?? null,
+    if (theme) {
+      await setTheme(adb, serial, theme);
+    }
+
+    await installAndLaunch(adb, serial, apkPath, appInfo);
+
+    // Pre-create output dir once
+    if (output_dir) mkdirSync(resolve(androidDir, output_dir), { recursive: true });
+
+    const snapshots = [];
+    for (let index = 0; index < captures.length; index += 1) {
+      const capture = captures[index];
+      snapshots.push(
+        await takeSingleAndroidCapture(
+          adb,
+          serial,
+          androidDir,
+          appInfo,
+          capture,
+          theme,
+          output_dir,
+        ),
+      );
+    }
+
+    return buildScreenshotResponse(snapshots, (snapshot) => ({
+      screen: snapshot.screen,
+      path: snapshot.path,
       emulator: serial,
-      theme: themeLabel,
+      theme: theme ?? "default",
       applicationId: appInfo.applicationId,
     }));
   } finally {
-    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+    releaseQueue?.();
+    if (androidScreenshotQueues.get(serial) === currentRun) {
+      androidScreenshotQueues.delete(serial);
+    }
   }
 }