specweave 2.3.0 → 3.0.1

package/dist/src/validators/format-preservation-validator.js

@@ -1,173 +0,0 @@
-/**
- * Format Preservation Validator
- *
- * Validates sync operations to ensure external items maintain their original format.
- * Prevents unintended modifications to external item titles, descriptions, and ACs.
- *
- * Key validations:
- * - External items (format_preservation=true) → only comments allowed
- * - Internal items (format_preservation=false) → full sync allowed
- * - Title immutability for external items
- * - Description immutability for external items
- * - AC modifications blocked for external items
- *
- * Part of increment 0047-us-task-linkage (T-034C)
- */
-import { consoleLogger } from '../utils/logger.js';
-/**
- * Format Preservation Validator
- *
- * Ensures external items maintain their original format during sync operations.
- */
-export class FormatPreservationValidator {
-    constructor(options = {}) {
-        this.logger = options.logger ?? consoleLogger;
-    }
-    /**
-     * Validate sync operation
-     *
-     * Checks if the proposed sync operation violates format preservation rules.
-     *
-     * Rules:
-     * 1. External items (format_preservation=true) → ONLY comments allowed
-     * 2. Title updates → BLOCKED for external items
-     * 3. Description updates → BLOCKED for external items
-     * 4. AC updates → BLOCKED for external items
-     * 5. Status updates → ALLOWED (external tools control lifecycle)
-     * 6. Comments → ALWAYS ALLOWED
-     *
-     * @param operation - Sync operation to validate
-     * @returns Validation result
-     */
-    validate(operation) {
-        const errors = [];
-        const warnings = [];
-        const blockedFields = [];
-        const allowedFields = [];
-        // Internal items → full sync allowed, no validation needed
-        if (!operation.formatPreservation) {
-            return {
-                valid: true,
-                allowedFields: operation.updates,
-                blockedFields: []
-            };
-        }
-        // External items → validate each field
-        for (const field of operation.updates) {
-            if (this.isBlockedField(field)) {
-                blockedFields.push(field);
-                errors.push(this.getBlockedFieldError(field, operation.usId));
-            }
-            else {
-                allowedFields.push(field);
-            }
-        }
-        // Validate title immutability (if title change proposed)
-        if (operation.proposedTitle && operation.currentTitle) {
-            if (operation.proposedTitle !== operation.currentTitle) {
-                errors.push(`Title immutability violation for ${operation.usId}: ` +
-                    `Cannot change external item title from "${operation.currentTitle}" to "${operation.proposedTitle}"`);
-            }
-        }
-        // Log validation result
-        if (errors.length > 0) {
-            this.logger.warn(`   ⚠️  Format preservation validation failed for ${operation.usId}:`);
-            errors.forEach(err => this.logger.warn(`      - ${err}`));
-        }
-        if (warnings.length > 0) {
-            warnings.forEach(warn => this.logger.warn(`   ⚠️  ${warn}`));
-        }
-        return {
-            valid: errors.length === 0,
-            errors: errors.length > 0 ? errors : undefined,
-            warnings: warnings.length > 0 ? warnings : undefined,
-            allowedFields,
-            blockedFields
-        };
-    }
-    /**
-     * Check if field is blocked for external items
-     */
-    isBlockedField(field) {
-        return FormatPreservationValidator.BLOCKED_FIELDS.has(field.toLowerCase());
-    }
-    /**
-     * Get error message for blocked field
-     */
-    getBlockedFieldError(field, usId) {
-        const fieldName = field.toLowerCase();
-        const suffix = `for ${usId} (external item with format preservation enabled)`;
-        if (fieldName === 'title') {
-            return `Cannot update title ${suffix}. Original title must be preserved.`;
-        }
-        if (['description', 'body', 'overview'].includes(fieldName)) {
-            return `Cannot update description/body ${suffix}. Original description must be preserved.`;
-        }
-        if (['acceptance_criteria', 'acs'].includes(fieldName)) {
-            return `Cannot update acceptance criteria ${suffix}. Original ACs must be preserved.`;
-        }
-        return `Cannot update field "${field}" ${suffix}.`;
-    }
-    /**
-     * Validate batch sync operations
-     *
-     * Validates multiple sync operations and returns results for each.
-     *
-     * @param operations - Array of sync operations
-     * @returns Array of validation results
-     */
-    validateBatch(operations) {
-        return operations.map(op => this.validate(op));
-    }
-    /**
-     * Quick check: Is sync allowed?
-     *
-     * Simplified validation that returns true/false without detailed errors.
-     *
-     * @param formatPreservation - Format preservation flag
-     * @param proposedUpdates - Fields to update
-     * @returns True if sync is allowed
-     */
-    isSyncAllowed(formatPreservation, proposedUpdates) {
-        // Internal items → always allowed
-        if (!formatPreservation) {
-            return true;
-        }
-        // External items → check if any blocked fields
-        return !proposedUpdates.some(field => this.isBlockedField(field));
-    }
-    /**
-     * Filter allowed fields from sync operation
-     *
-     * Returns only the fields that are allowed for the given operation.
-     *
-     * @param operation - Sync operation
-     * @returns Array of allowed field names
-     */
-    filterAllowedFields(operation) {
-        if (!operation.formatPreservation) {
-            return operation.updates; // All fields allowed for internal items
-        }
-        // For external items, filter out blocked fields
-        return operation.updates.filter(field => !this.isBlockedField(field));
-    }
-    /**
-     * Get validation summary for logging
-     *
-     * @param result - Validation result
-     * @returns Human-readable summary
-     */
-    getValidationSummary(result) {
-        if (result.valid) {
-            return `✅ Validation passed (${result.allowedFields?.length || 0} fields allowed)`;
-        }
-        const errorCount = result.errors?.length || 0;
-        const warningCount = result.warnings?.length || 0;
-        const blockedCount = result.blockedFields?.length || 0;
-        return `❌ Validation failed: ${errorCount} error(s), ${warningCount} warning(s), ${blockedCount} field(s) blocked`;
-    }
-}
-FormatPreservationValidator.BLOCKED_FIELDS = new Set([
-    'title', 'description', 'acceptance_criteria', 'acs', 'body', 'overview'
-]);
-//# sourceMappingURL=format-preservation-validator.js.map

