@jackwener/opencli 1.5.4 → 1.5.6

package/src/clis/zsxq/utils.ts

@@ -0,0 +1,351 @@
+import { ArgumentError, AuthRequiredError, CliError } from '../../errors.js';
+import type { IPage } from '../../types.js';
+
+export interface ZsxqUser {
+  user_id?: number;
+  name?: string;
+  avatar_url?: string;
+}
+
+export interface ZsxqGroup {
+  group_id?: number;
+  name?: string;
+  description?: string;
+  background_url?: string;
+  owner?: ZsxqUser;
+  statistics?: {
+    topics_count?: number;
+    answers_count?: number;
+    comments_count?: number;
+    likes_count?: number;
+    subscriptions_count?: number;
+  };
+  category?: {
+    title?: string;
+  };
+  user_specific?: {
+    join_time?: string;
+    validity?: {
+      end_time?: string;
+    };
+  };
+}
+
+export interface ZsxqComment {
+  comment_id?: number;
+  create_time?: string;
+  text?: string;
+  owner?: ZsxqUser;
+  likes_count?: number;
+  rewards_count?: number;
+  repliee?: ZsxqUser;
+}
+
+export interface ZsxqTopic {
+  topic_id?: number;
+  create_time?: string;
+  comments_count?: number;
+  likes_count?: number;
+  readers_count?: number;
+  reading_count?: number;
+  rewards_count?: number;
+  title?: string;
+  type?: string;
+  group?: ZsxqGroup;
+  owner?: ZsxqUser;
+  user_specific?: Record<string, unknown>;
+  talk?: {
+    owner?: ZsxqUser;
+    text?: string;
+  };
+  question?: {
+    owner?: ZsxqUser;
+    text?: string;
+  };
+  answer?: {
+    owner?: ZsxqUser;
+    text?: string;
+  };
+  task?: {
+    owner?: ZsxqUser;
+    text?: string;
+  };
+  solution?: {
+    owner?: ZsxqUser;
+    text?: string;
+  };
+  show_comments?: ZsxqComment[];
+  comments?: ZsxqComment[];
+}
+
+export interface BrowserFetchResult {
+  ok: boolean;
+  url?: string;
+  status?: number;
+  error?: string;
+  data?: unknown;
+}
+
+const SITE_DOMAIN = 'wx.zsxq.com';
+const SITE_URL = 'https://wx.zsxq.com';
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function pickArray<T>(...values: unknown[]): T[] {
+  for (const value of values) {
+    if (Array.isArray(value)) {
+      return value as T[];
+    }
+  }
+  return [];
+}
+
+export async function ensureZsxqPage(page: IPage): Promise<void> {
+  await page.goto(SITE_URL);
+}
+
+export async function ensureZsxqAuth(page: IPage): Promise<void> {
+  // zsxq uses httpOnly cookies that may be on different subdomains.
+  // Verify auth by attempting a lightweight API call instead of checking cookies.
+  try {
+    const result = await page.evaluate(`
+      (async () => {
+        try {
+          const r = await new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open('GET', 'https://api.zsxq.com/v2/groups', true);
+            xhr.withCredentials = true;
+            xhr.setRequestHeader('accept', 'application/json');
+            xhr.onload = () => {
+              if (xhr.status >= 200 && xhr.status < 300) {
+                try { resolve(JSON.parse(xhr.responseText)); }
+                catch { resolve(null); }
+              } else { resolve(null); }
+            };
+            xhr.onerror = () => resolve(null);
+            xhr.send();
+          });
+          return r !== null;
+        } catch { return false; }
+      })()
+    `);
+    if (!result) {
+      throw new AuthRequiredError('zsxq.com');
+    }
+  } catch (err) {
+    if (err instanceof AuthRequiredError) throw err;
+    throw new AuthRequiredError('zsxq.com');
+  }
+}
+
+export async function getCookieValue(page: IPage, name: string): Promise<string | undefined> {
+  const cookies = await page.getCookies({ domain: SITE_DOMAIN });
+  return cookies.find(cookie => cookie.name === name)?.value;
+}
+
+export async function getActiveGroupId(page: IPage): Promise<string> {
+  const groupId = await page.evaluate(`
+    (() => {
+      const target = localStorage.getItem('target_group');
+      if (target) {
+        try {
+          const parsed = JSON.parse(target);
+          if (parsed.group_id) return String(parsed.group_id);
+        } catch {}
+      }
+      return null;
+    })()
+  `);
+  if (groupId) return groupId;
+
+  throw new ArgumentError(
+    'Cannot determine active group_id',
+    'Pass --group_id <id> or open the target 知识星球 page in Chrome first',
+  );
+}
+
+export async function browserJsonRequest(page: IPage, path: string): Promise<BrowserFetchResult> {
+  return await page.evaluate(`
+    (async () => {
+      const path = ${JSON.stringify(path)};
+
+      try {
+        return await new Promise((resolve) => {
+          const xhr = new XMLHttpRequest();
+          xhr.open('GET', path, true);
+          xhr.withCredentials = true;
+          xhr.setRequestHeader('accept', 'application/json, text/plain, */*');
+          xhr.onload = () => {
+            let parsed = null;
+            if (xhr.responseText) {
+              try { parsed = JSON.parse(xhr.responseText); }
+              catch {}
+            }
+
+            resolve({
+              ok: xhr.status >= 200 && xhr.status < 300,
+              url: path,
+              status: xhr.status,
+              data: parsed,
+              error: xhr.status >= 200 && xhr.status < 300 ? undefined : 'HTTP ' + xhr.status,
+            });
+          };
+          xhr.onerror = () => resolve({
+            ok: false,
+            url: path,
+            error: 'Network error',
+          });
+          xhr.send();
+        });
+      } catch (error) {
+        return {
+          ok: false,
+          url: path,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })()
+  `) as BrowserFetchResult;
+}
+
+export async function fetchFirstJson(page: IPage, paths: string[]): Promise<BrowserFetchResult> {
+  let lastFailure: BrowserFetchResult | null = null;
+
+  for (const path of paths) {
+    const result = await browserJsonRequest(page, path);
+    if (result.ok) {
+      return result;
+    }
+    lastFailure = result;
+  }
+
+  if (!lastFailure) {
+    throw new CliError(
+      'FETCH_ERROR',
+      'No candidate endpoint returned JSON',
+      `Checked endpoints: ${paths.join(', ')}`,
+    );
+  }
+
+  throw new CliError(
+    'FETCH_ERROR',
+    lastFailure.error || 'Failed to fetch ZSXQ API',
+    `Checked endpoints: ${paths.join(', ')}`,
+  );
+}
+
+export function unwrapRespData<T>(payload: unknown): T {
+  const record = asRecord(payload);
+  if (!record) {
+    throw new CliError('PARSE_ERROR', 'Invalid ZSXQ API response');
+  }
+
+  if (record.succeeded === false) {
+    const code = typeof record.code === 'number' ? String(record.code) : 'API_ERROR';
+    const message = typeof record.info === 'string'
+      ? record.info
+      : typeof record.error === 'string'
+        ? record.error
+        : 'ZSXQ API returned an error';
+    throw new CliError(code, message);
+  }
+
+  return (record.resp_data ?? record.data ?? payload) as T;
+}
+
+export function getTopicsFromResponse(payload: unknown): ZsxqTopic[] {
+  const data = unwrapRespData<Record<string, unknown> | ZsxqTopic[]>(payload);
+  if (Array.isArray(data)) return data;
+  return pickArray<ZsxqTopic>(
+    data.topics,
+    data.list,
+    data.records,
+    data.items,
+    data.search_result,
+  );
+}
+
+export function getCommentsFromResponse(payload: unknown): ZsxqComment[] {
+  const data = unwrapRespData<Record<string, unknown> | ZsxqComment[]>(payload);
+  if (Array.isArray(data)) return data;
+  return pickArray<ZsxqComment>(data.comments, data.list, data.items);
+}
+
+export function getGroupsFromResponse(payload: unknown): ZsxqGroup[] {
+  const data = unwrapRespData<Record<string, unknown> | ZsxqGroup[]>(payload);
+  if (Array.isArray(data)) return data;
+  return pickArray<ZsxqGroup>(data.groups, data.list, data.items);
+}
+
+export function getTopicFromResponse(payload: unknown): ZsxqTopic | null {
+  const data = unwrapRespData<Record<string, unknown> | ZsxqTopic>(payload);
+  if (Array.isArray(data)) return data[0] ?? null;
+  if (typeof data.topic_id === 'number') return data;
+  const record = asRecord(data);
+  if (!record) return null;
+  const topic = record.topic;
+  return topic && typeof topic === 'object' ? topic as ZsxqTopic : null;
+}
+
+export function getTopicAuthor(topic: ZsxqTopic): string {
+  return (
+    topic.owner?.name ||
+    topic.talk?.owner?.name ||
+    topic.question?.owner?.name ||
+    topic.answer?.owner?.name ||
+    topic.task?.owner?.name ||
+    topic.solution?.owner?.name ||
+    ''
+  );
+}
+
+export function getTopicText(topic: ZsxqTopic): string {
+  const primary = [
+    topic.title,
+    topic.talk?.text,
+    topic.question?.text,
+    topic.answer?.text,
+    topic.task?.text,
+    topic.solution?.text,
+  ].find(value => typeof value === 'string' && value.trim());
+  return (primary || '').replace(/\s+/g, ' ').trim();
+}
+
+export function getTopicUrl(topicId: number | string | undefined): string {
+  return topicId ? `${SITE_URL}/topic/${topicId}` : SITE_URL;
+}
+
+export function summarizeComments(comments: ZsxqComment[], limit: number = 3): string {
+  return comments
+    .slice(0, limit)
+    .map((comment) => {
+      const author = comment.owner?.name || '匿名';
+      const target = comment.repliee?.name ? ` -> ${comment.repliee.name}` : '';
+      const text = (comment.text || '').replace(/\s+/g, ' ').trim();
+      return `${author}${target}: ${text}`;
+    })
+    .join(' | ');
+}
+
+export function toTopicRow(topic: ZsxqTopic): Record<string, unknown> {
+  const topicId = topic.topic_id ?? '';
+  const comments = pickArray<ZsxqComment>(topic.show_comments, topic.comments);
+  return {
+    topic_id: topicId,
+    type: topic.type || '',
+    group: topic.group?.name || '',
+    author: getTopicAuthor(topic),
+    title: getTopicText(topic).slice(0, 120),
+    content: getTopicText(topic),
+    comments: topic.comments_count ?? comments.length ?? 0,
+    likes: topic.likes_count ?? 0,
+    readers: topic.readers_count ?? topic.reading_count ?? 0,
+    time: topic.create_time || '',
+    comment_preview: summarizeComments(comments),
+    url: getTopicUrl(topicId),
+  };
+}

