@output.ai/cli 0.4.1 → 0.5.0

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

@@ -0,0 +1,134 @@
+---
+name: output-workflow-trace
+description: Analyze Output SDK workflow execution traces. Use when debugging a specific workflow, examining step failures, analyzing input/output data, understanding execution flow, or when you have a workflow ID to investigate.
+allowed-tools: [Bash, Read]
+---
+
+# Workflow Trace Analysis
+
+## Overview
+
+This skill provides guidance on retrieving and analyzing workflow execution traces using the Output CLI. Traces show the complete execution history including step inputs, outputs, errors, and timing information.
+
+## When to Use This Skill
+
+- You have a workflow ID and need to understand what happened
+- A workflow failed and you need to identify which step failed
+- You need to examine the input/output data at each step
+- You want to understand the execution flow and timing
+- You need to find error messages and stack traces
+- Debugging retry behavior or unexpected results
+
+## Instructions
+
+### Step 1: Retrieve the Execution Trace
+
+**Basic trace (text format, may be truncated):**
+```bash
+output workflow debug <workflowId>
+```
+
+**Full trace (JSON format, recommended for detailed analysis):**
+```bash
+output workflow debug <workflowId> --format json
+```
+
+**Tip**: Always use `--format json` when you need complete trace data. The text format truncates long values which can hide important debugging information.
+
+### Step 2: Analyze the Trace
+
+Follow this checklist when examining a trace:
+
+1. **Identify the failed step**: Look for steps with error status or failure indicators
+2. **Examine error messages**: Find the exact error message and stack trace
+3. **Check step inputs**: Verify the data passed to the failing step was correct
+4. **Check step outputs**: Look at outputs from preceding steps
+5. **Review retry attempts**: Note how many retries occurred and their outcomes
+6. **Check timing**: Look for unusual delays that might indicate timeouts
+
+### Step 3: Use the Temporal UI for Visual Analysis
+
+Open **http://localhost:8080** in your browser for a visual workflow inspection:
+
+1. Search for your workflow by ID
+2. View the event history timeline
+3. Click on individual events to see details
+4. Inspect step inputs and outputs
+5. See retry attempts and timing information
+6. Export trace data if needed
+
+## What to Look For in Traces
+
+### Error Patterns
+
+| Error Message | Likely Cause |
+|---------------|--------------|
+| "incompatible schema" | Zod import issue - using `zod` instead of `@output.ai/core` |
+| "non-deterministic" | Using Math.random(), Date.now(), etc. in workflow code |
+| "FatalError" with retry context | Try-catch wrapping step calls |
+| "undefined is not a function" | Missing schema definitions |
+| "workflow must be deterministic" | Direct I/O in workflow function |
+| "ECONNREFUSED" or timeout | Services not running or network issues |
+
+### Step Status Values
+
+- **COMPLETED**: Step finished successfully
+- **FAILED**: Step threw an error (may retry)
+- **RETRYING**: Step is being retried after a failure
+- **TIMED_OUT**: Step exceeded its timeout
+- **CANCELLED**: Workflow was stopped before step completed
+
+### Key Trace Fields
+
+When examining JSON traces, focus on these fields:
+
+- `steps[].name`: Step identifier
+- `steps[].status`: Execution result
+- `steps[].input`: Data passed to the step
+- `steps[].output`: Data returned from the step
+- `steps[].error`: Error details if failed
+- `steps[].attempts`: Number of execution attempts
+- `steps[].duration`: How long the step took
+
+## Examples
+
+**Scenario**: Debug a failed workflow
+
+```bash
+# Get the workflow ID from runs list
+output workflow runs list --limit 5 --format json
+
+# Get detailed trace
+output workflow debug abc123xyz --format json
+
+# Look for the failing step in the output
+# Example output structure:
+# {
+#   "workflowId": "abc123xyz",
+#   "status": "FAILED",
+#   "steps": [
+#     { "name": "fetchData", "status": "COMPLETED", ... },
+#     { "name": "processData", "status": "FAILED", "error": "..." }
+#   ]
+# }
+```
+
+**Scenario**: Investigate retry behavior
+
+```bash
+output workflow debug abc123xyz --format json | jq '.steps[] | select(.attempts > 1)'
+```
+
+**Scenario**: Check inputs to a specific step
+
+```bash
+output workflow debug abc123xyz --format json | jq '.steps[] | select(.name == "processData") | .input'
+```
+
+## Next Steps After Analysis
+
+1. Match the error to common patterns (see error skills)
+2. Consult the `workflow-quality` subagent for best practices
+3. Make code fixes based on identified issues
+4. Re-run the workflow: `output workflow run <workflowName> <input>`
+5. Verify the fix with a new trace

