@agentforge/cli 0.3.9 → 0.4.0

package/templates/tool-multi/README.md

@@ -0,0 +1,169 @@
+# {{TOOL_NAME_PASCAL}} Tool
+
+{{TOOL_DESCRIPTION}}
+
+## Category
+
+`{{TOOL_CATEGORY}}`
+
+## Installation
+
+This tool is part of your AgentForge project. No additional installation required.
+
+## Usage
+
+```typescript
+import { {{TOOL_NAME_CAMEL}}Tool } from './tools/{{TOOL_NAME}}/index.js';
+
+// Use in an agent
+const agent = createReActAgent({
+  model,
+  tools: [{{TOOL_NAME_CAMEL}}Tool],
+  // ...
+});
+
+// Or invoke directly
+const result = await {{TOOL_NAME_CAMEL}}Tool.invoke({
+  input: 'example input',
+});
+
+console.log(result);
+```
+
+## Input Schema
+
+```typescript
+{
+  input: string; // Input parameter (required, non-empty)
+}
+```
+
+## Output Schema
+
+```typescript
+{
+  success: boolean;        // Whether the operation was successful
+  data?: any;             // Result data (when successful)
+  error?: string;         // Error message (when failed)
+  metadata?: {            // Additional metadata
+    responseTime?: number;
+    [key: string]: any;
+  };
+}
+```
+
+## File Structure
+
+```
+{{TOOL_NAME}}/
+├── index.ts              # Main tool definition
+├── types.ts              # TypeScript type definitions
+├── schemas.ts            # Zod validation schemas
+├── utils.ts              # Utility functions
+├── providers/            # External service integrations
+│   └── example.ts        # Example provider
+├── __tests__/            # Test files
+│   └── index.test.ts     # Main test suite
+└── README.md             # This file
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests for this tool only
+pnpm test {{TOOL_NAME}}
+
+# Watch mode
+pnpm test:watch {{TOOL_NAME}}
+```
+
+### Adding Providers
+
+To add a new provider (e.g., for integrating with an external API):
+
+1. Create a new file in `providers/` directory:
+   ```typescript
+   // providers/myProvider.ts
+   export async function myProvider(input: string): Promise<{{TOOL_NAME_PASCAL}}Output> {
+     // Implementation
+   }
+   ```
+
+2. Import and use in `index.ts`:
+   ```typescript
+   import { myProvider } from './providers/myProvider.js';
+   ```
+
+### Extending Types
+
+Add new types in `types.ts`:
+
+```typescript
+export interface MyCustomType {
+  // Your properties
+}
+```
+
+### Adding Validation
+
+Add new schemas in `schemas.ts`:
+
+```typescript
+export const MyCustomSchema = z.object({
+  // Your schema
+});
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+const result = await {{TOOL_NAME_CAMEL}}Tool.invoke({
+  input: 'test input',
+});
+
+if (result.success) {
+  console.log('Success:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await {{TOOL_NAME_CAMEL}}Tool.invoke({
+    input: 'test',
+  });
+  
+  if (!result.success) {
+    throw new Error(result.error);
+  }
+  
+  // Process result.data
+} catch (error) {
+  console.error('Tool execution failed:', error);
+}
+```
+
+## TODO
+
+- [ ] Implement core functionality in `index.ts`
+- [ ] Add provider implementations in `providers/`
+- [ ] Define proper input/output types in `types.ts`
+- [ ] Add comprehensive validation in `schemas.ts`
+- [ ] Write tests in `__tests__/index.test.ts`
+- [ ] Add utility functions in `utils.ts`
+- [ ] Update this README with actual usage examples
+
+## License
+
+MIT
+

package/templates/tool-multi/__tests__/index.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { {{TOOL_NAME_CAMEL}}Tool } from '../index.js';
+
+describe('{{TOOL_NAME_PASCAL}} Tool', () => {
+  it('should have correct metadata', () => {
+    expect({{TOOL_NAME_CAMEL}}Tool.name).toBe('{{TOOL_NAME}}');
+    expect({{TOOL_NAME_CAMEL}}Tool.description).toBe('{{TOOL_DESCRIPTION}}');
+    expect({{TOOL_NAME_CAMEL}}Tool.category).toBe('{{TOOL_CATEGORY}}');
+  });
+
+  it('should validate input schema', async () => {
+    // Valid input
+    const validInput = {
+      input: 'test input',
+    };
+    
+    const result = await {{TOOL_NAME_CAMEL}}Tool.invoke(validInput);
+    expect(result).toBeDefined();
+    expect(result.success).toBe(true);
+  });
+
+  it('should reject invalid input', async () => {
+    // Invalid input (empty string)
+    const invalidInput = {
+      input: '',
+    };
+    
+    await expect({{TOOL_NAME_CAMEL}}Tool.invoke(invalidInput)).rejects.toThrow();
+  });
+
+  it('should execute successfully with valid input', async () => {
+    const input = {
+      input: 'test',
+    };
+
+    const result = await {{TOOL_NAME_CAMEL}}Tool.invoke(input);
+
+    expect(result).toBeDefined();
+    expect(result.success).toBe(true);
+    expect(result.data).toBeDefined();
+  });
+
+  it('should handle errors gracefully', async () => {
+    // TODO: Add error handling tests
+    // Example: Test with invalid API key, network errors, etc.
+  });
+
+  // TODO: Add more specific tests for your tool
+});
+