package/dist/src/validators/format-preservation-validator.js.map

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

package/plugins/specweave/lib/external-sync/README.md

@@ -1,117 +0,0 @@
-# External Sync Shared Templates
-
-Shared utilities and templates for external PM tool integration (GitHub, JIRA, Azure DevOps).
-
-## Overview
-
-This directory contains extracted boilerplate code that is 80-100% identical across all external sync plugins. Using these shared templates reduces code duplication and ensures consistent behavior.
-
-## Contents
-
-### TypeScript Utilities
-
-| File | Purpose | Used By |
-|------|---------|---------|
-| `permission-gate.ts` | Check read/write permissions | All sync commands |
-| `duplicate-detector-base.ts` | 3-phase duplicate protection | GitHub, JIRA, ADO |
-
-### Shell Utilities
-
-| File | Purpose | Used By |
-|------|---------|---------|
-
-## Usage
-
-### Permission Gate
-
-```typescript
-import { checkSyncPermissions } from '../specweave/lib/external-sync/permission-gate.js';
-
-const permissions = checkSyncPermissions(projectRoot, 'GitHub');
-if (!permissions.canWrite) {
-  console.log(permissions.message);
-  return;
-}
-```
-
-### Duplicate Detector
-
-```typescript
-import { DuplicateDetectorBase } from '../specweave/lib/external-sync/duplicate-detector-base.js';
-
-class GitHubDuplicateDetector extends DuplicateDetectorBase<GitHubIssue> {
-  protected async searchExisting(query: SearchQuery): Promise<GitHubIssue[]> {
-    // GitHub-specific implementation
-  }
-
-  protected async closeItem(itemId: string, reason: string): Promise<void> {
-    // GitHub-specific implementation
-  }
-
-  protected getItemId(item: GitHubIssue): string {
-    return item.number.toString();
-  }
-
-  protected getItemTitle(item: GitHubIssue): string {
-    return item.title;
-  }
-}
-```
-
-### Shell Hooks
-
-```bash
-#!/bin/bash
-# Source shared utilities
-SCRIPT_DIR="$(dirname "$0")"
-# (2.0) shell hook helpers were removed; call the Node modules in this directory directly
-
-# Use shared functions
-PROJECT_ROOT=$(find_project_root)
-if ! can_update_external "$PROJECT_ROOT"; then
-  log_warn "External updates disabled"
-  exit 0
-fi
-
-# Initialize circuit breaker
-CIRCUIT_FILE=$(init_circuit_breaker "github")
-if [ "$(is_circuit_open "$CIRCUIT_FILE")" = "true" ]; then
-  log_warn "Circuit breaker open, skipping external sync"
-  exit 0
-fi
-```
-
-## What's Shared vs Tool-Specific
-
-### Shared (in this directory)
-
-- Permission checking logic (100% identical)
-- Circuit breaker pattern (100% identical)
-- File locking mechanism (100% identical)
-- Logging utilities (100% identical)
-- Duplicate detection algorithm (100% identical)
-- Project root detection (100% identical)
-
-### Tool-Specific (remains in each plugin)
-
-- API clients (different REST/GraphQL endpoints)
-- Work item hierarchy mapping (Epic→Story→Task varies by tool)
-- Status mapping (different state machines)
-- Field mapping (custom fields differ)
-- Import handlers (different data structures)
-
-## Adding New External Tools
-
-When adding support for a new PM tool (e.g., Linear, Notion):
-
-1. Create plugin: `plugins/specweave-{tool}/`
-2. Extend `DuplicateDetectorBase` for the tool
-3. Import the Node modules in this directory (no shell helpers in 2.0)
-4. Use `checkSyncPermissions()` in commands
-5. Implement tool-specific API client
-
-## Related
-
-- `plugins/specweave-github/` - GitHub Issues/Projects integration
-- `plugins/specweave-jira/` - JIRA & Confluence integration
-- `plugins/specweave-ado/` - Azure DevOps integration

