@sovovs/bycli 2.1.11 → 2.1.13

package/clis/weixin/_wechat/crawler-runtime.js

@@ -0,0 +1,34 @@
+import crawler from '@sovovs/wechat-article-crawler';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
+
+const {
+  CrawlerError,
+  collectArticles,
+  createWechatApi,
+  isTrustedWechatArticleUrl,
+  saveArticles,
+} = crawler;
+
+export {
+  CrawlerError,
+  collectArticles,
+  createWechatApi,
+  isTrustedWechatArticleUrl,
+  saveArticles,
+};
+
+export async function callCrawler(operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (!(error instanceof CrawlerError)) throw error;
+
+    if (error.code === 'INVALID_ARGUMENT') {
+      throw new ArgumentError(error.message);
+    }
+    if (error.code === 'AUTH_REQUIRED') {
+      throw new AuthRequiredError('mp.weixin.qq.com', error.message);
+    }
+    throw new CommandExecutionError(error.message);
+  }
+}

package/clis/weixin/articles.js

@@ -1,8 +1,7 @@
 import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { readEnvironmentCredentials, resolveBrowserCredentials } from './_wechat/auth-session.js';
-import { collectArticles } from './_wechat/article-service.js';
-import { createWechatApi } from './_wechat/wechat-api.js';
+import { callCrawler, collectArticles, createWechatApi } from './_wechat/crawler-runtime.js';
 import { readAuthSource } from './_wechat/args.js';
 
 const DOMAIN = 'mp.weixin.qq.com';
