@jackwener/opencli 1.6.8 → 1.6.9

package/dist/clis/zhihu/target.test.js

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import { CliError } from '@jackwener/opencli/errors';
+import { __test__ } from './target.js';
+describe('zhihu target parser', () => {
+    it('parses typed answer IDs into canonical targets', () => {
+        expect(__test__.parseTarget('answer:123:456')).toEqual({
+            kind: 'answer',
+            questionId: '123',
+            id: '456',
+            url: 'https://www.zhihu.com/question/123/answer/456',
+        });
+    });
+    it('parses question URLs into canonical targets', () => {
+        expect(__test__.parseTarget('https://www.zhihu.com/question/123456')).toEqual({
+            kind: 'question',
+            id: '123456',
+            url: 'https://www.zhihu.com/question/123456',
+        });
+    });
+    it('canonicalizes question URLs with query strings and fragments', () => {
+        expect(__test__.parseTarget('https://www.zhihu.com/question/123456/?utm_source=share#answer-1')).toEqual({
+            kind: 'question',
+            id: '123456',
+            url: 'https://www.zhihu.com/question/123456',
+        });
+    });
+    it('canonicalizes answer URLs with query strings and fragments', () => {
+        expect(__test__.parseTarget('https://www.zhihu.com/question/123456/answer/7890/?utm_psn=1#comment')).toEqual({
+            kind: 'answer',
+            questionId: '123456',
+            id: '7890',
+            url: 'https://www.zhihu.com/question/123456/answer/7890',
+        });
+    });
+    it('canonicalizes article URLs with query strings and fragments', () => {
+        expect(__test__.parseTarget('https://zhuanlan.zhihu.com/p/98765/?utm_id=1#heading')).toEqual({
+            kind: 'article',
+            id: '98765',
+            url: 'https://zhuanlan.zhihu.com/p/98765',
+        });
+    });
+    it('canonicalizes user URLs with trailing slash, query strings, and fragments', () => {
+        expect(__test__.parseTarget('https://www.zhihu.com/people/example-user/?utm_term=share#about')).toEqual({
+            kind: 'user',
+            slug: 'example-user',
+            url: 'https://www.zhihu.com/people/example-user',
+        });
+    });
+    it('rejects non-https Zhihu URLs', () => {
+        expect(() => __test__.parseTarget('http://www.zhihu.com/question/123456')).toThrowError(CliError);
+    });
+    it('rejects Zhihu URLs with embedded credentials', () => {
+        expect(() => __test__.parseTarget('https://user@www.zhihu.com/question/123456')).toThrowError(CliError);
+    });
+    it('rejects Zhihu URLs with explicit ports', () => {
+        expect(() => __test__.parseTarget('https://www.zhihu.com:8443/question/123456')).toThrowError(CliError);
+    });
+    it('rejects Zhihu URLs with empty authority usernames', () => {
+        expect(() => __test__.parseTarget('https://@www.zhihu.com/question/123456')).toThrowError(CliError);
+    });
+    it('rejects Zhihu URLs with empty authority username and password markers', () => {
+        expect(() => __test__.parseTarget('https://:@www.zhihu.com/question/123456')).toThrowError(CliError);
+    });
+    it('rejects ambiguous bare numeric IDs', () => {
+        expect(() => __test__.parseTarget('123456')).toThrowError(CliError);
+    });
+    it('rejects malformed typed IDs', () => {
+        expect(() => __test__.parseTarget('answer:123')).toThrowError(/answer:<questionId>:<answerId>/);
+    });
+    it('rejects unsupported target kinds per command', () => {
+        expect(() => __test__.assertAllowedKinds('follow', {
+            kind: 'article',
+            id: '1',
+            url: 'https://zhuanlan.zhihu.com/p/1',
+        })).toThrowError(/follow/);
+    });
+});

