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

package/dist/services/docker.js

@@ -1,9 +1,12 @@
 import { execFileSync, execSync, spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ux } from '@oclif/core';
 import semver from 'semver';
 import { config } from '#config.js';
+import { getErrorMessage } from '#utils/error_utils.js';
+import { formatComposeFailure } from '#utils/port_collision.js';
 const DEFAULT_COMPOSE_PATH = '../assets/docker/docker-compose-dev.yml';
 export const SERVICE_HEALTH = {
     HEALTHY: 'healthy',
@@ -83,6 +86,22 @@ export function validateDockerEnvironment() {
 export function getDefaultDockerComposePath() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), DEFAULT_COMPOSE_PATH);
 }
+// Resolve the compose file a `dev` command should act on — a caller-supplied
+// path (relative to cwd) or the bundled default — and verify it exists. Shared
+// by `dev` and `dev down` so the resolution rule and not-found error stay in
+// one place.
+export async function resolveDockerComposePath(customPath) {
+    const dockerComposePath = customPath ?
+        path.resolve(process.cwd(), customPath) :
+        getDefaultDockerComposePath();
+    try {
+        await fs.access(dockerComposePath);
+    }
+    catch {
+        throw new DockerComposeConfigNotFoundError(dockerComposePath);
+    }
+    return dockerComposePath;
+}
 export function parseServiceStatus(jsonOutput) {
     if (!jsonOutput.trim()) {
         return [];
@@ -118,6 +137,37 @@ export function isServiceHealthy(service) {
 export function isServiceFailed(service) {
     return service.state === SERVICE_STATE.EXITED || service.health === SERVICE_HEALTH.UNHEALTHY;
 }
+export const STACK_STATE = {
+    /** Nothing live for this project — a fresh start we own. */
+    NONE: 'none',
+    /** Every container found is running and healthy (or has no healthcheck). */
+    RUNNING: 'running',
+    /** Something is live but not everything is healthy — reconcile. */
+    PARTIAL: 'partial'
+};
+/**
+ * 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 function classifyStackState(services) {
+    // No container is live. `ps --all` also reports exited ones, so a stack left
+    // behind by a reboot, a `docker compose stop`, or a failed teardown lands
+    // here — that's an owned fresh start, not something to attach to.
+    if (!services.some(service => service.state === SERVICE_STATE.RUNNING)) {
+        return STACK_STATE.NONE;
+    }
+    if (services.every(isServiceHealthy)) {
+        return STACK_STATE.RUNNING;
+    }
+    return STACK_STATE.PARTIAL;
+}
 export async function waitForServicesHealthy(dockerComposePath, timeoutMs = 120000, pollIntervalMs = 2000) {
     const startTime = Date.now();
     while (Date.now() - startTime < timeoutMs) {
@@ -129,6 +179,18 @@ export async function waitForServicesHealthy(dockerComposePath, timeoutMs = 1200
     }
     throw new Error('Timeout waiting for services to become healthy');
 }
+// A rolling buffer that retains the last ~20k chars of a spawned process's
+// combined output, so a startup failure can surface recent Docker logs without
+// holding the whole stream. Shared by the two compose spawn sites.
+function createOutputBuffer() {
+    const buffer = { value: '' };
+    return {
+        append: (chunk) => {
+            buffer.value = `${buffer.value}${chunk.toString()}`.slice(-20000).trimStart();
+        },
+        read: () => buffer.value.trimEnd()
+    };
+}
 export async function startDockerCompose({ dockerComposePath, pullPolicy, onError, onExit }) {
     const args = [
         'compose',
@@ -140,29 +202,34 @@ export async function startDockerCompose({ dockerComposePath, pullPolicy, onErro
     if (pullPolicy) {
         args.push('--pull', pullPolicy);
     }
-    const output = {
-        value: ''
-    };
-    const appendOutput = (chunk) => {
-        output.value = `${output.value}${chunk.toString()}`.slice(-20000).trimStart();
-    };
+    const output = createOutputBuffer();
     const dockerProcess = spawn('docker', args, {
         cwd: process.cwd(),
         // The Ink dev UI owns the terminal. Drain compose output so Docker cannot
         // block on a full pipe, while keeping recent output for startup failures.
         stdio: ['ignore', 'pipe', 'pipe']
     });
-    dockerProcess.stdout?.on('data', appendOutput);
-    dockerProcess.stderr?.on('data', appendOutput);
+    dockerProcess.stdout?.on('data', output.append);
+    dockerProcess.stderr?.on('data', output.append);
     if (onError) {
-        dockerProcess.on('error', error => onError(error, output.value.trimEnd()));
+        dockerProcess.on('error', error => onError(error, output.read()));
     }
     if (onExit) {
-        dockerProcess.on('exit', (code, signal) => onExit(code, signal, output.value.trimEnd()));
+        // `close` rather than `exit` so stdio has drained — the buffered output is
+        // what formatComposeFailure greps for a bind failure.
+        dockerProcess.on('close', (code, signal) => onExit(code, signal, output.read()));
     }
     return dockerProcess;
 }
-export function startDockerComposeDetached(dockerComposePath, pullPolicy) {
+// Run `docker compose up -d` to completion, teeing Docker's progress to the
+// user's terminal while retaining recent output. The predecessor used
+// execFileSync with inherited stdio, which threw a raw compose error the caller
+// couldn't inspect; returning the exit code and output lets it surface a
+// port-collision hint instead. Async so image pulls don't block the event loop.
+//
+// Trade-off: piping means Docker sees a non-TTY and drops its redrawing
+// progress bars for plain scrolling lines.
+export function runDockerComposeUpDetached(dockerComposePath, pullPolicy) {
     const args = [
         'compose',
         '-f', dockerComposePath,
@@ -173,7 +240,34 @@ export function startDockerComposeDetached(dockerComposePath, pullPolicy) {
     if (pullPolicy) {
         args.push('--pull', pullPolicy);
     }
-    execFileSync('docker', args, { stdio: 'inherit', cwd: process.cwd() });
+    const output = createOutputBuffer();
+    return new Promise((resolve, reject) => {
+        // Pipe rather than inherit so we can both echo Docker's progress and keep
+        // recent output for a startup-failure hint.
+        const child = spawn('docker', args, {
+            cwd: process.cwd(),
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        child.stdout?.on('data', (chunk) => {
+            process.stdout.write(chunk);
+            output.append(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            process.stderr.write(chunk);
+            output.append(chunk);
+        });
+        // `error` fires when the spawn itself failed (docker missing, EACCES).
+        // Reject with the buffered output attached so the caller keeps the context
+        // rather than surfacing a bare `spawn docker ENOENT`.
+        child.on('error', error => {
+            reject(new Error(formatComposeFailure(getErrorMessage(error), output.read(), config.ports)));
+        });
+        // `close`, not `exit`: exit fires while stdio may still be draining, and on
+        // a fast-failing `up -d` — exactly the bind-collision case — the stderr
+        // chunk carrying the bind error can land after it. Resolving early makes
+        // the port-collision hint disappear intermittently.
+        child.on('close', (code, signal) => resolve({ code, signal, output: output.read() }));
+    });
 }
 export async function stopDockerCompose(dockerComposePath) {
     ux.stdout('⏹️  Stopping services...\n');

package/dist/services/docker.spec.js

@@ -1,11 +1,16 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { execFileSync, spawn } from 'node:child_process';
-import { parseServiceStatus, getServiceStatus, startDockerCompose, startDockerComposeDetached, stopDockerCompose, waitForServicesHealthy, isServiceHealthy, isServiceFailed } from './docker.js';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parseServiceStatus, getServiceStatus, startDockerCompose, runDockerComposeUpDetached, stopDockerCompose, waitForServicesHealthy, isServiceHealthy, isServiceFailed, classifyStackState, STACK_STATE, resolveDockerComposePath, getDefaultDockerComposePath, DockerComposeConfigNotFoundError } from './docker.js';
 vi.mock('node:child_process', () => ({
     execSync: vi.fn(),
     execFileSync: vi.fn(),
     spawn: vi.fn()
 }));
+vi.mock('node:fs/promises', () => ({
+    default: { access: vi.fn() }
+}));
 const mockChildProcess = (process) => process;
 vi.mock('log-update', () => {
     const fn = vi.fn();
@@ -155,7 +160,7 @@ describe('docker service', () => {
                 onExit
             });
             expect(dockerProcess.on).toHaveBeenCalledWith('error', expect.any(Function));
-            expect(dockerProcess.on).toHaveBeenCalledWith('exit', expect.any(Function));
+            expect(dockerProcess.on).toHaveBeenCalledWith('close', expect.any(Function));
             streamHandlers.stdout?.(Buffer.from('starting services\n'));
             streamHandlers.stderr?.(Buffer.from('compose failed\n'));
             const error = new Error('Docker failed');
@@ -165,26 +170,99 @@ describe('docker service', () => {
             expect(onExit).toHaveBeenCalledWith(1, null, 'starting services\ncompose failed');
         });
     });
-    describe('startDockerComposeDetached', () => {
-        it('should pass --project-name and -d to docker compose up', () => {
-            vi.mocked(execFileSync).mockReturnValue('');
-            startDockerComposeDetached('/path/to/docker-compose.yml');
-            expect(execFileSync).toHaveBeenCalledWith('docker', [
+    describe('runDockerComposeUpDetached', () => {
+        const makeProcess = () => {
+            const handlers = {};
+            const proc = {
+                on: vi.fn((event, handler) => {
+                    if (event === 'error') {
+                        handlers.error = handler;
+                    }
+                    else {
+                        handlers.exit = handler;
+                    }
+                    return proc;
+                }),
+                stdout: {
+                    on: vi.fn((event, handler) => {
+                        handlers.stdout = handler;
+                        return proc.stdout;
+                    })
+                },
+                stderr: {
+                    on: vi.fn((event, handler) => {
+                        handlers.stderr = handler;
+                        return proc.stderr;
+                    })
+                }
+            };
+            return { proc, handlers };
+        };
+        it('passes --project-name and -d, tees output, and resolves with the exit code', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            const stdoutSpy = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
                 '--project-name', 'output-sdk',
                 'up', '-d'
-            ], expect.objectContaining({ stdio: 'inherit', cwd: process.cwd() }));
-        });
-        it('should append --pull when pullPolicy is provided', () => {
-            vi.mocked(execFileSync).mockReturnValue('');
-            startDockerComposeDetached('/path/to/docker-compose.yml', 'missing');
-            expect(execFileSync).toHaveBeenCalledWith('docker', [
+            ], expect.objectContaining({ cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] }));
+            handlers.stdout?.(Buffer.from('pulling images\n'));
+            handlers.exit?.(0);
+            expect(await promise).toEqual({ code: 0, output: 'pulling images' });
+            expect(stdoutSpy).toHaveBeenCalledWith(Buffer.from('pulling images\n'));
+            stdoutSpy.mockRestore();
+        });
+        it('appends --pull when pullPolicy is provided', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml', 'missing');
+            handlers.exit?.(0);
+            await promise;
+            expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
                 '--project-name', 'output-sdk',
                 'up', '-d', '--pull', 'missing'
-            ], expect.objectContaining({ stdio: 'inherit', cwd: process.cwd() }));
+            ], expect.objectContaining({ cwd: process.cwd() }));
+        });
+        it('resolves with a non-zero code and captured stderr so the caller can hint the collision', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            handlers.stderr?.(Buffer.from('Error: address already in use\n'));
+            handlers.exit?.(1);
+            expect(await promise).toEqual({ code: 1, output: 'Error: address already in use' });
+        });
+        it('rejects when the docker process fails to spawn', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            handlers.error?.(new Error('spawn ENOENT'));
+            await expect(promise).rejects.toThrow('spawn ENOENT');
+        });
+    });
+    describe('resolveDockerComposePath', () => {
+        it('resolves a custom path against cwd and returns it when it exists', async () => {
+            vi.mocked(fs.access).mockResolvedValue(undefined);
+            const result = await resolveDockerComposePath('custom/compose.yml');
+            const expected = path.resolve(process.cwd(), 'custom/compose.yml');
+            expect(result).toBe(expected);
+            expect(fs.access).toHaveBeenCalledWith(expected);
+        });
+        it('throws DockerComposeConfigNotFoundError when the path does not exist', async () => {
+            vi.mocked(fs.access).mockRejectedValue(new Error('ENOENT'));
+            await expect(resolveDockerComposePath('missing.yml'))
+                .rejects.toBeInstanceOf(DockerComposeConfigNotFoundError);
+        });
+        it('falls back to the bundled default when no custom path is given', async () => {
+            vi.mocked(fs.access).mockResolvedValue(undefined);
+            const result = await resolveDockerComposePath();
+            expect(result).toBe(getDefaultDockerComposePath());
         });
     });
     describe('DOCKER_SERVICE_NAME wiring', () => {
@@ -259,6 +337,58 @@ describe('docker service', () => {
             expect(isServiceFailed({ name: 'temporal', state: 'running', health: 'starting', ports: [] })).toBe(false);
         });
     });
+    describe('classifyStackState', () => {
+        const svc = (state, health) => ({ name: 's', state, health, ports: [] });
+        it('returns NONE for an empty stack (fresh start)', () => {
+            expect(classifyStackState([])).toBe(STACK_STATE.NONE);
+        });
+        it('returns RUNNING when every service is up and healthy', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('running', 'none')
+            ])).toBe(STACK_STATE.RUNNING);
+        });
+        it('returns PARTIAL when any service has failed (orphaned stack)', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        it('returns PARTIAL when services exist but some are still coming up', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('created', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        it('treats an unhealthy service as PARTIAL, not RUNNING', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('running', 'unhealthy')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        // `ps --all` reports exited containers, so a stack stopped by a reboot, a
+        // `docker compose stop`, or a failed teardown still has rows. Nothing is
+        // live, so this invocation would be the one starting it — that makes it an
+        // owned fresh start, not an attach.
+        it('returns NONE when every service is exited — an owned fresh start, not an attach', () => {
+            expect(classifyStackState([
+                svc('exited', 'none'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.NONE);
+        });
+        it('returns NONE when containers are created but none have started', () => {
+            expect(classifyStackState([
+                svc('created', 'none'),
+                svc('created', 'none')
+            ])).toBe(STACK_STATE.NONE);
+        });
+        it('still returns PARTIAL when at least one service is live', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+    });
     describe('waitForServicesHealthy', () => {
         it('should resolve when all services are healthy', async () => {
             const mockOutput = `{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}

package/dist/services/monitor_stream.d.ts

@@ -0,0 +1,62 @@
+import { type TerminalStatus } from '#utils/format_workflow_result.js';
+export type MonitorStreamOptions = {
+    workflowId: string;
+    runId?: string;
+    includePayloads: boolean;
+    interval: number;
+    json: boolean;
+    color: boolean;
+};
+/**
+ * The command surface the stream needs, kept as a parameter rather than a
+ * `Command` instance so `workflow start --monitor` can reuse the loop without
+ * constructing (or delegating to) a second oclif command — the repo has no
+ * `runCommand` precedent and `Command.run( argv, config )` would need a real
+ * oclif `Config` that unit tests don't have. `error` must be typed `never` so
+ * callers keep type narrowing after an error branch.
+ */
+export type MonitorStreamIo = {
+    log: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => never;
+};
+/**
+ * Adapts an oclif command to the above. Late-bound arrows rather than
+ * `command.log.bind( command )`: oclif (and the unit tests) replace these as own
+ * properties on the instance, so they must resolve at call time. Structurally
+ * typed so a test double satisfies it without a real oclif `Config`.
+ */
+export declare function commandStreamIo(command: {
+    log: (message: string) => void;
+    warn: (message: string) => unknown;
+    error: (message: string, options: {
+        exit: number;
+    }) => never;
+}): MonitorStreamIo;
+/**
+ * Polls a workflow run and emits status updates until it reaches a terminal
+ * state, following continue-as-new chains. Shared by `workflow monitor` and
+ * `workflow start --monitor` so both behave identically; see `MonitorStreamIo`
+ * for why output is injected rather than taken from a `Command`.
+ *
+ * Sets `process.exitCode = 1` on a terminal error status rather than throwing,
+ * so the caller's own output (e.g. `start`'s "Workflow started successfully")
+ * is still the command's primary result. Returns the terminal status it stopped
+ * on — `undefined` if it stopped because the user detached — so a caller can
+ * tailor its own follow-up (`workflow result` vs `workflow debug`).
+ */
+export declare function streamWorkflowUpdates(options: MonitorStreamOptions, io: MonitorStreamIo): Promise<TerminalStatus | undefined>;
+/**
+ * Shared `catch` handling for both entry points. A 400 is the generic status for
+ * several distinct causes (invalid pageToken, a missing runId, an out-of-range
+ * longPollTimeoutMs) — only override it with the stale-cursor message when the
+ * server actually identifies that specific cause; otherwise let the real
+ * validation error surface instead of misdiagnosing an unrelated 400.
+ *
+ * Deliberately no 404 here: "check the workflow ID" only reads correctly where
+ * the user typed the id, so `workflow monitor` adds it and `start --monitor`
+ * doesn't — there the id came back from `postWorkflowStart`, and the server's own
+ * message is left to surface inside the "started, but monitoring stopped" wrapper
+ * instead of advising a fix that isn't the user's to make.
+ */
+export declare function monitorErrorOverrides(error: Error): Record<number, string>;