@agents-at-scale/ark 0.1.35 → 0.1.36

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/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 {};

package/dist/lib/startup.spec.js

@@ -0,0 +1,152 @@
+import { describe, it, expect, jest, beforeEach, afterEach } from '@jest/globals';
+// Mock chalk to avoid ANSI codes in tests
+jest.unstable_mockModule('chalk', () => ({
+    default: {
+        red: (str) => str,
+        yellow: (str) => str,
+        gray: (str) => str,
+        blue: (str) => str,
+    },
+}));
+// Mock commands module
+jest.unstable_mockModule('./commands.js', () => ({
+    checkCommandExists: jest.fn(),
+}));
+// Mock config module
+jest.unstable_mockModule('./config.js', () => ({
+    loadConfig: jest.fn(),
+}));
+// Mock execa module
+jest.unstable_mockModule('execa', () => ({
+    execa: jest.fn(),
+}));
+// Dynamic imports after mocks
+const { checkCommandExists } = await import('./commands.js');
+const { loadConfig } = await import('./config.js');
+const { execa } = await import('execa');
+const { startup } = await import('./startup.js');
+// Type the mocks
+const mockCheckCommandExists = checkCommandExists;
+const mockLoadConfig = loadConfig;
+const mockExeca = execa;
+describe('startup', () => {
+    let mockExit;
+    let mockConsoleError;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Mock execa to reject by default (no kubectl context)
+        mockExeca.mockRejectedValue(new Error('No context'));
+        mockExit = jest.spyOn(process, 'exit').mockImplementation(() => {
+            throw new Error('process.exit');
+        });
+        mockConsoleError = jest
+            .spyOn(console, 'error')
+            .mockImplementation(() => { });
+    });
+    afterEach(() => {
+        mockExit.mockRestore();
+        mockConsoleError.mockRestore();
+    });
+    it('returns config when all required commands are installed', async () => {
+        const expectedConfig = {
+            chat: {
+                streaming: true,
+                outputFormat: 'text',
+            },
+        };
+        // Mock all commands as available
+        mockCheckCommandExists.mockResolvedValue(true);
+        mockLoadConfig.mockReturnValue(expectedConfig);
+        const config = await startup();
+        expect(config).toEqual(expectedConfig);
+        expect(mockCheckCommandExists).toHaveBeenCalledWith('kubectl', [
+            'version',
+            '--client',
+        ]);
+        expect(mockCheckCommandExists).toHaveBeenCalledWith('helm', [
+            'version',
+            '--short',
+        ]);
+        expect(mockLoadConfig).toHaveBeenCalledTimes(1);
+        expect(mockExit).not.toHaveBeenCalled();
+    });
+    it('exits with error when kubectl is missing', async () => {
+        // Mock kubectl as missing, helm as available
+        mockCheckCommandExists
+            .mockResolvedValueOnce(false) // kubectl
+            .mockResolvedValueOnce(true); // helm
+        await expect(startup()).rejects.toThrow('process.exit');
+        expect(mockConsoleError).toHaveBeenCalledWith('error: kubectl is required');
+        expect(mockConsoleError).toHaveBeenCalledWith('  https://kubernetes.io/docs/tasks/tools/');
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+    it('exits with error when helm is missing', async () => {
+        // Mock kubectl as available, helm as missing
+        mockCheckCommandExists
+            .mockResolvedValueOnce(true) // kubectl
+            .mockResolvedValueOnce(false); // helm
+        await expect(startup()).rejects.toThrow('process.exit');
+        expect(mockConsoleError).toHaveBeenCalledWith('error: helm is required');
+        expect(mockConsoleError).toHaveBeenCalledWith('  https://helm.sh/docs/intro/install/');
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+    it('exits with error when both commands are missing', async () => {
+        // Mock both commands as missing
+        mockCheckCommandExists.mockResolvedValue(false);
+        await expect(startup()).rejects.toThrow('process.exit');
+        expect(mockConsoleError).toHaveBeenCalledWith('error: kubectl is required');
+        expect(mockConsoleError).toHaveBeenCalledWith('  https://kubernetes.io/docs/tasks/tools/');
+        expect(mockConsoleError).toHaveBeenCalledWith('error: helm is required');
+        expect(mockConsoleError).toHaveBeenCalledWith('  https://helm.sh/docs/intro/install/');
+        expect(mockExit).toHaveBeenCalledWith(1);
+    });
+    it('checks commands with correct arguments', async () => {
+        mockCheckCommandExists.mockResolvedValue(true);
+        mockLoadConfig.mockReturnValue({ chat: {} });
+        await startup();
+        expect(mockCheckCommandExists).toHaveBeenCalledTimes(2);
+        expect(mockCheckCommandExists).toHaveBeenNthCalledWith(1, 'kubectl', [
+            'version',
+            '--client',
+        ]);
+        expect(mockCheckCommandExists).toHaveBeenNthCalledWith(2, 'helm', [
+            'version',
+            '--short',
+        ]);
+    });
+    it('loads config after checking requirements', async () => {
+        mockCheckCommandExists.mockResolvedValue(true);
+        const expectedConfig = { chat: { streaming: false } };
+        mockLoadConfig.mockReturnValue(expectedConfig);
+        const config = await startup();
+        // Verify order - checkCommandExists should be called before loadConfig
+        const checkCallOrder = mockCheckCommandExists.mock.invocationCallOrder[0];
+        const loadCallOrder = mockLoadConfig.mock.invocationCallOrder[0];
+        expect(checkCallOrder).toBeLessThan(loadCallOrder);
+        expect(config).toEqual(expectedConfig);
+    });
+    it('includes cluster context when available', async () => {
+        mockCheckCommandExists.mockResolvedValue(true);
+        mockLoadConfig.mockReturnValue({ chat: { streaming: true } });
+        // Mock successful kubectl context check
+        mockExeca.mockResolvedValue({
+            stdout: 'minikube',
+            stderr: '',
+        });
+        const config = await startup();
+        expect(config.clusterInfo).toEqual({
+            type: 'unknown',
+            context: 'minikube',
+        });
+        expect(mockExeca).toHaveBeenCalledWith('kubectl', ['config', 'current-context']);
+    });
+    it('handles missing kubectl context gracefully', async () => {
+        mockCheckCommandExists.mockResolvedValue(true);
+        const expectedConfig = { chat: { streaming: false } };
+        mockLoadConfig.mockReturnValue(expectedConfig);
+        // mockExeca already mocked to reject in beforeEach
+        const config = await startup();
+        expect(config).toEqual(expectedConfig);
+        expect(config.clusterInfo).toBeUndefined();
+    });
+});

package/dist/lib/types.d.ts

@@ -13,25 +13,109 @@ export interface KubernetesConfig {
     namespace?: string;
     inCluster: boolean;
 }
-export interface ServiceStatus {
+export type DeploymentStatus = 'available' | 'progressing' | 'replicafailure' | 'failed' | 'not found' | 'unknown';
+export type ServiceStatus = {
     name: string;
-    status: 'healthy' | 'unhealthy' | 'not installed';
+    status: 'healthy' | 'warning' | 'unhealthy' | 'not installed' | 'not ready';
+    deploymentStatus?: DeploymentStatus;
     url?: string;
     version?: string;
+    revision?: string;
     details?: string;
-}
+    isDev?: boolean;
+    namespace?: string;
+};
 export interface DependencyStatus {
     name: string;
     installed: boolean;
     version?: string;
     details?: string;
 }
+export interface ModelStatus {
+    exists: boolean;
+    available?: boolean;
+    provider?: string;
+    details?: string;
+}
 export interface StatusData {
     services: ServiceStatus[];
     dependencies: DependencyStatus[];
+    arkReady?: boolean;
+    defaultModelExists?: boolean;
+    defaultModel?: ModelStatus;
 }
 export interface CommandVersionConfig {
     command: string;
     versionArgs: string;
     versionExtract: (_output: string) => string;
 }
+export interface K8sMetadata {
+    name: string;
+    namespace?: string;
+}
+export interface K8sCondition {
+    type: string;
+    status: string;
+    message?: string;
+}
+export interface K8sListResource<T> {
+    items: T[];
+}
+export interface HelmRelease {
+    name: string;
+    app_version?: string;
+    revision?: string;
+}
+export interface K8sDeployment {
+    metadata: K8sMetadata;
+    spec?: {
+        replicas?: number;
+    };
+    status?: {
+        readyReplicas?: number;
+        availableReplicas?: number;
+        conditions?: K8sCondition[];
+    };
+}
+export interface Model {
+    metadata: K8sMetadata;
+    status?: ModelStatus;
+}
+export interface Agent {
+    metadata: K8sMetadata;
+}
+export interface Team {
+    metadata: K8sMetadata;
+}
+export interface QueryTarget {
+    type: string;
+    name: string;
+}
+export interface QueryResponse {
+    content?: string;
+}
+export interface Query {
+    apiVersion: string;
+    kind: 'Query';
+    metadata: K8sMetadata;
+    spec?: {
+        input: string;
+        targets: QueryTarget[];
+    };
+    status?: {
+        phase?: 'initializing' | 'running' | 'done' | 'error' | 'canceled';
+        conditions?: K8sCondition[];
+        responses?: QueryResponse[];
+        message?: string;
+        error?: string;
+    };
+}
+export interface Tool {
+    metadata: K8sMetadata;
+}
+export interface ClusterInfo {
+    context?: string;
+    cluster?: string;
+    user?: string;
+    namespace?: string;
+}

package/dist/lib/versions.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Version information for ARK
+ */
+export interface ArkVersionInfo {
+    current?: string;
+    latest?: string;
+    updateAvailable?: boolean;
+}
+/**
+ * Fetch the latest ARK version from GitHub releases
+ * @returns Latest version string or undefined if fetch fails
+ */
+export declare function fetchLatestVersion(): Promise<string | undefined>;
+/**
+ * Get current installed ARK version from Helm
+ * @returns Current version string or undefined if not found
+ */
+export declare function fetchCurrentVersion(): Promise<string | undefined>;
+/**
+ * Fetch both current and latest versions in parallel
+ * @returns Version information
+ */
+export declare function fetchVersionInfo(): Promise<ArkVersionInfo>;