@output.ai/cli 0.5.1 → 0.5.3

package/dist/commands/dev/index.d.ts

@@ -7,5 +7,7 @@ export default class Dev extends Command {
         'compose-file': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
         'no-watch': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
+    private dockerProcess;
     run(): Promise<void>;
+    private pollServiceStatus;
 }

package/dist/commands/dev/index.js

@@ -1,8 +1,45 @@
 import { Command, Flags } from '@oclif/core';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { validateDockerEnvironment, startDockerCompose, DockerComposeConfigNotFoundError, getDefaultDockerComposePath } from '#services/docker.js';
+import { validateDockerEnvironment, startDockerCompose, stopDockerCompose, getServiceStatus, DockerComposeConfigNotFoundError, getDefaultDockerComposePath, SERVICE_HEALTH, SERVICE_STATE } from '#services/docker.js';
 import { getErrorMessage } from '#utils/error_utils.js';
+import { getDevSuccessMessage } from '#services/messages.js';
+const ANSI = {
+    RESET: '\x1b[0m',
+    DIM: '\x1b[2m',
+    BOLD: '\x1b[1m',
+    CYAN: '\x1b[36m'
+};
+const STATUS_ICONS = {
+    [SERVICE_HEALTH.HEALTHY]: '●',
+    [SERVICE_HEALTH.UNHEALTHY]: '○',
+    [SERVICE_HEALTH.STARTING]: '◐',
+    [SERVICE_HEALTH.NONE]: '●',
+    [SERVICE_STATE.RUNNING]: '●'
+};
+const STATUS_COLORS = {
+    [SERVICE_HEALTH.HEALTHY]: '\x1b[32m',
+    [SERVICE_HEALTH.UNHEALTHY]: '\x1b[31m',
+    [SERVICE_HEALTH.STARTING]: '\x1b[33m',
+    [SERVICE_HEALTH.NONE]: '\x1b[34m',
+    [SERVICE_STATE.RUNNING]: '\x1b[34m'
+};
+const formatService = (service) => {
+    const healthKey = service.health === SERVICE_HEALTH.NONE ? service.state : service.health;
+    const icon = STATUS_ICONS[healthKey] || '?';
+    const color = STATUS_COLORS[healthKey] || '';
+    const ports = service.ports.length ? service.ports.join(', ') : '-';
+    const status = service.health === SERVICE_HEALTH.NONE ? service.state : service.health;
+    const name = service.name.padEnd(15);
+    const statusPadded = status.padEnd(10);
+    return `  ${color}${icon}${ANSI.RESET} ${name} ${ANSI.DIM}${statusPadded}${ANSI.RESET} ${ANSI.DIM}${ports}${ANSI.RESET}`;
+};
+const poll = async (fn, intervalMs) => {
+    for (;;) {
+        await fn();
+        await new Promise(resolve => setTimeout(resolve, intervalMs));
+    }
+};
 export default class Dev extends Command {
     static description = 'Start Output development services (auto-restarts worker on file changes)';
     static examples = [
@@ -22,6 +59,7 @@ export default class Dev extends Command {
             default: false
         })
     };
+    dockerProcess = null;
     async run() {
         const { flags } = await this.parse(Dev);
         validateDockerEnvironment();
@@ -44,11 +82,56 @@ export default class Dev extends Command {
         else {
             this.log('ℹ️  File watching disabled (--no-watch flag used)\n');
         }
+        const cleanup = async () => {
+            this.log('\n');
+            if (this.dockerProcess) {
+                this.dockerProcess.kill('SIGTERM');
+            }
+            await stopDockerCompose(dockerComposePath);
+            process.exit(0);
+        };
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
         try {
-            await startDockerCompose(dockerComposePath, !flags['no-watch']);
+            const { process: dockerProc, waitForHealthy } = await startDockerCompose(dockerComposePath, !flags['no-watch']);
+            this.dockerProcess = dockerProc;
+            dockerProc.on('error', error => {
+                this.error(`Docker process error: ${getErrorMessage(error)}`, { exit: 1 });
+            });
+            this.log('⏳ Waiting for services to become healthy...\n');
+            await waitForHealthy();
+            const services = await getServiceStatus(dockerComposePath);
+            this.log(getDevSuccessMessage(services));
+            await this.pollServiceStatus(dockerComposePath);
         }
         catch (error) {
             this.error(getErrorMessage(error), { exit: 1 });
         }
     }
+    async pollServiceStatus(dockerComposePath) {
+        const state = { lastLineCount: 0 };
+        const outputServiceStatus = async () => {
+            try {
+                const services = await getServiceStatus(dockerComposePath);
+                const lines = [
+                    `${ANSI.BOLD}📊 Service Status${ANSI.RESET}`,
+                    '',
+                    ...services.map(formatService),
+                    '',
+                    `${ANSI.CYAN}🌐 Temporal UI:${ANSI.RESET} ${ANSI.BOLD}http://localhost:8080${ANSI.RESET}`,
+                    '',
+                    `${ANSI.DIM}Press Ctrl+C to stop services${ANSI.RESET}`
+                ];
+                if (state.lastLineCount > 0) {
+                    process.stdout.write(`\x1b[${state.lastLineCount}A\x1b[J`);
+                }
+                process.stdout.write(lines.join('\n') + '\n');
+                state.lastLineCount = lines.length;
+            }
+            catch {
+                // silent retry on next poll
+            }
+        };
+        await poll(outputServiceStatus, 2000);
+    }
 }

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

