@outputai/cli 0.3.3-next.b4a190e.0 → 0.3.3-next.e8eff63.0

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

@@ -77,7 +77,7 @@ services:
         condition: service_healthy
       worker:
         condition: service_healthy
-    image: outputai/api:${OUTPUT_API_VERSION:-0.3.3-next.b4a190e.0}
+    image: outputai/api:${OUTPUT_API_VERSION:-0.3.3-next.e8eff63.0}
     init: true
     networks:
       - main

package/dist/commands/dev/index.js

@@ -64,7 +64,11 @@ export default class Dev extends Command {
             this.log('✅ Services started. Run `output dev` without --detached to monitor status.\n');
             return;
         }
+        const state = {
+            cleaningUp: false
+        };
         const cleanup = async () => {
+            state.cleaningUp = true;
             this.log('\n');
             if (this.dockerProcess) {
                 this.dockerProcess.kill('SIGTERM');
@@ -115,18 +119,34 @@ export default class Dev extends Command {
         process.on('SIGINT', handleSignal);
         process.on('SIGTERM', handleSignal);
         try {
-            const { process: dockerProc } = await startDockerCompose(dockerComposePath, pullPolicy);
-            this.dockerProcess = dockerProc;
             enterAltScreen();
             const instance = render(React.createElement(DevApp, { dockerComposePath, onCleanup: cleanup }), { exitOnCtrlC: false });
             instanceRef.current = instance;
-            dockerProc.on('error', error => {
-                instance.unmount(new Error(`Docker process error: ${getErrorMessage(error)}`));
+            const dockerProc = await startDockerCompose({
+                dockerComposePath,
+                pullPolicy,
+                onError: error => {
+                    instance.unmount(new Error(`Docker process error: ${getErrorMessage(error)}`));
+                },
+                onExit: (code, signal, output) => {
+                    if (state.cleaningUp) {
+                        return;
+                    }
+                    if (code === 0) {
+                        instance.unmount();
+                        return;
+                    }
+                    const exitReason = signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`;
+                    const detail = output ? `\n\nRecent Docker output:\n${output}` : '';
+                    instance.unmount(new Error(`Docker compose exited with ${exitReason}.${detail}`));
+                }
             });
+            this.dockerProcess = dockerProc;
             await instance.waitUntilExit();
             exitAltScreenOnce();
         }
         catch (error) {
+            instanceRef.current?.unmount();
             exitAltScreenOnce();
             this.error(getErrorMessage(error), { exit: 1 });
         }

package/dist/commands/dev/index.spec.js

@@ -1,6 +1,8 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import React from 'react';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import fs from 'node:fs/promises';
+import { render } from 'ink';
 import * as dockerService from '#services/docker.js';
 import * as codingAgentsService from '#services/coding_agents.js';
 import Dev from './index.js';
@@ -45,13 +47,36 @@ vi.mock('#views/dev/dev_app.js', () => ({
     DevApp: () => null
 }));
 const createMockDockerProcess = () => ({
-    process: {
-        on: vi.fn(),
-        kill: vi.fn(),
-        stdout: { on: vi.fn() },
-        stderr: { on: vi.fn() }
-    }
+    on: vi.fn(),
+    kill: vi.fn(),
+    stdout: { on: vi.fn() },
+    stderr: { on: vi.fn() }
 });
+const getStartDockerComposeOptions = () => {
+    const options = vi.mocked(dockerService.startDockerCompose).mock.calls.at(-1)?.[0];
+    if (!options) {
+        throw new Error('Expected startDockerCompose to receive options');
+    }
+    return options;
+};
+const createControllableInkInstance = () => {
+    const deferred = {};
+    deferred.promise = new Promise((resolve, reject) => {
+        deferred.resolve = resolve;
+        deferred.reject = reject;
+    });
+    const instance = {
+        waitUntilExit: vi.fn(() => deferred.promise),
+        unmount: vi.fn((error) => {
+            if (error) {
+                deferred.reject(error);
+                return;
+            }
+            deferred.resolve();
+        })
+    };
+    return instance;
+};
 describe('dev command', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -182,8 +207,12 @@ describe('dev command', () => {
             const runPromise = cmd.run();
             // Wait a tick for startDockerCompose to be called
             await new Promise(resolve => setImmediate(resolve));
-            expect(dockerService.startDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', 'always' // default pull policy
-            );
+            expect(dockerService.startDockerCompose).toHaveBeenCalledWith(expect.objectContaining({
+                dockerComposePath: '/path/to/docker-compose-dev.yml',
+                pullPolicy: 'always',
+                onError: expect.any(Function),
+                onExit: expect.any(Function)
+            }));
             // Cancel the promise (it will be rejected but we don't care)
             runPromise.catch(() => { });
         });
@@ -207,6 +236,53 @@ describe('dev command', () => {
             await cmd.run();
             expect(cmd.error).toHaveBeenCalledWith('Docker error', { exit: 1 });
         });
+        it('should surface docker compose exit failures with recent output', async () => {
+            const dockerProcess = createMockDockerProcess();
+            vi.mocked(dockerService.startDockerCompose).mockResolvedValue(dockerProcess);
+            const inkInstance = createControllableInkInstance();
+            vi.mocked(render).mockReturnValue(inkInstance);
+            const cmd = new Dev([], {});
+            cmd.log = vi.fn();
+            cmd.error = vi.fn();
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({ flags: { 'compose-file': undefined, 'image-pull-policy': 'always' }, args: {} }),
+                configurable: true
+            });
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            getStartDockerComposeOptions().onExit?.(1, null, 'failed to bind host port');
+            await runPromise;
+            expect(inkInstance.unmount).toHaveBeenCalledWith(expect.objectContaining({
+                message: expect.stringContaining('Docker compose exited with code 1')
+            }));
+            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('Recent Docker output:\nfailed to bind host port'), { exit: 1 });
+        });
+        it('should ignore docker compose exits triggered by cleanup', async () => {
+            const dockerProcess = createMockDockerProcess();
+            vi.mocked(dockerService.startDockerCompose).mockResolvedValue(dockerProcess);
+            const inkInstance = createControllableInkInstance();
+            vi.mocked(render).mockReturnValue(inkInstance);
+            const cmd = new Dev([], {});
+            cmd.log = vi.fn();
+            cmd.error = vi.fn();
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({ flags: { 'compose-file': undefined, 'image-pull-policy': 'always' }, args: {} }),
+                configurable: true
+            });
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            const appElement = vi.mocked(render).mock.calls[0]?.[0];
+            if (!React.isValidElement(appElement)) {
+                throw new Error('Expected render to receive a React element');
+            }
+            const appProps = appElement.props;
+            await appProps.onCleanup();
+            getStartDockerComposeOptions().onExit?.(null, 'SIGTERM', 'compose stopped');
+            inkInstance.unmount();
+            await runPromise;
+            expect(inkInstance.unmount).not.toHaveBeenCalledWith(expect.any(Error));
+            expect(cmd.error).not.toHaveBeenCalled();
+        });
     });
     describe('image pull policy', () => {
         it('should pass pull policy to startDockerCompose', async () => {
@@ -222,7 +298,12 @@ describe('dev command', () => {
             const runPromise = cmd.run();
             // Wait a tick for startDockerCompose to be called
             await new Promise(resolve => setImmediate(resolve));
-            expect(dockerService.startDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', 'missing');
+            expect(dockerService.startDockerCompose).toHaveBeenCalledWith(expect.objectContaining({
+                dockerComposePath: '/path/to/docker-compose-dev.yml',
+                pullPolicy: 'missing',
+                onError: expect.any(Function),
+                onExit: expect.any(Function)
+            }));
             // Cancel the promise (it will be rejected but we don't care)
             runPromise.catch(() => { });
         });
@@ -239,7 +320,12 @@ describe('dev command', () => {
             const runPromise = cmd.run();
             // Wait a tick for startDockerCompose to be called
             await new Promise(resolve => setImmediate(resolve));
-            expect(dockerService.startDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', 'never');
+            expect(dockerService.startDockerCompose).toHaveBeenCalledWith(expect.objectContaining({
+                dockerComposePath: '/path/to/docker-compose-dev.yml',
+                pullPolicy: 'never',
+                onError: expect.any(Function),
+                onExit: expect.any(Function)
+            }));
             // Cancel the promise (it will be rejected but we don't care)
             runPromise.catch(() => { });
         });

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.3.3-next.b4a190e.0"
+    "framework": "0.3.3-next.e8eff63.0"
 }

package/dist/services/docker.d.ts

@@ -7,6 +7,7 @@ export declare const SERVICE_HEALTH: {
 };
 export declare const SERVICE_STATE: {
     readonly RUNNING: "running";
+    readonly CREATED: "created";
     readonly EXITED: "exited";
 };
 declare class DockerValidationError extends Error {
@@ -28,11 +29,16 @@ export declare function getServiceStatus(dockerComposePath: string): Promise<Ser
 export declare function isServiceHealthy(service: ServiceStatus): boolean;
 export declare function isServiceFailed(service: ServiceStatus): boolean;
 export declare function waitForServicesHealthy(dockerComposePath: string, timeoutMs?: number, pollIntervalMs?: number): Promise<void>;
-export interface DockerComposeProcess {
-    process: ChildProcess;
+export interface DockerComposeHandlers {
+    onError?: (error: Error, output: string) => void;
+    onExit?: (code: number | null, signal: NodeJS.Signals | null, output: string) => void;
 }
 export type PullPolicy = 'always' | 'missing' | 'never';
-export declare function startDockerCompose(dockerComposePath: string, pullPolicy?: PullPolicy): Promise<DockerComposeProcess>;
+export interface StartDockerComposeOptions extends DockerComposeHandlers {
+    dockerComposePath: string;
+    pullPolicy?: PullPolicy;
+}
+export declare function startDockerCompose({ dockerComposePath, pullPolicy, onError, onExit }: StartDockerComposeOptions): Promise<ChildProcess>;
 export declare function startDockerComposeDetached(dockerComposePath: string, pullPolicy?: PullPolicy): void;
 export declare function stopDockerCompose(dockerComposePath: string): Promise<void>;
 export { isDockerInstalled, DockerValidationError };

package/dist/services/docker.js

@@ -13,6 +13,7 @@ export const SERVICE_HEALTH = {
 };
 export const SERVICE_STATE = {
     RUNNING: 'running',
+    CREATED: 'created',
     EXITED: 'exited'
 };
 class DockerValidationError extends Error {
@@ -101,11 +102,17 @@ export function parseServiceStatus(jsonOutput) {
     });
 }
 export async function getServiceStatus(dockerComposePath) {
-    const result = execFileSync('docker', ['compose', '-f', dockerComposePath, '--project-name', config.dockerServiceName, 'ps', '--all', '--format', 'json'], { encoding: 'utf-8', cwd: process.cwd() });
+    const result = execFileSync('docker', [
+        'compose',
+        '-f', dockerComposePath,
+        '--project-directory', process.cwd(),
+        '--project-name', config.dockerServiceName,
+        'ps', '--all', '--format', 'json'
+    ], { encoding: 'utf-8', cwd: process.cwd() });
     return parseServiceStatus(result);
 }
 export function isServiceHealthy(service) {
-    return service.state !== SERVICE_STATE.EXITED &&
+    return service.state === SERVICE_STATE.RUNNING &&
         (service.health === SERVICE_HEALTH.HEALTHY || service.health === SERVICE_HEALTH.NONE);
 }
 export function isServiceFailed(service) {
@@ -122,7 +129,7 @@ export async function waitForServicesHealthy(dockerComposePath, timeoutMs = 1200
     }
     throw new Error('Timeout waiting for services to become healthy');
 }
-export async function startDockerCompose(dockerComposePath, pullPolicy) {
+export async function startDockerCompose({ dockerComposePath, pullPolicy, onError, onExit }) {
     const args = [
         'compose',
         '-f', dockerComposePath,
@@ -133,11 +140,27 @@ export async function startDockerCompose(dockerComposePath, pullPolicy) {
     if (pullPolicy) {
         args.push('--pull', pullPolicy);
     }
+    const output = {
+        value: ''
+    };
+    const appendOutput = (chunk) => {
+        output.value = `${output.value}${chunk.toString()}`.slice(-20000).trimStart();
+    };
     const dockerProcess = spawn('docker', args, {
         cwd: process.cwd(),
+        // The Ink dev UI owns the terminal. Drain compose output so Docker cannot
+        // block on a full pipe, while keeping recent output for startup failures.
         stdio: ['ignore', 'pipe', 'pipe']
     });
-    return { process: dockerProcess };
+    dockerProcess.stdout?.on('data', appendOutput);
+    dockerProcess.stderr?.on('data', appendOutput);
+    if (onError) {
+        dockerProcess.on('error', error => onError(error, output.value.trimEnd()));
+    }
+    if (onExit) {
+        dockerProcess.on('exit', (code, signal) => onExit(code, signal, output.value.trimEnd()));
+    }
+    return dockerProcess;
 }
 export function startDockerComposeDetached(dockerComposePath, pullPolicy) {
     const args = [

package/dist/services/docker.spec.js

@@ -6,6 +6,7 @@ vi.mock('node:child_process', () => ({
     execFileSync: vi.fn(),
     spawn: vi.fn()
 }));
+const mockChildProcess = (process) => process;
 vi.mock('log-update', () => {
     const fn = vi.fn();
     fn.done = vi.fn();
@@ -14,6 +15,11 @@ vi.mock('log-update', () => {
 describe('docker service', () => {
     beforeEach(() => {
         vi.clearAllMocks();
+        vi.mocked(spawn).mockReturnValue(mockChildProcess({
+            on: vi.fn(),
+            stdout: { on: vi.fn() },
+            stderr: { on: vi.fn() }
+        }));
     });
     afterEach(() => {
         vi.restoreAllMocks();
@@ -73,7 +79,12 @@ describe('docker service', () => {
             const mockOutput = '{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}';
             vi.mocked(execFileSync).mockReturnValue(mockOutput);
             await getServiceStatus('/path/to/docker-compose.yml');
-            expect(execFileSync).toHaveBeenCalledWith('docker', ['compose', '-f', '/path/to/docker-compose.yml', '--project-name', 'output-sdk', 'ps', '--all', '--format', 'json'], expect.objectContaining({ encoding: 'utf-8' }));
+            expect(execFileSync).toHaveBeenCalledWith('docker', [
+                'compose', '-f', '/path/to/docker-compose.yml',
+                '--project-directory', process.cwd(),
+                '--project-name', 'output-sdk',
+                'ps', '--all', '--format', 'json'
+            ], expect.objectContaining({ encoding: 'utf-8' }));
         });
         it('should return parsed service status', async () => {
             const mockOutput = '{"Service":"redis","State":"running","Health":"healthy","Publishers":[{"PublishedPort":6379,"TargetPort":6379}]}';
@@ -91,7 +102,7 @@ describe('docker service', () => {
     });
     describe('startDockerCompose', () => {
         it('should pass --project-name to docker compose up', async () => {
-            await startDockerCompose('/path/to/docker-compose.yml');
+            await startDockerCompose({ dockerComposePath: '/path/to/docker-compose.yml' });
             expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
@@ -100,7 +111,7 @@ describe('docker service', () => {
             ], expect.objectContaining({ stdio: ['ignore', 'pipe', 'pipe'], cwd: process.cwd() }));
         });
         it('should append --pull when pullPolicy is provided', async () => {
-            await startDockerCompose('/path/to/docker-compose.yml', 'always');
+            await startDockerCompose({ dockerComposePath: '/path/to/docker-compose.yml', pullPolicy: 'always' });
             expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
@@ -108,6 +119,51 @@ describe('docker service', () => {
                 'up', '--pull', 'always'
             ], expect.objectContaining({ stdio: ['ignore', 'pipe', 'pipe'], cwd: process.cwd() }));
         });
+        it('should attach docker process handlers and pass captured output', async () => {
+            const onError = vi.fn();
+            const onExit = vi.fn();
+            const processHandlers = {};
+            const streamHandlers = {};
+            const process = {
+                on: vi.fn((event, handler) => {
+                    if (event === 'error') {
+                        processHandlers.error = handler;
+                    }
+                    else {
+                        processHandlers.exit = handler;
+                    }
+                    return process;
+                }),
+                stdout: {
+                    on: vi.fn((event, handler) => {
+                        streamHandlers.stdout = handler;
+                        return process.stdout;
+                    })
+                },
+                stderr: {
+                    on: vi.fn((event, handler) => {
+                        streamHandlers.stderr = handler;
+                        return process.stderr;
+                    })
+                }
+            };
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(process));
+            const dockerProcess = await startDockerCompose({
+                dockerComposePath: '/path/to/docker-compose.yml',
+                pullPolicy: 'always',
+                onError,
+                onExit
+            });
+            expect(dockerProcess.on).toHaveBeenCalledWith('error', expect.any(Function));
+            expect(dockerProcess.on).toHaveBeenCalledWith('exit', expect.any(Function));
+            streamHandlers.stdout?.(Buffer.from('starting services\n'));
+            streamHandlers.stderr?.(Buffer.from('compose failed\n'));
+            const error = new Error('Docker failed');
+            processHandlers.error?.(error);
+            processHandlers.exit?.(1, null);
+            expect(onError).toHaveBeenCalledWith(error, 'starting services\ncompose failed');
+            expect(onExit).toHaveBeenCalledWith(1, null, 'starting services\ncompose failed');
+        });
     });
     describe('startDockerComposeDetached', () => {
         it('should pass --project-name and -d to docker compose up', () => {
@@ -176,6 +232,9 @@ describe('docker service', () => {
         it('should return false for an exited service with health: unhealthy', () => {
             expect(isServiceHealthy({ name: 'worker', state: 'exited', health: 'unhealthy', ports: [] })).toBe(false);
         });
+        it('should return false for a created service with no health check', () => {
+            expect(isServiceHealthy({ name: 'api', state: 'created', health: 'none', ports: [] })).toBe(false);
+        });
         it('should return false for a service with health: starting', () => {
             expect(isServiceHealthy({ name: 'temporal', state: 'running', health: 'starting', ports: [] })).toBe(false);
         });

package/dist/utils/scenario_resolver.d.ts

@@ -4,6 +4,7 @@ export interface ScenarioResolutionResult {
     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 findWorkflowDirectoryFromPath(workflowPath: string | undefined, basePath?: string): string | null;
+export declare function resolveScenarioPath(workflowName: string, scenarioName: string, basePath?: string, workflowPath?: 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

@@ -1,14 +1,34 @@
 import { existsSync, readdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { getWorkflowCatalog } from '#api/generated/api.js';
 import { getWorkflowsBasePath } from '#utils/paths.js';
 const SCENARIOS_DIR = 'scenarios';
 const WORKFLOWS_PATHS = ['src/workflows', 'workflows'];
 export function extractWorkflowRelativePath(path) {
-    const match = path.match(/workflows\/(.+)\/workflow\.[jt]s$/);
+    const match = path.match(/(?:^|\/)workflows\/(.+)\/workflow\.[jt]s$/);
     return match ? match[1] : null;
 }
-async function fetchWorkflowDirectory(workflowName) {
+function unique(values) {
+    return [...new Set(values)];
+}
+function workflowPathSuffixes(workflowPath) {
+    const parts = dirname(workflowPath).split(/[/\\]+/).filter(Boolean);
+    return parts.map((_, index) => parts.slice(index));
+}
+function candidateWorkflowDirsFromPath(workflowPath, basePath) {
+    return unique(workflowPathSuffixes(workflowPath).flatMap(suffix => WORKFLOWS_PATHS.map(workflowsDir => resolve(basePath, workflowsDir, ...suffix))));
+}
+function candidateScenarioDirsFromPath(workflowPath, basePath) {
+    return candidateWorkflowDirsFromPath(workflowPath, basePath)
+        .map(workflowDir => resolve(workflowDir, SCENARIOS_DIR));
+}
+export function findWorkflowDirectoryFromPath(workflowPath, basePath = getWorkflowsBasePath()) {
+    if (!workflowPath) {
+        return null;
+    }
+    return candidateWorkflowDirsFromPath(workflowPath, basePath).find(existsSync) ?? null;
+}
+async function fetchWorkflowPath(workflowName) {
     try {
         const response = await getWorkflowCatalog();
         const data = response?.data;
@@ -20,11 +40,7 @@ async function fetchWorkflowDirectory(workflowName) {
         if (!workflow) {
             return null;
         }
-        const workflowPath = workflow.path;
-        if (!workflowPath) {
-            return null;
-        }
-        return extractWorkflowRelativePath(workflowPath);
+        return workflow.path ?? null;
     }
     catch {
         return null;
@@ -41,33 +57,48 @@ function resolveScenarioFromDirectory(relativeDir, scenarioFileName, basePath) {
     }
     return { found: false, searchedPaths };
 }
-export async function resolveScenarioPath(workflowName, scenarioName, basePath = getWorkflowsBasePath()) {
+function resolveScenarioFromScenarioDirs(scenariosDirs, scenarioFileName) {
+    const searchedPaths = scenariosDirs.map(dir => resolve(dir, scenarioFileName));
+    const path = searchedPaths.find(existsSync);
+    return path ?
+        { found: true, path, searchedPaths } :
+        { found: false, searchedPaths };
+}
+export async function resolveScenarioPath(workflowName, scenarioName, basePath = getWorkflowsBasePath(), workflowPath) {
     const scenarioFileName = scenarioName.endsWith('.json') ?
         scenarioName :
         `${scenarioName}.json`;
-    const catalogDir = await fetchWorkflowDirectory(workflowName);
-    if (catalogDir) {
-        const result = resolveScenarioFromDirectory(catalogDir, scenarioFileName, basePath);
+    if (workflowPath) {
+        const pathResult = resolveScenarioFromScenarioDirs(candidateScenarioDirsFromPath(workflowPath, basePath), scenarioFileName);
+        if (pathResult.found) {
+            return pathResult;
+        }
+    }
+    const catalogPath = workflowPath ? null : await fetchWorkflowPath(workflowName);
+    if (catalogPath) {
+        const result = resolveScenarioFromScenarioDirs(candidateScenarioDirsFromPath(catalogPath, basePath), scenarioFileName);
         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;
+        const fallback = resolveScenarioFromDirectory(workflowName, scenarioFileName, basePath);
+        return {
+            found: fallback.found,
+            path: fallback.path,
+            searchedPaths: [...result.searchedPaths, ...fallback.searchedPaths]
+        };
     }
     // API unavailable or workflow not in catalog — fall back to convention
     return resolveScenarioFromDirectory(workflowName, scenarioFileName, basePath);
 }
 export function listScenariosForWorkflow(workflowName, workflowPath, basePath = getWorkflowsBasePath()) {
-    const relativeDir = (workflowPath && extractWorkflowRelativePath(workflowPath)) || workflowName;
+    const scenariosDirs = workflowPath ? candidateScenarioDirsFromPath(workflowPath, basePath) : [];
+    const scenariosDir = scenariosDirs.find(existsSync);
+    if (scenariosDir) {
+        return readdirSync(scenariosDir)
+            .filter(f => f.endsWith('.json'))
+            .map(f => f.replace(/\.json$/, ''));
+    }
+    const relativeDir = workflowName;
     for (const workflowsDir of WORKFLOWS_PATHS) {
         const scenariosDir = resolve(basePath, workflowsDir, relativeDir, SCENARIOS_DIR);
         if (existsSync(scenariosDir)) {

package/dist/utils/scenario_resolver.spec.js

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
-import { resolveScenarioPath, getScenarioNotFoundMessage, extractWorkflowRelativePath, listScenariosForWorkflow } from './scenario_resolver.js';
+import { resolveScenarioPath, getScenarioNotFoundMessage, extractWorkflowRelativePath, findWorkflowDirectoryFromPath, listScenariosForWorkflow } from './scenario_resolver.js';
 import * as fs from 'node:fs';
 import * as api from '#api/generated/api.js';
 vi.mock('node:fs', () => ({
@@ -32,6 +32,10 @@ describe('extractWorkflowRelativePath', () => {
         expect(extractWorkflowRelativePath('/src/workflows/my_flow/workflow.ts'))
             .toBe('my_flow');
     });
+    it('should not match workflows inside a parent directory name', () => {
+        expect(extractWorkflowRelativePath('/app/test_workflows/dist/workflows/simple_sleep/workflow.js'))
+            .toBe('simple_sleep');
+    });
     it('should return null for non-matching paths', () => {
         expect(extractWorkflowRelativePath('/app/dist/other/workflow.js')).toBeNull();
         expect(extractWorkflowRelativePath('/app/dist/workflows/')).toBeNull();
@@ -100,6 +104,15 @@ describe('resolveScenarioPath', () => {
             expect(result.found).toBe(true);
             expect(result.path).toContain('src/workflows/my_workflow/scenarios/test_scenario.json');
         });
+        it('should resolve using a provided workflow path without requiring a workflows segment', async () => {
+            mockCatalogFailure();
+            vi.mocked(fs.existsSync).mockImplementation(path => {
+                return String(path) === '/project/src/workflows/writing/editor/scenarios/basic.json';
+            });
+            const result = await resolveScenarioPath('writing_editor', 'basic', '/project', '/app/build-output/writing/editor/workflow.js');
+            expect(result.found).toBe(true);
+            expect(result.path).toBe('/project/src/workflows/writing/editor/scenarios/basic.json');
+        });
     });
     describe('when workflow is not in catalog', () => {
         it('should fall back to convention-based lookup', async () => {
@@ -158,6 +171,12 @@ describe('listScenariosForWorkflow', () => {
         const result = listScenariosForWorkflow('my_workflow', undefined, '/project');
         expect(result).toEqual(['basic', 'advanced']);
     });
+    it('should list scenarios from a workflow path without requiring a workflows segment', () => {
+        vi.mocked(fs.existsSync).mockImplementation(path => String(path) === '/project/src/workflows/writing/editor/scenarios');
+        vi.mocked(fs.readdirSync).mockReturnValue(['basic.json', 'README.md']);
+        const result = listScenariosForWorkflow('writing_editor', '/app/build-output/writing/editor/workflow.js', '/project');
+        expect(result).toEqual(['basic']);
+    });
     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']);
@@ -197,6 +216,16 @@ describe('listScenariosForWorkflow', () => {
         expect(result).toEqual([]);
     });
 });
+describe('findWorkflowDirectoryFromPath', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+    });
+    it('should find the local workflow directory from a loaded workflow path suffix', () => {
+        vi.mocked(fs.existsSync).mockImplementation(path => String(path) === '/project/src/workflows/writing/editor');
+        const result = findWorkflowDirectoryFromPath('/app/build-output/writing/editor/workflow.js', '/project');
+        expect(result).toBe('/project/src/workflows/writing/editor');
+    });
+});
 describe('getScenarioNotFoundMessage', () => {
     it('should return a helpful error message', () => {
         const searchedPaths = [

package/dist/views/dev/dev_app.js

@@ -141,6 +141,6 @@ const Shell = ({ dockerComposePath, onCleanup }) => {
     if (ui.expandedJson.open) {
         return (_jsx(Box, { flexDirection: "column", height: rows, paddingX: 2, paddingTop: 1, children: _jsx(ExpandedJsonModal, {}) }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: rows, paddingX: 2, paddingTop: 1, children: [_jsx(Header, { counters: counters }), _jsx(TabBar, { active: ui.tab }), _jsx(HorizontalRule, {}), _jsx(SearchBar, { active: ui.search.open }), _jsx(Toasts, {}), _jsxs(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: [ui.tab === 'workflows' && !ui.runModal.open && _jsx(WorkflowsPanel, { workflows: workflows, runs: runs }), ui.tab === 'runs' && !ui.runModal.open && _jsx(RunsPanel, { runs: runs }), ui.tab === 'services' && !ui.runModal.open && (_jsx(ServicesPanel, { phase: phase, services: services, dockerComposePath: dockerComposePath })), ui.tab === 'help' && !ui.runModal.open && _jsx(HelpPanel, {}), ui.runModal.open && _jsx(RunModal, { workflowName: ui.runModal.workflowName })] })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: rows, paddingX: 2, paddingTop: 1, children: [_jsx(Header, { counters: counters }), _jsx(TabBar, { active: ui.tab }), _jsx(HorizontalRule, {}), _jsx(SearchBar, { active: ui.search.open }), _jsx(Toasts, {}), _jsxs(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: [ui.tab === 'workflows' && !ui.runModal.open && _jsx(WorkflowsPanel, { workflows: workflows, runs: runs }), ui.tab === 'runs' && !ui.runModal.open && _jsx(RunsPanel, { runs: runs }), ui.tab === 'services' && !ui.runModal.open && (_jsx(ServicesPanel, { phase: phase, services: services, dockerComposePath: dockerComposePath })), ui.tab === 'help' && !ui.runModal.open && _jsx(HelpPanel, {}), ui.runModal.open && _jsx(RunModal, { workflowName: ui.runModal.workflowName, workflowPath: ui.runModal.workflowPath })] })] }));
 };
 export const DevApp = ({ dockerComposePath, onCleanup }) => (_jsx(UiStateProvider, { children: _jsx(Shell, { dockerComposePath: dockerComposePath, onCleanup: onCleanup }) }));

package/dist/views/dev/modals/run_modal.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
 export declare const RunModal: React.FC<{
     workflowName: string;
+    workflowPath?: string;
 }>;

package/dist/views/dev/modals/run_modal.js

@@ -21,9 +21,9 @@ const buildEntries = (scenarios) => {
 };
 const Frame = ({ title, children }) => (_jsxs(Box, { flexDirection: "column", marginTop: 1, borderStyle: "round", paddingX: 1, paddingY: 0, children: [_jsx(Text, { bold: true, children: title }), children] }));
 const TextPrompt = ({ label, value }) => (_jsxs(Box, { marginTop: 1, children: [_jsxs(Text, { children: [label, " "] }), _jsx(Text, { children: value }), _jsx(Text, { inverse: true, children: ' ' })] }));
-export const RunModal = ({ workflowName }) => {
+export const RunModal = ({ workflowName, workflowPath }) => {
     const ui = useUiState();
-    const scenarios = useMemo(() => listScenariosForWorkflow(workflowName), [workflowName]);
+    const scenarios = useMemo(() => listScenariosForWorkflow(workflowName, workflowPath), [workflowName, workflowPath]);
     const entries = useMemo(() => buildEntries(scenarios), [scenarios]);
     const [mode, setMode] = useState('select');
     const [index, setIndex] = useState(0);
@@ -54,7 +54,7 @@ export const RunModal = ({ workflowName }) => {
     };
     const runScenario = async (scenarioName) => {
         try {
-            const input = await readScenario(workflowName, scenarioName);
+            const input = await readScenario(workflowName, scenarioName, workflowPath);
             await submit(input, scenarioName);
         }
         catch (err) {
@@ -64,7 +64,7 @@ export const RunModal = ({ workflowName }) => {
     };
     const startDuplicate = async (scenarioName) => {
         try {
-            const sourceContent = await readScenario(workflowName, scenarioName);
+            const sourceContent = await readScenario(workflowName, scenarioName, workflowPath);
             setEditName(`${scenarioName}_copy`);
             setEditSeed(sourceContent);
             setEditFrameTitle(`Duplicate '${scenarioName}'`);
@@ -106,7 +106,7 @@ export const RunModal = ({ workflowName }) => {
         }
         setMode('submitting');
         try {
-            const writtenPath = await writeScenario(workflowName, name, value);
+            const writtenPath = await writeScenario(workflowName, name, value, workflowPath);
             ui.pushToast(`Saved scenario at ${writtenPath}`, 'info');
             await submit(value, name);
         }

package/dist/views/dev/panels/workflows_panel.js

@@ -98,7 +98,7 @@ export const WorkflowsPanel = ({ workflows, runs }) => {
             ui.setTab('runs');
         }
         else if (input === 'r' && selectedWorkflow?.name) {
-            ui.openRunModal(selectedWorkflow.name);
+            ui.openRunModal(selectedWorkflow.name, selectedWorkflow.path);
         }
     }, { isActive });
     if (workflows.length === 0) {

package/dist/views/dev/services/scenario_io.d.ts

@@ -1,2 +1,2 @@
-export declare const readScenario: (workflowName: string, scenarioName: string) => Promise<unknown>;
-export declare const writeScenario: (workflowName: string, scenarioName: string, content: unknown) => Promise<string>;
+export declare const readScenario: (workflowName: string, scenarioName: string, workflowPath?: string) => Promise<unknown>;
+export declare const writeScenario: (workflowName: string, scenarioName: string, content: unknown, workflowPath?: string) => Promise<string>;

package/dist/views/dev/services/scenario_io.js

@@ -1,19 +1,23 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
-import { resolveScenarioPath } from '#utils/scenario_resolver.js';
+import { findWorkflowDirectoryFromPath, resolveScenarioPath } from '#utils/scenario_resolver.js';
 import { getWorkflowsBasePath } from '#utils/paths.js';
 const WORKFLOWS_PATHS = ['src/workflows', 'workflows'];
-export const readScenario = async (workflowName, scenarioName) => {
-    const resolution = await resolveScenarioPath(workflowName, scenarioName);
+export const readScenario = async (workflowName, scenarioName, workflowPath) => {
+    const resolution = await resolveScenarioPath(workflowName, scenarioName, getWorkflowsBasePath(), workflowPath);
     if (!resolution.found || !resolution.path) {
         throw new Error(`Scenario '${scenarioName}' not found for workflow '${workflowName}'.`);
     }
     const content = await readFile(resolution.path, 'utf-8');
     return JSON.parse(content);
 };
-const findWorkflowDirectory = (workflowName) => {
+const findWorkflowDirectory = (workflowName, workflowPath) => {
     const basePath = getWorkflowsBasePath();
+    const pathDir = findWorkflowDirectoryFromPath(workflowPath, basePath);
+    if (pathDir) {
+        return pathDir;
+    }
     for (const wfDir of WORKFLOWS_PATHS) {
         const candidate = resolve(basePath, wfDir, workflowName);
         if (existsSync(candidate)) {
@@ -22,8 +26,8 @@ const findWorkflowDirectory = (workflowName) => {
     }
     return null;
 };
-export const writeScenario = async (workflowName, scenarioName, content) => {
-    const dir = findWorkflowDirectory(workflowName);
+export const writeScenario = async (workflowName, scenarioName, content, workflowPath) => {
+    const dir = findWorkflowDirectory(workflowName, workflowPath);
     if (!dir) {
         throw new Error(`Workflow directory for '${workflowName}' not found locally.`);
     }

package/dist/views/dev/state/ui_state.d.ts

@@ -17,6 +17,7 @@ export interface SearchState {
 export interface RunModalState {
     open: boolean;
     workflowName: string;
+    workflowPath?: string;
 }
 export interface ExpandedJsonState {
     open: boolean;
@@ -47,7 +48,7 @@ export interface UiState {
     setSelection: (selection: Selection) => void;
     setRightPaneTab: (tab: RightPaneTab) => void;
     setRunsView: (view: RunsView) => void;
-    openRunModal: (workflowName: string) => void;
+    openRunModal: (workflowName: string, workflowPath?: string) => void;
     closeRunModal: () => void;
     openExpandedJson: (value: unknown, title: string) => void;
     closeExpandedJson: () => void;

package/dist/views/dev/state/ui_state.js

@@ -43,7 +43,7 @@ export const UiStateProvider = ({ children }) => {
         setSelection,
         setRightPaneTab,
         setRunsView,
-        openRunModal: (workflowName) => setRunModal({ open: true, workflowName }),
+        openRunModal: (workflowName, workflowPath) => setRunModal({ open: true, workflowName, workflowPath }),
         closeRunModal: () => setRunModal({ open: false, workflowName: '' }),
         openExpandedJson: (value, title) => setExpandedJson({ open: true, value, title }),
         closeExpandedJson: () => setExpandedJson({ open: false, value: null, title: '' }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/cli",
-  "version": "0.3.3-next.b4a190e.0",
+  "version": "0.3.3-next.e8eff63.0",
   "description": "CLI for Output.ai workflow generation",
   "type": "module",
   "main": "dist/index.js",
@@ -36,9 +36,9 @@
     "semver": "7.7.4",
     "undici": "8.1.0",
     "yaml": "^2.8.3",
-    "@outputai/credentials": "0.3.3-next.b4a190e.0",
-    "@outputai/evals": "0.3.3-next.b4a190e.0",
-    "@outputai/llm": "0.3.3-next.b4a190e.0"
+    "@outputai/credentials": "0.3.3-next.e8eff63.0",
+    "@outputai/evals": "0.3.3-next.e8eff63.0",
+    "@outputai/llm": "0.3.3-next.e8eff63.0"
   },
   "devDependencies": {
     "@types/cli-progress": "3.11.6",