design-constraint-validator 2.1.0 → 2.2.0

package/README.md

@@ -26,10 +26,12 @@ This is **not** a schema linter; it's a **reasoning validator** for values and r
 # Local (recommended)
 npm i -D design-constraint-validator
 
-# One-off run
-npx dcv --help
+# One-off run, no install (the bin name `dcv` belongs to an unrelated package)
+npx design-constraint-validator --help
 ```
 
+After a local install, the shorter `dcv` bin is available (e.g. `npx dcv --help`).
+
 **Requirements:** Node.js ≥ 18.x (ESM)
 
 ---
@@ -63,15 +65,19 @@ cat > dcv.config.json <<'JSON'
 JSON
 
 # 3. Validate (positional path or --tokens; exits non-zero on violations)
-npx dcv validate tokens.json --summary table
+npx design-constraint-validator validate tokens.json --summary table
 
 # Explain one token (the tokenId is required)
-npx dcv why color.text --tokens tokens.json --format table
+npx design-constraint-validator why color.text --tokens tokens.json --format table
 
 # Export the dependency graph
-npx dcv graph --tokens tokens.json --format mermaid > graph.mmd
+npx design-constraint-validator graph --tokens tokens.json --format mermaid > graph.mmd
 ```
 
+> These one-offs use the full package name because the bare `dcv` bin name on npm
+> belongs to an unrelated package. After `npm i -D design-constraint-validator`,
+> use the shorter `npx dcv …`.
+
 **Example output** (`validate`):
 
 ```text
@@ -124,11 +130,16 @@ DCV ships a second binary, `dcv-mcp`, that exposes the validator over MCP stdio
 }
 ```
 
-The server exposes exactly three JSON-returning tools:
+The server exposes six read-only, JSON-returning tools:
 
 - `validate` - validate inline `tokens` or a `tokensPath` against inline `constraints` or a config file.
 - `why` - explain provenance, aliases, dependencies, dependents, and alias chain for one token id.
 - `graph` - return token dependency `nodes` and `edges`.
+- `list-constraints` - enumerate the active constraints (WCAG pairs, thresholds, order/lightness scales, cross-axis) for the given input.
+- `explain` - turn a violation into plain-English text plus machine-readable facts.
+- `suggest-fix` - compute a verified satisfying value for a violation (WCAG color, threshold/monotonic boundary) without writing anything.
+
+The three derivation tools (`list-constraints`, `explain`, `suggest-fix`) stay read-only — they return suggestions; applying them is up to you (`dcv set` / `dcv patch`). See **[AI Guide](docs/AI-GUIDE.md)** for the full agent loop.
 
 Tool failures are returned as structured JSON: `{ "ok": false, "error": { "code": "...", "message": "..." } }`.
 

package/cli/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwD9F"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+D9F"}

package/cli/commands/build.js

@@ -1,21 +1,19 @@
-import { join, dirname, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { flattenTokens } from '../../core/flatten.js';
+import { mergeTokens } from '../../core/breakpoints.js';
 import { valuesToCss } from '../../adapters/css.js';
 import { emitJSON } from '../../adapters/json.js';
 import { emitJS } from '../../adapters/js.js';
+import { loadThemeTokens } from './utils.js';
 export async function buildCommand(options) {
     const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-    const tokens = loadTokensWithBreakpoint(undefined, options.tokens);
-    const { flat } = flattenTokens(tokens);
-    let allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, t.value]));
+    let tokens = loadTokensWithBreakpoint(undefined, options.tokens);
     if (options.theme) {
-        const themePath = join('tokens/themes', `${options.theme}.json`);
-        if (existsSync(themePath)) {
-            const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-            Object.assign(allValues, themeTokens);
-        }
+        tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
     }
+    const { flat } = flattenTokens(tokens);
+    const allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, t.value]));
     const format = options.format || 'css';
     const defaultOutput = `dist/tokens.${format}`;
     let manifest;
@@ -34,21 +32,31 @@ export async function buildCommand(options) {
             process.exit(1);
         }
     }
