@agents-at-scale/ark 0.1.35-rc.1 → 0.1.35-rc2

package/dist/lib/config.spec.js

@@ -0,0 +1,99 @@
+import { jest } from '@jest/globals';
+import path from 'path';
+import os from 'os';
+const mockFs = {
+    existsSync: jest.fn(),
+    readFileSync: jest.fn(),
+};
+jest.unstable_mockModule('fs', () => ({
+    default: mockFs,
+    ...mockFs,
+}));
+const mockYaml = {
+    parse: jest.fn(),
+    stringify: jest.fn(),
+};
+jest.unstable_mockModule('yaml', () => ({
+    default: mockYaml,
+    ...mockYaml,
+}));
+const { loadConfig, getConfigPaths, formatConfig } = await import('./config.js');
+describe('config', () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        process.env = { ...originalEnv };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    it('returns default config when no files exist', () => {
+        mockFs.existsSync.mockReturnValue(false);
+        const config = loadConfig();
+        expect(config).toEqual({
+            chat: {
+                streaming: true,
+                outputFormat: 'text',
+            },
+        });
+    });
+    it('loads and merges configs in order: defaults, user, project', () => {
+        mockFs.existsSync.mockReturnValue(true);
+        mockFs.readFileSync
+            .mockReturnValueOnce('user yaml')
+            .mockReturnValueOnce('project yaml');
+        mockYaml.parse
+            .mockReturnValueOnce({
+            chat: {
+                streaming: false,
+                outputFormat: 'markdown',
+            },
+        })
+            .mockReturnValueOnce({
+            chat: {
+                streaming: true,
+            },
+        });
+        const config = loadConfig();
+        expect(config.chat?.streaming).toBe(true);
+        expect(config.chat?.outputFormat).toBe('markdown');
+    });
+    it('environment variables override all configs', () => {
+        mockFs.existsSync.mockReturnValue(false);
+        process.env.ARK_CHAT_STREAMING = '1';
+        process.env.ARK_CHAT_OUTPUT_FORMAT = 'MARKDOWN';
+        const config = loadConfig();
+        expect(config.chat?.streaming).toBe(true);
+        expect(config.chat?.outputFormat).toBe('markdown');
+    });
+    it('throws error for invalid YAML', () => {
+        const userConfigPath = path.join(os.homedir(), '.arkrc.yaml');
+        mockFs.existsSync.mockImplementation((path) => path === userConfigPath);
+        mockFs.readFileSync.mockReturnValue('invalid yaml');
+        mockYaml.parse.mockImplementation(() => {
+            throw new Error('YAML parse error');
+        });
+        expect(() => loadConfig()).toThrow(`Invalid YAML in ${userConfigPath}: YAML parse error`);
+    });
+    it('handles non-Error exceptions', () => {
+        const userConfigPath = path.join(os.homedir(), '.arkrc.yaml');
+        mockFs.existsSync.mockImplementation((path) => path === userConfigPath);
+        mockFs.readFileSync.mockReturnValue('invalid yaml');
+        mockYaml.parse.mockImplementation(() => {
+            throw 'string error';
+        });
+        expect(() => loadConfig()).toThrow(`Invalid YAML in ${userConfigPath}: Unknown error`);
+    });
+    it('getConfigPaths returns correct paths', () => {
+        const paths = getConfigPaths();
+        expect(paths.user).toBe(path.join(os.homedir(), '.arkrc.yaml'));
+        expect(paths.project).toBe(path.join(process.cwd(), '.arkrc.yaml'));
+    });
+    it('formatConfig uses yaml.stringify', () => {
+        const config = { chat: { streaming: true, outputFormat: 'text' } };
+        mockYaml.stringify.mockReturnValue('formatted');
+        const result = formatConfig(config);
+        expect(mockYaml.stringify).toHaveBeenCalledWith(config);
+        expect(result).toBe('formatted');
+    });
+});

package/dist/lib/consts.d.ts

