design-constraint-validator 1.1.0 → 2.1.0

package/core/flatten.js

@@ -1,4 +1,6 @@
-const REF_RE = /\{([a-z0-9.-]+)\}/gi;
+import { normalizeDtcgValue } from "./dtcg.js";
+const REF_RE = /\{([a-z0-9_.-]+)\}/gi;
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 export function flattenTokens(root) {
     const flat = {};
     const edges = [];
@@ -8,13 +10,17 @@ export function flattenTokens(root) {
             return;
         if (Object.prototype.hasOwnProperty.call(node, '$value')) {
             const id = path.join('.');
-            const raw = node.$value;
-            if (raw === undefined)
+            if (node.$value === undefined)
                 return; // Skip tokens without values
+            // Normalize DTCG 2025.10 structured color/dimension objects to the
+            // string/number form the engine + plugins expect (strings, incl. aliases,
+            // pass through unchanged). Keeps the color math in core/color.ts untouched.
+            const raw = node.$value;
+            const normalized = normalizeDtcgValue(raw, node.$type);
             const refs = [];
             // Find all references in the value
-            if (typeof raw === 'string') {
-                const matches = raw.matchAll(REF_RE);
+            if (typeof normalized === 'string') {
+                const matches = normalized.matchAll(REF_RE);
                 for (const match of matches) {
                     refs.push(match[1]);
                 }
@@ -22,7 +28,7 @@ export function flattenTokens(root) {
             flat[id] = {
                 id,
                 type: String(node.$type ?? 'unknown'),
-                value: raw,
+                value: normalized,
                 raw,
                 refs
             };
@@ -44,7 +50,7 @@ export function flattenTokens(root) {
     // Second pass: resolve references iteratively
     let changed = true;
     let iterations = 0;
-    const maxIterations = Object.keys(flat).length * 2; // Safety limit
+    const maxIterations = Object.keys(flat).length * 2 + 1; // Safety limit (never 0)
     while (changed && iterations < maxIterations) {
         changed = false;
         iterations++;
@@ -63,7 +69,7 @@ export function flattenTokens(root) {
                         break;
                     }
                     // Replace the reference with the resolved value
-                    const refPattern = new RegExp(`\\{${refId}\\}`, 'g');
+                    const refPattern = new RegExp(`\\{${escapeRegExp(refId)}\\}`, 'g');
                     newValue = newValue.replace(refPattern, String(refToken.value));
                 }
                 if (fullyResolved && newValue !== token.value) {
@@ -73,8 +79,16 @@ export function flattenTokens(root) {
             }
         }
     }
-    if (iterations >= maxIterations) {
-        throw new Error('Token resolution exceeded maximum iterations - possible circular reference');
+    // A token still carrying an unresolved "{ref}" placeholder after the fixpoint
+    // means a genuine cycle (a -> b -> a) or a self-reference. An empty or
+    // fully-literal token set resolves cleanly and must never trip this guard —
+    // the old `iterations >= maxIterations` check threw a bogus "circular
+    // reference" error whenever no tokens were found (maxIterations === 0).
+    const unresolved = Object.values(flat).filter((t) => typeof t.value === 'string' && t.value.includes('{'));
+    if (unresolved.length > 0) {
+        throw new Error(`Token resolution exceeded maximum iterations - possible circular reference (unresolved: ${unresolved
+            .map((t) => t.id)
+            .join(', ')})`);
     }
     return { flat, edges };
 }

package/core/flatten.ts

@@ -1,16 +1,22 @@
+import { normalizeDtcgValue } from "./dtcg.js";
+
 export type TokenId = string; // e.g. "color.palette.brand.600"
 export type TokenValue = string | number;
-export type TokenNode = { 
-  $type?: string; 
-  $value?: TokenValue; 
-  [k: string]: TokenNode | string | number | undefined;
+// $value may also be a DTCG 2025.10 structured object (color / dimension); it is
+// normalized to a TokenValue at ingestion. See normalizeDtcgValue.
+export type DtcgStructuredValue = Record<string, unknown>;
+export type TokenNode = {
+  $type?: string;
+  $value?: TokenValue | DtcgStructuredValue;
+  $extensions?: DtcgStructuredValue; // spec passthrough — preserved, never interpreted
+  [k: string]: TokenNode | string | number | DtcgStructuredValue | undefined;
 };
 
 export type FlatToken = {
   id: TokenId;
   type: string;
   value: TokenValue;       // resolved (if ref)
-  raw: TokenValue;         // original $value
+  raw: TokenValue | DtcgStructuredValue; // original $value
   refs: TokenId[];         // referenced token IDs found in raw
 };
 
@@ -19,7 +25,8 @@ export type FlattenResult = {
   edges: Array<[from: TokenId, to: TokenId]>; // from ref -> to dependent
 };
 
-const REF_RE = /\{([a-z0-9.-]+)\}/gi;
+const REF_RE = /\{([a-z0-9_.-]+)\}/gi;
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
 export function flattenTokens(root: TokenNode): FlattenResult {
   const flat: Record<TokenId, FlatToken> = {};
@@ -31,14 +38,18 @@ export function flattenTokens(root: TokenNode): FlattenResult {
     
     if (Object.prototype.hasOwnProperty.call(node, '$value')) {
       const id = path.join('.');
+      if (node.$value === undefined) return; // Skip tokens without values
+      // Normalize DTCG 2025.10 structured color/dimension objects to the
+      // string/number form the engine + plugins expect (strings, incl. aliases,
+      // pass through unchanged). Keeps the color math in core/color.ts untouched.
       const raw = node.$value;
-      if (raw === undefined) return; // Skip tokens without values
-      
+      const normalized = normalizeDtcgValue(raw, node.$type);
+
       const refs: TokenId[] = [];
       
       // Find all references in the value
-      if (typeof raw === 'string') {
-        const matches = raw.matchAll(REF_RE);
+      if (typeof normalized === 'string') {
+        const matches = normalized.matchAll(REF_RE);
         for (const match of matches) {
           refs.push(match[1]);
         }
@@ -47,7 +58,7 @@ export function flattenTokens(root: TokenNode): FlattenResult {
       flat[id] = { 
         id, 
         type: String(node.$type ?? 'unknown'), 
-        value: raw,
+        value: normalized,
         raw, 
         refs 
       };
@@ -72,8 +83,8 @@ export function flattenTokens(root: TokenNode): FlattenResult {
   // Second pass: resolve references iteratively
   let changed = true;
   let iterations = 0;
-  const maxIterations = Object.keys(flat).length * 2; // Safety limit
-  
+  const maxIterations = Object.keys(flat).length * 2 + 1; // Safety limit (never 0)
+
   while (changed && iterations < maxIterations) {
     changed = false;
     iterations++;
@@ -96,7 +107,7 @@ export function flattenTokens(root: TokenNode): FlattenResult {
           }
           
           // Replace the reference with the resolved value
-          const refPattern = new RegExp(`\\{${refId}\\}`, 'g');
+          const refPattern = new RegExp(`\\{${escapeRegExp(refId)}\\}`, 'g');
           newValue = newValue.replace(refPattern, String(refToken.value));
         }
         
@@ -108,8 +119,20 @@ export function flattenTokens(root: TokenNode): FlattenResult {
     }
   }
   
-  if (iterations >= maxIterations) {
-    throw new Error('Token resolution exceeded maximum iterations - possible circular reference');
+  // A token still carrying an unresolved "{ref}" placeholder after the fixpoint
+  // means a genuine cycle (a -> b -> a) or a self-reference. An empty or
+  // fully-literal token set resolves cleanly and must never trip this guard —
+  // the old `iterations >= maxIterations` check threw a bogus "circular
+  // reference" error whenever no tokens were found (maxIterations === 0).
+  const unresolved = Object.values(flat).filter(
+    (t) => typeof t.value === 'string' && t.value.includes('{'),
+  );
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Token resolution exceeded maximum iterations - possible circular reference (unresolved: ${unresolved
+        .map((t) => t.id)
+        .join(', ')})`,
+    );
   }
 
   return { flat, edges };

package/core/image-export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-export.d.ts","sourceRoot":"","sources":["image-export.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AACrC,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;AAEzC,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EAAe,6BAA6B;AAC7D,OAAO,EAAE,MAAM,EAAiB,wBAAwB;AACxD,GAAG,EAAE,QAAQ,EAAmB,gBAAgB;AAChD,QAAQ,EAAE,QAAQ,GACjB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAoBhC"}
+{"version":3,"file":"image-export.d.ts","sourceRoot":"","sources":["image-export.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AACrC,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC;AAEzC,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EAAe,6BAA6B;AAC7D,OAAO,EAAE,MAAM,EAAiB,wBAAwB;AACxD,GAAG,EAAE,QAAQ,EAAmB,gBAAgB;AAChD,QAAQ,EAAE,QAAQ,GACjB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAoBhC"}

package/core/image-export.js

@@ -5,13 +5,16 @@ import { spawnSync } from "node:child_process";
 function which(cmd) {
     const paths = (process.env.PATH || "").split(path.delimiter);
     for (const p of paths) {
-        const full = path.join(p, cmd + (process.platform === "win32" ? ".cmd" : ""));
-        try {
-            fs.accessSync(full, fs.constants.X_OK);
-            return full;
-        }
-        catch {
-            // File not accessible, continue to next path
+        const names = process.platform === "win32" ? [cmd + ".cmd", cmd + ".exe", cmd] : [cmd];
+        for (const name of names) {
+            const full = path.join(p, name);
+            try {
+                fs.accessSync(full, fs.constants.X_OK);
+                return full;
+            }
+            catch {
+                // File not accessible, continue to next path
+            }
         }
     }
     return null;

package/core/image-export.ts

@@ -6,12 +6,15 @@ import { spawnSync } from "node:child_process";
 function which(cmd: string): string | null {
   const paths = (process.env.PATH || "").split(path.delimiter);
   for (const p of paths) {
-    const full = path.join(p, cmd + (process.platform === "win32" ? ".cmd" : ""));
-    try { 
-      fs.accessSync(full, fs.constants.X_OK); 
-      return full; 
-    } catch {
-      // File not accessible, continue to next path
+    const names = process.platform === "win32" ? [cmd + ".cmd", cmd + ".exe", cmd] : [cmd];
+    for (const name of names) {
+      const full = path.join(p, name);
+      try {
+        fs.accessSync(full, fs.constants.X_OK);
+        return full;
+      } catch {
+        // File not accessible, continue to next path
+      }
     }
   }
   return null;

package/core/index.d.ts

@@ -7,4 +7,6 @@
 export type { TokenId, TokenValue } from "./flatten.js";
 export type { ConstraintIssue, ConstraintPlugin, Graph } from "./engine.js";
 export { Engine } from "./engine.js";
+export { validate } from "../cli/validate-api.js";
+export type { ValidateInput, ValidateResult } from "../cli/validate-api.js";
 //# sourceMappingURL=index.d.ts.map

package/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAKrC,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/core/index.js

@@ -5,3 +5,7 @@
  * See engine.ts for full implementation with Phase 3C enhancements.
  */
 export { Engine } from "./engine.js";
+// Programmatic convenience API (validate tokens against constraints in one call).
+// Implemented in the CLI layer atop the shared registry; surfaced here as the
+// package's public entry point.
+export { validate } from "../cli/validate-api.js";

package/core/index.ts

@@ -8,3 +8,9 @@
 export type { TokenId, TokenValue } from "./flatten.js";
 export type { ConstraintIssue, ConstraintPlugin, Graph } from "./engine.js";
 export { Engine } from "./engine.js";
+
+// Programmatic convenience API (validate tokens against constraints in one call).
+// Implemented in the CLI layer atop the shared registry; surfaced here as the
+// package's public entry point.
+export { validate } from "../cli/validate-api.js";
+export type { ValidateInput, ValidateResult } from "../cli/validate-api.js";

package/core/why.d.ts

@@ -2,7 +2,7 @@ import type { FlatToken } from "./flatten.js";
 export type WhyReport = {
     id: string;
     value: string | number | undefined;
-    raw?: string | number;
+    raw?: unknown;
     refs?: string[];
     provenance: "base" | "theme" | "override" | "unknown";
     dependsOn: string[];

package/core/why.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAQxF;AAED,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,EAC7B,MAAM,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAO,GACpF,SAAS,CAkCX"}
+{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACnC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACtD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAQxF;AAED,wBAAgB,OAAO,CACrB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAC/B,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,EAAC,MAAM,CAAC,CAAC,EAC7B,MAAM,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAO,GACpF,SAAS,CAkCX"}

package/core/why.ts

@@ -3,7 +3,7 @@ import type { FlatToken } from "./flatten.js";
 export type WhyReport = {
   id: string;
   value: string | number | undefined;
-  raw?: string | number;
+  raw?: unknown;
   refs?: string[];
   provenance: "base" | "theme" | "override" | "unknown";
   dependsOn: string[];     // immediate refs (parents)

package/mcp/contracts.d.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export declare const jsonValueSchema: z.ZodType<JsonValue>;
+export declare const jsonObjectSchema: z.ZodType<JsonObject>;
+export declare const tokenInputShape: {
+    tokens: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    tokensPath: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    configPath: z.ZodOptional<z.ZodString>;
+    constraintsDir: z.ZodOptional<z.ZodString>;
+    breakpoint: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+};
+export declare const validateInputShape: {
+    tokens: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    tokensPath: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    configPath: z.ZodOptional<z.ZodString>;
+    constraintsDir: z.ZodOptional<z.ZodString>;
+    breakpoint: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+};
+export declare const whyInputShape: {
+    tokenId: z.ZodString;
+    tokens: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    tokensPath: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    configPath: z.ZodOptional<z.ZodString>;
+    constraintsDir: z.ZodOptional<z.ZodString>;
+    breakpoint: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+};
+export declare const graphInputShape: {
+    format: z.ZodOptional<z.ZodLiteral<"json">>;
+    tokens: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    tokensPath: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    configPath: z.ZodOptional<z.ZodString>;
+    constraintsDir: z.ZodOptional<z.ZodString>;
+    breakpoint: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+};
+export declare const validateInputSchema: z.ZodObject<{
+    tokens: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    tokensPath: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    configPath: z.ZodOptional<z.ZodString>;
+    constraintsDir: z.ZodOptional<z.ZodString>;
+    breakpoint: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+}, "strip", z.ZodTypeAny, {
+    tokens?: JsonObject | undefined;
+    constraints?: JsonObject | undefined;
+    constraintsDir?: string | undefined;
+    breakpoint?: "sm" | "md" | "lg" | undefined;
+    tokensPath?: string | undefined;
+    configPath?: string | undefined;
+}, {
+    tokens?: JsonObject | undefined;
+    constraints?: JsonObject | undefined;
+    constraintsDir?: string | undefined;
+    breakpoint?: "sm" | "md" | "lg" | undefined;
+    tokensPath?: string | undefined;
+    configPath?: string | undefined;
+}>;
+export declare const whyInputSchema: z.ZodObject<{
+    tokenId: z.ZodString;
+    tokens: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    tokensPath: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    configPath: z.ZodOptional<z.ZodString>;
+    constraintsDir: z.ZodOptional<z.ZodString>;
+    breakpoint: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+}, "strip", z.ZodTypeAny, {
+    tokenId: string;
+    tokens?: JsonObject | undefined;
+    constraints?: JsonObject | undefined;
+    constraintsDir?: string | undefined;
+    breakpoint?: "sm" | "md" | "lg" | undefined;
+    tokensPath?: string | undefined;
+    configPath?: string | undefined;
+}, {
+    tokenId: string;
+    tokens?: JsonObject | undefined;
+    constraints?: JsonObject | undefined;
+    constraintsDir?: string | undefined;
+    breakpoint?: "sm" | "md" | "lg" | undefined;
+    tokensPath?: string | undefined;
+    configPath?: string | undefined;
+}>;
+export declare const graphInputSchema: z.ZodObject<{
+    format: z.ZodOptional<z.ZodLiteral<"json">>;
+    tokens: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    tokensPath: z.ZodOptional<z.ZodString>;
+    constraints: z.ZodOptional<z.ZodType<JsonObject, z.ZodTypeDef, JsonObject>>;
+    configPath: z.ZodOptional<z.ZodString>;
+    constraintsDir: z.ZodOptional<z.ZodString>;
+    breakpoint: z.ZodOptional<z.ZodEnum<["sm", "md", "lg"]>>;
+}, "strip", z.ZodTypeAny, {
+    tokens?: JsonObject | undefined;
+    constraints?: JsonObject | undefined;
+    format?: "json" | undefined;
+    constraintsDir?: string | undefined;
+    breakpoint?: "sm" | "md" | "lg" | undefined;
+    tokensPath?: string | undefined;
+    configPath?: string | undefined;
+}, {
+    tokens?: JsonObject | undefined;
+    constraints?: JsonObject | undefined;
+    format?: "json" | undefined;
+    constraintsDir?: string | undefined;
+    breakpoint?: "sm" | "md" | "lg" | undefined;
+    tokensPath?: string | undefined;
+    configPath?: string | undefined;
+}>;
+export type ValidateToolInput = z.infer<typeof validateInputSchema>;
+export type WhyToolInput = z.infer<typeof whyInputSchema>;
+export type GraphToolInput = z.infer<typeof graphInputSchema>;
+//# sourceMappingURL=contracts.d.ts.map

package/mcp/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,EAAE,CAAC;AAEjE,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAID,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAEhD,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAA6B,CAAC;AAEjF,eAAO,MAAM,eAAe;;;;;;;CAW3B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;CAE9B,CAAC;AAEF,eAAO,MAAM,aAAa;;;;;;;;CAGzB,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;;CAG3B,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;EAA+B,CAAC;AAChE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;EAA0B,CAAC;AACtD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;EAA4B,CAAC;AAE1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACpE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC1D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}

package/mcp/contracts.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const jsonValueSchema = z.lazy(() => z.union([jsonPrimitiveSchema, z.array(jsonValueSchema), z.record(jsonValueSchema)]));
+export const jsonObjectSchema = z.record(jsonValueSchema);
+export const tokenInputShape = {
+    tokens: jsonObjectSchema
+        .optional()
+        .describe('Inline DTCG-style token tree. Takes precedence over tokensPath.'),
+    tokensPath: z.string().optional().describe('Path to a token JSON file on the server filesystem.'),
+    constraints: jsonObjectSchema
+        .optional()
+        .describe('Inline constraints block from dcv.config.json. Takes precedence over configPath.'),
+    configPath: z.string().optional().describe('Path to a JSON DCV config file.'),
+    constraintsDir: z.string().optional().describe('Directory holding order and cross-axis constraints.'),
+    breakpoint: z.enum(['sm', 'md', 'lg']).optional().describe('Optional constraint breakpoint.'),
+};
+export const validateInputShape = {
+    ...tokenInputShape,
+};
+export const whyInputShape = {
+    ...tokenInputShape,
+    tokenId: z.string().describe('Token id to explain, for example color.role.text.default.'),
+};
+export const graphInputShape = {
+    ...tokenInputShape,
+    format: z.literal('json').optional().describe('Only json is supported; omitted defaults to json.'),
+};
+export const validateInputSchema = z.object(validateInputShape);
+export const whyInputSchema = z.object(whyInputShape);
+export const graphInputSchema = z.object(graphInputShape);

package/mcp/contracts.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+const jsonPrimitiveSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+export const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([jsonPrimitiveSchema, z.array(jsonValueSchema), z.record(jsonValueSchema)]),
+);
+
+export const jsonObjectSchema: z.ZodType<JsonObject> = z.record(jsonValueSchema);
+
+export const tokenInputShape = {
+  tokens: jsonObjectSchema
+    .optional()
+    .describe('Inline DTCG-style token tree. Takes precedence over tokensPath.'),
+  tokensPath: z.string().optional().describe('Path to a token JSON file on the server filesystem.'),
+  constraints: jsonObjectSchema
+    .optional()
+    .describe('Inline constraints block from dcv.config.json. Takes precedence over configPath.'),
+  configPath: z.string().optional().describe('Path to a JSON DCV config file.'),
+  constraintsDir: z.string().optional().describe('Directory holding order and cross-axis constraints.'),
+  breakpoint: z.enum(['sm', 'md', 'lg']).optional().describe('Optional constraint breakpoint.'),
+};
+
+export const validateInputShape = {
+  ...tokenInputShape,
+};
+
+export const whyInputShape = {
+  ...tokenInputShape,
+  tokenId: z.string().describe('Token id to explain, for example color.role.text.default.'),
+};
+
+export const graphInputShape = {
+  ...tokenInputShape,
+  format: z.literal('json').optional().describe('Only json is supported; omitted defaults to json.'),
+};
+
+export const validateInputSchema = z.object(validateInputShape);
+export const whyInputSchema = z.object(whyInputShape);
+export const graphInputSchema = z.object(graphInputShape);
+
+export type ValidateToolInput = z.infer<typeof validateInputSchema>;
+export type WhyToolInput = z.infer<typeof whyInputSchema>;
+export type GraphToolInput = z.infer<typeof graphInputSchema>;

package/mcp/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { graphInputSchema, graphInputShape, jsonObjectSchema, jsonValueSchema, validateInputSchema, validateInputShape, whyInputSchema, whyInputShape, } from './contracts.js';
+export type { GraphToolInput, JsonObject, JsonPrimitive, JsonValue, ValidateToolInput, WhyToolInput, } from './contracts.js';
+export { dcvMcpTools, graphTool, registerDcvMcpTools, ToolExecutionError, validateTool, whyTool, } from './tools.js';
+export type { DcvMcpToolName, GraphToolResult, ToolFailure, ToolResponse, WhyToolResult, } from './tools.js';
+export declare function createDcvMcpServer(): McpServer;
+export declare function startStdioServer(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,UAAU,EACV,aAAa,EACb,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,OAAO,GACR,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,wBAAgB,kBAAkB,IAAI,SAAS,CAQ9C;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAItD"}

package/mcp/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerDcvMcpTools } from './tools.js';
+export { graphInputSchema, graphInputShape, jsonObjectSchema, jsonValueSchema, validateInputSchema, validateInputShape, whyInputSchema, whyInputShape, } from './contracts.js';
+export { dcvMcpTools, graphTool, registerDcvMcpTools, ToolExecutionError, validateTool, whyTool, } from './tools.js';
+export function createDcvMcpServer() {
+    const server = new McpServer({
+        name: 'dcv-mcp',
+        version: '2.1.0',
+    });
+    registerDcvMcpTools(server);
+    return server;
+}
+export async function startStdioServer() {
+    const server = createDcvMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+function isEntrypoint() {
+    const entry = process.argv[1];
+    return entry !== undefined && resolve(fileURLToPath(import.meta.url)) === resolve(entry);
+}
+if (isEntrypoint()) {
+    startStdioServer().catch((error) => {
+        const message = error instanceof Error ? error.message : 'Unknown MCP server failure';
+        console.error(`[dcv-mcp] ${message}`);
+        process.exitCode = 1;
+    });
+}

package/mcp/index.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { registerDcvMcpTools } from './tools.js';
+
+export {
+  graphInputSchema,
+  graphInputShape,
+  jsonObjectSchema,
+  jsonValueSchema,
+  validateInputSchema,
+  validateInputShape,
+  whyInputSchema,
+  whyInputShape,
+} from './contracts.js';
+export type {
+  GraphToolInput,
+  JsonObject,
+  JsonPrimitive,
+  JsonValue,
+  ValidateToolInput,
+  WhyToolInput,
+} from './contracts.js';
+export {
+  dcvMcpTools,
+  graphTool,
+  registerDcvMcpTools,
+  ToolExecutionError,
+  validateTool,
+  whyTool,
+} from './tools.js';
+export type {
+  DcvMcpToolName,
+  GraphToolResult,
+  ToolFailure,
+  ToolResponse,
+  WhyToolResult,
+} from './tools.js';
+
+export function createDcvMcpServer(): McpServer {
+  const server = new McpServer({
+    name: 'dcv-mcp',
+    version: '2.1.0',
+  });
+
+  registerDcvMcpTools(server);
+  return server;
+}
+
+export async function startStdioServer(): Promise<void> {
+  const server = createDcvMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+function isEntrypoint(): boolean {
+  const entry = process.argv[1];
+  return entry !== undefined && resolve(fileURLToPath(import.meta.url)) === resolve(entry);
+}
+
+if (isEntrypoint()) {
+  startStdioServer().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : 'Unknown MCP server failure';
+    console.error(`[dcv-mcp] ${message}`);
+    process.exitCode = 1;
+  });
+}