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

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

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

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.10.1-next.09ed166.0"
+    "framework": "0.10.1-next.2cbd0a2.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 };