package/dist/clis/zhihu/write-shared.d.ts

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import type { IPage } from '@jackwener/opencli/types';
+type FileStatLike = {
+    isFile(): boolean;
+};
+type FileReaderDeps = {
+    readFile: typeof readFile;
+    stat: (path: string) => Promise<FileStatLike>;
+    decodeUtf8: (raw: Buffer) => string;
+};
+type IdentityRootLike = {
+    querySelectorAll(selector: string): ArrayLike<unknown>;
+};
+export declare function resolveCurrentUserSlugFromDom(state: unknown, documentRoot: IdentityRootLike): string | null;
+export declare function requireExecute(kwargs: Record<string, unknown>): void;
+export declare function resolvePayload(kwargs: Record<string, unknown>, deps?: FileReaderDeps): Promise<string>;
+export declare function resolveCurrentUserIdentity(page: Pick<IPage, 'evaluate'>): Promise<string>;
+export declare function buildResultRow(message: string, targetType: string, target: string, outcome: 'applied' | 'already_applied' | 'created', extra?: Record<string, unknown>): {
+    status: string;
+    outcome: "created" | "applied" | "already_applied";
+    message: string;
+    target_type: string;
+    target: string;
+}[];
+export declare const __test__: {
+    requireExecute: typeof requireExecute;
+    resolvePayload: typeof resolvePayload;
+    resolveCurrentUserIdentity: typeof resolveCurrentUserIdentity;
+    resolveCurrentUserSlugFromDom: typeof resolveCurrentUserSlugFromDom;
+    buildResultRow: typeof buildResultRow;
+};
+export {};

package/dist/clis/zhihu/write-shared.js

