ai-sdlc 0.2.0-alpha.6 → 0.2.0-alpha.60

package/dist/core/story.js

@@ -1,7 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import matter from 'gray-matter';
-import { FOLDER_TO_STATUS, BLOCKED_DIR, STORIES_FOLDER, STORY_FILENAME, DEFAULT_PRIORITY_GAP } from '../types/index.js';
+import * as properLockfile from 'proper-lockfile';
+import { FOLDER_TO_STATUS, BLOCKED_DIR, STORIES_FOLDER, STORY_FILENAME, DEFAULT_PRIORITY_GAP, ReviewDecision } from '../types/index.js';
 /**
  * Parse a story markdown file into a Story object
  *
@@ -37,27 +38,91 @@ export function parseStory(filePath) {
     };
 }
 /**
- * Write a story back to disk
+ * Write a story back to disk with file locking for atomic updates.
+ *
+ * This function acquires an exclusive lock before writing to prevent race conditions
+ * from concurrent processes. The lock is always released, even if an error occurs.
+ *
+ * **IMPORTANT:** Do not nest locks on the same file to avoid deadlock. Batch multiple
+ * updates into a single writeStory() call instead.
+ *
+ * @param story - Story object to write
+ * @param options - Lock options (timeout, retries, stale threshold)
+ * @throws Error if file is locked by another process or filesystem is read-only
+ *
+ * @example
+ * ```typescript
+ * // Good: Batch updates
+ * story.frontmatter.status = 'in-progress';
+ * story.frontmatter.priority = 1;
+ * await writeStory(story);
+ *
+ * // Bad: Nested locks (potential deadlock)
+ * await writeStory(story); // holds lock
+ * await writeStory(story); // tries to acquire same lock = deadlock
+ * ```
  */
