@output.ai/cli 0.5.6 → 0.6.0

package/dist/templates/agent_instructions/skills/output-error-direct-io/SKILL.md.template

@@ -1,249 +0,0 @@
----
-name: output-error-direct-io
-description: Fix direct I/O in Output SDK workflow functions. Use when workflow hangs, returns undefined, shows "workflow must be deterministic" errors, or when HTTP/API calls are made directly in workflow code.
-allowed-tools: [Bash, Read]
----
-
-# Fix Direct I/O in Workflow Functions
-
-## Overview
-
-This skill helps diagnose and fix a critical error pattern where I/O operations (HTTP calls, database queries, file operations) are performed directly in workflow functions instead of in steps. This violates Temporal's determinism requirements.
-
-## When to Use This Skill
-
-You're seeing:
-- Workflow hangs indefinitely
-- Undefined or empty responses
-- "workflow must be deterministic" errors
-- Network operations failing silently
-- Timeouts without clear cause
-
-## Root Cause
-
-Workflow functions must be **deterministic** - they should only orchestrate steps, not perform I/O directly. When you make HTTP calls, database queries, or any external operations directly in a workflow function:
-
-1. **Hangs**: The workflow may hang because I/O isn't properly handled
-2. **Determinism violations**: Temporal replays workflows, and I/O results differ
-3. **No retry logic**: Direct calls bypass Output SDK's retry mechanisms
-4. **No tracing**: Operations aren't recorded in the workflow trace
-
-## Symptoms
-
-### Direct fetch/axios in Workflow
-
-```typescript
-// WRONG: I/O directly in workflow
-export default workflow({
-  fn: async (input) => {
-    const response = await fetch('https://api.example.com/data');  // BAD!
-    const data = await response.json();
-    return { data };
-  }
-});
-```
-
-### Direct Database Calls
-
-```typescript
-// WRONG: Database I/O in workflow
-export default workflow({
-  fn: async (input) => {
-    const user = await db.users.findById(input.userId);  // BAD!
-    return { user };
-  }
-});
-```
-
-### File System Operations
-
-```typescript
-// WRONG: File I/O in workflow
-import fs from 'fs/promises';
-
-export default workflow({
-  fn: async (input) => {
-    const data = await fs.readFile(input.path, 'utf-8');  // BAD!
-    return { data };
-  }
-});
-```
-
-## Solution
-
-Move ALL I/O operations to step functions. Steps are designed to handle non-deterministic operations.
-
-### Before (Wrong)
-
-```typescript
-export default workflow({
-  fn: async (input) => {
-    const response = await fetch('https://api.example.com/data');
-    const data = await response.json();
-    return { data };
-  }
-});
-```
-
-### After (Correct)
-
-```typescript
-import { z, step, workflow } from '@output.ai/core';
-import { httpClient } from '@output.ai/http';
-
-// Create a step for the I/O operation
-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 };
-  },
-});
-
-// Workflow only orchestrates steps
-export default workflow({
-  inputSchema: z.object({}),
-  outputSchema: z.object({ data: z.unknown() }),
-  fn: async (input) => {
-    const result = await fetchData({ endpoint: 'data' });
-    return result;
-  },
-});
-```
-
-## Complete Example: Database Operation
-
-### Before (Wrong)
-
-```typescript
-export default workflow({
-  fn: async (input) => {
-    const user = await prisma.user.findUnique({
-      where: { id: input.userId }
-    });
-    const orders = await prisma.order.findMany({
-      where: { userId: input.userId }
-    });
-    return { user, orders };
-  }
-});
-```
-
-### After (Correct)
-
-```typescript
-import { z, step, workflow } from '@output.ai/core';
-import { prisma } from '../lib/db';
-
-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(),
-  }),
-  fn: async (input) => {
-    const user = await prisma.user.findUnique({
-      where: { id: input.userId }
-    });
-    return { user };
-  },
-});
-
-export const fetchOrders = step({
-  name: 'fetchOrders',
-  inputSchema: z.object({ userId: z.string() }),
-  outputSchema: z.object({
-    orders: z.array(z.object({
-      id: z.string(),
-      total: z.number(),
-    })),
-  }),
-  fn: async (input) => {
-    const orders = await prisma.order.findMany({
-      where: { userId: input.userId }
-    });
-    return { orders };
-  },
-});
-
-export default workflow({
-  inputSchema: z.object({ userId: z.string() }),
-  outputSchema: z.object({
-    user: z.unknown(),
-    orders: z.array(z.unknown()),
-  }),
-  fn: async (input) => {
-    const { user } = await fetchUser({ userId: input.userId });
-    const { orders } = await fetchOrders({ userId: input.userId });
-    return { user, orders };
-  },
-});
-```
-
-## Finding Direct I/O in Workflows
-
-Search for common I/O patterns in workflow files:
-
-```bash
-# Find fetch calls
-grep -rn "await fetch" src/workflows/
-
-# Find axios calls
-grep -rn "axios\." src/workflows/
-
-# Find database operations
-grep -rn "prisma\.\|db\.\|mongoose\." src/workflows/
-
-# Find file system operations
-grep -rn "fs\.\|readFile\|writeFile" src/workflows/
-```
-
-Then review each match to see if it's in a workflow function vs a step function.
-
-## What CAN Be in Workflow Functions
-
-Workflow functions should contain:
-- **Step calls**: `await myStep(input)`
-- **Orchestration logic**: conditionals, loops (over step calls)
-- **Data transformation**: Pure functions on step results
-- **Constants**: Static values and configuration
-
-Workflow functions should NOT contain:
-- HTTP/API calls
-- Database operations
-- File system operations
-- External service calls
-- Anything that talks to the network or filesystem
-
-## Verification
-
-After moving I/O to steps:
-
-1. **Run the workflow**: `npx output workflow run <name> '<input>'`
-2. **Check the trace**: `npx output workflow debug <id> --format json`
-3. **Verify steps appear**: Look for your I/O steps in the trace
-4. **Confirm no errors**: No determinism warnings or hangs
-
-## Benefits of Steps for I/O
-
-1. **Retry logic**: Steps can be retried on failure
-2. **Tracing**: I/O operations appear in workflow traces
-3. **Timeouts**: Steps can have individual timeouts
-4. **Determinism**: Replays use recorded results
-5. **Debugging**: Clear visibility into what happened
-
-## Related Issues
-
-- For HTTP client best practices, see `output-error-http-client`
-- For non-determinism from other causes, see `output-error-nondeterminism`

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

@@ -1,298 +0,0 @@
----
-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**: `npx output workflow run <name> '<input>'`
-2. **Check the trace**: `npx 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`