@@ -0,0 +1,221 @@
+import { readFile, stat } from 'node:fs/promises';
+import { CliError } from '@jackwener/opencli/errors';
+const RESULT_ROW_RESERVED_KEYS = new Set(['status', 'outcome', 'message', 'target_type', 'target']);
+const NAV_SCOPE_SELECTOR = 'header, nav, [role="banner"], [role="navigation"]';
+const PROFILE_LINK_SELECTOR = 'a[href^="/people/"]';
+const AVATAR_SELECTOR = 'img, [class*="Avatar"], [data-testid*="avatar" i], [aria-label*="头像"]';
+const SELF_LABEL_TOKENS = ['我', '我的', '个人主页'];
+const EXPLICIT_IDENTITY_META_TOKEN_GROUPS = [
+    ['self'],
+    ['current', 'user'],
+    ['account', 'profile'],
+    ['my', 'profile'],
+    ['my', 'account'],
+];
+const IN_PAGE_EXPLICIT_IDENTITY_META_TOKEN_GROUPS = JSON.stringify(EXPLICIT_IDENTITY_META_TOKEN_GROUPS);
+function defaultFileReaderDeps() {
+    return {
+        readFile,
+        stat: (path) => stat(path),
+        decodeUtf8: (raw) => new TextDecoder('utf-8', { fatal: true }).decode(raw),
+    };
+}
+function hasExplicitIdentityLabel(text) {
+    const normalized = text.toLowerCase();
+    return SELF_LABEL_TOKENS.some((token) => text.includes(token)) || normalized.includes('my profile') || normalized.includes('my account');
+}
+function tokenizeIdentityMeta(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function hasExplicitIdentityMeta(text) {
+    const tokens = new Set(tokenizeIdentityMeta(text));
+    return EXPLICIT_IDENTITY_META_TOKEN_GROUPS.some((group) => group.every((token) => tokens.has(token)));
+}
+function isIdentityRootLike(value) {
+    return typeof value === 'object' && value !== null && 'querySelectorAll' in value
+        && typeof value.querySelectorAll === 'function';
+}
+function isIdentityNodeLike(value) {
+    return typeof value === 'object' && value !== null
+        && 'getAttribute' in value
+        && 'querySelector' in value
+        && typeof value.getAttribute === 'function'
+        && typeof value.querySelector === 'function';
+}
+function resolveSlugFromState(state) {
+    const slugFromState = state?.topstory?.me?.slug
+        || state?.me?.slug
+        || state?.initialState?.me?.slug;
+    return typeof slugFromState === 'string' && slugFromState ? slugFromState : null;
+}
+function getSlugFromIdentityLink(node, allowAvatarOnly) {
+    const href = node.getAttribute('href') || '';
+    const match = href.match(/^\/people\/([A-Za-z0-9_-]+)/);
+    if (!match)
+        return null;
+    const aria = node.getAttribute('aria-label') || '';
+    const title = node.getAttribute('title') || '';
+    const testid = node.getAttribute('data-testid') || '';
+    const className = node.getAttribute('class') || '';
+    const rel = node.getAttribute('rel') || '';
+    const identityLabel = `${aria} ${title} ${node.textContent || ''}`;
+    const identityMeta = `${testid} ${className} ${rel}`;
+    const hasAvatar = Boolean(node.querySelector(AVATAR_SELECTOR));
+    const isExplicitIdentityLabel = hasExplicitIdentityLabel(identityLabel);
+    const isExplicitIdentityMeta = hasExplicitIdentityMeta(identityMeta);
+    if (isExplicitIdentityLabel || isExplicitIdentityMeta)
+        return match[1];
+    if (allowAvatarOnly && hasAvatar)
+        return match[1];
+    return null;
+}
+function findCurrentUserSlugFromRoots(roots, allowAvatarOnly) {
+    for (const root of roots) {
+        for (const node of Array.from(root.querySelectorAll(PROFILE_LINK_SELECTOR)).filter(isIdentityNodeLike)) {
+            const slug = getSlugFromIdentityLink(node, allowAvatarOnly);
+            if (slug)
+                return slug;
+        }
+    }
+    return null;
+}
+export function resolveCurrentUserSlugFromDom(state, documentRoot) {
+    const slugFromState = resolveSlugFromState(state);
+    if (slugFromState)
+        return slugFromState;
+    const navScopes = Array.from(documentRoot.querySelectorAll(NAV_SCOPE_SELECTOR)).filter(isIdentityRootLike);
+    return findCurrentUserSlugFromRoots(navScopes, true) || findCurrentUserSlugFromRoots([documentRoot], false);
+}
+export function requireExecute(kwargs) {
+    if (!kwargs.execute) {
+        throw new CliError('INVALID_INPUT', 'This Zhihu write command requires --execute');
+    }
+}
+export async function resolvePayload(kwargs, deps = defaultFileReaderDeps()) {
+    const text = typeof kwargs.text === 'string' ? kwargs.text : undefined;
+    const file = typeof kwargs.file === 'string' ? kwargs.file : undefined;
+    if (text && file) {
+        throw new CliError('INVALID_INPUT', 'Use either <text> or --file, not both');
+    }
+    let resolved = text ?? '';
+    if (file) {
+        let fileStat;
+        try {
+            fileStat = await deps.stat(file);
+        }
+        catch {
+            throw new CliError('INVALID_INPUT', `File not found: ${file}`);
+        }
+        if (!fileStat.isFile()) {
+            throw new CliError('INVALID_INPUT', `File must be a readable text file: ${file}`);
+        }
+        let raw;
+        try {
+            raw = await deps.readFile(file);
+        }
+        catch {
+            throw new CliError('INVALID_INPUT', `File could not be read: ${file}`);
+        }
+        try {
+            resolved = deps.decodeUtf8(raw);
+        }
+        catch {
+            throw new CliError('INVALID_INPUT', `File could not be decoded as UTF-8 text: ${file}`);
+        }
+    }
+    if (!resolved.trim()) {
+        throw new CliError('INVALID_INPUT', 'Payload cannot be empty or whitespace only');
+    }
+    return resolved;
+}
+function buildResolveCurrentUserIdentityJs() {
+    return `(() => {
+    const selfLabelTokens = ${JSON.stringify(SELF_LABEL_TOKENS)};
+    const explicitIdentityMetaTokenGroups = ${IN_PAGE_EXPLICIT_IDENTITY_META_TOKEN_GROUPS};
+    const navScopeSelector = ${JSON.stringify(NAV_SCOPE_SELECTOR)};
+    const profileLinkSelector = ${JSON.stringify(PROFILE_LINK_SELECTOR)};
+    const avatarSelector = ${JSON.stringify(AVATAR_SELECTOR)};
+
+    const hasExplicitIdentityLabel = (text) => {
+      const normalized = String(text || '').toLowerCase();
+      return selfLabelTokens.some((token) => String(text || '').includes(token))
+        || normalized.includes('my profile')
+        || normalized.includes('my account');
+    };
+
+    const tokenizeIdentityMeta = (text) => String(text || '')
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter(Boolean);
+
+    const hasExplicitIdentityMeta = (text) => {
+      const tokens = new Set(tokenizeIdentityMeta(text));
+      return explicitIdentityMetaTokenGroups.some((group) => group.every((token) => tokens.has(token)));
+    };
+
+    const getSlugFromIdentityLink = (node, allowAvatarOnly) => {
+      const href = node.getAttribute('href') || '';
+      const match = href.match(/^\\/people\\/([A-Za-z0-9_-]+)/);
+      if (!match) return null;
+
+      const aria = node.getAttribute('aria-label') || '';
+      const title = node.getAttribute('title') || '';
+      const testid = node.getAttribute('data-testid') || '';
+      const className = node.getAttribute('class') || '';
+      const rel = node.getAttribute('rel') || '';
+      const identityLabel = \`\${aria} \${title} \${node.textContent || ''}\`;
+      const identityMeta = \`\${testid} \${className} \${rel}\`;
+      const hasAvatar = Boolean(node.querySelector(avatarSelector));
+
+      if (hasExplicitIdentityLabel(identityLabel) || hasExplicitIdentityMeta(identityMeta)) return match[1];
+      if (allowAvatarOnly && hasAvatar) return match[1];
+      return null;
+    };
+
+    const findCurrentUserSlugFromRoots = (roots, allowAvatarOnly) => {
+      for (const root of roots) {
+        for (const node of Array.from(root.querySelectorAll(profileLinkSelector))) {
+          const slug = getSlugFromIdentityLink(node, allowAvatarOnly);
+          if (slug) return slug;
+        }
+      }
+      return null;
+    };
+
+    const scopedGlobal = globalThis;
+    const state = scopedGlobal.__INITIAL_STATE__ || (scopedGlobal.window && scopedGlobal.window.__INITIAL_STATE__) || null;
+    const slugFromState = state && (state.topstory && state.topstory.me && state.topstory.me.slug)
+      || (state && state.me && state.me.slug)
+      || (state && state.initialState && state.initialState.me && state.initialState.me.slug);
+    if (typeof slugFromState === 'string' && slugFromState) return { slug: slugFromState };
+
+    const navScopes = Array.from(document.querySelectorAll(navScopeSelector));
+    const slug = findCurrentUserSlugFromRoots(navScopes, true) || findCurrentUserSlugFromRoots([document], false);
+    return slug ? { slug } : null;
+  })()`;
+}
+export async function resolveCurrentUserIdentity(page) {
+    const identity = await page.evaluate(buildResolveCurrentUserIdentityJs());
+    if (!identity?.slug) {
+        throw new CliError('ACTION_NOT_AVAILABLE', 'Could not resolve the logged-in Zhihu user identity before write');
+    }
+    return identity.slug;
+}
+export function buildResultRow(message, targetType, target, outcome, extra = {}) {
+    for (const key of Object.keys(extra)) {
+        if (RESULT_ROW_RESERVED_KEYS.has(key)) {
+            throw new CliError('INVALID_INPUT', `Result extra field cannot overwrite reserved key: ${key}`);
+        }
+    }
+    return [{ status: 'success', outcome, message, target_type: targetType, target, ...extra }];
+}
+export const __test__ = {
+    requireExecute,
+    resolvePayload,
+    resolveCurrentUserIdentity,
+    resolveCurrentUserSlugFromDom,
+    buildResultRow,
+};

package/dist/clis/zhihu/write-shared.test.d.ts

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

package/dist/clis/zhihu/write-shared.test.js

@@ -0,0 +1,175 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { describe, expect, it, vi } from 'vitest';
+import { CliError } from '@jackwener/opencli/errors';
+import { __test__ } from './write-shared.js';
+class FakeNode {
+    attrs;
+    textContent;
+    hasAvatar;
+    constructor(attrs, textContent = null, hasAvatar = false) {
+        this.attrs = attrs;
+        this.textContent = textContent;
+        this.hasAvatar = hasAvatar;
+    }
+    getAttribute(name) {
+        return this.attrs[name] ?? null;
+    }
+    querySelector(selector) {
+        if (this.hasAvatar && selector.includes('img'))
+            return {};
+        return null;
+    }
+}
+class FakeRoot {
+    selectors;
+    constructor(selectors) {
+        this.selectors = selectors;
+    }
+    querySelectorAll(selector) {
+        return this.selectors[selector] ?? [];
+    }
+}
+function createPageForDom(documentRoot, state = undefined) {
+    return {
+        evaluate: vi.fn().mockImplementation(async (js) => {
+            const previousDocument = globalThis.document;
+            const previousWindow = globalThis.window;
+            const previousState = globalThis.__INITIAL_STATE__;
+            const windowObject = { __INITIAL_STATE__: state };
+            try {
+                Object.assign(globalThis, {
+                    document: documentRoot,
+                    window: windowObject,
+                    __INITIAL_STATE__: state,
+                });
+                return globalThis.eval(js);
+            }
+            finally {
+                Object.assign(globalThis, {
+                    document: previousDocument,
+                    window: previousWindow,
+                    __INITIAL_STATE__: previousState,
+                });
+            }
+        }),
+    };
+}
+describe('zhihu write shared helpers', () => {
+    it('rejects missing --execute', () => {
+        expect(() => __test__.requireExecute({})).toThrowError(CliError);
+    });
+    it('accepts a non-empty text payload', async () => {
+        await expect(__test__.resolvePayload({ text: 'hello' })).resolves.toBe('hello');
+    });
+    it('rejects whitespace-only payloads', async () => {
+        await expect(__test__.resolvePayload({ text: '   ' })).rejects.toMatchObject({ code: 'INVALID_INPUT' });
+    });
+    it('rejects missing file payloads as INVALID_INPUT', async () => {
+        await expect(__test__.resolvePayload({ file: join(tmpdir(), 'zhihu-write-shared-missing.txt') })).rejects.toMatchObject({
+            code: 'INVALID_INPUT',
+            message: expect.stringContaining('File not found'),
+        });
+    });
+    it('rejects invalid UTF-8 file payloads as INVALID_INPUT', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'zhihu-write-shared-'));
+        const file = join(dir, 'payload.txt');
+        await writeFile(file, Buffer.from([0xc3, 0x28]));
+        try {
+            await expect(__test__.resolvePayload({ file })).rejects.toMatchObject({
+                code: 'INVALID_INPUT',
+                message: expect.stringContaining('decoded as UTF-8'),
+            });
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    it('rejects generic file read failures as INVALID_INPUT', async () => {
+        const dir = await mkdtemp(join(tmpdir(), 'zhihu-write-shared-'));
+        const file = join(dir, 'payload.txt');
+        await writeFile(file, 'hello');
+        try {
+            await expect(__test__.resolvePayload({ file }, {
+                stat: async () => ({ isFile: () => true }),
+                readFile: async () => {
+                    throw new Error('boom');
+                },
+                decodeUtf8: (raw) => new TextDecoder('utf-8', { fatal: true }).decode(raw),
+            })).rejects.toMatchObject({
+                code: 'INVALID_INPUT',
+                message: expect.stringContaining('could not be read'),
+            });
+        }
+        finally {
+            await rm(dir, { recursive: true, force: true });
+        }
+    });
+    it('prefers the state slug before DOM fallback', async () => {
+        const documentRoot = new FakeRoot({
+            'header, nav, [role="banner"], [role="navigation"]': [],
+            'a[href^="/people/"]': [new FakeNode({ href: '/people/not-used', 'data-testid': 'profile-link' }, null, true)],
+        });
+        expect(__test__.resolveCurrentUserSlugFromDom({ me: { slug: 'alice' } }, documentRoot)).toBe('alice');
+    });
+    it('accepts nav avatar links as a conservative fallback', async () => {
+        const navRoot = new FakeRoot({
+            'a[href^="/people/"]': [new FakeNode({ href: '/people/alice' }, null, true)],
+        });
+        const documentRoot = new FakeRoot({
+            'header, nav, [role="banner"], [role="navigation"]': [navRoot],
+            'a[href^="/people/"]': [],
+        });
+        expect(__test__.resolveCurrentUserSlugFromDom(undefined, documentRoot)).toBe('alice');
+    });
+    it('accepts document-wide fallback only for explicit account/profile signals', async () => {
+        const documentRoot = new FakeRoot({
+            'header, nav, [role="banner"], [role="navigation"]': [],
+            'a[href^="/people/"]': [
+                new FakeNode({ href: '/people/alice', 'data-testid': 'account-profile-link' }),
+            ],
+        });
+        expect(__test__.resolveCurrentUserSlugFromDom(undefined, documentRoot)).toBe('alice');
+    });
+    it('does not accept a document-wide author avatar link as current-user fallback', async () => {
+        const documentRoot = new FakeRoot({
+            'header, nav, [role="banner"], [role="navigation"]': [],
+            'a[href^="/people/"]': [new FakeNode({ href: '/people/author-1' }, 'Author', true)],
+        });
+        expect(__test__.resolveCurrentUserSlugFromDom(undefined, documentRoot)).toBeNull();
+    });
+    it('does not accept generic document metadata like user or dropdown alone', async () => {
+        const documentRoot = new FakeRoot({
+            'header, nav, [role="banner"], [role="navigation"]': [],
+            'a[href^="/people/"]': [
+                new FakeNode({ href: '/people/author-1', 'data-testid': 'user-menu-dropdown' }, 'Author'),
+            ],
+        });
+        expect(__test__.resolveCurrentUserSlugFromDom(undefined, documentRoot)).toBeNull();
+    });
+    it('freezes a stable current-user identity before write', async () => {
+        const navRoot = new FakeRoot({
+            'a[href^="/people/"]': [new FakeNode({ href: '/people/alice' }, null, true)],
+        });
+        const documentRoot = new FakeRoot({
+            'header, nav, [role="banner"], [role="navigation"]': [navRoot],
+            'a[href^="/people/"]': [],
+        });
+        const page = createPageForDom(documentRoot);
+        await expect(__test__.resolveCurrentUserIdentity(page)).resolves.toBe('alice');
+    });
+    it('rejects when current-user identity cannot be resolved', async () => {
+        const documentRoot = new FakeRoot({
+            'header, nav, [role="banner"], [role="navigation"]': [],
+            'a[href^="/people/"]': [],
+        });
+        const page = createPageForDom(documentRoot);
+        await expect(__test__.resolveCurrentUserIdentity(page)).rejects.toMatchObject({
+            code: 'ACTION_NOT_AVAILABLE',
+        });
+    });
+    it('rejects reserved buildResultRow extra keys', () => {
+        expect(() => __test__.buildResultRow('done', 'question', '123', 'applied', { status: 'oops' })).toThrowError(CliError);
+    });
+});

package/dist/src/browser/bridge.d.ts

@@ -18,4 +18,6 @@ export declare class BrowserBridge implements IBrowserFactory {
     }): Promise<IPage>;
     close(): Promise<void>;
     private _ensureDaemon;
