@godscene/shared 1.7.11

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/cli/cli-args.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { getKeyAliases } from '../key-alias-utils';
+import type { ToolCliOption, ToolDefinition } from '../mcp/types';
+
+export function parseValue(raw: string): unknown {
+  if (raw.startsWith('{') || raw.startsWith('[')) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      // Not valid JSON, treat as string below
+    }
+  }
+
+  if (/^-?\d+(\.\d+)?$/.test(raw)) {
+    return Number(raw);
+  }
+
+  return raw;
+}
+
+function walkCliArgs(
+  args: string[],
+  setArgValue: (key: string, value: unknown) => void,
+): void {
+  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) {
+      setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+    } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+      i++;
+      setArgValue(body, parseValue(args[i]));
+    } else {
+      setArgValue(body, true);
+    }
+  }
+}
+
+export function parseCliArgs(args: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  walkCliArgs(args, (key, value) => {
+    result[key] = value;
+  });
+
+  return result;
+}
+
+function formatCliOptionName(name: string): string {
+  return `--${name}`;
+}
+
+export function getCliOptionDisplay(
+  key: string,
+  cliOption?: ToolCliOption,
+): { label: string; aliases: string[] } {
+  const label = formatCliOptionName(cliOption?.preferredName ?? key);
+  const aliases = [...new Set(cliOption?.aliases ?? [])]
+    .map((alias) => formatCliOptionName(alias))
+    .filter((alias) => alias !== label);
+
+  return { label, aliases };
+}
+
+function getAcceptedCliOptionNames(
+  key: string,
+  cliOption?: ToolCliOption,
+): string[] {
+  return [
+    ...new Set(
+      cliOption
+        ? [cliOption.preferredName ?? key, ...(cliOption.aliases ?? [])]
+        : [key, ...getKeyAliases(key)],
+    ),
+  ];
+}
+
+function toOptionalCliSchemaField(field: unknown): z.ZodTypeAny {
+  if (
+    typeof field === 'object' &&
+    field !== null &&
+    typeof (field as z.ZodTypeAny).optional === 'function'
+  ) {
+    return (field as z.ZodTypeAny).optional();
+  }
+
+  const description =
+    typeof field === 'object' &&
+    field !== null &&
+    'description' in field &&
+    typeof (field as { description?: unknown }).description === 'string'
+      ? (field as { description: string }).description
+      : undefined;
+  return description ? z.any().describe(description) : z.any();
+}
+
+function buildCliArgSchema(def: ToolDefinition): Record<string, z.ZodTypeAny> {
+  return Object.fromEntries(
+    Object.entries(def.schema).flatMap(([key, zodType]) =>
+      getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey) => [
+        cliKey,
+        toOptionalCliSchemaField(zodType),
+      ]),
+    ),
+  );
+}
+
+function buildDisallowedCliSpellings(def: ToolDefinition): Set<string> {
+  const disallowedSpellings = new Set<string>();
+
+  for (const [key] of Object.entries(def.schema)) {
+    const cliOption = def.cli?.options?.[key];
+    const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
+    const knownSpellings = new Set<string>([
+      key,
+      ...getKeyAliases(key),
+      ...(cliOption?.preferredName
+        ? getKeyAliases(cliOption.preferredName)
+        : []),
+      ...(cliOption?.aliases ?? []),
+    ]);
+
+    for (const spelling of knownSpellings) {
+      if (!acceptedNames.has(spelling)) {
+        disallowedSpellings.add(spelling);
+      }
+    }
+  }
+
+  return disallowedSpellings;
+}
+
+export function formatCliValidationError(
+  scriptName: string,
+  commandName: string,
+  def: ToolDefinition,
+  rawArgs: Record<string, unknown>,
+): string | undefined {
+  if (Object.keys(def.schema).length === 0) {
+    return undefined;
+  }
+
+  const cliSchema = z.object(buildCliArgSchema(def)).strict();
+  const parsed = cliSchema.safeParse(rawArgs);
+  if (parsed.success) {
+    return undefined;
+  }
+
+  const disallowedSpellings = buildDisallowedCliSpellings(def);
+  const unknownKeys = parsed.error.issues.flatMap((issue) =>
+    issue.code === 'unrecognized_keys' ? issue.keys : [],
+  );
+
+  if (unknownKeys.length > 0) {
+    return unknownKeys
+      .map((key) => {
+        if (disallowedSpellings.has(key)) {
+          return `Unsupported option "--${key}" for ${scriptName} ${commandName}.`;
+        }
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+      })
+      .join('\n');
+  }
+
+  const [issue] = parsed.error.issues;
+  const optionName =
+    typeof issue?.path[0] === 'string' ? `--${issue.path[0]}` : 'CLI arguments';
+  return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
+}

