@outputai/cli 0.2.1-next.bd54540.0 → 0.2.1-next.e1a91cf.0

package/dist/hooks/init.spec.js

@@ -1,9 +1,13 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { checkForUpdate } from '#services/version_check.js';
+import { setNonInteractive } from '#utils/interactive.js';
 vi.mock('#services/version_check.js', () => ({
     checkForUpdate: vi.fn()
 }));
+vi.mock('#utils/interactive.js', () => ({
+    setNonInteractive: vi.fn()
+}));
 vi.mock('@oclif/core', () => ({
     ux: {
         stdout: vi.fn(),
@@ -11,7 +15,7 @@ vi.mock('@oclif/core', () => ({
     }
 }));
 import { ux } from '@oclif/core';
-import hook from './init.js';
+import hook, { hasInteractiveFlag, stripGlobalFlags } from './init.js';
 describe('init hook', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -26,7 +30,7 @@ describe('init hook', () => {
             latestVersion: '1.0.0'
         });
         const ctx = createHookContext();
-        await hook.call(ctx, {});
+        await hook.call(ctx, { argv: [], id: undefined });
         expect(checkForUpdate).toHaveBeenCalledWith('0.8.4', '/tmp/test-cache');
         expect(ux.stdout).toHaveBeenCalled();
         const output = vi.mocked(ux.stdout).mock.calls.map(c => c[0]).join('\n');
@@ -42,13 +46,83 @@ describe('init hook', () => {
             latestVersion: '0.8.4'
         });
         const ctx = createHookContext();
-        await hook.call(ctx, {});
+        await hook.call(ctx, { argv: [], id: undefined });
         expect(ux.stdout).not.toHaveBeenCalled();
     });
     it('should silently handle errors', async () => {
         vi.mocked(checkForUpdate).mockRejectedValue(new Error('network failure'));
         const ctx = createHookContext();
-        await hook.call(ctx, {});
+        await hook.call(ctx, { argv: [], id: undefined });
         expect(ux.stdout).not.toHaveBeenCalled();
     });
+    describe('global interactive flags', () => {
+        const originalArgv = process.argv;
+        beforeEach(() => {
+            vi.mocked(checkForUpdate).mockResolvedValue({
+                updateAvailable: false,
+                currentVersion: '0.8.4',
+                latestVersion: '0.8.4'
+            });
+        });
+        afterEach(() => {
+            process.argv = originalArgv;
+        });
+        it('should mutate opts.argv in place to strip --yes', async () => {
+            process.argv = ['node', 'run.js', 'init', '--yes', 'my-project'];
+            const optsArgv = ['--yes', 'my-project'];
+            const argvRef = optsArgv;
+            const ctx = createHookContext();
+            await hook.call(ctx, { argv: optsArgv, id: 'init' });
+            expect(setNonInteractive).toHaveBeenCalledWith(true);
+            expect(optsArgv).toBe(argvRef);
+            expect(optsArgv).toEqual(['my-project']);
+            expect(process.argv).toEqual(['node', 'run.js', 'init', 'my-project']);
+        });
+        it('should mutate opts.argv in place to strip --non-interactive', async () => {
+            process.argv = ['node', 'run.js', 'init', '--non-interactive'];
+            const optsArgv = ['--non-interactive'];
+            const ctx = createHookContext();
+            await hook.call(ctx, { argv: optsArgv, id: 'init' });
+            expect(setNonInteractive).toHaveBeenCalledWith(true);
+            expect(optsArgv).toEqual([]);
+            expect(process.argv).toEqual(['node', 'run.js', 'init']);
+        });
+        it('should leave argv untouched when no global flag is present', async () => {
+            process.argv = ['node', 'run.js', 'init', '--skip-env'];
+            const optsArgv = ['--skip-env'];
+            const ctx = createHookContext();
+            await hook.call(ctx, { argv: optsArgv, id: 'init' });
+            expect(setNonInteractive).not.toHaveBeenCalled();
+            expect(optsArgv).toEqual(['--skip-env']);
+            expect(process.argv).toEqual(['node', 'run.js', 'init', '--skip-env']);
+        });
+    });
+    describe('hasInteractiveFlag', () => {
+        it('returns true when --yes is present', () => {
+            expect(hasInteractiveFlag(['init', '--yes', 'foo'])).toBe(true);
+        });
+        it('returns true when --non-interactive is present', () => {
+            expect(hasInteractiveFlag(['--non-interactive'])).toBe(true);
+        });
+        it('returns false for unrelated flags', () => {
+            expect(hasInteractiveFlag(['init', '--skip-env', '--skip-git'])).toBe(false);
+        });
+        it('returns false for an empty argv', () => {
+            expect(hasInteractiveFlag([])).toBe(false);
+        });
+    });
+    describe('stripGlobalFlags', () => {
+        it('mutates argv in place to remove global flags', () => {
+            const argv = ['init', '--yes', 'foo', '--non-interactive'];
+            const ref = argv;
+            stripGlobalFlags(argv);
+            expect(argv).toBe(ref);
+            expect(argv).toEqual(['init', 'foo']);
+        });
+        it('leaves argv untouched when no global flag is present', () => {
+            const argv = ['init', '--skip-env'];
+            stripGlobalFlags(argv);
+            expect(argv).toEqual(['init', '--skip-env']);
+        });
+    });
 });

