@agentrhq/webcmd 0.1.1 → 0.1.2

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

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

package/dist/src/daemon.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT, buildCommandDispatchFailure, buildExtensionDisconnectFailure, commandResultUnknownMessage, getResponseCorsHeaders, } from './daemon-utils.js';
+describe('getResponseCorsHeaders', () => {
+    it('allows the packaged runtime origin to read /ping', () => {
+        expect(getResponseCorsHeaders('/ping', 'chrome-extension://abc123')).toEqual({
+            'Access-Control-Allow-Origin': 'chrome-extension://abc123',
+            Vary: 'Origin',
+        });
+    });
+    it('does not add CORS headers for ordinary web origins', () => {
+        expect(getResponseCorsHeaders('/ping', 'https://example.com')).toBeUndefined();
+    });
+    it('does not add CORS headers when origin is absent', () => {
+        expect(getResponseCorsHeaders('/ping')).toBeUndefined();
+    });
+    it('does not add CORS headers for command endpoints even from the packaged runtime origin', () => {
+        expect(getResponseCorsHeaders('/command', 'chrome-extension://abc123')).toBeUndefined();
+    });
+});
+describe('daemon command dispatch', () => {
+    it('uses a distinct command_result_unknown contract for ambiguous dispatched commands', () => {
+        expect(COMMAND_RESULT_UNKNOWN_CODE).toBe('command_result_unknown');
+        expect(commandResultUnknownMessage('navigate')).toContain('navigate command was dispatched');
+        expect(COMMAND_RESULT_UNKNOWN_HINT).toContain('Inspect the browser/session state');
+        expect(COMMAND_RESULT_UNKNOWN_HINT).toContain('Do not blindly retry write commands');
+    });
+    it('classifies dispatched extension disconnects as command_result_unknown', () => {
+        expect(buildExtensionDisconnectFailure({
+            contextId: 'work',
+            action: 'navigate',
+            dispatched: true,
+        })).toEqual({
+            message: 'Browser connection dropped after the navigate command was dispatched; it may have completed.',
+            errorCode: 'command_result_unknown',
+            errorHint: COMMAND_RESULT_UNKNOWN_HINT,
+            status: 503,
+            countAsCommandResultUnknown: true,
+        });
+    });
+    it('classifies pre-dispatch extension disconnects as profile_disconnected', () => {
+        expect(buildExtensionDisconnectFailure({
+            contextId: 'work',
+            action: 'navigate',
+            dispatched: false,
+        })).toMatchObject({
+            message: 'Browser profile "work" disconnected before command dispatch',
+            errorCode: 'profile_disconnected',
+            status: 503,
+            countAsCommandResultUnknown: false,
+        });
+    });
+    it('classifies ws.send dispatch failures as profile_disconnected', () => {
+        expect(buildCommandDispatchFailure('work')).toMatchObject({
+            message: 'Browser profile "work" disconnected before command dispatch',
+            errorCode: 'profile_disconnected',
+            status: 503,
+            countAsCommandResultUnknown: false,
+        });
+    });
+});

package/dist/src/discovery.d.ts