package/plugins/specweave/lib/external-sync/duplicate-detector-base.js

@@ -1,118 +0,0 @@
-class DuplicateDetectorBase {
-  constructor(toolName) {
-    this.toolName = toolName;
-  }
-  // =========================================================================
-  // PHASE 1: Detection (Before Create)
-  // =========================================================================
-  /**
-   * Check for existing items before creating a new one.
-   * Returns existing items if found, preventing duplicate creation.
-   */
-  async detectBeforeCreate(query) {
-    const existing = await this.searchExisting(query);
-    if (existing.length > 0) {
-      return {
-        hasDuplicates: true,
-        existing,
-        message: this.formatDetectionMessage(existing, query)
-      };
-    }
-    return {
-      hasDuplicates: false,
-      existing: [],
-      message: `No existing ${this.toolName} items found for increment ${query.incrementId}`
-    };
-  }
-  // =========================================================================
-  // PHASE 2: Verification (After Create)
-  // =========================================================================
-  /**
-   * Verify that creation didn't accidentally create duplicates.
-   * Called after a create operation to ensure only expected items exist.
-   */
-  async verifyAfterCreate(query, expectedCount) {
-    const existing = await this.searchExisting(query);
-    const actualCount = existing.length;
-    if (actualCount === expectedCount) {
-      return {
-        success: true,
-        expectedCount,
-        actualCount,
-        duplicates: [],
-        message: `Verification passed: ${actualCount} items as expected`
-      };
-    }
-    if (actualCount > expectedCount) {
-      const duplicates = existing.slice(expectedCount);
-      return {
-        success: false,
-        expectedCount,
-        actualCount,
-        duplicates,
-        message: this.formatVerificationMessage(expectedCount, actualCount, duplicates)
-      };
-    }
-    return {
-      success: false,
-      expectedCount,
-      actualCount,
-      duplicates: [],
-      message: `Warning: Expected ${expectedCount} items but found ${actualCount}`
-    };
-  }
-  // =========================================================================
-  // PHASE 3: Auto-Correction (Close Duplicates)
-  // =========================================================================
-  /**
-   * Automatically close duplicate items.
-   * Called when duplicates are detected to clean them up.
-   */
-  async closeDuplicates(duplicates) {
-    for (const duplicate of duplicates) {
-      const itemId = this.getItemId(duplicate);
-      const title = this.getItemTitle(duplicate);
-      try {
-        await this.closeItem(
-          itemId,
-          `Closed as duplicate by SpecWeave auto-correction`
-        );
-        console.log(`\u2705 Closed duplicate ${this.toolName} item #${itemId}: ${title}`);
-      } catch (error) {
-        console.error(`\u274C Failed to close duplicate #${itemId}: ${error}`);
-      }
-    }
-  }
-  // =========================================================================
-  // Message Formatting (Consistent across tools)
-  // =========================================================================
-  formatDetectionMessage(existing, query) {
-    const itemList = existing.map((item) => `  - #${this.getItemId(item)}: ${this.getItemTitle(item)}`).join("\n");
-    return `
-\u26A0\uFE0F  Existing ${this.toolName} items found for increment ${query.incrementId}:
-
-${itemList}
-
-Options:
-1. Link to existing: Use --link-existing to connect without creating new items
-2. Force create: Use --force to create anyway (not recommended)
-3. Skip: Cancel this operation
-`.trim();
-  }
-  formatVerificationMessage(expected, actual, duplicates) {
-    const itemList = duplicates.map((item) => `  - #${this.getItemId(item)}: ${this.getItemTitle(item)}`).join("\n");
-    return `
-\u26A0\uFE0F  Duplicate ${this.toolName} items detected!
-
-Expected: ${expected} items
-Found: ${actual} items
-Duplicates:
-${itemList}
-
-Auto-correction: These duplicates will be closed automatically.
-`.trim();
-  }
-}
-export {
-  DuplicateDetectorBase
-};

