@paths.design/caws-cli 5.0.1 → 5.1.0

package/dist/utils/async-utils.js

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Async Operation Utilities
+ * Provides consistent patterns for async operations, parallel execution, and resource cleanup
+ * @author @darianrosebrook
+ */
+
+/**
+ * Execute multiple async operations in parallel
+ * @param {Array<Promise>} promises - Array of promises to execute
+ * @param {Object} options - Options
+ * @param {boolean} [options.failFast=true] - Stop on first error
+ * @returns {Promise<Array>} Array of results
+ */
+async function parallel(promises, options = {}) {
+  const { failFast = true } = options;
+
+  if (failFast) {
+    return Promise.all(promises);
+  } else {
+    // Wait for all promises, collecting both successes and failures
+    return Promise.allSettled(promises).then((results) => {
+      return results.map((result) => {
+        if (result.status === 'fulfilled') {
+          return { success: true, value: result.value };
+        } else {
+          return { success: false, error: result.reason };
+        }
+      });
+    });
+  }
+}
+
+/**
+ * Execute async operations sequentially
+ * @param {Array<Function>} operations - Array of async functions to execute
+ * @param {Object} options - Options
+ * @param {boolean} [options.stopOnError=true] - Stop on first error
+ * @returns {Promise<Array>} Array of results
+ */
+async function sequential(operations, options = {}) {
+  const { stopOnError = true } = options;
+  const results = [];
+
+  for (const operation of operations) {
+    try {
+      const result = await operation();
+      results.push({ success: true, value: result });
+    } catch (error) {
+      if (stopOnError) {
+        throw error;
+      }
+      results.push({ success: false, error });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Retry an async operation with exponential backoff
+ * @param {Function} operation - Async function to retry
+ * @param {Object} options - Retry options
+ * @param {number} [options.maxRetries=3] - Maximum number of retries
+ * @param {number} [options.initialDelay=1000] - Initial delay in ms
+ * @param {number} [options.maxDelay=10000] - Maximum delay in ms
+ * @param {Function} [options.shouldRetry] - Function to determine if error should be retried
+ * @returns {Promise<any>} Operation result
+ */
+async function retry(operation, options = {}) {
+  const {
+    maxRetries = 3,
+    initialDelay = 1000,
+    maxDelay = 10000,
+    shouldRetry = () => true,
+  } = options;
+
+  let lastError;
+  let delay = initialDelay;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt === maxRetries || !shouldRetry(error)) {
+        throw error;
+      }
+
+      // Wait before retrying with exponential backoff
+      // eslint-disable-next-line no-undef
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      delay = Math.min(delay * 2, maxDelay);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * Execute operation with timeout
+ * @param {Promise} promise - Promise to execute
+ * @param {number} timeoutMs - Timeout in milliseconds
+ * @param {string} [errorMessage] - Custom error message
+ * @returns {Promise<any>} Operation result
+ */
+async function withTimeout(promise, timeoutMs, errorMessage = 'Operation timed out') {
+  const timeoutPromise = new Promise((_, reject) => {
+    // eslint-disable-next-line no-undef
+    setTimeout(() => {
+      reject(new Error(`${errorMessage} (${timeoutMs}ms)`));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]);
+}
+
+/**
+ * Execute operation with resource cleanup
+ * @param {Function} operation - Async operation to execute
+ * @param {Function} cleanup - Cleanup function (called in finally)
+ * @returns {Promise<any>} Operation result
+ */
+async function withCleanup(operation, cleanup) {
+  try {
+    return await operation();
+  } finally {
+    await cleanup();
+  }
+}
+
+/**
+ * Execute multiple operations and collect all errors
+ * @param {Array<Function>} operations - Array of async functions
+ * @returns {Promise<{successes: Array, errors: Array}>} Results and errors
+ */
+async function collectResults(operations) {
+  const results = await Promise.allSettled(
+    operations.map((op) => op())
+  );
+
+  const successes = [];
+  const errors = [];
+
+  results.forEach((result, index) => {
+    if (result.status === 'fulfilled') {
+      successes.push({ index, value: result.value });
+    } else {
+      errors.push({ index, error: result.reason });
+    }
+  });
+
+  return { successes, errors };
+}
+
+/**
+ * Execute operation with cancellation support
+ * @param {Function} operation - Async operation to execute
+ * @param {AbortSignal} signal - Abort signal for cancellation
+ * @returns {Promise<any>} Operation result
+ */
+async function withCancellation(operation, signal) {
+  if (signal.aborted) {
+    throw new Error('Operation cancelled');
+  }
+
+  return new Promise((resolve, reject) => {
+    signal.addEventListener('abort', () => {
+      reject(new Error('Operation cancelled'));
+    });
+
+    operation()
+      .then(resolve)
+      .catch(reject);
+  });
+}
+
+module.exports = {
+  parallel,
+  sequential,
+  retry,
+  withTimeout,
+  withCleanup,
+  collectResults,
+  withCancellation,
+};
+
+

package/dist/utils/command-wrapper.js

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview Unified Command Wrapper
+ * Provides consistent error handling and output formatting for all CLI commands
+ * @author @darianrosebrook
+ */
+
+const { safeAsync, handleCliError, outputResult, isJsonOutput } = require('../error-handler');
+const chalk = require('chalk');
+
+/**
+ * Unified command wrapper that provides:
+ * - Consistent error handling
+ * - Standardized output formatting
+ * - Execution timing
+ * - JSON output support
+ *
+ * @param {Function} commandFn - Async command function to execute
+ * @param {Object} options - Command options
+ * @param {string} options.commandName - Name of the command (for error context)
+ * @param {boolean} [options.includeTiming=true] - Include execution timing
+ * @param {boolean} [options.exitOnError=true] - Exit process on error
+ * @param {Object} [options.context={}] - Additional context for error handling
+ * @returns {Promise<any>} Command result
+ */
+async function commandWrapper(commandFn, options = {}) {
+  const {
+    commandName = 'command',
+    includeTiming = true,
+    exitOnError = true,
+    context = {},
+  } = options;
+
+  return safeAsync(
+    async () => {
+      try {
+        const result = await commandFn();
+        return result;
+      } catch (error) {
+        // Enhance error with command context
+        error.commandName = commandName;
+        error.context = { ...context, ...error.context };
+
+        // Handle error with unified handler
+        handleCliError(
+          error,
+          {
+            command: commandName,
+            ...context,
+          },
+          exitOnError
+        );
+
+        // If exitOnError is false, rethrow for caller to handle
+        if (!exitOnError) {
+          throw error;
+        }
+      }
+    },
+    commandName,
+    includeTiming
+  );
+}
+
+/**
+ * Unified output utilities for consistent formatting
+ */
+const Output = {
+  /**
+   * Output success message
+   * @param {string} message - Success message
+   * @param {Object} [data] - Additional data to output
+   */
+  success(message, data = {}) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          success: true,
+          message,
+          ...data,
+        },
+        true
+      );
+    } else {
+      console.log(chalk.green(`✅ ${message}`));
+      if (Object.keys(data).length > 0 && !isJsonOutput()) {
+        console.log(chalk.gray(JSON.stringify(data, null, 2)));
+      }
+    }
+  },
+
+  /**
+   * Output error message
+   * @param {string} message - Error message
+   * @param {string[]} [suggestions] - Recovery suggestions
+   */
+  error(message, suggestions = []) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          success: false,
+          error: {
+            message,
+            suggestions,
+          },
+        },
+        false
+      );
+    } else {
+      console.error(chalk.red(`❌ ${message}`));
+      if (suggestions.length > 0) {
+        console.error(chalk.yellow('\n💡 Suggestions:'));
+        suggestions.forEach((suggestion) => {
+          console.error(chalk.yellow(`   ${suggestion}`));
+        });
+      }
+    }
+  },
+
+  /**
+   * Output warning message
+   * @param {string} message - Warning message
+   * @param {string} [suggestion] - Optional suggestion
+   */
+  warning(message, suggestion = null) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          warning: true,
+          message,
+          suggestion,
+        },
+        true
+      );
+    } else {
+      console.warn(chalk.yellow(`⚠️  ${message}`));
+      if (suggestion) {
+        console.warn(chalk.blue(`   💡 ${suggestion}`));
+      }
+    }
+  },
+
+  /**
+   * Output info message
+   * @param {string} message - Info message
+   * @param {Object} [data] - Additional data
+   */
+  info(message, data = {}) {
+    if (isJsonOutput()) {
+      outputResult(
+        {
+          info: true,
+          message,
+          ...data,
+        },
+        true
+      );
+    } else {
+      console.log(chalk.blue(`ℹ️  ${message}`));
+      if (Object.keys(data).length > 0) {
+        console.log(chalk.gray(JSON.stringify(data, null, 2)));
+      }
+    }
+  },
+
+  /**
+   * Output data in JSON format
+   * @param {Object} data - Data to output
+   * @param {boolean} [success=true] - Whether operation was successful
+   */
+  json(data, success = true) {
+    outputResult(data, success);
+  },
+
+  /**
+   * Output progress message
+   * @param {string} message - Progress message
+   */
+  progress(message) {
+    if (!isJsonOutput()) {
+      console.log(chalk.blue(`🔄 ${message}`));
+    }
+  },
+
+  /**
+   * Output section header
+   * @param {string} title - Section title
+   */
+  section(title) {
+    if (!isJsonOutput()) {
+      console.log(chalk.bold(`\n${title}`));
+      console.log('─'.repeat(Math.min(title.length, 60)));
+    }
+  },
+};
+
+module.exports = {
+  commandWrapper,
+  Output,
+  isJsonOutput,
+};

