ccsetup 1.1.1 → 1.2.0

package/lib/templates/README.md

@@ -0,0 +1,176 @@
+# Template Catalog System
+
+The template catalog system provides a powerful foundation for browsing, filtering, and selecting from ccsetup's collection of 50+ agent templates. This system implements Phase 1 of the template selection feature as outlined in PLAN-009.
+
+## Overview
+
+The template catalog system consists of:
+- **Metadata Extraction**: Automatically extracts metadata from agent frontmatter
+- **Template Catalog**: Provides filtering, search, and discovery capabilities  
+- **Category Management**: Organizes templates into logical categories
+- **Caching**: Efficient caching for fast template discovery
+
+## Components
+
+### MetadataExtractor (`metadata-extractor.js`)
+- Parses agent frontmatter to extract metadata
+- Automatically categorizes agents based on content analysis
+- Generates tags from descriptions and tools
+- Creates structured metadata JSON files
+
+### TemplateCatalog (`catalog.js`)
+- Template discovery and loading
+- Filtering by category, tags, and search queries
+- Template validation
+- Caching for performance
+
+### Generated Metadata (`metadata/agents.json`)
+- Contains metadata for all 52 agents
+- Organized by categories: Development, Backend, Planning, AI/ML, etc.
+- Includes tags, tools, examples, and workflows for each agent
+
+## Usage
+
+### Basic Catalog Operations
+```javascript
+const { TemplateCatalog } = require('./lib/templates');
+
+const catalog = new TemplateCatalog();
+
+// Load all templates
+const data = await catalog.load();
+
+// Get templates by category
+const planningAgents = await catalog.getTemplates('planning');
+const frontendAgents = await catalog.getTemplates('frontend');
+
+// Filter by tags
+const testingAgents = await catalog.getTemplates(null, ['testing']);
+
+// Search templates
+const reactAgents = await catalog.searchTemplates('react');
+
+// Get categories
+const categories = await catalog.getCategories();
+```
+
+### Template Filtering
+```javascript
+// Multiple filters can be combined
+const templates = await catalog.getTemplates(
+  'development',    // category
+  ['frontend', 'ui'], // tags
+  'react'           // search query
+);
+
+// Advanced search with options
+const results = await catalog.searchTemplates('API', {
+  category: 'backend',
+  tags: ['api'],
+  limit: 10,
+  sortBy: 'name'
+});
+```
+
+### Template Validation
+```javascript
+// Validate a template
+const validation = await catalog.validateTemplate(template);
+if (!validation.valid) {
+  console.log('Errors:', validation.errors);
+  console.log('Warnings:', validation.warnings);
+}
+```
+
+## Categories
+
+The system automatically categorizes agents into:
+
+- **Planning & Architecture** (8 agents) - Strategic planning and system design
+- **Development & Implementation** (26 agents) - Code implementation and development
+- **Frontend Development** (13 agents) - UI/UX and frontend frameworks
+- **Backend Development** (2 agents) - API design and server-side development
+- **Quality Assurance & Testing** (9 agents) - Testing and code review
+- **Security & Auditing** (5 agents) - Security analysis and auditing
+- **DevOps & Infrastructure** (2 agents) - Deployment and infrastructure
+- **Database & Data** (3 agents) - Database management and data analysis
+- **AI & Machine Learning** (5 agents) - AI/ML development and operations
+- **Mobile Development** (1 agent) - Mobile app development
+- **General Purpose** (4 agents) - Utility and general-purpose agents
+
+## Popular Tags
+
+Most common tags across all templates:
+- `development` (35 agents)
+- `implementation` (35 agents) 
+- `ml`, `ai` (19 agents each)
+- `performance` (19 agents)
+- `frontend`, `ui` (13 agents each)
+- `backend`, `api` (9 agents each)
+- `testing` (9 agents)
+
+## Scripts
+
+### Generate Metadata
+```bash
+npm run metadata:generate
+```
+Scans all agent templates and generates fresh metadata.
+
+### Test Catalog
+```bash
+npm run catalog:test
+```
+Runs comprehensive tests of catalog functionality.
+
+### Demo System
+```bash
+node scripts/demo-template-selection.js
+```
+Demonstrates browsing, filtering, and search capabilities.
+
+## Data Structure
+
+Each template has the following metadata:
+```json
+{
+  "id": "agent-planner",
+  "name": "Strategic Planner Agent",
+  "category": "agents",
+  "subcategory": "planning",
+  "description": "Strategic planning specialist...",
+  "tags": ["planning", "architecture", "roadmap"],
+  "tools": ["Read", "Grep", "Glob", "TodoWrite"],
+  "version": "1.0.0",
+  "dependencies": [],
+  "files": ["planner.md"],
+  "author": "ccsetup",
+  "examples": ["Breaking down feature implementations"],
+  "workflows": ["Feature Development", "Refactoring"]
+}
+```
+
+## Performance
+
+- **Caching**: 5-minute cache validity for fast repeated access
+- **Lazy Loading**: Metadata loaded only when needed
+- **Efficient Filtering**: Fast category and tag-based filtering
+- **Search Optimization**: Text search across name, description, tags, and examples
+
+## Future Enhancements
+
+Phase 1 provides the foundation for:
+- Interactive CLI template selection (Phase 2)
+- Browse command implementation (Phase 3)
+- Additional template categories (Phase 4)
+- Template marketplace features (Future)
+
+## Files
+
+- `metadata-extractor.js` - Extracts metadata from agent templates
+- `catalog.js` - Main catalog class with filtering and search
+- `index.js` - Public API exports
+- `metadata/agents.json` - Generated metadata for all agents
+- `README.md` - This documentation
+
+The template catalog system provides a robust foundation for the enhanced template selection system outlined in PLAN-009.

