@jackwener/opencli 1.5.6 → 1.5.7

package/src/clis/xiaohongshu/note.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { IPage } from '../../types.js';
+import { getRegistry } from '../../registry.js';
+import { parseNoteId, buildNoteUrl } from './note-helpers.js';
+import './note.js';
+
+function createPageMock(evaluateResult: any): IPage {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    snapshot: vi.fn().mockResolvedValue(undefined),
+    click: vi.fn().mockResolvedValue(undefined),
+    typeText: vi.fn().mockResolvedValue(undefined),
+    pressKey: vi.fn().mockResolvedValue(undefined),
+    scrollTo: vi.fn().mockResolvedValue(undefined),
+    getFormState: vi.fn().mockResolvedValue({ forms: [], orphanFields: [] }),
+    wait: vi.fn().mockResolvedValue(undefined),
+    tabs: vi.fn().mockResolvedValue([]),
+    closeTab: vi.fn().mockResolvedValue(undefined),
+    newTab: vi.fn().mockResolvedValue(undefined),
+    selectTab: vi.fn().mockResolvedValue(undefined),
+    networkRequests: vi.fn().mockResolvedValue([]),
+    consoleMessages: vi.fn().mockResolvedValue([]),
+    scroll: vi.fn().mockResolvedValue(undefined),
+    autoScroll: vi.fn().mockResolvedValue(undefined),
+    installInterceptor: vi.fn().mockResolvedValue(undefined),
+    getInterceptedRequests: vi.fn().mockResolvedValue([]),
+    getCookies: vi.fn().mockResolvedValue([]),
+    screenshot: vi.fn().mockResolvedValue(''),
+    waitForCapture: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe('parseNoteId', () => {
+  it('extracts ID from /explore/ URL', () => {
+    expect(parseNoteId('https://www.xiaohongshu.com/explore/69c131c9000000002800be4c')).toBe('69c131c9000000002800be4c');
+  });
+
+  it('extracts ID from /search_result/ URL with query params', () => {
+    expect(parseNoteId('https://www.xiaohongshu.com/search_result/69c131c9000000002800be4c?xsec_token=abc')).toBe('69c131c9000000002800be4c');
+  });
+
+  it('extracts ID from /note/ URL', () => {
+    expect(parseNoteId('https://www.xiaohongshu.com/note/69c131c9000000002800be4c')).toBe('69c131c9000000002800be4c');
+  });
+
+  it('returns raw string when no URL pattern matches', () => {
+    expect(parseNoteId('69c131c9000000002800be4c')).toBe('69c131c9000000002800be4c');
+  });
+
+  it('trims whitespace', () => {
+    expect(parseNoteId('  69c131c9000000002800be4c  ')).toBe('69c131c9000000002800be4c');
+  });
+});
+
+describe('buildNoteUrl', () => {
+  it('returns full URL as-is when given https URL', () => {
+    const url = 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok';
+    expect(buildNoteUrl(url)).toBe(url);
+  });
+
+  it('constructs /explore/ URL for bare note ID', () => {
+    expect(buildNoteUrl('abc123')).toBe('https://www.xiaohongshu.com/explore/abc123');
+  });
+});
+
+describe('xiaohongshu note', () => {
+  const command = getRegistry().get('xiaohongshu/note');
+
+  it('is registered', () => {
+    expect(command).toBeDefined();
+    expect(command!.func).toBeTypeOf('function');
+  });
+
+  it('returns note content as field/value rows', async () => {
+    const page = createPageMock({
+      loginWall: false,
+      notFound: false,
+      title: '尚界Z7实车体验',
+      desc: '今天去看了实车，外观很帅',
+      author: '小红薯用户',
+      likes: '257',
+      collects: '98',
+      comments: '45',
+      tags: ['#尚界Z7', '#鸿蒙智行'],
+    });
+
+    const result = (await command!.func!(page, { 'note-id': '69c131c9000000002800be4c' })) as any[];
+
+    expect((page.goto as any).mock.calls[0][0]).toContain('/explore/69c131c9000000002800be4c');
+    expect(result).toEqual([
+      { field: 'title', value: '尚界Z7实车体验' },
+      { field: 'author', value: '小红薯用户' },
+      { field: 'content', value: '今天去看了实车，外观很帅' },
+      { field: 'likes', value: '257' },
+      { field: 'collects', value: '98' },
+      { field: 'comments', value: '45' },
+      { field: 'tags', value: '#尚界Z7, #鸿蒙智行' },
+    ]);
+  });
+
+  it('parses note ID from full /explore/ URL', async () => {
+    const page = createPageMock({
+      loginWall: false, notFound: false,
+      title: 'Test', desc: '', author: '', likes: '0', collects: '0', comments: '0', tags: [],
+    });
+
+    await command!.func!(page, {
+      'note-id': 'https://www.xiaohongshu.com/explore/69c131c9000000002800be4c?xsec_token=abc',
+    });
+
+    expect((page.goto as any).mock.calls[0][0]).toContain('/explore/69c131c9000000002800be4c');
+  });
+
+  it('preserves full search_result URL with xsec_token for navigation', async () => {
+    const page = createPageMock({
+      loginWall: false, notFound: false,
+      title: 'Test', desc: '', author: '', likes: '0', collects: '0', comments: '0', tags: [],
+    });
+
+    const fullUrl = 'https://www.xiaohongshu.com/search_result/69c131c9000000002800be4c?xsec_token=abc';
+    await command!.func!(page, { 'note-id': fullUrl });
+
+    // Should navigate to the full URL as-is, not strip the token
+    expect((page.goto as any).mock.calls[0][0]).toBe(fullUrl);
+  });
+
+  it('throws AuthRequiredError on login wall', async () => {
+    const page = createPageMock({ loginWall: true, notFound: false });
+
+    await expect(command!.func!(page, { 'note-id': 'abc123' })).rejects.toThrow('Note content requires login');
+  });
+
+  it('throws EmptyResultError when note is not found', async () => {
+    const page = createPageMock({ loginWall: false, notFound: true });
+
+    await expect(command!.func!(page, { 'note-id': 'abc123' })).rejects.toThrow('returned no data');
+  });
+
+  it('normalizes placeholder text to 0 for zero-count metrics', async () => {
+    const page = createPageMock({
+      loginWall: false, notFound: false,
+      title: 'New note', desc: 'Just posted', author: 'Author',
+      likes: '赞', collects: '收藏', comments: '评论', tags: [],
+    });
+
+    const result = (await command!.func!(page, { 'note-id': 'abc123' })) as any[];
+    expect(result.find((r: any) => r.field === 'likes')!.value).toBe('0');
+    expect(result.find((r: any) => r.field === 'collects')!.value).toBe('0');
+    expect(result.find((r: any) => r.field === 'comments')!.value).toBe('0');
+  });
+
+  it('omits tags row when no tags present', async () => {
+    const page = createPageMock({
+      loginWall: false, notFound: false,
+      title: 'No tags', desc: 'Content', author: 'Author',
+      likes: '1', collects: '2', comments: '3', tags: [],
+    });
+
+    const result = (await command!.func!(page, { 'note-id': 'abc123' })) as any[];
+    expect(result.find((r: any) => r.field === 'tags')).toBeUndefined();
+    expect(result).toHaveLength(6);
+  });
+});

package/src/clis/xiaohongshu/note.ts

@@ -0,0 +1,86 @@
+/**
+ * Xiaohongshu note — read full note content from a public note page.
+ *
+ * Extracts title, author, description text, and engagement metrics
+ * (likes, collects, comment count) via DOM extraction.
+ */
+
+import { cli, Strategy } from '../../registry.js';
+import { AuthRequiredError, EmptyResultError } from '../../errors.js';
+import { parseNoteId, buildNoteUrl } from './note-helpers.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'note',
+  description: '获取小红书笔记正文和互动数据',
+  domain: 'www.xiaohongshu.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'note-id', required: true, positional: true, help: 'Note ID or full URL (preserves xsec_token for access)' },
+  ],
+  columns: ['field', 'value'],
+  func: async (page, kwargs) => {
+    const raw = String(kwargs['note-id']);
+    const noteId = parseNoteId(raw);
+    const url = buildNoteUrl(raw);
+
+    await page.goto(url);
+    await page.wait(3);
+
+    const data = await page.evaluate(`
+      (() => {
+        const loginWall = /登录后查看|请登录/.test(document.body.innerText || '')
+        const notFound = /页面不见了|笔记不存在|无法浏览/.test(document.body.innerText || '')
+
+        const clean = (el) => (el?.textContent || '').replace(/\\s+/g, ' ').trim()
+
+        const title = clean(document.querySelector('#detail-title, .title'))
+        const desc = clean(document.querySelector('#detail-desc, .desc, .note-text'))
+        const author = clean(document.querySelector('.username, .author-wrapper .name'))
+        const likes = clean(document.querySelector('.like-wrapper .count'))
+        const collects = clean(document.querySelector('.collect-wrapper .count'))
+        const comments = clean(document.querySelector('.chat-wrapper .count'))
+
+        // Try to extract tags/topics
+        const tags = []
+        document.querySelectorAll('#detail-desc a.tag, #detail-desc a[href*="search_result"]').forEach(el => {
+          const t = (el.textContent || '').trim()
+          if (t) tags.push(t)
+        })
+
+        return { loginWall, notFound, title, desc, author, likes, collects, comments, tags }
+      })()
+    `);
+
+    if (!data || typeof data !== 'object') {
+      throw new EmptyResultError('xiaohongshu/note', 'Unexpected evaluate response');
+    }
+
+    if ((data as any).loginWall) {
+      throw new AuthRequiredError('www.xiaohongshu.com', 'Note content requires login');
+    }
+
+    if ((data as any).notFound) {
+      throw new EmptyResultError('xiaohongshu/note', `Note ${noteId} not found or unavailable — it may have been deleted or restricted`);
+    }
+
+    const d = data as any;
+    // XHS renders placeholder text like "赞"/"收藏"/"评论" when count is 0;
+    // normalize to '0' unless the value looks numeric.
+    const numOrZero = (v: string) => /^\d+/.test(v) ? v : '0';
+    const rows = [
+      { field: 'title', value: d.title || '' },
+      { field: 'author', value: d.author || '' },
+      { field: 'content', value: d.desc || '' },
+      { field: 'likes', value: numOrZero(d.likes || '') },
+      { field: 'collects', value: numOrZero(d.collects || '') },
+      { field: 'comments', value: numOrZero(d.comments || '') },
+    ];
+
+    if (d.tags?.length) {
+      rows.push({ field: 'tags', value: d.tags.join(', ') });
+    }
+
+    return rows;
+  },
+});

