@jackwener/opencli 1.7.22 → 1.8.0

package/dist/src/browser/errors.test.js

@@ -32,6 +32,12 @@ describe('classifyBrowserError', () => {
         expect(advice.retryable).toBe(true);
         expect(advice.delayMs).toBe(200);
     });
+    it('classifies CDP -32000 execution-context errors with 200ms delay', () => {
+        const advice = classifyBrowserError(new Error('{"code":-32000,"message":"Cannot find default execution context"}'));
+        expect(advice.kind).toBe('target-navigation');
+        expect(advice.retryable).toBe(true);
+        expect(advice.delayMs).toBe(200);
+    });
     it('returns non-retryable for unrelated errors', () => {
         for (const msg of ['Permission denied', 'malformed exec payload', 'SyntaxError']) {
             const advice = classifyBrowserError(new Error(msg));

package/dist/src/browser/page.js

@@ -22,6 +22,15 @@ function isUnsupportedNetworkCaptureError(err) {
     return (normalized.includes('unknown action') && normalized.includes('network-capture'))
         || (normalized.includes('network capture') && normalized.includes('not supported'));
 }
+// The extension throws "Page not found: <id> — stale page identity" when our cached
+// `_page` targetId no longer maps to a live tab — e.g. the user closed the automation
+// window, or a long-running script left the cache pointing at an evicted target.
+// Detect that signature so goto() can drop the stale id and let resolveTab fall back
+// to the session lease (or create a fresh tab).
+function isStalePageIdentityError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message.includes('stale page identity');
+}
 /**
  * Page — implements IPage by talking to the daemon via HTTP.
  */
@@ -69,10 +78,27 @@ export class Page extends BasePage {
         };
     }
     async goto(url, options) {
-        const result = await sendCommandFull('navigate', {
-            url,
-            ...this._cmdOpts(),
-        });
+        let result;
+        try {
+            result = await sendCommandFull('navigate', {
+                url,
+                ...this._cmdOpts(),
+            });
+        }
+        catch (err) {
+            // If our cached targetId went stale (tab closed externally, identity evicted),
+            // drop the dead id and retry without it — the extension will resolve through the
+            // session lease or open a fresh automation tab. Without this, subsequent
+            // navigations in the same Page instance keep re-sending the same dead targetId
+            // and cascade into "Page not found:" failures.
+            if (!isStalePageIdentityError(err) || this._page === undefined)
+                throw err;
+            this._page = undefined;
+            result = await sendCommandFull('navigate', {
+                url,
+                ...this._cmdOpts(),
+            });
+        }
         // Remember the page identity (targetId) for subsequent calls
         if (result.page) {
             this._page = result.page;

package/dist/src/browser/page.test.js

@@ -235,6 +235,48 @@ describe('Page active target tracking', () => {
             page: 'page-explicit',
         }));
     });
