claude-code-templates 1.21.13 → 1.21.14

package/docs/CLAUDE.md

@@ -0,0 +1,363 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This directory contains the static website (aitmpl.com) that serves as the public web interface for browsing and installing Claude Code components. The site is a vanilla JavaScript application that loads component data dynamically and provides an interactive browsing experience for 500+ components including agents, commands, settings, hooks, MCPs, and templates.
+
+## Development Commands
+
+### Local Development
+```bash
+# Serve locally with any static file server
+python -m http.server 8000
+# or
+npx http-server
+
+# Open browser to http://localhost:8000
+```
+
+### Component Data Generation
+```bash
+# From project root - regenerate components.json
+cd ..
+python generate_components_json.py
+
+# This creates/updates docs/components.json with all components
+```
+
+### Deployment
+- Site is automatically deployed to GitHub Pages when changes are pushed to `docs/` directory
+- Deployed at: https://aitmpl.com (davila7.github.io/claude-code-templates)
+- Vercel configuration in `vercel.json` for routing
+
+## Architecture
+
+### Data Flow
+1. **Component Generation**: Python script (`generate_components_json.py`) scans `cli-tool/components/` and generates `docs/components.json` (~2MB file with embedded content)
+2. **Static Loading**: Website loads `components.json` on page load (with mobile optimization and progress indicators)
+3. **Dynamic Rendering**: JavaScript renders component cards based on user filters and search
+4. **Download Tracking**: Supabase integration tracks component installations via backend API
+
+### Key Files
+
+#### HTML Pages
+- `index.html` - Main page with component browser and search
+- `component.html` - Individual component detail pages
+- `plugin.html` - Plugin marketplace interface
+- `trending.html` - Trending components dashboard
+- `download-stats.html` - Analytics and download statistics
+
+#### JavaScript Architecture (`js/`)
+- `data-loader.js` - Loads and caches components.json, handles data fetching
+- `search-functionality.js` - Real-time search across all components with fuzzy matching
+- `cart-manager.js` - Shopping cart for batch component installation
+- `stack-router.js` - Client-side routing for company stacks and plugins
+- `index-events.js` - Event handlers for filters, modals, and user interactions
+- `plugin-page.js` - Plugin marketplace functionality
+- `trending.js` - Trending components data visualization
+
+#### CSS (`css/`)
+- Modular CSS with separate files for components, modals, responsive design
+- Terminal-themed design system with monospace fonts and CLI aesthetics
+
+#### Data Files
+- `components.json` - Main component catalog (~2MB, generated file)
+- `trending-data.json` - Trending components rankings
+- `claude-jobs.json` - Job postings data
+
+### Component System
+
+#### Component Types
+Each component type has specific structure:
+
+**Agents** (162 total)
+- AI specialists organized by category (Development, Data/AI, Security, Business, etc.)
+- Stored in `cli-tool/components/agents/{category}/{name}.md`
+- Installation: `--agent <name>`
+
+**Commands** (210 total)
+- Custom slash commands organized by category
+- Stored in `cli-tool/components/commands/{category}/{name}.md`
+- Installation: `--command <name>`
+
+**Settings** (60 total)
+- Claude Code configuration files
+- Includes statuslines with accompanying Python scripts
+- Stored in `cli-tool/components/settings/{category}/{name}.json`
+- Installation: `--setting <name>`
+
+**Hooks** (39 total)
+- Event-driven automation triggers
+- Stored in `cli-tool/components/hooks/{category}/{name}.md`
+- Installation: `--hook <name>`
+
+**MCPs** (55 total)
+- Model Context Protocol integrations
+- Stored in `cli-tool/components/mcps/{name}.json`
+- Installation: `--mcp <name>`
+
+**Templates** (14 total)
+- Complete project configurations
+- Organized by language and framework in `cli-tool/templates/`
+- Installation: `--template <language>`
+
+**Plugins** (10 total)
+- Component bundles with marketplace metadata
+- Defined in `.claude-plugin/marketplace.json`
+- Installation: `--plugin <name>`
+
+### Data Loading Strategy
+
+The site implements a multi-stage loading strategy for optimal mobile performance:
+
+1. **Initial Load**: Show loading indicator with progress bar
+2. **Lazy Parsing**: Load components.json in chunks to avoid blocking
+3. **Progressive Rendering**: Render visible cards first, lazy-load others
+4. **Search Indexing**: Build search index in background
+5. **Caching**: LocalStorage caching for repeat visits
+
+### Search Functionality
+
+Real-time search across all components:
+- **Fuzzy Matching**: Tolerates typos and partial matches
+- **Multi-field Search**: Searches name, description, category, type
+- **Filter Integration**: Combines with type filters (agents/commands/etc)
+- **Category Filtering**: Dynamic category chips based on active filter
+- **Sorting**: Alphabetical or by download count
+
+### Shopping Cart System
+
+Batch installation builder:
+- Add multiple components across types (agents, commands, settings, hooks, MCPs)
+- Generates single NPX command for installation
+- Supports sharing cart via URL parameters
+- Social sharing to Twitter/Threads
+
+### Plugin Marketplace
+
+Plugin system for component bundles:
+- Each plugin contains agents, commands, and MCPs
+- Defined in marketplace.json with metadata
+- Installation installs all plugin components
+- Examples: `supabase-toolkit`, `nextjs-vercel-pro`, `ai-ml-toolkit`
+
+### Download Analytics
+
+Supabase-powered analytics:
+- Tracks component installations via API endpoints
+- Aggregates download counts by component and type
+- Displays trending components and download stats
+- Real-time updates with background refresh
+
+## Important Implementation Patterns
+
+### Component Data Structure
+
+```javascript
+// components.json structure
+{
+  "agents": [{
+    "name": "agent-name",
+    "category": "category-name",
+    "content": "Full markdown content...",
+    "path": "agents/category/agent-name.md",
+    "url": "https://github.com/..."
+  }],
+  "commands": [...],
+  "mcps": [...],
+  "settings": [...],
+  "hooks": [...],
+  "templates": [...],
+  "plugins": [...]
+}
+```
+
+### Dynamic Component Loading
+
+```javascript
+// Loading pattern from data-loader.js
+async function loadAllComponentsData() {
+  const response = await fetch('components.json');
+  const data = await response.json();
+  componentsData = data;
+  collectAvailableCategories();
+  generateUnifiedComponentCards();
+}
+```
+
+### Filter and Category System
+
+```javascript
+// Current filter state
+let currentFilter = 'agents'; // or 'commands', 'mcps', etc.
+let currentCategoryFilter = 'all'; // or specific category
+
+// Update filters
+function handleFilterClick(event, filter) {
+  currentFilter = filter;
+  updateCategorySubFilters();
+  generateUnifiedComponentCards();
+}
+```
+
+### Installation Command Generation
+
+```javascript
+// Pattern from cart-manager.js
+function generateCartCommand(cart) {
+  const flags = [];
+  if (cart.agents.length) flags.push(...cart.agents.map(a => `--agent ${a}`));
+  if (cart.commands.length) flags.push(...cart.commands.map(c => `--command ${c}`));
+  // ... other types
+  return `npx claude-code-templates@latest ${flags.join(' ')} --yes`;
+}
+```
+
+## File Generation Workflow
+
+### Updating Component Catalog
+
+When components are added/modified in `cli-tool/components/`:
+
+1. Run component generation script:
+   ```bash
+   cd /path/to/project/root
+   python generate_components_json.py
+   ```
+
+2. This script:
+   - Scans all directories in `cli-tool/components/`
+   - Scans all templates in `cli-tool/templates/`
+   - Fetches download stats from Supabase
+   - Embeds file content inline
+   - Excludes Python scripts from public listings (but includes them as dependencies)
+   - Generates `docs/components.json`
+
+3. Commit changes:
+   ```bash
+   git add docs/components.json
+   git commit -m "Update component catalog"
+   ```
+
+### Testing Locally
+
+Before committing:
+1. Serve site locally: `python -m http.server 8000`
+2. Test component loading and search
+3. Verify filter functionality
+4. Check responsive design on mobile
+5. Test cart and installation command generation
+
+## SEO and Metadata
+
+### Structured Data
+- Schema.org markup for SoftwareApplication
+- Open Graph tags for social sharing
+- Twitter Card metadata
+- Sitemap.xml for search engines
+
+### Performance Optimization
+- Cache-busting query parameters for dynamic content
+- Progressive loading for large JSON files
+- LocalStorage caching for repeat visits
+- Lazy loading for images and components below fold
+
+## External Integrations
+
+### GitHub API
+- Fetches component files dynamically (legacy, now uses components.json)
+- Links to source files on GitHub
+
+### Supabase
+- Tracks component downloads
+- Aggregates download statistics
+- Powers trending components
+
+### Vercel
+- Handles routing for SPA-style URLs
+- Configured in `vercel.json`
+
+### Analytics
+- Hotjar for user behavior tracking
+- Counter.dev for page view analytics
+
+## Deployment Checklist
+
+Before deploying to production:
+
+1. **Component Data**: Run `python generate_components_json.py` to update components.json
+2. **Test Locally**: Verify all pages load correctly
+3. **Check Links**: Ensure GitHub links point to correct paths
+4. **Verify Search**: Test search functionality with various queries
+5. **Mobile Testing**: Check responsive design on multiple devices
+6. **Cart Testing**: Verify installation commands are generated correctly
+7. **Analytics**: Confirm tracking is working
+
+## Common Development Tasks
+
+### Adding New Component Type
+
+1. Update `generate_components_json.py` to scan new component directory
+2. Add new filter button in `index.html`
+3. Add icon configuration in `js/script.js` typeConfig
+4. Update cart-manager.js to handle new type
+5. Regenerate components.json
+
+### Modifying Search Behavior
+
+Edit `js/search-functionality.js`:
+- `performSearch()` - Main search logic
+- `fuzzyMatch()` - Matching algorithm
+- `highlightMatches()` - Result highlighting
+
+### Updating Styles
+
+CSS is modular:
+- `css/styles.css` - Main styles and variables
+- `css/components.css` - Component cards and grid
+- `css/responsive.css` - Mobile breakpoints
+- `css/modals.css` - Modal dialogs
+- `css/cart.css` - Shopping cart sidebar
+
+## Browser Compatibility
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- ES6+ JavaScript features (Fetch API, async/await, template literals)
+- CSS Grid and Flexbox for layout
+- No build step required (vanilla JavaScript)
+
+## Performance Considerations
+
+### Large File Handling
+- `components.json` is ~2MB - implement progressive loading
+- Use virtual scrolling for large component lists
+- Debounce search input to avoid excessive filtering
+- Cache parsed JSON in memory after initial load
+
+### Mobile Optimization
+- Lazy load images and component content
+- Reduce initial bundle size
+- Minimize re-renders during search/filter
+- Use CSS animations sparingly
+
+## Troubleshooting
+
+### Components Not Loading
+- Check browser console for fetch errors
+- Verify components.json is accessible
+- Ensure CORS is properly configured
+- Check GitHub API rate limits (if using legacy loading)
+
+### Search Not Working
+- Verify search index is built correctly
+- Check fuzzy match threshold in search-functionality.js
+- Ensure component data includes searchable fields
+
+### Cart Not Saving
+- Check LocalStorage is enabled
+- Verify cart data structure matches expected format
+- Clear cache and reload if data structure changed
+
+This website serves as the primary user interface for the Claude Code Templates ecosystem, providing an intuitive way to discover and install 500+ components through a terminal-themed, responsive web interface.

