ai-sdlc 0.2.0-alpha.2 → 0.2.0-alpha.21

package/dist/core/story.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import matter from 'gray-matter';
+import * as properLockfile from 'proper-lockfile';
 import { FOLDER_TO_STATUS, BLOCKED_DIR, STORIES_FOLDER, STORY_FILENAME, DEFAULT_PRIORITY_GAP } 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,12 +178,45 @@ 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.)
+ * Scans the stories folder to find the highest existing number.
+ *
+ * @param storiesFolder - Path to the stories directory
+ * @returns Sequential story ID like "S-0001"
+ */
+export function generateStoryId(storiesFolder) {
+    let maxNum = 0;
+    if (storiesFolder && fs.existsSync(storiesFolder)) {
+        try {
+            const dirs = fs.readdirSync(storiesFolder, { withFileTypes: true });
+            for (const dir of dirs) {
+                if (!dir.isDirectory())
+                    continue;
+                // Match both S-XXXX format (new) and fall back to checking for any existing
+                const match = dir.name.match(/^S-(\d+)$/);
+                if (match) {
+                    const num = parseInt(match[1], 10);
+                    if (num > maxNum)
+                        maxNum = num;
+                }
+            }
+        }
+        catch {
+            // If we can't read, start from 0
+        }
+    }
+    // Generate next ID with zero-padded 4 digits
+    const nextId = `S-${String(maxNum + 1).padStart(4, '0')}`;
+    return nextId;
 }
 /**
- * Generate a unique story ID
+ * Generate a legacy story ID (for backwards compatibility/fallback)
+ * @deprecated Use generateStoryId() instead
  */