+    // Regression: a Page instance can keep re-sending a cached targetId after the tab
+    // has been closed externally, so the extension throws
+    // "Page not found: <id> — stale page identity" on follow-up navigation.
+    // goto() now drops the stale identity and retries once without it so the extension's
+    // session lease can resolve through to a live tab.
+    it('drops a stale page identity and retries navigate once', async () => {
+        sendCommandFullMock
+            .mockResolvedValueOnce({ data: { url: 'https://example.com/first' }, page: 'page-1' })
+            .mockRejectedValueOnce(new Error('Page not found: deadbeef — stale page identity'))
+            .mockResolvedValueOnce({ data: { url: 'https://example.com/second' }, page: 'page-2' });
+        const page = new Page('site:youtube', undefined, undefined, undefined, 'adapter', 'persistent');
+        await page.goto('https://example.com/first', { waitUntil: 'none' });
+        expect(page.getActivePage()).toBe('page-1');
+        await page.goto('https://example.com/second', { waitUntil: 'none' });
+        expect(page.getActivePage()).toBe('page-2');
+        expect(sendCommandFullMock).toHaveBeenCalledTimes(3);
+        // First retry attempt carried the stale page; the recovery call must drop it.
+        const retryCall = sendCommandFullMock.mock.calls[2];
+        expect(retryCall[0]).toBe('navigate');
+        expect(retryCall[1]).not.toHaveProperty('page');
+    });
+    it('does not retry stale page errors when no identity was cached', async () => {
+        // _page is undefined on a fresh Page — there's nothing to drop, so propagate the
+        // error instead of silently retrying with the same params.
+        sendCommandFullMock
+            .mockRejectedValueOnce(new Error('Page not found: deadbeef — stale page identity'));
+        const page = new Page('site:youtube', undefined, undefined, undefined, 'adapter', 'persistent');
+        await expect(page.goto('https://example.com', { waitUntil: 'none' }))
+            .rejects.toThrow('stale page identity');
+        expect(sendCommandFullMock).toHaveBeenCalledTimes(1);
+    });
+    it('propagates non-stale navigate errors unchanged', async () => {
+        sendCommandFullMock
+            .mockResolvedValueOnce({ data: { url: 'https://example.com/first' }, page: 'page-1' })
+            .mockRejectedValueOnce(new Error('Extension disconnected'));
+        const page = new Page('site:youtube', undefined, undefined, undefined, 'adapter', 'persistent');
+        await page.goto('https://example.com/first', { waitUntil: 'none' });
+        await expect(page.goto('https://example.com/second', { waitUntil: 'none' }))
+            .rejects.toThrow('Extension disconnected');
+        // No retry for unrelated errors — exactly two navigate calls total.
+        expect(sendCommandFullMock).toHaveBeenCalledTimes(2);
+    });
     it('creates a new tab without changing the current active page binding', async () => {
         sendCommandFullMock
             .mockResolvedValueOnce({ data: { url: 'https://first.example' }, page: 'page-1' })

package/dist/src/browser/utils.d.ts

@@ -1,7 +1,7 @@
 /**
  * Utility functions for browser operations
  */
-type EvaluateFunction = (...args: any[]) => unknown;
+type EvaluateFunction = (...args: never[]) => unknown;
 /**
  * Serialize a function-form page.evaluate call for CDP Runtime.evaluate.
  *

package/dist/src/cli-argv-preprocess.d.ts

@@ -35,3 +35,29 @@ export declare function rewriteBrowserArgv(argv: readonly string[]): string[];
 export declare class BrowserSessionArgvError extends Error {
     constructor(message: string);
 }
+/**
+ * Minimal manifest shape consumed by escapeLeadingDashPositional. Imported
+ * lazily by main.ts so this module stays dependency-free.
+ */
+export interface DashPositionalManifestEntry {
+    site: string;
+    name: string;
+    args?: Array<{
+        name: string;
+        positional?: boolean;
+        required?: boolean;
+        valueRequired?: boolean;
+        default?: unknown;
+    }>;
+    browser?: boolean;
+}
+/**
+ * `opencli boss detail -abc123def` fails because commander parses
+ * `-abc123def` as an unknown option rather than the required
+ * `<security-id>` positional. BOSS 直聘 securityId tokens are opaque
+ * strings that can legitimately start with `-` (issue #1160), and the
+ * same shape can show up in any adapter that takes an opaque-id
+ * positional. Insert a `--` separator so commander treats the next
+ * token as the positional value.
+ */
+export declare function escapeLeadingDashPositional(argv: readonly string[], manifest: readonly DashPositionalManifestEntry[]): string[];

package/dist/src/cli-argv-preprocess.js

@@ -129,3 +129,141 @@ export class BrowserSessionArgvError extends Error {
         this.name = 'BrowserSessionArgvError';
     }
 }
+function knownCommandOptions(cmd) {
+    const options = new Map([
+        ['-h', 'none'],
+        ['--help', 'none'],
+        ['-v', 'none'],
+        ['--verbose', 'none'],
+        ['-f', 'required'],
+        ['--format', 'required'],
+        ['--trace', 'required'],
+    ]);
+    if (cmd.browser) {
+        options.set('--window', 'required');
+        options.set('--site-session', 'required');
+        options.set('--keep-tab', 'required');
+    }
+    for (const arg of cmd.args ?? []) {
+        if (arg.positional)
+            continue;
+        // Keep in sync with commanderAdapter.ts:
+        // required/valueRequired -> `<value>`; otherwise -> `[value]`.
+        options.set(`--${arg.name}`, arg.required || arg.valueRequired ? 'required' : 'optional');
+    }
+    return options;
+}
+function consumeKnownOption(argv, index, options) {
+    const token = argv[index];
+    if (!token || token === '--')
+        return null;
+    const eq = token.indexOf('=');
+    const key = eq === -1 ? token : token.slice(0, eq);
+    const mode = options.get(key);
+    if (!mode && eq === -1 && token.startsWith('-') && !token.startsWith('--') && token.length > 2) {
+        const shortKey = token.slice(0, 2);
+        const shortMode = options.get(shortKey);
+        if (shortMode === 'required') {
+            return { values: [token], nextIndex: index + 1 };
+        }
+    }
+    if (!mode)
+        return null;
+    if (eq !== -1 || mode === 'none')
+        return { values: [token], nextIndex: index + 1 };
+    const next = argv[index + 1];
+    if (mode === 'required') {
+        return next === undefined
+            ? { values: [token], nextIndex: index + 1 }
+            : { values: [token, next], nextIndex: index + 2 };
+    }
+    if (next !== undefined && !next.startsWith('-')) {
+        return { values: [token, next], nextIndex: index + 2 };
+    }
+    return { values: [token], nextIndex: index + 1 };
+}
+/**
+ * `opencli boss detail -abc123def` fails because commander parses
+ * `-abc123def` as an unknown option rather than the required
+ * `<security-id>` positional. BOSS 直聘 securityId tokens are opaque
+ * strings that can legitimately start with `-` (issue #1160), and the
+ * same shape can show up in any adapter that takes an opaque-id
+ * positional. Insert a `--` separator so commander treats the next
+ * token as the positional value.
+ */
+export function escapeLeadingDashPositional(argv, manifest) {
+    const result = [...argv];
+    const requiredFirstPositional = new Map();
+    for (const cmd of manifest) {
+        const first = cmd.args?.find((a) => a.positional);
+        if (first?.required)
+            requiredFirstPositional.set(cmd.site + '/' + cmd.name, cmd);
+    }
+    let i = 0;
+    while (i < result.length) {
+        const tok = result[i];
+        if (!tok.startsWith('-'))
+            break;
+        if (tok.includes('=')) {
+            i += 1;
+            continue;
+        }
+        if (ROOT_VALUE_FLAGS.has(tok) && i + 1 < result.length) {
+            i += 2;
+        }
+        else {
+            i += 1;
+        }
+    }
+    const site = result[i];
+    const cmd = result[i + 1];
+    const positionalIdx = i + 2;
+    if (!site || !cmd || positionalIdx >= result.length)
+        return result;
+    const entry = requiredFirstPositional.get(site + '/' + cmd);
+    if (!entry)
+        return result;
+    const options = knownCommandOptions(entry);
+    const beforePositional = [];
+    let j = positionalIdx;
+    while (j < result.length) {
+        const token = result[j];
+        if (token === '--')
+            return result;
+        const consumed = consumeKnownOption(result, j, options);
+        if (consumed) {
+            beforePositional.push(...consumed.values);
+            j = consumed.nextIndex;
+            continue;
+        }
+        if (!token.startsWith('-'))
+            return result;
+        if (token.startsWith('--'))
+            return result;
+        break;
+    }
+    if (j >= result.length)
+        return result;
+    const positional = result[j];
+    const trailingOptions = [];
+    const trailingRest = [];
+    j += 1;
+    while (j < result.length) {
+        const consumed = consumeKnownOption(result, j, options);
+        if (consumed) {
+            trailingOptions.push(...consumed.values);
+            j = consumed.nextIndex;
+            continue;
+        }
+        trailingRest.push(result[j]);
+        j += 1;
+    }
+    return [
+        ...result.slice(0, positionalIdx),
+        ...beforePositional,
+        ...trailingOptions,
+        '--',
+        positional,
+        ...trailingRest,
+    ];
+}

package/dist/src/cli-argv-preprocess.test.js

@@ -128,3 +128,82 @@ describe('rewriteBrowserArgv', () => {
         }
     });
 });
