@xiuchang-midscene/shared 2.0.2

package/src/baseDB.ts

@@ -0,0 +1,158 @@
+// Generic database operations class
+export class IndexedDBManager {
+  private dbPromise: Promise<IDBDatabase>;
+  private dbName: string;
+  private version: number;
+  private storeConfigs: Array<{ name: string; keyPath: string }>;
+
+  constructor(
+    dbName: string,
+    version: number,
+    storeConfigs: Array<{ name: string; keyPath: string }>,
+  ) {
+    this.dbName = dbName;
+    this.version = version;
+    this.storeConfigs = storeConfigs;
+    this.dbPromise = this.initDB();
+  }
+
+  private initDB(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, this.version);
+
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve(request.result);
+
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+
+        // Create stores if they don't exist
+        this.storeConfigs.forEach(({ name, keyPath }) => {
+          if (!db.objectStoreNames.contains(name)) {
+            const store = db.createObjectStore(name, { keyPath });
+            store.createIndex('timestamp', 'timestamp', { unique: false });
+          }
+        });
+      };
+    });
+  }
+
+  private async withTransaction<T>(
+    storeNames: string | string[],
+    mode: IDBTransactionMode,
+    operation: (stores: IDBObjectStore | IDBObjectStore[]) => Promise<T>,
+  ): Promise<T> {
+    const db = await this.dbPromise;
+    const transaction = db.transaction(storeNames, mode);
+
+    const stores = Array.isArray(storeNames)
+      ? storeNames.map((name) => transaction.objectStore(name))
+      : transaction.objectStore(storeNames);
+
+    return operation(stores);
+  }
+
+  private promisifyRequest<T>(request: IDBRequest<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async put<T>(storeName: string, data: T): Promise<void> {
+    await this.withTransaction(storeName, 'readwrite', async (store) => {
+      await this.promisifyRequest((store as IDBObjectStore).put(data));
+    });
+  }
+
+  async get<T>(storeName: string, key: string): Promise<T | undefined> {
+    return this.withTransaction(storeName, 'readonly', async (store) => {
+      return this.promisifyRequest((store as IDBObjectStore).get(key));
+    });
+  }
+
+  async getAll<T>(storeName: string, sortByTimestamp = true): Promise<T[]> {
+    return this.withTransaction(storeName, 'readonly', async (store) => {
+      const objectStore = store as IDBObjectStore;
+      const results = sortByTimestamp
+        ? await this.promisifyRequest(objectStore.index('timestamp').getAll())
+        : await this.promisifyRequest(objectStore.getAll());
+
+      return sortByTimestamp
+        ? results.sort((a: any, b: any) => a.timestamp - b.timestamp)
+        : results;
+    });
+  }
+
+  async clear(storeName: string): Promise<void> {
+    await this.withTransaction(storeName, 'readwrite', async (store) => {
+      await this.promisifyRequest((store as IDBObjectStore).clear());
+    });
+  }
+
+  async delete(storeName: string, key: string): Promise<void> {
+    await this.withTransaction(storeName, 'readwrite', async (store) => {
+      await this.promisifyRequest((store as IDBObjectStore).delete(key));
+    });
+  }
+
+  async count(storeName: string): Promise<number> {
+    return this.withTransaction(storeName, 'readonly', async (store) => {
+      return this.promisifyRequest((store as IDBObjectStore).count());
+    });
+  }
+
+  getDBPromise(): Promise<IDBDatabase> {
+    return this.dbPromise;
+  }
+}
+
+// Generic error handler wrapper
+export const withErrorHandling = async <T>(
+  operation: () => Promise<T>,
+  errorMessage: string,
+  defaultValue?: T,
+  onQuotaExceeded?: () => Promise<void>,
+): Promise<T | undefined> => {
+  try {
+    return await operation();
+  } catch (e) {
+    console.error(errorMessage, e);
+    if (
+      e instanceof Error &&
+      e.name === 'QuotaExceededError' &&
+      onQuotaExceeded
+    ) {
+      console.log('Storage quota exceeded, running cleanup...');
+      await onQuotaExceeded();
+    }
+    return defaultValue;
+  }
+};
+
+// Base cleanup function for managing storage space
+export const createCleanupFunction = <
+  T extends { id: string; timestamp: number },
+>(
+  dbManager: IndexedDBManager,
+  storeName: string,
+  maxItems: number,
+) => {
+  return async (): Promise<void> => {
+    try {
+      const results = await dbManager.getAll<T>(storeName);
+
+      if (results.length > maxItems) {
+        const toDelete = results
+          .sort((a, b) => a.timestamp - b.timestamp)
+          .slice(0, results.length - maxItems);
+
+        await Promise.all(
+          toDelete.map((item) => dbManager.delete(storeName, item.id)),
+        );
+      }
+    } catch (e) {
+      console.error(`Failed to cleanup ${storeName}:`, e);
+    }
+  };
+};

