feat: add Vite plugin for cookbook static bundling (#1443)

* feat: add Vite plugin for cookbook static bundling

- Create cookbook-bundler Vite plugin that reads cookbook/ directory at
  build time and emits bundled JSON as a virtual ES module
- Merge pattern.json/component.json metadata into registry items
- Support HMR in dev mode by watching cookbook/ for changes
- Wire useCookbook hook to import from virtual:cookbook-data
- Add TypeScript declarations for the virtual module
- Add vitest tests for plugin resolve, load, and merge behavior

* fix: remove unused join import from cookbook-bundler

* fix: add cookbook-bundler plugin to vitest config

The virtual:cookbook-data module needs to be resolved in tests too.

* refactor: move virtual module declaration to vite-env.d.ts

Move the virtual:cookbook-data module declaration into src/vite-env.d.ts
where tsconfig.app.json can resolve the @/ alias, instead of a separate
file under vite-plugins/ where tsconfig.node.json lacks the alias.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

frontend/src/features/cookbook/hooks/use-cookbook.ts

@@ -45,8 +45,8 @@ export interface CookbookRegistry {
   items: CookbookItem[]
 }
 
-// Hook stub - returns empty data initially. Task 2 (Vite plugin) will provide real data.
+import cookbookData from 'virtual:cookbook-data'
+
 export function useCookbook(): { items: CookbookItem[]; isLoading: boolean } {
-  // TODO: Replace with Vite plugin bundled data (Task 2)
-  return { items: [], isLoading: false }
+  return { items: cookbookData.items, isLoading: false }
 }

frontend/src/vite-env.d.ts

@@ -1,5 +1,11 @@
 /// <reference types="vite/client" />
 
+declare module 'virtual:cookbook-data' {
+  import type { CookbookRegistry } from '@/features/cookbook/hooks/use-cookbook'
+  const data: CookbookRegistry
+  export default data
+}
+
 interface ImportMetaEnv {
   readonly VITE_API_BASE_URL: string
   readonly VITE_AUTH_AUDIENCE: string

frontend/tsconfig.node.json

@@ -22,5 +22,5 @@
     "noFallthroughCasesInSwitch": true,
     "noUncheckedSideEffectImports": true
   },
-  "include": ["vite.config.ts"]
+  "include": ["vite.config.ts", "vite-plugins"]
 }

frontend/vite-plugins/cookbook-bundler.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import cookbookBundler from './cookbook-bundler'
+
+function createTempCookbook() {
+  const dir = join(tmpdir(), `cookbook-test-${Date.now()}`)
+  mkdirSync(join(dir, 'patterns', 'energy-settlement'), { recursive: true })
+  mkdirSync(join(dir, 'ui', 'activity-feed'), { recursive: true })
+  return dir
+}
+
+describe('cookbook-bundler', () => {
+  let tempDir: string
+
+  beforeEach(() => {
+    tempDir = createTempCookbook()
+  })
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  it('resolves the virtual module ID', () => {
+    const plugin = cookbookBundler({ cookbookDir: tempDir })
+    const resolveId = plugin.resolveId as (id: string) => string | undefined
+    expect(resolveId('virtual:cookbook-data')).toBe('\0virtual:cookbook-data')
+    expect(resolveId('some-other-module')).toBeUndefined()
+  })
+
+  it('loads empty items when registry.json is missing', () => {
+    const plugin = cookbookBundler({ cookbookDir: tempDir })
+    const load = plugin.load as (id: string) => string | undefined
+    const result = load('\0virtual:cookbook-data')
+    expect(result).toContain('export default')
+    const data = JSON.parse(result!.replace('export default ', '').replace(';', ''))
+    expect(data.items).toEqual([])
+  })
+
+  it('loads registry items and merges pattern.json metadata', () => {
+    writeFileSync(
+      join(tempDir, 'registry.json'),
+      JSON.stringify({
+        name: 'test-cookbook',
+        items: [
+          { name: 'energy-settlement', type: 'registry:pattern', title: 'Energy' },
+          { name: 'activity-feed', type: 'registry:ui', title: 'Activity Feed' },
+        ],
+      }),
+    )
+
+    writeFileSync(
+      join(tempDir, 'patterns', 'energy-settlement', 'pattern.json'),
+      JSON.stringify({
+        name: 'energy-settlement',
+        type: 'registry:pattern',
+        title: 'Energy',
+        description: 'Converts kWh into value',
+        categories: ['energy'],
+        meta: { complexity: 3, design_pattern: 'cross-instrument-valuation' },
+        files: [{ path: 'patterns/energy-settlement/manifest-fragment.yaml', type: 'registry:file' }],
+      }),
+    )
+
+    writeFileSync(
+      join(tempDir, 'ui', 'activity-feed', 'component.json'),
+      JSON.stringify({
+        name: 'activity-feed',
+        type: 'registry:ui',
+        title: 'Activity Feed',
+        description: 'Displays events',
+        meta: { feature_module: 'dashboard' },
+      }),
+    )
+
+    const plugin = cookbookBundler({ cookbookDir: tempDir })
+    const load = plugin.load as (id: string) => string | undefined
+    const result = load('\0virtual:cookbook-data')
+    const data = JSON.parse(result!.replace('export default ', '').replace(';', ''))
+
+    expect(data.name).toBe('test-cookbook')
+    expect(data.items).toHaveLength(2)
+
+    const pattern = data.items[0]
+    expect(pattern.description).toBe('Converts kWh into value')
+    expect(pattern.meta.complexity).toBe(3)
+    expect(pattern.files).toHaveLength(1)
+
+    const ui = data.items[1]
+    expect(ui.description).toBe('Displays events')
+    expect(ui.meta.feature_module).toBe('dashboard')
+  })
+
+  it('handles missing pattern.json gracefully', () => {
+    writeFileSync(
+      join(tempDir, 'registry.json'),
+      JSON.stringify({
+        name: 'test-cookbook',
+        items: [
+          { name: 'no-detail', type: 'registry:pattern', title: 'No Detail' },
+        ],
+      }),
+    )
+
+    const plugin = cookbookBundler({ cookbookDir: tempDir })
+    const load = plugin.load as (id: string) => string | undefined
+    const result = load('\0virtual:cookbook-data')
+    const data = JSON.parse(result!.replace('export default ', '').replace(';', ''))
+
+    expect(data.items).toHaveLength(1)
+    expect(data.items[0].name).toBe('no-detail')
+    expect(data.items[0].meta).toBeUndefined()
+  })
+})

