designlang 5.0.0 → 7.0.0

package/src/mcp/server.js

@@ -0,0 +1,110 @@
+// Thin stdio MCP server glue. Loads the latest extraction from the given
+// output directory and wires buildResources + buildTools into the SDK.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { buildResources } from './resources.js';
+import { buildTools } from './tools.js';
+
+// Best-effort reconstruction of a design object from the files on disk.
+// We only need what the tools/resources consume: tokens + regions +
+// componentClusters + accessibility.remediation + cssHealth + colors.all.
+function loadExtraction(outputDir) {
+  if (!existsSync(outputDir)) return null;
+  const entries = readdirSync(outputDir);
+  const tokenFiles = entries
+    .filter((f) => f.endsWith('-design-tokens.json'))
+    .map((f) => {
+      const p = join(outputDir, f);
+      return { path: p, mtime: statSync(p).mtimeMs, prefix: f.replace(/-design-tokens\.json$/, '') };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+
+  if (!tokenFiles.length) return null;
+  const latest = tokenFiles[0];
+
+  let tokens;
+  try { tokens = JSON.parse(readFileSync(latest.path, 'utf-8')); } catch { return null; }
+
+  // Legacy (pre-v7) tokens don't have primitive/semantic. Skip silently.
+  if (!tokens?.primitive || !tokens?.semantic) {
+    return { tokens: null, design: {} };
+  }
+
+  // Load the MCP companion written at extraction time (`*-mcp.json`).
+  // Falls back to empty shape if absent — older extractions stay usable for
+  // token resources/tools even without regions/components/health.
+  const companionPath = join(outputDir, `${latest.prefix}-mcp.json`);
+  let companion = null;
+  if (existsSync(companionPath)) {
+    try { companion = JSON.parse(readFileSync(companionPath, 'utf-8')); } catch { /* ignore */ }
+  }
+
+  const design = {
+    colors: { all: companion?.colors?.all || [] },
+    regions: companion?.regions || [],
+    componentClusters: companion?.componentClusters || [],
+    accessibility: { remediation: companion?.accessibility?.remediation || [] },
+    cssHealth: companion?.cssHealth ?? null,
+  };
+
+  return { tokens, design };
+}
+
+export async function run({ outputDir }) {
+  const resolved = resolve(outputDir || './design-extract-output');
+  const loaded = loadExtraction(resolved);
+  const tokens = loaded?.tokens ?? null;
+  const design = loaded?.design ?? {};
+
+  const resources = buildResources({ design, tokens });
+  const tools = buildTools({ design, tokens });
+
+  const server = new Server(
+    { name: 'designlang', version: '7.0.0' },
+    { capabilities: { resources: {}, tools: {} } },
+  );
+
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: tokens ? resources.list() : [],
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+    if (!tokens) throw Object.assign(new Error('no extraction loaded'), { code: -32002 });
+    const { uri } = req.params;
+    const r = resources.read(uri);
+    return { contents: [r] };
+  });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: tools.list() }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    if (!tokens) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: 'no extraction loaded' }],
+      };
+    }
+    const { name, arguments: args } = req.params;
+    try {
+      const result = await tools.call(name, args);
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    } catch (err) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: err?.message || String(err) }],
+      };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/mcp/tools.js

