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

package/README.md

@@ -1,95 +1,78 @@
-# ARK CLI
+<div align="center">
+  <h1 align="center"><code>ark</code></h1>
+  <h4 align="center">Ark Command Line Interface</h4>
 
-Interactive terminal interface for ARK agents.
+  <hr>
 
-## Prerequisites
+  <p align="center">
+    <a href="#quickstart">Quickstart</a> •
+    <a href="https://mckinsey.github.io/agents-at-scale-ark/">Documentation</a>
+  </p>
+  <p align="center">
+    <a href="https://github.com/mckinsey/agents-at-scale-ark/actions/workflows/cicd.yaml"><img src="https://github.com/mckinsey/agents-at-scale-ark/actions/workflows/cicd.yaml/badge.svg" alt="CI/CD"></a>
+    <a href="https://www.npmjs.com/package/@agents-at-scale/ark"><img src="https://img.shields.io/npm/v/@agents-at-scale/ark.svg" alt="npm version"></a>
+  </p>
+</div>
 
-1. **ARK system deployed** in your Kubernetes cluster
-2. **Gateway setup** for service discovery:
-   ```bash
-   # From agents-at-scale project root
-   make localhost-gateway-install
-   ```
+## Quickstart
 
-## Installation
+Ensure you have [Node.js](https://nodejs.org/en/download) and [Helm](https://helm.sh/docs/intro/install/) installed. Then run the following commands to install Ark:
 
 ```bash
-cd tools/ark-cli
-npm run build
-npm install -g .
-```
-
-## Usage
-
-```bash
-# Interactive mode (no arguments)
-ark
+# Install the 'ark' CLI:
+npm install -g @agents-at-scale/ark
 
-# Show help
-ark --help
-ark cluster --help
+# Install Ark:
+ark install
 
-# Check system status
-ark check status
+# Optionally configure a 'default' model to use for agents:
+ark models create default
 
-# Generate (project, agent, team, etc)
-ark generate
+# Run the dashboard:
+ark dashboard
+```
 
-# Cluster operations
-ark cluster get-type
-ark cluster get-ip
-ark cluster get-ip --verbose
-ark cluster get-ip --context minikube
+In most cases the default installation options will be sufficient. This will install the Ark dependencies, the controller, the APIs and the dashboard. You can optionally setup a `default` model that will be the default used by agents. You will need a Kubernetes cluster to install Ark into, you can use [Minikube](https://minikube.sigs.k8s.io/docs/start), [Kind](https://kind.sigs.k8s.io/docs/user/quick-start/), [Docker Desktop](https://docs.docker.com/desktop/kubernetes/) or similar to run a local cluster. The `install` command will warn if any required dependencies are missing.
 
-# Show shell autocomplete options.
-ark autocomplete
-```
+User guides, developer guides, operations guides and API reference documentation is all available at:
 
-## Configuration
+https://mckinsey.github.io/agents-at-scale-ark/
 
-ARK CLI automatically detects services via:
+The [Quickstart](https://mckinsey.github.io/agents-at-scale-ark/quickstart/) guide will walk you through the process of configuring a model, creating an agent and running basic queries.
 
-1. **localhost-gateway** (when running) - `*.127.0.0.1.nip.io:8080`
-2. **Kubernetes service discovery** - for internal services
-3. **Default localhost URLs** - fallback
+To troubleshoot an installation, run `ark status`.
 
-Settings stored in `~/.config/ark-cli/config.json`
+## Configuration
 
-## Development
+You can customize Ark service installations using a `.arkrc.yaml` file in your home directory (`~/.arkrc.yaml`) or project directory. This allows you to override service properties like enabled status, namespace, or chart location.
 
-**Note:** All make commands must be run from the repository root directory.
+Example `.arkrc.yaml`:
 
-```bash
-# From repository root
-make ark-cli-install         # Build and install globally
-make ark-cli-build           # Build only
-make clean                   # Clean build artifacts and stamp files
-make ark-cli-uninstall       # Remove global installation
-
-# From tools/ark-cli directory
-npm run lint         # Run linting and formatting
-npm run lint:check   # Check linting without fixing
+```yaml
+services:
+  localhost-gateway:
+    enabled: true
+  ark-controller:
+    namespace: custom-namespace
 ```
 
-## Troubleshooting
+This example enables the `localhost-gateway` service (disabled by default) and changes the namespace for `ark-controller`.
 
-Enable debug logging to see detailed configuration discovery and service resolution:
+### Installing Agents @ Scale
 
-```bash
-# Debug configuration discovery and service resolution
-DEBUG=ark:config ark check status
+To install the Agents @ Scale platform with JFrog container registry credentials:
 
-# Debug all ARK CLI components
-DEBUG=ark:* ark check status
-
-# Keep debug enabled for multiple commands
-export DEBUG=ark:config
-ark check status
-ark dashboard
+```yaml
+services:
+  agents-at-scale:
+    enabled: true
+    installArgs:
+      - --set
+      - containerRegistry.enabled=true
+      - --set
+      - containerRegistry.username=YOUR_USERNAME
+      - --set
+      - containerRegistry.password=YOUR_PASSWORD
 ```
 
-**Common debug scenarios:**
-
-- **Wrong URL detected**: See which discovery method is being used
-- **Service timeouts**: Check localhost-gateway and kubernetes connectivity
-- **Config issues**: Trace fallback logic through multiple discovery methods
+Replace `YOUR_USERNAME` and `YOUR_PASSWORD` with your JFrog credentials.

package/dist/arkServices.d.ts

@@ -1,39 +1,15 @@
 /**
  * Centralized ARK service definitions used by both install and status commands
  */
-export interface ArkService {
-    name: string;
-    helmReleaseName: string;
-    description: string;
-    enabled: boolean;
-    namespace?: string;
-    chartPath?: string;
-    installArgs?: string[];
-    k8sServiceName?: string;
-    k8sServicePort?: number;
-    k8sPortForwardLocalPort?: number;
-    k8sDeploymentName?: string;
-    k8sDevDeploymentName?: string;
-}
-export interface ServiceCollection {
-    [key: string]: ArkService;
-}
-export interface ArkDependency {
-    name: string;
-    command: string;
-    args: string[];
-    description: string;
-}
-export interface DependencyCollection {
-    [key: string]: ArkDependency;
-}
+import type { ArkService, ServiceCollection, ArkDependency, DependencyCollection } from './types/arkService.js';
+export type { ArkService, ServiceCollection, ArkDependency, DependencyCollection, };
 /**
  * Dependencies that should be installed before ARK services
  * Note: Dependencies will be installed in the order they are defined here
  */
 export declare const arkDependencies: DependencyCollection;
 /**
- * Core ARK services with their installation and status check configurations
+ * Core ARK services - initialized with defaults and config overrides applied
  */
 export declare const arkServices: ServiceCollection;
 /**

package/dist/arkServices.js

@@ -1,6 +1,7 @@
 /**
  * Centralized ARK service definitions used by both install and status commands
  */
+import { loadConfig } from './lib/config.js';
 const REGISTRY_BASE = 'oci://ghcr.io/mckinsey/agents-at-scale-ark/charts';
 /**
  * Dependencies that should be installed before ARK services
@@ -53,14 +54,15 @@ export const arkDependencies = {
     },
 };
 /**
- * Core ARK services with their installation and status check configurations
+ * Default ARK services with their installation and status check configurations
  */
-export const arkServices = {
+const defaultArkServices = {
     'ark-controller': {
         name: 'ark-controller',
         helmReleaseName: 'ark-controller',
         description: 'Core Ark controller for managing AI resources',
         enabled: true,
+        category: 'core',
         namespace: 'ark-system',
         chartPath: `${REGISTRY_BASE}/ark-controller`,
         installArgs: ['--create-namespace', '--set', 'rbac.enable=true'],
@@ -72,7 +74,7 @@ export const arkServices = {
         helmReleaseName: 'ark-api',
         description: 'API layer for interacting with Ark resources',
         enabled: true,
-        // namespace: undefined - uses current context namespace
+        category: 'service',
         chartPath: `${REGISTRY_BASE}/ark-api`,
         installArgs: [],
         k8sServiceName: 'ark-api',
@@ -86,6 +88,7 @@ export const arkServices = {
         helmReleaseName: 'ark-dashboard',
         description: 'Ark Dashboard',
         enabled: true,
+        category: 'service',
         // namespace: undefined - uses current context namespace
         chartPath: `${REGISTRY_BASE}/ark-dashboard`,
         installArgs: [],
@@ -100,6 +103,7 @@ export const arkServices = {
         helmReleaseName: 'ark-api-a2a',
         description: 'Ark API agent-to-agent communication service',
         enabled: false, // Disabled - not currently used
+        category: 'service',
         // namespace: undefined - uses current context namespace
         // Note: This service might be installed as part of ark-api or separately
     },
@@ -108,22 +112,46 @@ export const arkServices = {
         helmReleaseName: 'ark-mcp',
         description: 'Ark Model Context Protocol server',
         enabled: true,
+        category: 'service',
         // namespace: undefined - uses current context namespace
         chartPath: `${REGISTRY_BASE}/ark-mcp`,
         installArgs: [],
         k8sDeploymentName: 'ark-mcp',
         k8sDevDeploymentName: 'ark-mcp-devspace',
     },
+    'agents-at-scale': {
+        name: 'agents-at-scale',
+        helmReleaseName: 'agents-at-scale',
+        description: 'Agents @ Scale Platform',
+        enabled: false,
+        category: 'service',
+        chartPath: 'oci://ghcr.io/mck-private/qb-fm-labs-legacyx/charts/legacyx',
+        installArgs: [],
+    },
     'localhost-gateway': {
         name: 'localhost-gateway',
         helmReleaseName: 'localhost-gateway',
         description: 'Gateway for local development clusters',
         enabled: false, // Disabled - not needed for most users
+        category: 'service',
         namespace: 'ark-system',
         chartPath: `${REGISTRY_BASE}/localhost-gateway`,
         installArgs: [],
     },
 };
+function applyConfigOverrides(defaults) {
+    const config = loadConfig();
+    const overrides = config?.services || {};
+    const result = {};
+    for (const [key, service] of Object.entries(defaults)) {
+        result[key] = overrides[key] ? { ...service, ...overrides[key] } : service;
+    }
+    return result;
+}
+/**
+ * Core ARK services - initialized with defaults and config overrides applied
+ */
+export const arkServices = applyConfigOverrides(defaultArkServices);
 /**
  * Get services that can be installed via Helm charts (only enabled services)
  */

package/dist/arkServices.spec.js

@@ -1,24 +1,132 @@
-import { arkDependencies, arkServices, getInstallableServices, } from './arkServices.js';
+import { jest } from '@jest/globals';
+const mockLoadConfig = jest.fn();
+jest.unstable_mockModule('./lib/config.js', () => ({
+    loadConfig: mockLoadConfig,
+}));
+const { arkDependencies, arkServices: originalArkServices, getInstallableServices, } = await import('./arkServices.js');
 describe('arkServices', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
     it('exports arkDependencies with expected structure', () => {
         expect(arkDependencies).toBeDefined();
         expect(arkDependencies['cert-manager']).toBeDefined();
         expect(arkDependencies['cert-manager'].command).toBe('helm');
     });
     it('exports arkServices with expected structure', () => {
-        expect(arkServices).toBeDefined();
-        expect(arkServices['ark-controller']).toBeDefined();
-        expect(arkServices['ark-controller'].namespace).toBe('ark-system');
-        // User services should have undefined namespace (use current context)
-        expect(arkServices['ark-api'].namespace).toBeUndefined();
-        expect(arkServices['ark-dashboard'].namespace).toBeUndefined();
-        // System services should have explicit namespace
-        expect(arkServices['localhost-gateway'].namespace).toBe('ark-system');
+        expect(originalArkServices).toBeDefined();
+        expect(originalArkServices['ark-controller']).toBeDefined();
+        expect(originalArkServices['ark-controller'].namespace).toBe('ark-system');
+        expect(originalArkServices['ark-api'].namespace).toBeUndefined();
+        expect(originalArkServices['ark-dashboard'].namespace).toBeUndefined();
+        expect(originalArkServices['localhost-gateway'].namespace).toBe('ark-system');
     });
     it('getInstallableServices returns services with chartPath', () => {
         const installable = getInstallableServices();
         expect(installable['ark-controller']).toBeDefined();
         expect(installable['ark-api']).toBeDefined();
-        expect(installable['ark-api-a2a']).toBeUndefined(); // no chartPath
+        expect(installable['ark-api-a2a']).toBeUndefined();
+    });
+    describe('applyConfigOverrides', () => {
+        it('applies no overrides when config has no services section', async () => {
+            mockLoadConfig.mockReturnValue({});
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-controller'].enabled).toBe(true);
+            expect(arkServices['ark-api'].enabled).toBe(true);
+        });
+        it('applies overrides to enable a disabled service', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'localhost-gateway': { enabled: true },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['localhost-gateway'].enabled).toBe(true);
+        });
+        it('applies overrides to disable an enabled service', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'ark-controller': { enabled: false },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-controller'].enabled).toBe(false);
+        });
+        it('applies overrides to multiple services', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'ark-controller': { enabled: false },
+                    'ark-api': { enabled: false },
+                    'localhost-gateway': { enabled: true },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-controller'].enabled).toBe(false);
+            expect(arkServices['ark-api'].enabled).toBe(false);
+            expect(arkServices['localhost-gateway'].enabled).toBe(true);
+        });
+        it('applies overrides to namespace', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'ark-api': { namespace: 'custom-namespace' },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-api'].namespace).toBe('custom-namespace');
+        });
+        it('applies overrides to chartPath', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'ark-controller': {
+                        chartPath: 'oci://custom-registry/charts/ark-controller',
+                    },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-controller'].chartPath).toBe('oci://custom-registry/charts/ark-controller');
+        });
+        it('applies partial overrides without affecting other properties', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'ark-controller': { enabled: false },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-controller'].enabled).toBe(false);
+            expect(arkServices['ark-controller'].namespace).toBe('ark-system');
+            expect(arkServices['ark-controller'].category).toBe('core');
+            expect(arkServices['ark-controller'].description).toBe('Core Ark controller for managing AI resources');
+        });
+        it('applies overrides to installArgs', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'ark-controller': { installArgs: ['--set', 'custom.value=true'] },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-controller'].installArgs).toEqual([
+                '--set',
+                'custom.value=true',
+            ]);
+        });
+        it('does not affect services without overrides', async () => {
+            mockLoadConfig.mockReturnValue({
+                services: {
+                    'ark-controller': { enabled: false },
+                },
+            });
+            jest.resetModules();
+            const { arkServices } = await import('./arkServices.js');
+            expect(arkServices['ark-api'].enabled).toBe(true);
+            expect(arkServices['ark-dashboard'].enabled).toBe(true);
+        });
     });
 });

package/dist/commands/completion/index.js

@@ -114,7 +114,6 @@ complete -F _ark_completion ark
         .description('Generate zsh completion script')
         .action(() => {
         // Shell script requires escaped $ characters
-        /* eslint-disable no-useless-escape */
         console.log(`
 #compdef ark
 
@@ -224,7 +223,6 @@ _ark() {
 
 _ark
       `.trim());
-        /* eslint-enable no-useless-escape */
     });
     return completion;
 }

package/dist/commands/install/index.js

@@ -4,10 +4,11 @@ import { execute } from '../../lib/commands.js';
 import inquirer from 'inquirer';
 import { showNoClusterError } from '../../lib/startup.js';
 import output from '../../lib/output.js';
-import { getInstallableServices, arkDependencies, } from '../../arkServices.js';
-import { isArkReady } from '../../lib/arkStatus.js';
+import { getInstallableServices, arkDependencies, arkServices, } from '../../arkServices.js';
 import { printNextSteps } from '../../lib/nextSteps.js';
 import ora from 'ora';
+import { waitForServicesReady, } from '../../lib/waitForReady.js';
+import { parseTimeoutToSeconds } from '../../lib/timeout.js';
 async function installService(service, verbose = false) {
     const helmArgs = [
         'upgrade',
@@ -67,6 +68,12 @@ export async function installArk(config, serviceName, options = {}) {
         console.log(chalk.cyan.bold('\nSelect components to install:'));
         console.log(chalk.gray('Use arrow keys to navigate, space to toggle, enter to confirm\n'));
         // Build choices for the checkbox prompt
+        const coreServices = Object.values(arkServices)
+            .filter((s) => s.category === 'core')
+            .sort((a, b) => a.name.localeCompare(b.name));
+        const otherServices = Object.values(arkServices)
+            .filter((s) => s.category === 'service')
+            .sort((a, b) => a.name.localeCompare(b.name));
         const allChoices = [
             new inquirer.Separator(chalk.bold('──── Dependencies ────')),
             {
@@ -80,32 +87,17 @@ export async function installArk(config, serviceName, options = {}) {
                 checked: true,
             },
             new inquirer.Separator(chalk.bold('──── Ark Core ────')),
-            {
-                name: `ark-controller ${chalk.gray('- Core Ark controller')}`,
-                value: 'ark-controller',
-                checked: true,
-            },
+            ...coreServices.map((service) => ({
+                name: `${service.name} ${chalk.gray(`- ${service.description}`)}`,
+                value: service.helmReleaseName,
+                checked: Boolean(service.enabled),
+            })),
             new inquirer.Separator(chalk.bold('──── Ark Services ────')),
-            {
-                name: `ark-api ${chalk.gray('- API service')}`,
-                value: 'ark-api',
-                checked: true,
-            },
-            {
-                name: `ark-dashboard ${chalk.gray('- Web dashboard')}`,
-                value: 'ark-dashboard',
-                checked: true,
-            },
-            {
-                name: `ark-mcp ${chalk.gray('- MCP services')}`,
-                value: 'ark-mcp',
-                checked: true,
-            },
-            {
-                name: `localhost-gateway ${chalk.gray('- Gateway for local access')}`,
-                value: 'localhost-gateway',
-                checked: true,
-            },
+            ...otherServices.map((service) => ({
+                name: `${service.name} ${chalk.gray(`- ${service.description}`)}`,
+                value: service.helmReleaseName,
+                checked: Boolean(service.enabled),
+            })),
         ];
         let selectedComponents = [];
         try {
@@ -190,11 +182,9 @@ export async function installArk(config, serviceName, options = {}) {
             }
         }
         // Install selected services
-        const services = getInstallableServices();
-        for (const service of Object.values(services)) {
-            // Check if this service was selected
-            const serviceKey = service.helmReleaseName;
-            if (!selectedComponents.includes(serviceKey)) {
+        for (const serviceName of selectedComponents) {
+            const service = Object.values(arkServices).find((s) => s.helmReleaseName === serviceName);
+            if (!service || !service.chartPath) {
                 continue;
             }
             output.info(`installing ${service.name}...`);
@@ -203,8 +193,8 @@ export async function installArk(config, serviceName, options = {}) {
                 console.log(); // Add blank line after command output
             }
             catch {
-                // Continue with remaining services on error
                 console.log(); // Add blank line after error output
+                process.exit(1);
             }
         }
     }
@@ -234,8 +224,8 @@ export async function installArk(config, serviceName, options = {}) {
                 console.log(); // Add blank line after command output
             }
             catch {
-                // Continue with remaining services on error
                 console.log(); // Add blank line after error output
+                process.exit(1);
             }
         }
     }
@@ -245,34 +235,35 @@ export async function installArk(config, serviceName, options = {}) {
     }
     // Wait for Ark to be ready if requested
     if (options.waitForReady) {
-        // Parse timeout value (e.g., '30s', '2m', '60')
-        const parseTimeout = (value) => {
-            const match = value.match(/^(\d+)([sm])?$/);
-            if (!match) {
-                throw new Error('Invalid timeout format. Use format like 30s or 2m');
-            }
-            const num = parseInt(match[1], 10);
-            const unit = match[2] || 's';
-            return unit === 'm' ? num * 60 : num;
-        };
         try {
-            const timeoutSeconds = parseTimeout(options.waitForReady);
-            const startTime = Date.now();
-            const endTime = startTime + timeoutSeconds * 1000;
+            const timeoutSeconds = parseTimeoutToSeconds(options.waitForReady);
+            const servicesToWait = Object.values(arkServices).filter((s) => s.enabled &&
+                s.category === 'core' &&
+                s.k8sDeploymentName &&
+                s.namespace);
             const spinner = ora(`Waiting for Ark to be ready (timeout: ${timeoutSeconds}s)...`).start();
-            while (Date.now() < endTime) {
-                if (await isArkReady()) {
-                    spinner.succeed('Ark is ready!');
-                    return;
-                }
+            const statusMap = new Map();
+            servicesToWait.forEach((s) => statusMap.set(s.name, false));
+            const startTime = Date.now();
+            const result = await waitForServicesReady(servicesToWait, timeoutSeconds, (progress) => {
+                statusMap.set(progress.serviceName, progress.ready);
                 const elapsed = Math.floor((Date.now() - startTime) / 1000);
-                spinner.text = `Waiting for Ark to be ready (${elapsed}/${timeoutSeconds}s)...`;
-                // Wait 2 seconds before checking again
-                await new Promise((resolve) => setTimeout(resolve, 2000));
+                const lines = servicesToWait.map((s) => {
+                    const ready = statusMap.get(s.name);
+                    const icon = ready ? '✓' : '⋯';
+                    const status = ready ? 'ready' : 'waiting...';
+                    const color = ready ? chalk.green : chalk.yellow;
+                    return `  ${color(icon)} ${chalk.bold(s.name)} ${chalk.blue(`(${s.namespace})`)} - ${status}`;
+                });
+                spinner.text = `Waiting for Ark to be ready (${elapsed}/${timeoutSeconds}s)...\n${lines.join('\n')}`;
+            });
+            if (result) {
+                spinner.succeed('Ark is ready');
+            }
+            else {
+                spinner.fail(`Ark did not become ready within ${timeoutSeconds} seconds`);
+                process.exit(1);
             }
-            // Timeout reached
-            spinner.fail(`Ark did not become ready within ${timeoutSeconds} seconds`);
-            process.exit(1);
         }
         catch (error) {
             output.error(`Failed to wait for ready: ${error instanceof Error ? error.message : 'Unknown error'}`);

package/dist/commands/models/create.d.ts

@@ -1 +1,9 @@
-export declare function createModel(modelName?: string): Promise<boolean>;
+export interface CreateModelOptions {
+    type?: string;
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    apiVersion?: string;
+    yes?: boolean;
+}
+export declare function createModel(modelName?: string, options?: CreateModelOptions): Promise<boolean>;