@paths.design/caws-cli 2.0.0 → 3.0.0

package/templates/apps/tools/caws/shared/base-tool.ts

@@ -0,0 +1,281 @@
+/**
+ * CAWS Base Tool
+ * Shared functionality for all CAWS tools including file operations,
+ * configuration management, and common utilities
+ *
+ * @author @darianrosebrook
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { CawsConfig } from './types.js';
+
+export interface ToolResult {
+  success: boolean;
+  message: string;
+  data?: any;
+  errors?: string[];
+  warnings?: string[];
+}
+
+export interface FileOperationOptions {
+  encoding?: string;
+  createDir?: boolean;
+  backup?: boolean;
+}
+
+export abstract class CawsBaseTool {
+  protected readonly __dirname: string;
+  protected readonly cawsDirectory: string;
+  protected readonly workingDirectory: string;
+
+  constructor() {
+    this.__dirname = path.dirname(fileURLToPath(import.meta.url));
+    this.workingDirectory = process.cwd();
+    this.cawsDirectory = path.join(this.workingDirectory, '.caws');
+  }
+
+  /**
+   * Get the CAWS configuration directory
+   */
+  protected getCawsDirectory(): string {
+    return this.cawsDirectory;
+  }
+
+  /**
+   * Get the working directory
+   */
+  protected getWorkingDirectory(): string {
+    return this.workingDirectory;
+  }
+
+  /**
+   * Safely read a JSON file with error handling
+   */
+  protected readJsonFile<T = any>(filePath: string): T | null {
+    try {
+      if (!fs.existsSync(filePath)) {
+        return null;
+      }
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      return JSON.parse(content) as T;
+    } catch (error) {
+      this.logError(`Failed to read JSON file ${filePath}: ${error}`);
+      return null;
+    }
+  }
+
+  /**
+   * Safely write a JSON file with backup option
+   */
+  protected writeJsonFile(
+    filePath: string,
+    data: any,
+    options: FileOperationOptions = {}
+  ): boolean {
+    try {
+      const { createDir = true, backup = false } = options;
+
+      // Create directory if needed
+      if (createDir) {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+          fs.mkdirSync(dir, { recursive: true });
+        }
+      }
+
+      // Create backup if requested
+      if (backup && fs.existsSync(filePath)) {
+        const backupPath = `${filePath}.backup`;
+        fs.copyFileSync(filePath, backupPath);
+      }
+
+      // Write the file
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+      return true;
+    } catch (error) {
+      this.logError(`Failed to write JSON file ${filePath}: ${error}`);
+      return false;
+    }
+  }
+
+  /**
+   * Safely read a YAML file
+   */
+  protected async readYamlFile<T = any>(filePath: string): Promise<T | null> {
+    try {
+      if (!fs.existsSync(filePath)) {
+        return null;
+      }
+
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const yaml = await import('js-yaml');
+      return yaml.load(content) as T;
+    } catch (error) {
+      this.logError(`Failed to read YAML file ${error}`);
+      return null;
+    }
+  }
+
+  /**
+   * Check if a path exists
+   */
+  protected pathExists(filePath: string): boolean {
+    return fs.existsSync(filePath);
+  }
+
+  /**
+   * Create directory if it doesn't exist
+   */
+  protected ensureDirectoryExists(dirPath: string): boolean {
+    try {
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+      }
+      return true;
+    } catch (error) {
+      this.logError(`Failed to create directory ${dirPath}: ${error}`);
+      return false;
+    }
+  }
+
+  /**
+   * Get relative path from working directory
+   */
+  protected getRelativePath(absolutePath: string): string {
+    return path.relative(this.workingDirectory, absolutePath);
+  }
+
+  /**
+   * Get absolute path from relative path
+   */
+  protected getAbsolutePath(relativePath: string): string {
+    return path.resolve(this.workingDirectory, relativePath);
+  }
+
+  /**
+   * Load tier policy configuration
+   */
+  protected loadTierPolicy(): Record<string, any> | null {
+    const policyPath = path.join(this.cawsDirectory, 'policy', 'tier-policy.json');
+    return this.readJsonFile(policyPath);
+  }
+
+  /**
+   * Load CAWS configuration
+   */
+  protected loadCawsConfig(): CawsConfig | null {
+    const configPath = path.join(this.cawsDirectory, 'config.json');
+    return this.readJsonFile(configPath);
+  }
+
+  /**
+   * Log an error message
+   */
+  protected logError(message: string): void {
+    console.error(`❌ ${message}`);
+  }
+
+  /**
+   * Log a warning message
+   */
+  protected logWarning(message: string): void {
+    console.warn(`⚠️  ${message}`);
+  }
+
+  /**
+   * Log an info message
+   */
+  protected logInfo(message: string): void {
+    console.log(`ℹ️  ${message}`);
+  }
+
+  /**
+   * Log a success message
+   */
+  protected logSuccess(message: string): void {
+    console.log(`✅ ${message}`);
+  }
+
+  /**
+   * Create a standardized result object
+   */
+  protected createResult(
+    success: boolean,
+    message: string,
+    data?: any,
+    errors?: string[],
+    warnings?: string[]
+  ): ToolResult {
+    return {
+      success,
+      message,
+      data,
+      errors: errors || [],
+      warnings: warnings || [],
+    };
+  }
+
+  /**
+   * Validate required environment variables
+   */
+  protected validateEnvironment(variables: string[]): boolean {
+    const missing = variables.filter((varName) => !process.env[varName]);
+
+    if (missing.length > 0) {
+      this.logError(`Missing required environment variables: ${missing.join(', ')}`);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Get environment variable with fallback
+   */
+  protected getEnvVar(name: string, fallback: string = ''): string {
+    return process.env[name] || fallback;
+  }
+
+  /**
+   * Parse command line arguments
+   */
+  protected parseArgs(expectedArgs: string[]): Record<string, string> {
+    const args = process.argv.slice(2);
+    const result: Record<string, string> = {};
+
+    for (let i = 0; i < args.length; i++) {
+      if (i < expectedArgs.length) {
+        result[expectedArgs[i]] = args[i];
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Show usage information
+   */
+  protected showUsage(usage: string, description: string): void {
+    console.log(`Usage: ${usage}`);
+    console.log(description);
+  }
+
+  /**
+   * Exit with appropriate code
+   */
+  protected exitWithResult(result: ToolResult): void {
+    if (result.success) {
+      this.logSuccess(result.message);
+      process.exit(0);
+    } else {
+      this.logError(result.message);
+      if (result.errors && result.errors.length > 0) {
+        result.errors.forEach((error) => this.logError(error));
+      }
+      process.exit(1);
+    }
+  }
+}

package/templates/apps/tools/caws/shared/config-manager.ts

@@ -0,0 +1,366 @@
+/**
+ * CAWS Configuration Manager
+ * Centralized configuration management for CAWS tools
+ *
+ * @author @darianrosebrook
+ */
+
+import * as path from 'path';
+import yaml from 'js-yaml';
+import { CawsConfig } from './types.js';
+import { CawsBaseTool, ToolResult } from './base-tool.js';
+
+export class CawsConfigManager extends CawsBaseTool {
+  private config: CawsConfig | null = null;
+  private readonly configPath: string;
+
+  constructor() {
+    super();
+    this.configPath = path.join(this.getCawsDirectory(), 'config.json');
+    this.loadConfig();
+  }
+
+  /**
+   * Load configuration from file
+   */
+  private loadConfig(): void {
+    try {
+      const configData = this.readJsonFile(this.configPath);
+      if (configData) {
+        this.config = configData as CawsConfig;
+        this.validateConfig();
+      }
+    } catch {
+      this.logWarning('Failed to load CAWS configuration, using defaults');
+      this.config = this.getDefaultConfig();
+    }
+  }
+
+  /**
+   * Save configuration to file
+   */
+  private saveConfig(): boolean {
+    try {
+      return this.writeJsonFile(this.configPath, this.config);
+    } catch (error) {
+      this.logError(`Failed to save CAWS configuration: ${error}`);
+      return false;
+    }
+  }
+
+  /**
+   * Get default configuration
+   */
+  private getDefaultConfig(): CawsConfig {
+    return {
+      version: '1.0.0',
+      environment: 'development',
+      gates: {
+        coverage: {
+          enabled: true,
+          thresholds: {
+            statements: 80,
+            branches: 75,
+            functions: 80,
+            lines: 80,
+          },
+        },
+        mutation: {
+          enabled: true,
+          thresholds: {
+            killed: 70,
+            survived: 30,
+          },
+        },
+        contracts: {
+          enabled: true,
+          required: true,
+        },
+        trust_score: {
+          enabled: true,
+          threshold: 0.8,
+        },
+      },
+      tools: {
+        coverage: {
+          command: 'nyc',
+          args: ['--reporter=json', '--reporter=text'],
+        },
+        mutation: {
+          command: 'stryker',
+          args: ['run'],
+        },
+        contracts: {
+          command: 'pact',
+          args: ['verify'],
+        },
+        linting: {
+          command: 'eslint',
+          args: ['.'],
+        },
+        testing: {
+          command: 'jest',
+          args: ['--coverage'],
+        },
+      },
+      paths: {
+        working_directory: this.getWorkingDirectory(),
+        reports: path.join(this.getWorkingDirectory(), 'reports'),
+        coverage: path.join(this.getWorkingDirectory(), 'coverage'),
+        artifacts: path.join(this.getWorkingDirectory(), 'artifacts'),
+      },
+      logging: {
+        level: 'info',
+        file: path.join(this.getCawsDirectory(), 'logs', 'caws.log'),
+        format: 'json',
+      },
+      features: {
+        multi_modal: true,
+        obsidian_support: true,
+        parallel_processing: true,
+      },
+      tiers: {
+        1: {
+          min_branch: 0.9,
+          min_coverage: 0.9,
+          min_mutation: 0.8,
+          requires_contracts: true,
+        },
+        2: {
+          min_branch: 0.8,
+          min_coverage: 0.8,
+          min_mutation: 0.7,
+          requires_contracts: true,
+        },
+        3: {
+          min_branch: 0.7,
+          min_coverage: 0.7,
+          min_mutation: 0.6,
+          requires_contracts: false,
+        },
+      },
+      defaultTier: '2',
+      workingSpecPath: path.join(this.getCawsDirectory(), 'working-spec.yaml'),
+      provenancePath: path.join(this.getCawsDirectory(), 'provenance.json'),
+      waiversPath: path.join(this.getCawsDirectory(), 'waivers.yml'),
+      cawsDirectory: this.getCawsDirectory(),
+      experiment_defaults: {
+        enabled: false,
+        timeboxed_hours: 24,
+        success_criteria: ['Basic functionality works'],
+      },
+    };
+  }
+
+  /**
+   * Validate configuration structure
+   */
+  private validateConfig(): void {
+    if (!this.config) return;
+
+    // Basic validation
+    if (!this.config.version) {
+      this.logWarning('Configuration missing version, setting to default');
+      this.config.version = '1.0.0';
+    }
+
+    if (!this.config.environment) {
+      this.logWarning('Configuration missing environment, setting to development');
+      this.config.environment = 'development';
+    }
+
+    // Validate paths
+    if (!this.config.paths) {
+      this.config.paths = this.getDefaultConfig().paths;
+    }
+
+    // Ensure required directories exist
+    this.ensureDirectories();
+  }
+
+  /**
+   * Ensure required directories exist
+   */
+  private ensureDirectories(): void {
+    if (!this.config?.paths) return;
+
+    const requiredDirs = [
+      this.config.paths.reports,
+      this.config.paths.coverage,
+      this.config.paths.artifacts,
+      path.dirname(this.config.logging?.file || ''),
+    ];
+
+    for (const dir of requiredDirs) {
+      if (dir) {
+        this.ensureDirectoryExists(dir);
+      }
+    }
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): CawsConfig {
+    return this.config || this.getDefaultConfig();
+  }
+
+  /**
+   * Update configuration
+   */
+  updateConfig(updates: Partial<CawsConfig>): ToolResult {
+    try {
+      if (!this.config) {
+        this.config = this.getDefaultConfig();
+      }
+
+      // Deep merge updates
+      this.config = {
+        ...this.config,
+        ...updates,
+        gates: { ...this.config.gates, ...updates.gates },
+        tools: { ...this.config.tools, ...updates.tools },
+        paths: { ...this.config.paths, ...updates.paths },
+        logging: { ...this.config.logging, ...updates.logging },
+        features: { ...this.config.features, ...updates.features },
+      };
+
+      // Validate and save
+      this.validateConfig();
+
+      if (this.saveConfig()) {
+        return this.createResult(true, 'Configuration updated successfully');
+      } else {
+        return this.createResult(false, 'Failed to save configuration');
+      }
+    } catch (error) {
+      return this.createResult(false, `Failed to update configuration: ${error}`);
+    }
+  }
+
+  /**
+   * Get specific configuration section
+   */
+  getSection<K extends keyof CawsConfig>(section: K): CawsConfig[K] | null {
+    const config = this.getConfig();
+    return config[section] || null;
+  }
+
+  /**
+   * Get gate configuration
+   */
+  getGateConfig(gateName: string): any {
+    const gates = this.getSection('gates');
+    return gates?.[gateName] || null;
+  }
+
+  /**
+   * Get tool configuration
+   */
+  getToolConfig(toolName: string): any {
+    const tools = this.getSection('tools');
+    return tools?.[toolName] || null;
+  }
+
+  /**
+   * Get path configuration
+   */
+  getPathConfig(pathName: string): string | null {
+    const paths = this.getSection('paths');
+    return paths?.[pathName] || null;
+  }
+
+  /**
+   * Check if a feature is enabled
+   */
+  isFeatureEnabled(feature: string): boolean {
+    const features = this.getSection('features');
+    const featureValue = features?.[feature];
+    return typeof featureValue === 'boolean' ? featureValue : featureValue?.enabled === true;
+  }
+
+  /**
+   * Get logging configuration
+   */
+  getLoggingConfig() {
+    return this.getSection('logging');
+  }
+
+  /**
+   * Load configuration from file path
+   */
+  loadConfigFromFile(filePath: string): ToolResult {
+    try {
+      const configData = this.readJsonFile(filePath);
+      if (!configData) {
+        return this.createResult(false, `Failed to read configuration from ${filePath}`);
+      }
+
+      this.config = configData as CawsConfig;
+      this.validateConfig();
+
+      return this.createResult(true, 'Configuration loaded from file');
+    } catch (error) {
+      return this.createResult(false, `Failed to load configuration: ${error}`);
+    }
+  }
+
+  /**
+   * Save configuration to custom path
+   */
+  saveConfigToFile(filePath: string): ToolResult {
+    try {
+      const saved = this.writeJsonFile(filePath, this.config);
+      if (saved) {
+        return this.createResult(true, `Configuration saved to ${filePath}`);
+      } else {
+        return this.createResult(false, `Failed to save configuration to ${filePath}`);
+      }
+    } catch (error) {
+      return this.createResult(false, `Failed to save configuration: ${error}`);
+    }
+  }
+
+  /**
+   * Reset configuration to defaults
+   */
+  resetConfig(): ToolResult {
+    this.config = this.getDefaultConfig();
+    return this.updateConfig({});
+  }
+
+  /**
+   * Export configuration as YAML
+   */
+  exportAsYaml(): string | null {
+    try {
+      return yaml.dump(this.getConfig(), {
+        indent: 2,
+        lineWidth: 80,
+        noRefs: true,
+      });
+    } catch (error) {
+      this.logError(`Failed to export configuration as YAML: ${error}`);
+      return null;
+    }
+  }
+
+  /**
+   * Import configuration from YAML
+   */
+  importFromYaml(yamlContent: string): ToolResult {
+    try {
+      const configData = yaml.load(yamlContent) as CawsConfig;
+      this.config = configData;
+      this.validateConfig();
+
+      if (this.saveConfig()) {
+        return this.createResult(true, 'Configuration imported from YAML successfully');
+      } else {
+        return this.createResult(false, 'Failed to save imported configuration');
+      }
+    } catch (error) {
+      return this.createResult(false, `Failed to import configuration from YAML: ${error}`);
+    }
+  }
+}