@godscene/shared 1.7.11

package/src/mcp/types.ts

@@ -0,0 +1,131 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { z } from 'zod';
+
+// Avoid circular dependency: don't import from @godscene/core
+// Instead, use generic types that will be provided by implementation
+
+/**
+ * Default timeout constants for app loading verification
+ */
+export const defaultAppLoadingTimeoutMs = 10000;
+export const defaultAppLoadingCheckIntervalMs = 2000;
+
+/**
+ * Content item types for tool results (MCP compatible)
+ */
+export type ToolResultContent =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string }
+  | { type: 'audio'; data: string; mimeType: string }
+  | {
+    type: 'resource';
+    resource:
+    | { text: string; uri: string; mimeType?: string }
+    | { uri: string; blob: string; mimeType?: string };
+  };
+
+/**
+ * Result type for tool execution (MCP compatible)
+ */
+export interface ToolResult {
+  [x: string]: unknown;
+  content: ToolResultContent[];
+  isError?: boolean;
+  _meta?: Record<string, unknown>;
+}
+
+/**
+ * Tool handler function type
+ * Takes parsed arguments and returns a tool result
+ */
+export type ToolHandler<T = Record<string, unknown>> = (
+  args: T,
+) => Promise<ToolResult>;
+
+/**
+ * Tool schema type using Zod
+ */
+export type ToolSchema = Record<string, z.ZodTypeAny>;
+
+export interface ToolCliOption {
+  preferredName?: string;
+  aliases?: string[];
+}
+
+export interface ToolCliMetadata {
+  options?: Record<string, ToolCliOption>;
+}
+
+/**
+ * Tool definition for MCP server
+ */
+export interface ToolDefinition<T = Record<string, unknown>> {
+  name: string;
+  description: string;
+  schema: ToolSchema;
+  handler: ToolHandler<T>;
+  cli?: ToolCliMetadata;
+}
+
+/**
+ * Tool type for mcpKitForAgent return value
+ */
+export type Tool = ToolDefinition;
+
+/**
+ * Action space item definition
+ * Note: Intentionally no index signature to maintain compatibility with DeviceAction
+ */
+export interface ActionSpaceItem {
+  name: string;
+  description?: string;
+  args?: Record<string, unknown>;
+  paramSchema?: z.ZodTypeAny;
+}
+
+/**
+ * Base agent interface
+ * Represents a platform-specific agent (Android, iOS, Web)
+ * Note: Return types use `unknown` for compatibility with platform-specific implementations
+ */
+export interface BaseAgent {
+  getActionSpace(): Promise<ActionSpaceItem[]>;
+  destroy?(): Promise<void>;
+  page?: {
+    screenshotBase64(): Promise<string>;
+  };
+  callActionInActionSpace?: (
+    actionName: string,
+    params?: unknown,
+  ) => Promise<unknown>;
+  aiAction?: (
+    description: string,
+    params?: Record<string, unknown>,
+  ) => Promise<unknown>;
+  aiWaitFor?: (
+    assertion: string,
+    options: Record<string, unknown>,
+  ) => Promise<unknown>;
+  aiAssert?: (
+    assertion: string,
+    msg?: string,
+    options?: Record<string, unknown>,
+  ) => Promise<unknown>;
+}
+
+/**
+ * Base device interface for temporary device instances
+ */
+export interface BaseDevice {
+  actionSpace(): ActionSpaceItem[];
+  destroy?(): Promise<void>;
+}
+
+/**
+ * Interface for platform-specific MCP tools manager
+ */
+export interface IMidsceneTools {
+  attachToServer(server: McpServer): void;
+  initTools(): Promise<void>;
+  destroy?(): Promise<void>;
+}