package/dist/utils/detection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Detect CAWS setup in a directory
+ * @param {string} cwd - Current working directory
+ * @returns {Object} Setup information
+ */
+export function detectCAWSSetup(cwd?: string): any;
+//# sourceMappingURL=detection.d.ts.map

package/dist/utils/detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detection.d.ts","sourceRoot":"","sources":["../../src/utils/detection.js"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,sCAHW,MAAM,OA6JhB"}

package/dist/utils/finalization.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generate provenance manifest and git initialization (for both modes)
+ * @param {string} projectName - Project name
+ * @param {Object} options - Command options
+ * @param {Object} answers - User answers
+ */
+export function finalizeProject(projectName: string, options: any, answers: any): Promise<void>;
+/**
+ * Display success message after project initialization
+ */
+export function continueToSuccess(): void;
+/**
+ * Set dependencies for finalization utilities
+ * @param {Object} deps - Dependencies object
+ */
+export function setFinalizationDependencies(deps: any): void;
+//# sourceMappingURL=finalization.d.ts.map

package/dist/utils/finalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalization.d.ts","sourceRoot":"","sources":["../../src/utils/finalization.js"],"names":[],"mappings":"AA6BA;;;;;GAKG;AACH,6CAJW,MAAM,6CAgKhB;AAED;;GAEG;AACH,0CA0BC;AA1MD;;;GAGG;AACH,6DAGC"}

