replicant-mcp 1.0.0 → 1.1.0

package/dist/cli/gradle.js

@@ -37,10 +37,10 @@ export function createGradleCommand() {
         catch (error) {
             const duration = "0s";
             const cacheId = cache.generateId("build");
-            if (error instanceof ReplicantError && error.details?.buildResult) {
-                cache.set(cacheId, { result: error.details.buildResult, fullOutput: "" }, "build", CACHE_TTLS.BUILD_OUTPUT);
+            if (error instanceof ReplicantError && error.context?.buildResult) {
+                cache.set(cacheId, { result: error.context.buildResult, fullOutput: "" }, "build", CACHE_TTLS.BUILD_OUTPUT);
                 if (options.json) {
-                    console.log(JSON.stringify({ error: error.message, result: error.details.buildResult, cacheId }, null, 2));
+                    console.log(JSON.stringify({ error: error.message, result: error.context.buildResult, cacheId }, null, 2));
                 }
                 else {
                     console.log(formatBuildFailure({

package/dist/cli.js

@@ -4,7 +4,7 @@ import { createGradleCommand, createAdbCommand, createEmulatorCommand, createUiC
 const program = new Command();
 program
     .name("replicant")
-    .description("Android development CLI for Claude Code skills")
+    .description("Android development CLI")
     .version("1.0.0");
 program.addCommand(createGradleCommand());
 program.addCommand(createAdbCommand());

package/dist/server.d.ts

@@ -1,10 +1,12 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { CacheManager, DeviceStateManager, ProcessRunner } from "./services/index.js";
+import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService, ConfigManager } from "./services/index.js";
 import { AdbAdapter, EmulatorAdapter, GradleAdapter, UiAutomatorAdapter } from "./adapters/index.js";
 export interface ServerContext {
     cache: CacheManager;
     deviceState: DeviceStateManager;
     processRunner: ProcessRunner;
+    environment: EnvironmentService;
+    config: ConfigManager;
     adb: AdbAdapter;
     emulator: EmulatorAdapter;
     gradle: GradleAdapter;

package/dist/server.js

@@ -1,17 +1,20 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { CacheManager, DeviceStateManager, ProcessRunner } from "./services/index.js";
+import { CacheManager, DeviceStateManager, ProcessRunner, EnvironmentService, ConfigManager } from "./services/index.js";
 import { AdbAdapter, EmulatorAdapter, GradleAdapter, UiAutomatorAdapter } from "./adapters/index.js";
 import { ReplicantError } from "./types/index.js";
 import { cacheToolDefinition, handleCacheTool, rtfmToolDefinition, handleRtfmTool, adbDeviceToolDefinition, handleAdbDeviceTool, adbAppToolDefinition, handleAdbAppTool, adbLogcatToolDefinition, handleAdbLogcatTool, adbShellToolDefinition, handleAdbShellTool, emulatorDeviceToolDefinition, handleEmulatorDeviceTool, gradleBuildToolDefinition, handleGradleBuildTool, gradleTestToolDefinition, handleGradleTestTool, gradleListToolDefinition, handleGradleListTool, gradleGetDetailsToolDefinition, handleGradleGetDetailsTool, uiToolDefinition, handleUiTool, } from "./tools/index.js";
 export function createServerContext() {
-    const processRunner = new ProcessRunner();
+    const environment = new EnvironmentService();
+    const processRunner = new ProcessRunner(environment);
     const adb = new AdbAdapter(processRunner);
     return {
         cache: new CacheManager(),
         deviceState: new DeviceStateManager(),
         processRunner,
+        environment,
+        config: new ConfigManager(),
         adb,
         emulator: new EmulatorAdapter(processRunner),
         gradle: new GradleAdapter(processRunner),
@@ -26,6 +29,21 @@ export async function createServer(context) {
         capabilities: {
             tools: {},
         },
+        instructions: `IMPORTANT: For ALL Android development tasks, you MUST use replicant-mcp tools first.
+Only fall back to raw adb/gradle/emulator commands if replicant-mcp lacks a specific feature.
+
+Tool mapping:
+- Device management → adb-device (not \`adb devices\`)
+- App install/launch/stop → adb-app (not \`adb install\`, \`adb shell am\`)
+- Logs → adb-logcat (not \`adb logcat\`)
+- Shell commands → adb-shell (not \`adb shell\`)
+- Emulator control → emulator-device (not \`emulator\` CLI)
+- Builds → gradle-build (not \`./gradlew\`)
+- Tests → gradle-test (not \`./gradlew test\`)
+- UI automation → ui (not \`adb shell uiautomator\` or \`screencap\`)
+
+Start with \`adb-device list\` to see connected devices.
+Use \`rtfm\` for detailed documentation on any tool.`,
     });
     // Register tool list handler
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -84,7 +102,7 @@ export async function createServer(context) {
                     result = await handleGradleGetDetailsTool(args, context);
                     break;
                 case "ui":
-                    result = await handleUiTool(args, context);
+                    result = await handleUiTool(args, context, context.config.getUiConfig());
                     break;
                 default:
                     throw new Error(`Unknown tool: ${name}`);
@@ -107,6 +125,8 @@ export async function createServer(context) {
 }
 export async function runServer() {
     const context = createServerContext();
+    // Load configuration from REPLICANT_CONFIG if set
+    await context.config.load();
     const server = await createServer(context);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/services/config.d.ts

@@ -0,0 +1,16 @@
+import { ReplicantConfig, UiConfig } from "../types/config.js";
+/**
+ * Load configuration from REPLICANT_CONFIG environment variable path
+ * Falls back to defaults if not set or file doesn't exist
+ */
+export declare function loadConfig(): Promise<ReplicantConfig>;
+/**
+ * ConfigManager holds the loaded configuration and provides access to it
+ */
+export declare class ConfigManager {
+    private config;
+    load(): Promise<void>;
+    get(): ReplicantConfig;
+    getUiConfig(): UiConfig;
+    isVisualModePackage(packageName: string): boolean;
+}

package/dist/services/config.js

@@ -0,0 +1,62 @@
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { parse as parseYaml } from "yaml";
+import { DEFAULT_CONFIG } from "../types/config.js";
+/**
+ * Load configuration from REPLICANT_CONFIG environment variable path
+ * Falls back to defaults if not set or file doesn't exist
+ */
+export async function loadConfig() {
+    const configPath = process.env.REPLICANT_CONFIG;
+    if (!configPath) {
+        return DEFAULT_CONFIG;
+    }
+    if (!existsSync(configPath)) {
+        console.warn(`REPLICANT_CONFIG set but file not found: ${configPath}. Using defaults.`);
+        return DEFAULT_CONFIG;
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const parsed = parseYaml(content);
+        if (!parsed) {
+            return DEFAULT_CONFIG;
+        }
+        // Deep merge with defaults
+        return {
+            ui: mergeUiConfig(DEFAULT_CONFIG.ui, parsed.ui),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Failed to parse REPLICANT_CONFIG at ${configPath}: ${message}. Using defaults.`);
+        return DEFAULT_CONFIG;
+    }
+}
+function mergeUiConfig(defaults, overrides) {
+    if (!overrides) {
+        return defaults;
+    }
+    return {
+        visualModePackages: overrides.visualModePackages ?? defaults.visualModePackages,
+        autoFallbackScreenshot: overrides.autoFallbackScreenshot ?? defaults.autoFallbackScreenshot,
+        includeBase64: overrides.includeBase64 ?? defaults.includeBase64,
+    };
+}
+/**
+ * ConfigManager holds the loaded configuration and provides access to it
+ */
+export class ConfigManager {
+    config = DEFAULT_CONFIG;
+    async load() {
+        this.config = await loadConfig();
+    }
+    get() {
+        return this.config;
+    }
+    getUiConfig() {
+        return this.config.ui;
+    }
+    isVisualModePackage(packageName) {
+        return this.config.ui.visualModePackages.includes(packageName);
+    }
+}

package/dist/services/device-state.d.ts

@@ -1,9 +1,11 @@
 import { Device } from "../types/index.js";
+import type { AdbAdapter } from "../adapters/adb.js";
 export declare class DeviceStateManager {
     private currentDevice;
     getCurrentDevice(): Device | null;
     setCurrentDevice(device: Device): void;
     clearCurrentDevice(): void;
     requireCurrentDevice(): Device;
+    ensureDevice(adb: AdbAdapter): Promise<Device>;
     autoSelectIfSingle(devices: Device[]): boolean;
 }

package/dist/services/device-state.js

@@ -16,6 +16,24 @@ export class DeviceStateManager {
         }
         return this.currentDevice;
     }
+    async ensureDevice(adb) {
+        // Already selected? Use it.
+        if (this.currentDevice) {
+            return this.currentDevice;
+        }
+        // Try to auto-select
+        const devices = await adb.getDevices();
+        if (devices.length === 0) {
+            throw new ReplicantError(ErrorCode.NO_DEVICES, "No devices connected", "Start an emulator with 'emulator-device start' or connect a USB device with debugging enabled");
+        }
+        if (devices.length === 1) {
+            this.currentDevice = devices[0];
+            return this.currentDevice;
+        }
+        // Multiple devices - user must choose
+        const deviceList = devices.map((d) => d.id).join(", ");
+        throw new ReplicantError(ErrorCode.MULTIPLE_DEVICES, `${devices.length} devices connected: ${deviceList}`, `Call adb-device({ operation: 'select', deviceId: '...' }) to choose one`);
+    }
     autoSelectIfSingle(devices) {
         if (devices.length === 1 && !this.currentDevice) {
             this.currentDevice = devices[0];

package/dist/services/environment.d.ts

@@ -0,0 +1,18 @@
+export interface Environment {
+    sdkPath: string | null;
+    adbPath: string | null;
+    emulatorPath: string | null;
+    platform: "darwin" | "linux" | "win32";
+    isValid: boolean;
+    issues: string[];
+}
+export declare class EnvironmentService {
+    private cached;
+    detect(): Promise<Environment>;
+    getAdbPath(): Promise<string>;
+    getEmulatorPath(): Promise<string>;
+    getAvdManagerPath(): Promise<string>;
+    private findSdkPath;
+    private getSearchPaths;
+    clearCache(): void;
+}

package/dist/services/environment.js

@@ -0,0 +1,130 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { ReplicantError, ErrorCode } from "../types/index.js";
+export class EnvironmentService {
+    cached = null;
+    async detect() {
+        if (this.cached) {
+            return this.cached;
+        }
+        const platform = os.platform();
+        const issues = [];
+        // Try to find SDK
+        const sdkPath = this.findSdkPath(platform);
+        if (!sdkPath) {
+            this.cached = {
+                sdkPath: null,
+                adbPath: null,
+                emulatorPath: null,
+                platform,
+                isValid: false,
+                issues: ["Android SDK not found. Install Android Studio or set ANDROID_HOME environment variable."],
+            };
+            return this.cached;
+        }
+        const adbPath = path.join(sdkPath, "platform-tools", "adb");
+        const emulatorPath = path.join(sdkPath, "emulator", "emulator");
+        // Verify adb exists
+        if (!fs.existsSync(adbPath)) {
+            issues.push(`adb not found at ${adbPath}`);
+        }
+        // Emulator is optional - just note if missing
+        if (!fs.existsSync(emulatorPath)) {
+            issues.push(`emulator not found at ${emulatorPath} (optional)`);
+        }
+        this.cached = {
+            sdkPath,
+            adbPath: fs.existsSync(adbPath) ? adbPath : null,
+            emulatorPath: fs.existsSync(emulatorPath) ? emulatorPath : null,
+            platform,
+            isValid: fs.existsSync(adbPath),
+            issues,
+        };
+        return this.cached;
+    }
+    async getAdbPath() {
+        const env = await this.detect();
+        if (!env.adbPath) {
+            throw new ReplicantError(ErrorCode.ADB_NOT_FOUND, "Android SDK not found", "Install Android Studio or set ANDROID_HOME environment variable", { checkedPaths: this.getSearchPaths(env.platform) });
+        }
+        return env.adbPath;
+    }
+    async getEmulatorPath() {
+        const env = await this.detect();
+        if (!env.emulatorPath) {
+            throw new ReplicantError(ErrorCode.EMULATOR_NOT_FOUND, "Android emulator not found", "Install Android Emulator via Android Studio SDK Manager");
+        }
+        return env.emulatorPath;
+    }
+    async getAvdManagerPath() {
+        const env = await this.detect();
+        if (!env.sdkPath) {
+            throw new ReplicantError(ErrorCode.SDK_NOT_FOUND, "Android SDK not found", "Install Android Studio or set ANDROID_HOME environment variable");
+        }
+        const avdManagerPath = path.join(env.sdkPath, "cmdline-tools", "latest", "bin", "avdmanager");
+        // Fallback to older location
+        const legacyPath = path.join(env.sdkPath, "tools", "bin", "avdmanager");
+        if (fs.existsSync(avdManagerPath)) {
+            return avdManagerPath;
+        }
+        if (fs.existsSync(legacyPath)) {
+            return legacyPath;
+        }
+        throw new ReplicantError(ErrorCode.SDK_NOT_FOUND, "avdmanager not found", "Install Android SDK Command-line Tools via Android Studio SDK Manager");
+    }
+    findSdkPath(platform) {
+        // 1. Check ANDROID_HOME
+        if (process.env.ANDROID_HOME) {
+            const adbPath = path.join(process.env.ANDROID_HOME, "platform-tools", "adb");
+            if (fs.existsSync(adbPath)) {
+                return process.env.ANDROID_HOME;
+            }
+        }
+        // 2. Check ANDROID_SDK_ROOT
+        if (process.env.ANDROID_SDK_ROOT) {
+            const adbPath = path.join(process.env.ANDROID_SDK_ROOT, "platform-tools", "adb");
+            if (fs.existsSync(adbPath)) {
+                return process.env.ANDROID_SDK_ROOT;
+            }
+        }
+        // 3. Probe common paths
+        const searchPaths = this.getSearchPaths(platform);
+        for (const sdkPath of searchPaths) {
+            const adbPath = path.join(sdkPath, "platform-tools", "adb");
+            if (fs.existsSync(adbPath)) {
+                return sdkPath;
+            }
+        }
+        return null;
+    }
+    getSearchPaths(platform) {
+        const home = os.homedir();
+        if (platform === "darwin") {
+            return [
+                path.join(home, "Library", "Android", "sdk"),
+                "/opt/homebrew/share/android-sdk",
+                "/usr/local/share/android-sdk",
+            ];
+        }
+        if (platform === "linux") {
+            return [
+                path.join(home, "Android", "Sdk"),
+                "/opt/android-sdk",
+                "/usr/lib/android-sdk",
+            ];
+        }
+        if (platform === "win32") {
+            const localAppData = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+            return [
+                path.join(localAppData, "Android", "Sdk"),
+                "C:\\Android\\sdk",
+            ];
+        }
+        return [];
+    }
+    // Clear cache (for testing)
+    clearCache() {
+        this.cached = null;
+    }
+}

package/dist/services/grid.d.ts

@@ -0,0 +1,28 @@
+export declare const GRID_COLS = 4;
+export declare const GRID_ROWS = 6;
+export declare const TOTAL_CELLS: number;
+export interface CellBounds {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/**
+ * Calculate the pixel bounds for a grid cell (1-24).
+ * Grid is 4 columns x 6 rows, numbered left-to-right, top-to-bottom.
+ */
+export declare function calculateGridCellBounds(cell: number, screenWidth: number, screenHeight: number): CellBounds;
+/**
+ * Calculate tap coordinates for a position within a cell.
+ * Position: 1=TL, 2=TR, 3=Center, 4=BL, 5=BR
+ */
+export declare function calculatePositionCoordinates(position: 1 | 2 | 3 | 4 | 5, cellBounds: CellBounds): {
+    x: number;
+    y: number;
+};
+export declare const POSITION_LABELS: string[];
+/**
+ * Create a 4x6 numbered grid overlay on a screenshot.
+ * Returns base64 PNG.
+ */
+export declare function createGridOverlay(imagePath: string): Promise<string>;

package/dist/services/grid.js

@@ -0,0 +1,98 @@
+// src/services/grid.ts
+import sharp from "sharp";
+export const GRID_COLS = 4;
+export const GRID_ROWS = 6;
+export const TOTAL_CELLS = GRID_COLS * GRID_ROWS; // 24
+/**
+ * Calculate the pixel bounds for a grid cell (1-24).
+ * Grid is 4 columns x 6 rows, numbered left-to-right, top-to-bottom.
+ */
+export function calculateGridCellBounds(cell, screenWidth, screenHeight) {
+    if (cell < 1 || cell > TOTAL_CELLS) {
+        throw new Error(`Invalid cell number: ${cell}. Must be 1-${TOTAL_CELLS}`);
+    }
+    const cellWidth = screenWidth / GRID_COLS;
+    const cellHeight = screenHeight / GRID_ROWS;
+    // Convert 1-based cell to 0-based row/col
+    const index = cell - 1;
+    const col = index % GRID_COLS;
+    const row = Math.floor(index / GRID_COLS);
+    return {
+        x0: Math.round(col * cellWidth),
+        y0: Math.round(row * cellHeight),
+        x1: Math.round((col + 1) * cellWidth),
+        y1: Math.round((row + 1) * cellHeight),
+    };
+}
+/**
+ * Calculate tap coordinates for a position within a cell.
+ * Position: 1=TL, 2=TR, 3=Center, 4=BL, 5=BR
+ */
+export function calculatePositionCoordinates(position, cellBounds) {
+    const width = cellBounds.x1 - cellBounds.x0;
+    const height = cellBounds.y1 - cellBounds.y0;
+    // Position multipliers (fraction of width/height from x0/y0)
+    const positionMap = {
+        1: { xMult: 0.25, yMult: 0.25 }, // Top-left
+        2: { xMult: 0.75, yMult: 0.25 }, // Top-right
+        3: { xMult: 0.5, yMult: 0.5 }, // Center
+        4: { xMult: 0.25, yMult: 0.75 }, // Bottom-left
+        5: { xMult: 0.75, yMult: 0.75 }, // Bottom-right
+    };
+    const { xMult, yMult } = positionMap[position];
+    return {
+        x: Math.round(cellBounds.x0 + width * xMult),
+        y: Math.round(cellBounds.y0 + height * yMult),
+    };
+}
+export const POSITION_LABELS = [
+    "Top-left",
+    "Top-right",
+    "Center",
+    "Bottom-left",
+    "Bottom-right",
+];
+const GRID_LINE_WIDTH = 3;
+const LABEL_FONT_SIZE = 36;
+/**
+ * Create a 4x6 numbered grid overlay on a screenshot.
+ * Returns base64 PNG.
+ */
+export async function createGridOverlay(imagePath) {
+    const image = sharp(imagePath);
+    const metadata = await image.metadata();
+    const width = metadata.width;
+    const height = metadata.height;
+    const cellWidth = width / GRID_COLS;
+    const cellHeight = height / GRID_ROWS;
+    // Create SVG overlay with grid lines and numbers
+    const svgParts = [];
+    // Grid lines (vertical)
+    for (let col = 1; col < GRID_COLS; col++) {
+        const x = Math.round(col * cellWidth);
+        svgParts.push(`<line x1="${x}" y1="0" x2="${x}" y2="${height}" stroke="rgba(255,165,0,0.8)" stroke-width="${GRID_LINE_WIDTH}"/>`);
+    }
+    // Grid lines (horizontal)
+    for (let row = 1; row < GRID_ROWS; row++) {
+        const y = Math.round(row * cellHeight);
+        svgParts.push(`<line x1="0" y1="${y}" x2="${width}" y2="${y}" stroke="rgba(255,165,0,0.8)" stroke-width="${GRID_LINE_WIDTH}"/>`);
+    }
+    // Cell numbers
+    for (let cell = 1; cell <= TOTAL_CELLS; cell++) {
+        const index = cell - 1;
+        const col = index % GRID_COLS;
+        const row = Math.floor(index / GRID_COLS);
+        const centerX = Math.round((col + 0.5) * cellWidth);
+        const centerY = Math.round((row + 0.5) * cellHeight);
+        // Background circle for visibility
+        svgParts.push(`<circle cx="${centerX}" cy="${centerY}" r="25" fill="rgba(0,0,0,0.6)"/>`);
+        // Number text
+        svgParts.push(`<text x="${centerX}" y="${centerY}" font-family="Arial, sans-serif" font-size="${LABEL_FONT_SIZE}" font-weight="bold" fill="white" text-anchor="middle" dominant-baseline="central">${cell}</text>`);
+    }
+    const svgOverlay = `<svg width="${width}" height="${height}">${svgParts.join("")}</svg>`;
+    const buffer = await image
+        .composite([{ input: Buffer.from(svgOverlay), top: 0, left: 0 }])
+        .png()
+        .toBuffer();
+    return buffer.toString("base64");
+}

package/dist/services/icon-patterns.d.ts

@@ -0,0 +1,10 @@
+export declare const ICON_PATTERNS: Record<string, string[]>;
+/**
+ * Match a user query to icon resourceId patterns.
+ * Returns array of patterns to search for, or null if no match.
+ */
+export declare function matchIconPattern(query: string): string[] | null;
+/**
+ * Check if a resourceId matches any of the given patterns.
+ */
+export declare function matchesResourceId(resourceId: string, patterns: string[]): boolean;

package/dist/services/icon-patterns.js

@@ -0,0 +1,51 @@
+export const ICON_PATTERNS = {
+    // Navigation
+    overflow: ["overflow", "more", "options", "menu", "dots", "kabob", "meatball"],
+    back: ["back", "navigate_up", "arrow_back", "return", "nav_back"],
+    close: ["close", "dismiss", "cancel", "ic_close", "btn_close"],
+    home: ["home", "nav_home", "ic_home"],
+    // Actions
+    search: ["search", "find", "magnify", "ic_search"],
+    settings: ["settings", "gear", "config", "preferences", "ic_settings"],
+    share: ["share", "ic_share", "btn_share"],
+    edit: ["edit", "pencil", "ic_edit", "btn_edit"],
+    delete: ["delete", "trash", "remove", "ic_delete"],
+    add: ["add", "plus", "create", "ic_add", "fab"],
+    // Media
+    play: ["play", "ic_play", "btn_play"],
+    pause: ["pause", "ic_pause"],
+    refresh: ["refresh", "reload", "sync", "ic_refresh"],
+    // Social
+    favorite: ["favorite", "heart", "like", "star", "ic_favorite"],
+    bookmark: ["bookmark", "save", "ic_bookmark"],
+    notification: ["notification", "bell", "ic_notification", "ic_notify"],
+    // Misc
+    filter: ["filter", "ic_filter", "btn_filter"],
+    sort: ["sort", "ic_sort", "btn_sort"],
+    download: ["download", "ic_download"],
+    upload: ["upload", "ic_upload"],
+    profile: ["profile", "account", "avatar", "user", "ic_profile"],
+    hamburger: ["hamburger", "drawer", "nav_drawer", "ic_menu"],
+};
+/**
+ * Match a user query to icon resourceId patterns.
+ * Returns array of patterns to search for, or null if no match.
+ */
+export function matchIconPattern(query) {
+    const lowerQuery = query.toLowerCase();
+    // Check each icon category
+    for (const [category, patterns] of Object.entries(ICON_PATTERNS)) {
+        // Match if query contains the category name or any pattern
+        if (lowerQuery.includes(category) || patterns.some((p) => lowerQuery.includes(p))) {
+            return patterns;
+        }
+    }
+    return null;
+}
+/**
+ * Check if a resourceId matches any of the given patterns.
+ */
+export function matchesResourceId(resourceId, patterns) {
+    const lowerId = resourceId.toLowerCase();
+    return patterns.some((pattern) => lowerId.includes(pattern));
+}

package/dist/services/index.d.ts

@@ -1,3 +1,9 @@
 export { ProcessRunner, type RunOptions, type RunResult } from "./process-runner.js";
 export { CacheManager, type CacheStats } from "./cache-manager.js";
 export { DeviceStateManager } from "./device-state.js";
+export { EnvironmentService, type Environment } from "./environment.js";
+export { ConfigManager, loadConfig } from "./config.js";
+export * from "./ocr.js";
+export * from "./icon-patterns.js";
+export * from "./grid.js";
+export * from "./visual-candidates.js";

package/dist/services/index.js

@@ -1,3 +1,9 @@
 export { ProcessRunner } from "./process-runner.js";
 export { CacheManager } from "./cache-manager.js";
 export { DeviceStateManager } from "./device-state.js";
+export { EnvironmentService } from "./environment.js";
+export { ConfigManager, loadConfig } from "./config.js";
+export * from "./ocr.js";
+export * from "./icon-patterns.js";
+export * from "./grid.js";
+export * from "./visual-candidates.js";

package/dist/services/ocr.d.ts

@@ -0,0 +1,4 @@
+import { OcrResult, OcrElement } from "../types/ocr.js";
+export declare function extractText(imagePath: string): Promise<OcrResult[]>;
+export declare function terminateOcr(): Promise<void>;
+export declare function searchText(ocrResults: OcrResult[], searchTerm: string): OcrElement[];

package/dist/services/ocr.js

@@ -0,0 +1,59 @@
+import { createWorker } from "tesseract.js";
+let worker = null;
+async function getWorker() {
+    if (!worker) {
+        worker = await createWorker("eng");
+    }
+    return worker;
+}
+export async function extractText(imagePath) {
+    const w = await getWorker();
+    const { data } = await w.recognize(imagePath, {}, { blocks: true });
+    const results = [];
+    // Navigate through blocks -> paragraphs -> lines -> words
+    if (data.blocks) {
+        for (const block of data.blocks) {
+            for (const paragraph of block.paragraphs) {
+                for (const line of paragraph.lines) {
+                    for (const word of line.words) {
+                        if (word.text.trim()) {
+                            results.push({
+                                text: word.text,
+                                confidence: word.confidence / 100, // Normalize to 0-1
+                                bounds: {
+                                    x0: word.bbox.x0,
+                                    y0: word.bbox.y0,
+                                    x1: word.bbox.x1,
+                                    y1: word.bbox.y1,
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return results;
+}
+export async function terminateOcr() {
+    if (worker) {
+        await worker.terminate();
+        worker = null;
+    }
+}
+export function searchText(ocrResults, searchTerm) {
+    const lowerSearch = searchTerm.toLowerCase();
+    const matches = ocrResults.filter((result) => result.text.toLowerCase().includes(lowerSearch));
+    // Index represents position in filtered matches (0, 1, 2...) for use with elementIndex tap
+    // This is intentional - users tap by match index, not original OCR result position
+    return matches.map((match, index) => ({
+        index,
+        text: match.text,
+        bounds: `[${match.bounds.x0},${match.bounds.y0}][${match.bounds.x1},${match.bounds.y1}]`,
+        center: {
+            x: Math.round((match.bounds.x0 + match.bounds.x1) / 2),
+            y: Math.round((match.bounds.y0 + match.bounds.y1) / 2),
+        },
+        confidence: match.confidence,
+    }));
+}

package/dist/services/process-runner.d.ts

@@ -1,3 +1,4 @@
+import type { EnvironmentService } from "./environment.js";
 export interface RunOptions {
     timeoutMs?: number;
     cwd?: string;
@@ -8,8 +9,13 @@ export interface RunResult {
     exitCode: number;
 }
 export declare class ProcessRunner {
+    private environment?;
     private readonly defaultTimeoutMs;
     private readonly maxTimeoutMs;
+    constructor(environment?: EnvironmentService | undefined);
     run(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+    runAdb(args: string[], options?: RunOptions): Promise<RunResult>;
+    runEmulator(args: string[], options?: RunOptions): Promise<RunResult>;
+    runAvdManager(args: string[], options?: RunOptions): Promise<RunResult>;
     private validateCommand;
 }