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

package/dist/services/monitor_stream.spec.js

@@ -0,0 +1,285 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { HttpError } from '#api/http_client.js';
+import { commandStreamIo, monitorErrorOverrides, streamWorkflowUpdates } from './monitor_stream.js';
+vi.mock('#services/workflow_history.js', () => ({ fetchWorkflowHistory: vi.fn(), fetchWorkflowHistoryUpdates: vi.fn() }));
+vi.mock('#utils/sleep.js', () => ({ sleep: vi.fn().mockResolvedValue(undefined) }));
+/**
+ * Direct coverage of the loop now that two commands share it. `monitor.spec.ts`
+ * exercises it end-to-end through `workflow monitor`, and `start.spec.ts` stubs
+ * it out entirely — so what's here is the behavior neither reaches: the return
+ * value both callers branch on, the pre-cursor retry cap, the detach guards, and
+ * the error classification at its edges.
+ */
+const cursor = { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] };
+const history = (status, overrides = {}) => ({
+    workflow: { status },
+    runId: 'run-1',
+    events: [],
+    spans: [],
+    totalDurationMs: 0,
+    continuedAsNewRunId: null,
+    cursor,
+    ...overrides
+});
+const update = (status, overrides = {}) => ({ result: history(status, overrides), cursor });
+const createIo = (errorReturns = false) => ({
+    log: vi.fn(),
+    warn: vi.fn(),
+    // Typed `never` in the interface but nothing enforces that at runtime, which is
+    // exactly what the continue-as-new guard defends against — so both shapes are
+    // constructible here.
+    error: (errorReturns ?
+        vi.fn() :
+        vi.fn((message) => {
+            throw new Error(message);
+        }))
+});
+const options = (overrides = {}) => ({
+    workflowId: 'wf-1',
+    runId: undefined,
+    includePayloads: false,
+    interval: 5000,
+    json: false,
+    color: false,
+    ...overrides
+});
+const flush = () => new Promise(resolve => setImmediate(resolve));
+describe('monitor_stream service', () => {
+    beforeEach(async () => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+        const { sleep } = await import('#utils/sleep.js');
+        vi.mocked(sleep).mockResolvedValue(undefined);
+    });
+    afterEach(() => {
+        process.exitCode = undefined;
+    });
+    const histories = async () => {
+        const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await import('#services/workflow_history.js');
+        return {
+            fetchWorkflowHistory: vi.mocked(fetchWorkflowHistory),
+            fetchWorkflowHistoryUpdates: vi.mocked(fetchWorkflowHistoryUpdates)
+        };
+    };
+    describe('streamWorkflowUpdates() return value', () => {
+        it('returns the terminal status it stopped on so the caller can name a follow-up', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            // `start --monitor` branches on this to print "workflow result" vs
+            // "workflow debug"; a boolean or a throw wouldn't carry enough.
+            expect(await streamWorkflowUpdates(options(), createIo())).toBe('completed');
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('returns a failed status and records exit 1 without throwing', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('failed'));
+            // Not thrown: the caller's own output stays the command's primary result.
+            expect(await streamWorkflowUpdates(options(), createIo())).toBe('failed');
+            expect(process.exitCode).toBe(1);
+        });
+        it('returns undefined when the user detached, so no follow-up is printed', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory.mockResolvedValue(history('running'));
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            vi.mocked(sleep).mockImplementation(async () => {
+                onSpy.mock.calls.find(([event]) => event === 'SIGINT')[1]();
+            });
+            expect(await streamWorkflowUpdates(options(), createIo())).toBeUndefined();
+            await flush();
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+    });
+    describe('retry pacing', () => {
+        it('caps the retry sleep while no cursor is established, ignoring a long --interval', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(history('completed'));
+            await streamWorkflowUpdates(options({ interval: 5000 }), createIo());
+            // Otherwise "the API is down" takes interval x budget to surface — minutes,
+            // for a `workflow monitor` against a server that was never reachable.
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(1000);
+        });
+        it('honors an --interval shorter than the cap rather than slowing the retry down', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(history('completed'));
+            await streamWorkflowUpdates(options({ interval: 250 }), createIo());
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(250);
+        });
+        it('sleeps the full --interval on a retry once a cursor exists', async () => {
+            const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(update('completed'));
+            await streamWorkflowUpdates(options({ interval: 5000 }), createIo());
+            expect(vi.mocked(sleep)).not.toHaveBeenCalledWith(1000);
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(5000);
+        });
+    });
+    describe('transient error classification', () => {
+        const retried = async (error) => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValueOnce(error).mockResolvedValueOnce(history('completed'));
+            const io = createIo();
+            await streamWorkflowUpdates(options(), io);
+            return { calls: fetchWorkflowHistory.mock.calls.length, io };
+        };
+        it.each([
+            ['a 503', new HttpError('Service unavailable', { status: 503 })],
+            ['a 429 rate limit', new HttpError('Too many requests', { status: 429 })],
+            ['a 408 request timeout', new HttpError('Request timeout', { status: 408 })],
+            ['a client-side TimeoutError', Object.assign(new Error('timed out'), { name: 'TimeoutError' })],
+            ['a nested ECONNREFUSED cause', Object.assign(new Error('fetch failed'), { cause: { code: 'ECONNREFUSED' } })],
+            ['a top-level EAI_AGAIN', Object.assign(new Error('dns'), { code: 'EAI_AGAIN' })]
+        ])('retries %s', async (_label, error) => {
+            const { calls, io } = await retried(error);
+            expect(calls).toBe(2);
+            expect(io.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+        });
+        it.each([
+            ['a 404 for a mistyped workflow id', new HttpError('Not found', { status: 404 })],
+            ['a 400 stale resume cursor', new HttpError('Invalid page token', { status: 400 })],
+            ['a bug in the parsing pipeline', new TypeError('spans is not iterable')]
+        ])('surfaces %s immediately instead of burning the retry budget', async (_label, error) => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValue(error);
+            const io = createIo();
+            await expect(streamWorkflowUpdates(options(), io)).rejects.toThrow();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(io.warn).not.toHaveBeenCalled();
+        });
+    });
+    describe('detaching', () => {
+        const detachDuring = async () => {
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            const sigint = () => onSpy.mock.calls.find(([event]) => event === 'SIGINT')[1]();
+            return { onSpy, exitSpy, sigint };
+        };
+        it('swallows a poll failure raised after the user detached instead of racing the exit code', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { onSpy, exitSpy, sigint } = await detachDuring();
+            // The in-flight poll dies because the process is on its way out. Rethrowing
+            // would unwind into `start`'s "monitoring stopped" handler and race exit 3
+            // against the 130 the detach already recorded.
+            fetchWorkflowHistory.mockImplementation(async () => {
+                sigint();
+                throw new Error('socket hang up');
+            });
+            const io = createIo();
+            expect(await streamWorkflowUpdates(options(), io)).toBeUndefined();
+            expect(process.exitCode).toBe(130);
+            expect(io.warn).not.toHaveBeenCalled();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            await flush();
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('ignores a second Ctrl+C while the first is still draining stdout', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const { onSpy, exitSpy, sigint } = await detachDuring();
+            const io = createIo();
+            await streamWorkflowUpdates(options(), io);
+            sigint();
+            // The exit is deferred behind a flush and the listener is still registered,
+            // so an impatient user lands here again before the process is gone.
+            sigint();
+            await flush();
+            const detached = io.log.mock.calls.filter((call) => String(call[0]).includes('Detached'));
+            expect(detached).toHaveLength(1);
+            expect(exitSpy).toHaveBeenCalledTimes(1);
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('removes its SIGINT listener once the loop ends', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const before = process.listenerCount('SIGINT');
+            await streamWorkflowUpdates(options(), createIo());
+            expect(process.listenerCount('SIGINT')).toBe(before);
+        });
+        it('removes its SIGINT listener even when the loop unwinds on an error', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValue(new HttpError('Not found', { status: 404 }));
+            const before = process.listenerCount('SIGINT');
+            await expect(streamWorkflowUpdates(options(), createIo())).rejects.toThrow();
+            expect(process.listenerCount('SIGINT')).toBe(before);
+        });
+    });
+    describe('continue-as-new', () => {
+        it('breaks instead of re-polling forever when the new run id is missing and io.error returns', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValue(history('continued_as_new'));
+            // `io.error` is typed `never`, but an io whose error returns would otherwise
+            // fall through and replay the whole history every interval, forever, with a
+            // zero exit code.
+            const io = createIo(true);
+            expect(await streamWorkflowUpdates(options(), io)).toBeUndefined();
+            expect(io.error).toHaveBeenCalledWith(expect.stringContaining('new run ID could not be determined'));
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+        });
+        it('reports the chained run under the new run id in json mode', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory
+                .mockResolvedValueOnce(history('continued_as_new', { continuedAsNewRunId: 'run-2' }))
+                .mockResolvedValueOnce(history('completed', { runId: 'run-2' }));
+            const io = createIo();
+            await streamWorkflowUpdates(options({ json: true }), io);
+            const lines = io.log.mock.calls.map((call) => JSON.parse(call[0]));
+            expect(lines.some((line) => line.continuedAsNewRunId === 'run-2')).toBe(true);
+            // Every subsequent line carries the run actually being polled, not the one
+            // the stream attached to.
+            expect(lines.at(-1)).toMatchObject({ workflowId: 'wf-1', runId: 'run-2', status: 'completed' });
+        });
+    });
+    describe('commandStreamIo()', () => {
+        it('resolves log/warn at call time so a replaced command method still receives output', async () => {
+            const command = { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+            const io = commandStreamIo(command);
+            // oclif (and the command specs) swap these in as own properties after the
+            // adapter exists, which a `.bind()` at construction time would miss.
+            const replacement = vi.fn();
+            command.log = replacement;
+            io.log('hello');
+            expect(replacement).toHaveBeenCalledWith('hello');
+        });
+        it('raises command errors with an explicit exit 1', () => {
+            const command = { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+            commandStreamIo(command).error('boom');
+            expect(command.error).toHaveBeenCalledWith('boom', { exit: 1 });
+        });
+    });
+    describe('monitorErrorOverrides()', () => {
+        const withResponse = (status, data) => Object.assign(new Error('failed'), { response: { status, data } });
+        it('overrides a 400 the server identifies as a stale resume cursor', () => {
+            expect(monitorErrorOverrides(withResponse(400, { error: 'InvalidPageTokenError' }))).toEqual({
+                400: expect.stringContaining('Resume cursor is no longer valid')
+            });
+        });
+        it('leaves an unrelated 400 alone rather than misdiagnosing it as a stale cursor', () => {
+            // 400 also covers a missing runId and an out-of-range longPollTimeoutMs, whose
+            // real validation messages are more useful than a cursor guess.
+            expect(monitorErrorOverrides(withResponse(400, { error: 'ValidationError' }))).toEqual({});
+            expect(monitorErrorOverrides(withResponse(400))).toEqual({});
+        });
+        it('does not override a 404, which only reads correctly where the user typed the id', () => {
+            // `workflow monitor` adds its own; under `start --monitor` the id came back
+            // from the API, so "check the workflow ID" would misdirect the user.
+            expect(monitorErrorOverrides(withResponse(404))).toEqual({});
+        });
+        it('tolerates an error with no response at all', () => {
+            expect(monitorErrorOverrides(new Error('fetch failed'))).toEqual({});
+        });
+    });
+});

