@agents-at-scale/ark 0.1.31

package/dist/commands/generate/templateEngine.js

@@ -0,0 +1,368 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { SecurityUtils } from '../../lib/security.js';
+import { TemplateError } from '../../lib/errors.js';
+export class TemplateEngine {
+    constructor() {
+        this.variables = {};
+    }
+    /**
+     * Set template variables for substitution
+     */
+    setVariables(variables) {
+        this.variables = { ...this.variables, ...variables };
+    }
+    /**
+     * Get current template variables
+     */
+    getVariables() {
+        return { ...this.variables };
+    }
+    /**
+     * Process a template directory and copy it to destination
+     */
+    async processTemplate(templatePath, destinationPath, options = {}) {
+        const { skipIfExists = false, createDirectories = true, exclude = ['.git', 'node_modules', '.DS_Store'], include = [], } = options;
+        // Validate paths for security
+        SecurityUtils.validatePath(templatePath, 'template path');
+        SecurityUtils.validatePath(destinationPath, 'destination path');
+        if (!fs.existsSync(templatePath)) {
+            throw new TemplateError(`Template path does not exist: ${templatePath}`, templatePath, [
+                'Check that the template directory exists',
+                'Verify the template path is correct',
+                'Ensure templates are properly installed',
+            ]);
+        }
+        if (createDirectories) {
+            await this.ensureDirectorySafe(destinationPath, destinationPath);
+        }
+        await this.copyDirectory(templatePath, destinationPath, {
+            skipIfExists,
+            exclude,
+            include,
+            baseDir: destinationPath,
+        });
+    }
+    /**
+     * Process a single template file
+     */
+    async processFile(templateFilePath, destinationFilePath, options = {}) {
+        const { skipIfExists = false, baseDir = process.cwd() } = options;
+        // Validate paths for security
+        SecurityUtils.validatePath(templateFilePath, 'template file path');
+        SecurityUtils.validatePath(destinationFilePath, 'destination file path');
+        SecurityUtils.validateOutputPath(destinationFilePath, baseDir);
+        if (skipIfExists && fs.existsSync(destinationFilePath)) {
+            console.log(chalk.yellow(`⏭️  Skipping existing file: ${destinationFilePath}`));
+            return;
+        }
+        let templateContent;
+        try {
+            templateContent = fs.readFileSync(templateFilePath, 'utf-8');
+        }
+        catch (error) {
+            throw new TemplateError(`Failed to read template file: ${templateFilePath}. ${error instanceof Error ? error.message : String(error)}`, templateFilePath, [
+                'Check that the template file exists',
+                'Verify file permissions',
+                'Ensure the template path is correct',
+            ]);
+        }
+        // Validate template content for security
+        SecurityUtils.validateTemplateContent(templateContent, templateFilePath);
+        const processedContent = this.substituteVariables(templateContent);
+        // Ensure destination directory exists
+        const destinationDir = path.dirname(destinationFilePath);
+        await this.ensureDirectorySafe(destinationDir, baseDir);
+        // Write file securely
+        await SecurityUtils.writeFileSafe(destinationFilePath, processedContent, baseDir);
+        // Show important generated content with relative paths
+        if (this.isImportantContent(destinationFilePath)) {
+            const relativePath = this.getRelativePath(destinationFilePath);
+            console.log(chalk.green(`📝 ${relativePath}`));
+        }
+    }
+    /**
+     * Substitute template variables in content
+     */
+    substituteVariables(content) {
+        let result = content;
+        // Replace template variables in Golang template format {{ .Values.variableName }}
+        for (const [key, value] of Object.entries(this.variables)) {
+            // Escape regex metacharacters in key to prevent ReDoS attacks
+            const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const regex = new RegExp(`{{\\s*\\.Values\\.${escapedKey}\\s*}}`, 'g');
+            result = result.replace(regex, String(value));
+        }
+        return result;
+    }
+    /**
+     * Substitute variables in file/directory names
+     */
+    substituteVariablesInPath(pathStr) {
+        let result = pathStr;
+        // Handle new .template.yaml naming convention
+        if (pathStr.endsWith('.template.yaml')) {
+            const templateName = path.basename(pathStr, '.template.yaml');
+            result = this.deriveDestinationFilename(templateName);
+        }
+        else {
+            // Use Golang template variable substitution for other files
+            for (const [key, value] of Object.entries(this.variables)) {
+                const regex = new RegExp(`{{\\s*\\.Values\\.${key}\\s*}}`, 'g');
+                result = result.replace(regex, String(value));
+            }
+        }
+        return result;
+    }
+    /**
+     * Derive destination filename from template name
+     */
+    deriveDestinationFilename(templateName) {
+        switch (templateName) {
+            case 'agent':
+                return `${this.variables.agentName || 'unnamed'}-agent.yaml`;
+            case 'team':
+                return `${this.variables.teamName || 'unnamed'}-team.yaml`;
+            case 'query':
+                return `${this.variables.queryName || 'unnamed'}-query.yaml`;
+            default: {
+                // For unknown template types, use the template name as-is with variables
+                let result = `${templateName}.yaml`;
+                for (const [key, value] of Object.entries(this.variables)) {
+                    const regex = new RegExp(`{{\\s*\\.Values\\.${key}\\s*}}`, 'g');
+                    result = result.replace(regex, String(value));
+                }
+                return result;
+            }
+        }
+    }
+    /**
+     * Copy directory recursively with template processing
+     */
+    async copyDirectory(sourcePath, destinationPath, options) {
+        const { baseDir = destinationPath } = options;
+        const entries = fs.readdirSync(sourcePath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!this.shouldProcessEntry(entry.name, options)) {
+                continue;
+            }
+            const sourceEntry = path.join(sourcePath, entry.name);
+            const destinationName = this.substituteVariablesInPath(entry.name);
+            const destinationEntry = path.join(destinationPath, destinationName);
+            if (entry.isDirectory()) {
+                await this.processDirectory(sourceEntry, destinationEntry, options, baseDir);
+            }
+            else {
+                await this.processFileEntry(sourceEntry, destinationEntry, destinationName, options, baseDir);
+            }
+        }
+    }
+    shouldProcessEntry(entryName, options) {
+        if (this.shouldExclude(entryName, options.exclude || [])) {
+            return false;
+        }
+        if (options.include &&
+            options.include.length > 0 &&
+            !this.shouldInclude(entryName, options.include)) {
+            return false;
+        }
+        return true;
+    }
+    async processDirectory(sourceEntry, destinationEntry, options, baseDir) {
+        await this.ensureDirectorySafe(destinationEntry, baseDir);
+        await this.copyDirectory(sourceEntry, destinationEntry, {
+            ...options,
+            baseDir,
+        });
+    }
+    async processFileEntry(sourceEntry, destinationEntry, destinationName, options, baseDir) {
+        const sanitizedName = SecurityUtils.sanitizeFileName(destinationName);
+        if (sanitizedName !== destinationName) {
+            console.warn(chalk.yellow(`⚠️  File name sanitized: "${destinationName}" → "${sanitizedName}"`));
+            return;
+        }
+        if (this.isTextFile(sourceEntry)) {
+            await this.processFile(sourceEntry, destinationEntry, {
+                skipIfExists: options.skipIfExists,
+                baseDir,
+            });
+        }
+        else if (options.skipIfExists && fs.existsSync(destinationEntry)) {
+            console.log(chalk.yellow(`⏭️  Skipping existing file: ${destinationEntry}`));
+        }
+        else {
+            SecurityUtils.validateOutputPath(destinationEntry, baseDir);
+            fs.copyFileSync(sourceEntry, destinationEntry);
+            if (this.isImportantContent(destinationEntry)) {
+                const relativePath = this.getRelativePath(destinationEntry);
+                console.log(chalk.green(`📋 ${relativePath}`));
+            }
+        }
+    }
+    /**
+     * Ensure a directory exists, creating it if necessary
+     */
+    async ensureDirectory(dirPath) {
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+        }
+    }
+    /**
+     * Safely ensure a directory exists with security validation
+     */
+    async ensureDirectorySafe(dirPath, baseDir) {
+        SecurityUtils.validateOutputPath(dirPath, baseDir);
+        if (!fs.existsSync(dirPath)) {
+            await SecurityUtils.createDirectorySafe(dirPath, baseDir);
+        }
+    }
+    /**
+     * Check if a file should be excluded
+     */
+    shouldExclude(fileName, excludePatterns) {
+        return excludePatterns.some((pattern) => {
+            if (pattern.includes('*')) {
+                // Safe glob pattern matching - escape regex metacharacters except *
+                const escapedPattern = pattern
+                    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                    .replace(/\\\*/g, '.*');
+                const regex = new RegExp(escapedPattern);
+                return regex.test(fileName);
+            }
+            return fileName === pattern;
+        });
+    }
+    /**
+     * Check if a file should be included
+     */
+    shouldInclude(fileName, includePatterns) {
+        return includePatterns.some((pattern) => {
+            if (pattern.includes('*')) {
+                // Safe glob pattern matching - escape regex metacharacters except *
+                const escapedPattern = pattern
+                    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+                    .replace(/\\\*/g, '.*');
+                const regex = new RegExp(escapedPattern);
+                return regex.test(fileName);
+            }
+            return fileName === pattern;
+        });
+    }
+    /**
+     * Check if a file is a text file that should have variable substitution
+     */
+    isTextFile(filePath) {
+        const textExtensions = [
+            '.txt',
+            '.md',
+            '.yaml',
+            '.yml',
+            '.json',
+            '.js',
+            '.ts',
+            '.jsx',
+            '.tsx',
+            '.py',
+            '.go',
+            '.rs',
+            '.java',
+            '.cs',
+            '.php',
+            '.rb',
+            '.sh',
+            '.bash',
+            '.zsh',
+            '.fish',
+            '.ps1',
+            '.bat',
+            '.cmd',
+            '.dockerfile',
+            '.docker',
+            '.makefile',
+            '.mk',
+            '.toml',
+            '.ini',
+            '.cfg',
+            '.conf',
+            '.properties',
+            '.xml',
+            '.html',
+            '.htm',
+            '.css',
+            '.scss',
+            '.sass',
+            '.less',
+            '.vue',
+            '.svelte',
+            '.sql',
+            '.r',
+            '.R',
+            '.swift',
+            '.kt',
+            '.scala',
+            '.clj',
+            '.hs',
+            '.elm',
+            '.ex',
+            '.exs',
+            '.erl',
+            '.pl',
+            '.pm',
+            '.raku',
+            '.lua',
+        ];
+        const extension = path.extname(filePath).toLowerCase();
+        if (textExtensions.includes(extension)) {
+            return true;
+        }
+        // Check for files without extensions that are commonly text
+        const basename = path.basename(filePath).toLowerCase();
+        const textBasenames = [
+            'readme',
+            'license',
+            'changelog',
+            'makefile',
+            'dockerfile',
+            'gitignore',
+            'gitattributes',
+            'editorconfig',
+            'eslintrc',
+            'prettierrc',
+        ];
+        return textBasenames.some((name) => basename.includes(name));
+    }
+    /**
+     * Check if a file path represents important generated content
+     */
+    isImportantContent(filePath) {
+        const normalizedPath = path.normalize(filePath);
+        // Show files in important directories (agents, teams, queries, models)
+        const importantDirs = ['agents', 'teams', 'queries', 'models'];
+        const hasImportantDir = importantDirs.some((dir) => normalizedPath.includes(`${path.sep}${dir}${path.sep}`) ||
+            normalizedPath.includes(`/${dir}/`));
+        if (hasImportantDir) {
+            // Skip .keep files
+            return !path.basename(filePath).includes('.keep');
+        }
+        return false;
+    }
+    /**
+     * Get relative path from a full file path for display
+     */
+    getRelativePath(filePath) {
+        const normalizedPath = path.normalize(filePath);
+        // Find the project root by looking for common patterns
+        const pathParts = normalizedPath.split(path.sep);
+        // Look for agents, teams, queries, or models directory
+        const importantDirs = ['agents', 'teams', 'queries', 'models'];
+        for (let i = pathParts.length - 1; i >= 0; i--) {
+            if (importantDirs.includes(pathParts[i])) {
+                // Return from this directory onwards
+                return pathParts.slice(i).join('/');
+            }
+        }
+        // Fallback to just filename
+        return path.basename(filePath);
+    }
+}