@@ -0,0 +1,46 @@
+/**
+ * CLI discovery: finds JS CLI definitions and registers them.
+ *
+ * Supports two modes:
+ * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
+ *    registers commands instantly. JS modules are loaded lazily only
+ *    when their command is executed.
+ * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
+ */
+/** User runtime directory: ~/.webcmd */
+export declare function getUserWebcmdDir(homeDir?: string): string;
+export declare function getUserClisDir(homeDir?: string): string;
+export declare function getPluginsDir(homeDir?: string): string;
+/** User runtime directory: ~/.webcmd */
+export declare const USER_WEBCMD_DIR: string;
+/** User CLIs directory: ~/.webcmd/clis */
+export declare const USER_CLIS_DIR: string;
+/** Plugins directory: ~/.webcmd/plugins/ */
+export declare const PLUGINS_DIR: string;
+/**
+ * Ensure ~/.webcmd/node_modules/<package> symlink exists so user CLIs can
+ * import runtime exports from the installed package.
+ *
+ * This is the sole resolution mechanism — adapters use package exports and
+ * Node.js resolves them through this symlink.
+ */
+export declare function ensureUserCliCompatShims(baseDir?: string): Promise<void>;
+/**
+ * Ensure the user adapters directory exists.
+ *
+ * With smart sync, ~/.webcmd/clis/ only holds files that differ from the
+ * package baseline (upstream-synced cache + autofix output + user overrides).
+ * Built-in adapters are loaded directly from the installed package.
+ */
+export declare function ensureUserAdapters(): Promise<void>;
+/**
+ * Discover and register CLI commands.
+ * Uses pre-compiled manifest when available for instant startup.
+ */
+export declare function discoverClis(...dirs: string[]): Promise<void>;
+/**
+ * Discover and register plugins from ~/.webcmd/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
+ */
+export declare function discoverPlugins(): Promise<void>;

package/dist/src/discovery.js