frontend/vite-plugins/cookbook-bundler.ts

@@ -0,0 +1,92 @@
+import type { Plugin } from 'vite'
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const VIRTUAL_MODULE_ID = 'virtual:cookbook-data'
+const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID
+
+interface RegistryEntry {
+  name: string
+  type: string
+  title: string
+  description?: string
+  categories?: string[]
+}
+
+interface CookbookBundlerOptions {
+  /** Path to the cookbook directory. Defaults to `../cookbook` relative to frontend/. */
+  cookbookDir?: string
+}
+
+function loadCookbookData(cookbookDir: string): string {
+  const registryPath = resolve(cookbookDir, 'registry.json')
+  if (!existsSync(registryPath)) {
+    console.warn(`[cookbook-bundler] registry.json not found at ${registryPath}`)
+    return JSON.stringify({ name: 'meridian-cookbook', items: [] })
+  }
+
+  const registry = JSON.parse(readFileSync(registryPath, 'utf-8')) as {
+    name: string
+    items: RegistryEntry[]
+  }
+
+  const items = registry.items.map((entry) => {
+    const isPattern = entry.type === 'registry:pattern'
+    const subdir = isPattern ? 'patterns' : 'ui'
+    const metaFile = isPattern ? 'pattern.json' : 'component.json'
+    const metaPath = resolve(cookbookDir, subdir, entry.name, metaFile)
+
+    if (!existsSync(metaPath)) {
+      return entry
+    }
+
+    const detail = JSON.parse(readFileSync(metaPath, 'utf-8'))
+    return {
+      ...entry,
+      description: detail.description ?? entry.description,
+      categories: detail.categories ?? entry.categories,
+      meta: detail.meta,
+      files: detail.files,
+    }
+  })
+
+  return JSON.stringify({ name: registry.name, items })
+}
+
+export default function cookbookBundler(
+  options: CookbookBundlerOptions = {},
+): Plugin {
+  const cookbookDir = options.cookbookDir ?? resolve(__dirname, '../../cookbook')
+
+  return {
+    name: 'cookbook-bundler',
+
+    resolveId(id: string) {
+      if (id === VIRTUAL_MODULE_ID) {
+        return RESOLVED_VIRTUAL_MODULE_ID
+      }
+    },
+
+    load(id: string) {
+      if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+        const data = loadCookbookData(cookbookDir)
+        return `export default ${data};`
+      }
+    },
+
+    configureServer(server) {
+      server.watcher.add(cookbookDir)
+      server.watcher.on('change', (file) => {
+        if (file.startsWith(cookbookDir)) {
+          const mod = server.moduleGraph.getModuleById(
+            RESOLVED_VIRTUAL_MODULE_ID,
+          )
+          if (mod) {
+            server.moduleGraph.invalidateModule(mod)
+            server.ws.send({ type: 'full-reload' })
+          }
+        }
+      })
+    },
+  }
+}

frontend/vite.config.ts

@@ -3,12 +3,13 @@ import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 import path from 'path'
 import { fileURLToPath } from 'url'
+import cookbookBundler from './vite-plugins/cookbook-bundler'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 // https://vite.dev/config/
 export default defineConfig({
-  plugins: [react(), tailwindcss()],
+  plugins: [react(), tailwindcss(), cookbookBundler()],
   resolve: {
     alias: {
       '@': path.resolve(__dirname, './src'),

frontend/vitest.config.ts

@@ -76,8 +76,10 @@ function genStubPlugin(): Plugin {
   }
 }
 
+import cookbookBundler from './vite-plugins/cookbook-bundler'
+
 export default defineConfig({
-  plugins: [genStubPlugin(), react()],
+  plugins: [genStubPlugin(), cookbookBundler(), react()],
   test: {
     environment: 'jsdom',
     setupFiles: ['./src/test/setup.ts'],