-export function writeStory(story) {
+export async function writeStory(story, options) {
     const content = matter.stringify(story.content, story.frontmatter);
-    fs.writeFileSync(story.path, content);
+    // For new files (file doesn't exist yet), write directly without locking
+    // No race condition possible when creating a new file
+    if (!fs.existsSync(story.path)) {
+        fs.writeFileSync(story.path, content);
+        return;
+    }
+    // For existing files, use locking to prevent concurrent write corruption
+    const timeout = options?.lockTimeout ?? 5000;
+    const retries = options?.retries ?? 3;
+    const stale = options?.stale ?? timeout;
+    // Acquire lock with retry logic and exponential backoff
+    let release;
+    try {
+        release = await properLockfile.lock(story.path, {
+            retries: {
+                retries,
+                minTimeout: 100,
+                maxTimeout: 1000,
+            },
+            stale,
+        });
+    }
+    catch (error) {
+        // Handle lock-specific errors with actionable messages
+        if (error.code === 'ELOCKED') {
+            throw new Error(`Story ${story.frontmatter.id || story.path} is locked by another process. ` +
+                `Please retry in a moment or check for hung processes.`);
+        }
+        if (error.code === 'EACCES' || error.code === 'EPERM') {
+            throw new Error(`Cannot create lock file: filesystem is read-only or insufficient permissions. ` +
+                `Ensure ${path.dirname(story.path)} is writable.`);
+        }
+        // ESTALE is handled automatically by proper-lockfile (stale lock removed)
+        throw error;
+    }
+    try {
+        // Critical section: write story to disk
+        fs.writeFileSync(story.path, content);
+    }
+    finally {
+        // Always release lock, even on error
+        await release();
+    }
 }
 /**
  * Update story status in frontmatter without moving files
  * This is the preferred method in the new folder-per-story architecture
  */
-export function updateStoryStatus(story, newStatus) {
+export async function updateStoryStatus(story, newStatus) {
     story.frontmatter.status = newStatus;
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
  * Move a story to a different kanban folder
  * @deprecated Use updateStoryStatus() instead. Will be removed in v2.0
  */
-export function moveStory(story, toFolder, sdlcRoot) {
+export async function moveStory(story, toFolder, sdlcRoot) {
     console.warn('moveStory() is deprecated. Use updateStoryStatus() instead. Will be removed in v2.0');
     const targetFolder = path.join(sdlcRoot, toFolder);
     // Ensure target folder exists
@@ -77,7 +142,7 @@ export function moveStory(story, toFolder, sdlcRoot) {
     // Write to new location
     const oldPath = story.path;
     story.path = newPath;
-    writeStory(story);
+    await writeStory(story);
     // Remove old file
     if (fs.existsSync(oldPath) && oldPath !== newPath) {
         fs.unlinkSync(oldPath);
@@ -91,7 +156,7 @@ export function moveStory(story, toFolder, sdlcRoot) {
  * @param storyPath - Absolute path to the story file
  * @param reason - Reason for blocking (e.g., "Max refinement attempts (2/2) reached")
  */
-export function moveToBlocked(storyPath, reason) {
+export async function moveToBlocked(storyPath, reason) {
     // Security: Validate path BEFORE any file I/O operations
     const resolvedPath = path.resolve(storyPath);
     const storyDir = path.dirname(resolvedPath);
@@ -113,7 +178,7 @@ export function moveToBlocked(storyPath, reason) {
     story.frontmatter.blocked_at = new Date().toISOString();
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
     // Write back to same location
-    writeStory(story);
+    await writeStory(story);
 }
 /**
  * Generate a unique story ID in sequential format (S-0001, S-0002, etc.)
@@ -166,13 +231,86 @@ export function slugify(title) {
         .replace(/^-|-$/g, '')
         .substring(0, 50);
 }
+/**
+ * Sanitize a title string for safe use in file paths and display.
+ * Removes dangerous characters that could be used for injection attacks.
+ *
+ * SECURITY: This function prevents command injection and path traversal through titles.
+ *
+ * @param title - Title string to sanitize
+ * @returns Sanitized title safe for use in paths and commands
+ */
+export function sanitizeTitle(title) {
+    if (!title)
+        return '';
+    let sanitized = title
+        // Remove shell metacharacters that could be used for command injection
+        .replace(/[`$()\\|&;<>]/g, '')
+        // Remove ANSI escape codes (colors, cursor control)
+        .replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '')
+        // Remove OSC sequences (hyperlinks, window titles)
+        .replace(/\x1B\][^\x07]*\x07/g, '')
+        .replace(/\x1B\][^\x1B]*\x1B\\/g, '')
+        // Remove null bytes and control characters
+        .replace(/[\x00-\x1F\x7F-\x9F]/g, '');
+    // Normalize Unicode to prevent homograph attacks
+    sanitized = sanitized.normalize('NFC');
+    // Limit length to prevent storage issues
+    if (sanitized.length > 200) {
+        sanitized = sanitized.substring(0, 200);
+    }
+    return sanitized.trim();
+}
+/**
+ * Extract title from file content using safe parsing.
+ * Priority: YAML frontmatter > H1 heading > null
+ *
+ * SECURITY: Uses regex-only approach to avoid YAML parser vulnerabilities.
+ *
+ * @param content - File content to extract title from
+ * @returns Extracted title or null if not found
+ */
+export function extractTitleFromContent(content) {
+    if (!content || content.trim().length === 0) {
+        return null;
+    }
+    // Try to extract from YAML frontmatter using safe regex (no full YAML parsing)
+    // Match: --- at start, then look for title: field, then --- to close
+    const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---/m);
+    if (frontmatterMatch) {
+        // Look for title: field in the frontmatter block
+        const titleMatch = frontmatterMatch[1].match(/^title:\s*['"]?([^'"\n]+?)['"]?\s*$/m);
+        if (titleMatch && titleMatch[1]) {
+            const title = titleMatch[1].trim();
+            if (title.length > 0) {
+                return sanitizeTitle(title);
+            }
+        }
+    }
+    // Fall back to first H1 heading (# Title)
+    // Use non-greedy matching with length limit to prevent ReDoS
+    const h1Match = content.match(/^#\s+(.{1,200}?)$/m);
+    if (h1Match && h1Match[1]) {
+        const title = h1Match[1].trim();
+        if (title.length > 0) {
+            return sanitizeTitle(title);
+        }
+    }
+    // No title found
+    return null;
+}
 /**
  * Create a new story in the folder-per-story structure
  *
  * Creates stories/{id}/story.md with slug and priority in frontmatter.
  * Priority uses gaps (10, 20, 30...) for easy insertion without renumbering.
+ *
+ * @param title - Story title
+ * @param sdlcRoot - Root path of .ai-sdlc folder
+ * @param options - Optional frontmatter fields
+ * @param content - Optional custom story content (if not provided, uses default template)
  */
-export function createStory(title, sdlcRoot, options = {}) {
+export async function createStory(title, sdlcRoot, options = {}, content) {
     const storiesFolder = path.join(sdlcRoot, STORIES_FOLDER);
     // Validate parent stories/ directory exists
     if (!fs.existsSync(storiesFolder)) {
@@ -228,9 +366,22 @@ export function createStory(title, sdlcRoot, options = {}) {
         plan_complete: false,
         implementation_complete: false,
         reviews_complete: false,
+        // Default content_type to 'code' for backward compatibility
+        // Stories that don't modify src/ should explicitly set content_type: 'configuration' or 'documentation'
+        content_type: 'code',
         ...options,
     };
-    const content = `# ${title}
+    // Use custom content if provided, otherwise use default template
+    let storyContent;
+    if (content) {
+        // Security: Strip dangerous HTML tags from custom content
+        storyContent = content
+            .replace(/<script[^>]*>.*?<\/script>/gis, '')
+            .replace(/<iframe[^>]*>.*?<\/iframe>/gis, '');
+    }
+    else {
+        // Default template
+        storyContent = `# ${title}
 
 ## Summary
 
@@ -251,13 +402,14 @@ export function createStory(title, sdlcRoot, options = {}) {
 ## Review Notes
 
 <!-- Populated by review agents -->`;
+    }
     const story = {
         path: filePath,
         slug,
         frontmatter,
-        content,
+        content: storyContent,
     };
-    writeStory(story);
+    await writeStory(story);
     // Return story with canonical path for consistency
     const canonicalPath = fs.realpathSync(filePath);
     return { ...story, path: canonicalPath };
@@ -265,16 +417,16 @@ export function createStory(title, sdlcRoot, options = {}) {
 /**
  * Update story frontmatter field
  */
-export function updateStoryField(story, field, value) {
+export async function updateStoryField(story, field, value) {
     story.frontmatter[field] = value;
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
  * Append content to a section in the story
  */
-export function appendToSection(story, section, content) {
+export async function appendToSection(story, section, content) {
     const sectionHeader = `## ${section}`;
     const sectionIndex = story.content.indexOf(sectionHeader);
     if (sectionIndex === -1) {
@@ -297,13 +449,13 @@ export function appendToSection(story, section, content) {
                 story.content.substring(insertPoint);
     }
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
  * Record a refinement attempt in the story's frontmatter
  */
-export function recordRefinementAttempt(story, agentType, reviewFeedback) {
+export async function recordRefinementAttempt(story, agentType, reviewFeedback) {
     // Initialize refinement tracking if not present
     if (!story.frontmatter.refinement_iterations) {
         story.frontmatter.refinement_iterations = [];
@@ -320,7 +472,7 @@ export function recordRefinementAttempt(story, agentType, reviewFeedback) {
     story.frontmatter.refinement_iterations.push(refinementRecord);
     story.frontmatter.refinement_count = iteration;
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
@@ -341,7 +493,7 @@ export function canRetryRefinement(story, maxAttempts) {
 /**
  * Reset phase completion flags for rework
  */
-export function resetPhaseCompletion(story, phase) {
+export async function resetPhaseCompletion(story, phase) {
     switch (phase) {
         case 'research':
             story.frontmatter.research_complete = false;
@@ -354,7 +506,7 @@ export function resetPhaseCompletion(story, phase) {
             break;
     }
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
@@ -372,9 +524,9 @@ export function getLatestReviewFeedback(story) {
 /**
  * Append refinement feedback to the story content
  */
-export function appendRefinementNote(story, iteration, feedback) {
+export async function appendRefinementNote(story, iteration, feedback) {
     const refinementNote = `### Refinement Iteration ${iteration}\n\n${feedback}`;
-    return appendToSection(story, 'Review Notes', refinementNote);
+    return await appendToSection(story, 'Review Notes', refinementNote);
 }
 /**
  * Get the effective maximum retries for a story (story-specific or config default)
@@ -403,18 +555,18 @@ export function isAtMaxRetries(story, config, maxIterationsOverride) {
 /**
  * Increment the retry count for a story
  */
-export function incrementRetryCount(story) {
+export async function incrementRetryCount(story) {
     const currentCount = story.frontmatter.retry_count || 0;
     story.frontmatter.retry_count = currentCount + 1;
     story.frontmatter.last_restart_timestamp = new Date().toISOString();
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
  * Reset RPIV cycle for a story (keep research, reset plan/implementation/reviews)
  */
-export function resetRPIVCycle(story, reason) {
+export async function resetRPIVCycle(story, reason) {
     // Keep research_complete as true, reset other flags
     story.frontmatter.plan_complete = false;
     story.frontmatter.implementation_complete = false;
@@ -425,13 +577,13 @@ export function resetRPIVCycle(story, reason) {
     // Increment retry count
     const currentCount = story.frontmatter.retry_count || 0;
     story.frontmatter.retry_count = currentCount + 1;
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
  * Append a review attempt to the story's review history
  */
-export function appendReviewHistory(story, attempt) {
+export async function appendReviewHistory(story, attempt) {
     if (!story.frontmatter.review_history) {
         story.frontmatter.review_history = [];
     }
@@ -442,7 +594,7 @@ export function appendReviewHistory(story, attempt) {
         story.frontmatter.review_history = story.frontmatter.review_history.slice(-10);
     }
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
@@ -457,23 +609,55 @@ export function getLatestReviewAttempt(story) {
 /**
  * Mark a story as complete (all workflow flags set to true)
  */
-export function markStoryComplete(story) {
+export async function markStoryComplete(story) {
     story.frontmatter.research_complete = true;
     story.frontmatter.plan_complete = true;
     story.frontmatter.implementation_complete = true;
     story.frontmatter.reviews_complete = true;
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
+/**
+ * Auto-complete story after review approval
+ * Handles marking story as complete and transitioning to done status
+ *
+ * @param story - The story to auto-complete
+ * @param config - The configuration containing reviewConfig settings
+ * @param reviewResult - The result from the review agent
+ * @returns Updated story if auto-completion occurred, original story otherwise
+ */
+export async function autoCompleteStoryAfterReview(story, config, reviewResult) {
+    // Only auto-complete if review was approved and config allows it
+    if (reviewResult.decision !== ReviewDecision.APPROVED) {
+        return story;
+    }
+    if (!config.reviewConfig.autoCompleteOnApproval) {
+        return story;
+    }
+    try {
+        // Mark all workflow flags as complete
+        story = await markStoryComplete(story);
+        // Update status to done if currently in-progress
+        if (story.frontmatter.status === 'in-progress') {
+            story = await updateStoryStatus(story, 'done');
+        }
+        return story;
+    }
+    catch (error) {
+        // Log error but don't fail the entire review operation
+        console.error('Failed to auto-complete story after review:', error);
+        return story;
+    }
+}
 /**
  * Snapshot max_retries from config to story frontmatter (for mid-cycle config change protection)
  */
-export function snapshotMaxRetries(story, config) {
+export async function snapshotMaxRetries(story, config) {
     if (story.frontmatter.max_retries === undefined) {
         story.frontmatter.max_retries = config.reviewConfig.maxRetries;
         story.frontmatter.updated = new Date().toISOString().split('T')[0];
-        writeStory(story);
+        await writeStory(story);
     }
     return story;
 }
@@ -517,22 +701,91 @@ export function isAtMaxImplementationRetries(story, config) {
 /**
  * Reset implementation retry count to 0
  */
-export function resetImplementationRetryCount(story) {
+export async function resetImplementationRetryCount(story) {
     story.frontmatter.implementation_retry_count = 0;
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
  * Increment the implementation retry count for a story
  */
-export function incrementImplementationRetryCount(story) {
+export async function incrementImplementationRetryCount(story) {
     const currentCount = story.frontmatter.implementation_retry_count || 0;
     story.frontmatter.implementation_retry_count = currentCount + 1;
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
+    return story;
+}
+/**
+ * Global recovery circuit breaker limit
+ */
+const GLOBAL_RECOVERY_LIMIT = 10;
+/**
+ * Get the current total recovery attempts for a story
+ */
+export function getTotalRecoveryAttempts(story) {
+    return story.frontmatter.total_recovery_attempts || 0;
+}
+/**
+ * Check if a story has reached the global recovery limit
+ */
+export function isAtGlobalRecoveryLimit(story) {
+    const currentAttempts = getTotalRecoveryAttempts(story);
+    return currentAttempts >= GLOBAL_RECOVERY_LIMIT;
+}
+/**
+ * Increment the total recovery attempts counter for a story
+ */
+export async function incrementTotalRecoveryAttempts(story) {
+    const currentCount = story.frontmatter.total_recovery_attempts || 0;
+    story.frontmatter.total_recovery_attempts = currentCount + 1;
+    story.frontmatter.updated = new Date().toISOString().split('T')[0];
+    await writeStory(story);
+    return story;
+}
+/**
+ * Reset the total recovery attempts counter to 0
+ */
+export async function resetTotalRecoveryAttempts(story) {
+    story.frontmatter.total_recovery_attempts = 0;
+    story.frontmatter.updated = new Date().toISOString().split('T')[0];
+    await writeStory(story);
     return story;
 }
+/**
+ * Sanitize story ID for safe path construction.
+ * Prevents path traversal attacks by rejecting dangerous characters.
+ *
+ * SECURITY: This function is CRITICAL for preventing path traversal vulnerabilities.
+ * Use this before constructing ANY file paths with user-provided story IDs.
+ *
+ * @param storyId - Story ID to sanitize (e.g., 'S-0001')
+ * @returns Sanitized story ID safe for path construction
+ * @throws Error if storyId contains dangerous characters or patterns
+ */
+export function sanitizeStoryId(storyId) {
+    if (!storyId) {
+        throw new Error('Story ID cannot be empty');
+    }
+    // Reject path traversal attempts
+    if (storyId.includes('..')) {
+        throw new Error('Invalid story ID: contains path traversal sequence (..)');
+    }
+    // Reject path separators
+    if (storyId.includes('/') || storyId.includes('\\')) {
+        throw new Error('Invalid story ID: contains path separator');
+    }
+    // Reject absolute paths
+    if (path.isAbsolute(storyId)) {
+        throw new Error('Invalid story ID: cannot be an absolute path');
+    }
+    // Reject control characters and other dangerous characters
+    if (/[\x00-\x1F\x7F]/.test(storyId)) {
+        throw new Error('Invalid story ID: contains control characters');
+    }
+    return storyId;
+}
 /**
  * Sanitize user-controlled text for safe display and storage.
  * Removes ANSI escape sequences, control characters, and potential injection vectors.
@@ -675,6 +928,40 @@ export function getStory(sdlcRoot, storyId) {
     }
     return story;
 }
+/**
+ * Reset workflow state for a story (clear worktree metadata and set status based on completion flags)
+ * Used when cleaning up an existing worktree and restarting from scratch
+ *
+ * @param story - Story to reset
+ * @returns Updated story with cleared worktree metadata and reset status
+ */
+export async function resetWorkflowState(story) {
+    // Clear worktree metadata
+    delete story.frontmatter.worktree_path;
+    delete story.frontmatter.branch;
+    // Determine appropriate status based on completion flags
+    if (story.frontmatter.implementation_complete) {
+        // Implementation complete - ready for review
+        story.frontmatter.status = 'ready';
+    }
+    else if (story.frontmatter.plan_complete) {
+        // Plan complete - ready for implementation
+        story.frontmatter.status = 'ready';
+    }
+    else if (story.frontmatter.research_complete) {
+        // Only research complete - back to backlog
+        story.frontmatter.status = 'backlog';
+    }
+    else {
+        // No phases complete - back to backlog
+        story.frontmatter.status = 'backlog';
+    }
+    // Update timestamp
+    story.frontmatter.updated = new Date().toISOString().split('T')[0];
+    // Write changes to disk
+    await writeStory(story);
+    return story;
+}
 /**
  * Unblock a story and set status back to in-progress
  * In the new architecture, this only updates frontmatter - file path remains unchanged
@@ -684,7 +971,7 @@ export function getStory(sdlcRoot, storyId) {
  * @param options - Optional configuration { resetRetries?: boolean }
  * @returns The unblocked story
  */
-export function unblockStory(storyId, sdlcRoot, options) {
+export async function unblockStory(storyId, sdlcRoot, options) {
     // Use the centralized getStory() function for lookup
     const foundStory = findStoryById(sdlcRoot, storyId);
     if (!foundStory) {
@@ -701,6 +988,7 @@ export function unblockStory(storyId, sdlcRoot, options) {
     if (options?.resetRetries) {
         foundStory.frontmatter.retry_count = 0;
         foundStory.frontmatter.refinement_count = 0;
+        foundStory.frontmatter.total_recovery_attempts = 0;
     }
     // Determine appropriate status based on completion flags
     let newStatus;
@@ -719,7 +1007,7 @@ export function unblockStory(storyId, sdlcRoot, options) {
     foundStory.frontmatter.status = newStatus;
     foundStory.frontmatter.updated = new Date().toISOString().split('T')[0];
     // Write back to same location
-    writeStory(foundStory);
+    await writeStory(foundStory);
     return foundStory;
 }
 //# sourceMappingURL=story.js.map