+    /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
+    private _pollUntilReady;
 }

package/dist/src/browser/bridge.js

@@ -6,8 +6,9 @@ import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { Page } from './page.js';
-import { fetchDaemonStatus, isExtensionConnected } from './daemon-client.js';
+import { getDaemonHealth } from './daemon-client.js';
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { BrowserConnectError } from '../errors.js';
 const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
 /**
  * Browser factory: manages daemon lifecycle and provides IPage instances.
@@ -52,25 +53,22 @@ export class BrowserBridge {
     async _ensureDaemon(timeoutSeconds) {
         const effectiveSeconds = (timeoutSeconds && timeoutSeconds > 0) ? timeoutSeconds : Math.ceil(DAEMON_SPAWN_TIMEOUT / 1000);
         const timeoutMs = effectiveSeconds * 1000;
-        // Single status check instead of two separate fetchDaemonStatus() calls
-        const status = await fetchDaemonStatus();
-        // Fast path: extension already connected
-        if (status?.extensionConnected)
+        const health = await getDaemonHealth();
+        // Fast path: everything ready
+        if (health.state === 'ready')
             return;
         // Daemon running but no extension — wait for extension with progress
-        if (status !== null) {
+        if (health.state === 'no-extension') {
             if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
                 process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
                 process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
             }
-            const deadline = Date.now() + timeoutMs;
-            while (Date.now() < deadline) {
-                await new Promise(resolve => setTimeout(resolve, 200));
-                if (await isExtensionConnected())
-                    return;
-            }
-            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
-                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+            if (await this._pollUntilReady(timeoutMs))
+                return;
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
+                '  Then run: opencli doctor', 'extension-not-connected');
         }
         // No daemon — spawn one
         const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -91,19 +89,27 @@ export class BrowserBridge {
             env: { ...process.env },
         });
         this._daemonProc.unref();
-        // Wait for daemon + extension with faster polling
+        // Wait for daemon + extension
+        if (await this._pollUntilReady(timeoutMs))
+            return;
+        const finalHealth = await getDaemonHealth();
+        if (finalHealth.state === 'no-extension') {
+            throw new BrowserConnectError('Browser Bridge extension not connected', 'Install the Browser Bridge:\n' +
+                '  1. Download: https://github.com/jackwener/opencli/releases\n' +
+                '  2. In Chrome or Chromium, open chrome://extensions → Developer Mode → Load unpacked\n' +
+                '  Then run: opencli doctor', 'extension-not-connected');
+        }
+        throw new BrowserConnectError('Failed to start opencli daemon', `Try running manually:\n  node ${daemonPath}\nMake sure port ${DEFAULT_DAEMON_PORT} is available.`, 'daemon-not-running');
+    }
+    /** Poll getDaemonHealth() until state is 'ready' or deadline is reached. */
+    async _pollUntilReady(timeoutMs) {
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             await new Promise(resolve => setTimeout(resolve, 200));
-            if (await isExtensionConnected())
-                return;
-        }
-        if ((await fetchDaemonStatus()) !== null) {
-            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
-                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+            const h = await getDaemonHealth();
+            if (h.state === 'ready')
+                return true;
         }