@@ -0,0 +1,341 @@
+/**
+ * CLI discovery: finds JS CLI definitions and registers them.
+ *
+ * Supports two modes:
+ * 1. FAST PATH (manifest): If a pre-compiled cli-manifest.json exists,
+ *    registers commands instantly. JS modules are loaded lazily only
+ *    when their command is executed.
+ * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { Strategy, registerCommand } from './registry.js';
+import { getErrorMessage } from './errors.js';
+import { log } from './logger.js';
+import { findPackageRoot, getCliManifestPath } from './package-paths.js';
+import { CONFIG_DIR_NAME, PACKAGE_NAME, PRODUCT_NAME } from './brand.js';
+/** User runtime directory: ~/.webcmd */
+export function getUserWebcmdDir(homeDir = os.homedir()) {
+    return path.join(homeDir, CONFIG_DIR_NAME);
+}
+export function getUserClisDir(homeDir = os.homedir()) {
+    return path.join(getUserWebcmdDir(homeDir), 'clis');
+}
+export function getPluginsDir(homeDir = os.homedir()) {
+    return path.join(getUserWebcmdDir(homeDir), 'plugins');
+}
+/** User runtime directory: ~/.webcmd */
+export const USER_WEBCMD_DIR = getUserWebcmdDir();
+/** User CLIs directory: ~/.webcmd/clis */
+export const USER_CLIS_DIR = getUserClisDir();
+/** Plugins directory: ~/.webcmd/plugins/ */
+export const PLUGINS_DIR = getPluginsDir();
+/** Matches files that register commands via cli() or lifecycle hooks */
+const PLUGIN_MODULE_PATTERN = /\b(?:cli|registerSiteAuthCommands|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;
+function parseStrategy(rawStrategy, fallback = Strategy.COOKIE) {
+    if (!rawStrategy)
+        return fallback;
+    const key = rawStrategy.toUpperCase();
+    return Strategy[key] ?? fallback;
+}
+const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
+function getSourcePackageExports() {
+    const pkgPath = path.join(PACKAGE_ROOT, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const exports = pkg.exports ?? {};
+    return Object.fromEntries(Object.entries(exports).map(([key, target]) => [
+        key,
+        target
+            .replace(/^\.\/dist\//, './')
+            .replace(/\.js$/, '.ts'),
+    ]));
+}
+async function pathIsSymlink(targetPath) {
+    try {
+        return (await fs.promises.lstat(targetPath)).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureSourcePackageShim(packageDir) {
+    const srcLink = path.join(packageDir, 'src');
+    const srcTarget = path.join(PACKAGE_ROOT, 'src');
+    const pkgJsonPath = path.join(packageDir, 'package.json');
+    const pkgJsonContent = `${JSON.stringify({
+        name: PACKAGE_NAME,
+        private: true,
+        type: 'module',
+        exports: getSourcePackageExports(),
+    }, null, 2)}\n`;
+    await fs.promises.mkdir(packageDir, { recursive: true });
+    try {
+        const existing = await fs.promises.readFile(pkgJsonPath, 'utf-8');
+        if (existing !== pkgJsonContent)
+            await fs.promises.writeFile(pkgJsonPath, pkgJsonContent, 'utf-8');
+    }
+    catch {
+        await fs.promises.writeFile(pkgJsonPath, pkgJsonContent, 'utf-8');
+    }
+    let needsSrcLink = true;
+    try {
+        const existing = await fs.promises.readlink(srcLink);
+        if (existing === srcTarget)
+            needsSrcLink = false;
+    }
+    catch { /* doesn't exist */ }
+    if (needsSrcLink) {
+        try {
+            await fs.promises.rm(srcLink, { recursive: true, force: true });
+        }
+        catch { /* doesn't exist */ }
+        const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
+        await fs.promises.symlink(srcTarget, srcLink, symlinkType);
+    }
+}
+/**
+ * Ensure ~/.webcmd/node_modules/<package> symlink exists so user CLIs can
+ * import runtime exports from the installed package.
+ *
+ * This is the sole resolution mechanism — adapters use package exports and
+ * Node.js resolves them through this symlink.
+ */
+export async function ensureUserCliCompatShims(baseDir = USER_WEBCMD_DIR) {
+    await fs.promises.mkdir(baseDir, { recursive: true });
+    // package.json for ESM resolution in ~/.webcmd/
+    const pkgJsonPath = path.join(baseDir, 'package.json');
+    const pkgJsonContent = `${JSON.stringify({ name: `${PRODUCT_NAME}-user-runtime`, private: true, type: 'module' }, null, 2)}\n`;
+    try {
+        const existing = await fs.promises.readFile(pkgJsonPath, 'utf-8');
+        if (existing !== pkgJsonContent)
+            await fs.promises.writeFile(pkgJsonPath, pkgJsonContent, 'utf-8');
+    }
+    catch {
+        await fs.promises.writeFile(pkgJsonPath, pkgJsonContent, 'utf-8');
+    }
+    // Create node_modules/<package> resolution pointing to the installed package root.
+    // Source checkouts do not have dist/, so they need a tiny package shim whose
+    // exports target src/ files instead.
+    const packageRoot = PACKAGE_ROOT;
+    const [scope, name] = PACKAGE_NAME.split('/');
+    const symlinkDir = path.join(baseDir, 'node_modules', scope);
+    const symlinkPath = path.join(symlinkDir, name);
+    const hasBuiltExports = fs.existsSync(path.join(packageRoot, 'dist', 'src', 'registry-api.js'));
+    try {
+        if (!hasBuiltExports) {
+            if (await pathIsSymlink(symlinkPath)) {
+                await fs.promises.rm(symlinkPath, { recursive: true, force: true });
+            }
+            await ensureSourcePackageShim(symlinkPath);
+            return;
+        }
+        let needsUpdate = true;
+        try {
+            const existing = await fs.promises.readlink(symlinkPath);
+            if (existing === packageRoot)
+                needsUpdate = false;
+        }
+        catch { /* doesn't exist */ }
+        if (needsUpdate) {
+            await fs.promises.mkdir(symlinkDir, { recursive: true });
+            try {
+                await fs.promises.rm(symlinkPath, { recursive: true, force: true });
+            }
+            catch { /* doesn't exist */ }
+            const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
+            await fs.promises.symlink(packageRoot, symlinkPath, symlinkType);
+        }
+    }
+    catch (err) {
+        log.warn(`Could not create symlink at ${symlinkPath}: ${getErrorMessage(err)}`);
+    }
+}
+/**
+ * Ensure the user adapters directory exists.
+ *
+ * With smart sync, ~/.webcmd/clis/ only holds files that differ from the
+ * package baseline (upstream-synced cache + autofix output + user overrides).
+ * Built-in adapters are loaded directly from the installed package.
+ */
+export async function ensureUserAdapters() {
+    await fs.promises.mkdir(USER_CLIS_DIR, { recursive: true });
+}
+/**
+ * Discover and register CLI commands.
+ * Uses pre-compiled manifest when available for instant startup.
+ */
+export async function discoverClis(...dirs) {
+    // Fast path: try manifest first (production / post-build)
+    for (const dir of dirs) {
+        const manifestPath = getCliManifestPath(dir);
+        try {
+            await fs.promises.access(manifestPath);
+            const loaded = await loadFromManifest(manifestPath, dir);
+            if (loaded)
+                continue; // Skip filesystem scan only when manifest is usable
+        }
+        catch {
+            // Fall through to filesystem scan
+        }
+        await discoverClisFromFs(dir);
+    }
+}
+/**
+ * Fast-path: register commands from pre-compiled manifest.
+ * TS modules are deferred — loaded lazily on first execution.
+ */
+async function loadFromManifest(manifestPath, clisDir) {
+    try {
+        const raw = await fs.promises.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(raw);
+        for (const entry of manifest) {
+            if (!entry.modulePath)
+                continue;
+            const modulePath = path.resolve(clisDir, entry.modulePath);
+            const cmd = {
+                site: entry.site,
+                name: entry.name,
+                aliases: entry.aliases,
+                description: entry.description ?? '',
+                access: entry.access,
+                example: entry.example,
+                domain: entry.domain,
+                strategy: parseStrategy(entry.strategy),
+                browser: entry.browser,
+                args: entry.args ?? [],
+                columns: entry.columns,
+                defaultFormat: entry.defaultFormat,
+                pipeline: entry.pipeline,
+                source: entry.sourceFile ? path.resolve(clisDir, entry.sourceFile) : modulePath,
+                navigateBefore: entry.navigateBefore,
+                siteSession: entry.siteSession,
+                defaultWindowMode: entry.defaultWindowMode,
+                _lazy: true,
+                _modulePath: modulePath,
+            };
+            // normalizeCommand inside registerCommand handles strategy → browser/navigateBefore
+            registerCommand(cmd);
+        }
+        return true;
+    }
+    catch (err) {
+        log.warn(`Failed to load manifest ${manifestPath}: ${getErrorMessage(err)}`);
+        return false;
+    }
+}
+/**
+ * Fallback: traditional filesystem scan (used during development with tsx).
+ */
+async function discoverClisFromFs(dir) {
+    try {
+        await fs.promises.access(dir);
+    }
+    catch {
+        return;
+    }
+    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    const sitePromises = entries
+        .filter(entry => entry.isDirectory())
+        .map(async (entry) => {
+        const site = entry.name;
+        const siteDir = path.join(dir, site);
+        const files = await fs.promises.readdir(siteDir);
+        await Promise.all(files.map(async (file) => {
+            const filePath = path.join(siteDir, file);
+            if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+                return;
+            }
+            if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
+                log.warn(`Ignoring TypeScript adapter ${filePath} — .ts adapters are no longer loaded. Rename to .js or convert to JavaScript.`);
+                return;
+            }
+            if (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js')) {
+                if (!(await isCliModule(filePath)))
+                    return;
+                await import(pathToFileURL(filePath).href).catch((err) => {
+                    log.warn(`Failed to load module ${filePath}: ${getErrorMessage(err)}`);
+                });
+            }
+        }));
+    });
+    await Promise.all(sitePromises);
+}
+/**
+ * Discover and register plugins from ~/.webcmd/plugins/.
+ * Each subdirectory is treated as a plugin (site = directory name).
+ * Files inside are scanned flat (no nested site subdirs).
+ */
+export async function discoverPlugins() {
+    try {
+        await fs.promises.access(PLUGINS_DIR);
+    }
+    catch {
+        return;
+    }
+    const entries = await fs.promises.readdir(PLUGINS_DIR, { withFileTypes: true });
+    await Promise.all(entries.map(async (entry) => {
+        const pluginDir = path.join(PLUGINS_DIR, entry.name);
+        if (!(await isDiscoverablePluginDir(entry, pluginDir)))
+            return;
+        await discoverPluginDir(pluginDir, entry.name);
+    }));
+}
+/**
+ * Flat scan: read ts/js files directly in a plugin directory.
+ * Unlike discoverClisFromFs, this does NOT expect nested site subdirectories.
+ */
+async function discoverPluginDir(dir, site) {
+    const files = await fs.promises.readdir(dir);
+    const fileSet = new Set(files);
+    await Promise.all(files.map(async (file) => {
+        const filePath = path.join(dir, file);
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+            return;
+        }
+        if (file.endsWith('.js') && !file.endsWith('.d.js')) {
+            if (!(await isCliModule(filePath)))
+                return;
+            await import(pathToFileURL(filePath).href).catch((err) => {
+                log.warn(`Plugin ${site}/${file}: ${getErrorMessage(err)}`);
+            });
+        }
+        else if (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts')) {
+            const jsFile = file.replace(/\.ts$/, '.js');
+            // Prefer compiled .js — skip the .ts source file
+            if (fileSet.has(jsFile))
+                return;
+            // No compiled .js found — cannot import raw .ts in production Node.js.
+            // This typically means esbuild transpilation failed during plugin install.
+            log.warn(`Plugin ${site}/${file}: no compiled .js found. ` +
+                `Run "webcmd plugin update ${site}" to re-transpile, or install esbuild.`);
+        }
+    }));
+}
+async function isCliModule(filePath) {
+    try {
+        const source = await fs.promises.readFile(filePath, 'utf-8');
+        return PLUGIN_MODULE_PATTERN.test(source);
+    }
+    catch (err) {
+        log.warn(`Failed to inspect module ${filePath}: ${getErrorMessage(err)}`);
+        return false;
+    }
+}
+async function isDiscoverablePluginDir(entry, pluginDir) {
+    if (entry.isDirectory())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return (await fs.promises.stat(pluginDir)).isDirectory();
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            log.warn(`Failed to inspect plugin link ${pluginDir}: ${getErrorMessage(err)}`);
+        }
+        return false;
+    }
+}