@@ -7,4 +7,3 @@ export declare const DEFAULT_ARK_DASHBOARD_URL = "http://localhost:3000";
 export declare const DEFAULT_ARK_A2A_URL = "http://localhost:8080";
 export declare const DEFAULT_ARK_MEMORY_URL = "http://localhost:8081";
 export declare const DEFAULT_ARK_OTEL_URL = "http://localhost:4318";
-export declare const ARK_REPO_ERROR_MESSAGE = "Error: This command must be run inside the ARK repository.";

package/dist/lib/consts.js

@@ -11,5 +11,3 @@ export const DEFAULT_ARK_DASHBOARD_URL = 'http://localhost:3000';
 export const DEFAULT_ARK_A2A_URL = 'http://localhost:8080';
 export const DEFAULT_ARK_MEMORY_URL = 'http://localhost:8081';
 export const DEFAULT_ARK_OTEL_URL = 'http://localhost:4318';
-// Error message for different ARK repo
-export const ARK_REPO_ERROR_MESSAGE = 'Error: This command must be run inside the ARK repository.';

package/dist/lib/consts.spec.d.ts

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

package/dist/lib/consts.spec.js

@@ -0,0 +1,15 @@
+import { describe, it, expect } from '@jest/globals';
+import { DEFAULT_ADDRESS_ARK_API, DEFAULT_TIMEOUT_MS, DEFAULT_CONNECTION_TEST_TIMEOUT_MS, CONFIG_DIR_NAME, CONFIG_FILE_NAME, DEFAULT_ARK_DASHBOARD_URL, DEFAULT_ARK_A2A_URL, DEFAULT_ARK_MEMORY_URL, DEFAULT_ARK_OTEL_URL, } from './consts.js';
+describe('Constants', () => {
+    it('defines correct default values', () => {
+        expect(DEFAULT_ADDRESS_ARK_API).toBe('http://localhost:8000');
+        expect(DEFAULT_TIMEOUT_MS).toBe(30000);
+        expect(DEFAULT_CONNECTION_TEST_TIMEOUT_MS).toBe(5000);
+        expect(CONFIG_DIR_NAME).toBe('ark');
+        expect(CONFIG_FILE_NAME).toBe('ark-cli.json');
+        expect(DEFAULT_ARK_DASHBOARD_URL).toBe('http://localhost:3000');
+        expect(DEFAULT_ARK_A2A_URL).toBe('http://localhost:8080');
+        expect(DEFAULT_ARK_MEMORY_URL).toBe('http://localhost:8081');
+        expect(DEFAULT_ARK_OTEL_URL).toBe('http://localhost:4318');
+    });
+});

package/dist/lib/errors.js