package/src/commanderAdapter.test.ts

@@ -76,3 +76,50 @@ describe('commanderAdapter arg passing', () => {
     expect(mockExecuteCommand).not.toHaveBeenCalled();
   });
 });
+
+describe('commanderAdapter boolean alias support', () => {
+  const cmd: CliCommand = {
+    site: 'reddit',
+    name: 'save',
+    description: 'Save a post',
+    browser: false,
+    args: [
+      { name: 'post-id', positional: true, required: true, help: 'Post ID' },
+      { name: 'undo', type: 'boolean', default: false, help: 'Unsave instead of save' },
+    ],
+    func: vi.fn(),
+  };
+
+  beforeEach(() => {
+    mockExecuteCommand.mockReset();
+    mockExecuteCommand.mockResolvedValue([]);
+    mockRenderOutput.mockReset();
+    delete process.env.OPENCLI_VERBOSE;
+    process.exitCode = undefined;
+  });
+
+  it('coerces default false for boolean args to a real boolean', async () => {
+    const program = new Command();
+    const siteCmd = program.command('reddit');
+    registerCommandToProgram(siteCmd, cmd);
+
+    await program.parseAsync(['node', 'opencli', 'reddit', 'save', 't3_abc123']);
+
+    expect(mockExecuteCommand).toHaveBeenCalled();
+    const kwargs = mockExecuteCommand.mock.calls[0][1];
+    expect(kwargs['post-id']).toBe('t3_abc123');
+    expect(kwargs.undo).toBe(false);
+  });
+
+  it('coerces explicit false for boolean args to a real boolean', async () => {
+    const program = new Command();
+    const siteCmd = program.command('reddit');
+    registerCommandToProgram(siteCmd, cmd);
+
+    await program.parseAsync(['node', 'opencli', 'reddit', 'save', 't3_abc123', '--undo', 'false']);
+
+    expect(mockExecuteCommand).toHaveBeenCalled();
+    const kwargs = mockExecuteCommand.mock.calls[0][1];
+    expect(kwargs.undo).toBe(false);
+  });
+});