package/plugins/specweave/lib/external-sync/duplicate-detector-base.ts

@@ -1,205 +0,0 @@
-/**
- * Base class for duplicate detection across external PM tools.
- * Implements 3-phase protection identical across GitHub, JIRA, and ADO.
- *
- * Usage:
- *   class GitHubDuplicateDetector extends DuplicateDetectorBase<GitHubIssue> {
- *     async searchExisting(query: SearchQuery): Promise<GitHubIssue[]> { ... }
- *     async closeItem(itemId: string, reason: string): Promise<void> { ... }
- *     getItemId(item: GitHubIssue): string { ... }
- *   }
- */
-
-export interface SearchQuery {
-  incrementId: string;
-  title?: string;
-  project?: string;
-  board?: string;
-}
-
-export interface VerificationResult<T> {
-  success: boolean;
-  expectedCount: number;
-  actualCount: number;
-  duplicates: T[];
-  message: string;
-}
-
-export interface DetectionResult<T> {
-  hasDuplicates: boolean;
-  existing: T[];
-  message: string;
-}
-
-/**
- * Abstract base class for duplicate detection.
- * Subclass per external tool (GitHub, JIRA, ADO).
- */
-export abstract class DuplicateDetectorBase<T> {
-  protected toolName: string;
-
-  constructor(toolName: string) {
-    this.toolName = toolName;
-  }
-
-  /**
-   * Search for existing items that might be duplicates.
-   * Implementation is tool-specific (different APIs).
-   */
-  protected abstract searchExisting(query: SearchQuery): Promise<T[]>;
-
-  /**
-   * Close/archive a duplicate item.
-   * Implementation is tool-specific (different APIs).
-   */
-  protected abstract closeItem(itemId: string, reason: string): Promise<void>;
-
-  /**
-   * Get the unique ID of an item.
-   */
-  protected abstract getItemId(item: T): string;
-
-  /**
-   * Get the title/summary of an item for display.
-   */
-  protected abstract getItemTitle(item: T): string;
-
-  // =========================================================================
-  // PHASE 1: Detection (Before Create)
-  // =========================================================================
-
-  /**
-   * Check for existing items before creating a new one.
-   * Returns existing items if found, preventing duplicate creation.
-   */
-  async detectBeforeCreate(query: SearchQuery): Promise<DetectionResult<T>> {
-    const existing = await this.searchExisting(query);
-
-    if (existing.length > 0) {
-      return {
-        hasDuplicates: true,
-        existing,
-        message: this.formatDetectionMessage(existing, query)
-      };
-    }
-
-    return {
-      hasDuplicates: false,
-      existing: [],
-      message: `No existing ${this.toolName} items found for increment ${query.incrementId}`
-    };
-  }
-
-  // =========================================================================
-  // PHASE 2: Verification (After Create)
-  // =========================================================================
-
-  /**
-   * Verify that creation didn't accidentally create duplicates.
-   * Called after a create operation to ensure only expected items exist.
-   */
-  async verifyAfterCreate(
-    query: SearchQuery,
-    expectedCount: number
-  ): Promise<VerificationResult<T>> {
-    const existing = await this.searchExisting(query);
-    const actualCount = existing.length;
-
-    if (actualCount === expectedCount) {
-      return {
-        success: true,
-        expectedCount,
-        actualCount,
-        duplicates: [],
-        message: `Verification passed: ${actualCount} items as expected`
-      };
-    }
-
-    if (actualCount > expectedCount) {
-      const duplicates = existing.slice(expectedCount);
-      return {
-        success: false,
-        expectedCount,
-        actualCount,
-        duplicates,
-        message: this.formatVerificationMessage(expectedCount, actualCount, duplicates)
-      };
-    }
-
-    // Fewer items than expected (unlikely but possible)
-    return {
-      success: false,
-      expectedCount,
-      actualCount,
-      duplicates: [],
-      message: `Warning: Expected ${expectedCount} items but found ${actualCount}`
-    };
-  }
-
-  // =========================================================================
-  // PHASE 3: Auto-Correction (Close Duplicates)
-  // =========================================================================
-
-  /**
-   * Automatically close duplicate items.
-   * Called when duplicates are detected to clean them up.
-   */
-  async closeDuplicates(duplicates: T[]): Promise<void> {
-    for (const duplicate of duplicates) {
-      const itemId = this.getItemId(duplicate);
-      const title = this.getItemTitle(duplicate);
-
-      try {
-        await this.closeItem(
-          itemId,
-          `Closed as duplicate by SpecWeave auto-correction`
-        );
-        console.log(`✅ Closed duplicate ${this.toolName} item #${itemId}: ${title}`);
-      } catch (error) {
-        console.error(`❌ Failed to close duplicate #${itemId}: ${error}`);
-      }
-    }
-  }
-
-  // =========================================================================
-  // Message Formatting (Consistent across tools)
-  // =========================================================================
-
-  private formatDetectionMessage(existing: T[], query: SearchQuery): string {
-    const itemList = existing
-      .map(item => `  - #${this.getItemId(item)}: ${this.getItemTitle(item)}`)
-      .join('\n');
-
-    return `
-⚠️  Existing ${this.toolName} items found for increment ${query.incrementId}:
-
-${itemList}
-
-Options:
-1. Link to existing: Use --link-existing to connect without creating new items
-2. Force create: Use --force to create anyway (not recommended)
-3. Skip: Cancel this operation
-`.trim();
-  }
-
-  private formatVerificationMessage(
-    expected: number,
-    actual: number,
-    duplicates: T[]
-  ): string {
-    const itemList = duplicates
-      .map(item => `  - #${this.getItemId(item)}: ${this.getItemTitle(item)}`)
-      .join('\n');
-
-    return `
-⚠️  Duplicate ${this.toolName} items detected!
-
-Expected: ${expected} items
-Found: ${actual} items
-Duplicates:
-${itemList}
-
-Auto-correction: These duplicates will be closed automatically.
-`.trim();
-  }
-}