package/src/node/fs.ts

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ifInBrowser, ifInWorker } from '../utils';
+
+declare const __HTML_ELEMENT_SCRIPT__: string;
+
+interface PkgInfo {
+  name: string;
+  version: string;
+  dir: string;
+}
+
+const pkgCacheMap: Record<string, PkgInfo> = {};
+
+export function getRunningPkgInfo(dir?: string): PkgInfo | null {
+  if (ifInBrowser || ifInWorker) {
+    return null;
+  }
+  const dirToCheck = dir || process.cwd();
+  if (pkgCacheMap[dirToCheck]) {
+    return pkgCacheMap[dirToCheck];
+  }
+
+  const pkgDir = findNearestPackageJson(dirToCheck);
+  const pkgJsonFile = pkgDir ? join(pkgDir, 'package.json') : null;
+
+  if (pkgDir && pkgJsonFile) {
+    const { name, version } = JSON.parse(readFileSync(pkgJsonFile, 'utf-8'));
+    pkgCacheMap[dirToCheck] = {
+      name: name || 'midscene-unknown-package-name',
+      version: version || '0.0.0',
+      dir: pkgDir,
+    };
+    return pkgCacheMap[dirToCheck];
+  }
+  return {
+    name: 'midscene-unknown-package-name',
+    version: '0.0.0',
+    dir: dirToCheck,
+  };
+}
+
+/**
+ * Find the nearest package.json file recursively
+ * @param {string} dir - Home directory
+ * @returns {string|null} - The most recent package.json file path or null
+ */
+export function findNearestPackageJson(dir: string): string | null {
+  const packageJsonPath = join(dir, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    return dir;
+  }
+
+  const parentDir = dirname(dir);
+
+  // Return null if the root directory has been reached
+  if (parentDir === dir) {
+    return null;
+  }
+
+  return findNearestPackageJson(parentDir);
+}
+
+export function getElementInfosScriptContent() {
+  const htmlElementScript = __HTML_ELEMENT_SCRIPT__;
+
+  if (!htmlElementScript) {
+    throw new Error('HTML_ELEMENT_SCRIPT inject failed.');
+  }
+  return htmlElementScript;
+}
+
+export async function getExtraReturnLogic(tree = false) {
+  if (ifInBrowser || ifInWorker) {
+    return null;
+  }
+
+  const elementInfosScriptContent = `${getElementInfosScriptContent()};`;
+
+  if (tree) {
+    return `${elementInfosScriptContent}midscene_element_inspector.webExtractNodeTree()`;
+  }
+  return `${elementInfosScriptContent}midscene_element_inspector.webExtractTextWithPosition()`;
+}

package/src/node/index.ts

@@ -0,0 +1,2 @@
+export * from './fs';
+export * from './port';

package/src/node/port.ts

@@ -0,0 +1,37 @@
+import { createServer } from 'node:net';
+
+/**
+ * Check if a port is available
+ */
+export async function isPortAvailable(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.on('error', () => resolve(false));
+    server.listen(port, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * Find an available port starting from the given port
+ */
+export async function findAvailablePort(
+  startPort: number,
+  maxAttempts = 15,
+): Promise<number> {
+  let port = startPort;
+  let attempts = 0;
+
+  while (!(await isPortAvailable(port))) {
+    attempts++;
+    if (attempts >= maxAttempts) {
+      console.error(
+        `❌ Unable to find available port after ${maxAttempts} attempts starting from ${startPort}`,
+      );
+      process.exit(1);
+    }
+    port++;
+  }
+  return port;
+}

package/src/polyfills/async-hooks.ts

@@ -0,0 +1,6 @@
+/**
+ * Browser polyfill for Node.js async_hooks module
+ * Provides empty implementation for browser environments where async_hooks is not available
+ */
+const AsyncLocalStorage = {};
+export { AsyncLocalStorage };

package/src/polyfills/index.ts

@@ -0,0 +1,4 @@
+/**
+ * Polyfills for Node.js modules in browser environments
+ */
+export * from './async-hooks';

package/src/types/index.ts

@@ -0,0 +1,54 @@
+import type { NodeType } from '../constants';
+import type { ElementInfo } from '../extractor';
+
+export interface Point {
+  left: number;
+  top: number;
+}
+
+export interface Size {
+  width: number; // The image sent to AI model will be resized to this width, also the coordinates in the action space will be scaled to the range [0, width]. Usually you should set it to the logical pixel size
+  height: number; // The image sent to AI model will be resized to this height, also the coordinates in the action space will be scaled to the range [0, height]. Usually you should set it to the logical pixel size
+}
+
+export type Rect = Point & Size;
+
+export abstract class BaseElement {
+  abstract id: string;
+
+  // abstract indexId?: number; // markerId for web
+
+  abstract attributes: {
+    nodeType: NodeType;
+    [key: string]: string;
+  };
+
+  abstract content: string;
+
+  abstract rect: Rect;
+
+  abstract center: [number, number];
+
+  // abstract xpaths?: string[];
+
+  abstract isVisible: boolean;
+}
+
+export interface ElementTreeNode<
+  ElementType extends BaseElement = BaseElement,
+> {
+  node: ElementType | null;
+  children: ElementTreeNode<ElementType>[];
+}
+
+export interface WebElementInfo extends ElementInfo {
+  zoom: number;
+}
+
+export type LocateResultElement = {
+  description: string; // the description of the element
+  center: [number, number];
+  rect: Rect;
+  allPaths?: any[],
+  containerPaths?: any[]
+};