@ginkoai/cli 1.0.0

package/dist/core/validators/config-validator.js

@@ -0,0 +1,433 @@
+/**
+ * @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 * as fs from 'fs-extra';
+import * as path from 'path';
+/**
+ * Default ginko configuration
+ */
+const DEFAULT_CONFIG = {
+    version: '1.0.0',
+    paths: {
+        docs: {
+            root: './docs',
+            adr: './docs/adr',
+            prd: './docs/PRD',
+            retrospectives: './docs/retrospectives'
+        },
+        ginko: {
+            root: './.ginko',
+            context: './.ginko/context',
+            modules: './.ginko/context/modules',
+            sessions: './.ginko/sessions'
+        }
+    },
+    features: {
+        autoHandoff: true,
+        contextCapture: true,
+        aiInsights: true,
+        teamSharing: false
+    }
+};
+/**
+ * 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 class ConfigValidator {
+    configPath;
+    lastError;
+    lastSuggestions = [];
+    config;
+    constructor(projectRoot = process.cwd()) {
+        this.configPath = path.join(projectRoot, 'ginko.json');
+    }
+    /**
+     * Perform comprehensive config validation
+     */
+    async validate() {
+        try {
+            // Check 1: File existence and readability
+            const fileCheck = await this.checkConfigFile();
+            if (!fileCheck.valid) {
+                return fileCheck;
+            }
+            // Check 2: JSON syntax and loading
+            const loadCheck = await this.loadConfiguration();
+            if (!loadCheck.valid) {
+                return loadCheck;
+            }
+            // Check 3: Schema validation
+            const schemaCheck = await this.validateSchema();
+            if (!schemaCheck.valid) {
+                return schemaCheck;
+            }
+            // Check 4: Path validation
+            const pathCheck = await this.validatePaths();
+            if (!pathCheck.valid) {
+                return pathCheck;
+            }
+            // All checks passed
+            return {
+                valid: true,
+                metadata: {
+                    configPath: this.configPath,
+                    config: this.config,
+                    hasCustomPaths: this.hasCustomPaths(),
+                    hasPlatformConfig: !!this.config?.platform,
+                    enabledFeatures: this.getEnabledFeatures()
+                }
+            };
+        }
+        catch (error) {
+            this.lastError = error instanceof Error ? error.message : 'Unknown config validation error';
+            this.lastSuggestions = this.generateErrorSuggestions(error);
+            return {
+                valid: false,
+                error: this.lastError,
+                suggestions: this.lastSuggestions
+            };
+        }
+    }
+    /**
+     * Get user-friendly error message
+     */
+    getErrorMessage() {
+        return this.lastError || 'Configuration validation failed';
+    }
+    /**
+     * Get actionable suggestions for fixing the error
+     */
+    getSuggestions() {
+        return this.lastSuggestions;
+    }
+    /**
+     * Check if config file exists and is readable
+     */
+    async checkConfigFile() {
+        try {
+            const exists = await fs.pathExists(this.configPath);
+            if (!exists) {
+                this.lastError = 'ginko.json configuration file not found';
+                this.lastSuggestions = [
+                    'Create ginko.json: ginko init',
+                    'Or create manually with default configuration',
+                    `Expected location: ${this.configPath}`,
+                    'Run in project root directory where ginko.json should exist'
+                ];
+                return {
+                    valid: false,
+                    error: this.lastError,
+                    suggestions: this.lastSuggestions
+                };
+            }
+            // Check if file is readable
+            try {
+                await fs.access(this.configPath, fs.constants.R_OK);
+            }
+            catch {
+                this.lastError = 'ginko.json exists but is not readable';
+                this.lastSuggestions = [
+                    'Check file permissions on ginko.json',
+                    'Ensure your user has read access',
+                    `File location: ${this.configPath}`
+                ];
+                return {
+                    valid: false,
+                    error: this.lastError,
+                    suggestions: this.lastSuggestions
+                };
+            }
+            return { valid: true };
+        }
+        catch (error) {
+            this.lastError = 'Failed to check config file accessibility';
+            this.lastSuggestions = [
+                'Verify directory permissions',
+                'Check if path is valid',
+                `Target path: ${this.configPath}`
+            ];
+            return {
+                valid: false,
+                error: this.lastError,
+                suggestions: this.lastSuggestions
+            };
+        }
+    }
+    /**
+     * Load and parse JSON configuration
+     */
+    async loadConfiguration() {
+        try {
+            const configData = await fs.readFile(this.configPath, 'utf-8');
+            // Parse JSON
+            try {
+                this.config = JSON.parse(configData);
+            }
+            catch (parseError) {
+                this.lastError = 'ginko.json contains invalid JSON syntax';
+                this.lastSuggestions = [
+                    'Fix JSON syntax errors in ginko.json',
+                    'Validate JSON online: https://jsonlint.com/',
+                    'Check for missing commas, quotes, or brackets',
+                    'Parse error: ' + (parseError instanceof Error ? parseError.message : 'Unknown')
+                ];
+                return {
+                    valid: false,
+                    error: this.lastError,
+                    suggestions: this.lastSuggestions
+                };
+            }
+            return { valid: true };
+        }
+        catch (error) {
+            this.lastError = 'Failed to read ginko.json file';
+            this.lastSuggestions = [
+                'Check if file is corrupted',
+                'Ensure file encoding is UTF-8',
+                'Try recreating the file: ginko init --force'
+            ];
+            return {
+                valid: false,
+                error: this.lastError,
+                suggestions: this.lastSuggestions
+            };
+        }
+    }
+    /**
+     * Validate configuration schema
+     */
+    async validateSchema() {
+        if (!this.config) {
+            this.lastError = 'Configuration not loaded';
+            return { valid: false, error: this.lastError };
+        }
+        const errors = [];
+        // Check required top-level fields
+        if (!this.config.version) {
+            errors.push('Missing required field: version');
+        }
+        if (!this.config.paths) {
+            errors.push('Missing required field: paths');
+        }
+        else {
+            // Check required path categories
+            if (!this.config.paths.docs) {
+                errors.push('Missing required field: paths.docs');
+            }
+            if (!this.config.paths.ginko) {
+                errors.push('Missing required field: paths.ginko');
+            }
+        }
+        if (!this.config.features) {
+            errors.push('Missing required field: features');
+        }
+        // Check version format
+        if (this.config.version && !this.isValidVersion(this.config.version)) {
+            errors.push('Invalid version format. Expected semantic version (e.g., "1.0.0")');
+        }
+        if (errors.length > 0) {
+            this.lastError = 'Configuration schema validation failed';
+            this.lastSuggestions = [
+                ...errors.map(err => `Fix: ${err}`),
+                'Compare with default config structure',
+                'Run: ginko init --force to reset to defaults'
+            ];
+            return {
+                valid: false,
+                error: this.lastError,
+                suggestions: this.lastSuggestions
+            };
+        }
+        return { valid: true };
+    }
+    /**
+     * Validate configured paths exist or can be created
+     */
+    async validatePaths() {
+        if (!this.config?.paths) {
+            return { valid: true }; // Already validated in schema check
+        }
+        const warnings = [];
+        const errors = [];
+        // Validate document paths
+        if (this.config.paths.docs) {
+            for (const [name, docPath] of Object.entries(this.config.paths.docs)) {
+                const fullPath = path.resolve(docPath);
+                const exists = await fs.pathExists(fullPath);
+                if (!exists) {
+                    warnings.push(`Document path '${name}' does not exist: ${docPath}`);
+                }
+                else {
+                    try {
+                        await fs.access(fullPath, fs.constants.R_OK | fs.constants.W_OK);
+                    }
+                    catch {
+                        errors.push(`Document path '${name}' is not accessible: ${docPath}`);
+                    }
+                }
+            }
+        }
+        // Validate ginko paths
+        if (this.config.paths.ginko) {
+            for (const [name, ginkoPath] of Object.entries(this.config.paths.ginko)) {
+                const fullPath = path.resolve(ginkoPath);
+                const exists = await fs.pathExists(fullPath);
+                if (!exists) {
+                    warnings.push(`Ginko path '${name}' does not exist: ${ginkoPath}`);
+                }
+            }
+        }
+        if (errors.length > 0) {
+            this.lastError = 'Path validation failed';
+            this.lastSuggestions = [
+                ...errors.map(err => `Fix: ${err}`),
+                'Ensure all paths are accessible',
+                'Check directory permissions',
+                'Run: ginko init to create missing directories'
+            ];
+            return {
+                valid: false,
+                error: this.lastError,
+                suggestions: this.lastSuggestions
+            };
+        }
+        // Return success with warnings
+        return {
+            valid: true,
+            metadata: {
+                warnings,
+                pathsChecked: {
+                    docs: Object.keys(this.config.paths.docs || {}),
+                    ginko: Object.keys(this.config.paths.ginko || {})
+                }
+            }
+        };
+    }
+    /**
+     * Check if version string is valid semantic version
+     */
+    isValidVersion(version) {
+        const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.-]+)?(\+[a-zA-Z0-9.-]+)?$/;
+        return semverRegex.test(version);
+    }
+    /**
+     * Check if config has custom paths (different from defaults)
+     */
+    hasCustomPaths() {
+        if (!this.config?.paths)
+            return false;
+        const defaultDocs = DEFAULT_CONFIG.paths.docs;
+        const defaultGinko = DEFAULT_CONFIG.paths.ginko;
+        return (JSON.stringify(this.config.paths.docs) !== JSON.stringify(defaultDocs) ||
+            JSON.stringify(this.config.paths.ginko) !== JSON.stringify(defaultGinko));
+    }
+    /**
+     * Get list of enabled features
+     */
+    getEnabledFeatures() {
+        if (!this.config?.features)
+            return [];
+        return Object.entries(this.config.features)
+            .filter(([_, enabled]) => enabled === true)
+            .map(([feature, _]) => feature);
+    }
+    /**
+     * Generate contextual suggestions based on error type
+     */
+    generateErrorSuggestions(error) {
+        const suggestions = [];
+        if (error?.code === 'ENOENT') {
+            suggestions.push('File not found - create ginko.json configuration', 'Run: ginko init', 'Or copy from another project');
+        }
+        else if (error?.code === 'EACCES') {
+            suggestions.push('Permission denied - check file permissions', 'Ensure you have read/write access to the directory');
+        }
+        else if (error instanceof SyntaxError) {
+            suggestions.push('JSON syntax error in ginko.json', 'Use a JSON validator to find syntax issues', 'Check for trailing commas, missing quotes');
+        }
+        else {
+            suggestions.push('Unexpected configuration error', 'Verify ginko.json format and accessibility', 'Try recreating: ginko init --force');
+        }
+        return suggestions;
+    }
+    /**
+     * Get the loaded configuration
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get default configuration
+     */
+    static getDefaultConfig() {
+        return JSON.parse(JSON.stringify(DEFAULT_CONFIG));
+    }
+    /**
+     * Static method to validate a config object directly
+     */
+    static validateConfigObject(config) {
+        try {
+            // Basic type check
+            if (typeof config !== 'object' || config === null) {
+                return {
+                    valid: false,
+                    error: 'Configuration must be an object',
+                    suggestions: ['Ensure ginko.json contains a valid JSON object']
+                };
+            }
+            // Required fields check
+            const required = ['version', 'paths', 'features'];
+            const missing = required.filter(field => !(field in config));
+            if (missing.length > 0) {
+                return {
+                    valid: false,
+                    error: `Missing required fields: ${missing.join(', ')}`,
+                    suggestions: missing.map(field => `Add required field: ${field}`)
+                };
+            }
+            return { valid: true };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: 'Failed to validate configuration object',
+                suggestions: ['Check configuration structure and types']
+            };
+        }
+    }
+    /**
+     * Static method to merge user config with defaults
+     */
+    static mergeWithDefaults(userConfig) {
+        const merged = {
+            ...DEFAULT_CONFIG,
+            ...userConfig
+        };
+        // Deep merge paths
+        if (userConfig.paths) {
+            merged.paths = {
+                docs: { ...DEFAULT_CONFIG.paths.docs, ...userConfig.paths.docs },
+                ginko: { ...DEFAULT_CONFIG.paths.ginko, ...userConfig.paths.ginko }
+            };
+        }
+        // Deep merge features
+        if (userConfig.features) {
+            merged.features = { ...DEFAULT_CONFIG.features, ...userConfig.features };
+        }
+        return merged;
+    }
+}
+//# sourceMappingURL=config-validator.js.map

