@outputai/cli 0.5.2-next.75f5eed.0 → 0.5.2-next.93dd22e.0

package/dist/assets/docker/docker-compose-dev.yml

@@ -43,9 +43,12 @@ services:
       - POSTGRES_USER=temporal
       - POSTGRES_PWD=temporal
       - POSTGRES_SEEDS=postgresql
+      - DEFAULT_NAMESPACE_RETENTION=720h
     image: temporalio/auto-setup:latest
     networks:
       - main
+    ports:
+      - '${OUTPUT_TEMPORAL_HOST_PORT:-7233}:7233'
     healthcheck:
       test:
         [
@@ -77,7 +80,7 @@ services:
         condition: service_healthy
       worker:
         condition: service_healthy
-    image: outputai/api:${OUTPUT_API_VERSION:-0.5.2-next.75f5eed.0}
+    image: outputai/api:${OUTPUT_API_VERSION:-0.5.2-next.93dd22e.0}
     init: true
     networks:
       - main

package/dist/commands/dev/index.js

@@ -5,6 +5,8 @@ import { render } from 'ink';
 import React from 'react';
 import { validateDockerEnvironment, startDockerCompose, startDockerComposeDetached, stopDockerCompose, DockerComposeConfigNotFoundError, getDefaultDockerComposePath } from '#services/docker.js';
 import { getErrorMessage } from '#utils/error_utils.js';
+import { formatPortCollisionHint, formatPortCollisionsHint } from '#utils/port_collision.js';
+import { findUnavailablePorts } from '#utils/port_availability.js';
 import { ensureClaudePlugin } from '#services/coding_agents.js';
 import { DevApp } from '#views/dev/dev_app.js';
 import { config } from '#config.js';
@@ -15,7 +17,8 @@ export default class Dev extends Command {
         'To run a second dev stack concurrently, override host ports in .env:',
         '',
         '  OUTPUT_API_HOST_PORT=3002',
-        '  OUTPUT_TEMPORAL_UI_HOST_PORT=8081'
+        '  OUTPUT_TEMPORAL_UI_HOST_PORT=8081',
+        '  OUTPUT_TEMPORAL_HOST_PORT=7234'
     ].join('\n');
     static examples = [
         '<%= config.bin %> <%= command.id %>',
@@ -48,6 +51,13 @@ export default class Dev extends Command {
         validateDockerEnvironment();
         // Eagerly resolve ports so InvalidPortError surfaces before Ink mounts.
         void config.ports;
+        // Probe each published host port before docker runs. docker compose up
+        // doesn't exit on partial container failure, so a bind collision would
+        // otherwise leave the Ink TUI in limbo with no actionable feedback.
+        const takenPorts = await findUnavailablePorts(Object.values(config.ports));
+        if (takenPorts.length > 0) {
+            this.error(formatPortCollisionsHint(takenPorts, config.ports), { exit: 1 });
+        }
         const dockerComposePath = flags['compose-file'] ?
             path.resolve(process.cwd(), flags['compose-file']) :
             getDefaultDockerComposePath();
@@ -137,8 +147,10 @@ export default class Dev extends Command {
                         return;
                     }
                     const exitReason = signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`;
+                    const hint = formatPortCollisionHint(output, config.ports);
+                    const prefix = hint ? `${hint}\n\n` : '';
                     const detail = output ? `\n\nRecent Docker output:\n${output}` : '';
-                    instance.unmount(new Error(`Docker compose exited with ${exitReason}.${detail}`));
+                    instance.unmount(new Error(`${prefix}Docker compose exited with ${exitReason}.${detail}`));
                 }
             });
             this.dockerProcess = dockerProc;

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

@@ -5,10 +5,14 @@ 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';
+import * as portAvailability from '#utils/port_availability.js';
 import Dev from './index.js';
 vi.mock('#services/coding_agents.js', () => ({
     ensureClaudePlugin: vi.fn().mockResolvedValue(undefined)
 }));
+vi.mock('#utils/port_availability.js', () => ({
+    findUnavailablePorts: vi.fn().mockResolvedValue([])
+}));
 vi.mock('#services/docker.js', () => ({
     validateDockerEnvironment: vi.fn(),
     startDockerCompose: vi.fn(),
@@ -82,6 +86,8 @@ describe('dev command', () => {
         vi.clearAllMocks();
         // By default, docker validation succeeds
         vi.mocked(dockerService.validateDockerEnvironment).mockResolvedValue(undefined);
+        // By default, no host port is taken — individual tests opt in.
+        vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([]);
         // By default, startDockerCompose returns a mock process
         vi.mocked(dockerService.startDockerCompose).mockResolvedValue(createMockDockerProcess());
         // By default, fs.access succeeds (file exists)
@@ -223,6 +229,42 @@ describe('dev command', () => {
             cmd.error = vi.fn();
             await expect(cmd.run()).rejects.toThrow();
         });
+        it('aborts with an actionable hint before docker runs when a host port is already taken', async () => {
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001]);
+            const cmd = new Dev([], {});
+            cmd.log = vi.fn();
+            cmd.error = vi.fn(() => {
+                throw new Error('oclif-error-thrown');
+            });
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({ flags: { 'compose-file': undefined, 'image-pull-policy': 'always' }, args: {} }),
+                configurable: true
+            });
+            await expect(cmd.run()).rejects.toThrow();
+            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('Port 3001 is already in use.'), { exit: 1 });
+            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('OUTPUT_API_HOST_PORT=<other port>'), { exit: 1 });
+            expect(dockerService.startDockerCompose).not.toHaveBeenCalled();
+            expect(render).not.toHaveBeenCalled();
+        });
+        it('lists every taken port when multiple collide, not just the first', async () => {
+            vi.mocked(portAvailability.findUnavailablePorts).mockResolvedValue([3001, 7233]);
+            const cmd = new Dev([], {});
+            cmd.log = vi.fn();
+            cmd.error = vi.fn(() => {
+                throw new Error('oclif-error-thrown');
+            });
+            Object.defineProperty(cmd, 'parse', {
+                value: vi.fn().mockResolvedValue({ flags: { 'compose-file': undefined, 'image-pull-policy': 'always' }, args: {} }),
+                configurable: true
+            });
+            await expect(cmd.run()).rejects.toThrow();
+            const [message] = vi.mocked(cmd.error).mock.calls[0];
+            expect(message).toContain('Multiple host ports are already in use:');
+            expect(message).toContain('• Port 3001 — override with OUTPUT_API_HOST_PORT=<other port>');
+            expect(message).toContain('• Port 7233 — override with OUTPUT_TEMPORAL_HOST_PORT=<other port>');
+            expect(dockerService.startDockerCompose).not.toHaveBeenCalled();
+            expect(render).not.toHaveBeenCalled();
+        });
         it('should handle startDockerCompose errors', async () => {
             vi.mocked(dockerService.startDockerCompose).mockRejectedValue(new Error('Docker error'));
             const cmd = new Dev([], {});
@@ -250,12 +292,14 @@ describe('dev command', () => {
             });
             const runPromise = cmd.run();
             await new Promise(resolve => setImmediate(resolve));
-            getStartDockerComposeOptions().onExit?.(1, null, 'failed to bind host port');
+            getStartDockerComposeOptions().onExit?.(1, null, 'Bind for 0.0.0.0:3001 failed: port is already allocated');
             await runPromise;
             expect(inkInstance.unmount).toHaveBeenCalledWith(expect.objectContaining({
                 message: expect.stringContaining('Docker compose exited with code 1')
             }));
-            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('Recent Docker output:\nfailed to bind host port'), { exit: 1 });
+            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('Recent Docker output:\nBind for 0.0.0.0:3001 failed'), { exit: 1 });
+            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('Port 3001 is already in use.'), { exit: 1 });
+            expect(cmd.error).toHaveBeenCalledWith(expect.stringContaining('OUTPUT_API_HOST_PORT=<other port>'), { exit: 1 });
         });
         it('should ignore docker compose exits triggered by cleanup', async () => {
             const dockerProcess = createMockDockerProcess();

package/dist/config.d.ts

@@ -2,6 +2,7 @@ export declare const config: {
     readonly apiUrl: string;
     readonly ports: {
         temporalUi: number;
+        temporal: number;
         api: number;
     };
     readonly temporalUiUrl: string;

package/dist/config.js

@@ -1,6 +1,7 @@
 import { parsePort } from '#utils/validation.js';
 const DEFAULT_API_PORT = 3001;
 const DEFAULT_TEMPORAL_UI_PORT = 8080;
+const DEFAULT_TEMPORAL_PORT = 7233;
 export const config = {
     get apiUrl() {
         return process.env.OUTPUT_API_URL || `http://localhost:${this.ports.api}`;
@@ -8,6 +9,7 @@ export const config = {
     get ports() {
         return {
             temporalUi: parsePort(process.env.OUTPUT_TEMPORAL_UI_HOST_PORT, DEFAULT_TEMPORAL_UI_PORT, 'OUTPUT_TEMPORAL_UI_HOST_PORT'),
+            temporal: parsePort(process.env.OUTPUT_TEMPORAL_HOST_PORT, DEFAULT_TEMPORAL_PORT, 'OUTPUT_TEMPORAL_HOST_PORT'),
             api: parsePort(process.env.OUTPUT_API_HOST_PORT, DEFAULT_API_PORT, 'OUTPUT_API_HOST_PORT')
         };
     },

package/dist/config.spec.js

@@ -6,6 +6,7 @@ describe('config', () => {
         'OUTPUT_API_URL',
         'OUTPUT_API_HOST_PORT',
         'OUTPUT_TEMPORAL_UI_HOST_PORT',
+        'OUTPUT_TEMPORAL_HOST_PORT',
         'OUTPUT_API_AUTH_TOKEN',
         'DOCKER_SERVICE_NAME',
         'OUTPUT_DEBUG',
@@ -41,11 +42,12 @@ describe('config', () => {
         delete process.env.OUTPUT_API_URL;
         delete process.env.OUTPUT_API_HOST_PORT;
         delete process.env.OUTPUT_TEMPORAL_UI_HOST_PORT;
+        delete process.env.OUTPUT_TEMPORAL_HOST_PORT;
         delete process.env.DOCKER_SERVICE_NAME;
         delete process.env.OUTPUT_DEBUG;
         delete process.env.OUTPUT_CLI_ENV;
         expect(config.apiUrl).toBe('http://localhost:3001');
-        expect(config.ports).toEqual({ temporalUi: 8080, api: 3001 });
+        expect(config.ports).toEqual({ temporalUi: 8080, temporal: 7233, api: 3001 });
         expect(config.temporalUiUrl).toBe('http://localhost:8080');
         expect(config.dockerServiceName).toBe('output-sdk');
         expect(config.debugMode).toBe(false);
@@ -68,18 +70,24 @@ describe('config', () => {
     });
     it('reads port overrides from env vars', () => {
         process.env.OUTPUT_TEMPORAL_UI_HOST_PORT = '8081';
+        process.env.OUTPUT_TEMPORAL_HOST_PORT = '7234';
         process.env.OUTPUT_API_HOST_PORT = '3002';
-        expect(config.ports).toEqual({ temporalUi: 8081, api: 3002 });
+        expect(config.ports).toEqual({ temporalUi: 8081, temporal: 7234, api: 3002 });
         expect(config.temporalUiUrl).toBe('http://localhost:8081');
     });
     it('treats empty-string port env vars as unset (matches Compose semantics)', () => {
         delete process.env.OUTPUT_API_URL;
         process.env.OUTPUT_API_HOST_PORT = '';
         process.env.OUTPUT_TEMPORAL_UI_HOST_PORT = '';
+        process.env.OUTPUT_TEMPORAL_HOST_PORT = '';
         expect(config.apiUrl).toBe('http://localhost:3001');
-        expect(config.ports).toEqual({ temporalUi: 8080, api: 3001 });
+        expect(config.ports).toEqual({ temporalUi: 8080, temporal: 7233, api: 3001 });
         expect(config.temporalUiUrl).toBe('http://localhost:8080');
     });
+    it('throws InvalidPortError on invalid OUTPUT_TEMPORAL_HOST_PORT', () => {
+        process.env.OUTPUT_TEMPORAL_HOST_PORT = 'not-a-port';
+        expect(() => config.ports).toThrow(InvalidPortError);
+    });
     it('throws InvalidPortError on non-numeric port values', () => {
         delete process.env.OUTPUT_API_URL;
         process.env.OUTPUT_API_HOST_PORT = 'abc';

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.5.2-next.75f5eed.0"
+    "framework": "0.5.2-next.93dd22e.0"
 }

package/dist/templates/project/.env.example.template

@@ -12,6 +12,7 @@ OPENAI_API_KEY=credential:openai.api_key
 # at temporal:7233) is unaffected.
 # OUTPUT_API_HOST_PORT=3001
 # OUTPUT_TEMPORAL_UI_HOST_PORT=8080
+# OUTPUT_TEMPORAL_HOST_PORT=7233
 
 # --- API connection ---
 # If OUTPUT_API_URL is set, it overrides OUTPUT_API_HOST_PORT.

package/dist/utils/port_availability.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Probe each port by attempting to bind a TCP server on `0.0.0.0`. Returns
+ * all ports that are currently in use (listening with `EADDRINUSE` errors).
+ *
+ * This function checks multiple ports concurrently and filters to return only
+ * those that are unavailable. Docker remains the ultimate decider for
+ * ambiguous cases during actual compose up.
+ */
+export declare function findUnavailablePorts(ports: number[]): Promise<number[]>;

package/dist/utils/port_availability.js

@@ -0,0 +1,40 @@
+import net from 'node:net';
+/**
+ * Check if a specific port is taken by attempting to bind a TCP server.
+ *
+ * Binds on `0.0.0.0` (not loopback) to match the publish address docker
+ * compose uses for `${PORT}:${TARGET}` mappings. Errors other than `EADDRINUSE`
+ * are treated as "free" so we don't abort on conditions docker would accept.
+ */
+function isPortTaken(port) {
+    return new Promise(resolve => {
+        const server = net.createServer();
+        const settle = (value) => {
+            server.removeAllListeners();
+            if (value) {
+                resolve(true);
+                return;
+            }
+            server.close(() => resolve(false));
+        };
+        server.once('error', (err) => {
+            settle(err.code === 'EADDRINUSE');
+        });
+        server.once('listening', () => {
+            settle(false);
+        });
+        server.listen(port, '0.0.0.0');
+    });
+}
+/**
+ * Probe each port by attempting to bind a TCP server on `0.0.0.0`. Returns
+ * all ports that are currently in use (listening with `EADDRINUSE` errors).
+ *
+ * This function checks multiple ports concurrently and filters to return only
+ * those that are unavailable. Docker remains the ultimate decider for
+ * ambiguous cases during actual compose up.
+ */
+export async function findUnavailablePorts(ports) {
+    const results = await Promise.all(ports.map(async (port) => ({ port, taken: await isPortTaken(port) })));
+    return results.filter(r => r.taken).map(r => r.port);
+}

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

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

package/dist/utils/port_availability.spec.js

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import net from 'node:net';
+import { findUnavailablePorts } from './port_availability.js';
+/**
+ * Open a real TCP server on an ephemeral port and return the bound port plus
+ * a close helper. We can't hard-code a "known free" port for testing because
+ * any port we pick could be taken on the dev machine — letting the OS hand
+ * out an ephemeral one keeps the test deterministic across environments.
+ */
+function listenOnEphemeralPort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once('error', reject);
+        server.listen(0, '0.0.0.0', () => {
+            const address = server.address();
+            if (typeof address !== 'object' || address === null) {
+                reject(new Error('failed to resolve ephemeral port address'));
+                return;
+            }
+            resolve({
+                port: address.port,
+                close: () => new Promise(resolveClose => server.close(() => resolveClose()))
+            });
+        });
+    });
+}
+describe('findUnavailablePorts', () => {
+    const fixture = { occupied: null };
+    beforeEach(async () => {
+        fixture.occupied = await listenOnEphemeralPort();
+    });
+    afterEach(async () => {
+        if (fixture.occupied) {
+            await fixture.occupied.close();
+            fixture.occupied = null;
+        }
+    });
+    it('returns an empty array when given no ports', async () => {
+        expect(await findUnavailablePorts([])).toEqual([]);
+    });
+    it('returns the occupied port when it is the only one probed', async () => {
+        expect(await findUnavailablePorts([fixture.occupied.port])).toEqual([fixture.occupied.port]);
+    });
+    it('returns all occupied ports, not just the first one', async () => {
+        const second = await listenOnEphemeralPort();
+        try {
+            const free = await listenOnEphemeralPort();
+            await free.close();
+            const result = await findUnavailablePorts([fixture.occupied.port, free.port, second.port]);
+            expect(result.sort()).toEqual([fixture.occupied.port, second.port].sort());
+        }
+        finally {
+            await second.close();
+        }
+    });
+    it('returns an empty array when every probed port is free', async () => {
+        const free = await listenOnEphemeralPort();
+        const port = free.port;
+        await free.close();
+        expect(await findUnavailablePorts([port])).toEqual([]);
+    });
+});

package/dist/utils/port_collision.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Parse docker compose stderr for host-port bind failures and turn them into
+ * an actionable hint that names the conflicting port and the env var to
+ * override.
+ *
+ * Docker compose surfaces port collisions through two common error shapes:
+ *   - "Bind for 0.0.0.0:3001 failed: port is already allocated"
+ *   - "failed to bind host port for 0.0.0.0:7233:.../tcp: address already in use"
+ *
+ * We match both, extract the host port, then map it back to the env var that
+ * sets it. The map prefers a runtime lookup of resolved ports (so a user who
+ * already set OUTPUT_API_HOST_PORT=3050 sees that var named when 3050
+ * collides) and falls back to a default-port table for the unresolved case.
+ */
+/**
+ * Find the first host port mentioned in a docker compose bind failure.
+ * Returns null when no recognized pattern matches.
+ */
+export declare function extractCollidedPort(stderr: string): number | null;
+/**
+ * Build an actionable, multi-line hint for the first port collision found in
+ * stderr. Returns null when no collision is detected. When the colliding port
+ * is one we own (api / temporalUi / temporal), the hint names the env var
+ * that overrides it; otherwise it suggests freeing the port.
+ */
+export declare function formatPortCollisionHint(stderr: string, resolvedPorts: Record<string, number>): string | null;
+/**
+ * Build a hint from a known list of colliding ports. For a single collision
+ * the output matches `formatPortCollisionHint` exactly so callers stay
+ * symmetric. For multiple collisions a bulleted list is rendered, each line
+ * naming the env var that overrides that specific port (or a generic
+ * suggestion when the port isn't one we own).
+ */
+export declare function formatPortCollisionsHint(ports: number[], resolvedPorts: Record<string, number>): string;

package/dist/utils/port_collision.js

@@ -0,0 +1,112 @@
+/**
+ * Parse docker compose stderr for host-port bind failures and turn them into
+ * an actionable hint that names the conflicting port and the env var to
+ * override.
+ *
+ * Docker compose surfaces port collisions through two common error shapes:
+ *   - "Bind for 0.0.0.0:3001 failed: port is already allocated"
+ *   - "failed to bind host port for 0.0.0.0:7233:.../tcp: address already in use"
+ *
+ * We match both, extract the host port, then map it back to the env var that
+ * sets it. The map prefers a runtime lookup of resolved ports (so a user who
+ * already set OUTPUT_API_HOST_PORT=3050 sees that var named when 3050
+ * collides) and falls back to a default-port table for the unresolved case.
+ */
+const PORT_BIND_PATTERNS = [
+    /Bind for [^:\s]+:(\d+) failed: port is already allocated/,
+    /failed to bind host port for [^:\s]+:(\d+)[^]*?address already in use/,
+    /listen tcp [^:\s]+:(\d+):\s*bind: address already in use/
+];
+const DEFAULT_PORT_TO_ENV_VAR = {
+    3001: 'OUTPUT_API_HOST_PORT',
+    8080: 'OUTPUT_TEMPORAL_UI_HOST_PORT',
+    7233: 'OUTPUT_TEMPORAL_HOST_PORT'
+};
+const RESOLVED_PORT_KEY_TO_ENV_VAR = {
+    api: 'OUTPUT_API_HOST_PORT',
+    temporalUi: 'OUTPUT_TEMPORAL_UI_HOST_PORT',
+    temporal: 'OUTPUT_TEMPORAL_HOST_PORT'
+};
+/**
+ * Find the first host port mentioned in a docker compose bind failure.
+ * Returns null when no recognized pattern matches.
+ */
+export function extractCollidedPort(stderr) {
+    if (!stderr) {
+        return null;
+    }
+    for (const pattern of PORT_BIND_PATTERNS) {
+        const match = stderr.match(pattern);
+        if (match) {
+            return parseInt(match[1], 10);
+        }
+    }
+    return null;
+}
+/**
+ * Map a host port to the env var that controls it. Resolved ports win over
+ * the static default map so user-overridden ports still resolve to the right
+ * var. Returns null when the port isn't owned by any of our services.
+ */
+function envVarForPort(port, resolvedPorts) {
+    for (const [key, value] of Object.entries(resolvedPorts)) {
+        if (value === port && RESOLVED_PORT_KEY_TO_ENV_VAR[key]) {
+            return RESOLVED_PORT_KEY_TO_ENV_VAR[key];
+        }
+    }
+    return DEFAULT_PORT_TO_ENV_VAR[port] ?? null;
+}
+/**
+ * Render a single port collision as two lines: the "Port N is already in use"
+ * statement and either an env-var override suggestion or a generic "stop the
+ * process" fallback.
+ */
+function formatSingleCollision(port, resolvedPorts) {
+    const envVar = envVarForPort(port, resolvedPorts);
+    if (envVar) {
+        return [
+            `Port ${port} is already in use.`,
+            `Override it in your .env file:  ${envVar}=<other port>`
+        ].join('\n');
+    }
+    return [
+        `Port ${port} is already in use.`,
+        'Stop the process holding it, or change the host port in your compose file.'
+    ].join('\n');
+}
+/**
+ * Build an actionable, multi-line hint for the first port collision found in
+ * stderr. Returns null when no collision is detected. When the colliding port
+ * is one we own (api / temporalUi / temporal), the hint names the env var
+ * that overrides it; otherwise it suggests freeing the port.
+ */
+export function formatPortCollisionHint(stderr, resolvedPorts) {
+    const port = extractCollidedPort(stderr);
+    if (port === null) {
+        return null;
+    }
+    return formatSingleCollision(port, resolvedPorts);
+}
+/**
+ * Build a hint from a known list of colliding ports. For a single collision
+ * the output matches `formatPortCollisionHint` exactly so callers stay
+ * symmetric. For multiple collisions a bulleted list is rendered, each line
+ * naming the env var that overrides that specific port (or a generic
+ * suggestion when the port isn't one we own).
+ */
+export function formatPortCollisionsHint(ports, resolvedPorts) {
+    if (ports.length === 0) {
+        return '';
+    }
+    if (ports.length === 1) {
+        return formatSingleCollision(ports[0], resolvedPorts);
+    }
+    const lines = ['Multiple host ports are already in use:'];
+    for (const port of ports) {
+        const envVar = envVarForPort(port, resolvedPorts);
+        lines.push(envVar ?
+            `  • Port ${port} — override with ${envVar}=<other port>` :
+            `  • Port ${port} — stop the process holding it`);
+    }
+    return lines.join('\n');
+}

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

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

package/dist/utils/port_collision.spec.js

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { extractCollidedPort, formatPortCollisionHint, formatPortCollisionsHint } from './port_collision.js';
+const DEFAULT_PORTS = { api: 3001, temporalUi: 8080, temporal: 7233 };
+describe('extractCollidedPort', () => {
+    it('matches the "Bind for ... port is already allocated" shape', () => {
+        expect(extractCollidedPort('Bind for 0.0.0.0:3001 failed: port is already allocated')).toBe(3001);
+    });
+    it('matches the "failed to bind host port ... address already in use" shape', () => {
+        const stderr = 'Error: failed to bind host port for 0.0.0.0:7233:172.17.0.2:7233/tcp: address already in use';
+        expect(extractCollidedPort(stderr)).toBe(7233);
+    });
+    it('matches the "listen tcp ... bind: address already in use" shape', () => {
+        expect(extractCollidedPort('listen tcp 127.0.0.1:8080: bind: address already in use')).toBe(8080);
+    });
+    it('returns the first port when stderr contains multiple bind failures', () => {
+        const stderr = [
+            'Bind for 0.0.0.0:3001 failed: port is already allocated',
+            'Bind for 0.0.0.0:8080 failed: port is already allocated'
+        ].join('\n');
+        expect(extractCollidedPort(stderr)).toBe(3001);
+    });
+    it('returns null when no bind failure is present', () => {
+        expect(extractCollidedPort('some unrelated stderr line')).toBeNull();
+    });
+    it('returns null for empty input', () => {
+        expect(extractCollidedPort('')).toBeNull();
+    });
+});
+describe('formatPortCollisionHint', () => {
+    it('names the env var when the colliding port matches a default', () => {
+        const hint = formatPortCollisionHint('Bind for 0.0.0.0:3001 failed: port is already allocated', DEFAULT_PORTS);
+        expect(hint).toContain('Port 3001 is already in use.');
+        expect(hint).toContain('OUTPUT_API_HOST_PORT=<other port>');
+    });
+    it('names the env var for Temporal gRPC collisions', () => {
+        const hint = formatPortCollisionHint('failed to bind host port for 0.0.0.0:7233:172.17.0.2:7233/tcp: address already in use', DEFAULT_PORTS);
+        expect(hint).toContain('OUTPUT_TEMPORAL_HOST_PORT=<other port>');
+    });
+    it('resolves an overridden port back to its env var', () => {
+        const hint = formatPortCollisionHint('Bind for 0.0.0.0:3050 failed: port is already allocated', { ...DEFAULT_PORTS, api: 3050 });
+        expect(hint).toContain('OUTPUT_API_HOST_PORT=<other port>');
+    });
+    it('falls back to a generic suggestion for unknown ports', () => {
+        const hint = formatPortCollisionHint('Bind for 0.0.0.0:5432 failed: port is already allocated', DEFAULT_PORTS);
+        expect(hint).toContain('Port 5432 is already in use.');
+        expect(hint).not.toContain('OUTPUT_');
+        expect(hint).toContain('Stop the process holding it');
+    });
+    it('returns null when stderr has no recognizable bind failure', () => {
+        expect(formatPortCollisionHint('compose succeeded then exited', DEFAULT_PORTS)).toBeNull();
+    });
+    it('returns null for empty stderr', () => {
+        expect(formatPortCollisionHint('', DEFAULT_PORTS)).toBeNull();
+    });
+});
+describe('formatPortCollisionsHint', () => {
+    it('returns an empty string when no ports collide', () => {
+        expect(formatPortCollisionsHint([], DEFAULT_PORTS)).toBe('');
+    });
+    it('matches the single-port hint when exactly one port collides', () => {
+        const list = formatPortCollisionsHint([3001], DEFAULT_PORTS);
+        const single = formatPortCollisionHint('Bind for 0.0.0.0:3001 failed: port is already allocated', DEFAULT_PORTS);
+        expect(list).toBe(single);
+    });
+    it('renders a bulleted list with one line per port when multiple collide', () => {
+        const hint = formatPortCollisionsHint([3001, 7233], DEFAULT_PORTS);
+        expect(hint).toContain('Multiple host ports are already in use:');
+        expect(hint).toContain('• Port 3001 — override with OUTPUT_API_HOST_PORT=<other port>');
+        expect(hint).toContain('• Port 7233 — override with OUTPUT_TEMPORAL_HOST_PORT=<other port>');
+    });
+    it('preserves the order of ports as supplied', () => {
+        const hint = formatPortCollisionsHint([7233, 3001], DEFAULT_PORTS);
+        const lines = hint.split('\n');
+        expect(lines[1]).toContain('Port 7233');
+        expect(lines[2]).toContain('Port 3001');
+    });
+    it('falls back to a generic suggestion for unknown ports inside a list', () => {
+        const hint = formatPortCollisionsHint([3001, 5432], DEFAULT_PORTS);
+        expect(hint).toContain('• Port 3001 — override with OUTPUT_API_HOST_PORT=<other port>');
+        expect(hint).toContain('• Port 5432 — stop the process holding it');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/cli",
-  "version": "0.5.2-next.75f5eed.0",
+  "version": "0.5.2-next.93dd22e.0",
   "description": "CLI for Output.ai workflow generation",
   "type": "module",
   "main": "dist/index.js",
@@ -36,9 +36,9 @@
     "semver": "7.7.4",
     "undici": "8.1.0",
     "yaml": "^2.8.3",
-    "@outputai/credentials": "0.5.2-next.75f5eed.0",
-    "@outputai/llm": "0.5.2-next.75f5eed.0",
-    "@outputai/evals": "0.5.2-next.75f5eed.0"
+    "@outputai/credentials": "0.5.2-next.93dd22e.0",
+    "@outputai/evals": "0.5.2-next.93dd22e.0",
+    "@outputai/llm": "0.5.2-next.93dd22e.0"
   },
   "devDependencies": {
     "@types/cli-progress": "3.11.6",