@@ -0,0 +1,149 @@
+// MCP tools builder. Pure/testable — returns { list, call } over the
+// loaded design + tokens. No transport concerns here.
+
+import { remediateFailingPairs } from '../extractors/a11y-remediation.js';
+
+function rpcError(code, message) {
+  const e = new Error(message);
+  e.code = code;
+  return e;
+}
+
+// Flatten a DTCG token tree to [{ path, $type, $value }] leaves.
+function flattenTokens(tree, prefix, out) {
+  if (tree == null || typeof tree !== 'object') return;
+  if ('$value' in tree) {
+    out.push({ path: prefix, $type: tree.$type, $value: tree.$value });
+    return;
+  }
+  for (const key of Object.keys(tree)) {
+    const next = prefix ? `${prefix}.${key}` : key;
+    flattenTokens(tree[key], next, out);
+  }
+}
+
+function paletteHexes(design) {
+  const all = design?.colors?.all || [];
+  const out = [];
+  for (const entry of all) {
+    if (!entry) continue;
+    if (typeof entry === 'string') out.push(entry);
+    else if (typeof entry === 'object' && typeof entry.hex === 'string') out.push(entry.hex);
+  }
+  return out;
+}
+
+const TOOL_DEFS = [
+  {
+    name: 'search_tokens',
+    description: 'Case-insensitive substring match over all token dot-paths.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'substring to search for' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'find_nearest_color',
+    description: 'Find the nearest palette color that passes the requested WCAG contrast rule against the given hex.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        hex: { type: 'string', description: 'background hex (e.g. #ffffff)' },
+        level: { type: 'string', enum: ['AA-normal', 'AA-large', 'AAA-normal', 'AAA-large'] },
+      },
+      required: ['hex', 'level'],
+    },
+  },
+  {
+    name: 'get_region',
+    description: 'Return the region with the given role (e.g. hero, nav, footer).',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_component',
+    description: 'Return the component cluster with matching kind, optionally narrowed to a variant index.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        variant: { type: 'number' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'list_failing_contrast_pairs',
+    description: 'Return the accessibility remediation array (failing fg/bg pairs with suggestions).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+export function buildTools({ design, tokens }) {
+  // Pre-flatten for search.
+  const flat = [];
+  flattenTokens(tokens?.primitive, 'primitive', flat);
+  flattenTokens(tokens?.semantic, 'semantic', flat);
+
+  async function searchTokens(args) {
+    if (!args || typeof args.query !== 'string') throw rpcError(-32602, 'search_tokens: query must be a string');
+    const q = args.query.toLowerCase();
+    const matches = flat.filter(t => t.path.toLowerCase().includes(q));
+    return { matches };
+  }
+
+  async function findNearestColor(args) {
+    if (!args || typeof args.hex !== 'string') throw rpcError(-32602, 'find_nearest_color: hex must be a string');
+    const validLevels = new Set(['AA-normal', 'AA-large', 'AAA-normal', 'AAA-large']);
+    if (!validLevels.has(args.level)) throw rpcError(-32602, 'find_nearest_color: level must be one of AA-normal|AA-large|AAA-normal|AAA-large');
+    const palette = paletteHexes(design);
+    const [res] = remediateFailingPairs(
+      [{ fg: '#000000', bg: args.hex, ratio: 0, rule: args.level }],
+      palette,
+    );
+    if (!res?.suggestion) return { color: null, newRatio: null };
+    return { color: res.suggestion.color, newRatio: res.suggestion.newRatio, replace: res.suggestion.replace };
+  }
+
+  async function getRegion(args) {
+    if (!args || typeof args.name !== 'string') throw rpcError(-32602, 'get_region: name must be a string');
+    const regions = design?.regions || [];
+    return regions.find(r => r && (r.role === args.name || r.name === args.name)) || null;
+  }
+
+  async function getComponent(args) {
+    if (!args || typeof args.name !== 'string') throw rpcError(-32602, 'get_component: name must be a string');
+    const clusters = design?.componentClusters || [];
+    const found = clusters.find(c => c && c.kind === args.name);
+    if (!found) return null;
+    if (typeof args.variant === 'number' && Array.isArray(found.variants)) {
+      return found.variants[args.variant] ?? null;
+    }
+    return found;
+  }
+
+  async function listFailing() {
+    return design?.accessibility?.remediation || [];
+  }
+
+  const dispatch = {
+    search_tokens: searchTokens,
+    find_nearest_color: findNearestColor,
+    get_region: getRegion,
+    get_component: getComponent,
+    list_failing_contrast_pairs: listFailing,
+  };
+
+  return {
+    list() { return TOOL_DEFS.slice(); },
+    async call(name, args) {
+      const fn = dispatch[name];
+      if (!fn) throw rpcError(-32602, `Unknown tool: ${name}`);
+      return await fn(args || {});
+    },
+  };
+}

package/src/utils.js

@@ -20,6 +20,29 @@ const NAMED_COLORS = {
   maroon: { r: 128, g: 0, b: 0, a: 1 },
 };
 
+function oklabToRgb(L, a, b) {
+  // OKLab -> linear sRGB
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+  let r = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  let g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  let bl = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
+  // Clamp to [0,255]
+  const clamp = v => Math.round(Math.max(0, Math.min(1, v)) * 255);
+  return { r: clamp(r), g: clamp(g), b: clamp(bl) };
+}
+
+function oklchToRgb(L, C, H) {
+  const hRad = H * Math.PI / 180;
+  const a = C * Math.cos(hRad);
+  const b = C * Math.sin(hRad);
+  return oklabToRgb(L, a, b);
+}
+
 export function parseColor(str) {
   if (!str || str === 'none' || str === 'currentcolor' || str === 'inherit' || str === 'initial') return null;
   str = str.trim().toLowerCase();
@@ -58,6 +81,51 @@ export function parseColor(str) {
     return { ...rgb, a: hslMatch[4] !== undefined ? +hslMatch[4] : 1 };
   }
 
+  // hsl modern: hsl(210 50% 40%) or hsl(210 50% 40% / 0.5)
+  const hslModern = str.match(/hsla?\(\s*([\d.]+)\s+([\d.]+)%\s+([\d.]+)%\s*(?:\/\s*([\d.]+%?))?\s*\)/);
+  if (hslModern) {
+    const rgb = hslToRgb(+hslModern[1], +hslModern[2], +hslModern[3]);
+    let a = 1;
+    if (hslModern[4] !== undefined) {
+      a = hslModern[4].endsWith('%') ? parseFloat(hslModern[4]) / 100 : +hslModern[4];
+    }
+    return { ...rgb, a };
+  }
+
+  // oklch(L C H) or oklch(L C H / a)
+  const oklchMatch = str.match(/oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*(?:\/\s*([\d.]+%?))?\s*\)/);
+  if (oklchMatch) {
+    const rgb = oklchToRgb(+oklchMatch[1], +oklchMatch[2], +oklchMatch[3]);
+    let a = 1;
+    if (oklchMatch[4] !== undefined) {
+      a = oklchMatch[4].endsWith('%') ? parseFloat(oklchMatch[4]) / 100 : +oklchMatch[4];
+    }
+    return { ...rgb, a };
+  }
+
+  // oklab(L a b) or oklab(L a b / alpha)
+  const oklabMatch = str.match(/oklab\(\s*([\d.e+-]+)\s+([\d.e+-]+)\s+([\d.e+-]+)\s*(?:\/\s*([\d.]+%?))?\s*\)/);
+  if (oklabMatch) {
+    const rgb = oklabToRgb(+oklabMatch[1], +oklabMatch[2], +oklabMatch[3]);
+    let a = 1;
+    if (oklabMatch[4] !== undefined) {
+      a = oklabMatch[4].endsWith('%') ? parseFloat(oklabMatch[4]) / 100 : +oklabMatch[4];
+    }
+    return { ...rgb, a };
+  }
+
+  // color-mix(in srgb, color1 pct, color2)
+  const mixMatch = str.match(/color-mix\(\s*in\s+\w+\s*,\s*(.+?)\s*,\s*(.+?)\s*\)/);
+  if (mixMatch) {
+    const part1 = mixMatch[1].trim().replace(/\s+\d+%$/, '');
+    const part2 = mixMatch[2].trim().replace(/\s+\d+%$/, '');
+    const c1 = parseColor(part1);
+    const c2 = parseColor(part2);
+    if (c1 && c2) {
+      return { r: Math.round((c1.r + c2.r) / 2), g: Math.round((c1.g + c2.g) / 2), b: Math.round((c1.b + c2.b) / 2), a: (c1.a + c2.a) / 2 };
+    }
+  }
+
   return null;
 }
 