package/dist/core/validators/config-validator.js.map

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

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

@@ -0,0 +1,138 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-09-19
+ * @tags: [validation, environment, nodejs, platform, first-use-experience]
+ * @related: [git-validator.ts, config-validator.ts, index.ts]
+ * @priority: critical
+ * @complexity: medium
+ * @dependencies: [fs-extra]
+ */
+import { ValidationResult, Validator } from './git-validator.js';
+/**
+ * Platform type detection
+ */
+export type Platform = 'windows' | 'macos' | 'linux' | 'unknown';
+/**
+ * Node.js version requirements
+ */
+export interface NodeRequirements {
+    minimum: string;
+    recommended: string;
+    maximum?: string;
+}
+/**
+ * Environment information
+ */
+export interface EnvironmentInfo {
+    platform: Platform;
+    nodeVersion: string;
+    npmVersion?: string;
+    gitVersion?: string;
+    shellType?: string;
+    workingDirectory: string;
+    homeDirectory: string;
+    pathSeparator: string;
+    executable: {
+        node: string;
+        npm?: string;
+        git?: string;
+    };
+}
+/**
+ * Validates system environment requirements for ginko
+ *
+ * Checks:
+ * - Node.js version compatibility
+ * - Platform detection and support
+ * - Required commands availability
+ * - Directory permissions
+ * - Path configuration
+ */
+export declare class EnvironmentValidator implements Validator {
+    private lastError?;
+    private lastSuggestions;
+    private environmentInfo?;
+    constructor();
+    /**
+     * Perform comprehensive environment validation
+     */
+    validate(): Promise<ValidationResult>;
+    /**
+     * Get user-friendly error message
+     */
+    getErrorMessage(): string;
+    /**
+     * Get actionable suggestions for fixing the error
+     */
+    getSuggestions(): string[];
+    /**
+     * Detect platform and basic environment info
+     */
+    private detectPlatform;
+    /**
+     * Validate Node.js version meets requirements
+     */
+    private validateNodeVersion;
+    /**
+     * Validate required commands are available
+     */
+    private validateCommands;
+    /**
+     * Validate directory permissions
+     */
+    private validatePermissions;
+    /**
+     * Validate environment paths and PATH variable
+     */
+    private validatePaths;
+    /**
+     * Get platform type from process.platform
+     */
+    private getPlatformType;
+    /**
+     * Detect shell type
+     */
+    private getShellType;
+    /**
+     * Get version of a command
+     */
+    private getCommandVersion;
+    /**
+     * Compare semantic versions
+     */
+    private compareVersions;
+    /**
+     * Check if Node.js version meets requirements
+     */
+    private isNodeVersionCompliant;
+    /**
+     * Check for optional tools that enhance ginko experience
+     */
+    private checkOptionalTools;
+    /**
+     * Find command in PATH
+     */
+    private findInPath;
+    /**
+     * Generate contextual suggestions based on error type
+     */
+    private generateErrorSuggestions;
+    /**
+     * Get environment information
+     */
+    getEnvironmentInfo(): EnvironmentInfo | undefined;
+    /**
+     * Static method to quickly check Node.js version
+     */
+    static isNodeVersionValid(): boolean;
+    /**
+     * Static method to get platform type
+     */
+    static getPlatform(): Platform;
+    /**
+     * Static method to get basic environment info
+     */
+    static getBasicInfo(): Promise<Partial<EnvironmentInfo>>;
+}
+//# sourceMappingURL=environment-validator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"environment-validator.d.ts","sourceRoot":"","sources":["../../../src/core/validators/environment-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAUD;;;;;;;;;GASG;AACH,qBAAa,oBAAqB,YAAW,SAAS;IACpD,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,eAAe,CAAC,CAAkB;;IAI1C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAuD3C;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;OAEG;YACW,cAAc;IAoD5B;;OAEG;YACW,mBAAmB;IAsDjC;;OAEG;YACW,gBAAgB;IAyD9B;;OAEG;YACW,mBAAmB;IA6DjC;;OAEG;YACW,aAAa;IAgD3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAavB;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB;;OAEG;YACW,iBAAiB;IA8B/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAK9B;;OAEG;YACW,kBAAkB;IAehC;;OAEG;YACW,UAAU;IAoBxB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IA0BhC;;OAEG;IACH,kBAAkB,IAAI,eAAe,GAAG,SAAS;IAIjD;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,OAAO;IAMpC;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,QAAQ;IAK9B;;OAEG;WACU,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;CAK/D"}