@output.ai/cli 0.3.0-dev.pr156.16605c1 → 0.3.0-dev.pr156.a0c12ed

package/README.md

@@ -103,15 +103,6 @@ output workflow debug <workflowId>
 
 # Display trace in JSON format
 output workflow debug <workflowId> --format json
-
-# Prefer remote (S3) trace over local
-output workflow debug <workflowId> --remote
-
-# Save trace to a custom directory
-output workflow debug <workflowId> --download-dir ./my-traces
-
-# Force re-download of remote traces (bypass cache)
-output workflow debug <workflowId> --remote --force-download
 ```
 
 #### What It Does
@@ -123,30 +114,13 @@ The `debug` command retrieves and displays detailed execution traces for debuggi
 - Error details and stack traces
 - Performance metrics and durations
 
-#### Trace Sources
-
-The command automatically handles both local and remote traces:
-- **Local traces**: Stored on your machine when `TRACE_LOCAL_ON=true`
-- **Remote traces**: Stored in S3 when `TRACE_REMOTE_ON=true` (requires AWS credentials)
-
-By default, it tries local traces first for faster access, then falls back to remote if needed.
-
 #### Command Options
 
 - `--format, -f` - Output format: `text` (default, human-readable) or `json` (raw trace data)
-- `--remote, -r` - Prefer remote S3 trace even if local exists
-- `--download-dir, -d` - Directory for saving downloaded traces (default: `.output/traces`)
-- `--open, -o` - Save trace to file for viewing in external JSON viewer
-- `--force-download` - Force re-download from S3, bypassing local cache
 
-#### AWS Configuration
+#### Environment Variables
 
-For remote traces, configure AWS credentials:
-```bash
-export AWS_ACCESS_KEY_ID=your-access-key
-export AWS_SECRET_ACCESS_KEY=your-secret-key
-export AWS_REGION=us-east-1  # or your region
-```
+- `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
 

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 = {
     /** The workflow execution id */
     workflowId?: string;
     /** The output 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 */

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

@@ -9,7 +9,7 @@ export default class WorkflowDebug extends Command {
         format: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
-    private getTrace;
     private outputJson;
     private displayTextTrace;
+    catch(error: Error): Promise<void>;
 }

package/dist/commands/workflow/debug.js

@@ -1,7 +1,8 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { OUTPUT_FORMAT } from '#utils/constants.js';
-import { traceFormatter } from '#utils/trace_formatter.js';
-import { TraceReader } from '#services/trace_reader.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 = [
@@ -29,7 +30,7 @@ export default class WorkflowDebug extends Command {
         if (!isJsonFormat) {
             this.log(`Fetching debug information for workflow: ${args.workflowId}...`);
         }
-        const traceData = await this.getTrace(args.workflowId);
+        const traceData = await getTrace(args.workflowId);
         // Output based on format
         if (isJsonFormat) {
             this.outputJson(traceData);
@@ -38,19 +39,19 @@ export default class WorkflowDebug extends Command {
         // Display text format
         this.displayTextTrace(traceData);
     }
-    async getTrace(workflowId) {
-        const reader = new TraceReader();
-        const tracePath = await reader.findTraceFile(workflowId);
-        return reader.readTraceFile(tracePath);
-    }
     outputJson(data) {
         this.log(JSON.stringify(data, null, 2));
     }
     displayTextTrace(traceData) {
         this.log('\nTrace Log:');
         this.log('─'.repeat(80));
-        this.log(traceFormatter.displayDebugTree(traceData));
+        this.log(displayDebugTree(traceData));
         this.log('\n' + '─'.repeat(80));
-        this.log('Tip: Use --format json for complete verbose output');
+        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/generate.js

@@ -2,6 +2,7 @@ import { Args, Command, Flags, ux } from '@oclif/core';
 import { generateWorkflow } from '#services/workflow_generator.js';
 import { buildWorkflow, buildWorkflowInteractiveLoop } from '#services/workflow_builder.js';
 import { ensureOutputAIStructure } from '#services/coding_agents.js';
+import { getWorkflowGenerateSuccessMessage } from '#services/messages.js';
 import { DEFAULT_OUTPUT_DIRS } from '#utils/paths.js';
 import path from 'node:path';
 export default class Generate extends Command {
@@ -78,15 +79,7 @@ export default class Generate extends Command {
         }
     }
     displaySuccess(result) {
-        this.log(`\n[SUCCESS] Workflow "${result.workflowName}" created successfully!`);
-        this.log(`\nLocation: ${result.targetDir}`);
-        this.log('\n-- Next steps --');
-        this.log(`   1. cd ${result.targetDir}`);
-        this.log('   2. Edit the workflow files to customize your implementation');
-        this.log('   3. If using @output.ai/llm, configure your .env file with LLM provider credentials:');
-        this.log('      - ANTHROPIC_API_KEY for Claude');
-        this.log('      - OPENAI_API_KEY for OpenAI');
-        this.log('   4. Build and run with the worker');
-        this.log('\nCheck the README.md for workflow-specific documentation.');
+        const message = getWorkflowGenerateSuccessMessage(result.workflowName, result.targetDir, result.filesCreated);
+        this.log(message);
     }
 }

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

@@ -46,7 +46,8 @@ describe('Generate Command', () => {
                 skeleton: true,
                 force: false
             });
-            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[SUCCESS] Workflow "test-workflow" created successfully!'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('SUCCESS!'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('test-workflow'));
         });
         it('should require skeleton flag and reject without it', async () => {
             const cmd = createCommand();
@@ -105,9 +106,10 @@ describe('Generate Command', () => {
                 filesCreated: ['index.ts', 'steps.ts', 'types.ts']
             });
             await cmd.run();
-            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('[SUCCESS] Workflow "my-workflow" created successfully!'));
-            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Location: /custom/path/my-workflow'));
-            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('-- Next steps --'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('SUCCESS!'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('my-workflow'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('/custom/path/my-workflow'));
+            expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('NEXT STEPS'));
         });
     });
 });

