@qodo/sdk 0.4.0 → 0.6.0

package/.claude/skills/qodo-agent/assets/programmatic-agent.ts

@@ -0,0 +1,317 @@
+/**
+ * Complete @qodo/sdk Programmatic Agent Template
+ *
+ * This template demonstrates all key SDK features:
+ * - sdkAgent() and sdkCommand() builders
+ * - Zod schemas with proper descriptions
+ * - Event streaming with matchSdkEvent()
+ * - Error handling
+ * - Proper cleanup with dispose()
+ *
+ * Usage:
+ *   npx tsx programmatic-agent.ts
+ */
+
+import {
+  QodoSDK,
+  sdkAgent,
+  sdkCommand,
+  sdkArgs,
+  SdkEventType,
+  matchSdkEvent,
+  zJsonValue,
+  zJsonAny,
+  QodoSchemaError,
+  QodoAuthError,
+} from '@qodo/sdk';
+import { z } from 'zod';
+
+// =============================================================================
+// STEP 1: Define Output Schemas
+// =============================================================================
+// IMPORTANT: Every property MUST have .describe() or you'll get QodoSchemaError
+
+const analyzeOutputSchema = z.object({
+  summary: z.string().describe('Brief overall assessment of the code quality'),
+  metrics: z
+    .object({
+      files_analyzed: z.number().describe('Number of files analyzed'),
+      total_lines: z.number().describe('Total lines of code'),
+      issues_found: z.number().describe('Total issues found'),
+    })
+    .describe('Quantitative metrics from the analysis'),
+  issues: z
+    .array(
+      z.object({
+        file: z.string().describe('Relative path to the file'),
+        line: z.number().describe('Line number where issue occurs'),
+        severity: z.enum(['info', 'warning', 'error']).describe('Issue severity level'),
+        category: z
+          .enum(['style', 'bug', 'security', 'performance', 'maintainability'])
+          .describe('Issue category'),
+        message: z.string().describe('Human-readable description of the issue'),
+        suggestion: z.string().optional().describe('Suggested fix if available'),
+      })
+    )
+    .describe('List of issues found during analysis'),
+  recommendations: z
+    .array(z.string().describe('A specific recommendation'))
+    .describe('High-level recommendations for improvement'),
+  score: z.number().min(0).max(100).describe('Overall quality score from 0-100'),
+});
+
+const refactorOutputSchema = z.object({
+  changes_made: z
+    .array(
+      z.object({
+        file: z.string().describe('File that was modified'),
+        description: z.string().describe('What was changed'),
+        before_snippet: z.string().optional().describe('Code before the change'),
+        after_snippet: z.string().optional().describe('Code after the change'),
+      })
+    )
+    .describe('List of changes made during refactoring'),
+  files_modified: z.array(z.string().describe('File path')).describe('All files that were modified'),
+  summary: z.string().describe('Summary of refactoring performed'),
+});
+
+// =============================================================================
+// STEP 2: Define Args Schemas
+// =============================================================================
+// Args schemas are optional but recommended for type-safe input validation
+
+const analyzeArgsSchema = sdkArgs({
+  path: z.string().describe('Path to the directory or file to analyze'),
+  include_patterns: z
+    .array(z.string())
+    .optional()
+    .default(['**/*.ts', '**/*.js'])
+    .describe('Glob patterns for files to include'),
+  exclude_patterns: z
+    .array(z.string())
+    .optional()
+    .default(['**/node_modules/**', '**/dist/**'])
+    .describe('Glob patterns for files to exclude'),
+  severity_threshold: z
+    .enum(['info', 'warning', 'error'])
+    .optional()
+    .default('info')
+    .describe('Minimum severity to report'),
+});
+
+const refactorArgsSchema = sdkArgs({
+  path: z.string().describe('Path to refactor'),
+  pattern: z.string().describe('What to look for (e.g., "Convert callbacks to async/await")'),
+  dry_run: z.boolean().optional().default(false).describe('If true, show changes without applying'),
+});
+
+// =============================================================================
+// STEP 3: Build the Agent Configuration
+// =============================================================================
+
+const codeAssistantAgent = sdkAgent({
+  instructions: `You are an expert code analysis and refactoring assistant.
+
+Your capabilities:
+- Analyze code for quality issues, bugs, and improvements
+- Refactor code following best practices
+- Provide actionable recommendations
+
+Guidelines:
+- Be thorough but prioritize high-impact issues
+- Always explain the "why" behind recommendations
+- Consider performance, maintainability, and security
+- Respect existing code style when making changes`,
+
+  // Optional: specify model
+  // model: 'gpt-4',
+
+  // Optional: agent-level tool configuration
+  available_tools: ['filesystem', 'ripgrep', 'git'],
+
+  commands: {
+    analyze: sdkCommand({
+      name: 'analyze',
+      description: 'Analyze code quality and identify issues',
+      instructions: `Perform a comprehensive code analysis:
+
+1. Scan all matching files in the specified path
+2. Identify issues across these categories:
+   - Style: formatting, naming conventions, code organization
+   - Bugs: potential runtime errors, logic issues
+   - Security: vulnerabilities, unsafe patterns
+   - Performance: inefficiencies, optimization opportunities
+   - Maintainability: complexity, duplication, unclear code
+
+3. For each issue, provide:
+   - Exact file and line location
+   - Clear description of the problem
+   - Suggested fix when possible
+
+4. Calculate an overall quality score (0-100) based on:
+   - Issue density and severity
+   - Code organization
+   - Best practices adherence`,
+      available_tools: ['filesystem', 'ripgrep'],
+      args: analyzeArgsSchema,
+      output: analyzeOutputSchema,
+    }),
+
+    refactor: sdkCommand({
+      name: 'refactor',
+      description: 'Refactor code based on a specified pattern',
+      instructions: `Perform the requested refactoring:
+
+1. Search for code matching the specified pattern
+2. Apply the refactoring transformation
+3. Ensure changes don't break functionality
+4. If dry_run is true, describe changes without applying them
+5. Report all changes made with before/after snippets`,
+      available_tools: ['filesystem', 'ripgrep'],
+      args: refactorArgsSchema,
+      output: refactorOutputSchema,
+      permissions: 'rwx', // Read, write, execute
+    }),
+  },
+});
+
+// =============================================================================
+// STEP 4: Create and Use the SDK
+// =============================================================================
+
+async function main() {
+  // Create SDK from the agent configuration
+  const sdk = QodoSDK.fromAgent(codeAssistantAgent, {
+    // Optional: override project path (defaults to cwd)
+    // projectPath: '/path/to/project',
+
+    // Optional: enable debug logging
+    // debug: true,
+
+    // Optional: custom tool approval (default: auto-approve)
+    // autoApproveTools: false,
+    // toolApproval: async ({ tool_name, tool_args }) => {
+    //   console.log(`Tool requested: ${tool_name}`);
+    //   return true; // or prompt user
+    // },
+  });
+
+  try {
+    // -------------------------------------------------------------------------
+    // Example 1: Run with streaming events
+    // -------------------------------------------------------------------------
+    console.log('Starting code analysis with streaming...\n');
+
+    for await (const event of sdk.stream('analyze', {
+      args: {
+        path: './src',
+        severity_threshold: 'warning',
+      },
+    })) {
+      matchSdkEvent(event, {
+        [SdkEventType.Init]: (e) => {
+          console.log(`SDK v${e.data.sdk_version} initialized`);
+        },
+
+        [SdkEventType.RunStarted]: (e) => {
+          console.log(`Run started - Session: ${e.data.session_id}`);
+          console.log(`Command: ${e.data.command || '(prompt mode)'}`);
+        },
+
+        [SdkEventType.MessageDelta]: (e) => {
+          // Stream assistant's text output
+          process.stdout.write(e.data.delta);
+        },
+
+        [SdkEventType.Progress]: (e) => {
+          if (e.data.title) {
+            console.log(`\n[Progress] ${e.data.title}`);
+          }
+        },
+
+        [SdkEventType.ToolRequested]: (e) => {
+          console.log(`\n[Tool] ${e.data.server_name}.${e.data.tool_name}`);
+          if (e.data.pending_approval) {
+            console.log('  (awaiting approval)');
+          }
+        },
+
+        [SdkEventType.ToolExecuted]: (e) => {
+          const status = e.data.result.isError ? 'ERROR' : 'OK';
+          console.log(`[Tool Result] ${status}`);
+        },
+
+        [SdkEventType.Error]: (e) => {
+          console.error(`\n[Error] ${e.data.message}`);
+        },
+
+        [SdkEventType.Final]: (e) => {
+          console.log('\n\n--- Analysis Complete ---');
+          console.log(`Success: ${e.data.success}`);
+
+          if (e.data.result.structured_output) {
+            const output = e.data.result.structured_output;
+            console.log(`\nScore: ${output.score}/100`);
+            console.log(`Issues found: ${output.issues?.length || 0}`);
+            console.log(`\nSummary: ${output.summary}`);
+          }
+        },
+
+        // Catch-all for events we don't handle
+        default: () => {},
+      });
+    }
+
+    // -------------------------------------------------------------------------
+    // Example 2: Simple run (no streaming)
+    // -------------------------------------------------------------------------
+    console.log('\n\n--- Running refactor command ---\n');
+
+    const refactorResult = await sdk.run('refactor', {
+      args: {
+        path: './src/utils',
+        pattern: 'Convert var declarations to const/let',
+        dry_run: true,
+      },
+    });
+
+    if (refactorResult.success) {
+      console.log('Refactor analysis complete!');
+      console.log('Changes that would be made:');
+      refactorResult.structured_output?.changes_made?.forEach((change: any) => {
+        console.log(`  - ${change.file}: ${change.description}`);
+      });
+    } else {
+      console.error('Refactor failed:', refactorResult.error);
+    }
+
+    // -------------------------------------------------------------------------
+    // Example 3: Prompt mode (no predefined command)
+    // -------------------------------------------------------------------------
+    console.log('\n\n--- Prompt mode example ---\n');
+
+    const promptResult = await sdk.prompt(
+      'What are the most common patterns you see in this codebase?'
+    );
+
+    console.log('Response:', promptResult.final_output);
+  } catch (error) {
+    // Handle specific error types
+    if (error instanceof QodoSchemaError) {
+      console.error('Schema validation error:', error.message);
+      console.error('Check that all output properties have .describe()');
+    } else if (error instanceof QodoAuthError) {
+      console.error('Authentication error:', error.message);
+      console.error('Check your QODO_API_KEY environment variable');
+    } else {
+      throw error;
+    }
+  } finally {
+    // IMPORTANT: Always dispose to cleanup MCP servers and connections
+    await sdk.dispose();
+    console.log('\nSDK disposed, cleanup complete.');
+  }
+}
+
+// Run the example
+main().catch(console.error);

