@outputai/cli 0.10.1-next.f6a7c1a.0 → 0.11.0

package/dist/commands/workflow/start.js

@@ -1,14 +1,26 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { postWorkflowStart } from '#api/generated/api.js';
-import { handleApiError } from '#utils/error_handler.js';
+import { commandStreamIo, monitorErrorOverrides, streamWorkflowUpdates } from '#services/monitor_stream.js';
+import { handleApiError, handleCommandError } from '#utils/error_handler.js';
+import { isErrorStatus } from '#utils/format_workflow_result.js';
+import { gatedMonitorStreamFlags, MONITOR_DEFAULTS } from '#utils/monitor_flags.js';
 import { resolveInput } from '#utils/resolve_input.js';
+/**
+ * Distinct from 1 (the workflow itself failed) and 2 (usage): the workflow was
+ * started and is still running, only the attached stream gave up. A caller that
+ * retries on exit 1 would otherwise re-submit a workflow that is already running.
+ */
+const MONITOR_FAILED_EXIT_CODE = 3;
 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 input.json --monitor',
+        '<%= config.bin %> <%= command.id %> simple --input \'{"key":"value"}\' --catalog my-catalog',
+        '<%= config.bin %> <%= command.id %> simple --json'
     ];
     static args = {
         workflowName: Args.string({
@@ -33,11 +45,45 @@ export default class WorkflowStart extends Command {
             deprecateAliases: true,
             description: 'Catalog name for workflow execution (defaults to OUTPUT_CATALOG_ID)',
             env: 'OUTPUT_CATALOG_ID'
-        })
+        }),
+        // No `default: false`: a defaulted flag counts as present, so it would
+        // satisfy the `dependsOn` guard the three flags in `gatedMonitorStreamFlags`
+        // point at, letting `--interval` and friends be accepted (and then ignored)
+        // on a plain `workflow start`. Those three omit their own defaults for a
+        // different reason — see `gatedMonitorStreamFlags`.
+        //
+        // No `exclusive: [ 'json' ]` either: oclif's own rejection would fire first
+        // and print a bare "--json=true cannot also be provided", pre-empting the
+        // guard in `run()` that explains what to use instead. That guard covers both
+        // triggers (`--json` on argv, and `CONTENT_TYPE=json`) with one message.
+        monitor: Flags.boolean({
+            char: 'm',
+            description: 'After starting, attach and stream status updates until the workflow ends ' +
+                '(Ctrl+C detaches; the workflow keeps running). Cannot be combined with --json'
+        }),
+        ...gatedMonitorStreamFlags('monitor')
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowStart);
-        const input = await resolveInput(args.workflowName, args.scenario, flags.input, 'start', flags.catalog);
+        // The built-in `--json` flag is injected by `enableJsonFlag`, and
+        // `CONTENT_TYPE=json` turns it on without it appearing on argv at all, so
+        // this runtime check — not an oclif flag relationship — is what catches
+        // every route into json mode. Streaming under `--json` is worse than
+        // useless: `Command.log()` is a no-op while json is enabled, so every update
+        // would be swallowed and the command would simply hang until the workflow
+        // ended.
+        if (flags.monitor && this.jsonEnabled()) {
+            this.error('Cannot combine --monitor with --json. Use "workflow run --json" to wait for the result, ' +
+                'or "workflow monitor <id> --format json" to stream newline-delimited JSON.', { exit: 2 });
+        }
+        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,
@@ -48,18 +94,67 @@ export default class WorkflowStart extends Command {
             this.error('API returned invalid response', { exit: 1 });
         }
         const result = response.data;
