@diviops/mcp-server 1.5.10 → 1.5.12

package/dist/preset-cli/heading-font-emitter.js

@@ -0,0 +1,166 @@
+/**
+ * `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 { loadRegistry, gateWriteAttr, } from "./registry.js";
+import { normalizeColorValue } from "./variable-token.js";
+export const HEADING_FONT_MODULE = "divi/heading";
+export const HEADING_FONT_GROUP_NAME = "divi/font";
+export const HEADING_FONT_GROUP_ID = "designTitleText";
+export const HEADING_FONT_PATTERN_FAMILY = "divi/font";
+/** The two verified pattern variants for `divi/font` on `divi/heading`. */
+export const HEADING_FONT_PATTERN_VARIANTS = {
+    google: "google_fonts_pattern_a",
+    local: "local_hosted_pattern_b",
+};
+/**
+ * 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 class UnsupportedVariantCombinationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedVariantCombinationError";
+    }
+}
+/**
+ * Compose the canonical `attrs.title.decoration.font.font.desktop.value`
+ * bag from the input. Emit-on-specification: only specified sub-fields
+ * produce keys.
+ */
+export function composeHeadingFontAttrs(input) {
+    const value = {};
+    if (input.family !== undefined)
+        value.family = input.family;
+    if (input.weight !== undefined)
+        value.weight = input.weight;
+    if (input.color !== undefined)
+        value.color = normalizeColorValue(input.color);
+    if (input.size !== undefined)
+        value.size = input.size;
+    if (input.lineHeight !== undefined)
+        value.lineHeight = input.lineHeight;
+    return {
+        title: {
+            decoration: {
+                font: {
+                    font: {
+                        desktop: {
+                            value,
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+/**
+ * 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 function emitHeadingFontGroupPreset(input, registry = loadRegistry()) {
+    if (!input.name || typeof input.name !== "string") {
+        throw new Error("Heading-font emitter requires a non-empty `name`.");
+    }
+    if (input.pattern !== "google" && input.pattern !== "local") {
+        throw new Error(`Heading-font emitter requires \`pattern\` to be "google" or "local"; got ${JSON.stringify(input.pattern)}. ` +
+            `There is no default — Pattern A (google) and Pattern B (local) are distinct registry/evidence variants.`);
+    }
+    // Pattern B + explicit weight is out-of-scope for Track 5. The verified
+    // Pattern B capture proves `weight` is absent; no registry entry
+    // currently authorizes a local-hosted-with-explicit-weight shape.
+    if (input.pattern === "local" && input.weight !== undefined) {
+        throw new UnsupportedVariantCombinationError(`Pattern B (local-hosted) does not support an explicit \`weight\` — the verified ` +
+            `Pattern B shape has no \`weight\` key, and there is no registry variant ` +
+            `authorizing local-hosted-with-explicit-weight. Encode the weight into the ` +
+            `family string instead (e.g. \`family: "Sora 700"\`). A future registry entry ` +
+            `can authorize that shape if VB evidence supports it.`);
+    }
+    const attrs = composeHeadingFontAttrs(input);
+    // Sanity check: at least one styling field was specified. An empty
+    // value bag is a usage error — there is nothing to write.
+    const value = attrs.title.decoration.font.font.desktop.value;
+    if (!value || Object.keys(value).length === 0) {
+        throw new Error("Heading-font emitter produced an empty preset — pass at least one of " +
+            "family, weight, color, size, or lineHeight.");
+    }
+    // Registry gate: variant-aware. Pattern A evidence must NOT vouch for
+    // Pattern B and vice versa — gateWriteAttr resolves by both family AND
+    // variant, so a missing/under-verified variant entry throws here.
+    const patternVariant = HEADING_FONT_PATTERN_VARIANTS[input.pattern];
+    gateWriteAttr(registry, HEADING_FONT_MODULE, HEADING_FONT_PATTERN_FAMILY, patternVariant);
+    return {
+        type: "group",
+        module_name: HEADING_FONT_MODULE,
+        group_name: HEADING_FONT_GROUP_NAME,
+        group_id: HEADING_FONT_GROUP_ID,
+        pattern_variant: patternVariant,
+        name: input.name,
+        attrs,
+    };
+}
+/**
+ * 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 function buildHeadingFontPresetCreateBody(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/registry.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Verified-attrs registry consumption for the preset-emitter CLI.
+ *
+ * Loads `diviops-server/data/verified-attrs.json` and resolves the
+ * EFFECTIVE evidence level per `(module, pattern-family)` cell using the
+ * `min()` rule documented in `docs/verification/README.md`:
+ *
+ *   effective_evidence = min(pattern_evidence_level,
+ *                            applicability[<module>].cell_evidence_level)
+ *
+ * A missing `applicability[<module>]` resolves to `UNVERIFIED` (0) — never
+ * to the pattern level. No invisible inheritance crosses the write
+ * threshold.
+ *
+ * This module is the consumer side of the verified-attrs registry
+ * contract. It does NOT mutate the registry; if a needed cell is absent
+ * or under-verified, the caller fails and the gap is filed as a backlog
+ * candidate.
+ */
+/**
+ * Effective evidence required for a write emitter to emit an attr.
+ * `VB_PRESET_STORAGE_VERIFIED` has numeric ordering 4.
+ */
+export declare const WRITE_EMITTER_THRESHOLD_LEVEL = "VB_PRESET_STORAGE_VERIFIED";
+export interface ApplicabilityCell {
+    wrapper?: string;
+    preset_type?: string;
+    group_name?: string;
+    group_id?: string;
+    cell_evidence_level?: string;
+    cell_divi_version?: string;
+    verified_at?: string;
+    source?: string;
+    caveats?: string[];
+}
+export interface Tier12Entry {
+    pattern_family: string;
+    pattern_variant?: string;
+    pattern_evidence_level: string;
+    pattern_evidence_source?: string;
+    applicability?: Record<string, ApplicabilityCell>;
+}
+export interface VerifiedAttrsRegistry {
+    schema_version?: string;
+    registry_version?: string;
+    evidence_level_ordering: Record<string, number>;
+    tier1?: Tier12Entry[];
+    tier2?: Tier12Entry[];
+    tier3?: unknown[];
+}
+/** Resolution of a single `(module, pattern-family[, pattern-variant])` cell against the registry. */
+export interface EvidenceResolution {
+    patternFamily: string;
+    /** The matched entry's `pattern_variant`, if any. */
+    patternVariant?: string;
+    module: string;
+    /** Numeric pattern-level evidence (0–5). */
+    patternLevel: number;
+    patternLevelName: string;
+    /** Numeric cell-level evidence (0–5); 0 when applicability[<module>] is absent. */
+    cellLevel: number;
+    cellLevelName: string;
+    /** min(patternLevel, cellLevel). */
+    effectiveLevel: number;
+    effectiveLevelName: string;
+    /** True when applicability[<module>] is missing — cellLevel is the 0-fallback. */
+    applicabilityMissing: boolean;
+    /** Best-available durable source string for error messages. */
+    source: string;
+    /** The applicability cell, if present (carries group_name / group_id / wrapper). */
+    cell?: ApplicabilityCell;
+}
+/**
+ * Load and cache `data/verified-attrs.json`. The path is resolved relative
+ * to the compiled module location (`dist/preset-cli/registry.js` →
+ * `dist/../data/verified-attrs.json`), and also tolerates the `src/` layout
+ * for direct ts-node-style execution / tests.
+ */
+export declare function loadRegistry(explicitPath?: string): VerifiedAttrsRegistry;
+/** Reset the module-level cache. Used by tests. */
+export declare function resetRegistryCache(): void;
+/**
+ * Find a Tier 1 / Tier 2 entry by `pattern_family` and (optionally)
+ * `pattern_variant`. Tier 2 is searched first, then Tier 1.
+ *
+ * Some pattern families (e.g. `divi/font`) carry multiple entries that
+ * differ ONLY by `pattern_variant` (`google_fonts_pattern_a` vs
+ * `local_hosted_pattern_b`). When `patternVariant` is supplied, ONLY an
+ * entry whose `pattern_variant` matches exactly is returned — a Pattern-A
+ * entry must not vouch for a Pattern-B caller, and vice versa.
+ *
+ * When `patternVariant` is omitted, the legacy behavior holds: the first
+ * matching `pattern_family` is returned regardless of variant — only safe
+ * for families with a single entry. New variant-aware callers should pass
+ * the variant explicitly.
+ */
+export declare function findPatternEntry(registry: VerifiedAttrsRegistry, patternFamily: string, patternVariant?: string): Tier12Entry | undefined;
+/**
+ * Resolve effective evidence for a `(module, pattern-family[, pattern-variant])` cell.
+ *
+ * Throws if the pattern family (or, when supplied, the specific variant)
+ * is entirely absent from the registry — that is an unrecoverable gap
+ * (the CLI must fail, not guess).
+ */
+export declare function resolveEvidence(registry: VerifiedAttrsRegistry, module: string, patternFamily: string, patternVariant?: string): EvidenceResolution;
+/** Numeric ordering of the write-emitter threshold against a registry. */
+export declare function writeThresholdNumber(registry: VerifiedAttrsRegistry): number;
+/**
+ * Gate a write-targeted attr. Returns the resolution when it clears the
+ * `VB_PRESET_STORAGE_VERIFIED` threshold; throws an `EvidenceGateError`
+ * naming the attr, its effective level, and the registry source otherwise.
+ */
+export declare class EvidenceGateError extends Error {
+    readonly patternFamily: string;
+    readonly module: string;
+    readonly resolution: EvidenceResolution;
+    readonly thresholdNumber: number;
+    readonly thresholdName: string;
+    constructor(patternFamily: string, module: string, resolution: EvidenceResolution, thresholdNumber: number, thresholdName: string);
+}
+export declare function gateWriteAttr(registry: VerifiedAttrsRegistry, module: string, patternFamily: string, patternVariant?: string): EvidenceResolution;

package/dist/preset-cli/registry.js

@@ -0,0 +1,192 @@
+/**
+ * Verified-attrs registry consumption for the preset-emitter CLI.
+ *
+ * Loads `diviops-server/data/verified-attrs.json` and resolves the
+ * EFFECTIVE evidence level per `(module, pattern-family)` cell using the
+ * `min()` rule documented in `docs/verification/README.md`:
+ *
+ *   effective_evidence = min(pattern_evidence_level,
+ *                            applicability[<module>].cell_evidence_level)
+ *
+ * A missing `applicability[<module>]` resolves to `UNVERIFIED` (0) — never
+ * to the pattern level. No invisible inheritance crosses the write
+ * threshold.
+ *
+ * This module is the consumer side of the verified-attrs registry
+ * contract. It does NOT mutate the registry; if a needed cell is absent
+ * or under-verified, the caller fails and the gap is filed as a backlog
+ * candidate.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Effective evidence required for a write emitter to emit an attr.
+ * `VB_PRESET_STORAGE_VERIFIED` has numeric ordering 4.
+ */
+export const WRITE_EMITTER_THRESHOLD_LEVEL = "VB_PRESET_STORAGE_VERIFIED";
+let cachedRegistry = null;
+/**
+ * Load and cache `data/verified-attrs.json`. The path is resolved relative
+ * to the compiled module location (`dist/preset-cli/registry.js` →
+ * `dist/../data/verified-attrs.json`), and also tolerates the `src/` layout
+ * for direct ts-node-style execution / tests.
+ */
+export function loadRegistry(explicitPath) {
+    if (!explicitPath && cachedRegistry)
+        return cachedRegistry;
+    const candidates = explicitPath
+        ? [explicitPath]
+        : [
+            // dist/preset-cli/registry.js -> dist/../data
+            join(__dirname, "..", "..", "data", "verified-attrs.json"),
+            // src/preset-cli/registry.ts -> src/../data
+            join(__dirname, "..", "data", "verified-attrs.json"),
+        ];
+    let lastErr = null;
+    for (const p of candidates) {
+        try {
+            const raw = readFileSync(p, "utf8");
+            const parsed = JSON.parse(raw);
+            if (!explicitPath)
+                cachedRegistry = parsed;
+            return parsed;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    throw new Error(`Could not load verified-attrs.json (tried: ${candidates.join(", ")}). ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+}
+/** Reset the module-level cache. Used by tests. */
+export function resetRegistryCache() {
+    cachedRegistry = null;
+}
+function levelNumber(registry, name) {
+    if (!name)
+        return 0;
+    const n = registry.evidence_level_ordering[name];
+    return typeof n === "number" ? n : 0;
+}
+function levelName(registry, num) {
+    for (const [name, n] of Object.entries(registry.evidence_level_ordering)) {
+        if (n === num)
+            return name;
+    }
+    return "UNVERIFIED";
+}
+/**
+ * Find a Tier 1 / Tier 2 entry by `pattern_family` and (optionally)
+ * `pattern_variant`. Tier 2 is searched first, then Tier 1.
+ *
+ * Some pattern families (e.g. `divi/font`) carry multiple entries that
+ * differ ONLY by `pattern_variant` (`google_fonts_pattern_a` vs
+ * `local_hosted_pattern_b`). When `patternVariant` is supplied, ONLY an
+ * entry whose `pattern_variant` matches exactly is returned — a Pattern-A
+ * entry must not vouch for a Pattern-B caller, and vice versa.
+ *
+ * When `patternVariant` is omitted, the legacy behavior holds: the first
+ * matching `pattern_family` is returned regardless of variant — only safe
+ * for families with a single entry. New variant-aware callers should pass
+ * the variant explicitly.
+ */
+export function findPatternEntry(registry, patternFamily, patternVariant) {
+    const tiers = [registry.tier2 ?? [], registry.tier1 ?? []];
+    for (const tier of tiers) {
+        const hit = tier.find((e) => {
+            if (e.pattern_family !== patternFamily)
+                return false;
+            if (patternVariant !== undefined) {
+                return e.pattern_variant === patternVariant;
+            }
+            return true;
+        });
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * Resolve effective evidence for a `(module, pattern-family[, pattern-variant])` cell.
+ *
+ * Throws if the pattern family (or, when supplied, the specific variant)
+ * is entirely absent from the registry — that is an unrecoverable gap
+ * (the CLI must fail, not guess).
+ */
+export function resolveEvidence(registry, module, patternFamily, patternVariant) {
+    const entry = findPatternEntry(registry, patternFamily, patternVariant);
+    if (!entry) {
+        const variantSuffix = patternVariant !== undefined ? ` (variant "${patternVariant}")` : "";
+        throw new Error(`Pattern family "${patternFamily}"${variantSuffix} is absent from verified-attrs.json. ` +
+            `The CLI cannot emit an unregistered attr. File this as a registry-gap backlog candidate.`);
+    }
+    const patternLevel = levelNumber(registry, entry.pattern_evidence_level);
+    // Missing applicability[<module>] resolves to UNVERIFIED (0) — no
+    // invisible inheritance from the pattern level.
+    const cell = entry.applicability?.[module];
+    const applicabilityMissing = !cell;
+    const cellLevel = cell ? levelNumber(registry, cell.cell_evidence_level) : 0;
+    const effectiveLevel = Math.min(patternLevel, cellLevel);
+    const source = cell?.source ??
+        entry.pattern_evidence_source ??
+        "verified-attrs.json (no source field)";
+    return {
+        patternFamily,
+        patternVariant: entry.pattern_variant,
+        module,
+        patternLevel,
+        patternLevelName: entry.pattern_evidence_level,
+        cellLevel,
+        cellLevelName: cell?.cell_evidence_level ?? "UNVERIFIED",
+        effectiveLevel,
+        effectiveLevelName: levelName(registry, effectiveLevel),
+        applicabilityMissing,
+        source,
+        cell,
+    };
+}
+/** Numeric ordering of the write-emitter threshold against a registry. */
+export function writeThresholdNumber(registry) {
+    return levelNumber(registry, WRITE_EMITTER_THRESHOLD_LEVEL);
+}
+/**
+ * Gate a write-targeted attr. Returns the resolution when it clears the
+ * `VB_PRESET_STORAGE_VERIFIED` threshold; throws an `EvidenceGateError`
+ * naming the attr, its effective level, and the registry source otherwise.
+ */
+export class EvidenceGateError extends Error {
+    patternFamily;
+    module;
+    resolution;
+    thresholdNumber;
+    thresholdName;
+    constructor(patternFamily, module, resolution, thresholdNumber, thresholdName) {
+        const variantTag = resolution.patternVariant !== undefined
+            ? ` variant "${resolution.patternVariant}"`
+            : "";
+        super(`Evidence-gate refusal: attr family "${patternFamily}"${variantTag} on module "${module}" ` +
+            `has EFFECTIVE evidence ${resolution.effectiveLevelName} (${resolution.effectiveLevel}), ` +
+            `below the write threshold ${thresholdName} (${thresholdNumber}). ` +
+            (resolution.applicabilityMissing
+                ? `applicability["${module}"] is absent from the registry entry — resolved to UNVERIFIED (0). `
+                : `pattern=${resolution.patternLevelName}(${resolution.patternLevel}), ` +
+                    `cell=${resolution.cellLevelName}(${resolution.cellLevel}). `) +
+            `Registry source: ${resolution.source}. ` +
+            `The CLI will not emit an under-verified attr — file a registry-gap backlog candidate.`);
+        this.patternFamily = patternFamily;
+        this.module = module;
+        this.resolution = resolution;
+        this.thresholdNumber = thresholdNumber;
+        this.thresholdName = thresholdName;
+        this.name = "EvidenceGateError";
+    }
+}
+export function gateWriteAttr(registry, module, patternFamily, patternVariant) {
+    const resolution = resolveEvidence(registry, module, patternFamily, patternVariant);
+    const thresholdNumber = writeThresholdNumber(registry);
+    if (resolution.effectiveLevel < thresholdNumber) {
+        throw new EvidenceGateError(patternFamily, module, resolution, thresholdNumber, WRITE_EMITTER_THRESHOLD_LEVEL);
+    }
+    return resolution;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * `$variable()` color-token helpers for the preset-emitter CLI.
+ *
+ * Divi 5.5.x color bindings use the token grammar:
+ *
+ *   $variable({"type":"color","value":{"name":"gcid-heading-color","settings":{}}})$
+ *
+ * Two load-bearing rules (both from VB-verified memory):
+ *  - The token MUST end with `)$` — a missing trailing `$` causes silent
+ *    render failure (`feedback_variable_trailing_dollar`).
+ *  - The `value` payload MUST be an object `{name, settings}`, not a flat
+ *    `gcid-*` string — a flat string crashes PHP 8 in Divi's DynamicData
+ *    resolver (`feedback_variable_color_value_object_shape`).
+ *
+ * The CLI accepts a color param that is EITHER a literal (a hex string,
+ * or an already-formed `$variable(...)$` token) OR a bare `gcid-*` /
+ * `gvid-*` token name, which this module wraps into the canonical shape.
+ */
+/** An already-formed `$variable(...)$` token. */
+export declare function isVariableToken(value: string): boolean;
+/** A bare token name like `gcid-primary-color`. */
+export declare function isBareTokenName(value: string): boolean;
+/**
+ * Build a canonical `$variable()` color token from a bare token name.
+ *
+ * The inner JSON uses single-escape `\"` when the whole preset is later
+ * `JSON.stringify`-d — that is handled by JSON.stringify itself; here we
+ * return the raw string value (un-stringified), which is what belongs in
+ * the in-memory preset object.
+ */
+export declare function buildColorVariableToken(tokenName: string): string;
+/**
+ * Normalize a CLI color param to the value that belongs in the preset.
+ *
+ * - An already-formed `$variable(...)$` token → returned verbatim (the
+ *   caller is responsible for its correctness; the trailing `)$` is
+ *   asserted).
+ * - A bare `gcid-*`/`gvid-*` name → wrapped into the canonical token.
+ * - Anything else (a hex string, `rgba(...)`, etc.) → returned verbatim
+ *   as a literal color value.
+ */
+export declare function normalizeColorValue(value: string): string;

package/dist/preset-cli/variable-token.js

@@ -0,0 +1,70 @@
+/**
+ * `$variable()` color-token helpers for the preset-emitter CLI.
+ *
+ * Divi 5.5.x color bindings use the token grammar:
+ *
+ *   $variable({"type":"color","value":{"name":"gcid-heading-color","settings":{}}})$
+ *
+ * Two load-bearing rules (both from VB-verified memory):
+ *  - The token MUST end with `)$` — a missing trailing `$` causes silent
+ *    render failure (`feedback_variable_trailing_dollar`).
+ *  - The `value` payload MUST be an object `{name, settings}`, not a flat
+ *    `gcid-*` string — a flat string crashes PHP 8 in Divi's DynamicData
+ *    resolver (`feedback_variable_color_value_object_shape`).
+ *
+ * The CLI accepts a color param that is EITHER a literal (a hex string,
+ * or an already-formed `$variable(...)$` token) OR a bare `gcid-*` /
+ * `gvid-*` token name, which this module wraps into the canonical shape.
+ */
+/** A bare Divi variable token name (gcid-* or gvid-*). */
+const BARE_TOKEN_RE = /^(gcid|gvid)-[A-Za-z0-9_-]+$/;
+/** An already-formed `$variable(...)$` token. */
+export function isVariableToken(value) {
+    return value.startsWith("$variable(") && value.endsWith(")$");
+}
+/** A bare token name like `gcid-primary-color`. */
+export function isBareTokenName(value) {
+    return BARE_TOKEN_RE.test(value);
+}
+/**
+ * Build a canonical `$variable()` color token from a bare token name.
+ *
+ * The inner JSON uses single-escape `\"` when the whole preset is later
+ * `JSON.stringify`-d — that is handled by JSON.stringify itself; here we
+ * return the raw string value (un-stringified), which is what belongs in
+ * the in-memory preset object.
+ */
+export function buildColorVariableToken(tokenName) {
+    if (!isBareTokenName(tokenName)) {
+        throw new Error(`Invalid variable token name "${tokenName}". Expected a bare gcid-*/gvid-* name ` +
+            `(e.g. "gcid-primary-color"), a hex literal, or an already-formed $variable(...)$ token.`);
+    }
+    const payload = JSON.stringify({
+        type: "color",
+        value: { name: tokenName, settings: {} },
+    });
+    return `$variable(${payload})$`;
+}
+/**
+ * Normalize a CLI color param to the value that belongs in the preset.
+ *
+ * - An already-formed `$variable(...)$` token → returned verbatim (the
+ *   caller is responsible for its correctness; the trailing `)$` is
+ *   asserted).
+ * - A bare `gcid-*`/`gvid-*` name → wrapped into the canonical token.
+ * - Anything else (a hex string, `rgba(...)`, etc.) → returned verbatim
+ *   as a literal color value.
+ */
+export function normalizeColorValue(value) {
+    if (isVariableToken(value)) {
+        return value;
+    }
+    if (value.startsWith("$variable(") && !value.endsWith(")$")) {
+        throw new Error(`Malformed $variable() token "${value}" — must end with ")$" ` +
+            `(missing trailing "$" causes silent render failure).`);
+    }
+    if (isBareTokenName(value)) {
+        return buildColorVariableToken(value);
+    }
+    return value;
+}

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

@@ -0,0 +1,74 @@
+/**
+ * Apply-mode write path for the preset-emitter CLI.
+ *
+ * Reuses the existing server WP-client conventions:
+ *  - `WP_URL` / `WP_USER` / `WP_APP_PASSWORD` env vars.
+ *  - `WPClient` from `wp-client.ts` for the HTTP + Basic-Auth machinery.
+ *  - `WPClient.handshake()` for the plugin capability map.
+ *
+ * Before any write the CLI verifies the plugin handshake reports the
+ * `storage_multipath_probe_v1` capability (the storage-path capability
+ * contract, shipped in plugin 1.4.9). Absent → fail fast, before composing
+ * a write.
+ *
+ * `--dry-run` never reaches this module: it requires no credentials, no
+ * handshake, and no network.
+ */
+import { WPClient } from "../wp-client.js";
+import type { HandshakeResult } from "../compatibility.js";
+import type { DiviopsResponse } from "../envelope.js";
+import type { ButtonPresetEntry } from "./button-emitter.js";
+import type { HeadingFontPresetEntry } from "./heading-font-emitter.js";
+/** The plugin capability the storage-path capability contract ships. */
+export declare const STORAGE_CAPABILITY = "storage_multipath_probe_v1";
+/** The REST route the CLI posts to — same route `diviops_preset_create` uses. */
+export declare const PRESET_CREATE_ROUTE = "/preset/create";
+/** Minimal client surface the write path needs — eased for mocking in tests. */
+export interface PresetWriteClient {
+    handshake(serverVersion: string): Promise<HandshakeResult>;
+    requestEnveloped<T = unknown>(endpoint: string, options?: {
+        method?: string;
+        body?: Record<string, unknown>;
+        params?: Record<string, string>;
+    }): Promise<DiviopsResponse<T>>;
+}
+export declare class CredentialsMissingError extends Error {
+    constructor(missing: string[]);
+}
+export declare class CapabilityMissingError extends Error {
+    readonly capability: string;
+    readonly pluginVersion: string;
+    constructor(capability: string, pluginVersion: string);
+}
+/** Build a `WPClient` from the standard env vars, or throw if any are absent. */
+export declare function buildClientFromEnv(env?: NodeJS.ProcessEnv): WPClient;
+/**
+ * Verify the plugin handshake reports `storage_multipath_probe_v1`.
+ * Throws `CapabilityMissingError` if absent. Returns the handshake result
+ * so callers can surface the plugin version.
+ */
+export declare function assertStorageCapability(client: PresetWriteClient, serverVersion: string): Promise<HandshakeResult>;
+/**
+ * Apply a button preset: capability-gate, then POST to `/preset/create`.
+ *
+ * The capability check runs BEFORE the write. The write goes through the
+ * existing storage-routed route — no plugin route is added here.
+ */
+export declare function applyButtonPreset(client: PresetWriteClient, entry: ButtonPresetEntry, opts: {
+    serverVersion: string;
+    dry_run?: boolean;
+}): Promise<DiviopsResponse<unknown>>;
+/**
+ * Apply a `divi/font` heading group preset: capability-gate, then POST
+ * to `/preset/create`. Mirrors `applyButtonPreset`'s sequence — the
+ * capability check runs BEFORE the write, and the write reuses the
+ * existing storage-routed route (no plugin route is added).
+ *
+ * The `pattern_variant` metadata is intentionally NOT in the wire body —
+ * variant selection is a client-side registry-gate decision and the
+ * server route accepts only the standard preset-create fields.
+ */
+export declare function applyHeadingFontPreset(client: PresetWriteClient, entry: HeadingFontPresetEntry, opts: {
+    serverVersion: string;
+    dry_run?: boolean;
+}): Promise<DiviopsResponse<unknown>>;