@agents-at-scale/ark 0.1.35 → 0.1.36-rc1

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.d.ts

@@ -0,0 +1,36 @@
+export type StatusType = 'success' | 'warning' | 'info' | 'error';
+declare const output: {
+    /**
+     * Display a status message with flexible formatting
+     */
+    statusMessage(type: StatusType, title: string, message?: string, ...args: unknown[]): void;
+    /**
+     * Display an error message with consistent formatting
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Display a success message with consistent formatting
+     */
+    success(message: string, ...args: unknown[]): void;
+    /**
+     * Display an info message (indented gray text)
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Display a warning message with consistent formatting
+     */
+    warning(message: string, ...args: unknown[]): void;
+    /**
+     * Display a status check item (like ark status format)
+     * @param status - 'found', 'missing', 'warning', 'error'
+     * @param label - The label to show (e.g., 'platform')
+     * @param value - The value in bright white (e.g., 'python3')
+     * @param details - Optional grey details
+     */
+    statusCheck(status: "found" | "missing" | "warning" | "error", label: string, value?: string, details?: string): void;
+    /**
+     * Display a section header (like 'ark services:')
+     */
+    section(title: string): void;
+};
+export default output;

package/dist/lib/output.js

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+const output = {
+    /**
+     * Display a status message with flexible formatting
+     */
+    statusMessage(type, title, message, ...args) {
+        const icons = {
+            success: chalk.green('✓'),
+            warning: chalk.yellow.bold('!'),
+            info: chalk.blue('ℹ'),
+            error: chalk.red('✗'),
+        };
+        const colors = {
+            success: chalk.green,
+            warning: chalk.yellow,
+            info: chalk.blue,
+            error: chalk.red,
+        };
+        const icon = icons[type];
+        const color = colors[type];
+        const logFn = type === 'error' ? console.error : console.log;
+        if (message) {
+            logFn(icon, color(`${title}:`), message, ...args);
+        }
+        else {
+            logFn(icon, title, ...args);
+        }
+    },
+    /**
+     * Display an error message with consistent formatting
+     */
+    error(message, ...args) {
+        this.statusMessage('error', 'error', message, ...args);
+    },
+    /**
+     * Display a success message with consistent formatting
+     */
+    success(message, ...args) {
+        this.statusMessage('success', message, undefined, ...args);
+    },
+    /**
+     * Display an info message (indented gray text)
+     */
+    info(message, ...args) {
+        console.log(chalk.gray(message), ...args);
+    },
+    /**
+     * Display a warning message with consistent formatting
+     */
+    warning(message, ...args) {
+        this.statusMessage('warning', 'warning', message, ...args);
+    },
+    /**
+     * Display a status check item (like ark status format)
+     * @param status - 'found', 'missing', 'warning', 'error'
+     * @param label - The label to show (e.g., 'platform')
+     * @param value - The value in bright white (e.g., 'python3')
+     * @param details - Optional grey details
+     */
+    statusCheck(status, label, value, details) {
+        const icons = {
+            found: chalk.green('✓'),
+            missing: chalk.yellow('?'),
+            warning: chalk.yellow('!'),
+            error: chalk.red('✗'),
+        };
+        const statusText = {
+            found: chalk.green(label),
+            missing: chalk.yellow(label),
+            warning: chalk.yellow(label),
+            error: chalk.red(label),
+        };
+        let output = `  ${icons[status]} ${statusText[status]}`;
+        if (value) {
+            output += ` ${chalk.bold.white(value)}`;
+        }
+        if (details) {
+            output += chalk.gray(` ${details}`);
+        }
+        console.log(output);
+    },
+    /**
+     * Display a section header (like 'ark services:')
+     */
+    section(title) {
+        console.log(chalk.cyan.bold(`${title}:`));
+    },
+};
+export default output;

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>;

package/dist/lib/portUtils.js

@@ -0,0 +1,39 @@
+import net from 'net';
+/**
+ * Check if a port is available
+ */
+export async function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                resolve(false);
+            }
+            else {
+                resolve(false);
+            }
+        });
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+/**
+ * Find an available port, starting from the preferred port
+ */
+export async function findAvailablePort(preferredPort, maxAttempts = 10) {
+    // First try the preferred port
+    if (await isPortAvailable(preferredPort)) {
+        return preferredPort;
+    }
+    // Try random ports
+    for (let i = 0; i < maxAttempts; i++) {
+        const randomPort = Math.floor(Math.random() * (65535 - 1024) + 1024);
+        if (await isPortAvailable(randomPort)) {
+            return randomPort;
+        }
+    }
+    throw new Error(`Could not find an available port after ${maxAttempts} attempts`);
+}

