@jackwener/opencli 1.7.4 → 1.7.6

package/dist/src/generate-verified.test.js

@@ -1,925 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-const { mockExploreUrl, mockLoadExploreBundle, mockSynthesizeFromExplore, mockBrowserSession, mockCascadeProbe, mockExecutePipeline, mockRegisterCommand, } = vi.hoisted(() => ({
-    mockExploreUrl: vi.fn(),
-    mockLoadExploreBundle: vi.fn(),
-    mockSynthesizeFromExplore: vi.fn(),
-    mockBrowserSession: vi.fn(),
-    mockCascadeProbe: vi.fn(),
-    mockExecutePipeline: vi.fn(),
-    mockRegisterCommand: vi.fn(),
-}));
-vi.mock('./explore.js', () => ({
-    exploreUrl: mockExploreUrl,
-}));
-vi.mock('./synthesize.js', () => ({
-    loadExploreBundle: mockLoadExploreBundle,
-    synthesizeFromExplore: mockSynthesizeFromExplore,
-}));
-vi.mock('./runtime.js', () => ({
-    browserSession: mockBrowserSession,
-}));
-vi.mock('./cascade.js', () => ({
-    cascadeProbe: mockCascadeProbe,
-}));
-vi.mock('./pipeline/index.js', () => ({
-    executePipeline: mockExecutePipeline,
-}));
-vi.mock('./registry.js', async () => {
-    const actual = await vi.importActual('./registry.js');
-    return {
-        ...actual,
-        registerCommand: mockRegisterCommand,
-    };
-});
-vi.mock('./discovery.js', () => ({
-    USER_CLIS_DIR: '/tmp/opencli-user-clis',
-}));
-import { Strategy } from './registry.js';
-import { generateVerifiedFromUrl } from './generate-verified.js';
-describe('generateVerifiedFromUrl', () => {
-    let tempDir;
-    beforeEach(() => {
-        tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-generate-verified-'));
-        mockExploreUrl.mockReset();
-        mockLoadExploreBundle.mockReset();
-        mockSynthesizeFromExplore.mockReset();
-        mockBrowserSession.mockReset();
-        mockCascadeProbe.mockReset();
-        mockExecutePipeline.mockReset();
-        mockRegisterCommand.mockReset();
-    });
-    afterEach(() => {
-        fs.rmSync(tempDir, { recursive: true, force: true });
-    });
-    // ── Blocked outcomes ──────────────────────────────────────────────────────
-    it('returns blocked with no-viable-api-surface when discover finds no API endpoints', async () => {
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 0,
-            capabilities: [],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [],
-            capabilities: [],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 0,
-            candidates: [],
-        });
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-        });
-        expect(result.status).toBe('blocked');
-        expect(result.reason).toBe('no-viable-api-surface');
-        expect(result.stage).toBe('explore');
-        expect(result.confidence).toBe('high');
-        expect(result.message).toBeDefined();
-        expect(result.stats.api_endpoint_count).toBe(0);
-        expect(mockBrowserSession).not.toHaveBeenCalled();
-    });
-    it('returns blocked with auth-too-complex when no PUBLIC/COOKIE probe succeeds', async () => {
-        const candidatePath = path.join(tempDir, 'hot.json');
-        fs.writeFileSync(candidatePath, JSON.stringify({
-            site: 'demo',
-            name: 'hot',
-            description: 'demo hot',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {},
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/hot' } },
-                { select: 'data.items' },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'cookie',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [{ name: 'hot' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [{
-                    pattern: 'demo.test/api/hot',
-                    url: 'https://demo.test/api/hot',
-                    itemPath: 'data.items',
-                    itemCount: 5,
-                    detectedFields: { title: 'title', url: 'url' },
-                }],
-            capabilities: [{ name: 'hot', strategy: 'cookie', endpoint: 'demo.test/api/hot', itemPath: 'data.items' }],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 1,
-            candidates: [{ name: 'hot', path: candidatePath, strategy: 'public' }],
-        });
-        const page = { goto: vi.fn() };
-        mockBrowserSession.mockImplementation(async (_factory, fn) => fn(page));
-        mockCascadeProbe.mockResolvedValue({
-            bestStrategy: Strategy.COOKIE,
-            probes: [
-                { strategy: Strategy.PUBLIC, success: false },
-                { strategy: Strategy.COOKIE, success: false },
-            ],
-            confidence: 0.3,
-        });
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-        });
-        expect(mockExecutePipeline).not.toHaveBeenCalled();
-        expect(result.status).toBe('blocked');
-        expect(result.reason).toBe('auth-too-complex');
-        expect(result.stage).toBe('cascade');
-        expect(result.confidence).toBe('high');
-    });
-    // ── Success outcomes ──────────────────────────────────────────────────────
-    it('verifies the selected candidate in a single session and registers on success with sidecar metadata', async () => {
-        const hotPath = path.join(tempDir, 'hot.json');
-        const searchPath = path.join(tempDir, 'search.json');
-        fs.writeFileSync(hotPath, JSON.stringify({
-            site: 'demo',
-            name: 'hot',
-            description: 'demo hot',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {
-                limit: { type: 'int', default: 20 },
-            },
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/hot?limit=${{ args.limit | default(20) }}' } },
-                { select: 'data.items' },
-                { map: { rank: '${{ index + 1 }}', title: '${{ item.title }}', url: '${{ item.url }}' } },
-                { limit: '${{ args.limit | default(20) }}' },
-            ],
-        }, null, 2));
-        fs.writeFileSync(searchPath, JSON.stringify({
-            site: 'demo',
-            name: 'search',
-            description: 'demo search',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {
-                keyword: { type: 'str', required: true },
-            },
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/search?q=${{ args.keyword }}' } },
-                { select: 'payload.items' },
-                { map: { title: '${{ item.title }}', url: '${{ item.url }}' } },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test/home',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'cookie',
-            endpoint_count: 2,
-            api_endpoint_count: 2,
-            capabilities: [{ name: 'hot' }, { name: 'search' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test/home' },
-            endpoints: [
-                {
-                    pattern: 'demo.test/api/hot',
-                    url: 'https://demo.test/api/hot?limit=20',
-                    itemPath: 'data.items',
-                    itemCount: 5,
-                    detectedFields: { title: 'title', url: 'url' },
-                },
-                {
-                    pattern: 'demo.test/api/search',
-                    url: 'https://demo.test/api/search?q=test',
-                    itemPath: 'payload.items',
-                    itemCount: 10,
-                    detectedFields: { title: 'headline', url: 'permalink' },
-                },
-            ],
-            capabilities: [
-                { name: 'hot', strategy: 'public', endpoint: 'demo.test/api/hot', itemPath: 'data.items' },
-                { name: 'search', strategy: 'cookie', endpoint: 'demo.test/api/search', itemPath: 'payload.items' },
-            ],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 2,
-            candidates: [
-                { name: 'hot', path: hotPath, strategy: 'public' },
-                { name: 'search', path: searchPath, strategy: 'public' },
-            ],
-        });
-        const page = { goto: vi.fn() };
-        mockBrowserSession.mockImplementation(async (_factory, fn) => fn(page));
-        mockCascadeProbe.mockResolvedValue({
-            bestStrategy: Strategy.COOKIE,
-            probes: [
-                { strategy: Strategy.PUBLIC, success: false },
-                { strategy: Strategy.COOKIE, success: true },
-            ],
-            confidence: 0.9,
-        });
-        mockExecutePipeline.mockResolvedValue([{ title: 'hello', url: 'https://demo.test/item/1' }]);
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            goal: 'search',
-            noRegister: false,
-        });
-        expect(mockBrowserSession).toHaveBeenCalledTimes(1);
-        expect(page.goto).toHaveBeenCalledWith('https://demo.test/home');
-        expect(mockCascadeProbe).toHaveBeenCalledWith(page, 'https://demo.test/api/search?q=test', { maxStrategy: Strategy.COOKIE });
-        expect(mockExecutePipeline).toHaveBeenCalledTimes(1);
-        expect(mockRegisterCommand).toHaveBeenCalledTimes(1);
-        expect(result.status).toBe('success');
-        expect(result.adapter).toBeDefined();
-        expect(result.adapter.command).toBe('demo/search');
-        expect(result.adapter.strategy).toBe(Strategy.COOKIE);
-        expect(result.adapter.metadata_path).toBeDefined();
-        expect(result.adapter.reusability).toBe('verified-artifact');
-        expect(result.reusability).toBe('verified-artifact');
-        expect(result.stats.verified).toBe(true);
-        expect(result.stats.repair_attempted).toBe(false);
-        // Verify sidecar metadata was written
-        expect(result.adapter.metadata_path).toMatch(/\.meta\.json$/);
-        const metaContent = JSON.parse(fs.readFileSync(result.adapter.metadata_path, 'utf-8'));
-        expect(metaContent).toEqual(expect.objectContaining({
-            artifact_kind: 'verified',
-            schema_version: 1,
-            source_url: 'https://demo.test',
-            strategy: Strategy.COOKIE,
-            verified: true,
-            reusable: true,
-            reusability_reason: 'verified-artifact',
-        }));
-    });
-    it('writes verified artifact + sidecar metadata for --no-register success', async () => {
-        const candidatePath = path.join(tempDir, 'search.json');
-        fs.writeFileSync(candidatePath, JSON.stringify({
-            site: 'demo',
-            name: 'search',
-            description: 'demo search',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {
-                keyword: { type: 'str', required: true },
-            },
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/search?q=${{ args.keyword }}' } },
-                { select: 'payload.items' },
-                { map: { title: '${{ item.title }}', url: '${{ item.url }}' } },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test/home',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'cookie',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [{ name: 'search' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test/home' },
-            endpoints: [{
-                    pattern: 'demo.test/api/search',
-                    url: 'https://demo.test/api/search?q=test',
-                    itemPath: 'payload.items',
-                    itemCount: 10,
-                    detectedFields: { title: 'headline', url: 'permalink' },
-                }],
-            capabilities: [{ name: 'search', strategy: 'cookie', endpoint: 'demo.test/api/search', itemPath: 'payload.items' }],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 1,
-            candidates: [{ name: 'search', path: candidatePath, strategy: 'public' }],
-        });
-        const page = { goto: vi.fn() };
-        mockBrowserSession.mockImplementation(async (_factory, fn) => fn(page));
-        mockCascadeProbe.mockResolvedValue({
-            bestStrategy: Strategy.COOKIE,
-            probes: [
-                { strategy: Strategy.PUBLIC, success: false },
-                { strategy: Strategy.COOKIE, success: true },
-            ],
-            confidence: 0.9,
-        });
-        mockExecutePipeline.mockResolvedValue([{ title: 'hello', url: 'https://demo.test/item/1' }]);
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            goal: 'search',
-            noRegister: true,
-        });
-        expect(result.status).toBe('success');
-        expect(path.normalize(result.adapter.path).endsWith(path.join('verified', 'search.verified.js'))).toBe(true);
-        expect(result.adapter?.path).not.toBe(candidatePath);
-        expect(path.normalize(result.adapter.metadata_path).endsWith(path.join('verified', 'search.verified.meta.json'))).toBe(true);
-        expect(fs.existsSync(result.adapter.path)).toBe(true);
-        expect(fs.existsSync(result.adapter.metadata_path)).toBe(true);
-        expect(mockRegisterCommand).not.toHaveBeenCalled();
-    });
-    // ── needs-human-check outcomes ────────────────────────────────────────────
-    it('returns needs-human-check with structured escalation when repair exhausted', async () => {
-        const candidatePath = path.join(tempDir, 'hot.json');
-        fs.writeFileSync(candidatePath, JSON.stringify({
-            site: 'demo',
-            name: 'hot',
-            description: 'demo hot',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {
-                limit: { type: 'int', default: 20 },
-            },
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/hot?limit=${{ args.limit | default(20) }}' } },
-                { select: 'wrong.items' },
-                { map: { rank: '${{ index + 1 }}', title: '${{ item.title }}', url: '${{ item.url }}' } },
-                { limit: '${{ args.limit | default(20) }}' },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [{ name: 'hot' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [{
-                    pattern: 'demo.test/api/hot',
-                    url: 'https://demo.test/api/hot?limit=20',
-                    itemPath: 'data.items',
-                    itemCount: 5,
-                    detectedFields: { title: 'title', url: 'url' },
-                }],
-            capabilities: [{ name: 'hot', strategy: 'public', endpoint: 'demo.test/api/hot', itemPath: 'data.items' }],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 1,
-            candidates: [{ name: 'hot', path: candidatePath, strategy: 'public' }],
-        });
-        const page = { goto: vi.fn() };
-        mockBrowserSession.mockImplementation(async (_factory, fn) => fn(page));
-        mockCascadeProbe.mockResolvedValue({
-            bestStrategy: Strategy.PUBLIC,
-            probes: [{ strategy: Strategy.PUBLIC, success: true }],
-            confidence: 1,
-        });
-        mockExecutePipeline.mockResolvedValueOnce([]).mockResolvedValueOnce([]);
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-        });
-        expect(mockExecutePipeline).toHaveBeenCalledTimes(2);
-        expect(mockExecutePipeline.mock.calls[0]?.[1]).toEqual(expect.arrayContaining([{ select: 'wrong.items' }]));
-        expect(mockExecutePipeline.mock.calls[1]?.[1]).toEqual(expect.arrayContaining([{ select: 'data.items' }]));
-        // Verify structured escalation contract
-        expect(result.status).toBe('needs-human-check');
-        expect(result.escalation).toBeDefined();
-        expect(result.escalation.stage).toBe('fallback');
-        expect(result.escalation.reason).toBe('empty-result');
-        expect(result.escalation.confidence).toBe('low');
-        expect(result.escalation.suggested_action).toBe('inspect-with-browser');
-        expect(result.escalation.candidate).toBeDefined();
-        expect(result.escalation.candidate.command).toBe('demo/hot');
-        expect(result.escalation.candidate.reusability).toBe('unverified-candidate');
-        expect(result.reusability).toBe('unverified-candidate');
-        expect(result.message).toContain('Repair exhausted');
-        expect(result.stats.repair_attempted).toBe(true);
-        expect(result.stats.verified).toBe(false);
-    });
-    it('returns needs-human-check with ask-for-sample-arg for unsupported required args', async () => {
-        const candidatePath = path.join(tempDir, 'detail.json');
-        fs.writeFileSync(candidatePath, JSON.stringify({
-            site: 'demo',
-            name: 'detail',
-            description: 'demo detail',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {
-                id: { type: 'str', required: true },
-            },
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/detail?id=${{ args.id }}' } },
-                { select: 'data.item' },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test/detail/123',
-            final_url: 'https://demo.test/detail/123',
-            title: 'Demo detail',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [{ name: 'detail' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test/detail/123', final_url: 'https://demo.test/detail/123' },
-            endpoints: [{
-                    pattern: 'demo.test/api/detail',
-                    url: 'https://demo.test/api/detail?id=123',
-                    itemPath: 'data.item',
-                    itemCount: 1,
-                    detectedFields: { title: 'title', url: 'url' },
-                }],
-            capabilities: [{ name: 'detail', strategy: 'public', endpoint: 'demo.test/api/detail', itemPath: 'data.item' }],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 1,
-            candidates: [{ name: 'detail', path: candidatePath, strategy: 'public' }],
-        });
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test/detail/123',
-            BrowserFactory: class {
-            },
-            goal: 'detail',
-            noRegister: true,
-        });
-        expect(mockBrowserSession).not.toHaveBeenCalled();
-        expect(result.status).toBe('needs-human-check');
-        expect(result.escalation).toBeDefined();
-        expect(result.escalation.stage).toBe('synthesize');
-        expect(result.escalation.reason).toBe('unsupported-required-args');
-        expect(result.escalation.confidence).toBe('high');
-        expect(result.escalation.suggested_action).toBe('ask-for-sample-arg');
-        expect(result.escalation.candidate.reusability).toBe('unverified-candidate');
-        expect(result.reusability).toBe('unverified-candidate');
-        expect(result.message).toContain('required args: id');
-    });
-    // ── Contract shape validation ─────────────────────────────────────────────
-    it('all outcome statuses include status and stats', async () => {
-        // Test the blocked path - simplest to set up
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 0,
-            api_endpoint_count: 0,
-            capabilities: [],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [],
-            capabilities: [],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 0,
-            candidates: [],
-        });
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-        });
-        // Every outcome must have these three fields
-        expect(result).toHaveProperty('status');
-        expect(result).toHaveProperty('stats');
-        expect(['success', 'blocked', 'needs-human-check']).toContain(result.status);
-        // Blocked must have stage + reason + confidence
-        if (result.status === 'blocked') {
-            expect(result).toHaveProperty('reason');
-            expect(result).toHaveProperty('stage');
-            expect(result).toHaveProperty('confidence');
-        }
-    });
-    // ── P2: EarlyHint callback ────────────────────────────────────────────────
-    it('emits explore stop hint when no API surface found', async () => {
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 0,
-            capabilities: [],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [],
-            capabilities: [],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 0,
-            candidates: [],
-        });
-        const hints = [];
-        await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-            onEarlyHint: (h) => hints.push(h),
-        });
-        expect(hints).toHaveLength(1);
-        expect(hints[0]).toEqual({
-            stage: 'explore',
-            continue: false,
-            reason: 'no-viable-api-surface',
-            confidence: 'high',
-        });
-    });
-    it('emits explore continue + synthesize stop hints when no candidate found', async () => {
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [{
-                    pattern: 'demo.test/api/hot',
-                    url: 'https://demo.test/api/hot',
-                    itemPath: 'data.items',
-                    itemCount: 5,
-                    detectedFields: { title: 'title' },
-                }],
-            capabilities: [],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 0,
-            candidates: [],
-        });
-        const hints = [];
-        await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-            onEarlyHint: (h) => hints.push(h),
-        });
-        expect(hints).toHaveLength(2);
-        expect(hints[0]).toMatchObject({ stage: 'explore', continue: true, reason: 'api-surface-looks-viable' });
-        expect(hints[1]).toMatchObject({ stage: 'synthesize', continue: false, reason: 'no-viable-candidate' });
-    });
-    it('emits explore + synthesize continue hints with candidate on success path', async () => {
-        const hotPath = path.join(tempDir, 'hot.json');
-        fs.writeFileSync(hotPath, JSON.stringify({
-            site: 'demo',
-            name: 'hot',
-            description: 'demo hot',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {},
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/hot' } },
-                { select: 'data.items' },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [{ name: 'hot' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [{
-                    pattern: 'demo.test/api/hot',
-                    url: 'https://demo.test/api/hot',
-                    itemPath: 'data.items',
-                    itemCount: 5,
-                    detectedFields: { title: 'title', url: 'url' },
-                }],
-            capabilities: [{ name: 'hot', strategy: 'public', endpoint: 'demo.test/api/hot', itemPath: 'data.items' }],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 1,
-            candidates: [{ name: 'hot', path: hotPath, strategy: 'public' }],
-        });
-        const page = { goto: vi.fn() };
-        mockBrowserSession.mockImplementation(async (_factory, fn) => fn(page));
-        mockCascadeProbe.mockResolvedValue({
-            bestStrategy: Strategy.PUBLIC,
-            probes: [{ strategy: Strategy.PUBLIC, success: true }],
-            confidence: 1.0,
-        });
-        mockExecutePipeline.mockResolvedValue([
-            { title: 'Post 1', url: 'https://demo.test/1' },
-            { title: 'Post 2', url: 'https://demo.test/2' },
-        ]);
-        const hints = [];
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-            onEarlyHint: (h) => hints.push(h),
-        });
-        expect(result.status).toBe('success');
-        expect(hints).toHaveLength(3);
-        expect(hints[0]).toMatchObject({ stage: 'explore', continue: true });
-        expect(hints[1]).toMatchObject({
-            stage: 'synthesize',
-            continue: true,
-            reason: 'candidate-ready-for-verify',
-            candidate: { name: 'hot', command: 'demo/hot', reusability: 'unverified-candidate' },
-        });
-        expect(hints[2]).toMatchObject({
-            stage: 'cascade',
-            continue: true,
-            reason: 'candidate-ready-for-verify',
-            candidate: { name: 'hot', command: 'demo/hot' },
-        });
-        // No candidate on explore hint
-        expect(hints[0]).not.toHaveProperty('candidate');
-    });
-    it('emits cascade stop hint when auth-too-complex', async () => {
-        const hotPath = path.join(tempDir, 'hot.json');
-        fs.writeFileSync(hotPath, JSON.stringify({
-            site: 'demo',
-            name: 'hot',
-            description: 'demo hot',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {},
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/hot' } },
-                { select: 'data.items' },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'cookie',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [{ name: 'hot' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [{
-                    pattern: 'demo.test/api/hot',
-                    url: 'https://demo.test/api/hot',
-                    itemPath: 'data.items',
-                    itemCount: 5,
-                    detectedFields: { title: 'title', url: 'url' },
-                }],
-            capabilities: [{ name: 'hot', strategy: 'cookie', endpoint: 'demo.test/api/hot', itemPath: 'data.items' }],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 1,
-            candidates: [{ name: 'hot', path: hotPath, strategy: 'public' }],
-        });
-        const page = { goto: vi.fn() };
-        mockBrowserSession.mockImplementation(async (_factory, fn) => fn(page));
-        mockCascadeProbe.mockResolvedValue({
-            bestStrategy: Strategy.COOKIE,
-            probes: [
-                { strategy: Strategy.PUBLIC, success: false },
-                { strategy: Strategy.COOKIE, success: false },
-            ],
-            confidence: 0.3,
-        });
-        const hints = [];
-        await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-            onEarlyHint: (h) => hints.push(h),
-        });
-        expect(hints).toHaveLength(3);
-        expect(hints[0]).toMatchObject({ stage: 'explore', continue: true });
-        expect(hints[1]).toMatchObject({ stage: 'synthesize', continue: true, reason: 'candidate-ready-for-verify' });
-        expect(hints[2]).toMatchObject({ stage: 'cascade', continue: false, reason: 'auth-too-complex' });
-        // No candidate on stop hint
-        expect(hints[2]).not.toHaveProperty('candidate');
-    });
-    it('does NOT emit P2 hint for unsupported-required-args (P1-only decision)', async () => {
-        const detailPath = path.join(tempDir, 'detail.json');
-        fs.writeFileSync(detailPath, JSON.stringify({
-            site: 'demo',
-            name: 'detail',
-            description: 'demo detail',
-            domain: 'demo.test',
-            strategy: 'public',
-            browser: false,
-            args: {
-                id: { type: 'str', required: true },
-            },
-            columns: ['title', 'url'],
-            pipeline: [
-                { fetch: { url: 'https://demo.test/api/detail?id=${{ args.id }}' } },
-                { select: 'data.item' },
-            ],
-        }, null, 2));
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test/detail/123',
-            final_url: 'https://demo.test/detail/123',
-            title: 'Demo detail',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 1,
-            capabilities: [{ name: 'detail' }],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test/detail/123', final_url: 'https://demo.test/detail/123' },
-            endpoints: [{
-                    pattern: 'demo.test/api/detail',
-                    url: 'https://demo.test/api/detail?id=123',
-                    itemPath: 'data.item',
-                    itemCount: 1,
-                    detectedFields: { title: 'title', url: 'url' },
-                }],
-            capabilities: [{ name: 'detail', strategy: 'public', endpoint: 'demo.test/api/detail', itemPath: 'data.item' }],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 1,
-            candidates: [{ name: 'detail', path: detailPath, strategy: 'public' }],
-        });
-        const hints = [];
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test/detail/123',
-            BrowserFactory: class {
-            },
-            goal: 'detail',
-            noRegister: true,
-            onEarlyHint: (h) => hints.push(h),
-        });
-        expect(result.status).toBe('needs-human-check');
-        expect(result.escalation.reason).toBe('unsupported-required-args');
-        // Only explore continue hint is emitted; NO synthesize hint before the P1 terminal
-        expect(hints).toHaveLength(1);
-        expect(hints[0]).toMatchObject({ stage: 'explore', continue: true });
-        // Specifically: no synthesize hint was emitted
-        expect(hints.find(h => h.stage === 'synthesize')).toBeUndefined();
-    });
-    it('does not emit hints when onEarlyHint is not provided', async () => {
-        mockExploreUrl.mockResolvedValue({
-            site: 'demo',
-            target_url: 'https://demo.test',
-            final_url: 'https://demo.test',
-            title: 'Demo',
-            framework: {},
-            stores: [],
-            top_strategy: 'public',
-            endpoint_count: 1,
-            api_endpoint_count: 0,
-            capabilities: [],
-            auth_indicators: [],
-            out_dir: tempDir,
-        });
-        mockLoadExploreBundle.mockReturnValue({
-            manifest: { site: 'demo', target_url: 'https://demo.test', final_url: 'https://demo.test' },
-            endpoints: [],
-            capabilities: [],
-        });
-        mockSynthesizeFromExplore.mockReturnValue({
-            site: 'demo',
-            explore_dir: tempDir,
-            out_dir: tempDir,
-            candidate_count: 0,
-            candidates: [],
-        });
-        // Should not throw even without onEarlyHint
-        const result = await generateVerifiedFromUrl({
-            url: 'https://demo.test',
-            BrowserFactory: class {
-            },
-            noRegister: true,
-        });
-        expect(result.status).toBe('blocked');
-    });
-});