@claudetools/tools 0.4.0 → 0.5.1

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/dist/templates/claude-md.d.ts

@@ -5,7 +5,7 @@ export declare const PROJECT_SECTION_END = "<!-- CLAUDETOOLS:PROJECT:END -->";
 /**
  * Global CLAUDE.md content - added to ~/.claude/CLAUDE.md
  */
-export declare const GLOBAL_TEMPLATE = "\n<!-- CLAUDETOOLS:START -->\n# ClaudeTools Memory System\n\nYou have access to a persistent memory system via the `claudetools_memory` MCP server. Use it to remember context across sessions.\n\n## Memory Tools\n\n### Searching Memory\n```\nmemory_search(query: \"authentication patterns\")\n```\nSearch for relevant facts, entities, and past context. Use this when:\n- Starting work on a feature to recall past decisions\n- Looking for patterns or conventions used before\n- Finding related code or architectural context\n\n### Storing Facts\n```\nmemory_store_fact(\n  entity1: \"UserService\",\n  relationship: \"USES\",\n  entity2: \"bcrypt\",\n  context: \"Password hashing uses bcrypt with 12 rounds\"\n)\n```\nStore important facts as relationships between entities. Use for:\n- Architectural decisions\n- Code patterns and conventions\n- Dependencies and relationships\n- User preferences learned during conversation\n\n### Context Injection\nContext is automatically injected at the start of each session based on the current project. Check `~/.claudetools/session-context.md` for project-specific context.\n\n## Task Management\n\n### Creating Work Plans with Auto-Dispatch\n```\ntask_plan(\n  goal: \"Add user authentication\",\n  epic_title: \"User Auth System\",\n  tasks: [...]\n)\n```\nBreak down complex work into tracked tasks. **Tasks are automatically set to `ready` status.**\n\nAfter `task_plan` completes, you will receive Task tool invocations to spawn parallel agents.\n**Execute ALL Task tool calls in a SINGLE message** to enable parallel execution.\n\n### Parallel Agent Workflow\n1. User describes work needed\n2. Call `task_plan_draft` to present the plan\n3. User says \"go\" to approve\n4. Call `task_plan` - tasks created in `ready` status\n5. Execute the provided Task tool calls in ONE message\n6. Agents work in parallel, each calling `task_complete` when done\n\n### Manual Task Start (Sequential)\n```\ntask_start(task_id: \"task_xxx\")\n```\nClaim a task before working on it. Use for sequential execution.\n\n### Completing Tasks\n```\ntask_complete(task_id: \"task_xxx\", summary: \"Implemented JWT auth with refresh tokens\")\n```\nMark tasks done with a summary of work completed. **Always call this when a task is finished.**\n\n## Codebase Intelligence\n\n### Finding Code\n```\ncodebase_map()           # Get overview of project structure\ncodebase_find(\"UserService\")  # Find symbols/files\ncodebase_context(\"src/auth.ts\")  # Get file dependencies\n```\n\n### Impact Analysis\n```\nanalyze_impact(function_name: \"validateToken\")\n```\nSee what would be affected by changing a function.\n\n## Best Practices\n\n1. **Search before implementing** - Check memory for existing patterns\n2. **Store decisions** - Save architectural choices as facts\n3. **Use task tracking** - Break complex work into tasks\n4. **Complete tasks** - Always mark tasks done with summaries\n<!-- CLAUDETOOLS:END -->\n";
+export declare const GLOBAL_TEMPLATE = "\n<!-- CLAUDETOOLS:START -->\n# ClaudeTools Memory System\n\nYou have access to a persistent memory system via the `claudetools_memory` MCP server. Use it to remember context across sessions.\n\n## Memory Tools\n\n### Searching Memory\n```\nmemory_search(query: \"authentication patterns\")\n```\nSearch for relevant facts, entities, and past context. Use this when:\n- Starting work on a feature to recall past decisions\n- Looking for patterns or conventions used before\n- Finding related code or architectural context\n\n### Storing Facts\n```\nmemory_store_fact(\n  entity1: \"UserService\",\n  relationship: \"USES\",\n  entity2: \"bcrypt\",\n  context: \"Password hashing uses bcrypt with 12 rounds\"\n)\n```\nStore important facts as relationships between entities. Use for:\n- Architectural decisions\n- Code patterns and conventions\n- Dependencies and relationships\n- User preferences learned during conversation\n\n### Context Injection\nContext is automatically injected at the start of each session based on the current project. Check `~/.claudetools/session-context.md` for project-specific context.\n\n## Task Management\n\n### Creating Work Plans with Auto-Dispatch\n```\ntask_plan(\n  goal: \"Add user authentication\",\n  epic_title: \"User Auth System\",\n  tasks: [...]\n)\n```\nBreak down complex work into tracked tasks. **Tasks are automatically set to `ready` status.**\n\nAfter `task_plan` completes, you will receive Task tool invocations to spawn parallel agents.\n**Execute ALL Task tool calls in a SINGLE message** to enable parallel execution.\n\n### Parallel Agent Workflow\n1. User describes work needed\n2. Call `task_plan_draft` to present the plan\n3. User says \"go\" to approve\n4. Call `task_plan` - tasks created in `ready` status\n5. Execute the provided Task tool calls in ONE message\n6. Agents work in parallel, each calling `task_complete` when done\n\n### Manual Task Start (Sequential)\n```\ntask_start(task_id: \"task_xxx\")\n```\nClaim a task before working on it. Use for sequential execution.\n\n### Completing Tasks\n```\ntask_complete(task_id: \"task_xxx\", summary: \"Implemented JWT auth with refresh tokens\")\n```\nMark tasks done with a summary of work completed. **Always call this when a task is finished.**\n\n## Codebase Intelligence\n\n### Finding Code\n```\ncodebase_map()           # Get overview of project structure\ncodebase_find(\"UserService\")  # Find symbols/files\ncodebase_context(\"src/auth.ts\")  # Get file dependencies\n```\n\n### Impact Analysis\n```\nanalyze_impact(function_name: \"validateToken\")\n```\nSee what would be affected by changing a function.\n\n## CodeDNA: AI Code Generation (95-99% Token Savings)\n\n**CRITICAL: Use CodeDNA for repetitive code generation to save massive tokens.**\n\n### When to Use CodeDNA\n- Creating REST APIs with CRUD operations\n- Generating database models, controllers, routes\n- Building validation middleware\n- Setting up authentication systems\n- Creating test suites\n\n### Available Generators\n```\ncodedna_generate_api(spec, framework, options)\ncodedna_validate_spec(spec)\ncodedna_list_generators()\n```\n\n### Entity DSL Syntax\n```\nEntityName(field:type:constraint, field:type:constraint, ...)\n\nExamples:\nUser(email:string:unique:required, password:string:hashed, age:integer:min(18))\nPost(title:string:required, content:string, author:ref(User))\nProduct(name:string, price:decimal:min(0), stock:integer:default(0))\n```\n\n### Constraints\n- `unique` - Unique constraint\n- `required` - NOT NULL\n- `hashed` - Bcrypt hashing (for passwords)\n- `min(n)` - Minimum value\n- `max(n)` - Maximum value\n- `default(value)` - Default value\n\n### Token Savings Example\n**Traditional approach:**\n- AI writes 1000 lines of code\n- Tokens: ~30,000 (input + output)\n- Cost: ~$0.30\n- Time: 2-3 minutes\n\n**CodeDNA approach:**\n```\ncodedna_generate_api({\n  spec: \"User(email:string:unique, password:string:hashed, role:enum(admin,user))\",\n  framework: \"express\",\n  options: { auth: true, validation: true, tests: true }\n})\n```\n- Tokens: ~200\n- Cost: ~$0.002\n- Time: 5-10 seconds\n- **Savings: 99.3% cost, 90% time**\n\n### Generated Files (Express)\n1. `models/entity.model.ts` - Sequelize ORM model\n2. `controllers/entity.controller.ts` - CRUD controllers\n3. `routes/entity.routes.ts` - Express routes\n4. `validators/entity.validator.ts` - Input validation (optional)\n5. `middleware/auth.middleware.ts` - JWT auth (optional)\n6. `tests/entity.test.ts` - Jest tests (optional)\n\n### Usage Pattern\n1. User asks: \"Create a User API with authentication\"\n2. **YOU MUST** call `codedna_generate_api` instead of writing code\n3. Receive 6 production-ready files\n4. Save 99% tokens and time\n\n**DO NOT write boilerplate code manually when CodeDNA can generate it.**\n\n## Best Practices\n\n1. **Search before implementing** - Check memory for existing patterns\n2. **Store decisions** - Save architectural choices as facts\n3. **Use task tracking** - Break complex work into tasks\n4. **Complete tasks** - Always mark tasks done with summaries\n5. **Use CodeDNA for APIs** - Save 95-99% tokens on boilerplate generation\n<!-- CLAUDETOOLS:END -->\n";
 /**
  * Project-level CLAUDE.md content - added to .claude/CLAUDE.md
  */