package/dist/utils/project-analysis.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Detect project type from existing files and structure
+ * @param {string} cwd - Current working directory
+ * @returns {string} Project type
+ */
+export function detectProjectType(cwd?: string): string;
+/**
+ * Detect if current directory appears to be a project that should be initialized directly
+ * @param {string} projectName - Project name from command line
+ * @param {string} currentDir - Current directory path
+ * @returns {boolean} Whether to init in current directory
+ */
+export function shouldInitInCurrentDirectory(projectName: string, currentDir: string): boolean;
+//# sourceMappingURL=project-analysis.d.ts.map

package/dist/utils/project-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-analysis.d.ts","sourceRoot":"","sources":["../../src/utils/project-analysis.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,wCAHW,MAAM,GACJ,MAAM,CAmDlB;AAED;;;;;GAKG;AACH,0DAJW,MAAM,cACN,MAAM,GACJ,OAAO,CA8BnB"}

package/dist/utils/promise-utils.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Promise Utilities
+ * Utilities for converting callback-based APIs to promises
+ * @author @darianrosebrook
+ */
+
+/**
+ * Convert readline question to promise
+ * @param {readline.Interface} rl - Readline interface
+ * @param {string} question - Question to ask
+ * @returns {Promise<string>} User's answer
+ */
+function question(rl, questionText) {
+  return new Promise((resolve) => {
+    rl.question(questionText, (answer) => {
+      resolve(answer);
+    });
+  });
+}
+
+/**
+ * Close readline interface and return promise
+ * @param {readline.Interface} rl - Readline interface
+ * @returns {Promise<void>}
+ */
+function closeReadline(rl) {
+  return new Promise((resolve) => {
+    rl.once('close', resolve);
+    rl.close();
+  });
+}
+
+/**
+ * Create a promise that resolves when event fires
+ * @param {EventEmitter} emitter - Event emitter
+ * @param {string} event - Event name
+ * @param {Object} options - Options
+ * @param {number} [options.timeout] - Timeout in ms
+ * @returns {Promise<any>} Event data
+ */
+function once(emitter, event, options = {}) {
+  return new Promise((resolve, reject) => {
+    const { timeout } = options;
+
+    const timeoutId = timeout
+      ? // eslint-disable-next-line no-undef
+        setTimeout(() => {
+          emitter.removeListener(event, handler);
+          reject(new Error(`Event '${event}' timed out after ${timeout}ms`));
+        }, timeout)
+      : null;
+
+    const handler = (...args) => {
+      if (timeoutId) {
+        // eslint-disable-next-line no-undef
+        clearTimeout(timeoutId);
+      }
+      emitter.removeListener(event, handler);
+      resolve(args.length === 1 ? args[0] : args);
+    };
+
+    emitter.once(event, handler);
+  });
+}
+
+module.exports = {
+  question,
+  closeReadline,
+  once,
+};
+
+