@@ -5,21 +5,47 @@ import * as dockerService from '#services/docker.js';
 import Dev from './index.js';
 vi.mock('#services/docker.js', () => ({
     validateDockerEnvironment: vi.fn(),
-    startDockerCompose: vi.fn().mockResolvedValue(undefined),
+    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'] }
+    ]),
     DockerComposeConfigNotFoundError: Error,
     DockerValidationError: Error,
-    getDefaultDockerComposePath: vi.fn(() => '/path/to/docker-compose-dev.yml')
+    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()
     }
 }));
+const createMockDockerProcess = () => ({
+    process: {
+        on: vi.fn(),
+        kill: vi.fn(),
+        stdout: { on: vi.fn() },
+        stderr: { on: vi.fn() }
+    },
+    waitForHealthy: vi.fn().mockResolvedValue(undefined)
+});
 describe('dev command', () => {
     beforeEach(() => {
         vi.clearAllMocks();
         // By default, docker validation succeeds
         vi.mocked(dockerService.validateDockerEnvironment).mockResolvedValue(undefined);
+        // 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);
     });
@@ -107,10 +133,15 @@ describe('dev command', () => {
                 value: vi.fn().mockResolvedValue({ flags: { 'no-watch': false, 'compose-file': undefined }, args: {} }),
                 configurable: true
             });
-            await cmd.run();
+            // Run the command but don't await it since it waits forever after startup
+            const runPromise = cmd.run();
+            // Wait a tick for startDockerCompose to be called
+            await new Promise(resolve => setImmediate(resolve));
             expect(dockerService.startDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', true // enableWatch should be true
             );
             expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('File watching enabled'));
+            // Cancel the promise (it will be rejected but we don't care)
+            runPromise.catch(() => { });
         });
         it('should disable watch with --no-watch flag', async () => {
             const cmd = new Dev(['--no-watch'], {});
@@ -121,10 +152,15 @@ describe('dev command', () => {
                 value: vi.fn().mockResolvedValue({ flags: { 'no-watch': true, 'compose-file': undefined }, args: {} }),
                 configurable: true
             });
-            await cmd.run();
+            // Run the command but don't await it since it waits forever after startup
+            const runPromise = cmd.run();
+            // Wait a tick for startDockerCompose to be called
+            await new Promise(resolve => setImmediate(resolve));
             expect(dockerService.startDockerCompose).toHaveBeenCalledWith('/path/to/docker-compose-dev.yml', false // enableWatch should be false
             );
             expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('File watching disabled'));
+            // Cancel the promise (it will be rejected but we don't care)
+            runPromise.catch(() => { });
         });
         it('should handle docker compose configuration not found', async () => {
             vi.mocked(fs).access.mockRejectedValue(new Error('File not found'));

package/dist/config.d.ts

@@ -16,6 +16,11 @@ export declare const config: {
      * Default timeout for API requests (in milliseconds)
      */
     requestTimeout: number;
+    /**
+     * Docker Compose project name
+     * Can be overridden with DOCKER_SERVICE_NAME environment variable
+     */
+    dockerServiceName: string;
 };
 /**
  * Agent configuration directory name

package/dist/config.js

@@ -15,7 +15,12 @@ export const config = {
     /**
      * Default timeout for API requests (in milliseconds)
      */
-    requestTimeout: 30000
+    requestTimeout: 30000,
+    /**
+     * Docker Compose project name
+     * Can be overridden with DOCKER_SERVICE_NAME environment variable
+     */
+    dockerServiceName: process.env.DOCKER_SERVICE_NAME || 'output-sdk'
 };
 /**
  * Agent configuration directory name

package/dist/services/docker.d.ts

@@ -1,5 +1,22 @@
+import { type ChildProcess } from 'node:child_process';
+export declare const SERVICE_HEALTH: {
+    readonly HEALTHY: "healthy";
+    readonly UNHEALTHY: "unhealthy";
+    readonly STARTING: "starting";
+    readonly NONE: "none";
+};
+export declare const SERVICE_STATE: {
+    readonly RUNNING: "running";
+    readonly EXITED: "exited";
+};
 declare class DockerValidationError extends Error {
 }
+export interface ServiceStatus {
+    name: string;
+    state: string;
+    health: string;
+    ports: string[];
+}
 export declare class DockerComposeConfigNotFoundError extends Error {
     constructor(dockerComposePath: string);
 }
@@ -7,6 +24,14 @@ declare const isDockerInstalled: () => boolean;
 declare const isDockerComposeAvailable: () => boolean;
 declare const isDockerDaemonRunning: () => boolean;
 export declare function validateDockerEnvironment(): void;
-export declare function startDockerCompose(dockerComposePath: string, enableWatch?: boolean): Promise<void>;
 export declare function getDefaultDockerComposePath(): string;
+export declare function parseServiceStatus(jsonOutput: string): ServiceStatus[];
+export declare function getServiceStatus(dockerComposePath: string): Promise<ServiceStatus[]>;
+export declare function waitForServicesHealthy(dockerComposePath: string, timeoutMs?: number, pollIntervalMs?: number): Promise<void>;
+export interface DockerComposeProcess {
+    process: ChildProcess;
+    waitForHealthy: () => Promise<void>;
+}
+export declare function startDockerCompose(dockerComposePath: string, enableWatch?: boolean): Promise<DockerComposeProcess>;
+export declare function stopDockerCompose(dockerComposePath: string): Promise<void>;
 export { isDockerInstalled, isDockerComposeAvailable, isDockerDaemonRunning, DockerValidationError };

package/dist/services/docker.js

@@ -1,7 +1,18 @@
-import { execSync, spawn } from 'node:child_process';
+import { execFileSync, execSync, spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ux } from '@oclif/core';
+const DEFAULT_COMPOSE_PATH = '../assets/docker/docker-compose-dev.yml';
+export const SERVICE_HEALTH = {
+    HEALTHY: 'healthy',
+    UNHEALTHY: 'unhealthy',
+    STARTING: 'starting',
+    NONE: 'none'
+};
+export const SERVICE_STATE = {
+    RUNNING: 'running',
+    EXITED: 'exited'
+};
 class DockerValidationError extends Error {
 }
 export class DockerComposeConfigNotFoundError extends Error {
@@ -42,6 +53,73 @@ export function validateDockerEnvironment() {
         throw new DockerValidationError(failedValidation.error);
     }
 }
+export function getDefaultDockerComposePath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), DEFAULT_COMPOSE_PATH);
+}
+export function parseServiceStatus(jsonOutput) {
+    if (!jsonOutput.trim()) {
+        return [];
+    }
+    return jsonOutput
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map(line => {
+        const data = JSON.parse(line);
+        return {
+            name: data.Service || data.Name || 'unknown',
+            state: data.State,
+            health: data.Health || SERVICE_HEALTH.NONE,
+            ports: data.Publishers?.map(p => `${p.PublishedPort}:${p.TargetPort}`) || []
+        };
+    });
+}
+export async function getServiceStatus(dockerComposePath) {
+    const result = execFileSync('docker', ['compose', '-f', dockerComposePath, 'ps', '--format', 'json'], { encoding: 'utf-8', cwd: process.cwd() });
+    return parseServiceStatus(result);
+}
+const STATUS_ICONS = {
+    [SERVICE_HEALTH.HEALTHY]: '✓',
+    [SERVICE_HEALTH.UNHEALTHY]: '✗',
+    [SERVICE_HEALTH.STARTING]: '◐',
+    [SERVICE_HEALTH.NONE]: '✓',
+    [SERVICE_STATE.RUNNING]: '●',
+    [SERVICE_STATE.EXITED]: '✗'
+};
+const STATUS_COLORS = {
+    [SERVICE_HEALTH.HEALTHY]: '\x1b[32m',
+    [SERVICE_HEALTH.UNHEALTHY]: '\x1b[31m',
+    [SERVICE_HEALTH.STARTING]: '\x1b[33m',
+    [SERVICE_HEALTH.NONE]: '\x1b[32m',
+    [SERVICE_STATE.RUNNING]: '\x1b[34m',
+    [SERVICE_STATE.EXITED]: '\x1b[31m'
+};
+const ANSI_RESET = '\x1b[0m';
+const formatServiceStatus = (services) => services.map(s => {
+    const healthKey = s.health === SERVICE_HEALTH.NONE ? s.state : s.health;
+    const icon = STATUS_ICONS[healthKey] || '?';
+    const color = STATUS_COLORS[healthKey] || '';
+    const status = s.health === SERVICE_HEALTH.NONE ? s.state : s.health;
+    return `  ${color}${icon}${ANSI_RESET} ${s.name}: ${status}`;
+}).join('\n');
+export async function waitForServicesHealthy(dockerComposePath, timeoutMs = 120000, pollIntervalMs = 2000) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        const services = await getServiceStatus(dockerComposePath);
+        const allHealthy = services.every(s => s.health === SERVICE_HEALTH.HEALTHY || s.health === SERVICE_HEALTH.NONE);
+        if (services.length > 0) {
+            const lineCount = services.length + 1;
+            process.stdout.write(`\x1b[${lineCount}A\x1b[J`);
+            ux.stdout('⏳ Waiting for services to become healthy...\n');
+            ux.stdout(formatServiceStatus(services) + '\n');
+        }
+        if (allHealthy && services.length > 0) {
+            return;
+        }
+        await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error('Timeout waiting for services to become healthy');
+}
 export async function startDockerCompose(dockerComposePath, enableWatch = false) {
     const args = [
         'compose',
@@ -52,28 +130,18 @@ export async function startDockerCompose(dockerComposePath, enableWatch = false)
     if (enableWatch) {
         args.push('--watch');
     }
-    const childProcess = spawn('docker', args, {
-        stdio: 'inherit',
-        cwd: process.cwd()
+    ux.stdout('🐳 Starting Docker services...\n');
+    const dockerProcess = spawn('docker', args, {
+        cwd: process.cwd(),
+        stdio: ['ignore', 'pipe', 'pipe']
     });
-    const cleanup = () => {
-        ux.stdout('⏹️  Stopping services...\n');
-        childProcess.kill('SIGTERM');
+    return {
+        process: dockerProcess,
+        waitForHealthy: () => waitForServicesHealthy(dockerComposePath)
     };
-    process.on('SIGINT', cleanup);
-    process.on('SIGTERM', cleanup);
-    return new Promise((resolve, reject) => {
-        childProcess.on('exit', _code => {
-            process.removeListener('SIGINT', cleanup);
-            process.removeListener('SIGTERM', cleanup);
-            resolve();
-        });
-        childProcess.on('error', error => {
-            reject(new Error(`Failed to start services: ${error.message}`));
-        });
-    });
 }
-export function getDefaultDockerComposePath() {
-    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../assets/docker/docker-compose-dev.yml');
+export async function stopDockerCompose(dockerComposePath) {
+    ux.stdout('⏹️  Stopping services...\n');
+    execFileSync('docker', ['compose', '-f', dockerComposePath, 'down'], { stdio: 'inherit', cwd: process.cwd() });
 }
 export { isDockerInstalled, isDockerComposeAvailable, isDockerDaemonRunning, DockerValidationError };

package/dist/services/docker.spec.d.ts

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

package/dist/services/docker.spec.js

@@ -0,0 +1,119 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { parseServiceStatus, getServiceStatus, waitForServicesHealthy } from './docker.js';
+vi.mock('node:child_process', () => ({
+    execSync: vi.fn(),
+    execFileSync: vi.fn(),
+    spawn: vi.fn()
+}));
+describe('docker service', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('parseServiceStatus', () => {
+        it('should parse single service JSON output', () => {
+            const jsonOutput = '{"Service":"redis","State":"running","Health":"healthy","Publishers":[{"PublishedPort":6379,"TargetPort":6379}]}';
+            const result = parseServiceStatus(jsonOutput);
+            expect(result).toHaveLength(1);
+            expect(result[0]).toEqual({
+                name: 'redis',
+                state: 'running',
+                health: 'healthy',
+                ports: ['6379:6379']
+            });
+        });
+        it('should parse multiple services from JSON lines output', () => {
+            const jsonOutput = `{"Service":"redis","State":"running","Health":"healthy","Publishers":[{"PublishedPort":6379,"TargetPort":6379}]}
+{"Service":"temporal","State":"running","Health":"healthy","Publishers":[{"PublishedPort":7233,"TargetPort":7233}]}
+{"Service":"temporal-ui","State":"running","Health":"","Publishers":[{"PublishedPort":8080,"TargetPort":8080}]}`;
+            const result = parseServiceStatus(jsonOutput);
+            expect(result).toHaveLength(3);
+            expect(result[0].name).toBe('redis');
+            expect(result[1].name).toBe('temporal');
+            expect(result[2].name).toBe('temporal-ui');
+        });
+        it('should handle empty health status', () => {
+            const jsonOutput = '{"Service":"api","State":"running","Health":"","Publishers":[]}';
+            const result = parseServiceStatus(jsonOutput);
+            expect(result[0].health).toBe('none');
+        });
+        it('should handle missing Publishers array', () => {
+            const jsonOutput = '{"Service":"worker","State":"running","Health":"healthy"}';
+            const result = parseServiceStatus(jsonOutput);
+            expect(result[0].ports).toEqual([]);
+        });
+        it('should handle empty output', () => {
+            const result = parseServiceStatus('');
+            expect(result).toEqual([]);
+        });
+        it('should filter out empty lines', () => {
+            const jsonOutput = `{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}
+
+{"Service":"api","State":"running","Health":"","Publishers":[]}
+`;
+            const result = parseServiceStatus(jsonOutput);
+            expect(result).toHaveLength(2);
+        });
+        it('should use Name field as fallback when Service is missing', () => {
+            const jsonOutput = '{"Name":"output-sdk-redis-1","State":"running","Health":"healthy","Publishers":[]}';
+            const result = parseServiceStatus(jsonOutput);
+            expect(result[0].name).toBe('output-sdk-redis-1');
+        });
+    });
+    describe('getServiceStatus', () => {
+        it('should call docker compose ps with correct arguments', async () => {
+            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', '--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}]}';
+            vi.mocked(execFileSync).mockReturnValue(mockOutput);
+            const result = await getServiceStatus('/path/to/docker-compose.yml');
+            expect(result).toHaveLength(1);
+            expect(result[0].name).toBe('redis');
+        });
+        it('should throw error when docker compose command fails', async () => {
+            vi.mocked(execFileSync).mockImplementation(() => {
+                throw new Error('Docker command failed');
+            });
+            await expect(getServiceStatus('/path/to/docker-compose.yml')).rejects.toThrow();
+        });
+    });
+    describe('waitForServicesHealthy', () => {
+        it('should resolve when all services are healthy', async () => {
+            const mockOutput = `{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}
+{"Service":"temporal","State":"running","Health":"healthy","Publishers":[]}`;
+            vi.mocked(execFileSync).mockReturnValue(mockOutput);
+            await expect(waitForServicesHealthy('/path/to/docker-compose.yml', 5000)).resolves.toBeUndefined();
+        });
+        it('should resolve when services have no health check (health: none)', async () => {
+            const mockOutput = `{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}
+{"Service":"api","State":"running","Health":"","Publishers":[]}`;
+            vi.mocked(execFileSync).mockReturnValue(mockOutput);
+            await expect(waitForServicesHealthy('/path/to/docker-compose.yml', 5000)).resolves.toBeUndefined();
+        });
+        it('should timeout when services remain unhealthy', async () => {
+            const mockOutput = '{"Service":"redis","State":"running","Health":"starting","Publishers":[]}';
+            vi.mocked(execFileSync).mockReturnValue(mockOutput);
+            const promise = waitForServicesHealthy('/path/to/docker-compose.yml', 100);
+            await expect(promise).rejects.toThrow('Timeout waiting for services to become healthy');
+        }, 10000);
+        it('should poll multiple times until healthy', async () => {
+            const callTracker = { count: 0 };
+            vi.mocked(execFileSync).mockImplementation(() => {
+                callTracker.count++;
+                if (callTracker.count < 3) {
+                    return '{"Service":"redis","State":"running","Health":"starting","Publishers":[]}';
+                }
+                return '{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}';
+            });
+            await waitForServicesHealthy('/path/to/docker-compose.yml', 10000, 50);
+            expect(callTracker.count).toBeGreaterThanOrEqual(3);
+        });
+    });
+});

package/dist/services/env_configurator.d.ts

@@ -2,10 +2,14 @@
  * Interactively configures environment variables for a project by prompting the user
  * to provide values for empty variables or variables marked as secrets.
  *
- * @param projectPath - The absolute path to the project directory containing the .env file
+ * This function reads from .env.example and, when the user confirms configuration,
+ * copies it to .env before prompting for values. The .env.example file remains
+ * unchanged as a template for other developers.
+ *
+ * @param projectPath - The absolute path to the project directory containing the .env.example file
  * @param skipPrompt - If true, skips the configuration prompt and returns false immediately
  * @returns A promise that resolves to true if environment variables were successfully configured,
- *          false if configuration was skipped (no .env file, user declined, no variables to configure,
+ *          false if configuration was skipped (no .env.example file, user declined, no variables to configure,
  *          or an error occurred)
  */
 export declare function configureEnvironmentVariables(projectPath: string, skipPrompt?: boolean): Promise<boolean>;

package/dist/services/env_configurator.js

@@ -115,10 +115,14 @@ async function writeEnvFile(filePath, variables) {
  * Interactively configures environment variables for a project by prompting the user
  * to provide values for empty variables or variables marked as secrets.
  *
- * @param projectPath - The absolute path to the project directory containing the .env file
+ * This function reads from .env.example and, when the user confirms configuration,
+ * copies it to .env before prompting for values. The .env.example file remains
+ * unchanged as a template for other developers.
+ *
+ * @param projectPath - The absolute path to the project directory containing the .env.example file
  * @param skipPrompt - If true, skips the configuration prompt and returns false immediately
  * @returns A promise that resolves to true if environment variables were successfully configured,
- *          false if configuration was skipped (no .env file, user declined, no variables to configure,
+ *          false if configuration was skipped (no .env.example file, user declined, no variables to configure,
  *          or an error occurred)
  */
 export async function configureEnvironmentVariables(projectPath, skipPrompt = false) {
@@ -126,12 +130,13 @@ export async function configureEnvironmentVariables(projectPath, skipPrompt = fa
         return false;
     }
     ux.stdout('configuring environment variables...');
+    const envExamplePath = path.join(projectPath, '.env.example');
     const envPath = path.join(projectPath, '.env');
     try {
-        await fs.access(envPath);
+        await fs.access(envExamplePath);
     }
     catch {
-        ux.stdout(ux.colorize('red', '🔴 .env file does not exist, nothing to configure'));
+        ux.stdout(ux.colorize('red', '.env.example file does not exist, nothing to configure'));
         return false;
     }
     const shouldConfigure = await confirm({
@@ -142,6 +147,8 @@ export async function configureEnvironmentVariables(projectPath, skipPrompt = fa
         return false;
     }
     try {
+        // Copy .env.example to .env before configuring
+        await fs.copyFile(envExamplePath, envPath);
         const variables = await parseEnvFile(envPath);
         const variablesToConfigure = variables.filter(v => isEmpty(v.value) || v.isSecret);
         if (variablesToConfigure.length === 0) {

package/dist/services/env_configurator.spec.js

@@ -5,16 +5,18 @@ import { configureEnvironmentVariables } from './env_configurator.js';
 // Mock inquirer prompts
 vi.mock('@inquirer/prompts', () => ({
     input: vi.fn(),
-    confirm: vi.fn()
+    confirm: vi.fn(),
+    password: vi.fn()
 }));
 describe('configureEnvironmentVariables', () => {
-    const testState = { tempDir: '', envPath: '' };
+    const testState = { tempDir: '', envExamplePath: '', envPath: '' };
     beforeEach(async () => {
         // Clear all mocks before each test
         vi.clearAllMocks();
         // Create temporary directory for test files
         testState.tempDir = path.join('/tmp', `test-env-${Date.now()}`);
         await fs.mkdir(testState.tempDir, { recursive: true });
+        testState.envExamplePath = path.join(testState.tempDir, '.env.example');
         testState.envPath = path.join(testState.tempDir, '.env');
     });
     afterEach(async () => {
@@ -27,36 +29,74 @@ describe('configureEnvironmentVariables', () => {
         }
     });
     it('should return false if skipPrompt is true', async () => {
-        // Create a minimal .env file
-        await fs.writeFile(testState.envPath, 'KEY=value');
+        // Create a minimal .env.example file
+        await fs.writeFile(testState.envExamplePath, 'KEY=value');
         const result = await configureEnvironmentVariables(testState.tempDir, true);
         expect(result).toBe(false);
     });
-    it('should return false if .env file does not exist', async () => {
+    it('should return false if .env.example file does not exist', async () => {
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(false);
     });
     it('should return false if user declines configuration', async () => {
         const { confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(false);
-        await fs.writeFile(testState.envPath, '# API key\nAPIKEY=');
+        await fs.writeFile(testState.envExamplePath, '# API key\nAPIKEY=');
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(false);
         expect(vi.mocked(confirm)).toHaveBeenCalled();
     });
+    it('should NOT create .env when user declines configuration', async () => {
+        const { confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(false);
+        await fs.writeFile(testState.envExamplePath, '# API key\nAPIKEY=');
+        await configureEnvironmentVariables(testState.tempDir, false);
+        // .env should NOT exist when user declines
+        await expect(fs.access(testState.envPath)).rejects.toThrow();
+        // .env.example should still exist
+        await expect(fs.access(testState.envExamplePath)).resolves.toBeUndefined();
+    });
     it('should return false if no empty variables exist', async () => {
         const { confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
-        await fs.writeFile(testState.envPath, 'APIKEY=my-secret-key');
+        await fs.writeFile(testState.envExamplePath, 'APIKEY=my-secret-key');
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(false);
     });
+    it('should copy .env.example to .env when user confirms configuration', async () => {
+        const { input, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(input).mockResolvedValueOnce('sk-proj-123');
+        const originalContent = `# API key
+APIKEY=`;
+        await fs.writeFile(testState.envExamplePath, originalContent);
+        await configureEnvironmentVariables(testState.tempDir, false);
+        // Both files should exist
+        await expect(fs.access(testState.envExamplePath)).resolves.toBeUndefined();
+        await expect(fs.access(testState.envPath)).resolves.toBeUndefined();
+    });
+    it('should write configured values to .env while leaving .env.example unchanged', async () => {
+        const { input, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(input).mockResolvedValueOnce('sk-proj-123');
+        const originalContent = `# API key
+APIKEY=`;
+        await fs.writeFile(testState.envExamplePath, originalContent);
+        const result = await configureEnvironmentVariables(testState.tempDir, false);
+        expect(result).toBe(true);
+        // .env should have the configured value
+        const envContent = await fs.readFile(testState.envPath, 'utf-8');
+        expect(envContent).toContain('APIKEY=sk-proj-123');
+        // .env.example should remain unchanged
+        const envExampleContent = await fs.readFile(testState.envExamplePath, 'utf-8');
+        expect(envExampleContent).toBe(originalContent);
+    });
     it('should prompt for empty variables and update .env', async () => {
         const { input, confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
         vi.mocked(input).mockResolvedValueOnce('sk-proj-123');
         vi.mocked(input).mockResolvedValueOnce('');
-        await fs.writeFile(testState.envPath, `# API key for Anthropic
+        await fs.writeFile(testState.envExamplePath, `# API key for Anthropic
 ANTHROPIC_API_KEY=
 
 # API key for OpenAI
@@ -78,7 +118,7 @@ APIKEY=
 
 # Another comment
 OTHER=value`;
-        await fs.writeFile(testState.envPath, originalContent);
+        await fs.writeFile(testState.envExamplePath, originalContent);
         await configureEnvironmentVariables(testState.tempDir, false);
         const content = await fs.readFile(testState.envPath, 'utf-8');
         expect(content).toContain('# This is a comment');
@@ -90,7 +130,7 @@ OTHER=value`;
         const { input, confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
         vi.mocked(input).mockResolvedValueOnce('new-key');
-        await fs.writeFile(testState.envPath, `APIKEY=your_api_key_here
+        await fs.writeFile(testState.envExamplePath, `APIKEY=your_api_key_here
 EMPTY_KEY=`);
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         expect(result).toBe(true);
@@ -103,21 +143,54 @@ EMPTY_KEY=`);
         const { input, confirm } = await import('@inquirer/prompts');
         vi.mocked(confirm).mockResolvedValue(true);
         vi.mocked(input).mockResolvedValueOnce('new-key');
-        await fs.writeFile(testState.envPath, `EXISTING_KEY=existing-value
+        await fs.writeFile(testState.envExamplePath, `EXISTING_KEY=existing-value
 
 EMPTY_KEY=`);
         await configureEnvironmentVariables(testState.tempDir, false);
         // Should only prompt for EMPTY_KEY, not EXISTING_KEY
         expect(vi.mocked(input)).toHaveBeenCalledTimes(1);
     });
+    it('should handle case where .env already exists (overwrite with copy)', async () => {
+        const { input, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(input).mockResolvedValueOnce('new-configured-value');
+        // Create existing .env with old content
+        await fs.writeFile(testState.envPath, 'OLD_KEY=old-value');
+        // Create .env.example with new content
+        await fs.writeFile(testState.envExamplePath, 'NEW_KEY=');
+        const result = await configureEnvironmentVariables(testState.tempDir, false);
+        expect(result).toBe(true);
+        // .env should be overwritten with .env.example content and configured values
+        const envContent = await fs.readFile(testState.envPath, 'utf-8');
+        expect(envContent).toContain('NEW_KEY=new-configured-value');
+        expect(envContent).not.toContain('OLD_KEY');
+    });
     it('should return false if an error occurs during parsing', async () => {
-        // This test verifies error handling by checking behavior when file operations fail
-        // The try-catch in configureEnvironmentVariables should handle it gracefully
-        await fs.writeFile(testState.envPath, 'KEY=');
-        // Delete the file to cause parsing error
-        await fs.rm(testState.envPath);
+        const { confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        await fs.writeFile(testState.envExamplePath, 'KEY=');
+        // Delete the .env.example file after access check but before parsing would happen
+        // We simulate this by deleting during the copy operation
+        const originalCopyFile = fs.copyFile;
+        vi.spyOn(fs, 'copyFile').mockImplementation(async () => {
+            throw new Error('Copy failed');
+        });
         const result = await configureEnvironmentVariables(testState.tempDir, false);
         // Should return false when error occurs
         expect(result).toBe(false);
+        // Restore original function
+        vi.mocked(fs.copyFile).mockImplementation(originalCopyFile);
+    });
+    it('should prompt for SECRET marker values with password input', async () => {
+        const { password, confirm } = await import('@inquirer/prompts');
+        vi.mocked(confirm).mockResolvedValue(true);
+        vi.mocked(password).mockResolvedValueOnce('my-secret-api-key');
+        await fs.writeFile(testState.envExamplePath, `# API Key
+ANTHROPIC_API_KEY=<SECRET>`);
+        const result = await configureEnvironmentVariables(testState.tempDir, false);
+        expect(result).toBe(true);
+        expect(vi.mocked(password)).toHaveBeenCalledTimes(1);
+        const envContent = await fs.readFile(testState.envPath, 'utf-8');
+        expect(envContent).toContain('ANTHROPIC_API_KEY=my-secret-api-key');
     });
 });

package/dist/services/messages.d.ts

@@ -4,3 +4,6 @@
 export declare const getEjectSuccessMessage: (destPath: string, outputFile: string, binName: string) => string;
 export declare const getProjectSuccessMessage: (folderName: string, installSuccess: boolean, envConfigured?: boolean) => string;
 export declare const getWorkflowGenerateSuccessMessage: (workflowName: string, targetDir: string, filesCreated: string[]) => string;
+export declare const getDevSuccessMessage: (services: Array<{
+    name: string;
+}>) => string;

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
  */
@@ -166,8 +167,8 @@ export const getProjectSuccessMessage = (folderName, installSuccess, envConfigur
     if (!envConfigured) {
         steps.push({
             step: 'Configure environment variables',
-            command: 'Edit .env file',
-            note: 'Add your Anthropic/OpenAI API keys'
+            command: 'cp .env.example .env',
+            note: 'Copy .env.example to .env and add your API keys'
         });
     }
     steps.push({
@@ -248,8 +249,8 @@ export const getWorkflowGenerateSuccessMessage = (workflowName, targetDir, files
         },
         {
             step: 'Configure environment',
-            command: 'Edit .env file',
-            note: 'Add your LLM provider credentials (ANTHROPIC_API_KEY or OPENAI_API_KEY)'
+            command: 'cp .env.example .env',
+            note: 'Copy .env.example to .env and add your LLM provider credentials'
         },
         {
             step: 'Test with example scenario',
@@ -295,3 +296,43 @@ ${ux.colorize('dim', '💡 Tip: Check the README.md in your workflow directory f
 ${ux.colorize('green', ux.colorize('bold', 'Happy building! 🛠️'))}
 `;
 };
+export const getDevSuccessMessage = (services) => {
+    const divider = ux.colorize('dim', '─'.repeat(80));
+    const bulletPoint = ux.colorize('green', '▸');
+    const serviceNames = services.map(s => s.name).sort().join('|');
+    const logsCommand = `docker compose -p ${config.dockerServiceName} logs -f <${serviceNames}>`;
+    return `
+${divider}
+
+${ux.colorize('bold', ux.colorize('green', '✅ SUCCESS!'))} ${ux.colorize('bold', 'Development services are running')}
+
+${divider}
+
+${createSectionHeader('SERVICES', '🐳')}
+
+  ${bulletPoint} ${ux.colorize('white', 'Temporal:')}     ${formatPath('localhost:7233')}
+  ${bulletPoint} ${ux.colorize('white', 'Temporal UI:')} ${formatCommand('http://localhost:8080')}
+  ${bulletPoint} ${ux.colorize('white', 'API Server:')}  ${formatPath('localhost:3001')}
+  ${bulletPoint} ${ux.colorize('white', 'Redis:')}       ${formatPath('localhost:6379')}
+
+${divider}
+
+${createSectionHeader('RUN A WORKFLOW', '🚀')}
+
+  ${ux.colorize('white', 'In a new terminal, execute:')}
+
+    ${formatCommand('output workflow run simple --input \'{"question": "Hello!"}\'')}
+
+${divider}
+
+${createSectionHeader('USEFUL COMMANDS', '⚡')}
+
+  ${bulletPoint} ${ux.colorize('white', 'Open Temporal UI:')} ${formatCommand('open http://localhost:8080')}
+  ${bulletPoint} ${ux.colorize('white', 'View logs:')}        ${formatCommand(logsCommand)}
+  ${bulletPoint} ${ux.colorize('white', 'Stop services:')}    ${formatCommand('Press Ctrl+C')}
+
+${divider}
+
+${ux.colorize('dim', '💡 Tip: The Temporal UI lets you monitor workflow executions in real-time')}
+`;
+};

package/dist/services/messages.spec.d.ts

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

package/dist/services/messages.spec.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { getDevSuccessMessage } from './messages.js';
+const mockServices = [
+    { name: 'api' },
+    { name: 'postgresql' },
+    { name: 'redis' },
+    { name: 'temporal' },
+    { name: 'temporal-ui' },
+    { name: 'worker' }
+];
+describe('messages', () => {
+    describe('getDevSuccessMessage', () => {
+        it('should return a string', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(typeof message).toBe('string');
+        });
+        it('should include the Temporal UI URL', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('http://localhost:8080');
+        });
+        it('should include the Temporal server address', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('localhost:7233');
+        });
+        it('should include the API server address', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('localhost:3001');
+        });
+        it('should include workflow run example', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('output workflow run');
+        });
+        it('should include success indicator', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('SUCCESS');
+        });
+        it('should include services section', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('Temporal UI');
+            expect(message).toContain('API Server');
+            expect(message).toContain('Redis');
+        });
+        it('should include helpful tip about Temporal UI', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('Temporal UI');
+            expect(message).toContain('workflow');
+        });
+        it('should include dynamic docker logs command with service names', () => {
+            const message = getDevSuccessMessage(mockServices);
+            expect(message).toContain('docker compose -p');
+            expect(message).toContain('logs -f');
+            expect(message).toContain('api|postgresql|redis|temporal|temporal-ui|worker');
+        });
+    });
+});

package/dist/services/workflow_generator.spec.js

@@ -65,7 +65,6 @@ describe('Workflow Generator', () => {
                 'workflow.ts',
                 'steps.ts',
                 'README.md',
-                '.env',
                 'prompts/prompt@v1.prompt',
                 'scenarios/test_input.json'
             ];

package/dist/templates/agent_instructions/skills/output-error-zod-import/SKILL.md.template

@@ -139,7 +139,7 @@ grep -r 'from "zod"' src/
 ### 2. Build the project
 
 ```bash
-npm run build
+npm run output:workflow:build
 ```
 
 ### 3. Run the workflow

package/dist/templates/agent_instructions/skills/output-workflow-list/SKILL.md.template

@@ -108,7 +108,7 @@ cat src/workflows/simple/workflow.ts
 ### Workflow not showing
 - Check the file exports a valid workflow definition
 - Ensure the workflow file compiles without errors
-- Run `npm run build` to check for TypeScript errors
+- Run `npm run output:workflow:build` to check for TypeScript errors
 
 ## Related Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/cli",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "CLI for Output.ai workflow generation",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "handlebars": "4.7.8",
     "json-schema-library": "10.3.0",
     "ky": "1.12.0",
-    "validator": "13.15.20"
+    "validator": "13.15.22"
   },
   "devDependencies": {
     "@types/cli-progress": "3.11.6",

package/dist/templates/workflow/.env.template

@@ -1,7 +0,0 @@
-# API Keys for LLM providers
-OPENAI_API_KEY=your_openai_api_key_here
-ANTHROPIC_API_KEY=your_anthropic_api_key_here
-
-# Optional: Additional configuration
-# NODE_ENV=development
-# LOG_LEVEL=info