aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/scripts/design-system/test_mcp_tools.cjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Tools E2E Test
+ *
+ * Tests all 8 design system MCP tools with real data.
+ * Run from repo root: node squads/design/scripts/design-system/test_mcp_tools.cjs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+
+// ---------------------------------------------------------------------------
+// Inline loader — mirrors server.ts logic without requiring tsx/esm
+// ---------------------------------------------------------------------------
+
+function readJson(relPath) {
+  const full = path.join(ROOT, relPath);
+  return JSON.parse(fs.readFileSync(full, 'utf8'));
+}
+
+const components = readJson('workspace/domains/design-system/metadata/components.json');
+const registry = readJson('workspace/ui/registry.json');
+const tokenRegistry = readJson('workspace/domains/design-system/metadata/tokens/index.json');
+const guidelines = readJson('workspace/domains/design-system/metadata/guidelines/usage.json');
+
+// ---------------------------------------------------------------------------
+// Handler implementations (pure-JS mirrors of the TS handlers)
+// ---------------------------------------------------------------------------
+
+function listComponents() {
+  return components.components.map((c) => ({
+    id: c.id,
+    name: c.name,
+    status: c.status,
+    owner: c.agent_owner
+  }));
+}
+
+function getComponentById(id) {
+  return components.components.find((c) => c.id === id) || null;
+}
+
+function searchComponents(query) {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  return components.components.filter((c) => {
+    const haystack = [c.id, c.name, c.agent_owner, ...c.variants, ...c.tokens, ...c.a11y.wcag]
+      .join(' ')
+      .toLowerCase();
+    return haystack.includes(q);
+  });
+}
+
+function getA11yRequirements(id) {
+  const c = getComponentById(id);
+  return c ? c.a11y : null;
+}
+
+function getRegistryItem(name) {
+  return (registry.items || []).find((i) => i.name === name) || null;
+}
+
+function getTokensByCategory(category) {
+  return tokenRegistry.tokens.filter((t) => t.category === category.trim().toLowerCase());
+}
+
+function getTokensByTier(tier) {
+  return tokenRegistry.tokens.filter((t) => t.tier === tier.trim().toLowerCase());
+}
+
+function listTokens() {
+  return {
+    tokens: tokenRegistry.tokens.map((t) => ({
+      name: t.name,
+      cssVariable: t.cssVariable,
+      category: t.category,
+      tier: t.tier
+    })),
+    integrity: tokenRegistry.integrity
+  };
+}
+
+function getGuidelineForComponent(componentId) {
+  return guidelines.guidelines.find((g) => g.component === componentId) || null;
+}
+
+function suggestComponent(useCase) {
+  const normalized = useCase.trim().toLowerCase();
+  if (!normalized) return [];
+  const results = [];
+  for (const g of guidelines.guidelines) {
+    const reasons = [];
+    let score = 0;
+    for (const w of g.when_to_use) {
+      if (w.toLowerCase().includes(normalized)) {
+        score += 3;
+        reasons.push('when_to_use: ' + w);
+      }
+    }
+    const comp = components.components.find((c) => c.id === g.component);
+    if (comp) {
+      const name = comp.name.toLowerCase();
+      if (name.includes(normalized) || normalized.includes(name)) {
+        score += 2;
+        reasons.push('name match: ' + comp.name);
+      }
+    }
+    for (const wn of g.when_not_to_use) {
+      if (wn.toLowerCase().includes(normalized)) {
+        score -= 1;
+        reasons.push('when_not_to_use: ' + wn);
+      }
+    }
+    if (score > 0) results.push({ component: g.component, score, reasons });
+  }
+  return results.sort((a, b) => b.score - a.score);
+}
+
+// ---------------------------------------------------------------------------
+// Tool dispatch (same switch as server.ts)
+// ---------------------------------------------------------------------------
+
+function callTool(name, args) {
+  switch (name) {
+    case 'design_system.list_components':
+      return listComponents();
+    case 'design_system.get_component':
+      return getComponentById(String(args.id || ''));
+    case 'design_system.search_components':
+      return searchComponents(String(args.query || ''));
+    case 'design_system.get_a11y_requirements':
+      return getA11yRequirements(String(args.id || ''));
+    case 'design_system.get_registry_entry':
+      return getRegistryItem(String(args.name || ''));
+    case 'design_system.get_tokens': {
+      const category = args.category;
+      const tier = args.tier;
+      if (category && tier) {
+        return getTokensByCategory(category).filter((t) => t.tier === tier.trim().toLowerCase());
+      }
+      if (category) return getTokensByCategory(category);
+      if (tier) return getTokensByTier(tier);
+      return listTokens();
+    }
+    case 'design_system.get_guidelines':
+      return getGuidelineForComponent(String(args.component || ''));
+    case 'design_system.suggest_component':
+      return suggestComponent(String(args.use_case || ''));
+    default:
+      throw new Error('Unknown tool: ' + name);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test cases
+// ---------------------------------------------------------------------------
+
+const tests = [
+  {
+    tool: 'design_system.list_components',
+    args: {},
+    validate: (r) => Array.isArray(r) && r.length >= 5 && r[0].id === 'button'
+  },
+  {
+    tool: 'design_system.get_component',
+    args: { id: 'button' },
+    validate: (r) => r !== null && r.id === 'button' && Array.isArray(r.variants)
+  },
+  {
+    tool: 'design_system.search_components',
+    args: { query: 'brad-frost' },
+    validate: (r) => Array.isArray(r) && r.length > 0
+  },
+  {
+    tool: 'design_system.get_a11y_requirements',
+    args: { id: 'input' },
+    validate: (r) => r !== null && r.role === 'textbox' && r.wcag.length > 0
+  },
+  {
+    tool: 'design_system.get_registry_entry',
+    args: { name: 'button' },
+    validate: (r) => r !== null && r.name === 'button'
+  },
+  {
+    tool: 'design_system.get_tokens',
+    args: { category: 'color' },
+    validate: (r) => Array.isArray(r) && r.length >= 20 && r.every((t) => t.category === 'color')
+  },
+  {
+    tool: 'design_system.get_guidelines',
+    args: { component: 'button' },
+    validate: (r) => r !== null && Array.isArray(r.when_to_use) && r.when_to_use.length > 0
+  },
+  {
+    tool: 'design_system.suggest_component',
+    args: { use_case: 'form' },
+    validate: (r) => Array.isArray(r) && r.length > 0 && r[0].score > 0
+  }
+];
+
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+
+let passed = 0;
+let failed = 0;
+
+for (const t of tests) {
+  try {
+    const result = callTool(t.tool, t.args);
+    if (t.validate(result)) {
+      console.log(`PASS: ${t.tool}`);
+      passed++;
+    } else {
+      console.error(`FAIL: ${t.tool} — validation failed`);
+      console.error('  Result:', JSON.stringify(result).slice(0, 200));
+      failed++;
+    }
+  } catch (err) {
+    console.error(`FAIL: ${t.tool} — ${err.message}`);
+    failed++;
+  }
+}
+
+console.log(`\n${passed}/${passed + failed} tools passed`);
+
+if (failed > 0) {
+  process.exit(1);
+}

package/pro/squads/design/scripts/design-system/validate_components_metadata.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+const metadataPath = path.join(ROOT, 'workspace/domains/design-system/metadata/components.json');
+const squadRoot = path.join(ROOT, 'squads/design');
+
+function fail(message) {
+  console.error(`ERROR: ${message}`);
+  process.exit(1);
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    fail(`Unable to parse JSON at ${filePath}: ${error.message}`);
+  }
+}
+
+function validateRefs(component, field, folder) {
+  const refs = component[field] || [];
+  if (!Array.isArray(refs)) {
+    fail(`Component ${component.id}: ${field} must be an array`);
+  }
+
+  for (const ref of refs) {
+    const full = path.join(squadRoot, folder, `${ref}.md`);
+    const yaml = path.join(squadRoot, folder, `${ref}.yaml`);
+    const yml = path.join(squadRoot, folder, `${ref}.yml`);
+
+    if (!fs.existsSync(full) && !fs.existsSync(yaml) && !fs.existsSync(yml)) {
+      fail(`Component ${component.id}: invalid ${field} reference "${ref}"`);
+    }
+  }
+}
+
+function validateComponent(component) {
+  const required = ['id', 'name', 'agent_owner', 'registryKey', 'files', 'variants', 'tokens', 'a11y'];
+  for (const key of required) {
+    if (!(key in component)) {
+      fail(`Component missing required field: ${key}`);
+    }
+  }
+
+  if (!Array.isArray(component.files) || component.files.length === 0) {
+    fail(`Component ${component.id}: files must be a non-empty array`);
+  }
+
+  for (const file of component.files) {
+    if (!file.path) {
+      fail(`Component ${component.id}: every file needs a path`);
+    }
+  }
+
+  const a11yRequired = ['role', 'keyboard', 'aria', 'wcag'];
+  for (const key of a11yRequired) {
+    if (!(key in component.a11y)) {
+      fail(`Component ${component.id}: a11y.${key} is required`);
+    }
+  }
+
+  validateRefs(component, 'task_refs', 'tasks');
+  validateRefs(component, 'template_refs', 'templates');
+  validateRefs(component, 'workflow_refs', 'workflows');
+}
+
+function main() {
+  if (!fs.existsSync(metadataPath)) {
+    fail(`Missing metadata file: ${metadataPath}`);
+  }
+
+  const payload = readJson(metadataPath);
+  if (!payload.version) {
+    fail('Missing top-level version');
+  }
+
+  if (!Array.isArray(payload.components)) {
+    fail('components must be an array');
+  }
+
+  for (const component of payload.components) {
+    validateComponent(component);
+  }
+
+  const declaredCount = payload.integrity && payload.integrity.componentCount;
+  if (typeof declaredCount === 'number' && declaredCount !== payload.components.length) {
+    fail(`integrity.componentCount (${declaredCount}) does not match components.length (${payload.components.length})`);
+  }
+
+  console.log(`PASS: validated ${payload.components.length} components in ${path.relative(ROOT, metadataPath)}`);
+}
+
+main();

package/pro/squads/design/scripts/design-system/validate_curation.cjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Quality Gates Validation — Curation Pipeline Final Check
+ *
+ * Reads curation-report.json and validates all thresholds.
+ * Returns PASS, CONDITIONAL, or FAIL with detailed breakdown.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+const EXTRACTION_DIR = path.join(ROOT, 'workspace', 'domains', 'design-system', 'extraction');
+const CURATED_DIR = path.join(EXTRACTION_DIR, 'curated');
+const REPORT_PATH = path.join(CURATED_DIR, 'curation-report.json');
+const VALIDATION_PATH = path.join(CURATED_DIR, 'validation-result.json');
+const STYLES_PATH = path.join(EXTRACTION_DIR, 'figma-styles.json');
+const COMPONENTS_PATH = path.join(CURATED_DIR, 'curated-components.json');
+
+// ── Gate Definitions ───────────────────────────────────────────────────────
+
+const GATES = [
+  {
+    id: 'G1',
+    name: 'Color Reduction',
+    check: (r) => {
+      const pct = parseFloat(r.scores.colors.reduction);
+      if (pct >= 85) return { status: 'PASS', value: r.scores.colors.reduction };
+      if (pct >= 70) return { status: 'CONDITIONAL', value: r.scores.colors.reduction };
+      return { status: 'FAIL', value: r.scores.colors.reduction };
+    },
+    target: '>= 85%',
+  },
+  {
+    id: 'G2',
+    name: 'WCAG AA Contrast',
+    check: (r) => {
+      const pct = parseFloat(r.scores.colors.wcag_aa_pass);
+      if (pct >= 100) return { status: 'PASS', value: r.scores.colors.wcag_aa_pass };
+      if (pct >= 90) return { status: 'CONDITIONAL', value: r.scores.colors.wcag_aa_pass };
+      return { status: 'FAIL', value: r.scores.colors.wcag_aa_pass };
+    },
+    target: '100%',
+  },
+  {
+    id: 'G3',
+    name: 'Spacing Reduction',
+    check: (r) => {
+      const pct = parseFloat(r.scores.spacing.reduction);
+      if (pct >= 60) return { status: 'PASS', value: r.scores.spacing.reduction };
+      if (pct >= 40) return { status: 'CONDITIONAL', value: r.scores.spacing.reduction };
+      return { status: 'FAIL', value: r.scores.spacing.reduction };
+    },
+    target: '>= 60%',
+  },
+  {
+    id: 'G4',
+    name: 'Spacing Coverage',
+    check: (r) => {
+      const pct = parseFloat(r.scores.spacing.coverage);
+      if (pct >= 95) return { status: 'PASS', value: r.scores.spacing.coverage };
+      if (pct >= 85) return { status: 'CONDITIONAL', value: r.scores.spacing.coverage };
+      return { status: 'FAIL', value: r.scores.spacing.coverage };
+    },
+    target: '>= 95%',
+  },
+  {
+    id: 'G5',
+    name: 'Typography Reduction',
+    check: (r) => {
+      const pct = parseFloat(r.scores.typography.reduction);
+      if (pct >= 50) return { status: 'PASS', value: r.scores.typography.reduction };
+      if (pct >= 35) return { status: 'CONDITIONAL', value: r.scores.typography.reduction };
+      return { status: 'FAIL', value: r.scores.typography.reduction };
+    },
+    target: '>= 50%',
+  },
+  {
+    id: 'G6',
+    name: 'Font Families',
+    check: (r) => {
+      const count = r.scores.typography.after.families;
+      if (count <= 3) return { status: 'PASS', value: `${count} families` };
+      if (count === 4) return { status: 'CONDITIONAL', value: `${count} families` };
+      return { status: 'FAIL', value: `${count} families` };
+    },
+    target: '<= 3',
+  },
+  {
+    id: 'G7',
+    name: 'Shadow Reduction',
+    check: (r) => {
+      const pct = parseFloat(r.scores.shadows.reduction);
+      if (pct >= 70) return { status: 'PASS', value: r.scores.shadows.reduction };
+      if (pct >= 50) return { status: 'CONDITIONAL', value: r.scores.shadows.reduction };
+      return { status: 'FAIL', value: r.scores.shadows.reduction };
+    },
+    target: '>= 70%',
+  },
+  {
+    id: 'G8',
+    name: 'Radius Reduction',
+    check: (r) => {
+      const pct = parseFloat(r.scores.radius.reduction);
+      if (pct >= 60) return { status: 'PASS', value: r.scores.radius.reduction };
+      if (pct >= 40) return { status: 'CONDITIONAL', value: r.scores.radius.reduction };
+      return { status: 'FAIL', value: r.scores.radius.reduction };
+    },
+    target: '>= 60%',
+  },
+  {
+    id: 'G9',
+    name: 'Overall Reduction',
+    check: (r) => {
+      const pct = parseFloat(r.scores.overall.reduction);
+      if (pct >= 80) return { status: 'PASS', value: r.scores.overall.reduction };
+      if (pct >= 60) return { status: 'CONDITIONAL', value: r.scores.overall.reduction };
+      return { status: 'FAIL', value: r.scores.overall.reduction };
+    },
+    target: '>= 80%',
+  },
+  {
+    id: 'G10',
+    name: 'Component Naming Coverage',
+    check: () => {
+      try {
+        const comps = JSON.parse(fs.readFileSync(COMPONENTS_PATH, 'utf8'));
+        const all = comps.components || [];
+        const named = all.filter((c) => c.name && c.name.trim() !== '');
+        const pct = all.length > 0 ? (named.length / all.length) * 100 : 0;
+        if (pct >= 90) return { status: 'PASS', value: `${Math.round(pct)}% (${named.length}/${all.length})` };
+        if (pct >= 70) return { status: 'CONDITIONAL', value: `${Math.round(pct)}% (${named.length}/${all.length})` };
+        return { status: 'FAIL', value: `${Math.round(pct)}% (${named.length}/${all.length})` };
+      } catch (_) {
+        return { status: 'CONDITIONAL', value: 'curated-components.json not found' };
+      }
+    },
+    target: '>= 90%',
+  },
+  {
+    id: 'G11',
+    name: 'Figma Styles Coverage',
+    check: () => {
+      try {
+        const styles = JSON.parse(fs.readFileSync(STYLES_PATH, 'utf8'));
+        const count = styles.length;
+        if (count > 0) return { status: 'PASS', value: `${count} styles fetched` };
+        return { status: 'CONDITIONAL', value: '0 styles (endpoint may not be available)' };
+      } catch (_) {
+        return { status: 'CONDITIONAL', value: 'figma-styles.json not found' };
+      }
+    },
+    target: '> 0 styles',
+  },
+];
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  console.log('=== QUALITY GATES VALIDATION ===\n');
+
+  const report = JSON.parse(fs.readFileSync(REPORT_PATH, 'utf8'));
+
+  const results = [];
+  let passCount = 0;
+  let conditionalCount = 0;
+  let failCount = 0;
+
+  for (const gate of GATES) {
+    const result = gate.check(report);
+    results.push({
+      id: gate.id,
+      name: gate.name,
+      target: gate.target,
+      value: result.value,
+      status: result.status,
+    });
+
+    const icon = result.status === 'PASS' ? '✓' : result.status === 'CONDITIONAL' ? '⚠' : '✗';
+    console.log(`  [${gate.id}] ${icon} ${gate.name}: ${result.value} (target: ${gate.target}) → ${result.status}`);
+
+    if (result.status === 'PASS') passCount++;
+    else if (result.status === 'CONDITIONAL') conditionalCount++;
+    else failCount++;
+  }
+
+  // Overall verdict
+  let verdict;
+  if (failCount > 0) {
+    verdict = 'FAIL';
+  } else if (conditionalCount > 0) {
+    verdict = 'CONDITIONAL';
+  } else {
+    verdict = 'PASS';
+  }
+
+  const validation = {
+    timestamp: new Date().toISOString(),
+    source: 'curation-report.json',
+    verdict,
+    summary: {
+      total: GATES.length,
+      pass: passCount,
+      conditional: conditionalCount,
+      fail: failCount,
+    },
+    gates: results,
+  };
+
+  fs.writeFileSync(VALIDATION_PATH, JSON.stringify(validation, null, 2));
+
+  console.log(`\n--- VERDICT ---`);
+  console.log(`  PASS: ${passCount}/${GATES.length}`);
+  console.log(`  CONDITIONAL: ${conditionalCount}/${GATES.length}`);
+  console.log(`  FAIL: ${failCount}/${GATES.length}`);
+  console.log(`\n  Final Verdict: ${verdict}`);
+  console.log(`\nOutput: ${VALIDATION_PATH}`);
+  console.log('=== DONE ===');
+
+  // Exit with code based on verdict
+  if (verdict === 'FAIL') process.exit(1);
+  if (verdict === 'CONDITIONAL') process.exit(0);
+  process.exit(0);
+}
+
+main();

