@output.ai/cli 0.5.6 → 0.7.0

package/dist/templates/agent_instructions/skills/output-error-try-catch/SKILL.md.template

@@ -1,226 +0,0 @@
----
-name: output-error-try-catch
-description: Fix try-catch anti-pattern in Output SDK workflows. Use when retries aren't working, errors are being swallowed, seeing unexpected FatalError wrapping, or when step failures don't trigger retry policies.
-allowed-tools: [Bash, Read]
----
-
-# Fix Try-Catch Anti-Pattern
-
-## Overview
-
-This skill helps diagnose and fix a common anti-pattern where step calls are wrapped in try-catch blocks. This prevents Output SDK's retry mechanism from working properly and can lead to confusing error behavior.
-
-## When to Use This Skill
-
-You're seeing:
-- Retries not working as expected
-- Errors being swallowed silently
-- Unexpected FatalError wrapping
-- Step failures not triggering retry policies
-- Errors being caught and re-thrown incorrectly
-
-## Root Cause
-
-When you wrap step calls in try-catch blocks, you intercept errors before the Output SDK retry mechanism can handle them. This defeats the built-in retry logic and can cause:
-
-1. **Retries not happening**: The error is caught, so the framework doesn't know to retry
-2. **Wrong error classification**: Re-throwing as FatalError prevents retries entirely
-3. **Lost error context**: Original error details may be lost in the catch block
-
-## Symptoms
-
-### Pattern 1: Errors Swallowed
-
-```typescript
-// WRONG: Error is silently ignored
-try {
-  const result = await myStep(input);
-} catch (error) {
-  console.log('Step failed');  // Swallowed!
-  return { success: false };
-}
-```
-
-### Pattern 2: FatalError Wrapping
-
-```typescript
-// WRONG: Turns retryable errors into fatal errors
-try {
-  const result = await myStep(input);
-} catch (error) {
-  throw new FatalError(error.message);  // Prevents retries!
-}
-```
-
-### Pattern 3: Re-throwing Generic Errors
-
-```typescript
-// WRONG: Loses error context and may affect retry behavior
-try {
-  const result = await myStep(input);
-} catch (error) {
-  throw new Error(`Step failed: ${error.message}`);
-}
-```
-
-## Solution
-
-**Let failures propagate naturally.** Remove try-catch blocks around step calls and let the Output SDK handle errors:
-
-### Before (Wrong)
-
-```typescript
-export default workflow({
-  fn: async (input) => {
-    try {
-      const data = await fetchDataStep(input);
-      const result = await processDataStep(data);
-      return result;
-    } catch (error) {
-      throw new FatalError(error.message);
-    }
-  }
-});
-```
-
-### After (Correct)
-
-```typescript
-export default workflow({
-  fn: async (input) => {
-    const data = await fetchDataStep(input);
-    const result = await processDataStep(data);
-    return result;
-  }
-});
-```
-
-## When Try-Catch IS Appropriate
-
-There are limited cases where catching errors in workflows is valid:
-
-### 1. Optional/Fallback Steps
-
-When a step failure should trigger an alternative path:
-
-```typescript
-export default workflow({
-  fn: async (input) => {
-    let data;
-    try {
-      data = await fetchFromPrimarySource(input);
-    } catch {
-      // Fallback to secondary source
-      data = await fetchFromSecondarySource(input);
-    }
-    return await processData(data);
-  }
-});
-```
-
-### 2. Aggregate Results with Partial Failures
-
-When processing multiple items where some may fail:
-
-```typescript
-export default workflow({
-  fn: async (input) => {
-    const results = [];
-    for (const item of input.items) {
-      try {
-        const result = await processItem(item);
-        results.push({ item, result, success: true });
-      } catch (error) {
-        results.push({ item, error: error.message, success: false });
-      }
-    }
-    return results;  // Contains both successes and failures
-  }
-});
-```
-
-**Note**: Even in these cases, be careful not to swallow errors that should cause the whole workflow to fail.
-
-## Finding Try-Catch Around Steps
-
-Search for the pattern:
-
-```bash
-# Find try blocks in workflow files
-grep -rn "try {" src/workflows/
-
-# Look for FatalError usage
-grep -rn "FatalError" src/workflows/
-```
-
-Then review each match to see if it's wrapping step calls.
-
-## How Retries Work
-
-When you DON'T catch errors:
-
-1. Step throws an error
-2. Output SDK receives the error
-3. SDK checks retry policy (configured per step)
-4. If retries remain, step is re-executed
-5. If retries exhausted, workflow fails with full error context
-
-When you DO catch errors:
-
-1. Step throws an error
-2. Your catch block handles it
-3. Output SDK never sees the original error
-4. Retry logic is bypassed
-5. You control what happens (often incorrectly)
-
-## Configuring Retry Behavior
-
-Instead of try-catch, configure retry policies on steps:
-
-```typescript
-export const fetchData = step({
-  name: 'fetchData',
-  retry: {
-    maxAttempts: 3,
-    initialInterval: '1s',
-    maxInterval: '30s',
-    backoffCoefficient: 2
-  },
-  fn: async (input) => {
-    // If this fails, it will be retried according to policy
-    return await callApi(input);
-  }
-});
-```
-
-## Using FatalError Correctly
-
-FatalError is for errors that should NEVER be retried:
-
-```typescript
-export const validateInput = step({
-  name: 'validateInput',
-  fn: async (input) => {
-    if (!input.userId) {
-      // This will never succeed on retry
-      throw new FatalError('userId is required');
-    }
-    return input;
-  }
-});
-```
-
-Do NOT use FatalError to wrap other errors unless you're certain they shouldn't retry.
-
-## Verification
-
-After removing try-catch:
-
-1. **Test normal operation**: `npx output workflow run <name> '<valid-input>'`
-2. **Test failure scenarios**: Use input that causes step failures
-3. **Check retry behavior**: Look for retry attempts in `npx output workflow debug <id>`
-
-## Related Issues
-
-- For configuring retry policies, see step definition documentation
-- For handling expected failures gracefully, consider using conditional logic instead of try-catch

