@jackwener/opencli 1.7.8 → 1.7.10

package/clis/36kr/news.js

@@ -12,7 +12,7 @@ cli({
         { name: 'limit', type: 'int', default: 20, help: 'Number of articles (max 50)' },
     ],
     columns: ['rank', 'title', 'summary', 'date', 'url'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         const count = Math.min(kwargs.limit || 20, 50);
         const resp = await fetch('https://www.36kr.com/feed', {
             headers: { 'User-Agent': 'Mozilla/5.0 (compatible; opencli/1.0)' },

package/clis/apple-podcasts/commands.test.js

@@ -24,7 +24,7 @@ describe('apple-podcasts search command', () => {
             }),
         });
         vi.stubGlobal('fetch', fetchMock);
-        const result = await cmd.func(null, {
+        const result = await cmd.func({
             query: 'machine learning',
             keyword: 'sports',
             limit: 5,
@@ -60,7 +60,7 @@ describe('apple-podcasts top command', () => {
             }),
         });
         vi.stubGlobal('fetch', fetchMock);
-        await cmd.func(null, { country: 'US', limit: 1 });
+        await cmd.func({ country: 'US', limit: 1 });
         const [, options] = fetchMock.mock.calls[0] ?? [];
         expect(options).toBeDefined();
         expect(options.signal).toBeDefined();
@@ -81,7 +81,7 @@ describe('apple-podcasts top command', () => {
             }),
         });
         vi.stubGlobal('fetch', fetchMock);
-        const result = await cmd.func(null, { country: 'US', limit: 2 });
+        const result = await cmd.func({ country: 'US', limit: 2 });
         expect(fetchMock).toHaveBeenCalledWith('https://rss.marketingtools.apple.com/api/v2/us/podcasts/top/2/podcasts.json', expect.objectContaining({
             signal: expect.any(Object),
         }));
@@ -94,6 +94,6 @@ describe('apple-podcasts top command', () => {
         const cmd = getRegistry().get('apple-podcasts/top');
         expect(cmd?.func).toBeTypeOf('function');
         vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('socket hang up')));
-        await expect(cmd.func(null, { country: 'us', limit: 3 })).rejects.toThrow('Unable to reach Apple Podcasts charts for US');
+        await expect(cmd.func({ country: 'us', limit: 3 })).rejects.toThrow('Unable to reach Apple Podcasts charts for US');
     });
 });

package/clis/apple-podcasts/episodes.js

