@claudetools/tools 0.4.0 → 0.5.0

package/dist/helpers/usage-analytics.js

@@ -0,0 +1,256 @@
+// =============================================================================
+// CodeDNA Usage Analytics
+// =============================================================================
+//
+// Track CodeDNA usage patterns, token savings, and generator popularity
+// for analytics and optimization insights.
+//
+import { storeFact, searchMemory } from './api-client.js';
+import { DEFAULT_USER_ID, resolveProjectId } from './config.js';
+export class UsageAnalytics {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!UsageAnalytics.instance) {
+            UsageAnalytics.instance = new UsageAnalytics();
+        }
+        return UsageAnalytics.instance;
+    }
+    /**
+     * Track a successful generation
+     */
+    async trackGeneration(event) {
+        try {
+            const usageEvent = {
+                ...event,
+                timestamp: new Date().toISOString(),
+                success: true,
+            };
+            const userId = DEFAULT_USER_ID;
+            const projectId = event.projectId || resolveProjectId();
+            // Store as fact in memory system
+            await storeFact(projectId, 'CodeDNA', 'GENERATION_COMPLETED', event.generator || event.operation, JSON.stringify(usageEvent), userId);
+            console.log('[CodeDNA Analytics]', {
+                operation: event.operation,
+                generator: event.generator,
+                tokensSaved: event.tokensSaved,
+            });
+        }
+        catch (error) {
+            // Don't fail the operation if analytics fails
+            console.error('[CodeDNA Analytics Failed]', error);
+        }
+    }
+    /**
+     * Track a validation
+     */
+    async trackValidation(spec, valid, entityName, fieldCount, projectId) {
+        await this.trackGeneration({
+            operation: 'validate_spec',
+            entityName,
+            fieldCount,
+            specLength: spec.length,
+            success: valid,
+            projectId,
+        });
+    }
+}
+// Export singleton instance
+export const analytics = UsageAnalytics.getInstance();
+/**
+ * Query usage analytics
+ */
+export async function getUsageAnalytics(query) {
+    const userId = DEFAULT_USER_ID;
+    const projectId = resolveProjectId();
+    // Search for usage facts
+    const searchQuery = `CodeDNA GENERATION_COMPLETED ${query.operation || ''}`;
+    const result = await searchMemory(projectId, searchQuery, 500, userId);
+    // Parse usage events from facts
+    const events = result.relevant_facts
+        .map((fact) => {
+        try {
+            return JSON.parse(fact.fact);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e !== null)
+        .filter((e) => {
+        const eventTime = new Date(e.timestamp).getTime();
+        const start = new Date(query.startTime).getTime();
+        const end = new Date(query.endTime).getTime();
+        return eventTime >= start && eventTime <= end;
+    })
+        .filter((e) => !query.operation || e.operation === query.operation)
+        .filter((e) => !query.generator || e.generator === query.generator)
+        .filter((e) => !query.framework || e.framework === query.framework);
+    // Calculate statistics
+    const totalTokensSaved = events.reduce((sum, e) => sum + (e.tokensSaved || 0), 0);
+    const totalLinesOfCode = events.reduce((sum, e) => sum + (e.linesOfCode || 0), 0);
+    const totalFiles = events.reduce((sum, e) => sum + (e.filesGenerated || 0), 0);
+    // Generator statistics
+    const generatorStats = {};
+    events.forEach(event => {
+        const gen = event.generator || 'unknown';
+        if (!generatorStats[gen]) {
+            generatorStats[gen] = { count: 0, tokensSaved: 0, linesOfCode: 0, filesGenerated: 0 };
+        }
+        generatorStats[gen].count++;
+        generatorStats[gen].tokensSaved += event.tokensSaved || 0;
+        generatorStats[gen].linesOfCode += event.linesOfCode || 0;
+        generatorStats[gen].filesGenerated += event.filesGenerated || 0;
+    });
+    // Framework statistics
+    const frameworkStats = {};
+    events.forEach(event => {
+        if (event.framework) {
+            frameworkStats[event.framework] = (frameworkStats[event.framework] || 0) + 1;
+        }
+    });
+    // Options usage
+    let authCount = 0;
+    let validationCount = 0;
+    let testsCount = 0;
+    events.forEach(event => {
+        if (event.options?.auth)
+            authCount++;
+        if (event.options?.validation)
+            validationCount++;
+        if (event.options?.tests)
+            testsCount++;
+    });
+    // Entity patterns
+    const entityPatterns = {};
+    events.forEach(event => {
+        if (event.entityName) {
+            entityPatterns[event.entityName] = (entityPatterns[event.entityName] || 0) + 1;
+        }
+    });
+    // Average execution time
+    const executionTimes = events.filter(e => e.executionTimeMs).map(e => e.executionTimeMs);
+    const avgExecutionTime = executionTimes.length > 0
+        ? executionTimes.reduce((sum, t) => sum + t, 0) / executionTimes.length
+        : undefined;
+    return {
+        totalGenerations: events.length,
+        totalTokensSaved,
+        avgTokensSavedPerGeneration: events.length > 0 ? totalTokensSaved / events.length : 0,
+        totalLinesOfCode,
+        totalFiles,
+        generatorStats,
+        frameworkStats,
+        optionsUsage: {
+            auth: authCount,
+            validation: validationCount,
+            tests: testsCount,
+        },
+        entityPatterns,
+        avgExecutionTime,
+        recentGenerations: events.slice(0, 10).reverse(),
+    };
+}
+/**
+ * Get analytics for last 24 hours
+ */
+export async function getLast24HoursAnalytics() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    return getUsageAnalytics({ startTime, endTime });
+}
+/**
+ * Get analytics for last 7 days
+ */
+export async function getLast7DaysAnalytics() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    return getUsageAnalytics({ startTime, endTime });
+}
+/**
+ * Get analytics for last 30 days
+ */
+export async function getLast30DaysAnalytics() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+    return getUsageAnalytics({ startTime, endTime });
+}
+/**
+ * Print analytics report
+ */
+export function printAnalytics(result, title = 'CodeDNA Usage Analytics') {
+    console.log('\n=================================================');
+    console.log(title);
+    console.log('=================================================\n');
+    console.log('Overview:');
+    console.log(`  Total Generations: ${result.totalGenerations}`);
+    console.log(`  Total Tokens Saved: ${result.totalTokensSaved.toLocaleString()}`);
+    console.log(`  Avg Tokens/Generation: ${Math.round(result.avgTokensSavedPerGeneration).toLocaleString()}`);
+    console.log(`  Total Lines of Code: ${result.totalLinesOfCode.toLocaleString()}`);
+    console.log(`  Total Files Generated: ${result.totalFiles}`);
+    if (result.avgExecutionTime) {
+        console.log(`  Avg Execution Time: ${Math.round(result.avgExecutionTime)}ms`);
+    }
+    console.log();
+    if (Object.keys(result.generatorStats).length > 0) {
+        console.log('Generator Usage:');
+        Object.entries(result.generatorStats)
+            .sort((a, b) => b[1].count - a[1].count)
+            .forEach(([gen, stats]) => {
+            console.log(`  ${gen}:`);
+            console.log(`    Count: ${stats.count}`);
+            console.log(`    Tokens Saved: ${stats.tokensSaved.toLocaleString()}`);
+            console.log(`    Lines of Code: ${stats.linesOfCode.toLocaleString()}`);
+            console.log(`    Files Generated: ${stats.filesGenerated}`);
+        });
+        console.log();
+    }
+    if (Object.keys(result.frameworkStats).length > 0) {
+        console.log('Framework Popularity:');
+        Object.entries(result.frameworkStats)
+            .sort((a, b) => b[1] - a[1])
+            .forEach(([framework, count]) => {
+            console.log(`  ${framework}: ${count} generations`);
+        });
+        console.log();
+    }
+    console.log('Options Usage:');
+    console.log(`  Auth: ${result.optionsUsage.auth} generations`);
+    console.log(`  Validation: ${result.optionsUsage.validation} generations`);
+    console.log(`  Tests: ${result.optionsUsage.tests} generations`);
+    console.log();
+    if (Object.keys(result.entityPatterns).length > 0) {
+        console.log('Popular Entities:');
+        Object.entries(result.entityPatterns)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .forEach(([entity, count]) => {
+            console.log(`  ${entity}: ${count} times`);
+        });
+        console.log();
+    }
+    if (result.recentGenerations.length > 0) {
+        console.log('Recent Generations:');
+        result.recentGenerations.forEach((gen, i) => {
+            console.log(`  ${i + 1}. [${gen.timestamp}] ${gen.operation}`);
+            console.log(`     Generator: ${gen.generator || 'N/A'}`);
+            console.log(`     Entity: ${gen.entityName || 'N/A'}`);
+            console.log(`     Tokens Saved: ${(gen.tokensSaved || 0).toLocaleString()}`);
+        });
+    }
+    console.log('\n=================================================\n');
+}
+/**
+ * Weekly analytics summary
+ */
+export async function weeklyAnalyticsSummary() {
+    console.log('Generating weekly CodeDNA analytics summary...\n');
+    const result = await getLast7DaysAnalytics();
+    printAnalytics(result, 'CodeDNA Weekly Analytics Summary');
+    // Calculate ROI
+    const estimatedCost = result.totalTokensSaved * 0.00001; // ~$0.01 per 1000 tokens
+    console.log('💰 Estimated Cost Savings:');
+    console.log(`   Traditional approach: $${estimatedCost.toFixed(2)}`);
+    console.log(`   With CodeDNA: $${(estimatedCost * 0.01).toFixed(2)} (99% savings)`);
+    console.log(`   Total saved: $${(estimatedCost * 0.99).toFixed(2)}\n`);
+}