package/dist/services/docker.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ux } from '@oclif/core';
 import semver from 'semver';
+import { config } from '#config.js';
 const DEFAULT_COMPOSE_PATH = '../assets/docker/docker-compose-dev.yml';
 export const SERVICE_HEALTH = {
     HEALTHY: 'healthy',
@@ -100,7 +101,7 @@ export function parseServiceStatus(jsonOutput) {
     });
 }
 export async function getServiceStatus(dockerComposePath) {
-    const result = execFileSync('docker', ['compose', '-f', dockerComposePath, 'ps', '--all', '--format', 'json'], { encoding: 'utf-8', cwd: process.cwd() });
+    const result = execFileSync('docker', ['compose', '-f', dockerComposePath, '--project-name', config.dockerServiceName, 'ps', '--all', '--format', 'json'], { encoding: 'utf-8', cwd: process.cwd() });
     return parseServiceStatus(result);
 }
 export function isServiceHealthy(service) {
@@ -126,6 +127,7 @@ export async function startDockerCompose(dockerComposePath, pullPolicy) {
         'compose',
         '-f', dockerComposePath,
         '--project-directory', process.cwd(),
+        '--project-name', config.dockerServiceName,
         'up'
     ];
     if (pullPolicy) {
@@ -143,6 +145,7 @@ export function startDockerComposeDetached(dockerComposePath, pullPolicy) {
         'compose',
         '-f', dockerComposePath,
         '--project-directory', process.cwd(),
+        '--project-name', config.dockerServiceName,
         'up', '-d'
     ];
     if (pullPolicy) {
@@ -152,6 +155,6 @@ export function startDockerComposeDetached(dockerComposePath, pullPolicy) {
 }
 export async function stopDockerCompose(dockerComposePath) {
     ux.stdout('⏹️  Stopping services...\n');
-    execFileSync('docker', ['compose', '-f', dockerComposePath, 'down'], { stdio: 'inherit', cwd: process.cwd() });
+    execFileSync('docker', ['compose', '-f', dockerComposePath, '--project-directory', process.cwd(), '--project-name', config.dockerServiceName, 'down'], { stdio: 'inherit', cwd: process.cwd() });
 }
 export { isDockerInstalled, DockerValidationError };

package/dist/services/docker.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { execFileSync } from 'node:child_process';
-import { parseServiceStatus, getServiceStatus, waitForServicesHealthy, isServiceHealthy, isServiceFailed } from './docker.js';
+import { execFileSync, spawn } from 'node:child_process';
+import { parseServiceStatus, getServiceStatus, startDockerCompose, startDockerComposeDetached, stopDockerCompose, waitForServicesHealthy, isServiceHealthy, isServiceFailed } from './docker.js';
 vi.mock('node:child_process', () => ({
     execSync: vi.fn(),
     execFileSync: vi.fn(),
@@ -73,7 +73,7 @@ describe('docker service', () => {
             const mockOutput = '{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}';
             vi.mocked(execFileSync).mockReturnValue(mockOutput);
             await getServiceStatus('/path/to/docker-compose.yml');
-            expect(execFileSync).toHaveBeenCalledWith('docker', ['compose', '-f', '/path/to/docker-compose.yml', 'ps', '--all', '--format', 'json'], expect.objectContaining({ encoding: 'utf-8' }));
+            expect(execFileSync).toHaveBeenCalledWith('docker', ['compose', '-f', '/path/to/docker-compose.yml', '--project-name', 'output-sdk', 'ps', '--all', '--format', 'json'], expect.objectContaining({ encoding: 'utf-8' }));
         });
         it('should return parsed service status', async () => {
             const mockOutput = '{"Service":"redis","State":"running","Health":"healthy","Publishers":[{"PublishedPort":6379,"TargetPort":6379}]}';
@@ -89,6 +89,77 @@ describe('docker service', () => {
             await expect(getServiceStatus('/path/to/docker-compose.yml')).rejects.toThrow();
         });
     });
+    describe('startDockerCompose', () => {
+        it('should pass --project-name to docker compose up', async () => {
+            await startDockerCompose('/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'
+            ], expect.objectContaining({ stdio: ['ignore', 'pipe', 'pipe'], cwd: process.cwd() }));
+        });
+        it('should append --pull when pullPolicy is provided', async () => {
+            await startDockerCompose('/path/to/docker-compose.yml', 'always');
+            expect(spawn).toHaveBeenCalledWith('docker', [
+                'compose', '-f', '/path/to/docker-compose.yml',
+                '--project-directory', process.cwd(),
+                '--project-name', 'output-sdk',
+                'up', '--pull', 'always'
+            ], expect.objectContaining({ stdio: ['ignore', 'pipe', 'pipe'], cwd: process.cwd() }));
+        });
+    });
+    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', [
+                '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', [
+                '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() }));
+        });
+    });
+    describe('DOCKER_SERVICE_NAME wiring', () => {
+        const saved = process.env.DOCKER_SERVICE_NAME;
+        afterEach(() => {
+            if (saved === undefined) {
+                delete process.env.DOCKER_SERVICE_NAME;
+            }
+            else {
+                process.env.DOCKER_SERVICE_NAME = saved;
+            }
+        });
+        it('threads DOCKER_SERVICE_NAME through to --project-name (not hardcoded output-sdk)', async () => {
+            process.env.DOCKER_SERVICE_NAME = 'custom-project';
+            vi.mocked(execFileSync).mockReturnValue('');
+            await stopDockerCompose('/path/to/docker-compose.yml');
+            expect(execFileSync).toHaveBeenCalledWith('docker', [
+                'compose', '-f', '/path/to/docker-compose.yml',
+                '--project-directory', process.cwd(),
+                '--project-name', 'custom-project',
+                'down'
+            ], expect.objectContaining({ stdio: 'inherit' }));
+        });
+    });
+    describe('stopDockerCompose', () => {
+        it('should pass --project-name and --project-directory to docker compose down', async () => {
+            vi.mocked(execFileSync).mockReturnValue('');
+            await stopDockerCompose('/path/to/docker-compose.yml');
+            expect(execFileSync).toHaveBeenCalledWith('docker', ['compose', '-f', '/path/to/docker-compose.yml', '--project-directory', process.cwd(), '--project-name', 'output-sdk', 'down'], expect.objectContaining({ stdio: 'inherit' }));
+        });
+    });
     describe('isServiceHealthy', () => {
         it('should return true for a running service with health: healthy', () => {
             expect(isServiceHealthy({ name: 'redis', state: 'running', health: 'healthy', ports: [] })).toBe(true);

package/dist/services/messages.js

@@ -2,6 +2,7 @@
  * Success and informational messages for project initialization
  */
 import { ux } from '@oclif/core';
+import { config } from '#config.js';
 /**
  * Creates a colored ASCII art banner for Output.ai
  */
@@ -180,7 +181,7 @@ export const getProjectSuccessMessage = (folderName, installSuccess, credentials
         note: 'Execute in a new terminal after services are running'
     }, {
         step: 'Monitor workflows',
-        command: 'open http://localhost:8080',
+        command: `open ${config.temporalUiUrl}`,
         note: 'Access Temporal UI for workflow visualization'
     });
     // Format each step with proper indentation and colors

package/dist/services/project_scaffold.d.ts

@@ -27,5 +27,5 @@ export declare function createSigintHandler(projectPath: string, folderCreated:
  * @param skipEnv - Whether to skip environment configuration prompts
  * @param folderName - Optional folder name to skip folder name prompt
  */
-export declare function runInit(skipEnv?: boolean, folderName?: string): Promise<void>;
+export declare function runInit(skipEnv?: boolean, skipGit?: boolean, folderName?: string): Promise<void>;
 export {};

package/dist/services/project_scaffold.js

@@ -119,6 +119,18 @@ async function executeNpmInstall(projectPath) {
 async function initializeAgents(projectPath) {
     await initializeAgentConfig({ projectRoot: projectPath, force: false });
 }
+async function maybeInitializeGit(projectPath) {
+    const shouldInit = await confirm({
+        message: 'Initialize a git repository?',
+        default: true
+    });
+    if (!shouldInit) {
+        return false;
+    }
+    return executeCommandWithMessages(async () => {
+        await executeCommand('git', ['init'], projectPath);
+    }, 'Initializing git repository...', 'Git repository initialized');
+}
 /**
  * Format error message for init errors
  * Single responsibility: only format error messages, no cleanup logic
@@ -172,7 +184,7 @@ function handleRunInitError(error, projectPath, projectFolderCreated) {
  * @param skipEnv - Whether to skip environment configuration prompts
  * @param folderName - Optional folder name to skip folder name prompt
  */
-export async function runInit(skipEnv = false, folderName) {
+export async function runInit(skipEnv = false, skipGit = false, folderName) {
     // Track state for SIGINT cleanup using an object to avoid let
     const state = {
         projectFolderCreated: false,
@@ -210,6 +222,9 @@ export async function runInit(skipEnv = false, folderName) {
         await fs.copyFile(path.join(config.projectPath, '.env.example'), path.join(config.projectPath, '.env'));
         await executeCommandWithMessages(() => initializeAgents(config.projectPath), 'Initializing agent system...', 'Agent system initialized');
         const installSuccess = await executeCommandWithMessages(() => executeNpmInstall(config.projectPath), 'Installing dependencies...', 'Dependencies installed');
+        if (!skipGit) {
+            await maybeInitializeGit(config.projectPath);
+        }
         const nextSteps = getProjectSuccessMessage(config.folderName, installSuccess, credentialsConfigured);
         ux.stdout('Project created successfully!');
         ux.stdout(nextSteps);

package/dist/services/workflow_runs.d.ts

@@ -9,6 +9,7 @@ export interface WorkflowRunsResult {
 }
 export interface FetchWorkflowRunsOptions {
     workflowType?: string;
+    catalog?: string;
     limit?: number;
 }
 export declare function fetchWorkflowRuns(options?: FetchWorkflowRunsOptions): Promise<WorkflowRunsResult>;

package/dist/services/workflow_runs.js

@@ -10,6 +10,9 @@ export async function fetchWorkflowRuns(options = {}) {
     if (options.workflowType) {
         params.workflowType = options.workflowType;
     }
+    if (options.catalog) {
+        params.catalog = options.catalog;
+    }
     const response = await getWorkflowRuns(params);
     if (!response) {
         throw new Error('Failed to connect to API server. Is it running?');

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

@@ -7,3 +7,20 @@ ANTHROPIC_API_KEY=credential:anthropic.api_key
 # Configure if you plan to use OpenAI in your LLM prompts
 OPENAI_API_KEY=credential:openai.api_key
 
+# --- Host port overrides (for running multiple dev stacks) ---
+# Only the host-side port changes; inter-service traffic (e.g. worker -> Temporal
+# at temporal:7233) is unaffected.
+# OUTPUT_API_HOST_PORT=3001
+# OUTPUT_TEMPORAL_UI_HOST_PORT=8080
+
+# --- API connection ---
+# If OUTPUT_API_URL is set, it overrides OUTPUT_API_HOST_PORT.
+# Use OUTPUT_API_URL for remote/staging servers; use OUTPUT_API_HOST_PORT for local port shifts.
+# OUTPUT_API_URL=http://localhost:3001
+
+# --- Project isolation ---
+# Compose prefixes named volumes with the project name, so changing
+# DOCKER_SERVICE_NAME creates fresh volumes and leaves the previous ones behind.
+# Run `docker volume ls --filter name=<old-project-name>` to find orphaned
+# volumes and `docker volume rm` to remove them.
+

package/dist/utils/credentials_loader.d.ts

@@ -0,0 +1 @@
+export declare const loadCredentialRefs: () => void;

package/dist/utils/credentials_loader.js

@@ -0,0 +1,18 @@
+import { InvalidCredentialsKeyError, MalformedCredentialsKeyError, MissingKeyError, resolveCredentialRefs } from '@outputai/credentials';
+const isCredentialsConfigError = (error) => error instanceof MissingKeyError ||
+    error instanceof InvalidCredentialsKeyError ||
+    error instanceof MalformedCredentialsKeyError;
+export const loadCredentialRefs = () => {
+    try {
+        resolveCredentialRefs();
+    }
+    catch (error) {
+        if (isCredentialsConfigError(error)) {
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+        else {
+            throw error;
+        }
+    }
+};

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

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

package/dist/utils/credentials_loader.spec.js

@@ -0,0 +1,84 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as credentials from '@outputai/credentials';
+import { loadCredentialRefs } from './credentials_loader.js';
+vi.mock('@outputai/credentials', async () => {
+    const actual = await vi.importActual('@outputai/credentials');
+    return {
+        ...actual,
+        resolveCredentialRefs: vi.fn()
+    };
+});
+describe('loadCredentialRefs', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('should call resolveCredentialRefs without errors when no credentials are misconfigured', () => {
+        vi.mocked(credentials.resolveCredentialRefs).mockReturnValue([]);
+        expect(() => loadCredentialRefs()).not.toThrow();
+        expect(credentials.resolveCredentialRefs).toHaveBeenCalledTimes(1);
+    });
+    it('should print a clean error message and exit on MissingKeyError without dumping a stack trace', () => {
+        vi.mocked(credentials.resolveCredentialRefs).mockImplementation(() => {
+            throw new credentials.MissingKeyError();
+        });
+        const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+        loadCredentialRefs();
+        expect(consoleErrorSpy).toHaveBeenCalledTimes(1);
+        const printedMessage = consoleErrorSpy.mock.calls[0]?.[0];
+        expect(printedMessage).toContain('No credentials key found');
+        expect(printedMessage).toContain('OUTPUT_CREDENTIALS_KEY');
+        expect(printedMessage).toContain('config/credentials.key');
+        expect(printedMessage).not.toContain('    at ');
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+    it('should include the environment-specific hints in the printed message when an environment is set', () => {
+        vi.mocked(credentials.resolveCredentialRefs).mockImplementation(() => {
+            throw new credentials.MissingKeyError('production');
+        });
+        const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+        loadCredentialRefs();
+        const printedMessage = consoleErrorSpy.mock.calls[0]?.[0];
+        expect(printedMessage).toContain('OUTPUT_CREDENTIALS_KEY_PRODUCTION');
+        expect(printedMessage).toContain('config/credentials/production.key');
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+    it('should print a clean error message and exit on InvalidCredentialsKeyError', () => {
+        vi.mocked(credentials.resolveCredentialRefs).mockImplementation(() => {
+            throw new credentials.InvalidCredentialsKeyError('config/credentials.yml.enc');
+        });
+        const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+        loadCredentialRefs();
+        expect(consoleErrorSpy).toHaveBeenCalledTimes(1);
+        const printedMessage = consoleErrorSpy.mock.calls[0]?.[0];
+        expect(printedMessage).toContain('Failed to decrypt config/credentials.yml.enc');
+        expect(printedMessage).toContain('does not match');
+        expect(printedMessage).not.toContain('    at ');
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+    it('should print a clean error message and exit on MalformedCredentialsKeyError', () => {
+        vi.mocked(credentials.resolveCredentialRefs).mockImplementation(() => {
+            throw new credentials.MalformedCredentialsKeyError('config/credentials.yml.enc', 'hex string expected, got unpadded hex of length 55');
+        });
+        const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+        loadCredentialRefs();
+        const printedMessage = consoleErrorSpy.mock.calls[0]?.[0];
+        expect(printedMessage).toContain('is malformed');
+        expect(printedMessage).toContain('must be exactly 64 hex characters');
+        expect(printedMessage).toContain('unpadded hex of length 55');
+        expect(printedMessage).not.toContain('    at ');
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+    it('should rethrow unexpected errors so they are not silently swallowed', () => {
+        vi.mocked(credentials.resolveCredentialRefs).mockImplementation(() => {
+            throw new Error('something else broke');
+        });
+        expect(() => loadCredentialRefs()).toThrow('something else broke');
+    });
+});

package/dist/utils/validation.d.ts

@@ -11,3 +11,16 @@ export declare function validateWorkflowName(name: string): void;
  * Validate that a directory path is safe to create
  */
 export declare function validateOutputDirectory(outputDir: string): void;
+export declare class InvalidPortError extends Error {
+    constructor(envVarName: string, raw: string, reason: string);
+}
+/**
+ * Parse a port number from an env var. Empty string and undefined fall back to
+ * the default silently (matching Compose's `${VAR:-default}` semantics).
+ * Throws InvalidPortError on anything else: non-numeric, signed, decimal,
+ * trailing junk (e.g. "3001abc"), or out of range 1-65535. Throwing (vs
+ * warn-and-fallback) prevents CLI/Docker disagreement: Compose reads the same
+ * env var via `${VAR:-default}` and uses its own parser, so a CLI fallback
+ * would silently desync from the bound port.
+ */
+export declare function parsePort(raw: string | undefined, defaultPort: number, envVarName: string): number;

package/dist/utils/validation.js

@@ -23,3 +23,34 @@ export function validateOutputDirectory(outputDir) {
         throw new InvalidOutputDirectoryError(outputDir, 'Output directory cannot be empty');
     }
 }
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+export class InvalidPortError extends Error {
+    constructor(envVarName, raw, reason) {
+        super(`${envVarName}=${raw} is invalid (${reason}). ` +
+            `Set a port in ${MIN_PORT}-${MAX_PORT} in your .env file, or unset the variable to use the default.`);
+        this.name = 'InvalidPortError';
+    }
+}
+/**
+ * Parse a port number from an env var. Empty string and undefined fall back to
+ * the default silently (matching Compose's `${VAR:-default}` semantics).
+ * Throws InvalidPortError on anything else: non-numeric, signed, decimal,
+ * trailing junk (e.g. "3001abc"), or out of range 1-65535. Throwing (vs
+ * warn-and-fallback) prevents CLI/Docker disagreement: Compose reads the same
+ * env var via `${VAR:-default}` and uses its own parser, so a CLI fallback
+ * would silently desync from the bound port.
+ */
+export function parsePort(raw, defaultPort, envVarName) {
+    if (raw === undefined || raw === '') {
+        return defaultPort;
+    }
+    if (!/^\d+$/.test(raw)) {
+        throw new InvalidPortError(envVarName, raw, 'not a positive integer');
+    }
+    const n = parseInt(raw, 10);
+    if (n < MIN_PORT || n > MAX_PORT) {
+        throw new InvalidPortError(envVarName, raw, `out of range ${MIN_PORT}-${MAX_PORT}`);
+    }
+    return n;
+}

package/dist/utils/validation.spec.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { isValidWorkflowName } from './validation.js';
+import { isValidWorkflowName, parsePort, InvalidPortError } from './validation.js';
 describe('isValidWorkflowName', () => {
     describe('valid workflow names', () => {
         it('should accept single letter', () => {
@@ -138,3 +138,49 @@ describe('isValidWorkflowName', () => {
         });
     });
 });
+describe('parsePort', () => {
+    it('returns the parsed value for a valid port', () => {
+        expect(parsePort('3001', 3001, 'P')).toBe(3001);
+        expect(parsePort('7234', 7233, 'P')).toBe(7234);
+    });
+    it('falls back to default for undefined silently', () => {
+        expect(parsePort(undefined, 3001, 'P')).toBe(3001);
+    });
+    it('falls back to default for empty string silently (matches Compose ${VAR:-default})', () => {
+        expect(parsePort('', 3001, 'P')).toBe(3001);
+    });
+    it('throws InvalidPortError for non-numeric input', () => {
+        expect(() => parsePort('abc', 3001, 'OUTPUT_API_HOST_PORT')).toThrow(InvalidPortError);
+        expect(() => parsePort('abc', 3001, 'OUTPUT_API_HOST_PORT'))
+            .toThrow(/OUTPUT_API_HOST_PORT=abc/);
+    });
+    it('throws for trailing junk (parseInt would silently truncate)', () => {
+        expect(() => parsePort('3001abc', 3001, 'P')).toThrow(InvalidPortError);
+    });
+    it('throws for negative input', () => {
+        expect(() => parsePort('-1', 3001, 'P')).toThrow(InvalidPortError);
+    });
+    it('throws for port 0 (CLI rejects but Compose would treat as ephemeral - prevents desync)', () => {
+        expect(() => parsePort('0', 3001, 'P')).toThrow(InvalidPortError);
+    });
+    it('throws for port above 65535', () => {
+        expect(() => parsePort('65536', 3001, 'P')).toThrow(InvalidPortError);
+        expect(() => parsePort('99999', 3001, 'P')).toThrow(InvalidPortError);
+    });
+    it('accepts boundary ports 1 and 65535', () => {
+        expect(parsePort('1', 3001, 'P')).toBe(1);
+        expect(parsePort('65535', 3001, 'P')).toBe(65535);
+    });
+    it('error message includes env var name and remediation hint', () => {
+        try {
+            parsePort('abc', 3001, 'OUTPUT_API_HOST_PORT');
+            expect.fail('expected throw');
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(InvalidPortError);
+            expect(err.message).toContain('OUTPUT_API_HOST_PORT=abc');
+            expect(err.message).toContain('1-65535');
+            expect(err.message).toContain('.env file');
+        }
+    });
+});

package/dist/views/dev.js

@@ -138,10 +138,10 @@ const DevSuccessMessage = ({ services }) => {
     const divider = '─'.repeat(80);
     const sortedNames = services.map(s => s.name).sort().join('|');
     const logsCommand = `docker compose -p ${config.dockerServiceName} logs -f <${sortedNames}>`;
-    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsxs(Box, { children: [_jsx(Text, { color: "green", bold: true, children: '✅ SUCCESS! ' }), _jsx(Text, { bold: true, children: "Development services are running" })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "\uD83D\uDC33 SERVICES" }) }), _jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Temporal:    ' }), _jsx(Text, { color: "yellow", children: "localhost:7233" })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Temporal UI: ' }), _jsx(Text, { color: "cyan", children: "http://localhost:8080" })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'API Server:  ' }), _jsx(Text, { color: "yellow", children: "localhost:3001" })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Redis:       ' }), _jsx(Text, { color: "yellow", children: "localhost:6379" })] })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "\uD83D\uDE80 RUN A WORKFLOW" }) }), _jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsx(Text, { color: "white", children: "In a new terminal, execute:" }), _jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "cyan", children: "npx output workflow run blog_evaluator paulgraham_hwh" }) })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "\u26A1 USEFUL COMMANDS" }) }), _jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Open Temporal UI: ' }), _jsx(Text, { color: "cyan", children: "open http://localhost:8080" })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'View logs:        ' }), _jsx(Text, { color: "cyan", children: logsCommand })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Stop services:    ' }), _jsx(Text, { color: "cyan", children: "Press Ctrl+C" })] })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Text, { dimColor: true, children: "\uD83D\uDCA1 Tip: The Temporal UI lets you monitor workflow executions in real-time" })] }));
+    return (_jsxs(Box, { flexDirection: "column", marginBottom: 1, children: [_jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsxs(Box, { children: [_jsx(Text, { color: "green", bold: true, children: '✅ SUCCESS! ' }), _jsx(Text, { bold: true, children: "Development services are running" })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "\uD83D\uDC33 SERVICES" }) }), _jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Temporal UI: ' }), _jsx(Text, { color: "cyan", children: config.temporalUiUrl })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'API Server:  ' }), _jsxs(Text, { color: "yellow", children: ["localhost:", config.ports.api] })] })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "\uD83D\uDE80 RUN A WORKFLOW" }) }), _jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsx(Text, { color: "white", children: "In a new terminal, execute:" }), _jsx(Box, { marginLeft: 2, children: _jsx(Text, { color: "cyan", children: "npx output workflow run blog_evaluator paulgraham_hwh" }) })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Box, { marginBottom: 1, children: _jsx(Text, { bold: true, children: "\u26A1 USEFUL COMMANDS" }) }), _jsxs(Box, { flexDirection: "column", marginLeft: 2, children: [_jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Open Temporal UI: ' }), _jsxs(Text, { color: "cyan", children: ["open ", config.temporalUiUrl] })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'View logs:        ' }), _jsx(Text, { color: "cyan", children: logsCommand })] }), _jsxs(Box, { children: [_jsx(Text, { color: "white", children: 'Stop services:    ' }), _jsx(Text, { color: "cyan", children: "Press Ctrl+C" })] })] }), _jsx(Box, { marginTop: 1, marginBottom: 1, children: _jsx(Text, { dimColor: true, children: divider }) }), _jsx(Text, { dimColor: true, children: "\uD83D\uDCA1 Tip: The Temporal UI lets you monitor workflow executions in real-time" })] }));
 };
 const WaitingView = ({ services }) => (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { children: " Waiting for services to become healthy..." })] }), services.length > 0 && (_jsx(Box, { flexDirection: "column", marginTop: 1, children: services.map(s => _jsx(ServiceRow, { service: s }, s.name)) }))] }));
