@jackwener/opencli 1.7.8 → 1.7.10

package/dist/src/observation/redaction.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { redactHeaders, redactUrl, redactValue } from './redaction.js';
+describe('observation redaction', () => {
+    it('redacts sensitive headers by default', () => {
+        expect(redactHeaders({
+            authorization: 'Bearer secret-token',
+            cookie: 'sid=abc',
+            'set-cookie': 'sid=abc',
+            accept: 'application/json',
+        })).toEqual({
+            authorization: '[REDACTED]',
+            cookie: '[REDACTED]',
+            'set-cookie': '[REDACTED]',
+            accept: 'application/json',
+        });
+    });
+    it('redacts sensitive url query params', () => {
+        expect(redactUrl('https://x.test/api?token=abc&ok=1&password=secret'))
+            .toBe('https://x.test/api?token=[REDACTED]&ok=1&password=[REDACTED]');
+    });
+    it('redacts password and token fields recursively', () => {
+        expect(redactValue({
+            user: 'alice',
+            password: 'secret',
+            nested: { access_token: 'abc123456789', value: 'safe' },
+        })).toEqual({
+            user: 'alice',
+            password: '[REDACTED]',
+            nested: { access_token: '[REDACTED]', value: 'safe' },
+        });
+    });
+});

package/dist/src/observation/retention.d.ts

@@ -0,0 +1,32 @@
+export interface TraceRetentionPolicyInput {
+    maxAgeDays?: number;
+    maxCountPerProfile?: number;
+    maxBytesPerProfile?: string | number;
+}
+export interface ResolvedTraceRetentionPolicy {
+    maxAgeDays: number;
+    maxAgeMs: number;
+    maxCountPerProfile: number;
+    maxBytesPerProfile: number;
+}
+export interface TraceRetentionPruneResult {
+    scanned: number;
+    deleted: string[];
+    kept: string[];
+    totalBytesBefore: number;
+    totalBytesAfter: number;
+}
+export declare const DEFAULT_TRACE_RETENTION_POLICY: {
+    maxAgeDays: number;
+    maxCountPerProfile: number;
+    maxBytesPerProfile: string;
+};
+export declare function parseByteSize(value: string | number): number;
+export declare function resolveTraceRetentionPolicy(input?: TraceRetentionPolicyInput): ResolvedTraceRetentionPolicy;
+export declare function traceExpiresAt(createdAt: string, policyInput?: TraceRetentionPolicyInput): string;
+export declare function pruneTraceArtifacts(tracesDir: string, opts?: {
+    policy?: TraceRetentionPolicyInput;
+    protectedTraceDirs?: string[];
+    now?: () => number;
+    warn?: (message: string) => void;
+}): TraceRetentionPruneResult;

package/dist/src/observation/retention.js