package/pro/squads/design/scripts/design-system/validate_design_manifest_drift.cjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const process = require('process');
+const {
+  buildGeneratedConfig,
+  getCanonicalProjection,
+  getDesignPaths,
+  readYaml,
+  stableJson
+} = require('./design_manifest_lib.cjs');
+
+function fail(message) {
+  console.error(`ERROR: ${message}`);
+  process.exit(1);
+}
+
+function validateSquadReferences(rootDir, squad) {
+  const base = path.join(rootDir, 'squads/design');
+  const checks = [
+    ['agents', '.md'],
+    ['tasks', '.md'],
+    ['checklists', '.md'],
+    ['templates', null],
+    ['workflows', null]
+  ];
+
+  for (const [section, extension] of checks) {
+    const items = squad[section] || [];
+    for (const item of items) {
+      const file = item.file;
+      if (!file) {
+        fail(`Missing file field in squad.${section} item: ${item.id || 'unknown-id'}`);
+      }
+
+      const fullPath = path.join(base, file);
+      if (!fs.existsSync(fullPath)) {
+        fail(`Broken reference in squad.${section}: ${file}`);
+      }
+
+      if (extension && !file.endsWith(extension)) {
+        fail(`Invalid extension in squad.${section}: ${file} (expected ${extension})`);
+      }
+    }
+  }
+}
+
+function main() {
+  const rootDir = process.cwd();
+  const { squadPath, configPath } = getDesignPaths(rootDir);
+
+  const squad = readYaml(squadPath);
+  const config = readYaml(configPath);
+  const expected = buildGeneratedConfig(squad, config);
+
+  validateSquadReferences(rootDir, squad);
+
+  const actualCanonical = getCanonicalProjection(config);
+  const expectedCanonical = getCanonicalProjection(expected);
+
+  const actualJson = stableJson(actualCanonical);
+  const expectedJson = stableJson(expectedCanonical);
+
+  if (actualJson !== expectedJson) {
+    fail('Design manifest drift detected. Run: npm run design:manifest:sync');
+  }
+
+  console.log('PASS: design manifest is synchronized with squad.yaml');
+}
+
+main();

package/pro/squads/design/scripts/design-system/validate_mcp_skeleton.cjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+const requiredFiles = [
+  'workspace/domains/design-system/mcp/server.ts',
+  'workspace/domains/design-system/mcp/types.ts',
+  'workspace/domains/design-system/mcp/config.json',
+  'workspace/domains/design-system/mcp/handlers/components.ts',
+  'workspace/domains/design-system/mcp/handlers/registry.ts',
+  'workspace/domains/design-system/mcp/handlers/tokens.ts',
+  'workspace/domains/design-system/mcp/handlers/guidelines.ts'
+];
+
+function fail(message) {
+  console.error(`ERROR: ${message}`);
+  process.exit(1);
+}
+
+function main() {
+  for (const rel of requiredFiles) {
+    const full = path.join(ROOT, rel);
+    if (!fs.existsSync(full)) {
+      fail(`Missing required MCP file: ${rel}`);
+    }
+
+    const content = fs.readFileSync(full, 'utf8');
+    if (!content.trim()) {
+      fail(`MCP file is empty: ${rel}`);
+    }
+  }
+
+  console.log('PASS: MCP skeleton files are present');
+}
+
+main();