package/plugins/specweave/lib/external-sync/permission-gate.js

@@ -1,64 +0,0 @@
-import { existsSync, readFileSync } from "fs";
-import { join } from "path";
-function checkSyncPermissions(projectRoot, toolName) {
-  const configPath = join(projectRoot, ".specweave", "config.json");
-  const result = {
-    canRead: true,
-    canWrite: false,
-    message: "",
-    configPath
-  };
-  if (!existsSync(configPath)) {
-    result.message = `Config not found at ${configPath}`;
-    return result;
-  }
-  try {
-    const config = JSON.parse(readFileSync(configPath, "utf-8"));
-    result.canWrite = config?.sync?.settings?.canUpdateExternalItems ?? false;
-    if (!result.canWrite) {
-      result.message = formatPermissionDeniedMessage(toolName);
-    }
-  } catch {
-    result.message = `Failed to read config at ${configPath}`;
-  }
-  return result;
-}
-function formatPermissionDeniedMessage(toolName) {
-  const toolLower = toolName.toLowerCase().replace(/\s+/g, "-");
-  return `
-\u274C Permission Denied: ${toolName} Write Operations Disabled
-
-Cannot push changes to ${toolName} (sync.settings.canUpdateExternalItems = false).
-
-Options:
-1. Enable writes: Set canUpdateExternalItems to true in config.json
-   {
-     "sync": {
-       "settings": {
-         "canUpdateExternalItems": true
-       }
-     }
-   }
-
-2. Pull-only mode: sw-${toolLower}:sync \${incrementId} --direction from-${toolLower}
-
-3. View status: sw-${toolLower}:status \${incrementId}
-`.trim();
-}
-function isSyncEnabled(projectRoot) {
-  const configPath = join(projectRoot, ".specweave", "config.json");
-  if (!existsSync(configPath)) {
-    return false;
-  }
-  try {
-    const config = JSON.parse(readFileSync(configPath, "utf-8"));
-    return config?.sync?.enabled !== false;
-  } catch {
-    return false;
-  }
-}
-export {
-  checkSyncPermissions,
-  formatPermissionDeniedMessage,
-  isSyncEnabled
-};