@@ -162,9 +162,9 @@ export class InputValidator {
         if (!kebabRegex.test(trimmed)) {
             const suggestions = [];
             const normalized = trimmed
+                .replace(/([a-z])([A-Z])/g, '$1-$2') // Handle camelCase first
                 .toLowerCase()
                 .replace(/[\s_]+/g, '-')
-                .replace(/([a-z])([A-Z])/g, '$1-$2')
                 .replace(/-{2,}/g, '-') // Replace 2+ consecutive hyphens with single hyphen (ReDoS-safe)
                 .replace(/^-/, '') // Remove single leading hyphen (ReDoS-safe)
                 .replace(/-$/, ''); // Remove single trailing hyphen (ReDoS-safe)

package/dist/lib/errors.spec.d.ts

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

package/dist/lib/errors.spec.js

@@ -0,0 +1,221 @@
+import { describe, it, expect, jest, beforeEach, afterEach } from '@jest/globals';
+import { ErrorCode, ArkError, ValidationError, TemplateError, ProjectStructureError, ErrorHandler, InputValidator, } from './errors.js';
+jest.mock('fs');
+describe('Error Classes', () => {
+    describe('ArkError', () => {
+        it('creates error with default code', () => {
+            const error = new ArkError('test message');
+            expect(error.message).toBe('test message');
+            expect(error.code).toBe(ErrorCode.UNKNOWN_ERROR);
+            expect(error.name).toBe('ArkError');
+            expect(error.details).toBeUndefined();
+            expect(error.suggestions).toBeUndefined();
+        });
+        it('creates error with all properties', () => {
+            const error = new ArkError('test error', ErrorCode.INVALID_INPUT, { field: 'name' }, ['Check the input', 'Try again']);
+            expect(error.message).toBe('test error');
+            expect(error.code).toBe(ErrorCode.INVALID_INPUT);
+            expect(error.details).toEqual({ field: 'name' });
+            expect(error.suggestions).toEqual(['Check the input', 'Try again']);
+        });
+    });
+    describe('ValidationError', () => {
+        it('creates validation error without field', () => {
+            const error = new ValidationError('validation failed');
+            expect(error.message).toBe('validation failed');
+            expect(error.code).toBe(ErrorCode.VALIDATION_ERROR);
+            expect(error.name).toBe('ValidationError');
+            expect(error.details).toBeUndefined();
+        });
+        it('creates validation error with field and suggestions', () => {
+            const error = new ValidationError('invalid email', 'email', [
+                'Use valid format',
+            ]);
+            expect(error.message).toBe('invalid email');
+            expect(error.code).toBe(ErrorCode.VALIDATION_ERROR);
+            expect(error.details).toEqual({ field: 'email' });
+            expect(error.suggestions).toEqual(['Use valid format']);
+        });
+    });
+    describe('TemplateError', () => {
+        it('creates template error', () => {
+            const error = new TemplateError('template failed', 'template.yaml');
+            expect(error.message).toBe('template failed');
+            expect(error.code).toBe(ErrorCode.TEMPLATE_ERROR);
+            expect(error.name).toBe('TemplateError');
+            expect(error.details).toEqual({ templatePath: 'template.yaml' });
+        });
+    });
+    describe('ProjectStructureError', () => {
+        it('creates project structure error with defaults', () => {
+            const error = new ProjectStructureError('project invalid');
+            expect(error.message).toBe('project invalid');
+            expect(error.code).toBe(ErrorCode.PROJECT_STRUCTURE_INVALID);
+            expect(error.name).toBe('ProjectStructureError');
+            expect(error.suggestions).toEqual([
+                'Ensure you are in a valid ARK project directory',
+                'Run "ark generate project" to create a new project',
+                'Check that Chart.yaml and agents/ directory exist',
+            ]);
+        });
+        it('creates project structure error with path', () => {
+            const error = new ProjectStructureError('project invalid', '/path/to/project');
+            expect(error.message).toBe('project invalid');
+            expect(error.code).toBe(ErrorCode.PROJECT_STRUCTURE_INVALID);
+            expect(error.details).toEqual({ projectPath: '/path/to/project' });
+        });
+    });
+    describe('ErrorHandler', () => {
+        it('formats basic error', () => {
+            const error = new Error('simple error');
+            const formatted = ErrorHandler.formatError(error);
+            expect(formatted).toContain('❌ simple error');
+        });
+        it('formats ArkError with details and suggestions', () => {
+            const error = new ArkError('test error', ErrorCode.INVALID_INPUT, { field: 'name', value: 'test' }, ['Fix the input', 'Try again']);
+            const formatted = ErrorHandler.formatError(error);
+            expect(formatted).toContain('❌ test error');
+            expect(formatted).toContain('Details:');
+            expect(formatted).toContain('field: name');
+            expect(formatted).toContain('value: test');
+            expect(formatted).toContain('💡 Suggestions:');
+            expect(formatted).toContain('• Fix the input');
+            expect(formatted).toContain('• Try again');
+        });
+        it('includes stack trace in debug mode', () => {
+            process.env.DEBUG = 'true';
+            const error = new Error('debug error');
+            const formatted = ErrorHandler.formatError(error);
+            expect(formatted).toContain('Stack trace:');
+            delete process.env.DEBUG;
+        });
+        it('handles missing stack trace', () => {
+            process.env.NODE_ENV = 'development';
+            const error = new Error('no stack');
+            error.stack = undefined;
+            const formatted = ErrorHandler.formatError(error);
+            expect(formatted).toContain('No stack trace available');
+            delete process.env.NODE_ENV;
+        });
+        describe('handleAndExit', () => {
+            let mockExit;
+            let mockConsoleError;
+            beforeEach(() => {
+                mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+                    throw new Error('process.exit');
+                });
+                mockConsoleError = jest
+                    .spyOn(console, 'error')
+                    .mockImplementation(() => { });
+            });
+            afterEach(() => {
+                mockExit.mockRestore();
+                mockConsoleError.mockRestore();
+            });
+            it('exits with code 22 for validation errors', () => {
+                const error = new ValidationError('invalid');
+                expect(() => ErrorHandler.handleAndExit(error)).toThrow('process.exit');
+                expect(mockExit).toHaveBeenCalledWith(22);
+            });
+            it('exits with code 2 for file not found', () => {
+                const error = new ArkError('not found', ErrorCode.FILE_NOT_FOUND);
+                expect(() => ErrorHandler.handleAndExit(error)).toThrow('process.exit');
+                expect(mockExit).toHaveBeenCalledWith(2);
+            });
+            it('exits with code 13 for permission denied', () => {
+                const error = new ArkError('denied', ErrorCode.PERMISSION_DENIED);
+                expect(() => ErrorHandler.handleAndExit(error)).toThrow('process.exit');
+                expect(mockExit).toHaveBeenCalledWith(13);
+            });
+            it('exits with code 127 for missing dependency', () => {
+                const error = new ArkError('missing', ErrorCode.DEPENDENCY_MISSING);
+                expect(() => ErrorHandler.handleAndExit(error)).toThrow('process.exit');
+                expect(mockExit).toHaveBeenCalledWith(127);
+            });
+            it('exits with code 1 for unknown errors', () => {
+                const error = new Error('unknown');
+                expect(() => ErrorHandler.handleAndExit(error)).toThrow('process.exit');
+                expect(mockExit).toHaveBeenCalledWith(1);
+            });
+            it('exits with code 1 for default ArkError', () => {
+                const error = new ArkError('general', ErrorCode.UNKNOWN_ERROR);
+                expect(() => ErrorHandler.handleAndExit(error)).toThrow('process.exit');
+                expect(mockExit).toHaveBeenCalledWith(1);
+            });
+        });
+        describe('catchAndHandle', () => {
+            it('returns successful promise result', async () => {
+                const result = await ErrorHandler.catchAndHandle(async () => 'success');
+                expect(result).toBe('success');
+            });
+            it('rethrows ArkError unchanged', async () => {
+                const arkError = new ValidationError('test');
+                await expect(ErrorHandler.catchAndHandle(async () => {
+                    throw arkError;
+                })).rejects.toThrow(arkError);
+            });
+            it('wraps generic errors with context', async () => {
+                const error = new Error('generic');
+                await expect(ErrorHandler.catchAndHandle(async () => {
+                    throw error;
+                }, 'context')).rejects.toThrow('context: generic');
+            });
+            it('wraps non-Error objects', async () => {
+                await expect(ErrorHandler.catchAndHandle(async () => {
+                    throw 'string error';
+                })).rejects.toThrow('string error');
+            });
+        });
+    });
+    describe('InputValidator', () => {
+        describe('validateName', () => {
+            it('accepts valid names', () => {
+                expect(() => InputValidator.validateName('valid-name')).not.toThrow();
+                expect(() => InputValidator.validateName('test123')).not.toThrow();
+                expect(() => InputValidator.validateName('a-b-c-123')).not.toThrow();
+            });
+            it('rejects empty names', () => {
+                expect(() => InputValidator.validateName('')).toThrow('name cannot be empty');
+                expect(() => InputValidator.validateName('   ')).toThrow('name cannot be empty');
+            });
+            it('rejects names over 63 characters', () => {
+                const longName = 'a'.repeat(64);
+                expect(() => InputValidator.validateName(longName)).toThrow('must be 63 characters or less');
+            });
+            it('rejects invalid characters', () => {
+                expect(() => InputValidator.validateName('Invalid Name')).toThrow('Invalid name');
+                expect(() => InputValidator.validateName('test_name')).toThrow('Invalid name');
+                expect(() => InputValidator.validateName('-start')).toThrow('Invalid name');
+                expect(() => InputValidator.validateName('end-')).toThrow('Invalid name');
+            });
+            it('suggests normalized names', () => {
+                try {
+                    InputValidator.validateName('TestName');
+                }
+                catch (e) {
+                    expect(e.suggestions).toContain('Try: "test-name"');
+                }
+            });
+        });
+        describe('validatePath', () => {
+            it('accepts valid paths', () => {
+                expect(() => InputValidator.validatePath('/valid/path')).not.toThrow();
+                expect(() => InputValidator.validatePath('./relative')).not.toThrow();
+                expect(() => InputValidator.validatePath('simple')).not.toThrow();
+            });
+            it('rejects empty paths', () => {
+                expect(() => InputValidator.validatePath('')).toThrow('path cannot be empty');
+            });
+            it('rejects dangerous paths', () => {
+                expect(() => InputValidator.validatePath('../parent')).toThrow('unsafe characters');
+                expect(() => InputValidator.validatePath('~/home')).toThrow('unsafe characters');
+                expect(() => InputValidator.validatePath('$HOME/test')).toThrow('unsafe characters');
+            });
+        });
+        describe('validateDirectory', () => {
+            it('validates path first', () => {
+                expect(() => InputValidator.validateDirectory('')).toThrow('directory cannot be empty');
+            });
+        });
+    });
+});