package/dist/services/workflow_history.js

@@ -10,13 +10,13 @@
 import { getWorkflowIdHistory } from '#api/generated/api.js';
 import { correlate, eventAttributes, eventTypeName } from '#services/workflow_history/correlator.js';
 import { normalizeWorkflowStatus } from '#utils/normalize_workflow_status.js';
-import { TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
+import { isTerminalStatus } from '#utils/format_workflow_result.js';
 const PAGE_SIZE = 50;
 // The status here comes from the request's own describe (fresh whenever `wait` is
 // set), so it can report the run closed before the closing event has been paged in.
 function isRunClosed(meta) {
     const status = normalizeWorkflowStatus(meta?.status);
-    return status === 'continued_as_new' || (status !== undefined && TERMINAL_STATUSES.has(status));
+    return status === 'continued_as_new' || isTerminalStatus(status) !== undefined;
 }
 function numericEventId(event) {
     const id = Number(event.eventId);

package/dist/templates/agent_instructions/CLAUDE.md.template

@@ -17,10 +17,12 @@ claude plugin install outputai@outputai --scope project
 npm run output:dev           # Start dev environment (worker + Temporal)
 npm run output:worker:build  # Build TypeScript to dist/
 npm run output:worker:check  # Optional: bundle-check workflows for bad imports (node: built-ins)
-npm run output:worker:watch  # Build + restart on file changes
-npm run output:worker        # Install, build, and start worker
+npm run output:worker:watch  # Build + restart on src/ file changes
+npm run output:worker        # Build and start worker
 ```
 
+Hot-reload watches `src/` only. After changing dependencies (`package.json` / lockfile), run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
+
 ## Project Structure
 
 ```

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

@@ -79,7 +79,9 @@ This starts:
 - Temporal server and UI (http://localhost:8080)
 - PostgreSQL and Redis databases
 - Output.ai API server (http://localhost:3001)
-- Worker process for executing workflows
+- Worker process for executing workflows (auto-reloads on `src/` changes)
+
+Dependency changes (`package.json` / lockfile) are not picked up by hot-reload. Run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
 
 ### 4. Run a workflow
 

package/dist/templates/project/package.json.template

@@ -9,8 +9,8 @@
     "output:worker:build": "rm -rf dist/* && tsc -p ./ && output-copy-assets",
     "output:worker:start": "output-worker",
     "output:worker:check": "output-worker --check",
-    "output:worker": "npm run output:worker:install && npm run output:worker:build && npm run output:worker:start",
-    "output:worker:watch": "npx nodemon --watch src --watch package.json --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
+    "output:worker": "npm run output:worker:build && npm run output:worker:start",
+    "output:worker:watch": "npx nodemon --watch src --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
     "output:dev": "output dev"
   },
   "dependencies": {

package/dist/utils/env_loader.js

@@ -5,7 +5,6 @@
  */
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import * as dotenv from 'dotenv';
 import debugFactory from 'debug';
 const debug = debugFactory('output-cli:env-loader');
 export function loadEnvironment() {
@@ -17,5 +16,10 @@ export function loadEnvironment() {
         return;
     }
     debug(`Loading env from: ${envPath}`);
-    dotenv.config({ path: envPath, quiet: true });
+    try {
+        process.loadEnvFile(envPath);
+    }
+    catch (err) {
+        debug(`Warning: Failed to load env file ${envPath}: ${err}`);
+    }
 }

package/dist/utils/env_loader.spec.js

@@ -1,43 +1,72 @@
-/**
- * Tests for the env loader utility
- */
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import * as dotenv from 'dotenv';
-vi.mock('node:fs');
-vi.mock('dotenv');
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadEnvironment } from './env_loader.js';
 describe('loadEnvironment', () => {
-    const originalEnv = { ...process.env };
-    const mockCwd = '/mock/project';
+    const mockCwd = mkdtempSync(join(tmpdir(), 'output-env-loader-'));
     beforeEach(() => {
-        vi.resetModules();
-        vi.clearAllMocks();
+        for (const name of readdirSync(mockCwd)) {
+            rmSync(join(mockCwd, name), { recursive: true, force: true });
+        }
         vi.spyOn(process, 'cwd').mockReturnValue(mockCwd);
-        vi.spyOn(console, 'log').mockImplementation(() => { });
-        vi.spyOn(console, 'warn').mockImplementation(() => { });
+        vi.stubEnv('OUTPUT_CLI_ENV', undefined);
+        vi.stubEnv('OUTPUT_API_URL', undefined);
+        vi.stubEnv('OUTPUT_API_TOKEN', undefined);
     });
     afterEach(() => {
-        process.env = { ...originalEnv };
         vi.restoreAllMocks();
+        vi.unstubAllEnvs();
     });
-    it('should load from OUTPUT_CLI_ENV when set and file exists', async () => {
-        process.env.OUTPUT_CLI_ENV = '.env.prod';
-        const expectedPath = resolve(mockCwd, '.env.prod');
-        vi.mocked(existsSync).mockReturnValue(true);
-        vi.mocked(dotenv.config).mockReturnValue({ parsed: { OUTPUT_API_URL: 'https://prod.api.com' } });
-        const { loadEnvironment } = await import('./env_loader.js');
+    afterAll(() => {
+        rmSync(mockCwd, { recursive: true, force: true });
+    });
+    it('loads variables from OUTPUT_CLI_ENV', () => {
+        writeFileSync(join(mockCwd, '.env'), [
+            'OUTPUT_API_URL=https://default.api.com',
+            'OUTPUT_API_TOKEN=default-token'
+        ].join('\n'));
+        writeFileSync(join(mockCwd, '.env.mock'), [
+            'OUTPUT_API_URL=https://mock.api.com',
+            'OUTPUT_API_TOKEN=mock-token'
+        ].join('\n'));
+        process.env.OUTPUT_CLI_ENV = '.env.mock';
+        loadEnvironment();
+        expect(process.env.OUTPUT_API_URL).toBe('https://mock.api.com');
+        expect(process.env.OUTPUT_API_TOKEN).toBe('mock-token');
+    });
+    it('loads variables from .env by default', () => {
+        writeFileSync(join(mockCwd, '.env'), [
+            'OUTPUT_API_URL=https://default.api.com',
+            'OUTPUT_API_TOKEN=default-token'
+        ].join('\n'));
+        writeFileSync(join(mockCwd, '.env.mock'), [
+            'OUTPUT_API_URL=https://mock.api.com',
+            'OUTPUT_API_TOKEN=mock-token'
+        ].join('\n'));
         loadEnvironment();
-        expect(dotenv.config).toHaveBeenCalledWith({ path: expectedPath, quiet: true });
-    });
-    it('should load .env by default and log', async () => {
-        delete process.env.OUTPUT_CLI_ENV;
-        const envPath = resolve(mockCwd, '.env');
-        vi.mocked(existsSync).mockImplementation(p => p === envPath);
-        vi.mocked(dotenv.config).mockReturnValue({ parsed: {} });
-        const { loadEnvironment } = await import('./env_loader.js');
+        expect(process.env.OUTPUT_API_URL).toBe('https://default.api.com');
+        expect(process.env.OUTPUT_API_TOKEN).toBe('default-token');
+    });
+    it('does nothing when the env file is missing', () => {
+        expect(() => loadEnvironment()).not.toThrow();
+        expect(process.env.OUTPUT_API_URL).toBeUndefined();
+        expect(process.env.OUTPUT_API_TOKEN).toBeUndefined();
+    });
+    it('does not throw when the env path is not a readable file', () => {
+        mkdirSync(join(mockCwd, 'not-a-file.env'));
+        process.env.OUTPUT_CLI_ENV = 'not-a-file.env';
+        expect(() => loadEnvironment()).not.toThrow();
+        expect(process.env.OUTPUT_API_URL).toBeUndefined();
+    });
+    it('does not overwrite already-set process.env values', () => {
+        vi.stubEnv('OUTPUT_API_URL', 'https://ambient.api.com');
+        writeFileSync(join(mockCwd, '.env'), [
+            'OUTPUT_API_URL=https://file.api.com',
+            'OUTPUT_API_TOKEN=file-token'
+        ].join('\n'));
         loadEnvironment();
-        expect(dotenv.config).toHaveBeenCalledTimes(1);
-        expect(dotenv.config).toHaveBeenCalledWith({ path: envPath, quiet: true });
+        expect(process.env.OUTPUT_API_URL).toBe('https://ambient.api.com');
+        expect(process.env.OUTPUT_API_TOKEN).toBe('file-token');
     });
 });

package/dist/utils/error_handler.d.ts

@@ -5,4 +5,14 @@ type ErrorOverrides = {
 export declare function handleApiError(error: unknown, errorFn: (...args: [message: string, options: {
     exit: number;
 }]) => never, overrides?: ErrorOverrides): never;
+/**
+ * `catch()` handling for a command that raises oclif errors of its own. Flag
+ * relationship failures and every `this.error( ..., { exit } )` already carry an
+ * exit code and formatted output, and `handleApiError` would flatten all of it
+ * to a bare exit 1 — so pass those straight through and only map what actually
+ * came back from the API.
+ */
+export declare function handleCommandError(error: Error, errorFn: (...args: [message: string, options: {
+    exit: number;
+}]) => never, overrides?: ErrorOverrides): never;
 export {};

package/dist/utils/error_handler.js

@@ -1,3 +1,4 @@
+import { CLIError } from '@oclif/core/errors';
 import { config } from '#config.js';
 function getDefaultMessages() {
     return {
@@ -79,3 +80,16 @@ export function handleApiError(error, errorFn, overrides = {}) {
     const detailedMessage = getDetailedErrorMessage(error);
     errorFn(detailedMessage, { exit: 1 });
 }
+/**
+ * `catch()` handling for a command that raises oclif errors of its own. Flag
+ * relationship failures and every `this.error( ..., { exit } )` already carry an
+ * exit code and formatted output, and `handleApiError` would flatten all of it
+ * to a bare exit 1 — so pass those straight through and only map what actually
+ * came back from the API.
+ */
+export function handleCommandError(error, errorFn, overrides = {}) {
+    if (error instanceof CLIError) {
+        throw error;
+    }
+    return handleApiError(error, errorFn, overrides);
+}

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

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

package/dist/utils/error_handler.spec.js

@@ -0,0 +1,62 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi } from 'vitest';
+import { CLIError } from '@oclif/core/errors';
+import { handleApiError, handleCommandError } from './error_handler.js';
+const errorFn = () => vi.fn((message) => {
+    throw new Error(message);
+});
+const apiError = (status, data) => Object.assign(new Error('request failed'), { response: { status, data } });
+describe('handleApiError()', () => {
+    it('prefers a caller override over the server body for the same status', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(404, { error: 'WorkflowNotFoundError', message: 'Workflow "wf-1" not found' }), fn, { 404: 'Workflow not found. Check the workflow ID.' })).toThrow('Workflow not found. Check the workflow ID.');
+    });
+    it('surfaces the server body when no override covers the status', () => {
+        const fn = errorFn();
+        // What `start --monitor` relies on now that it passes no 404 override: the
+        // API's own words, rather than advice about an id the user never typed.
+        expect(() => handleApiError(apiError(404, { error: 'WorkflowNotFoundError', message: 'Workflow "wf-1" not found' }), fn)).toThrow('WorkflowNotFoundError: Workflow "wf-1" not found.');
+    });
+    it('appends a root cause to the server message when the API reports one', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(500, { error: 'StepFailure', message: 'Step failed', rootCause: { error: 'TypeError', message: 'x is not a function' } }), fn)).toThrow(/TypeError: x is not a function/);
+    });
+    it('falls back to the status default when the body carries no detail', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(401), fn)).toThrow(/OUTPUT_API_AUTH_TOKEN/);
+    });
+    it.each([
+        ['a top-level code', Object.assign(new Error('connect'), { code: 'ECONNREFUSED' })],
+        ['a nested cause', Object.assign(new Error('fetch failed'), { cause: { code: 'ECONNREFUSED' } })]
+    ])('reports a refused connection from %s before looking at any status', (_label, error) => {
+        const fn = errorFn();
+        expect(() => handleApiError(error, fn)).toThrow(/Is the API server running\?/);
+    });
+    it('assembles a detailed message when there is no response at all', () => {
+        const fn = errorFn();
+        const error = Object.assign(new Error('fetch failed'), {
+            cause: Object.assign(new Error('getaddrinfo EAI_AGAIN api'), { code: 'EAI_AGAIN', hostname: 'api', port: 3001 })
+        });
+        expect(() => handleApiError(error, fn)).toThrow(/fetch failed \| Cause: getaddrinfo EAI_AGAIN api \| Code: EAI_AGAIN \| Host: api:3001/);
+    });
+    it('always exits 1, leaving a command\'s own exit codes to the command', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(500), fn)).toThrow();
+        expect(fn).toHaveBeenCalledWith(expect.any(String), { exit: 1 });
+    });
+});
+describe('handleCommandError()', () => {
+    it('rethrows an oclif error untouched so its exit code and formatting survive', () => {
+        const fn = errorFn();
+        // `workflow start --monitor` raises exit 2 (bad flag combination) and exit 3
+        // (started but unmonitorable); flattening those to exit 1 would let a CI job
+        // retrying on a failed workflow re-submit one that is already running.
+        const cliError = new CLIError('Cannot combine --monitor with --json', { exit: 2 });
+        expect(() => handleCommandError(cliError, fn)).toThrow(cliError);
+        expect(fn).not.toHaveBeenCalled();
+    });
+    it('maps anything that came back from the API the same way handleApiError does', () => {
+        const fn = errorFn();
+        expect(() => handleCommandError(apiError(404), fn, { 404: 'Workflow not found. Check the workflow name.' })).toThrow('Workflow not found. Check the workflow name.');
+    });
+});

