@agents-at-scale/ark 0.1.60 → 0.1.62

package/dist/arkServices.d.ts

@@ -13,6 +13,7 @@ export declare const arkDependencies: DependencyCollection;
  */
 export declare const arkServices: ServiceCollection;
 /**
- * Get services that can be installed via Helm charts (only enabled services)
+ * Get services that can be installed via Helm charts (only enabled services).
+ * When a backend is specified, services with a non-matching requiresBackend are excluded.
  */
-export declare function getInstallableServices(): ServiceCollection;
+export declare function getInstallableServices(backend?: 'etcd' | 'postgresql'): ServiceCollection;

package/dist/arkServices.js

@@ -74,6 +74,19 @@ const defaultArkServices = {
         k8sDeploymentName: 'ark-controller',
         k8sDevDeploymentName: 'ark-controller-devspace',
     },
+    'ark-apiserver': {
+        name: 'ark-apiserver',
+        helmReleaseName: 'ark-apiserver',
+        description: 'Aggregated API server serving ark.mckinsey.com APIs from PostgreSQL',
+        enabled: true,
+        mandatory: true,
+        category: 'core',
+        namespace: 'ark-system',
+        chartPath: `${REGISTRY_BASE}/ark-apiserver:${CHART_VERSION}`,
+        installArgs: ['--create-namespace'],
+        k8sDeploymentName: 'ark-apiserver',
+        requiresBackend: 'postgresql',
+    },
     'ark-completions': {
         name: 'ark-completions',
         helmReleaseName: 'ark-completions',
@@ -208,14 +221,17 @@ function applyConfigOverrides(defaults) {
  */
 export const arkServices = applyConfigOverrides(defaultArkServices);
 /**
- * Get services that can be installed via Helm charts (only enabled services)
+ * Get services that can be installed via Helm charts (only enabled services).
+ * When a backend is specified, services with a non-matching requiresBackend are excluded.
  */
-export function getInstallableServices() {
+export function getInstallableServices(backend = 'etcd') {
     const installable = {};
     for (const [key, service] of Object.entries(arkServices)) {
-        if (service.enabled && service.chartPath) {
-            installable[key] = service;
-        }
+        if (!service.enabled || !service.chartPath)
+            continue;
+        if (service.requiresBackend && service.requiresBackend !== backend)
+            continue;
+        installable[key] = service;
     }
     return installable;
 }

package/dist/commands/install/index.js

@@ -10,6 +10,7 @@ import { printNextSteps } from '../../lib/nextSteps.js';
 import ora from 'ora';
 import { waitForServicesReady, } from '../../lib/waitForReady.js';
 import { parseTimeoutToSeconds } from '../../lib/timeout.js';
+import { detectStorageBackend } from '../../lib/readinessChecks.js';
 function isValidVersion(version) {
     return /^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/.test(version);
 }
@@ -75,7 +76,7 @@ async function checkAndCleanFailedRelease(releaseName, namespace, verbose = fals
         // Ignore errors - prerequisite may not exist
     }
 }
-async function installService(service, verbose = false, arkVersionOverride, marketplaceVersionOverride) {
+async function installService(service, verbose = false, arkVersionOverride, marketplaceVersionOverride, backend) {
     await uninstallPrerequisites(service, verbose);
     await checkAndCleanFailedRelease(service.helmReleaseName, service.namespace, verbose);
     let chartPath = service.chartPath;
@@ -140,6 +141,7 @@ export async function installArk(config, serviceNames = [], options = {}) {
     // Show cluster info
     output.success(`connected to cluster: ${chalk.bold(clusterInfo.context)}`);
     console.log(); // Add blank line after cluster info
+    const backend = await detectStorageBackend();
     // If specific services are requested, install only those services
     if (serviceNames.length > 0) {
         for (const serviceName of serviceNames) {
@@ -185,7 +187,7 @@ export async function installArk(config, serviceNames = [], options = {}) {
                 continue;
             }
             // Core ARK service
-            const services = getInstallableServices();
+            const services = getInstallableServices(backend);
             const service = Object.values(services).find((s) => s.name === serviceName);
             if (!service) {
                 output.error(`service '${serviceName}' not found`);
@@ -210,11 +212,19 @@ export async function installArk(config, serviceNames = [], options = {}) {
     }
     // If not using -y flag, show checklist interface
     if (!options.yes) {
+        const backendMatch = (s) => !s.requiresBackend || s.requiresBackend === backend;
         const coreServices = Object.values(arkServices)
-            .filter((s) => s.category === 'core')
-            .sort((a, b) => a.name.localeCompare(b.name));
+            .filter((s) => s.category === 'core' && backendMatch(s))
+            .sort((a, b) => {
+            // Ensure ark-controller is always first
+            if (a.name === 'ark-controller')
+                return -1;
+            if (b.name === 'ark-controller')
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
         const otherServices = Object.values(arkServices)
-            .filter((s) => s.category === 'service')
+            .filter((s) => s.category === 'service' && backendMatch(s))
             .sort((a, b) => a.name.localeCompare(b.name));
         const mandatoryServiceNames = [...coreServices, ...otherServices]
             .filter((s) => s.mandatory)
@@ -361,8 +371,16 @@ export async function installArk(config, serviceNames = [], options = {}) {
             }
         }
         // Install all services
-        const services = getInstallableServices();
-        for (const service of Object.values(services)) {
+        const services = getInstallableServices(backend);
+        const sortedServices = Object.values(services).sort((a, b) => {
+            // Ensure ark-controller is always first
+            if (a.name === 'ark-controller')
+                return -1;
+            if (b.name === 'ark-controller')
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        for (const service of sortedServices) {
             output.info(`installing ${service.name}...`);
             try {
                 await installService(service, options.verbose, options.arkVersion, options.marketplaceVersion);
@@ -388,7 +406,8 @@ export async function installArk(config, serviceNames = [], options = {}) {
             const servicesToWait = Object.values(arkServices).filter((s) => s.enabled &&
                 s.category === 'core' &&
                 s.k8sDeploymentName &&
-                s.namespace);
+                s.namespace &&
+                (!s.requiresBackend || s.requiresBackend === backend));
             const spinner = ora(`Waiting for Ark to be ready (timeout: ${timeoutSeconds}s)...`).start();
             const statusMap = new Map();
             servicesToWait.forEach((s) => statusMap.set(s.name, false));

package/dist/commands/status/index.js

@@ -5,6 +5,7 @@ import { StatusChecker } from '../../components/statusChecker.js';
 import { StatusFormatter, } from '../../ui/statusFormatter.js';
 import { fetchVersionInfo } from '../../lib/versions.js';
 import { waitForServicesReady, } from '../../lib/waitForReady.js';
+import { runReadinessChecks, detectStorageBackend, } from '../../lib/readinessChecks.js';
 import { arkServices } from '../../arkServices.js';
 import output from '../../lib/output.js';
 import { parseTimeoutToSeconds } from '../../lib/timeout.js';
@@ -270,13 +271,15 @@ export async function checkStatus(serviceNames, options) {
         StatusFormatter.printSections(sections);
         if (options?.waitForReady) {
             const timeoutSeconds = parseTimeoutToSeconds(options.waitForReady);
+            const backend = await detectStorageBackend();
             let servicesToWait = [];
             if (serviceNames && serviceNames.length > 0) {
                 servicesToWait = serviceNames
                     .map((name) => Object.values(arkServices).find((s) => s.name === name))
                     .filter((s) => s !== undefined &&
                     s.k8sDeploymentName !== undefined &&
-                    s.namespace !== undefined);
+                    s.namespace !== undefined &&
+                    (!s.requiresBackend || s.requiresBackend === backend));
                 if (servicesToWait.length === 0) {
                     output.error(`No valid services found matching: ${serviceNames.join(', ')}`);
                     process.exit(1);
@@ -286,7 +289,8 @@ export async function checkStatus(serviceNames, options) {
                 servicesToWait = Object.values(arkServices).filter((s) => s.enabled &&
                     s.category === 'core' &&
                     s.k8sDeploymentName &&
-                    s.namespace);
+                    s.namespace &&
+                    (!s.requiresBackend || s.requiresBackend === backend));
             }
             console.log();
             const waitSpinner = ora(`Waiting for services to be ready (timeout: ${timeoutSeconds}s)...`).start();
@@ -305,14 +309,23 @@ export async function checkStatus(serviceNames, options) {
                 });
                 waitSpinner.text = `Waiting for services to be ready (${elapsed}/${timeoutSeconds}s)...\n${lines.join('\n')}`;
             });
-            if (result) {
-                waitSpinner.succeed('All services are ready');
-                process.exit(0);
-            }
-            else {
+            if (!result) {
                 waitSpinner.fail(`Services did not become ready within ${timeoutSeconds} seconds`);
                 process.exit(1);
             }
+            waitSpinner.succeed('All services are ready');
+            const elapsedSeconds = Math.floor((Date.now() - startTime) / 1000);
+            const remainingSeconds = Math.max(1, timeoutSeconds - elapsedSeconds);
+            const deepResults = await runReadinessChecks(remainingSeconds, (r) => {
+                const icon = r.passed ? chalk.green('✓') : chalk.red('✗');
+                const dur = `${(r.durationMs / 1000).toFixed(1)}s`;
+                const suffix = r.message ? ` — ${r.message}` : '';
+                console.log(`  ${icon} ${r.name} (${dur})${suffix}`);
+            });
+            if (deepResults.some((r) => !r.passed)) {
+                process.exit(1);
+            }
+            process.exit(0);
         }
         process.exit(0);
     }

package/dist/lib/readinessChecks.d.ts

@@ -0,0 +1,10 @@
+export type StorageBackend = 'etcd' | 'postgresql';
+export interface ReadinessCheckResult {
+    name: string;
+    passed: boolean;
+    durationMs: number;
+    message?: string;
+}
+export type ReadinessProgress = (result: ReadinessCheckResult) => void;
+export declare function detectStorageBackend(): Promise<StorageBackend>;
+export declare function runReadinessChecks(timeoutSeconds: number, onProgress?: ReadinessProgress): Promise<ReadinessCheckResult[]>;

package/dist/lib/readinessChecks.js

@@ -0,0 +1,88 @@
+import { execa } from 'execa';
+const API_GROUP_POLL_INTERVAL_MS = 10000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function runKubectl(args, timeoutMs) {
+    const result = await execa('kubectl', args, {
+        timeout: timeoutMs,
+        reject: false,
+    });
+    return {
+        exitCode: result.exitCode ?? 1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+export async function detectStorageBackend() {
+    const { exitCode } = await runKubectl(['get', 'crd', 'agents.ark.mckinsey.com'], 10000);
+    return exitCode === 0 ? 'etcd' : 'postgresql';
+}
+async function waitForApiServices(timeoutSeconds) {
+    const start = Date.now();
+    const primary = await runKubectl([
+        'wait',
+        '--for=condition=Available',
+        'apiservice',
+        'v1alpha1.ark.mckinsey.com',
+        `--timeout=${timeoutSeconds}s`,
+    ], timeoutSeconds * 1000 + 5000);
+    await runKubectl([
+        'wait',
+        '--for=condition=Available',
+        'apiservice',
+        'v1prealpha1.ark.mckinsey.com',
+        '--timeout=30s',
+    ], 35000);
+    return {
+        name: 'APIServices available',
+        passed: primary.exitCode === 0,
+        durationMs: Date.now() - start,
+        message: primary.exitCode === 0
+            ? undefined
+            : (primary.stderr || primary.stdout).trim(),
+    };
+}
+async function waitForApiGroup(timeoutSeconds) {
+    const start = Date.now();
+    const deadline = start + timeoutSeconds * 1000;
+    while (Date.now() < deadline) {
+        const { stdout, exitCode } = await runKubectl(['api-resources', '--api-group=ark.mckinsey.com', '-o', 'name'], 10000);
+        if (exitCode === 0 && /agents\./.test(stdout)) {
+            return {
+                name: 'API group registered',
+                passed: true,
+                durationMs: Date.now() - start,
+            };
+        }
+        await sleep(API_GROUP_POLL_INTERVAL_MS);
+    }
+    return {
+        name: 'API group registered',
+        passed: false,
+        durationMs: Date.now() - start,
+        message: 'timed out waiting for ark.mckinsey.com API group',
+    };
+}
+export async function runReadinessChecks(timeoutSeconds, onProgress) {
+    const backend = await detectStorageBackend();
+    if (backend === 'etcd') {
+        return [];
+    }
+    const overallStart = Date.now();
+    const remaining = () => Math.max(1, timeoutSeconds - Math.floor((Date.now() - overallStart) / 1000));
+    const checks = [
+        () => waitForApiServices(Math.min(remaining(), 120)),
+        () => waitForApiGroup(Math.min(remaining(), 300)),
+    ];
+    const results = [];
+    for (const check of checks) {
+        const result = await check();
+        results.push(result);
+        onProgress?.(result);
+        if (!result.passed) {
+            break;
+        }
+    }
+    return results;
+}

package/dist/types/arkService.d.ts

@@ -18,6 +18,7 @@ export interface ArkService {
     k8sPortForwardLocalPort?: number;
     k8sDeploymentName?: string;
     k8sDevDeploymentName?: string;
+    requiresBackend?: 'etcd' | 'postgresql';
 }
 export interface ServiceCollection {
     [key: string]: ArkService;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-at-scale/ark",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "description": "Ark CLI - Interactive terminal interface for ARK agents",
   "main": "dist/index.js",
   "type": "module",
@@ -44,7 +44,7 @@
   "dependencies": {
     "@kubernetes/client-node": "^1.3.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "axios": "^1.15.0",
+    "axios": "^1.16.0",
     "chalk": "^4.1.2",
     "commander": "^12.1.0",
     "debug": "^4.4.1",
@@ -91,6 +91,7 @@
     "@hono/node-server": "^1.19.13",
     "flatted": "^3.4.2",
     "tar": "^7.5.11",
-    "express-rate-limit": "^8.3.0"
+    "express-rate-limit": "^8.3.0",
+    "fast-uri": "^3.1.1"
   }
 }

package/templates/tool/uv.lock

@@ -763,11 +763,11 @@ wheels = [
 
 [[package]]
 name = "python-dotenv"
-version = "1.1.1"
+version = "1.2.2"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f6/b0/4bc07ccd3572a2f9df7e6782f52b0c6c90dcbb803ac4a167702d7d0dfe1e/python_dotenv-1.1.1.tar.gz", hash = "sha256:a8a6399716257f45be6a007360200409fce5cda2661e3dec71d23dc15f6189ab", size = 41978, upload-time = "2025-06-24T04:21:07.341Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz", hash = "sha256:2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3", size = 50135, upload-time = "2026-03-01T16:00:26.196Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/5f/ed/539768cf28c661b5b068d66d96a2f155c4971a5d55684a514c1a0e0dec2f/python_dotenv-1.1.1-py3-none-any.whl", hash = "sha256:31f23644fe2602f88ff55e1f5c79ba497e01224ee7737937930c448e4d0e24dc", size = 20556, upload-time = "2025-06-24T04:21:06.073Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
 ]
 
 [[package]]
@@ -1007,15 +1007,15 @@ wheels = [
 
 [[package]]
 name = "starlette"
-version = "0.47.1"
+version = "0.49.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
     { name = "typing-extensions", marker = "python_full_version < '3.13'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/0a/69/662169fdb92fb96ec3eaee218cf540a629d629c86d7993d9651226a6789b/starlette-0.47.1.tar.gz", hash = "sha256:aef012dd2b6be325ffa16698f9dc533614fb1cebd593a906b90dc1025529a79b", size = 2583072, upload-time = "2025-06-21T04:03:17.337Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/3f/507c21db33b66fb027a332f2cb3abbbe924cc3a79ced12f01ed8645955c9/starlette-0.49.1.tar.gz", hash = "sha256:481a43b71e24ed8c43b11ea02f5353d77840e01480881b8cb5a26b8cae64a8cb", size = 2654703, upload-time = "2025-10-28T17:34:10.928Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/82/95/38ef0cd7fa11eaba6a99b3c4f5ac948d8bc6ff199aabd327a29cc000840c/starlette-0.47.1-py3-none-any.whl", hash = "sha256:5e11c9f5c7c3f24959edbf2dffdc01bba860228acf657129467d8a7468591527", size = 72747, upload-time = "2025-06-21T04:03:15.705Z" },
+    { url = "https://files.pythonhosted.org/packages/51/da/545b75d420bb23b5d494b0517757b351963e974e79933f01e05c929f20a6/starlette-0.49.1-py3-none-any.whl", hash = "sha256:d92ce9f07e4a3caa3ac13a79523bd18e3bc0042bb8ff2d759a8e7dd0e1859875", size = 74175, upload-time = "2025-10-28T17:34:09.13Z" },
 ]
 
 [[package]]