@jackwener/opencli 1.6.8 → 1.6.10

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

@@ -0,0 +1,925 @@
+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.ts'))).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');
+    });
+});