@output.ai/cli 0.3.0 → 0.4.0

package/README.md

@@ -95,6 +95,33 @@ output workflow list --filter simple
 
 The list command connects to the API server and retrieves all available workflows. By default, it displays a simple list of workflow names (like `ls`). Use `--format table` for detailed information.
 
+### Debug a Workflow Execution
+
+```bash
+# Display trace information for a workflow run
+output workflow debug <workflowId>
+
+# Display trace in JSON format
+output workflow debug <workflowId> --format json
+```
+
+#### What It Does
+
+The `debug` command retrieves and displays detailed execution traces for debugging workflow runs. It shows:
+- Complete execution timeline with all events
+- Hierarchical execution tree showing workflow structure
+- Step and activity inputs/outputs
+- Error details and stack traces
+- Performance metrics and durations
+
+#### Command Options
+
+- `--format, -f` - Output format: `text` (default, human-readable) or `json` (raw trace data)
+
+#### Environment Variables
+
+- `HOST_TRACE_PATH` - When running in Docker, this maps the container's trace log path to the host filesystem path. Set this to your project's `logs` directory (e.g., `${PWD}/logs`). Required for trace files to be accessible from the CLI when workflows run in containers.
+
 ### Generate a Workflow
 
 ```bash

package/dist/api/generated/api.d.ts

@@ -32,6 +32,28 @@ export interface Workflow {
     inputSchema?: JSONSchema;
     outputSchema?: JSONSchema;
 }
+/**
+ * File destinations for trace data
+ */
+export type TraceInfoDestinations = {
+    /**
+     * Absolute path to local trace file, or null if not saved locally
+     * @nullable
+     */
+    local: string | null;
+    /**
+     * Remote trace location (e.g., S3 URI), or null if not saved remotely
+     * @nullable
+     */
+    remote: string | null;
+};
+/**
+ * An object with information about the trace generated by the execution
+ */
+export interface TraceInfo {
+    /** File destinations for trace data */
+    destinations?: TraceInfoDestinations;
+}
 export type PostWorkflowRunBody = {
     /** The name of the workflow to execute */
     workflowName: string;
@@ -42,19 +64,12 @@ export type PostWorkflowRunBody = {
     /** The name of the task queue to send the workflow to */
     taskQueue?: string;
 };
-/**
- * An object with information about the trace generated by the execution
- */
-export type PostWorkflowRun200Trace = {
-    [key: string]: unknown;
-};
 export type PostWorkflowRun200 = {
     /** The workflow execution id */
     workflowId?: string;
     /** The output of the workflow */
     output?: unknown;
-    /** An object with information about the trace generated by the execution */
-    trace?: PostWorkflowRun200Trace;
+    trace?: TraceInfo;
 };
 export type PostWorkflowStartBody = {
     /** The name of the workflow to execute */
@@ -94,19 +109,12 @@ export type GetWorkflowIdStatus200 = {
     /** An epoch timestamp representing when the workflow ended */
     completedAt?: number;
 };
-/**
- * An object with information about the trace generated by the execution
- */
-export type GetWorkflowIdOutput200Trace = {
-    [key: string]: unknown;
-};
-export type GetWorkflowIdOutput200 = {
+export type GetWorkflowIdResult200 = {
     /** The workflow execution id */
     workflowId?: string;
-    /** The output of workflow */
+    /** The result of workflow */
     output?: unknown;
-    /** An object with information about the trace generated by the execution */
-    trace?: GetWorkflowIdOutput200Trace;
+    trace?: TraceInfo;
 };
 export type GetWorkflowCatalogId200 = {
     /** Each workflow available in this catalog */
@@ -201,25 +209,25 @@ export type patchWorkflowIdStopResponse = (patchWorkflowIdStopResponseSuccess |
 export declare const getPatchWorkflowIdStopUrl: (id: string) => string;
 export declare const patchWorkflowIdStop: (id: string, options?: ApiRequestOptions) => Promise<patchWorkflowIdStopResponse>;
 /**
- * @summary Return the output of a workflow
+ * @summary Return the result of a workflow
  */
-export type getWorkflowIdOutputResponse200 = {
-    data: GetWorkflowIdOutput200;
+export type getWorkflowIdResultResponse200 = {
+    data: GetWorkflowIdResult200;
     status: 200;
 };
-export type getWorkflowIdOutputResponse404 = {
+export type getWorkflowIdResultResponse404 = {
     data: void;
     status: 404;
 };
-export type getWorkflowIdOutputResponseSuccess = (getWorkflowIdOutputResponse200) & {
+export type getWorkflowIdResultResponseSuccess = (getWorkflowIdResultResponse200) & {
     headers: Headers;
 };
-export type getWorkflowIdOutputResponseError = (getWorkflowIdOutputResponse404) & {
+export type getWorkflowIdResultResponseError = (getWorkflowIdResultResponse404) & {
     headers: Headers;
 };
-export type getWorkflowIdOutputResponse = (getWorkflowIdOutputResponseSuccess | getWorkflowIdOutputResponseError);
-export declare const getGetWorkflowIdOutputUrl: (id: string) => string;
-export declare const getWorkflowIdOutput: (id: string, options?: ApiRequestOptions) => Promise<getWorkflowIdOutputResponse>;
+export type getWorkflowIdResultResponse = (getWorkflowIdResultResponseSuccess | getWorkflowIdResultResponseError);
+export declare const getGetWorkflowIdResultUrl: (id: string) => string;
+export declare const getWorkflowIdResult: (id: string, options?: ApiRequestOptions) => Promise<getWorkflowIdResultResponse>;
 /**
  * @summary Get a specific workflow catalog by ID
  */

package/dist/api/generated/api.js

@@ -69,11 +69,11 @@ export const patchWorkflowIdStop = async (id, options) => {
         method: 'PATCH'
     });
 };
-export const getGetWorkflowIdOutputUrl = (id) => {
-    return `/workflow/${id}/output`;
+export const getGetWorkflowIdResultUrl = (id) => {
+    return `/workflow/${id}/result`;
 };
-export const getWorkflowIdOutput = async (id, options) => {
-    return customFetchInstance(getGetWorkflowIdOutputUrl(id), {
+export const getWorkflowIdResult = async (id, options) => {
+    return customFetchInstance(getGetWorkflowIdResultUrl(id), {
         ...options,
         method: 'GET'
     });

package/dist/assets/docker/docker-compose-dev.yml

@@ -80,6 +80,7 @@ services:
       temporal:
         condition: service_healthy
     image: growthxteam/output-api:latest
+    pull_policy: always
     networks:
       - main
     environment:
@@ -104,6 +105,7 @@ services:
       - REDIS_URL=redis://redis:6379
       - TEMPORAL_ADDRESS=temporal:7233
       - TRACE_LOCAL_ON=true
+      - HOST_TRACE_PATH=${PWD}/logs
     command: npm run start-worker
     working_dir: /app
     volumes:

package/dist/commands/workflow/debug.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+export default class WorkflowDebug extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        workflowId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        format: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private outputJson;
+    private displayTextTrace;
+    catch(error: Error): Promise<void>;
+}

package/dist/commands/workflow/debug.js

@@ -0,0 +1,57 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { OUTPUT_FORMAT } from '#utils/constants.js';
+import { displayDebugTree } from '#utils/trace_formatter.js';
+import { getTrace } from '#services/trace_reader.js';
+import { handleApiError } from '#utils/error_handler.js';
+export default class WorkflowDebug extends Command {
+    static description = 'Get and display workflow execution trace for debugging';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> wf-12345',
+        '<%= config.bin %> <%= command.id %> wf-12345 --format json',
+        '<%= config.bin %> <%= command.id %> wf-12345 --format text'
+    ];
+    static args = {
+        workflowId: Args.string({
+            description: 'The workflow ID to debug',
+            required: true
+        })
+    };
+    static flags = {
+        format: Flags.string({
+            char: 'f',
+            description: 'Output format',
+            options: [OUTPUT_FORMAT.JSON, OUTPUT_FORMAT.TEXT],
+            default: OUTPUT_FORMAT.TEXT
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkflowDebug);
+        const isJsonFormat = flags.format === OUTPUT_FORMAT.JSON;
+        if (!isJsonFormat) {
+            this.log(`Fetching debug information for workflow: ${args.workflowId}...`);
+        }
+        const traceData = await getTrace(args.workflowId);
+        // Output based on format
+        if (isJsonFormat) {
+            this.outputJson(traceData);
+            return;
+        }
+        // Display text format
+        this.displayTextTrace(traceData);
+    }
+    outputJson(data) {
+        this.log(JSON.stringify(data, null, 2));
+    }
+    displayTextTrace(traceData) {
+        this.log('\nTrace Log:');
+        this.log('─'.repeat(80));
+        this.log(displayDebugTree(traceData));
+        this.log('\n' + '─'.repeat(80));
+        this.log('Tip: Use --format json for the full untruncated trace');
+    }
+    async catch(error) {
+        return handleApiError(error, (...args) => this.error(...args), {
+            404: 'Workflow not found or trace not available. Check the workflow ID.'
+        });
+    }
+}

package/dist/commands/workflow/debug.spec.js

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// Mock the TraceReader service
+vi.mock('../../services/trace_reader.js', () => ({
+    findTraceFile: vi.fn(),
+    readTraceFile: vi.fn(),
+    getTrace: vi.fn()
+}));
+// Mock the utilities
+vi.mock('../../utils/trace_formatter.js', () => ({
+    displayDebugTree: vi.fn()
+}));
+describe('workflow debug command', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('command definition', () => {
+        it('should export a valid OCLIF command', async () => {
+            const WorkflowDebug = (await import('./debug.js')).default;
+            expect(WorkflowDebug).toBeDefined();
+            expect(WorkflowDebug.description).toContain('Get and display workflow execution trace for debugging');
+            expect(WorkflowDebug.args).toHaveProperty('workflowId');
+            expect(WorkflowDebug.flags).toHaveProperty('format');
+        });
+        it('should have correct flag configuration', async () => {
+            const WorkflowDebug = (await import('./debug.js')).default;
+            // Format flag
+            expect(WorkflowDebug.flags.format.options).toEqual(['json', 'text']);
+            expect(WorkflowDebug.flags.format.default).toBe('text');
+        });
+        it('should have correct examples', async () => {
+            const WorkflowDebug = (await import('./debug.js')).default;
+            expect(WorkflowDebug.examples).toBeDefined();
+            expect(WorkflowDebug.examples.length).toBeGreaterThan(0);
+        });
+    });
+});

package/dist/commands/workflow/{output.d.ts → result.d.ts}

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-export default class WorkflowOutput extends Command {
+export default class WorkflowResult extends Command {
     static description: string;
     static examples: string[];
     static args: {

package/dist/commands/workflow/{output.js → result.js}

@@ -1,17 +1,17 @@
 import { Args, Command, Flags } from '@oclif/core';
-import { getWorkflowIdOutput } from '#api/generated/api.js';
+import { getWorkflowIdResult } from '#api/generated/api.js';
 import { OUTPUT_FORMAT } from '#utils/constants.js';
 import { formatOutput } from '#utils/output_formatter.js';
 import { handleApiError } from '#utils/error_handler.js';
-export default class WorkflowOutput extends Command {
-    static description = 'Get workflow execution output';
+export default class WorkflowResult extends Command {
+    static description = 'Get workflow execution result';
     static examples = [
         '<%= config.bin %> <%= command.id %> wf-12345',
         '<%= config.bin %> <%= command.id %> wf-12345 --format json'
     ];
     static args = {
         workflowId: Args.string({
-            description: 'The workflow ID to get output for',
+            description: 'The workflow ID to get result for',
             required: true
         })
     };
@@ -24,9 +24,9 @@ export default class WorkflowOutput extends Command {
         })
     };
     async run() {
-        const { args, flags } = await this.parse(WorkflowOutput);
-        this.log(`Fetching output for workflow: ${args.workflowId}...`);
-        const response = await getWorkflowIdOutput(args.workflowId);
+        const { args, flags } = await this.parse(WorkflowResult);
+        this.log(`Fetching result for workflow: ${args.workflowId}...`);
+        const response = await getWorkflowIdResult(args.workflowId);
         if (!response || !response.data) {
             this.error('API returned invalid response', { exit: 1 });
         }
@@ -34,7 +34,7 @@ export default class WorkflowOutput extends Command {
             const lines = [
                 `Workflow ID: ${result.workflowId || 'unknown'}`,
                 '',
-                'Output:',
+                'Result:',
                 JSON.stringify(result.output, null, 2)
             ];
             return lines.join('\n');

package/dist/commands/workflow/result.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/workflow/result.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('../../api/generated/api.js', () => ({
+    getWorkflowIdResult: vi.fn()
+}));
+describe('workflow result command', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('command definition', () => {
+        it('should export a valid OCLIF command', async () => {
+            const WorkflowResult = (await import('./result.js')).default;
+            expect(WorkflowResult).toBeDefined();
+            expect(WorkflowResult.description).toContain('Get workflow execution result');
+            expect(WorkflowResult.args).toHaveProperty('workflowId');
+            expect(WorkflowResult.flags).toHaveProperty('format');
+        });
+        it('should have correct flag configuration', async () => {
+            const WorkflowResult = (await import('./result.js')).default;
+            expect(WorkflowResult.flags.format.options).toEqual(['json', 'text']);
+            expect(WorkflowResult.flags.format.default).toBe('text');
+        });
+    });
+});

package/dist/commands/workflow/start.js

@@ -45,7 +45,7 @@ export default class WorkflowStart extends Command {
             `Workflow ID: ${result.workflowId || 'unknown'}`,
             '',
             `Use "workflow status ${result.workflowId || '<workflow-id>'}" to check the workflow status`,
-            `Use "workflow output ${result.workflowId || '<workflow-id>'}" to get the workflow output when complete`
+            `Use "workflow result ${result.workflowId || '<workflow-id>'}" to get the workflow result when complete`
         ].join('\n');
         this.log(`\n${output}`);
     }

package/dist/services/trace_reader.d.ts

@@ -0,0 +1,14 @@
+import type { TraceData } from '#types/trace.js';
+export type { TraceData };
+/**
+ * Find trace file from workflow metadata
+ */
+export declare function findTraceFile(workflowId: string): Promise<string>;
+/**
+ * Read and parse trace file
+ */
+export declare function readTraceFile(path: string): Promise<TraceData>;
+/**
+ * Get trace data from workflow ID
+ */
+export declare function getTrace(workflowId: string): Promise<TraceData>;

package/dist/services/trace_reader.js

@@ -0,0 +1,67 @@
+import { readFile, stat } from 'node:fs/promises';
+import { getWorkflowIdResult } from '#api/generated/api.js';
+import { getErrorCode } from '#utils/error_utils.js';
+/**
+ * Check if a file exists with detailed error information
+ */
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return { exists: true };
+    }
+    catch (error) {
+        const code = getErrorCode(error);
+        if (code === 'ENOENT') {
+            return { exists: false };
+        }
+        if (code === 'EACCES') {
+            return { exists: false, error: `Permission denied: ${path}` };
+        }
+        return { exists: false, error: `Cannot access file: ${path}` };
+    }
+}
+/**
+ * Find trace file from workflow metadata
+ */
+export async function findTraceFile(workflowId) {
+    const response = await getWorkflowIdResult(workflowId);
+    // Check if we got a successful response
+    if (response.status !== 200) {
+        throw new Error(`Failed to get workflow result for ${workflowId}`);
+    }
+    const tracePath = response.data.trace?.destinations?.local;
+    if (!tracePath) {
+        throw new Error(`No trace file path found for workflow ${workflowId}`);
+    }
+    const fileCheck = await fileExists(tracePath);
+    if (!fileCheck.exists) {
+        const errorDetail = fileCheck.error || `Trace file not found at path: ${tracePath}`;
+        throw new Error(errorDetail);
+    }
+    return tracePath;
+}
+/**
+ * Read and parse trace file
+ */
+export async function readTraceFile(path) {
+    try {
+        const content = await readFile(path, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (getErrorCode(error) === 'ENOENT') {
+            throw new Error(`Trace file not found at path: ${path}`);
+        }
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in trace file: ${path}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Get trace data from workflow ID
+ */
+export async function getTrace(workflowId) {
+    const tracePath = await findTraceFile(workflowId);
+    return readTraceFile(tracePath);
+}

package/dist/services/trace_reader.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/trace_reader.spec.js

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { findTraceFile, readTraceFile } from './trace_reader.js';
+// Mock file system operations
+vi.mock('node:fs/promises', () => ({
+    readFile: vi.fn(),
+    stat: vi.fn()
+}));
+// Mock API
+vi.mock('../api/generated/api.js', () => ({
+    getWorkflowIdResult: vi.fn()
+}));
+describe('TraceReader', () => {
+    const getMocks = async () => {
+        const fsModule = await import('node:fs/promises');
+        const apiModule = await import('../api/generated/api.js');
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mockReadFile: fsModule.readFile,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mockStat: fsModule.stat,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mockGetWorkflowIdResult: apiModule.getWorkflowIdResult
+        };
+    };
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('findTraceFile', () => {
+        it('should find trace file from workflow output metadata', async () => {
+            const { mockGetWorkflowIdResult, mockStat } = await getMocks();
+            const workflowId = 'test-workflow-123';
+            const expectedPath = '/app/logs/runs/test/2024-01-01_test-workflow-123.json';
+            mockGetWorkflowIdResult.mockResolvedValue({
+                status: 200,
+                data: {
+                    workflowId,
+                    output: { result: 'test result' },
+                    trace: {
+                        destinations: {
+                            local: expectedPath,
+                            remote: null
+                        }
+                    }
+                }
+            });
+            mockStat.mockResolvedValue({ isFile: () => true });
+            const result = await findTraceFile(workflowId);
+            expect(result).toBe(expectedPath);
+            expect(mockGetWorkflowIdResult).toHaveBeenCalledWith(workflowId);
+            expect(mockStat).toHaveBeenCalledWith(expectedPath);
+        });
+        it('should throw error when no trace path in metadata', async () => {
+            const { mockGetWorkflowIdResult } = await getMocks();
+            const workflowId = 'test-workflow-456';
+            mockGetWorkflowIdResult.mockResolvedValue({
+                status: 200,
+                data: {
+                    workflowId,
+                    output: { result: 'test result' },
+                    trace: {
+                        destinations: {
+                            local: null,
+                            remote: null
+                        }
+                    }
+                }
+            });
+            await expect(findTraceFile(workflowId))
+                .rejects.toThrow(`No trace file path found for workflow ${workflowId}`);
+        });
+        it('should throw error when trace file not on disk', async () => {
+            const { mockGetWorkflowIdResult, mockStat } = await getMocks();
+            const workflowId = 'test-workflow-789';
+            const expectedPath = '/app/logs/runs/test/2024-01-01_test-workflow-789.json';
+            mockGetWorkflowIdResult.mockResolvedValue({
+                status: 200,
+                data: {
+                    workflowId,
+                    output: { result: 'test result' },
+                    trace: {
+                        destinations: {
+                            local: expectedPath,
+                            remote: null
+                        }
+                    }
+                }
+            });
+            const enoentError = Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' });
+            mockStat.mockRejectedValue(enoentError);
+            await expect(findTraceFile(workflowId))
+                .rejects.toThrow(`Trace file not found at path: ${expectedPath}`);
+        });
+        it('should throw error when API call fails', async () => {
+            const { mockGetWorkflowIdResult } = await getMocks();
+            const workflowId = 'non-existent';
+            mockGetWorkflowIdResult.mockRejectedValue(new Error('Workflow not found'));
+            await expect(findTraceFile(workflowId))
+                .rejects.toThrow('Workflow not found');
+        });
+        it('should handle missing trace property gracefully', async () => {
+            const { mockGetWorkflowIdResult } = await getMocks();
+            const workflowId = 'test-workflow-no-trace';
+            mockGetWorkflowIdResult.mockResolvedValue({
+                status: 200,
+                data: {
+                    workflowId,
+                    output: { result: 'test result' }
+                    // No trace property at all
+                }
+            });
+            await expect(findTraceFile(workflowId))
+                .rejects.toThrow(`No trace file path found for workflow ${workflowId}`);
+        });
+        it('should throw error when workflow not found (404)', async () => {
+            const { mockGetWorkflowIdResult } = await getMocks();
+            const workflowId = 'non-existent-workflow';
+            mockGetWorkflowIdResult.mockResolvedValue({
+                status: 404,
+                data: void 0
+            });
+            await expect(findTraceFile(workflowId))
+                .rejects.toThrow(`Failed to get workflow result for ${workflowId}`);
+        });
+    });
+    describe('readTraceFile', () => {
+        it('should read and parse JSON file successfully', async () => {
+            const { mockReadFile } = await getMocks();
+            const path = '/logs/test.json';
+            const traceData = {
+                root: { workflowName: 'test' },
+                events: []
+            };
+            mockReadFile.mockResolvedValue(JSON.stringify(traceData));
+            const result = await readTraceFile(path);
+            expect(result).toEqual(traceData);
+            expect(mockReadFile).toHaveBeenCalledWith(path, 'utf-8');
+        });
+        it('should throw error for non-existent file', async () => {
+            const { mockReadFile } = await getMocks();
+            const path = '/logs/missing.json';
+            const error = new Error('ENOENT');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            error.code = 'ENOENT';
+            mockReadFile.mockRejectedValue(error);
+            await expect(readTraceFile(path))
+                .rejects.toThrow(`Trace file not found at path: ${path}`);
+        });
+        it('should throw error for invalid JSON', async () => {
+            const { mockReadFile } = await getMocks();
+            const path = '/logs/invalid.json';
+            mockReadFile.mockResolvedValue('invalid json {');
+            await expect(readTraceFile(path))
+                .rejects.toThrow(`Invalid JSON in trace file: ${path}`);
+        });
+        it('should rethrow other errors', async () => {
+            const { mockReadFile } = await getMocks();
+            const path = '/logs/test.json';
+            const error = new Error('Permission denied');
+            mockReadFile.mockRejectedValue(error);
+            await expect(readTraceFile(path))
+                .rejects.toThrow('Permission denied');
+        });
+    });
+});

package/dist/types/trace.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Trace types for workflow execution data.
+ *
+ * These types represent the structure of trace files generated during workflow execution,
+ * used for debugging, visualization, and analysis of workflow runs.
+ */
+/** Node kind values for trace events */
+export type NodeKind = 'workflow' | 'activity' | 'step' | 'internal_step' | string;
+/** Phase of a trace event lifecycle */
+export type NodePhase = 'start' | 'end' | 'error' | string;
+/** Execution status of a node */
+export type NodeStatus = 'completed' | 'failed' | 'running' | string;
+/**
+ * Details associated with a trace event.
+ * Contains input/output data and identifying information for the event.
+ */
+export interface TraceDetails {
+    /** Input data passed to the step/activity */
+    input?: unknown;
+    /** Output data returned from the step/activity */
+    output?: unknown;
+    /** Name of the activity (for activity events) */
+    activityName?: string;
+    /** Name of the step (for step events) */
+    stepName?: string;
+    /** Generic name field */
+    name?: string;
+}
+/**
+ * A trace event representing a point in workflow execution.
+ * Used for timeline display and event-based analysis.
+ */
+export interface TraceEvent {
+    /** The type of event (workflow, activity, step, etc.) */
+    kind: NodeKind;
+    /** The lifecycle phase of the event */
+    phase: NodePhase;
+    /** Unix timestamp when the event occurred */
+    timestamp: number;
+    /** Unique identifier for the workflow run */
+    workflowId: string;
+    /** Name of the workflow being executed */
+    workflowName: string;
+    /** Additional event details including input/output */
+    details?: TraceDetails;
+    /** Child events for nested executions */
+    children?: TraceEvent[];
+    /** Error information if the event represents a failure */
+    error?: unknown;
+    /** Duration of the event in milliseconds */
+    duration?: number;
+}
+/**
+ * A node in the debug tree representation of workflow execution.
+ * Contains more detailed timing and state information than TraceEvent.
+ */
+export interface DebugNode {
+    /** The type of node (workflow, activity, step, internal_step) */
+    kind?: NodeKind;
+    /** Alternative type field */
+    type?: string;
+    /** The name of the step or activity */
+    name?: string;
+    /** Name of the workflow (for workflow nodes) */
+    workflowName?: string;
+    /** Name of the step (for step nodes) */
+    stepName?: string;
+    /** Name of the activity (for activity nodes) */
+    activityName?: string;
+    /** The lifecycle phase of the node */
+    phase?: NodePhase;
+    /** Execution status (completed, failed, running) */
+    status?: NodeStatus;
+    /** Unix timestamp or ISO string when execution started */
+    startedAt?: number | string;
+    /** Unix timestamp when the event occurred */
+    timestamp?: number | string;
+    /** Unix timestamp or ISO string when execution ended */
+    endedAt?: number | string;
+    /** Unix timestamp when execution started (alternative field) */
+    startTime?: number;
+    /** Unix timestamp when execution ended (alternative field) */
+    endTime?: number;
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Input data passed to the step/activity */
+    input?: unknown;
+    /** Output data returned from the step/activity */
+    output?: unknown;
+    /** Additional execution details */
+    details?: Record<string, unknown>;
+    /** Error information if the node failed */
+    error?: unknown;
+    /** Child nodes representing nested executions */
+    children?: DebugNode[];
+}
+/**
+ * Root structure of a workflow trace.
+ * Contains the execution tree and optional flat event list.
+ */
+export interface TraceStructure {
+    /** Root node of the execution tree */
+    root?: TraceEvent | DebugNode;
+    /** Flat list of execution events for timeline display */
+    events?: TraceEvent[];
+    /** Hierarchical tree of execution nodes (alternative to root.children) */
+    children?: DebugNode[];
+}
+/**
+ * The structure of a workflow trace file generated by Output SDK workflow runs.
+ * This file is written to the local filesystem during workflow execution and contains
+ * the complete execution history including timing, inputs, outputs, and any errors.
+ */
+export interface TraceData {
+    /** Root workflow execution information */
+    root: {
+        /** The name of the workflow that was executed */
+        workflowName: string;
+        /** Unique identifier for this workflow run */
+        workflowId: string;
+        /** Unix timestamp when the workflow started */
+        startTime: number;
+        /** Unix timestamp when the workflow ended */
+        endTime?: number;
+        /** Total workflow duration in milliseconds */
+        duration?: number;
+        /** Final workflow status */
+        status?: string;
+        /** Error information if the workflow failed */
+        error?: unknown;
+    };
+    /** Flat list of execution events for timeline display */
+    events?: Array<{
+        name: string;
+        phase: string;
+        timestamp: number;
+        details?: unknown;
+    }>;
+    /** Hierarchical tree of execution nodes */
+    children?: DebugNode[];
+}
+/**
+ * Extracted node information for display formatting.
+ * Used internally by the trace formatter.
+ */
+export interface NodeInfo {
+    /** Display name for the node */
+    name: string;
+    /** Formatted phase indicator */
+    phase: string;
+    /** Formatted duration string */
+    duration: string;
+}
+/**
+ * Type guard to check if a node is a TraceEvent.
+ */
+export declare const isTraceEvent: (node: TraceEvent | DebugNode) => node is TraceEvent;
+/**
+ * Type guard to check if a value is a valid timestamp.
+ */
+export declare const isValidTimestamp: (value: unknown) => value is number | string;

package/dist/types/trace.js

@@ -0,0 +1,18 @@
+/**
+ * Trace types for workflow execution data.
+ *
+ * These types represent the structure of trace files generated during workflow execution,
+ * used for debugging, visualization, and analysis of workflow runs.
+ */
+/**
+ * Type guard to check if a node is a TraceEvent.
+ */
+export const isTraceEvent = (node) => {
+    return 'workflowId' in node && 'timestamp' in node;
+};
+/**
+ * Type guard to check if a value is a valid timestamp.
+ */
+export const isValidTimestamp = (value) => {
+    return typeof value === 'number' || typeof value === 'string';
+};

package/dist/utils/date_formatter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Format a duration in milliseconds to a human-readable string.
+ * Uses date-fns for durations >= 1 minute, custom formatting for shorter durations.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string (e.g., "150ms", "2.50s", "3 minutes 45 seconds")
+ */
+export declare function formatDuration(ms: number): string;

package/dist/utils/date_formatter.js

@@ -0,0 +1,19 @@
+import { formatDuration as formatDurationFns, intervalToDuration } 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.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string (e.g., "150ms", "2.50s", "3 minutes 45 seconds")
+ */
+export function formatDuration(ms) {
+    const duration = intervalToDuration({ start: 0, end: ms });
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    if (ms < 60000) {
+        const seconds = ms / 1000;
+        return `${seconds.toFixed(2)}s`;
+    }
+    return formatDurationFns(duration, { format: ['minutes', 'seconds'] });
+}

package/dist/utils/trace_formatter.d.ts

@@ -0,0 +1,11 @@
+import { formatDuration } from '#utils/date_formatter.js';
+export { formatDuration };
+export declare function format(traceData: string | object, outputFormat?: 'json' | 'text'): string;
+export declare function getSummary(traceData: string | object): {
+    totalDuration: number;
+    totalEvents: number;
+    totalSteps: number;
+    totalActivities: number;
+    hasErrors: boolean;
+};
+export declare function displayDebugTree(node: unknown): string;

package/dist/utils/trace_formatter.js

@@ -0,0 +1,402 @@
+import Table from 'cli-table3';
+import { ux } from '@oclif/core';
+import { formatOutput } from '#utils/output_formatter.js';
+import { formatDuration } from '#utils/date_formatter.js';
+import { getErrorMessage } from '#utils/error_utils.js';
+import { isTraceEvent, isValidTimestamp } from '#types/trace.js';
+export { formatDuration };
+const TRUNCATION = {
+    SHORT: 50,
+    STANDARD: 120,
+    SUFFIX: '...',
+    SUFFIX_VERBOSE: '... (truncated)'
+};
+const TREE_CHARS = {
+    BRANCH: '├─ ',
+    LAST: '└─ ',
+    VERTICAL: '│  ',
+    SPACE: '   ',
+    DETAIL_BRANCH: '│    ',
+    DETAIL_LAST: '     '
+};
+const HEADER_DIVIDER = '═'.repeat(60);
+const colors = {
+    workflowHeader: (text) => ux.colorize('bold', ux.colorize('cyan', text)),
+    stepHeader: (text) => ux.colorize('yellow', text),
+    internalStep: (text) => ux.colorize('dim', text),
+    label: (text) => ux.colorize('blue', text),
+    error: (text) => ux.colorize('red', text),
+    success: (text) => ux.colorize('green', text)
+};
+const truncate = (value, maxLength = TRUNCATION.STANDARD, suffix = TRUNCATION.SUFFIX_VERBOSE, recursive = false) => {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        if (value.length <= maxLength) {
+            return value;
+        }
+        return `${value.substring(0, maxLength)}${suffix}`;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        if (recursive) {
+            return value;
+        }
+        return String(value);
+    }
+    if (!recursive) {
+        const str = JSON.stringify(value);
+        if (str.length <= maxLength) {
+            return str;
+        }
+        return `${str.substring(0, maxLength)}${suffix}`;
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => truncate(item, maxLength, suffix, true));
+    }
+    if (typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, truncate(v, maxLength, suffix, true)]));
+    }
+    return value;
+};
+const truncateShort = (value) => {
+    return truncate(value, TRUNCATION.SHORT, TRUNCATION.SUFFIX, false);
+};
+const truncateRecursive = (value) => {
+    return truncate(value, TRUNCATION.STANDARD, TRUNCATION.SUFFIX_VERBOSE, true);
+};
+const formatPhase = (phase) => {
+    const phaseMap = {
+        start: '[START]',
+        end: '[END]',
+        error: '[ERROR]'
+    };
+    return phaseMap[phase] ?? phase;
+};
+const getNodeName = (node) => {
+    return node.name || node.workflowName || node.stepName || node.activityName || '';
+};
+const getNodeKind = (node) => {
+    return node.kind || node.type || '';
+};
+const getEventName = (event) => {
+    const { kind, workflowName, details } = event;
+    if (kind === 'workflow') {
+        return `Workflow: ${workflowName}`;
+    }
+    if (kind === 'activity') {
+        return `Activity: ${details?.activityName || 'unknown'}`;
+    }
+    if (kind === 'step') {
+        return `Step: ${details?.stepName || details?.name || 'unknown'}`;
+    }
+    return kind || 'Unknown Event';
+};
+const colorizeByKind = (kind, text) => {
+    if (kind === 'workflow') {
+        return colors.workflowHeader(text);
+    }
+    if (kind === 'internal_step') {
+        return colors.internalStep(text);
+    }
+    if (kind === 'step' || kind === 'activity') {
+        return colors.stepHeader(text);
+    }
+    return text;
+};
+const getStatusIndicator = (node) => {
+    if (node.phase === 'error' || node.status === 'failed') {
+        return colors.error('[FAILED]');
+    }
+    if (node.phase === 'end' || node.status === 'completed') {
+        return colors.success('[COMPLETED]');
+    }
+    if (node.status === 'running') {
+        return colors.label('[RUNNING]');
+    }
+    return '';
+};
+const getDebugNodeInfo = (node) => {
+    if (typeof node === 'string') {
+        return node;
+    }
+    if (typeof node !== 'object' || node === null) {
+        return String(node);
+    }
+    const debugNode = node;
+    const kind = getNodeKind(debugNode);
+    const name = getNodeName(debugNode);
+    const status = getStatusIndicator(debugNode);
+    const parts = [];
+    if (kind) {
+        parts.push(colorizeByKind(kind, `[${kind}]`));
+    }
+    if (name) {
+        parts.push(colorizeByKind(kind, name));
+    }
+    if (status) {
+        parts.push(status);
+    }
+    if (parts.length === 0) {
+        const keys = Object.keys(debugNode).filter(k => k !== 'children' && k !== 'parent');
+        if (keys.length > 0) {
+            return `Node {${keys.slice(0, 3).join(', ')}${keys.length > 3 ? ', ...' : ''}}`;
+        }
+        return 'Node';
+    }
+    return parts.join(' ');
+};
+const extractNodeInfo = (node) => {
+    if (isTraceEvent(node)) {
+        return {
+            name: getEventName(node),
+            phase: formatPhase(node.phase),
+            duration: node.duration ? ` (${formatDuration(node.duration)})` : ''
+        };
+    }
+    return {
+        name: getDebugNodeInfo(node),
+        phase: node.phase ? formatPhase(node.phase) : '',
+        duration: node.duration ? ` (${formatDuration(node.duration)})` : ''
+    };
+};
+const formatDetails = (details) => {
+    if (!details) {
+        return '-';
+    }
+    if (typeof details === 'string') {
+        return details;
+    }
+    const info = [];
+    if (details.input) {
+        info.push(`Input: ${truncateShort(details.input)}`);
+    }
+    if (details.output) {
+        info.push(`Output: ${truncateShort(details.output)}`);
+    }
+    if (details.activityName) {
+        info.push(`Activity: ${details.activityName}`);
+    }
+    if (details.stepName || details.name) {
+        info.push(`Step: ${details.stepName || details.name}`);
+    }
+    if (info.length > 0) {
+        return info.join(', ');
+    }
+    return truncateShort(details);
+};
+const formatTreeDetails = (details, depth) => {
+    const indent = '  '.repeat(depth);
+    const lines = [];
+    if (details.input !== null && details.input !== undefined) {
+        lines.push(`${indent}Input: ${truncateShort(details.input)}`);
+    }
+    if (details.output !== null && details.output !== undefined) {
+        lines.push(`${indent}Output: ${truncateShort(details.output)}`);
+    }
+    return lines;
+};
+const formatValueWithIndent = (value, indentPrefix) => {
+    if (value === null || value === undefined) {
+        return String(value);
+    }
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return truncate(value, TRUNCATION.STANDARD, TRUNCATION.SUFFIX_VERBOSE, false);
+    }
+    const truncated = truncateRecursive(value);
+    const jsonStr = JSON.stringify(truncated, null, 2);
+    const lines = jsonStr.split('\n');
+    if (lines.length <= 1) {
+        return jsonStr;
+    }
+    return lines.map((line, i) => {
+        if (i === 0) {
+            return line;
+        }
+        return indentPrefix + line;
+    }).join('\n');
+};
+const formatHeader = (root) => {
+    const isTrace = isTraceEvent(root);
+    const debugRoot = root;
+    const workflowName = isTrace ? root.workflowName : (getNodeName(debugRoot) || 'Unknown');
+    const workflowId = isTrace ? root.workflowId : 'N/A';
+    const timestamp = isTrace ? root.timestamp : debugRoot.startTime;
+    const phase = isTrace ? root.phase : debugRoot.phase;
+    const status = !isTrace ? debugRoot.status : undefined;
+    const lines = [
+        HEADER_DIVIDER,
+        `Workflow: ${workflowName}`,
+        `Workflow ID: ${workflowId}`
+    ];
+    if (isValidTimestamp(timestamp)) {
+        lines.push(`Start Time: ${new Date(timestamp).toISOString()}`);
+    }
+    if (root.duration) {
+        lines.push(`Duration: ${formatDuration(root.duration)}`);
+    }
+    if ((phase === 'error' || status === 'failed') && root.error) {
+        lines.push('Status: Failed', `Error: ${getErrorMessage(root.error)}`);
+    }
+    else if (phase === 'end' || status === 'completed') {
+        lines.push('Status: Completed');
+    }
+    else {
+        lines.push('Status: In Progress');
+    }
+    lines.push(HEADER_DIVIDER);
+    return lines.join('\n');
+};
+const formatEventsTable = (events) => {
+    const table = new Table({
+        head: ['Time', 'Event', 'Phase', 'Duration', 'Details'],
+        style: { head: ['cyan'] },
+        colWidths: [20, 25, 10, 12, null],
+        wordWrap: true
+    });
+    for (const event of events) {
+        table.push([
+            new Date(event.timestamp).toISOString().substring(11, 23),
+            getEventName(event),
+            formatPhase(event.phase),
+            event.duration ? formatDuration(event.duration) : '-',
+            formatDetails(event.details)
+        ]);
+    }
+    return table.toString();
+};
+const formatTree = (node, depth) => {
+    const indent = '  '.repeat(depth);
+    const marker = depth === 0 ? '' : TREE_CHARS.BRANCH;
+    const info = extractNodeInfo(node);
+    const lines = [`${indent}${marker} ${info.name} ${info.phase}${info.duration}`];
+    if (node.error) {
+        lines.push(`${indent}   ${TREE_CHARS.LAST.trim()} ERROR: ${getErrorMessage(node.error)}`);
+    }
+    if (node.details && typeof node.details === 'object') {
+        lines.push(...formatTreeDetails(node.details, depth + 1));
+    }
+    if (node.children && node.children.length > 0) {
+        for (const child of node.children) {
+            lines.push(...formatTree(child, depth + 1));
+        }
+    }
+    return lines;
+};
+const getDebugNodeDetails = (node, prefix) => {
+    if (typeof node !== 'object' || node === null) {
+        return [];
+    }
+    const details = [];
+    const startedAt = node.startedAt || node.timestamp;
+    const inputIndentPrefix = prefix + ' '.repeat(7);
+    const outputIndentPrefix = prefix + ' '.repeat(8);
+    if (isValidTimestamp(startedAt)) {
+        const startDate = new Date(startedAt);
+        if (!isNaN(startDate.getTime())) {
+            details.push(`${prefix}${colors.label('Started:')} ${startDate.toISOString()}`);
+        }
+    }
+    if (isValidTimestamp(node.endedAt)) {
+        const endDate = new Date(node.endedAt);
+        if (!isNaN(endDate.getTime())) {
+            details.push(`${prefix}${colors.label('Ended:')}   ${endDate.toISOString()}`);
+        }
+    }
+    if (typeof node.startedAt === 'number' && typeof node.endedAt === 'number') {
+        details.push(`${prefix}${colors.label('Duration:')} ${formatDuration(node.endedAt - node.startedAt)}`);
+    }
+    else if (node.duration) {
+        details.push(`${prefix}${colors.label('Duration:')} ${formatDuration(node.duration)}`);
+    }
+    if (node.input !== null && node.input !== undefined) {
+        details.push(`${prefix}${colors.label('Input:')} ${formatValueWithIndent(node.input, inputIndentPrefix)}`);
+    }
+    if (node.output !== null && node.output !== undefined) {
+        details.push(`${prefix}${colors.label('Output:')} ${formatValueWithIndent(node.output, outputIndentPrefix)}`);
+    }
+    if (node.error) {
+        details.push(`${prefix}${colors.error('Error:')} ${colors.error(getErrorMessage(node.error))}`);
+    }
+    if (details.length > 0) {
+        details.push('');
+    }
+    return details;
+};
+const buildDebugTreeLines = (node, depth, isLast, prefix) => {
+    if (node === null || node === undefined) {
+        return [];
+    }
+    const isRoot = depth === 0;
+    const getConnector = () => {
+        if (isRoot) {
+            return '';
+        }
+        return isLast ? TREE_CHARS.LAST : TREE_CHARS.BRANCH;
+    };
+    const connector = getConnector();
+    const indent = isRoot ? '' : prefix + connector;
+    const lines = [indent + getDebugNodeInfo(node)];
+    const detailPrefix = isRoot ? '  ' : prefix + (isLast ? TREE_CHARS.DETAIL_LAST : TREE_CHARS.DETAIL_BRANCH);
+    if (typeof node === 'object' && node !== null) {
+        lines.push(...getDebugNodeDetails(node, detailPrefix));
+    }
+    const childPrefix = isRoot ? '' : prefix + (isLast ? TREE_CHARS.SPACE : TREE_CHARS.VERTICAL);
+    if (typeof node === 'object' && node !== null) {
+        const debugNode = node;
+        if (Array.isArray(debugNode.children)) {
+            debugNode.children.forEach((child, i) => {
+                const isLastChild = i === debugNode.children.length - 1;
+                lines.push(...buildDebugTreeLines(child, depth + 1, isLastChild, childPrefix));
+            });
+        }
+    }
+    return lines;
+};
+const formatAsText = (trace) => {
+    const output = [];
+    if (trace.root) {
+        output.push(formatHeader(trace.root), '');
+    }
+    if (trace.events && trace.events.length > 0) {
+        output.push('Execution Timeline:', formatEventsTable(trace.events), '');
+    }
+    if (trace.root) {
+        output.push('Execution Tree:', ...formatTree(trace.root, 0));
+    }
+    return output.join('\n');
+};
+export function format(traceData, outputFormat = 'text') {
+    const trace = typeof traceData === 'string' ? JSON.parse(traceData) : traceData;
+    if (outputFormat === 'json') {
+        return formatOutput(trace, 'json');
+    }
+    return formatAsText(trace);
+}
+export function getSummary(traceData) {
+    const trace = typeof traceData === 'string' ? JSON.parse(traceData) : traceData;
+    const stats = {
+        totalDuration: trace.root?.duration || 0,
+        totalEvents: trace.events?.length || 0,
+        totalSteps: 0,
+        totalActivities: 0,
+        hasErrors: false
+    };
+    if (trace.events) {
+        for (const event of trace.events) {
+            if (event.kind === 'step') {
+                stats.totalSteps++;
+            }
+            if (event.kind === 'activity') {
+                stats.totalActivities++;
+            }
+            if (event.phase === 'error') {
+                stats.hasErrors = true;
+            }
+        }
+    }
+    return stats;
+}
+export function displayDebugTree(node) {
+    return buildDebugTreeLines(node, 0, false, '').join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "CLI for Output.ai workflow generation",
   "type": "module",
   "main": "dist/index.js",
@@ -30,6 +30,7 @@
     "change-case": "5.4.4",
     "cli-progress": "3.12.0",
     "cli-table3": "0.6.5",
+    "date-fns": "4.1.0",
     "dotenv": "16.4.7",
     "handlebars": "4.7.8",
     "json-schema-library": "10.3.0",

package/dist/commands/workflow/output.test.js

@@ -1,23 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-vi.mock('../../api/generated/api.js', () => ({
-    getWorkflowIdOutput: vi.fn()
-}));
-describe('workflow output command', () => {
-    beforeEach(() => {
-        vi.clearAllMocks();
-    });
-    describe('command definition', () => {
-        it('should export a valid OCLIF command', async () => {
-            const WorkflowOutput = (await import('./output.js')).default;
-            expect(WorkflowOutput).toBeDefined();
-            expect(WorkflowOutput.description).toContain('Get workflow execution output');
-            expect(WorkflowOutput.args).toHaveProperty('workflowId');
-            expect(WorkflowOutput.flags).toHaveProperty('format');
-        });
-        it('should have correct flag configuration', async () => {
-            const WorkflowOutput = (await import('./output.js')).default;
-            expect(WorkflowOutput.flags.format.options).toEqual(['json', 'text']);
-            expect(WorkflowOutput.flags.format.default).toBe('text');
-        });
-    });
-});