@outputai/cli 0.1.2 → 0.1.3-dev.0

package/dist/services/project_scaffold.js

@@ -0,0 +1,212 @@
+import { input, confirm } from '@inquirer/prompts';
+import { ux } from '@oclif/core';
+import { kebabCase, pascalCase } from 'change-case';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FolderAlreadyExistsError, UserCancelledError, DirectoryCreationError } from '#types/errors.js';
+import { createDirectory } from '#utils/file_system.js';
+import { executeCommand, executeCommandWithMessages } from '#utils/process.js';
+import { getFrameworkVersion } from '#utils/framework_version.js';
+import { getErrorMessage, getErrorCode } from '#utils/error_utils.js';
+import { isDockerInstalled } from '#services/docker.js';
+import { isClaudeCliAvailable } from '#utils/claude.js';
+import { configureEnvironmentVariables } from './env_configurator.js';
+import { getTemplateFiles, processTemplateFile } from './template_processor.js';
+import { initializeAgentConfig } from './coding_agents.js';
+import { getProjectSuccessMessage } from './messages.js';
+/**
+ * Check for required dependencies (Docker and Claude CLI)
+ * Prompts user to continue if dependencies are missing
+ * @throws UserCancelledError if user declines to proceed without dependencies
+ */
+export async function checkDependencies() {
+    const dockerInstalled = isDockerInstalled();
+    const claudeAvailable = isClaudeCliAvailable();
+    if (dockerInstalled && claudeAvailable) {
+        return;
+    }
+    const missingDeps = [];
+    if (!dockerInstalled) {
+        missingDeps.push('Docker (https://docs.docker.com/)');
+    }
+    if (!claudeAvailable) {
+        missingDeps.push('Claude CLI (https://code.claude.com/)');
+    }
+    const depList = missingDeps.join('\n  - ');
+    const message = `The following dependencies are missing:\n  - ${depList}\n\n` +
+        'Some features may not work correctly without these dependencies.';
+    ux.warn(message);
+    try {
+        const shouldProceed = await confirm({
+            message: 'Would you like to proceed anyway?',
+            default: false
+        });
+        if (!shouldProceed) {
+            throw new UserCancelledError();
+        }
+    }
+    catch {
+        throw new UserCancelledError();
+    }
+}
+const promptForFolderName = async (projectName) => {
+    return await input({
+        message: 'What folder name should be used?',
+        default: kebabCase(projectName)
+    }) || kebabCase(projectName);
+};
+const promptForProjectName = async (defaultProjectName) => {
+    return await input({
+        message: 'What is your project name?',
+        default: defaultProjectName
+    }) || defaultProjectName;
+};
+const generateProjectDescription = (projectName) => {
+    return `AI Agents & Workflows built with Output.ai for ${kebabCase(projectName)}`;
+};
+/**
+ * Get project configuration from user input
+ * @param userFolderNameArg - Optional folder name to skip folder name prompt
+ */
+export const getProjectConfig = async (userFolderNameArg) => {
+    const defaultProjectName = 'my-outputai-workflows';
+    try {
+        const projectName = userFolderNameArg ?
+            userFolderNameArg :
+            await promptForProjectName(defaultProjectName);
+        const folderName = userFolderNameArg ?
+            userFolderNameArg :
+            await promptForFolderName(projectName);
+        const description = generateProjectDescription(projectName);
+        return {
+            projectName,
+            folderName,
+            projectPath: path.resolve(process.cwd(), folderName),
+            description
+        };
+    }
+    catch {
+        throw new UserCancelledError();
+    }
+};
+async function scaffoldProjectFiles(projectPath, projectName, description) {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
+    const templatesDir = path.join(__dirname, '..', 'templates', 'project');
+    // Get framework version for dynamic template injection
+    const frameworkVersion = await getFrameworkVersion();
+    const templateVars = {
+        projectName: kebabCase(projectName),
+        ProjectName: pascalCase(projectName),
+        description: description || `An Output.ai workflow for ${projectName}`,
+        frameworkVersion: frameworkVersion.framework
+    };
+    const templateFiles = await getTemplateFiles(templatesDir);
+    await Promise.all(templateFiles.map(templateFile => processTemplateFile(templateFile, projectPath, templateVars)));
+    return templateFiles.map(f => f.outputName);
+}
+async function executeNpmInstall(projectPath) {
+    await executeCommand('npm', ['install'], projectPath);
+}
+async function initializeAgents(projectPath) {
+    await initializeAgentConfig({ projectRoot: projectPath, force: false });
+}
+/**
+ * Format error message for init errors
+ * Single responsibility: only format error messages, no cleanup logic
+ */
+function formatInitError(error, projectPath) {
+    if (error instanceof UserCancelledError) {
+        return error.message;
+    }
+    if (error instanceof FolderAlreadyExistsError) {
+        return error.message;
+    }
+    const errorCode = getErrorCode(error);
+    const pathSuffix = projectPath ? ` at ${projectPath}` : '';
+    switch (errorCode) {
+        case 'EEXIST': return 'Folder already exists';
+        case 'EACCES': return `Permission denied${pathSuffix}`;
+        case 'ENOSPC': return `Not enough disk space${pathSuffix}`;
+        case 'EPERM': return `Operation not permitted${pathSuffix}`;
+        case 'ENOENT': return `Required file or directory not found${pathSuffix}`;
+        default: {
+            const originalMessage = error instanceof Error ? error.message : String(error);
+            return `Failed to create project${pathSuffix}: ${originalMessage}`;
+        }
+    }
+}
+/**
+ * Create a SIGINT handler for cleanup during init
+ * Exits immediately without prompting to avoid race conditions
+ * @param projectPath - Path to the project folder
+ * @param folderCreated - Whether the folder has been created
+ */
+export function createSigintHandler(projectPath, folderCreated) {
+    return () => {
+        ux.stdout('\n');
+        if (folderCreated) {
+            ux.warn(`Incomplete project folder may exist at: ${projectPath}`);
+            ux.warn(`Run: rm -rf "${projectPath}" to clean up`);
+        }
+        process.exit(130);
+    };
+}
+function handleRunInitError(error, projectPath, projectFolderCreated) {
+    const errorMessage = formatInitError(error, projectPath);
+    if (projectFolderCreated && projectPath) {
+        ux.warn(`Incomplete project folder may exist at: ${projectPath}`);
+        ux.warn(`Run: rm -rf "${projectPath}" to clean up`);
+    }
+    throw new Error(errorMessage);
+}
+/**
+ * Run the init command workflow
+ * @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) {
+    // Track state for SIGINT cleanup using an object to avoid let
+    const state = {
+        projectFolderCreated: false,
+        projectPath: ''
+    };
+    // Create and register SIGINT handler
+    const sigintHandler = () => {
+        const handler = createSigintHandler(state.projectPath, state.projectFolderCreated);
+        handler();
+    };
+    process.on('SIGINT', sigintHandler);
+    try {
+        // Check dependencies first
+        await checkDependencies();
+        const config = await getProjectConfig(folderName);
+        state.projectPath = config.projectPath;
+        try {
+            createDirectory(config.projectPath);
+            state.projectFolderCreated = true;
+        }
+        catch (error) {
+            throw new DirectoryCreationError(getErrorMessage(error), config.projectPath);
+        }
+        ux.stdout(`Created project folder: ${config.folderName}`);
+        const filesCreated = await scaffoldProjectFiles(config.projectPath, config.projectName, config.description);
+        ux.stdout(`Created ${filesCreated.length} project files`);
+        const envConfigured = await configureEnvironmentVariables(config.projectPath, skipEnv);
+        if (envConfigured) {
+            ux.stdout('Environment variables configured in .env');
+        }
+        await executeCommandWithMessages(() => initializeAgents(config.projectPath), 'Initializing agent system...', 'Agent system initialized');
+        const installSuccess = await executeCommandWithMessages(() => executeNpmInstall(config.projectPath), 'Installing dependencies...', 'Dependencies installed');
+        const nextSteps = getProjectSuccessMessage(config.folderName, installSuccess, envConfigured);
+        ux.stdout('Project created successfully!');
+        ux.stdout(nextSteps);
+    }
+    catch (error) {
+        handleRunInitError(error, state.projectPath || null, state.projectFolderCreated);
+    }
+    finally {
+        // Remove SIGINT handler on completion (success or error)
+        process.removeListener('SIGINT', sigintHandler);
+    }
+}

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

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

package/dist/services/project_scaffold.spec.js

@@ -0,0 +1,122 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { getProjectConfig, checkDependencies, createSigintHandler } from './project_scaffold.js';
+import { UserCancelledError } from '#types/errors.js';
+// Mock the framework version utility
+vi.mock('#utils/framework_version.js', () => ({
+    getFrameworkVersion: vi.fn().mockResolvedValue({
+        framework: '0.1.1'
+    })
+}));
+// Mock other dependencies
+vi.mock('@inquirer/prompts', () => ({
+    input: vi.fn(),
+    confirm: vi.fn()
+}));
+vi.mock('#utils/file_system.js');
+vi.mock('#utils/process.js');
+vi.mock('./env_configurator.js', () => ({
+    configureEnvironmentVariables: vi.fn().mockResolvedValue(false)
+}));
+vi.mock('./template_processor.js');
+vi.mock('./coding_agents.js');
+vi.mock('#services/docker.js', () => ({
+    isDockerInstalled: vi.fn().mockReturnValue(true)
+}));
+vi.mock('#utils/claude.js', () => ({
+    isClaudeCliAvailable: vi.fn().mockReturnValue(true)
+}));
+vi.mock('@oclif/core', () => ({
+    ux: {
+        stdout: vi.fn(),
+        warn: vi.fn()
+    }
+}));
+describe('project_scaffold', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('getProjectConfig', () => {
+        it('should skip all prompts when folderName is provided', async () => {
+            const { input } = await import('@inquirer/prompts');
+            const config = await getProjectConfig('my-project');
+            expect(config.folderName).toBe('my-project');
+            expect(config.projectName).toBe('my-project');
+            expect(input).not.toHaveBeenCalled();
+        });
+        it('should auto-generate description when folderName provided', async () => {
+            const config = await getProjectConfig('test-folder');
+            expect(config.description).toBe('AI Agents & Workflows built with Output.ai for test-folder');
+        });
+        it('should prompt for project name and folder name when not provided', async () => {
+            const { input } = await import('@inquirer/prompts');
+            vi.mocked(input)
+                .mockResolvedValueOnce('Test Project')
+                .mockResolvedValueOnce('test-project');
+            const config = await getProjectConfig();
+            expect(config.projectName).toBe('Test Project');
+            expect(config.folderName).toBe('test-project');
+            expect(config.description).toBe('AI Agents & Workflows built with Output.ai for test-project');
+            expect(input).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('checkDependencies', () => {
+        it('should not prompt when all dependencies are available', async () => {
+            const { isDockerInstalled } = await import('#services/docker.js');
+            const { isClaudeCliAvailable } = await import('#utils/claude.js');
+            const { confirm } = await import('@inquirer/prompts');
+            vi.mocked(isDockerInstalled).mockReturnValue(true);
+            vi.mocked(isClaudeCliAvailable).mockReturnValue(true);
+            await checkDependencies();
+            expect(confirm).not.toHaveBeenCalled();
+        });
+        it('should prompt user when docker is missing', async () => {
+            const { isDockerInstalled } = await import('#services/docker.js');
+            const { isClaudeCliAvailable } = await import('#utils/claude.js');
+            const { confirm } = await import('@inquirer/prompts');
+            vi.mocked(isDockerInstalled).mockReturnValue(false);
+            vi.mocked(isClaudeCliAvailable).mockReturnValue(true);
+            vi.mocked(confirm).mockResolvedValue(true);
+            await checkDependencies();
+            expect(confirm).toHaveBeenCalledWith(expect.objectContaining({
+                message: expect.stringContaining('proceed')
+            }));
+        });
+        it('should throw UserCancelledError when user declines to proceed', async () => {
+            const { isDockerInstalled } = await import('#services/docker.js');
+            const { isClaudeCliAvailable } = await import('#utils/claude.js');
+            const { confirm } = await import('@inquirer/prompts');
+            vi.mocked(isDockerInstalled).mockReturnValue(false);
+            vi.mocked(isClaudeCliAvailable).mockReturnValue(true);
+            vi.mocked(confirm).mockResolvedValue(false);
+            await expect(checkDependencies()).rejects.toThrow(UserCancelledError);
+        });
+    });
+    describe('SIGINT handler', () => {
+        it('should show cleanup message when project folder was created', async () => {
+            const { ux } = await import('@oclif/core');
+            const handler = createSigintHandler('/test/project', true);
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined);
+            handler();
+            expect(ux.warn).toHaveBeenCalledWith(expect.stringContaining('/test/project'));
+            expect(ux.warn).toHaveBeenCalledWith(expect.stringContaining('rm -rf'));
+            expect(exitSpy).toHaveBeenCalledWith(130);
+            exitSpy.mockRestore();
+        });
+        it('should exit immediately without warning when folder not created', async () => {
+            const { ux } = await import('@oclif/core');
+            const handler = createSigintHandler('/nonexistent', false);
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined);
+            handler();
+            expect(ux.warn).not.toHaveBeenCalled();
+            expect(exitSpy).toHaveBeenCalledWith(130);
+            exitSpy.mockRestore();
+        });
+        it('should exit with code 130 (SIGINT convention)', async () => {
+            const handler = createSigintHandler('/test/project', true);
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined);
+            handler();
+            expect(exitSpy).toHaveBeenCalledWith(130);
+            exitSpy.mockRestore();
+        });
+    });
+});

package/dist/services/s3_trace_downloader.d.ts

@@ -0,0 +1,12 @@
+import type { TraceData } from '#types/trace.js';
+interface RemoteTraceInfo {
+    key: string;
+    lastModified?: Date;
+    size?: number;
+}
+export declare function listRemoteTraces(workflowName: string, options?: {
+    limit?: number;
+    since?: Date;
+}): Promise<RemoteTraceInfo[]>;
+export declare function downloadRemoteTrace(key: string): Promise<TraceData>;
+export {};

package/dist/services/s3_trace_downloader.js

@@ -0,0 +1,57 @@
+import { S3Client, ListObjectsV2Command, GetObjectCommand } from '@aws-sdk/client-s3';
+import { config } from '#config.js';
+function getS3Config() {
+    const { bucket, region, accessKeyId, secretAccessKey } = config.s3;
+    if (!bucket || !region || !accessKeyId || !secretAccessKey) {
+        throw new Error('Missing S3 configuration. Set OUTPUT_TRACE_REMOTE_S3_BUCKET, OUTPUT_AWS_REGION, ' +
+            'OUTPUT_AWS_ACCESS_KEY_ID, and OUTPUT_AWS_SECRET_ACCESS_KEY environment variables.');
+    }
+    return { bucket, region, accessKeyId, secretAccessKey };
+}
+function createS3Client(s3Config) {
+    return new S3Client({
+        region: s3Config.region,
+        credentials: {
+            accessKeyId: s3Config.accessKeyId,
+            secretAccessKey: s3Config.secretAccessKey
+        }
+    });
+}
+export async function listRemoteTraces(workflowName, options = {}) {
+    const s3Config = getS3Config();
+    const client = createS3Client(s3Config);
+    const limit = options.limit ?? 20;
+    const command = new ListObjectsV2Command({
+        Bucket: s3Config.bucket,
+        Prefix: `${workflowName}/`,
+        MaxKeys: limit
+    });
+    const response = await client.send(command);
+    const contents = response.Contents ?? [];
+    return contents
+        .filter(obj => {
+        if (!obj.Key) {
+            return false;
+        }
+        if (options.since && obj.LastModified && obj.LastModified < options.since) {
+            return false;
+        }
+        return true;
+    })
+        .map(obj => ({
+        key: obj.Key,
+        lastModified: obj.LastModified,
+        size: obj.Size
+    }));
+}
+export async function downloadRemoteTrace(key) {
+    const s3Config = getS3Config();
+    const client = createS3Client(s3Config);
+    const command = new GetObjectCommand({ Bucket: s3Config.bucket, Key: key });
+    const response = await client.send(command);
+    const body = await response.Body?.transformToString();
+    if (!body) {
+        throw new Error(`Empty response for S3 object: ${key}`);
+    }
+    return JSON.parse(body);
+}

package/dist/services/template_processor.d.ts

@@ -0,0 +1,14 @@
+import type { TemplateFile } from '#types/generator.js';
+/**
+ * Get list of template files from a directory
+ * Automatically discovers all .template files (including in subdirectories) and derives output names
+ */
+export declare function getTemplateFiles(templatesDir: string): Promise<TemplateFile[]>;
+/**
+ * Process a single template file
+ */
+export declare function processTemplateFile(templateFile: TemplateFile, targetDir: string, variables: Record<string, string>): Promise<void>;
+/**
+ * Process all template files
+ */
+export declare function processAllTemplates(templateFiles: TemplateFile[], targetDir: string, variables: Record<string, string>): Promise<string[]>;

