@diviops/mcp-server 1.5.10 → 1.5.11

package/dist/preset-cli/__tests__/write-path.test.js

@@ -0,0 +1,120 @@
+/**
+ * Apply-mode coverage — mocked only (no live substrate write, per #725 AC #8).
+ *
+ * Asserts: the capability gate (storage_multipath_probe_v1 present → proceed,
+ * absent → fail fast), the POST route + request body, and credential
+ * handling. The HTTP client is a stub; nothing touches the network.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyButtonPreset, assertStorageCapability, buildClientFromEnv, CapabilityMissingError, CredentialsMissingError, STORAGE_CAPABILITY, PRESET_CREATE_ROUTE, } from "../write-path.js";
+import { emitButtonGroupPreset } from "../button-emitter.js";
+import { loadRegistry } from "../registry.js";
+const registry = loadRegistry();
+function handshake(capabilities) {
+    return {
+        compatible: true,
+        plugin_version: "1.4.9",
+        min_server: "1.5.0",
+        divi: { active: true, version: "5.5.2" },
+        capabilities,
+    };
+}
+const TEST_SERVER_VERSION = "1.5.9";
+/** A mock client recording the calls it receives. */
+function mockClient(opts) {
+    const calls = [];
+    const handshakeVersions = [];
+    return {
+        calls,
+        handshakeVersions,
+        async handshake(serverVersion) {
+            handshakeVersions.push(serverVersion);
+            const hs = handshake(opts.capabilities);
+            if (opts.pluginVersion)
+                hs.plugin_version = opts.pluginVersion;
+            return hs;
+        },
+        async requestEnveloped(endpoint, options) {
+            calls.push({ endpoint, options });
+            return { ok: true, data: { preset_id: "mocked123" } };
+        },
+    };
+}
+test("assertStorageCapability proceeds when the capability is present", async () => {
+    const client = mockClient({ capabilities: { [STORAGE_CAPABILITY]: true } });
+    const hs = await assertStorageCapability(client, TEST_SERVER_VERSION);
+    assert.equal(hs.capabilities[STORAGE_CAPABILITY], true);
+    assert.deepEqual(client.handshakeVersions, [TEST_SERVER_VERSION], "the server version reaches handshake()");
+    assert.ok(client.handshakeVersions.every((v) => typeof v === "string" && v.length > 0), "handshake() never receives an undefined/empty server version");
+});
+test("assertStorageCapability fails fast when the capability is absent", async () => {
+    const client = mockClient({ capabilities: {}, pluginVersion: "1.4.8" });
+    await assert.rejects(() => assertStorageCapability(client, TEST_SERVER_VERSION), (err) => {
+        assert.ok(err instanceof CapabilityMissingError);
+        assert.equal(err.capability, STORAGE_CAPABILITY);
+        assert.match(err.message, /1\.4\.8/);
+        return true;
+    });
+});
+test("applyButtonPreset gates capability BEFORE issuing the write", async () => {
+    const client = mockClient({ capabilities: {} });
+    const entry = emitButtonGroupPreset({ name: "Primary", bg_color: "#111" }, registry);
+    await assert.rejects(() => applyButtonPreset(client, entry, { serverVersion: TEST_SERVER_VERSION }), CapabilityMissingError);
+    assert.equal(client.calls.length, 0, "no write issued when capability is absent");
+});
+test("applyButtonPreset posts to /preset/create with the canonical body", async () => {
+    const client = mockClient({ capabilities: { [STORAGE_CAPABILITY]: true } });
+    const entry = emitButtonGroupPreset({
+        name: "Primary",
+        bg_color: "gcid-primary-color",
+        bg_color_hover: "gcid-secondary-color",
+        radius: { topLeft: "8px", topRight: "8px", bottomLeft: "8px", bottomRight: "8px" },
+        font: { family: "Inter", weight: "600", color: "gcid-body-color" },
+    }, registry);
+    const result = await applyButtonPreset(client, entry, {
+        serverVersion: TEST_SERVER_VERSION,
+    });
+    assert.equal(client.handshakeVersions[0], TEST_SERVER_VERSION, "applyButtonPreset threads a non-empty server version into handshake()");
+    assert.ok((client.handshakeVersions[0] ?? "").length > 0, "handshake() server version is never empty in apply mode");
+    assert.equal(client.calls.length, 1, "exactly one write");
+    const call = client.calls[0];
+    assert.equal(call.endpoint, PRESET_CREATE_ROUTE, "posts to /preset/create");
+    const options = call.options;
+    assert.equal(options.method, "POST");
+    assert.equal(options.body.type, "group");
+    assert.equal(options.body.module_name, "divi/button");
+    assert.equal(options.body.group_name, "divi/button");
+    assert.equal(options.body.group_id, "button");
+    assert.equal(options.body.name, "Primary");
+    assert.deepEqual(options.body.attrs, entry.attrs);
+    assert.equal("dry_run" in options.body, false, "apply mode does not set dry_run");
+    assert.deepEqual(result, { ok: true, data: { preset_id: "mocked123" } });
+});
+test("applyButtonPreset threads dry_run into the body when requested", async () => {
+    const client = mockClient({ capabilities: { [STORAGE_CAPABILITY]: true } });
+    const entry = emitButtonGroupPreset({ name: "P", bg_color: "#111" }, registry);
+    await applyButtonPreset(client, entry, {
+        serverVersion: TEST_SERVER_VERSION,
+        dry_run: true,
+    });
+    const options = client.calls[0].options;
+    assert.equal(options.body.dry_run, true);
+});
+test("buildClientFromEnv throws CredentialsMissingError when env vars are absent", () => {
+    assert.throws(() => buildClientFromEnv({}), (err) => {
+        assert.ok(err instanceof CredentialsMissingError);
+        assert.match(err.message, /WP_URL/);
+        assert.match(err.message, /WP_USER/);
+        assert.match(err.message, /WP_APP_PASSWORD/);
+        return true;
+    });
+});
+test("buildClientFromEnv succeeds with the standard env vars", () => {
+    const client = buildClientFromEnv({
+        WP_URL: "http://divi5-ai.local",
+        WP_USER: "admin",
+        WP_APP_PASSWORD: "xxxx xxxx xxxx",
+    });
+    assert.ok(client, "WPClient constructed from WP_URL/WP_USER/WP_APP_PASSWORD");
+});

