@output.ai/cli 0.7.13 → 0.7.14

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

@@ -29,6 +29,8 @@ export interface Workflow {
     name: string;
     /** The description of the workflow */
     description?: string;
+    /** Absolute path to the workflow file */
+    path?: string;
     inputSchema?: JSONSchema;
     outputSchema?: JSONSchema;
 }

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

@@ -5,6 +5,7 @@ interface WorkflowDisplay {
     description: string;
     inputs: string;
     outputs: string;
+    scenarios: string;
 }
 export declare function parseWorkflowForDisplay(workflow: Workflow): WorkflowDisplay;
 export default class WorkflowList extends Command {

package/dist/commands/workflow/list.js

@@ -3,6 +3,7 @@ import Table from 'cli-table3';
 import { getWorkflowCatalog } from '#api/generated/api.js';
 import { parseWorkflowDefinition, formatParameters } from '#api/parser.js';
 import { handleApiError } from '#utils/error_handler.js';
+import { listScenariosForWorkflow } from '#utils/scenario_resolver.js';
 const OUTPUT_FORMAT = {
     LIST: 'list',
     TABLE: 'table',
@@ -10,11 +11,13 @@ const OUTPUT_FORMAT = {
 };
 export function parseWorkflowForDisplay(workflow) {
     const parsed = parseWorkflowDefinition(workflow);
+    const scenarioNames = listScenariosForWorkflow(workflow.name, workflow.path);
     return {
         name: parsed.name,
         description: parsed.description || 'No description',
         inputs: formatParameters(parsed.inputs),
-        outputs: formatParameters(parsed.outputs)
+        outputs: formatParameters(parsed.outputs),
+        scenarios: scenarioNames.length > 0 ? scenarioNames.join(', ') : 'none'
     };
 }
 function caseInsensitiveIncludes(str, filter) {
@@ -35,8 +38,8 @@ function sortWorkflowsByName(workflows) {
 }
 function createWorkflowTable(workflows, detailed) {
     const table = new Table({
-        head: ['Name', 'Description', 'Inputs', 'Outputs'],
-        colWidths: detailed ? [25, 40, 40, 40] : [20, 30, 25, 25],
+        head: ['Name', 'Description', 'Inputs', 'Outputs', 'Scenarios'],
+        colWidths: detailed ? [30, 42, 42, 42, 60] : [24, 30, 24, 24, 48],
         wordWrap: true,
         style: {
             head: ['cyan']
@@ -48,17 +51,11 @@ function createWorkflowTable(workflows, detailed) {
         if (detailed) {
             const inputs = display.inputs.split(', ').join('\n');
             const outputs = display.outputs.split(', ').join('\n');
-            table.push([display.name, display.description, inputs, outputs]);
+            const scenarios = display.scenarios.split(', ').join('\n');
+            table.push([display.name, display.description, inputs, outputs, scenarios]);
         }
         else {
-            const maxLen = 22;
-            const inputs = display.inputs.length > maxLen ?
-                display.inputs.substring(0, maxLen) + '...' :
-                display.inputs;
-            const outputs = display.outputs.length > maxLen ?
-                display.outputs.substring(0, maxLen) + '...' :
-                display.outputs;
-            table.push([display.name, display.description, inputs, outputs]);
+            table.push([display.name, display.description, display.inputs, display.outputs, display.scenarios]);
         }
     });
     return table.toString();
@@ -77,6 +74,7 @@ function formatWorkflowsAsJson(workflows) {
                 description: display.description,
                 inputs: display.inputs.split(', '),
                 outputs: display.outputs.split(', '),
+                scenarios: display.scenarios === 'none' ? [] : display.scenarios.split(', '),
                 raw: w
             };
         })

package/dist/commands/workflow/{list.test.js → list.spec.js}

@@ -1,4 +1,8 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+const mockListScenarios = vi.fn().mockReturnValue([]);
+vi.mock('#utils/scenario_resolver.js', () => ({
+    listScenariosForWorkflow: mockListScenarios
+}));
 describe('workflow list command', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -47,6 +51,7 @@ describe('workflow list parsing', () => {
         expect(parsed.inputs).toContain('message: string');
         expect(parsed.inputs).toContain('count: number?');
         expect(parsed.outputs).toContain('result: string?');
+        expect(parsed.scenarios).toBe('none');
     });
     it('should handle workflows without schemas', async () => {
         const { parseWorkflowForDisplay } = await import('./list.js');
@@ -58,6 +63,17 @@ describe('workflow list parsing', () => {
         expect(parsed.name).toBe('simple-workflow');
         expect(parsed.inputs).toBe('none');
         expect(parsed.outputs).toBe('none');
+        expect(parsed.scenarios).toBe('none');
+    });
+    it('should include scenario names when scenarios exist', async () => {
+        mockListScenarios.mockReturnValueOnce(['basic', 'advanced', 'stress_test']);
+        const { parseWorkflowForDisplay } = await import('./list.js');
+        const mockWorkflow = {
+            name: 'workflow-with-scenarios',
+            description: 'Has scenarios'
+        };
+        const parsed = parseWorkflowForDisplay(mockWorkflow);
+        expect(parsed.scenarios).toBe('basic, advanced, stress_test');
     });
     it('should format nested parameters correctly', async () => {
         const { parseWorkflowForDisplay } = await import('./list.js');

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

@@ -4,9 +4,10 @@ export default class WorkflowRun extends Command {
     static examples: string[];
     static args: {
         workflowName: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        scenario: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
-        input: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        input: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'task-queue': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         format: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
     };

package/dist/commands/workflow/run.js

@@ -1,28 +1,33 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { postWorkflowRun } from '#api/generated/api.js';
 import { OUTPUT_FORMAT } from '#utils/constants.js';
-import { parseInputFlag } from '#utils/input_parser.js';
 import { formatOutput } from '#utils/output_formatter.js';
 import { handleApiError } from '#utils/error_handler.js';
+import { resolveInput } from '#utils/resolve_input.js';
 export default class WorkflowRun extends Command {
     static description = 'Execute a workflow synchronously and wait for completion';
     static examples = [
+        '<%= config.bin %> <%= command.id %> simple basic_input',
+        '<%= config.bin %> <%= command.id %> simple my_scenario --format json',
         '<%= config.bin %> <%= command.id %> simple --input \'{"values":[1,2,3]}\'',
         '<%= config.bin %> <%= command.id %> simple --input input.json',
-        '<%= config.bin %> <%= command.id %> simple --input \'{"key":"value"}\' --format json',
         '<%= config.bin %> <%= command.id %> simple --input \'{"key":"value"}\' --task-queue my-queue'
     ];
     static args = {
         workflowName: Args.string({
             description: 'Name of the workflow to execute',
             required: true
+        }),
+        scenario: Args.string({
+            description: 'Scenario name (resolved from the workflow\'s scenarios/ directory)',
+            required: false
         })
     };
     static flags = {
         input: Flags.string({
             char: 'i',
-            description: 'Workflow input as JSON string or file path',
-            required: true
+            description: 'Workflow input as JSON string or file path (overrides scenario)',
+            required: false
         }),
         'task-queue': Flags.string({
             char: 'q',
@@ -37,7 +42,7 @@ export default class WorkflowRun extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowRun);
-        const input = parseInputFlag(flags.input);
+        const input = await resolveInput(args.workflowName, args.scenario, flags.input, 'run');
         this.log(`Executing workflow: ${args.workflowName}...`);
         const response = await postWorkflowRun({
             workflowName: args.workflowName,

package/dist/commands/workflow/{run.test.js → run.spec.js}

@@ -20,7 +20,12 @@ describe('workflow run command', () => {
             const WorkflowRun = (await import('./run.js')).default;
             expect(WorkflowRun.flags.format.options).toEqual(['json', 'text']);
             expect(WorkflowRun.flags.format.default).toBe('text');
-            expect(WorkflowRun.flags.input.required).toBe(true);
+            expect(WorkflowRun.flags.input.required).toBe(false);
+        });
+        it('should have optional scenario argument', async () => {
+            const WorkflowRun = (await import('./run.js')).default;
+            expect(WorkflowRun.args).toHaveProperty('scenario');
+            expect(WorkflowRun.args.scenario.required).toBe(false);
         });
     });
 });

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

@@ -4,9 +4,10 @@ export default class WorkflowStart extends Command {
     static examples: string[];
     static args: {
         workflowName: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        scenario: import("@oclif/core/lib/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static flags: {
-        input: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        input: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'task-queue': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;

package/dist/commands/workflow/start.js

@@ -1,10 +1,11 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { postWorkflowStart } from '#api/generated/api.js';
-import { parseInputFlag } from '#utils/input_parser.js';
 import { handleApiError } from '#utils/error_handler.js';
+import { resolveInput } from '#utils/resolve_input.js';
 export default class WorkflowStart extends Command {
     static description = 'Start a workflow asynchronously without waiting for completion';
     static examples = [
+        '<%= config.bin %> <%= command.id %> simple basic_input',
         '<%= config.bin %> <%= command.id %> simple --input \'{"values":[1,2,3]}\'',
         '<%= config.bin %> <%= command.id %> simple --input input.json',
         '<%= config.bin %> <%= command.id %> simple --input \'{"key":"value"}\' --task-queue my-queue'
@@ -13,13 +14,17 @@ export default class WorkflowStart extends Command {
         workflowName: Args.string({
             description: 'Name of the workflow to start',
             required: true
+        }),
+        scenario: Args.string({
+            description: 'Scenario name (resolved from the workflow\'s scenarios/ directory)',
+            required: false
         })
     };
     static flags = {
         input: Flags.string({
             char: 'i',
-            description: 'Workflow input as JSON string or file path',
-            required: true
+            description: 'Workflow input as JSON string or file path (overrides scenario)',
+            required: false
         }),
         'task-queue': Flags.string({
             char: 'q',
@@ -28,7 +33,7 @@ export default class WorkflowStart extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowStart);
-        const input = parseInputFlag(flags.input);
+        const input = await resolveInput(args.workflowName, args.scenario, flags.input, 'start');
         this.log(`Starting workflow: ${args.workflowName}...`);
         const response = await postWorkflowStart({
             workflowName: args.workflowName,

package/dist/commands/workflow/{start.test.js → start.spec.js}

@@ -17,7 +17,12 @@ describe('workflow start command', () => {
         });
         it('should have correct flag configuration', async () => {
             const WorkflowStart = (await import('./start.js')).default;
-            expect(WorkflowStart.flags.input.required).toBe(true);
+            expect(WorkflowStart.flags.input.required).toBe(false);
+        });
+        it('should have optional scenario argument', async () => {
+            const WorkflowStart = (await import('./start.js')).default;
+            expect(WorkflowStart.args).toHaveProperty('scenario');
+            expect(WorkflowStart.args.scenario.required).toBe(false);
         });
     });
 });

package/dist/generated/sdk_versions.json

@@ -2,5 +2,5 @@
     "core": "0.3.2",
     "llm": "0.2.10",
     "http": "0.1.2",
-    "cli": "0.7.13"
+    "cli": "0.7.14"
 }

package/dist/services/messages.js

@@ -177,7 +177,7 @@ export const getProjectSuccessMessage = (folderName, installSuccess, envConfigur
         note: 'Launches Temporal, Redis, PostgreSQL, API, Worker, and UI'
     }, {
         step: 'Run example workflow',
-        command: 'npx output workflow run blog_evaluator --input src/workflows/blog_evaluator/scenarios/paulgraham_hwh.json',
+        command: 'npx output workflow run blog_evaluator paulgraham_hwh',
         note: 'Execute in a new terminal after services are running'
     }, {
         step: 'Monitor workflows',
@@ -321,7 +321,7 @@ ${createSectionHeader('RUN A WORKFLOW', '🚀')}
 
   ${ux.colorize('white', 'In a new terminal, execute:')}
 
-    ${formatCommand('npx output workflow run blog_evaluator --input src/workflows/blog_evaluator/scenarios/paulgraham_hwh.json')}
+    ${formatCommand('npx output workflow run blog_evaluator paulgraham_hwh')}
 
 ${divider}
 

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

@@ -81,7 +81,7 @@ This starts:
 In a new terminal:
 
 ```bash
-npx output workflow run blog_evaluator --input src/workflows/blog_evaluator/scenarios/paulgraham_hwh.json
+npx output workflow run blog_evaluator paulgraham_hwh
 ```
 
 ### 5. Stop Services

package/dist/utils/resolve_input.d.ts

@@ -0,0 +1 @@
+export declare function resolveInput(workflowName: string, scenario: string | undefined, inputFlag: string | undefined, commandName: string): Promise<unknown>;

package/dist/utils/resolve_input.js

@@ -0,0 +1,22 @@
+import { ux } from '@oclif/core';
+import { parseInputFlag } from '#utils/input_parser.js';
+import { resolveScenarioPath, getScenarioNotFoundMessage } from '#utils/scenario_resolver.js';
+export async function resolveInput(workflowName, scenario, inputFlag, commandName) {
+    if (inputFlag && scenario) {
+        return ux.error('Cannot use both scenario argument and --input flag. Choose one.', { exit: 1 });
+    }
+    if (inputFlag) {
+        return parseInputFlag(inputFlag);
+    }
+    if (scenario) {
+        const resolution = await resolveScenarioPath(workflowName, scenario);
+        if (!resolution.found) {
+            return ux.error(getScenarioNotFoundMessage(workflowName, scenario, resolution.searchedPaths), { exit: 1 });
+        }
+        ux.stdout(`Using scenario: ${resolution.path}\n`);
+        return parseInputFlag(resolution.path);
+    }
+    return ux.error('Input required. Provide either:\n' +
+        `  - A scenario name: output workflow ${commandName} <workflow> <scenario>\n` +
+        `  - An input flag: output workflow ${commandName} <workflow> --input <json-or-file>`, { exit: 1 });
+}

package/dist/utils/scenario_resolver.d.ts

@@ -0,0 +1,9 @@
+export interface ScenarioResolutionResult {
+    found: boolean;
+    path?: string;
+    searchedPaths: string[];
+}
+export declare function extractWorkflowRelativePath(path: string): string | null;
+export declare function resolveScenarioPath(workflowName: string, scenarioName: string, basePath?: string): Promise<ScenarioResolutionResult>;
+export declare function listScenariosForWorkflow(workflowName: string, workflowPath?: string, basePath?: string): string[];
+export declare function getScenarioNotFoundMessage(workflowName: string, scenarioName: string, searchedPaths: string[]): string;

package/dist/utils/scenario_resolver.js

@@ -0,0 +1,92 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getWorkflowCatalog } from '#api/generated/api.js';
+const SCENARIOS_DIR = 'scenarios';
+const WORKFLOWS_PATHS = ['src/workflows', 'workflows'];
+export function extractWorkflowRelativePath(path) {
+    const match = path.match(/workflows\/(.+)\/workflow\.[jt]s$/);
+    return match ? match[1] : null;
+}
+async function fetchWorkflowDirectory(workflowName) {
+    try {
+        const response = await getWorkflowCatalog();
+        const workflows = response?.data?.workflows;
+        if (!workflows) {
+            return null;
+        }
+        const workflow = workflows.find(w => w.name === workflowName);
+        if (!workflow) {
+            return null;
+        }
+        const workflowPath = workflow.path;
+        if (!workflowPath) {
+            return null;
+        }
+        return extractWorkflowRelativePath(workflowPath);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveScenarioFromDirectory(relativeDir, scenarioFileName, basePath) {
+    const searchedPaths = [];
+    for (const workflowsDir of WORKFLOWS_PATHS) {
+        const candidatePath = resolve(basePath, workflowsDir, relativeDir, SCENARIOS_DIR, scenarioFileName);
+        searchedPaths.push(candidatePath);
+        if (existsSync(candidatePath)) {
+            return { found: true, path: candidatePath, searchedPaths };
+        }
+    }
+    return { found: false, searchedPaths };
+}
+export async function resolveScenarioPath(workflowName, scenarioName, basePath = process.cwd()) {
+    const scenarioFileName = scenarioName.endsWith('.json') ?
+        scenarioName :
+        `${scenarioName}.json`;
+    const catalogDir = await fetchWorkflowDirectory(workflowName);
+    if (catalogDir) {
+        const result = resolveScenarioFromDirectory(catalogDir, scenarioFileName, basePath);
+        if (result.found) {
+            return result;
+        }
+        // Catalog resolved but scenario not found at that path — still try convention fallback
+        // in case the catalog path differs from local source layout
+        if (catalogDir !== workflowName) {
+            const fallback = resolveScenarioFromDirectory(workflowName, scenarioFileName, basePath);
+            return {
+                found: fallback.found,
+                path: fallback.path,
+                searchedPaths: [...result.searchedPaths, ...fallback.searchedPaths]
+            };
+        }
+        return result;
+    }
+    // API unavailable or workflow not in catalog — fall back to convention
+    return resolveScenarioFromDirectory(workflowName, scenarioFileName, basePath);
+}
+export function listScenariosForWorkflow(workflowName, workflowPath, basePath = process.cwd()) {
+    const relativeDir = (workflowPath && extractWorkflowRelativePath(workflowPath)) || workflowName;
+    for (const workflowsDir of WORKFLOWS_PATHS) {
+        const scenariosDir = resolve(basePath, workflowsDir, relativeDir, SCENARIOS_DIR);
+        if (existsSync(scenariosDir)) {
+            return readdirSync(scenariosDir)
+                .filter(f => f.endsWith('.json'))
+                .map(f => f.replace(/\.json$/, ''));
+        }
+    }
+    return [];
+}
+export function getScenarioNotFoundMessage(workflowName, scenarioName, searchedPaths) {
+    const pathsList = searchedPaths.map(p => `  - ${p}`).join('\n');
+    return [
+        `Scenario '${scenarioName}' not found for workflow '${workflowName}'.`,
+        '',
+        'Searched in:',
+        pathsList,
+        '',
+        'Tip: Create a scenario file in your workflow\'s scenarios/ directory.',
+        '',
+        'Or use --input to specify a custom path:',
+        `  output workflow run ${workflowName} --input /path/to/input.json`
+    ].join('\n');
+}

package/dist/utils/scenario_resolver.spec.d.ts

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

package/dist/utils/scenario_resolver.spec.js

@@ -0,0 +1,214 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { resolveScenarioPath, getScenarioNotFoundMessage, extractWorkflowRelativePath, listScenariosForWorkflow } from './scenario_resolver.js';
+import * as fs from 'node:fs';
+import * as api from '#api/generated/api.js';
+vi.mock('node:fs', () => ({
+    existsSync: vi.fn(),
+    readdirSync: vi.fn()
+}));
+vi.mock('#api/generated/api.js', () => ({
+    getWorkflowCatalog: vi.fn()
+}));
+function mockCatalog(workflows) {
+    vi.mocked(api.getWorkflowCatalog).mockResolvedValue({
+        data: { workflows },
+        status: 200,
+        headers: new Headers()
+    });
+}
+function mockCatalogFailure() {
+    vi.mocked(api.getWorkflowCatalog).mockRejectedValue(new Error('API unavailable'));
+}
+describe('extractWorkflowRelativePath', () => {
+    it('should extract relative path from workflow.js path', () => {
+        expect(extractWorkflowRelativePath('/app/dist/workflows/basic_research/workflow.js'))
+            .toBe('basic_research');
+    });
+    it('should extract nested relative path', () => {
+        expect(extractWorkflowRelativePath('/app/dist/workflows/viz_examples/01_simple_linear/workflow.js'))
+            .toBe('viz_examples/01_simple_linear');
+    });
+    it('should handle workflow.ts extension', () => {
+        expect(extractWorkflowRelativePath('/src/workflows/my_flow/workflow.ts'))
+            .toBe('my_flow');
+    });
+    it('should return null for non-matching paths', () => {
+        expect(extractWorkflowRelativePath('/app/dist/other/workflow.js')).toBeNull();
+        expect(extractWorkflowRelativePath('/app/dist/workflows/')).toBeNull();
+    });
+});
+describe('resolveScenarioPath', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('when API returns workflow with path', () => {
+        it('should resolve scenario using catalog path', async () => {
+            mockCatalog([{ name: 'my_workflow', path: '/app/dist/workflows/my_workflow/workflow.js' }]);
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('src/workflows/my_workflow/scenarios/test_scenario.json');
+            });
+            const result = await resolveScenarioPath('my_workflow', 'test_scenario', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('src/workflows/my_workflow/scenarios/test_scenario.json');
+        });
+        it('should resolve when workflow name differs from folder name', async () => {
+            mockCatalog([{ name: 'simpleLinear', path: '/app/dist/workflows/viz_examples/01_simple_linear/workflow.js' }]);
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('src/workflows/viz_examples/01_simple_linear/scenarios/basic.json');
+            });
+            const result = await resolveScenarioPath('simpleLinear', 'basic', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('src/workflows/viz_examples/01_simple_linear/scenarios/basic.json');
+        });
+        it('should handle nested workflow directories', async () => {
+            mockCatalog([{ name: 'deep_flow', path: '/app/dist/workflows/category/sub/deep_flow/workflow.js' }]);
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('src/workflows/category/sub/deep_flow/scenarios/test.json');
+            });
+            const result = await resolveScenarioPath('deep_flow', 'test', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('src/workflows/category/sub/deep_flow/scenarios/test.json');
+        });
+        it('should return not found when scenario file does not exist', async () => {
+            mockCatalog([{ name: 'my_workflow', path: '/app/dist/workflows/my_workflow/workflow.js' }]);
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            const result = await resolveScenarioPath('my_workflow', 'missing', '/project');
+            expect(result.found).toBe(false);
+            expect(result.searchedPaths.length).toBeGreaterThanOrEqual(2);
+        });
+        it('should fall back to convention when catalog path has no scenario but convention does', async () => {
+            mockCatalog([{ name: 'renamedFlow', path: '/app/dist/workflows/actual_folder/workflow.js' }]);
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                // Not found at catalog-resolved path, but found at convention path
+                return String(path).includes('src/workflows/renamedFlow/scenarios/test.json');
+            });
+            const result = await resolveScenarioPath('renamedFlow', 'test', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('src/workflows/renamedFlow/scenarios/test.json');
+        });
+    });
+    describe('when API is unavailable', () => {
+        it('should fall back to convention-based lookup', async () => {
+            mockCatalogFailure();
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('src/workflows/my_workflow/scenarios/test_scenario.json');
+            });
+            const result = await resolveScenarioPath('my_workflow', 'test_scenario', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('src/workflows/my_workflow/scenarios/test_scenario.json');
+        });
+    });
+    describe('when workflow is not in catalog', () => {
+        it('should fall back to convention-based lookup', async () => {
+            mockCatalog([{ name: 'other_workflow', path: '/app/dist/workflows/other/workflow.js' }]);
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('src/workflows/my_workflow/scenarios/test.json');
+            });
+            const result = await resolveScenarioPath('my_workflow', 'test', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('src/workflows/my_workflow/scenarios/test.json');
+        });
+    });
+    describe('json extension normalization', () => {
+        it('should handle scenario name with .json extension', async () => {
+            mockCatalogFailure();
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('src/workflows/my_workflow/scenarios/test_scenario.json');
+            });
+            const result = await resolveScenarioPath('my_workflow', 'test_scenario.json', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('test_scenario.json');
+            expect(result.path).not.toContain('test_scenario.json.json');
+        });
+    });
+    describe('workflows fallback directory', () => {
+        it('should find scenario in workflows/ fallback path', async () => {
+            mockCatalogFailure();
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('workflows/my_workflow/scenarios/test_scenario.json') &&
+                    !String(path).includes('src/workflows');
+            });
+            const result = await resolveScenarioPath('my_workflow', 'test_scenario', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('workflows/my_workflow/scenarios/test_scenario.json');
+        });
+    });
+    describe('subdirectory scenarios', () => {
+        it('should support subdirectory paths in scenario name', async () => {
+            mockCatalogFailure();
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path).includes('src/workflows/my_workflow/scenarios/complex/deep_test.json');
+            });
+            const result = await resolveScenarioPath('my_workflow', 'complex/deep_test', '/project');
+            expect(result.found).toBe(true);
+            expect(result.path).toContain('complex/deep_test.json');
+        });
+    });
+});
+describe('listScenariosForWorkflow', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    it('should return scenario names from scenarios directory', () => {
+        vi.mocked(fs.existsSync).mockImplementation(path => String(path).includes('src/workflows/my_workflow/scenarios'));
+        vi.mocked(fs.readdirSync).mockReturnValue(['basic.json', 'advanced.json', 'README.md']);
+        const result = listScenariosForWorkflow('my_workflow', undefined, '/project');
+        expect(result).toEqual(['basic', 'advanced']);
+    });
+    it('should use workflowPath from catalog to derive directory', () => {
+        vi.mocked(fs.existsSync).mockImplementation(path => String(path).includes('src/workflows/viz_examples/01_simple_linear/scenarios'));
+        vi.mocked(fs.readdirSync).mockReturnValue(['test.json']);
+        const result = listScenariosForWorkflow('simpleLinear', '/app/dist/workflows/viz_examples/01_simple_linear/workflow.js', '/project');
+        expect(result).toEqual(['test']);
+    });
+    it('should fall back to workflowName when workflowPath is undefined', () => {
+        vi.mocked(fs.existsSync).mockImplementation(path => String(path).includes('src/workflows/my_workflow/scenarios'));
+        vi.mocked(fs.readdirSync).mockReturnValue(['scenario_a.json']);
+        const result = listScenariosForWorkflow('my_workflow', undefined, '/project');
+        expect(result).toEqual(['scenario_a']);
+    });
+    it('should fall back to workflowName when path extraction returns null', () => {
+        vi.mocked(fs.existsSync).mockImplementation(path => String(path).includes('src/workflows/my_workflow/scenarios'));
+        vi.mocked(fs.readdirSync).mockReturnValue(['test.json']);
+        const result = listScenariosForWorkflow('my_workflow', '/invalid/path.js', '/project');
+        expect(result).toEqual(['test']);
+    });
+    it('should return empty array when no scenarios directory exists', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        const result = listScenariosForWorkflow('my_workflow', undefined, '/project');
+        expect(result).toEqual([]);
+    });
+    it('should try workflows/ fallback when src/workflows/ does not exist', () => {
+        vi.mocked(fs.existsSync).mockImplementation(path => {
+            const p = String(path);
+            return p.includes('workflows/my_workflow/scenarios') && !p.includes('src/workflows');
+        });
+        vi.mocked(fs.readdirSync).mockReturnValue(['fallback.json']);
+        const result = listScenariosForWorkflow('my_workflow', undefined, '/project');
+        expect(result).toEqual(['fallback']);
+    });
+    it('should return empty array for empty scenarios directory', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readdirSync).mockReturnValue([]);
+        const result = listScenariosForWorkflow('my_workflow', undefined, '/project');
+        expect(result).toEqual([]);
+    });
+});
+describe('getScenarioNotFoundMessage', () => {
+    it('should return a helpful error message', () => {
+        const searchedPaths = [
+            '/project/src/workflows/my_workflow/scenarios/test.json',
+            '/project/workflows/my_workflow/scenarios/test.json'
+        ];
+        const message = getScenarioNotFoundMessage('my_workflow', 'test', searchedPaths);
+        expect(message).toContain('Scenario \'test\' not found for workflow \'my_workflow\'');
+        expect(message).toContain('Searched in:');
+        expect(message).toContain(searchedPaths[0]);
+        expect(message).toContain(searchedPaths[1]);
+        expect(message).toContain('Tip:');
+        expect(message).toContain('--input');
+    });
+});

package/package.json

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