@agentrhq/webcmd 0.1.1 → 0.1.2

package/dist/src/registry-api.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Public API for webcmd plugins.
+ *
+ * TS plugins should import from '@agentrhq/webcmd/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export type { CliCommand, Arg, CliOptions, CommandArgs, SiteSessionMode } from './registry.js';
+export type { IPage } from './types.js';
+export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';
+export type { HookFn, HookContext, HookName } from './hooks.js';

package/dist/src/registry-api.js

@@ -0,0 +1,10 @@
+/**
+ * Public API for webcmd plugins.
+ *
+ * TS plugins should import from '@agentrhq/webcmd/registry' which resolves to
+ * this file. It re-exports ONLY the core registration API — no serialization,
+ * no transitive side-effects — to avoid circular dependency deadlocks when
+ * plugins are dynamically imported during discoverPlugins().
+ */
+export { cli, Strategy, getRegistry, fullName, registerCommand } from './registry.js';
+export { onStartup, onBeforeExecute, onAfterExecute } from './hooks.js';

package/dist/src/registry.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
+ */
+import type { IPage } from './types.js';
+export declare enum Strategy {
+    PUBLIC = "public",
+    LOCAL = "local",
+    COOKIE = "cookie",
+    INTERCEPT = "intercept",
+    UI = "ui"
+}
+export interface Arg {
+    name: string;
+    type?: string;
+    default?: unknown;
+    required?: boolean;
+    valueRequired?: boolean;
+    positional?: boolean;
+    help?: string;
+    choices?: string[];
+}
+export type CommandArgs = Record<string, any>;
+export type BrowserCommandFunc = (page: IPage, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
+export type NonBrowserCommandFunc = (kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
+export type CommandAccess = 'read' | 'write';
+export type SiteSessionMode = 'ephemeral' | 'persistent';
+export interface AuthStatusMetadata {
+    quickCheck?: BrowserCommandFunc;
+    refresh?: BrowserCommandFunc;
+}
+interface BaseCliCommand {
+    site: string;
+    name: string;
+    aliases?: string[];
+    description: string;
+    access: CommandAccess;
+    /** Canonical invocation shown in agent-facing help. Generated when omitted. */
+    example?: string;
+    domain?: string;
+    strategy?: Strategy;
+    args: Arg[];
+    columns?: string[];
+    pipeline?: Record<string, unknown>[];
+    /** Origin of this command: 'yaml', 'ts', or plugin name. */
+    source?: string;
+    footerExtra?: (kwargs: CommandArgs) => string | undefined;
+    validateArgs?: (kwargs: CommandArgs) => void;
+    /**
+     * Control pre-navigation and browser-session requirement.
+     *
+     * After normalizeCommand() expands strategy, this field carries the
+     * resolved runtime intent:
+     *
+     * - `undefined`: no pre-navigation, browser session decided by pipeline steps
+     * - `false`: explicitly skip pre-navigation (adapter handles its own navigation)
+     * - `true`: needs authenticated browser context but no specific pre-nav URL
+     *   (e.g. INTERCEPT/UI adapters, or COOKIE without domain)
+     * - `string`: pre-navigate to this URL before running the adapter
+     *   (e.g. `'https://x.com'` for COOKIE strategy with domain)
+     *
+     * Adapter authors can set this explicitly to override the strategy-based default.
+     */
+    navigateBefore?: boolean | string;
+    /** Site session lifecycle for adapter commands. */
+    siteSession?: SiteSessionMode;
+    /** Default browser window mode for commands whose UX requires visibility. */
+    defaultWindowMode?: 'foreground' | 'background';
+    /** Override the default CLI output format when the user does not pass -f/--format. */
+    defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
+    /** Optional auth-status metadata attached by shared auth adapters. */
+    authStatus?: AuthStatusMetadata;
+}
+export interface BrowserCliCommand extends BaseCliCommand {
+    /** Browser commands receive an IPage. Omitted means true after normalization. */
+    browser?: true;
+    func?: BrowserCommandFunc;
+}
+export interface NonBrowserCliCommand extends BaseCliCommand {
+    /** Non-browser commands do not receive a page argument. */
+    browser: false;
+    func?: NonBrowserCommandFunc;
+}
+export type CliCommand = BrowserCliCommand | NonBrowserCliCommand;
+type RawCliCommand = BaseCliCommand & {
+    browser?: boolean;
+    func?: BrowserCommandFunc | NonBrowserCommandFunc;
+};
+/** Internal extension for lazy-loaded TS modules (not exposed in public API) */
+export type InternalCliCommand = CliCommand & {
+    _lazy?: boolean;
+    _modulePath?: string;
+};
+type RequiredCliOptions = {
+    site: string;
+    name: string;
+    access: CommandAccess;
+    description?: string;
+    args?: Arg[];
+};
+type BrowserStrategy = Exclude<Strategy, Strategy.PUBLIC | Strategy.LOCAL>;
+type BrowserCliOptions = Partial<Omit<BrowserCliCommand, 'args' | 'description' | 'browser' | 'strategy'>> & RequiredCliOptions & ({
+    browser: true;
+    strategy?: Strategy;
+} | {
+    browser?: true;
+    strategy?: BrowserStrategy;
+});
+type NonBrowserCliOptions = Partial<Omit<NonBrowserCliCommand, 'args' | 'description'>> & RequiredCliOptions & ({
+    browser: false;
+} | {
+    strategy: Strategy.PUBLIC | Strategy.LOCAL;
+    browser?: false;
+});
+export type CliOptions = BrowserCliOptions | NonBrowserCliOptions;
+declare global {
+    var __webcmd_registry__: Map<string, CliCommand> | undefined;
+}
+export declare function cli(opts: CliOptions): CliCommand;
+export declare function getRegistry(): Map<string, CliCommand>;
+export declare function fullName(cmd: Pick<BaseCliCommand, 'site' | 'name'>): string;
+export declare function strategyLabel(cmd: CliCommand): string;
+export declare function registerCommand(cmd: RawCliCommand): void;
+export {};

package/dist/src/registry.js

@@ -0,0 +1,125 @@
+/**
+ * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
+ */
+export var Strategy;
+(function (Strategy) {
+    Strategy["PUBLIC"] = "public";
+    Strategy["LOCAL"] = "local";
+    Strategy["COOKIE"] = "cookie";
+    Strategy["INTERCEPT"] = "intercept";
+    Strategy["UI"] = "ui";
+})(Strategy || (Strategy = {}));
+const _registry = globalThis.__webcmd_registry__ ??= new Map();
+export function cli(opts) {
+    const cmd = {
+        site: opts.site,
+        name: opts.name,
+        aliases: opts.aliases,
+        description: opts.description ?? '',
+        access: opts.access,
+        example: opts.example,
+        domain: opts.domain,
+        strategy: opts.strategy,
+        browser: opts.browser,
+        args: opts.args ?? [],
+        columns: opts.columns,
+        func: opts.func,
+        pipeline: opts.pipeline,
+        footerExtra: opts.footerExtra,
+        validateArgs: opts.validateArgs,
+        navigateBefore: opts.navigateBefore,
+        siteSession: opts.siteSession,
+        defaultWindowMode: opts.defaultWindowMode,
+        defaultFormat: opts.defaultFormat,
+        authStatus: opts.authStatus,
+    };
+    registerCommand(cmd);
+    return _registry.get(fullName(cmd));
+}
+export function getRegistry() {
+    return _registry;
+}
+export function fullName(cmd) {
+    return `${cmd.site}/${cmd.name}`;
+}
+export function strategyLabel(cmd) {
+    return cmd.strategy ?? Strategy.PUBLIC;
+}
+/**
+ * Normalize a command's runtime fields. This is the single place where
+ * `strategy` is decoded into the concrete fields that the execution path
+ * reads (`browser`, `navigateBefore`). After normalization, execution code
+ * (resolvePreNav, shouldUseBrowserSession) never reads `cmd.strategy`.
+ *
+ * `strategy` itself is preserved as metadata for `webcmd list`, cascade
+ * probe, adapter generation, and human documentation.
+ *
+ * Override priority (highest wins):
+ *   1. Explicit field on the command (`browser: false`, `navigateBefore: false`)
+ *   2. Derived from strategy + domain (the defaults below)
+ */
+function normalizeCommand(cmd) {
+    assertCommandAccess(cmd);
+    assertSiteSession(cmd);
+    const strategy = cmd.strategy ?? (cmd.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
+    const browser = cmd.browser ?? (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL);
+    let navigateBefore = cmd.navigateBefore;
+    if (navigateBefore === undefined) {
+        if (strategy === Strategy.COOKIE && cmd.domain) {
+            navigateBefore = `https://${cmd.domain}`;
+        }
+        else if (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL) {
+            // Non-PUBLIC without domain: needs authenticated browser context
+            // but no specific pre-navigation URL. `true` signals this to
+            // shouldUseBrowserSession without triggering resolvePreNav.
+            navigateBefore = true;
+        }
+    }
+    return browser
+        ? { ...cmd, strategy, browser: true, navigateBefore }
+        : { ...cmd, strategy, browser: false, navigateBefore };
+}
+function assertCommandAccess(cmd) {
+    if (cmd.access === 'read' || cmd.access === 'write')
+        return;
+    const key = `${cmd.site}/${cmd.name}`;
+    throw new Error(`Command ${key} must declare access: 'read' | 'write'`);
+}
+function assertSiteSession(cmd) {
+    if (cmd.siteSession === undefined)
+        return;
+    const key = `${cmd.site}/${cmd.name}`;
+    if (cmd.siteSession !== 'ephemeral' && cmd.siteSession !== 'persistent') {
+        throw new Error(`Command ${key} siteSession must be one of: ephemeral, persistent`);
+    }
+}
+export function registerCommand(cmd) {
+    const normalized = normalizeCommand(cmd);
+    const canonicalKey = fullName(normalized);
+    const existing = _registry.get(canonicalKey);
+    if (existing?.aliases) {
+        for (const alias of existing.aliases) {
+            _registry.delete(`${existing.site}/${alias}`);
+        }
+    }
+    const aliases = normalizeAliases(normalized.aliases, normalized.name);
+    normalized.aliases = aliases.length > 0 ? aliases : undefined;
+    _registry.set(canonicalKey, normalized);
+    for (const alias of aliases) {
+        _registry.set(`${normalized.site}/${alias}`, normalized);
+    }
+}
+function normalizeAliases(aliases, commandName) {
+    if (!Array.isArray(aliases) || aliases.length === 0)
+        return [];
+    const seen = new Set();
+    const normalized = [];
+    for (const alias of aliases) {
+        const value = typeof alias === 'string' ? alias.trim() : '';
+        if (!value || value === commandName || seen.has(value))
+            continue;
+        seen.add(value);
+        normalized.push(value);
+    }
+    return normalized;
+}

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

@@ -0,0 +1,4 @@
+/**
+ * Tests for registry.ts: Strategy enum, cli() registration, helpers.
+ */
+export {};

package/dist/src/registry.test.js

@@ -0,0 +1,209 @@
+/**
+ * Tests for registry.ts: Strategy enum, cli() registration, helpers.
+ */
+import { describe, it, expect } from 'vitest';
+import { cli, getRegistry, fullName, strategyLabel, registerCommand, Strategy } from './registry.js';
+describe('cli() registration', () => {
+    it('registers a command and returns it', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'hello', access: 'read',
+            description: 'A test command',
+            strategy: Strategy.PUBLIC,
+            browser: false,
+        });
+        expect(cmd.site).toBe('test-registry');
+        expect(cmd.name).toBe('hello');
+        expect(cmd.access).toBe('read');
+        expect(cmd.strategy).toBe(Strategy.PUBLIC);
+        expect(cmd.browser).toBe(false);
+        expect(cmd.args).toEqual([]);
+    });
+    it('puts registered command in the registry', () => {
+        cli({
+            site: 'test-registry',
+            name: 'registered', access: 'read',
+            description: 'test',
+        });
+        const registry = getRegistry();
+        expect(registry.has('test-registry/registered')).toBe(true);
+    });
+    it('defaults strategy to COOKIE when browser is true', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'default-strategy', access: 'read',
+        });
+        expect(cmd.strategy).toBe(Strategy.COOKIE);
+        expect(cmd.browser).toBe(true);
+    });
+    it('defaults strategy to PUBLIC when browser is false', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'no-browser', access: 'read',
+            browser: false,
+        });
+        expect(cmd.strategy).toBe(Strategy.PUBLIC);
+    });
+    it('preserves LOCAL strategy on registration', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'local-strategy', access: 'read',
+            description: 'reads local credentials',
+            strategy: Strategy.LOCAL,
+            browser: false,
+        });
+        expect(cmd.strategy).toBe(Strategy.LOCAL);
+        expect(cmd.browser).toBe(false);
+    });
+    it('overwrites existing command on re-registration', () => {
+        cli({ site: 'test-registry', name: 'overwrite', access: 'read', description: 'v1' });
+        cli({ site: 'test-registry', name: 'overwrite', access: 'read', description: 'v2' });
+        const reg = getRegistry();
+        expect(reg.get('test-registry/overwrite')?.description).toBe('v2');
+    });
+    it('registers aliases as alternate registry keys for the same command', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'canonical', access: 'read',
+            description: 'test aliases',
+            aliases: ['compat', 'legacy-name'],
+        });
+        const registry = getRegistry();
+        expect(cmd.aliases).toEqual(['compat', 'legacy-name']);
+        expect(registry.get('test-registry/canonical')).toBe(cmd);
+        expect(registry.get('test-registry/compat')).toBe(cmd);
+        expect(registry.get('test-registry/legacy-name')).toBe(cmd);
+    });
+    it('preserves defaultFormat on the registered command', () => {
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'plain-default', access: 'read',
+            description: 'prefers plain output',
+            defaultFormat: 'plain',
+        });
+        expect(cmd.defaultFormat).toBe('plain');
+        expect(getRegistry().get('test-registry/plain-default')?.defaultFormat).toBe('plain');
+    });
+    it('preserves validateArgs on the registered command', () => {
+        const validateArgs = () => undefined;
+        const cmd = cli({
+            site: 'test-registry',
+            name: 'validated', access: 'read',
+            description: 'validates args before execution',
+            validateArgs,
+        });
+        expect(cmd.validateArgs).toBe(validateArgs);
+        expect(getRegistry().get('test-registry/validated')?.validateArgs).toBe(validateArgs);
+    });
+    it('rejects commands without explicit access metadata', () => {
+        expect(() => cli({
+            site: 'test-registry',
+            name: 'missing-access',
+        })).toThrow("Command test-registry/missing-access must declare access: 'read' | 'write'");
+    });
+});
+describe('fullName', () => {
+    it('returns site/name', () => {
+        const cmd = {
+            site: 'bilibili', name: 'hot', access: 'read', description: '', args: [],
+        };
+        expect(fullName(cmd)).toBe('bilibili/hot');
+    });
+});
+describe('strategyLabel', () => {
+    it('returns strategy string', () => {
+        const cmd = {
+            site: 'test', name: 'test', access: 'read', description: '', args: [],
+            strategy: Strategy.INTERCEPT,
+        };
+        expect(strategyLabel(cmd)).toBe('intercept');
+    });
+    it('returns public when no strategy set', () => {
+        const cmd = {
+            site: 'test', name: 'test', access: 'read', description: '', args: [],
+        };
+        expect(strategyLabel(cmd)).toBe('public');
+    });
+});
+describe('registerCommand', () => {
+    it('registers a pre-built command', () => {
+        const cmd = {
+            site: 'test-registry',
+            name: 'direct-reg', access: 'read',
+            description: 'directly registered',
+            args: [],
+            strategy: Strategy.COOKIE,
+            browser: true,
+        };
+        registerCommand(cmd);
+        const reg = getRegistry();
+        expect(reg.get('test-registry/direct-reg')?.strategy).toBe(Strategy.COOKIE);
+    });
+});
+describe('normalizeCommand (via registerCommand)', () => {
+    it('COOKIE + domain → navigateBefore is the domain URL', () => {
+        registerCommand({
+            site: 'test-norm', name: 'cookie-domain', access: 'read', description: '', args: [],
+            strategy: Strategy.COOKIE, domain: 'x.com',
+        });
+        const cmd = getRegistry().get('test-norm/cookie-domain');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe('https://x.com');
+    });
+    it('COOKIE without domain → navigateBefore is true (auth context, no URL)', () => {
+        registerCommand({
+            site: 'test-norm', name: 'cookie-nodomain', access: 'read', description: '', args: [],
+            strategy: Strategy.COOKIE,
+        });
+        const cmd = getRegistry().get('test-norm/cookie-nodomain');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe(true);
+    });
+    it('INTERCEPT → navigateBefore is true (auth context)', () => {
+        registerCommand({
+            site: 'test-norm', name: 'intercept', access: 'read', description: '', args: [],
+            strategy: Strategy.INTERCEPT, domain: 'example.com',
+        });
+        const cmd = getRegistry().get('test-norm/intercept');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe(true);
+    });
+    it('PUBLIC → browser false, navigateBefore undefined', () => {
+        registerCommand({
+            site: 'test-norm', name: 'public', access: 'read', description: '', args: [],
+            strategy: Strategy.PUBLIC,
+        });
+        const cmd = getRegistry().get('test-norm/public');
+        expect(cmd.browser).toBe(false);
+        expect(cmd.navigateBefore).toBeUndefined();
+    });
+    it('LOCAL → browser false, navigateBefore undefined', () => {
+        registerCommand({
+            site: 'test-norm', name: 'local', access: 'read', description: '', args: [],
+            strategy: Strategy.LOCAL,
+        });
+        const cmd = getRegistry().get('test-norm/local');
+        expect(cmd.strategy).toBe(Strategy.LOCAL);
+        expect(strategyLabel(cmd)).toBe('local');
+        expect(cmd.browser).toBe(false);
+        expect(cmd.navigateBefore).toBeUndefined();
+    });
+    it('explicit navigateBefore: false overrides COOKIE + domain', () => {
+        registerCommand({
+            site: 'test-norm', name: 'cookie-override', access: 'read', description: '', args: [],
+            strategy: Strategy.COOKIE, domain: 'amazon.com', navigateBefore: false,
+        });
+        const cmd = getRegistry().get('test-norm/cookie-override');
+        expect(cmd.browser).toBe(true);
+        expect(cmd.navigateBefore).toBe(false);
+    });
+    it('explicit navigateBefore URL overrides strategy default', () => {
+        registerCommand({
+            site: 'test-norm', name: 'explicit-url', access: 'read', description: '', args: [],
+            strategy: Strategy.COOKIE, domain: 'x.com',
+            navigateBefore: 'https://x.com/explore',
+        });
+        const cmd = getRegistry().get('test-norm/explicit-url');
+        expect(cmd.navigateBefore).toBe('https://x.com/explore');
+    });
+});