package/dist/preset-cli/bin.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * `diviops-preset` bin entrypoint.
+ *
+ * Thin wrapper around `run()` from `cli.ts`: forwards argv, prints output,
+ * and translates the structured exit code into `process.exitCode`.
+ */
+export {};

package/dist/preset-cli/bin.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * `diviops-preset` bin entrypoint.
+ *
+ * Thin wrapper around `run()` from `cli.ts`: forwards argv, prints output,
+ * and translates the structured exit code into `process.exitCode`.
+ */
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { run } from "./cli.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Read version from package.json — same single-source-of-truth pattern as
+// `src/index.ts`. Threaded into `run()` so apply-mode supplies it to the
+// plugin handshake (the /handshake route requires `mcp_server_version`).
+const SERVER_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, "..", "..", "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+run(process.argv.slice(2), undefined, SERVER_VERSION)
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    process.stderr.write(`diviops-preset: unexpected error: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exitCode = 4;
+});

package/dist/preset-cli/button-emitter.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `divi/button` group-preset emitter — Track 4 vertical slice.
+ *
+ * Emits a byte-canonical Divi 5.5.x `type: "group"` button preset at
+ * `attrs.button.decoration.{background, border, font}`, gated by the
+ * verified-attrs registry. Shape canon:
+ * `docs/verification/canonical-preset-shapes-per-module-type-2026-05-18.md`
+ * (`divi/button` section), cross-checked against
+ * `docs/verification/evidence/canonical-shape-dumps-2026-05-18/round-3-button-canonical-complete.json`.
+ *
+ * Shape rules enforced here (brief §3):
+ *  - Emit-on-specification only — omitted params produce NO keys.
+ *  - Hover shape is one wrapper shallower: `background.desktop.hover.color`
+ *    (NO `value` wrapper). Desktop is `background.desktop.value.color`.
+ *  - Border radius vocabulary `{topLeft, topRight, bottomLeft, bottomRight,
+ *    sync}`.
+ *  - Font double-nesting: `font.font.desktop.value.{family, weight, color,
+ *    size}`.
+ *  - `$variable()` color tokens use the `{name, settings}` object shape
+ *    with the trailing `)$`.
+ *  - Do NOT emit `attrs.font`/`attrs.spacing` top-level, `renderAttrs`, or
+ *    `button.decoration.button.desktop.value.*` — unless
+ *    `bypass_hover_padding_gate: true`, which adds only
+ *    `button.decoration.button.desktop.value.padding.top: "0px"`.
+ */
+import { type VerifiedAttrsRegistry } from "./registry.js";
+export declare const BUTTON_MODULE = "divi/button";
+export declare const BUTTON_GROUP_NAME = "divi/button";
+export declare const BUTTON_GROUP_ID = "button";
+/** Pattern families the button emitter touches in the registry. */
+export declare const BUTTON_PATTERN_FAMILIES: {
+    readonly background: "divi/button.background";
+    readonly border: "divi/button.border";
+    readonly font: "divi/button.font";
+};
+export interface ButtonRadiusInput {
+    topLeft?: string;
+    topRight?: string;
+    bottomLeft?: string;
+    bottomRight?: string;
+    /** Explicit override; otherwise auto-derived (see deriveRadiusSync). */
+    sync?: "on" | "off";
+}
+export interface ButtonBorderStylesInput {
+    width?: string;
+    style?: string;
+    color?: string;
+}
+export interface ButtonFontInput {
+    family?: string;
+    weight?: string;
+    color?: string;
+    size?: string;
+}
+export interface ButtonEmitterInput {
+    /** Required display name for the preset. */
+    name: string;
+    /** Desktop background color — literal hex or bare/formed variable token. */
+    bg_color?: string;
+    /** Hover background color — literal hex or bare/formed variable token. */
+    bg_color_hover?: string;
+    /** Border radius composable widget. */
+    radius?: ButtonRadiusInput;
+    /** Outline-button border styles (`styles.all`). */
+    border?: ButtonBorderStylesInput;
+    /** Button font. */
+    font?: ButtonFontInput;
+    /** Opt-in hover-padding-gate bypass corner (default false). */
+    bypass_hover_padding_gate?: boolean;
+}
+/** The composed canonical preset entry shape sent to `/preset/create`. */
+export interface ButtonPresetEntry {
+    type: "group";
+    module_name: string;
+    group_name: string;
+    group_id: string;
+    name: string;
+    attrs: Record<string, unknown>;
+}
+/** Deep clone via structuredClone with a JSON fallback. */
+export declare function deepClone<T>(value: T): T;
+/**
+ * Compose the canonical `attrs.button.decoration.*` bag from the input.
+ * Emit-on-specification: only specified sub-fields produce keys.
+ */
+export declare function composeButtonAttrs(input: ButtonEmitterInput): Record<string, unknown>;
+/**
+ * Gate every pattern family the composed attrs touch against the registry.
+ * Throws `EvidenceGateError` if any touched family is below the
+ * `VB_PRESET_STORAGE_VERIFIED` threshold. The `divi/button` decoration
+ * slot (`button.decoration.button.*`) used by the bypass corner is part
+ * of the `divi/button.border`/baseline write surface; it is not separately
+ * gated because the bypass corner is an explicit opt-in workaround, not a
+ * styling attr — but the three styling families ARE gated.
+ */
+export declare function gateButtonAttrs(attrs: Record<string, unknown>, registry: VerifiedAttrsRegistry): void;
+/**
+ * Emit a canonical `divi/button` group preset.
+ *
+ * 1. Compose `attrs.button.decoration.*` (emit-on-specification).
+ * 2. Gate every touched styling family against the verified-attrs
+ *    registry — throws if any is below `VB_PRESET_STORAGE_VERIFIED`.
+ * 3. Return the canonical preset entry. `styleAttrs` and `renderAttrs` are
+ *    intentionally NOT part of this entry — the plugin's `/preset/create`
+ *    route mirrors the single `attrs` bag into all three buckets, writing
+ *    `attrs == styleAttrs == renderAttrs` to match VB save semantics
+ *    (see `trait-preset.php` `preset_create`).
+ */
+export declare function emitButtonGroupPreset(input: ButtonEmitterInput, registry?: VerifiedAttrsRegistry): ButtonPresetEntry;
+/**
+ * Build the `POST /diviops/v1/preset/create` request body from a preset
+ * entry. Matches the body shape the `diviops_preset_create` MCP tool
+ * posts — the CLI reuses the existing route, it does not add one.
+ */
+export declare function buildPresetCreateBody(entry: ButtonPresetEntry, opts?: {
+    dry_run?: boolean;
+}): Record<string, unknown>;

package/dist/preset-cli/button-emitter.js

@@ -0,0 +1,218 @@
+/**
+ * `divi/button` group-preset emitter — Track 4 vertical slice.
+ *
+ * Emits a byte-canonical Divi 5.5.x `type: "group"` button preset at
+ * `attrs.button.decoration.{background, border, font}`, gated by the
+ * verified-attrs registry. Shape canon:
+ * `docs/verification/canonical-preset-shapes-per-module-type-2026-05-18.md`
+ * (`divi/button` section), cross-checked against
+ * `docs/verification/evidence/canonical-shape-dumps-2026-05-18/round-3-button-canonical-complete.json`.
+ *
+ * Shape rules enforced here (brief §3):
+ *  - Emit-on-specification only — omitted params produce NO keys.
+ *  - Hover shape is one wrapper shallower: `background.desktop.hover.color`
+ *    (NO `value` wrapper). Desktop is `background.desktop.value.color`.
+ *  - Border radius vocabulary `{topLeft, topRight, bottomLeft, bottomRight,
+ *    sync}`.
+ *  - Font double-nesting: `font.font.desktop.value.{family, weight, color,
+ *    size}`.
+ *  - `$variable()` color tokens use the `{name, settings}` object shape
+ *    with the trailing `)$`.
+ *  - Do NOT emit `attrs.font`/`attrs.spacing` top-level, `renderAttrs`, or
+ *    `button.decoration.button.desktop.value.*` — unless
+ *    `bypass_hover_padding_gate: true`, which adds only
+ *    `button.decoration.button.desktop.value.padding.top: "0px"`.
+ */
+import { loadRegistry, gateWriteAttr, } from "./registry.js";
+import { normalizeColorValue } from "./variable-token.js";
+export const BUTTON_MODULE = "divi/button";
+export const BUTTON_GROUP_NAME = "divi/button";
+export const BUTTON_GROUP_ID = "button";
+/** Pattern families the button emitter touches in the registry. */
+export const BUTTON_PATTERN_FAMILIES = {
+    background: "divi/button.background",
+    border: "divi/button.border",
+    font: "divi/button.font",
+};
+/**
+ * Derive the radius `sync` flag when the caller did not pass it explicitly.
+ *
+ * Per Rule 1a in `docs/verification/canonical-preset-shapes-per-module-type-2026-05-18.md`:
+ * composable-widget sync flags default to `"off"` when any sub-field is
+ * touched. Auto-deriving `"on"` is only correct when ALL FOUR corners are
+ * specified AND identical — a partial corner set (or a single corner) must
+ * derive `"off"`, never `"on"` (a 1-element set is trivially "all equal").
+ * An explicitly-passed `radius.sync` always wins.
+ */
+function deriveRadiusSync(radius) {
+    if (radius.sync === "on" || radius.sync === "off")
+        return radius.sync;
+    const corners = [
+        radius.topLeft,
+        radius.topRight,
+        radius.bottomLeft,
+        radius.bottomRight,
+    ].filter((v) => typeof v === "string");
+    if (corners.length === 0)
+        return "off";
+    return corners.length === 4 && corners.every((v) => v === corners[0])
+        ? "on"
+        : "off";
+}
+function isPlainObject(v) {
+    return (!!v && typeof v === "object" && !Array.isArray(v));
+}
+/** Deep clone via structuredClone with a JSON fallback. */
+export function deepClone(value) {
+    if (typeof structuredClone === "function")
+        return structuredClone(value);
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Compose the canonical `attrs.button.decoration.*` bag from the input.
+ * Emit-on-specification: only specified sub-fields produce keys.
+ */
+export function composeButtonAttrs(input) {
+    const decoration = {};
+    // --- background -----------------------------------------------------
+    if (input.bg_color !== undefined || input.bg_color_hover !== undefined) {
+        const desktop = {};
+        if (input.bg_color !== undefined) {
+            desktop.value = { color: normalizeColorValue(input.bg_color) };
+        }
+        if (input.bg_color_hover !== undefined) {
+            // Hover is one wrapper shallower — NO `value` between hover and color.
+            desktop.hover = { color: normalizeColorValue(input.bg_color_hover) };
+        }
+        decoration.background = { desktop };
+    }
+    // --- border ---------------------------------------------------------
+    const borderValue = {};
+    if (input.radius) {
+        const r = input.radius;
+        const radius = {};
+        if (r.topLeft !== undefined)
+            radius.topLeft = r.topLeft;
+        if (r.topRight !== undefined)
+            radius.topRight = r.topRight;
+        if (r.bottomLeft !== undefined)
+            radius.bottomLeft = r.bottomLeft;
+        if (r.bottomRight !== undefined)
+            radius.bottomRight = r.bottomRight;
+        if (Object.keys(radius).length > 0) {
+            // Composable widget: `sync` emits alongside any corner.
+            radius.sync = deriveRadiusSync(r);
+            borderValue.radius = radius;
+        }
+    }
+    if (input.border) {
+        const b = input.border;
+        const all = {};
+        if (b.width !== undefined)
+            all.width = b.width;
+        if (b.style !== undefined)
+            all.style = b.style;
+        if (b.color !== undefined)
+            all.color = normalizeColorValue(b.color);
+        if (Object.keys(all).length > 0) {
+            borderValue.styles = { all };
+        }
+    }
+    if (Object.keys(borderValue).length > 0) {
+        decoration.border = { desktop: { value: borderValue } };
+    }
+    // --- font (double-nested font.font) --------------------------------
+    if (input.font) {
+        const f = input.font;
+        const value = {};
+        if (f.family !== undefined)
+            value.family = f.family;
+        if (f.weight !== undefined)
+            value.weight = f.weight;
+        if (f.color !== undefined)
+            value.color = normalizeColorValue(f.color);
+        if (f.size !== undefined)
+            value.size = f.size;
+        if (Object.keys(value).length > 0) {
+            decoration.font = { font: { desktop: { value } } };
+        }
+    }
+    // --- hover-padding-gate bypass (opt-in only) -----------------------
+    if (input.bypass_hover_padding_gate === true) {
+        decoration.button = { desktop: { value: { padding: { top: "0px" } } } };
+    }
+    return { button: { decoration } };
+}
+/**
+ * Gate every pattern family the composed attrs touch against the registry.
+ * Throws `EvidenceGateError` if any touched family is below the
+ * `VB_PRESET_STORAGE_VERIFIED` threshold. The `divi/button` decoration
+ * slot (`button.decoration.button.*`) used by the bypass corner is part
+ * of the `divi/button.border`/baseline write surface; it is not separately
+ * gated because the bypass corner is an explicit opt-in workaround, not a
+ * styling attr — but the three styling families ARE gated.
+ */
+export function gateButtonAttrs(attrs, registry) {
+    const decoration = (isPlainObject(attrs.button) ? attrs.button.decoration : undefined);
+    if (!isPlainObject(decoration))
+        return;
+    if (decoration.background !== undefined) {
+        gateWriteAttr(registry, BUTTON_MODULE, BUTTON_PATTERN_FAMILIES.background);
+    }
+    if (decoration.border !== undefined) {
+        gateWriteAttr(registry, BUTTON_MODULE, BUTTON_PATTERN_FAMILIES.border);
+    }
+    if (decoration.font !== undefined) {
+        gateWriteAttr(registry, BUTTON_MODULE, BUTTON_PATTERN_FAMILIES.font);
+    }
+}
+/**
+ * Emit a canonical `divi/button` group preset.
+ *
+ * 1. Compose `attrs.button.decoration.*` (emit-on-specification).
+ * 2. Gate every touched styling family against the verified-attrs
+ *    registry — throws if any is below `VB_PRESET_STORAGE_VERIFIED`.
+ * 3. Return the canonical preset entry. `styleAttrs` and `renderAttrs` are
+ *    intentionally NOT part of this entry — the plugin's `/preset/create`
+ *    route mirrors the single `attrs` bag into all three buckets, writing
+ *    `attrs == styleAttrs == renderAttrs` to match VB save semantics
+ *    (see `trait-preset.php` `preset_create`).
+ */
+export function emitButtonGroupPreset(input, registry = loadRegistry()) {
+    if (!input.name || typeof input.name !== "string") {
+        throw new Error("Button emitter requires a non-empty `name`.");
+    }
+    const attrs = composeButtonAttrs(input);
+    const decoration = attrs.button.decoration;
+    if (!decoration || Object.keys(decoration).length === 0) {
+        throw new Error("Button emitter produced an empty preset — pass at least one of " +
+            "bg_color, bg_color_hover, radius, border, or font.");
+    }
+    gateButtonAttrs(attrs, registry);
+    return {
+        type: "group",
+        module_name: BUTTON_MODULE,
+        group_name: BUTTON_GROUP_NAME,
+        group_id: BUTTON_GROUP_ID,
+        name: input.name,
+        attrs,
+    };
+}
+/**
+ * Build the `POST /diviops/v1/preset/create` request body from a preset
+ * entry. Matches the body shape the `diviops_preset_create` MCP tool
+ * posts — the CLI reuses the existing route, it does not add one.
+ */
+export function buildPresetCreateBody(entry, opts = {}) {
+    const body = {
+        module_name: entry.module_name,
+        name: entry.name,
+        attrs: entry.attrs,
+        type: entry.type,
+        group_name: entry.group_name,
+        group_id: entry.group_id,
+    };
+    if (opts.dry_run)
+        body.dry_run = true;
+    return body;
+}

package/dist/preset-cli/cli.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `diviops-preset` — standalone preset-emitter CLI (Track 4 scaffold).
+ *
+ * Emits byte-canonical Divi 5.5.x preset JSON, gated by the verified-attrs
+ * registry and routed through the existing storage-path contract. Track 4
+ * ships one emitter: `divi/button` group presets.
+ *
+ * Usage:
+ *   diviops-preset button [options]      Emit a divi/button group preset
+ *   diviops-preset --help                Show help
+ *
+ * Modes:
+ *   --dry-run (default)   Compose and print canonical JSON. No credentials,
+ *                         no handshake, no network.
+ *   --apply               Capability-gate + POST to /preset/create. Reuses
+ *                         WP_URL / WP_USER / WP_APP_PASSWORD env vars.
+ *
+ * Exit codes:
+ *   0  success
+ *   1  invalid input / usage error
+ *   2  evidence-gate refusal (attr below VB_PRESET_STORAGE_VERIFIED)
+ *   3  capability-missing (plugin lacks storage_multipath_probe_v1)
+ *   4  write / network error
+ */
+import { type ButtonEmitterInput } from "./button-emitter.js";
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly INVALID_INPUT: 1;
+    readonly EVIDENCE_GATE: 2;
+    readonly CAPABILITY_MISSING: 3;
+    readonly WRITE_ERROR: 4;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** Sink for CLI output — injectable so tests capture without touching real stdio. */
+export interface CliIO {
+    out(text: string): void;
+    err(text: string): void;
+}
+interface ParsedArgs {
+    command: string | null;
+    help: boolean;
+    apply: boolean;
+    dryRun: boolean;
+    options: Map<string, string | true>;
+}
+/** Parse argv (after `node script`) into a structured shape. Throws on unknown flags. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare class UsageError extends Error {
+    constructor(message: string);
+}
+/** Map parsed `button` options into the emitter input shape. */
+export declare function buildButtonInput(parsed: ParsedArgs): ButtonEmitterInput;
+/**
+ * Run the CLI. Returns the structured exit code (does NOT call
+ * `process.exit` — the thin bin wrapper does). `io` is injectable so
+ * tests capture output without touching real stdio.
+ */
+export declare function run(argv: string[], io?: CliIO, serverVersion?: string): Promise<ExitCode>;
+export {};