package/dist/templates/project/README.md.template

@@ -30,7 +30,7 @@ Edit `.env` to add:
 ### 3. Start Output Services
 
 ```bash
-npx output dev
+npm run dev
 ```
 
 This starts:

package/dist/templates/project/package.json.template

@@ -5,8 +5,9 @@
   "type": "module",
   "main": "dist/worker.js",
   "scripts": {
-    "build": "rm -rf dist/* && tsc -p ./ && copyfiles -u 1 './src/**/*.prompt' dist",
-    "start-worker": "npm install && npm run build && output-worker",
+    "output:worker:install": "npm install",
+    "output:worker:build": "rm -rf dist/* && tsc -p ./ && copyfiles -u 1 './src/**/*.prompt' dist",
+    "output:worker:start": "output-worker",
     "dev": "output dev"
   },
   "dependencies": {

package/dist/utils/date_formatter.d.ts

@@ -6,3 +6,18 @@
  * @returns Formatted duration string (e.g., "150ms", "2.50s", "3 minutes 45 seconds")
  */
 export declare function formatDuration(ms: number): string;
+/**
+ * Format an ISO date string to a human-readable format
+ *
+ * @param isoString - ISO 8601 date string
+ * @returns Formatted date string (e.g., "Dec 3, 2025 10:30 AM")
+ */
+export declare function formatDate(isoString: string | null | undefined): string;
+/**
+ * Format a duration between two ISO timestamps
+ *
+ * @param startedAt - ISO 8601 start timestamp
+ * @param completedAt - ISO 8601 end timestamp (or null if still running)
+ * @returns Human-readable duration string (e.g., "5 seconds", "running")
+ */
+export declare function formatDurationFromTimestamps(startedAt: string, completedAt: string | null | undefined): string;

package/dist/utils/date_formatter.js

@@ -1,4 +1,7 @@
-import { formatDuration as formatDurationFns, intervalToDuration } from 'date-fns';
+/**
+ * Date and duration formatting utilities
+ */
+import { format, formatDistanceStrict, formatDuration as formatDurationFns, intervalToDuration, parseISO } from 'date-fns';
 /**
  * Format a duration in milliseconds to a human-readable string.
  * Uses date-fns for durations >= 1 minute, custom formatting for shorter durations.
@@ -17,3 +20,30 @@ export function formatDuration(ms) {
     }
     return formatDurationFns(duration, { format: ['minutes', 'seconds'] });
 }
+/**
+ * Format an ISO date string to a human-readable format
+ *
+ * @param isoString - ISO 8601 date string
+ * @returns Formatted date string (e.g., "Dec 3, 2025 10:30 AM")
+ */
+export function formatDate(isoString) {
+    if (!isoString) {
+        return '-';
+    }
+    return format(parseISO(isoString), 'MMM d, yyyy h:mm a');
+}
+/**
+ * Format a duration between two ISO timestamps
+ *
+ * @param startedAt - ISO 8601 start timestamp
+ * @param completedAt - ISO 8601 end timestamp (or null if still running)
+ * @returns Human-readable duration string (e.g., "5 seconds", "running")
+ */
+export function formatDurationFromTimestamps(startedAt, completedAt) {
+    if (!completedAt) {
+        return 'running';
+    }
+    const start = parseISO(startedAt);
+    const end = parseISO(completedAt);
+    return formatDistanceStrict(start, end, { addSuffix: false });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "CLI for Output.ai workflow generation",
   "type": "module",
   "main": "dist/index.js",