@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/release-notes.test.js

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'vitest';
+import { RELEASE_NOTE_SECTIONS, buildReleaseNotesPrompt, extractPullRequestNumber, filterReleasePullRequests, normalizeReleaseNotes, } from './release-notes.js';
+describe('release notes helpers', () => {
+    it('extracts PR numbers from squash and merge commit messages', () => {
+        expect(extractPullRequestNumber('feat: add release notes (#123)')).toBe(123);
+        expect(extractPullRequestNumber('feat: add release notes (#124)\n\nExpanded body')).toBe(124);
+        expect(extractPullRequestNumber('Merge pull request #456 from agentrhq/example')).toBe(456);
+        expect(extractPullRequestNumber('docs: plain commit without pr')).toBeNull();
+    });
+    it('filters release and skip-changelog pull requests', () => {
+        const prs = [
+            { number: 1, title: 'feat: browser polish', author: { login: 'alice' }, labels: [], files: [], url: 'https://example.com/1' },
+            { number: 2, title: 'release: 0.2.0', author: { login: 'bot' }, labels: [], files: [], url: 'https://example.com/2' },
+            { number: 3, title: 'chore: generated updates', author: { login: 'ci' }, labels: [{ name: 'skip-changelog' }], files: [], url: 'https://example.com/3' },
+            { number: 4, title: 'chore: release prep', author: { login: 'ci' }, labels: [{ name: 'release' }], files: [], url: 'https://example.com/4' },
+            { number: 5, title: 'chore(main): release webcmd 0.2.0', author: { login: 'release-please' }, labels: [], files: [], url: 'https://example.com/5' },
+        ];
+        expect(filterReleasePullRequests(prs).map((pr) => pr.number)).toEqual([1]);
+    });
+    it('normalizes all required sections and fills empty sections with None', () => {
+        const raw = [
+            '## Highlights',
+            '- Better release notes.',
+            '',
+            '## Fixes',
+            '- Fixed release fallback.',
+        ].join('\n');
+        const normalized = normalizeReleaseNotes(raw, ['alice', 'bob']);
+        for (const section of RELEASE_NOTE_SECTIONS) {
+            expect(normalized).toContain(`## ${section}`);
+        }
+        expect(normalized).toContain('## Improvements\nNone.');
+        expect(normalized).toContain('## Contributors\n- @alice\n- @bob');
+        expect(normalized).toContain('## Reverts\nNone.');
+    });
+    it('builds a prompt grounded in the exact release range and PR list', () => {
+        const context = {
+            tag: 'v0.2.0',
+            previousTag: 'v0.1.1',
+            currentRef: 'abc123',
+            pullRequests: [
+                {
+                    number: 42,
+                    title: 'feat: add docs scaffold',
+                    body: 'Adds docs structure.',
+                    author: { login: 'alice' },
+                    labels: [{ name: 'feature' }],
+                    files: [{ path: 'docs/docs.json' }],
+                    diff: 'diff --git a/docs/docs.json b/docs/docs.json',
+                    url: 'https://github.com/agentrhq/webcmd/pull/42',
+                },
+            ],
+        };
+        const prompt = buildReleaseNotesPrompt(context);
+        expect(prompt).toContain('v0.1.1...abc123');
+        expect(prompt).toContain('PR #42: feat: add docs scaffold');
+        expect(prompt).toContain('docs/docs.json');
+        expect(prompt).toContain('## Highlights');
+        expect(prompt).toContain('## Reverts');
+    });
+});

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);
+    });
+});

package/dist/src/runtime.d.ts