package/src/commanderAdapter.ts

@@ -18,6 +18,7 @@ import { render as renderOutput } from './output.js';
 import { executeCommand } from './execution.js';
 import {
   CliError,
+  EXIT_CODES,
   ERROR_ICONS,
   getErrorMessage,
   BrowserConnectError,
@@ -32,7 +33,7 @@ import {
 import { checkDaemonStatus } from './browser/discover.js';
 
 export function normalizeArgValue(argType: string | undefined, value: unknown, name: string): unknown {
-  if (argType !== 'bool') return value;
+  if (argType !== 'bool' && argType !== 'boolean') return value;
   if (typeof value === 'boolean') return value;
   if (value == null || value === '') return false;
 
@@ -40,7 +41,7 @@ export function normalizeArgValue(argType: string | undefined, value: unknown, n
   if (normalized === 'true') return true;
   if (normalized === 'false') return false;
 
-  throw new CliError('ARGUMENT', `"${name}" must be either "true" or "false".`);
+  throw new ArgumentError(`"${name}" must be either "true" or "false".`);
 }
 
 /**
@@ -117,11 +118,33 @@ export function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): voi
       });
     } catch (err) {
       await renderError(err, fullName(cmd), optionsRecord.verbose === true);
-      process.exitCode = 1;
+      process.exitCode = resolveExitCode(err);
     }
   });
 }
 
+// ── Exit code resolution ─────────────────────────────────────────────────────
+
+/**
+ * Map any thrown value to a Unix process exit code.
+ *
+ * - CliError subclasses carry their own exitCode (set in errors.ts).
+ * - Generic Error objects are classified by message pattern so that
+ *   un-typed auth / not-found errors from adapters still produce
+ *   meaningful exit codes for shell scripts.
+ */
+function resolveExitCode(err: unknown): number {
+  if (err instanceof CliError) return err.exitCode;
+
+  // Pattern-based fallback for untyped errors thrown by third-party adapters.
+  const msg = getErrorMessage(err);
+  const kind = classifyGenericError(msg);
+  if (kind === 'auth')      return EXIT_CODES.NOPERM;
+  if (kind === 'not-found') return EXIT_CODES.EMPTY_RESULT;
+  if (kind === 'http')      return EXIT_CODES.GENERIC_ERROR;  // HTTP 4xx/5xx → generic; renderer shows details
+  return EXIT_CODES.GENERIC_ERROR;
+}
+
 // ── Error rendering ──────────────────────────────────────────────────────────
 
 const ISSUES_URL = 'https://github.com/jackwener/opencli/issues';

package/src/daemon.ts

@@ -22,6 +22,7 @@
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 import { WebSocketServer, WebSocket, type RawData } from 'ws';
 import { DEFAULT_DAEMON_PORT } from './constants.js';
+import { EXIT_CODES } from './errors.js';
 
 const PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const IDLE_TIMEOUT = 5 * 60 * 1000; // 5 minutes
@@ -53,7 +54,7 @@ function resetIdleTimer(): void {
   if (idleTimer) clearTimeout(idleTimer);
   idleTimer = setTimeout(() => {
     console.error('[daemon] Idle timeout, shutting down');
-    process.exit(0);
+    process.exit(EXIT_CODES.SUCCESS);
   }, IDLE_TIMEOUT);
 }
 
@@ -303,10 +304,10 @@ httpServer.listen(PORT, '127.0.0.1', () => {
 httpServer.on('error', (err: NodeJS.ErrnoException) => {
   if (err.code === 'EADDRINUSE') {
     console.error(`[daemon] Port ${PORT} already in use — another daemon is likely running. Exiting.`);
-    process.exit(1);
+    process.exit(EXIT_CODES.SERVICE_UNAVAIL);
   }
   console.error('[daemon] Server error:', err.message);
-  process.exit(1);
+  process.exit(EXIT_CODES.GENERIC_ERROR);
 });
 
 // Graceful shutdown
@@ -319,7 +320,7 @@ function shutdown(): void {
   pending.clear();
   if (extensionWs) extensionWs.close();
   httpServer.close();
-  process.exit(0);
+  process.exit(EXIT_CODES.SUCCESS);
 }
 
 process.on('SIGTERM', shutdown);

package/src/errors.ts

@@ -4,48 +4,96 @@
  * All errors thrown by the framework should extend CliError so that
  * the top-level handler in commanderAdapter.ts can render consistent,
  * helpful output with emoji-coded severity and actionable hints.
+ *
+ * ## Exit codes
+ *
+ * opencli follows Unix conventions (sysexits.h) for process exit codes:
+ *
+ *   0   Success
+ *   1   Generic / unexpected error
+ *   2   Argument / usage error          (ArgumentError)
+ *  66   No input / empty result         (EmptyResultError)
+ *  69   Service unavailable             (BrowserConnectError, AdapterLoadError)
+ *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
+ *  77   Permission denied / auth needed (AuthRequiredError)
+ *  78   Configuration error             (ConfigError)
+ * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
  */
 
+// ── Exit code table ──────────────────────────────────────────────────────────
+
+export const EXIT_CODES = {
+  SUCCESS:         0,
+  GENERIC_ERROR:   1,
+  USAGE_ERROR:     2,   // Bad arguments / command misuse
+  EMPTY_RESULT:   66,   // No data / not found           (EX_NOINPUT)
+  SERVICE_UNAVAIL:69,   // Daemon / browser unavailable  (EX_UNAVAILABLE)
+  TEMPFAIL:       75,   // Timeout — try again later     (EX_TEMPFAIL)
+  NOPERM:         77,   // Auth required / permission    (EX_NOPERM)
+  CONFIG_ERROR:   78,   // Missing / invalid config      (EX_CONFIG)
+  INTERRUPTED:   130,   // Ctrl-C / SIGINT
+} as const;
+
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
+
+// ── Base class ───────────────────────────────────────────────────────────────
+
 export class CliError extends Error {
   /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'AUTH_REQUIRED') */
   readonly code: string;
   /** Human-readable hint on how to fix the problem */
   readonly hint?: string;
+  /** Unix process exit code — defaults to 1 (generic error) */
+  readonly exitCode: ExitCode;
 
-  constructor(code: string, message: string, hint?: string) {
+  constructor(code: string, message: string, hint?: string, exitCode: ExitCode = EXIT_CODES.GENERIC_ERROR) {
     super(message);
     this.name = new.target.name;
     this.code = code;
     this.hint = hint;
+    this.exitCode = exitCode;
   }
 }
 
+// ── Typed subclasses ─────────────────────────────────────────────────────────
+
 export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
 
 export class BrowserConnectError extends CliError {
   readonly kind: BrowserConnectKind;
   constructor(message: string, hint?: string, kind: BrowserConnectKind = 'unknown') {
-    super('BROWSER_CONNECT', message, hint);
+    super('BROWSER_CONNECT', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
     this.kind = kind;
   }
 }
 
 export class AdapterLoadError extends CliError {
-  constructor(message: string, hint?: string) { super('ADAPTER_LOAD', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('ADAPTER_LOAD', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
+  }
 }
 
 export class CommandExecutionError extends CliError {
-  constructor(message: string, hint?: string) { super('COMMAND_EXEC', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('COMMAND_EXEC', message, hint, EXIT_CODES.GENERIC_ERROR);
+  }
 }
 
 export class ConfigError extends CliError {
-  constructor(message: string, hint?: string) { super('CONFIG', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('CONFIG', message, hint, EXIT_CODES.CONFIG_ERROR);
+  }
 }
 
 export class AuthRequiredError extends CliError {
   readonly domain: string;
   constructor(domain: string, message?: string) {
-    super('AUTH_REQUIRED', message ?? `Not logged in to ${domain}`, `Please open Chrome and log in to https://${domain}`);
+    super(
+      'AUTH_REQUIRED',
+      message ?? `Not logged in to ${domain}`,
+      `Please open Chrome and log in to https://${domain}`,
+      EXIT_CODES.NOPERM,
+    );
     this.domain = domain;
   }
 }
@@ -56,27 +104,40 @@ export class TimeoutError extends CliError {
       'TIMEOUT',
       `${label} timed out after ${seconds}s`,
       hint ?? 'Try again, or increase timeout with OPENCLI_BROWSER_COMMAND_TIMEOUT env var',
+      EXIT_CODES.TEMPFAIL,
     );
   }
 }
 
 export class ArgumentError extends CliError {
-  constructor(message: string, hint?: string) { super('ARGUMENT', message, hint); }
+  constructor(message: string, hint?: string) {
+    super('ARGUMENT', message, hint, EXIT_CODES.USAGE_ERROR);
+  }
 }
 
 export class EmptyResultError extends CliError {
   constructor(command: string, hint?: string) {
-    super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'The page structure may have changed, or you may need to log in');
+    super(
+      'EMPTY_RESULT',
+      `${command} returned no data`,
+      hint ?? 'The page structure may have changed, or you may need to log in',
+      EXIT_CODES.EMPTY_RESULT,
+    );
   }
 }
 
 export class SelectorError extends CliError {
   constructor(selector: string, hint?: string) {
-    super('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.');
+    super(
+      'SELECTOR',
+      `Could not find element: ${selector}`,
+      hint ?? 'The page UI may have changed. Please report this issue.',
+      EXIT_CODES.GENERIC_ERROR,
+    );
   }
 }
 
-// ── Utilities ───────────────────────────────────────────────────────────
+// ── Utilities ───────────────────────────────────────────────────────────────
 
 /** Extract a human-readable message from an unknown caught value. */
 export function getErrorMessage(error: unknown): string {

package/src/external-clis.yaml

@@ -30,6 +30,23 @@
   install:
     default: "npm install -g @larksuite/cli"
 
+- name: dws
+  binary: dws
+  description: "DingTalk Workspace CLI — messages, docs, calendar, contacts and more for humans and AI agents"
+  homepage: "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+  tags: [dingtalk, collaboration, productivity, ai-agent]
+  install:
+    mac: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+    linux: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+
+- name: wecom-cli
+  binary: wecom-cli
+  description: "WeCom/企业微信 CLI — contacts, todos, meetings, messages, calendar, docs and smart sheets for AI agents"
+  homepage: "https://github.com/WecomTeam/wecom-cli"
+  tags: [wecom, wechat-work, collaboration, productivity, ai-agent]
+  install:
+    default: "npm install -g @wecom/cli"
+
 - name: vercel
   binary: vercel
   description: "Vercel CLI — deploy projects, manage domains, env vars, logs and serverless functions"