package/docs/AUTO-REGISTRATION.md

@@ -0,0 +1,353 @@
+# Auto Project Registration
+
+The ClaudeTools Memory MCP server now supports automatic project registration. When you use the server in a new directory, it will automatically register that directory as a project with the ClaudeTools API and cache the binding locally.
+
+## How It Works
+
+### 1. Project ID Resolution Flow
+
+```
+MCP Server Starts
+    ↓
+Check CLAUDETOOLS_PROJECT_ID env var
+    ↓ (if not set)
+Check ~/.claudetools/projects.json cache
+    ↓ (if no binding found)
+Auto-register via API (if autoRegister: true)
+    ↓
+Cache project_id locally
+    ↓
+Use project_id for all memory operations
+```
+
+### 2. System Registration
+
+On first use, the server registers your machine:
+
+- **System ID**: Unique identifier for this machine (e.g., `sys_abc123...`)
+- **Hostname**: Your machine's hostname
+- **Platform**: Operating system (darwin, linux, win32)
+- **Username**: Current user
+
+The system ID is cached in `~/.claudetools/projects.json`:
+
+```json
+{
+  "system_id": "sys_bdbcff93724e4a05b488",
+  "bindings": [...],
+  "last_sync": "2025-12-03T02:37:44.635Z"
+}
+```
+
+### 3. Project Binding
+
+When you use the MCP server in a directory for the first time:
+
+1. **Detects** project metadata:
+   - Project name (from directory name)
+   - Local path (absolute path)
+   - Git remote (if available)
+
+2. **Registers** via API:
+   - Creates project in your ClaudeTools account
+   - Returns project_id (UUID format: `proj_xxxxxxxxxxxxxxxxxxxx`)
+
+3. **Creates binding** linking:
+   - System ID (your machine)
+   - Project ID (the project)
+   - Local path (where the project lives)
+
+4. **Caches** binding locally in `~/.claudetools/projects.json`:
+
+```json
+{
+  "bindings": [
+    {
+      "binding_id": "bind_904de164763a47d0924e",
+      "project_id": "proj_3a33ce7579874351b990",
+      "system_id": "sys_bdbcff93724e4a05b488",
+      "local_path": "/Users/you/Projects/myproject",
+      "git_remote": "git@github.com:you/myproject.git",
+      "project_name": "myproject",
+      "org_id": "your-org-id",
+      "cached_at": "2025-12-03T02:37:44.635Z"
+    }
+  ],
+  "system_id": "sys_bdbcff93724e4a05b488",
+  "last_sync": "2025-12-03T02:37:44.635Z"
+}
+```
+
+## Configuration
+
+### Enable/Disable Auto-Registration
+
+Edit `~/.claudetools/config.json`:
+
+```json
+{
+  "autoRegister": true,  // Enable auto-registration (default)
+  "apiUrl": "https://api.claudetools.dev",
+  "apiKey": "ct_live_..."
+}
+```
+
+To disable auto-registration:
+
+```json
+{
+  "autoRegister": false
+}
+```
+
+### Set API Key
+
+Three ways to configure your API key:
+
+1. **Environment variable** (highest priority):
+   ```bash
+   export CLAUDETOOLS_API_KEY="ct_live_..."
+   # or
+   export MEMORY_API_KEY="ct_live_..."
+   ```
+
+2. **Config file**:
+   ```json
+   {
+     "apiKey": "ct_live_..."
+   }
+   ```
+
+3. **.env file** (in project root):
+   ```bash
+   MEMORY_API_KEY=ct_live_...
+   ```
+
+### Manual Project ID
+
+If you want to use a specific project ID instead of auto-registering:
+
+```bash
+export CLAUDETOOLS_PROJECT_ID="proj_xxxxxxxxxxxxxxxxxxxx"
+```
+
+## Project ID Format Validation
+
+All project IDs must follow the format:
+- Prefix: `proj_`
+- 20 hexadecimal characters
+- Example: `proj_3a33ce7579874351b990`
+
+Invalid formats will be rejected with a clear error message.
+
+## Cache Management
+
+### View Cache
+
+```bash
+cat ~/.claudetools/projects.json
+```
+
+### Clear Cache
+
+```bash
+rm ~/.claudetools/projects.json
+```
+
+The server will auto-register on next use (if `autoRegister: true`).
+
+### Sync from API
+
+Future feature - will pull all your project bindings from the API:
+
+```typescript
+import { syncProjectsFromAPI } from './helpers/project-registration.js';
+await syncProjectsFromAPI();
+```
+
+## Path Matching
+
+The server uses smart path matching:
+
+1. **Exact match**: `/Users/you/Projects/myproject` matches exactly
+2. **Prefix match**: `/Users/you/Projects/myproject/src` uses parent binding
+3. **Longest match**: If multiple bindings match, uses the longest path
+
+Example:
+```json
+{
+  "bindings": [
+    {"local_path": "/Users/you/Projects"},
+    {"local_path": "/Users/you/Projects/myproject"}
+  ]
+}
+```
+
+Using server from `/Users/you/Projects/myproject/src`:
+- ✅ Uses: `/Users/you/Projects/myproject` (longer match)
+- ❌ Not: `/Users/you/Projects` (shorter match)
+
+## Error Handling
+
+### No API Key
+
+```
+Error: No API key found. Set CLAUDETOOLS_API_KEY or MEMORY_API_KEY in environment,
+or configure via ~/.claudetools/config.json
+```
+
+**Solution**: Set API key using one of the methods above.
+
+### Auto-Registration Disabled
+
+```
+Error: No project binding found for /path/to/project and auto-registration is disabled.
+To register this project:
+  1. Set CLAUDETOOLS_PROJECT_ID environment variable with a valid proj_* UUID
+  2. Enable autoRegister in ~/.claudetools/config.json
+  3. Or manually register via API
+```
+
+**Solution**: Either:
+- Enable auto-registration in config
+- Set `CLAUDETOOLS_PROJECT_ID` manually
+- Register project via ClaudeTools dashboard
+
+### Invalid Project ID Format
+
+```
+Error: Invalid project ID format: my-project-123
+Expected format: proj_xxxxxxxxxxxxxxxxxxxx (20 hex chars)
+```
+
+**Solution**: Use a valid UUID format or let the system auto-register.
+
+### Network Error
+
+```
+Error: Failed to auto-register project: API error: 500 Internal Server Error
+```
+
+**Solution**: Check:
+1. API URL is correct in config
+2. Network connectivity to `api.claudetools.dev`
+3. API service status
+
+## Testing
+
+Run the registration test suite:
+
+```bash
+cd mcp-server
+npm run build
+npx tsx test-registration.ts
+```
+
+Expected output:
+```
+================================================================================
+Testing Auto-Registration System
+================================================================================
+
+Test 1: Direct registration via getOrRegisterProject()
+✅ Success: proj_3a33ce7579874351b990
+
+Test 2: Resolution via resolveProjectIdAsync()
+✅ Success: proj_3a33ce7579874351b990
+
+Test 3: Verify consistency
+✅ Both methods returned same ID: proj_3a33ce7579874351b990
+
+Test 4: Check cache file
+Cache file exists at: /Users/you/.claudetools/projects.json
+Bindings count: 1
+System ID: sys_bdbcff93724e4a05b488
+
+✅ All tests passed!
+================================================================================
+```
+
+## Known Issues
+
+### API Schema Error (Temporary)
+
+Currently, the project creation endpoint has a schema issue:
+```
+Error: table projects has no column named created_by
+```
+
+**Workaround**: Use an existing cached binding or manually set `CLAUDETOOLS_PROJECT_ID`.
+
+This will be fixed in the next API deployment.
+
+## Migration from Name-Based IDs
+
+If you were previously using name-based IDs like `claude-code-myproject`:
+
+1. **Delete old cache**: `rm ~/.claudetools/projects.json`
+2. **Set API key**: Export `CLAUDETOOLS_API_KEY`
+3. **Restart server**: Will auto-register with proper UUID
+
+Or keep using the old ID by setting:
+```bash
+export CLAUDETOOLS_PROJECT_ID="claude-code-myproject"
+```
+
+However, this is **not recommended** as UUID-based IDs provide:
+- ✅ Global uniqueness
+- ✅ Cross-machine project sharing
+- ✅ Proper project management in ClaudeTools dashboard
+- ✅ Multi-system bindings
+
+## Architecture
+
+### Key Files
+
+- `src/helpers/project-registration.ts` - Registration logic
+- `src/helpers/config.ts` - Project ID resolution
+- `src/helpers/config-manager.ts` - Configuration management
+- `~/.claudetools/config.json` - User configuration
+- `~/.claudetools/projects.json` - Cached bindings
+
+### API Endpoints
+
+- `POST /api/v1/systems/register` - Register machine
+- `POST /api/v1/projects` - Create project
+- `POST /api/v1/systems/{system_id}/bindings` - Create binding
+- `GET /api/v1/systems/{system_id}/bindings` - List bindings (future)
+
+### Data Flow
+
+```
+User → MCP Server → resolveProjectIdAsync()
+                      ↓
+                   Check cache
+                      ↓ (miss)
+                   getOrRegisterProject()
+                      ↓
+                   ensureSystemRegistered() → API
+                      ↓
+                   registerProject() → API
+                      ↓
+                   updateProjectsCache()
+                      ↓
+                   Return project_id
+```
+
+## Best Practices
+
+1. **Set API key globally**: Use environment variable or config file
+2. **Enable auto-registration**: Let the system handle project setup
+3. **One binding per project**: Don't create multiple bindings for same path
+4. **Git remotes help**: They make project identification easier
+5. **Cache is local**: Each machine has its own bindings cache
+
+## Future Enhancements
+
+- [ ] Sync bindings from API on startup
+- [ ] Detect project changes (git remote updates)
+- [ ] Multi-org support
+- [ ] Project metadata updates
+- [ ] Binding removal/cleanup
+- [ ] Cross-machine project resolution
+- [ ] Project templates