package/tests/cli.test.js

@@ -0,0 +1,84 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { parsePlatforms, mergeConfig } from '../src/config.js';
+
+const CLI_PATH = resolve(import.meta.dirname, '..', 'bin', 'design-extract.js');
+
+describe('CLI', () => {
+  it('shows help with --help', () => {
+    const output = execFileSync('node', [CLI_PATH, '--help'], { encoding: 'utf-8' });
+    assert.ok(output.includes('designlang'));
+    assert.ok(output.includes('Extract'));
+  });
+
+  it('shows version with --version', () => {
+    const output = execFileSync('node', [CLI_PATH, '--version'], { encoding: 'utf-8' });
+    assert.ok(output.trim().match(/^\d+\.\d+\.\d+$/));
+  });
+
+  it('shows version number 6.0.0', () => {
+    const output = execFileSync('node', [CLI_PATH, '--version'], { encoding: 'utf-8' });
+    assert.equal(output.trim(), '6.0.0');
+  });
+
+  it('exits with error when no arguments provided', () => {
+    try {
+      execFileSync('node', [CLI_PATH], { encoding: 'utf-8', stdio: 'pipe' });
+      assert.fail('Should have thrown');
+    } catch (err) {
+      // Commander exits with code 1 when required argument is missing
+      assert.ok(err.status !== 0);
+    }
+  });
+
+  it('lists --platforms option in help output', () => {
+    const output = execFileSync('node', [CLI_PATH, '--help'], { encoding: 'utf-8' });
+    assert.ok(output.includes('--platforms'));
+  });
+});
+
+describe('parsePlatforms', () => {
+  it('defaults to web only', () => {
+    assert.deepEqual(parsePlatforms('web'), ['web']);
+  });
+
+  it('parses comma-separated values', () => {
+    assert.deepEqual(parsePlatforms('ios,android'), ['web', 'ios', 'android']);
+  });
+
+  it('expands "all" to every known platform', () => {
+    assert.deepEqual(parsePlatforms('all'), ['web', 'ios', 'android', 'flutter', 'wordpress']);
+  });
+
+  it('always includes web (additive)', () => {
+    assert.ok(parsePlatforms('ios').includes('web'));
+    assert.ok(parsePlatforms('wordpress').includes('web'));
+  });
+
+  it('ignores unknown platforms', () => {
+    assert.deepEqual(parsePlatforms('ios,badplatform,android'), ['web', 'ios', 'android']);
+  });
+
+  it('accepts arrays', () => {
+    assert.deepEqual(parsePlatforms(['ios', 'flutter']), ['web', 'ios', 'flutter']);
+  });
+});
+
+describe('mergeConfig platforms', () => {
+  it('threads CLI --platforms through mergeConfig', () => {
+    const merged = mergeConfig({ platforms: 'ios,flutter' }, {});
+    assert.deepEqual(merged.platforms, ['web', 'ios', 'flutter']);
+  });
+
+  it('honors platforms from config file', () => {
+    const merged = mergeConfig({}, { platforms: 'android' });
+    assert.deepEqual(merged.platforms, ['web', 'android']);
+  });
+
+  it('defaults to [web] when neither CLI nor config provides platforms', () => {
+    const merged = mergeConfig({}, {});
+    assert.deepEqual(merged.platforms, ['web']);
+  });
+});