@output.ai/cli 0.4.1 → 0.5.0

package/dist/templates/agent_instructions/skills/output-error-http-client/SKILL.md.template

@@ -0,0 +1,298 @@
+---
+name: output-error-http-client
+description: Fix HTTP client misuse in Output SDK steps. Use when seeing untraced requests, missing error details, axios-related errors, or when HTTP calls aren't being properly logged and retried.
+allowed-tools: [Bash, Read]
+---
+
+# Fix HTTP Client Misuse
+
+## Overview
+
+This skill helps diagnose and fix issues caused by using axios, fetch, or other HTTP clients directly instead of Output SDK's `httpClient` from `@output.ai/http`. The Output SDK client provides tracing, automatic retries, and better error handling.
+
+## When to Use This Skill
+
+You're seeing:
+- Untraced HTTP requests (not appearing in workflow traces)
+- Missing error details for failed requests
+- axios-related errors or import issues
+- Retries not working for HTTP failures
+- Inconsistent timeout behavior
+
+## Root Cause
+
+Using axios, fetch, or other HTTP clients directly bypasses Output SDK's:
+- **Request/response tracing**: Calls aren't logged in workflow traces
+- **Automatic retries**: Failed requests aren't retried
+- **Error standardization**: Error formats may be inconsistent
+- **Timeout handling**: Timeouts may not integrate with step timeouts
+
+## Symptoms
+
+### Using axios Directly
+
+```typescript
+// WRONG: Using axios
+import axios from 'axios';
+
+export const fetchData = step({
+  name: 'fetchData',
+  fn: async (input) => {
+    const response = await axios.get('https://api.example.com/data');
+    return response.data;
+  },
+});
+```
+
+### Using fetch Directly
+
+```typescript
+// WRONG: Using fetch
+export const fetchData = step({
+  name: 'fetchData',
+  fn: async (input) => {
+    const response = await fetch('https://api.example.com/data');
+    return response.json();
+  },
+});
+```
+
+## Solution
+
+Use `httpClient` from `@output.ai/http`:
+
+### Basic Usage
+
+```typescript
+import { z, step } from '@output.ai/core';
+import { httpClient } from '@output.ai/http';
+
+export const fetchData = step({
+  name: 'fetchData',
+  inputSchema: z.object({
+    endpoint: z.string(),
+  }),
+  outputSchema: z.object({
+    data: z.unknown(),
+  }),
+  fn: async (input) => {
+    const client = httpClient({
+      prefixUrl: 'https://api.example.com',
+    });
+
+    const data = await client.get(input.endpoint).json();
+    return { data };
+  },
+});
+```
+
+### With Full Configuration
+
+```typescript
+import { httpClient } from '@output.ai/http';
+
+const client = httpClient({
+  prefixUrl: 'https://api.example.com',
+  timeout: 30000,  // 30 second timeout
+  retry: {
+    limit: 3,      // Retry up to 3 times
+    methods: ['GET', 'POST'],  // Which methods to retry
+    statusCodes: [408, 500, 502, 503, 504],  // Which status codes trigger retry
+  },
+  headers: {
+    'Authorization': `Bearer ${apiKey}`,
+    'Content-Type': 'application/json',
+  },
+});
+```
+
+## HTTP Methods
+
+### GET Request
+
+```typescript
+const data = await client.get('users/123').json();
+```
+
+### POST Request
+
+```typescript
+const result = await client.post('users', {
+  json: {
+    name: 'John',
+    email: 'john@example.com',
+  },
+}).json();
+```
+
+### PUT Request
+
+```typescript
+const updated = await client.put('users/123', {
+  json: {
+    name: 'John Updated',
+  },
+}).json();
+```
+
+### DELETE Request
+
+```typescript
+await client.delete('users/123');
+```
+
+### With Query Parameters
+
+```typescript
+const data = await client.get('search', {
+  searchParams: {
+    q: 'query',
+    limit: 10,
+  },
+}).json();
+```
+
+## Complete Migration Example
+
+### Before (Wrong - using axios)
+
+```typescript
+import axios from 'axios';
+import { step } from '@output.ai/core';
+
+export const createUser = step({
+  name: 'createUser',
+  fn: async (input) => {
+    try {
+      const response = await axios.post(
+        'https://api.example.com/users',
+        { name: input.name, email: input.email },
+        {
+          headers: { 'Authorization': `Bearer ${process.env.API_KEY}` },
+          timeout: 30000,
+        }
+      );
+      return response.data;
+    } catch (error) {
+      if (axios.isAxiosError(error)) {
+        throw new Error(`API Error: ${error.response?.data?.message}`);
+      }
+      throw error;
+    }
+  },
+});
+```
+
+### After (Correct - using httpClient)
+
+```typescript
+import { z, step } from '@output.ai/core';
+import { httpClient } from '@output.ai/http';
+
+export const createUser = step({
+  name: 'createUser',
+  inputSchema: z.object({
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  outputSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+  }),
+  fn: async (input) => {
+    const client = httpClient({
+      prefixUrl: 'https://api.example.com',
+      timeout: 30000,
+      retry: { limit: 3 },
+      headers: {
+        'Authorization': `Bearer ${process.env.API_KEY}`,
+      },
+    });
+
+    const user = await client.post('users', {
+      json: {
+        name: input.name,
+        email: input.email,
+      },
+    }).json();
+
+    return user;
+  },
+});
+```
+
+## Error Handling
+
+The httpClient provides structured error handling:
+
+```typescript
+import { httpClient, HTTPError } from '@output.ai/http';
+
+export const fetchData = step({
+  name: 'fetchData',
+  fn: async (input) => {
+    const client = httpClient({ prefixUrl: 'https://api.example.com' });
+
+    try {
+      return await client.get('data').json();
+    } catch (error) {
+      if (error instanceof HTTPError) {
+        // Access response details
+        const status = error.response.status;
+        const body = await error.response.json();
+        throw new Error(`API returned ${status}: ${body.message}`);
+      }
+      throw error;
+    }
+  },
+});
+```
+
+## Finding axios/fetch Usage
+
+Search your codebase:
+
+```bash
+# Find axios imports
+grep -rn "from 'axios'\|from \"axios\"" src/
+
+# Find fetch calls
+grep -rn "await fetch(" src/
+
+# Find other HTTP libraries
+grep -rn "got\|node-fetch\|request\|superagent" src/
+```
+
+## Benefits of httpClient
+
+1. **Tracing**: Requests appear in workflow traces with timing
+2. **Automatic Retries**: Configurable retry logic for transient failures
+3. **Consistent Errors**: Standardized error format across all requests
+4. **Timeout Integration**: Works with step and workflow timeouts
+5. **Type Safety**: Full TypeScript support
+
+## Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `prefixUrl` | Base URL for all requests | (required) |
+| `timeout` | Request timeout in ms | 10000 |
+| `retry.limit` | Max retry attempts | 2 |
+| `retry.methods` | HTTP methods to retry | ['GET', 'PUT', 'HEAD', 'DELETE', 'OPTIONS', 'TRACE'] |
+| `retry.statusCodes` | Status codes to retry | [408, 413, 429, 500, 502, 503, 504] |
+| `headers` | Default headers | {} |
+
+## Verification
+
+After migrating to httpClient:
+
+1. **Run the workflow**: `output workflow run <name> '<input>'`
+2. **Check the trace**: `output workflow debug <id> --format json`
+3. **Verify tracing**: HTTP requests should appear in the step trace
+4. **Test retries**: Simulate failures to verify retry behavior
+
+## Related Issues
+
+- For I/O in workflow functions, see `output-error-direct-io`
+- For connection issues, see `output-services-check`