package/src/build/copy-static.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface CopyStaticOptions {
+  /** Source directory to copy from */
+  srcDir: string;
+  /** Destination directory to copy to */
+  destDir: string;
+  /** Optional favicon source path (relative to directory containing srcDir) */
+  faviconPath?: string;
+  /** Name for the rsbuild plugin */
+  pluginName?: string;
+}
+
+/**
+ * Creates an rsbuild plugin that copies static files after build
+ * @param options Configuration options for copying static files
+ * @returns Rsbuild plugin object
+ */
+export const createCopyStaticPlugin = (options: CopyStaticOptions) => ({
+  name: options.pluginName || 'copy-static',
+  setup(api: any) {
+    api.onAfterBuild(async () => {
+      const { srcDir, destDir, faviconPath } = options;
+
+      // Remove symlink left by dev mode before copying
+      const stat = await fs.promises.lstat(destDir).catch(() => null);
+      if (stat?.isSymbolicLink()) {
+        await fs.promises.unlink(destDir);
+      }
+
+      await fs.promises.mkdir(destDir, { recursive: true });
+
+      // Copy directory contents recursively
+      await fs.promises.cp(srcDir, destDir, { recursive: true });
+      console.log(`Copied build artifacts from ${srcDir} to ${destDir}`);
+
+      // Copy favicon if specified
+      if (faviconPath) {
+        const faviconDest = path.join(destDir, 'favicon.ico');
+        await fs.promises.copyFile(faviconPath, faviconDest);
+        console.log(`Copied favicon from ${faviconPath} to ${faviconDest}`);
+      }
+    });
+  },
+});
+
+/**
+ * Helper function to create a copy static plugin for playground builds
+ * @param srcDir Source directory (usually dist directory)
+ * @param destDir Destination directory
+ * @param pluginName Optional plugin name
+ * @param faviconSrc Optional favicon source path
+ * @returns Rsbuild plugin
+ */
+export const createPlaygroundCopyPlugin = (
+  srcDir: string,
+  destDir: string,
+  pluginName?: string,
+  faviconSrc?: string,
+) => {
+  return createCopyStaticPlugin({
+    srcDir,
+    destDir,
+    faviconPath: faviconSrc,
+    pluginName,
+  });
+};

package/src/build/rspack-config.ts

@@ -0,0 +1,12 @@
+/**
+ * Common Rspack configuration helpers for rsbuild projects
+ */
+
+/**
+ * Common warning patterns to ignore in Rspack builds.
+ * These warnings are typically from optional dependencies or known non-critical issues.
+ */
+export const commonIgnoreWarnings = [
+  // Ignore dynamic import warnings from langsmith/langfuse optional dependencies
+  /Critical dependency: the request of a dependency is an expression/,
+];

package/src/cli/cli-runner.ts