package/dist/lib/queryRunner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared query execution logic for both universal and resource-specific query commands
+ */
+export interface QueryOptions {
+    targetType: string;
+    targetName: string;
+    message: string;
+    verbose?: boolean;
+}
+/**
+ * Execute a query against any ARK target (model, agent, team)
+ * This is the shared implementation used by all query commands
+ */
+export declare function executeQuery(options: QueryOptions): Promise<void>;
+/**
+ * Parse a target string like "model/default" or "agent/weather"
+ * Returns { targetType, targetName } or null if invalid
+ */
+export declare function parseTarget(target: string): {
+    targetType: string;
+    targetName: string;
+} | null;

package/dist/lib/queryRunner.js

@@ -0,0 +1,142 @@
+/**
+ * Shared query execution logic for both universal and resource-specific query commands
+ */
+import { execa } from 'execa';
+import ora from 'ora';
+import output from './output.js';
+/**
+ * Execute a query against any ARK target (model, agent, team)
+ * This is the shared implementation used by all query commands
+ */
+export async function executeQuery(options) {
+    const spinner = ora('Creating query...').start();
+    // Generate a unique query name
+    const timestamp = Date.now();
+    const queryName = `cli-query-${timestamp}`;
+    // Create the Query resource
+    const queryManifest = {
+        apiVersion: 'ark.mckinsey.com/v1alpha1',
+        kind: 'Query',
+        metadata: {
+            name: queryName,
+        },
+        spec: {
+            input: options.message,
+            targets: [
+                {
+                    type: options.targetType,
+                    name: options.targetName,
+                },
+            ],
+        },
+    };
+    try {
+        // Apply the query
+        spinner.text = 'Submitting query...';
+        await execa('kubectl', ['apply', '-f', '-'], {
+            input: JSON.stringify(queryManifest),
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // Watch for query completion
+        spinner.text = 'Query status: initializing';
+        let queryComplete = false;
+        let attempts = 0;
+        const maxAttempts = 300; // 5 minutes with 1 second intervals
+        while (!queryComplete && attempts < maxAttempts) {
+            attempts++;
+            try {
+                const { stdout } = await execa('kubectl', [
+                    'get',
+                    'query',
+                    queryName,
+                    '-o',
+                    'json',
+                ], { stdio: 'pipe' });
+                const query = JSON.parse(stdout);
+                const phase = query.status?.phase;
+                // Update spinner with current phase
+                if (phase) {
+                    spinner.text = `Query status: ${phase}`;
+                }
+                // Check if query is complete based on phase
+                if (phase === 'done') {
+                    queryComplete = true;
+                    spinner.succeed('Query completed');
+                    // Extract and display the response from responses array
+                    if (query.status?.responses && query.status.responses.length > 0) {
+                        const response = query.status.responses[0];
+                        console.log('\n' + (response.content || response));
+                    }
+                    else {
+                        output.warning('No response received');
+                    }
+                }
+                else if (phase === 'error') {
+                    queryComplete = true;
+                    spinner.fail('Query failed');
+                    // Try to get error message from conditions or status
+                    const errorCondition = query.status?.conditions?.find((c) => {
+                        const condition = c;
+                        return condition.type === 'Complete' && condition.status === 'False';
+                    });
+                    if (errorCondition?.message) {
+                        output.error(errorCondition.message);
+                    }
+                    else if (query.status?.error) {
+                        output.error(query.status.error);
+                    }
+                    else {
+                        output.error('Query failed with unknown error');
+                    }
+                }
+                else if (phase === 'canceled') {
+                    queryComplete = true;
+                    spinner.warn('Query canceled');
+                    // Try to get cancellation reason if available
+                    if (query.status?.message) {
+                        output.warning(query.status.message);
+                    }
+                }
+            }
+            catch {
+                // Query might not exist yet, continue waiting
+                spinner.text = 'Query status: waiting for query to be created';
+            }
+            if (!queryComplete) {
+                await new Promise(resolve => setTimeout(resolve, 1000)); // Wait 1 second
+            }
+        }
+        if (!queryComplete) {
+            spinner.fail('Query timed out');
+            output.error('Query did not complete within 5 minutes');
+        }
+    }
+    catch (error) {
+        spinner.fail('Query failed');
+        output.error(error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
+    finally {
+        // Clean up the query resource
+        try {
+            await execa('kubectl', ['delete', 'query', queryName], { stdio: 'pipe' });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+}
+/**
+ * Parse a target string like "model/default" or "agent/weather"
+ * Returns { targetType, targetName } or null if invalid
+ */
+export function parseTarget(target) {
+    const parts = target.split('/');
+    if (parts.length !== 2) {
+        return null;
+    }
+    return {
+        targetType: parts[0],
+        targetName: parts[1],
+    };
+}

package/dist/lib/startup.d.ts

@@ -0,0 +1,9 @@
+import type { ArkConfig } from './config.js';
+/**
+ * Show error message when no cluster is detected
+ */
+export declare function showNoClusterError(): void;
+/**
+ * Initialize the CLI with minimal checks for fast startup
+ */
+export declare function startup(): Promise<ArkConfig>;

package/dist/lib/startup.js

@@ -0,0 +1,87 @@
+import chalk from 'chalk';
+import { execa } from 'execa';
+import { checkCommandExists } from './commands.js';
+import { loadConfig } from './config.js';
+const REQUIRED_COMMANDS = [
+    {
+        name: 'kubectl',
+        command: 'kubectl',
+        args: ['version', '--client'],
+        installUrl: 'https://kubernetes.io/docs/tasks/tools/',
+    },
+    {
+        name: 'helm',
+        command: 'helm',
+        args: ['version', '--short'],
+        installUrl: 'https://helm.sh/docs/intro/install/',
+    },
+];
+async function checkRequirements() {
+    const missing = [];
+    for (const cmd of REQUIRED_COMMANDS) {
+        const exists = await checkCommandExists(cmd.command, cmd.args);
+        if (!exists) {
+            missing.push(cmd);
+        }
+    }
+    if (missing.length > 0) {
+        for (const cmd of missing) {
+            console.error(chalk.red('error:') + ` ${cmd.name} is required`);
+            console.error('  ' + chalk.blue(cmd.installUrl));
+        }
+        process.exit(1);
+    }
+}
+/**
+ * Show error message when no cluster is detected
+ */
+export function showNoClusterError() {
+    console.log(chalk.red.bold('\n✗ No Kubernetes cluster detected\n'));
+    console.log('Please ensure you have configured a connection to a Kubernetes cluster.');
+    console.log('For local development, you can use:');
+    console.log(`  • Minikube: ${chalk.blue('https://minikube.sigs.k8s.io/docs/start')}`);
+    console.log(`  • Docker Desktop: ${chalk.blue('https://docs.docker.com/desktop/kubernetes/')}`);
+    console.log(`  • Kind: ${chalk.blue('https://kind.sigs.k8s.io/docs/user/quick-start/')}`);
+    console.log('');
+    console.log('And more. For help, check the Quickstart guide:');
+    console.log(chalk.blue('  https://mckinsey.github.io/agents-at-scale-ark/quickstart/'));
+}
+/**
+ * Check if a Kubernetes context is configured
+ * This is a fast local check that doesn't hit the cluster
+ */
+async function hasKubernetesContext() {
+    try {
+        const { stdout } = await execa('kubectl', ['config', 'current-context']);
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Initialize the CLI with minimal checks for fast startup
+ */
+export async function startup() {
+    // Check required commands (kubectl, helm) - fast local checks
+    await checkRequirements();
+    // Load config from disk (fast - just file I/O)
+    const config = loadConfig();
+    // Check if we have a kubernetes context configured (fast local check)
+    // We don't check cluster connectivity here - that's expensive
+    const hasContext = await hasKubernetesContext();
+    if (hasContext) {
+        try {
+            const { stdout } = await execa('kubectl', ['config', 'current-context']);
+            config.clusterInfo = {
+                type: 'unknown', // We don't detect cluster type here - too slow
+                context: stdout.trim(),
+                // We don't fetch namespace or cluster details here - too slow
+            };
+        }
+        catch {
+            // Ignore - no context
+        }
+    }
+    return config;
+}

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

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