@diviops/mcp-server 1.5.10 → 1.5.12

package/dist/preset-cli/cli.js

@@ -0,0 +1,429 @@
+/**
+ * `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 { emitButtonGroupPreset, buildPresetCreateBody, } from "./button-emitter.js";
+import { emitHeadingFontGroupPreset, buildHeadingFontPresetCreateBody, UnsupportedVariantCombinationError, } from "./heading-font-emitter.js";
+import { EvidenceGateError } from "./registry.js";
+import { applyButtonPreset, applyHeadingFontPreset, buildClientFromEnv, CredentialsMissingError, CapabilityMissingError, } from "./write-path.js";
+export const EXIT = {
+    OK: 0,
+    INVALID_INPUT: 1,
+    EVIDENCE_GATE: 2,
+    CAPABILITY_MISSING: 3,
+    WRITE_ERROR: 4,
+};
+const realIO = {
+    out: (t) => process.stdout.write(t + "\n"),
+    err: (t) => process.stderr.write(t + "\n"),
+};
+const HELP = `diviops-preset — Divi 5.5.x canonical preset-emitter CLI
+
+USAGE
+  diviops-preset button [options]         Emit a divi/button group preset
+  diviops-preset heading-font [options]   Emit a divi/font group preset for
+                                          divi/heading
+  diviops-preset --help                   Show this help
+
+MODE
+  --dry-run            Compose + print canonical JSON only (DEFAULT).
+                       No credentials, no handshake, no network.
+  --apply              Capability-gate, then POST to /preset/create.
+                       Requires WP_URL / WP_USER / WP_APP_PASSWORD.
+
+button OPTIONS (all styling fields optional; emit-on-specification only)
+  --name <string>          Preset display name (required).
+  --bg-color <value>       Desktop background color. Hex literal, or a
+                           bare gcid-*/gvid-* token, or a $variable(...)$ token.
+  --bg-color-hover <value> Hover background color (same value forms).
+  --radius-top-left <v>      Border radius corner. Any subset of the four
+  --radius-top-right <v>     corners; the radius widget emits a sync flag
+  --radius-bottom-left <v>   alongside any corner ("on" only when all four
+  --radius-bottom-right <v>  corners are given and equal, else "off";
+                             override with --radius-sync).
+  --radius-sync <on|off>     Explicit radius sync flag.
+  --radius <v>               Shorthand: sets all four corners to <v>.
+  --border-width <v>       Outline-button border width.
+  --border-style <v>       Outline-button border style (solid|dashed|...).
+  --border-color <value>   Outline-button border color (same value forms).
+  --font-family <string>   Button font family (literal string).
+  --font-weight <string>   Button font weight (e.g. "600").
+  --font-color <value>     Button font color (same value forms).
+  --font-size <v>          Button font size (e.g. "16px").
+  --bypass-hover-padding-gate
+                           Opt-in: emit button.decoration.button.desktop
+                           .value.padding.top="0px" (hover-padding-gate
+                           workaround). Off by default.
+
+heading-font OPTIONS (all styling fields optional; emit-on-specification only)
+  --name <string>          Preset display name (required).
+  --pattern <google|local> Required. Selects the verified variant:
+                             google — Pattern A: plain family + explicit
+                                      numeric weight (e.g. family "Inter",
+                                      weight "700"). Verified against
+                                      round-1a fixture.
+                             local  — Pattern B: weight-encoded family
+                                      string (e.g. family "Sora 700") with
+                                      NO --font-weight. Used for local-
+                                      hosted/EU-GDPR font flows. Verified
+                                      against round-1b fixture.
+                           Pattern A and Pattern B are distinct registry
+                           variants — there is NO default; omitting
+                           --pattern is invalid input.
+  --font-family <string>   Font family. Pattern A: plain name ("Inter").
+                           Pattern B: weight-encoded ("Sora 700").
+  --font-weight <string>   Font weight (e.g. "700"). Pattern A only —
+                           passing it with --pattern local is refused.
+  --font-color <value>     Font color. Hex literal, bare gcid-*/gvid-*
+                           token, or already-formed $variable(...)$ token.
+  --font-size <v>          Font size (e.g. "48px").
+  --font-line-height <v>   Font line-height (e.g. "1.1").
+
+EXIT CODES
+  0 success   1 invalid input   2 evidence-gate refusal
+  3 capability missing   4 write error
+
+EXAMPLES
+  diviops-preset button --name "Primary" --bg-color gcid-primary-color \\
+    --bg-color-hover gcid-secondary-color --radius 8px \\
+    --font-family Inter --font-weight 600 --font-color gcid-body-color
+
+  diviops-preset button --name "Primary" --bg-color "#2563eb" --apply
+
+  diviops-preset heading-font --name "Heading H1" --pattern google \\
+    --font-family Inter --font-weight 700 \\
+    --font-color gcid-heading-color --font-size 48px
+
+  diviops-preset heading-font --name "Heading H1 (local)" --pattern local \\
+    --font-family "Sora 700" \\
+    --font-color gcid-heading-color --font-size 48px
+`;
+const VALUE_FLAGS = new Set([
+    "--name",
+    "--bg-color",
+    "--bg-color-hover",
+    "--radius",
+    "--radius-top-left",
+    "--radius-top-right",
+    "--radius-bottom-left",
+    "--radius-bottom-right",
+    "--radius-sync",
+    "--border-width",
+    "--border-style",
+    "--border-color",
+    "--font-family",
+    "--font-weight",
+    "--font-color",
+    "--font-size",
+    "--font-line-height",
+    "--pattern",
+]);
+/** Parse argv (after `node script`) into a structured shape. Throws on unknown flags. */
+export function parseArgs(argv) {
+    const parsed = {
+        command: null,
+        help: false,
+        apply: false,
+        dryRun: false,
+        options: new Map(),
+    };
+    let i = 0;
+    // First non-flag token is the command.
+    if (argv.length > 0 && !argv[0].startsWith("-")) {
+        parsed.command = argv[0];
+        i = 1;
+    }
+    for (; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--help" || tok === "-h") {
+            parsed.help = true;
+            continue;
+        }
+        if (tok === "--apply") {
+            parsed.apply = true;
+            continue;
+        }
+        if (tok === "--dry-run") {
+            parsed.dryRun = true;
+            continue;
+        }
+        if (tok === "--bypass-hover-padding-gate") {
+            parsed.options.set(tok, true);
+            continue;
+        }
+        if (VALUE_FLAGS.has(tok)) {
+            const val = argv[i + 1];
+            if (val === undefined || val.startsWith("--")) {
+                throw new UsageError(`Flag ${tok} requires a value.`);
+            }
+            parsed.options.set(tok, val);
+            i++;
+            continue;
+        }
+        if (!tok.startsWith("-") && parsed.command === null) {
+            parsed.command = tok;
+            continue;
+        }
+        throw new UsageError(`Unknown flag or argument: ${tok}`);
+    }
+    if (parsed.apply && parsed.dryRun) {
+        throw new UsageError("--apply and --dry-run are mutually exclusive.");
+    }
+    // dry-run is the default-safe mode when neither is given.
+    if (!parsed.apply)
+        parsed.dryRun = true;
+    return parsed;
+}
+export class UsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageError";
+    }
+}
+/** Known CLI commands. The CLI rejects anything else with EXIT.INVALID_INPUT. */
+const KNOWN_COMMANDS = new Set(["button", "heading-font"]);
+/** Map parsed `button` options into the emitter input shape. */
+export function buildButtonInput(parsed) {
+    const opt = (k) => {
+        const v = parsed.options.get(k);
+        return typeof v === "string" ? v : undefined;
+    };
+    const name = opt("--name");
+    if (!name) {
+        throw new UsageError("button command requires --name <string>.");
+    }
+    const input = { name };
+    const bg = opt("--bg-color");
+    if (bg !== undefined)
+        input.bg_color = bg;
+    const bgh = opt("--bg-color-hover");
+    if (bgh !== undefined)
+        input.bg_color_hover = bgh;
+    // Radius — shorthand --radius sets all four corners.
+    const radius = {};
+    const radiusAll = opt("--radius");
+    if (radiusAll !== undefined) {
+        radius.topLeft = radiusAll;
+        radius.topRight = radiusAll;
+        radius.bottomLeft = radiusAll;
+        radius.bottomRight = radiusAll;
+    }
+    const rtl = opt("--radius-top-left");
+    if (rtl !== undefined)
+        radius.topLeft = rtl;
+    const rtr = opt("--radius-top-right");
+    if (rtr !== undefined)
+        radius.topRight = rtr;
+    const rbl = opt("--radius-bottom-left");
+    if (rbl !== undefined)
+        radius.bottomLeft = rbl;
+    const rbr = opt("--radius-bottom-right");
+    if (rbr !== undefined)
+        radius.bottomRight = rbr;
+    const rsync = opt("--radius-sync");
+    if (rsync !== undefined) {
+        if (rsync !== "on" && rsync !== "off") {
+            throw new UsageError('--radius-sync must be "on" or "off".');
+        }
+        radius.sync = rsync;
+    }
+    if (Object.keys(radius).length > 0)
+        input.radius = radius;
+    // Outline border styles.
+    const border = {};
+    const bw = opt("--border-width");
+    if (bw !== undefined)
+        border.width = bw;
+    const bs = opt("--border-style");
+    if (bs !== undefined)
+        border.style = bs;
+    const bc = opt("--border-color");
+    if (bc !== undefined)
+        border.color = bc;
+    if (Object.keys(border).length > 0)
+        input.border = border;
+    // Font.
+    const font = {};
+    const ff = opt("--font-family");
+    if (ff !== undefined)
+        font.family = ff;
+    const fw = opt("--font-weight");
+    if (fw !== undefined)
+        font.weight = fw;
+    const fc = opt("--font-color");
+    if (fc !== undefined)
+        font.color = fc;
+    const fs = opt("--font-size");
+    if (fs !== undefined)
+        font.size = fs;
+    if (Object.keys(font).length > 0)
+        input.font = font;
+    if (parsed.options.get("--bypass-hover-padding-gate") === true) {
+        input.bypass_hover_padding_gate = true;
+    }
+    return input;
+}
+/** Map parsed `heading-font` options into the heading-font emitter input shape. */
+export function buildHeadingFontInput(parsed) {
+    const opt = (k) => {
+        const v = parsed.options.get(k);
+        return typeof v === "string" ? v : undefined;
+    };
+    const name = opt("--name");
+    if (!name) {
+        throw new UsageError("heading-font command requires --name <string>.");
+    }
+    // --pattern is REQUIRED — Pattern A vs Pattern B are distinct registry/
+    // evidence variants and there is no safe default. An omitted --pattern
+    // is invalid input; the CLI fails BEFORE emission (no guessing).
+    const patternRaw = opt("--pattern");
+    if (patternRaw === undefined) {
+        throw new UsageError("heading-font command requires --pattern <google|local>. " +
+            "There is no default — Pattern A (google) and Pattern B (local) are distinct " +
+            "registry variants and must be selected intentionally.");
+    }
+    if (patternRaw !== "google" && patternRaw !== "local") {
+        throw new UsageError(`--pattern must be "google" or "local"; got ${JSON.stringify(patternRaw)}.`);
+    }
+    const pattern = patternRaw;
+    const input = { name, pattern };
+    const family = opt("--font-family");
+    if (family !== undefined)
+        input.family = family;
+    const weight = opt("--font-weight");
+    if (weight !== undefined)
+        input.weight = weight;
+    const color = opt("--font-color");
+    if (color !== undefined)
+        input.color = color;
+    const size = opt("--font-size");
+    if (size !== undefined)
+        input.size = size;
+    const lineHeight = opt("--font-line-height");
+    if (lineHeight !== undefined)
+        input.lineHeight = lineHeight;
+    return input;
+}
+/**
+ * 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 async function run(argv, io = realIO, serverVersion) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (err) {
+        io.err(err instanceof Error ? err.message : String(err));
+        io.err("");
+        io.err("Run `diviops-preset --help` for usage.");
+        return EXIT.INVALID_INPUT;
+    }
+    if (parsed.help || (parsed.command === null && parsed.options.size === 0)) {
+        io.out(HELP);
+        return EXIT.OK;
+    }
+    if (parsed.command === null || !KNOWN_COMMANDS.has(parsed.command)) {
+        io.err(`Unknown command: ${parsed.command ?? "(none)"}. ` +
+            `Known commands: ${[...KNOWN_COMMANDS].sort().join(", ")}.`);
+        io.err("Run `diviops-preset --help` for usage.");
+        return EXIT.INVALID_INPUT;
+    }
+    // --- compose + gate -------------------------------------------------
+    // Per-command branch produces:
+    //  - `dryRunBody`: the canonical JSON to print in --dry-run mode.
+    //  - `applyFn`: a closure that issues the apply-mode write when the
+    //    capability check passes. Both branches reuse the existing write-
+    //    path plumbing (`assertStorageCapability` → `/preset/create`).
+    let dryRunBody;
+    let applyFn;
+    try {
+        if (parsed.command === "button") {
+            const input = buildButtonInput(parsed);
+            const entry = emitButtonGroupPreset(input);
+            dryRunBody = buildPresetCreateBody(entry, { dry_run: true });
+            applyFn = (client, sv) => applyButtonPreset(client, entry, { serverVersion: sv });
+        }
+        else {
+            // heading-font
+            const input = buildHeadingFontInput(parsed);
+            const entry = emitHeadingFontGroupPreset(input);
+            dryRunBody = buildHeadingFontPresetCreateBody(entry, { dry_run: true });
+            applyFn = (client, sv) => applyHeadingFontPreset(client, entry, { serverVersion: sv });
+        }
+    }
+    catch (err) {
+        if (err instanceof EvidenceGateError) {
+            io.err(err.message);
+            return EXIT.EVIDENCE_GATE;
+        }
+        if (err instanceof UsageError) {
+            io.err(err.message);
+            io.err("Run `diviops-preset --help` for usage.");
+            return EXIT.INVALID_INPUT;
+        }
+        if (err instanceof UnsupportedVariantCombinationError) {
+            // Distinct from EvidenceGateError: the registry IS complete for the
+            // verified variants, but the caller asked for a combination outside
+            // any verified variant. Surfaces as invalid input (exit 1).
+            io.err(err.message);
+            return EXIT.INVALID_INPUT;
+        }
+        io.err(err instanceof Error ? err.message : String(err));
+        return EXIT.INVALID_INPUT;
+    }
+    // --- dry-run --------------------------------------------------------
+    if (parsed.dryRun) {
+        io.out(JSON.stringify(dryRunBody, null, 2));
+        return EXIT.OK;
+    }
+    // --- apply ----------------------------------------------------------
+    try {
+        const client = buildClientFromEnv();
+        // Apply mode requires the server version for the plugin handshake; the
+        // /handshake route gates on `mcp_server_version`. The bin entrypoint
+        // always supplies it — guard here so apply mode can never reach the
+        // handshake with an undefined/empty version.
+        if (!serverVersion) {
+            io.err("Apply mode requires the server version for the plugin handshake. " +
+                "This is an internal error — invoke via the `diviops-preset` bin.");
+            return EXIT.WRITE_ERROR;
+        }
+        const result = await applyFn(client, serverVersion);
+        io.out(JSON.stringify(result, null, 2));
+        return EXIT.OK;
+    }
+    catch (err) {
+        if (err instanceof CapabilityMissingError) {
+            io.err(err.message);
+            return EXIT.CAPABILITY_MISSING;
+        }
+        if (err instanceof CredentialsMissingError) {
+            io.err(err.message);
+            return EXIT.INVALID_INPUT;
+        }
+        io.err(`Write failed: ${err instanceof Error ? err.message : String(err)}`);
+        return EXIT.WRITE_ERROR;
+    }
+}

package/dist/preset-cli/heading-font-emitter.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `divi/font` heading group-preset emitter — Track 5 vertical slice.
+ *
+ * Emits a byte-canonical Divi 5.5.x `type: "group"` `divi/font` preset
+ * targeting `divi/heading` at `attrs.title.decoration.font.font.desktop.value.*`,
+ * gated by the verified-attrs registry. Canonical shape:
+ * `docs/verification/canonical-preset-shapes-per-module-type-2026-05-18.md`
+ * (`divi/font` section), cross-checked against
+ * `docs/verification/evidence/canonical-shape-dumps-2026-05-18/round-1a-heading-h1-pattern-a-google.json`
+ * and `…/round-1b-heading-h1-pattern-b-local.json`.
+ *
+ * Two verified Pattern variants live in the registry — they are NOT
+ * interchangeable evidence. The caller MUST select one explicitly:
+ *
+ *  - Pattern A (Google Fonts CDN): plain family + explicit numeric weight.
+ *    Registry entry: `divi/font` with `pattern_variant: "google_fonts_pattern_a"`.
+ *    Verified evidence: round-1a fixture.
+ *  - Pattern B (local-hosted, EU-GDPR): weight encoded into the family
+ *    string ("Sora 700") and NO `weight` key at all in the preset.
+ *    Registry entry: `divi/font` with `pattern_variant: "local_hosted_pattern_b"`.
+ *    Verified evidence: round-1b fixture.
+ *
+ * Shape rules enforced here:
+ *  - Emit-on-specification only — omitted params produce NO keys.
+ *  - `attrs == styleAttrs == renderAttrs` at the route layer (the plugin's
+ *    `/preset/create` route mirrors `attrs` into all three buckets to match
+ *    VB save semantics); the CLI request body only carries `attrs`.
+ *  - Double-font nesting: `title.decoration.font.font.desktop.value.*` —
+ *    outer `font` is the decoration category, inner `font` is the attr
+ *    name within that category.
+ *  - Pattern B with an explicit `weight` is REFUSED — the verified Pattern
+ *    B capture has no `weight` key and there is no registry entry
+ *    authorizing local-hosted-with-explicit-weight.
+ */
+import { type VerifiedAttrsRegistry } from "./registry.js";
+export declare const HEADING_FONT_MODULE = "divi/heading";
+export declare const HEADING_FONT_GROUP_NAME = "divi/font";
+export declare const HEADING_FONT_GROUP_ID = "designTitleText";
+export declare const HEADING_FONT_PATTERN_FAMILY = "divi/font";
+/** The two verified pattern variants for `divi/font` on `divi/heading`. */
+export declare const HEADING_FONT_PATTERN_VARIANTS: {
+    readonly google: "google_fonts_pattern_a";
+    readonly local: "local_hosted_pattern_b";
+};
+export type HeadingFontPattern = "google" | "local";
+export interface HeadingFontEmitterInput {
+    /** Required display name for the preset. */
+    name: string;
+    /**
+     * Required pattern selector. There is no default — Pattern A and
+     * Pattern B are distinct registry/evidence variants and the caller
+     * must select intentionally.
+     */
+    pattern: HeadingFontPattern;
+    /**
+     * Font family.
+     *  - Pattern A (google): plain family name, e.g. `"Inter"`.
+     *  - Pattern B (local):  weight-encoded family name, e.g. `"Sora 700"`.
+     */
+    family?: string;
+    /**
+     * Font weight (numeric-string, e.g. `"700"`).
+     *  - Pattern A: optional; emitted when specified.
+     *  - Pattern B: PROHIBITED — passing a weight in `local` mode is a
+     *    usage error (the verified Pattern B shape has no `weight` key,
+     *    and there is no registry entry vouching for that combination).
+     */
+    weight?: string;
+    /** Font color — literal hex or bare/formed variable token. */
+    color?: string;
+    /** Font size — literal (e.g. `"48px"`) or already-formed `$variable(...)$`. */
+    size?: string;
+    /** Line height — optional, emit-on-specification only. */
+    lineHeight?: string;
+}
+/** The composed canonical preset entry shape sent to `/preset/create`. */
+export interface HeadingFontPresetEntry {
+    type: "group";
+    module_name: string;
+    group_name: string;
+    group_id: string;
+    pattern_variant: string;
+    name: string;
+    attrs: Record<string, unknown>;
+}
+/**
+ * Raised when the caller passes a combination the registry does not
+ * authorize for the current Track — distinct from `EvidenceGateError`
+ * (registry-evidence shortfall) and `UsageError` (CLI arg parse).
+ */
+export declare class UnsupportedVariantCombinationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Compose the canonical `attrs.title.decoration.font.font.desktop.value`
+ * bag from the input. Emit-on-specification: only specified sub-fields
+ * produce keys.
+ */
+export declare function composeHeadingFontAttrs(input: HeadingFontEmitterInput): Record<string, unknown>;
+/**
+ * Emit a canonical `divi/font` heading group preset.
+ *
+ * 1. Validate input shape (name, pattern, Pattern B + weight refusal).
+ * 2. Compose `attrs.title.decoration.font.font.desktop.value.*`
+ *    (emit-on-specification).
+ * 3. Gate the chosen `(divi/font, pattern_variant)` cell on `divi/heading`
+ *    against the verified-attrs registry — throws `EvidenceGateError`
+ *    when effective evidence is below `VB_PRESET_STORAGE_VERIFIED`.
+ *
+ * `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`.
+ * The Round 1a/1b fixtures capture the post-write storage shape.
+ */
+export declare function emitHeadingFontGroupPreset(input: HeadingFontEmitterInput, registry?: VerifiedAttrsRegistry): HeadingFontPresetEntry;
+/**
+ * Build the `POST /diviops/v1/preset/create` request body from a heading
+ * font preset entry. Matches the body shape the `diviops_preset_create`
+ * MCP tool posts — the CLI reuses the existing route, it does not add one.
+ *
+ * `pattern_variant` is informational metadata on the in-memory entry and
+ * is NOT sent over the wire — the registry-gate decision happens
+ * client-side before the write.
+ */
+export declare function buildHeadingFontPresetCreateBody(entry: HeadingFontPresetEntry, opts?: {
+    dry_run?: boolean;
+}): Record<string, unknown>;