@ginkoai/cli 1.0.0

package/dist/core/validators/command-argument-validator.js

@@ -0,0 +1,377 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-09-22
+ * @tags: [validation, command-arguments, cli, middleware, security]
+ * @related: [input-validator.ts, command-validator.ts, index.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: [commander]
+ */
+import { Command } from 'commander';
+import { InputValidator } from './input-validator.js';
+/**
+ * Command argument validator that provides type-safe validation for CLI commands
+ * Integrates with Commander.js to provide comprehensive argument validation
+ */
+export class CommandArgumentValidator {
+    inputValidator;
+    lastError;
+    lastSuggestions = [];
+    commandConfigs = new Map();
+    constructor() {
+        this.inputValidator = new InputValidator();
+        this.registerBuiltinCommands();
+    }
+    /**
+     * Register a command configuration for validation
+     */
+    registerCommand(config) {
+        this.commandConfigs.set(config.name, config);
+    }
+    /**
+     * Validate command arguments and options
+     */
+    async validateCommand(commandName, args, options) {
+        const config = this.commandConfigs.get(commandName);
+        if (!config) {
+            return {
+                command: commandName,
+                arguments: {},
+                options,
+                rawArgs: args,
+                valid: false,
+                errors: [`Unknown command: ${commandName}`],
+                suggestions: ['Run "ginko --help" to see available commands']
+            };
+        }
+        const validationResult = {
+            command: commandName,
+            arguments: {},
+            options: {},
+            rawArgs: args,
+            valid: true,
+            errors: [],
+            suggestions: []
+        };
+        // Validate arguments
+        if (config.arguments) {
+            const argValidation = await this.validateArguments(args, config.arguments);
+            if (!argValidation.valid) {
+                validationResult.valid = false;
+                if (argValidation.errors) {
+                    const errorMessages = argValidation.errors.map(e => e.message);
+                    validationResult.errors?.push(...errorMessages);
+                }
+                if (argValidation.suggestions) {
+                    validationResult.suggestions?.push(...argValidation.suggestions);
+                }
+            }
+            else {
+                validationResult.arguments = argValidation.sanitizedData || {};
+            }
+        }
+        // Validate options
+        if (config.options) {
+            const optionValidation = await this.validateOptions(options, config.options);
+            if (!optionValidation.valid) {
+                validationResult.valid = false;
+                if (optionValidation.errors) {
+                    const errorMessages = optionValidation.errors.map(e => e.message);
+                    validationResult.errors?.push(...errorMessages);
+                }
+                if (optionValidation.suggestions) {
+                    validationResult.suggestions?.push(...optionValidation.suggestions);
+                }
+            }
+            else {
+                validationResult.options = optionValidation.sanitizedData || {};
+            }
+        }
+        // Custom validation
+        if (config.customValidation && validationResult.valid) {
+            const customResult = await config.customValidation(validationResult.arguments, validationResult.options);
+            if (!customResult.valid) {
+                validationResult.valid = false;
+                if (customResult.error) {
+                    validationResult.errors?.push(customResult.error);
+                }
+                if (customResult.suggestions) {
+                    validationResult.suggestions?.push(...customResult.suggestions);
+                }
+            }
+        }
+        if (!validationResult.valid) {
+            this.lastError = validationResult.errors?.join('; ') || 'Command validation failed';
+            this.lastSuggestions = validationResult.suggestions || [];
+        }
+        return validationResult;
+    }
+    /**
+     * Validate command arguments against configuration
+     */
+    async validateArguments(args, argumentConfigs) {
+        const argumentData = {};
+        const schema = {};
+        // Map arguments to configuration
+        for (let i = 0; i < argumentConfigs.length; i++) {
+            const config = argumentConfigs[i];
+            const value = args[i];
+            if (value !== undefined) {
+                argumentData[config.name] = value;
+            }
+            else if (config.defaultValue !== undefined) {
+                argumentData[config.name] = config.defaultValue;
+            }
+            // Build validation schema
+            if (config.validation) {
+                Object.assign(schema, config.validation);
+            }
+            else {
+                // Default string validation
+                schema[config.name] = {
+                    type: 'string',
+                    required: config.required || false,
+                    maxLength: 500
+                };
+            }
+            // Add choices validation if specified
+            if (config.choices && config.choices.length > 0) {
+                schema[config.name] = {
+                    ...schema[config.name],
+                    allowedValues: config.choices
+                };
+            }
+        }
+        return await this.inputValidator.validateInput(argumentData, schema);
+    }
+    /**
+     * Validate command options against configuration
+     */
+    async validateOptions(options, optionConfigs) {
+        const schema = {};
+        // Build validation schema for options
+        for (const config of optionConfigs) {
+            if (config.validation) {
+                Object.assign(schema, config.validation);
+            }
+            else {
+                // Default validation based on option type
+                schema[config.name] = {
+                    type: 'string',
+                    required: config.required || false,
+                    maxLength: 1000
+                };
+            }
+            // Add choices validation if specified
+            if (config.choices && config.choices.length > 0) {
+                schema[config.name] = {
+                    ...schema[config.name],
+                    allowedValues: config.choices
+                };
+            }
+        }
+        return await this.inputValidator.validateInput(options, schema);
+    }
+    /**
+     * Create a Commander.js command with built-in validation
+     */
+    createValidatedCommand(config) {
+        const command = new Command(config.name);
+        command.description(config.description);
+        // Add arguments
+        if (config.arguments) {
+            for (const arg of config.arguments) {
+                if (arg.required) {
+                    command.argument(`<${arg.name}>`, arg.description);
+                }
+                else {
+                    command.argument(`[${arg.name}]`, arg.description, arg.defaultValue);
+                }
+            }
+        }
+        // Add options
+        if (config.options) {
+            for (const opt of config.options) {
+                const flags = opt.aliases
+                    ? `--${opt.name}, ${opt.aliases.map(a => `-${a}`).join(', ')}`
+                    : `--${opt.name}`;
+                if (opt.choices) {
+                    command.option(flags, opt.description, opt.defaultValue);
+                    command.addOption(command.createOption(flags, opt.description)
+                        .choices(opt.choices)
+                        .default(opt.defaultValue));
+                }
+                else {
+                    command.option(flags, opt.description, opt.defaultValue);
+                }
+            }
+        }
+        // Add validation action
+        command.action(async (...args) => {
+            const commandArgs = args.slice(0, -2); // Remove options and command objects
+            const options = args[args.length - 2];
+            const validation = await this.validateCommand(config.name, commandArgs, options);
+            if (!validation.valid) {
+                console.error('Command validation failed:');
+                validation.errors?.forEach(error => console.error(`  • ${error}`));
+                if (validation.suggestions?.length) {
+                    console.error('\nSuggestions:');
+                    validation.suggestions.forEach(suggestion => console.error(`  • ${suggestion}`));
+                }
+                process.exit(1);
+            }
+            // Continue with execution - validation passed
+        });
+        // Register the command configuration
+        this.registerCommand(config);
+        return command;
+    }
+    /**
+     * Register built-in ginko commands with validation
+     */
+    registerBuiltinCommands() {
+        // Start command
+        this.registerCommand({
+            name: 'start',
+            description: 'Start a new ginko session',
+            options: [
+                {
+                    name: 'message',
+                    description: 'Initial session message',
+                    validation: {
+                        message: {
+                            type: 'string',
+                            maxLength: 500,
+                            pattern: /^[a-zA-Z0-9\s.,!?-]+$/
+                        }
+                    }
+                },
+                {
+                    name: 'verbose',
+                    description: 'Enable verbose output',
+                    validation: {
+                        verbose: { type: 'boolean' }
+                    }
+                }
+            ],
+            requiresGit: true
+        });
+        // Handoff command
+        this.registerCommand({
+            name: 'handoff',
+            description: 'Create a handoff for the current session',
+            arguments: [
+                {
+                    name: 'message',
+                    description: 'Handoff message describing current state',
+                    required: true,
+                    validation: {
+                        message: {
+                            type: 'string',
+                            required: true,
+                            minLength: 10,
+                            maxLength: 1000,
+                            pattern: /^[a-zA-Z0-9\s.,!?-]+$/
+                        }
+                    }
+                }
+            ],
+            requiresGit: true
+        });
+        // Context command
+        this.registerCommand({
+            name: 'context',
+            description: 'Manage context modules',
+            arguments: [
+                {
+                    name: 'action',
+                    description: 'Context action to perform',
+                    choices: ['list', 'load', 'create', 'update', 'delete'],
+                    validation: {
+                        action: {
+                            type: 'string',
+                            allowedValues: ['list', 'load', 'create', 'update', 'delete']
+                        }
+                    }
+                }
+            ]
+        });
+        // Doctor command
+        this.registerCommand({
+            name: 'doctor',
+            description: 'Diagnose ginko environment and configuration',
+            options: [
+                {
+                    name: 'fix',
+                    description: 'Automatically fix detected issues',
+                    validation: {
+                        fix: { type: 'boolean' }
+                    }
+                },
+                {
+                    name: 'verbose',
+                    description: 'Show detailed diagnostic information',
+                    validation: {
+                        verbose: { type: 'boolean' }
+                    }
+                }
+            ]
+        });
+        // Sprint command
+        this.registerCommand({
+            name: 'sprint',
+            description: 'Sprint planning and management',
+            arguments: [
+                {
+                    name: 'action',
+                    description: 'Sprint action to perform',
+                    choices: ['start', 'status', 'complete', 'plan'],
+                    validation: {
+                        action: {
+                            type: 'string',
+                            allowedValues: ['start', 'status', 'complete', 'plan']
+                        }
+                    }
+                }
+            ],
+            requiresGit: true,
+            requiresConfig: true
+        });
+    }
+    /**
+     * Validate common CLI patterns
+     */
+    static validateCommonPatterns(value, pattern) {
+        const patterns = {
+            email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+            url: /^https?:\/\/[^\s/$.?#].[^\s]*$/i,
+            semver: /^\d+\.\d+\.\d+(-[a-zA-Z0-9-]+)?(\+[a-zA-Z0-9-]+)?$/,
+            uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+        };
+        return patterns[pattern]?.test(value) || false;
+    }
+    async validate() {
+        // This validator is stateless, always valid
+        return { valid: true };
+    }
+    getErrorMessage() {
+        return this.lastError || 'No validation errors';
+    }
+    getSuggestions() {
+        return this.lastSuggestions;
+    }
+    /**
+     * Get all registered command configurations
+     */
+    getRegisteredCommands() {
+        return Array.from(this.commandConfigs.values());
+    }
+    /**
+     * Get command configuration by name
+     */
+    getCommandConfig(name) {
+        return this.commandConfigs.get(name);
+    }
+}
+//# sourceMappingURL=command-argument-validator.js.map

package/dist/core/validators/command-argument-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-argument-validator.js","sourceRoot":"","sources":["../../../src/core/validators/command-argument-validator.ts"],"names":[],"mappings":"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"}

package/dist/core/validators/config-validator.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-09-19
+ * @tags: [validation, config, ginko-json, schema, first-use-experience]
+ * @related: [git-validator.ts, environment-validator.ts, index.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: [fs-extra]
+ */
+import { ValidationResult, Validator } from './git-validator.js';
+/**
+ * Schema for ginko.json configuration
+ */
+export interface GinkoConfig {
+    version: string;
+    paths: {
+        docs: Record<string, string>;
+        ginko: Record<string, string>;
+    };
+    features: Record<string, boolean>;
+    platform?: PlatformConfig;
+    [key: string]: any;
+}
+/**
+ * Platform-specific configuration
+ */
+export interface PlatformConfig {
+    type: 'windows' | 'macos' | 'linux';
+    shell?: string;
+    pathSeparator?: string;
+    hooks?: Record<string, string>;
+}
+/**
+ * Validates ginko.json configuration file
+ *
+ * Checks:
+ * - File exists and is readable
+ * - Valid JSON syntax
+ * - Required fields are present
+ * - Paths are valid and accessible
+ * - Configuration schema compliance
+ */
+export declare class ConfigValidator implements Validator {
+    private configPath;
+    private lastError?;
+    private lastSuggestions;
+    private config?;
+    constructor(projectRoot?: string);
+    /**
+     * Perform comprehensive config validation
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Get user-friendly error message
+     */
+    getErrorMessage(): string;
+    /**
+     * Get actionable suggestions for fixing the error
+     */
+    getSuggestions(): string[];
+    /**
+     * Check if config file exists and is readable
+     */
+    private checkConfigFile;
+    /**
+     * Load and parse JSON configuration
+     */
+    private loadConfiguration;
+    /**
+     * Validate configuration schema
+     */
+    private validateSchema;
+    /**
+     * Validate configured paths exist or can be created
+     */
+    private validatePaths;
+    /**
+     * Check if version string is valid semantic version
+     */
+    private isValidVersion;
+    /**
+     * Check if config has custom paths (different from defaults)
+     */
+    private hasCustomPaths;
+    /**
+     * Get list of enabled features
+     */
+    private getEnabledFeatures;
+    /**
+     * Generate contextual suggestions based on error type
+     */
+    private generateErrorSuggestions;
+    /**
+     * Get the loaded configuration
+     */
+    getConfig(): GinkoConfig | undefined;
+    /**
+     * Get default configuration
+     */
+    static getDefaultConfig(): GinkoConfig;
+    /**
+     * Static method to validate a config object directly
+     */
+    static validateConfigObject(config: any): ValidationResult;
+    /**
+     * Static method to merge user config with defaults
+     */
+    static mergeWithDefaults(userConfig: Partial<GinkoConfig>): GinkoConfig;
+}
+//# sourceMappingURL=config-validator.d.ts.map

package/dist/core/validators/config-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-validator.d.ts","sourceRoot":"","sources":["../../../src/core/validators/config-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC/B,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AA6BD;;;;;;;;;GASG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,MAAM,CAAC,CAAc;gBAEjB,WAAW,GAAE,MAAsB;IAI/C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAkD3C;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;OAEG;YACW,eAAe;IAuD7B;;OAEG;YACW,iBAAiB;IAwC/B;;OAEG;YACW,cAAc;IAoD5B;;OAEG;YACW,aAAa;IAmE3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAKtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA+BhC;;OAEG;IACH,SAAS,IAAI,WAAW,GAAG,SAAS;IAIpC;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,WAAW;IAItC;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,MAAM,EAAE,GAAG,GAAG,gBAAgB;IAiC1D;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,UAAU,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW;CAqBxE"}