test(image-analysis): cover runtime auth and fallback

tests/unit/utils/claudecode-env-stripping.test.ts

@@ -384,6 +384,41 @@ describe('CLAUDECODE environment stripping', () => {
     });
   });
 
+  it('headless executor prepares image-analysis MCP and compatibility hook fallback', async () => {
+    writeConfigWithAutoUpdatePreference(false);
+    const ccsDir = path.join(process.env.CCS_HOME as string, '.ccs');
+    const settingsPath = path.join(ccsDir, 'glm.settings.json');
+    fs.writeFileSync(settingsPath, '{}\n', 'utf8');
+    process.env.CCS_CLAUDE_PATH = 'claude';
+
+    const result = await HeadlessExecutor.execute('glm', 'describe screenshot', {
+      permissionMode: 'default',
+      timeout: 1000,
+    });
+
+    expect(result.success).toBe(true);
+    expect(spawnCalls.length).toBeGreaterThan(0);
+
+    const persistedSettings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) as {
+      hooks?: { PreToolUse?: Array<{ matcher?: string }> };
+    };
+    expect(persistedSettings.hooks?.PreToolUse?.some((hook) => hook.matcher === 'Read')).toBe(true);
+
+    const claudeUserConfig = JSON.parse(
+      fs.readFileSync(path.join(process.env.CCS_HOME as string, '.claude.json'), 'utf8')
+    ) as {
+      mcpServers?: Record<string, unknown>;
+    };
+    expect(claudeUserConfig.mcpServers?.['ccs-image-analysis']).toEqual({
+      type: 'stdio',
+      command: 'node',
+      args: [path.join(ccsDir, 'mcp', 'ccs-image-analysis-server.cjs')],
+      env: {},
+    });
+    expect(fs.existsSync(path.join(ccsDir, 'hooks', 'image-analyzer-transformer.cjs'))).toBe(true);
+    expect(fs.existsSync(path.join(ccsDir, 'hooks', 'image-analysis-runtime.cjs'))).toBe(true);
+  });
+
   it('headless executor propagates a WebSearch trace launch id when tracing is enabled', async () => {
     writeConfigWithAutoUpdatePreference(false);
     const ccsDir = path.join(process.env.CCS_HOME as string, '.ccs');

tests/unit/utils/hooks/image-analysis-runtime-status.test.ts

@@ -116,7 +116,7 @@ describe('image-analysis-runtime-status', () => {
     expect(status.effectiveRuntimeReason).toContain('remote.example:443');
   });
 
-  it('keeps hook-missing on native read even when auth and proxy are ready', async () => {
+  it('keeps hook-missing as a degraded fallback state while primary runtime stays active', async () => {
     const status = await hydrateImageAnalysisRuntimeStatus(
       createStatus({
         status: 'hook-missing',
@@ -144,7 +144,7 @@ describe('image-analysis-runtime-status', () => {
 
     expect(status.authReadiness).toBe('ready');
     expect(status.proxyReadiness).toBe('ready');
-    expect(status.effectiveRuntimeMode).toBe('native-read');
+    expect(status.effectiveRuntimeMode).toBe('cliproxy-image-analysis');
     expect(status.effectiveRuntimeReason).toContain('Profile hook is missing');
   });
 });

tests/unit/utils/hooks/image-analyzer-hook-installer.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  hasImageAnalyzerHook,
+  installImageAnalyzerHook,
+} from '../../../../src/utils/hooks/image-analyzer-hook-installer';
+import { prepareImageAnalysisFallbackHook } from '../../../../src/utils/hooks';
+
+describe('image-analyzer-hook-installer', () => {
+  let tempHome = '';
+  let originalCcsHome: string | undefined;
+  let runtimePath = '';
+  let bundledRuntimePath = '';
+
+  beforeEach(() => {
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-image-analyzer-hook-'));
+    originalCcsHome = process.env.CCS_HOME;
+    process.env.CCS_HOME = tempHome;
+
+    const ccsDir = path.join(tempHome, '.ccs');
+    fs.mkdirSync(ccsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ccsDir, 'config.yaml'),
+      'version: 12\nimage_analysis:\n  enabled: true\n',
+      'utf8'
+    );
+
+    runtimePath = path.join(ccsDir, 'hooks', 'image-analysis-runtime.cjs');
+    bundledRuntimePath = path.join(process.cwd(), 'lib', 'hooks', 'image-analysis-runtime.cjs');
+  });
+
+  afterEach(() => {
+    if (originalCcsHome === undefined) {
+      delete process.env.CCS_HOME;
+    } else {
+      process.env.CCS_HOME = originalCcsHome;
+    }
+
+    if (tempHome) {
+      fs.rmSync(tempHome, { recursive: true, force: true });
+    }
+  });
+
+  it('treats a missing runtime artifact as not ready and repairs it on prepare', () => {
+    expect(installImageAnalyzerHook()).toBe(true);
+    fs.unlinkSync(runtimePath);
+
+    expect(hasImageAnalyzerHook()).toBe(false);
+    expect(prepareImageAnalysisFallbackHook()).toBe(true);
+    expect(fs.existsSync(runtimePath)).toBe(true);
+    expect(hasImageAnalyzerHook()).toBe(true);
+  });
+
+  it('refreshes stale runtime content during fallback hook preparation', () => {
+    expect(installImageAnalyzerHook()).toBe(true);
+    fs.writeFileSync(runtimePath, 'stale runtime\n', 'utf8');
+
+    expect(hasImageAnalyzerHook()).toBe(false);
+    expect(prepareImageAnalysisFallbackHook()).toBe(true);
+    expect(fs.readFileSync(runtimePath, 'utf8')).toBe(fs.readFileSync(bundledRuntimePath, 'utf8'));
+  });
+});

tests/unit/utils/hooks/image-analyzer-profile-hook-injector.test.ts

@@ -67,4 +67,23 @@ describe('image-analyzer-profile-hook-injector', () => {
     expect(fs.existsSync(defaultSettingsPath)).toBe(false);
     expect(persisted.hooks?.PreToolUse?.some((hook) => hook.matcher === 'Read')).toBe(true);
   });
+
+  it('skips copilot hook persistence when the shared fallback hook is unavailable', () => {
+    const settingsPath = path.join(tempHome, '.ccs', 'copilot.settings.json');
+    writeJson(settingsPath, {});
+
+    const ensured = ensureProfileHooks({
+      profileName: 'copilot',
+      profileType: 'copilot',
+      settingsPath,
+      sharedHookInstalled: false,
+    });
+
+    const persisted = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) as {
+      hooks?: { PreToolUse?: Array<{ matcher?: string }> };
+    };
+
+    expect(ensured).toBe(false);
+    expect(persisted.hooks).toBeUndefined();
+  });
 });

tests/unit/utils/image-analysis/claude-tool-args.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  appendThirdPartyImageAnalysisToolArgs,
+  getImageAnalysisSteeringPrompt,
+} from '../../../../src/utils/image-analysis';
+
+describe('appendThirdPartyImageAnalysisToolArgs', () => {
+  it('appends the steering prompt for image analysis', () => {
+    const args = appendThirdPartyImageAnalysisToolArgs(['-p', 'describe the screenshot']);
+
+    expect(args).toEqual(['-p', 'describe the screenshot', '--append-system-prompt', getImageAnalysisSteeringPrompt()]);
+  });
+
+  it('does not duplicate the steering prompt when already present', () => {
+    const steeringPrompt = getImageAnalysisSteeringPrompt();
+    const args = appendThirdPartyImageAnalysisToolArgs([
+      '-p',
+      'describe the screenshot',
+      '--append-system-prompt',
+      steeringPrompt,
+    ]);
+
+    expect(args.filter((arg) => arg === steeringPrompt)).toHaveLength(1);
+    expect(args.filter((arg) => arg === '--append-system-prompt')).toHaveLength(1);
+  });
+
+  it('preserves trailing arguments after --', () => {
+    const args = appendThirdPartyImageAnalysisToolArgs(['-p', 'describe', '--', 'extra']);
+
+    expect(args).toEqual([
+      '-p',
+      'describe',
+      '--append-system-prompt',
+      getImageAnalysisSteeringPrompt(),
+      '--',
+      'extra',
+    ]);
+  });
+});

tests/unit/utils/image-analysis/mcp-installer.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, describe, expect, it, mock } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  ensureImageAnalysisMcp,
+  getImageAnalysisMcpRuntimePath,
+  getImageAnalysisMcpServerName,
+  getImageAnalysisMcpServerPath,
+  uninstallImageAnalysisMcp,
+} from '../../../../src/utils/image-analysis';
+
+describe('ensureImageAnalysisMcp', () => {
+  let tempHome: string | undefined;
+  let originalCcsHome: string | undefined;
+
+  function setupTempHome(): string {
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-image-analysis-mcp-'));
+    originalCcsHome = process.env.CCS_HOME;
+    process.env.CCS_HOME = tempHome;
+    return tempHome;
+  }
+
+  function getCcsDir(): string {
+    if (!tempHome) {
+      throw new Error('tempHome not initialized');
+    }
+    return path.join(tempHome, '.ccs');
+  }
+
+  function writeEnabledConfig(): void {
+    const ccsDir = getCcsDir();
+    fs.mkdirSync(ccsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ccsDir, 'config.yaml'),
+      [
+        'version: 12',
+        'image_analysis:',
+        '  enabled: true',
+        '  timeout: 60',
+        '  fallback_backend: agy',
+        '  provider_models:',
+        '    agy: gemini-3-1-flash-preview',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+  }
+
+  function getManagedConfig() {
+    return {
+      type: 'stdio',
+      command: 'node',
+      args: [getImageAnalysisMcpServerPath()],
+      env: {},
+    };
+  }
+
+  afterEach(() => {
+    mock.restore();
+
+    if (originalCcsHome !== undefined) {
+      process.env.CCS_HOME = originalCcsHome;
+    } else {
+      delete process.env.CCS_HOME;
+    }
+
+    if (tempHome && fs.existsSync(tempHome)) {
+      fs.rmSync(tempHome, { recursive: true, force: true });
+    }
+
+    tempHome = undefined;
+    originalCcsHome = undefined;
+  });
+
+  it('installs the MCP server and preserves existing user mcpServers entries', () => {
+    setupTempHome();
+    writeEnabledConfig();
+
+    const claudeUserConfigPath = path.join(tempHome as string, '.claude.json');
+    fs.writeFileSync(
+      claudeUserConfigPath,
+      JSON.stringify(
+        {
+          mcpServers: {
+            existing: { command: 'uvx', args: ['some-server'] },
+          },
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    expect(ensureImageAnalysisMcp()).toBe(true);
+    expect(fs.existsSync(getImageAnalysisMcpServerPath())).toBe(true);
+    expect(fs.existsSync(getImageAnalysisMcpRuntimePath())).toBe(true);
+
+    const config = JSON.parse(fs.readFileSync(claudeUserConfigPath, 'utf8')) as {
+      mcpServers: Record<string, unknown>;
+    };
+
+    expect(config.mcpServers.existing).toEqual({ command: 'uvx', args: ['some-server'] });
+    expect(config.mcpServers[getImageAnalysisMcpServerName()]).toEqual(getManagedConfig());
+  });
+
+  it('removes the managed MCP runtime while preserving unrelated server entries', () => {
+    setupTempHome();
+    writeEnabledConfig();
+
+    const claudeUserConfigPath = path.join(tempHome as string, '.claude.json');
+    fs.writeFileSync(
+      claudeUserConfigPath,
+      JSON.stringify(
+        {
+          mcpServers: {
+            existing: { command: 'uvx', args: ['some-server'] },
+          },
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    expect(ensureImageAnalysisMcp()).toBe(true);
+
+    const instancePath = path.join(tempHome as string, '.ccs', 'instances', 'work');
+    fs.mkdirSync(instancePath, { recursive: true });
+    fs.writeFileSync(
+      path.join(instancePath, '.claude.json'),
+      JSON.stringify(
+        {
+          mcpServers: {
+            existing: { command: 'uvx', args: ['instance-server'] },
+            [getImageAnalysisMcpServerName()]: { command: 'node', args: ['/tmp/override.cjs'] },
+          },
+          otherKey: 'keep-me',
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    expect(uninstallImageAnalysisMcp()).toBe(true);
+    expect(fs.existsSync(getImageAnalysisMcpServerPath())).toBe(false);
+    expect(fs.existsSync(getImageAnalysisMcpRuntimePath())).toBe(false);
+
+    const globalConfig = JSON.parse(fs.readFileSync(claudeUserConfigPath, 'utf8')) as {
+      mcpServers: Record<string, { command: string; args: string[] }>;
+    };
+    expect(globalConfig.mcpServers).toEqual({
+      existing: { command: 'uvx', args: ['some-server'] },
+    });
+
+    const instanceConfig = JSON.parse(
+      fs.readFileSync(path.join(instancePath, '.claude.json'), 'utf8')
+    ) as {
+      otherKey: string;
+      mcpServers: Record<string, { command: string; args: string[] }>;
+    };
+    expect(instanceConfig.otherKey).toBe('keep-me');
+    expect(instanceConfig.mcpServers).toEqual({
+      existing: { command: 'uvx', args: ['instance-server'] },
+    });
+  });
+
+  it('installs the first-class MCP runtime even when the legacy hooks path is unusable', () => {
+    setupTempHome();
+    writeEnabledConfig();
+
+    const hooksPath = path.join(getCcsDir(), 'hooks');
+    fs.writeFileSync(hooksPath, 'not-a-directory', 'utf8');
+
+    expect(ensureImageAnalysisMcp()).toBe(true);
+    expect(fs.existsSync(getImageAnalysisMcpServerPath())).toBe(true);
+    expect(fs.existsSync(getImageAnalysisMcpRuntimePath())).toBe(true);
+  });
+});