feat(core): unify processCacheConfig between CLI and Agent (#1320)

* feat(core,cli): unify processCacheConfig and support cache strategy

- Unified processCacheConfig between CLI and Agent to handle
  MIDSCENE_CACHE env variable consistently
- Added strategy parameter to support YAML configurations with
  separate cache and strategy properties
- Added strategy property to AgentOpt interface for proper type support
- Updated CLI to pass strategy parameter when processing cache config
- Added comprehensive unit tests for processCacheConfig (18 tests)
- Verified read-only cache strategy prevents cache file updates

This ensures backward compatibility with MIDSCENE_CACHE environment
variable while supporting new cache strategy configurations
(read-only, read-write, write-only).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* feat(core): unify processCacheConfig between CLI and Agent

This commit unifies the cache configuration processing logic between CLI
and Agent to ensure consistent handling of the MIDSCENE_CACHE environment
variable and cache strategies.

Changes:
- Moved processCacheConfig to core/utils.ts for shared use
- Added support for cache strategies (read-only, read-write, write-only)
- Implemented auto-generation of cache IDs for CLI/YAML scenarios
- Added validation in Agent to reject cache: true without explicit ID
- Maintained backward compatibility with legacy cacheId format
- Added comprehensive unit tests for both CLI and Agent

The key design decision is that processCacheConfig utility function
auto-generates IDs (needed for CLI/YAML), while Agent's processCacheConfig
method validates and rejects invalid configs (needed for direct API usage).

This ensures:
1. CLI respects MIDSCENE_CACHE environment variable
2. YAML scripts can use cache: true with auto-generated IDs
3. Direct Agent API usage requires explicit cache IDs for safety
4. Read-only cache strategy prevents unintended cache updates

All tests passing:
- 30 Agent tests
- 18 CLI processCacheConfig tests
- 7 CLI create-yaml-player tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(core): mark unused parameter with underscore prefix

Fix TypeScript warning for unused 'key' parameter in replacerForPageObject.
The parameter is required by JSON.stringify's replacer function signature
but not used in this implementation.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: quanru

.gitignore

@@ -121,6 +121,7 @@ CLAUDE.md
 .claude
 **/.claude
 **/CLAUDE.md
+AGENTS.md
 .cursor/rules/nx-rules.mdc
 .github/instructions/nx.instructions.md
 .gemini-clipboard

packages/cli/src/create-yaml-player.ts

@@ -122,7 +122,11 @@ export async function createYamlPlayer(
             webTarget,
             {
               ...preference,
-              cache: processCacheConfig(yamlScript.agent?.cache, fileName),
+              cache: processCacheConfig(
+                yamlScript.agent?.cache,
+                fileName,
+                fileName,
+              ),
             },
             options?.browser,
           );
@@ -151,7 +155,11 @@ export async function createYamlPlayer(
 
         const agent = new AgentOverChromeBridge({
           closeNewTabsAfterDisconnect: webTarget.closeNewTabsAfterDisconnect,
-          cache: processCacheConfig(yamlScript.agent?.cache, fileName),
+          cache: processCacheConfig(
+            yamlScript.agent?.cache,
+            fileName,
+            fileName,
+          ),
         });
 
         if (webTarget.bridgeMode === 'newTabWithUrl') {
@@ -178,7 +186,11 @@ export async function createYamlPlayer(
       if (typeof yamlScript.android !== 'undefined') {
         const androidTarget = yamlScript.android;
         const agent = await agentFromAdbDevice(androidTarget?.deviceId, {
-          cache: processCacheConfig(yamlScript.agent?.cache, fileName),
+          cache: processCacheConfig(
+            yamlScript.agent?.cache,
+            fileName,
+            fileName,
+          ),
         });
 
         if (androidTarget?.launch) {
@@ -258,7 +270,11 @@ export async function createYamlPlayer(
         debug('creating agent from device', device);
         const agent = createAgent(device, {
           ...yamlScript.agent,
-          cache: processCacheConfig(yamlScript.agent?.cache, fileName),
+          cache: processCacheConfig(
+            yamlScript.agent?.cache,
+            fileName,
+            fileName,
+          ),
         });
 
         freeFn.push({

packages/cli/tests/midscene_scripts/local/local.yml

@@ -1,7 +1,13 @@
 target:
   serve: ./tests/server_root
   url: index.html
+agent:
+  cache: true
+  strategy: read-only
 tasks:
+  - name: click title
+    flow:
+      - aiTap: click the title
   - name: check title
     flow:
       - aiAssert: the content title is "My App"

packages/cli/tests/unit-test/create-yaml-player.test.ts

@@ -3,6 +3,14 @@ import { createYamlPlayer, launchServer } from '@/create-yaml-player';
 import type { MidsceneYamlScript, MidsceneYamlScriptEnv } from '@midscene/core';
 import { beforeEach, describe, expect, test, vi } from 'vitest';
 
+// Mock the global config manager to control environment variables
+vi.mock('@midscene/shared/env', () => ({
+  MIDSCENE_CACHE: 'MIDSCENE_CACHE',
+  globalConfigManager: {
+    getEnvConfigInBoolean: vi.fn(),
+  },
+}));
+
 // Mock dependencies
 vi.mock('node:fs', () => ({
   readFileSync: vi.fn(),
@@ -33,6 +41,8 @@ import { ScriptPlayer, parseYamlScript } from '@midscene/core/yaml';
 import { createServer } from 'http-server';
 
 describe('create-yaml-player', () => {
+  const mockFilePath = '/test/script.yml';
+
   beforeEach(() => {
     vi.clearAllMocks();
   });
@@ -70,8 +80,6 @@ describe('create-yaml-player', () => {
   });
 
   describe('createYamlPlayer', () => {
-    const mockFilePath = '/test/script.yml';
-
     test('should create player with web target', async () => {
       const mockScript: MidsceneYamlScript = {
         web: {

packages/cli/tests/unit-test/process-cache-config.test.ts

@@ -0,0 +1,261 @@
+import type { Cache } from '@midscene/core';
+import { processCacheConfig } from '@midscene/core/utils';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+
+// Mock the global config manager to control environment variables
+vi.mock('@midscene/shared/env', () => ({
+  MIDSCENE_CACHE: 'MIDSCENE_CACHE',
+  globalConfigManager: {
+    getEnvConfigInBoolean: vi.fn(),
+  },
+}));
+
+import { globalConfigManager } from '@midscene/shared/env';
+
+describe('processCacheConfig in CLI', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Basic cache configuration', () => {
+    test('should return cache object with ID when cache config is provided with ID', () => {
+      const cacheConfig: Cache = {
+        id: 'test-cache-id',
+        strategy: 'read-write',
+      };
+      const result = processCacheConfig(cacheConfig, 'fallback-id');
+
+      expect(result).toEqual({
+        id: 'test-cache-id',
+        strategy: 'read-write',
+      });
+    });
+
+    test('should auto-generate ID when cache config is true', () => {
+      const result = processCacheConfig(true, 'fallback-id');
+
+      expect(result).toEqual({
+        id: 'fallback-id',
+      });
+    });
+
+    test('should auto-generate ID when cache config object has no ID', () => {
+      const cacheConfig: Cache = { strategy: 'read-only' };
+      const result = processCacheConfig(cacheConfig, 'fallback-id');
+
+      expect(result).toEqual({
+        id: 'fallback-id',
+        strategy: 'read-only',
+      });
+    });
+
+    test('should return undefined when cache config is false', () => {
+      const result = processCacheConfig(false, 'fallback-id');
+
+      expect(result).toBeUndefined();
+    });
+
+    test('should return undefined when cache config is undefined', () => {
+      const result = processCacheConfig(undefined, 'fallback-id');
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('Environment variable support (MIDSCENE_CACHE)', () => {
+    test('should enable legacy cacheId when MIDSCENE_CACHE is true', () => {
+      vi.mocked(globalConfigManager.getEnvConfigInBoolean).mockReturnValue(
+        true,
+      );
+
+      const result = processCacheConfig(
+        undefined,
+        'fallback-id',
+        'legacy-cache-id',
+      );
+
+      expect(globalConfigManager.getEnvConfigInBoolean).toHaveBeenCalledWith(
+        'MIDSCENE_CACHE',
+      );
+      expect(result).toEqual({
+        id: 'legacy-cache-id',
+      });
+    });
+
+    test('should disable legacy cacheId when MIDSCENE_CACHE is false', () => {
+      vi.mocked(globalConfigManager.getEnvConfigInBoolean).mockReturnValue(
+        false,
+      );
+
+      const result = processCacheConfig(
+        undefined,
+        'fallback-id',
+        'legacy-cache-id',
+      );
+
+      expect(globalConfigManager.getEnvConfigInBoolean).toHaveBeenCalledWith(
+        'MIDSCENE_CACHE',
+      );
+      expect(result).toBeUndefined();
+    });
+
+    test('should prefer new cache config over legacy cacheId', () => {
+      vi.mocked(globalConfigManager.getEnvConfigInBoolean).mockReturnValue(
+        true,
+      );
+
+      const cacheConfig: Cache = { id: 'new-cache-id', strategy: 'read-write' };
+      const result = processCacheConfig(
+        cacheConfig,
+        'fallback-id',
+        'legacy-cache-id',
+      );
+
+      expect(globalConfigManager.getEnvConfigInBoolean).not.toHaveBeenCalled();
+      expect(result).toEqual({
+        id: 'new-cache-id',
+        strategy: 'read-write',
+      });
+    });
+
+    test('should prefer new cache config over legacy cacheId even when env is false', () => {
+      vi.mocked(globalConfigManager.getEnvConfigInBoolean).mockReturnValue(
+        false,
+      );
+
+      const cacheConfig: Cache = { id: 'new-cache-id', strategy: 'read-write' };
+      const result = processCacheConfig(
+        cacheConfig,
+        'fallback-id',
+        'legacy-cache-id',
+      );
+
+      expect(globalConfigManager.getEnvConfigInBoolean).not.toHaveBeenCalled();
+      expect(result).toEqual({
+        id: 'new-cache-id',
+        strategy: 'read-write',
+      });
+    });
+  });
+
+  describe('Strategy handling', () => {
+    test('should preserve strategy in cache config', () => {
+      const strategies = ['read-only', 'read-write', 'write-only'] as const;
+
+      strategies.forEach((strategy) => {
+        const cacheConfig = { id: 'test-cache', strategy };
+        const result = processCacheConfig(cacheConfig, 'fallback-id');
+
+        expect(result).toEqual({
+          id: 'test-cache',
+          strategy,
+        });
+      });
+    });
+
+    test('should add default strategy when not provided', () => {
+      const cacheConfig = { id: 'test-cache' };
+      const result = processCacheConfig(cacheConfig, 'fallback-id');
+
+      expect(result).toEqual({
+        id: 'test-cache',
+      });
+    });
+  });
+
+  describe('Fallback ID generation', () => {
+    test('should use provided fallback ID', () => {
+      const result = processCacheConfig(true, 'my-custom-fallback-id');
+
+      expect(result).toEqual({
+        id: 'my-custom-fallback-id',
+      });
+    });
+
+    test('should use fallback ID when cache object missing ID', () => {
+      const cacheConfig: Cache = { strategy: 'read-only' };
+      const result = processCacheConfig(cacheConfig, 'my-custom-fallback-id');
+
+      expect(result).toEqual({
+        id: 'my-custom-fallback-id',
+        strategy: 'read-only',
+      });
+    });
+  });
+
+  describe('CLI-specific scenarios', () => {
+    test('should handle YAML script cache configuration from file name', () => {
+      // Simulate a scenario where cache config comes from YAML script
+      const fileName = 'test-script';
+      const yamlCacheConfig = { id: 'yaml-defined-cache' };
+
+      const result = processCacheConfig(yamlCacheConfig, fileName);
+
+      expect(result).toEqual({
+        id: 'yaml-defined-cache',
+      });
+    });
+
+    test('should generate cache ID from file name when YAML cache is true', () => {
+      const fileName = 'test-script';
+      const yamlCacheConfig = true;
+
+      const result = processCacheConfig(yamlCacheConfig, fileName);
+
+      expect(result).toEqual({
+        id: 'test-script',
+      });
+    });
+
+    test('should handle complex YAML cache configuration', () => {
+      const fileName = 'complex-test';
+      const yamlCacheConfig: Cache = {
+        id: 'complex-cache',
+        strategy: 'read-only',
+        // Additional properties that might be in YAML
+        customProp: 'should-be-preserved',
+      } as Cache;
+
+      const result = processCacheConfig(yamlCacheConfig, fileName);
+
+      expect(result).toEqual({
+        id: 'complex-cache',
+        strategy: 'read-only',
+        customProp: 'should-be-preserved',
+      });
+    });
+  });
+
+  describe('Backward compatibility', () => {
+    test('should handle legacy cacheId with environment variable correctly', () => {
+      vi.mocked(globalConfigManager.getEnvConfigInBoolean).mockReturnValue(
+        true,
+      );
+
+      // Simulate old-style cache configuration
+      const result = processCacheConfig(
+        undefined,
+        'fallback-id',
+        'my-legacy-cache',
+      );
+
+      expect(result).toEqual({
+        id: 'my-legacy-cache',
+      });
+    });
+
+    test('should ignore legacy cacheId when environment variable is not set', () => {
+      vi.mocked(globalConfigManager.getEnvConfigInBoolean).mockReturnValue(
+        false,
+      );
+
+      const result = processCacheConfig(
+        undefined,
+        'fallback-id',
+        'my-legacy-cache',
+      );
+
+      expect(result).toBeUndefined();
+    });
+  });
+});