@paths.design/caws-cli 10.2.0 → 11.1.0

package/dist/spec/SpecFileManager.js

@@ -1,419 +0,0 @@
-/**
- * @fileoverview Spec File Manager - WorkingSpec ↔ YAML conversion and file management
- * Handles conversion between JavaScript WorkingSpec objects and YAML files,
- * manages .caws/working-spec.yaml lifecycle, and provides temporary file utilities.
- * Ported from agent-agency v2 CAWS integration patterns.
- * @author @darianrosebrook
- */
-
-const fs = require('fs-extra');
-const path = require('path');
-const yaml = require('js-yaml');
-const os = require('os');
-
-/**
- * Spec File Manager - Handles WorkingSpec file operations and YAML conversion
- *
- * Features:
- * - Bidirectional WorkingSpec ↔ YAML conversion
- * - Temporary file support for validation workflows
- * - Backup/restore capabilities
- * - Automatic cleanup of old temporary files
- */
-class SpecFileManager {
-  constructor(config = {}) {
-    this.projectRoot = config.projectRoot || process.cwd();
-    this.useTemporaryFiles = config.useTemporaryFiles ?? false;
-    this.tempDir = config.tempDir || os.tmpdir();
-  }
-
-  /**
-   * Convert WorkingSpec object to YAML string
-   *
-   * @param {Object} spec - WorkingSpec to convert
-   * @returns {string} YAML string representation
-   */
-  specToYaml(spec) {
-    return yaml.dump(spec, {
-      indent: 2,
-      lineWidth: 100,
-      noRefs: true,
-      sortKeys: false,
-    });
-  }
-
-  /**
-   * Parse YAML string to WorkingSpec object
-   *
-   * @param {string} yamlContent - YAML string to parse
-   * @returns {Object} Parsed WorkingSpec object
-   * @throws {Error} If YAML is invalid or doesn't match WorkingSpec schema
-   */
-  yamlToSpec(yamlContent) {
-    try {
-      const parsed = yaml.load(yamlContent);
-
-      // Basic validation
-      if (!parsed || typeof parsed !== 'object') {
-        throw new Error('Invalid YAML: not an object');
-      }
-
-      if (!parsed.id || !parsed.title || !parsed.risk_tier) {
-        throw new Error('Invalid WorkingSpec: missing required fields (id, title, risk_tier)');
-      }
-
-      return parsed;
-    } catch (error) {
-      throw new Error(`Failed to parse YAML: ${error.message}`);
-    }
-  }
-
-  /**
-   * Get path to .caws/working-spec.yaml in project
-   *
-   * @returns {string} Absolute path to working spec file
-   */
-  getSpecFilePath() {
-    return path.join(this.projectRoot, '.caws', 'working-spec.yaml');
-  }
-
-  /**
-   * Check if working spec file exists
-   *
-   * @returns {Promise<boolean>} True if file exists
-   */
-  async specFileExists() {
-    try {
-      await fs.access(this.getSpecFilePath());
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Read working spec from .caws/working-spec.yaml
-   *
-   * @returns {Promise<Object>} Parsed WorkingSpec object
-   * @throws {Error} If file doesn't exist or is invalid
-   */
-  async readSpecFile() {
-    const specPath = this.getSpecFilePath();
-
-    try {
-      const content = await fs.readFile(specPath, 'utf-8');
-      return this.yamlToSpec(content);
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        throw new Error(`Working spec not found: ${specPath}\nRun 'caws init' to create it`);
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Write WorkingSpec to file
-   *
-   * Writes to .caws/working-spec.yaml or a temporary file based on configuration.
-   *
-   * @param {Object} spec - WorkingSpec to write
-   * @param {Object} options - Write options
-   * @param {boolean} options.useTemp - Override temp file usage
-   * @param {boolean} options.backup - Create backup before writing
-   * @returns {Promise<Object>} Write result with file path and cleanup function
-   */
-  async writeSpecFile(spec, options = {}) {
-    const yamlContent = this.specToYaml(spec);
-    const useTemp = options.useTemp ?? this.useTemporaryFiles;
-
-    if (useTemp) {
-      // Write to temporary file
-      const tempPath = path.join(this.tempDir, `caws-spec-${spec.id || 'temp'}-${Date.now()}.yaml`);
-
-      await fs.writeFile(tempPath, yamlContent, 'utf-8');
-
-      return {
-        filePath: tempPath,
-        isTemporary: true,
-        cleanup: async () => {
-          try {
-            await fs.unlink(tempPath);
-          } catch {
-            // Ignore cleanup errors (file may already be deleted)
-          }
-        },
-      };
-    } else {
-      // Write to project .caws directory
-      const specPath = this.getSpecFilePath();
-      const cawsDir = path.dirname(specPath);
-
-      // Create backup if requested
-      if (options.backup && (await this.specFileExists())) {
-        await this.backupSpecFile();
-      }
-
-      // Ensure .caws directory exists
-      await fs.mkdir(cawsDir, { recursive: true });
-
-      await fs.writeFile(specPath, yamlContent, 'utf-8');
-
-      return {
-        filePath: specPath,
-        isTemporary: false,
-      };
-    }
-  }
-
-  /**
-   * Update existing working spec file
-   *
-   * Reads current spec, merges changes, and writes back.
-   *
-   * @param {Object} updates - Partial WorkingSpec with fields to update
-   * @returns {Promise<Object>} Updated WorkingSpec
-   */
-  async updateSpecFile(updates) {
-    const currentSpec = await this.readSpecFile();
-    const updatedSpec = {
-      ...currentSpec,
-      ...updates,
-    };
-
-    // Always write to permanent location for updates
-    await this.writeSpecFile(updatedSpec, { useTemp: false });
-
-    return updatedSpec;
-  }
-
-  /**
-   * Create backup of working spec
-   *
-   * @returns {Promise<string>} Path to backup file
-   */
-  async backupSpecFile() {
-    const specPath = this.getSpecFilePath();
-    const backupPath = `${specPath}.backup-${Date.now()}`;
-
-    await fs.copyFile(specPath, backupPath);
-
-    return backupPath;
-  }
-
-  /**
-   * Restore working spec from backup
-   *
-   * @param {string} backupPath - Path to backup file
-   * @returns {Promise<void>}
-   */
-  async restoreSpecFile(backupPath) {
-    const specPath = this.getSpecFilePath();
-    await fs.copyFile(backupPath, specPath);
-  }
-
-  /**
-   * List all backup files
-   *
-   * @returns {Promise<string[]>} Array of backup file paths
-   */
-  async listBackups() {
-    const specPath = this.getSpecFilePath();
-    const cawsDir = path.dirname(specPath);
-    const specName = path.basename(specPath);
-
-    try {
-      const files = await fs.readdir(cawsDir);
-      const backups = files
-        .filter((f) => f.startsWith(`${specName}.backup-`))
-        .map((f) => path.join(cawsDir, f));
-
-      // Sort by timestamp (newest first)
-      backups.sort().reverse();
-
-      return backups;
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Delete old backup files
-   *
-   * @param {Object} options - Cleanup options
-   * @param {number} options.maxAge - Maximum age in milliseconds (default: 7 days)
-   * @param {number} options.keep - Minimum number of backups to keep (default: 5)
-   * @returns {Promise<number>} Number of backups deleted
-   */
-  async cleanupBackups(options = {}) {
-    const maxAge = options.maxAge ?? 7 * 24 * 60 * 60 * 1000; // 7 days
-    const keepCount = options.keep ?? 5;
-
-    const backups = await this.listBackups();
-    const now = Date.now();
-    let deleted = 0;
-
-    // Delete old backups beyond the keep count
-    for (let i = 0; i < backups.length; i++) {
-      const backupPath = backups[i];
-
-      try {
-        const stats = await fs.stat(backupPath);
-        const age = now - stats.mtimeMs;
-
-        // Keep the most recent N backups, or delete if too old
-        const shouldDelete = i >= keepCount && age > maxAge;
-
-        if (shouldDelete) {
-          await fs.unlink(backupPath);
-          deleted++;
-        }
-      } catch {
-        // Skip files that can't be accessed
-      }
-    }
-
-    return deleted;
-  }
-
-  /**
-   * Validate spec file exists and is parseable
-   *
-   * @returns {Promise<Object>} Validation result
-   */
-  async validateSpecFile() {
-    try {
-      const spec = await this.readSpecFile();
-      return {
-        valid: true,
-        spec,
-      };
-    } catch (error) {
-      return {
-        valid: false,
-        error: error.message,
-      };
-    }
-  }
-
-  /**
-   * Clean up old temporary spec files
-   *
-   * Removes temp files older than specified age.
-   *
-   * @param {number} maxAge - Maximum age in milliseconds (default: 1 hour)
-   * @returns {Promise<number>} Number of files cleaned up
-   */
-  async cleanupTempFiles(maxAge = 3600000) {
-    try {
-      const files = await fs.readdir(this.tempDir);
-      const specFiles = files.filter((f) => f.startsWith('caws-spec-'));
-
-      let cleaned = 0;
-      const now = Date.now();
-
-      for (const file of specFiles) {
-        const filePath = path.join(this.tempDir, file);
-        try {
-          const stats = await fs.stat(filePath);
-          const age = now - stats.mtimeMs;
-
-          if (age > maxAge) {
-            await fs.unlink(filePath);
-            cleaned++;
-          }
-        } catch {
-          // Skip files that can't be accessed
-        }
-      }
-
-      return cleaned;
-    } catch {
-      return 0;
-    }
-  }
-
-  /**
-   * Get spec file stats (size, modified date, etc.)
-   *
-   * @returns {Promise<Object>} File stats
-   */
-  async getSpecFileStats() {
-    const specPath = this.getSpecFilePath();
-
-    try {
-      const stats = await fs.stat(specPath);
-      const content = await fs.readFile(specPath, 'utf-8');
-      const lines = content.split('\n').length;
-
-      return {
-        exists: true,
-        size: stats.size,
-        sizeKB: Math.round((stats.size / 1024) * 10) / 10,
-        lines,
-        modified: stats.mtime,
-        created: stats.birthtime,
-      };
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        return {
-          exists: false,
-        };
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Create a new SpecFileManager instance with different configuration
-   *
-   * @param {Object} config - New configuration
-   * @returns {SpecFileManager} New instance
-   */
-  withConfig(config) {
-    return new SpecFileManager({
-      projectRoot: this.projectRoot,
-      useTemporaryFiles: this.useTemporaryFiles,
-      tempDir: this.tempDir,
-      ...config,
-    });
-  }
-}
-
-/**
- * Create a SpecFileManager instance with default configuration
- *
- * @param {string} projectRoot - Project root directory
- * @param {Object} options - Additional options
- * @returns {SpecFileManager} SpecFileManager instance
- */
-function createSpecFileManager(projectRoot, options = {}) {
-  return new SpecFileManager({
-    projectRoot,
-    ...options,
-  });
-}
-
-// Export singleton instance for convenience
-const defaultSpecFileManager = new SpecFileManager();
-
-module.exports = {
-  SpecFileManager,
-  defaultSpecFileManager,
-  createSpecFileManager,
-
-  // Convenience exports for backward compatibility
-  specToYaml: (spec) => defaultSpecFileManager.specToYaml(spec),
-  yamlToSpec: (yaml) => defaultSpecFileManager.yamlToSpec(yaml),
-  readSpecFile: (projectRoot) => {
-    if (projectRoot) {
-      return createSpecFileManager(projectRoot).readSpecFile();
-    }
-    return defaultSpecFileManager.readSpecFile();
-  },
-  writeSpecFile: (spec, projectRoot, options) => {
-    if (projectRoot) {
-      return createSpecFileManager(projectRoot).writeSpecFile(spec, options);
-    }
-    return defaultSpecFileManager.writeSpecFile(spec, options);
-  },
-};

package/dist/templates/.caws/schemas/policy.schema.json

@@ -1,117 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "required": [
-    "version",
-    "risk_tiers",
-    "edit_rules"
-  ],
-  "properties": {
-    "version": {
-      "type": "integer",
-      "enum": [
-        1
-      ],
-      "description": "Policy schema version"
-    },
-    "risk_tiers": {
-      "type": "object",
-      "patternProperties": {
-        "^[1-3]$": {
-          "type": "object",
-          "required": [
-            "max_files",
-            "max_loc"
-          ],
-          "properties": {
-            "max_files": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Maximum files allowed for this risk tier"
-            },
-            "max_loc": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "Maximum lines of code allowed for this risk tier"
-            },
-            "description": {
-              "type": "string",
-              "description": "Human-readable description of the tier"
-            }
-          },
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false,
-      "description": "Risk tier definitions with budget limits"
-    },
-    "edit_rules": {
-      "type": "object",
-      "required": [
-        "policy_and_code_same_pr",
-        "min_approvers_for_budget_raise"
-      ],
-      "properties": {
-        "policy_and_code_same_pr": {
-          "type": "boolean",
-          "description": "Whether policy and code changes can be in the same PR"
-        },
-        "min_approvers_for_budget_raise": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Minimum approvers required for budget increases"
-        },
-        "require_signed_commits": {
-          "type": "boolean",
-          "description": "Whether signed commits are required for policy changes"
-        }
-      },
-      "additionalProperties": false,
-      "description": "Rules governing policy file edits"
-    },
-    "gates": {
-      "type": "object",
-      "patternProperties": {
-        "^.*$": {
-          "type": "object",
-          "required": [
-            "enabled"
-          ],
-          "properties": {
-            "enabled": {
-              "type": "boolean",
-              "description": "Whether this gate is active"
-            },
-            "mode": {
-              "type": "string",
-              "enum": [
-                "warn",
-                "block",
-                "skip"
-              ],
-              "description": "How the gate reports failures: warn, block, or skip entirely"
-            },
-            "description": {
-              "type": "string",
-              "description": "Human-readable description of the gate"
-            },
-            "thresholds": {
-              "type": "object",
-              "description": "Gate-specific thresholds (e.g. warning/critical limits)"
-            }
-          },
-          "additionalProperties": false
-        }
-      },
-      "additionalProperties": false,
-      "description": "Quality gate configurations"
-    },
-    "non_governed_zones": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Glob patterns (picomatch, dot:true) for paths declared outside CAWS scope enforcement. Any file matching a pattern is exempt from scope-boundary checks — neither spec.scope.in nor spec.scope.out are consulted. Intended for research, playground, or experimental subtrees where governance is explicitly off by design. Example: [\"research/**\", \"playground/**\"]. (CAWSFIX-26 / D9)"
-    }
-  },
-  "additionalProperties": false,
-  "title": "CAWS Policy"
-}

package/dist/templates/.caws/schemas/scope.schema.json

@@ -1,52 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "CAWS Lite Scope Configuration",
-  "description": "Scope configuration for CAWS lite mode — guardrails without YAML specs. This schema governs the standalone .caws/scope.json file ONLY; inline scope: blocks inside working-spec.yaml or feature specs are governed by the working-spec schema's scope sub-schema and do NOT invoke this schema. See CAWSFIX-11.",
-  "type": "object",
-  "required": ["allowedDirectories"],
-  "properties": {
-    "version": {
-      "type": "integer",
-      "const": 1,
-      "description": "Schema version. Optional for back-compat with scope.json files that predate versioning; the runtime (src/config/lite-scope.js) defaults to 1 when missing. If present, must be exactly 1. CAWSFIX-11 lifted `version` from the required list because no code path enforces a version mismatch — only the schema did, producing spurious warnings for pre-versioning scope.json files."
-    },
-    "allowedDirectories": {
-      "type": "array",
-      "items": { "type": "string" },
-      "minItems": 1,
-      "description": "Directories the agent is allowed to modify (e.g., src/, tests/)"
-    },
-    "bannedPatterns": {
-      "type": "object",
-      "properties": {
-        "files": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Glob patterns for banned file names (e.g., *-enhanced.*, *-final.*)"
-        },
-        "directories": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Glob patterns for banned directory names (e.g., *venv*, .venv)"
-        },
-        "docs": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "Glob patterns for banned doc file names (e.g., *-summary.md)"
-        }
-      },
-      "additionalProperties": false
-    },
-    "maxNewFilesPerCommit": {
-      "type": "integer",
-      "minimum": 1,
-      "maximum": 100,
-      "description": "Maximum number of new files allowed per commit (prevents file sprawl)"
-    },
-    "designatedVenvPath": {
-      "type": "string",
-      "description": "The only allowed virtual environment path (e.g., .venv)"
-    }
-  },
-  "additionalProperties": false
-}

package/dist/templates/.caws/schemas/waivers.schema.json

@@ -1,106 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "title": "CAWS Waiver",
-  "description": "Individual waiver file created by caws waivers create",
-  "type": "object",
-  "required": ["id", "applies_to", "gates", "delta", "reason_code", "expires_at", "risk_owner", "approvers", "status"],
-  "properties": {
-    "id": {
-      "type": "string",
-      "pattern": "^WV-\\d{4}$",
-      "description": "Waiver ID in format WV-XXXX"
-    },
-    "applies_to": {
-      "type": "string",
-      "description": "Spec ID or PR number this waiver applies to"
-    },
-    "gates": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["budget_limit", "spec_completeness", "contract_compliance", "coverage_threshold", "mutation_threshold", "security_scan", "accessibility_check", "performance_budget", "scope_boundary"]
-      },
-      "minItems": 1,
-      "description": "Quality gates to waive"
-    },
-    "delta": {
-      "type": "object",
-      "description": "Additive budget deltas (only positive values allowed)",
-      "properties": {
-        "max_files": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Additional files allowed"
-        },
-        "max_loc": {
-          "type": "integer",
-          "minimum": 0,
-          "description": "Additional lines of code allowed"
-        }
-      },
-      "additionalProperties": false
-    },
-    "reason_code": {
-      "type": "string",
-      "enum": ["emergency_hotfix", "legacy_integration", "experimental_feature", "third_party_constraint", "performance_critical", "security_patch", "infrastructure_limitation", "architectural_refactor", "other"],
-      "description": "Controlled vocabulary for waiver reasons"
-    },
-    "description": {
-      "type": "string",
-      "minLength": 50,
-      "maxLength": 1000,
-      "description": "Detailed explanation of why waiver is needed"
-    },
-    "mitigation": {
-      "type": "string",
-      "minLength": 50,
-      "description": "Plan to address the underlying issue"
-    },
-    "expires_at": {
-      "type": "string",
-      "format": "date-time",
-      "description": "ISO 8601 datetime when waiver expires"
-    },
-    "risk_owner": {
-      "type": "string",
-      "description": "Person/entity responsible for managing this risk"
-    },
-    "approvers": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["handle"],
-        "properties": {
-          "handle": {
-            "type": "string",
-            "description": "GitHub handle or email of approver"
-          },
-          "approved_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "When this approval was given"
-          }
-        },
-        "additionalProperties": false
-      },
-      "minItems": 1,
-      "description": "List of people who approved this waiver"
-    },
-    "status": {
-      "type": "string",
-      "enum": ["proposed", "active", "expired", "revoked"],
-      "description": "Current status of the waiver"
-    },
-    "metadata": {
-      "type": "object",
-      "properties": {
-        "related_pr": { "type": "string" },
-        "related_issue": { "type": "string" },
-        "environment": { "type": "string", "enum": ["development", "staging", "production"] },
-        "urgency": { "type": "string", "enum": ["low", "normal", "high", "critical"] }
-      },
-      "additionalProperties": false
-    }
-  },
-  "additionalProperties": false
-}