package/dist/templates/agent_instructions/skills/output-error-zod-import/SKILL.md.template

@@ -1,209 +0,0 @@
----
-name: output-error-zod-import
-description: Fix Zod schema import issues in Output SDK workflows. Use when seeing "incompatible schema" errors, type errors at step boundaries, schema validation failures, or when schemas don't match between steps.
-allowed-tools: [Bash, Read]
----
-
-# Fix Zod Import Source Issues
-
-## Overview
-
-This skill helps diagnose and fix a common issue where Zod schemas are imported from the wrong source. Output SDK requires schemas to be imported from `@output.ai/core`, not directly from `zod`.
-
-## When to Use This Skill
-
-You're seeing:
-- "incompatible schema" errors
-- Type errors at step boundaries
-- Schema validation failures when passing data between steps
-- Errors mentioning Zod types not matching
-- "Expected ZodObject but received..." errors
-
-## Root Cause
-
-The issue occurs when you import `z` from `zod` instead of `@output.ai/core`. While both provide Zod schemas, they create different schema instances that aren't compatible with each other within the Output SDK context.
-
-**Why this matters**: Output SDK uses a specific version of Zod internally for serialization and validation. When you use a different Zod instance, the schemas are technically different objects even if they define the same shape.
-
-## Symptoms
-
-### Error Messages
-
-```
-Error: Incompatible schema types
-Error: Schema validation failed: expected compatible Zod instance
-TypeError: Cannot read property 'parse' of undefined
-```
-
-### Code Patterns That Cause This
-
-```typescript
-// WRONG: Importing from 'zod' directly
-import { z } from 'zod';
-
-const inputSchema = z.object({
-  name: z.string(),
-});
-```
-
-## Solution
-
-### Step 1: Find All Zod Imports
-
-Search your codebase for incorrect imports:
-
-```bash
-grep -r "from 'zod'" src/
-grep -r 'from "zod"' src/
-```
-
-### Step 2: Update Imports
-
-Change all imports from:
-
-```typescript
-// Wrong
-import { z } from 'zod';
-```
-
-To:
-
-```typescript
-// Correct
-import { z } from '@output.ai/core';
-```
-
-### Step 3: Verify No Direct Zod Dependencies
-
-Check your imports don't accidentally use zod elsewhere:
-
-```bash
-grep -r "import.*zod" src/
-```
-
-All matches should show `@output.ai/core`, not `zod`.
-
-## Complete Example
-
-### Before (Wrong)
-
-```typescript
-// src/workflows/my-workflow/steps/process.ts
-import { z } from 'zod';  // Wrong!
-import { step } from '@output.ai/core';
-
-export const processStep = step({
-  name: 'processData',
-  inputSchema: z.object({
-    id: z.string(),
-  }),
-  outputSchema: z.object({
-    result: z.string(),
-  }),
-  fn: async (input) => {
-    return { result: `Processed ${input.id}` };
-  },
-});
-```
-
-### After (Correct)
-
-```typescript
-// src/workflows/my-workflow/steps/process.ts
-import { z, step } from '@output.ai/core';  // Correct!
-
-export const processStep = step({
-  name: 'processData',
-  inputSchema: z.object({
-    id: z.string(),
-  }),
-  outputSchema: z.object({
-    result: z.string(),
-  }),
-  fn: async (input) => {
-    return { result: `Processed ${input.id}` };
-  },
-});
-```
-
-## Verification Steps
-
-### 1. Check for remaining wrong imports
-
-```bash
-# Should return no results
-grep -r "from 'zod'" src/
-grep -r 'from "zod"' src/
-```
-
-### 2. Build the project
-
-```bash
-npm run output:workflow:build
-```
-
-### 3. Run the workflow
-
-```bash
-npx output workflow run <workflowName> '<input>'
-```
-
-## Prevention
-
-### ESLint Rule (if using ESLint)
-
-Add a rule to prevent direct zod imports:
-
-```javascript
-// .eslintrc.js
-module.exports = {
-  rules: {
-    'no-restricted-imports': ['error', {
-      paths: [{
-        name: 'zod',
-        message: "Import { z } from '@output.ai/core' instead of 'zod'"
-      }]
-    }]
-  }
-};
-```
-
-### IDE Settings
-
-Configure your editor to auto-import from `@output.ai/core`:
-
-For VS Code, add to settings.json:
-```json
-{
-  "typescript.preferences.autoImportFileExcludePatterns": ["zod"]
-}
-```
-
-## Common Gotchas
-
-### Mixed Imports in Same File
-Even one wrong import can cause issues:
-```typescript
-import { z } from '@output.ai/core';
-import { z as zod } from 'zod';  // This causes problems!
-```
-
-### Indirect Dependencies
-If a utility file uses the wrong import and is shared:
-```typescript
-// utils/schemas.ts
-import { z } from 'zod';  // Wrong! This affects all files using these schemas
-export const idSchema = z.string().uuid();
-```
-
-### Third-Party Libraries
-If using external Zod schemas, you may need to recreate them:
-```typescript
-// Don't use: externalLibrary.schema
-// Instead: recreate the schema with @output.ai/core's z
-```
-
-## Related Issues
-
-- If schemas are correct but you still see type errors, check `output-error-missing-schemas`
-- For validation failures with correct imports, verify schema definitions match actual data

