@output.ai/cli 0.5.6 → 0.7.0

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

@@ -1,265 +0,0 @@
----
-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 output:workflow:build` should pass without type errors
-2. **Runtime test**: `npx 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

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

@@ -1,252 +0,0 @@
----
-name: output-error-nondeterminism
-description: Fix non-determinism errors in Output SDK workflows. Use when seeing replay failures, inconsistent results between runs, "non-deterministic" error messages, or workflows behaving differently on retry.
-allowed-tools: [Bash, Read]
----
-
-# Fix Non-Determinism Errors
-
-## Overview
-
-This skill helps diagnose and fix non-determinism errors in Output SDK workflows. Workflows must be deterministic because Temporal may replay them during recovery or retries, and the replay must produce identical results.
-
-## When to Use This Skill
-
-You're seeing:
-- "non-deterministic" error messages
-- Replay failures after workflow restart
-- Inconsistent results between runs with same input
-- Errors during workflow recovery
-- Warnings about determinism violations
-
-## Root Cause
-
-Temporal workflows must be deterministic: given the same input, they must always execute the same sequence of operations. This is because Temporal replays workflow history to recover state after crashes or restarts.
-
-Non-deterministic operations break this replay mechanism because they produce different values each time.
-
-## Common Causes and Solutions
-
-### 1. Math.random()
-
-**Problem**: Random values differ on each execution.
-
-```typescript
-// WRONG: Non-deterministic
-export default workflow({
-  fn: async (input) => {
-    const id = Math.random().toString(36);  // Different each time!
-    return await processWithId({ id });
-  }
-});
-```
-
-**Solution**: Pass random values as workflow input or generate in a step.
-
-```typescript
-// Option 1: Pass as input
-export default workflow({
-  inputSchema: z.object({
-    id: z.string()  // Generate ID before calling workflow
-  }),
-  fn: async (input) => {
-    return await processWithId({ id: input.id });
-  }
-});
-
-// Option 2: Generate in a step (steps can be non-deterministic)
-export const generateId = step({
-  name: 'generateId',
-  fn: async () => ({ id: Math.random().toString(36) })
-});
-
-export default workflow({
-  fn: async (input) => {
-    const { id } = await generateId({});
-    return await processWithId({ id });
-  }
-});
-```
-
-### 2. Date.now() / new Date()
-
-**Problem**: Timestamps change between executions.
-
-```typescript
-// WRONG: Non-deterministic
-export default workflow({
-  fn: async (input) => {
-    const timestamp = Date.now();  // Different each replay!
-    return await logEvent({ timestamp });
-  }
-});
-```
-
-**Solution**: Pass timestamps as input or use Temporal's time API.
-
-```typescript
-// Option 1: Pass as input
-export default workflow({
-  inputSchema: z.object({
-    timestamp: z.number()
-  }),
-  fn: async (input) => {
-    return await logEvent({ timestamp: input.timestamp });
-  }
-});
-
-// Option 2: Generate in a step
-export const getTimestamp = step({
-  name: 'getTimestamp',
-  fn: async () => ({ timestamp: Date.now() })
-});
-```
-
-### 3. crypto.randomUUID()
-
-**Problem**: UUIDs differ each execution.
-
-```typescript
-// WRONG: Non-deterministic
-import { randomUUID } from 'crypto';
-
-export default workflow({
-  fn: async (input) => {
-    const requestId = randomUUID();  // Different each time!
-    return await makeRequest({ requestId });
-  }
-});
-```
-
-**Solution**: Generate UUIDs as input or in steps.
-
-```typescript
-// Correct: Generate in step
-export const generateRequestId = step({
-  name: 'generateRequestId',
-  fn: async () => {
-    const { randomUUID } = await import('crypto');
-    return { requestId: randomUUID() };
-  }
-});
-```
-
-### 4. Dynamic Imports
-
-**Problem**: Dynamic imports may resolve differently.
-
-```typescript
-// WRONG: Non-deterministic import timing
-export default workflow({
-  fn: async (input) => {
-    const module = await import(`./handlers/${input.type}`);
-    return module.handle(input);
-  }
-});
-```
-
-**Solution**: Use static imports and conditional logic.
-
-```typescript
-// Correct: Static imports with conditional use
-import { handleTypeA } from './handlers/typeA';
-import { handleTypeB } from './handlers/typeB';
-
-export default workflow({
-  fn: async (input) => {
-    if (input.type === 'A') {
-      return await handleTypeA(input);
-    } else {
-      return await handleTypeB(input);
-    }
-  }
-});
-```
-
-### 5. Environment Variables
-
-**Problem**: Environment may differ between replays.
-
-```typescript
-// WRONG: Environment can change
-export default workflow({
-  fn: async (input) => {
-    const apiUrl = process.env.API_URL;  // May differ on different workers
-    return await callApi({ url: apiUrl });
-  }
-});
-```
-
-**Solution**: Pass configuration as input or use constants.
-
-```typescript
-// Correct: Pass as input
-export default workflow({
-  inputSchema: z.object({
-    apiUrl: z.string()
-  }),
-  fn: async (input) => {
-    return await callApi({ url: input.apiUrl });
-  }
-});
-```
-
-## How to Find Non-Deterministic Code
-
-### Search for Common Patterns
-
-```bash
-# Find Math.random usage
-grep -rn "Math.random" src/workflows/
-
-# Find Date.now or new Date
-grep -rn "Date.now\|new Date" src/workflows/
-
-# Find crypto random functions
-grep -rn "randomUUID\|randomBytes" src/workflows/
-
-# Find dynamic imports
-grep -rn "import(" src/workflows/
-```
-
-### Review Workflow Files
-
-Look at your workflow `fn` functions specifically. Non-deterministic code is only a problem **in workflow functions**, not in step functions.
-
-## Verification Steps
-
-1. **Fix the code** using solutions above
-2. **Run the workflow**: `npx output workflow run <name> '<input>'`
-3. **Run again with same input**: Result should be identical
-4. **Check for errors**: No "non-deterministic" messages
-
-## The Determinism Rule
-
-**Workflow functions must be deterministic:**
-- Same input = same execution path
-- No side effects (network, filesystem, random values)
-- Only orchestration logic and step calls
-
-**Step functions can be non-deterministic:**
-- Steps record their results in Temporal history
-- Replays use recorded results, not re-execution
-- All I/O should happen in steps
-
-## Debugging Tip
-
-If unsure whether code is causing issues:
-
-```bash
-# Run the workflow
-npx output workflow start my-workflow '{"input": "test"}'
-
-# Get the workflow ID and run debug to see replay behavior
-npx output workflow debug <workflowId> --format json
-```
-
-Look for errors or warnings about non-determinism in the trace.
-
-## Related Issues
-
-- For I/O in workflow code, see `output-error-direct-io`
-- For random values needed in logic, generate them in steps or pass as input