package/dist/services/template_processor.js

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { processTemplate } from '#utils/template.js';
+const TEMPLATE_EXTENSION = '.template';
+const isTemplateFile = (file) => file.endsWith(TEMPLATE_EXTENSION);
+const fileToTemplateFile = (file, templatesDir, relativePath = '') => {
+    const fullPath = relativePath ? path.join(relativePath, file) : file;
+    return {
+        name: file,
+        path: path.join(templatesDir, relativePath, file),
+        outputName: fullPath.replace(TEMPLATE_EXTENSION, '')
+    };
+};
+const processEntry = async (entry, templatesDir, relativePath, getFilesRecursively) => {
+    if (entry.isDirectory()) {
+        const subDir = relativePath ? path.join(relativePath, entry.name) : entry.name;
+        return getFilesRecursively(templatesDir, subDir);
+    }
+    if (entry.isFile() && isTemplateFile(entry.name)) {
+        return [fileToTemplateFile(entry.name, templatesDir, relativePath)];
+    }
+    return [];
+};
+async function getTemplateFilesRecursive(templatesDir, relativePath = '') {
+    const fullPath = relativePath ? path.join(templatesDir, relativePath) : templatesDir;
+    const entries = await fs.readdir(fullPath, { withFileTypes: true });
+    const results = await Promise.all(entries.map(entry => processEntry(entry, templatesDir, relativePath, getTemplateFilesRecursive)));
+    return results.flatMap(x => x);
+}
+/**
+ * Get list of template files from a directory
+ * Automatically discovers all .template files (including in subdirectories) and derives output names
+ */
+export async function getTemplateFiles(templatesDir) {
+    return getTemplateFilesRecursive(templatesDir);
+}
+/**
+ * Process a single template file
+ */
+export async function processTemplateFile(templateFile, targetDir, variables) {
+    const templateContent = await fs.readFile(templateFile.path, 'utf-8');
+    const processedContent = processTemplate(templateContent, variables);
+    const outputPath = path.join(targetDir, templateFile.outputName);
+    // Create parent directories if they don't exist
+    const outputDir = path.dirname(outputPath);
+    await fs.mkdir(outputDir, { recursive: true });
+    await fs.writeFile(outputPath, processedContent, 'utf-8');
+}
+/**
+ * Process all template files
+ */
+export async function processAllTemplates(templateFiles, targetDir, variables) {
+    return Promise.all(templateFiles.map(async (templateFile) => {
+        await processTemplateFile(templateFile, targetDir, variables);
+        return templateFile.outputName;
+    }));
+}