@@ -12,7 +12,7 @@ cli({
         { name: 'limit', type: 'int', default: 15, help: 'Max episodes to show' },
     ],
     columns: ['title', 'duration', 'date'],
-    func: async (_page, args) => {
+    func: async (args) => {
         const limit = Math.max(1, Math.min(Number(args.limit), 200));
         // results[0] is the podcast itself; the rest are episodes
         const data = await itunesFetch(`/lookup?id=${args.id}&entity=podcastEpisode&limit=${limit + 1}`);

package/clis/apple-podcasts/search.js

@@ -12,7 +12,7 @@ cli({
         { name: 'limit', type: 'int', default: 10, help: 'Max results' },
     ],
     columns: ['id', 'title', 'author', 'episodes', 'genre', 'url'],
-    func: async (_page, args) => {
+    func: async (args) => {
         const term = encodeURIComponent(args.query);
         const limit = Math.max(1, Math.min(Number(args.limit), 25));
         const data = await itunesFetch(`/search?term=${term}&media=podcast&limit=${limit}`);

package/clis/apple-podcasts/top.js

@@ -14,7 +14,7 @@ cli({
         { name: 'country', default: 'us', help: 'Country code (e.g. us, cn, gb, jp)' },
     ],
     columns: ['rank', 'title', 'author', 'id'],
-    func: async (_page, args) => {
+    func: async (args) => {
         const limit = Math.max(1, Math.min(Number(args.limit), 100));
         const country = String(args.country || 'us').trim().toLowerCase();
         const url = `${CHARTS_URL}/${country}/podcasts/top/${limit}/podcasts.json`;

package/clis/arxiv/paper.js

@@ -11,7 +11,7 @@ cli({
         { name: 'id', positional: true, required: true, help: 'arXiv paper ID (e.g. 1706.03762)' },
     ],
     columns: ['id', 'title', 'authors', 'published', 'abstract', 'url'],
-    func: async (_page, args) => {
+    func: async (args) => {
         const xml = await arxivFetch(`id_list=${encodeURIComponent(args.id)}`);
         const entries = parseEntries(xml);
         if (!entries.length)

package/clis/arxiv/search.js

@@ -12,7 +12,7 @@ cli({
         { name: 'limit', type: 'int', default: 10, help: 'Max results (max 25)' },
     ],
     columns: ['id', 'title', 'authors', 'published', 'url'],
-    func: async (_page, args) => {
+    func: async (args) => {
         const limit = Math.max(1, Math.min(Number(args.limit), 25));
         const query = encodeURIComponent(`all:${args.query}`);
         const xml = await arxivFetch(`search_query=${query}&max_results=${limit}&sortBy=relevance`);

package/clis/band/mentions.js

@@ -1,4 +1,4 @@
-import { AuthRequiredError, EmptyResultError, SelectorError } from '@jackwener/opencli/errors';
+import { AuthRequiredError, EmptyResultError, selectorError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 /**
  * band mentions — Show Band notifications where you were @mentioned.
@@ -52,7 +52,7 @@ cli({
             await page.wait(0.5);
         }
         if (!bellReady) {
-            throw new SelectorError('button._btnWidgetIcon', 'Notification bell not found. The Band.us UI may have changed.');
+            throw selectorError('button._btnWidgetIcon', 'Notification bell not found. The Band.us UI may have changed.');
         }
         // Poll until a capture containing result_data.news arrives, up to maxSecs seconds.
         // getInterceptedRequests() clears the array on each call, so captures are accumulated
@@ -80,7 +80,7 @@ cli({
       return true;
     }`);
         if (!bellClicked) {
-            throw new SelectorError('button._btnWidgetIcon', 'Notification bell disappeared before click. The Band.us UI may have changed.');
+            throw selectorError('button._btnWidgetIcon', 'Notification bell disappeared before click. The Band.us UI may have changed.');
         }
         const requests = await waitForOneCapture();
         // Find the get_news response (has result_data.news); get_news_count responses do not.

package/clis/bbc/news.js

@@ -12,7 +12,7 @@ cli({
         { name: 'limit', type: 'int', default: 20, help: 'Number of headlines (max 50)' },
     ],
     columns: ['rank', 'title', 'description', 'url'],
-    func: async (page, kwargs) => {
+    func: async (kwargs) => {
         const count = Math.min(kwargs.limit || 20, 50);
         const resp = await fetch('https://feeds.bbci.co.uk/news/rss.xml');
         if (!resp.ok)

package/clis/bilibili/subtitle.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { AuthRequiredError, CommandExecutionError, EmptyResultError, SelectorError } from '@jackwener/opencli/errors';
+import { AuthRequiredError, CommandExecutionError, EmptyResultError, selectorError } from '@jackwener/opencli/errors';
 import { apiGet, resolveBvid } from './utils.js';
 cli({
     site: 'bilibili',
@@ -23,7 +23,7 @@ cli({
       return state?.videoData?.cid;
     })()`);
         if (!cid) {
-            throw new SelectorError('videoData.cid', '无法在页面中提取到当前视频的 CID，请检查页面是否正常加载。');
+            throw selectorError('videoData.cid', '无法在页面中提取到当前视频的 CID，请检查页面是否正常加载。');
         }
         // 3. 在 Node 端使用 apiGet 获取带 Wbi 签名的字幕列表
         // 之前纯靠 evaluate 里的 fetch 会失败，因为 B 站 /wbi/ 开头的接口强校验 w_rid，未签名直接被风控返回 403 HTML

package/clis/bloomberg/businessweek.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('businessweek', kwargs.limit ?? 1);
     },
 });

package/clis/bloomberg/economics.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('economics', kwargs.limit ?? 1);
     },
 });

package/clis/bloomberg/industries.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('industries', kwargs.limit ?? 1);
     },
 });

package/clis/bloomberg/main.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('main', kwargs.limit ?? 1);
     },
 });

package/clis/bloomberg/markets.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('markets', kwargs.limit ?? 1);
     },
 });

package/clis/bloomberg/opinions.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('opinions', kwargs.limit ?? 1);
     },
 });

package/clis/bloomberg/politics.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('politics', kwargs.limit ?? 1);
     },
 });

package/clis/bloomberg/tech.js

@@ -11,7 +11,7 @@ cli({
         { name: 'limit', type: 'int', default: 1, help: 'Number of feed items to return (max 20)' },
     ],
     columns: ['title', 'summary', 'link', 'mediaLinks'],
-    func: async (_page, kwargs) => {
+    func: async (kwargs) => {
         return fetchBloombergFeed('tech', kwargs.limit ?? 1);
     },
 });

package/clis/boss/search.js

@@ -2,6 +2,7 @@
  * BOSS直聘 job search — browser cookie API.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
 import { requirePage, navigateTo, bossFetch, verbose } from './utils.js';
 /** City name → BOSS Zhipin city code mapping */
 const CITY_CODES = {
@@ -22,8 +23,16 @@ const CITY_CODES = {
     '香港': '101320100',
 };
 const EXP_MAP = {
-    '不限': '0', '在校/应届': '108', '应届': '108', '1年以内': '101',
-    '1-3年': '102', '3-5年': '103', '5-10年': '104', '10年以上': '105',
+    '不限': '0',
+    '在校/应届': '108',
+    '在校生': '108', '在校': '108',
+    '应届生': '102', '应届': '102',
+    '经验不限': '101',
+    '1年以内': '103',
+    '1-3年': '104',
+    '3-5年': '105',
+    '5-10年': '106',
+    '10年以上': '107',
 };
 const DEGREE_MAP = {
     '不限': '0', '初中及以下': '209', '中专/中技': '208', '高中': '206',
@@ -38,6 +47,10 @@ const INDUSTRY_MAP = {
     '人工智能': '100901', '大数据': '100902', '金融': '100101',
     '教育培训': '100200', '医疗健康': '100300',
 };
+const JOB_TYPE_MAP = {
+    '不限': '0', '全职': '1901', '实习': '1902', '兼职': '1903',
+};
+const JOB_TYPE_CODES = new Set(Object.values(JOB_TYPE_MAP));
 function resolveCity(input) {
     if (!input)
         return '101010100';
@@ -62,35 +75,54 @@ function resolveMap(input, map) {
     }
     return input;
 }
+function resolveJobType(input) {
+    if (!input)
+        return '';
+    if (JOB_TYPE_MAP[input] !== undefined)
+        return JOB_TYPE_MAP[input];
+    if (JOB_TYPE_CODES.has(input))
+        return input;
+    throw new ArgumentError(`Invalid jobType: ${input}`, 'Use one of: 全职, 兼职, 实习, 不限');
+}
+function formatBossOnline(value) {
+    if (value === true)
+        return 'Y';
+    if (value === false)
+        return 'N';
+    return '';
+}
 cli({
     site: 'boss',
     name: 'search',
-    description: 'BOSS直聘搜索职位',
+    description: 'BOSS直聘搜索职位（不带关键词时返回为你推荐职位）',
     domain: 'www.zhipin.com',
     strategy: Strategy.COOKIE,
     navigateBefore: false,
     browser: true,
     args: [
-        { name: 'query', required: true, positional: true, help: 'Search keyword (e.g. AI agent, 前端)' },
+        { name: 'query', positional: true, help: 'Search keyword (optional, empty = recommended jobs)' },
         { name: 'city', default: '北京', help: 'City name or code (e.g. 杭州, 上海, 101010100)' },
-        { name: 'experience', default: '', help: 'Experience: 应届/1年以内/1-3年/3-5年/5-10年/10年以上' },
+        { name: 'experience', default: '', help: 'Experience: 在校生(实习)/应届生(校招)/经验不限/1年以内/1-3年/3-5年/5-10年/10年以上' },
         { name: 'degree', default: '', help: 'Degree: 大专/本科/硕士/博士' },
         { name: 'salary', default: '', help: 'Salary: 3K以下/3-5K/5-10K/10-15K/15-20K/20-30K/30-50K/50K以上' },
         { name: 'industry', default: '', help: 'Industry code or name (e.g. 100020, 互联网)' },
+        { name: 'jobType', default: '', help: 'Job type: 全职/兼职/实习（不传=不限，混合校招与实习）' },
         { name: 'page', type: 'int', default: 1, help: 'Page number' },
         { name: 'limit', type: 'int', default: 15, help: 'Number of results' },
     ],
-    columns: ['name', 'salary', 'company', 'area', 'experience', 'degree', 'skills', 'boss', 'security_id', 'url'],
+    columns: ['name', 'salary', 'company', 'area', 'experience', 'degree', 'skills', 'boss', 'bossOnline', 'security_id', 'url'],
     func: async (page, kwargs) => {
         requirePage(page);
+        const query = String(kwargs.query ?? '').trim();
         const cityCode = resolveCity(kwargs.city);
         verbose('Navigating to set referrer context...');
-        await navigateTo(page, `https://www.zhipin.com/web/geek/job?query=${encodeURIComponent(kwargs.query)}&city=${cityCode}`);
+        await navigateTo(page, `https://www.zhipin.com/web/geek/job?query=${encodeURIComponent(query)}&city=${cityCode}`);
         await new Promise(r => setTimeout(r, 1000));
         const expVal = resolveMap(kwargs.experience, EXP_MAP);
         const degreeVal = resolveMap(kwargs.degree, DEGREE_MAP);
         const salaryVal = resolveMap(kwargs.salary, SALARY_MAP);
         const industryVal = resolveMap(kwargs.industry, INDUSTRY_MAP);
+        const jobTypeVal = resolveJobType(kwargs.jobType);
         const limit = kwargs.limit || 15;
         let currentPage = kwargs.page || 1;
         let allJobs = [];
@@ -101,7 +133,7 @@ cli({
             }
             const qs = new URLSearchParams({
                 scene: '1',
-                query: kwargs.query,
+                query,
                 city: cityCode,
                 page: String(currentPage),
                 pageSize: '15',
@@ -114,6 +146,8 @@ cli({
                 qs.set('salary', salaryVal);
             if (industryVal)
                 qs.set('industry', industryVal);
+            if (jobTypeVal)
+                qs.set('jobType', jobTypeVal);
             const targetUrl = `https://www.zhipin.com/wapi/zpgeek/search/joblist.json?${qs.toString()}`;
             verbose(`Fetching page ${currentPage}... (current jobs: ${allJobs.length})`);
             const data = await bossFetch(page, targetUrl);
@@ -135,6 +169,7 @@ cli({
                     degree: j.jobDegree,
                     skills: (j.skills || []).join(','),
                     boss: j.bossName + ' · ' + j.bossTitle,
+                    bossOnline: formatBossOnline(j.bossOnline),
                     security_id: j.securityId || '',
                     url: 'https://www.zhipin.com/job_detail/' + j.encryptJobId + '.html',
                 });
@@ -153,3 +188,9 @@ cli({
         return allJobs;
     },
 });
+export const __test__ = {
+    EXP_MAP,
+    resolveMap,
+    resolveJobType,
+    formatBossOnline,
+};

package/clis/boss/search.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError } from '@jackwener/opencli/errors';
+import { __test__ } from './search.js';
+import './search.js';
+
+function createPageMock(response) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(response),
+    };
+}
+
+describe('boss search', () => {
+    const command = getRegistry().get('boss/search');
+
+    it('keeps legacy 在校/应届 experience input compatible', () => {
+        expect(__test__.resolveMap('在校/应届', __test__.EXP_MAP)).toBe('108');
+        expect(__test__.resolveMap('应届', __test__.EXP_MAP)).toBe('102');
+    });
+
+    it('fails fast on invalid jobType values', async () => {
+        expect(() => __test__.resolveJobType('外包')).toThrow(ArgumentError);
+    });
+
+    it('accepts supported jobType labels and raw codes', () => {
+        expect(__test__.resolveJobType('全职')).toBe('1901');
+        expect(__test__.resolveJobType('实习')).toBe('1902');
+        expect(__test__.resolveJobType('兼职')).toBe('1903');
+        expect(__test__.resolveJobType('1902')).toBe('1902');
+    });
+
+    it('keeps empty query empty and sends jobType filter to the API', async () => {
+        const page = createPageMock({
+            code: 0,
+            zpData: {
+                hasMore: false,
+                jobList: [
+                    {
+                        encryptJobId: 'abc',
+                        securityId: 'sec',
+                        jobName: '前端开发实习生',
+                        salaryDesc: '150-200/天',
+                        brandName: 'OpenCLI',
+                        cityName: '北京',
+                        areaDistrict: '海淀区',
+                        businessDistrict: '',
+                        jobExperience: '在校/应届',
+                        jobDegree: '本科',
+                        skills: ['JavaScript'],
+                        bossName: '张三',
+                        bossTitle: '技术负责人',
+                        bossOnline: false,
+                    },
+                ],
+            },
+        });
+
+        const rows = await command.func(page, {
+            query: undefined,
+            city: '北京',
+            jobType: '实习',
+            limit: 1,
+            page: 1,
+        });
+
+        expect(page.goto).toHaveBeenCalledWith('https://www.zhipin.com/web/geek/job?query=&city=101010100');
+        const fetchScript = page.evaluate.mock.calls.at(-1)[0];
+        expect(fetchScript).toContain('query=');
+        expect(fetchScript).not.toContain('query=undefined');
+        expect(fetchScript).toContain('jobType=1902');
+        expect(rows[0]).toMatchObject({
+            name: '前端开发实习生',
+            bossOnline: 'N',
+        });
+    });
+});

package/clis/boss/send.js

@@ -6,7 +6,7 @@
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { requirePage, navigateToChat, findFriendByUid, clickCandidateInList, typeAndSendMessage, } from './utils.js';
-import { EmptyResultError, SelectorError } from '@jackwener/opencli/errors';
+import { EmptyResultError, selectorError } from '@jackwener/opencli/errors';
 cli({
     site: 'boss',
     name: 'send',
@@ -30,12 +30,12 @@ cli({
         const friendName = friend.name || '候选人';
         const clicked = await clickCandidateInList(page, numericUid);
         if (!clicked) {
-            throw new SelectorError('聊天列表中的用户', '请确认聊天列表中有此人');
+            throw selectorError('聊天列表中的用户', '请确认聊天列表中有此人');
         }
         await page.wait({ time: 2 });
         const sent = await typeAndSendMessage(page, kwargs.text);
         if (!sent) {
-            throw new SelectorError('消息输入框', '聊天页面 UI 可能已改变');
+            throw selectorError('消息输入框', '聊天页面 UI 可能已改变');
         }
         await page.wait({ time: 1 });
         return [{ status: '✅ 发送成功', detail: `已向 ${friendName} 发送: ${kwargs.text}` }];

package/clis/chatgpt/image.js

@@ -1,7 +1,9 @@
 import * as os from 'node:os';
 import * as path from 'node:path';
+import * as fs from 'node:fs';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { saveBase64ToFile } from '@jackwener/opencli/utils';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { getChatGPTVisibleImageUrls, sendChatGPTMessage, waitForChatGPTImages, getChatGPTImageAssets } from './utils.js';
 
 const CHATGPT_DOMAIN = 'chatgpt.com';
@@ -24,6 +26,22 @@ function displayPath(filePath) {
     return filePath.startsWith(home) ? `~${filePath.slice(home.length)}` : filePath;
 }
 
+export function resolveOutputDir(value) {
+    const raw = String(value || '').trim();
+    if (!raw) return path.join(os.homedir(), 'Pictures', 'chatgpt');
+    if (raw === '~') return os.homedir();
+    if (raw.startsWith('~/')) return path.join(os.homedir(), raw.slice(2));
+    return path.resolve(raw);
+}
+
+export function nextAvailablePath(dir, baseName, ext, existsSync = fs.existsSync) {
+    let candidate = path.join(dir, `${baseName}${ext}`);
+    for (let index = 1; existsSync(candidate); index += 1) {
+        candidate = path.join(dir, `${baseName}_${index}${ext}`);
+    }
+    return candidate;
+}
+
 async function currentChatGPTLink(page) {
     const url = await page.evaluate('window.location.href').catch(() => '');
     return typeof url === 'string' && url ? url : 'https://chatgpt.com';
@@ -41,13 +59,13 @@ export const imageCommand = cli({
     timeoutSeconds: 240,
     args: [
         { name: 'prompt', positional: true, required: true, help: 'Image prompt to send to ChatGPT' },
-        { name: 'op', default: '~/Pictures/chatgpt', help: 'Output directory' },
+        { name: 'op', help: 'Output directory (default: ~/Pictures/chatgpt)' },
         { name: 'sd', type: 'boolean', default: false, help: 'Skip download shorthand; only show ChatGPT link' },
     ],
     columns: ['status', 'file', 'link'],
     func: async (page, kwargs) => {
         const prompt = kwargs.prompt;
-        const outputDir = kwargs.op || path.join(os.homedir(), 'Pictures', 'chatgpt');
+        const outputDir = resolveOutputDir(kwargs.op);
         const skipDownloadRaw = kwargs.sd;
         const skipDownload = skipDownloadRaw === '' || skipDownloadRaw === true || normalizeBooleanFlag(skipDownloadRaw);
         const timeout = 120;
@@ -63,12 +81,23 @@ export const imageCommand = cli({
             return [{ status: '⚠️ send-failed', file: '📁 -', link: `🔗 ${await currentChatGPTLink(page)}` }];
         }
 
-        // Wait for response and images
-        const urls = await waitForChatGPTImages(page, beforeUrls, timeout);
-        const link = await currentChatGPTLink(page);
+        // ChatGPT briefly navigates to /c/{id} after sending, then may
+        // redirect back to the home page. Poll until we capture the /c/ URL.
+        let convUrl = '';
+        for (let ci = 0; ci < 10; ci++) {
+            const url = await currentChatGPTLink(page);
+            if (url.includes('/c/')) { convUrl = url; break; }
+            await page.wait(2);
+        }
+        if (!convUrl) {
+            convUrl = await currentChatGPTLink(page);
+        }
+
+        const urls = await waitForChatGPTImages(page, beforeUrls, timeout, convUrl);
+        const link = convUrl;
 
         if (!urls.length) {
-            return [{ status: '⚠️ no-images', file: '📁 -', link: `🔗 ${link}` }];
+            throw new EmptyResultError('chatgpt image', `No generated images were detected before timeout. Open ${link} and verify whether ChatGPT finished generating the image.`);
         }
 
         if (skipDownload) {
@@ -78,7 +107,7 @@ export const imageCommand = cli({
         // Export and save images
         const assets = await getChatGPTImageAssets(page, urls);
         if (!assets.length) {
-            return [{ status: '⚠️ export-failed', file: '📁 -', link: `🔗 ${link}` }];
+            throw new CommandExecutionError('Failed to export generated ChatGPT image assets', `Open ${link} and verify the generated images are visible, then retry.`);
         }
 
         const stamp = Date.now();
@@ -88,7 +117,7 @@ export const imageCommand = cli({
             const base64 = asset.dataUrl.replace(/^data:[^;]+;base64,/, '');
             const suffix = assets.length > 1 ? `_${index + 1}` : '';
             const ext = extFromMime(asset.mimeType);
-            const filePath = path.join(outputDir, `chatgpt_${stamp}${suffix}${ext}`);
+            const filePath = nextAvailablePath(outputDir, `chatgpt_${stamp}${suffix}`, ext);
             await saveBase64ToFile(base64, filePath);
             results.push({ status: '✅ saved', file: `📁 ${displayPath(filePath)}`, link: `🔗 ${link}` });
         }

package/clis/chatgpt/image.test.js

@@ -0,0 +1,92 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    getChatGPTVisibleImageUrls: vi.fn(),
+    sendChatGPTMessage: vi.fn(),
+    waitForChatGPTImages: vi.fn(),
+    getChatGPTImageAssets: vi.fn(),
+    saveBase64ToFile: vi.fn(),
+}));
+
+vi.mock('./utils.js', () => ({
+    getChatGPTVisibleImageUrls: mocks.getChatGPTVisibleImageUrls,
+    sendChatGPTMessage: mocks.sendChatGPTMessage,
+    waitForChatGPTImages: mocks.waitForChatGPTImages,
+    getChatGPTImageAssets: mocks.getChatGPTImageAssets,
+}));
+
+vi.mock('@jackwener/opencli/utils', () => ({
+    saveBase64ToFile: mocks.saveBase64ToFile,
+}));
+
+const { imageCommand, nextAvailablePath, resolveOutputDir } = await import('./image.js');
+
+function createPage() {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue('https://chatgpt.com/c/test-conversation'),
+    };
+}
+
+beforeEach(() => {
+    vi.restoreAllMocks();
+    mocks.getChatGPTVisibleImageUrls.mockReset().mockResolvedValue([]);
+    mocks.sendChatGPTMessage.mockReset().mockResolvedValue(true);
+    mocks.waitForChatGPTImages.mockReset().mockResolvedValue(['https://images.example/generated.png']);
+    mocks.getChatGPTImageAssets.mockReset().mockResolvedValue([{
+        url: 'https://images.example/generated.png',
+        dataUrl: 'data:image/png;base64,aGVsbG8=',
+        mimeType: 'image/png',
+    }]);
+    mocks.saveBase64ToFile.mockReset().mockResolvedValue(undefined);
+});
+
+describe('chatgpt image output paths', () => {
+    it('expands the default and explicit home-relative output directories', () => {
+        expect(resolveOutputDir()).toBe(path.join(os.homedir(), 'Pictures', 'chatgpt'));
+        expect(resolveOutputDir('~/tmp/chatgpt-images')).toBe(path.join(os.homedir(), 'tmp', 'chatgpt-images'));
+        expect(resolveOutputDir('~')).toBe(os.homedir());
+    });
+
+    it('generates a non-overwriting file path when a timestamp collision exists', () => {
+        const dir = '/tmp/chatgpt';
+        const taken = new Set([
+            path.join(dir, 'chatgpt_123.png'),
+            path.join(dir, 'chatgpt_123_1.png'),
+        ]);
+
+        expect(nextAvailablePath(dir, 'chatgpt_123', '.png', (file) => taken.has(file))).toBe(path.join(dir, 'chatgpt_123_2.png'));
+    });
+});
+
+describe('chatgpt image failure contracts', () => {
+    it('fails fast when image generation detection finds no new images', async () => {
+        mocks.waitForChatGPTImages.mockResolvedValue([]);
+
+        await expect(imageCommand.func(createPage(), {
+            prompt: 'cat',
+            op: '',
+            sd: false,
+        })).rejects.toMatchObject({
+            code: 'EMPTY_RESULT',
+            message: expect.stringContaining('chatgpt image returned no data'),
+            hint: expect.stringContaining('No generated images were detected'),
+        });
+    });
+
+    it('fails fast when generated image assets cannot be exported', async () => {
+        mocks.getChatGPTImageAssets.mockResolvedValue([]);
+
+        await expect(imageCommand.func(createPage(), {
+            prompt: 'cat',
+            op: '',
+            sd: false,
+        })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('Failed to export generated ChatGPT image assets'),
+        });
+    });
+});