package/dist/templates/agent_instructions/skills/output-services-check/SKILL.md.template

@@ -1,128 +0,0 @@
----
-name: output-services-check
-description: Verify Output SDK development services are running. Use when debugging workflows, starting development, encountering connection errors, services may be down, or when you see "ECONNREFUSED" or timeout errors.
-allowed-tools: [Bash, Read]
----
-
-# Output Services Health Check
-
-## Overview
-
-This skill verifies that all required Output SDK development services are running and healthy. The Output SDK requires three services for local development: Docker containers, the API server, and the Temporal server with its UI.
-
-## When to Use This Skill
-
-- Starting a debugging session
-- Encountering connection refused errors (ECONNREFUSED)
-- Workflows failing to start or connect
-- Timeout errors when running workflows
-- Before running any workflow commands
-- When the development environment seems unresponsive
-
-## Instructions
-
-### Step 1: Check Docker Containers
-
-```bash
-docker ps | grep output
-```
-
-**Expected**: You should see containers related to `output` running. If no containers appear, Docker may not be running or the services haven't been started.
-
-### Step 2: Check API Server Health
-
-```bash
-curl -s http://localhost:3001/health
-```
-
-**Expected**: Returns a health status response. If this fails with "Connection refused", the API server is not running.
-
-### Step 3: Check Temporal UI Accessibility
-
-```bash
-curl -s http://localhost:8080 > /dev/null && echo "Temporal UI accessible" || echo "Temporal UI not accessible"
-```
-
-**Expected**: "Temporal UI accessible". If not accessible, Temporal server may not be running.
-
-## Remediation Steps
-
-### If Docker is not running:
-1. Start Docker Desktop (macOS/Windows) or the Docker daemon (Linux)
-2. Wait for Docker to fully initialize
-3. Re-run the checks
-
-### If services are not running:
-```bash
-# Start all development services
-npx output dev
-```
-
-Wait 30-60 seconds for all services to initialize, then re-run the checks.
-
-### If only some services are down:
-```bash
-# Restart all services using Docker Compose
-docker compose down
-docker compose up -d
-```
-
-### If services fail to start:
-1. Check for port conflicts: `lsof -i :3001` and `lsof -i :8080`
-2. Check Docker logs: `docker compose logs`
-3. Ensure you have sufficient system resources (memory, disk space)
-
-## Decision Tree
-
-```
-IF docker_not_running:
-  ACTION: Start Docker Desktop/daemon
-  WAIT: for Docker to initialize
-
-IF no_output_containers:
-  RUN: npx output dev
-  WAIT: 30-60 seconds for services
-
-IF api_not_responding:
-  CHECK: port 3001 for conflicts
-  RUN: output dev (if not already running)
-
-IF temporal_not_accessible:
-  CHECK: port 8080 for conflicts
-  CHECK: docker compose logs for Temporal errors
-
-IF all_services_healthy:
-  PROCEED: with workflow debugging
-```
-
-## Examples
-
-**Scenario**: User reports "connection refused" when running a workflow
-
-```bash
-# First, check if services are running
-docker ps | grep output
-# Output: (empty - no containers)
-
-# Start services
-npx output dev
-
-# Wait and verify
-sleep 60
-curl -s http://localhost:3001/health
-# Output: {"status":"healthy"}
-```
-
-**Scenario**: Partial service failure
-
-```bash
-# API responds but Temporal doesn't
-curl -s http://localhost:3001/health  # Works
-curl -s http://localhost:8080  # Fails
-
-# Check Temporal logs
-docker compose logs temporal
-
-# Restart just Temporal
-docker compose restart temporal
-```