package/lib/templates/catalog.js

@@ -0,0 +1,230 @@
+const fs = require('fs');
+const path = require('path');
+const MetadataExtractor = require('./metadata-extractor');
+
+class TemplateCatalog {
+  constructor() {
+    this.cache = null;
+    this.cacheTimestamp = null;
+    this.cacheValidityMs = 5 * 60 * 1000; // 5 minutes
+  }
+  
+  async load(forceRefresh = false) {
+    if (!forceRefresh && this.isCacheValid()) {
+      return this.cache;
+    }
+    
+    try {
+      const metadataPath = path.join(__dirname, 'metadata/agents.json');
+      
+      if (fs.existsSync(metadataPath) && !forceRefresh) {
+        const content = fs.readFileSync(metadataPath, 'utf8');
+        this.cache = JSON.parse(content);
+        this.cacheTimestamp = Date.now();
+        return this.cache;
+      }
+      
+      console.log('Generating fresh catalog from agent templates...');
+      const catalog = MetadataExtractor.generateCatalogFromAgents();
+      
+      MetadataExtractor.saveCatalogToFile(catalog, metadataPath);
+      
+      this.cache = catalog;
+      this.cacheTimestamp = Date.now();
+      
+      return this.cache;
+    } catch (error) {
+      console.error('Error loading template catalog:', error.message);
+      
+      return {
+        agents: [],
+        categories: {},
+        stats: {
+          totalAgents: 0,
+          categories: 0,
+          lastUpdated: new Date().toISOString(),
+          error: error.message
+        }
+      };
+    }
+  }
+  
+  isCacheValid() {
+    return this.cache && 
+           this.cacheTimestamp && 
+           (Date.now() - this.cacheTimestamp) < this.cacheValidityMs;
+  }
+  
+  async getTemplates(category = null, tags = [], searchQuery = null) {
+    const catalog = await this.load();
+    let templates = catalog.agents || [];
+    
+    if (category && category !== 'all') {
+      if (category === 'agents') {
+        // Already filtered to agents
+      } else {
+        templates = templates.filter(t => t.subcategory === category);
+      }
+    }
+    
+    if (tags && tags.length > 0) {
+      templates = templates.filter(t => 
+        tags.some(tag => t.tags.includes(tag.toLowerCase()))
+      );
+    }
+    
+    if (searchQuery && searchQuery.trim()) {
+      const query = searchQuery.toLowerCase().trim();
+      templates = templates.filter(t => {
+        const searchableText = [
+          t.name,
+          t.description,
+          ...t.tags,
+          ...t.examples
+        ].join(' ').toLowerCase();
+        
+        return searchableText.includes(query);
+      });
+    }
+    
+    return templates;
+  }
+  
+  async getTemplate(id) {
+    const catalog = await this.load();
+    return catalog.agents.find(agent => agent.id === id);
+  }
+  
+  async getCategories() {
+    const catalog = await this.load();
+    return catalog.categories || {};
+  }
+  
+  async getStats() {
+    const catalog = await this.load();
+    return catalog.stats || {};
+  }
+  
+  async searchTemplates(query, options = {}) {
+    const {
+      category = null,
+      tags = [],
+      limit = 50,
+      sortBy = 'name'
+    } = options;
+    
+    let templates = await this.getTemplates(category, tags, query);
+    
+    if (sortBy === 'name') {
+      templates.sort((a, b) => a.name.localeCompare(b.name));
+    } else if (sortBy === 'category') {
+      templates.sort((a, b) => {
+        const categoryCompare = a.subcategory.localeCompare(b.subcategory);
+        return categoryCompare !== 0 ? categoryCompare : a.name.localeCompare(b.name);
+      });
+    }
+    
+    return templates.slice(0, limit);
+  }
+  
+  async validateTemplate(template) {
+    const requiredFields = ['id', 'name', 'category', 'description'];
+    const validation = {
+      valid: true,
+      errors: [],
+      warnings: []
+    };
+    
+    for (const field of requiredFields) {
+      if (!template[field]) {
+        validation.valid = false;
+        validation.errors.push(`Missing required field: ${field}`);
+      }
+    }
+    
+    if (template.category !== 'agents') {
+      validation.warnings.push(`Unexpected category: ${template.category}`);
+    }
+    
+    if (!template.files || template.files.length === 0) {
+      validation.valid = false;
+      validation.errors.push('Template must specify at least one file');
+    }
+    
+    if (template.files) {
+      const templateDir = path.join(__dirname, '../../template/.claude/agents');
+      for (const file of template.files) {
+        const filePath = path.join(templateDir, file);
+        if (!fs.existsSync(filePath)) {
+          validation.valid = false;
+          validation.errors.push(`Template file not found: ${file}`);
+        }
+      }
+    }
+    
+    if (!template.tags || template.tags.length === 0) {
+      validation.warnings.push('Template has no tags - may be hard to discover');
+    }
+    
+    return validation;
+  }
+  
+  async refreshCatalog() {
+    console.log('Refreshing template catalog...');
+    
+    const catalog = MetadataExtractor.generateCatalogFromAgents();
+    const metadataPath = path.join(__dirname, 'metadata/agents.json');
+    
+    const saved = MetadataExtractor.saveCatalogToFile(catalog, metadataPath);
+    
+    if (saved) {
+      this.cache = catalog;
+      this.cacheTimestamp = Date.now();
+      console.log(`Catalog refreshed: ${catalog.stats.totalAgents} agents processed`);
+      return catalog;
+    } else {
+      throw new Error('Failed to save refreshed catalog');
+    }
+  }
+  
+  async getCatalogBySubcategory() {
+    const catalog = await this.load();
+    const result = {};
+    
+    for (const agent of catalog.agents) {
+      if (!result[agent.subcategory]) {
+        result[agent.subcategory] = [];
+      }
+      result[agent.subcategory].push(agent);
+    }
+    
+    Object.keys(result).forEach(category => {
+      result[category].sort((a, b) => a.name.localeCompare(b.name));
+    });
+    
+    return result;
+  }
+  
+  async getTagCloud() {
+    const catalog = await this.load();
+    const tagCounts = {};
+    
+    for (const agent of catalog.agents) {
+      for (const tag of agent.tags) {
+        tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+      }
+    }
+    
+    const sortedTags = Object.entries(tagCounts)
+      .sort((a, b) => b[1] - a[1])
+      .map(([tag, count]) => ({ tag, count }));
+    
+    return sortedTags;
+  }
+  
+  static createInstance() {
+    return new TemplateCatalog();
+  }
+}
+
+module.exports = TemplateCatalog;