+import { escapeLeadingDashPositional } from './cli-argv-preprocess.js';
+describe('escapeLeadingDashPositional', () => {
+    const manifest = [
+        { site: 'boss', name: 'detail', browser: true, args: [{ name: 'security-id', positional: true, required: true }, { name: 'retry', positional: false, valueRequired: true }] },
+        { site: 'boss', name: 'search', args: [{ name: 'query', positional: true, required: false }, { name: 'limit', positional: false }] },
+        { site: 'twitter', name: 'follow', args: [{ name: 'username', positional: true, required: true }] },
+        { site: 'twitter', name: 'lists', args: [{ name: 'limit', positional: false }] },
+    ];
+    it('inserts -- before a required positional starting with `-`', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-abc123def'], manifest))
+            .toEqual(['boss', 'detail', '--', '-abc123def']);
+    });
+    it('preserves trailing flags after the dash-leading positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-xyz', '-f', 'json'], manifest))
+            .toEqual(['boss', 'detail', '-f', 'json', '--', '-xyz']);
+    });
+    it('preserves attached short option values like commander does', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-fjson', '-xyz'], manifest))
+            .toEqual(['boss', 'detail', '-fjson', '--', '-xyz']);
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-xyz', '-fjson'], manifest))
+            .toEqual(['boss', 'detail', '-fjson', '--', '-xyz']);
+    });
+    it('handles known options before a dash-leading positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--format', 'json', '--trace=on', '-xyz'], manifest))
+            .toEqual(['boss', 'detail', '--format', 'json', '--trace=on', '--', '-xyz']);
+    });
+    it('keeps adapter and browser options parseable when they follow the positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-xyz', '--retry', '2', '--window', 'foreground'], manifest))
+            .toEqual(['boss', 'detail', '--retry', '2', '--window', 'foreground', '--', '-xyz']);
+    });
+    it('protects negative numeric positionals too', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-42'], manifest))
+            .toEqual(['boss', 'detail', '--', '-42']);
+    });
+    it('leaves unknown dash options untouched instead of hiding them behind --', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--unknown', 'value'], manifest))
+            .toEqual(['boss', 'detail', '--unknown', 'value']);
+    });
+    it('does not touch positional values that do not start with -', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', 'normal-id'], manifest))
+            .toEqual(['boss', 'detail', 'normal-id']);
+    });
+    it('does not touch the recognised short flags -f / -v / -h', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-f', 'json'], manifest))
+            .toEqual(['boss', 'detail', '-f', 'json']);
+        expect(escapeLeadingDashPositional(['boss', 'detail', '-v'], manifest))
+            .toEqual(['boss', 'detail', '-v']);
+    });
+    it('does not touch long flags (--*)', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--format', 'json'], manifest))
+            .toEqual(['boss', 'detail', '--format', 'json']);
+    });
+    it('does not touch already-escaped --', () => {
+        expect(escapeLeadingDashPositional(['boss', 'detail', '--', '-already-escaped'], manifest))
+            .toEqual(['boss', 'detail', '--', '-already-escaped']);
+    });
+    it('does not touch commands without a required positional', () => {
+        expect(escapeLeadingDashPositional(['boss', 'search', '-something'], manifest))
+            .toEqual(['boss', 'search', '-something']);
+        expect(escapeLeadingDashPositional(['twitter', 'lists', '-something'], manifest))
+            .toEqual(['twitter', 'lists', '-something']);
+    });
+    it('works when --profile or another root flag precedes the site', () => {
+        expect(escapeLeadingDashPositional(['--profile', 'work', 'boss', 'detail', '-abc'], manifest))
+            .toEqual(['--profile', 'work', 'boss', 'detail', '--', '-abc']);
+    });
+    it('works for any adapter, not just boss', () => {
+        expect(escapeLeadingDashPositional(['twitter', 'follow', '-someuser'], manifest))
+            .toEqual(['twitter', 'follow', '--', '-someuser']);
+    });
+    it('returns argv unchanged when the command is unknown', () => {
+        expect(escapeLeadingDashPositional(['unknown', 'cmd', '-arg'], manifest))
+            .toEqual(['unknown', 'cmd', '-arg']);
+    });
+    it('returns argv unchanged when argv is too short', () => {
+        expect(escapeLeadingDashPositional(['boss'], manifest)).toEqual(['boss']);
+        expect(escapeLeadingDashPositional(['boss', 'detail'], manifest)).toEqual(['boss', 'detail']);
+    });
+});