package/src/clis/xiaohongshu/search.test.ts

@@ -41,15 +41,16 @@ describe('xiaohongshu search', () => {
     expect(cmd?.func).toBeTypeOf('function');
 
     const page = createPageMock([
-      {
-        loginWall: true,
-        results: [],
-      },
+      // First evaluate: early login-wall check (returns true)
+      true,
     ]);
 
     await expect(cmd!.func!(page, { query: '特斯拉', limit: 5 })).rejects.toThrow(
       'Xiaohongshu search results are blocked behind a login wall'
     );
+
+    // autoScroll must NOT be called when a login wall is detected early
+    expect(page.autoScroll).not.toHaveBeenCalled();
   });
 
   it('returns ranked results with search_result url and author_url preserved', async () => {
@@ -62,6 +63,9 @@ describe('xiaohongshu search', () => {
       'https://www.xiaohongshu.com/user/profile/635a9c720000000018028b40?xsec_token=user-token&xsec_source=pc_search';
 
     const page = createPageMock([
+      // First evaluate: early login-wall check (returns false → no wall)
+      false,
+      // Second evaluate: main DOM extraction
       {
         loginWall: false,
         results: [
@@ -99,6 +103,9 @@ describe('xiaohongshu search', () => {
     expect(cmd?.func).toBeTypeOf('function');
 
     const page = createPageMock([
+      // First evaluate: early login-wall check (returns false → no wall)
+      false,
+      // Second evaluate: main DOM extraction
       {
         loginWall: false,
         results: [

package/src/clis/xiaohongshu/search.ts

@@ -44,6 +44,19 @@ cli({
     );
     await page.wait(3);
 
+    // Early login-wall detection: XHS may show a login gate instead of
+    // results. Check *before* autoScroll to avoid crashing on a page
+    // that has no meaningful content to scroll through.
+    const loginCheck = await page.evaluate(`
+      (() => /登录后查看搜索结果/.test(document.body?.innerText || ''))()
+    `);
+    if (loginCheck) {
+      throw new AuthRequiredError(
+        'www.xiaohongshu.com',
+        'Xiaohongshu search results are blocked behind a login wall',
+      );
+    }
+
     // Scroll a couple of times to load more results
     await page.autoScroll({ times: 2 });
 

package/src/clis/youtube/search.ts

@@ -12,32 +12,60 @@ cli({
   args: [
     { name: 'query', required: true, positional: true, help: 'Search query' },
     { name: 'limit', type: 'int', default: 20, help: 'Max results (max 50)' },
+    { name: 'type', default: '', help: 'Filter type: shorts, video, channel, playlist' },
+    { name: 'upload', default: '', help: 'Upload date: hour, today, week, month, year' },
+    { name: 'sort', default: '', help: 'Sort by: relevance, date, views, rating' },
   ],
-  columns: ['rank', 'title', 'channel', 'views', 'duration', 'url'],
+  columns: ['rank', 'title', 'channel', 'views', 'duration', 'published', 'url'],
   func: async (page, kwargs) => {
     const limit = Math.min(kwargs.limit || 20, 50);
-    await page.goto('https://www.youtube.com');
-    await page.wait(2);
+    const query = encodeURIComponent(kwargs.query);
+
+    // Build search URL with filter params
+    // YouTube uses sp= parameter for filters — we use the URL approach for reliability
+    const spMap: Record<string, string> = {
+      // type filters
+      'shorts': 'EgIQCQ%3D%3D',    // Shorts (type=9)
+      'video': 'EgIQAQ%3D%3D',
+      'channel': 'EgIQAg%3D%3D',
+      'playlist': 'EgIQAw%3D%3D',
+      // upload date filters (can be combined with type via URL)
+      'hour': 'EgIIAQ%3D%3D',
+      'today': 'EgIIAg%3D%3D',
+      'week': 'EgIIAw%3D%3D',
+      'month': 'EgIIBA%3D%3D',
+      'year': 'EgIIBQ%3D%3D',
+    };
+    const sortMap: Record<string, string> = {
+      'date': 'CAI%3D',
+      'views': 'CAM%3D',
+      'rating': 'CAE%3D',
+    };
+
+    // YouTube only supports a single sp= parameter — pick the most specific filter.
+    // Priority: type > upload > sort (type is the most common use case)
+    let sp = '';
+    if (kwargs.type && spMap[kwargs.type]) sp = spMap[kwargs.type];
+    else if (kwargs.upload && spMap[kwargs.upload]) sp = spMap[kwargs.upload];
+    else if (kwargs.sort && sortMap[kwargs.sort]) sp = sortMap[kwargs.sort];
+
+    let url = `https://www.youtube.com/results?search_query=${query}`;
+    if (sp) url += `&sp=${sp}`;
+
+    await page.goto(url);
+    await page.wait(3);
     const data = await page.evaluate(`
       (async () => {
-        const cfg = window.ytcfg?.data_ || {};
-        const apiKey = cfg.INNERTUBE_API_KEY;
-        const context = cfg.INNERTUBE_CONTEXT;
-        if (!apiKey || !context) return {error: 'YouTube config not found'};
+        const data = window.ytInitialData;
+        if (!data) return {error: 'YouTube data not found'};
 
-        const resp = await fetch('/youtubei/v1/search?key=' + apiKey + '&prettyPrint=false', {
-          method: 'POST', credentials: 'include',
-          headers: {'Content-Type': 'application/json'},
-          body: JSON.stringify({context, query: '${kwargs.query.replace(/'/g, "\\'")}'})
-        });
-        if (!resp.ok) return {error: 'HTTP ' + resp.status};
-
-        const data = await resp.json();
         const contents = data.contents?.twoColumnSearchResultsRenderer?.primaryContents?.sectionListRenderer?.contents || [];
         const videos = [];
         for (const section of contents) {
-          for (const item of (section.itemSectionRenderer?.contents || [])) {
-            if (item.videoRenderer && videos.length < ${limit}) {
+          const items = section.itemSectionRenderer?.contents || section.reelShelfRenderer?.items || [];
+          for (const item of items) {
+            if (videos.length >= ${limit}) break;
+            if (item.videoRenderer) {
               const v = item.videoRenderer;
               videos.push({
                 rank: videos.length + 1,
@@ -45,8 +73,20 @@ cli({
                 channel: v.ownerText?.runs?.[0]?.text || '',
                 views: v.viewCountText?.simpleText || v.shortViewCountText?.simpleText || '',
                 duration: v.lengthText?.simpleText || 'LIVE',
+                published: v.publishedTimeText?.simpleText || '',
                 url: 'https://www.youtube.com/watch?v=' + v.videoId
               });
+            } else if (item.reelItemRenderer) {
+              const r = item.reelItemRenderer;
+              videos.push({
+                rank: videos.length + 1,
+                title: r.headline?.simpleText || '',
+                channel: r.navigationEndpoint?.reelWatchEndpoint?.overlay?.reelPlayerOverlayRenderer?.reelPlayerHeaderSupportedRenderers?.reelPlayerHeaderRenderer?.channelTitleText?.runs?.[0]?.text || '',
+                views: r.viewCountText?.simpleText || '',
+                duration: 'SHORT',
+                published: r.publishedTimeText?.simpleText || '',
+                url: 'https://www.youtube.com/shorts/' + r.videoId
+              });
             }
           }
         }

package/src/clis/zhihu/question.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '../../registry.js';
+import { AuthRequiredError } from '../../errors.js';
+import './question.js';
+
+describe('zhihu question', () => {
+  it('returns answers even when the unused question detail request fails', async () => {
+    const cmd = getRegistry().get('zhihu/question');
+    expect(cmd?.func).toBeTypeOf('function');
+
+    const evaluate = vi.fn().mockImplementation(async (_fn: unknown, args: { questionId: string; answerLimit: number }) => {
+      expect(args).toEqual({ questionId: '2021881398772981878', answerLimit: 3 });
+      return {
+        ok: true,
+        answers: [
+          {
+            author: { name: 'alice' },
+            voteup_count: 12,
+            content: '<p>Hello <b>Zhihu</b></p>',
+          },
+        ],
+      };
+    });
+
+    const page = {
+      evaluate,
+    } as any;
+
+    await expect(
+      cmd!.func!(page, { id: '2021881398772981878', limit: 3 }),
+    ).resolves.toEqual([
+      {
+        rank: 1,
+        author: 'alice',
+        votes: 12,
+        content: 'Hello Zhihu',
+      },
+    ]);
+
+    expect(evaluate).toHaveBeenCalledTimes(1);
+  });
+
+  it('maps auth-like answer failures to AuthRequiredError', async () => {
+    const cmd = getRegistry().get('zhihu/question');
+    expect(cmd?.func).toBeTypeOf('function');
+
+    const page = {
+      evaluate: vi.fn().mockResolvedValue({ ok: false, status: 403 }),
+    } as any;
+
+    await expect(
+      cmd!.func!(page, { id: '2021881398772981878', limit: 3 }),
+    ).rejects.toBeInstanceOf(AuthRequiredError);
+  });
+
+  it('preserves non-auth fetch failures as CliError instead of login errors', async () => {
+    const cmd = getRegistry().get('zhihu/question');
+    expect(cmd?.func).toBeTypeOf('function');
+
+    const page = {
+      evaluate: vi.fn().mockResolvedValue({ ok: false, status: 500 }),
+    } as any;
+
+    await expect(
+      cmd!.func!(page, { id: '2021881398772981878', limit: 3 }),
+    ).rejects.toMatchObject({
+      code: 'FETCH_ERROR',
+      message: 'Zhihu question answers request failed with HTTP 500',
+    });
+  });
+});

package/src/clis/zhihu/question.ts

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { AuthRequiredError } from '../../errors.js';
+import { AuthRequiredError, CliError } from '../../errors.js';
 
 cli({
   site: 'zhihu',
@@ -14,27 +14,39 @@ cli({
   columns: ['rank', 'author', 'votes', 'content'],
   func: async (page, kwargs) => {
     const { id, limit = 5 } = kwargs;
+    const answerLimit = Number(limit);
 
     const stripHtml = (html: string) =>
       (html || '').replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').trim();
 
-    // Fetch question detail and answers in parallel via evaluate
-    const result = await page.evaluate(`
-      async () => {
-        const [qResp, aResp] = await Promise.all([
-          fetch('https://www.zhihu.com/api/v4/questions/${id}?include=data[*].detail,excerpt,answer_count,follower_count,visit_count', {credentials: 'include'}),
-          fetch('https://www.zhihu.com/api/v4/questions/${id}/answers?limit=${limit}&offset=0&sort_by=default&include=data[*].content,voteup_count,comment_count,author', {credentials: 'include'})
-        ]);
-        if (!qResp.ok || !aResp.ok) return { error: true };
-        const q = await qResp.json();
+    // Only fetch answers here. The question detail endpoint is not used by the
+    // current CLI output and can fail independently, which would incorrectly
+    // turn a successful answers response into a login error.
+    const result = await (page as any).evaluate(
+      async ({ questionId, answerLimit }: { questionId: string; answerLimit: number }) => {
+        const aResp = await fetch(
+          `https://www.zhihu.com/api/v4/questions/${questionId}/answers?limit=${answerLimit}&offset=0&sort_by=default&include=data[*].content,voteup_count,comment_count,author`,
+          { credentials: 'include' },
+        );
+        if (!aResp.ok) return { ok: false as const, status: aResp.status };
         const a = await aResp.json();
-        return { question: q, answers: a.data || [] };
-      }
-    `);
+        return { ok: true as const, answers: Array.isArray(a?.data) ? a.data : [] };
+      },
+      { questionId: String(id), answerLimit },
+    );
 
-    if (!result || result.error) throw new AuthRequiredError('www.zhihu.com', 'Failed to fetch question data from Zhihu');
+    if (!result?.ok) {
+      if (result?.status === 401 || result?.status === 403) {
+        throw new AuthRequiredError('www.zhihu.com', 'Failed to fetch question data from Zhihu');
+      }
+      throw new CliError(
+        'FETCH_ERROR',
+        `Zhihu question answers request failed with HTTP ${result?.status ?? 'unknown'}`,
+        'Try again later or rerun with -v for more detail',
+      );
+    }
 
-    const answers = (result.answers ?? []).slice(0, Number(limit)).map((a: any, i: number) => ({
+    const answers = result.answers.slice(0, answerLimit).map((a: any, i: number) => ({
       rank: i + 1,
       author: a.author?.name ?? 'anonymous',
       votes: a.voteup_count ?? 0,

package/src/commanderAdapter.test.ts

@@ -123,3 +123,33 @@ describe('commanderAdapter boolean alias support', () => {
     expect(kwargs.undo).toBe(false);
   });
 });
+
+describe('commanderAdapter command aliases', () => {
+  const cmd: CliCommand = {
+    site: 'notebooklm',
+    name: 'get',
+    aliases: ['metadata'],
+    description: 'Get notebook metadata',
+    browser: false,
+    args: [],
+    func: vi.fn(),
+  };
+
+  beforeEach(() => {
+    mockExecuteCommand.mockReset();
+    mockExecuteCommand.mockResolvedValue([]);
+    mockRenderOutput.mockReset();
+    delete process.env.OPENCLI_VERBOSE;
+    process.exitCode = undefined;
+  });
+
+  it('registers aliases with Commander so compatibility names execute the same command', async () => {
+    const program = new Command();
+    const siteCmd = program.command('notebooklm');
+    registerCommandToProgram(siteCmd, cmd);
+
+    await program.parseAsync(['node', 'opencli', 'notebooklm', 'metadata']);
+
+    expect(mockExecuteCommand).toHaveBeenCalledWith(cmd, {}, false);
+  });
+});

package/src/commanderAdapter.ts

@@ -52,6 +52,7 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
 
   const deprecatedSuffix = cmd.deprecated ? ' [deprecated]' : '';
   const subCmd = siteCmd.command(cmd.name).description(`${cmd.description}${deprecatedSuffix}`);
+  if (cmd.aliases?.length) subCmd.aliases(cmd.aliases);
 
   // Register positional args first, then named options
   const positionalArgs: typeof cmd.args = [];
@@ -103,6 +104,9 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
       }
 
       const result = await executeCommand(cmd, kwargs, verbose);
+      if (result === null || result === undefined) {
+        return;
+      }
 
       if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
         console.error(chalk.yellow('[Verbose] Warning: Command returned an empty result.'));
@@ -293,7 +297,10 @@ export function registerAllCommands(
   program: Command,
   siteGroups: Map<string, Command>,
 ): void {
+  const seen = new Set<CliCommand>();
   for (const [, cmd] of getRegistry()) {
+    if (seen.has(cmd)) continue;
+    seen.add(cmd);
     let siteCmd = siteGroups.get(cmd.site);
     if (!siteCmd) {
       siteCmd = program.command(cmd.site).description(`${cmd.site} commands`);