@agents-at-scale/ark 0.1.31

package/dist/commands/generate/generators/marketplace.js

@@ -0,0 +1,304 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import path from 'path';
+import fs from 'fs';
+import { TemplateDiscovery } from '../templateDiscovery.js';
+import { TemplateEngine } from '../templateEngine.js';
+import { ArkError, ErrorCode } from '../../../lib/errors.js';
+export function createMarketplaceGenerator() {
+    const generator = new MarketplaceGenerator();
+    return {
+        name: 'marketplace',
+        description: 'Central repository for sharing reusable ARK components',
+        templatePath: 'marketplace',
+        generate: async (name, destination, options) => {
+            await generator.generate(name, destination, options);
+        },
+    };
+}
+class MarketplaceGenerator {
+    constructor() {
+        this.templateDiscovery = new TemplateDiscovery();
+        this.templateEngine = new TemplateEngine();
+    }
+    /**
+     * Get marketplace configuration from user input and validation
+     */
+    async getMarketplaceConfig(destination, options) {
+        // Always use "ark-marketplace" as the name
+        const normalizedName = 'ark-marketplace';
+        const targetDir = path.resolve(destination, normalizedName);
+        // Check if directory already exists
+        if (fs.existsSync(targetDir)) {
+            throw new ArkError(`Directory ${targetDir} already exists. Please choose a different name or location.`, ErrorCode.VALIDATION_ERROR);
+        }
+        const config = {
+            name: normalizedName,
+            destination: targetDir,
+            description: 'Ark marketplace for sharing ARK components',
+            initGit: true,
+        };
+        // Get current git configuration
+        const gitConfig = await this.getGitUserConfig();
+        // Use command line options if provided, otherwise use current git config, fallback to defaults
+        config.initGit = !options.skipGit;
+        config.gitUserName =
+            options.gitUserName || gitConfig.name || 'Marketplace Team';
+        config.gitUserEmail =
+            options.gitUserEmail || gitConfig.email || 'marketplace@example.com';
+        return config;
+    }
+    /**
+     * Get current git user configuration (secure implementation)
+     */
+    async getGitUserConfig() {
+        try {
+            const { execa } = await import('execa');
+            // Use secure PATH and argument arrays to prevent injection
+            const gitPath = process.env.GIT_PATH || '/usr/bin/git';
+            const secureEnv = {
+                PATH: '/usr/local/bin:/usr/bin:/bin',
+                ...process.env,
+            };
+            const nameResult = await execa(gitPath, ['config', 'user.name'], {
+                env: secureEnv,
+                stdio: 'pipe',
+                timeout: 5000, // 5 second timeout
+            });
+            const emailResult = await execa(gitPath, ['config', 'user.email'], {
+                env: secureEnv,
+                stdio: 'pipe',
+                timeout: 5000,
+            });
+            return {
+                name: nameResult.stdout.trim(),
+                email: emailResult.stdout.trim(),
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Get marketplace configuration with interactive prompts
+     */
+    async getInteractiveConfig(config) {
+        console.log(chalk.cyan('\n🏪 Marketplace Configuration\n'));
+        const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'destination',
+                message: 'Where would you like to create the marketplace?',
+                default: path.dirname(config.destination),
+                validate: (input) => {
+                    if (!input.trim()) {
+                        return 'Destination path is required';
+                    }
+                    return true;
+                },
+            },
+            {
+                type: 'confirm',
+                name: 'initGit',
+                message: `Initialize Git repository with ${config.gitUserName} <${config.gitUserEmail}>?`,
+                default: config.initGit,
+            },
+        ]);
+        // Update config with answers
+        const updatedConfig = {
+            ...config,
+            destination: path.resolve(answers.destination, config.name),
+            initGit: answers.initGit,
+        };
+        // Check if the updated destination already exists
+        if (fs.existsSync(updatedConfig.destination)) {
+            throw new ArkError(`Directory ${updatedConfig.destination} already exists. Please choose a different location.`, ErrorCode.VALIDATION_ERROR);
+        }
+        return updatedConfig;
+    }
+    /**
+     * Show configuration summary and ask for confirmation
+     */
+    async confirmGeneration(config) {
+        console.log(chalk.cyan('\n📋 Marketplace Generation Summary\n'));
+        console.log(`Name: ${chalk.green(config.name)}`);
+        console.log(`Description: ${config.description}`);
+        console.log(`Destination: ${chalk.yellow(config.destination)}`);
+        console.log(`Git Repository: ${config.initGit ? chalk.green('Yes') : 'No'}`);
+        if (config.initGit) {
+            console.log(`Git User: ${config.gitUserName} <${config.gitUserEmail}>`);
+        }
+        const confirm = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'proceed',
+                message: 'Create marketplace with this configuration?',
+                default: true,
+            },
+        ]);
+        if (!confirm.proceed) {
+            console.log(chalk.yellow('Marketplace generation cancelled.'));
+            process.exit(0);
+        }
+    }
+    /**
+     * Validate git configuration values to prevent injection
+     */
+    validateGitConfig(value, type) {
+        if (!value || typeof value !== 'string') {
+            throw new ArkError(`Invalid git ${type}: must be a non-empty string`, ErrorCode.VALIDATION_ERROR);
+        }
+        // Prevent command injection by checking for dangerous characters
+        const dangerousChars = /[\\`$;|&<>(){}[\]]/;
+        if (dangerousChars.test(value)) {
+            throw new ArkError(`Invalid git ${type}: contains dangerous characters`, ErrorCode.VALIDATION_ERROR, undefined, ['Remove special characters and shell metacharacters']);
+        }
+        // Additional validation for email format
+        if (type === 'email') {
+            const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+            if (!emailRegex.test(value)) {
+                throw new ArkError(`Invalid git email format: ${value}`, ErrorCode.VALIDATION_ERROR);
+            }
+        }
+        // Length validation
+        if (value.length > 100) {
+            throw new ArkError(`Git ${type} too long (max 100 characters)`, ErrorCode.VALIDATION_ERROR);
+        }
+    }
+    /**
+     * Setup git repository with initial commit (secure implementation)
+     */
+    async setupGit(config) {
+        try {
+            const { execa } = await import('execa');
+            // Use secure PATH and git path
+            const gitPath = process.env.GIT_PATH || '/usr/bin/git';
+            const secureEnv = {
+                PATH: '/usr/local/bin:/usr/bin:/bin',
+                ...process.env,
+            };
+            const execOptions = {
+                cwd: config.destination,
+                env: secureEnv,
+                stdio: 'pipe',
+                timeout: 10000, // 10 second timeout
+            };
+            // Initialize git repository
+            await execa(gitPath, ['init'], execOptions);
+            // Configure git user if provided (with validation)
+            if (config.gitUserName) {
+                this.validateGitConfig(config.gitUserName, 'name');
+                await execa(gitPath, ['config', 'user.name', config.gitUserName], execOptions);
+            }
+            if (config.gitUserEmail) {
+                this.validateGitConfig(config.gitUserEmail, 'email');
+                await execa(gitPath, ['config', 'user.email', config.gitUserEmail], execOptions);
+            }
+            // Add all files and create initial commit
+            await execa(gitPath, ['add', '.'], execOptions);
+            await execa(gitPath, ['commit', '-m', 'Initial marketplace structure'], execOptions);
+            console.log(chalk.green('✅ Git repository initialized'));
+        }
+        catch (error) {
+            console.warn(chalk.yellow('⚠️  Git initialization failed:'), error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * Generate marketplace structure
+     */
+    async generateMarketplace(config) {
+        console.log(chalk.cyan('\n🏗️  Creating marketplace structure...'));
+        // Set template variables
+        const variables = {
+            projectName: config.name,
+            description: config.description,
+            PROJECT_NAME: config.name,
+            authorName: config.gitUserName || 'Marketplace Team',
+            authorEmail: config.gitUserEmail || 'marketplace@example.com',
+        };
+        this.templateEngine.setVariables(variables);
+        // Get template path
+        const templatePath = this.templateDiscovery.getTemplatePath('marketplace');
+        // Verify template exists
+        if (!this.templateDiscovery.templateExists('marketplace')) {
+            throw new ArkError('Marketplace template not found. Please ensure the template is available in the templates directory.', ErrorCode.TEMPLATE_ERROR);
+        }
+        // Configure exclude patterns
+        const excludePatterns = ['.git', 'node_modules', '.DS_Store'];
+        // Process template
+        await this.templateEngine.processTemplate(templatePath, config.destination, {
+            createDirectories: true,
+            exclude: excludePatterns,
+        });
+        console.log(chalk.green('✅ Marketplace structure created'));
+    }
+    /**
+     * Show completion message with next steps
+     */
+    showCompletionMessage(config) {
+        const relativePath = path.relative(process.cwd(), config.destination);
+        const displayPath = relativePath || config.destination;
+        console.log(chalk.green('\n🎉 Marketplace created successfully!'));
+        console.log(chalk.cyan('\n📁 Location:'), displayPath);
+        console.log(chalk.cyan('📝 Description:'), config.description);
+        console.log(chalk.cyan('\n🚀 Next steps:'));
+        console.log('  1. ' + chalk.yellow('cd ' + displayPath));
+        console.log('  2. ' + chalk.yellow('# Create remote repository on GitHub/GitLab'));
+        console.log('  3. ' + chalk.yellow('git remote add origin <YOUR_REPO_URL>'));
+        console.log('  4. ' + chalk.yellow('git push -u origin main'));
+        console.log('  5. ' +
+            chalk.yellow('# Add your first component to the appropriate directory'));
+        console.log('  6. ' +
+            chalk.yellow('# Update the README.md with marketplace-specific information'));
+        console.log('  7. ' + chalk.yellow('# Set up CI/CD workflows in .github/workflows/'));
+        console.log('  8. ' +
+            chalk.yellow('# Configure contribution guidelines and review process'));
+        console.log(chalk.cyan('\n📂 Directory structure:'));
+        console.log('  • agents/         - Reusable agent definitions');
+        console.log('  • teams/          - Multi-agent workflow configurations');
+        console.log('  • models/         - Model configurations by provider');
+        console.log('  • queries/        - Query templates and patterns');
+        console.log('  • tools/          - Tool definitions and implementations');
+        console.log('  • mcp-servers/    - MCP server configurations');
+        console.log('  • projects/       - Complete Ark project templates and solutions');
+        console.log('  • docs/           - Documentation and guides');
+        console.log(chalk.cyan('\n💡 Tips:'));
+        console.log('  • Each .keep file contains guidelines for that directory');
+        console.log('  • Use the templates/ directory to create component templates');
+        console.log('  • Set up automated validation in CI/CD pipelines');
+        console.log('  • Encourage comprehensive documentation for all components');
+        if (config.initGit) {
+            console.log(chalk.cyan('\n🔗 Git repository:'));
+            console.log('  • Repository initialized with initial commit');
+            console.log('  • Ready to add remote origin and push to GitHub/GitLab');
+            console.log('  • Consider setting up branch protection rules');
+        }
+    }
+    /**
+     * Main generation method
+     */
+    async generate(_name, destination, options) {
+        try {
+            // Get initial configuration
+            let config = await this.getMarketplaceConfig(destination, options);
+            // Get interactive configuration (allows editing destination and git settings)
+            config = await this.getInteractiveConfig(config);
+            // Show summary and confirm
+            await this.confirmGeneration(config);
+            // Generate marketplace
+            await this.generateMarketplace(config);
+            // Setup git if requested
+            if (config.initGit) {
+                await this.setupGit(config);
+            }
+            // Show completion message
+            this.showCompletionMessage(config);
+        }
+        catch (error) {
+            if (error instanceof ArkError) {
+                throw error;
+            }
+            throw new ArkError(`Failed to generate marketplace: ${error instanceof Error ? error.message : String(error)}`, ErrorCode.UNKNOWN_ERROR);
+        }
+    }
+}

package/dist/commands/generate/generators/mcpserver.d.ts

@@ -0,0 +1,25 @@
+export interface McpServerConfig {
+    mcpServerName: string;
+    description: string;
+    technology: 'node' | 'deno' | 'go' | 'python';
+    packageSource: 'local' | 'npm' | 'jsr' | 'go-install' | 'pip';
+    packageName?: string;
+    destination: string;
+    requiresAuth: boolean;
+    hasCustomConfig: boolean;
+    maintainerName: string;
+    homeUrl?: string;
+    tools: Array<{
+        name: string;
+        description: string;
+    }>;
+    packageManager: string;
+    sourceUrls: string[];
+    sampleQuery: string;
+}
+export declare function createMcpServerGenerator(): {
+    name: string;
+    description: string;
+    templatePath: string;
+    generate: (name: string, destination: string, options: any) => Promise<void>;
+};

package/dist/commands/generate/generators/mcpserver.js

@@ -0,0 +1,350 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import path from 'path';
+import fs from 'fs';
+import { TemplateEngine } from '../templateEngine.js';
+import { TemplateDiscovery } from '../templateDiscovery.js';
+export function createMcpServerGenerator() {
+    return {
+        name: 'mcp-server',
+        description: 'Generate a new MCP server with Kubernetes deployment from template',
+        templatePath: 'templates/mcp-server',
+        generate: async (name, destination, options) => {
+            const generator = new McpServerGenerator();
+            await generator.generate(name, destination, options);
+        },
+    };
+}
+class McpServerGenerator {
+    constructor() {
+        this.templateDiscovery = new TemplateDiscovery();
+        this.templateEngine = new TemplateEngine();
+    }
+    async generate(name, destination, _options) {
+        console.log(chalk.blue('🚀 ARK MCP Server Generator\n'));
+        // Get MCP server configuration
+        const config = await this.getMcpServerConfig(name, destination);
+        // Show summary and confirm
+        await this.showSummaryAndConfirm(config);
+        // Generate the MCP server
+        await this.generateMcpServer(config);
+        // Show next steps
+        this.showNextSteps(config);
+    }
+    async getMcpServerConfig(name, destination) {
+        console.log(chalk.cyan('📋 MCP Server Configuration\n'));
+        // Determine if we're in a project context
+        const isInProject = this.isInProjectContext(destination);
+        const defaultDestination = isInProject
+            ? path.join(destination, 'mcp-servers', name)
+            : path.join(destination, name);
+        const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'mcpServerName',
+                message: 'MCP server name:',
+                default: name,
+                validate: (input) => {
+                    if (!/^[a-zA-Z0-9_-]+$/.test(input)) {
+                        return 'MCP server name can only contain letters, numbers, hyphens, and underscores';
+                    }
+                    return true;
+                },
+            },
+            {
+                type: 'input',
+                name: 'description',
+                message: 'MCP server description:',
+                default: `A custom MCP server named ${name} with Kubernetes deployment`,
+            },
+            {
+                type: 'list',
+                name: 'technology',
+                message: 'Choose the technology stack:',
+                choices: [
+                    { name: 'Node.js (JavaScript/TypeScript)', value: 'node' },
+                    { name: 'Deno (TypeScript)', value: 'deno' },
+                    { name: 'Go', value: 'go' },
+                    { name: 'Python', value: 'python' },
+                ],
+                default: 'node',
+            },
+            {
+                type: 'list',
+                name: 'packageSource',
+                message: 'Package source:',
+                choices: (answers) => {
+                    switch (answers.technology) {
+                        case 'node':
+                            return [
+                                {
+                                    name: 'Local development (custom implementation)',
+                                    value: 'local',
+                                },
+                                { name: 'NPM package', value: 'npm' },
+                            ];
+                        case 'deno':
+                            return [
+                                {
+                                    name: 'Local development (custom implementation)',
+                                    value: 'local',
+                                },
+                                { name: 'JSR package', value: 'jsr' },
+                            ];
+                        case 'go':
+                            return [
+                                {
+                                    name: 'Local development (custom implementation)',
+                                    value: 'local',
+                                },
+                                { name: 'Go install package', value: 'go-install' },
+                            ];
+                        case 'python':
+                            return [
+                                {
+                                    name: 'Local development (custom implementation)',
+                                    value: 'local',
+                                },
+                                { name: 'Pip package', value: 'pip' },
+                            ];
+                        default:
+                            return [{ name: 'Local development', value: 'local' }];
+                    }
+                },
+                default: 'local',
+            },
+            {
+                type: 'input',
+                name: 'packageName',
+                message: 'Package name (if using external package):',
+                when: (answers) => answers.packageSource !== 'local',
+                validate: (input, answers) => {
+                    if (answers.packageSource !== 'local' && !input.trim()) {
+                        return 'Package name is required when using external packages';
+                    }
+                    return true;
+                },
+            },
+            {
+                type: 'input',
+                name: 'destination',
+                message: 'Destination directory:',
+                default: defaultDestination,
+            },
+            {
+                type: 'confirm',
+                name: 'requiresAuth',
+                message: 'Does this MCP server require authentication?',
+                default: false,
+            },
+            {
+                type: 'confirm',
+                name: 'hasCustomConfig',
+                message: 'Does this MCP server need custom configuration?',
+                default: false,
+            },
+            {
+                type: 'input',
+                name: 'maintainerName',
+                message: 'Maintainer name:',
+                default: 'QBAF Team',
+            },
+            {
+                type: 'input',
+                name: 'homeUrl',
+                message: 'Home URL (optional):',
+                default: '',
+            },
+        ]);
+        // Get tool definitions
+        const tools = await this.getToolDefinitions();
+        // Check if destination exists
+        if (fs.existsSync(answers.destination)) {
+            const overwrite = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'overwrite',
+                    message: `Directory ${answers.destination} already exists. Overwrite?`,
+                    default: false,
+                },
+            ]);
+            if (!overwrite.overwrite) {
+                console.log(chalk.yellow('Operation cancelled.'));
+                process.exit(0);
+            }
+        }
+        return {
+            ...answers,
+            tools,
+            packageManager: this.getPackageManager(answers.technology),
+            sourceUrls: answers.homeUrl ? [answers.homeUrl] : [],
+            sampleQuery: this.generateSampleQuery(tools),
+        };
+    }
+    async getToolDefinitions() {
+        console.log(chalk.cyan('\n🔧 Tool Definitions\n'));
+        console.log('Define the tools this MCP server will provide:');
+        const tools = [];
+        const addMore = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'addTools',
+                message: 'Add tool definitions?',
+                default: true,
+            },
+        ]);
+        if (addMore.addTools) {
+            let addingTools = true;
+            while (addingTools) {
+                const toolInfo = await inquirer.prompt([
+                    {
+                        type: 'input',
+                        name: 'name',
+                        message: 'Tool name:',
+                        validate: (input) => {
+                            if (!input.trim()) {
+                                return 'Tool name is required';
+                            }
+                            return true;
+                        },
+                    },
+                    {
+                        type: 'input',
+                        name: 'description',
+                        message: 'Tool description:',
+                        validate: (input) => {
+                            if (!input.trim()) {
+                                return 'Tool description is required';
+                            }
+                            return true;
+                        },
+                    },
+                ]);
+                tools.push(toolInfo);
+                const continueAdding = await inquirer.prompt([
+                    {
+                        type: 'confirm',
+                        name: 'continue',
+                        message: 'Add another tool?',
+                        default: false,
+                    },
+                ]);
+                addingTools = continueAdding.continue;
+            }
+        }
+        // Add default tool if none were added
+        if (tools.length === 0) {
+            tools.push({
+                name: 'example_tool',
+                description: 'An example tool provided by this MCP server',
+            });
+        }
+        return tools;
+    }
+    getPackageManager(technology) {
+        switch (technology) {
+            case 'node':
+                return 'npm';
+            case 'deno':
+                return 'deno';
+            case 'python':
+                return 'pip';
+            case 'go':
+                return 'go';
+            default:
+                return 'npm';
+        }
+    }
+    generateSampleQuery(tools) {
+        if (tools.length === 0)
+            return 'Test the MCP server functionality.';
+        const toolNames = tools.map((t) => t.name).join(', ');
+        return `Test the MCP server by using the available tools: ${toolNames}. Please demonstrate how each tool works.`;
+    }
+    isInProjectContext(destination) {
+        // Check if we're in an ARK project by looking for common project files
+        const projectMarkers = [
+            'Makefile',
+            'Chart.yaml',
+            'agents/',
+            'models/',
+            'mcp-servers/',
+        ];
+        return projectMarkers.some((marker) => fs.existsSync(path.join(destination, marker)));
+    }
+    async showSummaryAndConfirm(config) {
+        console.log(chalk.cyan('\n📋 Configuration Summary\n'));
+        console.log(`MCP Server Name: ${chalk.green(config.mcpServerName)}`);
+        console.log(`Description: ${config.description}`);
+        console.log(`Technology: ${chalk.blue(config.technology)}`);
+        console.log(`Package Source: ${config.packageSource}`);
+        if (config.packageName) {
+            console.log(`Package Name: ${config.packageName}`);
+        }
+        console.log(`Destination: ${config.destination}`);
+        console.log(`Authentication: ${config.requiresAuth ? chalk.red('Required') : chalk.green('Not required')}`);
+        console.log(`Custom Config: ${config.hasCustomConfig ? chalk.yellow('Yes') : 'No'}`);
+        console.log(`Tools: ${config.tools.map((t) => t.name).join(', ')}`);
+        const confirm = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'proceed',
+                message: 'Generate MCP server with this configuration?',
+                default: true,
+            },
+        ]);
+        if (!confirm.proceed) {
+            console.log(chalk.yellow('Operation cancelled.'));
+            process.exit(0);
+        }
+    }
+    async generateMcpServer(config) {
+        console.log(chalk.blue('\n🚀 Generating MCP Server...\n'));
+        try {
+            const templatePath = this.templateDiscovery.getTemplatePath('mcp-server');
+            if (!templatePath) {
+                throw new Error('MCP server template not found');
+            }
+            // Generate from template
+            // Set template variables using the same structure expected by templates
+            this.templateEngine.setVariables(config);
+            await this.templateEngine.processTemplate(templatePath, config.destination);
+            // Make build script executable (owner only for security)
+            const buildScriptPath = path.join(config.destination, 'build.sh');
+            if (fs.existsSync(buildScriptPath)) {
+                fs.chmodSync(buildScriptPath, '700'); // rwx------ (owner only)
+            }
+            console.log(chalk.green(`✅ MCP server generated successfully at ${config.destination}`));
+        }
+        catch (error) {
+            console.error(chalk.red('Failed to generate MCP server:'), error.message);
+            process.exit(1);
+        }
+    }
+    showNextSteps(config) {
+        console.log(chalk.cyan('\n🎯 Next Steps:\n'));
+        console.log(`1. Navigate to your MCP server directory:`);
+        console.log(chalk.yellow(`   cd ${config.destination}`));
+        console.log(``);
+        console.log(`2. Build the Docker image:`);
+        console.log(chalk.yellow(`   make build`));
+        console.log(``);
+        console.log(`3. Install to Kubernetes:`);
+        if (config.requiresAuth) {
+            console.log(chalk.yellow(`   make install AUTH_TOKEN=your-auth-token`));
+        }
+        else {
+            console.log(chalk.yellow(`   make install`));
+        }
+        console.log(``);
+        console.log(`4. Check deployment status:`);
+        console.log(chalk.yellow(`   make status`));
+        console.log(``);
+        console.log(`5. Deploy example agent and query:`);
+        console.log(chalk.yellow(`   make deploy-examples`));
+        console.log(``);
+        console.log(chalk.green('🎉 Your MCP server is ready to use!'));
+        console.log(``);
+        console.log('For more information, see the README.md file in your server directory.');
+    }
+}

package/dist/commands/generate/generators/project.d.ts

@@ -0,0 +1,2 @@
+import { Generator } from '../index.js';
+export declare function createProjectGenerator(): Generator;