package/dist/commands/generate/utils/nameUtils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Utilities for name validation and normalization
+ */
+/**
+ * Convert a string to lowercase kebab-case
+ * Examples:
+ * - "My Project" -> "my-project"
+ * - "MyProject" -> "my-project"
+ * - "my_project" -> "my-project"
+ * - "myProject123" -> "my-project123"
+ */
+export declare function toKebabCase(str: string): string;
+/**
+ * Validate that a name follows kebab-case format
+ */
+export declare function isValidKebabCase(str: string): boolean;
+/**
+ * Validate that a name is suitable for Kubernetes resources
+ */
+export declare function isValidKubernetesName(str: string): boolean;
+/**
+ * Get validation error message for invalid names
+ */
+export declare function getNameValidationError(name: string): string | null;
+/**
+ * Strict name validation that throws ValidationError with suggestions
+ */
+export declare function validateNameStrict(name: string, type?: string): void;
+/**
+ * Normalize and validate a name for use in generators
+ */
+export declare function normalizeAndValidateName(input: string, type?: string): {
+    name: string;
+    wasTransformed: boolean;
+};

package/dist/commands/generate/utils/nameUtils.js

@@ -0,0 +1,110 @@
+/**
+ * Utilities for name validation and normalization
+ */
+import { ValidationError } from '../../../lib/errors.js';
+/**
+ * Convert a string to lowercase kebab-case
+ * Examples:
+ * - "My Project" -> "my-project"
+ * - "MyProject" -> "my-project"
+ * - "my_project" -> "my-project"
+ * - "myProject123" -> "my-project123"
+ */
+export function toKebabCase(str) {
+    if (str.length > 1000) {
+        throw new Error('Input string too long for processing');
+    }
+    let result = str
+        .trim()
+        // Replace spaces and underscores with hyphens
+        .replace(/[\s_]+/g, '-')
+        // Insert hyphens before uppercase letters (camelCase -> kebab-case)
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        // Convert to lowercase
+        .toLowerCase()
+        // Remove any double hyphens
+        .replace(/-+/g, '-');
+    // Remove leading/trailing hyphens using string methods to avoid regex backtracking
+    while (result.startsWith('-')) {
+        result = result.slice(1);
+    }
+    while (result.endsWith('-')) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+/**
+ * Validate that a name follows kebab-case format
+ */
+export function isValidKebabCase(str) {
+    // Must be lowercase, can contain letters, numbers, and hyphens
+    // Cannot start or end with hyphen, cannot have consecutive hyphens
+    const kebabRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+    return kebabRegex.test(str);
+}
+/**
+ * Validate that a name is suitable for Kubernetes resources
+ */
+export function isValidKubernetesName(str) {
+    // Kubernetes names must be lowercase alphanumeric or '-'
+    // Must start and end with alphanumeric character
+    // Max length 63 characters
+    return (isValidKebabCase(str) &&
+        str.length <= 63 &&
+        str.length >= 1 &&
+        /^[a-z0-9]/.test(str) &&
+        /[a-z0-9]$/.test(str));
+}
+/**
+ * Get validation error message for invalid names
+ */
+export function getNameValidationError(name) {
+    try {
+        validateNameStrict(name);
+        return null;
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            return error.message;
+        }
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+/**
+ * Strict name validation that throws ValidationError with suggestions
+ */
+export function validateNameStrict(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`]);
+    }
+    if (!isValidKubernetesName(trimmed)) {
+        const suggested = toKebabCase(trimmed);
+        const suggestions = [];
+        if (suggested !== trimmed && isValidKubernetesName(suggested)) {
+            suggestions.push(`Try: "${suggested}"`);
+        }
+        suggestions.push(`${type} must be lowercase letters, numbers, and hyphens only`);
+        suggestions.push(`${type} cannot start or end with a hyphen`);
+        suggestions.push(`${type} cannot contain consecutive hyphens`);
+        throw new ValidationError(`Invalid ${type}: "${trimmed}"`, 'name', suggestions);
+    }
+}
+/**
+ * Normalize and validate a name for use in generators
+ */
+export function normalizeAndValidateName(input, type = 'name') {
+    const original = input.trim();
+    const normalized = toKebabCase(original);
+    // Validate the normalized name
+    validateNameStrict(normalized, type);
+    return {
+        name: normalized,
+        wasTransformed: normalized !== original,
+    };
+}

package/dist/commands/generate/utils/projectUtils.d.ts

@@ -0,0 +1,28 @@
+export interface ProjectValidationResult {
+    isValid: boolean;
+    projectName?: string;
+    error?: string;
+}
+/**
+ * Validate if the given directory is a valid ARK project
+ */
+export declare function validateProjectStructure(projectDir: string): ProjectValidationResult;
+/**
+ * Validate project structure and throw detailed error if invalid
+ */
+export declare function validateProjectStructureStrict(projectDir: string): string;
+/**
+ * Get the current project directory (current working directory)
+ */
+export declare function getCurrentProjectDirectory(): string;
+/**
+ * Check if the current directory is a valid ARK project
+ */
+export declare function validateCurrentProject(): ProjectValidationResult;
+/**
+ * Get current project info with strict validation
+ */
+export declare function getCurrentProjectInfo(): {
+    projectName: string;
+    projectDir: string;
+};

package/dist/commands/generate/utils/projectUtils.js

@@ -0,0 +1,133 @@
+import fs from 'fs';
+import path from 'path';
+import { ProjectStructureError } from '../../../lib/errors.js';
+/**
+ * Validate if the given directory is a valid ARK project
+ */
+export function validateProjectStructure(projectDir) {
+    // Check for required project files
+    const chartYamlPath = path.join(projectDir, 'Chart.yaml');
+    const agentsDir = path.join(projectDir, 'agents');
+    if (!fs.existsSync(chartYamlPath)) {
+        return {
+            isValid: false,
+            error: 'Chart.yaml not found. This does not appear to be a valid ARK project directory.',
+        };
+    }
+    if (!fs.existsSync(agentsDir)) {
+        return {
+            isValid: false,
+            error: 'agents/ directory not found. This does not appear to be a valid ARK project directory.',
+        };
+    }
+    // Try to extract project name from Chart.yaml
+    try {
+        const chartContent = fs.readFileSync(chartYamlPath, 'utf-8');
+        const nameMatch = /^name:\s*([a-zA-Z0-9\s._-]{1,200}?)$/m.exec(chartContent);
+        if (nameMatch) {
+            return {
+                isValid: true,
+                projectName: nameMatch[1].trim(),
+            };
+        }
+    }
+    catch (error) {
+        return {
+            isValid: false,
+            error: `Failed to read Chart.yaml: ${error}`,
+        };
+    }
+    return {
+        isValid: true,
+    };
+}
+/**
+ * Check file/directory validation
+ */
+function validateRequiredPath(projectDir, required, missing, wrongType) {
+    const fullPath = path.join(projectDir, required.path);
+    if (!fs.existsSync(fullPath)) {
+        missing.push(required.path);
+        return;
+    }
+    const stat = fs.statSync(fullPath);
+    if (required.type === 'file' && !stat.isFile()) {
+        wrongType.push(`${required.path} (expected file, found directory)`);
+    }
+    else if (required.type === 'directory' && !stat.isDirectory()) {
+        wrongType.push(`${required.path} (expected directory, found file)`);
+    }
+}
+/**
+ * Extract project name from Chart.yaml
+ */
+function extractProjectName(projectDir) {
+    const chartYamlPath = path.join(projectDir, 'Chart.yaml');
+    const chartContent = fs.readFileSync(chartYamlPath, 'utf-8');
+    const nameMatch = /^name:\s*([a-zA-Z0-9\s._-]{1,200}?)$/m.exec(chartContent);
+    if (nameMatch) {
+        return nameMatch[1].trim();
+    }
+    throw new Error('No name field found in Chart.yaml');
+}
+/**
+ * Validate project structure and throw detailed error if invalid
+ */
+export function validateProjectStructureStrict(projectDir) {
+    const requiredFiles = [
+        { path: 'Chart.yaml', type: 'file' },
+        { path: 'agents', type: 'directory' },
+        { path: 'teams', type: 'directory' },
+        { path: 'queries', type: 'directory' },
+        { path: 'models', type: 'directory' },
+    ];
+    const missing = [];
+    const wrongType = [];
+    for (const required of requiredFiles) {
+        validateRequiredPath(projectDir, required, missing, wrongType);
+    }
+    if (missing.length > 0 || wrongType.length > 0) {
+        const issues = [];
+        if (missing.length > 0) {
+            issues.push(`Missing: ${missing.join(', ')}`);
+        }
+        if (wrongType.length > 0) {
+            issues.push(`Wrong type: ${wrongType.join(', ')}`);
+        }
+        throw new ProjectStructureError(`Invalid ARK project structure: ${issues.join('; ')}`, projectDir, [
+            'Ensure you are in a valid ARK project directory',
+            'Run "ark generate project" to create a new project',
+            'Check that all required files and directories exist',
+        ]);
+    }
+    try {
+        return extractProjectName(projectDir);
+    }
+    catch (error) {
+        throw new ProjectStructureError(`Failed to read project name from Chart.yaml: ${error instanceof Error ? error.message : String(error)}`, projectDir, [
+            'Ensure Chart.yaml exists and is readable',
+            'Check that Chart.yaml contains a valid name field',
+            'Verify file permissions',
+        ]);
+    }
+}
+/**
+ * Get the current project directory (current working directory)
+ */
+export function getCurrentProjectDirectory() {
+    return process.cwd();
+}
+/**
+ * Check if the current directory is a valid ARK project
+ */
+export function validateCurrentProject() {
+    return validateProjectStructure(getCurrentProjectDirectory());
+}
+/**
+ * Get current project info with strict validation
+ */
+export function getCurrentProjectInfo() {
+    const projectDir = getCurrentProjectDirectory();
+    const projectName = validateProjectStructureStrict(projectDir);
+    return { projectName, projectDir };
+}

package/dist/components/DashboardCLI.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+declare const DashboardCLI: () => import("react/jsx-runtime").JSX.Element;
+export default DashboardCLI;