package/dist/src/runtime-copy.test.d.ts

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

package/dist/src/runtime-copy.test.js

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+describe('runtime copy', () => {
+    it('does not keep legacy browser runtime setup copy in runtime source', () => {
+        const files = [
+            'src/browser/errors.ts',
+            'src/browser/daemon-lifecycle.ts',
+            'src/commands/daemon.ts',
+            'src/cli.ts',
+            'README.md',
+        ];
+        const phrase = (...parts) => parts.join('');
+        const forbiddenUserFacingCopy = [
+            phrase('Browser ', 'Bridge'),
+            phrase('chrome://', 'extensions'),
+            phrase('Load ', 'unpacked'),
+            phrase('extension', 'Connected'),
+            phrase('extension', 'Version'),
+            phrase('extension', 'CompatRange'),
+        ];
+        const offenders = files.flatMap((file) => {
+            const text = fs.readFileSync(path.join(process.cwd(), file), 'utf-8');
+            const matches = forbiddenUserFacingCopy.filter((phrase) => text.includes(phrase));
+            return matches.length > 0 ? [{ file, matches }] : [];
+        });
+        expect(offenders).toEqual([]);
+    });
+});

package/dist/src/runtime-detect.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime detection — identify whether webcmd is running under Node.js or Bun.
+ *
+ * Bun injects `globalThis.Bun` at startup, making detection trivial.
+ * This module centralises the check so other code can adapt behaviour
+ * (e.g. logging, diagnostics) without littering runtime sniffing everywhere.
+ */
+export type Runtime = 'bun' | 'node';
+export declare const MIN_SUPPORTED_NODE_MAJOR = 20;
+/**
+ * Detect the current JavaScript runtime.
+ */
+export declare function detectRuntime(): Runtime;
+/**
+ * Return a human-readable version string for the current runtime.
+ * Examples: "v22.13.0" (Node), "1.1.42" (Bun)
+ */
+export declare function getRuntimeVersion(): string;
+/**
+ * Return a combined label like "node v22.13.0" or "bun 1.1.42".
+ */
+export declare function getRuntimeLabel(): string;
+/**
+ * Parse a Node.js version string like "v22.13.0" and return its major version.
+ * Returns null for non-Node or malformed inputs.
+ */
+export declare function parseNodeMajor(version: string): number | null;
+/**
+ * Whether the given Node.js version satisfies the current minimum support policy.
+ */
+export declare function isSupportedNodeVersion(version?: string): boolean;