package/dist/src/doctor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * webcmd doctor — diagnose browser connectivity.
+ *
+ * Simplified for the daemon-based architecture.
+ */
+import type { BrowserProfileStatus } from './browser/daemon-transport.js';
+import { type AdapterShadow } from './adapter-shadow.js';
+export type DoctorOptions = {
+    yes?: boolean;
+    cliVersion?: string;
+};
+export type ConnectivityResult = {
+    ok: boolean;
+    error?: string;
+    durationMs: number;
+};
+export type DoctorReport = {
+    cliVersion?: string;
+    daemonRunning: boolean;
+    daemonFlaky?: boolean;
+    daemonStale?: boolean;
+    daemonVersion?: string;
+    runtimeConnected: boolean;
+    runtimeFlaky?: boolean;
+    runtimeName?: string;
+    runtimeVersion?: string;
+    connectivity?: ConnectivityResult;
+    profiles?: BrowserProfileStatus[];
+    adapterShadows?: AdapterShadow[];
+    issues: string[];
+};
+/**
+ * Test connectivity by attempting a real browser command.
+ */
+export declare function checkConnectivity(opts?: {
+    timeout?: number;
+}): Promise<ConnectivityResult>;
+export declare function runBrowserDoctor(opts?: DoctorOptions): Promise<DoctorReport>;
+export declare function renderBrowserDoctorReport(report: DoctorReport): string;