-        throw new Error('Failed to start opencli daemon. Try running manually:\n' +
-            `  node ${daemonPath}\n` +
-            `Make sure port ${DEFAULT_DAEMON_PORT} is available.`);
+        return false;
     }
 }

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

@@ -50,17 +50,26 @@ export interface DaemonStatus {
 export declare function fetchDaemonStatus(opts?: {
     timeout?: number;
 }): Promise<DaemonStatus | null>;
+export type DaemonHealth = {
+    state: 'stopped';
+    status: null;
+} | {
+    state: 'no-extension';
+    status: DaemonStatus;
+} | {
+    state: 'ready';
+    status: DaemonStatus;
+};
+/**
+ * Unified daemon health check — single entry point for all status queries.
+ * Replaces isDaemonRunning(), isExtensionConnected(), and checkDaemonStatus().
+ */
+export declare function getDaemonHealth(opts?: {
+    timeout?: number;
+}): Promise<DaemonHealth>;
 export declare function requestDaemonShutdown(opts?: {
     timeout?: number;
 }): Promise<boolean>;
-/**
- * Check if daemon is running.
- */
-export declare function isDaemonRunning(): Promise<boolean>;
-/**
- * Check if daemon is running AND the extension is connected.
- */
-export declare function isExtensionConnected(): Promise<boolean>;
 /**
  * Send a command to the daemon and wait for a result.
  * Retries up to 4 times: network errors retry at 500ms,