-    const allFormats = options.allFormats ?? options['all-formats'];
+    // Read both the kebab key (CLI, camel-case-expansion is off) and the camelCase
+    // key (programmatic callers, e.g. tests). Reading only one form silently no-ops
+    // for the other caller — that was the TASK-024 bug class.
+    const allFormats = options['all-formats'] ?? options.allFormats;
+    const dryRun = options['dry-run'] ?? options.dryRun;
     if (allFormats) {
+        const css = valuesToCss(allValues, { manifest });
+        const json = emitJSON(allValues, manifest);
+        const js = emitJS(allValues, manifest);
+        if (dryRun) {
+            // Dry run: print every format, write nothing.
+            console.log(css);
+            console.log(json);
+            console.log(js);
+            return;
+        }
         const dir = 'dist';
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
-        const css = valuesToCss(allValues, { manifest });
         writeFileSync('dist/tokens.css', css, 'utf8');
-        if (options.dryRun)
-            console.log(css);
-        writeFileSync('dist/tokens.json', emitJSON(allValues, manifest), 'utf8');
-        writeFileSync('dist/tokens.js', emitJS(allValues, manifest), 'utf8');
+        writeFileSync('dist/tokens.json', json, 'utf8');
+        writeFileSync('dist/tokens.js', js, 'utf8');
         console.log(`Tokens written (all formats) to dist/ (css/json/js)${manifest ? ' with mapper' : ''}`);
         return;
     }
-    const dryRun = options.dryRun ?? options['dry-run'];
     if (format === 'css') {
         const css = valuesToCss(allValues, { manifest });
         if (dryRun) {
@@ -63,26 +71,26 @@ export async function buildCommand(options) {
         console.log(`CSS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
     }
     else if (format === 'json') {
-        const outPath = options.output || defaultOutput;
-        const dir = dirname(outPath);
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
         if (dryRun) {
             console.log(emitJSON(allValues, manifest));
             return;
         }
-        writeFileSync(outPath, emitJSON(allValues, manifest), 'utf8');
-        console.log(`JSON tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
-    }
-    else if (format === 'js') {
         const outPath = options.output || defaultOutput;
         const dir = dirname(outPath);
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
+        writeFileSync(outPath, emitJSON(allValues, manifest), 'utf8');
+        console.log(`JSON tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
+    }
+    else if (format === 'js') {
         if (dryRun) {
             console.log(emitJS(allValues, manifest));
             return;
         }
+        const outPath = options.output || defaultOutput;
+        const dir = dirname(outPath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
         writeFileSync(outPath, emitJS(allValues, manifest), 'utf8');
         console.log(`JS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
     }

package/cli/commands/build.ts

@@ -1,23 +1,21 @@
-import { join, dirname, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { flattenTokens, type FlatToken } from '../../core/flatten.js';
+import { mergeTokens } from '../../core/breakpoints.js';
 import { valuesToCss, type ManifestRow } from '../../adapters/css.js';
 import { emitJSON } from '../../adapters/json.js';
 import { emitJS } from '../../adapters/js.js';
 import type { BuildOptions } from '../types.js';
+import { loadThemeTokens } from './utils.js';
 
 export async function buildCommand(options: BuildOptions & { [k: string]: any }): Promise<void> {
   const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-  const tokens = loadTokensWithBreakpoint(undefined, options.tokens);
-  const { flat } = flattenTokens(tokens);
-  let allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, (t as FlatToken).value]));
+  let tokens = loadTokensWithBreakpoint(undefined, options.tokens);
   if (options.theme) {
-    const themePath = join('tokens/themes', `${options.theme}.json`);
-    if (existsSync(themePath)) {
-      const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-      Object.assign(allValues, themeTokens);
-    }
+    tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
   }
+  const { flat } = flattenTokens(tokens);
+  const allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, (t as FlatToken).value]));
   const format = options.format || 'css';
   const defaultOutput = `dist/tokens.${format}`;
   let manifest: ManifestRow[] | undefined;
@@ -33,18 +31,29 @@ export async function buildCommand(options: BuildOptions & { [k: string]: any })
       process.exit(1);
     }
   }
