@urbicon-ui/mcp-server 6.1.4

package/src/data/component-loader.ts

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import { getComponentLlmPath } from '../utils/paths.js';
+
+const SEARCH_GROUPS = [
+  'blocks/primitives',
+  'blocks/components',
+  'docs/components',
+  'table',
+  'auth/components'
+];
+
+export async function loadComponentLlmTxt(slug: string): Promise<string | null> {
+  for (const group of SEARCH_GROUPS) {
+    const path = getComponentLlmPath(group, slug);
+    try {
+      return await readFile(path, 'utf-8');
+    } catch (err) {
+      // Read-tolerant: "not in this group" (file absent) → try the next group.
+      // Anything else (permission, corrupt mount, …) is a real fault we must
+      // not mask as "component not found" — surface it.
+      if ((err as { code?: string }).code === 'ENOENT') continue;
+      throw err;
+    }
+  }
+  // Absent in every group: a genuine "unknown component". The caller turns this
+  // null into a clear not-found message rather than a thrown error.
+  return null;
+}
+
+export type LlmTxtSection = 'overview' | 'examples' | 'variants' | 'api' | 'slots';
+
+const SECTION_HEADING_MAP: Record<string, LlmTxtSection> = {
+  examples: 'examples',
+  variants: 'variants',
+  api: 'api',
+  'slots (slotclasses keys)': 'slots'
+};
+
+export function extractSection(content: string, section: LlmTxtSection): string | null {
+  if (section === 'overview') {
+    const firstH3 = content.indexOf('\n### ');
+    if (firstH3 === -1) return content.trim();
+    return content.slice(0, firstH3).trim();
+  }
+
+  const lines = content.split('\n');
+  let capturing = false;
+  const result: string[] = [];
+
+  for (const line of lines) {
+    if (line.startsWith('### ')) {
+      const heading = line.slice(4).trim().toLowerCase();
+      const mapped = SECTION_HEADING_MAP[heading];
+      if (mapped === section) {
+        capturing = true;
+        result.push(line);
+        continue;
+      } else if (capturing) {
+        break;
+      }
+    }
+    if (capturing) {
+      result.push(line);
+    }
+  }
+
+  return result.length > 0 ? result.join('\n').trim() : null;
+}

