@eldrforge/ai-service 0.1.12 → 0.1.14

package/examples/01-simple-commit.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Example 1: Simple Commit Message Generation
+ *
+ * This example shows the most basic usage of the library to generate
+ * a commit message from staged git changes.
+ *
+ * Usage:
+ *   1. Stage some changes: git add .
+ *   2. Run: npx tsx examples/01-simple-commit.ts
+ */
+
+/* eslint-disable no-console */
+
+import { runAgenticCommit } from '@eldrforge/ai-service';
+import { execSync } from 'child_process';
+
+async function main() {
+    try {
+        console.log('🔍 Checking for staged changes...\n');
+
+        // Get the diff of staged changes
+        const diffContent = execSync('git diff --staged', { encoding: 'utf8' });
+
+        if (!diffContent.trim()) {
+            console.log('❌ No staged changes found.');
+            console.log('   Stage some changes first with: git add <files>');
+            process.exit(1);
+        }
+
+        // Get list of changed files
+        const statusOutput = execSync('git status --porcelain', { encoding: 'utf8' });
+        const changedFiles = statusOutput
+            .split('\n')
+            .filter(line => line.trim())
+            .map(line => line.substring(3));
+
+        console.log('📝 Files changed:', changedFiles.length);
+        changedFiles.forEach(file => console.log(`   - ${file}`));
+        console.log('');
+
+        console.log('🤖 Generating commit message...\n');
+
+        // Generate commit message using agentic mode
+        const result = await runAgenticCommit({
+            changedFiles,
+            diffContent,
+            model: 'gpt-4o-mini', // Using mini for faster/cheaper generation
+            maxIterations: 10,
+        });
+
+        console.log('✨ Generated Commit Message:\n');
+        console.log('─'.repeat(60));
+        console.log(result.commitMessage);
+        console.log('─'.repeat(60));
+        console.log('');
+        console.log(`📊 Stats: ${result.toolCallsExecuted} tool calls, ${result.iterations} iterations`);
+
+        // Show suggested splits if any
+        if (result.suggestedSplits.length > 0) {
+            console.log('\n💡 Suggested Commit Splits:');
+            console.log('   The AI recommends splitting this into multiple commits:\n');
+
+            result.suggestedSplits.forEach((split, idx) => {
+                console.log(`   Split ${idx + 1}:`);
+                console.log(`   Files: ${split.files.join(', ')}`);
+                console.log(`   Rationale: ${split.rationale}`);
+                console.log(`   Message: ${split.message}`);
+                console.log('');
+            });
+        }
+
+    } catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+
+main();
+

package/examples/02-release-notes.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * Example 2: Generate Release Notes
+ *
+ * This example generates comprehensive release notes between two git refs.
+ * The AI will use multiple tools to analyze the changes and create
+ * detailed, context-aware release notes.
+ *
+ * Usage:
+ *   npx tsx examples/02-release-notes.ts v1.0.0 v1.1.0
+ *   npx tsx examples/02-release-notes.ts v1.0.0 HEAD
+ */
+
+/* eslint-disable no-console */
+
+import { runAgenticRelease } from '@eldrforge/ai-service';
+import { execSync } from 'child_process';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+async function main() {
+    const args = process.argv.slice(2);
+
+    if (args.length < 2) {
+        console.log('Usage: npx tsx 02-release-notes.ts <from-ref> <to-ref>');
+        console.log('Example: npx tsx 02-release-notes.ts v1.0.0 v1.1.0');
+        process.exit(1);
+    }
+
+    const [fromRef, toRef] = args;
+
+    try {
+        console.log(`📋 Generating release notes from ${fromRef} to ${toRef}...\n`);
+
+        // Verify refs exist
+        try {
+            execSync(`git rev-parse ${fromRef}`, { stdio: 'ignore' });
+            execSync(`git rev-parse ${toRef}`, { stdio: 'ignore' });
+        } catch {
+            console.error(`❌ Invalid git reference: ${fromRef} or ${toRef}`);
+            process.exit(1);
+        }
+
+        // Get commit log
+        console.log('📖 Fetching commit history...');
+        const logContent = execSync(
+            `git log ${fromRef}..${toRef} --pretty=format:"%h %s (%an)" --abbrev-commit`,
+            { encoding: 'utf8' }
+        );
+
+        // Get diff stats
+        console.log('📊 Analyzing changes...');
+        const diffContent = execSync(
+            `git diff ${fromRef}..${toRef} --stat`,
+            { encoding: 'utf8' }
+        );
+
+        // Count commits
+        const commitCount = logContent.split('\n').filter(line => line.trim()).length;
+        console.log(`   Found ${commitCount} commits\n`);
+
+        // Run agentic release notes generation
+        console.log('🤖 AI is analyzing the release...');
+        console.log('   (This may take 1-3 minutes for thorough analysis)\n');
+
+        const result = await runAgenticRelease({
+            fromRef,
+            toRef,
+            logContent,
+            diffContent,
+            model: 'gpt-4o',
+            maxIterations: 30,
+        });
+
+        console.log('✅ Release notes generated!\n');
+        console.log('═'.repeat(70));
+        console.log(`TITLE: ${result.releaseNotes.title}`);
+        console.log('═'.repeat(70));
+        console.log('');
+        console.log(result.releaseNotes.body);
+        console.log('');
+        console.log('═'.repeat(70));
+        console.log('');
+        console.log(`📊 Metrics:`);
+        console.log(`   - Iterations: ${result.iterations}`);
+        console.log(`   - Tool calls: ${result.toolCallsExecuted}`);
+        console.log('');
+
+        // Show which tools were used
+        const toolUsage: Record<string, number> = {};
+        result.toolMetrics.forEach(metric => {
+            toolUsage[metric.name] = (toolUsage[metric.name] || 0) + 1;
+        });
+
+        console.log('🔧 Tools used:');
+        Object.entries(toolUsage)
+            .sort((a, b) => b[1] - a[1])
+            .forEach(([tool, count]) => {
+                console.log(`   - ${tool}: ${count}x`);
+            });
+        console.log('');
+
+        // Save to file
+        const outputDir = path.join(process.cwd(), 'output');
+        await fs.mkdir(outputDir, { recursive: true });
+
+        const releaseFile = path.join(outputDir, 'RELEASE_NOTES.md');
+        await fs.writeFile(releaseFile, result.releaseNotes.body, 'utf8');
+
+        const titleFile = path.join(outputDir, 'RELEASE_TITLE.txt');
+        await fs.writeFile(titleFile, result.releaseNotes.title, 'utf8');
+
+        console.log('💾 Saved to:');
+        console.log(`   - ${releaseFile}`);
+        console.log(`   - ${titleFile}`);
+
+    } catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+
+main();
+

package/examples/03-interactive-commit.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Example 3: Interactive Commit Workflow
+ *
+ * This example demonstrates an interactive workflow where the user can:
+ * - Generate an initial commit message
+ * - Review and choose to confirm, edit, or regenerate
+ * - Optionally add user feedback for improvement
+ * - Automatically create the commit
+ *
+ * Usage:
+ *   1. Stage changes: git add .
+ *   2. Run: npx tsx examples/03-interactive-commit.ts
+ */
+
+/* eslint-disable no-console */
+
+import {
+    runAgenticCommit,
+    getUserChoice,
+    editContentInEditor,
+    STANDARD_CHOICES,
+} from '@eldrforge/ai-service';
+import { execSync } from 'child_process';
+
+async function main() {
+    try {
+    // Check for staged changes
+        const diffContent = execSync('git diff --staged', { encoding: 'utf8' });
+
+        if (!diffContent.trim()) {
+            console.log('❌ No staged changes found.');
+            console.log('   Stage some changes first with: git add <files>');
+            process.exit(1);
+        }
+
+        // Get changed files
+        const statusOutput = execSync('git status --porcelain', { encoding: 'utf8' });
+        const changedFiles = statusOutput
+            .split('\n')
+            .filter(line => line.trim())
+            .map(line => line.substring(3));
+
+        console.log('📝 Changed files:', changedFiles.length);
+        changedFiles.forEach(file => console.log(`   - ${file}`));
+        console.log('');
+
+        // Generate initial commit message
+        console.log('🤖 Generating commit message...\n');
+
+        const result = await runAgenticCommit({
+            changedFiles,
+            diffContent,
+            model: 'gpt-4o-mini',
+            maxIterations: 10,
+        });
+
+        let currentMessage = result.commitMessage;
+        let shouldContinue = true;
+
+        while (shouldContinue) {
+            // Display current message
+            console.log('\n✨ Commit Message:\n');
+            console.log('─'.repeat(60));
+            console.log(currentMessage);
+            console.log('─'.repeat(60));
+            console.log('');
+
+            // Get user choice
+            const choice = await getUserChoice(
+                'What would you like to do?',
+                [
+                    STANDARD_CHOICES.CONFIRM,
+                    STANDARD_CHOICES.EDIT,
+                    STANDARD_CHOICES.SKIP,
+                ],
+                {
+                    nonTtyErrorSuggestions: [
+                        'Run in a terminal environment',
+                        'Use examples/01-simple-commit.ts for non-interactive mode',
+                    ],
+                }
+            );
+
+            switch (choice) {
+                case 'c': { // Confirm
+                    console.log('\n📝 Creating commit...');
+
+                    try {
+                        execSync('git', ['commit', '-m', currentMessage], {
+                            stdio: 'inherit',
+                        });
+                        console.log('✅ Commit created successfully!');
+                    } catch (commitError) {
+                        console.error('❌ Failed to create commit:', commitError);
+                    }
+
+                    shouldContinue = false;
+                    break;
+                }
+
+                case 'e': { // Edit
+                    console.log('\n📝 Opening editor...');
+
+                    const edited = await editContentInEditor(
+                        currentMessage,
+                        [
+                            '# Edit your commit message below',
+                            '# Lines starting with # will be removed',
+                            '# Save and close the editor when done',
+                        ],
+                        '.txt'
+                    );
+
+                    if (edited.wasEdited) {
+                        currentMessage = edited.content;
+                        console.log('\n✅ Commit message updated!');
+                    } else {
+                        console.log('\n⚠️  No changes made');
+                    }
+                    break;
+                }
+
+                case 's': // Skip
+                    console.log('\n⏭️  Commit cancelled. Your changes are still staged.');
+                    shouldContinue = false;
+                    break;
+
+                default:
+                    console.log('\n❌ Invalid choice');
+                    break;
+            }
+        }
+
+    } catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+
+// Check if running in TTY
+if (!process.stdin.isTTY) {
+    console.error('❌ This example requires a terminal (TTY).');
+    console.error('   Run it directly in your terminal, not piped or in CI.');
+    console.error('   For non-interactive mode, use: examples/01-simple-commit.ts');
+    process.exit(1);
+}
+
+main();
+

package/examples/04-custom-storage.ts

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * Example 4: Custom Storage Adapter
+ *
+ * This example demonstrates how to implement a custom storage adapter
+ * to save AI-generated content to a specific location or cloud storage.
+ *
+ * Usage:
+ *   npx tsx examples/04-custom-storage.ts
+ */
+
+/* eslint-disable no-console */
+
+import { runAgenticCommit, type StorageAdapter } from '@eldrforge/ai-service';
+import { execSync } from 'child_process';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+/**
+ * Custom storage adapter that saves files to a structured output directory
+ */
+class CustomStorageAdapter implements StorageAdapter {
+    private outputDir: string;
+    private tempDir: string;
+
+    constructor(outputDir: string, tempDir: string = '/tmp') {
+        this.outputDir = outputDir;
+        this.tempDir = tempDir;
+    }
+
+    async writeOutput(fileName: string, content: string): Promise<void> {
+    // Ensure output directory exists
+        await fs.mkdir(this.outputDir, { recursive: true });
+
+        const filePath = path.join(this.outputDir, fileName);
+        await fs.writeFile(filePath, content, 'utf8');
+
+        console.log(`   📁 Saved to: ${filePath}`);
+    }
+
+    async readTemp(fileName: string): Promise<string> {
+        const filePath = path.join(this.tempDir, fileName);
+        return fs.readFile(filePath, 'utf8');
+    }
+
+    async writeTemp(fileName: string, content: string): Promise<void> {
+        await fs.mkdir(this.tempDir, { recursive: true });
+        const filePath = path.join(this.tempDir, fileName);
+        await fs.writeFile(filePath, content, 'utf8');
+    }
+
+    async readFile(fileName: string): Promise<string> {
+        return fs.readFile(fileName, 'utf8');
+    }
+}
+
+/**
+ * Alternative: Cloud storage adapter (example structure)
+ * In a real implementation, you would integrate with AWS S3, Google Cloud Storage, etc.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+class CloudStorageAdapter implements StorageAdapter {
+    async writeOutput(fileName: string, _content: string): Promise<void> {
+    // Example: Upload to S3
+    // const s3 = new S3Client({ region: 'us-east-1' });
+    // await s3.send(new PutObjectCommand({
+    //   Bucket: 'my-bucket',
+    //   Key: `ai-output/${fileName}`,
+    //   Body: content,
+    // }));
+
+        console.log(`   ☁️  Would upload to cloud: ${fileName}`);
+    }
+
+    async readTemp(fileName: string): Promise<string> {
+    // Local temp files
+        return fs.readFile(path.join('/tmp', fileName), 'utf8');
+    }
+
+    async writeTemp(fileName: string, content: string): Promise<void> {
+        await fs.writeFile(path.join('/tmp', fileName), content, 'utf8');
+    }
+
+    async readFile(fileName: string): Promise<string> {
+        return fs.readFile(fileName, 'utf8');
+    }
+}
+
+async function main() {
+    try {
+        console.log('🔍 Checking for staged changes...\n');
+
+        const diffContent = execSync('git diff --staged', { encoding: 'utf8' });
+
+        if (!diffContent.trim()) {
+            console.log('❌ No staged changes found.');
+            console.log('   Stage some changes first with: git add <files>');
+            process.exit(1);
+        }
+
+        const statusOutput = execSync('git status --porcelain', { encoding: 'utf8' });
+        const changedFiles = statusOutput
+            .split('\n')
+            .filter(line => line.trim())
+            .map(line => line.substring(3));
+
+        console.log('📝 Files changed:', changedFiles.length);
+        console.log('');
+
+        // Create custom storage adapter
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const outputDir = path.join(process.cwd(), 'output', 'ai-service', timestamp);
+        const storage = new CustomStorageAdapter(outputDir);
+
+        console.log('🤖 Generating commit message with custom storage...\n');
+
+        const result = await runAgenticCommit({
+            changedFiles,
+            diffContent,
+            model: 'gpt-4o-mini',
+            maxIterations: 10,
+            storage,
+        });
+
+        console.log('\n✨ Generated Commit Message:\n');
+        console.log('─'.repeat(60));
+        console.log(result.commitMessage);
+        console.log('─'.repeat(60));
+        console.log('');
+
+        // Save additional metadata
+        console.log('💾 Saving files...\n');
+
+        await storage.writeOutput('commit-message.txt', result.commitMessage);
+
+        await storage.writeOutput(
+            'metadata.json',
+            JSON.stringify({
+                timestamp: new Date().toISOString(),
+                iterations: result.iterations,
+                toolCallsExecuted: result.toolCallsExecuted,
+                model: 'gpt-4o-mini',
+                changedFiles,
+            }, null, 2)
+        );
+
+        // Save tool metrics
+        await storage.writeOutput(
+            'tool-metrics.json',
+            JSON.stringify(result.toolMetrics, null, 2)
+        );
+
+        console.log('\n✅ Complete! All files saved to:', outputDir);
+
+    } catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+
+main();
+