designlang 6.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/tests/cli.test.js

@@ -2,6 +2,7 @@ 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');
 
@@ -31,4 +32,53 @@ describe('CLI', () => {
       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']);
+  });
 });

package/tests/extractors.test.js

@@ -11,6 +11,11 @@ import { extractLayout } from '../src/extractors/layout.js';
 import { extractGradients } from '../src/extractors/gradients.js';
 import { extractZIndex } from '../src/extractors/zindex.js';
 import { scoreDesignSystem } from '../src/extractors/scoring.js';
+import { extractStackFingerprint } from '../src/extractors/stack-fingerprint.js';
+import { extractCssHealth } from '../src/extractors/css-health.js';
+import { remediateFailingPairs } from '../src/extractors/a11y-remediation.js';
+import { extractSemanticRegions } from '../src/extractors/semantic-regions.js';
+import { clusterComponents } from '../src/extractors/component-clusters.js';
 
 // ── Shared fixture defaults ─────────────────────────────────────
 
@@ -659,3 +664,129 @@ describe('scoreDesignSystem', () => {
     assert.ok(result.issues.some(i => i.includes('primary')));
   });
 });
+
+// ── extractStackFingerprint ─────────────────────────────────────
+
+describe('extractStackFingerprint', () => {
+  it('detects Next.js from __NEXT_DATA__', () => {
+    const out = extractStackFingerprint({ windowGlobals: ['__NEXT_DATA__'], scripts: [], metas: [], classNameSample: [] });
+    assert.equal(out.framework, 'next');
+  });
+
+  it('detects Tailwind from utility-heavy classNames', () => {
+    const out = extractStackFingerprint({
+      windowGlobals: [],
+      scripts: [],
+      metas: [],
+      classNameSample: [
+        'flex items-center gap-4 text-sm text-gray-600',
+        'px-4 py-2 rounded-md bg-blue-500',
+        'grid grid-cols-3 md:grid-cols-4',
+        'flex justify-center',
+        'p-4 shadow-md',
+        'mt-4 text-lg',
+      ],
+    });
+    assert.equal(out.css.layer, 'tailwind');
+    assert.ok(out.css.tailwind.utilities.length > 0);
+  });
+
+  it('returns unknown when nothing matches', () => {
+    const out = extractStackFingerprint({ windowGlobals: [], scripts: [], metas: [], classNameSample: ['foo', 'bar'] });
+    assert.equal(out.framework, 'unknown');
+    assert.equal(out.css.layer, 'unknown');
+  });
+});
+
+// ── extractCssHealth ────────────────────────────────────────────
+
+describe('extractCssHealth', () => {
+  const payload = [{
+    url: 'https://x.com/a.css',
+    text: '.a{color:red}.a{color:red}.b{color:blue !important}.c-webkit-foo{color:x}@keyframes fade{0%{opacity:0}100%{opacity:1}\n}',
+    totalBytes: 1000,
+    ranges: [{ start: 0, end: 400 }], // 60% unused
+  }];
+
+  it('counts !important', () => {
+    const r = extractCssHealth(payload);
+    assert.equal(r.importantCount, 1);
+  });
+
+  it('counts duplicate declarations', () => {
+    const r = extractCssHealth(payload);
+    assert.ok(r.duplicates >= 1);
+  });
+
+  it('reports unused bytes', () => {
+    const r = extractCssHealth(payload);
+    assert.equal(r.unusedBytes, 600);
+    assert.equal(r.usedBytes, 400);
+  });
+
+  it('catalogs keyframes', () => {
+    const r = extractCssHealth(payload);
+    assert.ok(r.keyframes.some(k => k.name === 'fade'));
+  });
+});
+
+// ── remediateFailingPairs ───────────────────────────────────────
+
+describe('remediateFailingPairs', () => {
+  it('suggests a palette color that passes AA', () => {
+    const failing = [{ fg: '#777777', bg: '#ffffff', ratio: 3.5, rule: 'AA-normal' }];
+    const palette = ['#000000', '#222222', '#555555', '#cccccc'];
+    const out = remediateFailingPairs(failing, palette);
+    assert.equal(out.length, 1);
+    assert.ok(out[0].suggestion);
+    assert.ok(out[0].suggestion.newRatio >= 4.5);
+  });
+
+  it('returns null suggestion when no palette color passes', () => {
+    const failing = [{ fg: '#eee', bg: '#fff', ratio: 1.1, rule: 'AA-normal' }];
+    const palette = ['#dedede'];
+    const out = remediateFailingPairs(failing, palette);
+    assert.equal(out[0].suggestion, null);
+  });
+});
+
+// ── extractSemanticRegions ──────────────────────────────────────
+
+describe('extractSemanticRegions', () => {
+  it('labels header as nav', () => {
+    const out = extractSemanticRegions([{ tag: 'header', role: '', className: '', id: '', text: 'Home About', headings: [], buttonCount: 3, cardCount: 0, bounds: { x: 0, y: 0, w: 1280, h: 80 } }]);
+    assert.equal(out[0].role, 'nav');
+  });
+
+  it('labels section with CTA + heading as hero', () => {
+    const out = extractSemanticRegions([{ tag: 'section', role: '', className: 'hero', id: '', text: 'Welcome', headings: ['Build better'], buttonCount: 2, cardCount: 0, bounds: { x: 0, y: 80, w: 1280, h: 600 } }]);
+    assert.equal(out[0].role, 'hero');
+  });
+
+  it('labels pricing based on cards + keyword', () => {
+    const out = extractSemanticRegions([{ tag: 'section', role: '', className: '', id: '', text: 'Basic $9/mo Pro $29/mo Team $99/mo', headings: ['Pricing'], buttonCount: 3, cardCount: 3, bounds: { x: 0, y: 0, w: 1280, h: 400 } }]);
+    assert.equal(out[0].role, 'pricing');
+  });
+});
+
+// ── clusterComponents ───────────────────────────────────────────
+
+describe('clusterComponents', () => {
+  it('collapses identical instances into one entry', () => {
+    const els = Array.from({ length: 5 }, () => ({ kind: 'button', structuralHash: 'button>span', styleVector: [16, 8, 0, 0], css: { bg: '#f00' } }));
+    const out = clusterComponents(els);
+    assert.equal(out.length, 1);
+    assert.equal(out[0].instanceCount, 5);
+  });
+
+  it('separates variants with different style vectors', () => {
+    const els = [
+      { kind: 'button', structuralHash: 'button>span', styleVector: [16, 8, 0, 0], css: { bg: '#f00' } },
+      { kind: 'button', structuralHash: 'button>span', styleVector: [16, 8, 0, 0], css: { bg: '#f00' } },
+      { kind: 'button', structuralHash: 'button>span', styleVector: [0, 0, 16, 8], css: { bg: '#0f0' } },
+    ];
+    const out = clusterComponents(els);
+    assert.equal(out.length, 1);
+    assert.equal(out[0].variants.length, 2);
+  });
+});