-        const output = [
+        const started = [
             'Workflow started successfully',
             '',
-            `Workflow ID: ${result.workflowId || 'unknown'}`,
-            '',
-            `Use "workflow status ${result.workflowId || '<workflow-id>'}" to check the workflow status`,
-            `Use "workflow result ${result.workflowId || '<workflow-id>'}" to get the workflow result when complete`
-        ].join('\n');
-        this.log(`\n${output}`);
+            `Workflow ID: ${result.workflowId || 'unknown'}`
+        ];
+        if (!flags.monitor) {
+            this.log(`\n${[
+                ...started,
+                '',
+                `Use "workflow status ${result.workflowId || '<workflow-id>'}" to check the workflow status`,
+                `Use "workflow result ${result.workflowId || '<workflow-id>'}" to get the workflow result when complete`
+            ].join('\n')}`);
+            return result;
+        }
+        // Checked before the banner prints: "Workflow started successfully" followed
+        // immediately by a failure contradicts itself, and the `unknown` placeholder
+        // id it would show is not something the user can act on. Exit 3, not 1 — the
+        // start itself succeeded, so this is the "started but unmonitorable" case.
+        if (!result.workflowId) {
+            this.error('The workflow was started, but the API did not return a workflow ID, so it cannot be monitored. ' +
+                'Use "workflow runs list" to find it.', { exit: MONITOR_FAILED_EXIT_CODE });
+        }
+        this.log(`\n${started.join('\n')}`);
+        this.log('');
+        try {
+            const status = await streamWorkflowUpdates({
+                workflowId: result.workflowId,
+                // Pin to the run just started rather than letting the monitor resolve
+                // "latest run" — with a retry or a rapid re-start those can differ.
+                runId: result.runId ?? undefined,
+                includePayloads: flags['include-payloads'] ?? MONITOR_DEFAULTS.includePayloads,
+                interval: flags.interval ?? MONITOR_DEFAULTS.interval,
+                // Always text: monitoring under json mode is rejected above, so the
+                // NDJSON path is `workflow monitor --format json`.
+                json: false,
+                color: flags.color ?? MONITOR_DEFAULTS.color
+            }, commandStreamIo(this));
+            // Monitoring reports the workflow's *progress*; the return value still has
+            // to be fetched separately, so name the command that does it. A failed run
+            // has no result to fetch, so point at the one that explains the failure.
+            if (status) {
+                this.log(isErrorStatus(status) ?
+                    `\nUse "workflow debug ${result.workflowId}" to inspect the failure` :
+                    `\nUse "workflow result ${result.workflowId}" to get the workflow result`);
+            }
+        }
+        catch (error) {
+            // The workflow was started and is still running — only the stream gave up.
+            // Say so explicitly and exit on a code of its own, so this can't be read
+            // (by a human or by a CI job retrying on exit 1) as a failed start.
+            //
+            // `handleApiError`, not `handleCommandError`: an error the stream raised
+            // through `io.error` is already a CLIError, and passing it through would
+            // report it as a plain exit-1 failure rather than a live workflow.
+            handleApiError(error, message => this.error(`Workflow ${result.workflowId} started, but monitoring stopped:\n${message}\n` +
+                `The workflow is still running. Use "workflow status ${result.workflowId}" to check on it.`, { exit: MONITOR_FAILED_EXIT_CODE }), monitorErrorOverrides(error));
+        }
+        return result;
     }
     async catch(error) {
-        return handleApiError(error, (...args) => this.error(...args), {
+        return handleCommandError(error, (...args) => this.error(...args), {
             404: 'Workflow not found. Check the workflow name.'
         });
     }

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

@@ -1,11 +1,20 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Parser } from '@oclif/core';
+import { CLIError } from '@oclif/core/errors';
 vi.mock('#api/generated/api.js', () => ({
     postWorkflowStart: vi.fn()
 }));
 vi.mock('#utils/resolve_input.js', () => ({
     resolveInput: vi.fn()
 }));
+// Only the streaming loop is stubbed; monitorErrorOverrides and commandStreamIo
+// stay real so the default-application and error-mapping branches are exercised
+// against the values `workflow monitor` actually uses.
+vi.mock('#services/monitor_stream.js', async (importOriginal) => ({
+    ...await importOriginal(),
+    streamWorkflowUpdates: vi.fn()
+}));
 describe('workflow start command', () => {
     beforeEach(async () => {
         vi.clearAllMocks();
@@ -36,13 +45,72 @@ 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);
+        });
+        it('exposes --monitor with no default so dependsOn stays enforceable', async () => {
+            const WorkflowStart = (await import('./start.js')).default;
+            expect(WorkflowStart.flags.monitor.char).toBe('m');
+            // A defaulted flag counts as present, so a default here would satisfy the
+            // dependsOn guards below and let --interval through without --monitor.
+            expect(WorkflowStart.flags.monitor.default).toBeUndefined();
+        });
+        it('leaves the --monitor/--json conflict to the runtime guard', async () => {
+            const WorkflowStart = (await import('./start.js')).default;
+            // An `exclusive: [ 'json' ]` relationship would fire first and print a bare
+            // "--json=true cannot also be provided", pre-empting the guard in run()
+            // that explains what to use instead — and it still wouldn't catch
+            // CONTENT_TYPE=json, which never reaches argv.
+            expect(WorkflowStart.flags.monitor.exclusive).toBeUndefined();
+        });
+        it('gates every monitor passthrough flag behind --monitor and leaves them undefaulted', async () => {
+            const WorkflowStart = (await import('./start.js')).default;
+            for (const name of ['interval', 'include-payloads', 'color']) {
+                expect(WorkflowStart.flags[name].dependsOn).toEqual(['monitor']);
+                // A default would count as present and trigger this flag's own dependsOn
+                // check, failing every invocation that omits --monitor.
+                expect(WorkflowStart.flags[name].default).toBeUndefined();
+            }
+        });
+        // The properties asserted above are only the inputs; what matters is what
+        // oclif does with them. Parser.parse needs no oclif Config, so the actual
+        // gating is cheap to pin — worth doing because the no-default design is
+        // subtle enough that someone will try to "fix" it by adding one.
+        describe('flag parsing', () => {
+            const parse = async (argv) => {
+                const WorkflowStart = (await import('./start.js')).default;
+                return Parser.parse(argv, { flags: WorkflowStart.flags, strict: false });
+            };
+            it('accepts a plain start with none of the monitor flags', async () => {
+                await expect(parse(['my_workflow'])).resolves.toBeDefined();
+            });
+            it('accepts the passthrough flags once --monitor is given', async () => {
+                const { flags } = await parse(['my_workflow', '--monitor', '--interval', '500', '--include-payloads']);
+                expect(flags).toMatchObject({ monitor: true, interval: 500, 'include-payloads': true });
+            });
+            it('rejects a passthrough flag without --monitor', async () => {
+                await expect(parse(['my_workflow', '--interval', '500'])).rejects.toThrow(/--monitor/);
+            });
+            it('gates --no-color behind --monitor as well', async () => {
+                // A consequence of gating --color, not an independent decision: --no-color
+                // is reflexive enough that this is worth stating outright rather than
+                // leaving as a surprise.
+                await expect(parse(['my_workflow', '--no-color'])).rejects.toThrow(/--monitor/);
+                await expect(parse(['my_workflow', '--monitor', '--no-color']))
+                    .resolves.toMatchObject({ flags: { color: false } });
+            });
+            it('rejects an interval below the minimum', async () => {
+                await expect(parse(['my_workflow', '--monitor', '--interval', '0'])).rejects.toThrow();
+            });
+        });
     });
     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');