package/dist/utils/format_workflow_result.d.ts

@@ -1,6 +1,18 @@
-import type { WorkflowResultResponse, WorkflowResultResponseStatus } from '../api/generated/api.js';
+import type { WorkflowResultResponse } from '../api/generated/api.js';
 type WorkflowResult = Pick<WorkflowResultResponse, 'workflowId' | 'output' | 'status' | 'error'>;
-export declare const ERROR_STATUSES: ReadonlySet<WorkflowResultResponseStatus | undefined>;
-export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+declare const ERROR_STATUS_VALUES: readonly ["failed", "cancelled", "terminated", "timed_out"];
+export type ErrorStatus = typeof ERROR_STATUS_VALUES[number];
+export type TerminalStatus = 'completed' | ErrorStatus;
+/**
+ * Maps a raw status to a canonical error status, or `undefined` if it is not one.
+ * Legacy spellings (`canceled`) are normalized so callers only ever see the
+ * current API vocabulary — until `normalizeWorkflowStatus` is removed.
+ */
+export declare function isErrorStatus(status: string | null | undefined): ErrorStatus | undefined;
+/**
+ * Maps a raw status to a canonical terminal status, or `undefined` if it is not
+ * one. Same normalization contract as `isErrorStatus`.
+ */
+export declare function isTerminalStatus(status: string | null | undefined): TerminalStatus | undefined;
 export declare function formatWorkflowResult(result: WorkflowResult): string;
 export {};