fix(adapters): surface empty results as EmptyResultError, not sentinel rows (#1981)

jackwener · codex-mini0 · web-flow · commit 65576221566e · 2026-06-21T15:44:19.000+08:00
* fix(adapters): surface empty results as EmptyResultError, not sentinel rows

Four adapters returned a fabricated row (exit 0) on the not-found/empty
path instead of throwing a typed error, so an agent reading the exit code
or rows could not tell "no results" from success — the framework assigns
EMPTY_RESULT its own exit code precisely so this is detectable:

- maimai/search-talents: returned [{error, query}] on zero candidates.
  Worse, `error`/`query` are not in `columns`, so the message was dropped
  by column projection — the user saw an empty/garbage row, never the
  reason. Now throws EmptyResultError (fixes the silent-column-drop too).
- discord-app/search: returned a synthetic "System" row on no matches.
- pixiv/download: returned a failed sentinel when an illust had 0 pages
  (the file already throws typed errors elsewhere). Test updated to
  assert the throw.
- xiaohongshu/download: returned a failed sentinel when a note had no
  media (the file already throws CliError for the security-block branch).

Per-image partial-failure status rows in the download loops are left
as-is (legitimate batch reporting). Auth-path conversions
(tiktok/facebook string-prefix + maimai in-page throw) are a separate
follow-up since they involve in-page-throw handling.

Adapter suites green; typed-error-lint and silent-column-drop audits
report no new violations.

* fix(adapters): fail closed on malformed empty payloads

* fix(audit): bump undici in lockfile

* fix(pixiv): fail closed on missing pages payload

---------

Co-authored-by: codex-mini0 &lt;codex-mini0@slock.local&gt;
diff --git a/clis/discord-app/commands.test.js b/clis/discord-app/commands.test.js
@@ -5,6 +5,7 @@ import { getRegistry } from '@jackwener/opencli/registry';
 import './channels.js';
 import './goto.js';
 import './read.js';
+import './search.js';
 import './servers.js';
 import './thread-read.js';
 import './threads.js';
@@ -148,6 +149,46 @@ describe('discord-app command registration', () => {
     });
 });
 