@@ -0,0 +1,160 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { log } from '../logger.js';
+export const DEFAULT_TRACE_RETENTION_POLICY = {
+    maxAgeDays: 7,
+    maxCountPerProfile: 20,
+    maxBytesPerProfile: '500MB',
+};
+const BYTES_UNITS = {
+    B: 1,
+    KB: 1024,
+    MB: 1024 ** 2,
+    GB: 1024 ** 3,
+};
+export function parseByteSize(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value < 0)
+            throw new Error(`Invalid byte size: ${value}`);
+        return Math.floor(value);
+    }
+    const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$/i);
+    if (!match)
+        throw new Error(`Invalid byte size: ${value}`);
+    const amount = Number(match[1]);
+    const unit = (match[2] ?? 'B').toUpperCase();
+    return Math.floor(amount * BYTES_UNITS[unit]);
+}
+export function resolveTraceRetentionPolicy(input = {}) {
+    const maxAgeDays = input.maxAgeDays ?? DEFAULT_TRACE_RETENTION_POLICY.maxAgeDays;
+    const maxCountPerProfile = input.maxCountPerProfile ?? DEFAULT_TRACE_RETENTION_POLICY.maxCountPerProfile;
+    if (!Number.isFinite(maxAgeDays) || maxAgeDays < 0)
+        throw new Error(`Invalid trace maxAgeDays: ${maxAgeDays}`);
+    if (!Number.isInteger(maxCountPerProfile) || maxCountPerProfile < 0) {
+        throw new Error(`Invalid trace maxCountPerProfile: ${maxCountPerProfile}`);
+    }
+    return {
+        maxAgeDays,
+        maxAgeMs: maxAgeDays * 24 * 60 * 60 * 1000,
+        maxCountPerProfile,
+        maxBytesPerProfile: parseByteSize(input.maxBytesPerProfile ?? DEFAULT_TRACE_RETENTION_POLICY.maxBytesPerProfile),
+    };
+}
+export function traceExpiresAt(createdAt, policyInput = {}) {
+    const policy = resolveTraceRetentionPolicy(policyInput);
+    const createdAtMs = Date.parse(createdAt);
+    const base = Number.isFinite(createdAtMs) ? createdAtMs : Date.now();
+    return new Date(base + policy.maxAgeMs).toISOString();
+}
+export function pruneTraceArtifacts(tracesDir, opts = {}) {
+    const warn = opts.warn ?? ((message) => log.warn(`[trace] ${message}`));
+    const policy = resolveTraceRetentionPolicy(opts.policy);
+    const now = opts.now ?? Date.now;
+    const protectedDirs = new Set((opts.protectedTraceDirs ?? []).map((dir) => path.resolve(dir)));
+    const entries = readTraceEntries(tracesDir, protectedDirs, warn);
+    const totalBytesBefore = entries.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+    const deleted = new Set();
+    const sorted = [...entries].sort((a, b) => a.createdAtMs - b.createdAtMs || a.dir.localeCompare(b.dir));
+    const cutoff = now() - policy.maxAgeMs;
+    for (const entry of sorted) {
+        if (!entry.protected && entry.createdAtMs < cutoff)
+            deleted.add(entry.dir);
+    }
+    let remaining = sorted.filter((entry) => !deleted.has(entry.dir));
+    while (remaining.length > policy.maxCountPerProfile) {
+        const victim = remaining.find((entry) => !entry.protected);
+        if (!victim)
+            break;
+        deleted.add(victim.dir);
+        remaining = remaining.filter((entry) => entry.dir !== victim.dir);
+    }
+    let remainingBytes = remaining.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+    while (remainingBytes > policy.maxBytesPerProfile) {
+        const victim = remaining.find((entry) => !entry.protected);
+        if (!victim)
+            break;
+        deleted.add(victim.dir);
+        remaining = remaining.filter((entry) => entry.dir !== victim.dir);
+        remainingBytes -= victim.sizeBytes;
+    }
+    const deletedDirs = [];
+    for (const dir of sorted.map((entry) => entry.dir).filter((dir) => deleted.has(dir))) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            deletedDirs.push(dir);
+        }
+        catch (err) {
+            warn(`Failed to prune trace artifact ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const keptEntries = entries.filter((entry) => !deletedDirs.includes(entry.dir));
+    return {
+        scanned: entries.length,
+        deleted: deletedDirs,
+        kept: keptEntries.map((entry) => entry.dir),
+        totalBytesBefore,
+        totalBytesAfter: keptEntries.reduce((sum, entry) => sum + entry.sizeBytes, 0),
+    };
+}
+function readTraceEntries(tracesDir, protectedDirs, warn) {
+    let names;
+    try {
+        names = fs.readdirSync(tracesDir);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return [];
+        warn(`Failed to list trace artifacts in ${tracesDir}: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        const dir = path.join(tracesDir, name);
+        try {
+            const stat = fs.statSync(dir);
+            if (!stat.isDirectory())
+                continue;
+            entries.push({
+                dir,
+                createdAtMs: readCreatedAtMs(dir, stat.mtimeMs),
+                sizeBytes: directorySize(dir),
+                protected: protectedDirs.has(path.resolve(dir)),
+            });
+        }
+        catch (err) {
+            if (!isEnoent(err)) {
+                warn(`Failed to inspect trace artifact ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return entries;
+}
+function readCreatedAtMs(dir, fallbackMs) {
+    try {
+        const receipt = JSON.parse(fs.readFileSync(path.join(dir, 'receipt.json'), 'utf-8'));
+        if (typeof receipt.createdAt === 'string') {
+            const parsed = Date.parse(receipt.createdAt);
+            if (Number.isFinite(parsed))
+                return parsed;
+        }
+    }
+    catch {
+        // Older or hand-edited trace directories may not have a receipt.
+    }
+    return fallbackMs;
+}
+function directorySize(dir) {
+    let total = 0;
+    for (const name of fs.readdirSync(dir)) {
+        const item = path.join(dir, name);
+        const stat = fs.lstatSync(item);
+        if (stat.isDirectory())
+            total += directorySize(item);
+        else
+            total += stat.size;
+    }
+    return total;
+}
+function isEnoent(err) {
+    return typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT';
+}

package/dist/src/observation/retention.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/observation/retention.test.js

@@ -0,0 +1,118 @@
+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';
+import { parseByteSize, pruneTraceArtifacts } from './retention.js';
+describe('trace artifact retention', () => {
+    let tmpDir;
+    let tracesDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-trace-retention-'));
+        tracesDir = path.join(tmpDir, 'profiles', 'default', 'traces');
+        fs.mkdirSync(tracesDir, { recursive: true });
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('parses byte budgets with units', () => {
+        expect(parseByteSize(128)).toBe(128);
+        expect(parseByteSize('128')).toBe(128);
+        expect(parseByteSize('2KB')).toBe(2 * 1024);
+        expect(parseByteSize('1.5MB')).toBe(Math.floor(1.5 * 1024 * 1024));
+        expect(parseByteSize('1 GB')).toBe(1024 ** 3);
+        expect(() => parseByteSize('many')).toThrow('Invalid byte size');
+    });
+    it('prunes traces older than the age budget', () => {
+        const now = Date.parse('2026-05-03T00:00:00.000Z');
+        const old = createTraceDir('old', '2026-04-24T00:00:00.000Z');
+        const recent = createTraceDir('recent', '2026-05-02T00:00:00.000Z');
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => now,
+            policy: { maxAgeDays: 7, maxCountPerProfile: 20, maxBytesPerProfile: '500MB' },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([old]);
+        expect(fs.existsSync(old)).toBe(false);
+        expect(fs.existsSync(recent)).toBe(true);
+    });
+    it('prunes oldest traces over the count budget', () => {
+        const oldest = createTraceDir('oldest', '2026-05-01T00:00:00.000Z');
+        const middle = createTraceDir('middle', '2026-05-02T00:00:00.000Z');
+        const newest = createTraceDir('newest', '2026-05-03T00:00:00.000Z');
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => Date.parse('2026-05-03T12:00:00.000Z'),
+            policy: { maxAgeDays: 30, maxCountPerProfile: 2, maxBytesPerProfile: '500MB' },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([oldest]);
+        expect(fs.existsSync(oldest)).toBe(false);
+        expect(fs.existsSync(middle)).toBe(true);
+        expect(fs.existsSync(newest)).toBe(true);
+    });
+    it('prunes oldest traces over the byte budget', () => {
+        const oldest = createTraceDir('oldest', '2026-05-01T00:00:00.000Z', 512);
+        const middle = createTraceDir('middle', '2026-05-02T00:00:00.000Z', 64);
+        const newest = createTraceDir('newest', '2026-05-03T00:00:00.000Z', 64);
+        const budget = directorySize(middle) + directorySize(newest) + 1;
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => Date.parse('2026-05-03T12:00:00.000Z'),
+            policy: { maxAgeDays: 30, maxCountPerProfile: 20, maxBytesPerProfile: budget },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([oldest]);
+        expect(fs.existsSync(oldest)).toBe(false);
+        expect(fs.existsSync(middle)).toBe(true);
+        expect(fs.existsSync(newest)).toBe(true);
+    });
+    it('falls back to directory mtime when receipt is missing', () => {
+        const now = Date.parse('2026-05-03T00:00:00.000Z');
+        const old = createTraceDir('old-no-receipt', undefined);
+        const recent = createTraceDir('recent', '2026-05-02T00:00:00.000Z');
+        const oldDate = new Date('2026-04-20T00:00:00.000Z');
+        fs.utimesSync(old, oldDate, oldDate);
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => now,
+            policy: { maxAgeDays: 7, maxCountPerProfile: 20, maxBytesPerProfile: '500MB' },
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([old]);
+        expect(fs.existsSync(old)).toBe(false);
+        expect(fs.existsSync(recent)).toBe(true);
+    });
+    it('does not delete the protected trace exported by the current run', () => {
+        const old = createTraceDir('oldest', '2026-05-01T00:00:00.000Z');
+        const current = createTraceDir('current', '2026-04-01T00:00:00.000Z', 1024);
+        const result = pruneTraceArtifacts(tracesDir, {
+            now: () => Date.parse('2026-05-03T12:00:00.000Z'),
+            policy: { maxAgeDays: 0, maxCountPerProfile: 0, maxBytesPerProfile: 1 },
+            protectedTraceDirs: [current],
+            warn: vi.fn(),
+        });
+        expect(result.deleted).toEqual([old]);
+        expect(fs.existsSync(old)).toBe(false);
+        expect(fs.existsSync(current)).toBe(true);
+    });
+    function createTraceDir(name, createdAt, payloadBytes = 8) {
+        const dir = path.join(tracesDir, name);
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'trace.jsonl'), 'x'.repeat(payloadBytes), 'utf-8');
+        if (createdAt) {
+            fs.writeFileSync(path.join(dir, 'receipt.json'), JSON.stringify({ createdAt }, null, 2), 'utf-8');
+            const date = new Date(createdAt);
+            fs.utimesSync(dir, date, date);
+        }
+        return dir;
+    }
+});
+function directorySize(dir) {
+    let total = 0;
+    for (const name of fs.readdirSync(dir)) {
+        const item = path.join(dir, name);
+        const stat = fs.lstatSync(item);
+        if (stat.isDirectory())
+            total += directorySize(item);
+        else
+            total += stat.size;
+    }
+    return total;
+}

package/dist/src/observation/ring-buffer.d.ts

@@ -0,0 +1,22 @@
+export interface RingBufferOptions {
+    maxAgeMs?: number;
+    maxItems?: number;
+    now?: () => number;
+}
+export declare class RingBuffer<T extends {
+    ts: number;
+}> {
+    private readonly maxAgeMs;
+    private readonly maxItems;
+    private readonly now;
+    private items;
+    constructor(opts?: RingBufferOptions);
+    push(item: T): void;
+    values(opts?: {
+        since?: number;
+        until?: number;
+    }): T[];
+    clear(): void;
+    get size(): number;
+    private prune;
+}

package/dist/src/observation/ring-buffer.js

@@ -0,0 +1,45 @@
+export class RingBuffer {
+    maxAgeMs;
+    maxItems;
+    now;
+    items = [];
+    constructor(opts = {}) {
+        this.maxAgeMs = opts.maxAgeMs ?? 120_000;
+        this.maxItems = opts.maxItems ?? 1_000;
+        this.now = opts.now ?? Date.now;
+    }
+    push(item) {
+        this.items.push(item);
+        this.prune();
+    }
+    values(opts = {}) {
+        this.prune();
+        return this.items.filter((item) => {
+            if (opts.since !== undefined && item.ts < opts.since)
+                return false;
+            if (opts.until !== undefined && item.ts > opts.until)
+                return false;
+            return true;
+        });
+    }
+    clear() {
+        this.items = [];
+    }
+    get size() {
+        this.prune();
+        return this.items.length;
+    }
+    prune() {
+        const minTs = this.now() - this.maxAgeMs;
+        if (this.items.length > this.maxItems) {
+            this.items = this.items.slice(this.items.length - this.maxItems);
+        }
+        if (this.maxAgeMs > 0) {
+            const firstKept = this.items.findIndex((item) => item.ts >= minTs);
+            if (firstKept > 0)
+                this.items = this.items.slice(firstKept);
+            else if (firstKept === -1)
+                this.items = [];
+        }
+    }
+}

package/dist/src/observation/ring-buffer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/observation/ring-buffer.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { RingBuffer } from './ring-buffer.js';
+describe('RingBuffer', () => {
+    it('keeps items in event order and filters by time window', () => {
+        let now = 10_000;
+        const buffer = new RingBuffer({ maxAgeMs: 5_000, now: () => now });
+        buffer.push({ ts: 4_000, value: 'old' });
+        buffer.push({ ts: 7_000, value: 'kept' });
+        buffer.push({ ts: 9_000, value: 'new' });
+        expect(buffer.values().map((item) => item.value)).toEqual(['kept', 'new']);
+        expect(buffer.values({ since: 8_000 }).map((item) => item.value)).toEqual(['new']);
+        now = 13_000;
+        expect(buffer.values().map((item) => item.value)).toEqual(['new']);
+    });
+    it('caps by item count', () => {
+        const buffer = new RingBuffer({ maxItems: 2, maxAgeMs: 100_000, now: () => 10 });
+        buffer.push({ ts: 1, value: 1 });
+        buffer.push({ ts: 2, value: 2 });
+        buffer.push({ ts: 3, value: 3 });
+        expect(buffer.values().map((item) => item.value)).toEqual([2, 3]);
+    });
+});

package/dist/src/observation/session.d.ts

@@ -0,0 +1,25 @@
+import type { ObservationEvent, ObservationEventInput, ObservationScope, ObservationStream } from './events.js';
+export declare const DEFAULT_OBSERVATION_WINDOW_MS = 120000;
+export interface ObservationSessionOptions {
+    id?: string;
+    scope: ObservationScope;
+    windowMs?: number;
+    maxEventsPerStream?: number;
+    now?: () => number;
+}
+export declare class ObservationSession {
+    readonly id: string;
+    readonly scope: ObservationScope;
+    readonly startedAt: number;
+    private readonly now;
+    private counter;
+    private readonly buffers;
+    constructor(opts: ObservationSessionOptions);
+    record(input: ObservationEventInput): ObservationEvent;
+    events(opts?: {
+        stream?: ObservationStream;
+        since?: number;
+        until?: number;
+    }): ObservationEvent[];
+}
+export declare function createTraceId(now?: number | (() => number)): string;

package/dist/src/observation/session.js

@@ -0,0 +1,50 @@
+import { RingBuffer } from './ring-buffer.js';
+import { randomBytes } from 'node:crypto';
+export const DEFAULT_OBSERVATION_WINDOW_MS = 120_000;
+export class ObservationSession {
+    id;
+    scope;
+    startedAt;
+    now;
+    counter = 0;
+    buffers;
+    constructor(opts) {
+        this.id = opts.id ?? createTraceId(opts.now?.() ?? Date.now());
+        this.scope = opts.scope;
+        this.now = opts.now ?? Date.now;
+        this.startedAt = this.now();
+        const bufferOpts = {
+            maxAgeMs: opts.windowMs ?? DEFAULT_OBSERVATION_WINDOW_MS,
+            maxItems: opts.maxEventsPerStream ?? 1_000,
+            now: this.now,
+        };
+        this.buffers = {
+            action: new RingBuffer(bufferOpts),
+            network: new RingBuffer(bufferOpts),
+            console: new RingBuffer(bufferOpts),
+            screenshot: new RingBuffer({ ...bufferOpts, maxItems: Math.min(opts.maxEventsPerStream ?? 50, 50) }),
+            state: new RingBuffer({ ...bufferOpts, maxItems: Math.min(opts.maxEventsPerStream ?? 50, 50) }),
+            error: new RingBuffer(bufferOpts),
+        };
+    }
+    record(input) {
+        const event = {
+            ...input,
+            id: input.id ?? `${this.id}-${++this.counter}`,
+            ts: input.ts ?? this.now(),
+        };
+        this.buffers[event.stream].push(event);
+        return event;
+    }
+    events(opts = {}) {
+        const streams = opts.stream ? [opts.stream] : Object.keys(this.buffers);
+        return streams
+            .flatMap((stream) => this.buffers[stream].values({ since: opts.since, until: opts.until }))
+            .sort((a, b) => a.ts - b.ts || a.id.localeCompare(b.id));
+    }
+}
+export function createTraceId(now = Date.now) {
+    const ts = typeof now === 'function' ? now() : now;
+    const rand = randomBytes(4).toString('hex');
+    return `${new Date(ts).toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)}-${rand}`;
+}

package/dist/src/pipeline/executor.test.js

@@ -9,6 +9,7 @@ function createMockPage(overrides = {}) {
     return {
         goto: vi.fn(),
         evaluate: vi.fn().mockResolvedValue(null),
+        fetchJson: vi.fn().mockResolvedValue(null),
         getCookies: vi.fn().mockResolvedValue([]),
         snapshot: vi.fn().mockResolvedValue(''),
         click: vi.fn(),

package/dist/src/pipeline/steps/download.test.js

@@ -20,6 +20,7 @@ function createMockPage(getCookies) {
     return {
         goto: vi.fn(),
         evaluate: vi.fn().mockResolvedValue(null),
+        fetchJson: vi.fn().mockResolvedValue(null),
         getCookies,
         snapshot: vi.fn().mockResolvedValue(''),
         click: vi.fn(),

package/dist/src/pipeline/steps/fetch.js

@@ -25,27 +25,7 @@ async function fetchSingle(page, url, method, queryParams, headers, args, data)
         }
         return resp.json();
     }
-    const headersJs = JSON.stringify(renderedHeaders);
-    const urlJs = JSON.stringify(finalUrl);
-    const methodJs = JSON.stringify(method.toUpperCase());
-    // Return error status instead of throwing inside evaluate to avoid CDP wrapper
-    // rewriting the message (CDP prepends "Evaluate error: " to thrown errors).
-    const result = await page.evaluate(`
-    async () => {
-      const resp = await fetch(${urlJs}, {
-        method: ${methodJs}, headers: ${headersJs}, credentials: "include"
-      });
-      if (!resp.ok) {
-        return { __httpError: resp.status, statusText: resp.statusText };
-      }
-      return await resp.json();
-    }
-  `);
-    if (result && typeof result === 'object' && '__httpError' in result) {
-        const { __httpError: status, statusText } = result;
-        throw new CliError('FETCH_ERROR', `HTTP ${status} ${statusText} from ${finalUrl}`);
-    }
-    return result;
+    return page.fetchJson(finalUrl, { method: method.toUpperCase(), headers: renderedHeaders });
 }
 /**
  * Batch fetch: send all URLs into the browser as a single evaluate() call.

package/dist/src/pipeline/steps/fetch.test.js

@@ -22,25 +22,19 @@ describe('stepFetch', () => {
         expect(err.message).toBe('HTTP 429 Too Many Requests from https://api.example.com/items');
         expect(jsonMock).not.toHaveBeenCalled();
     });
-    // W1 + W3: browser single fetch returns error status from evaluate, outer code throws CliError
+    // W1 + W3: browser single fetch delegates to page.fetchJson, which owns browser-context fetch errors
     it('throws CliError with FETCH_ERROR code on non-ok responses inside the browser session', async () => {
-        const jsonMock = vi.fn().mockResolvedValue({ error: 'auth required' });
-        const fetchMock = vi.fn().mockResolvedValue({
-            ok: false,
-            status: 401,
-            statusText: 'Unauthorized',
-            json: jsonMock,
-        });
-        vi.stubGlobal('fetch', fetchMock);
-        // Simulate real CDP behavior: evaluate returns a value, errors are thrown outside
         const page = {
-            evaluate: vi.fn(async (js) => Function(`return (${js})`)()()),
+            fetchJson: vi.fn().mockRejectedValue(new CliError('FETCH_ERROR', 'HTTP 401 Unauthorized from https://api.example.com/items')),
         };
         const err = await stepFetch(page, { url: 'https://api.example.com/items' }, null, {}).catch((e) => e);
         expect(err).toBeInstanceOf(CliError);
         expect(err.code).toBe('FETCH_ERROR');
         expect(err.message).toBe('HTTP 401 Unauthorized from https://api.example.com/items');
-        expect(jsonMock).not.toHaveBeenCalled();
+        expect(page.fetchJson).toHaveBeenCalledWith('https://api.example.com/items', {
+            method: 'GET',
+            headers: {},
+        });
     });
     it('returns per-item HTTP errors for batch fetches without a browser session', async () => {
         const jsonMock = vi.fn().mockResolvedValue({ error: 'upstream unavailable' });

package/dist/src/plugin-scaffold.js

@@ -93,7 +93,7 @@ cli({
     { name: 'name', positional: true, required: true, help: 'Name to greet' },
   ],
   columns: ['greeting'],
-  func: async (_page, kwargs) => [{ greeting: \`Hello, \${String(kwargs.name ?? 'World')}!\` }],
+  func: async (kwargs) => [{ greeting: \`Hello, \${String(kwargs.name ?? 'World')}!\` }],
 });
 `;
     writeFile(targetDir, 'greet.ts', tsContent);

package/dist/src/plugin-scaffold.test.js

@@ -59,7 +59,7 @@ describe('createPluginScaffold', () => {
         expect(tsSample).toContain(`import { cli, Strategy } from '@jackwener/opencli/registry';`);
         expect(tsSample).toContain(`strategy: Strategy.PUBLIC`);
         expect(tsSample).toContain(`help: 'Name to greet'`);
-        expect(tsSample).toContain(`func: async (_page, kwargs)`);
+        expect(tsSample).toContain(`func: async (kwargs)`);
         expect(tsSample).not.toContain('async run(');
     });
     it('documents a supported local install flow', () => {