-const RunningView = ({ services, workflowSummary }) => (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "\uD83D\uDCCA Service Status" }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: services.map(s => _jsx(ServiceRow, { service: s }, s.name)) }), _jsx(FailureWarning, { services: services }), workflowSummary && _jsx(WorkflowSummarySection, { summary: workflowSummary }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "cyan", children: '🌐 Temporal UI: ' }), _jsx(Text, { bold: true, children: "http://localhost:8080" })] }), _jsx(CommandFooter, { hints: [
+const RunningView = ({ services, workflowSummary }) => (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "\uD83D\uDCCA Service Status" }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: services.map(s => _jsx(ServiceRow, { service: s }, s.name)) }), _jsx(FailureWarning, { services: services }), workflowSummary && _jsx(WorkflowSummarySection, { summary: workflowSummary }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "cyan", children: '🌐 Temporal UI: ' }), _jsx(Text, { bold: true, children: config.temporalUiUrl })] }), _jsx(CommandFooter, { hints: [
                 { key: 'o', label: 'open ui' },
                 { key: 'w', label: 'view workflow runs' },
                 { key: 'ctrl+c', label: 'stop' }
@@ -173,7 +173,7 @@ export const DevApp = ({ dockerComposePath, onCleanup }) => {
     useStatusRefresh(dockerComposePath, phase === 'running', setServices);
     useWorkflowPolling(phase === 'running' || phase === 'failed', setWorkflowRuns);
     useMainViewInput(activeView === 'main' && phase !== 'waiting', {
-        onOpenTemporal: () => openUrl('http://localhost:8080'),
+        onOpenTemporal: () => openUrl(config.temporalUiUrl),
         onOpenWorkflows: () => setActiveView('workflows')
     });
     useCtrlC(onCleanup);