package/dist/src/runtime-detect.js

@@ -0,0 +1,47 @@
+/**
+ * Runtime detection — identify whether webcmd is running under Node.js or Bun.
+ *
+ * Bun injects `globalThis.Bun` at startup, making detection trivial.
+ * This module centralises the check so other code can adapt behaviour
+ * (e.g. logging, diagnostics) without littering runtime sniffing everywhere.
+ */
+export const MIN_SUPPORTED_NODE_MAJOR = 20;
+/**
+ * Detect the current JavaScript runtime.
+ */
+export function detectRuntime() {
+    // Bun always exposes globalThis.Bun (including Bun.version)
+    return globalThis.Bun !== undefined ? 'bun' : 'node';
+}
+/**
+ * Return a human-readable version string for the current runtime.
+ * Examples: "v22.13.0" (Node), "1.1.42" (Bun)
+ */
+export function getRuntimeVersion() {
+    const bun = globalThis.Bun;
+    return bun ? bun.version : process.version;
+}
+/**
+ * Return a combined label like "node v22.13.0" or "bun 1.1.42".
+ */
+export function getRuntimeLabel() {
+    return `${detectRuntime()} ${getRuntimeVersion()}`;
+}
+/**
+ * Parse a Node.js version string like "v22.13.0" and return its major version.
+ * Returns null for non-Node or malformed inputs.
+ */
+export function parseNodeMajor(version) {
+    const match = /^v?(\d+)\./.exec(String(version).trim());
+    if (!match)
+        return null;
+    const major = Number(match[1]);
+    return Number.isInteger(major) ? major : null;
+}
+/**
+ * Whether the given Node.js version satisfies the current minimum support policy.
+ */
+export function isSupportedNodeVersion(version = process.version) {
+    const major = parseNodeMajor(version);
+    return major !== null && major >= MIN_SUPPORTED_NODE_MAJOR;
+}