package/dist/templates/claude-md.js

@@ -95,12 +95,85 @@ analyze_impact(function_name: "validateToken")
 \`\`\`
 See what would be affected by changing a function.
 
+## CodeDNA: AI Code Generation (95-99% Token Savings)
+
+**CRITICAL: Use CodeDNA for repetitive code generation to save massive tokens.**
+
+### When to Use CodeDNA
+- Creating REST APIs with CRUD operations
+- Generating database models, controllers, routes
+- Building validation middleware
+- Setting up authentication systems
+- Creating test suites
+
+### Available Generators
+\`\`\`
+codedna_generate_api(spec, framework, options)
+codedna_validate_spec(spec)
+codedna_list_generators()
+\`\`\`
+
+### Entity DSL Syntax
+\`\`\`
+EntityName(field:type:constraint, field:type:constraint, ...)
+
+Examples:
+User(email:string:unique:required, password:string:hashed, age:integer:min(18))
+Post(title:string:required, content:string, author:ref(User))
+Product(name:string, price:decimal:min(0), stock:integer:default(0))
+\`\`\`
+
+### Constraints
+- \`unique\` - Unique constraint
+- \`required\` - NOT NULL
+- \`hashed\` - Bcrypt hashing (for passwords)
+- \`min(n)\` - Minimum value
+- \`max(n)\` - Maximum value
+- \`default(value)\` - Default value
+
+### Token Savings Example
+**Traditional approach:**
+- AI writes 1000 lines of code
+- Tokens: ~30,000 (input + output)
+- Cost: ~$0.30
+- Time: 2-3 minutes
+
+**CodeDNA approach:**
+\`\`\`
+codedna_generate_api({
+  spec: "User(email:string:unique, password:string:hashed, role:enum(admin,user))",
+  framework: "express",
+  options: { auth: true, validation: true, tests: true }
+})
+\`\`\`
+- Tokens: ~200
+- Cost: ~$0.002
+- Time: 5-10 seconds
+- **Savings: 99.3% cost, 90% time**
+
+### Generated Files (Express)
+1. \`models/entity.model.ts\` - Sequelize ORM model
+2. \`controllers/entity.controller.ts\` - CRUD controllers
+3. \`routes/entity.routes.ts\` - Express routes
+4. \`validators/entity.validator.ts\` - Input validation (optional)
+5. \`middleware/auth.middleware.ts\` - JWT auth (optional)
+6. \`tests/entity.test.ts\` - Jest tests (optional)
+
+### Usage Pattern
+1. User asks: "Create a User API with authentication"
+2. **YOU MUST** call \`codedna_generate_api\` instead of writing code
+3. Receive 6 production-ready files
+4. Save 99% tokens and time
+
+**DO NOT write boilerplate code manually when CodeDNA can generate it.**
+
 ## Best Practices
 
 1. **Search before implementing** - Check memory for existing patterns
 2. **Store decisions** - Save architectural choices as facts
 3. **Use task tracking** - Break complex work into tasks
 4. **Complete tasks** - Always mark tasks done with summaries
+5. **Use CodeDNA for APIs** - Save 95-99% tokens on boilerplate generation
 ${SECTION_END}
 `;
 /**