@@ -53,6 +121,7 @@ describe('workflow start command', () => {
             });
             return { cmd, postWorkflowStart: vi.mocked(postWorkflowStart), resolveInput: vi.mocked(resolveInput) };
         };
+        const logged = (cmd) => cmd.log.mock.calls.map(([line]) => line);
         it('threads the resolved catalog to resolveInput and postWorkflowStart', async () => {
             const { cmd, postWorkflowStart, resolveInput } = await createCommand({ catalog: 'my-catalog' });
             resolveInput.mockResolvedValue({ key: 'value' });
@@ -61,9 +130,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 +149,209 @@ 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 }));
+        });
+        describe('--monitor', () => {
+            const startResponse = (data) => ({
+                data, status: 200, headers: new Headers()
+            });
+            it('does not attach when the flag is absent, and keeps the follow-up hints', async () => {
+                const { cmd, postWorkflowStart } = await createCommand();
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: 'run-1' }));
+                await cmd.run();
+                expect(streamWorkflowUpdates).not.toHaveBeenCalled();
+                const printed = logged(cmd).join('\n');
+                expect(printed).toContain('workflow status wf-123');
+                expect(printed).toContain('workflow result wf-123');
+            });
+            it('streams updates pinned to the run it just started', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: 'run-1' }));
+                await cmd.run();
+                expect(streamWorkflowUpdates).toHaveBeenCalledWith(
+                // runId is pinned rather than left undefined so a rapid re-start can't
+                // make the monitor resolve "latest run" to a different execution.
+                expect.objectContaining({ workflowId: 'wf-123', runId: 'run-1', json: false }), expect.objectContaining({ log: expect.any(Function), error: expect.any(Function) }));
+            });
+            it('still returns the start result after monitoring finishes', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: 'run-1' }));
+                await expect(cmd.run()).resolves.toEqual({ workflowId: 'wf-123', runId: 'run-1' });
+            });
+            it('drops the up-front status hint that duplicates what monitoring already does', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: 'run-1' }));
+                await cmd.run();
+                const printed = logged(cmd).join('\n');
+                expect(printed).toContain('Workflow ID: wf-123');
+                expect(printed).not.toContain('workflow status wf-123');
+            });
+            it('points at "workflow result" once monitoring finishes', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: 'run-1' }));
+                vi.mocked(streamWorkflowUpdates).mockResolvedValue('completed');
+                await cmd.run();
+                // The stream reports progress, never the return value, so the command
+                // that fetches it has to be named somewhere.
+                const printed = logged(cmd);
+                expect(printed.at(-1)).toContain('workflow result wf-123');
+            });
+            it('points at "workflow debug" instead when the workflow failed', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: 'run-1' }));
+                vi.mocked(streamWorkflowUpdates).mockResolvedValue('failed');
+                await cmd.run();
+                // A failed run has no result to fetch.
+                const printed = logged(cmd);
+                expect(printed.at(-1)).toContain('workflow debug wf-123');
+                expect(printed.at(-1)).not.toContain('workflow result');
+            });
+            it('adds no follow-up hint when the user detached mid-run', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: 'run-1' }));
+                // Detaching returns no terminal status; the detach message carries its
+                // own hints, so a second one guessing at the outcome would be wrong.
+                vi.mocked(streamWorkflowUpdates).mockResolvedValue(undefined);
+                await cmd.run();
+                const printed = logged(cmd).join('\n');
+                expect(printed).not.toContain('workflow result wf-123');
+                expect(printed).not.toContain('workflow debug wf-123');
+            });
+            it('applies monitor defaults for the passthrough flags left unset', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                const { MONITOR_DEFAULTS } = await import('#utils/monitor_flags.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123' }));
+                await cmd.run();
+                // These carry no oclif default (that would defeat dependsOn), so run() must
+                // supply them — asserted against the shared source rather than re-stating
+                // the literals, which is exactly how the two commands would drift apart.
+                expect(streamWorkflowUpdates).toHaveBeenCalledWith(expect.objectContaining({
+                    interval: MONITOR_DEFAULTS.interval,
+                    color: MONITOR_DEFAULTS.color,
+                    includePayloads: MONITOR_DEFAULTS.includePayloads
+                }), expect.anything());
+            });
+            it('forwards explicit passthrough flag values', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({
+                    monitor: true, interval: 500, color: false, 'include-payloads': true
+                });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123' }));
+                await cmd.run();
+                expect(streamWorkflowUpdates).toHaveBeenCalledWith(expect.objectContaining({ interval: 500, color: false, includePayloads: true }), expect.anything());
+            });
+            it('leaves runId undefined when the API omits it, falling back to the latest run', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123', runId: null }));
+                await cmd.run();
+                expect(streamWorkflowUpdates).toHaveBeenCalledWith(expect.objectContaining({ runId: undefined }), expect.anything());
+            });
+            it('errors instead of monitoring when the API returns no workflow ID', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ runId: 'run-1' }));
+                await expect(cmd.run()).rejects.toThrow();
+                expect(streamWorkflowUpdates).not.toHaveBeenCalled();
+                const [message, options] = cmd.error.mock.calls.at(-1);
+                // The start succeeded — only monitoring is impossible — so this is the
+                // exit-3 case. Exit 1 here would tell a CI job retrying a failed workflow
+                // to re-submit one that is already running.
+                expect(message).toContain('started');
+                expect(message).toContain('cannot be monitored');
+                expect(options).toEqual(expect.objectContaining({ exit: 3 }));
+                // Claiming success and then failing on the next line contradicts itself,
+                // and the "unknown" placeholder id isn't something the user can act on.
+                const printed = logged(cmd).join('\n');
+                expect(printed).not.toContain('Workflow started successfully');
+                expect(printed).not.toContain('unknown');
+            });
+            it('refuses to monitor under --json instead of silently swallowing the stream', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                // CONTENT_TYPE=json enables json mode without --json ever reaching argv,
+                // so oclif's `exclusive` check has nothing to reject — this guard catches it.
+                vi.spyOn(cmd, 'jsonEnabled').mockReturnValue(true);
+                await expect(cmd.run()).rejects.toThrow();
+                expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('Cannot combine --monitor with --json'), expect.objectContaining({ exit: 2 }));
+                expect(postWorkflowStart).not.toHaveBeenCalled();
+                expect(streamWorkflowUpdates).not.toHaveBeenCalled();
+            });
+            // Shaped like the API's real 404 body so the two 404 paths below differ the
+            // way they do in practice: `catch()`'s override replaces the body, while
+            // monitoring has no override and lets the body through.
+            const notFound = () => Object.assign(new Error('not found'), {
+                response: { status: 404, data: { error: 'WorkflowNotFoundError', message: 'Workflow "wf-123" not found' } }
+            });
+            it('blames the workflow name for a 404 raised before monitoring begins', async () => {
+                const { cmd } = await createCommand();
+                await expect(cmd.catch(notFound())).rejects.toThrow();
+                expect(cmd.error).toHaveBeenCalledWith('Workflow not found. Check the workflow name.', expect.objectContaining({ exit: 1 }));
+            });
+            it('reports a monitoring failure as a live workflow, not a failed start', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123' }));
+                vi.mocked(streamWorkflowUpdates).mockRejectedValue(notFound());
+                await expect(cmd.run()).rejects.toThrow();
+                const [message, options] = cmd.error.mock.calls.at(-1);
+                // The workflow started fine, so a 404 here is about the run being polled.
+                // The server's own message surfaces; `workflow monitor`'s "Check the
+                // workflow ID" must not, since this id came back from postWorkflowStart —
+                // it would both misdirect the user and contradict the "still running" line.
+                expect(message).toContain('WorkflowNotFoundError');
+                expect(message).not.toContain('Check the workflow ID');
+                expect(message).toContain('wf-123 started, but monitoring stopped');
+                expect(message).toContain('workflow status wf-123');
+                // Exit 3, not 1: a caller retrying on a failed workflow must not
+                // re-submit one that is already running.
+                expect(options).toEqual(expect.objectContaining({ exit: 3 }));
+            });
+            it('still reports a live workflow when the stream raises its own CLIError', async () => {
+                const { cmd, postWorkflowStart } = await createCommand({ monitor: true });
+                const { streamWorkflowUpdates } = await import('#services/monitor_stream.js');
+                postWorkflowStart.mockResolvedValue(startResponse({ workflowId: 'wf-123' }));
+                // What `io.error` produces — e.g. the continue-as-new branch. run() must
+                // use handleApiError here, not handleCommandError: the latter rethrows a
+                // CLIError untouched, which would surface this as a bare exit 1 and lose
+                // the "still running" message entirely.
+                vi.mocked(streamWorkflowUpdates).mockRejectedValue(new CLIError('Workflow continued as a new run, but the new run ID could not be determined.'));
+                await expect(cmd.run()).rejects.toThrow();
+                const [message, options] = cmd.error.mock.calls.at(-1);
+                expect(message).toContain('wf-123 started, but monitoring stopped');
+                expect(message).toContain('The workflow is still running');
+                expect(options).toEqual(expect.objectContaining({ exit: 3 }));
+            });
+            it('rethrows oclif errors instead of flattening them to exit 1', async () => {
+                const { cmd } = await createCommand();
+                // `catch` re-raising a CLIError through handleApiError would discard both
+                // its exit code (2 for usage, 3 for a dropped stream) and oclif's own
+                // formatted flag-validation output.
+                const usageError = new CLIError('Cannot combine --monitor with --json.', { exit: 2 });
+                await expect(cmd.catch(usageError)).rejects.toBe(usageError);
+                expect(cmd.error).not.toHaveBeenCalled();
+            });
         });
     });
 });

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

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 vi.mock('../../api/generated/api.js', () => ({
     getWorkflowIdStatus: vi.fn(),
     GetWorkflowIdStatus200Status: {
-        canceled: 'canceled',
+        cancelled: 'cancelled',
         completed: 'completed',
         continued_as_new: 'continued_as_new',
         failed: 'failed',

package/dist/commands/workflow/{test_eval.d.ts → test.d.ts}

@@ -1,7 +1,6 @@
 import { Command } from '@oclif/core';
 import type { EvalOutput } from '@outputai/evals';
 export default class WorkflowTest extends Command {
-    static aliases: string[];
     static description: string;
     static enableJsonFlag: boolean;
     static examples: string[];

package/dist/commands/workflow/{test_eval.js → test.js}

@@ -7,7 +7,6 @@ import { diagnoseMissingEvalWorkflow } from '#utils/eval_diagnostics.js';
 import { handleApiError } from '#utils/error_handler.js';
 import { getEvalWorkflowName, renderEvalOutput, computeExitCode, EvalOutputSchema } from '@outputai/evals';
 export default class WorkflowTest extends Command {
-    static aliases = ['workflow:test'];
     static description = 'Run evaluations against a workflow using its datasets';
     static enableJsonFlag = true;
     static examples = [

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

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

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

@@ -45,11 +45,11 @@ describe('workflow test command', () => {
     });
     describe('command definition', () => {
         it('enables the built-in --json flag', async () => {
-            const WorkflowTest = (await import('./test_eval.js')).default;
+            const WorkflowTest = (await import('./test.js')).default;
             expect(WorkflowTest.enableJsonFlag).toBe(true);
         });
         it('binds the catalog flag to OUTPUT_CATALOG_ID', async () => {
-            const WorkflowTest = (await import('./test_eval.js')).default;
+            const WorkflowTest = (await import('./test.js')).default;
             expect(WorkflowTest.flags).toHaveProperty('catalog');
             expect(WorkflowTest.flags.catalog.env).toBe('OUTPUT_CATALOG_ID');
             expect(WorkflowTest.flags.catalog.char).toBe('c');
@@ -57,7 +57,7 @@ describe('workflow test command', () => {
     });
     describe('run()', () => {
         const createCommand = async (jsonEnabled) => {
-            const WorkflowTest = (await import('./test_eval.js')).default;
+            const WorkflowTest = (await import('./test.js')).default;
             const { postWorkflowRun } = await import('#api/generated/api.js');
             const cmd = new WorkflowTest(['simple'], {});
             cmd.log = vi.fn();
@@ -99,7 +99,7 @@ describe('workflow test command', () => {
             expect(process.exitCode).toBe(1);
         });
         it('routes registration, dataset runs, and the eval run to the resolved catalog', async () => {
-            const WorkflowTest = (await import('./test_eval.js')).default;
+            const WorkflowTest = (await import('./test.js')).default;
             const { postWorkflowRun } = await import('#api/generated/api.js');
             const { fetchWorkflowCatalog } = await import('#api/workflow_catalog.js');
             const cmd = new WorkflowTest(['my_workflow'], {});

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.10.1-next.f6a7c1a.0"
+    "framework": "0.11.0"
 }

package/dist/services/docker.d.ts

@@ -24,10 +24,32 @@ export declare class DockerComposeConfigNotFoundError extends Error {
 declare const isDockerInstalled: () => boolean;
 export declare function validateDockerEnvironment(): void;
 export declare function getDefaultDockerComposePath(): string;
+export declare function resolveDockerComposePath(customPath?: string): Promise<string>;
 export declare function parseServiceStatus(jsonOutput: string): ServiceStatus[];
 export declare function getServiceStatus(dockerComposePath: string): Promise<ServiceStatus[]>;
 export declare function isServiceHealthy(service: ServiceStatus): boolean;
 export declare function isServiceFailed(service: ServiceStatus): boolean;
+export declare const STACK_STATE: {
+    /** Nothing live for this project — a fresh start we own. */
+    readonly NONE: "none";
+    /** Every container found is running and healthy (or has no healthcheck). */
+    readonly RUNNING: "running";
+    /** Something is live but not everything is healthy — reconcile. */
+    readonly PARTIAL: "partial";
+};
+export type StackState = typeof STACK_STATE[keyof typeof STACK_STATE];
+/**
+ * Classify the current state of a project's stack from `docker compose ps`.
+ *
+ * This is the detection signal `output dev` branches on: nothing live means a
+ * fresh start; an all-healthy result means we can attach and monitor without
+ * touching the stack; anything in between is reconciled with `up -d`.
+ *
+ * Scoped to the shared `output-sdk` compose project, which distinguishes our
+ * containers from unrelated processes — but not one Output checkout from
+ * another, since the project name defaults to a machine-global constant.
+ */
+export declare function classifyStackState(services: ServiceStatus[]): StackState;
 export declare function waitForServicesHealthy(dockerComposePath: string, timeoutMs?: number, pollIntervalMs?: number): Promise<void>;
 export interface DockerComposeHandlers {
     onError?: (error: Error, output: string) => void;
@@ -39,6 +61,11 @@ export interface StartDockerComposeOptions extends DockerComposeHandlers {
     pullPolicy?: PullPolicy;
 }
 export declare function startDockerCompose({ dockerComposePath, pullPolicy, onError, onExit }: StartDockerComposeOptions): Promise<ChildProcess>;
-export declare function startDockerComposeDetached(dockerComposePath: string, pullPolicy?: PullPolicy): void;
+export interface DetachedUpResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    output: string;
+}
+export declare function runDockerComposeUpDetached(dockerComposePath: string, pullPolicy?: PullPolicy): Promise<DetachedUpResult>;
 export declare function stopDockerCompose(dockerComposePath: string): Promise<void>;
 export { isDockerInstalled, DockerValidationError };