@jackwener/opencli 1.5.9 → 1.6.1

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

@@ -137,6 +137,57 @@ describe('xiaohongshu note', () => {
     await expect(command!.func!(page, { 'note-id': 'abc123' })).rejects.toThrow('returned no data');
   });
 
+  it('throws a token hint when the note page renders as an empty shell', async () => {
+    const page = createPageMock({
+      loginWall: false,
+      notFound: false,
+      title: '',
+      desc: '',
+      author: '',
+      likes: '',
+      collects: '',
+      comments: '',
+      tags: [],
+    });
+
+    try {
+      await command!.func!(page, { 'note-id': '69ca3927000000001a020fd5' });
+      throw new Error('expected xiaohongshu note to fail on an empty shell page');
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'EMPTY_RESULT',
+        hint: expect.stringMatching(/xsec_token|full url|search_result/i),
+      });
+    }
+  });
+
+  it('keeps the empty-shell hint generic when the user already passed a full URL', async () => {
+    const page = createPageMock({
+      loginWall: false,
+      notFound: false,
+      title: '',
+      desc: '',
+      author: '',
+      likes: '',
+      collects: '',
+      comments: '',
+      tags: [],
+    });
+
+    try {
+      await command!.func!(page, {
+        'note-id': 'https://www.xiaohongshu.com/search_result/69ca3927000000001a020fd5?xsec_token=abc',
+      });
+      throw new Error('expected xiaohongshu note to fail on an empty shell page');
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'EMPTY_RESULT',
+        hint: expect.stringContaining('loaded without visible content'),
+      });
+      expect((error as { hint?: string }).hint).not.toContain('bare note ID');
+    }
+  });
+
   it('normalizes placeholder text to 0 for zero-count metrics', async () => {
     const page = createPageMock({
       loginWall: false, notFound: false,

package/src/clis/xiaohongshu/note.ts

@@ -21,6 +21,7 @@ cli({
   columns: ['field', 'value'],
   func: async (page, kwargs) => {
     const raw = String(kwargs['note-id']);
+    const isBareNoteId = !/^https?:\/\//.test(raw.trim());
     const noteId = parseNoteId(raw);
     const url = buildNoteUrl(raw);
 
@@ -68,6 +69,23 @@ cli({
     // 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';
+
+    // XHS sometimes renders an empty shell page for bare /explore/<id> visits
+    // when the request lacks a valid xsec_token.  Title + author are always
+    // present on a real note, so their absence is the simplest reliable signal.
+    const emptyShell = !d.title && !d.author;
+    if (emptyShell) {
+      if (isBareNoteId) {
+        throw new EmptyResultError(
+          'xiaohongshu/note',
+          'Pass the full search_result URL with xsec_token, for example from `opencli xiaohongshu search`, instead of a bare note ID.',
+        );
+      }
+      throw new EmptyResultError(
+        'xiaohongshu/note',
+        'The note page loaded without visible content. Retry with a fresh URL or run with --verbose; if it persists, the page structure may have changed.',
+      );
+    }
     const rows = [
       { field: 'title', value: d.title || '' },
       { field: 'author', value: d.author || '' },

package/src/commanderAdapter.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { Command } from 'commander';
 import type { CliCommand } from './registry.js';
+import { EmptyResultError, SelectorError } from './errors.js';
 
 const { mockExecuteCommand, mockRenderOutput } = vi.hoisted(() => ({
   mockExecuteCommand: vi.fn(),
@@ -200,3 +201,64 @@ describe('commanderAdapter default formats', () => {
     );
   });
 });
+
+describe('commanderAdapter empty result hints', () => {
+  const cmd: CliCommand = {
+    site: 'xiaohongshu',
+    name: 'note',
+    description: 'Read one note',
+    browser: false,
+    args: [
+      { name: 'note-id', positional: true, required: true, help: 'Note ID' },
+    ],
+    func: vi.fn(),
+  };
+
+  beforeEach(() => {
+    mockExecuteCommand.mockReset();
+    mockRenderOutput.mockReset();
+    delete process.env.OPENCLI_VERBOSE;
+    process.exitCode = undefined;
+  });
+
+  it('prints the adapter hint instead of the generic outdated-adapter message', async () => {
+    const program = new Command();
+    const siteCmd = program.command('xiaohongshu');
+    registerCommandToProgram(siteCmd, cmd);
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    mockExecuteCommand.mockRejectedValueOnce(
+      new EmptyResultError(
+        'xiaohongshu/note',
+        'Pass the full search_result URL with xsec_token instead of a bare note ID.',
+      ),
+    );
+
+    await program.parseAsync(['node', 'opencli', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+
+    const output = errorSpy.mock.calls.flat().join('\n');
+    expect(output).toContain('xsec_token');
+    expect(output).not.toContain('this adapter may be outdated');
+
+    errorSpy.mockRestore();
+  });
+
+  it('prints selector-specific hints too', async () => {
+    const program = new Command();
+    const siteCmd = program.command('xiaohongshu');
+    registerCommandToProgram(siteCmd, cmd);
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    mockExecuteCommand.mockRejectedValueOnce(
+      new SelectorError('.note-title', 'The note title selector no longer matches the current page.'),
+    );
+
+    await program.parseAsync(['node', 'opencli', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+
+    const output = errorSpy.mock.calls.flat().join('\n');
+    expect(output).toContain('selector no longer matches');
+    expect(output).not.toContain('this adapter may be outdated');
+
+    errorSpy.mockRestore();
+  });
+});

package/src/commanderAdapter.ts

@@ -225,7 +225,7 @@ async function renderError(err: unknown, cmdName: string, verbose: boolean): Pro
   if (err instanceof SelectorError || err instanceof EmptyResultError) {
     const icon = ERROR_ICONS[err.code] ?? '⚠️';
     console.error(chalk.red(`${icon} ${err.message}`));
-    console.error(chalk.yellow('→ The page structure may have changed — this adapter may be outdated.'));
+    console.error(chalk.yellow(`→ ${err.hint ?? 'The page structure may have changed — this adapter may be outdated.'}`));
     console.error(chalk.dim(`  Debug:  ${cmdName} --verbose`));
     console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
     return;

package/src/commands/daemon.test.ts

@@ -1,5 +1,13 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 
+const {
+  fetchDaemonStatusMock,
+  requestDaemonShutdownMock,
+} = vi.hoisted(() => ({
+  fetchDaemonStatusMock: vi.fn(),
+  requestDaemonShutdownMock: vi.fn(),
+}));
+
 vi.mock('chalk', () => ({
   default: {
     green: (s: string) => s,
@@ -16,6 +24,11 @@ vi.mock('../browser/bridge.js', () => ({
   },
 }));
 
+vi.mock('../browser/daemon-client.js', () => ({
+  fetchDaemonStatus: fetchDaemonStatusMock,
+  requestDaemonShutdown: requestDaemonShutdownMock,
+}));
+
 import { daemonStatus, daemonStop, daemonRestart } from './daemon.js';
 
 describe('daemon commands', () => {
@@ -25,6 +38,8 @@ describe('daemon commands', () => {
   beforeEach(() => {
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    fetchDaemonStatusMock.mockReset();
+    requestDaemonShutdownMock.mockReset();
   });
 
   afterEach(() => {
@@ -34,7 +49,7 @@ describe('daemon commands', () => {
 
   describe('daemonStatus', () => {
     it('shows "not running" when daemon is unreachable', async () => {
-      vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+      fetchDaemonStatusMock.mockResolvedValue(null);
 
       await daemonStatus();
 
@@ -42,7 +57,7 @@ describe('daemon commands', () => {
     });
 
     it('shows "not running" when daemon returns non-ok response', async () => {
-      vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false }));
+      fetchDaemonStatusMock.mockResolvedValue(null);
 
       await daemonStatus();
 
@@ -61,13 +76,7 @@ describe('daemon commands', () => {
         port: 19825,
       };
 
-      vi.stubGlobal(
-        'fetch',
-        vi.fn().mockResolvedValue({
-          ok: true,
-          json: () => Promise.resolve(status),
-        }),
-      );
+      fetchDaemonStatusMock.mockResolvedValue(status);
 
       await daemonStatus();
 
@@ -91,13 +100,7 @@ describe('daemon commands', () => {
         port: 19825,
       };
 
-      vi.stubGlobal(
-        'fetch',
-        vi.fn().mockResolvedValue({
-          ok: true,
-          json: () => Promise.resolve(status),
-        }),
-      );
+      fetchDaemonStatusMock.mockResolvedValue(status);
 
       await daemonStatus();
 
@@ -107,7 +110,7 @@ describe('daemon commands', () => {
 
   describe('daemonStop', () => {
     it('reports "not running" when daemon is unreachable', async () => {
-      vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+      fetchDaemonStatusMock.mockResolvedValue(null);
 
       await daemonStop();
 
@@ -115,59 +118,36 @@ describe('daemon commands', () => {
     });
 
     it('sends shutdown and reports success', async () => {
-      const statusResponse = {
+      fetchDaemonStatusMock.mockResolvedValue({
         ok: true,
-        json: () =>
-          Promise.resolve({
-            ok: true,
-            pid: 12345,
-            uptime: 100,
-            extensionConnected: true,
-            pending: 0,
-            lastCliRequestTime: Date.now(),
-            memoryMB: 50,
-            port: 19825,
-          }),
-      };
-      const shutdownResponse = { ok: true };
-
-      const mockFetch = vi.fn()
-        .mockResolvedValueOnce(statusResponse)
-        .mockResolvedValueOnce(shutdownResponse);
-      vi.stubGlobal('fetch', mockFetch);
+        pid: 12345,
+        uptime: 100,
+        extensionConnected: true,
+        pending: 0,
+        lastCliRequestTime: Date.now(),
+        memoryMB: 50,
+        port: 19825,
+      });
+      requestDaemonShutdownMock.mockResolvedValue(true);
 
       await daemonStop();
 
-      // Verify shutdown was called with POST
-      expect(mockFetch).toHaveBeenCalledTimes(2);
-      const shutdownCall = mockFetch.mock.calls[1];
-      expect(shutdownCall[0]).toContain('/shutdown');
-      expect(shutdownCall[1]).toMatchObject({ method: 'POST' });
-
+      expect(requestDaemonShutdownMock).toHaveBeenCalledTimes(1);
       expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon stopped'));
     });
 
     it('reports failure when shutdown request fails', async () => {
-      const statusResponse = {
+      fetchDaemonStatusMock.mockResolvedValue({
         ok: true,
-        json: () =>
-          Promise.resolve({
-            ok: true,
-            pid: 12345,
-            uptime: 100,
-            extensionConnected: true,
-            pending: 0,
-            lastCliRequestTime: Date.now(),
-            memoryMB: 50,
-            port: 19825,
-          }),
-      };
-      const shutdownResponse = { ok: false };
-
-      const mockFetch = vi.fn()
-        .mockResolvedValueOnce(statusResponse)
-        .mockResolvedValueOnce(shutdownResponse);
-      vi.stubGlobal('fetch', mockFetch);
+        pid: 12345,
+        uptime: 100,
+        extensionConnected: true,
+        pending: 0,
+        lastCliRequestTime: Date.now(),
+        memoryMB: 50,
+        port: 19825,
+      });
+      requestDaemonShutdownMock.mockResolvedValue(false);
 
       await daemonStop();
 
@@ -188,7 +168,7 @@ describe('daemon commands', () => {
     };
 
     it('starts daemon directly when not running', async () => {
-      vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+      fetchDaemonStatusMock.mockResolvedValue(null);
       mockConnect.mockResolvedValue(undefined);
 
       await daemonRestart();
@@ -198,36 +178,22 @@ describe('daemon commands', () => {
     });
 
     it('stops then starts when daemon is running', async () => {
-      const mockFetch = vi.fn()
-        // First call: fetchStatus in daemonRestart — daemon is running
-        .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(statusData) })
-        // Second call: requestShutdown — success
-        .mockResolvedValueOnce({ ok: true })
-        // Subsequent calls: polling fetchStatus until unreachable
-        .mockRejectedValue(new Error('ECONNREFUSED'));
-
-      vi.stubGlobal('fetch', mockFetch);
+      fetchDaemonStatusMock
+        .mockResolvedValueOnce(statusData)
+        .mockResolvedValueOnce(null);
+      requestDaemonShutdownMock.mockResolvedValue(true);
       mockConnect.mockResolvedValue(undefined);
 
       await daemonRestart();
 
-      // Verify shutdown was called
-      const shutdownCall = mockFetch.mock.calls[1];
-      expect(shutdownCall[0]).toContain('/shutdown');
-      expect(shutdownCall[1]).toMatchObject({ method: 'POST' });
-
+      expect(requestDaemonShutdownMock).toHaveBeenCalledTimes(1);
       expect(mockConnect).toHaveBeenCalledWith({ timeout: 10 });
       expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon restarted'));
     });
 
     it('aborts when shutdown fails', async () => {
-      const mockFetch = vi.fn()
-        // fetchStatus — daemon is running
-        .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(statusData) })
-        // requestShutdown — failure
-        .mockResolvedValueOnce({ ok: false });
-
-      vi.stubGlobal('fetch', mockFetch);
+      fetchDaemonStatusMock.mockResolvedValue(statusData);
+      requestDaemonShutdownMock.mockResolvedValue(false);
 
       await daemonRestart();
 

package/src/commands/daemon.ts

@@ -6,55 +6,7 @@
  */
 
 import chalk from 'chalk';
-import { DEFAULT_DAEMON_PORT } from '../constants.js';
-
-const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
-
-interface DaemonStatus {
-  ok: boolean;
-  pid: number;
-  uptime: number;
-  extensionConnected: boolean;
-  pending: number;
-  lastCliRequestTime: number;
-  memoryMB: number;
-  port: number;
-}
-
-async function fetchStatus(): Promise<DaemonStatus | null> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 2000);
-  try {
-    const res = await fetch(`${DAEMON_URL}/status`, {
-      headers: { 'X-OpenCLI': '1' },
-      signal: controller.signal,
-    });
-    if (!res.ok) return null;
-    return await res.json() as DaemonStatus;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-async function requestShutdown(): Promise<boolean> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 5000);
-  try {
-    const res = await fetch(`${DAEMON_URL}/shutdown`, {
-      method: 'POST',
-      headers: { 'X-OpenCLI': '1' },
-      signal: controller.signal,
-    });
-    return res.ok;
-  } catch {
-    return false;
-  } finally {
-    clearTimeout(timer);
-  }
-}
+import { fetchDaemonStatus, requestDaemonShutdown } from '../browser/daemon-client.js';
 
 function formatUptime(seconds: number): string {
   const h = Math.floor(seconds / 3600);
@@ -74,7 +26,7 @@ function formatTimeSince(timestampMs: number): string {
 }
 
 export async function daemonStatus(): Promise<void> {
-  const status = await fetchStatus();
+  const status = await fetchDaemonStatus();
   if (!status) {
     console.log(`Daemon: ${chalk.dim('not running')}`);
     return;
@@ -89,13 +41,13 @@ export async function daemonStatus(): Promise<void> {
 }
 
 export async function daemonStop(): Promise<void> {
-  const status = await fetchStatus();
+  const status = await fetchDaemonStatus();
   if (!status) {
     console.log(chalk.dim('Daemon is not running.'));
     return;
   }
 
-  const ok = await requestShutdown();
+  const ok = await requestDaemonShutdown();
   if (ok) {
     console.log(chalk.green('Daemon stopped.'));
   } else {
@@ -105,9 +57,9 @@ export async function daemonStop(): Promise<void> {
 }
 
 export async function daemonRestart(): Promise<void> {
-  const status = await fetchStatus();
+  const status = await fetchDaemonStatus();
   if (status) {
-    const ok = await requestShutdown();
+    const ok = await requestDaemonShutdown();
     if (!ok) {
       console.error(chalk.red('Failed to stop daemon.'));
       process.exitCode = 1;
@@ -117,7 +69,7 @@ export async function daemonRestart(): Promise<void> {
     const deadline = Date.now() + 5000;
     while (Date.now() < deadline) {
       await new Promise(r => setTimeout(r, 200));
-      if (!(await fetchStatus())) break;
+      if (!(await fetchDaemonStatus())) break;
     }
   }
 

package/src/discovery.ts

@@ -76,6 +76,28 @@ export async function ensureUserCliCompatShims(baseDir: string = USER_OPENCLI_DI
       `${JSON.stringify({ name: 'opencli-user-runtime', private: true, type: 'module' }, null, 2)}\n`,
     ),
   ]);
+
+  // Create node_modules/@jackwener/opencli symlink so user TS CLIs can import
+  // from '@jackwener/opencli/registry' (the package export).
+  // This is needed because ~/.opencli/clis/ is outside opencli's node_modules tree.
+  const opencliRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const symlinkDir = path.join(baseDir, 'node_modules', '@jackwener');
+  const symlinkPath = path.join(symlinkDir, 'opencli');
+  try {
+    // Only recreate if symlink is missing or points to wrong target
+    let needsUpdate = true;
+    try {
+      const existing = await fs.promises.readlink(symlinkPath);
+      if (existing === opencliRoot) needsUpdate = false;
+    } catch { /* doesn't exist */ }
+    if (needsUpdate) {
+      await fs.promises.mkdir(symlinkDir, { recursive: true });
+      try { await fs.promises.unlink(symlinkPath); } catch { /* doesn't exist */ }
+      await fs.promises.symlink(opencliRoot, symlinkPath, 'dir');
+    }
+  } catch {
+    // Non-fatal: npm-linked installs or permission issues may prevent this
+  }
 }
 
 /**

package/src/doctor.ts

@@ -25,6 +25,7 @@ export type ConnectivityResult = {
   durationMs: number;
 };
 
+
 export type DoctorReport = {
   cliVersion?: string;
   daemonRunning: boolean;
@@ -93,7 +94,6 @@ export async function runBrowserDoctor(opts: DoctorOptions = {}): Promise<Doctor
   if (connectivity && !connectivity.ok) {
     issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
   }
-
   if (status.extensionVersion && opts.cliVersion) {
     const extMajor = status.extensionVersion.split('.')[0];
     const cliMajor = opts.cliVersion.split('.')[0];

package/src/types.ts

@@ -77,4 +77,12 @@ export interface IPage {
   getCurrentUrl?(): Promise<string | null>;
   /** Returns the active tab ID, or undefined if not yet resolved. */
   getActiveTabId?(): number | undefined;
+  /** Send a raw CDP command via chrome.debugger passthrough. */
+  cdp?(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  /** Click at native coordinates via CDP Input.dispatchMouseEvent. */
+  nativeClick?(x: number, y: number): Promise<void>;
+  /** Type text via CDP Input.insertText. */
+  nativeType?(text: string): Promise<void>;
+  /** Press a key via CDP Input.dispatchKeyEvent. */
+  nativeKeyPress?(key: string, modifiers?: string[]): Promise<void>;
 }