package/dist/utils/quality-gates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Get staged files from git
+ * @returns {string[]} Array of staged file paths
+ */
+export function getStagedFiles(): string[];
+/**
+ * Check for god objects in staged files
+ * @param {string[]} stagedFiles - Array of staged file paths
+ * @param {string} language - Language to check ('rust', 'typescript', etc.)
+ * @returns {Object} God object analysis results
+ */
+export function checkGodObjects(stagedFiles: string[], language?: string): any;
+/**
+ * Check for hidden TODOs in staged files
+ * @param {string[]} stagedFiles - Array of staged file paths
+ * @returns {Object} TODO analysis results
+ */
+export function checkHiddenTodos(stagedFiles: string[]): any;
+/**
+ * Check if a waiver applies to the given gate
+ * @param {string} gate - Gate name to check
+ * @returns {Object} Waiver check result
+ */
+export function checkWaiver(gate: string): any;
+/**
+ * Detect if project is in crisis response mode
+ * @returns {boolean} True if in crisis mode
+ */
+export function detectCrisisMode(): boolean;
+/**
+ * Run comprehensive quality gates on staged files
+ * @param {Object} options - Options for quality gates
+ * @returns {Object} Quality gate results
+ */
+export function runQualityGates(options?: any): any;
+export namespace CONFIG {
+    namespace godObjectThresholds {
+        let warning: number;
+        let critical: number;
+    }
+    let todoConfidenceThreshold: number;
+    let supportedExtensions: string[];
+    namespace crisisResponseThresholds {
+        export let godObjectCritical: number;
+        let todoConfidenceThreshold_1: number;
+        export { todoConfidenceThreshold_1 as todoConfidenceThreshold };
+    }
+}
+//# sourceMappingURL=quality-gates.d.ts.map

package/dist/utils/quality-gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-gates.d.ts","sourceRoot":"","sources":["../../src/utils/quality-gates.js"],"names":[],"mappings":"AAyGA;;;GAGG;AACH,kCAFa,MAAM,EAAE,CAcpB;AAED;;;;;GAKG;AACH,6CAJW,MAAM,EAAE,aACR,MAAM,OAqDhB;AAED;;;;GAIG;AACH,8CAHW,MAAM,EAAE,OA2ClB;AApMD;;;;GAIG;AACH,kCAHW,MAAM,OAiChB;AAED;;;GAGG;AACH,oCAFa,OAAO,CAkCnB;AA6HD;;;;GAIG;AACH,oDAqHC"}