package/dist/templates/agent_instructions/skills/output-error-missing-schemas/SKILL.md.template

@@ -0,0 +1,265 @@
+---
+name: output-error-missing-schemas
+description: Fix missing schema definitions in Output SDK steps. Use when seeing type errors, undefined properties at step boundaries, validation failures, or when step inputs/outputs aren't being properly typed.
+allowed-tools: [Bash, Read]
+---
+
+# Fix Missing Schema Definitions
+
+## Overview
+
+This skill helps diagnose and fix issues caused by steps that lack explicit `inputSchema` or `outputSchema` definitions. Schemas are essential for type safety, validation, and proper data serialization between steps.
+
+## When to Use This Skill
+
+You're seeing:
+- Type errors at step boundaries
+- Undefined properties in step inputs/outputs
+- Validation failures when passing data between steps
+- TypeScript errors about incompatible types
+- Runtime errors about unexpected data shapes
+
+## Root Cause
+
+Steps without explicit schemas:
+- Don't validate input data at runtime
+- Don't provide TypeScript type inference
+- May serialize/deserialize data incorrectly
+- Can pass undefined or malformed data silently
+
+## Symptoms
+
+### Missing Input Schema
+
+```typescript
+// WRONG: No input validation
+export const processData = step({
+  name: 'processData',
+  // inputSchema: missing!
+  outputSchema: z.object({ result: z.string() }),
+  fn: async (input) => {
+    return { result: input.value };  // input.value might be undefined!
+  }
+});
+```
+
+### Missing Output Schema
+
+```typescript
+// WRONG: No output validation
+export const fetchData = step({
+  name: 'fetchData',
+  inputSchema: z.object({ id: z.string() }),
+  // outputSchema: missing!
+  fn: async (input) => {
+    return { data: await getFromApi(input.id) };  // Output shape not validated
+  }
+});
+```
+
+### Both Schemas Missing
+
+```typescript
+// WRONG: No validation at all
+export const transformData = step({
+  name: 'transformData',
+  // No schemas!
+  fn: async (input) => {
+    return transform(input);
+  }
+});
+```
+
+## Solution
+
+Always define both `inputSchema` and `outputSchema` for every step:
+
+### Complete Step Definition
+
+```typescript
+import { z, step } from '@output.ai/core';
+
+export const processData = step({
+  name: 'processData',
+  inputSchema: z.object({
+    id: z.string(),
+    value: z.number(),
+    optional: z.string().optional(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+    processedAt: z.number(),
+  }),
+  fn: async (input) => {
+    // input is fully typed: { id: string, value: number, optional?: string }
+    return {
+      result: `Processed ${input.id}`,
+      processedAt: Date.now(),
+    };
+    // output is validated against outputSchema
+  },
+});
+```
+
+## Schema Definition Best Practices
+
+### Use Descriptive Schemas
+
+```typescript
+// Good: Clear, descriptive schema
+inputSchema: z.object({
+  userId: z.string().uuid(),
+  email: z.string().email(),
+  age: z.number().int().positive(),
+})
+```
+
+### Handle Optional Fields
+
+```typescript
+inputSchema: z.object({
+  required: z.string(),
+  optional: z.string().optional(),
+  withDefault: z.string().default('fallback'),
+})
+```
+
+### Use Schema Composition
+
+```typescript
+// Define reusable schemas
+const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+});
+
+const addressSchema = z.object({
+  street: z.string(),
+  city: z.string(),
+});
+
+// Compose in step
+inputSchema: z.object({
+  user: userSchema,
+  address: addressSchema,
+})
+```
+
+### Handle Arrays and Nested Objects
+
+```typescript
+inputSchema: z.object({
+  items: z.array(z.object({
+    id: z.string(),
+    quantity: z.number(),
+  })),
+  metadata: z.record(z.string()),
+})
+```
+
+## Finding Steps Without Schemas
+
+Search your codebase:
+
+```bash
+# Find step definitions
+grep -rn "step({" src/workflows/
+
+# Look for steps without inputSchema
+grep -A5 "step({" src/workflows/ | grep -B2 "fn:"
+
+# Check if schemas are present
+grep -rn "inputSchema:" src/workflows/
+grep -rn "outputSchema:" src/workflows/
+```
+
+Review each step definition to ensure both schemas are present.
+
+## Benefits of Explicit Schemas
+
+1. **Runtime Validation**: Catches data errors early
+2. **Type Safety**: Full TypeScript inference in step functions
+3. **Documentation**: Schemas document expected data shapes
+4. **Serialization**: Ensures proper data serialization between steps
+5. **Error Messages**: Clear validation errors when data is wrong
+
+## Common Schema Patterns
+
+### API Response Steps
+
+```typescript
+export const fetchUser = step({
+  name: 'fetchUser',
+  inputSchema: z.object({
+    userId: z.string(),
+  }),
+  outputSchema: z.object({
+    user: z.object({
+      id: z.string(),
+      name: z.string(),
+      email: z.string(),
+    }).nullable(),  // Handle not found
+    found: z.boolean(),
+  }),
+  fn: async (input) => {
+    const user = await api.getUser(input.userId);
+    return { user, found: user !== null };
+  },
+});
+```
+
+### Transformation Steps
+
+```typescript
+export const transformData = step({
+  name: 'transformData',
+  inputSchema: z.object({
+    raw: z.array(z.unknown()),
+  }),
+  outputSchema: z.object({
+    processed: z.array(z.object({
+      id: z.string(),
+      value: z.number(),
+    })),
+    count: z.number(),
+  }),
+  fn: async (input) => {
+    const processed = input.raw.map(transformItem);
+    return { processed, count: processed.length };
+  },
+});
+```
+
+### Void Output Steps
+
+For steps that don't return meaningful data:
+
+```typescript
+export const logEvent = step({
+  name: 'logEvent',
+  inputSchema: z.object({
+    event: z.string(),
+    data: z.record(z.unknown()),
+  }),
+  outputSchema: z.object({
+    logged: z.literal(true),
+  }),
+  fn: async (input) => {
+    await logger.log(input.event, input.data);
+    return { logged: true };
+  },
+});
+```
+
+## Verification
+
+After adding schemas:
+
+1. **TypeScript check**: `npm run build` should pass without type errors
+2. **Runtime test**: `output workflow run <name> '<input>'` should validate correctly
+3. **Invalid input test**: Pass invalid data and verify validation errors appear
+
+## Related Issues
+
+- For Zod import issues, see `output-error-zod-import`
+- For type mismatches despite schemas, verify schema matches actual data