macro-agent 0.1.1 → 0.1.2

package/references/skill-tree/examples/basic-usage.ts

@@ -0,0 +1,190 @@
+/**
+ * Basic usage example for skill-tree
+ *
+ * This example demonstrates:
+ * - Creating a SkillBank
+ * - Parsing Claude Code sessions
+ * - Extracting skills (manual and automatic)
+ * - Managing skill versions
+ */
+
+import {
+  createSkillBank,
+  type Skill,
+  type LLMProvider,
+  type Trajectory,
+} from '../src/index.js';
+
+// Example Claude Code session (simplified)
+const sampleSession = `{"type":"user","message":{"role":"user","content":"I'm getting a TypeScript error: Cannot find module './utils' when importing"}}
+{"type":"assistant","message":{"role":"assistant","content":"Let me investigate this import error. This is usually caused by missing file extensions in TypeScript with ES modules."}}
+{"type":"assistant","message":{"role":"assistant","content":"The issue is that TypeScript with ES modules requires explicit .js extensions in imports, even for .ts files."},"toolCalls":[{"name":"Edit","input":{"file_path":"src/index.ts","old_string":"import { helper } from './utils'","new_string":"import { helper } from './utils.js'"}}]}
+{"type":"result","toolUseId":"1","toolName":"Edit","result":"File edited successfully"}
+{"type":"assistant","message":{"role":"assistant","content":"I've fixed the import by adding the .js extension. This is required when using ES modules with TypeScript."}}`;
+
+async function main() {
+  // ==========================================================================
+  // 1. Initialize SkillBank with filesystem storage
+  // ==========================================================================
+  console.log('1. Creating SkillBank...');
+
+  const skillBank = createSkillBank({
+    storage: {
+      type: 'filesystem',
+      basePath: './skills',
+      openSkillsCompatible: true,
+    },
+  });
+
+  await skillBank.initialize();
+  console.log('   SkillBank initialized!\n');
+
+  // ==========================================================================
+  // 2. Parse a Claude Code session
+  // ==========================================================================
+  console.log('2. Parsing session...');
+
+  const trajectory = await skillBank.parseSession(sampleSession);
+  console.log(`   Session ID: ${trajectory.sessionId}`);
+  console.log(`   Turns: ${trajectory.turns.length}`);
+  console.log(`   Agent: ${trajectory.metadata.agentType}\n`);
+
+  // ==========================================================================
+  // 3. Manual skill extraction
+  // ==========================================================================
+  console.log('3. Extracting skill manually...');
+
+  const extractionResult = await skillBank.extractManual(trajectory, {
+    suggestedName: 'typescript-esm-import-fix',
+    description: 'Fix TypeScript ES module import errors by adding .js extension',
+    tags: ['typescript', 'esm', 'imports'],
+  });
+
+  if (extractionResult.success && extractionResult.skill) {
+    console.log(`   Extracted: ${extractionResult.skill.name}`);
+    console.log(`   Confidence: ${extractionResult.confidence}`);
+    console.log(`   Version: ${extractionResult.skill.version}`);
+  } else {
+    console.log(`   Extraction failed: ${extractionResult.failureReason}`);
+  }
+  console.log();
+
+  // ==========================================================================
+  // 4. List and search skills
+  // ==========================================================================
+  console.log('4. Listing skills...');
+
+  const allSkills = await skillBank.listSkills();
+  console.log(`   Total skills: ${allSkills.length}`);
+
+  const tsSkills = await skillBank.searchSkills('typescript');
+  console.log(`   TypeScript skills: ${tsSkills.length}\n`);
+
+  // ==========================================================================
+  // 5. Version management
+  // ==========================================================================
+  if (extractionResult.skill) {
+    console.log('5. Creating new version...');
+
+    const updatedSkill = await skillBank.createVersion(
+      extractionResult.skill.id,
+      {
+        solution: extractionResult.skill.solution + '\n\nAlternatively, configure tsconfig.json with "moduleResolution": "bundler".',
+        notes: 'Updated with alternative solution using bundler resolution.',
+      },
+      {
+        bumpType: 'minor',
+        changelog: 'Added alternative solution using bundler module resolution',
+      }
+    );
+
+    console.log(`   New version: ${updatedSkill.version}`);
+    console.log(`   Parent version: ${updatedSkill.parentVersion}`);
+
+    // Get version history
+    const history = await skillBank.getVersionHistory(extractionResult.skill.id);
+    console.log(`   Version history: ${history.map((v) => v.version).join(', ')}\n`);
+  }
+
+  // ==========================================================================
+  // 6. Fork a skill
+  // ==========================================================================
+  if (extractionResult.skill) {
+    console.log('6. Forking skill for React projects...');
+
+    const forkedSkill = await skillBank.forkSkill(extractionResult.skill.id, {
+      newId: 'react-typescript-esm-import-fix',
+      newName: 'React TypeScript ESM Import Fix',
+      reason: 'Specialized version for React/Next.js projects',
+    });
+
+    console.log(`   Forked: ${forkedSkill.name}`);
+    console.log(`   Derived from: ${forkedSkill.derivedFrom?.join(', ')}\n`);
+  }
+
+  // ==========================================================================
+  // 7. Get statistics
+  // ==========================================================================
+  console.log('7. Skill bank statistics...');
+
+  const stats = await skillBank.getStats();
+  console.log(`   Total skills: ${stats.totalSkills}`);
+  console.log(`   Active: ${stats.byStatus.active}`);
+  console.log(`   Draft: ${stats.byStatus.draft}`);
+  console.log(`   Tags: ${Object.keys(stats.byTag).join(', ')}\n`);
+
+  // ==========================================================================
+  // 8. Event handling
+  // ==========================================================================
+  console.log('8. Setting up event handlers...');
+
+  const unsubscribe = skillBank.on((event) => {
+    console.log(`   Event: ${event.type}`);
+  });
+
+  // Trigger some events
+  if (extractionResult.skill) {
+    await skillBank.deprecateSkill(extractionResult.skill.id);
+  }
+
+  // Cleanup
+  unsubscribe();
+  console.log('\nDone!');
+}
+
+// ==========================================================================
+// Example: Custom LLM Provider for automatic extraction
+// ==========================================================================
+function createMockLLMProvider(): LLMProvider {
+  return {
+    name: 'mock-llm',
+
+    async complete(prompt: string): Promise<string> {
+      // In a real implementation, this would call an LLM API
+      return JSON.stringify({
+        candidates: [
+          {
+            name: 'extracted-skill',
+            description: 'Auto-extracted skill',
+            problem: 'Sample problem',
+            solution: 'Sample solution',
+            triggerConditions: [{ type: 'error', value: 'sample error' }],
+            verification: 'Verify it works',
+            turnRange: [0, 3],
+            confidence: 0.8,
+            reasoning: 'High confidence extraction',
+          },
+        ],
+      });
+    },
+
+    async completeStructured<T>(prompt: string, schema: object): Promise<T> {
+      // In a real implementation, this would use structured output
+      const response = await this.complete(prompt);
+      return JSON.parse(response) as T;
+    },
+  };
+}
+
+// Run the example
+main().catch(console.error);