package/docs/api/README.md

@@ -0,0 +1,297 @@
+# API Directory - Documentation
+
+This directory contains both **static files** and **serverless functions** for the Claude Code Templates project deployed on Vercel.
+
+## 📁 Structure Overview
+
+```
+docs/api/
+├── README.md                      # This file
+├── agents.json                    # Static JSON file for agent queries
+├── package.json                   # Dependencies for serverless functions
+└── track-download-supabase.js     # Serverless function for download tracking
+```
+
+## 🔍 Why This Structure?
+
+The project is configured with `"outputDirectory": "docs"` in `vercel.json`, which means:
+- Vercel serves **all content from the `/docs/` directory**
+- Serverless functions must be located at `/docs/api/` to be recognized
+- Static files are also served from this same directory
+
+### Original Structure (Before Fix)
+
+Previously, there were **two separate API directories**:
+
+```
+/api/                              # ❌ Not detected by Vercel
+├── track-download-supabase.js     # Serverless function (404 error)
+└── package.json
+
+/docs/api/                         # ✅ Served correctly
+└── agents.json                    # Static file
+```
+
+**Problem:** The serverless function in `/api/` was not being detected by Vercel because the `outputDirectory` was set to `docs`, causing 404 errors when trying to track downloads.
+
+### Current Structure (After Fix)
+
+```
+/docs/api/                         # ✅ Everything in one place
+├── agents.json                    # Static file for queries
+├── track-download-supabase.js     # Serverless function for tracking
+└── package.json                   # Dependencies
+```
+
+**Solution:** All API-related files (both static and serverless) are now in `/docs/api/`, ensuring Vercel can find and execute them correctly.
+
+---
+
+## 📄 File Descriptions
+
+### 1. `agents.json` (Static File)
+- **Type:** Static JSON data
+- **Purpose:** Contains the list of available agents for the frontend
+- **Accessed by:** Frontend application via fetch/axios
+- **URL:** `https://www.aitmpl.com/api/agents.json`
+- **Size:** ~25KB
+- **Updates:** Generated by `generate_components_json.py` script
+
+**Usage:**
+```javascript
+fetch('https://www.aitmpl.com/api/agents.json')
+  .then(res => res.json())
+  .then(data => console.log(data));
+```
+
+---
+
+### 2. `track-download-supabase.js` (Serverless Function)
+- **Type:** Vercel Serverless Function (Edge Function)
+- **Purpose:** Tracks component downloads and stores them in Supabase
+- **Runtime:** Node.js with ES Modules
+- **HTTP Method:** POST
+- **URL:** `https://www.aitmpl.com/api/track-download-supabase`
+
+**Environment Variables Required:**
+- `SUPABASE_URL` - Your Supabase project URL
+- `SUPABASE_SERVICE_ROLE_KEY` - Supabase service role key (with write permissions)
+
+**Request Payload:**
+```json
+{
+  "type": "agent",
+  "name": "frontend-developer",
+  "path": "agents/development/frontend-developer",
+  "category": "development",
+  "cliVersion": "1.20.2"
+}
+```
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "message": "Download tracked successfully",
+  "data": {
+    "type": "agent",
+    "name": "frontend-developer",
+    "timestamp": "2025-10-12T13:00:00.000Z"
+  }
+}
+```
+
+**Response (Error):**
+```json
+{
+  "error": "Internal server error",
+  "message": "Failed to track download"
+}
+```
+
+**Database Tables:**
+- `component_downloads` - Individual download records
+- `download_stats` - Aggregated statistics
+
+**Called by:** `cli-tool/src/tracking-service.js` when components are installed
+
+---
+
+### 3. `package.json` (Dependencies)
+- **Type:** NPM package configuration
+- **Purpose:** Defines dependencies for serverless functions
+- **Key Dependencies:**
+  - `@supabase/supabase-js` - Supabase client library
+  - `@vercel/postgres` - PostgreSQL client for Vercel
+
+---
+
+## 🚀 Deployment Process
+
+### Prerequisites
+1. Ensure environment variables are set in Vercel dashboard:
+   - `SUPABASE_URL`
+   - `SUPABASE_SERVICE_ROLE_KEY`
+
+### Automatic Deployment
+When you push to the `main` branch, Vercel automatically:
+1. Detects changes in `/docs/`
+2. Installs dependencies from `/docs/api/package.json`
+3. Deploys serverless functions from `/docs/api/*.js`
+4. Serves static files from `/docs/`
+
+### Manual Deployment
+```bash
+# From project root
+cd docs
+vercel --prod
+
+# Or using Vercel CLI
+vercel deploy --prod
+```
+
+### Testing After Deployment
+```bash
+# Test serverless function
+curl -X POST https://www.aitmpl.com/api/track-download-supabase \
+  -H "Content-Type: application/json" \
+  -d '{"type":"agent","name":"test","path":"test","category":"test","cliVersion":"1.0.0"}'
+
+# Test static file
+curl https://www.aitmpl.com/api/agents.json
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Issue: 404 Error on API Endpoint
+**Symptom:** `/api/track-download-supabase` returns 404
+
+**Possible Causes:**
+1. File not in `/docs/api/` directory
+2. File has incorrect export format
+3. Vercel environment variables not set
+4. Deploy not completed
+
+**Solution:**
+```bash
+# Verify file exists
+ls -la docs/api/track-download-supabase.js
+
+# Check Vercel logs
+vercel logs [deployment-url]
+
+# Redeploy
+vercel --prod
+```
+
+### Issue: Function Times Out
+**Symptom:** Request takes too long and times out
+
+**Possible Causes:**
+1. Supabase connection issues
+2. Database performance problems
+3. Network latency
+
+**Solution:**
+- Check Supabase status dashboard
+- Verify database indexes exist
+- Review function timeout settings in Vercel
+
+### Issue: Data Not Saving
+**Symptom:** API returns 200 but data doesn't appear in Supabase
+
+**Possible Causes:**
+1. Wrong environment variables
+2. Insufficient permissions on service role key
+3. Table schema mismatch
+
+**Solution:**
+```javascript
+// Enable debug mode in tracking-service.js
+process.env.CCT_DEBUG = 'true'
+
+// Check logs in Vercel dashboard
+```
+
+---
+
+## 📊 Monitoring
+
+### Vercel Analytics
+- View function execution logs in Vercel dashboard
+- Monitor function performance and errors
+- Track deployment history
+
+### Supabase Analytics
+- View download statistics in Supabase dashboard
+- Query `component_downloads` table directly
+- Use `download_stats` for aggregated data
+
+### CLI Debug Mode
+Enable debug mode to see tracking requests:
+```bash
+export CCT_DEBUG=true
+npx claude-code-templates@latest --agent frontend-developer
+```
+
+---
+
+## 🔄 Maintenance
+
+### Updating the Serverless Function
+1. Edit `/api/track-download-supabase.js` (source of truth)
+2. Copy changes to `/docs/api/track-download-supabase.js`
+3. Test locally if possible
+4. Commit and push changes
+5. Verify deployment in Vercel dashboard
+
+### Updating Dependencies
+1. Edit `/docs/api/package.json`
+2. Commit changes
+3. Vercel will automatically install on next deployment
+
+### Syncing Files
+If you update `/api/track-download-supabase.js`, remember to sync:
+```bash
+cp api/track-download-supabase.js docs/api/
+cp api/package.json docs/api/
+git add docs/api/
+git commit -m "Sync API changes to docs/api"
+```
+
+---
+
+## 📝 Best Practices
+
+1. **Keep Both Directories in Sync:** If you modify `/api/`, copy changes to `/docs/api/`
+2. **Test Before Deploy:** Use debug mode to test tracking locally
+3. **Monitor Logs:** Check Vercel logs after deployment
+4. **Version Control:** Always commit both directories together
+5. **Environment Variables:** Never commit sensitive keys
+
+---
+
+## 🔗 Related Files
+
+- `/vercel.json` - Vercel configuration (defines `outputDirectory: "docs"`)
+- `/cli-tool/src/tracking-service.js` - Client-side tracking implementation
+- `/generate_components_json.py` - Generates `agents.json`
+- `/api/` - Original API directory (keep as source of truth)
+
+---
+
+## 📞 Support
+
+If you encounter issues with the API:
+1. Check Vercel deployment logs
+2. Verify environment variables in Vercel dashboard
+3. Test endpoints manually with curl
+4. Review Supabase logs for database errors
+5. Enable debug mode in CLI for detailed tracking logs
+
+---
+
+**Last Updated:** October 12, 2025
+**Maintained by:** Claude Code Templates Team

package/docs/api/package.json

@@ -0,0 +1,7 @@
+{
+  "type": "module",
+  "dependencies": {
+    "@vercel/postgres": "^0.10.0",
+    "@supabase/supabase-js": "^2.45.0"
+  }
+}