-  const allFormats = options.allFormats ?? options['all-formats'];
+  // Read both the kebab key (CLI, camel-case-expansion is off) and the camelCase
+  // key (programmatic callers, e.g. tests). Reading only one form silently no-ops
+  // for the other caller — that was the TASK-024 bug class.
+  const allFormats = options['all-formats'] ?? options.allFormats;
+  const dryRun = options['dry-run'] ?? options.dryRun;
   if (allFormats) {
-    const dir = 'dist'; if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const css = valuesToCss(allValues, { manifest });
+    const json = emitJSON(allValues, manifest);
+    const js = emitJS(allValues, manifest);
+    if (dryRun) {
+      // Dry run: print every format, write nothing.
+      console.log(css);
+      console.log(json);
+      console.log(js);
+      return;
+    }
+    const dir = 'dist'; if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync('dist/tokens.css', css, 'utf8');
-    if (options.dryRun) console.log(css);
-    writeFileSync('dist/tokens.json', emitJSON(allValues, manifest), 'utf8');
-    writeFileSync('dist/tokens.js', emitJS(allValues, manifest), 'utf8');
+    writeFileSync('dist/tokens.json', json, 'utf8');
+    writeFileSync('dist/tokens.js', js, 'utf8');
     console.log(`Tokens written (all formats) to dist/ (css/json/js)${manifest ? ' with mapper' : ''}`);
     return;
   }