package/lib/templates/filter.js

@@ -0,0 +1,257 @@
+class TemplateFilter {
+  constructor(templates = []) {
+    this.templates = templates;
+  }
+  
+  setTemplates(templates) {
+    this.templates = templates;
+    return this;
+  }
+  
+  byCategory(category) {
+    if (!category || category === 'all') {
+      return new TemplateFilter(this.templates);
+    }
+    
+    const filtered = this.templates.filter(template => {
+      if (category === 'agents') {
+        return template.category === 'agents';
+      }
+      return template.subcategory === category;
+    });
+    
+    return new TemplateFilter(filtered);
+  }
+  
+  byTags(tags) {
+    if (!tags || tags.length === 0) {
+      return new TemplateFilter(this.templates);
+    }
+    
+    const normalizedTags = tags.map(tag => tag.toLowerCase());
+    const filtered = this.templates.filter(template => {
+      if (!template.tags || template.tags.length === 0) {
+        return false;
+      }
+      
+      return normalizedTags.some(tag => 
+        template.tags.some(templateTag => 
+          templateTag.toLowerCase().includes(tag)
+        )
+      );
+    });
+    
+    return new TemplateFilter(filtered);
+  }
+  
+  byExactTags(tags) {
+    if (!tags || tags.length === 0) {
+      return new TemplateFilter(this.templates);
+    }
+    
+    const normalizedTags = tags.map(tag => tag.toLowerCase());
+    const filtered = this.templates.filter(template => {
+      if (!template.tags || template.tags.length === 0) {
+        return false;
+      }
+      
+      return normalizedTags.every(tag => 
+        template.tags.some(templateTag => 
+          templateTag.toLowerCase() === tag
+        )
+      );
+    });
+    
+    return new TemplateFilter(filtered);
+  }
+  
+  byAnyTag(tags) {
+    if (!tags || tags.length === 0) {
+      return new TemplateFilter(this.templates);
+    }
+    
+    const normalizedTags = tags.map(tag => tag.toLowerCase());
+    const filtered = this.templates.filter(template => {
+      if (!template.tags || template.tags.length === 0) {
+        return false;
+      }
+      
+      return normalizedTags.some(tag => 
+        template.tags.some(templateTag => 
+          templateTag.toLowerCase() === tag
+        )
+      );
+    });
+    
+    return new TemplateFilter(filtered);
+  }
+  
+  byAllTags(tags) {
+    if (!tags || tags.length === 0) {
+      return new TemplateFilter(this.templates);
+    }
+    
+    const normalizedTags = tags.map(tag => tag.toLowerCase());
+    const filtered = this.templates.filter(template => {
+      if (!template.tags || template.tags.length === 0) {
+        return false;
+      }
+      
+      return normalizedTags.every(tag => 
+        template.tags.some(templateTag => 
+          templateTag.toLowerCase() === tag
+        )
+      );
+    });
+    
+    return new TemplateFilter(filtered);
+  }
+  
+  combine(filters = {}) {
+    let result = this.templates;
+    
+    if (filters.category) {
+      result = new TemplateFilter(result).byCategory(filters.category).getResults();
+    }
+    
+    if (filters.tags && filters.tags.length > 0) {
+      const tagMode = filters.tagMode || 'any';
+      if (tagMode === 'all') {
+        result = new TemplateFilter(result).byAllTags(filters.tags).getResults();
+      } else if (tagMode === 'exact') {
+        result = new TemplateFilter(result).byExactTags(filters.tags).getResults();
+      } else {
+        result = new TemplateFilter(result).byAnyTag(filters.tags).getResults();
+      }
+    }
+    
+    if (filters.subcategories && filters.subcategories.length > 0) {
+      result = result.filter(template => 
+        filters.subcategories.includes(template.subcategory)
+      );
+    }
+    
+    return new TemplateFilter(result);
+  }
+  
+  getResults() {
+    return [...this.templates];
+  }
+  
+  getCount() {
+    return this.templates.length;
+  }
+  
+  getCategories() {
+    const categories = new Set();
+    this.templates.forEach(template => {
+      if (template.category) {
+        categories.add(template.category);
+      }
+    });
+    return Array.from(categories).sort();
+  }
+  
+  getSubcategories() {
+    const subcategories = new Set();
+    this.templates.forEach(template => {
+      if (template.subcategory) {
+        subcategories.add(template.subcategory);
+      }
+    });
+    return Array.from(subcategories).sort();
+  }
+  
+  getAllTags() {
+    const tags = new Set();
+    this.templates.forEach(template => {
+      if (template.tags && Array.isArray(template.tags)) {
+        template.tags.forEach(tag => tags.add(tag.toLowerCase()));
+      }
+    });
+    return Array.from(tags).sort();
+  }
+  
+  getTagsByFrequency() {
+    const tagCounts = {};
+    this.templates.forEach(template => {
+      if (template.tags && Array.isArray(template.tags)) {
+        template.tags.forEach(tag => {
+          const normalizedTag = tag.toLowerCase();
+          tagCounts[normalizedTag] = (tagCounts[normalizedTag] || 0) + 1;
+        });
+      }
+    });
+    
+    return Object.entries(tagCounts)
+      .sort((a, b) => b[1] - a[1])
+      .map(([tag, count]) => ({ tag, count }));
+  }
+  
+  sortBy(field, direction = 'asc') {
+    const sorted = [...this.templates].sort((a, b) => {
+      let valueA = a[field];
+      let valueB = b[field];
+      
+      if (typeof valueA === 'string' && typeof valueB === 'string') {
+        valueA = valueA.toLowerCase();
+        valueB = valueB.toLowerCase();
+      }
+      
+      if (valueA < valueB) {
+        return direction === 'asc' ? -1 : 1;
+      }
+      if (valueA > valueB) {
+        return direction === 'asc' ? 1 : -1;
+      }
+      return 0;
+    });
+    
+    return new TemplateFilter(sorted);
+  }
+  
+  limit(count) {
+    return new TemplateFilter(this.templates.slice(0, count));
+  }
+  
+  offset(count) {
+    return new TemplateFilter(this.templates.slice(count));
+  }
+  
+  paginate(page, pageSize) {
+    const start = (page - 1) * pageSize;
+    const end = start + pageSize;
+    return new TemplateFilter(this.templates.slice(start, end));
+  }
+  
+  isEmpty() {
+    return this.templates.length === 0;
+  }
+  
+  first() {
+    return this.templates.length > 0 ? this.templates[0] : null;
+  }
+  
+  last() {
+    return this.templates.length > 0 ? this.templates[this.templates.length - 1] : null;
+  }
+  
+  find(predicate) {
+    return this.templates.find(predicate);
+  }
+  
+  some(predicate) {
+    return this.templates.some(predicate);
+  }
+  
+  every(predicate) {
+    return this.templates.every(predicate);
+  }
+  
+  static createFromCatalog(catalog) {
+    const templates = catalog?.agents || [];
+    return new TemplateFilter(templates);
+  }
+}
+
+module.exports = TemplateFilter;