package/dist/services/trace_reader.d.ts

@@ -0,0 +1,16 @@
+import type { TraceData } from '#types/trace.js';
+export type { TraceData };
+export interface TraceLocation {
+    path: string;
+    isRemote: boolean;
+}
+export interface TraceResult {
+    data: TraceData;
+    location: TraceLocation;
+}
+/**
+ * Get trace data from workflow ID using the API
+ * The API handles S3 fetching - CLI only needs to read local files when necessary
+ * @returns Both the trace data and the location it was fetched from
+ */
+export declare function getTrace(workflowId: string): Promise<TraceResult>;

package/dist/services/trace_reader.js

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises';
+import { getWorkflowIdTraceLog } from '#api/generated/api.js';
+import { getErrorCode } from '#utils/error_utils.js';
+/**
+ * Read and parse trace file from local path
+ */
+async function readLocalTraceFile(path) {
+    try {
+        const content = await readFile(path, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (getErrorCode(error) === 'ENOENT') {
+            throw new Error(`Trace file not found at path: ${path}`);
+        }
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in trace file: ${path}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Get trace data from workflow ID using the API
+ * The API handles S3 fetching - CLI only needs to read local files when necessary
+ * @returns Both the trace data and the location it was fetched from
+ */
+export async function getTrace(workflowId) {
+    const response = await getWorkflowIdTraceLog(workflowId);
+    if (response.status === 404) {
+        throw new Error(`Workflow not found or no trace available: ${workflowId}`);
+    }
+    if (response.status === 500) {
+        const errorData = response.data;
+        const errorMessage = errorData?.error || 'Failed to fetch trace from API';
+        throw new Error(`API error (500): ${errorMessage}`);
+    }
+    if (response.status !== 200) {
+        const errorResponse = response;
+        throw new Error(`Unexpected API response status: ${errorResponse.status}`);
+    }
+    const data = response.data;
+    if (data.source === 'remote') {
+        return {
+            data: data.data,
+            location: { path: 'remote', isRemote: true }
+        };
+    }
+    if (data.source === 'local') {
+        const localPath = data.localPath;
+        const traceData = await readLocalTraceFile(localPath);
+        return {
+            data: traceData,
+            location: { path: localPath, isRemote: false }
+        };
+    }
+    throw new Error('Invalid trace log response format');
+}

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

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

package/dist/services/trace_reader.spec.js

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+const mockGetWorkflowIdTraceLog = vi.fn();
+vi.mock('#api/generated/api.js', () => ({
+    getWorkflowIdTraceLog: (...args) => mockGetWorkflowIdTraceLog(...args)
+}));
+const mockReadFile = vi.fn();
+vi.mock('node:fs/promises', () => ({
+    readFile: (...args) => mockReadFile(...args)
+}));
+describe('trace_reader', () => {
+    beforeEach(() => {
+        mockGetWorkflowIdTraceLog.mockReset();
+        mockReadFile.mockReset();
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    describe('getTrace', () => {
+        it('should return trace data directly for remote source', async () => {
+            const mockTraceData = {
+                root: { workflowName: 'test', workflowId: 'wf-123', startTime: Date.now() },
+                children: []
+            };
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
+                status: 200,
+                data: {
+                    source: 'remote',
+                    data: mockTraceData
+                }
+            });
+            const { getTrace } = await import('./trace_reader.js');
+            const result = await getTrace('wf-123');
+            expect(result.data).toEqual(mockTraceData);
+            expect(result.location.isRemote).toBe(true);
+            expect(mockReadFile).not.toHaveBeenCalled();
+        });
+        it('should read local file for local source', async () => {
+            const mockTraceData = {
+                root: { workflowName: 'test', workflowId: 'wf-123', startTime: Date.now() },
+                children: []
+            };
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
+                status: 200,
+                data: {
+                    source: 'local',
+                    localPath: '/path/to/trace.json'
+                }
+            });
+            mockReadFile.mockResolvedValue(JSON.stringify(mockTraceData));
+            const { getTrace } = await import('./trace_reader.js');
+            const result = await getTrace('wf-123');
+            expect(result.data).toEqual(mockTraceData);
+            expect(result.location.isRemote).toBe(false);
+            expect(result.location.path).toBe('/path/to/trace.json');
+            expect(mockReadFile).toHaveBeenCalledWith('/path/to/trace.json', 'utf-8');
+        });
+        it('should throw error when API returns 404', async () => {
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
+                status: 404,
+                data: { error: 'Not found' }
+            });
+            const { getTrace } = await import('./trace_reader.js');
+            await expect(getTrace('wf-123'))
+                .rejects
+                .toThrow('Workflow not found or no trace available: wf-123');
+        });
+        it('should throw error when API returns 500', async () => {
+            mockGetWorkflowIdTraceLog.mockResolvedValue({
+                status: 500,
+                data: { error: 'S3 access denied' }
+            });
+            const { getTrace } = await import('./trace_reader.js');
+            await expect(getTrace('wf-123'))
+                .rejects
+                .toThrow('S3 access denied');
+        });
+    });
+});

package/dist/services/version_check.d.ts

@@ -0,0 +1,6 @@
+export interface VersionCheckResult {
+    updateAvailable: boolean;
+    currentVersion: string;
+    latestVersion: string;
+}
+export declare function checkForUpdate(currentVersion: string, cacheDir?: string): Promise<VersionCheckResult>;