package/dist/templates/agent_instructions/skills/output-workflow-list/SKILL.md.template

@@ -1,117 +0,0 @@
----
-name: output-workflow-list
-description: List all available Output SDK workflows in the project. Use when discovering what workflows exist, checking workflow names, exploring the project's workflow structure, or when unsure which workflows are available to run.
-allowed-tools: [Bash]
----
-
-# List Available Workflows
-
-## Overview
-
-This skill helps you discover all available workflows in an Output SDK project. Workflows are the main execution units that orchestrate steps to accomplish tasks.
-
-## When to Use This Skill
-
-- Discovering what workflows exist in a project
-- Verifying a workflow name before running it
-- Exploring a new or unfamiliar codebase
-- Checking if a specific workflow has been created
-- Getting an overview of project capabilities
-
-## Instructions
-
-### List All Workflows
-
-```bash
-npx output workflow list
-```
-
-This command scans the project and displays all available workflows.
-
-### Understanding the Output
-
-The command outputs a table with workflow information:
-
-| Column | Description |
-|--------|-------------|
-| Name | The workflow identifier used in commands |
-| Description | Brief description of what the workflow does |
-| Location | File path where the workflow is defined |
-
-### Finding Workflow Files
-
-Workflows are typically located in:
-```
-src/workflows/*/
-```
-
-Each workflow directory usually contains:
-- `workflow.ts` or `index.ts` - The main workflow definition
-- Step files - Individual steps used by the workflow
-- Schema files - Input/output type definitions
-
-### Inspecting a Workflow
-
-After finding a workflow, you can examine its code:
-
-```bash
-# Read the workflow file
-cat src/workflows/<workflowName>/workflow.ts
-
-# Or examine the entire workflow directory
-ls -la src/workflows/<workflowName>/
-```
-
-## Examples
-
-**Scenario**: Discover available workflows in a project
-
-```bash
-npx output workflow list
-
-# Example output:
-# Name          Description                    Location
-# -----------   ---------------------------    --------------------------------
-# simple        Simple workflow example        src/workflows/simple/workflow.ts
-# data-pipeline Process and transform data     src/workflows/data-pipeline/workflow.ts
-# user-signup   Handle user registration       src/workflows/user-signup/workflow.ts
-```
-
-**Scenario**: Verify a workflow exists before running
-
-```bash
-# Check if "email-sender" workflow exists
-npx output workflow list | grep email-sender
-
-# If no output, the workflow doesn't exist
-# If found, proceed with running it
-npx output workflow run email-sender '{"to": "user@example.com"}'
-```
-
-**Scenario**: Explore workflow implementation
-
-```bash
-# List workflows
-npx output workflow list
-
-# Find the location and examine it
-cat src/workflows/simple/workflow.ts
-```
-
-## Troubleshooting
-
-### No workflows found
-- Ensure you're in the project root directory
-- Check that workflows are in `src/workflows/*/`
-- Verify workflow files export a default workflow
-
-### Workflow not showing
-- Check the file exports a valid workflow definition
-- Ensure the workflow file compiles without errors
-- Run `npm run output:workflow:build` to check for TypeScript errors
-
-## Related Commands
-
-- `npx output workflow run <name>` - Execute a workflow synchronously
-- `npx output workflow start <name>` - Start a workflow asynchronously
-- `npx output workflow runs list` - View execution history