package/dist/src/runtime-detect.test.d.ts

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

package/dist/src/runtime-detect.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { detectRuntime, getRuntimeVersion, getRuntimeLabel, parseNodeMajor, isSupportedNodeVersion, MIN_SUPPORTED_NODE_MAJOR } from './runtime-detect.js';
+describe('runtime-detect', () => {
+    it('detectRuntime returns a valid runtime string', () => {
+        const rt = detectRuntime();
+        expect(['bun', 'node']).toContain(rt);
+    });
+    it('getRuntimeVersion returns a non-empty version string', () => {
+        const ver = getRuntimeVersion();
+        expect(typeof ver).toBe('string');
+        expect(ver.length).toBeGreaterThan(0);
+    });
+    it('getRuntimeLabel returns "<runtime> <version>" format', () => {
+        const label = getRuntimeLabel();
+        expect(label).toMatch(/^(bun|node) .+$/);
+    });
+    it('detects the current environment correctly', () => {
+        const isBun = typeof globalThis.Bun !== 'undefined';
+        const rt = detectRuntime();
+        if (isBun) {
+            expect(rt).toBe('bun');
+        }
+        else {
+            expect(rt).toBe('node');
+        }
+    });
+    it('parses Node major versions from standard version strings', () => {
+        expect(parseNodeMajor('v21.0.0')).toBe(21);
+        expect(parseNodeMajor('22.13.1')).toBe(22);
+        expect(parseNodeMajor('bun-1.2.0')).toBeNull();
+    });
+    it('checks the current minimum supported Node major version', () => {
+        expect(MIN_SUPPORTED_NODE_MAJOR).toBe(20);
+        expect(isSupportedNodeVersion('v19.9.0')).toBe(false);
+        expect(isSupportedNodeVersion('v20.0.0')).toBe(true);
+        expect(isSupportedNodeVersion('v21.0.0')).toBe(true);
+        expect(isSupportedNodeVersion('v25.0.0')).toBe(true);
+    });
+});