package/templates/tool-multi/index.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { createTool } from '@agentforge/core';
+import { {{TOOL_NAME_PASCAL}}Schema } from './schemas.js';
+import type { {{TOOL_NAME_PASCAL}}Input, {{TOOL_NAME_PASCAL}}Output } from './types.js';
+
+/**
+ * {{TOOL_DESCRIPTION}}
+ * 
+ * Category: {{TOOL_CATEGORY}}
+ * 
+ * @example
+ * ```typescript
+ * const result = await {{TOOL_NAME_CAMEL}}Tool.invoke({
+ *   input: 'example input',
+ * });
+ * console.log(result);
+ * ```
+ */
+export const {{TOOL_NAME_CAMEL}}Tool = createTool()
+  .name('{{TOOL_NAME}}')
+  .description('{{TOOL_DESCRIPTION}}')
+  .category('{{TOOL_CATEGORY}}')
+  .schema({{TOOL_NAME_PASCAL}}Schema)
+  .implement(async (input: {{TOOL_NAME_PASCAL}}Input): Promise<{{TOOL_NAME_PASCAL}}Output> => {
+    try {
+      // TODO: Implement your tool logic here
+      
+      // Example implementation:
+      const result = `Processed: ${input.input}`;
+      
+      return {
+        success: true,
+        data: result,
+      };
+    } catch (error: any) {
+      return {
+        success: false,
+        error: error.message,
+      };
+    }
+  })
+  .build();
+
+// Re-export types for convenience
+export * from './types.js';
+export * from './schemas.js';
+

package/templates/tool-multi/providers/example.ts

@@ -0,0 +1,34 @@
+/**
+ * Example provider for {{TOOL_NAME}} tool
+ * 
+ * This is a template for creating providers that integrate with external services.
+ * Replace this with your actual provider implementation.
+ */
+
+import type { {{TOOL_NAME_PASCAL}}Output } from '../types.js';
+
+/**
+ * Example provider function
+ * 
+ * @param input - Input parameter
+ * @returns Provider result
+ */
+export async function exampleProvider(input: string): Promise<{{TOOL_NAME_PASCAL}}Output> {
+  try {
+    // TODO: Implement your provider logic here
+    // Example: Call external API, process data, etc.
+    
+    const result = `Provider processed: ${input}`;
+    
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (error: any) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+

package/templates/tool-multi/schemas.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for {{TOOL_NAME}} tool input validation
+ */
+export const {{TOOL_NAME_PASCAL}}Schema = z.object({
+  /**
+   * Input parameter
+   * TODO: Define your input schema
+   */
+  input: z.string()
+    .min(1, 'Input cannot be empty')
+    .describe('Input parameter'),
+});
+
+/**
+ * Infer the input type from the schema
+ */
+export type {{TOOL_NAME_PASCAL}}Input = z.infer<typeof {{TOOL_NAME_PASCAL}}Schema>;
+

package/templates/tool-multi/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Type definitions for {{TOOL_NAME}} tool
+ */
+
+/**
+ * Input type for {{TOOL_NAME}} tool
+ */
+export interface {{TOOL_NAME_PASCAL}}Input {
+  /**
+   * Input parameter
+   * TODO: Define your input properties
+   */
+  input: string;
+}
+
+/**
+ * Output type for {{TOOL_NAME}} tool
+ */
+export interface {{TOOL_NAME_PASCAL}}Output {
+  /**
+   * Whether the operation was successful
+   */
+  success: boolean;
+  
+  /**
+   * Result data (when successful)
+   */
+  data?: any;
+  
+  /**
+   * Error message (when failed)
+   */
+  error?: string;
+  
+  /**
+   * Additional metadata
+   */
+  metadata?: {
+    /**
+     * Response time in milliseconds
+     */
+    responseTime?: number;
+    
+    /**
+     * Additional context
+     */
+    [key: string]: any;
+  };
+}
+

package/templates/tool-multi/utils.ts

@@ -0,0 +1,55 @@
+/**
+ * Utility functions for {{TOOL_NAME}} tool
+ */
+
+/**
+ * Delay execution for a specified number of milliseconds
+ * 
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Format error message
+ * 
+ * @param error - Error object or message
+ * @returns Formatted error message
+ */
+export function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  return 'An unknown error occurred';
+}
+
+/**
+ * Validate environment variable
+ * 
+ * @param name - Environment variable name
+ * @returns Environment variable value
+ * @throws Error if environment variable is not set
+ */
+export function getEnvVar(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Environment variable ${name} is not set`);
+  }
+  return value;
+}
+
+/**
+ * Get optional environment variable
+ * 
+ * @param name - Environment variable name
+ * @returns Environment variable value or undefined
+ */
+export function getOptionalEnvVar(name: string): string | undefined {
+  return process.env[name];
+}
+