@agents-at-scale/ark 0.1.36 → 0.1.38

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/chat/index.js

@@ -13,14 +13,13 @@ export function createChatCommand(config) {
         // Direct target argument (e.g., "agent/sample-agent")
         const initialTargetId = targetArg;
         // Config is passed from main
-        // Initialize proxy first - no spinner, just let ChatUI handle loading state
         try {
             const proxy = new ArkApiProxy();
             const arkApiClient = await proxy.start();
-            // Pass the initialized client and config to ChatUI
             render(_jsx(ChatUI, { initialTargetId: initialTargetId, arkApiClient: arkApiClient, arkApiProxy: proxy, config: config }));
         }
         catch (error) {
+            // Handle proxy startup failure or other errors
             output.error(error instanceof Error ? error.message : 'ARK API connection failed');
             process.exit(1);
         }

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/generate/generators/project.js

@@ -46,7 +46,7 @@ class ProjectGenerator {
             spinner.succeed('Prerequisites validated');
             // Get project configuration
             spinner.start('Gathering project configuration');
-            const config = await this.getProjectConfig(name, destination, options);
+            const config = await this.getProjectConfig(name, destination, options, spinner);
             spinner.succeed(`Project "${config.name}" configured`);
             // Discover and configure models (only if not skipped)
             if (config.configureModels) {
@@ -104,25 +104,28 @@ class ProjectGenerator {
             console.log(chalk.cyan('💡 Tip: Install kubectl and helm later to deploy your project to a cluster'));
         }
     }
-    async getProjectConfig(name, destination, options) {
-        console.log(chalk.gray(`\n${'─'.repeat(50)}`));
-        console.log(chalk.cyan('Project Configuration'));
-        console.log(chalk.gray(`${'─'.repeat(50)}\n`));
-        // Use command line options if provided, otherwise prompt
+    async getProjectConfig(name, destination, options, spinner) {
+        // Use command line options if provided
         let projectType = options.projectType;
         let parentDir = destination;
-        let namespace = options.namespace || name;
+        let namespace = options.namespace;
         // Validate project type if provided
         if (projectType &&
             projectType !== 'empty' &&
             projectType !== 'with-samples') {
             throw new Error(`Invalid project type: ${projectType}. Must be 'empty' or 'with-samples'`);
         }
-        // Validate and normalize namespace
-        namespace = toKebabCase(namespace);
-        validateNameStrict(namespace, 'namespace');
-        // Only prompt if in interactive mode and missing required options
-        if (options.interactive || !options.projectType || !options.namespace) {
+        // Default to interactive mode unless all required options are provided
+        // or explicitly set to non-interactive
+        const shouldPrompt = options.interactive !== false &&
+            (!options.projectType || !options.namespace);
+        if (shouldPrompt) {
+            // Stop spinner before showing prompts
+            spinner.stop();
+            // Show configuration header only when prompting
+            console.log(chalk.gray(`\n${'─'.repeat(50)}`));
+            console.log(chalk.cyan('Project Configuration'));
+            console.log(chalk.gray(`${'─'.repeat(50)}\n`));
             const prompts = [];
             if (!options.projectType) {
                 prompts.push({
@@ -160,11 +163,19 @@ class ProjectGenerator {
                 parentDir = answers.parentDir || parentDir;
                 namespace = answers.namespace || namespace;
             }
+            // Restart spinner after prompts
+            spinner.start('Finalizing configuration');
         }
-        // Ensure projectType has a value
+        // Use defaults for missing options
         if (!projectType) {
-            throw new Error('Project type is required. Use --project-type <empty|with-samples> or run in interactive mode.');
+            projectType = GENERATOR_DEFAULTS.projectType; // 'with-samples'
         }
+        if (!namespace) {
+            namespace = name; // Default namespace to project name
+        }
+        // Validate and normalize namespace
+        namespace = toKebabCase(namespace);
+        validateNameStrict(namespace, 'namespace');
         const projectPath = path.join(parentDir, name);
         // Check if directory exists
         if (fs.existsSync(projectPath)) {
@@ -329,7 +340,10 @@ class ProjectGenerator {
         return descriptions[name] || `Model: ${name}`;
     }
     async configureGit(config) {
-        console.log(chalk.cyan('📋 Git Repository Configuration\n'));
+        // If git setup is explicitly skipped, don't do anything
+        if (!config.initGit) {
+            return;
+        }
         // Check if git is available
         const gitAvailable = await this.isGitAvailable();
         if (!gitAvailable) {
@@ -337,7 +351,7 @@ class ProjectGenerator {
             config.initGit = false;
             return;
         }
-        // Check if git is configured
+        // Check if git is configured (only if we're initializing git)
         try {
             await execa('git', ['config', 'user.name'], { stdio: 'pipe' });
             await execa('git', ['config', 'user.email'], { stdio: 'pipe' });
@@ -345,16 +359,9 @@ class ProjectGenerator {
         catch {
             console.log(chalk.yellow('⚠️  Git user not configured. Run: git config --global user.name "Your Name" && git config --global user.email "your.email@example.com"'));
         }
-        const gitAnswers = await inquirer.prompt([
-            {
-                type: 'confirm',
-                name: 'initGit',
-                message: 'Initialize git repository with initial commit?',
-                default: true,
-            },
-        ]);
-        config.initGit = gitAnswers.initGit;
-        config.createCommit = gitAnswers.initGit; // Always create commit if initializing git
+        // Since initGit is already true from command line options or defaults,
+        // we can proceed without prompting
+        config.createCommit = true; // Always create commit if initializing git
     }
     async generateProject(config) {
         console.log(chalk.cyan(CLI_CONFIG.messages.generatingProject));

package/dist/commands/generate/index.js

@@ -214,9 +214,9 @@ ${chalk.cyan('Use Cases:')}
             : 'Working directory (default: current directory)', type === 'project' || type === 'marketplace'
             ? getDefaultDestination()
             : undefined)
-            .option('-i, --interactive', type === 'marketplace'
+            .option('--no-interactive', type === 'marketplace'
             ? 'Not supported for marketplace'
-            : 'Force additional configuration prompts (generators prompt by default when info is missing)', false);
+            : 'Skip interactive prompts and use defaults (prompts by default)');
         if (helpText?.examples) {
             subCommand.addHelpText('after', helpText.examples);
         }

package/dist/commands/generate/templateDiscovery.js

@@ -3,11 +3,20 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 export class TemplateDiscovery {
     constructor() {
-        // Get the path to the templates directory relative to the ark CLI
-        // Navigate from tools/ark-cli/src/commands/generate/templateDiscovery.js to agents-at-scale/templates
+        // Get the path to the templates directory
+        // This handles both development and production scenarios
         const currentFile = fileURLToPath(import.meta.url);
-        const arkRoot = path.resolve(path.dirname(currentFile), '../../../../../');
-        this.templatesPath = path.join(arkRoot, 'templates');
+        // Try production path first (templates included in npm package)
+        const packageRoot = path.resolve(path.dirname(currentFile), '../../../');
+        const productionTemplatesPath = path.join(packageRoot, 'templates');
+        if (fs.existsSync(productionTemplatesPath)) {
+            this.templatesPath = productionTemplatesPath;
+        }
+        else {
+            // Fall back to development path (relative to ARK project root)
+            const arkRoot = path.resolve(path.dirname(currentFile), '../../../../../');
+            this.templatesPath = path.join(arkRoot, 'templates');
+        }
     }
     /**
      * Discover all available templates in the templates directory