-  const dryRun = options.dryRun ?? options['dry-run'];
   if (format === 'css') {
     const css = valuesToCss(allValues, { manifest });
   if (dryRun) { console.log(css); return; }
@@ -52,13 +61,13 @@ export async function buildCommand(options: BuildOptions & { [k: string]: any })
     writeFileSync(outPath, css, 'utf8');
     console.log(`CSS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
   } else if (format === 'json') {
+    if (dryRun) { console.log(emitJSON(allValues, manifest)); return; }
     const outPath = options.output || defaultOutput; const dir = dirname(outPath); if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  if (dryRun) { console.log(emitJSON(allValues, manifest)); return; }
     writeFileSync(outPath, emitJSON(allValues, manifest), 'utf8');
     console.log(`JSON tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
   } else if (format === 'js') {
+    if (dryRun) { console.log(emitJS(allValues, manifest)); return; }
     const outPath = options.output || defaultOutput; const dir = dirname(outPath); if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  if (dryRun) { console.log(emitJS(allValues, manifest)); return; }
     writeFileSync(outPath, emitJS(allValues, manifest), 'utf8');
     console.log(`JS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
   }

package/cli/commands/graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2BhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuJvE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8BhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiKvE"}

package/cli/commands/graph.js

@@ -16,11 +16,14 @@ function generateDependencyGraph(edges, format) {
             return dot + '}\n';
         }
         case 'mermaid': {
+            // Injective id encoding so distinct token ids (e.g. a.b vs a_b) never
+            // collapse to the same Mermaid node (TASK-027).
+            const safe = (s) => s.replace(/[^a-zA-Z0-9]/g, (c) => `_${c.charCodeAt(0)}_`);
             let mermaid = 'graph LR\n';
             const mermaidNodes = new Set();
             edges.forEach(([from, to]) => {
-                const fromId = from.replace(/[^a-zA-Z0-9]/g, '_');
-                const toId = to.replace(/[^a-zA-Z0-9]/g, '_');
+                const fromId = safe(from);
+                const toId = safe(to);
                 if (!mermaidNodes.has(fromId)) {
                     mermaid += `  ${fromId}["${from}"]\n`;
                     mermaidNodes.add(fromId);
@@ -44,16 +47,21 @@ export async function graphCommand(options) {
     if (options.hasse) {
         const name = options.hasse;
         const bundle = options.bundle;
+        const constraintsDir = options['constraints-dir'] ?? 'themes';
         const fmt = (options.format === 'json' ? 'mermaid' : options.format);
-        const imageFrom = options.imageFrom || 'mermaid';
-        const filterPrefixes = options.filterPrefix ? options.filterPrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
-        const excludePrefixes = options.excludePrefix ? options.excludePrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
-        const onlyViolations = options.onlyViolations || false;
-        const highlightViolations = options.highlightViolations || false;
-        const violationColor = options.violationColor || '#ff2d55';
-        const labelViolations = options.labelViolations || false;
-        const labelTruncate = Math.max(0, options.labelTruncate || 0);
-        const minSeverity = options.minSeverity || 'warn';
+        const imageFrom = options['image-from'] || 'mermaid';
+        // The CLI runs with camel-case-expansion off, so kebab flags arrive only under
+        // their kebab keys. Read those (camelCase reads here silently no-op'd before).
+        const filterPrefix = options['filter-prefix'];
+        const excludePrefix = options['exclude-prefix'];
+        const filterPrefixes = filterPrefix ? filterPrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
+        const excludePrefixes = excludePrefix ? excludePrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
+        const onlyViolations = options['only-violations'] || false;
+        const highlightViolations = options['highlight-violations'] || false;
+        const violationColor = options['violation-color'] || '#ff2d55';
+        const labelViolations = options['label-violations'] || false;
+        const labelTruncate = Math.max(0, options['label-truncate'] || 0);
+        const minSeverity = options['min-severity'] || 'warn';
         const focus = options.focus;
         const radius = Math.max(0, options.radius || 1);
         for (const breakpoint of plan) {
@@ -78,7 +86,7 @@ export async function graphCommand(options) {
             const outDir = 'dist/graphs';
             const baseFile = `${outDir}/${name}${suffix}-hasse.${ext}`;
             try {
-                const src = `themes/${name}.order.json`;
+                const src = `${constraintsDir}/${name}.order.json`;
                 if (!existsSync(src)) {
                     console.error(`❌ Order constraint file not found: ${src}`);
                     process.exit(1);
@@ -122,12 +130,21 @@ export async function graphCommand(options) {
                         const numericOrders = order;
                         issues = MonotonicPlugin(numericOrders, parseSize, 'monotonic').evaluate(engine, allIdsInHasse);
                     }
-                    // Attach threshold (and any other runtime constraints) respecting config flags
-                    const cfgRes = loadConfig(undefined);
-                    if (cfgRes.ok) {
+                    // Attach threshold (and any other runtime constraints) respecting config flags.
+                    // Honor the global --config and --constraints-dir, matching `validate`.
+                    const cfgRes = loadConfig(options.config);
+                    if (!cfgRes.ok) {
+                        // An explicitly requested config that fails is a hard error (parity with
+                        // validate); otherwise proceed with order-file violations only.
+                        if (options.config) {
+                            console.error(cfgRes.error);
+                            process.exit(2);
+                        }
+                    }
+                    else {
                         const config = cfgRes.value;
                         const knownIds = new Set(Object.keys(flat));
-                        setupConstraints(engine, { config, bp: breakpoint }, { knownIds });
+                        setupConstraints(engine, { config, bp: breakpoint, constraintsDir }, { knownIds });
                         const runtimeIssues = engine.evaluate(allIdsInHasse);
                         issues.push(...runtimeIssues);
                     }

package/cli/commands/graph.ts

@@ -15,8 +15,11 @@ function generateDependencyGraph(edges: Array<[string, string]>, format: string)
       dot += '\n'; edges.forEach(([f,t]) => { dot += `  "${f}" -> "${t}";\n`; });
       return dot + '}\n'; }
     case 'mermaid': {
+      // Injective id encoding so distinct token ids (e.g. a.b vs a_b) never
+      // collapse to the same Mermaid node (TASK-027).
+      const safe = (s: string) => s.replace(/[^a-zA-Z0-9]/g, (c) => `_${c.charCodeAt(0)}_`);
       let mermaid = 'graph LR\n'; const mermaidNodes = new Set<string>();
-      edges.forEach(([from,to]) => { const fromId = from.replace(/[^a-zA-Z0-9]/g,'_'); const toId = to.replace(/[^a-zA-Z0-9]/g,'_');
+      edges.forEach(([from,to]) => { const fromId = safe(from); const toId = safe(to);
         if (!mermaidNodes.has(fromId)) { mermaid += `  ${fromId}["${from}"]\n`; mermaidNodes.add(fromId); }
         if (!mermaidNodes.has(toId)) { mermaid += `  ${toId}["${to}"]\n`; mermaidNodes.add(toId); }
         mermaid += `  ${fromId} --> ${toId}\n`; });
@@ -33,16 +36,21 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
   if (options.hasse) {
     const name = options.hasse;
   const bundle = (options as any).bundle;
+  const constraintsDir = options['constraints-dir'] ?? 'themes';
   const fmt = (options.format === 'json' ? 'mermaid' : options.format) as 'mermaid' | 'dot' | 'svg' | 'png';
-    const imageFrom = options.imageFrom || 'mermaid';
-    const filterPrefixes = options.filterPrefix ? options.filterPrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
-    const excludePrefixes = options.excludePrefix ? options.excludePrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
-    const onlyViolations = options.onlyViolations || false;
-    const highlightViolations = options.highlightViolations || false;
-    const violationColor = options.violationColor || '#ff2d55';
-    const labelViolations = options.labelViolations || false;
-    const labelTruncate = Math.max(0, options.labelTruncate || 0);
-    const minSeverity = options.minSeverity || 'warn';
+    const imageFrom = options['image-from'] || 'mermaid';
+    // The CLI runs with camel-case-expansion off, so kebab flags arrive only under
+    // their kebab keys. Read those (camelCase reads here silently no-op'd before).
+    const filterPrefix = options['filter-prefix'];
+    const excludePrefix = options['exclude-prefix'];
+    const filterPrefixes = filterPrefix ? filterPrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
+    const excludePrefixes = excludePrefix ? excludePrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
+    const onlyViolations = options['only-violations'] || false;
+    const highlightViolations = options['highlight-violations'] || false;
+    const violationColor = options['violation-color'] || '#ff2d55';
+    const labelViolations = options['label-violations'] || false;
+    const labelTruncate = Math.max(0, options['label-truncate'] || 0);
+    const minSeverity = options['min-severity'] || 'warn';
     const focus = options.focus; const radius = Math.max(0, options.radius || 1);
     for (const breakpoint of plan) {
       const suffixParts: string[] = [];
@@ -57,7 +65,7 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
       const ext = baseFmt === 'mermaid' ? 'mmd' : 'dot';
       const outDir = 'dist/graphs'; const baseFile = `${outDir}/${name}${suffix}-hasse.${ext}`;
       try {
-        const src = `themes/${name}.order.json`;
+        const src = `${constraintsDir}/${name}.order.json`;
         if (!existsSync(src)) { console.error(`❌ Order constraint file not found: ${src}`); process.exit(1); }
         const { order } = JSON.parse(readFileSync(src, 'utf8'));
         const { buildPoset, transitiveReduction, toMermaidHasseStyled, toDotHasseStyled, filterByPrefix, filterExcludePrefix, khopSubgraph, pickSeedsByPattern } = await import('../../core/poset.js');
@@ -93,12 +101,17 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
             issues = MonotonicPlugin(numericOrders, parseSize, 'monotonic').evaluate(engine, allIdsInHasse);
           }
 
-          // Attach threshold (and any other runtime constraints) respecting config flags
-          const cfgRes = loadConfig(undefined);
-          if (cfgRes.ok) {
+          // Attach threshold (and any other runtime constraints) respecting config flags.
+          // Honor the global --config and --constraints-dir, matching `validate`.
+          const cfgRes = loadConfig(options.config);
+          if (!cfgRes.ok) {
+            // An explicitly requested config that fails is a hard error (parity with
+            // validate); otherwise proceed with order-file violations only.
+            if (options.config) { console.error(cfgRes.error); process.exit(2); }
+          } else {
             const config = cfgRes.value;
             const knownIds = new Set(Object.keys(flat as Record<string, FlatToken>));
-            setupConstraints(engine, { config, bp: breakpoint }, { knownIds });
+            setupConstraints(engine, { config, bp: breakpoint, constraintsDir }, { knownIds });
             const runtimeIssues = engine.evaluate(allIdsInHasse);
             issues.push(...runtimeIssues);
           }

package/cli/commands/patch-apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patch-apply.d.ts","sourceRoot":"","sources":["patch-apply.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkCrD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4C9E"}
+{"version":3,"file":"patch-apply.d.ts","sourceRoot":"","sources":["patch-apply.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkCrD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+C9E"}

package/cli/commands/patch-apply.js

@@ -60,7 +60,10 @@ export async function patchApplyCommand(opts) {
     for (const c of patchDoc.changes) {
         applyChange(tokens, c.id, c.to, c.type);
     }
-    if (opts.dryRun) {
+    // Read both forms: kebab from the CLI (camel-case-expansion off) and camelCase
+    // from programmatic callers. Reading only opts.dryRun was dead for the CLI, so
+    // `--dry-run --output` silently wrote the file (TASK-024).
+    if (opts['dry-run'] ?? opts.dryRun) {
         outputResult(tokens, 'json');
         return;
     }

package/cli/commands/patch-apply.ts

@@ -66,7 +66,10 @@ export async function patchApplyCommand(opts: PatchApplyOptions): Promise<void>
     applyChange(tokens, c.id, c.to, c.type);
   }
 
-  if (opts.dryRun) {
+  // Read both forms: kebab from the CLI (camel-case-expansion off) and camelCase
+  // from programmatic callers. Reading only opts.dryRun was dead for the CLI, so
+  // `--dry-run --output` silently wrote the file (TASK-024).
+  if (opts['dry-run'] ?? opts.dryRun) {
     outputResult(tokens, 'json');
     return;
   }

package/cli/commands/set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["set.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,UAAU,EAAe,MAAM,aAAa,CAAC;AAmE1E,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAsKnE"}
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["set.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAiB,UAAU,EAAe,MAAM,aAAa,CAAC;AAmE1E,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAuKnE"}

package/cli/commands/set.js

@@ -1,9 +1,8 @@
-import { join } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
 import { loadConfig } from '../config.js';
 import { Engine } from '../../core/engine.js';
 import { flattenTokens } from '../../core/flatten.js';
-import { loadTokens, outputResult } from './utils.js';
+import { mergeTokens } from '../../core/breakpoints.js';
+import { loadThemeTokens, loadTokens, outputResult } from './utils.js';
 import { setupConstraints } from '../constraint-registry.js';
 // Lightweight suggestion helpers (kept local – why command uses core formatter instead)
 function levenshtein(a, b) {
@@ -81,7 +80,10 @@ export async function setCommand(options) {
         process.exit(2);
     }
     const config = cfgRes.value;
-    const tokens = loadTokens(tokensPath);
+    let tokens = loadTokens(tokensPath);
+    if (options.theme) {
+        tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
+    }
     // Create engine with flattened tokens
     const { flat, edges } = flattenTokens(tokens);
     const init = {};
@@ -103,18 +105,6 @@ export async function setCommand(options) {
             process.exit(1);
         }
     }
-    if (options.theme) {
-        const themePath = join('tokens/themes', `${options.theme}.json`);
-        if (existsSync(themePath)) {
-            const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-            for (const [id, value] of Object.entries(themeTokens)) {
-                engine.commit(id, value);
-            }
-        }
-        else {
-            console.warn(`Theme file not found: ${themePath}`);
-        }
-    }
     let finalResult = {};
     function setDeep(obj, parts, v) {
         let cur = obj;
@@ -210,7 +200,7 @@ export async function setCommand(options) {
             for (const e of entries)
                 console.log(' ', e);
         }
-        const dryRun = process.argv.includes('--dry-run');
+        const dryRun = !!(options['dry-run'] ?? options.dryRun);
         for (const { id, value, unset } of entries) {
             if (unset) {
                 if (!options.quiet)
@@ -227,7 +217,8 @@ export async function setCommand(options) {
             }
         }
         const format = options.format || 'json';
-        outputResult(finalResult, format, options.output);
+        // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+        outputResult(finalResult, format, dryRun ? undefined : options.output);
         if (options.write && !dryRun) {
             const path = 'tokens/overrides/local.json';
             let local = {};
@@ -264,9 +255,17 @@ export async function setCommand(options) {
         }
         Object.assign(finalResult, result.patch);
     }
+    const dryRun = !!(options['dry-run'] ?? options.dryRun);
     const format = options.format || 'json';
-    outputResult(finalResult, format, options.output);
+    // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+    outputResult(finalResult, format, dryRun ? undefined : options.output);
     if (options.write || (options.unset && options.unset.length)) {
+        // --dry-run must not touch the filesystem (it previously persisted the
+        // override file on the positional path; the batch path already guarded it).
+        if (dryRun) {
+            console.log('Dry-run: changes not written');
+            return;
+        }
         const fs = await import('node:fs');
         const path = 'tokens/overrides/local.json';
         let local = {};

package/cli/commands/set.ts

@@ -1,10 +1,9 @@
-import { join } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
 import { loadConfig } from '../config.js';
 import { Engine } from '../../core/engine.js';
 import { flattenTokens, type FlatToken } from '../../core/flatten.js';
+import { mergeTokens } from '../../core/breakpoints.js';
 import type { OverridesTree, SetOptions, ValuesPatch } from '../types.js';
-import { loadTokens, outputResult } from './utils.js';
+import { loadThemeTokens, loadTokens, outputResult } from './utils.js';
 import { setupConstraints } from '../constraint-registry.js';
 
 // Lightweight suggestion helpers (kept local – why command uses core formatter instead)
@@ -76,7 +75,11 @@ export async function setCommand(options: SetOptions): Promise<void> {
   const cfgRes = loadConfig(options.config);
   if (!cfgRes.ok) { console.error(cfgRes.error); process.exit(2); }
   const config = cfgRes.value;
-  const tokens = loadTokens(tokensPath);
+  let tokens = loadTokens(tokensPath);
+
+  if (options.theme) {
+    tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
+  }
 
   // Create engine with flattened tokens
   const { flat, edges } = flattenTokens(tokens);
@@ -105,18 +108,6 @@ export async function setCommand(options: SetOptions): Promise<void> {
     }
   }
 
-  if (options.theme) {
-    const themePath = join('tokens/themes', `${options.theme}.json`);
-    if (existsSync(themePath)) {
-      const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-      for (const [id, value] of Object.entries(themeTokens)) {
-        engine.commit(id, value as string | number);
-      }
-    } else {
-      console.warn(`Theme file not found: ${themePath}`);
-    }
-  }
-
   let finalResult: ValuesPatch = {};
 
   function setDeep(obj: OverridesTree, parts: string[], v: unknown) {
@@ -183,7 +174,7 @@ export async function setCommand(options: SetOptions): Promise<void> {
     for (const ent of entries) ensureKnownOrSuggest(ent.id);
     const debug = process.argv.includes('--debug-set') || process.env.DCV_DEBUG_SET === '1';
     if (debug) { console.log('[set:batch] parsed entries:'); for (const e of entries) console.log(' ', e); }
-    const dryRun = process.argv.includes('--dry-run');
+    const dryRun = !!(options['dry-run'] ?? options.dryRun);
     for (const { id, value, unset } of entries) {
       if (unset) { if (!options.quiet) console.log(`preview: unset ${id}`); }
       else {
@@ -193,7 +184,8 @@ export async function setCommand(options: SetOptions): Promise<void> {
       }
     }
     const format = options.format || 'json';
-    outputResult(finalResult, format, options.output);
+    // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+    outputResult(finalResult, format, dryRun ? undefined : options.output);
     if (options.write && !dryRun) {
       const path = 'tokens/overrides/local.json';
       let local: OverridesTree = {} as OverridesTree;
@@ -218,9 +210,17 @@ export async function setCommand(options: SetOptions): Promise<void> {
     }
     Object.assign(finalResult, result.patch);
   }
+  const dryRun = !!(options['dry-run'] ?? options.dryRun);
   const format = options.format || 'json';
-  outputResult(finalResult, format, options.output);
+  // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+  outputResult(finalResult, format, dryRun ? undefined : options.output);
   if (options.write || (options.unset && options.unset.length)) {
+    // --dry-run must not touch the filesystem (it previously persisted the
+    // override file on the positional path; the batch path already guarded it).
+    if (dryRun) {
+      console.log('Dry-run: changes not written');
+      return;
+    }
     const fs = await import('node:fs');
     const path = 'tokens/overrides/local.json';
     let local: OverridesTree = {} as OverridesTree;

package/cli/commands/utils.d.ts

@@ -1,4 +1,5 @@
 import type { TokenNode } from '../../core/flatten.js';
 export declare function loadTokens(tokensPath: string): TokenNode;
+export declare function loadThemeTokens(theme: string): TokenNode;
 export declare function outputResult(data: unknown, format: string, outputPath?: string): void;
 //# sourceMappingURL=utils.d.ts.map

package/cli/commands/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,uBAAuB,CAAC;AAInE,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAUxD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CA8BrF"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,uBAAuB,CAAC;AAInE,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAUxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAoBxD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CA8BrF"}