designlang 6.0.0 → 7.1.0

package/src/index.js

@@ -16,6 +16,11 @@ import { extractZIndex } from './extractors/zindex.js';
 import { extractIcons } from './extractors/icons.js';
 import { extractFonts } from './extractors/fonts.js';
 import { extractImageStyles } from './extractors/images.js';
+import { extractStackFingerprint } from './extractors/stack-fingerprint.js';
+import { extractCssHealth } from './extractors/css-health.js';
+import { remediateFailingPairs } from './extractors/a11y-remediation.js';
+import { extractSemanticRegions } from './extractors/semantic-regions.js';
+import { clusterComponents } from './extractors/component-clusters.js';
 
 function safeExtract(fn, ...args) {
   try { return fn(...args); } catch { return null; }
@@ -54,6 +59,10 @@ export async function extractDesignLanguage(url, options = {}) {
     fonts: rawData.light.fontData ? (safeExtract(extractFonts, rawData.light.fontData) || { fonts: [], systemFonts: [] }) : { fonts: [], systemFonts: [] },
     images: rawData.light.images ? (safeExtract(extractImageStyles, rawData.light.images) || { patterns: [], aspectRatios: [] }) : { patterns: [], aspectRatios: [] },
     componentScreenshots: rawData.componentScreenshots || {},
+    stack: safeExtract(extractStackFingerprint, rawData.light.stack) || { framework: 'unknown', css: { layer: 'unknown', tailwind: null }, analytics: [], detectedFrom: { globalCount: 0, scriptCount: 0, classSampleSize: 0 } },
+    cssHealth: safeExtract(extractCssHealth, rawData.light.cssCoverage) || null,
+    regions: safeExtract(extractSemanticRegions, rawData.light.sections) || [],
+    componentClusters: safeExtract(clusterComponents, rawData.light.componentCandidates) || [],
     score: null,
   };
 
@@ -77,6 +86,26 @@ export async function extractDesignLanguage(url, options = {}) {
     };
   }
 
+  // A11y remediation: derive failing pairs from accessibility extractor output
+  // and propose palette colors that pass the matching WCAG rule.
+  try {
+    const a11y = design.accessibility || {};
+    const palette = (design.colors?.all || []).map(c => c.hex).filter(Boolean);
+    const failingPairs = (a11y.pairs || [])
+      .filter(p => p.level === 'FAIL')
+      .map(p => ({
+        fg: p.foreground,
+        bg: p.background,
+        ratio: p.ratio,
+        rule: p.isLargeText ? 'AA-large' : 'AA-normal',
+      }));
+    design.accessibility = {
+      ...a11y,
+      failingPairs,
+      remediation: remediateFailingPairs(failingPairs, palette),
+    };
+  } catch { /* non-fatal */ }
+
   design.score = safeExtract(scoreDesignSystem, design);
   if (design.score === null) warnings.push('scoring failed');
 