package/dist/services/coding_agents.js

@@ -29,6 +29,21 @@ export const AGENT_CONFIGS = {
                 from: 'agents/workflow_planner.md.template',
                 to: `${AGENT_CONFIG_DIR}/agents/workflow_planner.md`
             },
+            {
+                type: 'template',
+                from: 'agents/workflow_quality.md.template',
+                to: `${AGENT_CONFIG_DIR}/agents/workflow_quality.md`
+            },
+            {
+                type: 'template',
+                from: 'agents/context_fetcher.md.template',
+                to: `${AGENT_CONFIG_DIR}/agents/context_fetcher.md`
+            },
+            {
+                type: 'template',
+                from: 'agents/prompt_writer.md.template',
+                to: `${AGENT_CONFIG_DIR}/agents/prompt_writer.md`
+            },
             {
                 type: 'template',
                 from: 'commands/plan_workflow.md.template',
@@ -65,6 +80,21 @@ export const AGENT_CONFIGS = {
                 from: `${AGENT_CONFIG_DIR}/agents/workflow_planner.md`,
                 to: '.claude/agents/workflow_planner.md'
             },
+            {
+                type: 'symlink',
+                from: `${AGENT_CONFIG_DIR}/agents/workflow_quality.md`,
+                to: '.claude/agents/workflow_quality.md'
+            },
+            {
+                type: 'symlink',
+                from: `${AGENT_CONFIG_DIR}/agents/context_fetcher.md`,
+                to: '.claude/agents/context_fetcher.md'
+            },
+            {
+                type: 'symlink',
+                from: `${AGENT_CONFIG_DIR}/agents/prompt_writer.md`,
+                to: '.claude/agents/prompt_writer.md'
+            },
             {
                 type: 'symlink',
                 from: `${AGENT_CONFIG_DIR}/commands/plan_workflow.md`,

package/dist/services/coding_agents.spec.js

@@ -39,11 +39,11 @@ describe('coding_agents service', () => {
             const expectedCount = AGENT_CONFIGS.outputai.mappings.length +
                 AGENT_CONFIGS['claude-code'].mappings.length;
             expect(files.length).toBe(expectedCount);
-            expect(files.length).toBe(10);
+            expect(files.length).toBe(16);
         });
         it('should have outputai files with .outputai prefix', () => {
             const files = getRequiredFiles();
-            const outputaiFiles = files.slice(0, 6);
+            const outputaiFiles = files.slice(0, 9);
             outputaiFiles.forEach(file => {
                 expect(file).toMatch(/^\.outputai\//);
             });
@@ -77,12 +77,18 @@ describe('coding_agents service', () => {
                 missingFiles: [
                     '.outputai/AGENTS.md',
                     '.outputai/agents/workflow_planner.md',
+                    '.outputai/agents/workflow_quality.md',
+                    '.outputai/agents/context_fetcher.md',
+                    '.outputai/agents/prompt_writer.md',
                     '.outputai/commands/plan_workflow.md',
                     '.outputai/commands/build_workflow.md',
                     '.outputai/meta/pre_flight.md',
                     '.outputai/meta/post_flight.md',
                     'CLAUDE.md',
                     '.claude/agents/workflow_planner.md',
+                    '.claude/agents/workflow_quality.md',
+                    '.claude/agents/context_fetcher.md',
+                    '.claude/agents/prompt_writer.md',
                     '.claude/commands/plan_workflow.md',
                     '.claude/commands/build_workflow.md'
                 ],
@@ -98,54 +104,21 @@ describe('coding_agents service', () => {
                 missingFiles: [],
                 isComplete: true
             });
-            expect(access).toHaveBeenCalledTimes(11); // dir + 6 outputai + 4 claude-code
+            expect(access).toHaveBeenCalledTimes(17); // dir + 9 outputai + 7 claude-code
         });
         it('should return missing files when some files do not exist', async () => {
-            const calls = [];
-            vi.mocked(access).mockImplementation(async () => {
-                const callNum = calls.length + 1;
-                calls.push(callNum);
-                // Call 1: directory exists
-                if (callNum === 1) {
-                    return undefined;
-                }
-                // Call 2: .outputai/AGENTS.md exists
-                if (callNum === 2) {
-                    return undefined;
-                }
-                // Call 3: .outputai/agents/workflow_planner.md missing
-                if (callNum === 3) {
-                    throw { code: 'ENOENT' };
-                }
-                // Call 4: .outputai/commands/plan_workflow.md exists
-                if (callNum === 4) {
-                    return undefined;
-                }
-                // Call 5: .outputai/commands/build_workflow.md exists
-                if (callNum === 5) {
-                    return undefined;
-                }
-                // Call 6: .outputai/meta/pre_flight.md exists
-                if (callNum === 6) {
-                    return undefined;
-                }
-                // Call 7: .outputai/meta/post_flight.md exists
-                if (callNum === 7) {
-                    return undefined;
-                }
-                // Call 8: CLAUDE.md exists
-                if (callNum === 8) {
-                    return undefined;
-                }
-                // Call 9: .claude/agents/workflow_planner.md missing
-                if (callNum === 9) {
-                    throw { code: 'ENOENT' };
-                }
-                // Call 10: .claude/commands/plan_workflow.md exists
-                if (callNum === 10) {
-                    return undefined;
+            const missingFiles = new Set([
+                '.outputai/agents/workflow_planner.md',
+                '.claude/agents/workflow_planner.md'
+            ]);
+            vi.mocked(access).mockImplementation(async (path) => {
+                const pathStr = path.toString();
+                // Check if this path ends with any of the missing files
+                for (const missing of missingFiles) {
+                    if (pathStr.endsWith(missing)) {
+                        throw { code: 'ENOENT' };
+                    }
                 }
-                // Call 11: .claude/commands/build_workflow.md exists
                 return undefined;
             });
             const result = await checkAgentStructure('/test/project');
@@ -159,18 +132,20 @@ describe('coding_agents service', () => {
             });
         });
         it('should check all required files even when directory exists', async () => {
-            vi.mocked(access)
-                .mockResolvedValueOnce(undefined) // directory
-                .mockResolvedValueOnce(undefined) // .outputai/AGENTS.md
-                .mockRejectedValueOnce({ code: 'ENOENT' }) // .outputai/agents/workflow_planner.md
-                .mockRejectedValueOnce({ code: 'ENOENT' }) // .outputai/commands/plan_workflow.md
-                .mockResolvedValueOnce(undefined) // .outputai/commands/build_workflow.md
-                .mockResolvedValueOnce(undefined) // .outputai/meta/pre_flight.md
-                .mockResolvedValueOnce(undefined) // .outputai/meta/post_flight.md
-                .mockResolvedValueOnce(undefined) // CLAUDE.md
-                .mockResolvedValueOnce(undefined) // .claude/agents/workflow_planner.md
-                .mockRejectedValueOnce({ code: 'ENOENT' }) // .claude/commands/plan_workflow.md
-                .mockResolvedValueOnce(undefined); // .claude/commands/build_workflow.md
+            const missingFiles = new Set([
+                '.outputai/agents/workflow_planner.md',
+                '.outputai/commands/plan_workflow.md',
+                '.claude/commands/plan_workflow.md'
+            ]);
+            vi.mocked(access).mockImplementation(async (path) => {
+                const pathStr = path.toString();
+                for (const missing of missingFiles) {
+                    if (pathStr.endsWith(missing)) {
+                        throw { code: 'ENOENT' };
+                    }
+                }
+                return undefined;
+            });
             const result = await checkAgentStructure('/test/project');
             expect(result.dirExists).toBe(true);
             expect(result.missingFiles).toEqual([
@@ -207,8 +182,8 @@ describe('coding_agents service', () => {
             });
             // Should create outputai files (6 templates)
             expect(fs.writeFile).toHaveBeenCalledWith(expect.stringContaining('AGENTS.md'), expect.any(String), 'utf-8');
-            // Should create symlinks (4 symlinks for claude-code)
-            expect(fs.symlink).toHaveBeenCalledTimes(4);
+            // Should create symlinks (7 symlinks for claude-code)
+            expect(fs.symlink).toHaveBeenCalledTimes(7);
         });
         it('should skip existing files when force is false', async () => {
             // Mock some files exist

package/dist/services/messages.d.ts

@@ -3,3 +3,4 @@
  */
 export declare const getEjectSuccessMessage: (destPath: string, outputFile: string, binName: string) => string;
 export declare const getProjectSuccessMessage: (folderName: string, installSuccess: boolean, envConfigured?: boolean) => string;
+export declare const getWorkflowGenerateSuccessMessage: (workflowName: string, targetDir: string, filesCreated: string[]) => string;

package/dist/services/messages.js

@@ -176,7 +176,7 @@ export const getProjectSuccessMessage = (folderName, installSuccess, envConfigur
         note: 'Launches Temporal, Redis, PostgreSQL, API, Worker, and UI'
     }, {
         step: 'Run example workflow',
-        command: 'output workflow run simple --input \'{"question": "who really is ada lovelace?"}\'',
+        command: 'output workflow run simple --input src/simple/scenarios/question_ada_lovelace.json',
         note: 'Execute in a new terminal after services are running'
     }, {
         step: 'Monitor workflows',
@@ -231,3 +231,67 @@ ${ux.colorize('dim', '         with AI assistance.')}
 ${ux.colorize('green', ux.colorize('bold', 'Happy building with Output SDK! 🚀'))}
 `;
 };
+export const getWorkflowGenerateSuccessMessage = (workflowName, targetDir, filesCreated) => {
+    const divider = ux.colorize('dim', '─'.repeat(80));
+    const bulletPoint = ux.colorize('green', '▸');
+    const formattedFiles = filesCreated.map(file => {
+        return `  ${bulletPoint} ${formatPath(file)}`;
+    }).join('\n');
+    const steps = [
+        {
+            step: 'Navigate to workflow directory',
+            command: `cd ${targetDir}`
+        },
+        {
+            step: 'Edit workflow files',
+            note: 'Customize workflow.ts, steps.ts, and prompts to match your requirements'
+        },
+        {
+            step: 'Configure environment',
+            command: 'Edit .env file',
+            note: 'Add your LLM provider credentials (ANTHROPIC_API_KEY or OPENAI_API_KEY)'
+        },
+        {
+            step: 'Test with example scenario',
+            command: `output workflow run ${workflowName} --input ${targetDir}/scenarios/test_input.json`,
+            note: 'Run after starting services with "output dev"'
+        }
+    ];
+    const formattedSteps = steps.map((item, index) => {
+        const stepNumber = ux.colorize('dim', `${index + 1}.`);
+        const stepText = ux.colorize('white', item.step);
+        const command = item.command ? `\n     ${bulletPoint} ${formatCommand(item.command)}` : '';
+        const note = item.note ? `\n     ${ux.colorize('dim', `  ${item.note}`)}` : '';
+        return `  ${stepNumber} ${stepText}${command}${note}`;
+    }).join('\n\n');
+    return `
+${divider}
+
+${ux.colorize('bold', ux.colorize('green', '✅ SUCCESS!'))} ${ux.colorize('bold', `Workflow "${workflowName}" created`)}
+
+${divider}
+
+${createSectionHeader('WORKFLOW DETAILS', '📁')}
+
+  ${bulletPoint} ${ux.colorize('white', 'Name:')} ${formatPath(workflowName)}
+  ${bulletPoint} ${ux.colorize('white', 'Location:')} ${formatPath(targetDir)}
+
+${divider}
+
+${createSectionHeader('FILES CREATED', '📄')}
+
+${formattedFiles}
+
+${divider}
+
+${createSectionHeader('NEXT STEPS', '🚀')}
+
+${formattedSteps}
+
+${divider}
+
+${ux.colorize('dim', '💡 Tip: Check the README.md in your workflow directory for detailed documentation.')}
+
+${ux.colorize('green', ux.colorize('bold', 'Happy building! 🛠️'))}
+`;
+};

package/dist/services/trace_reader.d.ts

@@ -1,15 +1,14 @@
-export declare class TraceReader {
-    /**
-     * Find trace file from workflow metadata
-     */
-    findTraceFile(workflowId: string): Promise<string>;
-    /**
-     * Read and parse trace file
-     */
-    readTraceFile(path: string): Promise<any>;
-    /**
-     * Check if a file exists
-     */
-    private fileExists;
-}
-export declare const traceReader: TraceReader;
+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>;