@diviops/mcp-server 1.5.9 → 1.5.11

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,59 @@
+/**
+ * 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";
+/** 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>>;

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

@@ -0,0 +1,89 @@
+/**
+ * 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 { buildPresetCreateBody } from "./button-emitter.js";
+/** The plugin capability the storage-path capability contract ships. */
+export const STORAGE_CAPABILITY = "storage_multipath_probe_v1";
+/** The REST route the CLI posts to — same route `diviops_preset_create` uses. */
+export const PRESET_CREATE_ROUTE = "/preset/create";
+export class CredentialsMissingError extends Error {
+    constructor(missing) {
+        super(`Apply mode requires WordPress credentials. Missing: ${missing.join(", ")}. ` +
+            `Set WP_URL / WP_USER / WP_APP_PASSWORD (the same env vars the MCP server uses). ` +
+            `Use --dry-run to compose preset JSON without credentials.`);
+        this.name = "CredentialsMissingError";
+    }
+}
+export class CapabilityMissingError extends Error {
+    capability;
+    pluginVersion;
+    constructor(capability, pluginVersion) {
+        super(`The active diviops-agent plugin (version ${pluginVersion}) does not report ` +
+            `the "${capability}" capability required for storage-routed preset writes. ` +
+            `Upgrade diviops-agent to a version that ships the "${capability}" capability ` +
+            `(plugin 1.4.9 or later).`);
+        this.capability = capability;
+        this.pluginVersion = pluginVersion;
+        this.name = "CapabilityMissingError";
+    }
+}
+/** Build a `WPClient` from the standard env vars, or throw if any are absent. */
+export function buildClientFromEnv(env = process.env) {
+    const url = env.WP_URL ?? "";
+    const user = env.WP_USER ?? "";
+    const pass = env.WP_APP_PASSWORD ?? "";
+    const missing = [];
+    if (!url)
+        missing.push("WP_URL");
+    if (!user)
+        missing.push("WP_USER");
+    if (!pass)
+        missing.push("WP_APP_PASSWORD");
+    if (missing.length > 0)
+        throw new CredentialsMissingError(missing);
+    return new WPClient({
+        siteUrl: url,
+        username: user,
+        applicationPassword: pass,
+    });
+}
+/**
+ * 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 async function assertStorageCapability(client, serverVersion) {
+    const hs = await client.handshake(serverVersion);
+    if (!hs.capabilities || hs.capabilities[STORAGE_CAPABILITY] !== true) {
+        throw new CapabilityMissingError(STORAGE_CAPABILITY, hs.plugin_version ?? "unknown");
+    }
+    return hs;
+}
+/**
+ * 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 async function applyButtonPreset(client, entry, opts) {
+    await assertStorageCapability(client, opts.serverVersion);
+    const body = buildPresetCreateBody(entry, { dry_run: opts.dry_run });
+    return client.requestEnveloped(PRESET_CREATE_ROUTE, {
+        method: "POST",
+        body,
+    });
+}

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "@diviops/mcp-server",
-  "version": "1.5.9",
+  "version": "1.5.11",
   "description": "MCP server exposing Divi 5 Visual Builder as tools for Claude",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "diviops-mcp": "dist/index.js"
+    "diviops-mcp": "dist/index.js",
+    "diviops-preset": "dist/preset-cli/bin.js"
   },
   "files": [
     "dist",
     "templates",
+    "data/verified-attrs.json",
+    "data/verified-attrs-backlog.json",
     "README.md"
   ],
   "scripts": {
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
+    "test": "npm run build && node --test \"dist/preset-cli/__tests__/*.test.js\"",
     "prepublishOnly": "npm run build",
     "regen:skill": "node scripts/regen-module-formats.mjs"
   },