package/src/cli/cli-error.ts

@@ -0,0 +1,24 @@
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public exitCode = 1,
+  ) {
+    super(message);
+  }
+}
+
+export function reportCLIError(
+  error: unknown,
+  log: (
+    message?: unknown,
+    ...optionalParams: unknown[]
+  ) => void = console.error,
+): number {
+  if (error instanceof CLIError) {
+    log(error.message);
+    return error.exitCode;
+  }
+
+  log(error);
+  return 1;
+}

package/src/cli/cli-runner.ts

@@ -0,0 +1,230 @@
+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';
+import {
+  formatCliValidationError,
+  getCliOptionDisplay,
+  parseCliArgs,
+} from './cli-args';
+import { CLIError } from './cli-error';
+
+const debug = getDebug('cli-runner');
+
+interface CLICommand {
+  name: string;
+  def: ToolDefinition;
+  hidden?: boolean;
+}
+
+export interface CLIExtraCommand {
+  name: string;
+  def: ToolDefinition;
+  aliases?: string[];
+  hidden?: boolean;
+}
+
+export interface CLIRunnerOptions {
+  stripPrefix?: string;
+  argv?: string[];
+  version?: string;
+  extraCommands?: CLIExtraCommand[];
+}
+
+export { parseCliArgs, parseValue } from './cli-args';
+export { CLIError, reportCLIError } from './cli-error';
+
+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) {
+    const optionWidth = Math.max(
+      22,
+      ...schemaEntries.map(
+        ([key]) =>
+          getCliOptionDisplay(key, def.cli?.options?.[key]).label.length,
+      ),
+    );
+    console.log('\nOptions:');
+    for (const [key, zodType] of schemaEntries) {
+      const { label, aliases } = getCliOptionDisplay(
+        key,
+        def.cli?.options?.[key],
+      );
+      const desc = zodType.description ?? '';
+      const aliasText =
+        aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : '';
+      console.log(`  ${label.padEnd(optionWidth)} ${desc}${aliasText}`);
+    }
+  }
+}
+
+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.filter((command) => !command.hidden)) {
+    console.log(`  ${name.padEnd(30)} ${def.description}`);
+  }
+  console.log(`  ${'version'.padEnd(30)} Show CLI version`);
+  console.log(`\nRun "${scriptName} <command> --help" for more info.`);
+}
+
+type AnyMidsceneTools = BaseMidsceneTools<any, any>;
+
+export async function runToolsCLI(
+  tools: AnyMidsceneTools,
+  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,
+  }));
+  if (options?.extraCommands?.length) {
+    commands.push(
+      ...options.extraCommands.flatMap((cmd) => [
+        {
+          name: cmd.name.toLowerCase(),
+          def: cmd.def,
+          hidden: cmd.hidden,
+        },
+        ...(cmd.aliases ?? []).map((alias) => ({
+          name: alias.toLowerCase(),
+          def: cmd.def,
+          hidden: true,
+        })),
+      ]),
+    );
+  }
+  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);
+  if (parsedArgs.help === true) {
+    debug('showing command help for: %s', match.name);
+    printCommandHelp(scriptName, match);
+    return;
+  }
+
+  const cliValidationError = formatCliValidationError(
+    scriptName,
+    match.name,
+    match.def,
+    parsedArgs,
+  );
+  if (cliValidationError) {
+    throw new CLIError(cliValidationError);
+  }
+
+  debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
+
+  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,4 @@
+export { CLIError, reportCLIError } from './cli-error';
+export { parseCliArgs, parseValue } from './cli-args';
+export { runToolsCLI, removePrefix } from './cli-runner';
+export type { CLIRunnerOptions, CLIExtraCommand } 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';