@@ -0,0 +1,224 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import dotenv from 'dotenv';
+import { getDebug } from '../logger';
+import type { BaseMidsceneTools } from '../mcp/base-tools';
+import type {
+  ToolDefinition,
+  ToolResult,
+  ToolResultContent,
+} from '../mcp/types';
+
+const debug = getDebug('cli-runner');
+
+interface CLICommand {
+  name: string;
+  def: ToolDefinition;
+}
+
+export interface CLIRunnerOptions {
+  stripPrefix?: string;
+  argv?: string[];
+  version?: string;
+}
+
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public exitCode = 1,
+  ) {
+    super(message);
+  }
+}
+
+export function parseValue(raw: string): unknown {
+  // JSON objects/arrays
+  if (raw.startsWith('{') || raw.startsWith('[')) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      // Not valid JSON, treat as string below
+    }
+  }
+
+  // Numbers
+  if (/^-?\d+(\.\d+)?$/.test(raw)) {
+    return Number(raw);
+  }
+
+  return raw;
+}
+
+export function parseCliArgs(args: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) continue;
+
+    const body = arg.slice(2);
+    const eqIdx = body.indexOf('=');
+
+    if (eqIdx >= 0) {
+      // --key=value
+      result[body.slice(0, eqIdx)] = parseValue(body.slice(eqIdx + 1));
+    } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+      // --key value
+      i++;
+      result[body] = parseValue(args[i]);
+    } else {
+      // --flag (boolean)
+      result[body] = true;
+    }
+  }
+
+  return result;
+}
+
+function outputContentItem(item: ToolResultContent, isError: boolean): void {
+  switch (item.type) {
+    case 'text':
+      if (isError) {
+        console.error(item.text);
+      } else {
+        console.log(item.text);
+      }
+      break;
+
+    case 'image': {
+      const filename = `screenshot-${Date.now()}.png`;
+      const filepath = join(tmpdir(), filename);
+      writeFileSync(filepath, Buffer.from(item.data, 'base64'));
+      console.log(`Screenshot saved: ${filepath}`);
+      break;
+    }
+
+    default:
+      console.log(`[${item.type} content not displayed in CLI]`);
+  }
+}
+
+function outputResult(result: ToolResult): void {
+  for (const item of result.content) {
+    outputContentItem(item, result.isError ?? false);
+  }
+}
+
+export function removePrefix(name: string, prefix?: string): string {
+  if (prefix && name.startsWith(prefix)) {
+    return name.slice(prefix.length);
+  }
+  return name;
+}
+
+function printCommandHelp(scriptName: string, cmd: CLICommand): void {
+  const { def } = cmd;
+  console.log(`\nUsage: ${scriptName} ${cmd.name} [options]\n`);
+  console.log(def.description);
+
+  const schemaEntries = Object.entries(def.schema);
+  if (schemaEntries.length > 0) {
+    console.log('\nOptions:');
+    for (const [key, zodType] of schemaEntries) {
+      const desc = zodType.description ?? '';
+      console.log(`  --${key.padEnd(20)} ${desc}`);
+    }
+  }
+}
+
+function printVersion(scriptName: string, version: string): void {
+  console.log(`${scriptName} v${version}`);
+}
+
+function printHelp(
+  scriptName: string,
+  commands: CLICommand[],
+  version?: string,
+): void {
+  if (version) {
+    printVersion(scriptName, version);
+    console.log('');
+  }
+  console.log(`\nUsage: ${scriptName} <command> [options]\n`);
+  console.log('Commands:');
+  for (const { name, def } of commands) {
+    console.log(`  ${name.padEnd(30)} ${def.description}`);
+  }
+  console.log(`  ${'version'.padEnd(30)} Show CLI version`);
+  console.log(`\nRun "${scriptName} <command> --help" for more info.`);
+}
+
+export async function runToolsCLI(
+  tools: BaseMidsceneTools,
+  scriptName: string,
+  options?: CLIRunnerOptions,
+): Promise<void> {
+  const rawArgs = options?.argv ?? process.argv.slice(2);
+  debug('CLI invoked: %s %s', scriptName, rawArgs.join(' '));
+
+  // Load .env from cwd before any tool initialization
+  const envFile = join(process.cwd(), '.env');
+  if (existsSync(envFile)) {
+    dotenv.config({ path: envFile });
+  }
+
+  await tools.initTools();
+
+  const commands: CLICommand[] = tools.getToolDefinitions().map((def) => ({
+    name: removePrefix(def.name, options?.stripPrefix).toLowerCase(),
+    def,
+  }));
+  const cliVersion = options?.version;
+
+  const [commandName, ...restArgs] = rawArgs;
+
+  if (!commandName || commandName === '--help' || commandName === '-h') {
+    debug('showing help (no command or --help flag)');
+    printHelp(scriptName, commands, cliVersion);
+    return;
+  }
+
+  if (
+    commandName === '--version' ||
+    commandName === '-v' ||
+    commandName.toLowerCase() === 'version'
+  ) {
+    if (!cliVersion) {
+      throw new CLIError('Failed to determine CLI version');
+    }
+    printVersion(scriptName, cliVersion);
+    return;
+  }
+
+  const match = commands.find(
+    (c) => c.name.toLowerCase() === commandName.toLowerCase(),
+  );
+  if (!match) {
+    debug('unknown command: %s', commandName);
+    console.error(`Unknown command: ${commandName}`);
+    printHelp(scriptName, commands, cliVersion);
+    throw new CLIError(`Unknown command: ${commandName}`);
+  }
+
+  const parsedArgs = parseCliArgs(restArgs);
+  debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
+
+  if (parsedArgs.help === true) {
+    debug('showing command help for: %s', match.name);
+    printCommandHelp(scriptName, match);
+    return;
+  }
+
+  const result = await match.def.handler(parsedArgs);
+  debug(
+    'command %s completed, isError: %s',
+    match.name,
+    result.isError ?? false,
+  );
+  outputResult(result);
+  await tools.destroy();
+  if (result.isError) {
+    throw new CLIError('Command failed', 1);
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,8 @@
+export {
+  runToolsCLI,
+  CLIError,
+  parseValue,
+  parseCliArgs,
+  removePrefix,
+} from './cli-runner';
+export type { CLIRunnerOptions } from './cli-runner';

package/src/common.ts

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+// do not import getBasicEnvValue and MIDSCENE_RUN_DIR directly from ./env,
+// because it will cause circular dependency
+import { getBasicEnvValue } from './env/basic';
+import { MIDSCENE_RUN_DIR } from './env/types';
+import { ifInNode } from './utils';
+
+export const defaultRunDirName = 'midscene_run';
+// Define locally for now to avoid import issues
+
+export const getMidsceneRunDir = () => {
+  if (!ifInNode) {
+    return '';
+  }
+
+  return getBasicEnvValue(MIDSCENE_RUN_DIR) || defaultRunDirName;
+};
+
+export const getMidsceneRunBaseDir = () => {
+  if (!ifInNode) {
+    return '';
+  }
+
+  let basePath = path.resolve(process.cwd(), getMidsceneRunDir());
+
+  // Create a base directory
+  if (!existsSync(basePath)) {
+    try {
+      mkdirSync(basePath, { recursive: true });
+    } catch (error) {
+      // console.error(`Failed to create ${runDirName} directory: ${error}`);
+      basePath = path.join(tmpdir(), defaultRunDirName);
+      mkdirSync(basePath, { recursive: true });
+    }
+  }
+
+  return basePath;
+};
+
+/**
+ * Get the path to the midscene_run directory or a subdirectory within it.
+ * Creates the directory if it doesn't exist.
+ *
+ * @param subdir - Optional subdirectory name (e.g., 'log', 'report')
+ * @returns The absolute path to the requested directory
+ */
+export const getMidsceneRunSubDir = (
+  subdir: 'dump' | 'cache' | 'report' | 'tmp' | 'log' | 'output',
+): string => {
+  if (!ifInNode) {
+    return '';
+  }
+
+  // Create a log directory
+  const basePath = getMidsceneRunBaseDir();
+  const logPath = path.join(basePath, subdir);
+  if (!existsSync(logPath)) {
+    mkdirSync(logPath, { recursive: true });
+  }
+
+  return logPath;
+};
+
+export const ERROR_CODE_NOT_IMPLEMENTED_AS_DESIGNED =
+  'NOT_IMPLEMENTED_AS_DESIGNED';