@@ -24,8 +23,10 @@ export const articlesCommand = cli({
     const authSource = readAuthSource(args);
     const credentials = authSource === 'env'
       ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
-    const { fetchPage } = createWechatApi(credentials);
-    const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
+    const { articles } = await callCrawler(async () => {
+      const { fetchPage } = createWechatApi(credentials);
+      return collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
+    });
     if (articles.length === 0) throw new EmptyResultError('weixin articles', `No published articles were found for ${fakeid}.`);
     return articles.map(article => ({
       title: article.title, author: article.author || null, digest: article.digest || null,

package/clis/weixin/save-articles.js

@@ -2,10 +2,11 @@ import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs
 import { MAX_WECHAT_HTML_BYTES } from '@sovovs/bycli/download/wechat-article';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { readEnvironmentCredentials, resolveBrowserCredentials } from './_wechat/auth-session.js';
-import { collectArticles, isTrustedWechatArticleUrl } from './_wechat/article-service.js';
-import { saveArticles } from './_wechat/save-service.js';
-import { createWechatApi } from './_wechat/wechat-api.js';
+import {
+  callCrawler, collectArticles, createWechatApi, isTrustedWechatArticleUrl, saveArticles,
+} from './_wechat/crawler-runtime.js';
 import { readAuthSource } from './_wechat/args.js';
+import { wechatArticleToMarkdown } from './_wechat/markdown.js';
 
 const DOMAIN = 'mp.weixin.qq.com';
 const browserRequired = args => readAuthSource(args) === 'browser';
@@ -165,12 +166,18 @@ export const saveArticlesCommand = cli({
     const authSource = readAuthSource(args);
     const credentials = authSource === 'env'
       ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
-    const { fetchPage } = createWechatApi(credentials);
-    const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
     const articleHtmlDownloader = createArticleHtmlDownloader({ authSource, page });
-    const rows = await saveArticles({
-      articles, accountName: String(args.name ?? '').trim(),
-      outputDir: args.output ?? './weixin-articles', fetchArticleHtml: articleHtmlDownloader,
+    const rows = await callCrawler(async () => {
+      const { fetchPage } = createWechatApi(credentials);
+      const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
+      return saveArticles({
+        articles, accountName: String(args.name ?? '').trim(),
+        outputDir: args.output ?? './weixin-articles', fetchArticleHtml: articleHtmlDownloader,
+        buildMarkdown: (article, html) => wechatArticleToMarkdown({
+          html, title: article.title, accountName: String(args.name ?? '').trim(), author: article.author,
+          publishedAt: article.publishedAt, digest: article.digest, url: article.url,
+        }), existingFilePolicy: 'suffix',
+      });
     });
     return rows.map(row => ({
       title: row.title, status: row.status, stage: row.stage || null, path: row.saved || null,

package/dist/src/browser/daemon-client.d.ts

@@ -87,6 +87,27 @@ export interface BrowserProfileStatus {
     pending: number;
     lastSeenAt?: number;
 }
+export type DaemonStatusProbe = {
+    kind: 'status';
+    status: DaemonStatus;
+} | {
+    kind: 'stopped';
+} | {
+    kind: 'timeout';
+} | {
+    kind: 'http_error';
+    statusCode: number;
+} | {
+    kind: 'invalid_response';
+} | {
+    kind: 'config_error';
+} | {
+    kind: 'network_error';
+};
+export declare function probeDaemonStatus(opts?: {
+    timeout?: number;
+    contextId?: string;
+}): Promise<DaemonStatusProbe>;
 export declare function fetchDaemonStatus(opts?: {
     timeout?: number;
     contextId?: string;

package/dist/src/browser/daemon-client.js

@@ -3,12 +3,10 @@
  *
  * Provides a typed send() function that posts a Command and returns a Result.
  */
-import { DEFAULT_DAEMON_PORT } from '../constants.js';
 import { sleep } from '../utils.js';
+import { resolveDaemonPort } from './daemon-config.js';
 import { classifyBrowserError } from './errors.js';
 import { resolveProfileContextId } from './profile.js';
-const DAEMON_PORT = parseInt(process.env.BYCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 const BYCLI_HEADERS = { 'X-byCLI': '1' };
 let _idCounter = 0;
 function generateId() {
@@ -24,32 +22,69 @@ export class BrowserCommandError extends Error {
         this.name = 'BrowserCommandError';
     }
 }
-async function requestDaemon(pathname, init) {
+async function consumeDaemonResponse(pathname, init, consume, port) {
     const { timeout = 2000, headers, ...rest } = init ?? {};
+    const portResolution = port === undefined ? resolveDaemonPort() : { ok: true, port };
+    if (!portResolution.ok)
+        throw new Error('Invalid BYCLI_DAEMON_PORT configuration');
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        return await fetch(`${DAEMON_URL}${pathname}`, {
+        const response = await fetch(`http://127.0.0.1:${portResolution.port}${pathname}`, {
             ...rest,
             headers: { ...BYCLI_HEADERS, ...headers },
             signal: controller.signal,
         });
+        return await consume(response);
     }
     finally {
         clearTimeout(timer);
     }
 }
-export async function fetchDaemonStatus(opts) {
+async function requestDaemon(pathname, init) {
+    return consumeDaemonResponse(pathname, init, async (response) => response);
+}
+function errorCode(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const candidate = error;
+    if (typeof candidate.code === 'string')
+        return candidate.code;
+    return errorCode(candidate.cause);
+}
+export async function probeDaemonStatus(opts) {
+    const portResolution = resolveDaemonPort();
+    if (!portResolution.ok)
+        return { kind: 'config_error' };
     try {
         const params = opts?.contextId ? `?contextId=${encodeURIComponent(opts.contextId)}` : '';
-        const res = await requestDaemon(`/status${params}`, { timeout: opts?.timeout ?? 2000 });
-        if (!res.ok)
-            return null;
-        return await res.json();
+        return await consumeDaemonResponse(`/status${params}`, { timeout: opts?.timeout ?? 2000 }, async (res) => {
+            if (!res.ok)
+                return { kind: 'http_error', statusCode: res.status };
+            try {
+                return { kind: 'status', status: await res.json() };
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'AbortError')
+                    throw error;
+                return { kind: 'invalid_response' };
+            }
+        }, portResolution.port);
     }
-    catch {
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError')
+            return { kind: 'timeout' };
+        if (errorCode(error) === 'ECONNREFUSED')
+            return { kind: 'stopped' };
+        return { kind: 'network_error' };
+    }
+}
+export async function fetchDaemonStatus(opts) {
+    const result = await probeDaemonStatus(opts);
+    if (result.kind !== 'status') {
         return null;
     }
+    return result.status;
 }
 /**
  * Unified daemon health check — single entry point for all status queries.

package/dist/src/browser/daemon-config.d.ts

@@ -0,0 +1,9 @@
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+export type DaemonPortResolution = {
+    ok: true;
+    port: number;
+} | {
+    ok: false;
+    port: typeof DEFAULT_DAEMON_PORT;
+};
+export declare function resolveDaemonPort(raw?: string | undefined): DaemonPortResolution;

package/dist/src/browser/daemon-config.js

@@ -0,0 +1,12 @@
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+export function resolveDaemonPort(raw = process.env.BYCLI_DAEMON_PORT) {
+    if (raw === undefined)
+        return { ok: true, port: DEFAULT_DAEMON_PORT };
+    if (!/^\d+$/.test(raw))
+        return { ok: false, port: DEFAULT_DAEMON_PORT };
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return { ok: false, port: DEFAULT_DAEMON_PORT };
+    }
+    return { ok: true, port };
+}

package/dist/src/cli.js

@@ -2958,7 +2958,9 @@ cli({
     daemonCmd
         .command('status')
         .description('Show daemon status')
-        .action(async () => { await daemonStatus(); });
+        .option('--json', 'Output stable machine-readable JSON')
+        .option('--verbose', 'Include process and profile diagnostics in JSON output')
+        .action(async (opts) => { await daemonStatus(opts); });
     daemonCmd
         .command('stop')
         .description('Stop the daemon')

package/dist/src/commands/daemon-status.d.ts

@@ -0,0 +1,60 @@
+import type { DaemonStatusProbe } from '../browser/daemon-client.js';
+export declare const DAEMON_STATUS_SCHEMA_VERSION: "1.0";
+export type DaemonStatusState = 'stopped' | 'daemon_stale' | 'extension_disconnected' | 'profile_required' | 'profile_disconnected' | 'ready' | 'degraded';
+export interface DaemonStatusIssue {
+    code: string;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    remediation?: {
+        type: 'command';
+        command: string[];
+    };
+}
+export interface DaemonStatusReport {
+    schemaVersion: typeof DAEMON_STATUS_SCHEMA_VERSION;
+    command: 'daemon.status';
+    ok: boolean;
+    state: DaemonStatusState;
+    cli: {
+        version: string;
+    };
+    daemon: {
+        state: 'stopped' | 'running' | 'unknown';
+        version: string | null;
+        port: number;
+        stale: boolean;
+        pid?: number;
+        uptimeSeconds?: number;
+        memoryMB?: number;
+    };
+    extension: {
+        state: 'unknown' | 'disconnected' | 'connected';
+        version: string | null;
+        compatibility: 'unknown' | 'compatible' | 'incompatible';
+    };
+    profiles: {
+        connectedCount: number;
+        selectionRequired: boolean;
+        selectedContextId?: string | null;
+        items?: Array<{
+            contextId: string;
+            alias?: string;
+            selected: boolean;
+            extensionVersion: string | null;
+        }>;
+    };
+    issues: DaemonStatusIssue[];
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface DaemonStatusReportOptions {
+    cliVersion: string;
+    port: number;
+    verbose?: boolean;
+    /** Profile aliases in the persisted alias -> contextId form. */
+    profileAliases?: Record<string, string>;
+}
+export declare function buildDaemonStatusErrorReport(options: DaemonStatusReportOptions, code: string, message: string): DaemonStatusReport;
+export declare function buildDaemonStatusReport(probe: DaemonStatusProbe, options: DaemonStatusReportOptions): DaemonStatusReport;

package/dist/src/commands/daemon-status.js

@@ -0,0 +1,195 @@
+import { isDaemonStale } from '../browser/daemon-version.js';
+import { satisfiesRange } from '../plugin-manifest.js';
+export const DAEMON_STATUS_SCHEMA_VERSION = '1.0';
+function baseReport(options) {
+    return {
+        schemaVersion: DAEMON_STATUS_SCHEMA_VERSION,
+        command: 'daemon.status',
+        ok: true,
+        state: 'stopped',
+        cli: { version: options.cliVersion },
+        daemon: { state: 'stopped', version: null, port: options.port, stale: false },
+        extension: { state: 'unknown', version: null, compatibility: 'unknown' },
+        profiles: { connectedCount: 0, selectionRequired: false },
+        issues: [],
+    };
+}
+function failureReport(options, code, message) {
+    const result = baseReport(options);
+    result.ok = false;
+    result.state = 'degraded';
+    result.daemon.state = 'unknown';
+    result.error = { code, message };
+    return result;
+}
+export function buildDaemonStatusErrorReport(options, code, message) {
+    return failureReport(options, code, message);
+}
+function isOptionalString(value) {
+    return value === undefined || typeof value === 'string';
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === 'boolean';
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isProfileStatus(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const profile = value;
+    return typeof profile.contextId === 'string'
+        && typeof profile.extensionConnected === 'boolean'
+        && isFiniteNumber(profile.pending)
+        && isOptionalString(profile.extensionVersion)
+        && isOptionalString(profile.extensionCompatRange);
+}
+function isDaemonStatus(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const status = value;
+    return status.ok === true
+        && isFiniteNumber(status.pid)
+        && isFiniteNumber(status.uptime)
+        && typeof status.extensionConnected === 'boolean'
+        && isFiniteNumber(status.pending)
+        && isFiniteNumber(status.memoryMB)
+        && isFiniteNumber(status.port)
+        && isOptionalString(status.daemonVersion)
+        && isOptionalString(status.extensionVersion)
+        && isOptionalString(status.extensionCompatRange)
+        && isOptionalString(status.contextId)
+        && isOptionalBoolean(status.profileRequired)
+        && isOptionalBoolean(status.profileDisconnected)
+        && (status.profiles === undefined
+            || (Array.isArray(status.profiles) && status.profiles.every(isProfileStatus)));
+}
+function compatibilityOf(status, cliVersion) {
+    if (!status.extensionConnected || !status.extensionVersion || !status.extensionCompatRange) {
+        return 'unknown';
+    }
+    return satisfiesRange(cliVersion, status.extensionCompatRange) ? 'compatible' : 'incompatible';
+}
+function aliasForContextId(aliases, contextId) {
+    return Object.entries(aliases).find(([, id]) => id === contextId)?.[0];
+}
+function probeFailure(probe) {
+    switch (probe.kind) {
+        case 'timeout':
+            return { code: 'daemon_status_timeout', message: 'Timed out while requesting daemon status.' };
+        case 'http_error':
+            return { code: 'daemon_http_error', message: `Daemon status request failed with HTTP ${probe.statusCode}.` };
+        case 'invalid_response':
+            return { code: 'invalid_daemon_response', message: 'The daemon returned an invalid status response.' };
+        case 'config_error':
+            return { code: 'invalid_daemon_config', message: 'BYCLI_DAEMON_PORT must be an integer from 1 to 65535.' };
+        case 'network_error':
+            return { code: 'daemon_unreachable', message: 'The daemon status endpoint could not be reached.' };
+    }
+}
+export function buildDaemonStatusReport(probe, options) {
+    if (probe.kind === 'stopped')
+        return baseReport(options);
+    if (probe.kind !== 'status') {
+        const failure = probeFailure(probe);
+        return failureReport(options, failure.code, failure.message);
+    }
+    if (!isDaemonStatus(probe.status)) {
+        return failureReport(options, 'invalid_daemon_response', 'The daemon returned an invalid status response.');
+    }
+    const status = probe.status;
+    const result = baseReport(options);
+    const stale = isDaemonStale(status, options.cliVersion);
+    const compatibility = compatibilityOf(status, options.cliVersion);
+    const connectedProfiles = status.profiles?.filter((profile) => profile.extensionConnected) ?? [];
+    result.daemon = {
+        state: 'running',
+        version: status.daemonVersion ?? null,
+        port: status.port,
+        stale,
+        ...(options.verbose && {
+            pid: status.pid,
+            uptimeSeconds: status.uptime,
+            memoryMB: status.memoryMB,
+        }),
+    };
+    result.extension = {
+        state: status.extensionConnected ? 'connected' : 'disconnected',
+        version: status.extensionVersion ?? null,
+        compatibility,
+    };
+    result.profiles = {
+        connectedCount: connectedProfiles.length,
+        selectionRequired: status.profileRequired === true,
+        ...(options.verbose && {
+            selectedContextId: status.contextId ?? null,
+            items: (status.profiles ?? []).map((profile) => {
+                const alias = aliasForContextId(options.profileAliases ?? {}, profile.contextId);
+                return {
+                    contextId: profile.contextId,
+                    ...(alias !== undefined && { alias }),
+                    selected: profile.contextId === status.contextId,
+                    extensionVersion: profile.extensionVersion ?? null,
+                };
+            }),
+        }),
+    };
+    if (stale) {
+        result.issues.push({
+            code: 'daemon_stale',
+            severity: 'warning',
+            message: 'The daemon version does not match the CLI version.',
+            remediation: { type: 'command', command: ['bycli', 'daemon', 'restart'] },
+        });
+    }
+    if (!status.extensionConnected) {
+        result.issues.push({
+            code: 'extension_disconnected',
+            severity: 'warning',
+            message: 'The Browser Bridge extension is not connected.',
+        });
+    }
+    else if (!status.extensionVersion) {
+        result.issues.push({
+            code: 'extension_version_missing',
+            severity: 'warning',
+            message: 'The connected Browser Bridge extension did not report its version.',
+        });
+    }
+    if (compatibility === 'incompatible') {
+        result.issues.push({
+            code: 'extension_incompatible',
+            severity: 'warning',
+            message: 'The CLI version is incompatible with the Browser Bridge extension.',
+        });
+    }
+    if (status.profileRequired) {
+        result.issues.push({
+            code: 'profile_selection_required',
+            severity: 'warning',
+            message: 'Multiple Browser Bridge profiles are connected and no profile is selected.',
+            remediation: { type: 'command', command: ['bycli', 'profile', 'list'] },
+        });
+    }
+    if (status.profileDisconnected) {
+        result.issues.push({
+            code: 'selected_profile_disconnected',
+            severity: 'warning',
+            message: 'The selected Browser Bridge profile is disconnected.',
+            remediation: { type: 'command', command: ['bycli', 'profile', 'list'] },
+        });
+    }
+    if (stale)
+        result.state = 'daemon_stale';
+    else if (status.profileRequired)
+        result.state = 'profile_required';
+    else if (status.profileDisconnected)
+        result.state = 'profile_disconnected';
+    else if (!status.extensionConnected)
+        result.state = 'extension_disconnected';
+    else if (compatibility === 'incompatible')
+        result.state = 'degraded';
+    else
+        result.state = 'ready';
+    return result;
+}

package/dist/src/commands/daemon-status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/commands/daemon.d.ts

@@ -4,6 +4,12 @@
  *   bycli daemon stop   — graceful shutdown
  *   bycli daemon restart — graceful shutdown, then start a fresh daemon
  */
-export declare function daemonStatus(): Promise<void>;
+export interface DaemonStatusOptions {
+    json?: boolean;
+    verbose?: boolean;
+    /** Pre-validated fast-path usage failure; keeps --json output machine-readable. */
+    usageError?: string;
+}
+export declare function daemonStatus(options?: DaemonStatusOptions): Promise<void>;
 export declare function daemonStop(): Promise<void>;
 export declare function daemonRestart(): Promise<void>;

package/dist/src/commands/daemon.js

@@ -4,13 +4,57 @@
  *   bycli daemon stop   — graceful shutdown
  *   bycli daemon restart — graceful shutdown, then start a fresh daemon
  */
-import { fetchDaemonStatus, requestDaemonShutdown } from '../browser/daemon-client.js';
+import { fetchDaemonStatus, probeDaemonStatus, requestDaemonShutdown } from '../browser/daemon-client.js';
+import { resolveDaemonPort } from '../browser/daemon-config.js';
 import { restartDaemon } from '../browser/daemon-lifecycle.js';
+import { loadProfileConfig } from '../browser/profile.js';
 import { formatDuration } from '../download/progress.js';
+import { EXIT_CODES } from '../errors.js';
 import { log } from '../logger.js';
 import { PKG_VERSION } from '../version.js';
 import { formatDaemonVersion, isDaemonStale } from '../browser/daemon-version.js';
-export async function daemonStatus() {
+import { buildDaemonStatusErrorReport, buildDaemonStatusReport } from './daemon-status.js';
+function configuredDaemonPort() {
+    return resolveDaemonPort().port;
+}
+function jsonStatusExitCode(errorCode) {
+    if (!errorCode)
+        return EXIT_CODES.SUCCESS;
+    if (errorCode === 'daemon_status_timeout')
+        return EXIT_CODES.TEMPFAIL;
+    if (errorCode === 'invalid_daemon_response' || errorCode === 'invalid_daemon_config') {
+        return EXIT_CODES.CONFIG_ERROR;
+    }
+    return EXIT_CODES.GENERIC_ERROR;
+}
+export async function daemonStatus(options = {}) {
+    if (options.verbose && !options.json) {
+        console.error('Error: --verbose requires --json.');
+        process.exitCode = EXIT_CODES.USAGE_ERROR;
+        return;
+    }
+    if (options.json) {
+        if (options.usageError) {
+            const report = buildDaemonStatusErrorReport({
+                cliVersion: PKG_VERSION,
+                port: configuredDaemonPort(),
+            }, 'invalid_arguments', options.usageError);
+            console.log(JSON.stringify(report));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const probe = await probeDaemonStatus();
+        const profileConfig = loadProfileConfig();
+        const report = buildDaemonStatusReport(probe, {
+            cliVersion: PKG_VERSION,
+            port: configuredDaemonPort(),
+            verbose: options.verbose,
+            profileAliases: profileConfig.aliases,
+        });
+        console.log(JSON.stringify(report));
+        process.exitCode = jsonStatusExitCode(report.error?.code);
+        return;
+    }
     const status = await fetchDaemonStatus();
     if (!status) {
         console.log('Daemon: not running');

package/dist/src/main-daemon-status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/main.js

@@ -39,6 +39,29 @@ if (typeof globalThis.Bun === 'undefined' && !isSupportedNodeVersion(process.ver
     ].join('\n'));
     process.exit(EXIT_CODES.CONFIG_ERROR);
 }
+// Fast path: passive machine-readable daemon status. Keep this before discovery,
+// hooks, proxy installation, and update checks so stdout/stderr remain API-safe
+// and the only network operation is the loopback daemon status request.
+const daemonStatusArgs = argv.slice(2);
+if (argv[0] === 'daemon'
+    && argv[1] === 'status'
+    && daemonStatusArgs.includes('--json')) {
+    const unsupportedArgs = daemonStatusArgs.filter((arg) => arg !== '--json' && arg !== '--verbose');
+    const { daemonStatus } = await import('./commands/daemon.js');
+    await daemonStatus({
+        json: true,
+        verbose: daemonStatusArgs.includes('--verbose'),
+        ...(unsupportedArgs.length > 0 && {
+            usageError: `Unsupported daemon status argument(s): ${unsupportedArgs.join(', ')}`,
+        }),
+    });
+    // console.log() may still be buffered when stdout is piped. An empty queued
+    // write completes only after the preceding JSON line has drained.
+    await new Promise((resolve, reject) => {
+        process.stdout.write('', (error) => error ? reject(error) : resolve());
+    });
+    process.exit(process.exitCode ?? EXIT_CODES.SUCCESS);
+}
 // Fast path: --version (only when it's the top-level intent, not passed to a subcommand)
 // e.g. `bycli --version` or `bycli -V`, but NOT `bycli gh --version`
 if (argv[0] === '--version' || argv[0] === '-V') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovovs/bycli",
-  "version": "2.1.11",
+  "version": "2.1.13",
   "publishConfig": {
     "access": "public"
   },
@@ -90,6 +90,7 @@
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
     "@sovovs/bycli-recorder-core": "^0.1.0",
+    "@sovovs/wechat-article-crawler": "^1.1.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
     "js-yaml": "^4.1.0",

package/scripts/check-package-install.mjs

@@ -3,6 +3,7 @@ import { execFileSync } from 'node:child_process';
 import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -58,8 +59,24 @@ try {
     project, 'node_modules/@sovovs/bycli/package.json',
   ), 'utf8'));
   assert.equal(mainManifest.dependencies?.['@sovovs/bycli-recorder-core'], '^0.1.0');
+  assert.equal(mainManifest.dependencies?.['@sovovs/wechat-article-crawler'], '^1.1.0');
 
   const coreDirectory = join(project, 'node_modules/@sovovs/bycli-recorder-core');
+  const crawlerDirectoryInstalled = join(project, 'node_modules/@sovovs/wechat-article-crawler');
+  const crawlerManifest = JSON.parse(readFileSync(
+    join(crawlerDirectoryInstalled, 'package.json'), 'utf8',
+  ));
+  assert.equal(crawlerManifest.version, '1.1.2');
+  const projectRequire = createRequire(join(project, 'package.json'));
+  const crawlerEntry = projectRequire.resolve('@sovovs/wechat-article-crawler');
+  const crawlerModule = await import(pathToFileURL(crawlerEntry).href);
+  const crawlerApi = crawlerModule.default ?? crawlerModule;
+  for (const name of [
+    'CrawlerError', 'createWechatApi', 'collectArticles',
+    'isTrustedWechatArticleUrl', 'saveArticles',
+  ]) {
+    assert.ok(crawlerApi[name], `crawler root API missing ${name}`);
+  }
   const recorderEntry = join(
     project, 'node_modules/@sovovs/bycli/dist/src/browser/analyze.js',
   );

package/clis/weixin/_wechat/article-service.js

@@ -1,124 +0,0 @@
-import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
-
-export const MAX_PAGES = 100;
-export const MAX_PAGE_SIZE = 10;
-export const MAX_ARTICLES = 1000;
-
-export function isTrustedWechatArticleUrl(value) {
-  try {
-    const url = new URL(value);
-    return url.protocol === 'https:'
-      && url.hostname === 'mp.weixin.qq.com'
-      && url.port === ''
-      && url.username === ''
-      && url.password === ''
-      && (url.pathname === '/s' || url.pathname.startsWith('/s/'));
-  } catch {
-    return false;
-  }
-}
-
-/** @param {any} article */
-export function isUsableArticle(article) {
-  return Boolean(article)
-    && article.isDeleted !== true
-    && typeof article.url === 'string'
-    && isTrustedWechatArticleUrl(article.url)
-    && !article.url.includes('tempkey=');
-}
-
-function canonicalUrl(value) {
-  try {
-    const url = new URL(value);
-    url.hash = '';
-    return url.href;
-  } catch {
-    return value;
-  }
-}
-
-function publicArticle(article) {
-  return {
-    title: typeof article.title === 'string' ? article.title : '',
-    url: article.url,
-    publishedAt: typeof article.publishedAt === 'string' ? article.publishedAt : null,
-    digest: typeof article.digest === 'string' ? article.digest : '',
-    author: typeof article.author === 'string' ? article.author : '',
-  };
-}
-
-/**
- * @param {{fakeid:string,fetchPage:(input:{fakeid:string,begin:number,count:number})=>Promise<any>,limit?:number,maxPages?:number,pageSize?:number}} options
- */
-export async function collectArticles({ fakeid, fetchPage, limit, maxPages, pageSize = 10 }) {
-  for (const [name, value, maximum] of [
-    ['pageSize', pageSize, MAX_PAGE_SIZE],
-    ['limit', limit, MAX_ARTICLES],
-    ['maxPages', maxPages, MAX_PAGES],
-  ]) {
-    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
-      throw new ArgumentError(`${name} must be a positive safe integer`);
-    }
-    if (value !== undefined && value > maximum) {
-      throw new ArgumentError(`${name} must not exceed ${maximum}`);
-    }
-  }
-  const pageLimit = maxPages ?? MAX_PAGES;
-  const articleLimit = limit ?? MAX_ARTICLES;
-  const articles = [];
-  const seen = new Set();
-  let totalFromApi = 0;
-  let scanned = 0;
-  let invalid = 0;
-  let duplicates = 0;
-  let pages = 0;
-  let begin = 0;
-
-  while (true) {
-    const page = await fetchPage({ fakeid, begin, count: pageSize });
-    pages += 1;
-    const pageTotal = page?.total === undefined ? 0 : page.total;
-    if (!Number.isSafeInteger(pageTotal) || pageTotal < 0) {
-      throw new CommandExecutionError('WeChat article history returned invalid total metadata');
-    }
-    if (pages === 1) totalFromApi = pageTotal;
-    const rawArticles = Array.isArray(page?.articles) ? page.articles : [];
-    const publishItemCount = page?.publishItemCount === undefined ? 0 : page.publishItemCount;
-    if (!Number.isSafeInteger(publishItemCount) || publishItemCount < 0) {
-      throw new CommandExecutionError('WeChat article history returned invalid publish-item metadata');
-    }
-
-    for (const article of rawArticles) {
-      scanned += 1;
-      if (!isUsableArticle(article)) {
-        invalid += 1;
-        continue;
-      }
-      const canonical = canonicalUrl(article.url);
-      if (seen.has(canonical)) {
-        duplicates += 1;
-        continue;
-      }
-      seen.add(canonical);
-      articles.push(publicArticle(article));
-      if (articles.length >= articleLimit) break;
-    }
-
-    const reachedLimit = articles.length >= articleLimit;
-    const reachedMaxPages = pages >= pageLimit;
-    const reachedEnd = publishItemCount === 0
-      || publishItemCount < pageSize
-      || (totalFromApi > 0 && begin + publishItemCount >= totalFromApi);
-    if (reachedLimit || reachedMaxPages || reachedEnd) break;
-    const nextBegin = begin + pageSize;
-    if (!Number.isSafeInteger(nextBegin) || nextBegin <= begin) {
-      throw new CommandExecutionError('WeChat article pagination could not advance safely');
-    }
-    begin = nextBegin;
-  }
-
-  return {
-    articles,
-    summary: { totalFromApi, scanned, valid: articles.length, invalid, duplicates, pages },
-  };
-}

package/clis/weixin/_wechat/save-service.js

@@ -1,176 +0,0 @@
-import * as defaultFs from 'node:fs';
-import path from 'node:path';
-import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
-import { cleanMarkdownFilename, wechatArticleToMarkdown } from './markdown.js';
-
-export const MAX_FILENAME_ATTEMPTS = 100;
-
-function commandError(action, error) {
-  return new CommandExecutionError(`Failed to ${action}: ${error instanceof Error ? error.message : String(error)}`);
-}
-
-function assertInside(root, target) {
-  const relative = path.relative(root, target);
-  if (relative === '' || relative.startsWith(`..${path.sep}`) || relative === '..' || path.isAbsolute(relative)) {
-    throw new CommandExecutionError('Refusing to save an article outside the output directory');
-  }
-}
-
-function sameIdentity(left, right) {
-  return left.dev === right.dev && left.ino === right.ino;
-}
-
-function assertResolvedPathComponents(root, fsImpl) {
-  const parsed = path.parse(root);
-  let current = parsed.root;
-  for (const part of root.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
-    current = path.join(current, part);
-    const stat = fsImpl.lstatSync(current);
-    if (stat.isSymbolicLink?.()) throw new CommandExecutionError('Refusing to save through a symbolic link');
-  }
-}
-
-function assertRootIdentity(root, rootFd, rootIdentity, fsImpl) {
-  assertResolvedPathComponents(root, fsImpl);
-  const pathStat = fsImpl.lstatSync(root);
-  const fdStat = fsImpl.fstatSync(rootFd);
-  if (!pathStat.isDirectory?.() || !fdStat.isDirectory?.()
-      || !sameIdentity(pathStat, rootIdentity) || !sameIdentity(fdStat, rootIdentity)) {
-    throw new CommandExecutionError('Output directory identity changed during save');
-  }
-}
-
-function cleanupOpenedTarget(target, openedStat, fsImpl) {
-  try {
-    const current = fsImpl.lstatSync(target);
-    if (sameIdentity(current, openedStat) && !current.isSymbolicLink?.()) fsImpl.unlinkSync(target);
-  } catch {
-    // Fail closed; cleanup is best effort after identity mismatch.
-  }
-}
-
-function writeExclusive(root, rootFd, rootIdentity, target, markdown, fsImpl) {
-  const noFollow = defaultFs.constants.O_NOFOLLOW;
-  if (typeof noFollow !== 'number') {
-    throw new CommandExecutionError('Secure article saving is unavailable: O_NOFOLLOW is unsupported');
-  }
-  // The opened root fd plus its dev/ino is the authorization capability.
-  // Path checks detect namespace replacement, but cannot and need not prevent
-  // a same-privilege process from renaming that already-authorized inode.
-  assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-  let fd;
-  let openedStat;
-  try {
-    fd = fsImpl.openSync(target,
-      defaultFs.constants.O_CREAT | defaultFs.constants.O_EXCL | defaultFs.constants.O_WRONLY | noFollow,
-      0o600);
-    // Once open succeeds, this fd remains bound to that inode; later renames
-    // or symlink swaps cannot redirect its writes into a replacement root.
-    openedStat = fsImpl.fstatSync(fd);
-    if (!openedStat.isFile?.() || openedStat.isSymbolicLink?.()) {
-      throw new CommandExecutionError('Refusing to write a non-regular article target');
-    }
-    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-    const body = Buffer.from(markdown, 'utf8');
-    let offset = 0;
-    while (offset < body.length) {
-      const written = fsImpl.writeSync(fd, body, offset, body.length - offset);
-      if (!Number.isInteger(written) || written <= 0) throw new CommandExecutionError('Failed to write article bytes');
-      offset += written;
-    }
-    fsImpl.fsyncSync?.(fd);
-    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-  } catch (error) {
-    if (openedStat) cleanupOpenedTarget(target, openedStat, fsImpl);
-    throw error;
-  } finally {
-    if (fd !== undefined) fsImpl.closeSync(fd);
-  }
-}
-
-export async function saveArticles({ articles, accountName, outputDir, fetchArticleHtml, buildMarkdown = wechatArticleToMarkdown, fsImpl = defaultFs }) {
-  if (!Array.isArray(articles) || articles.length > 1000) {
-    throw new ArgumentError('articles must be an array of at most 1000 items');
-  }
-  const requestedRoot = path.resolve(outputDir);
-  try { fsImpl.mkdirSync(requestedRoot, { recursive: true }); } catch (error) { throw commandError('create output directory', error); }
-  let root;
-  try { root = fsImpl.realpathSync(requestedRoot); } catch (error) { throw commandError('resolve output directory', error); }
-  let rootFd;
-  let rootIdentity;
-  try {
-    assertResolvedPathComponents(root, fsImpl);
-    rootIdentity = fsImpl.lstatSync(root);
-    if (!rootIdentity.isDirectory?.() || rootIdentity.isSymbolicLink?.()) throw new Error('not a directory');
-    rootFd = fsImpl.openSync(root, defaultFs.constants.O_RDONLY);
-    const openedRoot = fsImpl.fstatSync(rootFd);
-    if (!openedRoot.isDirectory?.() || !sameIdentity(openedRoot, rootIdentity)) {
-      throw new CommandExecutionError('Output directory identity changed during secure open');
-    }
-    assertRootIdentity(root, rootFd, rootIdentity, fsImpl);
-  } catch (error) {
-    if (rootFd !== undefined) fsImpl.closeSync(rootFd);
-    if (error instanceof CommandExecutionError) throw error;
-    throw commandError('secure output directory', error);
-  }
-  const reserved = new Set();
-  const rows = [];
-
-  try {
-    for (const article of articles) {
-      let articleHtml;
-      try {
-        articleHtml = await fetchArticleHtml(article);
-      } catch (error) {
-        if (error instanceof AuthRequiredError) throw error;
-        rows.push({ title: article.title || '', url: article.url || '', status: 'failed', stage: 'download', saved: '', error: 'article download failed' });
-        continue;
-      }
-      let markdown;
-      try {
-        markdown = buildMarkdown({ html: articleHtml, title: article.title, accountName,
-          author: article.author, publishedAt: article.publishedAt, digest: article.digest, url: article.url });
-      } catch {
-        rows.push({ title: article.title || '', url: article.url || '', status: 'failed', stage: 'download', saved: '', error: 'invalid article content' });
-        continue;
-      }
-
-      let suffix = 1;
-      let target;
-      while (suffix <= MAX_FILENAME_ATTEMPTS) {
-        const suffixText = suffix === 1 ? '' : `-${suffix}`;
-        const name = `${cleanMarkdownFilename(article.title, 100, suffixText)}${suffixText}`;
-        target = path.resolve(root, `${name}.md`);
-        assertInside(root, target);
-        if (reserved.has(target)) { suffix += 1; continue; }
-        try {
-          const stat = fsImpl.lstatSync(target);
-          if (stat.isSymbolicLink?.()) throw new CommandExecutionError('Refusing to overwrite a symbolic link');
-          suffix += 1;
-          continue;
-        } catch (error) {
-          if (error instanceof CommandExecutionError) throw error;
-          if (error?.code !== 'ENOENT') throw commandError('inspect article target', error);
-        }
-        try {
-          writeExclusive(root, rootFd, rootIdentity, target, markdown, fsImpl);
-          reserved.add(target);
-          break;
-        } catch (error) {
-          if (error?.code === 'EEXIST') {
-            suffix += 1;
-            continue;
-          }
-          throw commandError('write article Markdown', error);
-        }
-      }
-      if (suffix > MAX_FILENAME_ATTEMPTS) {
-        throw new CommandExecutionError(`Failed to reserve an article filename after ${MAX_FILENAME_ATTEMPTS} attempts`);
-      }
-      rows.push({ title: article.title || '', url: article.url || '', status: 'saved', stage: null, saved: target, error: '' });
-    }
-  } finally {
-    fsImpl.closeSync(rootFd);
-  }
-  return rows;
-}

package/clis/weixin/_wechat/wechat-api.js

@@ -1,133 +0,0 @@
-import { AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
-import { buildSecretSet, redactText } from './redact.js';
-
-const DOMAIN = 'mp.weixin.qq.com';
-const ENDPOINT = `https://${DOMAIN}/cgi-bin/appmsgpublish`;
-
-function normalizedMessage(value) {
-  return String(value ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
-}
-
-function commandError(message) {
-  return new CommandExecutionError(redactText(message, []));
-}
-
-function parseNestedJson(value, label) {
-  if (typeof value !== 'string') return value;
-  try {
-    return JSON.parse(value);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw commandError(`WeChat ${label} is malformed: ${detail}`);
-  }
-}
-
-/** @param {unknown} data */
-export function parsePublishData(data) {
-  if (!data || typeof data !== 'object') {
-    throw new CommandExecutionError('WeChat article history returned an unreadable response');
-  }
-  const response = /** @type {Record<string, any>} */ (data);
-  const ret = response.base_resp?.ret;
-  const message = response.base_resp?.err_msg ?? response.base_resp?.err_msg_en ?? '';
-  if (ret === 200013 && normalizedMessage(message) === 'invalid credential') {
-    throw new AuthRequiredError(DOMAIN, 'WeChat article-history credentials have expired');
-  }
-  if (ret !== undefined && ret !== 0) {
-    throw new CommandExecutionError(`WeChat article history failed (ret=${String(ret)})`);
-  }
-  if (response.publish_page === undefined || response.publish_page === null || response.publish_page === '') {
-    return { total: 0, publishItemCount: 0, articles: [] };
-  }
-  const page = parseNestedJson(response.publish_page, 'publish_page');
-  if (!page || typeof page !== 'object' || !Array.isArray(page.publish_list)) {
-    throw new CommandExecutionError('WeChat article history returned an invalid publish page');
-  }
-  const total = page.total_count === undefined ? 0 : page.total_count;
-  if (!Number.isSafeInteger(total) || total < 0) {
-    throw new CommandExecutionError('WeChat article history returned invalid total metadata');
-  }
-  const articles = [];
-  for (const item of page.publish_list) {
-    const info = parseNestedJson(item?.publish_info ?? {}, 'publish_info');
-    if (!info || typeof info !== 'object' || !Array.isArray(info.appmsg_info)) {
-      throw new CommandExecutionError('WeChat article history returned invalid publish information');
-    }
-    const timestamp = info.sent_info?.time ?? info.publish_info?.create_time ?? 0;
-    let publishedAt = null;
-    if (timestamp !== 0) {
-      if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0) {
-        throw new CommandExecutionError('WeChat article history returned an invalid publish timestamp');
-      }
-      const date = new Date(timestamp * 1000);
-      if (!Number.isFinite(date.getTime())) {
-        throw new CommandExecutionError('WeChat article history returned an invalid publish timestamp');
-      }
-      publishedAt = date.toISOString();
-    }
-    for (const messageItem of info.appmsg_info) {
-      const article = messageItem && typeof messageItem === 'object' ? messageItem : {};
-      articles.push({
-        title: typeof article.title === 'string' ? article.title : '',
-        url: typeof article.content_url === 'string' ? article.content_url : '',
-        isDeleted: article.is_deleted === true,
-        timestamp,
-        publishedAt,
-        digest: typeof article.digest === 'string' ? article.digest : '',
-        author: typeof article.author === 'string' ? article.author : '',
-      });
-    }
-  }
-  return {
-    total,
-    publishItemCount: page.publish_list.length,
-    articles,
-  };
-}
-
-export function requestHeaders(cookie, token) {
-  return {
-    Accept: 'application/json, text/javascript, */*; q=0.01',
-    Cookie: cookie,
-    Origin: `https://${DOMAIN}`,
-    Referer: `https://${DOMAIN}/cgi-bin/appmsg?t=media/appmsg_edit_v2&action=edit&isNew=1&type=10&token=${encodeURIComponent(token)}&lang=zh_CN`,
-    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/143 Safari/537.36',
-    'X-Requested-With': 'XMLHttpRequest',
-  };
-}
-
-/**
- * @param {{token:string,cookie:string,timeoutMs?:number,fetchImpl?:typeof fetch}} options
- */
-export function createWechatApi({ token, cookie, timeoutMs = 30_000, fetchImpl = fetch }) {
-  const headers = requestHeaders(cookie, token);
-  const secrets = buildSecretSet({ token, cookie });
-
-  return {
-    async fetchPage({ fakeid, begin = 0, count = 10 }) {
-      const query = new URLSearchParams({
-        sub: 'list', begin: String(begin), count: String(count), fakeid, token,
-        lang: 'zh_CN', f: 'json', ajax: '1',
-      });
-      try {
-        const response = await fetchImpl(`${ENDPOINT}?${query}`, {
-          headers,
-          signal: AbortSignal.timeout(timeoutMs),
-        });
-        if (!response.ok) {
-          throw new CommandExecutionError(`WeChat article history request failed: HTTP ${response.status} ${response.statusText ?? ''}`.trim());
-        }
-        return parsePublishData(await response.json());
-      } catch (error) {
-        if (error instanceof AuthRequiredError && error.domain === DOMAIN) throw error;
-        const message = error instanceof Error ? error.message : String(error);
-        const hint = error && typeof error === 'object' && 'hint' in error && typeof error.hint === 'string'
-          ? error.hint : undefined;
-        throw new CommandExecutionError(
-          `WeChat article history request failed: ${redactText(message, secrets)}`,
-          hint ? redactText(hint, secrets) : undefined,
-        );
-      }
-    },
-  };
-}