package/lib/templates/index.js

@@ -0,0 +1,45 @@
+const TemplateCatalog = require('./catalog');
+const MetadataExtractor = require('./metadata-extractor');
+const TemplateFilter = require('./filter');
+const TemplateSearch = require('./search');
+
+module.exports = {
+  TemplateCatalog,
+  MetadataExtractor,
+  TemplateFilter,
+  TemplateSearch,
+  
+  async createCatalog() {
+    return TemplateCatalog.createInstance();
+  },
+  
+  async refreshCatalog() {
+    const catalog = TemplateCatalog.createInstance();
+    return await catalog.refreshCatalog();
+  },
+  
+  async getCatalogStats() {
+    const catalog = TemplateCatalog.createInstance();
+    return await catalog.getStats();
+  },
+  
+  createFilter(templates) {
+    return new TemplateFilter(templates);
+  },
+  
+  createSearch(templates) {
+    return new TemplateSearch(templates);
+  },
+  
+  async searchTemplates(query, options = {}) {
+    const catalog = TemplateCatalog.createInstance();
+    const templates = await catalog.load();
+    return new TemplateSearch(templates.agents || []).search(query, options);
+  },
+  
+  async filterTemplates(filters = {}) {
+    const catalog = TemplateCatalog.createInstance();
+    const templates = await catalog.load();
+    return new TemplateFilter(templates.agents || []).combine(filters);
+  }
+};