package/dist/utils/spec-resolver.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Resolve spec file path based on priority
+ * @param {Object} options - Resolution options
+ * @param {string} [options.specId] - Feature-specific spec ID (e.g., 'user-auth', 'FEAT-001')
+ * @param {string} [options.specFile] - Explicit file path override
+ * @param {boolean} [options.warnLegacy=true] - Warn when falling back to legacy spec
+ * @param {boolean} [options.interactive=false] - Use interactive spec selection for multiple specs
+ * @returns {Promise<{path: string, type: 'feature' | 'legacy', spec: Object}>}
+ */
+export function resolveSpec(options?: {
+    specId?: string;
+    specFile?: string;
+    warnLegacy?: boolean;
+    interactive?: boolean;
+}): Promise<{
+    path: string;
+    type: "feature" | "legacy";
+    spec: any;
+}>;
+/**
+ * List all available specs
+ * @returns {Promise<Array<{id: string, path: string, type: string}>>}
+ */
+export function listAvailableSpecs(): Promise<Array<{
+    id: string;
+    path: string;
+    type: string;
+}>>;
+/**
+ * Check if project is using multi-spec architecture
+ * @returns {Promise<{isMultiSpec: boolean, specCount: number, needsMigration: boolean}>}
+ */
+export function checkMultiSpecStatus(): Promise<{
+    isMultiSpec: boolean;
+    specCount: number;
+    needsMigration: boolean;
+}>;
+/**
+ * Check for scope conflicts between specs
+ * @param {string[]} specIds - Array of spec IDs to check
+ * @returns {Promise<Array<{spec1: string, spec2: string, conflicts: string[]}>>} Array of conflicts
+ */
+export function checkScopeConflicts(specIds: string[]): Promise<Array<{
+    spec1: string;
+    spec2: string;
+    conflicts: string[];
+}>>;
+/**
+ * Suggest migration from legacy to multi-spec
+ * @returns {Promise<void>}
+ */
+export function suggestMigration(): Promise<void>;
+/**
+ * Interactive spec selection using readline
+ * @param {string[]} specIds - Available spec IDs
+ * @returns {Promise<string>} Selected spec ID
+ */
+export function interactiveSpecSelection(specIds: string[]): Promise<string>;
+/**
+ * Load specs registry
+ * @returns {Promise<Object>} Registry data
+ */
+export function loadSpecsRegistry(): Promise<any>;
+export function suggestFeatureBreakdown(legacySpec: any): {
+    id: string;
+    title: any;
+    criteria: any;
+    scope: {
+        in: string[];
+        out: any[];
+    };
+}[];
+/**
+ * Check if two paths overlap (simplified implementation)
+ * @param {string} path1 - First path
+ * @param {string} path2 - Second path
+ * @returns {boolean} True if paths overlap
+ */
+export function pathsOverlap(path1: string, path2: string): boolean;
+/**
+ * Spec resolution priority:
+ * 1. .caws/specs/<spec-id>.yaml (feature-specific, multi-agent safe)
+ * 2. .caws/working-spec.yaml (legacy, single-agent only)
+ */
+export const SPECS_DIR: ".caws/specs";
+export const LEGACY_SPEC: ".caws/working-spec.yaml";
+export const SPECS_REGISTRY: ".caws/specs/registry.json";
+//# sourceMappingURL=spec-resolver.d.ts.map

package/dist/utils/spec-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/spec-resolver.js"],"names":[],"mappings":"AAwBA;;;;;;;;GAQG;AACH,sCANG;IAAyB,MAAM,GAAvB,MAAM;IACW,QAAQ,GAAzB,MAAM;IACY,UAAU,GAA5B,OAAO;IACW,WAAW,GAA7B,OAAO;CACf,GAAU,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,IAAI,MAAQ;CAAC,CAAC,CAwK7E;AA6BD;;;GAGG;AACH,sCAFa,OAAO,CAAC,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,CAoDpE;AAgDD;;;GAGG;AACH,wCAFa,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAC,CAAC,CAavF;AAED;;;;GAIG;AACH,6CAHW,MAAM,EAAE,GACN,OAAO,CAAC,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAC,CAAC,CAAC,CA2D/E;AA+DD;;;GAGG;AACH,oCAFa,OAAO,CAAC,IAAI,CAAC,CAczB;AA5MD;;;;GAIG;AACH,kDAHW,MAAM,EAAE,GACN,OAAO,CAAC,MAAM,CAAC,CAyC3B;AA/HD;;;GAGG;AACH,qCAFa,OAAO,KAAQ,CAuB3B;AAyQD;;;;;;;;IA+FC;AA/KD;;;;;GAKG;AACH,oCAJW,MAAM,SACN,MAAM,GACJ,OAAO,CAuDnB;AAvcD;;;;GAIG;AACH,wBAAkB,aAAa,CAAC;AAChC,0BAAoB,yBAAyB,CAAC;AAC9C,6BAAuB,2BAA2B,CAAC"}