-export function generateStoryId() {
+export function generateLegacyStoryId() {
     const timestamp = Date.now().toString(36);
     const random = Math.random().toString(36).substring(2, 6);
     return `story-${timestamp}-${random}`;
@@ -139,14 +237,14 @@ export function slugify(title) {
  * Creates stories/{id}/story.md with slug and priority in frontmatter.
  * Priority uses gaps (10, 20, 30...) for easy insertion without renumbering.
  */
-export function createStory(title, sdlcRoot, options = {}) {
+export async function createStory(title, sdlcRoot, options = {}) {
     const storiesFolder = path.join(sdlcRoot, STORIES_FOLDER);
     // Validate parent stories/ directory exists
     if (!fs.existsSync(storiesFolder)) {
         throw new Error(`Stories folder does not exist: ${storiesFolder}. Run 'ai-sdlc init' first.`);
     }
     // Generate unique ID and slug
-    const id = generateStoryId();
+    const id = generateStoryId(storiesFolder);
     const slug = slugify(title);
     // Create story folder: stories/{id}/
     const storyFolder = path.join(storiesFolder, id);
@@ -224,22 +322,24 @@ export function createStory(title, sdlcRoot, options = {}) {
         frontmatter,
         content,
     };
-    writeStory(story);
-    return story;
+    await writeStory(story);
+    // Return story with canonical path for consistency
+    const canonicalPath = fs.realpathSync(filePath);
+    return { ...story, path: canonicalPath };
 }
 /**
  * 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) {
@@ -262,13 +362,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 = [];
@@ -285,7 +385,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;
 }
 /**
@@ -306,7 +406,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;
@@ -319,7 +419,7 @@ export function resetPhaseCompletion(story, phase) {
             break;
     }
     story.frontmatter.updated = new Date().toISOString().split('T')[0];
-    writeStory(story);
+    await writeStory(story);
     return story;
 }
 /**
@@ -337,9 +437,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)
@@ -368,18 +468,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;
@@ -390,13 +490,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 = [];
     }
@@ -407,7 +507,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;
 }
 /**
@@ -422,26 +522,115 @@ 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;
 }
 /**
  * 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;
 }
+/**
+ * Get the current implementation retry count for a story
+ */
+export function getImplementationRetryCount(story) {
+    return story.frontmatter.implementation_retry_count || 0;
+}
+/**
+ * Get the effective maximum implementation retries for a story (story-specific or config default)
+ * Story-specific overrides are capped at the upper bound to prevent resource exhaustion
+ */
+export function getEffectiveMaxImplementationRetries(story, config) {
+    const storyMax = story.frontmatter.max_implementation_retries;
+    const configMax = config.implementation.maxRetries;
+    const upperBound = config.implementation.maxRetriesUpperBound;
+    if (storyMax !== undefined) {
+        // Cap story override at upper bound
+        return Math.min(storyMax, upperBound);
+    }
+    return configMax;
+}
+/**
+ * Check if a story has reached its maximum implementation retry limit.
+ * maxRetries represents the number of RETRY attempts allowed after the initial attempt.
+ * So with maxRetries=1, you get 1 initial attempt + 1 retry = 2 total attempts.
+ */
+export function isAtMaxImplementationRetries(story, config) {
+    const currentRetryCount = getImplementationRetryCount(story);
+    const maxRetries = getEffectiveMaxImplementationRetries(story, config);
+    // Infinity means no limit
+    if (!Number.isFinite(maxRetries)) {
+        return false;
+    }
+    // Use > instead of >= because maxRetries is the number of retries allowed,
+    // not the total number of attempts. With maxRetries=1, we allow 1 retry
+    // (so 2 total attempts before being considered "at max").
+    return currentRetryCount > maxRetries;
+}
+/**
+ * Reset implementation retry count to 0
+ */
+export async function resetImplementationRetryCount(story) {
+    story.frontmatter.implementation_retry_count = 0;
+    story.frontmatter.updated = new Date().toISOString().split('T')[0];
+    await writeStory(story);
+    return story;
+}
+/**
+ * Increment the implementation retry count for a 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];
+    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.
@@ -472,6 +661,118 @@ export function sanitizeReasonText(text) {
     }
     return sanitized.trim();
 }
+/**
+ * Find a story by ID using O(1) direct path lookup
+ * Falls back to searching old folder structure for backwards compatibility
+ *
+ * This function is the internal lookup mechanism. Use getStory() for external access.
+ *
+ * @param sdlcRoot - Root directory of the SDLC workspace
+ * @param storyId - Story ID (e.g., 'S-0001')
+ * @returns Story object or null if not found
+ */
+export function findStoryById(sdlcRoot, storyId) {
+    // SECURITY: Validate storyId format (defense-in-depth)
+    // Reject any input that could be used for path traversal
+    if (!storyId ||
+        storyId.includes('..') ||
+        storyId.includes('/') ||
+        storyId.includes('\\') ||
+        path.isAbsolute(storyId)) {
+        return null;
+    }
+    // O(n) directory scan for case-insensitive matching in new architecture
+    // Reads all story directories to find case-insensitive match
+    // Note: fs.realpathSync() does NOT canonicalize casing on macOS, so we must scan
+    const storiesFolder = path.join(sdlcRoot, STORIES_FOLDER);
+    if (fs.existsSync(storiesFolder)) {
+        try {
+            // Read actual directory names from filesystem
+            const directories = fs.readdirSync(storiesFolder, { withFileTypes: true })
+                .filter(dirent => dirent.isDirectory())
+                .map(dirent => dirent.name);
+            // Find directory that matches case-insensitively
+            const actualDirName = directories.find(dir => dir.toLowerCase() === storyId.toLowerCase());
+            if (actualDirName) {
+                // Use the actual directory name (with correct filesystem casing)
+                const storyPath = path.join(storiesFolder, actualDirName, STORY_FILENAME);
+                if (fs.existsSync(storyPath)) {
+                    const canonicalPath = fs.realpathSync(storyPath);
+                    const story = parseStory(canonicalPath);
+                    return { ...story, path: canonicalPath };
+                }
+            }
+        }
+        catch (err) {
+            // If reading directory fails, fall through to fallback search
+        }
+    }
+    // Fallback: search old folder structure for backwards compatibility
+    // Search kanban folders first
+    const KANBAN_FOLDERS = ['backlog', 'ready', 'in-progress', 'done'];
+    for (const folder of KANBAN_FOLDERS) {
+        const folderPath = path.join(sdlcRoot, folder);
+        if (!fs.existsSync(folderPath)) {
+            continue;
+        }
+        const files = fs.readdirSync(folderPath).filter(f => f.endsWith('.md'));
+        for (const file of files) {
+            const filePath = path.join(folderPath, file);
+            try {
+                const canonicalPath = fs.realpathSync(filePath);
+                const story = parseStory(canonicalPath);
+                // Case-insensitive comparison to match input
+                if (story.frontmatter.id?.toLowerCase() === storyId.toLowerCase()) {
+                    return { ...story, path: canonicalPath };
+                }
+            }
+            catch (err) {
+                continue;
+            }
+        }
+    }
+    // Also search blocked folder
+    const blockedFolder = path.join(sdlcRoot, BLOCKED_DIR);
+    if (fs.existsSync(blockedFolder)) {
+        const blockedFiles = fs.readdirSync(blockedFolder).filter(f => f.endsWith('.md'));
+        for (const file of blockedFiles) {
+            const filePath = path.join(blockedFolder, file);
+            try {
+                const canonicalPath = fs.realpathSync(filePath);
+                const story = parseStory(canonicalPath);
+                // Case-insensitive comparison to match input
+                if (story.frontmatter.id?.toLowerCase() === storyId.toLowerCase()) {
+                    return { ...story, path: canonicalPath };
+                }
+            }
+            catch (err) {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Retrieves a story by ID, resolving its current location across all folders.
+ * This is the single source of truth for story lookup - use this instead of
+ * directly calling parseStory() with cached paths.
+ *
+ * @param sdlcRoot - Root directory of the SDLC workspace
+ * @param storyId - Story ID (e.g., 'S-0001')
+ * @returns Fully parsed Story object with current path and metadata
+ * @throws Error if story ID not found in any folder
+ */
+export function getStory(sdlcRoot, storyId) {
+    const story = findStoryById(sdlcRoot, storyId);
+    if (!story) {
+        const newStructurePath = path.join(sdlcRoot, STORIES_FOLDER, storyId, STORY_FILENAME);
+        throw new Error(`Story not found: ${storyId}\n` +
+            `Searched in: ${newStructurePath}\n` +
+            `Also searched old folder structure (backlog, in-progress, done, blocked).\n` +
+            `The story may have been deleted or the ID is incorrect.`);
+    }
+    return story;
+}
 /**
  * Unblock a story and set status back to in-progress
  * In the new architecture, this only updates frontmatter - file path remains unchanged
@@ -481,29 +782,9 @@ export function sanitizeReasonText(text) {
  * @param options - Optional configuration { resetRetries?: boolean }
  * @returns The unblocked story
  */
-export function unblockStory(storyId, sdlcRoot, options) {
-    // In new architecture, try direct path lookup first
-    const storyPath = path.join(sdlcRoot, STORIES_FOLDER, storyId, STORY_FILENAME);
-    let foundStory = null;
-    if (fs.existsSync(storyPath)) {
-        // Found in new structure
-        foundStory = parseStory(storyPath);
-    }
-    else {
-        // Fallback: search for story in old blocked folder (backwards compatibility)
-        const blockedFolder = path.join(sdlcRoot, BLOCKED_DIR);
-        if (fs.existsSync(blockedFolder)) {
-            const blockedFiles = fs.readdirSync(blockedFolder).filter(f => f.endsWith('.md'));
-            for (const file of blockedFiles) {
-                const filePath = path.join(blockedFolder, file);
-                const story = parseStory(filePath);
-                if (story.frontmatter.id === storyId) {
-                    foundStory = story;
-                    break;
-                }
-            }
-        }
-    }
+export async function unblockStory(storyId, sdlcRoot, options) {
+    // Use the centralized getStory() function for lookup
+    const foundStory = findStoryById(sdlcRoot, storyId);
     if (!foundStory) {
         throw new Error(`Story ${storyId} not found`);
     }
@@ -536,7 +817,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