@@ -0,0 +1,47 @@
+import type { IPage } from './types.js';
+import { DEFAULT_BROWSER_COMMAND_TIMEOUT, DEFAULT_BROWSER_CONNECT_TIMEOUT } from './browser/config.js';
+export { DEFAULT_BROWSER_COMMAND_TIMEOUT, DEFAULT_BROWSER_CONNECT_TIMEOUT };
+/**
+ * Returns the appropriate browser factory based on site type.
+ * Uses CDPBridge for registered Electron apps, otherwise BrowserBridge.
+ */
+export declare function getBrowserFactory(site?: string): new () => IBrowserFactory;
+export type BrowserWindowMode = 'foreground' | 'background';
+export type BrowserSurface = 'browser' | 'adapter';
+/**
+ * Timeout with seconds unit. Used for high-level command timeouts.
+ */
+export declare function runWithTimeout<T>(promise: Promise<T>, opts: {
+    timeout: number;
+    label?: string;
+    hint?: string;
+}): Promise<T>;
+/**
+ * Timeout with milliseconds unit. Used for low-level internal timeouts.
+ * Accepts a factory function to create the rejection error, keeping this
+ * utility decoupled from specific error types.
+ */
+export declare function withTimeoutMs<T>(promise: Promise<T>, timeoutMs: number, makeError?: string | (() => Error)): Promise<T>;
+/** Interface for browser factory (BrowserBridge or test mocks) */
+export interface IBrowserFactory {
+    connect(opts?: {
+        timeout?: number;
+        session?: string;
+        cdpEndpoint?: string;
+        contextId?: string;
+        idleTimeout?: number;
+        windowMode?: BrowserWindowMode;
+        surface?: BrowserSurface;
+        siteSession?: 'ephemeral' | 'persistent';
+    }): Promise<IPage>;
+    close(): Promise<void>;
+}
+export declare function browserSession<T>(BrowserFactory: new () => IBrowserFactory, fn: (page: IPage) => Promise<T>, opts?: {
+    session?: string;
+    cdpEndpoint?: string;
+    contextId?: string;
+    idleTimeout?: number;
+    windowMode?: BrowserWindowMode;
+    surface?: BrowserSurface;
+    siteSession?: 'ephemeral' | 'persistent';
+}): Promise<T>;

package/dist/src/runtime.js

@@ -0,0 +1,54 @@
+import { BrowserBridge, CDPBridge } from './browser/index.js';
+import { TimeoutError } from './errors.js';
+import { isElectronApp } from './electron-apps.js';
+import { DEFAULT_BROWSER_COMMAND_TIMEOUT, DEFAULT_BROWSER_CONNECT_TIMEOUT } from './browser/config.js';
+export { DEFAULT_BROWSER_COMMAND_TIMEOUT, DEFAULT_BROWSER_CONNECT_TIMEOUT };
+/**
+ * Returns the appropriate browser factory based on site type.
+ * Uses CDPBridge for registered Electron apps, otherwise BrowserBridge.
+ */
+export function getBrowserFactory(site) {
+    if (site && isElectronApp(site))
+        return CDPBridge;
+    return BrowserBridge;
+}
+/**
+ * Timeout with seconds unit. Used for high-level command timeouts.
+ */
+export async function runWithTimeout(promise, opts) {
+    const label = opts.label ?? 'Operation';
+    return withTimeoutMs(promise, opts.timeout * 1000, () => new TimeoutError(label, opts.timeout, opts.hint));
+}
+/**
+ * Timeout with milliseconds unit. Used for low-level internal timeouts.
+ * Accepts a factory function to create the rejection error, keeping this
+ * utility decoupled from specific error types.
+ */
+export function withTimeoutMs(promise, timeoutMs, makeError = 'Operation timed out') {
+    const reject_ = typeof makeError === 'string'
+        ? () => new Error(makeError)
+        : makeError;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(reject_()), timeoutMs);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+    });
+}
+export async function browserSession(BrowserFactory, fn, opts = {}) {
+    const browser = new BrowserFactory();
+    try {
+        const page = await browser.connect({
+            timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT,
+            session: opts.session,
+            cdpEndpoint: opts.cdpEndpoint,
+            contextId: opts.contextId,
+            idleTimeout: opts.idleTimeout,
+            windowMode: opts.windowMode,
+            surface: opts.surface,
+            siteSession: opts.siteSession,
+        });
+        return await fn(page);
+    }
+    finally {
+        await browser.close().catch(() => { });
+    }
+}

package/dist/src/scripts/framework.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Injected script for detecting frontend frameworks (Vue, React, Next, Nuxt, etc.)
+ *
+ * Serialized via `.toString()` and evaluated in the page context. Types here are
+ * only for the TS boundary — see scripts/store.ts for the same pattern.
+ */
+export declare function detectFramework(): Record<string, boolean>;

package/dist/src/scripts/framework.js

@@ -0,0 +1,25 @@
+/**
+ * Injected script for detecting frontend frameworks (Vue, React, Next, Nuxt, etc.)
+ *
+ * Serialized via `.toString()` and evaluated in the page context. Types here are
+ * only for the TS boundary — see scripts/store.ts for the same pattern.
+ */
+export function detectFramework() {
+    const r = {};
+    try {
+        const app = document.querySelector('#app');
+        const w = window;
+        r.vue3 = !!(app && app.__vue_app__);
+        r.vue2 = !!(app && app.__vue__);
+        r.react = !!w.__REACT_DEVTOOLS_GLOBAL_HOOK__ || !!document.querySelector('[data-reactroot]');
+        r.nextjs = !!w.__NEXT_DATA__;
+        r.nuxt = !!w.__NUXT__;
+        if (r.vue3 && app?.__vue_app__) {
+            const gp = app.__vue_app__.config?.globalProperties;
+            r.pinia = !!(gp && gp.$pinia);
+            r.vuex = !!(gp && gp.$store);
+        }
+    }
+    catch { }
+    return r;
+}

