@qodo/sdk 0.13.4 → 2.0.0-next.1

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

@@ -1,407 +0,0 @@
-/**
- * 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()
- * - Pipeline DSL with typed state threading
- * - Tool middleware for auditing
- * - Dry run mode
- * - Execution timeouts
- * - Error handling
- * - Proper cleanup with dispose()
- *
- * Usage:
- *   npx tsx programmatic-agent.ts
- */
-
-import {
-  QodoSDK,
-  sdkAgent,
-  sdkCommand,
-  sdkArgs,
-  SdkEventType,
-  matchSdkEvent,
-  zJsonValue,
-  zJsonAny,
-  QodoSchemaError,
-  QodoAuthError,
-  QodoOutputValidationError,
-  sdkPipeline,
-  runPipeline,
-  z,
-  type ToolMiddleware,
-} from '@qodo/sdk';
-
-// =============================================================================
-// 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() {
-  // Optional: create tool middleware for auditing
-  const auditMiddleware: ToolMiddleware = {
-    name: 'audit',
-    preExecute(toolData) {
-      console.log(`  [audit] >>> ${toolData.server_name}.${toolData.tool_name}`);
-    },
-    postExecute(toolData, result) {
-      console.log(`  [audit] <<< ${result.isError ? 'ERROR' : 'OK'}`);
-    },
-  };
-
-  // 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: tool middleware for auditing, rate limiting, etc.
-    toolMiddleware: [auditMiddleware],
-
-    // 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:');
-      // @ts-ignore
-      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?'
-    );
-    // @ts-ignore
-    console.log('Response:', promptResult.final_output);
-    // -------------------------------------------------------------------------
-    // Example 4: Pipeline (multi-step workflow with gates and branches)
-    // -------------------------------------------------------------------------
-    console.log('\n\n--- Pipeline example ---\n');
-
-    const pipeline = sdkPipeline<{ path: string }>()
-      .step('analyze', async ({ state, run }) => {
-        const r = await run('analyze', { args: { path: state.path } });
-        return { analysis: r.result.structured_output };
-      })
-      // Gate: only continue if analysis produced results
-      .gate((state) => !!state.analysis, { name: 'has-analysis' })
-      // Branch: choose different summary strategies based on score
-      .branch(
-        (state) => (state.analysis as any)?.score > 80,
-        {
-          true: (b) => b.step('brief-summary', async ({ state, run }) => {
-            const r = await run('', {
-              extraInstructions: `High quality code (score: ${(state.analysis as any)?.score}). Brief summary: ${JSON.stringify(state.analysis)}`,
-            });
-            return { summary: r.result.final_output };
-          }),
-          false: (b) => b.step('detailed-summary', async ({ state, run }) => {
-            const r = await run('', {
-              extraInstructions: `Code needs improvement. Detailed summary with recommendations: ${JSON.stringify(state.analysis)}`,
-            });
-            return { summary: r.result.final_output };
-          }),
-        },
-        { name: 'quality-check' },
-      )
-      .build();
-
-    const pipelineResult = await runPipeline(sdk, pipeline, { path: './src' });
-    console.log('Pipeline summary:', pipelineResult.state.summary);
-    for (const log of pipelineResult.steps) {
-      const branch = log.branchTaken ? ` (branch: ${log.branchTaken})` : '';
-      console.log(`  ${log.name}: ${log.status}${branch} (${log.durationMs}ms)`);
-    }
-
-    // -------------------------------------------------------------------------
-    // Example 5: Dry run mode (preview without side effects)
-    // -------------------------------------------------------------------------
-    console.log('\n\n--- Dry run example ---\n');
-
-    const dryResult = await sdk.run('analyze', {
-      args: { path: './src' },
-      dryRun: true,
-    });
-    console.log('Dry run output:', dryResult.result.final_output?.slice(0, 200));
-    console.log('Was dry run:', dryResult.meta.dry_run);
-
-    // -------------------------------------------------------------------------
-    // Example 6: Execution timeout with retry
-    // -------------------------------------------------------------------------
-    console.log('\n\n--- Timeout example ---\n');
-
-    const timedResult = await sdk.run('analyze', {
-      args: { path: './src' },
-      timeout: 60000,     // 60 second limit
-      maxRetries: 1,      // Retry once on failure
-    });
-    console.log('Timed out:', timedResult.meta.timed_out ?? false);
-
-  } 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 if (error instanceof QodoOutputValidationError) {
-      console.error('Output validation error:', error.issues);
-      console.error('Raw output:', error.rawOutput);
-    } 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);