@@ -85,6 +114,7 @@ export async function extractDesignLanguage(url, options = {}) {
 
 export { crawlPage } from './crawler.js';
 export { formatTokens } from './formatters/tokens.js';
+export { formatDtcgTokens } from './formatters/dtcg-tokens.js';
 export { formatMarkdown } from './formatters/markdown.js';
 export { formatTailwind } from './formatters/tailwind.js';
 export { formatCssVars } from './formatters/css-vars.js';

package/src/mcp/resources.js

@@ -0,0 +1,64 @@
+// MCP resources builder. Pure/testable — returns { list, read } over the
+// loaded design + tokens. No transport concerns here.
+
+const URIS = {
+  'designlang://tokens/primitive': {
+    name: 'Primitive tokens',
+    description: 'DTCG primitive tier (raw colors, spacing, fonts, etc.)',
+  },
+  'designlang://tokens/semantic': {
+    name: 'Semantic tokens',
+    description: 'DTCG semantic tier (aliases like action.primary, surface.default)',
+  },
+  'designlang://regions': {
+    name: 'Semantic regions',
+    description: 'Detected page regions (hero, nav, footer, etc.) with bounds',
+  },
+  'designlang://components': {
+    name: 'Component clusters',
+    description: 'Clustered component instances with variant CSS',
+  },
+  'designlang://health': {
+    name: 'CSS health',
+    description: 'Coverage, dead-rule, and z-index-stack diagnostics',
+  },
+};
+
+function rpcError(code, message) {
+  const e = new Error(message);
+  e.code = code;
+  return e;
+}
+
+export function buildResources({ design, tokens }) {
+  function payloadFor(uri) {
+    switch (uri) {
+      case 'designlang://tokens/primitive': return tokens?.primitive ?? null;
+      case 'designlang://tokens/semantic':  return tokens?.semantic ?? null;
+      case 'designlang://regions':          return design?.regions ?? [];
+      case 'designlang://components':       return design?.componentClusters ?? [];
+      case 'designlang://health':           return design?.cssHealth ?? null;
+      default: return undefined;
+    }
+  }
+
+  return {
+    list() {
+      return Object.keys(URIS).map((uri) => ({
+        uri,
+        name: URIS[uri].name,
+        description: URIS[uri].description,
+        mimeType: 'application/json',
+      }));
+    },
+    read(uri) {
+      const payload = payloadFor(uri);
+      if (payload === undefined) throw rpcError(-32602, `Unknown resource URI: ${uri}`);
+      return {
+        uri,
+        mimeType: 'application/json',
+        text: JSON.stringify(payload),
+      };
+    },
+  };
+}

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-cookies.js

@@ -0,0 +1,73 @@
+// Cookie file loaders. Supports three formats so users can paste whatever
+// their existing tooling exports:
+//   - JSON array of Playwright cookie objects: [{name, value, domain, path, …}]
+//   - Playwright storageState JSON: { cookies: [...], origins: [...] }
+//   - Netscape cookies.txt: tab-separated lines (curl / wget / browser extensions)
+//
+// Returned shape is always the Playwright cookie array.
+
+import { readFileSync } from 'fs';
+
+function parseNetscape(text, targetUrl) {
+  const cookies = [];
+  const lines = text.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Skip comment lines, but keep the Netscape `#HttpOnly_<domain>` prefix
+    // that browsers use to mark HttpOnly cookies — those are real entries.
+    if (line.startsWith('#') && !/^#HttpOnly_/i.test(line)) continue;
+    const parts = raw.split('\t');
+    if (parts.length < 7) continue;
+    const [domain, , path, secure, expires, name, value] = parts;
+    if (!name) continue;
+    const cookie = {
+      name,
+      value: value ?? '',
+      domain: domain.replace(/^#HttpOnly_/i, ''),
+      path: path || '/',
+      secure: secure === 'TRUE',
+      httpOnly: /^#HttpOnly_/i.test(domain),
+    };
+    const exp = Number(expires);
+    if (Number.isFinite(exp) && exp > 0) cookie.expires = exp;
+    if (!cookie.domain && targetUrl) cookie.url = targetUrl;
+    cookies.push(cookie);
+  }
+  return cookies;
+}
+
+function parseJson(text) {
+  const parsed = JSON.parse(text);
+  // Playwright storageState: { cookies: [...], origins: [...] }
+  if (parsed && Array.isArray(parsed.cookies)) return parsed.cookies;
+  // Raw array
+  if (Array.isArray(parsed)) return parsed;
+  throw new Error('cookie file: JSON must be a cookie array or Playwright storageState');
+}
+
+export function loadCookiesFromFile(filePath, targetUrl) {
+  const text = readFileSync(filePath, 'utf-8');
+  const trimmed = text.trimStart();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    return parseJson(text);
+  }
+  return parseNetscape(text, targetUrl);
+}
+
+// Merge CLI-provided cookies (name=value strings) with file cookies.
+// Later entries (file) override earlier entries (CLI) at the same name+domain.
+export function mergeCookies(cliCookies = [], fileCookies = [], targetUrl) {
+  const seen = new Map();
+  const parseCli = (c) => {
+    if (typeof c !== 'string') return c;
+    const [name, ...rest] = c.split('=');
+    return { name, value: rest.join('='), url: targetUrl };
+  };
+  for (const c of [...cliCookies.map(parseCli), ...fileCookies]) {
+    if (!c || !c.name) continue;
+    const key = `${c.name}|${c.domain || c.url || ''}`;
+    seen.set(key, c);
+  }
+  return [...seen.values()];
+}

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/cookies.test.js

@@ -0,0 +1,98 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFileSync, mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { loadCookiesFromFile, mergeCookies } from '../src/utils-cookies.js';
+
+const tmp = mkdtempSync(join(tmpdir(), 'dl-cookies-'));
+
+function tmpFile(name, text) {
+  const p = join(tmp, name);
+  writeFileSync(p, text, 'utf-8');
+  return p;
+}
+
+describe('loadCookiesFromFile', () => {
+  it('loads JSON array', () => {
+    const f = tmpFile('c.json', JSON.stringify([
+      { name: 'session', value: 'abc', domain: '.example.com', path: '/' },
+    ]));
+    const out = loadCookiesFromFile(f, 'https://example.com');
+    assert.equal(out.length, 1);
+    assert.equal(out[0].name, 'session');
+    assert.equal(out[0].domain, '.example.com');
+  });
+
+  it('loads Playwright storageState', () => {
+    const f = tmpFile('state.json', JSON.stringify({
+      cookies: [{ name: 'csrf', value: 'xyz', domain: 'example.com', path: '/' }],
+      origins: [],
+    }));
+    const out = loadCookiesFromFile(f, 'https://example.com');
+    assert.equal(out.length, 1);
+    assert.equal(out[0].name, 'csrf');
+  });
+
+  it('loads Netscape cookies.txt with tab-separated lines and comment', () => {
+    const netscape = [
+      '# Netscape HTTP Cookie File',
+      '# comment',
+      '.example.com\tTRUE\t/\tFALSE\t1765000000\tsid\tabc123',
+      '#HttpOnly_.example.com\tTRUE\t/\tTRUE\t0\tauth\ttoken-value',
+    ].join('\n');
+    const f = tmpFile('c.txt', netscape);
+    const out = loadCookiesFromFile(f, 'https://example.com');
+    assert.equal(out.length, 2);
+    const sid = out.find((c) => c.name === 'sid');
+    assert.equal(sid.value, 'abc123');
+    assert.equal(sid.domain, '.example.com');
+    assert.equal(sid.secure, false);
+    assert.equal(sid.expires, 1765000000);
+    const auth = out.find((c) => c.name === 'auth');
+    assert.equal(auth.httpOnly, true);
+    assert.equal(auth.secure, true);
+  });
+
+  it('throws on invalid JSON shape', () => {
+    const f = tmpFile('bad.json', '{"not":"array"}');
+    assert.throws(() => loadCookiesFromFile(f, 'https://example.com'));
+  });
+});
+
+describe('mergeCookies', () => {
+  it('parses CLI name=value strings into cookie objects', () => {
+    const out = mergeCookies(['session=abc'], [], 'https://example.com');
+    assert.equal(out.length, 1);
+    assert.equal(out[0].name, 'session');
+    assert.equal(out[0].value, 'abc');
+    assert.equal(out[0].url, 'https://example.com');
+  });
+
+  it('lets file cookies override CLI cookies with the same name+domain', () => {
+    const out = mergeCookies(
+      [{ name: 'session', value: 'cli', domain: '.example.com' }],
+      [{ name: 'session', value: 'file', domain: '.example.com' }],
+      'https://example.com',
+    );
+    assert.equal(out.length, 1);
+    assert.equal(out[0].value, 'file');
+  });
+
+  it('keeps cookies with different domains separately', () => {
+    const out = mergeCookies(
+      [],
+      [
+        { name: 'x', value: '1', domain: 'a.example.com' },
+        { name: 'x', value: '2', domain: 'b.example.com' },
+      ],
+      'https://example.com',
+    );
+    assert.equal(out.length, 2);
+  });
+
+  it('strips entries without a name', () => {
+    const out = mergeCookies([], [{ value: 'orphan' }], 'https://example.com');
+    assert.equal(out.length, 0);
+  });
+});