@agents-at-scale/ark 0.1.31

package/README.md

@@ -0,0 +1,95 @@
+# ARK CLI
+
+Interactive terminal interface for ARK agents.
+
+## Prerequisites
+
+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
+   ```
+
+## Installation
+
+```bash
+cd tools/ark-cli
+npm run build
+npm install -g .
+```
+
+## Usage
+
+```bash
+# Interactive mode (no arguments)
+ark
+
+# Show help
+ark --help
+ark cluster --help
+
+# Check system status
+ark check status
+
+# Generate (project, agent, team, etc)
+ark generate
+
+# Cluster operations
+ark cluster get-type
+ark cluster get-ip
+ark cluster get-ip --verbose
+ark cluster get-ip --context minikube
+
+# Show shell autocomplete options.
+ark autocomplete
+```
+
+## Configuration
+
+ARK CLI automatically detects services via:
+
+1. **localhost-gateway** (when running) - `*.127.0.0.1.nip.io:8080`
+2. **Kubernetes service discovery** - for internal services
+3. **Default localhost URLs** - fallback
+
+Settings stored in `~/.config/ark-cli/config.json`
+
+## Development
+
+**Note:** All make commands must be run from the repository root directory.
+
+```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
+```
+
+## Troubleshooting
+
+Enable debug logging to see detailed configuration discovery and service resolution:
+
+```bash
+# Debug configuration discovery and service resolution
+DEBUG=ark:config ark check status
+
+# 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
+```
+
+**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

package/dist/commands/cluster/get-ip.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createGetIpCommand(): Command;

package/dist/commands/cluster/get-ip.js

@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+import { Command } from 'commander';
+import { getClusterIp } from '../../lib/cluster.js';
+export function createGetIpCommand() {
+    const getIp = new Command('get-ip');
+    getIp
+        .description('Get the IP address of the current Kubernetes cluster')
+        .option('-c, --context <context>', 'Kubernetes context to use')
+        .action(async (options) => {
+        try {
+            const clusterInfo = await getClusterIp(options.context);
+            if (clusterInfo.error) {
+                console.error(chalk.red('Error getting cluster IP:'), clusterInfo.error);
+                process.exit(1);
+            }
+            if (!clusterInfo.ip) {
+                console.error(chalk.red('Could not determine cluster IP'));
+                process.exit(1);
+            }
+            console.log(clusterInfo.ip);
+            console.error(chalk.grey(`Cluster type: ${clusterInfo.type}`));
+            if (clusterInfo.context) {
+                console.error(chalk.grey(`Context: ${clusterInfo.context}`));
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Failed to get cluster IP:'), error.message);
+            process.exit(1);
+        }
+    });
+    return getIp;
+}

package/dist/commands/cluster/get-type.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createGetTypeCommand(): Command;

package/dist/commands/cluster/get-type.js

@@ -0,0 +1,26 @@
+import chalk from 'chalk';
+import { Command } from 'commander';
+import { detectClusterType } from '../../lib/cluster.js';
+export function createGetTypeCommand() {
+    const getType = new Command('get-type');
+    getType
+        .description('Detect and display the current Kubernetes cluster type')
+        .action(async () => {
+        try {
+            const clusterInfo = await detectClusterType();
+            if (clusterInfo.error) {
+                console.error(chalk.red('Error detecting cluster type:'), clusterInfo.error);
+                process.exit(1);
+            }
+            console.log(clusterInfo.type);
+            if (clusterInfo.context) {
+                console.error(chalk.grey(`Context: ${clusterInfo.context}`));
+            }
+        }
+        catch (error) {
+            console.error(chalk.red('Failed to detect cluster type:'), error.message);
+            process.exit(1);
+        }
+    });
+    return getType;
+}

package/dist/commands/cluster/index.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createClusterCommand(): Command;

package/dist/commands/cluster/index.js

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+import { createGetIpCommand } from './get-ip.js';
+import { createGetTypeCommand } from './get-type.js';
+export function createClusterCommand() {
+    const cluster = new Command('cluster');
+    cluster.description('Cluster management commands');
+    cluster.addCommand(createGetTypeCommand());
+    cluster.addCommand(createGetIpCommand());
+    return cluster;
+}

package/dist/commands/completion.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function createCompletionCommand(): Command;

package/dist/commands/completion.js

@@ -0,0 +1,108 @@
+import chalk from 'chalk';
+import { Command } from 'commander';
+export function createCompletionCommand() {
+    const completion = new Command('completion');
+    completion.description('Generate shell completion scripts').action(() => {
+        console.log(chalk.cyan('Shell completion for ARK CLI'));
+        console.log('');
+        console.log('Usage:');
+        console.log('  ark completion bash   Generate bash completion script');
+        console.log('  ark completion zsh    Generate zsh completion script');
+        console.log('');
+        console.log('To enable completion, add this to your shell profile:');
+        console.log(chalk.grey('  # For bash:'));
+        console.log(chalk.grey('  eval "$(ark completion bash)"'));
+        console.log(chalk.grey('  # For zsh:'));
+        console.log(chalk.grey('  eval "$(ark completion zsh)"'));
+    });
+    completion
+        .command('bash')
+        .description('Generate bash completion script')
+        .action(() => {
+        console.log(`
+_ark_completion() {
+  local cur prev opts
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  
+  case \${COMP_CWORD} in
+    1)
+      opts="cluster completion check help"
+      COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
+      return 0
+      ;;
+    2)
+      case \${prev} in
+        cluster)
+          opts="get-ip get-type"
+          COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
+          return 0
+          ;;
+        completion)
+          opts="bash zsh"
+          COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
+          return 0
+          ;;
+        check)
+          opts="status"
+          COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
+          return 0
+          ;;
+      esac
+      ;;
+  esac
+}
+
+complete -F _ark_completion ark
+      `.trim());
+    });
+    completion
+        .command('zsh')
+        .description('Generate zsh completion script')
+        .action(() => {
+        console.log(`
+#compdef ark
+
+_ark() {
+  local context state line
+  
+  _arguments -C \\
+    '1:command:->command' \\
+    '2:subcommand:->subcommand' \\
+    '*::arg:->args'
+    
+  case $state in
+    command)
+      _values 'ark commands' \\
+        'cluster[Cluster management commands]' \\
+        'completion[Generate shell completion scripts]' \\
+        'check[Check system components]' \\
+        'help[Show help information]'
+      ;;
+    subcommand)
+      case $words[2] in
+        cluster)
+          _values 'cluster commands' \\
+            'get-ip[Get cluster IP address]' \\
+            'get-type[Get cluster type]'
+          ;;
+        completion)
+          _values 'completion shells' \\
+            'bash[Generate bash completion]' \\
+            'zsh[Generate zsh completion]'
+          ;;
+        check)
+          _values 'check commands' \\
+            'status[Check system status]'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_ark
+      `.trim());
+    });
+    return completion;
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Configuration management commands for ARK CLI
+ */
+import { Command } from 'commander';
+export declare function createConfigCommand(): Command;

package/dist/commands/config.js

@@ -0,0 +1,327 @@
+/**
+ * Configuration management commands for ARK CLI
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { ConfigManager } from '../lib/config.js';
+import { ErrorHandler } from '../lib/errors.js';
+import { OutputFormatter, EnhancedPrompts } from '../lib/progress.js';
+export function createConfigCommand() {
+    const config = new Command('config');
+    config
+        .description('Manage ARK CLI configuration')
+        .addHelpText('before', `
+${chalk.blue('⚙️  ARK Configuration Management')}
+Manage your ARK CLI preferences and defaults.
+`)
+        .addHelpText('after', `
+${chalk.cyan('Examples:')}
+  ${chalk.yellow('ark config list')}                    # Show current configuration
+  ${chalk.yellow('ark config set defaultProjectType with-samples')}
+  ${chalk.yellow('ark config get defaultProjectType')}  # Get specific value
+  ${chalk.yellow('ark config edit')}                    # Interactive configuration
+  ${chalk.yellow('ark config reset')}                   # Reset to defaults
+`);
+    // List command - show current configuration
+    const listCommand = new Command('list');
+    listCommand
+        .alias('ls')
+        .description('Show current configuration')
+        .option('--json', 'Output in JSON format', false)
+        .action((options) => {
+        ErrorHandler.catchAndHandle(async () => {
+            const configManager = new ConfigManager();
+            const currentConfig = configManager.getMergedConfig();
+            if (options.json) {
+                console.log(JSON.stringify(currentConfig, null, 2));
+                return;
+            }
+            console.log(chalk.blue('\n⚙️  ARK CLI Configuration\n'));
+            // Generator settings
+            console.log(chalk.cyan('🎯 Generator Defaults:'));
+            OutputFormatter.formatKeyValueList([
+                {
+                    key: 'Project Type',
+                    value: currentConfig.defaultProjectType,
+                    highlight: true,
+                },
+                {
+                    key: 'Default Destination',
+                    value: currentConfig.defaultDestination,
+                },
+                {
+                    key: 'Skip Git by Default',
+                    value: currentConfig.skipGitByDefault ? 'yes' : 'no',
+                },
+                {
+                    key: 'Skip Models by Default',
+                    value: currentConfig.skipModelsbyDefault ? 'yes' : 'no',
+                },
+                {
+                    key: 'Default Model Provider',
+                    value: currentConfig.defaultModelProvider,
+                },
+            ]);
+            // User preferences
+            console.log(chalk.cyan('\n👤 User Preferences:'));
+            OutputFormatter.formatKeyValueList([
+                { key: 'Preferred Editor', value: currentConfig.preferredEditor },
+                {
+                    key: 'Color Output',
+                    value: currentConfig.colorOutput ? 'enabled' : 'disabled',
+                },
+                {
+                    key: 'Verbose Output',
+                    value: currentConfig.verboseOutput ? 'enabled' : 'disabled',
+                },
+            ]);
+            // Advanced settings
+            console.log(chalk.cyan('\n🔧 Advanced Settings:'));
+            OutputFormatter.formatKeyValueList([
+                {
+                    key: 'Parallel Operations',
+                    value: currentConfig.parallelOperations ? 'enabled' : 'disabled',
+                },
+                {
+                    key: 'Max Concurrent Files',
+                    value: currentConfig.maxConcurrentFiles.toString(),
+                },
+                {
+                    key: 'File Watching',
+                    value: currentConfig.fileWatchingEnabled ? 'enabled' : 'disabled',
+                },
+                {
+                    key: 'Telemetry',
+                    value: currentConfig.telemetryEnabled ? 'enabled' : 'disabled',
+                },
+            ]);
+            console.log(chalk.gray(`\nConfig file: ${configManager.getConfigFilePath()}`));
+            console.log(chalk.gray('Use "ark config edit" for interactive configuration\n'));
+        }, 'Listing configuration').catch(ErrorHandler.handleAndExit);
+    });
+    // Get command - get a specific configuration value
+    const getCommand = new Command('get');
+    getCommand
+        .description('Get a specific configuration value')
+        .argument('<key>', 'Configuration key to retrieve')
+        .action((key) => {
+        ErrorHandler.catchAndHandle(async () => {
+            const configManager = new ConfigManager();
+            const currentConfig = configManager.getMergedConfig();
+            if (key in currentConfig) {
+                const value = currentConfig[key];
+                console.log(typeof value === 'object'
+                    ? JSON.stringify(value, null, 2)
+                    : String(value));
+            }
+            else {
+                console.error(chalk.red(`Unknown configuration key: ${key}`));
+                console.log(chalk.gray('Available keys:'));
+                Object.keys(currentConfig).forEach((k) => console.log(chalk.gray(`  ${k}`)));
+                process.exit(1);
+            }
+        }, 'Getting configuration value').catch(ErrorHandler.handleAndExit);
+    });
+    // Set command - set a specific configuration value
+    const setCommand = new Command('set');
+    setCommand
+        .description('Set a specific configuration value')
+        .argument('<key>', 'Configuration key to set')
+        .argument('<value>', 'Value to set')
+        .action((key, value) => {
+        ErrorHandler.catchAndHandle(async () => {
+            const configManager = new ConfigManager();
+            const currentConfig = configManager.getConfig();
+            if (!(key in currentConfig)) {
+                console.error(chalk.red(`Unknown configuration key: ${key}`));
+                console.log(chalk.gray('Available keys:'));
+                Object.keys(currentConfig).forEach((k) => console.log(chalk.gray(`  ${k}`)));
+                process.exit(1);
+            }
+            // Parse value based on the current type
+            const currentValue = currentConfig[key];
+            let parsedValue = value;
+            if (typeof currentValue === 'boolean') {
+                parsedValue = ['true', 'yes', '1', 'on'].includes(value.toLowerCase());
+            }
+            else if (typeof currentValue === 'number') {
+                parsedValue = parseInt(value, 10);
+                if (isNaN(parsedValue)) {
+                    console.error(chalk.red(`Invalid number value: ${value}`));
+                    process.exit(1);
+                }
+            }
+            // Update configuration
+            configManager.set(key, parsedValue);
+            // Validate the configuration
+            configManager.validateConfig();
+            console.log(chalk.green(`✅ Set ${key} = ${parsedValue}`));
+        }, 'Setting configuration value').catch(ErrorHandler.handleAndExit);
+    });
+    // Edit command - interactive configuration editor
+    const editCommand = new Command('edit');
+    editCommand.description('Edit configuration interactively').action(() => {
+        ErrorHandler.catchAndHandle(async () => {
+            const configManager = new ConfigManager();
+            const currentConfig = configManager.getConfig();
+            console.log(chalk.blue('\n⚙️  ARK CLI Configuration Editor\n'));
+            EnhancedPrompts.showInfo('Leave fields empty to keep current values');
+            const answers = await inquirer.prompt([
+                {
+                    type: 'list',
+                    name: 'defaultProjectType',
+                    message: 'Default project type:',
+                    choices: [
+                        {
+                            name: 'with-samples (recommended for beginners)',
+                            value: 'with-samples',
+                        },
+                        { name: 'empty (for experienced users)', value: 'empty' },
+                    ],
+                    default: currentConfig.defaultProjectType,
+                },
+                {
+                    type: 'input',
+                    name: 'defaultDestination',
+                    message: 'Default destination directory:',
+                    default: currentConfig.defaultDestination,
+                },
+                {
+                    type: 'list',
+                    name: 'defaultModelProvider',
+                    message: 'Default model provider:',
+                    choices: [
+                        { name: 'Azure OpenAI (recommended)', value: 'azure' },
+                        { name: 'OpenAI', value: 'openai' },
+                        { name: 'Claude (Anthropic)', value: 'claude' },
+                        { name: 'Gemini (Google)', value: 'gemini' },
+                        { name: 'Custom', value: 'custom' },
+                    ],
+                    default: currentConfig.defaultModelProvider,
+                },
+                {
+                    type: 'input',
+                    name: 'preferredEditor',
+                    message: 'Preferred editor command:',
+                    default: currentConfig.preferredEditor,
+                },
+                {
+                    type: 'confirm',
+                    name: 'skipGitByDefault',
+                    message: 'Skip git setup by default?',
+                    default: currentConfig.skipGitByDefault,
+                },
+                {
+                    type: 'confirm',
+                    name: 'skipModelsbyDefault',
+                    message: 'Skip model configuration by default?',
+                    default: currentConfig.skipModelsbyDefault,
+                },
+                {
+                    type: 'confirm',
+                    name: 'colorOutput',
+                    message: 'Enable colored output?',
+                    default: currentConfig.colorOutput,
+                },
+                {
+                    type: 'confirm',
+                    name: 'verboseOutput',
+                    message: 'Enable verbose output?',
+                    default: currentConfig.verboseOutput,
+                },
+                {
+                    type: 'number',
+                    name: 'maxConcurrentFiles',
+                    message: 'Maximum concurrent file operations:',
+                    default: currentConfig.maxConcurrentFiles,
+                    validate: (input) => input !== undefined && input >= 1 && input <= 100
+                        ? true
+                        : 'Must be between 1 and 100',
+                },
+            ]);
+            // Update configuration
+            configManager.updateConfig(answers);
+            // Validate the configuration
+            configManager.validateConfig();
+            EnhancedPrompts.showSuccess('Configuration updated successfully');
+            console.log(chalk.gray(`Config saved to: ${configManager.getConfigFilePath()}\n`));
+        }, 'Editing configuration').catch(ErrorHandler.handleAndExit);
+    });
+    // Reset command - reset to default configuration
+    const resetCommand = new Command('reset');
+    resetCommand
+        .description('Reset configuration to defaults')
+        .option('--confirm', 'Skip confirmation prompt', false)
+        .action((options) => {
+        ErrorHandler.catchAndHandle(async () => {
+            if (!options.confirm) {
+                const { confirmReset } = await inquirer.prompt([
+                    {
+                        type: 'confirm',
+                        name: 'confirmReset',
+                        message: 'Are you sure you want to reset all configuration to defaults?',
+                        default: false,
+                    },
+                ]);
+                if (!confirmReset) {
+                    console.log(chalk.yellow('Reset cancelled'));
+                    return;
+                }
+            }
+            const configManager = new ConfigManager();
+            configManager.resetConfig();
+            EnhancedPrompts.showSuccess('Configuration reset to defaults');
+            console.log(chalk.gray(`Config file: ${configManager.getConfigFilePath()}\n`));
+        }, 'Resetting configuration').catch(ErrorHandler.handleAndExit);
+    });
+    // Export command - export configuration for backup
+    const exportCommand = new Command('export');
+    exportCommand
+        .description('Export configuration to JSON')
+        .option('-o, --output <file>', 'Output file (default: stdout)')
+        .action((options) => {
+        ErrorHandler.catchAndHandle(async () => {
+            const configManager = new ConfigManager();
+            const configJson = configManager.exportConfig();
+            if (options.output) {
+                const fs = await import('fs');
+                fs.writeFileSync(options.output, configJson);
+                EnhancedPrompts.showSuccess(`Configuration exported to ${options.output}`);
+            }
+            else {
+                console.log(configJson);
+            }
+        }, 'Exporting configuration').catch(ErrorHandler.handleAndExit);
+    });
+    // Import command - import configuration from backup
+    const importCommand = new Command('import');
+    importCommand
+        .description('Import configuration from JSON file')
+        .argument('<file>', 'JSON file to import')
+        .option('--merge', 'Merge with existing configuration', false)
+        .action((file, options) => {
+        ErrorHandler.catchAndHandle(async () => {
+            const fs = await import('fs');
+            const configJson = fs.readFileSync(file, 'utf-8');
+            const configManager = new ConfigManager();
+            if (options.merge) {
+                const importedConfig = JSON.parse(configJson);
+                configManager.updateConfig(importedConfig);
+            }
+            else {
+                configManager.importConfig(configJson);
+            }
+            EnhancedPrompts.showSuccess(`Configuration imported from ${file}`);
+        }, 'Importing configuration').catch(ErrorHandler.handleAndExit);
+    });
+    // Add subcommands
+    config.addCommand(listCommand);
+    config.addCommand(getCommand);
+    config.addCommand(setCommand);
+    config.addCommand(editCommand);
+    config.addCommand(resetCommand);
+    config.addCommand(exportCommand);
+    config.addCommand(importCommand);
+    return config;
+}