@agents-at-scale/ark 0.1.31

package/dist/lib/config.js

@@ -0,0 +1,223 @@
+/**
+ * Configuration management for ARK CLI
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { SecurityUtils } from './security.js';
+import { ValidationError } from './errors.js';
+export const DEFAULT_CONFIG = {
+    defaultProjectType: 'with-samples',
+    defaultDestination: process.cwd(),
+    skipGitByDefault: false,
+    skipModelsbyDefault: false,
+    preferredEditor: process.env.EDITOR || 'code',
+    colorOutput: true,
+    verboseOutput: false,
+    defaultModelProvider: 'azure',
+    customTemplates: {},
+    parallelOperations: true,
+    maxConcurrentFiles: 10,
+    fileWatchingEnabled: false,
+    telemetryEnabled: false,
+    errorReporting: false,
+};
+export class ConfigManager {
+    constructor() {
+        this.configPath = this.getConfigPath();
+        this.config = this.loadConfig();
+    }
+    /**
+     * Get the path to the configuration file
+     */
+    getConfigPath() {
+        const configDir = process.env.ARK_CONFIG_DIR || path.join(os.homedir(), '.config', 'ark');
+        // Ensure config directory exists
+        if (!fs.existsSync(configDir)) {
+            fs.mkdirSync(configDir, { recursive: true, mode: 0o755 });
+        }
+        return path.join(configDir, 'config.json');
+    }
+    /**
+     * Load configuration from file or create with defaults
+     */
+    loadConfig() {
+        try {
+            if (fs.existsSync(this.configPath)) {
+                const configContent = fs.readFileSync(this.configPath, 'utf-8');
+                const userConfig = JSON.parse(configContent);
+                // Merge with defaults to ensure all properties exist
+                return { ...DEFAULT_CONFIG, ...userConfig };
+            }
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to load config from ${this.configPath}: ${error}`);
+        }
+        // Return defaults and save them
+        this.saveConfig(DEFAULT_CONFIG);
+        return { ...DEFAULT_CONFIG };
+    }
+    /**
+     * Save configuration to file
+     */
+    saveConfig(config) {
+        try {
+            const configContent = JSON.stringify(config, null, 2);
+            SecurityUtils.validatePath(this.configPath, 'config file');
+            fs.writeFileSync(this.configPath, configContent, {
+                mode: 0o600, // Owner read/write only
+                flag: 'w',
+            });
+        }
+        catch (error) {
+            throw new ValidationError(`Failed to save configuration: ${error}`, 'config', [
+                'Check file permissions',
+                'Ensure config directory exists',
+                'Verify disk space',
+            ]);
+        }
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update configuration
+     */
+    updateConfig(updates) {
+        this.config = { ...this.config, ...updates };
+        this.saveConfig(this.config);
+    }
+    /**
+     * Reset configuration to defaults
+     */
+    resetConfig() {
+        this.config = { ...DEFAULT_CONFIG };
+        this.saveConfig(this.config);
+    }
+    /**
+     * Get a specific configuration value
+     */
+    get(key) {
+        return this.config[key];
+    }
+    /**
+     * Set a specific configuration value
+     */
+    set(key, value) {
+        this.config[key] = value;
+        this.saveConfig(this.config);
+    }
+    /**
+     * Validate configuration values
+     */
+    validateConfig() {
+        const config = this.config;
+        // Validate project type
+        if (!['empty', 'with-samples'].includes(config.defaultProjectType)) {
+            throw new ValidationError(`Invalid defaultProjectType: ${config.defaultProjectType}`, 'defaultProjectType', ['Must be "empty" or "with-samples"']);
+        }
+        // Validate model provider
+        const validProviders = ['azure', 'openai', 'claude', 'gemini', 'custom'];
+        if (!validProviders.includes(config.defaultModelProvider)) {
+            throw new ValidationError(`Invalid defaultModelProvider: ${config.defaultModelProvider}`, 'defaultModelProvider', [`Must be one of: ${validProviders.join(', ')}`]);
+        }
+        // Validate numeric values
+        if (config.maxConcurrentFiles < 1 || config.maxConcurrentFiles > 100) {
+            throw new ValidationError(`Invalid maxConcurrentFiles: ${config.maxConcurrentFiles}`, 'maxConcurrentFiles', ['Must be between 1 and 100']);
+        }
+        // Validate paths
+        if (config.defaultDestination) {
+            SecurityUtils.validatePath(config.defaultDestination, 'default destination');
+        }
+        if (config.templateDirectory) {
+            SecurityUtils.validatePath(config.templateDirectory, 'template directory');
+        }
+    }
+    /**
+     * Get environment variable overrides
+     */
+    getEnvironmentOverrides() {
+        const overrides = {};
+        // Check for environment variable overrides
+        if (process.env.ARK_DEFAULT_PROJECT_TYPE) {
+            const projectType = process.env.ARK_DEFAULT_PROJECT_TYPE;
+            if (['empty', 'with-samples'].includes(projectType)) {
+                overrides.defaultProjectType = projectType;
+            }
+        }
+        if (process.env.ARK_DEFAULT_DESTINATION) {
+            overrides.defaultDestination = process.env.ARK_DEFAULT_DESTINATION;
+        }
+        if (process.env.ARK_SKIP_GIT) {
+            overrides.skipGitByDefault = process.env.ARK_SKIP_GIT === 'true';
+        }
+        if (process.env.ARK_SKIP_MODELS) {
+            overrides.skipModelsbyDefault = process.env.ARK_SKIP_MODELS === 'true';
+        }
+        if (process.env.ARK_COLOR_OUTPUT) {
+            overrides.colorOutput = process.env.ARK_COLOR_OUTPUT !== 'false';
+        }
+        if (process.env.ARK_VERBOSE) {
+            overrides.verboseOutput = process.env.ARK_VERBOSE === 'true';
+        }
+        if (process.env.ARK_DEFAULT_MODEL_PROVIDER) {
+            const provider = process.env.ARK_DEFAULT_MODEL_PROVIDER;
+            const validProviders = [
+                'azure',
+                'openai',
+                'claude',
+                'gemini',
+                'custom',
+            ];
+            if (validProviders.includes(provider)) {
+                overrides.defaultModelProvider =
+                    provider;
+            }
+        }
+        return overrides;
+    }
+    /**
+     * Get merged configuration with environment overrides
+     */
+    getMergedConfig() {
+        const envOverrides = this.getEnvironmentOverrides();
+        return { ...this.config, ...envOverrides };
+    }
+    /**
+     * Export configuration for backup
+     */
+    exportConfig() {
+        return JSON.stringify(this.config, null, 2);
+    }
+    /**
+     * Import configuration from backup
+     */
+    importConfig(configJson) {
+        try {
+            const importedConfig = JSON.parse(configJson);
+            // Validate the imported config
+            const tempManager = new ConfigManager();
+            tempManager.config = { ...DEFAULT_CONFIG, ...importedConfig };
+            tempManager.validateConfig();
+            // If validation passes, update our config
+            this.config = tempManager.config;
+            this.saveConfig(this.config);
+        }
+        catch (error) {
+            throw new ValidationError(`Failed to import configuration: ${error}`, 'config', [
+                'Check JSON syntax',
+                'Ensure all required fields are present',
+                'Verify configuration values are valid',
+            ]);
+        }
+    }
+    /**
+     * Get configuration file path for CLI display
+     */
+    getConfigFilePath() {
+        return this.configPath;
+    }
+}

package/dist/lib/consts.d.ts

@@ -0,0 +1,10 @@
+export declare const DEFAULT_ADDRESS_ARK_API = "http://localhost:8000";
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_CONNECTION_TEST_TIMEOUT_MS = 5000;
+export declare const CONFIG_DIR_NAME = "ark";
+export declare const CONFIG_FILE_NAME = "ark-cli.json";
+export declare const DEFAULT_ARK_DASHBOARD_URL = "http://localhost:3000";
+export declare const DEFAULT_ARK_A2A_URL = "http://localhost:8080";
+export declare const DEFAULT_ARK_MEMORY_URL = "http://localhost:8081";
+export declare const DEFAULT_ARK_OTEL_URL = "http://localhost:4318";
+export declare const ARK_REPO_ERROR_MESSAGE = "Error: This command must be run inside the ARK repository.";

package/dist/lib/consts.js

@@ -0,0 +1,15 @@
+// Default ARK API server address
+export const DEFAULT_ADDRESS_ARK_API = 'http://localhost:8000';
+// Default timeout values
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const DEFAULT_CONNECTION_TEST_TIMEOUT_MS = 5000;
+// Configuration paths
+export const CONFIG_DIR_NAME = 'ark';
+export const CONFIG_FILE_NAME = 'ark-cli.json';
+// Default service URLs
+export const DEFAULT_ARK_DASHBOARD_URL = 'http://localhost:3000';
+export const DEFAULT_ARK_A2A_URL = 'http://localhost:8080';
+export const DEFAULT_ARK_MEMORY_URL = 'http://localhost:8081';
+export const DEFAULT_ARK_OTEL_URL = 'http://localhost:4318';
+// Error message for different ARK repo
+export const ARK_REPO_ERROR_MESSAGE = 'Error: This command must be run inside the ARK repository.';

package/dist/lib/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Centralized error handling for ARK CLI
+ */
+export declare enum ErrorCode {
+    INVALID_INPUT = "INVALID_INPUT",
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    TEMPLATE_ERROR = "TEMPLATE_ERROR",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    DEPENDENCY_MISSING = "DEPENDENCY_MISSING",
+    PROJECT_STRUCTURE_INVALID = "PROJECT_STRUCTURE_INVALID",
+    GENERATION_FAILED = "GENERATION_FAILED",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+}
+export declare class ArkError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly suggestions?: string[];
+    constructor(message: string, code?: ErrorCode, details?: Record<string, unknown>, suggestions?: string[]);
+}
+export declare class ValidationError extends ArkError {
+    constructor(message: string, field?: string, suggestions?: string[]);
+}
+export declare class TemplateError extends ArkError {
+    constructor(message: string, templatePath?: string, suggestions?: string[]);
+}
+export declare class ProjectStructureError extends ArkError {
+    constructor(message: string, projectPath?: string, suggestions?: string[]);
+}
+export declare class ErrorHandler {
+    /**
+     * Format and display an error with helpful context
+     */
+    static formatError(error: Error | ArkError): string;
+    /**
+     * Handle and exit with appropriate error code
+     */
+    static handleAndExit(error: Error | ArkError): never;
+    /**
+     * Wrap async functions with error handling
+     */
+    static catchAndHandle<T>(fn: () => Promise<T>, context?: string): Promise<T>;
+    /**
+     * Validate required dependencies and throw helpful errors
+     */
+    static validateDependency(command: string, purpose: string, installInstructions?: string): Promise<void>;
+}
+/**
+ * Input validation utilities with better error messages
+ */
+export declare class InputValidator {
+    static validateName(name: string, type?: string): void;
+    static validatePath(path: string, type?: string): void;
+    static validateDirectory(dirPath: string, shouldExist?: boolean): void;
+}

package/dist/lib/errors.js

@@ -0,0 +1,208 @@
+/**
+ * Centralized error handling for ARK CLI
+ */
+import chalk from 'chalk';
+import fs from 'fs';
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["INVALID_INPUT"] = "INVALID_INPUT";
+    ErrorCode["FILE_NOT_FOUND"] = "FILE_NOT_FOUND";
+    ErrorCode["PERMISSION_DENIED"] = "PERMISSION_DENIED";
+    ErrorCode["TEMPLATE_ERROR"] = "TEMPLATE_ERROR";
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCode["DEPENDENCY_MISSING"] = "DEPENDENCY_MISSING";
+    ErrorCode["PROJECT_STRUCTURE_INVALID"] = "PROJECT_STRUCTURE_INVALID";
+    ErrorCode["GENERATION_FAILED"] = "GENERATION_FAILED";
+    ErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+export class ArkError extends Error {
+    constructor(message, code = ErrorCode.UNKNOWN_ERROR, details, suggestions) {
+        super(message);
+        this.name = 'ArkError';
+        this.code = code;
+        this.details = details;
+        this.suggestions = suggestions;
+    }
+}
+export class ValidationError extends ArkError {
+    constructor(message, field, suggestions) {
+        super(message, ErrorCode.VALIDATION_ERROR, field ? { field } : undefined, suggestions);
+        this.name = 'ValidationError';
+    }
+}
+export class TemplateError extends ArkError {
+    constructor(message, templatePath, suggestions) {
+        super(message, ErrorCode.TEMPLATE_ERROR, templatePath ? { templatePath } : undefined, suggestions);
+        this.name = 'TemplateError';
+    }
+}
+export class ProjectStructureError extends ArkError {
+    constructor(message, projectPath, suggestions) {
+        super(message, ErrorCode.PROJECT_STRUCTURE_INVALID, projectPath ? { projectPath } : undefined, suggestions || [
+            'Ensure you are in a valid ARK project directory',
+            'Run "ark generate project" to create a new project',
+            'Check that Chart.yaml and agents/ directory exist',
+        ]);
+        this.name = 'ProjectStructureError';
+    }
+}
+export class ErrorHandler {
+    /**
+     * Format and display an error with helpful context
+     */
+    static formatError(error) {
+        const lines = [];
+        // Error header
+        lines.push(chalk.red(`❌ ${error.message}`));
+        // Add error details if available
+        if (error instanceof ArkError) {
+            if (error.details) {
+                lines.push('');
+                lines.push(chalk.gray('Details:'));
+                for (const [key, value] of Object.entries(error.details)) {
+                    lines.push(chalk.gray(`  ${key}: ${value}`));
+                }
+            }
+            // Add suggestions if available
+            if (error.suggestions && error.suggestions.length > 0) {
+                lines.push('');
+                lines.push(chalk.yellow('💡 Suggestions:'));
+                error.suggestions.forEach((suggestion) => {
+                    lines.push(chalk.yellow(`  • ${suggestion}`));
+                });
+            }
+        }
+        // Add stack trace in debug mode
+        if (process.env.DEBUG || process.env.NODE_ENV === 'development') {
+            lines.push('');
+            lines.push(chalk.gray('Stack trace:'));
+            lines.push(chalk.gray(error.stack || 'No stack trace available'));
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Handle and exit with appropriate error code
+     */
+    static handleAndExit(error) {
+        console.error('\n' + this.formatError(error));
+        // Exit with appropriate code
+        if (error instanceof ArkError) {
+            switch (error.code) {
+                case ErrorCode.INVALID_INPUT:
+                case ErrorCode.VALIDATION_ERROR:
+                    process.exit(22); // EINVAL
+                    break;
+                case ErrorCode.FILE_NOT_FOUND:
+                    process.exit(2); // ENOENT
+                    break;
+                case ErrorCode.PERMISSION_DENIED:
+                    process.exit(13); // EACCES
+                    break;
+                case ErrorCode.DEPENDENCY_MISSING:
+                    process.exit(127); // Command not found
+                    break;
+                default:
+                    process.exit(1);
+            }
+        }
+        process.exit(1);
+    }
+    /**
+     * Wrap async functions with error handling
+     */
+    static async catchAndHandle(fn, context) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (error instanceof ArkError) {
+                throw error;
+            }
+            // Convert generic errors to ArkError with context
+            const errorText = error instanceof Error ? error.message : String(error);
+            const message = context ? `${context}: ${errorText}` : errorText;
+            throw new ArkError(message, ErrorCode.UNKNOWN_ERROR);
+        }
+    }
+    /**
+     * Validate required dependencies and throw helpful errors
+     */
+    static async validateDependency(command, purpose, installInstructions) {
+        try {
+            const { execa } = await import('execa');
+            await execa(command, ['--version'], { stdio: 'ignore' });
+        }
+        catch {
+            const suggestions = [];
+            if (installInstructions) {
+                suggestions.push(installInstructions);
+            }
+            suggestions.push(`Visit the official ${command} documentation for installation instructions`);
+            throw new ArkError(`${command} is required for ${purpose} but was not found`, ErrorCode.DEPENDENCY_MISSING, { command, purpose }, suggestions);
+        }
+    }
+}
+/**
+ * Input validation utilities with better error messages
+ */
+export class InputValidator {
+    static validateName(name, type = 'name') {
+        if (!name || name.trim().length === 0) {
+            throw new ValidationError(`${type} cannot be empty`, 'name', [
+                `Provide a valid ${type}`,
+            ]);
+        }
+        const trimmed = name.trim();
+        if (trimmed.length > 63) {
+            throw new ValidationError(`${type} must be 63 characters or less (got ${trimmed.length})`, 'name', [`Shorten the ${type} to 63 characters or less`]);
+        }
+        // Kubernetes name validation
+        const kebabRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+        if (!kebabRegex.test(trimmed)) {
+            const suggestions = [];
+            const normalized = trimmed
+                .toLowerCase()
+                .replace(/[\s_]+/g, '-')
+                .replace(/([a-z])([A-Z])/g, '$1-$2')
+                .replace(/-{2,}/g, '-') // Replace 2+ consecutive hyphens with single hyphen (ReDoS-safe)
+                .replace(/^-/, '') // Remove single leading hyphen (ReDoS-safe)
+                .replace(/-$/, ''); // Remove single trailing hyphen (ReDoS-safe)
+            if (normalized !== trimmed) {
+                suggestions.push(`Try: "${normalized}"`);
+            }
+            suggestions.push(`${type} must be lowercase letters, numbers, and hyphens only`);
+            suggestions.push(`${type} cannot start or end with a hyphen`);
+            throw new ValidationError(`Invalid ${type}: "${trimmed}"`, 'name', suggestions);
+        }
+    }
+    static validatePath(path, type = 'path') {
+        if (!path || path.trim().length === 0) {
+            throw new ValidationError(`${type} cannot be empty`, 'path');
+        }
+        // Check for potentially dangerous paths
+        const dangerous = ['..', '~', '$'];
+        if (dangerous.some((pattern) => path.includes(pattern))) {
+            throw new ValidationError(`${type} contains potentially unsafe characters`, 'path', [
+                'Use absolute paths or simple relative paths',
+                'Avoid parent directory references (..)',
+                'Avoid shell variables and special characters',
+            ]);
+        }
+    }
+    static validateDirectory(dirPath, shouldExist = false) {
+        this.validatePath(dirPath, 'directory');
+        if (shouldExist) {
+            if (!fs.existsSync(dirPath)) {
+                throw new ValidationError(`Directory does not exist: ${dirPath}`, 'directory', [
+                    'Create the directory first',
+                    'Check the path spelling',
+                    'Ensure you have read permissions',
+                ]);
+            }
+            if (!fs.statSync(dirPath).isDirectory()) {
+                throw new ValidationError(`Path exists but is not a directory: ${dirPath}`, 'directory');
+            }
+        }
+    }
+}

package/dist/lib/exec.d.ts

@@ -0,0 +1,5 @@
+export declare function executeCommand(command: string, args?: string[]): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function fileExists(path: string): boolean;

package/dist/lib/exec.js

@@ -0,0 +1,20 @@
+import fs from 'fs';
+import { execa } from 'execa';
+export async function executeCommand(command, args = []) {
+    try {
+        const result = await execa(command, args);
+        return { stdout: result.stdout, stderr: result.stderr };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Command failed: ${command} ${args.join(' ')}\n${errorMessage}`);
+    }
+}
+export function fileExists(path) {
+    try {
+        return fs.existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/lib/gatewayManager.d.ts

@@ -0,0 +1,24 @@
+export declare class GatewayManager {
+    private kubernetesManager;
+    constructor();
+    /**
+     * Check if localhost-gateway port-forward is running by testing the endpoint
+     */
+    isPortForwardRunning(port?: number): Promise<boolean>;
+    /**
+     * Check if localhost-gateway service is deployed in cluster
+     */
+    isGatewayDeployed(): Promise<boolean>;
+    /**
+     * Check if port-forward is needed and provide setup instructions
+     */
+    checkPortForwardStatus(port?: number): Promise<{
+        isRunning: boolean;
+        needsSetup: boolean;
+        instructions?: string;
+    }>;
+    /**
+     * Get setup instructions for fresh installations
+     */
+    getSetupInstructions(): string;
+}

package/dist/lib/gatewayManager.js

@@ -0,0 +1,85 @@
+import * as k8s from '@kubernetes/client-node';
+import { KubernetesConfigManager } from './kubernetes.js';
+export class GatewayManager {
+    constructor() {
+        this.kubernetesManager = new KubernetesConfigManager();
+    }
+    /**
+     * Check if localhost-gateway port-forward is running by testing the endpoint
+     */
+    async isPortForwardRunning(port = 8080) {
+        try {
+            const axios = (await import('axios')).default;
+            await axios.get(`http://127.0.0.1:${port}`, {
+                timeout: 2000,
+                validateStatus: () => true,
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if localhost-gateway service is deployed in cluster
+     */
+    async isGatewayDeployed() {
+        try {
+            await this.kubernetesManager.initializeConfig();
+            const kc = this.kubernetesManager.getKubeConfig();
+            const k8sApi = kc.makeApiClient(k8s.CoreV1Api);
+            await k8sApi.readNamespacedService({
+                name: 'localhost-gateway-nginx',
+                namespace: 'ark-system',
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if port-forward is needed and provide setup instructions
+     */
+    async checkPortForwardStatus(port = 8080) {
+        const isRunning = await this.isPortForwardRunning(port);
+        if (isRunning) {
+            return { isRunning: true, needsSetup: false };
+        }
+        const isDeployed = await this.isGatewayDeployed();
+        if (!isDeployed) {
+            return {
+                isRunning: false,
+                needsSetup: true,
+                instructions: this.getSetupInstructions(),
+            };
+        }
+        return {
+            isRunning: false,
+            needsSetup: true,
+            instructions: `Gateway is deployed but port-forward not running. Start it with:\nkubectl port-forward -n ark-system service/localhost-gateway-nginx ${port}:80`,
+        };
+    }
+    /**
+     * Get setup instructions for fresh installations
+     */
+    getSetupInstructions() {
+        return `
+🔧 ARK Gateway Setup Required:
+
+To enable service discovery, you need to install the localhost-gateway:
+
+1. From your agents-at-scale project root, run:
+   make localhost-gateway-install
+
+2. This will:
+   - Install Gateway API CRDs
+   - Deploy NGINX Gateway Fabric
+   - Set up port-forwarding to localhost:8080
+
+3. Then run 'ark check status' again
+
+For more info: docs/content/ark-101/ark-gateway.mdx
+`;
+    }
+}

package/dist/lib/kubernetes.d.ts

@@ -0,0 +1,28 @@
+import * as k8s from '@kubernetes/client-node';
+import { KubernetesConfig } from './types.js';
+export declare class KubernetesConfigManager {
+    private kc;
+    constructor();
+    /**
+     * Get the KubeConfig instance for API client creation
+     */
+    getKubeConfig(): k8s.KubeConfig;
+    /**
+     * Initialize Kubernetes configuration similar to fark's approach
+     * Priority: in-cluster config > KUBECONFIG env > ~/.kube/config
+     */
+    initializeConfig(): Promise<KubernetesConfig>;
+    /**
+     * Get the API server URL for the current cluster
+     */
+    getClusterApiUrl(): string;
+    /**
+     * Detect ark-api service URL in the cluster
+     * This mimics how fark discovers services
+     */
+    getArkApiUrl(namespace?: string): Promise<string>;
+    /**
+     * Check if we can access the cluster
+     */
+    testClusterAccess(): Promise<boolean>;
+}