@salesforce/afv-skills 1.14.0 → 1.15.0

package/skills/applying-slds/scripts/search-blueprints.cjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * Search SLDS blueprint metadata.
+ *
+ * Usage:
+ *   node search-blueprints.js --search "dialog"
+ *   node search-blueprints.js --category "Overlay"
+ *   node search-blueprints.js --name "modals"
+ *   node search-blueprints.js                      # list all blueprints
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BLUEPRINTS_DIR = path.join(__dirname, '..', 'metadata', 'blueprints', 'components');
+
+function loadBlueprints() {
+  const blueprints = [];
+  if (!fs.existsSync(BLUEPRINTS_DIR)) {
+    console.error(`Blueprints directory not found: ${BLUEPRINTS_DIR}`);
+    process.exit(1);
+  }
+
+  const files = fs.readdirSync(BLUEPRINTS_DIR).filter(f => f.endsWith('.yaml'));
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(BLUEPRINTS_DIR, file), 'utf8');
+    const nameMatch = content.match(/^name:\s*"?([^"\n]+)"?/m);
+    const descMatch = content.match(/^description:\s*"?([^"\n]+)"?/m);
+    const catMatch = content.match(/^category:\s*"?([^"\n]+)"?/m);
+    const rootMatch = content.match(/root:\s*"?([^"\n]+)"?/m);
+
+    blueprints.push({
+      file: file.replace('.yaml', ''),
+      name: nameMatch ? nameMatch[1].trim() : file.replace('.yaml', ''),
+      description: descMatch ? descMatch[1].trim() : '',
+      category: catMatch ? catMatch[1].trim() : 'Unknown',
+      rootClass: rootMatch ? rootMatch[1].trim() : '',
+    });
+  }
+
+  return blueprints.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  const flags = {};
+  for (let i = 0; i < args.length; i += 2) {
+    if (args[i].startsWith('--')) {
+      flags[args[i].slice(2)] = args[i + 1] || '';
+    }
+  }
+
+  const blueprints = loadBlueprints();
+
+  if (flags.name) {
+    const needle = flags.name.toLowerCase();
+    const bp = blueprints.find(b =>
+      b.file.toLowerCase() === needle || b.name.toLowerCase() === needle
+    );
+    if (!bp) {
+      console.log(`Blueprint "${flags.name}" not found.`);
+      console.log(`\nAvailable: ${blueprints.map(b => b.file).join(', ')}`);
+      return;
+    }
+    console.log(`\n=== ${bp.name} ===`);
+    console.log(`Category: ${bp.category}`);
+    console.log(`Root class: ${bp.rootClass}`);
+    console.log(`Description: ${bp.description}`);
+    console.log(`\nFull YAML: metadata/blueprints/components/${bp.file}.yaml`);
+    console.log('\nRead the full YAML file for classes, modifiers, states, accessibility, and example HTML.');
+    return;
+  }
+
+  let results = blueprints;
+
+  if (flags.category) {
+    const cat = flags.category.toLowerCase();
+    results = results.filter(b => b.category.toLowerCase() === cat);
+  }
+
+  if (flags.search) {
+    const term = flags.search.toLowerCase();
+    results = results.filter(b =>
+      b.name.toLowerCase().includes(term) ||
+      b.description.toLowerCase().includes(term) ||
+      b.file.toLowerCase().includes(term)
+    );
+  }
+
+  if (results.length === 0) {
+    console.log('No blueprints found matching your criteria.');
+    const categories = [...new Set(blueprints.map(b => b.category))].sort();
+    console.log(`\nAvailable categories: ${categories.join(', ')}`);
+    return;
+  }
+
+  console.log(`\nFound ${results.length} blueprint(s):\n`);
+
+  const byCategory = {};
+  for (const bp of results) {
+    if (!byCategory[bp.category]) byCategory[bp.category] = [];
+    byCategory[bp.category].push(bp);
+  }
+
+  for (const [cat, bps] of Object.entries(byCategory).sort()) {
+    console.log(`── ${cat} ──`);
+    for (const bp of bps) {
+      console.log(`  ${bp.name.padEnd(30)} ${bp.rootClass.padEnd(25)} ${bp.description.slice(0, 60)}`);
+    }
+    console.log();
+  }
+
+  console.log('Use --name "<blueprint>" to get full details.');
+}
+
+run();