+describe('discord-app search', () => {
+    function createSearchPage(bodyText = '', resultRows = []) {
+        return {
+            pressKey: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn(async (script) => {
+                if (script.includes('const input = document.querySelector')) return undefined;
+                if (script.includes('const items = []')) {
+                    const rowsHtml = resultRows.map((row, index) => `
+                      <div class="searchResult_${index}" id="search-result-${index}">
+                        <span class="username">${row.author}</span>
+                        <div id="message-content-${index}">${row.message}</div>
+                      </div>
+                    `).join('');
+                    const dom = new JSDOM(`<!doctype html><body>${bodyText}${rowsHtml}</body>`, {
+                        url: 'https://discord.com/channels/111/222',
+                        runScripts: 'outside-only',
+                    });
+                    return dom.window.eval(script);
+                }
+                throw new Error(`unexpected evaluate script: ${script.slice(0, 80)}`);
+            }),
+        };
+    }
+
+    it('throws EmptyResultError when Discord shows an explicit no-results state', async () => {
+        const cmd = getRegistry().get('discord-app/search');
+        const page = createSearchPage('<div>No results found</div>');
+
+        await expect(cmd.func(page, { query: 'missing' })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('throws CommandExecutionError when result selectors return no rows and no empty-state marker', async () => {
+        const cmd = getRegistry().get('discord-app/search');
+        const page = createSearchPage('<main>search panel changed</main>');
+
+        await expect(cmd.func(page, { query: 'missing' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});
+
 describe('discord-app list row validation', () => {
     it('typed-fails channel rows missing stable channel identity', async () => {
         const page = {
diff --git a/clis/discord-app/search.js b/clis/discord-app/search.js
@@ -1,4 +1,5 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 export const searchCommand = cli({
     site: 'discord-app',
     name: 'search',
@@ -29,7 +30,7 @@ export const searchCommand = cli({
         await page.pressKey('Enter');
         await page.wait(2);
         // Scrape search results
-        const results = await page.evaluate(`
+        const searchState = await page.evaluate(`
       (function() {
         const items = [];
         const resultNodes = document.querySelectorAll('[class*="searchResult_"], [id*="search-result"]');
@@ -44,13 +45,22 @@ export const searchCommand = cli({
           });
         });
         
-        return items;
+        const bodyText = document.body?.innerText || document.body?.textContent || '';
+        const empty = /no results|no messages match|没有结果|无结果/i.test(bodyText);
+        return { items, empty };
       })()
     `);
+        if (!searchState || !Array.isArray(searchState.items)) {
+            throw new CommandExecutionError('Discord search returned malformed browser payload.');
+        }
+        const results = searchState.items;
         // Close search
         await page.pressKey('Escape');
         if (results.length === 0) {
-            return [{ Index: 0, Author: 'System', Message: `No results for "${query}"` }];
+            if (!searchState.empty) {
+                throw new CommandExecutionError('Discord search result selector returned no rows and no explicit empty-state marker.');
+            }
+            throw new EmptyResultError('discord-app search', `No results for "${query}".`);
         }
         return results;
     },
diff --git a/clis/maimai/search-talents.js b/clis/maimai/search-talents.js
@@ -3,6 +3,7 @@
  * Reuses Chrome login session to search for candidates on maimai.cn
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 
 cli({
   site: 'maimai',
@@ -123,11 +124,25 @@ cli({
       return result;
     }`);
 
-    // Extract talent list from response
-    const talentList = data.data?.list || data.data?.talent_list || data.list || data.talent_list || [];
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new CommandExecutionError('Maimai search returned malformed API payload');
+    }
+
+    // Extract talent list from response. Missing list fields mean the API
+    // shape drifted; only an explicit empty array is a true empty result.
+    const talentListCandidates = [
+      data.data?.list,
+      data.data?.talent_list,
+      data.list,
+      data.talent_list,
+    ];
+    const talentList = talentListCandidates.find((value) => Array.isArray(value));
+    if (!talentList) {
+      throw new CommandExecutionError('Maimai search API payload missing talent list');
+    }
 
-    if (!talentList || talentList.length === 0) {
-      return [{ error: '未找到匹配的候选人', query: query }];
+    if (talentList.length === 0) {
+      throw new EmptyResultError('maimai search-talents', `未找到匹配 "${query}" 的候选人`);
     }
 
     // Map to output format
diff --git a/clis/maimai/search-talents.test.js b/clis/maimai/search-talents.test.js
@@ -0,0 +1,29 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './search-talents.js';
+
+function createPageMock(apiPayload) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    waitForTimeout: vi.fn().mockResolvedValue(undefined),
+    getCookies: vi.fn().mockResolvedValue([{ name: 'csrftoken', value: 'csrf' }]),
+    evaluate: vi.fn().mockResolvedValue(apiPayload),
+  };
+}
+
+describe('maimai search-talents', () => {
+  const command = getRegistry().get('maimai/search-talents');
+
+  it('throws EmptyResultError for an explicit empty talent list', async () => {
+    const page = createPageMock({ code: 200, data: { list: [] } });
+
+    await expect(command.func(page, { query: 'Java' })).rejects.toBeInstanceOf(EmptyResultError);
+  });
+
+  it('throws CommandExecutionError when API payload is missing the talent list shape', async () => {
+    const page = createPageMock({ code: 200, data: { items: [] } });
+
+    await expect(command.func(page, { query: 'Java' })).rejects.toBeInstanceOf(CommandExecutionError);
+  });
+});
diff --git a/clis/pixiv/download.js b/clis/pixiv/download.js
@@ -9,7 +9,7 @@ import * as path from 'node:path';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { formatCookieHeader, httpDownload } from '@jackwener/opencli/download';
 import { formatBytes } from '@jackwener/opencli/download/progress';
-import { CommandExecutionError, getErrorMessage } from '@jackwener/opencli/errors';
+import { CommandExecutionError, EmptyResultError, getErrorMessage } from '@jackwener/opencli/errors';
 import { pixivFetch } from './utils.js';
 cli({
     site: 'pixiv',
@@ -32,9 +32,12 @@ cli({
         // pixivFetch handles navigate + error checking; returns the response body directly
         const pages = await pixivFetch(page, `/ajax/illust/${illustId}/pages`, {
             notFoundMsg: `Illustration not found: ${illustId}`,
-        }) || [];
+        });
+        if (!Array.isArray(pages)) {
+            throw new CommandExecutionError('Pixiv pages API returned malformed payload');
+        }
         if (pages.length === 0) {
-            return [{ index: 0, type: '-', status: 'failed', size: 'No images found' }];
+            throw new EmptyResultError('pixiv download', `No images found for illustration ${illustId}.`);
         }
         // Extract cookies for authenticated downloads
         const cookies = formatCookieHeader(await page.getCookies({ domain: 'pixiv.net' }));
diff --git a/clis/pixiv/download.test.js b/clis/pixiv/download.test.js
@@ -1,6 +1,6 @@
 import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
-import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { createPageMock } from '../test-utils.js';
 // Mock download dependencies before importing the adapter
 const { mockHttpDownload, mockMkdirSync } = vi.hoisted(() => ({
@@ -42,10 +42,20 @@ describe('pixiv download', () => {
         const page = createPageMock([{ __httpError: 500 }]);
         await expect(cmd.func(page, { 'illust-id': '12345', output: '/tmp/test' })).rejects.toThrow(CommandExecutionError);
     });
-    it('returns failure when no images found', async () => {
+    it('throws EmptyResultError when no images found', async () => {
         const page = createPageMock([{ body: [] }]);
-        const result = (await cmd.func(page, { 'illust-id': '12345', output: '/tmp/test' }));
-        expect(result).toEqual([{ index: 0, type: '-', status: 'failed', size: 'No images found' }]);
+        await expect(cmd.func(page, { 'illust-id': '12345', output: '/tmp/test' }))
+            .rejects.toThrow(EmptyResultError);
+    });
+    it('throws CommandExecutionError when pages payload is malformed', async () => {
+        const page = createPageMock([{ body: { pages: [] } }]);
+        await expect(cmd.func(page, { 'illust-id': '12345', output: '/tmp/test' }))
+            .rejects.toThrow(CommandExecutionError);
+    });
+    it('throws CommandExecutionError when pages payload is null', async () => {
+        const page = createPageMock([{ body: null }]);
+        await expect(cmd.func(page, { 'illust-id': '12345', output: '/tmp/test' }))
+            .rejects.toThrow(CommandExecutionError);
     });
     it('downloads images with Referer header', async () => {
         mockHttpDownload.mockResolvedValue({ success: true, size: 1024000 });
diff --git a/clis/xiaohongshu/download.js b/clis/xiaohongshu/download.js
@@ -9,7 +9,7 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { formatCookieHeader } from '@jackwener/opencli/download';
 import { downloadMedia } from '@jackwener/opencli/download/media-download';
-import { CliError } from '@jackwener/opencli/errors';
+import { CliError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { buildNoteUrl, parseNoteId } from './note-helpers.js';
 /**
  * Build the media-extraction IIFE. The note id is interpolated as a default
@@ -227,8 +227,11 @@ export const command = cli({
                 ? 'The page may be temporarily restricted. Try again later or from a different session.'
                 : 'Try using a full URL from search results (with xsec_token) instead of a bare note ID.');
         }
-        if (!data || !data.media || data.media.length === 0) {
-            return [{ index: 0, type: '-', status: 'failed', size: 'No media found' }];
+        if (!data || typeof data !== 'object' || !Array.isArray(data.media)) {
+            throw new CommandExecutionError('Xiaohongshu media extraction returned malformed payload.');
+        }
+        if (data.media.length === 0) {
+            throw new EmptyResultError('xiaohongshu download', 'No downloadable media found on this note.');
         }
         // Extract cookies for authenticated downloads
         const cookies = formatCookieHeader(await page.getCookies({ domain: 'xiaohongshu.com' }));
diff --git a/clis/xiaohongshu/download.test.js b/clis/xiaohongshu/download.test.js
@@ -10,6 +10,7 @@ vi.mock('@jackwener/opencli/download', () => ({
     formatCookieHeader: mockFormatCookieHeader,
 }));
 import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { JSDOM } from 'jsdom';
 import './download.js';
 import { buildDownloadExtractJs } from './download.js';
@@ -114,6 +115,28 @@ describe('xiaohongshu download', () => {
         });
         expect(mockDownloadMedia).not.toHaveBeenCalled();
     });
+    it('throws EmptyResultError when extraction returns an explicit empty media array', async () => {
+        const page = createPageMock({
+            noteId: '69bc166f000000001a02069a',
+            media: [],
+        });
+        await expect(command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/explore/69bc166f000000001a02069a?xsec_token=abc',
+            output: './out',
+        })).rejects.toBeInstanceOf(EmptyResultError);
+        expect(mockDownloadMedia).not.toHaveBeenCalled();
+    });
+    it('throws CommandExecutionError when extraction media shape is malformed', async () => {
+        const page = createPageMock({
+            noteId: '69bc166f000000001a02069a',
+            media: { url: 'https://ci.xiaohongshu.com/example.jpg' },
+        });
+        await expect(command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/explore/69bc166f000000001a02069a?xsec_token=abc',
+            output: './out',
+        })).rejects.toBeInstanceOf(CommandExecutionError);
+        expect(mockDownloadMedia).not.toHaveBeenCalled();
+    });
 });
 
 describe('xiaohongshu download buildDownloadExtractJs carousel ordering (JSDOM)', () => {