package/dist/src/runtime-identity.test.d.ts

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

package/dist/src/runtime-identity.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import * as path from 'node:path';
+import { unsupportedDaemonPortEnvMessage } from './constants.js';
+import { getUserWebcmdDir, getUserClisDir, getPluginsDir } from './discovery.js';
+describe('webcmd runtime identity', () => {
+    it('uses webcmd runtime directories', async () => {
+        expect(getUserWebcmdDir('/home/tester')).toBe(path.join('/home/tester', '.webcmd'));
+        expect(getUserClisDir('/home/tester')).toBe(path.join('/home/tester', '.webcmd', 'clis'));
+        expect(getPluginsDir('/home/tester')).toBe(path.join('/home/tester', '.webcmd', 'plugins'));
+    });
+    it('reports unsupported daemon port with WEBCMD env names', () => {
+        const legacyEnvName = ['OPEN', 'CLI_DAEMON_PORT'].join('');
+        expect(unsupportedDaemonPortEnvMessage('1234')).toContain('WEBCMD_DAEMON_PORT');
+        expect(unsupportedDaemonPortEnvMessage('1234')).toContain('Webcmd');
+        expect(unsupportedDaemonPortEnvMessage('1234')).toContain('rerun webcmd');
+        expect(unsupportedDaemonPortEnvMessage('1234')).not.toContain(legacyEnvName);
+    });
+});