@output.ai/cli 0.4.2 → 0.5.1

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

@@ -0,0 +1,128 @@
+---
+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

@@ -0,0 +1,117 @@
+---
+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 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

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

@@ -0,0 +1,199 @@
+---
+name: output-workflow-result
+description: Get the result of an Output SDK workflow execution. Use when retrieving the output of a completed workflow, getting the return value, or checking what a workflow produced after async execution.
+allowed-tools: [Bash]
+---
+
+# Get Workflow Execution Result
+
+## Overview
+
+This skill retrieves the result (return value) of a completed workflow execution. Use it after a workflow started with `npx output workflow start` has completed, or to retrieve results from historical runs.
+
+## When to Use This Skill
+
+- Getting output from an asynchronously started workflow
+- Retrieving results from a completed workflow
+- Checking what a workflow produced
+- Processing workflow output in scripts
+- Comparing results between runs
+
+## Prerequisites
+
+- The workflow must have completed (status: COMPLETED)
+- You need the workflow ID
+- For FAILED workflows, use `npx output workflow debug` instead
+
+## Instructions
+
+### Get Result
+
+```bash
+npx output workflow result <workflowId>
+```
+
+The result is the return value of the workflow function, typically JSON.
+
+### Check Status First
+
+Before getting results, verify the workflow completed:
+
+```bash
+npx output workflow status <workflowId>
+# Should show: COMPLETED
+
+npx output workflow result <workflowId>
+```
+
+## Understanding Results
+
+### Success Results
+
+A successful workflow returns the value from its `fn` function:
+
+```typescript
+// Workflow code
+export default workflow({
+  fn: async (input) => {
+    return { processed: true, count: 42 };
+  }
+});
+```
+
+```bash
+# Result output
+npx output workflow result abc123
+# { "processed": true, "count": 42 }
+```
+
+### Error Results
+
+If you try to get the result of a failed workflow:
+- You'll get an error message
+- Use `npx output workflow debug` instead to see what went wrong
+
+### No Result (void workflows)
+
+Some workflows don't return a value:
+```bash
+npx output workflow result abc123
+# null
+```
+
+## Examples
+
+**Scenario**: Get result after async start
+
+```bash
+# Start workflow
+npx output workflow start calculate '{"values": [1, 2, 3]}'
+# Output: Workflow ID: calc-abc123
+
+# Wait for completion
+npx output workflow status calc-abc123
+# Status: COMPLETED
+
+# Get the result
+npx output workflow result calc-abc123
+# { "sum": 6, "average": 2 }
+```
+
+**Scenario**: Process result with jq
+
+```bash
+# Extract specific field
+npx output workflow result abc123 | jq '.total'
+
+# Format for display
+npx output workflow result abc123 | jq '.'
+
+# Save to file
+npx output workflow result abc123 > result.json
+```
+
+**Scenario**: Compare results between runs
+
+```bash
+# Get results from two runs
+npx output workflow result run-1-abc > result1.json
+npx output workflow result run-2-xyz > result2.json
+
+# Compare
+diff result1.json result2.json
+```
+
+**Scenario**: Use in a script
+
+```bash
+WORKFLOW_ID="abc123"
+
+# Wait for completion
+while [[ $(npx output workflow status $WORKFLOW_ID) == *"RUNNING"* ]]; do
+  sleep 5
+done
+
+# Check if completed successfully
+if [[ $(npx output workflow status $WORKFLOW_ID) == *"COMPLETED"* ]]; then
+  RESULT=$(npx output workflow result $WORKFLOW_ID)
+  echo "Workflow result: $RESULT"
+else
+  echo "Workflow did not complete successfully"
+  npx output workflow debug $WORKFLOW_ID
+fi
+```
+
+## Handling Different Result Types
+
+### JSON Objects
+```bash
+npx output workflow result abc123
+# { "key": "value", "nested": { "data": true } }
+```
+
+### Arrays
+```bash
+npx output workflow result abc123
+# [1, 2, 3, 4, 5]
+```
+
+### Primitive Values
+```bash
+npx output workflow result abc123
+# 42
+
+npx output workflow result abc123
+# "success"
+
+npx output workflow result abc123
+# true
+```
+
+### Large Results
+
+For large results, redirect to a file:
+```bash
+npx output workflow result abc123 > large-result.json
+```
+
+## Error Handling
+
+### "Workflow not found"
+- Check the workflow ID is correct
+- Use `npx output workflow runs list` to find valid IDs
+
+### "Workflow not completed"
+- Check status: `npx output workflow status <id>`
+- Wait for COMPLETED status before getting result
+- If RUNNING, wait and try again
+- If FAILED, use `npx output workflow debug`
+
+### "No result available"
+- The workflow may return void/undefined
+- Check the workflow code to see what it returns
+
+## Related Commands
+
+- `npx output workflow status <id>` - Check if workflow completed
+- `npx output workflow debug <id>` - Debug failed workflows
+- `npx output workflow run <name>` - Run and get result in one step
+- `npx output workflow runs list` - Find workflow IDs

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

