@outputai/cli 0.10.1-next.09ed166.0 → 0.10.1-next.2caa4a1.0

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

@@ -1,7 +1,6 @@
 /* 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';
@@ -13,34 +12,23 @@ vi.mock('#services/coding_agents.js', () => ({
 vi.mock('#utils/port_availability.js', () => ({
     findUnavailablePorts: vi.fn().mockResolvedValue([])
 }));
-vi.mock('#services/docker.js', () => ({
-    validateDockerEnvironment: vi.fn(),
-    startDockerCompose: vi.fn(),
-    stopDockerCompose: vi.fn().mockResolvedValue(undefined),
-    getServiceStatus: vi.fn().mockResolvedValue([
-        { name: 'redis', state: 'running', health: 'healthy', ports: ['6379:6379'] },
-        { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] }
-    ]),
-    isServiceFailed: vi.fn((s) => s.state === 'exited' || s.health === 'unhealthy'),
-    DockerComposeConfigNotFoundError: Error,
-    DockerValidationError: Error,
-    getDefaultDockerComposePath: vi.fn(() => '/path/to/docker-compose-dev.yml'),
-    SERVICE_HEALTH: {
-        HEALTHY: 'healthy',
-        UNHEALTHY: 'unhealthy',
-        STARTING: 'starting',
-        NONE: 'none'
-    },
-    SERVICE_STATE: {
-        RUNNING: 'running',
-        EXITED: 'exited'
-    }
-}));
-vi.mock('node:fs/promises', () => ({
-    default: {
-        access: vi.fn()
-    }
-}));
+vi.mock('#services/docker.js', async (importActual) => {
+    const actual = await importActual();
+    return {
+        ...actual,
+        // Override only the IO surface. Pure helpers (classifyStackState,
+        // isServiceHealthy, STACK_STATE, error classes) come from the real module,
+        // so branch selection here exercises the same logic production runs.
+        validateDockerEnvironment: vi.fn(),
+        startDockerCompose: vi.fn(),
+        runDockerComposeUpDetached: vi.fn().mockResolvedValue({ code: 0, signal: null, output: '' }),
+        stopDockerCompose: vi.fn().mockResolvedValue(undefined),
+        // Default: nothing running — a fresh start. Individual tests opt into an
+        // existing stack by overriding this to drive attach / reconcile branches.
+        getServiceStatus: vi.fn().mockResolvedValue([]),
+        resolveDockerComposePath: vi.fn().mockResolvedValue('/path/to/docker-compose-dev.yml')
+    };
+});
 vi.mock('ink', () => ({
     render: vi.fn().mockReturnValue({
         waitUntilExit: vi.fn().mockResolvedValue(undefined),
@@ -88,12 +76,22 @@ describe('dev command', () => {
         vi.mocked(dockerService.validateDockerEnvironment).mockResolvedValue(undefined);
         // By default, no host port is taken — individual tests opt in.
         vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([]);
+        // By default, no stack is running — a fresh start. Tests opt into the
+        // attach / reconcile branches by overriding getServiceStatus.
+        vi.mocked(dockerService.getServiceStatus).mockResolvedValue([]);
+        vi.mocked(dockerService.runDockerComposeUpDetached).mockResolvedValue({ code: 0, signal: null, output: '' });
         // By default, startDockerCompose returns a mock process
         vi.mocked(dockerService.startDockerCompose).mockResolvedValue(createMockDockerProcess());
-        // By default, fs.access succeeds (file exists)
-        vi.mocked(fs).access.mockResolvedValue(undefined);
+        // By default, the compose file resolves and exists.
+        vi.mocked(dockerService.resolveDockerComposePath).mockResolvedValue('/path/to/docker-compose-dev.yml');
         // By default, ensureClaudePlugin succeeds
         vi.mocked(codingAgentsService.ensureClaudePlugin).mockResolvedValue(undefined);
+        // By default, render returns an instance that exits immediately. Tests
+        // needing a controllable lifecycle override this.
+        vi.mocked(render).mockReturnValue({
+            waitUntilExit: vi.fn().mockResolvedValue(undefined),
+            unmount: vi.fn()
+        });
     });
     afterEach(() => {
         vi.restoreAllMocks();
@@ -154,19 +152,19 @@ describe('dev command', () => {
             });
             await expect(cmd.run()).rejects.toThrow('Docker is not installed');
         });
-        it('should call validateDockerEnvironment', async () => {
+        it('should call validateDockerEnvironment before doing any work', async () => {
             const cmd = new Dev([], {});
             cmd.log = vi.fn();
             cmd.error = vi.fn();
-            // Mock the subprocess spawn to prevent actual execution
-            vi.doMock('node:child_process', () => ({
-                spawn: vi.fn().mockReturnValue({
-                    on: vi.fn(),
-                    kill: vi.fn()
-                })
-            }));
-            // This test just verifies the function is called
-            expect(vi.mocked(dockerService.validateDockerEnvironment)).toBeDefined();
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({
+                    flags: { 'compose-file': undefined, 'image-pull-policy': 'always', detached: true },
+                    args: {}
+                }),
+                configurable: true
+            });
+            await cmd.run();
+            expect(dockerService.validateDockerEnvironment).toHaveBeenCalled();
         });
     });
     describe('Claude plugin update', () => {
@@ -223,7 +221,7 @@ describe('dev command', () => {
             runPromise.catch(() => { });
         });
         it('should handle docker compose configuration not found', async () => {
-            vi.mocked(fs).access.mockRejectedValue(new Error('File not found'));
+            vi.mocked(dockerService.resolveDockerComposePath).mockRejectedValue(new dockerService.DockerComposeConfigNotFoundError('/path/to/docker-compose-dev.yml'));
             const cmd = new Dev([], {});
             cmd.log = vi.fn();
             cmd.error = vi.fn();
@@ -327,6 +325,356 @@ describe('dev command', () => {
             expect(inkInstance.unmount).not.toHaveBeenCalledWith(expect.any(Error));
             expect(cmd.error).not.toHaveBeenCalled();
         });
+        // Without this, mutating teardownIfOwned to return unconditionally leaves
+        // every test green while each session leaks containers holding ports.
+        it('stops compose and kills the foreground process when it owns the stack', async () => {
+            const dockerProcess = createMockDockerProcess();
+            vi.mocked(dockerService.startDockerCompose).mockResolvedValue(dockerProcess);
+            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', detached: false },
+                    args: {}
+                }),
+                configurable: true
+            });
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            const appElement = vi.mocked(render).mock.calls.at(-1)?.[0];
+            if (!React.isValidElement(appElement)) {
+                throw new Error('Expected render to receive a React element');
+            }
+            await appElement.props.onCleanup();
+            expect(dockerService.stopDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml');
+            expect(dockerProcess.kill).toHaveBeenCalledWith('SIGTERM');
+            runPromise.catch(() => { });
+        });
+        // The abnormal-exit route (health timeout, compose crash) resolves outside
+        // the signal path and has its own teardown call.
+        it('tears down an owned stack when the TUI exits abnormally', 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(() => {
+                throw new Error('aborted');
+            });
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({
+                    flags: { 'compose-file': undefined, 'image-pull-policy': 'always', detached: false },
+                    args: {}
+                }),
+                configurable: true
+            });
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            inkInstance.unmount(new Error('Timeout waiting for services to become healthy'));
+            await expect(runPromise).rejects.toThrow('aborted');
+            expect(dockerService.stopDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml');
+        });
+    });
+    describe('attach and reconcile behavior', () => {
+        const runningStack = [
+            { name: 'redis', state: 'running', health: 'healthy', ports: [] },
+            { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] },
+            { name: 'api', state: 'running', health: 'none', ports: ['3001:3001'] }
+        ];
+        const makeCmd = () => {
+            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', detached: false },
+                    args: {}
+                }),
+                configurable: true
+            });
+            return cmd;
+        };
+        const lastRenderedProps = () => {
+            const appElement = vi.mocked(render).mock.calls.at(-1)?.[0];
+            if (!React.isValidElement(appElement)) {
+                throw new Error('Expected render to receive a React element');
+            }
+            return appElement.props;
+        };
+        it('attaches to a healthy running stack without a foreground up or port probe', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            const cmd = makeCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).not.toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(true);
+        });
+        it('leaves an attached stack running on cleanup (no teardown)', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            const cmd = makeCmd();
+            await cmd.run();
+            await lastRenderedProps().onCleanup();
+            expect(dockerService.stopDockerCompose).not.toHaveBeenCalled();
+        });
+        it('does not port-probe or error when our own stack already holds the ports', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001]);
+            const cmd = makeCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+        });
+        it('reconciles a partially-failed stack with a detached up, then monitors', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] },
+                { name: 'worker', state: 'exited', health: 'none', ports: [] }
+            ]);
+            const cmd = makeCmd();
+            await cmd.run();
+            expect(dockerService.runDockerComposeUpDetached).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', 'always');
+            // Reconcile monitors via ps polling, not a foreground up.
+            expect(dockerService.startDockerCompose).not.toHaveBeenCalled();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(true);
+        });
+        it('aborts with a port-collision hint when the reconcile up fails to bind', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'running', health: 'healthy', ports: ['7233:7233'] },
+                { name: 'worker', state: 'exited', health: 'none', ports: [] }
+            ]);
+            vi.mocked(dockerService.runDockerComposeUpDetached).mockResolvedValue({
+                code: 1,
+                signal: null,
+                output: 'Error response from daemon: failed to set up container networking: driver failed ' +
+                    'programming external connectivity on endpoint out-api-1 (a1b2c3): ' +
+                    'Bind for 0.0.0.0:3001 failed: port is already allocated'
+            });
+            const cmd = makeCmd();
+            // this.error throws in oclif; emulate so the flow stops at the abort.
+            const errorMock = vi.fn((_message) => {
+                throw new Error('aborted');
+            });
+            cmd.error = errorMock;
+            await expect(cmd.run()).rejects.toThrow('aborted');
+            const message = errorMock.mock.calls.at(-1)?.[0];
+            expect(message).toContain('Port 3001 is already in use.');
+            expect(message).toContain('OUTPUT_API_HOST_PORT=');
+            expect(render).not.toHaveBeenCalled();
+        });
+        it('falls back to a fresh foreground start when no stack is running', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(false);
+            runPromise.catch(() => { });
+        });
+        // A stopped stack (reboot, `docker compose stop`, failed teardown) leaves
+        // exited rows in `ps --all`. Before the classifier keyed on "is anything
+        // live", these reconciled and then disowned themselves: a plain `output dev`
+        // started every container and left them running on quit.
+        it('treats an all-exited stack as an owned fresh start, not an attach', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'exited', health: 'none', ports: [] },
+                { name: 'worker', state: 'exited', health: 'none', ports: [] }
+            ]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(false);
+            runPromise.catch(() => { });
+        });
+        it('tears down an all-exited stack it restarted, since it owns it', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'temporal', state: 'exited', health: 'none', ports: [] }
+            ]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            await lastRenderedProps().onCleanup();
+            expect(dockerService.stopDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml');
+            runPromise.catch(() => { });
+        });
+        // The `ps` query absorbs a broken compose file, a dead daemon, EACCES on the
+        // socket, and any JSON.parse throw. Falling back to a fresh start is right;
+        // doing it silently is what reported a port collision with the wrong remedy.
+        it('falls back to a fresh start and warns when the state query fails', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockRejectedValue(new Error('no configuration file provided: not found'));
+            const cmd = makeCmd();
+            cmd.warn = vi.fn();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.startDockerCompose).toHaveBeenCalled();
+            expect(lastRenderedProps().attached).toBe(false);
+            const warned = vi.mocked(cmd.warn).mock.calls.map(c => String(c[0])).join('\n');
+            expect(warned).toContain('no configuration file provided: not found');
+            expect(warned).toContain('output dev down');
+            runPromise.catch(() => { });
+        });
+        it('warns that quitting leaves the stack up when attaching', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue(runningStack);
+            const cmd = makeCmd();
+            await cmd.run();
+            const logged = vi.mocked(cmd.log).mock.calls.map(c => c[0]).join('\n');
+            expect(logged).toContain('Quitting leaves these services running');
+            expect(logged).toContain('output dev down');
+        });
+        it('does not claim the stack survives quitting on an owned fresh start', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([]);
+            const cmd = makeCmd();
+            const runPromise = cmd.run();
+            await new Promise(resolve => setImmediate(resolve));
+            const logged = vi.mocked(cmd.log).mock.calls.map(c => c[0]).join('\n');
+            expect(logged).not.toContain('Quitting leaves these services running');
+            runPromise.catch(() => { });
+        });
+    });
+    describe('detached flag', () => {
+        const makeDetachedCmd = () => {
+            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', detached: true },
+                    args: {}
+                }),
+                configurable: true
+            });
+            return cmd;
+        };
+        it('brings the stack up detached and exits without mounting the TUI', async () => {
+            const cmd = makeDetachedCmd();
+            await cmd.run();
+            expect(dockerService.runDockerComposeUpDetached).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', 'always');
+            expect(render).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+        });
+        // The -d path lost its probe when the state check moved inside the NONE
+        // branch. It matters more than it looks: a non-container process holding a
+        // published port does NOT fail `compose up -d` on Docker Desktop — the
+        // container starts and the port keeps answering the other process.
+        it('probes host ports before starting a fresh detached stack', async () => {
+            const cmd = makeDetachedCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+            expect(dockerService.runDockerComposeUpDetached).toHaveBeenCalled();
+        });
+        it('aborts before compose when a foreign process holds a port', async () => {
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001]);
+            const cmd = makeDetachedCmd();
+            const errorMock = vi.fn((_message) => {
+                throw new Error('aborted');
+            });
+            cmd.error = errorMock;
+            await expect(cmd.run()).rejects.toThrow('aborted');
+            expect(errorMock.mock.calls.at(-1)?.[0]).toContain('Port 3001 is already in use.');
+            expect(dockerService.runDockerComposeUpDetached).not.toHaveBeenCalled();
+        });
+        it('warns rather than silently assuming a fresh start when the query fails', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockRejectedValue(new Error('daemon not running'));
+            const cmd = makeDetachedCmd();
+            cmd.warn = vi.fn();
+            await cmd.run();
+            const warned = vi.mocked(cmd.warn).mock.calls.map(c => String(c[0])).join('\n');
+            expect(warned).toContain('daemon not running');
+            expect(portAvailability.findUnavailablePorts).toHaveBeenCalled();
+        });
+        it('does not probe when our own stack is already running', async () => {
+            vi.mocked(dockerService.getServiceStatus).mockResolvedValue([
+                { name: 'api', state: 'running', health: 'healthy', ports: ['3001:3001'] }
+            ]);
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001]);
+            const cmd = makeDetachedCmd();
+            await cmd.run();
+            expect(portAvailability.findUnavailablePorts).not.toHaveBeenCalled();
+            expect(cmd.error).not.toHaveBeenCalled();
+        });
+        it('aborts with a port-collision hint when the detached up fails to bind', async () => {
+            vi.mocked(dockerService.runDockerComposeUpDetached).mockResolvedValue({
+                code: 1,
+                signal: null,
+                output: 'Error response from daemon: failed to set up container networking: driver failed ' +
+                    'programming external connectivity on endpoint out-temporal-1 (d4e5f6): ' +
+                    'Bind for 0.0.0.0:7233 failed: port is already allocated'
+            });
+            const cmd = makeDetachedCmd();
+            const errorMock = vi.fn((_message) => {
+                throw new Error('aborted');
+            });
+            cmd.error = errorMock;
+            await expect(cmd.run()).rejects.toThrow('aborted');
+            const message = errorMock.mock.calls.at(-1)?.[0];
+            expect(message).toContain('Port 7233 is already in use.');
+            expect(message).toContain('OUTPUT_TEMPORAL_HOST_PORT=');
+        });
+    });
+    describe('fatal error handling', () => {
+        it('restores the terminal and exits non-zero on an uncaught exception', async () => {
+            const inkInstance = createControllableInkInstance();
+            vi.mocked(render).mockReturnValue(inkInstance);
+            // Capture the registered handlers instead of letting them attach to the
+            // real process, and neutralize process.exit so firing one doesn't kill
+            // the test runner.
+            const handlers = {};
+            const onSpy = vi.spyOn(process, 'on').mockImplementation(((event, handler) => {
+                handlers[event] = handler;
+                return process;
+            }));
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+            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));
+            expect(handlers.uncaughtException).toBeInstanceOf(Function);
+            expect(handlers.unhandledRejection).toBeInstanceOf(Function);
+            const crash = new Error('boom');
+            handlers.uncaughtException(crash);
+            // Terminal restore, the crash print, and exit all run after docker
+            // teardown settles, so they land a tick later.
+            await new Promise(resolve => setImmediate(resolve));
+            // Docker is torn down before exit, so a crash doesn't orphan the
+            // compose stack.
+            expect(dockerService.stopDockerCompose).toHaveBeenCalled();
+            expect(inkInstance.unmount).toHaveBeenCalled();
+            expect(stdoutSpy).toHaveBeenCalledWith('\x1b[?1049l');
+            expect(errorSpy).toHaveBeenCalledWith(crash);
+            expect(exitSpy).toHaveBeenCalledWith(1);
+            // Discriminating order: docker must be fully torn down BEFORE Ink
+            // unmounts. Unmounting resolves waitUntilExit() and resumes run(),
+            // which strips the signal listeners — so an unmount-first ordering
+            // would drop the SIGINT handler mid-teardown and risk orphaning the
+            // stack on a Ctrl+C.
+            expect(vi.mocked(dockerService.stopDockerCompose).mock.invocationCallOrder[0])
+                .toBeLessThan(inkInstance.unmount.mock.invocationCallOrder[0]);
+            // Within the restore, Ink unmounts before the alt-screen is left, and
+            // the crash prints only after — otherwise console.error paints into a
+            // buffer the user never sees.
+            const leaveAltScreenCall = stdoutSpy.mock.invocationCallOrder[stdoutSpy.mock.calls.findIndex(([seq]) => seq === '\x1b[?1049l')];
+            expect(inkInstance.unmount.mock.invocationCallOrder[0]).toBeLessThan(leaveAltScreenCall);
+            expect(leaveAltScreenCall).toBeLessThan(errorSpy.mock.invocationCallOrder[0]);
+            onSpy.mockRestore();
+            runPromise.catch(() => { });
+        });
     });
     describe('image pull policy', () => {
         it('should pass pull policy to startDockerCompose', async () => {

package/dist/commands/workflow/run.js

@@ -63,7 +63,14 @@ export default class WorkflowRun extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowRun);
-        const input = await resolveInput(args.workflowName, args.scenario, flags.input, 'run', flags.catalog);
+        const input = await resolveInput({
+            workflowName: args.workflowName,
+            scenario: args.scenario,
+            inputFlag: flags.input,
+            commandName: 'run',
+            catalog: flags.catalog,
+            json: this.jsonEnabled()
+        });
         this.log(`Executing workflow: ${args.workflowName}...`);
         const response = await executeWorkflow({
             body: {

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

@@ -64,7 +64,12 @@ describe('workflow run command', () => {
                 headers: new Headers()
             });
             await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', undefined, undefined, 'run', undefined);
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                commandName: 'run',
+                catalog: undefined,
+                json: false
+            }));
             expect(postWorkflowRun).toHaveBeenCalledTimes(1);
             expect(postWorkflowRun).toHaveBeenCalledWith({ workflowName: 'my_workflow', input: { key: 'value' }, catalog: undefined }, expect.objectContaining({ config: { timeout: 600000 } }));
             expect(cmd.log).toHaveBeenCalledWith('Executing workflow: my_workflow...');
@@ -83,7 +88,12 @@ describe('workflow run command', () => {
                 headers: new Headers()
             });
             await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', 'basic', undefined, 'run', 'my-catalog');
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                scenario: 'basic',
+                commandName: 'run',
+                catalog: 'my-catalog'
+            }));
             expect(postWorkflowRun).toHaveBeenCalledWith(expect.objectContaining({ catalog: 'my-catalog' }), expect.anything());
         });
         it('retries when response has Retry-After and succeeds on second attempt', async () => {

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

@@ -1,6 +1,8 @@
 import { Command } from '@oclif/core';
+import { type PostWorkflowStart200 } from '#api/generated/api.js';
 export default class WorkflowStart extends Command {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static args: {
         workflowName: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
@@ -10,6 +12,6 @@ export default class WorkflowStart extends Command {
         input: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         catalog: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    run(): Promise<PostWorkflowStart200>;
     catch(error: Error): Promise<void>;
 }

package/dist/commands/workflow/start.js

@@ -4,11 +4,13 @@ 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 enableJsonFlag = true;
     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"}\' --catalog my-catalog'
+        '<%= config.bin %> <%= command.id %> simple --input \'{"key":"value"}\' --catalog my-catalog',
+        '<%= config.bin %> <%= command.id %> simple --json'
     ];
     static args = {
         workflowName: Args.string({
@@ -37,7 +39,14 @@ export default class WorkflowStart extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowStart);
-        const input = await resolveInput(args.workflowName, args.scenario, flags.input, 'start', flags.catalog);
+        const input = await resolveInput({
+            workflowName: args.workflowName,
+            scenario: args.scenario,
+            inputFlag: flags.input,
+            commandName: 'start',
+            catalog: flags.catalog,
+            json: this.jsonEnabled()
+        });
         this.log(`Starting workflow: ${args.workflowName}...`);
         const response = await postWorkflowStart({
             workflowName: args.workflowName,
@@ -57,6 +66,7 @@ export default class WorkflowStart extends Command {
             `Use "workflow result ${result.workflowId || '<workflow-id>'}" to get the workflow result when complete`
         ].join('\n');
         this.log(`\n${output}`);
+        return result;
     }
     async catch(error) {
         return handleApiError(error, (...args) => this.error(...args), {

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

@@ -36,13 +36,17 @@ describe('workflow start command', () => {
             expect(WorkflowStart.flags.catalog.env).toBe('OUTPUT_CATALOG_ID');
             expect(WorkflowStart.flags.catalog.char).toBe('c');
         });
+        it('enables the built-in --json flag', async () => {
+            const WorkflowStart = (await import('./start.js')).default;
+            expect(WorkflowStart.enableJsonFlag).toBe(true);
+        });
     });
     describe('run()', () => {
-        const createCommand = async (flagOverrides = {}) => {
+        const createCommand = async (flagOverrides = {}, argv = ['my_workflow']) => {
             const WorkflowStart = (await import('./start.js')).default;
             const { postWorkflowStart } = await import('#api/generated/api.js');
             const { resolveInput } = await import('#utils/resolve_input.js');
-            const cmd = new WorkflowStart(['my_workflow'], {});
+            const cmd = new WorkflowStart(argv, {});
             cmd.log = vi.fn();
             cmd.error = vi.fn(() => {
                 throw new Error('error called');
@@ -61,9 +65,15 @@ describe('workflow start command', () => {
                 status: 200,
                 headers: new Headers()
             });
-            await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', undefined, undefined, 'start', 'my-catalog');
+            const result = await cmd.run();
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                commandName: 'start',
+                catalog: 'my-catalog',
+                json: false
+            }));
             expect(postWorkflowStart).toHaveBeenCalledWith(expect.objectContaining({ workflowName: 'my_workflow', catalog: 'my-catalog' }));
+            expect(result).toEqual({ workflowId: 'wf-123' });
         });
         it('passes undefined catalog through when none is set', async () => {
             const { cmd, postWorkflowStart, resolveInput } = await createCommand();
@@ -74,7 +84,22 @@ describe('workflow start command', () => {
                 headers: new Headers()
             });
             await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', undefined, undefined, 'start', undefined);
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                commandName: 'start',
+                catalog: undefined
+            }));
+        });
+        it('tells resolveInput to stay quiet when --json is set', async () => {
+            const { cmd, postWorkflowStart, resolveInput } = await createCommand({}, ['my_workflow', 'basic', '--json']);
+            resolveInput.mockResolvedValue({});
+            postWorkflowStart.mockResolvedValue({
+                data: { workflowId: 'wf-123' },
+                status: 200,
+                headers: new Headers()
+            });
+            await cmd.run();
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({ json: true }));
         });
     });
 });

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.10.1-next.09ed166.0"
+    "framework": "0.10.1-next.2caa4a1.0"
 }