package/dist/lib/exec.d.ts

@@ -1,5 +1 @@
-export declare function executeCommand(command: string, args?: string[]): Promise<{
-    stdout: string;
-    stderr: string;
-}>;
 export declare function fileExists(path: string): boolean;

package/dist/lib/exec.js

@@ -1,15 +1,4 @@
 import fs from 'fs';
-import { execa } from 'execa';
-export async function executeCommand(command, args = []) {
-    try {
-        const result = await execa(command, args);
-        return { stdout: result.stdout, stderr: result.stderr };
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Command failed: ${command} ${args.join(' ')}\n${errorMessage}`);
-    }
-}
 export function fileExists(path) {
     try {
         return fs.existsSync(path);

package/dist/lib/nextSteps.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Print helpful next steps after successful ARK installation
+ */
+export declare function printNextSteps(): void;

package/dist/lib/nextSteps.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+/**
+ * Print helpful next steps after successful ARK installation
+ */
+export function printNextSteps() {
+    console.log();
+    console.log(chalk.green.bold('✓ ARK installed successfully!'));
+    console.log();
+    console.log(chalk.gray('Next steps:'));
+    console.log();
+    console.log(`  ${chalk.gray('docs:')}              ${chalk.blue('https://mckinsey.github.io/agents-at-scale-ark/')}`);
+    console.log(`  ${chalk.gray('create model:')}      ${chalk.white.bold('ark models create default')}`);
+    console.log(`  ${chalk.gray('open dashboard:')}    ${chalk.white.bold('ark dashboard')}`);
+    console.log(`  ${chalk.gray('show agents:')}       ${chalk.white.bold('kubectl get agents')}`);
+    console.log(`  ${chalk.gray('run a query:')}       ${chalk.white.bold('ark query model/default "What are large language models?"')}`);
+    console.log(`  ${chalk.gray('interactive chat:')}  ${chalk.white.bold('ark')} ${chalk.gray('# then choose \'Chat\'')}`);
+    console.log(`  ${chalk.gray('new project:')}       ${chalk.white.bold('ark generate project my-agents')}`);
+    console.log(`  ${chalk.gray('install fark:')}      ${chalk.blue('https://mckinsey.github.io/agents-at-scale-ark/developer-guide/cli-tools/')}`);
+    console.log();
+}

package/dist/lib/nextSteps.spec.d.ts

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

package/dist/lib/nextSteps.spec.js

@@ -0,0 +1,59 @@
+import { jest } from '@jest/globals';
+import { printNextSteps } from './nextSteps.js';
+describe('printNextSteps', () => {
+    let consoleLogSpy;
+    let output = [];
+    beforeEach(() => {
+        output = [];
+        consoleLogSpy = jest.spyOn(console, 'log').mockImplementation((...args) => {
+            output.push(args.join(' '));
+        });
+    });
+    afterEach(() => {
+        consoleLogSpy.mockRestore();
+    });
+    it('prints successful installation message', () => {
+        printNextSteps();
+        const fullOutput = output.join('\n');
+        expect(fullOutput).toContain('ARK installed successfully!');
+    });
+    it('includes all required commands', () => {
+        printNextSteps();
+        const fullOutput = output.join('\n');
+        // Check for each command
+        expect(fullOutput).toContain('ark models create default');
+        expect(fullOutput).toContain('ark dashboard');
+        expect(fullOutput).toContain('kubectl get agents');
+        expect(fullOutput).toContain('ark query model/default "What are large language models?"');
+        expect(fullOutput).toContain('ark');
+        expect(fullOutput).toContain("# then choose 'Chat'");
+        expect(fullOutput).toContain('ark generate project my-agents');
+    });
+    it('includes all required links', () => {
+        printNextSteps();
+        const fullOutput = output.join('\n');
+        // Check for documentation links
+        expect(fullOutput).toContain('https://mckinsey.github.io/agents-at-scale-ark/');
+        expect(fullOutput).toContain('https://mckinsey.github.io/agents-at-scale-ark/developer-guide/cli-tools/');
+    });
+    it('includes all section labels', () => {
+        printNextSteps();
+        const fullOutput = output.join('\n');
+        // Check for labels
+        expect(fullOutput).toContain('Next steps:');
+        expect(fullOutput).toContain('docs:');
+        expect(fullOutput).toContain('create model:');
+        expect(fullOutput).toContain('open dashboard:');
+        expect(fullOutput).toContain('show agents:');
+        expect(fullOutput).toContain('run a query:');
+        expect(fullOutput).toContain('interactive chat:');
+        expect(fullOutput).toContain('new project:');
+        expect(fullOutput).toContain('install fark:');
+    });
+    it('has correct structure with empty lines', () => {
+        printNextSteps();
+        // Should have empty lines for formatting
+        expect(output[0]).toBe('');
+        expect(output[output.length - 1]).toBe('');
+    });
+});

package/dist/lib/output.spec.d.ts

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

package/dist/lib/output.spec.js

@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
+import chalk from 'chalk';
+import output from './output.js';
+describe('output', () => {
+    let consoleErrorSpy;
+    let consoleLogSpy;
+    beforeEach(() => {
+        consoleErrorSpy = jest
+            .spyOn(console, 'error')
+            .mockImplementation(() => undefined);
+        consoleLogSpy = jest
+            .spyOn(console, 'log')
+            .mockImplementation(() => undefined);
+    });
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+    describe('error', () => {
+        it('should output error message with red cross and prefix', () => {
+            output.error('Something went wrong');
+            expect(consoleErrorSpy).toHaveBeenCalledWith(chalk.red('✗'), chalk.red('error:'), 'Something went wrong');
+        });
+        it('should handle additional arguments', () => {
+            const error = new Error('Test error');
+            output.error('Failed to connect', error, 123);
+            expect(consoleErrorSpy).toHaveBeenCalledWith(chalk.red('✗'), chalk.red('error:'), 'Failed to connect', error, 123);
+        });
+    });
+    describe('success', () => {
+        it('should output success message with green checkmark', () => {
+            output.success('Operation completed');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.green('✓'), 'Operation completed');
+        });
+        it('should handle additional arguments', () => {
+            output.success('Deployed', 'v1.0.0', { status: 'ok' });
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.green('✓'), 'Deployed', 'v1.0.0', { status: 'ok' });
+        });
+    });
+    describe('info', () => {
+        it('should output info message in gray', () => {
+            output.info('Processing request...');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.gray('Processing request...'));
+        });
+        it('should handle additional arguments', () => {
+            output.info('Status:', 'running', 42);
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.gray('Status:'), 'running', 42);
+        });
+    });
+    describe('warning', () => {
+        it('should output warning message with yellow exclamation and prefix', () => {
+            output.warning('Resource limit approaching');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.yellow.bold('!'), chalk.yellow('warning:'), 'Resource limit approaching');
+        });
+        it('should handle additional arguments', () => {
+            const details = { cpu: '85%', memory: '92%' };
+            output.warning('High resource usage', details);
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.yellow.bold('!'), chalk.yellow('warning:'), 'High resource usage', details);
+        });
+    });
+    describe('statusCheck', () => {
+        it('should display found status with value and details', () => {
+            output.statusCheck('found', 'platform', 'python3', 'v3.10');
+            expect(consoleLogSpy).toHaveBeenCalledWith(`  ${chalk.green('✓')} ${chalk.green('platform')} ${chalk.bold.white('python3')}${chalk.gray(' v3.10')}`);
+        });
+        it('should display found status with value only', () => {
+            output.statusCheck('found', 'fastmcp', 'v0.1.0');
+            expect(consoleLogSpy).toHaveBeenCalledWith(`  ${chalk.green('✓')} ${chalk.green('fastmcp')} ${chalk.bold.white('v0.1.0')}`);
+        });
+        it('should display found status with label only', () => {
+            output.statusCheck('found', '3 tools');
+            expect(consoleLogSpy).toHaveBeenCalledWith(`  ${chalk.green('✓')} ${chalk.green('3 tools')}`);
+        });
+        it('should display missing status with details', () => {
+            output.statusCheck('missing', 'fastmcp', undefined, 'not in dependencies');
+            expect(consoleLogSpy).toHaveBeenCalledWith(`  ${chalk.yellow('?')} ${chalk.yellow('fastmcp')}${chalk.gray(' not in dependencies')}`);
+        });
+        it('should display warning status', () => {
+            output.statusCheck('warning', 'version', '0.0.1', 'pre-release');
+            expect(consoleLogSpy).toHaveBeenCalledWith(`  ${chalk.yellow('!')} ${chalk.yellow('version')} ${chalk.bold.white('0.0.1')}${chalk.gray(' pre-release')}`);
+        });
+        it('should display error status', () => {
+            output.statusCheck('error', 'tools', undefined, 'discovery failed');
+            expect(consoleLogSpy).toHaveBeenCalledWith(`  ${chalk.red('✗')} ${chalk.red('tools')}${chalk.gray(' discovery failed')}`);
+        });
+    });
+    describe('section', () => {
+        it('should display section header with colon', () => {
+            output.section('dev-tests');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.cyan.bold('dev-tests:'));
+        });
+        it('should display section header with custom text', () => {
+            output.section('ark services');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.cyan.bold('ark services:'));
+        });
+    });
+    describe('statusMessage', () => {
+        it('should output success status with title and message', () => {
+            output.statusMessage('success', 'fastmcp', 'installed (v0.1.0)');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.green('✓'), chalk.green('fastmcp:'), 'installed (v0.1.0)');
+        });
+        it('should output warning status with title and message', () => {
+            output.statusMessage('warning', 'virtual environment', 'not found');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.yellow.bold('!'), chalk.yellow('virtual environment:'), 'not found');
+        });
+        it('should output error status with title and message', () => {
+            output.statusMessage('error', 'fastmcp', 'not found in dependencies');
+            expect(consoleErrorSpy).toHaveBeenCalledWith(chalk.red('✗'), chalk.red('fastmcp:'), 'not found in dependencies');
+        });
+        it('should output info status with title and message', () => {
+            output.statusMessage('info', 'platform', 'python3');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.blue('ℹ'), chalk.blue('platform:'), 'python3');
+        });
+        it('should handle title-only messages', () => {
+            output.statusMessage('success', 'Operation completed');
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.green('✓'), 'Operation completed');
+        });
+        it('should handle additional arguments', () => {
+            const extra = { version: '1.0' };
+            output.statusMessage('info', 'status', 'running', extra, 42);
+            expect(consoleLogSpy).toHaveBeenCalledWith(chalk.blue('ℹ'), chalk.blue('status:'), 'running', extra, 42);
+        });
+    });
+});

package/dist/lib/portUtils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Check if a port is available
+ */
+export declare function isPortAvailable(port: number): Promise<boolean>;
+/**
+ * Find an available port, starting from the preferred port
+ */
+export declare function findAvailablePort(preferredPort: number, maxAttempts?: number): Promise<number>;