package/skills/applying-slds/scripts/search-hooks.cjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+/**
+ * Search SLDS styling hooks metadata.
+ *
+ * Usage:
+ *   node search-hooks.js --prefix "--slds-g-color-accent-"
+ *   node search-hooks.js --category "color"
+ *   node search-hooks.js --property "background-color"
+ *   node search-hooks.js --value "#0176d3"
+ *   node search-hooks.js --search "accent"
+ *   node search-hooks.js                            # show category summary
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const INDEX_PATH = path.join(__dirname, '..', 'metadata', 'hooks-index.json');
+
+function loadHooks() {
+  if (!fs.existsSync(INDEX_PATH)) {
+    console.error(`Hooks index not found: ${INDEX_PATH}`);
+    process.exit(1);
+  }
+  const data = JSON.parse(fs.readFileSync(INDEX_PATH, 'utf8'));
+  return { hooks: data.hooks || [], categories: data.categories || {} };
+}
+
+function normalizeValue(v) {
+  return (v || '').toLowerCase().replace(/\s+/g, '');
+}
+
+function matchesValue(hook, searchValue) {
+  const needle = normalizeValue(searchValue);
+
+  const check = (v) => {
+    if (!v) return false;
+    const n = normalizeValue(v);
+    return n === needle || n.includes(needle);
+  };
+
+  if (hook.value && check(hook.value)) return true;
+  if (hook.value_dark && check(hook.value_dark)) return true;
+  if (hook.rawValues) {
+    if (check(hook.rawValues.slds) || check(hook.rawValues.cosmos)) return true;
+  }
+  if (hook.values) {
+    if (check(hook.values.slds) || check(hook.values.cosmos)) return true;
+  }
+  return false;
+}
+
+function matchesProperty(hook, targetProps) {
+  const appliesTo = hook.properties?.['applies-to'] || hook.properties || [];
+  if (!Array.isArray(appliesTo) || appliesTo.length === 0) return false;
+  const targets = targetProps.map(p => p.toLowerCase());
+  return targets.some(t => appliesTo.some(hp => hp.toLowerCase().includes(t) || t.includes(hp.toLowerCase())));
+}
+
+function formatHook(hook) {
+  const parts = [`  ${hook.token}`];
+  if (hook.category) parts.push(`    category: ${hook.category}`);
+  if (hook.value) parts.push(`    value: ${hook.value}`);
+  if (hook.value_dark) parts.push(`    value_dark: ${hook.value_dark}`);
+  if (hook.rawValues?.slds) parts.push(`    value(slds): ${hook.rawValues.slds}`);
+  if (hook.rawValues?.cosmos) parts.push(`    value(cosmos): ${hook.rawValues.cosmos}`);
+  const props = hook.properties?.['applies-to'] || [];
+  if (props.length) parts.push(`    applies-to: ${props.join(', ')}`);
+  return parts.join('\n');
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--') && i + 1 < args.length) {
+      flags[args[i].slice(2)] = args[i + 1];
+      i++;
+    }
+  }
+
+  const { hooks, categories } = loadHooks();
+
+  if (Object.keys(flags).length === 0) {
+    console.log(`\nSLDS Styling Hooks: ${hooks.length} total\n`);
+    console.log('Categories:');
+    for (const [cat, count] of Object.entries(categories).sort()) {
+      console.log(`  ${cat.padEnd(15)} ${count} hooks`);
+    }
+    console.log('\nUsage:');
+    console.log('  --prefix   Match by token prefix (e.g., "--slds-g-color-accent-")');
+    console.log('  --category Filter by category (e.g., "color", "spacing", "font")');
+    console.log('  --property Filter by CSS property (e.g., "background-color")');
+    console.log('  --value    Find hook by CSS value (e.g., "#0176d3")');
+    console.log('  --search   Search token names (e.g., "accent")');
+    return;
+  }
+
+  let results = hooks;
+
+  if (flags.prefix) {
+    const prefix = flags.prefix.toLowerCase();
+    results = results.filter(h => h.token.toLowerCase().startsWith(prefix));
+  }
+
+  if (flags.search) {
+    const term = flags.search.toLowerCase();
+    results = results.filter(h => h.token.toLowerCase().includes(term));
+  }
+
+  if (flags.category) {
+    const cat = flags.category.toLowerCase();
+    results = results.filter(h => (h.category || '').toLowerCase() === cat);
+  }
+
+  if (flags.property) {
+    results = results.filter(h => matchesProperty(h, [flags.property]));
+  }
+
+  if (flags.value) {
+    results = results.filter(h => matchesValue(h, flags.value));
+  }
+
+  if (results.length === 0) {
+    console.log('No hooks found matching your criteria.');
+    return;
+  }
+
+  console.log(`\nFound ${results.length} hook(s):\n`);
+  for (const hook of results.slice(0, 50)) {
+    console.log(formatHook(hook));
+    console.log();
+  }
+  if (results.length > 50) {
+    console.log(`... and ${results.length - 50} more. Narrow your search.`);
+  }
+}
+
+run();

package/skills/applying-slds/scripts/search-icons.cjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * Search SLDS icons with synonym matching and relevance scoring.
+ *
+ * Usage:
+ *   node search-icons.js --query "save button"
+ *   node search-icons.js --query "user" --category "standard"
+ *   node search-icons.js --query "delete" --limit 20
+ *   node search-icons.js --list-categories
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ICONS_PATH = path.join(__dirname, '..', 'metadata', 'icon-metadata.json');
+
+function loadIcons() {
+  if (!fs.existsSync(ICONS_PATH)) {
+    console.error(`Icon metadata not found: ${ICONS_PATH}`);
+    process.exit(1);
+  }
+  const data = JSON.parse(fs.readFileSync(ICONS_PATH, 'utf8'));
+  const icons = [];
+  for (const [key, icon] of Object.entries(data.icons || {})) {
+    icons.push({
+      symbol: key,
+      displayName: icon.displayName || key,
+      category: icon.category || 'unknown',
+      description: icon.description || '',
+      synonyms: icon.synonyms || [],
+      fullName: `${icon.category}:${key}`,
+    });
+  }
+  return icons;
+}
+
+function tokenize(query) {
+  return query.toLowerCase().split(/[\s_-]+/).filter(t => t.length > 0);
+}
+
+function scoreIcon(icon, query, tokens) {
+  let score = 0;
+  let matchType = 'partial';
+  const matchedTerms = [];
+  const sym = icon.symbol.toLowerCase();
+  const syns = icon.synonyms.map(s => s.toLowerCase());
+  const desc = icon.description.toLowerCase();
+
+  if (sym === query) {
+    score = 100; matchType = 'exact'; matchedTerms.push(icon.symbol);
+  } else if (syns.includes(query)) {
+    score = 95; matchType = 'synonym'; matchedTerms.push(...icon.synonyms.filter(s => s.toLowerCase() === query));
+  } else if (sym.startsWith(query)) {
+    score = 85; matchType = 'partial'; matchedTerms.push(icon.symbol);
+  } else if (syns.some(s => s.startsWith(query))) {
+    score = 80; matchType = 'synonym'; matchedTerms.push(...icon.synonyms.filter(s => s.toLowerCase().startsWith(query)));
+  }
+
+  if (score < 80 && sym.includes(query)) {
+    score = Math.max(score, 70); matchedTerms.push(icon.symbol);
+  }
+  const partialSyns = icon.synonyms.filter(s => s.toLowerCase().includes(query));
+  if (partialSyns.length > 0) {
+    score = Math.max(score, 65); matchedTerms.push(...partialSyns);
+    if (matchType === 'partial' && score === 65) matchType = 'synonym';
+  }
+  if (desc.includes(query)) {
+    score = Math.max(score, 55);
+    if (matchType === 'partial' && score === 55) matchType = 'contextual';
+  }
+
+  if (tokens.length > 1) {
+    let tokenScore = 0;
+    let matched = 0;
+    for (const token of tokens) {
+      let hit = false;
+      if (sym.includes(token)) { tokenScore += 30; hit = true; matchedTerms.push(icon.symbol); }
+      const synHits = icon.synonyms.filter(s => s.toLowerCase().includes(token));
+      if (synHits.length) { tokenScore += 25; hit = true; matchedTerms.push(...synHits); }
+      if (desc.includes(token)) { tokenScore += 10; hit = true; }
+      if (hit) matched++;
+    }
+    if (matched > 1) tokenScore *= 1.2;
+    if (tokenScore > score) { score = tokenScore; matchType = matched > 0 ? 'synonym' : 'contextual'; }
+  }
+
+  return { icon, score: Math.round(score), matchType, matchedTerms: [...new Set(matchedTerms)] };
+}
+
+function usageExample(fullName, category) {
+  const altText = 'TODO: describe what this icon communicates';
+  switch (category) {
+    case 'action':
+      return `<lightning-button-icon icon-name="${fullName}" alternative-text="${altText}" title="TODO: tooltip"></lightning-button-icon>`;
+    case 'utility':
+      return `<lightning-icon icon-name="${fullName}" alternative-text="${altText}" size="small"></lightning-icon>`;
+    case 'standard':
+    case 'custom':
+      return `<lightning-icon icon-name="${fullName}" alternative-text="${altText}" size="medium"></lightning-icon>`;
+    case 'doctype':
+      return `<lightning-icon icon-name="${fullName}" alternative-text="${altText}" size="small"></lightning-icon>`;
+    default:
+      return `<lightning-icon icon-name="${fullName}" alternative-text="${altText}"></lightning-icon>`;
+  }
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--list-categories') { flags.listCategories = true; continue; }
+    if (args[i].startsWith('--') && i + 1 < args.length) {
+      flags[args[i].slice(2)] = args[i + 1]; i++;
+    }
+  }
+
+  const icons = loadIcons();
+
+  if (flags.listCategories) {
+    const cats = {};
+    for (const icon of icons) {
+      cats[icon.category] = (cats[icon.category] || 0) + 1;
+    }
+    console.log('\nIcon categories:');
+    for (const [cat, count] of Object.entries(cats).sort()) {
+      console.log(`  ${cat.padEnd(12)} ${count} icons`);
+    }
+    return;
+  }
+
+  if (!flags.query) {
+    console.log('Usage: node search-icons.js --query "search term" [--category action|utility|standard|custom|doctype] [--limit N]');
+    return;
+  }
+
+  const query = flags.query.toLowerCase().trim();
+  const limit = parseInt(flags.limit) || 10;
+  const tokens = tokenize(query);
+
+  let searchable = icons;
+  if (flags.category) {
+    const cat = flags.category.toLowerCase();
+    searchable = searchable.filter(i => i.category === cat);
+  }
+
+  const results = searchable
+    .map(icon => scoreIcon(icon, query, tokens))
+    .filter(r => r.score > 0)
+    .sort((a, b) => b.score - a.score || a.icon.symbol.localeCompare(b.icon.symbol))
+    .slice(0, limit);
+
+  if (results.length === 0) {
+    console.log(`No icons found for "${flags.query}".`);
+    const suggestions = icons
+      .filter(i => i.symbol.startsWith(query.slice(0, 3)))
+      .slice(0, 5)
+      .map(i => i.symbol);
+    if (suggestions.length) console.log(`Try: ${suggestions.join(', ')}`);
+    return;
+  }
+
+  console.log(`\nFound ${results.length} icon(s) for "${flags.query}":\n`);
+  for (const r of results) {
+    const { icon, score, matchType, matchedTerms } = r;
+    console.log(`  ${icon.fullName.padEnd(35)} score: ${score}  match: ${matchType}`);
+    if (matchedTerms.length) console.log(`    matched: ${matchedTerms.join(', ')}`);
+    console.log(`    ${icon.description.slice(0, 80)}`);
+    console.log(`    LWC: ${usageExample(icon.fullName, icon.category)}`);
+    console.log();
+  }
+}
+
+run();

package/skills/applying-slds/scripts/search-utilities.cjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+/**
+ * Search SLDS utility classes metadata.
+ *
+ * Usage:
+ *   node search-utilities.js --category "all"         # list all categories
+ *   node search-utilities.js --category "grid"         # browse category
+ *   node search-utilities.js --search "slds-m-bottom"  # search by class name
+ *   node search-utilities.js --pattern "slds-p-*"      # wildcard pattern
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const INDEX_PATH = path.join(__dirname, '..', 'metadata', 'utilities-index.json');
+const GUIDANCE_DIR = path.join(__dirname, '..', 'guidance', 'utilities');
+
+function loadUtilities() {
+  if (!fs.existsSync(INDEX_PATH)) {
+    console.error(`Utilities index not found: ${INDEX_PATH}`);
+    process.exit(1);
+  }
+  const data = JSON.parse(fs.readFileSync(INDEX_PATH, 'utf8'));
+  return {
+    utilities: data.utilities || [],
+    categories: data.categories || {},
+    total: data.total_utilities || 0,
+  };
+}
+
+function formatUtility(u) {
+  const parts = [`  ${u.class}`];
+  if (u.category) parts.push(`    category: ${u.category}`);
+  if (u.description) parts.push(`    description: ${u.description}`);
+  if (u.css) {
+    const rules = Object.entries(u.css).map(([prop, val]) => `${prop}: ${val}`).join('; ');
+    parts.push(`    css: ${rules}`);
+  }
+  if (u.css_rules && u.css_rules.length) {
+    parts.push(`    css: ${u.css_rules.join('; ')}`);
+  }
+  return parts.join('\n');
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--') && i + 1 < args.length) {
+      flags[args[i].slice(2)] = args[i + 1]; i++;
+    }
+  }
+
+  const { utilities, categories, total } = loadUtilities();
+
+  if (Object.keys(flags).length === 0) {
+    console.log(`\nSLDS Utility Classes: ${total} total across ${Object.keys(categories).length} categories\n`);
+    console.log('Usage:');
+    console.log('  --category "all"        List all categories with counts');
+    console.log('  --category "grid"       Show utilities in a specific category');
+    console.log('  --search "slds-m-"      Search by class name or description');
+    console.log('  --pattern "slds-p-*"    Wildcard pattern match');
+    return;
+  }
+
+  if (flags.category) {
+    if (flags.category === 'all') {
+      console.log(`\nAll utility categories (${Object.keys(categories).length}):\n`);
+      for (const [cat, count] of Object.entries(categories).sort()) {
+        const guidePath = path.join(GUIDANCE_DIR, `${cat}.md`);
+        const hasGuide = fs.existsSync(guidePath) ? ' (has guidance)' : '';
+        console.log(`  ${cat.padEnd(20)} ${String(count).padStart(4)} classes${hasGuide}`);
+      }
+      console.log(`\nTotal: ${total} utility classes`);
+      console.log('\nUse --category "<name>" to browse a specific category.');
+      return;
+    }
+
+    const catKey = flags.category.toLowerCase().replace(/\s+/g, '-');
+    const catUtilities = utilities.filter(u => {
+      const uCat = (u.category_key || u.category || '').toLowerCase().replace(/\s+/g, '-');
+      return uCat === catKey;
+    });
+
+    if (catUtilities.length === 0) {
+      console.log(`Category "${flags.category}" not found or empty.`);
+      console.log(`Available: ${Object.keys(categories).join(', ')}`);
+      return;
+    }
+
+    console.log(`\n── ${flags.category} (${catUtilities.length} classes) ──\n`);
+    for (const u of catUtilities.slice(0, 30)) {
+      console.log(formatUtility(u));
+      console.log();
+    }
+    if (catUtilities.length > 30) {
+      console.log(`... and ${catUtilities.length - 30} more. Use --search to narrow.`);
+    }
+
+    const guidePath = path.join(GUIDANCE_DIR, `${catKey}.md`);
+    if (fs.existsSync(guidePath)) {
+      console.log(`\nDetailed guidance: guidance/utilities/${catKey}.md`);
+    }
+    return;
+  }
+
+  if (flags.pattern) {
+    const regex = new RegExp('^' + flags.pattern.toLowerCase().replace(/\*/g, '.*') + '$');
+    const matches = utilities.filter(u => regex.test((u.class || '').toLowerCase()));
+
+    if (matches.length === 0) {
+      console.log(`No utilities matching pattern "${flags.pattern}".`);
+      return;
+    }
+
+    console.log(`\nFound ${matches.length} utility(ies) matching "${flags.pattern}":\n`);
+    for (const u of matches.slice(0, 50)) {
+      console.log(formatUtility(u));
+      console.log();
+    }
+    if (matches.length > 50) {
+      console.log(`... and ${matches.length - 50} more.`);
+    }
+    return;
+  }
+
+  if (flags.search) {
+    const term = flags.search.toLowerCase();
+
+    const exact = utilities.find(u => (u.class || '').toLowerCase() === term);
+    if (exact) {
+      console.log(`\nExact match:\n`);
+      console.log(formatUtility(exact));
+      return;
+    }
+
+    const matches = utilities.filter(u =>
+      (u.class || '').toLowerCase().includes(term) ||
+      (u.description || '').toLowerCase().includes(term)
+    );
+
+    if (matches.length === 0) {
+      console.log(`No utilities found for "${flags.search}".`);
+      console.log('Use --category "all" to browse available categories.');
+      return;
+    }
+
+    console.log(`\nFound ${matches.length} utility(ies) for "${flags.search}":\n`);
+    for (const u of matches.slice(0, 30)) {
+      console.log(formatUtility(u));
+      console.log();
+    }
+    if (matches.length > 30) {
+      console.log(`... and ${matches.length - 30} more.`);
+    }
+    return;
+  }
+}
+
+run();