package/.claude/skills/qodo-agent/references/builtin-tools.md

@@ -0,0 +1,342 @@
+# Built-in Tools Reference
+
+This guide covers the built-in MCP tools available in `@qodo/sdk` and when to use each one.
+
+## Overview
+
+| Tool | Purpose | Use Cases |
+|------|---------|-----------|
+| `filesystem` | File operations | Read/write/edit files, navigate directories |
+| `git` | Version control | Check status, diff, commit, branch operations |
+| `ripgrep` | Code search | Find patterns in files, search across codebase |
+| `shell` | Command execution | Run system commands, scripts, build tools |
+
+---
+
+## filesystem
+
+File system operations with sandboxed access to allowed directories.
+
+### When to Use
+
+- Reading file contents (single or multiple files)
+- Writing or creating new files
+- Making targeted edits to existing files
+- Navigating and exploring directory structures
+- Moving, renaming, or deleting files
+
+### Available Operations
+
+| Operation | Description | Auto-Approved |
+|-----------|-------------|---------------|
+| `read_files` | Read one or more files with optional line ranges | No |
+| `write_file` | Create or overwrite a file | No |
+| `edit_file` | Make precise text replacements | No |
+| `create_directory` | Create directories (recursive) | No |
+| `list_files_in_directories` | List immediate children of directories | Yes |
+| `directory_tree` | Get recursive directory structure (folders only) | Yes |
+| `move_file` | Move or rename files/directories | No |
+| `get_file_info` | Get file metadata (size, dates, permissions) | Yes |
+| `list_allowed_directories` | Show accessible directories | Yes |
+| `delete_files` | Delete files or directories | No |
+
+### Example Usage
+
+```typescript
+// Agent that analyzes and refactors code needs filesystem access
+const agent = sdkAgent({
+  commands: {
+    analyze: sdkCommand({
+      name: 'analyze',
+      description: 'Analyze code quality',
+      available_tools: ['filesystem'],  // Read files, navigate directories
+      // ...
+    }),
+    refactor: sdkCommand({
+      name: 'refactor',
+      description: 'Refactor code',
+      available_tools: ['filesystem'],  // Read AND write files
+      // ...
+    }),
+  },
+});
+```
+
+### Key Features
+
+- **Line ranges**: Read specific portions of files with `startLine`/`endLine`, `head`, or `tail`
+- **Batch operations**: Read multiple files in one call
+- **Git-style diffs**: `edit_file` returns a diff showing changes made
+- **Safe by default**: Operations are sandboxed to allowed directories
+
+---
+
+## git
+
+Git version control operations.
+
+### When to Use
+
+- Checking repository status and changes
+- Viewing diffs (staged, unstaged, between branches)
+- Staging and committing changes
+- Creating and switching branches
+- Viewing commit history
+
+### Available Operations
+
+| Operation | Description | Auto-Approved |
+|-----------|-------------|---------------|
+| `git_status` | Show working tree status | Yes |
+| `git_diff_unstaged` | Show unstaged changes | Yes |
+| `git_diff_staged` | Show staged changes | Yes |
+| `git_diff` | Diff between branches/commits | Yes |
+| `git_diff_files` | Get file contents before/after changes | Yes |
+| `git_log` | Show commit history | Yes |
+| `git_show` | Show commit contents | Yes |
+| `git_add` | Stage files | No |
+| `git_reset` | Unstage all changes | No |
+| `git_commit` | Create a commit | No |
+| `git_init` | Initialize a repository | No |
+| `git_create_branch` | Create a new branch | No |
+| `git_checkout` | Switch branches | No |
+
+### Example Usage
+
+```typescript
+// Code review agent that examines changes
+const agent = sdkAgent({
+  commands: {
+    review: sdkCommand({
+      name: 'review',
+      description: 'Review code changes',
+      available_tools: ['git', 'filesystem'],  // Read diffs AND file contents
+      // ...
+    }),
+  },
+});
+```
+
+### Key Features
+
+- **Comprehensive diffs**: View changes at file, staged, or branch level
+- **File content access**: `git_diff_files` returns full before/after content for changed files
+- **Safe reads**: All read operations are auto-approved
+- **Branch operations**: Create, checkout, and manage branches
+
+---
+
+## ripgrep
+
+Fast code search using ripgrep (rg).
+
+### When to Use
+
+- Searching for patterns across a codebase
+- Finding function/class definitions
+- Locating usages of variables or imports
+- Searching with regex patterns
+- Filtering by file type
+
+### Available Operations
+
+| Operation | Description | Auto-Approved |
+|-----------|-------------|---------------|
+| `ripgrep_search` | Search for patterns in files | Yes |
+| `ripgrep_file_types` | List supported file types | Yes |
+
+### Example Usage
+
+```typescript
+// Agent that needs to find and understand code
+const agent = sdkAgent({
+  commands: {
+    findUsages: sdkCommand({
+      name: 'findUsages',
+      description: 'Find all usages of a function or variable',
+      available_tools: ['ripgrep', 'filesystem'],  // Search + read
+      // ...
+    }),
+  },
+});
+```
+
+### Search Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `pattern` | Search pattern (regex supported) | Required |
+| `fileTypes` | File extensions to search (e.g., `['ts', 'js']`) | Required |
+| `path` | Directory or file to search | `.` |
+| `caseSensitive` | Case-sensitive matching | `false` |
+| `wholeWord` | Match whole words only | `false` |
+| `fixedStrings` | Treat pattern as literal (not regex) | `false` |
+| `excludePatterns` | Patterns to exclude | `[]` |
+| `maxResults` | Maximum results to return | `100` |
+| `contextLines` | Lines of context around matches | `0` |
+| `includeHidden` | Include hidden files | `false` |
+
+### Key Features
+
+- **Fast**: Uses ripgrep for blazing-fast searches
+- **Regex support**: Full regex pattern matching
+- **File type filtering**: Required to focus searches and improve performance
+- **Context**: Optionally show surrounding lines
+
+### Tips
+
+1. **Always specify fileTypes** - This is required and improves search performance
+2. **Use `fixedStrings: true`** for literal searches with special characters
+3. **Combine with filesystem** - Search finds locations, then read for full context
+
+---
+
+## shell
+
+Execute shell commands with optional sandboxing.
+
+### When to Use
+
+- Running build tools (npm, cargo, make)
+- Executing scripts
+- System commands (with appropriate permissions)
+- Any command not covered by other tools
+
+### Available Operations
+
+| Operation | Description | Auto-Approved |
+|-----------|-------------|---------------|
+| `shell_execute` | Execute a command | Depends on command |
+
+### Auto-Approved Commands
+
+These read-only commands run without user confirmation:
+
+**Unix/Linux/macOS:**
+- `ls`, `pwd`, `whoami`, `date`, `echo`
+- `cat`, `head`, `tail`, `grep`, `find`
+- `wc`, `env`, `printenv`, `which`
+- `ps`, `df`, `du`, `hostname`, `uname`, `id`, `groups`
+
+**Windows:**
+- `dir`, `echo`, `ver`, `where`, `whoami`, `hostname`
+
+### Example Usage
+
+```typescript
+// Build agent that runs npm commands
+const agent = sdkAgent({
+  commands: {
+    build: sdkCommand({
+      name: 'build',
+      description: 'Build the project',
+      available_tools: ['shell', 'filesystem'],
+      // ...
+    }),
+    test: sdkCommand({
+      name: 'test',
+      description: 'Run tests',
+      available_tools: ['shell'],
+      // ...
+    }),
+  },
+});
+```
+
+### Execute Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `command` | Command to execute | Required |
+| `args` | Command arguments array | `[]` |
+| `cwd` | Working directory | Current directory |
+| `timeout` | Timeout in milliseconds | `30000` |
+| `use_shell` | Execute through shell (enables pipes, redirects) | `false` |
+
+### Key Features
+
+- **Shell mode**: Set `use_shell: true` for piping, redirection, etc.
+- **Timeout protection**: Commands are killed after timeout
+- **Cross-platform**: Works on macOS, Linux, and Windows
+- **Optional sandboxing**: macOS supports sandbox-exec profiles
+
+### Tips
+
+1. **Prefer direct execution** (`use_shell: false`) for better security
+2. **Use `use_shell: true`** only when you need shell features (pipes, redirects)
+3. **Set appropriate timeouts** for long-running commands
+
+---
+
+## Tool Combinations
+
+Common tool combinations for different tasks:
+
+### Code Analysis
+
+```typescript
+available_tools: ['filesystem', 'ripgrep']
+```
+Search for patterns, then read full file contents for context.
+
+### Code Modification
+
+```typescript
+available_tools: ['filesystem', 'git']
+```
+Read/edit files, then check status and create commits.
+
+### Full Development Workflow
+
+```typescript
+available_tools: ['filesystem', 'git', 'ripgrep', 'shell']
+```
+Complete access for complex development tasks.
+
+### Code Review
+
+```typescript
+available_tools: ['git', 'filesystem']
+```
+View diffs and read changed files for review.
+
+### Build & Test
+
+```typescript
+available_tools: ['shell', 'filesystem']
+```
+Run build commands and check output files.
+
+---
+
+## Security Considerations
+
+1. **Sandboxed Access**: filesystem operations are limited to allowed directories
+2. **Auto-Approval**: Read-only operations are generally auto-approved; write operations require approval
+3. **Shell Safety**: Direct execution is preferred over shell mode for security
+4. **Timeout Protection**: All shell commands have enforced timeouts
+
+---
+
+## Troubleshooting
+
+### Tool Not Available
+
+If a tool isn't working, check:
+
+1. **Tool in `available_tools`**: Ensure the tool is listed in your command config
+2. **Not in `ignore_tools`**: Make sure it's not accidentally ignored
+3. **Dependencies installed**: ripgrep requires `rg` to be installed (or `@vscode/ripgrep` package)
+
+### Permission Denied
+
+For filesystem operations:
+- Check that the path is within allowed directories
+- Use `list_allowed_directories` to see accessible paths
+
+### Shell Commands Failing
+
+- Check the command exists on the system
+- Verify the working directory exists
+- Use `use_shell: true` if you need shell features
+- Increase timeout for long-running commands