ai-sdlc 0.2.0-alpha.3 → 0.2.0-alpha.31

package/dist/core/story-logger.js

@@ -0,0 +1,265 @@
+/**
+ * Per-story logging for concurrent execution
+ *
+ * Each story execution creates a new timestamped log file with dual output
+ * (console + file) for debugging and audit trail.
+ */
+import fs from 'fs';
+import path from 'path';
+import { sanitizeStoryId } from './story.js';
+import { STORIES_FOLDER } from '../types/index.js';
+const MAX_MESSAGE_LENGTH = 10 * 1024; // 10KB per log entry
+/**
+ * Per-story logger that writes to timestamped files
+ *
+ * Features:
+ * - Dual output: console + timestamped file per execution
+ * - Automatic log rotation (keeps last N logs per story)
+ * - Crash-safe synchronous writes
+ * - Location: stories/{id}/logs/{timestamp}.log
+ */
+export class StoryLogger {
+    logStream;
+    storyId;
+    logPath;
+    closed = false;
+    /**
+     * Initialize a per-story logger
+     *
+     * @param storyId - Story ID (sanitized automatically)
+     * @param sdlcRoot - Path to .ai-sdlc directory
+     * @param maxLogs - Maximum number of log files to retain per story (default: 5)
+     */
+    constructor(storyId, sdlcRoot, maxLogs = 5) {
+        // SECURITY: Sanitize story ID to prevent path traversal
+        this.storyId = sanitizeStoryId(storyId);
+        const logDir = path.join(sdlcRoot, STORIES_FOLDER, this.storyId, 'logs');
+        // Ensure log directory exists
+        if (!fs.existsSync(logDir)) {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        // Generate timestamp for log filename (ISO 8601 with safe characters)
+        // Split first to remove milliseconds (.000Z), then replace colons
+        const timestamp = new Date()
+            .toISOString()
+            .split('.')[0] // Remove milliseconds: 2026-01-15T10:30:00
+            .replace(/:/g, '-'); // Replace colons: 2026-01-15T10-30-00
+        this.logPath = path.join(logDir, `${timestamp}.log`);
+        // Ensure file exists before creating write stream (createWriteStream may not create immediately)
+        if (!fs.existsSync(this.logPath)) {
+            fs.writeFileSync(this.logPath, '');
+        }
+        // Create write stream in append mode
+        this.logStream = fs.createWriteStream(this.logPath, { flags: 'a' });
+        // Handle stream errors gracefully to prevent uncaught exceptions during cleanup
+        this.logStream.on('error', (err) => {
+            // ENOENT errors during cleanup are expected and can be ignored
+            if (err.code !== 'ENOENT') {
+                console.warn(`Warning: Log stream error: ${err.message}`);
+            }
+        });
+        // Rotate old logs (cleanup happens at initialization, not during writes)
+        this.rotateOldLogs(logDir, maxLogs);
+    }
+    /**
+     * Log a message with specified level
+     *
+     * Writes to both console and file. Sanitizes message to prevent issues
+     * with very long lines or non-printable characters.
+     *
+     * @param level - Log level (INFO, AGENT, ERROR, WARN, DEBUG)
+     * @param message - Message to log
+     */
+    log(level, message) {
+        if (this.closed) {
+            console.warn('Warning: Attempted to log to closed logger');
+            return;
+        }
+        // Sanitize and truncate message
+        const sanitized = this.sanitizeMessage(message);
+        // Format log entry with ISO 8601 timestamp
+        const timestamp = new Date().toISOString();
+        const entry = `[${timestamp}] [${level}] ${sanitized}\n`;
+        // Write to file synchronously (crash-safe)
+        try {
+            this.logStream.write(entry);
+        }
+        catch (error) {
+            // Graceful degradation: if file write fails, continue with console-only
+            console.warn(`Warning: Failed to write to log file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Write to console based on level
+        switch (level) {
+            case 'ERROR':
+                console.error(sanitized);
+                break;
+            case 'WARN':
+                console.warn(sanitized);
+                break;
+            case 'DEBUG':
+                // Only log debug to file, not console (unless explicitly debugging)
+                if (process.env.DEBUG) {
+                    console.log(sanitized);
+                }
+                break;
+            default:
+                console.log(sanitized);
+        }
+    }
+    /**
+     * Close the log stream
+     *
+     * Should be called when story execution completes or on process exit.
+     * Flushes any buffered data and closes the file handle.
+     *
+     * @returns Promise that resolves when the stream is fully closed
+     */
+    close() {
+        return new Promise((resolve) => {
+            if (!this.closed) {
+                this.logStream.end(() => {
+                    this.closed = true;
+                    resolve();
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    /**
+     * Get the path to the current log file
+     *
+     * @returns Absolute path to the current log file
+     */
+    getLogPath() {
+        return this.logPath;
+    }
+    /**
+     * Sanitize log message to prevent issues
+     *
+     * - Truncates messages longer than 10KB
+     * - Strips or escapes non-printable characters (except newlines/tabs)
+     * - Preserves ANSI color codes for console output
+     *
+     * @param message - Raw message to sanitize
+     * @returns Sanitized message
+     */
+    sanitizeMessage(message) {
+        let sanitized = message;
+        // Truncate very long messages
+        if (sanitized.length > MAX_MESSAGE_LENGTH) {
+            sanitized = sanitized.substring(0, MAX_MESSAGE_LENGTH) + '\n... [message truncated]';
+        }
+        // Replace non-printable characters (except newlines, tabs, and ANSI escape codes)
+        // ANSI escape codes start with \x1b[ and are followed by formatting codes
+        // We preserve these for console output (they're stripped when written to most log viewers)
+        sanitized = sanitized.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, '');
+        return sanitized;
+    }
+    /**
+     * Rotate old log files, keeping only the most recent N logs
+     *
+     * Sorting is lexicographic (filename-based) since timestamps are in ISO 8601 format.
+     * Deletes oldest logs beyond the retention limit.
+     *
+     * @param logDir - Directory containing log files
+     * @param keep - Number of logs to retain
+     */
+    rotateOldLogs(logDir, keep) {
+        try {
+            const logs = fs
+                .readdirSync(logDir)
+                .filter((f) => f.endsWith('.log'))
+                .sort()
+                .reverse(); // Newest first (lexicographic sort of ISO 8601 timestamps)
+            // Delete logs beyond the keep limit
+            const toDelete = logs.slice(keep);
+            for (const log of toDelete) {
+                try {
+                    fs.unlinkSync(path.join(logDir, log));
+                }
+                catch {
+                    // Ignore deletion errors (file may have been deleted by another process)
+                }
+            }
+        }
+        catch {
+            // Ignore rotation errors (directory may not exist or be readable)
+            // Rotation is a best-effort cleanup, not critical
+        }
+    }
+}
+/**
+ * Get the latest log file path for a story
+ *
+ * @param sdlcRoot - Path to .ai-sdlc directory
+ * @param storyId - Story ID (sanitized automatically)
+ * @returns Path to latest log file, or null if no logs exist
+ */
+export function getLatestLogPath(sdlcRoot, storyId) {
+    const sanitized = sanitizeStoryId(storyId);
+    const logDir = path.join(sdlcRoot, STORIES_FOLDER, sanitized, 'logs');
+    if (!fs.existsSync(logDir)) {
+        return null;
+    }
+    const logs = fs
+        .readdirSync(logDir)
+        .filter((f) => f.endsWith('.log'))
+        .sort()
+        .reverse(); // Newest first
+    if (logs.length === 0) {
+        return null;
+    }
+    return path.join(logDir, logs[0]);
+}
+/**
+ * Read the last N lines from a log file
+ *
+ * @param filePath - Path to log file
+ * @param lines - Number of lines to read (default: 50)
+ * @returns Last N lines as a string
+ */
+export async function readLastLines(filePath, lines = 50) {
+    const content = await fs.promises.readFile(filePath, 'utf-8');
+    const allLines = content.split('\n').filter((line) => line.trim() !== '');
+    const lastLines = allLines.slice(-lines);
+    return lastLines.join('\n');
+}
+/**
+ * Tail a log file (follow mode, like tail -f)
+ *
+ * Watches the file for changes and outputs new lines as they're written.
+ * Press Ctrl+C to exit.
+ *
+ * @param filePath - Path to log file
+ */
+export function tailLog(filePath) {
+    // Read existing content first
+    const existingContent = fs.readFileSync(filePath, 'utf-8');
+    process.stdout.write(existingContent);
+    // Track current file size
+    let lastSize = existingContent.length;
+    // Watch for changes
+    const watcher = fs.watchFile(filePath, { interval: 100 }, (curr) => {
+        if (curr.size > lastSize) {
+            // File grew - read new content
+            const stream = fs.createReadStream(filePath, {
+                start: lastSize,
+                encoding: 'utf-8',
+            });
+            stream.on('data', (chunk) => {
+                process.stdout.write(chunk);
+            });
+            lastSize = curr.size;
+        }
+    });
+    // Handle Ctrl+C gracefully
+    process.on('SIGINT', () => {
+        fs.unwatchFile(filePath);
+        process.exit(0);
+    });
+    // Keep process alive
+    console.log('\n[Following log file - Press Ctrl+C to exit]');
+}
+//# sourceMappingURL=story-logger.js.map

package/dist/core/story-logger.js.map

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

package/dist/core/story.d.ts

@@ -1,4 +1,4 @@
-import { Story, StoryFrontmatter, StoryStatus, ReviewAttempt, Config } from '../types/index.js';
+import { Story, StoryFrontmatter, StoryStatus, ReviewAttempt, Config, LockOptions } from '../types/index.js';
 /**
  * Parse a story markdown file into a Story object
  *
@@ -7,19 +7,41 @@ import { Story, StoryFrontmatter, StoryStatus, ReviewAttempt, Config } from '../
  */
 export declare function parseStory(filePath: string): Story;
 /**
- * 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 declare function writeStory(story: Story): void;
+export declare function writeStory(story: Story, options?: LockOptions): Promise<void>;
 /**
  * Update story status in frontmatter without moving files
  * This is the preferred method in the new folder-per-story architecture
  */
-export declare function updateStoryStatus(story: Story, newStatus: StoryStatus): Story;
+export declare function updateStoryStatus(story: Story, newStatus: StoryStatus): Promise<Story>;
 /**
  * Move a story to a different kanban folder
  * @deprecated Use updateStoryStatus() instead. Will be removed in v2.0
  */
-export declare function moveStory(story: Story, toFolder: string, sdlcRoot: string): Story;
+export declare function moveStory(story: Story, toFolder: string, sdlcRoot: string): Promise<Story>;
 /**
  * Move a story to blocked status with reason and timestamp
  * In the new architecture, this only updates frontmatter - file path remains unchanged
@@ -27,34 +49,68 @@ export declare function moveStory(story: Story, toFolder: string, sdlcRoot: stri
  * @param storyPath - Absolute path to the story file
  * @param reason - Reason for blocking (e.g., "Max refinement attempts (2/2) reached")
  */
-export declare function moveToBlocked(storyPath: string, reason: string): void;
+export declare function moveToBlocked(storyPath: string, reason: string): Promise<void>;
 /**
- * Generate a unique story ID
+ * 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 declare function generateStoryId(storiesFolder?: string): string;
+/**
+ * Generate a legacy story ID (for backwards compatibility/fallback)
+ * @deprecated Use generateStoryId() instead
  */
-export declare function generateStoryId(): string;
+export declare function generateLegacyStoryId(): string;
 /**
  * Create a slug from a title
  */
 export declare function slugify(title: string): string;
+/**
+ * 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 declare function sanitizeTitle(title: string): string;
+/**
+ * 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 declare function extractTitleFromContent(content: string): string | 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 declare function createStory(title: string, sdlcRoot: string, options?: Partial<StoryFrontmatter>): Story;
+export declare function createStory(title: string, sdlcRoot: string, options?: Partial<StoryFrontmatter>, content?: string): Promise<Story>;
 /**
  * Update story frontmatter field
  */
-export declare function updateStoryField<K extends keyof StoryFrontmatter>(story: Story, field: K, value: StoryFrontmatter[K]): Story;
+export declare function updateStoryField<K extends keyof StoryFrontmatter>(story: Story, field: K, value: StoryFrontmatter[K]): Promise<Story>;
 /**
  * Append content to a section in the story
  */
-export declare function appendToSection(story: Story, section: string, content: string): Story;
+export declare function appendToSection(story: Story, section: string, content: string): Promise<Story>;
 /**
  * Record a refinement attempt in the story's frontmatter
  */
-export declare function recordRefinementAttempt(story: Story, agentType: string, reviewFeedback: string): Story;
+export declare function recordRefinementAttempt(story: Story, agentType: string, reviewFeedback: string): Promise<Story>;
 /**
  * Get the current refinement count for a story
  */
@@ -66,7 +122,7 @@ export declare function canRetryRefinement(story: Story, maxAttempts: number): b
 /**
  * Reset phase completion flags for rework
  */
-export declare function resetPhaseCompletion(story: Story, phase: 'research' | 'plan' | 'implement'): Story;
+export declare function resetPhaseCompletion(story: Story, phase: 'research' | 'plan' | 'implement'): Promise<Story>;
 /**
  * Get the latest review feedback from the story content
  */
@@ -74,7 +130,7 @@ export declare function getLatestReviewFeedback(story: Story): string | null;
 /**
  * Append refinement feedback to the story content
  */
-export declare function appendRefinementNote(story: Story, iteration: number, feedback: string): Story;
+export declare function appendRefinementNote(story: Story, iteration: number, feedback: string): Promise<Story>;
 /**
  * Get the effective maximum retries for a story (story-specific or config default)
  */
@@ -87,15 +143,15 @@ export declare function isAtMaxRetries(story: Story, config: Config, maxIteratio
 /**
  * Increment the retry count for a story
  */
-export declare function incrementRetryCount(story: Story): Story;
+export declare function incrementRetryCount(story: Story): Promise<Story>;
 /**
  * Reset RPIV cycle for a story (keep research, reset plan/implementation/reviews)
  */
-export declare function resetRPIVCycle(story: Story, reason: string): Story;
+export declare function resetRPIVCycle(story: Story, reason: string): Promise<Story>;
 /**
  * Append a review attempt to the story's review history
  */
-export declare function appendReviewHistory(story: Story, attempt: ReviewAttempt): Story;
+export declare function appendReviewHistory(story: Story, attempt: ReviewAttempt): Promise<Story>;
 /**
  * Get the latest review attempt from a story's history
  */
@@ -103,17 +159,74 @@ export declare function getLatestReviewAttempt(story: Story): ReviewAttempt | nu
 /**
  * Mark a story as complete (all workflow flags set to true)
  */
-export declare function markStoryComplete(story: Story): Story;
+export declare function markStoryComplete(story: Story): Promise<Story>;
 /**
  * Snapshot max_retries from config to story frontmatter (for mid-cycle config change protection)
  */
-export declare function snapshotMaxRetries(story: Story, config: Config): Story;
+export declare function snapshotMaxRetries(story: Story, config: Config): Promise<Story>;
+/**
+ * Get the current implementation retry count for a story
+ */
+export declare function getImplementationRetryCount(story: Story): number;
+/**
+ * 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 declare function getEffectiveMaxImplementationRetries(story: Story, config: Config): number;
+/**
+ * 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 declare function isAtMaxImplementationRetries(story: Story, config: Config): boolean;
+/**
+ * Reset implementation retry count to 0
+ */
+export declare function resetImplementationRetryCount(story: Story): Promise<Story>;
+/**
+ * Increment the implementation retry count for a story
+ */
+export declare function incrementImplementationRetryCount(story: Story): Promise<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 declare function sanitizeStoryId(storyId: string): string;
 /**
  * Sanitize user-controlled text for safe display and storage.
  * Removes ANSI escape sequences, control characters, and potential injection vectors.
  * Truncates to 200 characters maximum.
  */
 export declare function sanitizeReasonText(text: string): string;
+/**
+ * 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 declare function findStoryById(sdlcRoot: string, storyId: string): Story | 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 declare function getStory(sdlcRoot: string, storyId: string): Story;
 /**
  * Unblock a story and set status back to in-progress
  * In the new architecture, this only updates frontmatter - file path remains unchanged
@@ -125,5 +238,5 @@ export declare function sanitizeReasonText(text: string): string;
  */
 export declare function unblockStory(storyId: string, sdlcRoot: string, options?: {
     resetRetries?: boolean;
-}): Story;
+}): Promise<Story>;
 //# sourceMappingURL=story.d.ts.map

package/dist/core/story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/core/story.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../src/core/story.ts"],"names":[],"mappings":"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"}