package/dist/src/convention-audit.js

@@ -246,19 +246,26 @@ function auditTypedErrorPatterns(command, source, sourcePath, projectRoot) {
         }
         const sentinel = /(?:\?\?|\|\|)\s*(['"])(unknown|Unknown|UNKNOWN|N\/A|n\/a|NA|未知|-)\1/.exec(line);
         if (sentinel) {
-            violations.push({
-                rule: 'silent-sentinel',
-                ...command,
-                file: relative,
-                line: index + 1,
-                message: `sentinel fallback ${sentinel[0].trim()} can turn missing data into fake data; prefer dropping the field or throwing a typed error`,
-                details: { text: line.trim() },
-            });
+            if (!isThrowMessageLine(line)) {
+                violations.push({
+                    rule: 'silent-sentinel',
+                    ...command,
+                    file: relative,
+                    line: index + 1,
+                    message: `sentinel fallback ${sentinel[0].trim()} can turn missing data into fake data; prefer dropping the field or throwing a typed error`,
+                    details: { text: line.trim() },
+                });
+            }
         }
         offset += line.length + 1;
     });
     return dedupeViolations(violations);
 }
+function isThrowMessageLine(line) {
+    // Only single-line `throw new X(...)` diagnostics are ignored. Multi-line
+    // throw expressions with row-like sentinel fallbacks still stay visible.
+    return /\bthrow\s+new\b/.test(line);
+}
 function auditWriteDeletePair(entries) {
     const bySite = new Map();
     for (const entry of entries) {

package/dist/src/convention-audit.test.js

@@ -223,4 +223,25 @@ describe('convention audit', () => {
         const violations = report.categories.find((item) => item.rule === 'silent-empty-fallback').violations;
         expect(violations.map((violation) => violation.command)).toEqual(['demo/catch']);
     });
+    it('does not report sentinel fallbacks inside thrown error messages', () => {
+        const root = makeProject([
+            { site: 'demo', name: 'error', access: 'read', columns: ['id'], sourceFile: 'demo/error.js' },
+            { site: 'demo', name: 'row', access: 'read', columns: ['id', 'title'], sourceFile: 'demo/row.js' },
+        ], {
+            'demo/error.js': `
+        export async function run(data) {
+          if (!data.ok) throw new Error(\`demo failed: \${data.message ?? 'unknown'}\`);
+          return [{ id: 1 }];
+        }
+      `,
+            'demo/row.js': `
+        export async function run(item) {
+          return [{ id: item.id, title: item.title ?? 'unknown' }];
+        }
+      `,
+        });
+        const report = runConventionAudit({ projectRoot: root });
+        const violations = report.categories.find((item) => item.rule === 'silent-sentinel').violations;
+        expect(violations.map((violation) => violation.command)).toEqual(['demo/row']);
+    });
 });