package/src/data/design-system-loader.test.ts

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { getDesignSystemDir } from '../utils/paths.js';
+import {
+  extractPrincipleSection,
+  getPatternByName,
+  loadPatterns,
+  loadPrinciples
+} from './design-system-loader.js';
+
+const dsDir = getDesignSystemDir();
+const principlesAvailable = existsSync(resolve(dsDir, 'principles.md'));
+const patternsAvailable = existsSync(resolve(dsDir, 'patterns'));
+
+describe.skipIf(!principlesAvailable)('loadPrinciples', () => {
+  it('loads principles as a non-empty string', async () => {
+    const principles = await loadPrinciples();
+    expect(principles.length).toBeGreaterThan(0);
+  });
+
+  it('contains expected topic headings', async () => {
+    const principles = await loadPrinciples();
+    expect(principles).toContain('## Visual Hierarchy');
+    expect(principles).toContain('## Theming');
+    expect(principles).toContain('## Component Selection');
+  });
+});
+
+describe.skipIf(!principlesAvailable)('extractPrincipleSection', () => {
+  it('extracts a specific topic section', async () => {
+    const principles = await loadPrinciples();
+    const section = extractPrincipleSection(principles, 'theming');
+    expect(section).not.toBeNull();
+    expect(section).toContain('## Theming');
+    expect(section).not.toContain('## Visual Hierarchy');
+  });
+
+  it('returns null for unknown topics', async () => {
+    const principles = await loadPrinciples();
+    // @ts-expect-error testing invalid input
+    const section = extractPrincipleSection(principles, 'nonexistent');
+    expect(section).toBeNull();
+  });
+});
+
+describe.skipIf(!patternsAvailable)('loadPatterns', () => {
+  it('loads at least one pattern', async () => {
+    const patterns = await loadPatterns();
+    expect(patterns.length).toBeGreaterThan(0);
+  });
+
+  it('each pattern has required fields', async () => {
+    const patterns = await loadPatterns();
+    for (const p of patterns) {
+      expect(p.name).toBeTruthy();
+      expect(p.title).toBeTruthy();
+      expect(p.description).toBeTruthy();
+      expect(p.content.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('patterns are sorted by name', async () => {
+    const patterns = await loadPatterns();
+    const names = patterns.map((p) => p.name);
+    expect(names).toEqual([...names].sort());
+  });
+});
+
+describe.skipIf(!patternsAvailable)('getPatternByName', () => {
+  it('finds an existing pattern', async () => {
+    const pattern = await getPatternByName('settings-page');
+    expect(pattern).not.toBeNull();
+    expect(pattern?.name).toBe('settings-page');
+    expect(pattern?.title).toBe('Settings Page');
+  });
+
+  it('returns null for unknown patterns', async () => {
+    const pattern = await getPatternByName('nonexistent');
+    expect(pattern).toBeNull();
+  });
+});

package/src/data/design-system-loader.ts

@@ -0,0 +1,125 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { getDesignSystemDir } from '../utils/paths.js';
+
+export interface PatternEntry {
+  name: string;
+  title: string;
+  description: string;
+  content: string;
+}
+
+export const PRINCIPLE_TOPICS = [
+  'visual-hierarchy',
+  'interaction',
+  'component-selection',
+  'layout',
+  'accessibility',
+  'theming'
+] as const;
+
+export type PrincipleTopic = (typeof PRINCIPLE_TOPICS)[number];
+
+let cachedPrinciples: string | null = null;
+let cachedPatterns: PatternEntry[] | null = null;
+
+export async function loadPrinciples(): Promise<string> {
+  if (cachedPrinciples !== null) return cachedPrinciples;
+
+  const filePath = resolve(getDesignSystemDir(), 'principles.md');
+  try {
+    cachedPrinciples = await readFile(filePath, 'utf-8');
+  } catch {
+    cachedPrinciples = '';
+  }
+  return cachedPrinciples;
+}
+
+export async function loadPatterns(): Promise<PatternEntry[]> {
+  if (cachedPatterns) return cachedPatterns;
+
+  const patternsDir = resolve(getDesignSystemDir(), 'patterns');
+  const entries: PatternEntry[] = [];
+
+  let files: string[];
+  try {
+    files = await readdir(patternsDir);
+  } catch {
+    cachedPatterns = [];
+    return [];
+  }
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+
+    const filePath = resolve(patternsDir, file);
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const name = file.replace(/\.md$/, '');
+    const title = extractTitle(content);
+    const description = extractDescription(content);
+
+    entries.push({ name, title, description, content });
+  }
+
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  cachedPatterns = entries;
+  return entries;
+}
+
+export async function getPatternByName(name: string): Promise<PatternEntry | null> {
+  const patterns = await loadPatterns();
+  return patterns.find((p) => p.name === name) ?? null;
+}
+
+function extractTitle(content: string): string {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match?.[1]?.trim() ?? '';
+}
+
+function extractDescription(content: string): string {
+  const lines = content.split('\n');
+  const titleIdx = lines.findIndex((l) => /^#\s+/.test(l));
+  if (titleIdx === -1) return '';
+
+  for (let i = titleIdx + 1; i < lines.length; i++) {
+    const line = lines[i]!.trim();
+    if (line === '') continue;
+    if (line.startsWith('#')) break;
+    return line;
+  }
+  return '';
+}
+
+const TOPIC_HEADINGS: Record<PrincipleTopic, string> = {
+  'visual-hierarchy': '## Visual Hierarchy',
+  interaction: '## Interaction',
+  'component-selection': '## Component Selection',
+  layout: '## Layout',
+  accessibility: '## Accessibility',
+  theming: '## Theming'
+};
+
+export function extractPrincipleSection(content: string, topic: PrincipleTopic): string | null {
+  const heading = TOPIC_HEADINGS[topic];
+  if (!heading) return null;
+
+  const lines = content.split('\n');
+  const startIdx = lines.findIndex((l) => l.trim() === heading);
+  if (startIdx === -1) return null;
+
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (/^## /.test(lines[i]!)) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  return lines.slice(startIdx, endIdx).join('\n').trim();
+}

package/src/data/icon-loader.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { parseComponentNames, parseIconMetadata } from './icon-loader.js';
+
+const FIXTURE = `
+// Simulated icon.context.ts content
+import type { Component } from 'svelte';
+import HomeIcon from './HomeIcon.svelte';
+import SearchIcon from './SearchIcon.svelte';
+
+export const DEFAULT_ICONS = {
+  home: HomeIcon,
+  search: SearchIcon,
+  arrowRight: ArrowRightIcon
+};
+
+export const ICON_METADATA = {
+  home: { label: 'Home', categories: ['navigation'], keywords: ['house', 'start'] },
+  search: { label: 'Search', categories: ['navigation', 'ui'], keywords: ['find', 'lookup'] },
+  arrowRight: { label: 'Arrow Right', categories: ['navigation'], keywords: [] }
+};
+`;
+
+describe('parseComponentNames', () => {
+  it('builds a name → ComponentName map from DEFAULT_ICONS', () => {
+    const map = parseComponentNames(FIXTURE);
+    expect(map.get('home')).toBe('HomeIcon');
+    expect(map.get('search')).toBe('SearchIcon');
+    expect(map.get('arrowRight')).toBe('ArrowRightIcon');
+  });
+
+  it('returns an empty map when the DEFAULT_ICONS block is missing', () => {
+    const map = parseComponentNames('const NOT_IT = {};');
+    expect(map.size).toBe(0);
+  });
+});
+
+describe('parseIconMetadata', () => {
+  it('extracts label, categories, and keywords per entry', () => {
+    const entries = parseIconMetadata(FIXTURE);
+    expect(entries).toHaveLength(3);
+
+    const home = entries.find((e) => e.name === 'home');
+    expect(home).toMatchObject({
+      name: 'home',
+      componentName: 'HomeIcon',
+      label: 'Home',
+      categories: ['navigation'],
+      keywords: ['house', 'start']
+    });
+  });
+
+  it('uses the DEFAULT_ICONS mapping for componentName when available', () => {
+    const entries = parseIconMetadata(FIXTURE);
+    const search = entries.find((e) => e.name === 'search');
+    expect(search?.componentName).toBe('SearchIcon');
+  });
+
+  it('falls back to a capitalised name + "Icon" suffix when no mapping exists', () => {
+    const withoutMapping = `
+      export const ICON_METADATA = {
+        custom: { label: 'Custom', categories: ['x'], keywords: ['y'] }
+      };
+    `;
+    const entries = parseIconMetadata(withoutMapping);
+    expect(entries[0]?.componentName).toBe('CustomIcon');
+  });
+
+  it('returns an empty array when ICON_METADATA block is missing', () => {
+    expect(parseIconMetadata('// nothing to see')).toEqual([]);
+  });
+
+  it('handles empty categories and keywords arrays gracefully', () => {
+    const fixture = `
+      export const ICON_METADATA = {
+        minimal: { label: 'Minimal', categories: [], keywords: [] }
+      };
+    `;
+    const entries = parseIconMetadata(fixture);
+    expect(entries[0]).toMatchObject({
+      name: 'minimal',
+      categories: [],
+      keywords: []
+    });
+  });
+});

package/src/data/icon-loader.ts

@@ -0,0 +1,90 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(__dirname, '..', '..');
+
+export interface IconEntry {
+  name: string;
+  componentName: string;
+  label: string;
+  categories: string[];
+  keywords: string[];
+}
+
+let cachedIcons: IconEntry[] | null = null;
+
+function getIconRegistryPath(): string {
+  // DEFAULT_ICONS + ICON_METADATA live in icon-registry.ts since the icon module
+  // split (icon.context.ts now holds only the override context + resolveIcon).
+  return resolve(packageRoot, '..', 'blocks', 'src', 'lib', 'icons', 'icon-registry.ts');
+}
+
+/** Parse DEFAULT_ICONS to get the real name → ComponentName mapping */
+export function parseComponentNames(content: string): Map<string, string> {
+  const map = new Map<string, string>();
+  const start = content.indexOf('DEFAULT_ICONS');
+  if (start === -1) return map;
+
+  const end = content.indexOf('};', start);
+  if (end === -1) return map;
+
+  const block = content.slice(start, end);
+  const regex = /(\w+):\s*(\w+Icon)/g;
+  for (const match of block.matchAll(regex)) {
+    map.set(match[1]!, match[2]!);
+  }
+  return map;
+}
+
+export function parseIconMetadata(content: string): IconEntry[] {
+  const componentNames = parseComponentNames(content);
+  const entries: IconEntry[] = [];
+
+  const metadataStart = content.indexOf('ICON_METADATA');
+  if (metadataStart === -1) return [];
+
+  const entryRegex =
+    /(\w+):\s*\{\s*label:\s*'([^']*)',\s*categories:\s*\[([^\]]*)\],\s*keywords:\s*\[([^\]]*)\]\s*\}/g;
+  const block = content.slice(metadataStart);
+
+  for (const match of block.matchAll(entryRegex)) {
+    const name = match[1]!;
+    const label = match[2]!;
+    const categories = match[3]!
+      .split(',')
+      .map((s) => s.trim().replace(/^'|'$/g, ''))
+      .filter((s) => s.length > 0);
+    const keywords = match[4]!
+      .split(',')
+      .map((s) => s.trim().replace(/^'|'$/g, ''))
+      .filter((s) => s.length > 0);
+
+    const componentName =
+      componentNames.get(name) ?? `${name.charAt(0).toUpperCase() + name.slice(1)}Icon`;
+
+    entries.push({
+      name,
+      componentName,
+      label,
+      categories,
+      keywords
+    });
+  }
+
+  return entries;
+}
+
+export async function loadIcons(): Promise<IconEntry[]> {
+  if (cachedIcons) return cachedIcons;
+
+  try {
+    const content = await readFile(getIconRegistryPath(), 'utf-8');
+    cachedIcons = parseIconMetadata(content);
+  } catch {
+    cachedIcons = [];
+  }
+
+  return cachedIcons;
+}

package/src/data/recipe-loader.test.ts

@@ -0,0 +1,49 @@
+import { existsSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { getRecipeDir } from '../utils/paths.js';
+import { getRecipeById, loadRecipes } from './recipe-loader.js';
+
+const recipesAvailable = existsSync(getRecipeDir());
+
+describe.skipIf(!recipesAvailable)('recipe-loader pattern annotations', () => {
+  it('parses the Layer-4 pattern reference from meta.ts', async () => {
+    const dashboard = await getRecipeById('dashboard');
+    expect(dashboard?.pattern).toBe('dashboard');
+
+    const login = await getRecipeById('login');
+    expect(login?.pattern).toBe('form-page');
+
+    const onboarding = await getRecipeById('onboarding-flow');
+    expect(onboarding?.pattern).toBe('onboarding-guide');
+  });
+
+  it('leaves pattern undefined for recipes without one', async () => {
+    const profile = await getRecipeById('profile-card');
+    // profile-card is a component-level snippet, not a page archetype → no pattern
+    expect(profile?.pattern).toBeUndefined();
+  });
+
+  it('loads the meal-planner recipe with its planning-board pattern + Planner code', async () => {
+    const mealPlanner = await getRecipeById('meal-planner');
+    expect(mealPlanner?.title).toBe('Meal Planner');
+    expect(mealPlanner?.pattern).toBe('planning-board');
+    expect(mealPlanner?.components).toContain('Planner');
+    expect(mealPlanner?.code).toContain('<Planner');
+  });
+
+  it('every annotated pattern names an existing pattern file', async () => {
+    const recipes = await loadRecipes();
+    const known = new Set([
+      'dashboard',
+      'form-page',
+      'settings-page',
+      'tab-navigation',
+      'onboarding-guide',
+      'planning-board'
+    ]);
+    for (const r of recipes) {
+      if (r.pattern)
+        expect(known, `recipe "${r.id}" → unknown pattern "${r.pattern}"`).toContain(r.pattern);
+    }
+  });
+});

package/src/data/recipe-loader.ts

@@ -0,0 +1,131 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { getRecipeDir } from '../utils/paths.js';
+import type { RecipeEntry } from './catalog-loader.js';
+
+let cachedRecipes: RecipeEntry[] | null = null;
+
+function extractRecipeCode(content: string): string {
+  const startMatch = content.match(/const\s+recipeCode\s*=\s*\n?\s*/);
+  if (!startMatch) return '';
+
+  const startIdx = (startMatch.index ?? 0) + startMatch[0].length;
+  const rest = content.slice(startIdx);
+
+  let depth = 0;
+  let endIdx = -1;
+
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '`') {
+      depth = depth === 0 ? 1 : 0;
+    }
+    if (depth === 0 && rest[i] === ';') {
+      endIdx = i;
+      break;
+    }
+  }
+
+  if (endIdx === -1) return '';
+
+  const raw = rest.slice(0, endIdx);
+  const parts = raw.split(/`\s*\+\s*\n?\s*`/);
+  return parts.map((p) => p.replace(/^\s*`|`\s*$/g, '')).join('');
+}
+
+export async function loadRecipes(): Promise<RecipeEntry[]> {
+  if (cachedRecipes) return cachedRecipes;
+
+  const recipeDir = getRecipeDir();
+  const entries: RecipeEntry[] = [];
+
+  let dirs: string[];
+  try {
+    dirs = await readdir(recipeDir);
+  } catch {
+    cachedRecipes = [];
+    return [];
+  }
+
+  for (const dirName of dirs) {
+    const dirPath = resolve(recipeDir, dirName);
+    const dirStat = await stat(dirPath).catch(() => null);
+    if (!dirStat?.isDirectory()) continue;
+
+    // Read structured metadata from meta.ts
+    const metaPath = resolve(dirPath, 'meta.ts');
+    let meta: {
+      title: string;
+      description: string;
+      components: string[];
+      features: string[];
+      pattern: string;
+    };
+    try {
+      const metaContent = await readFile(metaPath, 'utf-8');
+      meta = parseRecipeMeta(metaContent);
+    } catch {
+      continue;
+    }
+
+    // Read recipeCode from +page.svelte (still embedded there for the live preview)
+    const pagePath = resolve(dirPath, '+page.svelte');
+    let code = '';
+    try {
+      const pageContent = await readFile(pagePath, 'utf-8');
+      code = extractRecipeCode(pageContent);
+    } catch {
+      // No page = no code, but metadata is still valid
+    }
+
+    entries.push({
+      id: dirName,
+      title: meta.title,
+      description: meta.description,
+      components: meta.components,
+      code,
+      features: meta.features,
+      pattern: meta.pattern || undefined
+    });
+  }
+
+  cachedRecipes = entries;
+  return entries;
+}
+
+export async function getRecipeById(id: string): Promise<RecipeEntry | null> {
+  const recipes = await loadRecipes();
+  return recipes.find((r) => r.id === id) ?? null;
+}
+
+function parseRecipeMeta(content: string): {
+  title: string;
+  description: string;
+  components: string[];
+  features: string[];
+  pattern: string;
+} {
+  const extractString = (key: string): string => {
+    const match = content.match(new RegExp(`${key}:\\s*['"]([^'"]*?)['"]`));
+    if (match?.[1]) return match[1];
+    // Multi-line string with concatenation
+    const multiMatch = content.match(new RegExp(`${key}:\\s*\\n?\\s*['"]([\\s\\S]*?)['"]`, 'm'));
+    return multiMatch?.[1]?.replace(/'\s*\+\s*\n?\s*'/g, '') ?? '';
+  };
+
+  const extractArray = (key: string): string[] => {
+    const match = content.match(new RegExp(`${key}:\\s*\\[([^\\]]+)\\]`, 's'));
+    if (!match?.[1]) return [];
+    return match[1]
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+      .filter((s) => s.length > 0);
+  };
+
+  return {
+    title: extractString('title'),
+    description: extractString('description'),
+    components: extractArray('components'),
+    features: extractArray('features'),
+    pattern: extractString('pattern')
+  };
+}

package/src/data/template-loader.ts

@@ -0,0 +1,55 @@
+import { readFile } from 'node:fs/promises';
+import { getTemplatePath } from '../utils/paths.js';
+
+export interface TemplateSections {
+  'api-grammar': string;
+  'component-families': string;
+  tokens: string;
+  'design-quality': string;
+  customization: string;
+  'style-patterns': string;
+  'auth-setup': string;
+}
+
+let cachedSections: TemplateSections | null = null;
+
+function extractSection(lines: string[], startHeading: string, endMarker: string): string {
+  const startIdx = lines.findIndex((l) => l.trim().startsWith(startHeading));
+  if (startIdx === -1) return '';
+
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === endMarker) {
+      endIdx = i;
+      break;
+    }
+  }
+
+  return lines.slice(startIdx, endIdx).join('\n').trim();
+}
+
+export async function loadTemplateSections(): Promise<TemplateSections> {
+  if (cachedSections) return cachedSections;
+
+  const templatePath = getTemplatePath();
+  const raw = await readFile(templatePath, 'utf-8');
+  const lines = raw.split('\n');
+
+  cachedSections = {
+    'api-grammar': extractSection(lines, '## Shared API Grammar', '---'),
+    'component-families': extractSection(lines, '## Component Families', '---'),
+    tokens: extractSection(lines, '## Design Token System', '---'),
+    'design-quality': extractSection(lines, '## Design Quality', '---'),
+    customization: extractSection(lines, '## Customization', '---'),
+    'style-patterns': extractSection(lines, '## Style Patterns', '---'),
+    // Auth Setup is the last section and contains no `---` rules of its own, so
+    // it extracts cleanly to EOF. Its `###` stage sub-headings carry the staging.
+    'auth-setup': extractSection(lines, '## Auth Setup', '---')
+  };
+
+  return cachedSections;
+}
+
+export function getCachedSections(): TemplateSections | null {
+  return cachedSections;
+}