grg-kit-cli 0.3.3 → 0.4.0

package/commands/add.js

@@ -1,7 +1,7 @@
 const degit = require('degit');
 const chalk = require('chalk');
 const ora = require('ora');
-const { RESOURCES, REPO } = require('../config/resources');
+const { fetchCatalog, REPO } = require('../config/catalog-fetcher');
 
 /**
  * Add command - downloads blocks
@@ -12,6 +12,11 @@ const { RESOURCES, REPO } = require('../config/resources');
  *   grg add block --all
  */
 async function add(options) {
+  // Fetch catalog dynamically (with caching)
+  const spinner = ora('Fetching catalog...').start();
+  const RESOURCES = await fetchCatalog({ silent: true });
+  spinner.stop();
+
   // Determine which blocks to add
   const blocksToAdd = [];
   
@@ -44,14 +49,14 @@ async function add(options) {
 
   console.log(chalk.bold.cyan(`\n📦 Adding ${blocksToAdd.length} block(s)\n`));
 
-  const spinner = ora();
+  const downloadSpinner = ora();
 
   for (const block of blocksToAdd) {
     const outputPath = options.output 
       ? `${options.output}/${block.name}` 
       : block.defaultOutput;
 
-    spinner.start(`Downloading ${block.title}...`);
+    downloadSpinner.start(`Downloading ${block.title}...`);
 
     try {
       const emitter = degit(`${REPO}/${block.path}`, {
@@ -62,7 +67,7 @@ async function add(options) {
 
       await emitter.clone(outputPath);
 
-      spinner.succeed(chalk.green(`✓ ${block.title} added`));
+      downloadSpinner.succeed(chalk.green(`✓ ${block.title} added`));
       console.log(chalk.gray(`  Location: ${outputPath}`));
       
       // Show dependencies if any
@@ -72,7 +77,7 @@ async function add(options) {
       console.log();
 
     } catch (error) {
-      spinner.fail(chalk.red(`Failed to download ${block.title}`));
+      downloadSpinner.fail(chalk.red(`Failed to download ${block.title}`));
       console.error(chalk.red(error.message));
     }
   }

package/commands/list.js

@@ -1,11 +1,17 @@
 const chalk = require('chalk');
-const { RESOURCES } = require('../config/resources');
+const ora = require('ora');
+const { fetchCatalog } = require('../config/catalog-fetcher');
 
 /**
  * List command - displays available blocks and themes
  * Usage: grg list [category]
  */
 async function list(category) {
+  // Fetch catalog dynamically
+  const spinner = ora('Fetching catalog...').start();
+  const RESOURCES = await fetchCatalog({ silent: true });
+  spinner.stop();
+
   if (!category) {
     // Show overview
     console.log(chalk.bold.cyan('\n📦 GRG Kit Resources\n'));

package/config/catalog-fetcher.js

@@ -0,0 +1,198 @@
+/**
+ * Dynamic catalog fetcher with caching
+ * Fetches catalog.json from GitHub with fallback to static resources
+ */
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const REPO = 'Genesis-Research/grg-kit';
+const CATALOG_URL = `https://raw.githubusercontent.com/${REPO}/main/templates/catalog.json`;
+const CACHE_FILE = path.join(__dirname, '.catalog-cache.json');
+const CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+// In-memory cache for current session
+let memoryCache = null;
+let memoryCacheTime = 0;
+
+/**
+ * Fetch JSON from URL
+ */
+function fetchJson(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}`));
+        return;
+      }
+
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (e) {
+          reject(new Error('Invalid JSON'));
+        }
+      });
+    }).on('error', reject);
+  });
+}
+
+/**
+ * Read file cache
+ */
+function readFileCache() {
+  try {
+    if (fs.existsSync(CACHE_FILE)) {
+      const cached = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
+      if (Date.now() - cached.timestamp < CACHE_TTL_MS) {
+        return cached.data;
+      }
+    }
+  } catch (e) {
+    // Cache read failed, ignore
+  }
+  return null;
+}
+
+/**
+ * Write file cache
+ */
+function writeFileCache(data) {
+  try {
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({
+      timestamp: Date.now(),
+      data
+    }), 'utf-8');
+  } catch (e) {
+    // Cache write failed, ignore
+  }
+}
+
+/**
+ * Get static fallback resources
+ */
+function getStaticFallback() {
+  try {
+    const { RESOURCES } = require('./resources');
+    return RESOURCES;
+  } catch (e) {
+    return { themes: [], components: [], blocks: [] };
+  }
+}
+
+/**
+ * Fetch catalog with caching
+ * Priority: memory cache -> file cache -> network -> static fallback
+ */
+async function fetchCatalog(options = {}) {
+  const { forceRefresh = false, silent = false } = options;
+
+  // Check memory cache first (fastest)
+  if (!forceRefresh && memoryCache && (Date.now() - memoryCacheTime < CACHE_TTL_MS)) {
+    return memoryCache;
+  }
+
+  // Check file cache
+  if (!forceRefresh) {
+    const fileCached = readFileCache();
+    if (fileCached) {
+      memoryCache = fileCached;
+      memoryCacheTime = Date.now();
+      return fileCached;
+    }
+  }
+
+  // Fetch from network
+  try {
+    const catalog = await fetchJson(CATALOG_URL);
+    
+    // Transform to match expected format
+    const resources = {
+      themes: catalog.themes.map(t => ({
+        ...t,
+        path: `templates/ui/themes/${t.file}`,
+        defaultOutput: `src/themes/${t.file}`
+      })),
+      components: catalog.components.map(c => ({
+        ...c,
+        path: `templates/ui/components/${c.name}`,
+        defaultOutput: `src/app/components/${c.name}`
+      })),
+      blocks: catalog.blocks.map(b => ({
+        ...b,
+        path: `templates/ui/blocks/${b.name}`,
+        defaultOutput: `src/app/blocks/${b.name}`
+      }))
+    };
+
+    // Update caches
+    memoryCache = resources;
+    memoryCacheTime = Date.now();
+    writeFileCache(resources);
+
+    return resources;
+  } catch (error) {
+    if (!silent) {
+      console.warn(`Warning: Could not fetch catalog (${error.message}), using cached/static resources`);
+    }
+    
+    // Try file cache even if expired
+    try {
+      if (fs.existsSync(CACHE_FILE)) {
+        const cached = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
+        return cached.data;
+      }
+    } catch (e) {
+      // Ignore
+    }
+
+    // Final fallback to static resources
+    return getStaticFallback();
+  }
+}
+
+/**
+ * Get resources synchronously (uses cache or static fallback)
+ */
+function getResourcesSync() {
+  // Check memory cache
+  if (memoryCache && (Date.now() - memoryCacheTime < CACHE_TTL_MS)) {
+    return memoryCache;
+  }
+
+  // Check file cache
+  const fileCached = readFileCache();
+  if (fileCached) {
+    memoryCache = fileCached;
+    memoryCacheTime = Date.now();
+    return fileCached;
+  }
+
+  // Static fallback
+  return getStaticFallback();
+}
+
+/**
+ * Clear all caches
+ */
+function clearCache() {
+  memoryCache = null;
+  memoryCacheTime = 0;
+  try {
+    if (fs.existsSync(CACHE_FILE)) {
+      fs.unlinkSync(CACHE_FILE);
+    }
+  } catch (e) {
+    // Ignore
+  }
+}
+
+module.exports = {
+  fetchCatalog,
+  getResourcesSync,
+  clearCache,
+  REPO
+};

package/config/resources.js

@@ -133,11 +133,18 @@ const RESOURCES = {
     {
       "name": "file-upload",
       "title": "File Upload Component",
-      "description": "file-upload component",
+      "description": "Drag and drop file upload component",
       "path": "templates/ui/components/file-upload",
       "defaultOutput": "src/app/components/file-upload",
-      "tags": [],
-      "dependencies": []
+      "tags": [
+        "file",
+        "upload",
+        "form",
+        "drag-drop"
+      ],
+      "dependencies": [
+        "@spartan-ng/helm/button"
+      ]
     },
     {
       "name": "stepper",
@@ -154,23 +161,22 @@ const RESOURCES = {
       "dependencies": [
         "@spartan-ng/helm/button",
         "@spartan-ng/helm/card"
-      ],
-      "type": "grg-component",
-      "prefix": "grg"
+      ]
     }
   ],
   "blocks": [
     {
       "name": "auth",
-      "title": "Auth Block",
-      "description": "Authentication pages layout (login, signup, forgot password)",
+      "title": "Auth",
+      "description": "Authentication pages (login, signup, forgot password)",
       "path": "templates/ui/blocks/auth",
       "defaultOutput": "src/app/blocks/auth",
       "tags": [
         "auth",
         "login",
         "signup",
-        "authentication"
+        "authentication",
+        "form"
       ],
       "dependencies": [
         "@spartan-ng/helm/button",
@@ -180,25 +186,45 @@ const RESOURCES = {
     },
     {
       "name": "settings",
-      "title": "Settings Block",
-      "description": "settings block",
+      "title": "Settings",
+      "description": "Settings pages: profile, notifications, security, danger zone",
       "path": "templates/ui/blocks/settings",
       "defaultOutput": "src/app/blocks/settings",
       "tags": [
-        "settings"
+        "settings",
+        "preferences",
+        "account",
+        "profile",
+        "security"
       ],
-      "dependencies": []
+      "dependencies": [
+        "@spartan-ng/helm/button",
+        "@spartan-ng/helm/card",
+        "@spartan-ng/helm/form-field",
+        "@spartan-ng/helm/switch"
+      ]
     },
     {
       "name": "shell",
-      "title": "Shell Block",
-      "description": "shell block",
+      "title": "Shell",
+      "description": "Application shell layouts: sidebar, topnav, collapsible - each with optional footer variant",
       "path": "templates/ui/blocks/shell",
       "defaultOutput": "src/app/blocks/shell",
       "tags": [
-        "shell"
+        "shell",
+        "layout",
+        "sidebar",
+        "header",
+        "footer",
+        "navigation",
+        "topnav",
+        "collapsible"
       ],
-      "dependencies": []
+      "dependencies": [
+        "@spartan-ng/helm/button",
+        "@spartan-ng/helm/icon",
+        "@spartan-ng/helm/dropdown-menu"
+      ]
     }
   ]
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grg-kit-cli",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "CLI tool for pulling GRG Kit resources into your Angular project",
   "main": "index.js",
   "bin": {

package/scripts/README.md

@@ -1,101 +1,233 @@
-# CLI Scripts
+# Resource Generation Flow
 
-## generate-resources.js
+## Overview
 
-Automatically generates `config/resources.js` by scanning the `templates/` directory.
+GRG Kit uses a **two-stage generation pipeline** to ensure CLI and MCP server always have up-to-date resource definitions.
 
-### Purpose
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           SOURCE OF TRUTH                                    │
+│                                                                              │
+│  app/src/app/blocks/{block}/meta.json    ← Block metadata                   │
+│  app/src/themes/meta.json                ← Theme metadata                   │
+│  app/libs/grg-ui/{component}/meta.json   ← Component metadata               │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  STAGE 1: pnpm generate:sources (in app/)                                   │
+│                                                                              │
+│  • Transforms source components → template files                            │
+│  • Copies meta.json files → templates/ directory                            │
+│  • Generates generated-sources.ts for showcase app                          │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         TEMPLATES DIRECTORY                                  │
+│                                                                              │
+│  templates/ui/blocks/{block}/meta.json      ← Copied from app               │
+│  templates/ui/blocks/{block}/*.component.ts ← Generated                     │
+│  templates/ui/themes/meta.json              ← Copied from app               │
+│  templates/ui/components/{comp}/meta.json   ← Copied from app               │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  STAGE 2: node scripts/generate-resources.js (in cli/)                      │
+│                                                                              │
+│  • Scans templates/ directory                                               │
+│  • Reads meta.json files for metadata                                       │
+│  • Generates cli/config/resources.js (static fallback)                      │
+│  • Generates templates/catalog.json (dynamic, fetched at runtime)           │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         RUNTIME (CLI & MCP)                                  │
+│                                                                              │
+│  1. Check memory cache (instant)                                            │
+│  2. Check file cache (~1ms)                                                 │
+│  3. Fetch catalog.json from GitHub (~100-200ms)                             │
+│  4. Fallback to static resources.js                                         │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
 
-Ensures the CLI always has up-to-date resource definitions based on what's actually available in the templates, preventing:
-- Outdated resource lists
-- Manual maintenance errors
-- Mismatched paths
-- Missing new resources
+## Adding New Resources
 
-### Usage
+### 1. Add a New Block
 
 ```bash
-# Run manually
-pnpm run generate
+# 1. Create block component in app
+app/src/app/blocks/my-block/my-block.component.ts
 
-# Or directly
-node scripts/generate-resources.js
+# 2. Add metadata
+app/src/app/blocks/my-block/meta.json
 ```
 
-### Auto-Generation
+```json
+{
+  "description": "Description for AI and CLI",
+  "tags": ["keyword1", "keyword2", "searchable"],
+  "dependencies": ["@spartan-ng/helm/button", "@spartan-ng/helm/card"]
+}
+```
 
-The script runs automatically before publishing:
 ```bash
-pnpm publish  # Runs prepublishOnly hook → pnpm run generate
+# 3. Update generate-sources.js CONFIG.blocks.sources array
+
+# 4. Run generation
+cd app && pnpm generate:sources
+cd ../cli && node scripts/generate-resources.js
+
+# 5. Commit and push - CLI/MCP pick up changes automatically
 ```
 
-### What It Does
+### 2. Add a New Theme
 
-1. **Scans templates directory** for:
-   - Themes (`templates/ui/themes/*.css`)
-   - Components (`templates/ui/components/*/`)
-   - Layouts (`templates/ui/layouts/*/`)
-   - Examples (`templates/spartan-examples/components/(*)`)
+```bash
+# 1. Create theme CSS
+app/src/themes/my-theme.css
 
-2. **Generates metadata** for each resource:
-   - Name, title, description
-   - Path and default output location
-   - Tags for searchability
-   - Dependencies (if applicable)
+# 2. Add entry to themes meta.json
+app/src/themes/meta.json
+```
 
-3. **Writes `config/resources.js`** with structured data
+```json
+{
+  "my-theme.css": {
+    "description": "My custom theme description",
+    "tags": ["custom", "dark", "modern"]
+  }
+}
+```
 
-### Output
+### 3. Add a New GRG Component
+
+```bash
+# 1. Create component in libs/grg-ui
+app/libs/grg-ui/my-component/src/...
 
+# 2. Add metadata
+app/libs/grg-ui/my-component/meta.json
 ```
-🔍 Scanning templates directory...
-✓ Found 6 themes
-✓ Found 2 components
-✓ Found 3 layouts
-✓ Found 56 example components
-
-✅ Generated /path/to/config/resources.js
-
-📦 Resource Summary:
-   Themes: 6
-   Components: 2
-   Layouts: 3
-   Examples: 56
+
+---
+
+## Scripts
+
+### `app/scripts/generate-sources.js`
+
+Generates template files and copies metadata.
+
+```bash
+cd app
+pnpm generate:sources
 ```
 
-### Customizing Metadata
+**What it does:**
+- Transforms block components → standalone template files
+- Copies `meta.json` files to `templates/` directory
+- Generates `generated-sources.ts` for showcase app
 
-Edit the metadata constants in `generate-resources.js`:
+### `cli/scripts/generate-resources.js`
 
-```javascript
-const THEME_METADATA = {
-  'grg-theme.css': {
-    description: 'Default theme with purple/orange accents',
-    tags: ['default', 'purple', 'orange', 'colorful']
-  }
-};
+Generates CLI resources and dynamic catalog.
 
-const COMPONENT_METADATA = {
-  'stepper': {
-    description: 'Multi-step form component',
-    tags: ['form', 'wizard'],
-    dependencies: ['@spartan-ng/helm/button']
-  }
-};
+```bash
+cd cli
+node scripts/generate-resources.js
 ```
 
-### Benefits
+**What it does:**
+- Scans `templates/` directory
+- Reads `meta.json` files for metadata
+- Generates `cli/config/resources.js` (static fallback)
+- Generates `templates/catalog.json` (dynamic catalog)
+
+---
+
+## Dynamic Catalog Fetching
+
+CLI and MCP server fetch `catalog.json` from GitHub at runtime with caching:
+
+| Cache Level | TTL | Speed |
+|-------------|-----|-------|
+| Memory cache | 15 min | <1ms |
+| File cache | 15 min | ~1ms |
+| GitHub fetch | - | ~100-200ms |
+| Static fallback | - | <1ms |
+
+**Benefits:**
+- No CLI/MCP redeploy needed for new resources
+- Changes propagate within 15 minutes
+- Graceful fallback if network fails
+
+---
+
+## File Structure
+
+```
+grg-kit/
+├── app/
+│   ├── src/
+│   │   ├── app/blocks/
+│   │   │   ├── auth/
+│   │   │   │   ├── meta.json           ← Source metadata
+│   │   │   │   └── *.component.ts
+│   │   │   ├── shell/
+│   │   │   │   ├── meta.json
+│   │   │   │   └── *.component.ts
+│   │   │   └── settings/
+│   │   │       ├── meta.json
+│   │   │       └── *.component.ts
+│   │   └── themes/
+│   │       ├── meta.json               ← All themes metadata
+│   │       └── *.css
+│   ├── libs/grg-ui/
+│   │   ├── stepper/meta.json
+│   │   └── file-upload/meta.json
+│   └── scripts/
+│       └── generate-sources.js         ← Stage 1
+│
+├── cli/
+│   ├── config/
+│   │   ├── resources.js                ← Generated (static fallback)
+│   │   └── catalog-fetcher.js          ← Dynamic fetcher
+│   └── scripts/
+│       └── generate-resources.js       ← Stage 2
+│
+├── mcp-server/
+│   └── src/
+│       ├── index.ts
+│       └── catalog-fetcher.ts          ← Dynamic fetcher
+│
+└── templates/
+    ├── catalog.json                    ← Generated (dynamic)
+    └── ui/
+        ├── blocks/
+        │   ├── auth/
+        │   │   ├── meta.json           ← Copied from app
+        │   │   └── *.component.ts      ← Generated
+        │   └── ...
+        ├── themes/
+        │   ├── meta.json               ← Copied from app
+        │   └── *.css
+        └── components/
+            ├── stepper/meta.json       ← Copied from app
+            └── file-upload/meta.json
+```
 
-✅ **Always accurate** - Resources match what's in templates  
-✅ **No manual updates** - Add files to templates, run script  
-✅ **Type-safe** - Consistent structure for all resources  
-✅ **MCP-ready** - Structured metadata for LLM consumption  
-✅ **Auto-discovery** - New resources automatically included  
+---
 
-### Development Workflow
+## Quick Reference
 
-1. Add new resource to `templates/` directory
-2. (Optional) Add metadata to script constants
-3. Run `pnpm run generate`
-4. Test with `grg list` or `grg add`
-5. Publish with `pnpm publish` (auto-generates)
+| Task | Command |
+|------|---------|
+| Generate templates + copy meta | `cd app && pnpm generate:sources` |
+| Generate resources + catalog | `cd cli && node scripts/generate-resources.js` |
+| Full regeneration | Run both above |
+| Test CLI | `cd cli && node bin/grg.js list` |
+| Build MCP | `cd mcp-server && pnpm build` |

package/scripts/generate-resources.js

@@ -10,59 +10,48 @@ const path = require('path');
 
 const TEMPLATES_DIR = path.join(__dirname, '../../templates');
 const OUTPUT_FILE = path.join(__dirname, '../config/resources.js');
+const CATALOG_FILE = path.join(TEMPLATES_DIR, 'catalog.json');
 
-// Theme metadata (can be enhanced by reading CSS files)
-const THEME_METADATA = {
-  'grg-theme.css': {
-    description: 'Default theme with purple/orange accents',
-    tags: ['default', 'purple', 'orange', 'colorful']
-  },
-  'claude.css': {
-    description: 'Claude-inspired warm tones',
-    tags: ['warm', 'orange', 'brown', 'claude']
-  },
-  'clean-slate.css': {
-    description: 'Minimal grayscale palette',
-    tags: ['minimal', 'grayscale', 'neutral', 'clean']
-  },
-  'modern-minimal.css': {
-    description: 'Contemporary minimal design',
-    tags: ['minimal', 'modern', 'contemporary', 'clean']
-  },
-  'amber-minimal.css': {
-    description: 'Warm amber accents',
-    tags: ['minimal', 'warm', 'amber', 'orange']
-  },
-  'mocks.css': {
-    description: 'Theme for mockups and prototypes',
-    tags: ['mockup', 'prototype', 'design']
-  }
-};
-
-// Component metadata
-const COMPONENT_METADATA = {
-  'stepper': {
-    description: 'Multi-step form component with progress indicator',
-    tags: ['form', 'wizard', 'multi-step', 'progress'],
-    dependencies: ['@spartan-ng/helm/button', '@spartan-ng/helm/card'],
-    type: 'grg-component',
-    prefix: 'grg'
-  }
-};
-
-// Block metadata (formerly layouts)
-const BLOCK_METADATA = {
-  'dashboard': {
-    description: 'Full dashboard layout with sidebar and header',
-    tags: ['dashboard', 'admin', 'sidebar', 'navigation'],
-    dependencies: ['@spartan-ng/helm/button', '@spartan-ng/helm/card', '@spartan-ng/helm/navigation-menu']
-  },
-  'auth': {
-    description: 'Authentication pages layout (login, signup, forgot password)',
-    tags: ['auth', 'login', 'signup', 'authentication'],
-    dependencies: ['@spartan-ng/helm/button', '@spartan-ng/helm/card', '@spartan-ng/helm/form-field']
+/**
+ * Read meta.json from a directory if it exists
+ */
+function readMeta(dir) {
+  const metaPath = path.join(dir, 'meta.json');
+  try {
+    if (fs.existsSync(metaPath)) {
+      return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    }
+  } catch (error) {
+    console.warn(`Warning: Could not read ${metaPath}`);
   }
-};
+  return null;
+}
+
+/**
+ * Default metadata generators
+ */
+function defaultBlockMeta(name) {
+  return {
+    description: `${name} block`,
+    tags: [name],
+    dependencies: []
+  };
+}
+
+function defaultComponentMeta(name) {
+  return {
+    description: `${name} component`,
+    tags: [],
+    dependencies: []
+  };
+}
+
+function defaultThemeMeta(name) {
+  return {
+    description: `${name} theme`,
+    tags: []
+  };
+}
 
 function scanDirectory(dir) {
   try {
@@ -77,14 +66,14 @@ function generateThemes() {
   const themesDir = path.join(TEMPLATES_DIR, 'ui/themes');
   const files = scanDirectory(themesDir);
   
+  // Read themes meta.json (contains all theme metadata keyed by filename)
+  const themesMeta = readMeta(themesDir) || {};
+  
   return files
     .filter(file => file.isFile() && file.name.endsWith('.css'))
     .map(file => {
       const name = file.name.replace('.css', '');
-      const metadata = THEME_METADATA[file.name] || {
-        description: `${name} theme`,
-        tags: []
-      };
+      const metadata = themesMeta[file.name] || defaultThemeMeta(name);
       
       return {
         name,
@@ -93,7 +82,7 @@ function generateThemes() {
         file: file.name,
         path: `templates/ui/themes/${file.name}`,
         defaultOutput: `src/themes/${file.name}`,
-        tags: metadata.tags,
+        tags: metadata.tags || [],
         features: ['dark-mode', 'tailwind-v4', 'spartan-ng', 'oklch']
       };
     });
@@ -106,11 +95,8 @@ function generateComponents() {
   return dirs
     .filter(dir => dir.isDirectory())
     .map(dir => {
-      const metadata = COMPONENT_METADATA[dir.name] || {
-        description: `${dir.name} component`,
-        tags: [],
-        dependencies: []
-      };
+      const componentDir = path.join(componentsDir, dir.name);
+      const metadata = readMeta(componentDir) || defaultComponentMeta(dir.name);
       
       return {
         name: dir.name,
@@ -126,27 +112,150 @@ function generateComponents() {
     });
 }
 
-function generateBlocks() {
+/**
+ * Convert filename to readable title
+ * e.g., 'sidebar-shell-footer.component.ts' -> 'Sidebar Shell Footer'
+ */
+function fileToTitle(filename) {
+  return filename
+    .replace('.component.ts', '')
+    .split('-')
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * Convert filename to id
+ * e.g., 'sidebar-shell-footer.component.ts' -> 'sidebar-footer'
+ */
+function fileToId(filename, blockName) {
+  const base = filename.replace('.component.ts', '');
+  // Remove block name prefix if present (e.g., 'sidebar-shell' -> 'sidebar')
+  return base.replace(`-${blockName}`, '').replace(`${blockName}-`, '');
+}
+
+/**
+ * Scan block directory for individual component files
+ */
+function scanBlockFiles(blockDir, blockName) {
+  const files = scanDirectory(blockDir);
+  
+  return files
+    .filter(file => file.isFile() && file.name.endsWith('.component.ts'))
+    .map(file => {
+      const id = fileToId(file.name, blockName);
+      const title = fileToTitle(file.name);
+      
+      return {
+        id,
+        file: file.name,
+        title,
+        description: title
+      };
+    })
+    .sort((a, b) => a.file.localeCompare(b.file));
+}
+
+function generateBlocks(includeFiles = false) {
   const blocksDir = path.join(TEMPLATES_DIR, 'ui/blocks');
   const dirs = scanDirectory(blocksDir);
   
   return dirs
     .filter(dir => dir.isDirectory())
     .map(dir => {
-      const metadata = BLOCK_METADATA[dir.name] || {
-        description: `${dir.name} block`,
-        tags: [dir.name],
-        dependencies: []
-      };
+      const blockDir = path.join(blocksDir, dir.name);
+      const metadata = readMeta(blockDir) || defaultBlockMeta(dir.name);
       
-      return {
+      const block = {
         name: dir.name,
-        title: dir.name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ') + ' Block',
+        title: dir.name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '),
         description: metadata.description,
         path: `templates/ui/blocks/${dir.name}`,
         defaultOutput: `src/app/blocks/${dir.name}`,
-        tags: metadata.tags,
-        dependencies: metadata.dependencies
+        tags: metadata.tags || [],
+        dependencies: metadata.dependencies || []
+      };
+      
+      // Include file-level details for catalog
+      if (includeFiles) {
+        block.files = scanBlockFiles(blockDir, dir.name);
+      }
+      
+      return block;
+    });
+}
+
+/**
+ * Generate catalog.json for themes (with features)
+ */
+function generateThemesForCatalog() {
+  const themesDir = path.join(TEMPLATES_DIR, 'ui/themes');
+  const files = scanDirectory(themesDir);
+  
+  // Read themes meta.json
+  const themesMeta = readMeta(themesDir) || {};
+  
+  return files
+    .filter(file => file.isFile() && file.name.endsWith('.css'))
+    .map(file => {
+      const name = file.name.replace('.css', '');
+      const metadata = themesMeta[file.name] || defaultThemeMeta(name);
+      
+      return {
+        name,
+        title: name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '),
+        description: metadata.description,
+        file: file.name,
+        tags: metadata.tags || [],
+        features: ['dark-mode', 'tailwind-v4', 'spartan-ng', 'oklch']
+      };
+    });
+}
+
+/**
+ * Generate catalog.json for components
+ */
+function generateComponentsForCatalog() {
+  const componentsDir = path.join(TEMPLATES_DIR, 'ui/components');
+  const dirs = scanDirectory(componentsDir);
+  
+  return dirs
+    .filter(dir => dir.isDirectory())
+    .map(dir => {
+      const componentDir = path.join(componentsDir, dir.name);
+      const metadata = readMeta(componentDir) || defaultComponentMeta(dir.name);
+      
+      return {
+        name: dir.name,
+        title: dir.name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '),
+        description: metadata.description,
+        tags: metadata.tags || [],
+        dependencies: metadata.dependencies || []
+      };
+    });
+}
+
+/**
+ * Generate catalog.json for blocks (with files)
+ */
+function generateBlocksForCatalog() {
+  const blocksDir = path.join(TEMPLATES_DIR, 'ui/blocks');
+  const dirs = scanDirectory(blocksDir);
+  
+  return dirs
+    .filter(dir => dir.isDirectory())
+    .map(dir => {
+      const blockDir = path.join(blocksDir, dir.name);
+      const metadata = readMeta(blockDir) || defaultBlockMeta(dir.name);
+      const files = scanBlockFiles(blockDir, dir.name);
+      
+      return {
+        name: dir.name,
+        title: dir.name.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '),
+        description: metadata.description,
+        tags: metadata.tags || [],
+        dependencies: metadata.dependencies,
+        files
       };
     });
 }
@@ -162,6 +271,7 @@ function generateResourcesFile() {
   console.log(`✓ Found ${components.length} components`);
   console.log(`✓ Found ${blocks.length} blocks`);
   
+  // Generate resources.js (static fallback for CLI)
   const output = `/**
  * Resource definitions for GRG Kit
  * This file is auto-generated from templates directory
@@ -180,10 +290,29 @@ module.exports = { RESOURCES, REPO };
   
   fs.writeFileSync(OUTPUT_FILE, output);
   console.log(`\n✅ Generated ${OUTPUT_FILE}`);
+  
+  // Generate catalog.json (dynamic, fetched at runtime)
+  const catalogThemes = generateThemesForCatalog();
+  const catalogComponents = generateComponentsForCatalog();
+  const catalogBlocks = generateBlocksForCatalog();
+  
+  const totalFiles = catalogBlocks.reduce((sum, b) => sum + (b.files?.length || 0), 0);
+  
+  const catalog = {
+    version: '1.0.0',
+    lastUpdated: new Date().toISOString().split('T')[0],
+    themes: catalogThemes,
+    components: catalogComponents,
+    blocks: catalogBlocks
+  };
+  
+  fs.writeFileSync(CATALOG_FILE, JSON.stringify(catalog, null, 2));
+  console.log(`✅ Generated ${CATALOG_FILE}`);
+  
   console.log('\n📦 Resource Summary:');
   console.log(`   Themes: ${themes.length}`);
   console.log(`   Components: ${components.length}`);
-  console.log(`   Blocks: ${blocks.length}`);
+  console.log(`   Blocks: ${blocks.length} (${totalFiles} files)`);
 }
 
 // Run the generator