package/dist/src/download/media-download.js

@@ -9,7 +9,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getErrorMessage } from '../errors.js';
-import { httpDownload, ytdlpDownload, checkYtdlp, getTempDir, exportCookiesToNetscape, } from './index.js';
+import { httpDownload, ytdlpDownload, checkYtdlp, getTempDir, exportCookiesToNetscape, sanitizeFilename, } from './index.js';
 import { DownloadProgressTracker, formatBytes } from './progress.js';
 // ============================================================
 // Main API
@@ -50,7 +50,7 @@ export async function downloadMedia(items, options) {
             const media = items[i];
             const isVideo = media.type !== 'image';
             const ext = isVideo ? 'mp4' : 'jpg';
-            const filename = media.filename || `${filenamePrefix}_${i + 1}.${ext}`;
+            const filename = resolveMediaFilename(media.filename, filenamePrefix, i + 1, ext);
             const destPath = path.join(outputDir, filename);
             const progressBar = tracker.onFileStart(filename, i);
             try {
@@ -112,3 +112,16 @@ export async function downloadMedia(items, options) {
     }
     return results;
 }
+function resolveMediaFilename(filename, prefix, index, ext) {
+    const safePrefix = sanitizePathSegment(path.basename(path.win32.basename(prefix))) || 'download';
+    const fallback = `${safePrefix}_${index}.${ext}`;
+    if (!filename)
+        return fallback;
+    const basename = path.basename(path.win32.basename(filename));
+    const safeName = sanitizePathSegment(basename);
+    return safeName || fallback;
+}
+function sanitizePathSegment(value) {
+    const sanitized = sanitizeFilename(value);
+    return sanitized && sanitized !== '.' && sanitized !== '..' ? sanitized : '';
+}

package/dist/src/download/media-download.test.d.ts

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

package/dist/src/download/media-download.test.js

@@ -0,0 +1,110 @@
+import * as fs from 'node:fs';
+import * as http from 'node:http';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { downloadMedia } from './media-download.js';
+const servers = [];
+const tempDirs = [];
+afterEach(async () => {
+    await Promise.all(servers.map((server) => new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    })));
+    servers.length = 0;
+    for (const dir of tempDirs) {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+    }
+    tempDirs.length = 0;
+});
+async function startServer(handler) {
+    const server = http.createServer(handler);
+    servers.push(server);
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Failed to start test server');
+    }
+    return `http://127.0.0.1:${address.port}`;
+}
+describe('media downloads', () => {
+    it('keeps custom filenames inside the output directory', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 200;
+            res.end('image');
+        });
+        const parentDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-media-parent-'));
+        tempDirs.push(parentDir);
+        const outputDir = path.join(parentDir, 'downloads');
+        const results = await downloadMedia([
+            { type: 'image', url: `${baseUrl}/image.jpg`, filename: '../escape.jpg' },
+        ], {
+            output: outputDir,
+            verbose: false,
+        });
+        expect(results).toEqual([
+            { index: 1, type: 'image', status: 'success', size: '5.0 B' },
+        ]);
+        expect(fs.readFileSync(path.join(outputDir, 'escape.jpg'), 'utf8')).toBe('image');
+        expect(fs.existsSync(path.join(parentDir, 'escape.jpg'))).toBe(false);
+    });
+    it('strips nested and absolute path components from custom filenames', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 200;
+            res.end('image');
+        });
+        const parentDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-media-parent-'));
+        tempDirs.push(parentDir);
+        const outputDir = path.join(parentDir, 'downloads');
+        const results = await downloadMedia([
+            { type: 'image', url: `${baseUrl}/one.jpg`, filename: '../../etc/passwd' },
+            { type: 'image', url: `${baseUrl}/two.jpg`, filename: '/tmp/evil.jpg' },
+            { type: 'image', url: `${baseUrl}/three.jpg`, filename: 'nested/path/photo.png' },
+            { type: 'image', url: `${baseUrl}/four.jpg`, filename: '..\\windows\\escape.jpg' },
+        ], {
+            output: outputDir,
+            verbose: false,
+        });
+        expect(results).toEqual([
+            { index: 1, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 2, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 3, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 4, type: 'image', status: 'success', size: '5.0 B' },
+        ]);
+        expect(fs.readFileSync(path.join(outputDir, 'passwd'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'evil.jpg'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'photo.png'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'escape.jpg'), 'utf8')).toBe('image');
+        expect(fs.existsSync(path.join(parentDir, 'etc', 'passwd'))).toBe(false);
+        expect(fs.existsSync(path.join(parentDir, 'tmp', 'evil.jpg'))).toBe(false);
+    });
+    it('falls back to generated names for empty dot-directory filenames', async () => {
+        const baseUrl = await startServer((_req, res) => {
+            res.statusCode = 200;
+            res.end('image');
+        });
+        const parentDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'opencli-media-parent-'));
+        tempDirs.push(parentDir);
+        const outputDir = path.join(parentDir, 'downloads');
+        const results = await downloadMedia([
+            { type: 'image', url: `${baseUrl}/dot.jpg`, filename: '.' },
+            { type: 'image', url: `${baseUrl}/dotdot.jpg`, filename: '..' },
+            { type: 'image', url: `${baseUrl}/blank.jpg`, filename: '   ' },
+        ], {
+            output: outputDir,
+            filenamePrefix: '../unsafe prefix',
+            verbose: false,
+        });
+        expect(results).toEqual([
+            { index: 1, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 2, type: 'image', status: 'success', size: '5.0 B' },
+            { index: 3, type: 'image', status: 'success', size: '5.0 B' },
+        ]);
+        expect(fs.readFileSync(path.join(outputDir, 'unsafe_prefix_1.jpg'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'unsafe_prefix_2.jpg'), 'utf8')).toBe('image');
+        expect(fs.readFileSync(path.join(outputDir, 'unsafe_prefix_3.jpg'), 'utf8')).toBe('image');
+        expect(fs.existsSync(path.join(parentDir, 'unsafe prefix_1.jpg'))).toBe(false);
+    });
+});