@@ -0,0 +1,228 @@
+---
+name: output-workflow-run
+description: Execute an Output SDK workflow synchronously and wait for the result. Use when running a workflow and needing immediate results, testing workflow execution, or getting the output directly in the terminal.
+allowed-tools: [Bash, Read, Write]
+---
+
+# Run Workflow Synchronously
+
+## Overview
+
+This skill executes a workflow synchronously, meaning the command waits for the workflow to complete and returns the result directly. This is ideal for testing, quick executions, and when you need immediate feedback.
+
+## When to Use This Skill
+
+- Testing a workflow during development
+- Running a workflow and needing the result immediately
+- Quick one-off workflow executions
+- Debugging by re-running a workflow with different inputs
+- When you don't need to monitor the workflow separately
+
+## When to Use Async Instead
+
+Consider using `npx output workflow start` (async) when:
+- The workflow takes a long time (minutes to hours)
+- You need to run multiple workflows in parallel
+- You want to disconnect and check results later
+- You need to monitor progress separately
+
+## Instructions
+
+### Basic Syntax
+
+```bash
+npx output workflow run <workflowName> --input '<json-input>'
+npx output workflow run <workflowName> --input <path-to-json-file>
+```
+
+The `--input` flag is required when the workflow expects input data.
+
+### Input Methods
+
+#### 1. Inline JSON
+
+Pass JSON directly on the command line:
+
+```bash
+npx output workflow run example --input '{"question": "who really is ada lovelace?"}'
+```
+
+#### 2. File Path (Recommended)
+
+Reference a JSON file containing the input:
+
+```bash
+npx output workflow run simple --input src/simple/scenarios/question_ada_lovelace.json
+```
+
+This is the recommended approach because:
+- Input is version controlled and reproducible
+- Complex inputs are easier to read and edit
+- Scenarios can be shared and reused
+
+### Scenario Folder Pattern (Best Practice)
+
+Workflows typically have a `scenarios/` folder containing test inputs:
+
+```
+src/
+  my_workflow/
+    workflow.ts
+    steps.ts
+    scenarios/
+      basic_test.json
+      edge_case_empty.json
+      large_payload.json
+```
+
+**Best practice workflow:**
+
+1. Create a scenario file with your input:
+   ```bash
+   # Create scenarios folder if it doesn't exist
+   mkdir -p src/my_workflow/scenarios
+   ```
+
+2. Write your input to a scenario file:
+   ```json
+   // src/my_workflow/scenarios/test_user.json
+   {
+     "userId": "123",
+     "options": {
+       "verbose": true
+     }
+   }
+   ```
+
+3. Run the workflow referencing the scenario:
+   ```bash
+   npx output workflow run my_workflow --input src/my_workflow/scenarios/test_user.json
+   ```
+
+### Input Examples
+
+```bash
+# Inline JSON - simple object
+npx output workflow run my-workflow --input '{"userId": "123"}'
+
+# Inline JSON - complex nested input
+npx output workflow run data-pipeline --input '{"source": "api", "options": {"limit": 100}}'
+
+# File path - reference a scenario file
+npx output workflow run simple --input src/simple/scenarios/basic.json
+
+# File path - relative to current directory
+npx output workflow run batch-processor --input ./test_inputs/batch1.json
+
+# No input (only if workflow doesn't require it)
+npx output workflow run health-check
+```
+
+## Understanding the Output
+
+The command returns the workflow result directly to stdout.
+
+### Success Output
+The workflow's return value is displayed, typically as JSON.
+
+### Error Output
+If the workflow fails, you'll see:
+- Error message
+- The workflow ID (for further debugging)
+- Suggestion to use `npx output workflow debug` for details
+
+## Examples
+
+**Scenario**: Test a workflow with a scenario file
+
+```bash
+# First, look for existing scenarios
+ls src/simple/scenarios/
+
+# Run using a scenario file
+npx output workflow run simple --input src/simple/scenarios/basic_sum.json
+
+# Output:
+# { "sum": 6, "count": 3 }
+```
+
+**Scenario**: Create and run a new test scenario
+
+```bash
+# Create a scenario file
+cat > src/my_workflow/scenarios/test_case_1.json << 'EOF'
+{
+  "question": "What is the capital of France?",
+  "context": "geography"
+}
+EOF
+
+# Run the workflow
+npx output workflow run my_workflow --input src/my_workflow/scenarios/test_case_1.json
+```
+
+**Scenario**: Quick inline test during development
+
+```bash
+npx output workflow run example --input '{"question": "explain quantum computing"}'
+```
+
+**Scenario**: Re-run a workflow with different input for debugging
+
+```bash
+# First attempt with scenario file
+npx output workflow run process-data --input src/process_data/scenarios/user_abc.json
+# Error occurs
+
+# Create a new scenario to isolate the issue
+cat > src/process_data/scenarios/debug_minimal.json << 'EOF'
+{"id": "test", "debug": true}
+EOF
+
+npx output workflow run process-data --input src/process_data/scenarios/debug_minimal.json
+```
+
+**Scenario**: Capture output for further processing
+
+```bash
+# Save result to a file
+npx output workflow run generate-report --input src/generate_report/scenarios/jan_2024.json > report.json
+
+# Pipe to jq for processing
+npx output workflow run get-users --input src/get_users/scenarios/active.json | jq '.users[].name'
+```
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "Workflow not found" | Workflow name is incorrect | Check with `npx output workflow list` |
+| "Invalid input" | JSON doesn't match schema | Verify input matches workflow's inputSchema |
+| "Parse error" | Malformed JSON or file not found | Check JSON syntax or file path |
+| "Timeout" | Workflow took too long | Use async execution for long workflows |
+
+### Getting More Details on Failures
+
+When a workflow fails, the output includes the workflow ID. Use it to get the full trace:
+
+```bash
+npx output workflow run my-workflow --input src/my_workflow/scenarios/test.json
+# Output: Workflow failed. ID: abc123xyz
+
+npx output workflow debug abc123xyz --format json
+```
+
+## Input Schema Tips
+
+1. **Check the schema first**: Look at the workflow's `inputSchema` in the code
+2. **Use scenario files**: Create reusable test inputs in the workflow's `scenarios/` folder
+3. **Use proper types**: Strings in quotes, numbers without quotes, booleans as true/false
+4. **Include required fields**: All non-optional schema fields must be provided
+
+## Related Commands
+
+- `npx output workflow start <name> --input` - Start asynchronously
+- `npx output workflow list` - See available workflows
+- `npx output workflow debug <id>` - Debug a failed run