package/dist/src/scripts/interact.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Injected script for interactive fuzzing (clicking elements to trigger lazy loading)
+ */
+export declare function interactFuzz(): Promise<number>;

package/dist/src/scripts/interact.js

@@ -0,0 +1,20 @@
+/**
+ * Injected script for interactive fuzzing (clicking elements to trigger lazy loading)
+ */
+export async function interactFuzz() {
+    const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+    const clickables = Array.from(document.querySelectorAll('button, [role="button"], [role="tab"], .tab, .btn, a[href="javascript:void(0)"], a[href="#"]')).slice(0, 15); // limit to a small number to avoid endless loops
+    let clicked = 0;
+    for (const el of clickables) {
+        try {
+            const rect = el.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) {
+                el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: window }));
+                clicked++;
+                await sleep(300); // give it time to trigger network
+            }
+        }
+        catch { }
+    }
+    return clicked;
+}

package/dist/src/scripts/store.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Injected script for discovering Pinia or Vuex stores and their actions/state representations.
+ *
+ * This function is serialized via `.toString()` and evaluated inside the page context,
+ * so the types below only exist at the TS boundary — the runtime shapes are whatever
+ * Pinia/Vuex put on the Vue app. We use narrow structural types for the fields we touch.
+ */
+export declare function discoverStores(): {
+    type: string;
+    id: string;
+    actions: string[];
+    stateKeys: string[];
+}[];

package/dist/src/scripts/store.js

@@ -0,0 +1,48 @@
+/**
+ * Injected script for discovering Pinia or Vuex stores and their actions/state representations.
+ *
+ * This function is serialized via `.toString()` and evaluated inside the page context,
+ * so the types below only exist at the TS boundary — the runtime shapes are whatever
+ * Pinia/Vuex put on the Vue app. We use narrow structural types for the fields we touch.
+ */
+export function discoverStores() {
+    const stores = [];
+    try {
+        const app = document.querySelector('#app');
+        if (!app?.__vue_app__)
+            return stores;
+        const gp = app.__vue_app__.config?.globalProperties;
+        // Pinia stores
+        const pinia = gp?.$pinia;
+        if (pinia?._s) {
+            pinia._s.forEach((store, id) => {
+                const actions = [];
+                const stateKeys = [];
+                for (const k in store) {
+                    try {
+                        if (k.startsWith('$') || k.startsWith('_'))
+                            continue;
+                        if (typeof store[k] === 'function')
+                            actions.push(k);
+                        else
+                            stateKeys.push(k);
+                    }
+                    catch { }
+                }
+                stores.push({ type: 'pinia', id, actions: actions.slice(0, 20), stateKeys: stateKeys.slice(0, 15) });
+            });
+        }
+        // Vuex store modules
+        const vuex = gp?.$store;
+        if (vuex?._modules?.root?._children) {
+            const children = vuex._modules.root._children;
+            for (const [modName, mod] of Object.entries(children)) {
+                const actions = Object.keys(mod._rawModule?.actions ?? {}).slice(0, 20);
+                const stateKeys = Object.keys(mod.state ?? {}).slice(0, 15);
+                stores.push({ type: 'vuex', id: modName, actions, stateKeys });
+            }
+        }
+    }
+    catch { }
+    return stores;
+}

package/dist/src/serialization.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Serialization and formatting helpers for CLI commands and args.
+ *
+ * Used by the `list` command, Commander --help, and build-manifest.
+ * Separated from registry.ts to keep the registry focused on types + registration.
+ */
+import type { Arg, CliCommand } from './registry.js';
+export type SerializedArg = {
+    name: string;
+    type: string;
+    required: boolean;
+    valueRequired: boolean;
+    positional: boolean;
+    choices: string[];
+    default: unknown;
+    help: string;
+};
+/** Stable arg schema — every field is always present (no sparse objects). */
+export declare function serializeArg(a: Arg): SerializedArg;
+/** Full command metadata for structured output (json/yaml). */
+export declare function serializeCommand(cmd: CliCommand): {
+    command: string;
+    site: string;
+    name: string;
+    aliases: string[];
+    description: string;
+    access: import("./registry.js").CommandAccess;
+    strategy: string;
+    browser: boolean;
+    args: SerializedArg[];
+    columns: string[];
+    domain: string | null;
+    example: string;
+    defaultFormat: "table" | "plain" | "json" | "yaml" | "yml" | "md" | "markdown" | "csv" | null;
+    siteSession: import("./registry.js").SiteSessionMode | null;
+};
+/** Human-readable arg summary: `<required> [optional]` style. */
+export declare function formatArgSummary(args: Arg[]): string;
+/** Agent-facing canonical invocation. Adapter authors may override with `example`. */
+export declare function formatCommandExample(cmd: CliCommand): string;
+/** Generate the --help appendix showing registry metadata not exposed by Commander. */
+export declare function formatRegistryHelpText(cmd: CliCommand): string;