package/dist/src/electron-apps.js

@@ -10,7 +10,7 @@ import * as os from 'node:os';
 import yaml from 'js-yaml';
 export const builtinApps = {
     cursor: { port: 9226, processName: 'Cursor', bundleId: 'com.todesktop.runtime.Cursor', displayName: 'Cursor' },
-    codex: { port: 9222, processName: 'Codex', bundleId: 'com.openai.codex', displayName: 'Codex' },
+    codex: { port: 9238, processName: 'Codex', bundleId: 'com.openai.codex', displayName: 'Codex' },
     chatwise: { port: 9228, processName: 'ChatWise', bundleId: 'com.chatwise.app', displayName: 'ChatWise' },
     'discord-app': { port: 9232, processName: 'Discord', bundleId: 'com.discord.app', displayName: 'Discord' },
     'doubao-app': { port: 9225, processName: 'Doubao', bundleId: 'com.volcengine.doubao', displayName: 'Doubao' },

package/dist/src/electron-apps.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { getElectronApp, isElectronApp, loadApps } from './electron-apps.js';
+import { builtinApps, getElectronApp, isElectronApp, loadApps } from './electron-apps.js';
 describe('electron-apps registry', () => {
     it('returns builtin app entry for cursor', () => {
         const app = getElectronApp('cursor');
@@ -10,7 +10,12 @@ describe('electron-apps registry', () => {
     it('returns builtin app entry for codex', () => {
         const app = getElectronApp('codex');
         expect(app).toBeDefined();
-        expect(app.port).toBe(9222);
+        expect(app.port).toBe(9238);
+    });
+    it('keeps builtin Electron app CDP ports unique and off the browser-bridge port', () => {
+        const ports = Object.values(builtinApps).map((app) => app.port);
+        expect(new Set(ports).size).toBe(ports.length);
+        expect(ports).not.toContain(9222);
     });
     it('returns undefined for non-Electron sites', () => {
         expect(getElectronApp('bilibili')).toBeUndefined();

package/dist/src/errors.d.ts

@@ -72,6 +72,23 @@ export declare function selectorError(selector: string, hint?: string): CliError
 export declare class PluginError extends CliError {
     constructor(message: string, hint?: string);
 }
+/**
+ * Thrown when a JSON endpoint returns HTML instead of JSON — typically a login
+ * wall, rate-limit page, or WAF challenge. Surfaced as a structured error so
+ * callers can show "re-login or wait out the rate limit" guidance instead of
+ * the cryptic `SyntaxError: Unexpected token '<', "<!DOCTYPE "...` that a naive
+ * JSON.parse on an HTML body produces.
+ *
+ * `bodyPreview` is the first 100 chars of the response body (after trimming
+ * leading whitespace) — useful for logs / debugging without dumping the full
+ * page.
+ */
+export declare class LoginWallError extends CliError {
+    readonly status: number;
+    readonly url: string;
+    readonly bodyPreview: string;
+    constructor(message: string, status: number, url: string, bodyPreview: string, hint?: string);
+}
 /** Structured error output — unified contract for all consumers (AI agents, scripts, humans). */
 export interface ErrorEnvelope {
     ok: false;