@diviops/mcp-server 1.5.10 → 1.5.11

package/dist/preset-cli/cli.js

@@ -0,0 +1,326 @@
+/**
+ * `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 { EvidenceGateError } from "./registry.js";
+import { applyButtonPreset, 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 --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.
+
+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
+`;
+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",
+]);
+/** 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";
+    }
+}
+/** 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;
+}
+/**
+ * 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 !== "button") {
+        io.err(`Unknown command: ${parsed.command ?? "(none)"}. ` +
+            `Track 4 ships one command: "button".`);
+        io.err("Run `diviops-preset --help` for usage.");
+        return EXIT.INVALID_INPUT;
+    }
+    // --- compose + gate -------------------------------------------------
+    let entry;
+    try {
+        const input = buildButtonInput(parsed);
+        entry = emitButtonGroupPreset(input);
+    }
+    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;
+        }
+        io.err(err instanceof Error ? err.message : String(err));
+        return EXIT.INVALID_INPUT;
+    }
+    // --- dry-run --------------------------------------------------------
+    if (parsed.dryRun) {
+        const body = buildPresetCreateBody(entry, { dry_run: true });
+        io.out(JSON.stringify(body, 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 applyButtonPreset(client, entry, { 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/registry.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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)` cell against the registry. */
+export interface EvidenceResolution {
+    patternFamily: 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`. Tier 2 is searched
+ * first (the button families live there), then Tier 1.
+ */
+export declare function findPatternEntry(registry: VerifiedAttrsRegistry, patternFamily: string): Tier12Entry | undefined;
+/**
+ * Resolve effective evidence for a `(module, pattern-family)` cell.
+ *
+ * Throws if the pattern family 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): 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): EvidenceResolution;

package/dist/preset-cli/registry.js

@@ -0,0 +1,168 @@
+/**
+ * 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`. Tier 2 is searched
+ * first (the button families live there), then Tier 1.
+ */
+export function findPatternEntry(registry, patternFamily) {
+    const tiers = [registry.tier2 ?? [], registry.tier1 ?? []];
+    for (const tier of tiers) {
+        const hit = tier.find((e) => e.pattern_family === patternFamily);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * Resolve effective evidence for a `(module, pattern-family)` cell.
+ *
+ * Throws if the pattern family is entirely absent from the registry —
+ * that is an unrecoverable gap (the CLI must fail, not guess).
+ */
+export function resolveEvidence(registry, module, patternFamily) {
+    const entry = findPatternEntry(registry, patternFamily);
+    if (!entry) {
+        throw new Error(`Pattern family "${patternFamily}" 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,
+        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) {
+        super(`Evidence-gate refusal: attr family "${patternFamily}" 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) {
+    const resolution = resolveEvidence(registry, module, patternFamily);
+    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;