package/dist/src/serialization.js

@@ -0,0 +1,103 @@
+/**
+ * Serialization and formatting helpers for CLI commands and args.
+ *
+ * Used by the `list` command, Commander --help, and build-manifest.
+ * Separated from registry.ts to keep the registry focused on types + registration.
+ */
+import { fullName, strategyLabel } from './registry.js';
+import { CLI_COMMAND } from './brand.js';
+/** Stable arg schema — every field is always present (no sparse objects). */
+export function serializeArg(a) {
+    return {
+        name: a.name,
+        type: a.type ?? 'string',
+        required: !!a.required,
+        valueRequired: !!a.valueRequired,
+        positional: !!a.positional,
+        choices: a.choices ?? [],
+        default: a.default ?? null,
+        help: a.help ?? '',
+    };
+}
+/** Full command metadata for structured output (json/yaml). */
+export function serializeCommand(cmd) {
+    return {
+        command: fullName(cmd),
+        site: cmd.site,
+        name: cmd.name,
+        aliases: cmd.aliases ?? [],
+        description: cmd.description,
+        access: cmd.access,
+        strategy: strategyLabel(cmd),
+        browser: !!cmd.browser,
+        args: cmd.args.map(serializeArg),
+        columns: cmd.columns ?? [],
+        domain: cmd.domain ?? null,
+        example: formatCommandExample(cmd),
+        defaultFormat: cmd.defaultFormat ?? null,
+        siteSession: cmd.siteSession ?? null,
+    };
+}
+// ── Formatting ──────────────────────────────────────────────────────────────
+/** Human-readable arg summary: `<required> [optional]` style. */
+export function formatArgSummary(args) {
+    return args
+        .map(a => {
+        if (a.positional)
+            return a.required ? `<${a.name}>` : `[${a.name}]`;
+        return a.required ? `--${a.name}` : `[--${a.name}]`;
+    })
+        .join(' ');
+}
+function summarizeChoices(choices) {
+    if (choices.length <= 4)
+        return choices.join(', ');
+    return `${choices.slice(0, 4).join(', ')}, ... (+${choices.length - 4} more)`;
+}
+function formatValuePlaceholder(name) {
+    return `<${name}>`;
+}
+/** Agent-facing canonical invocation. Adapter authors may override with `example`. */
+export function formatCommandExample(cmd) {
+    if (cmd.example?.trim())
+        return cmd.example.trim();
+    const parts = [CLI_COMMAND, cmd.site, cmd.name];
+    for (const arg of cmd.args) {
+        if (arg.positional && arg.required) {
+            parts.push(formatValuePlaceholder(arg.name));
+        }
+    }
+    for (const arg of cmd.args) {
+        if (arg.positional || !arg.required)
+            continue;
+        parts.push(`--${arg.name}`);
+        if (arg.type !== 'bool' && arg.type !== 'boolean')
+            parts.push(formatValuePlaceholder(arg.name));
+    }
+    parts.push('-f', 'yaml');
+    return parts.join(' ');
+}
+/** Generate the --help appendix showing registry metadata not exposed by Commander. */
+export function formatRegistryHelpText(cmd) {
+    const lines = [];
+    const choicesArgs = cmd.args.filter(a => a.choices?.length);
+    for (const a of choicesArgs) {
+        const prefix = a.positional ? `<${a.name}>` : `--${a.name}`;
+        const def = a.default != null ? `  (default: ${a.default})` : '';
+        lines.push(`  ${prefix}: ${summarizeChoices(a.choices)}${def}`);
+    }
+    const meta = [];
+    meta.push(`Access: ${cmd.access}`);
+    meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
+    if (cmd.domain)
+        meta.push(`Domain: ${cmd.domain}`);
+    if (cmd.defaultFormat)
+        meta.push(`Default format: ${cmd.defaultFormat}`);
+    if (cmd.aliases?.length)
+        meta.push(`Aliases: ${cmd.aliases.join(', ')}`);
+    lines.push(meta.join(' | '));
+    lines.push(`Example: ${formatCommandExample(cmd)}`);
+    if (cmd.columns?.length)
+        lines.push(`Output columns: ${cmd.columns.join(', ')}`);
+    return '\n' + lines.join('\n') + '\n';
+}

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

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