package/dist/src/doctor.js

@@ -0,0 +1,168 @@
+/**
+ * webcmd doctor — diagnose browser connectivity.
+ *
+ * Simplified for the daemon-based architecture.
+ */
+import { DEFAULT_DAEMON_PORT } from './constants.js';
+import { BrowserBridge } from './browser/index.js';
+import { getDaemonHealth } from './browser/daemon-transport.js';
+import { getErrorMessage } from './errors.js';
+import { getRuntimeLabel } from './runtime-detect.js';
+import { aliasForContextId, loadProfileConfig } from './browser/profile.js';
+import { formatDaemonVersion, isDaemonStale, staleDaemonIssue } from './browser/daemon-version.js';
+import { findShadowedUserAdapters, formatAdapterShadowIssue } from './adapter-shadow.js';
+const DOCTOR_LIVE_TIMEOUT_SECONDS = 8;
+const DOCTOR_SESSION = '__doctor__';
+/**
+ * Test connectivity by attempting a real browser command.
+ */
+export async function checkConnectivity(opts) {
+    const start = Date.now();
+    try {
+        const bridge = new BrowserBridge();
+        const page = await bridge.connect({
+            timeout: opts?.timeout ?? DOCTOR_LIVE_TIMEOUT_SECONDS,
+            session: DOCTOR_SESSION,
+            surface: 'browser',
+        });
+        try {
+            // Try a simple eval to verify end-to-end connectivity.
+            await page.evaluate('1 + 1');
+            await page.closeWindow?.();
+        }
+        finally {
+            await bridge.close();
+        }
+        return { ok: true, durationMs: Date.now() - start };
+    }
+    catch (err) {
+        return { ok: false, error: getErrorMessage(err), durationMs: Date.now() - start };
+    }
+}
+export async function runBrowserDoctor(opts = {}) {
+    // Live connectivity check is the core of doctor — it doubles as auto-start
+    // (bridge.connect spawns daemon) and validates end-to-end browser bridge health.
+    const connectivity = await checkConnectivity();
+    // Single status read *after* connectivity side-effects settle.
+    const health = await getDaemonHealth();
+    const daemonRunning = health.state !== 'stopped';
+    const runtimeConnected = health.state === 'ready';
+    const daemonFlaky = connectivity.ok && !daemonRunning;
+    const runtimeFlaky = connectivity.ok && daemonRunning && !runtimeConnected;
+    const daemonStale = isDaemonStale(health.status, opts.cliVersion);
+    const profiles = health.status?.profiles;
+    const runtimeName = health.status?.runtimeName;
+    const runtimeVersion = health.status?.runtimeVersion;
+    const adapterShadows = findShadowedUserAdapters();
+    const issues = [];
+    if (daemonFlaky) {
+        issues.push('Daemon connectivity is unstable. The live browser test succeeded, but the daemon was no longer running immediately afterward.\n' +
+            'This usually means the daemon crashed or exited right after serving the live probe.');
+    }
+    else if (!daemonRunning) {
+        issues.push('Daemon is not running. It should start automatically when you run a webcmd browser command.');
+    }
+    if (daemonStale && opts.cliVersion) {
+        issues.push(staleDaemonIssue(health.status, opts.cliVersion));
+    }
+    if (runtimeFlaky) {
+        issues.push('Cloak runtime connection is unstable. The live browser test succeeded, but the daemon reported the runtime disconnected immediately afterward.\n' +
+            'This usually means Chrome/Chromium or the Cloak runtime is still starting, reconnecting, or was suspended.');
+    }
+    else if (daemonRunning && !runtimeConnected) {
+        if (health.state === 'profile-required') {
+            issues.push('Multiple Chrome profiles are connected to the daemon, but no default profile was selected.\n' +
+                '  Run webcmd profile list, then webcmd profile use <name>, or pass --profile <name>.');
+        }
+        else if (health.state === 'profile-disconnected') {
+            issues.push(`Selected browser profile is not connected: ${health.status?.contextId ?? 'unknown'}.\n` +
+                '  Open that Chrome profile and make sure Cloak is enabled.');
+        }
+        else {
+            issues.push('Daemon is running but the Cloak runtime is not connected.\n' +
+                '  Make sure Chrome/Chromium is open and Cloak is enabled.\n' +
+                '  If Chrome is already open, try: webcmd daemon restart');
+        }
+    }
+    if (!connectivity.ok) {
+        issues.push(`Browser connectivity test failed: ${connectivity.error ?? 'unknown'}`);
+    }
+    if (adapterShadows.length > 0) {
+        issues.push(formatAdapterShadowIssue(adapterShadows));
+    }
+    return {
+        cliVersion: opts.cliVersion,
+        daemonRunning,
+        daemonFlaky,
+        daemonStale,
+        daemonVersion: health.status?.daemonVersion,
+        runtimeConnected,
+        runtimeFlaky,
+        runtimeName,
+        runtimeVersion,
+        connectivity,
+        profiles,
+        adapterShadows,
+        issues,
+    };
+}
+export function renderBrowserDoctorReport(report) {
+    const lines = [`webcmd v${report.cliVersion ?? 'unknown'} doctor` + ` (${getRuntimeLabel()})`, ''];
+    // Daemon status
+    const daemonIcon = report.daemonFlaky
+        ? '[WARN]'
+        : report.daemonStale
+            ? '[WARN]'
+            : report.daemonRunning ? '[OK]' : '[MISSING]';
+    const daemonLabel = report.daemonFlaky
+        ? 'unstable (running during live check, then stopped)'
+        : report.daemonRunning
+            ? `running on port ${DEFAULT_DAEMON_PORT} (${report.daemonStale
+                ? `${formatDaemonVersion(report)}, stale; CLI v${report.cliVersion ?? 'unknown'}`
+                : formatDaemonVersion(report)})`
+            : 'not running';
+    lines.push(`${daemonIcon} Daemon: ${daemonLabel}`);
+    // Runtime status
+    const runtimeIcon = report.runtimeFlaky
+        ? '[WARN]'
+        : report.runtimeConnected ? '[OK]' : '[MISSING]';
+    const runtimeVersion = !report.runtimeConnected
+        ? ''
+        : report.runtimeVersion
+            ? ` (v${report.runtimeVersion})`
+            : ' (version unknown)';
+    const runtimeName = report.runtimeName ?? 'Cloak';
+    const runtimeLabel = report.runtimeFlaky
+        ? 'unstable (connected during live check, then disconnected)'
+        : report.runtimeConnected ? 'connected' : 'not connected';
+    lines.push(`${runtimeIcon} Runtime: ${runtimeName} ${runtimeLabel}${runtimeVersion}`);
+    if (report.profiles && report.profiles.length > 0) {
+        const config = loadProfileConfig();
+        lines.push('', 'Profiles:');
+        for (const profile of report.profiles) {
+            const alias = aliasForContextId(config, profile.contextId);
+            const aliasText = alias ? ` (${alias})` : '';
+            const defaultText = config.defaultContextId === profile.contextId ? ', default' : '';
+            const version = profile.runtimeVersion ? `v${profile.runtimeVersion}` : 'version unknown';
+            lines.push(`  • ${profile.contextId}${aliasText}: connected ${version}${defaultText}`);
+        }
+    }
+    // Connectivity
+    if (report.connectivity) {
+        const connIcon = report.connectivity.ok ? '[OK]' : '[FAIL]';
+        const detail = report.connectivity.ok
+            ? `connected in ${(report.connectivity.durationMs / 1000).toFixed(1)}s`
+            : `failed (${report.connectivity.error ?? 'unknown'})`;
+        lines.push(`${connIcon} Connectivity: ${detail}`);
+    }
+    if (report.issues.length) {
+        lines.push('', 'Issues:');
+        for (const issue of report.issues) {
+            lines.push(`  • ${issue}`);
+        }
+    }
+    else if (report.daemonRunning && report.runtimeConnected) {
+        lines.push('', 'Everything looks good!');
+    }
+    return lines.join('\n');
+}

package/dist/src/doctor.test.d.ts

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