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

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,11 +49,20 @@ 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 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 unique story ID
+ * 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
  */
@@ -42,19 +73,19 @@ export declare function slugify(title: string): string;
  * Creates stories/{id}/story.md with slug and priority in frontmatter.
  * Priority uses gaps (10, 20, 30...) for easy insertion without renumbering.
  */
-export declare function createStory(title: string, sdlcRoot: string, options?: Partial<StoryFrontmatter>): Story;
+export declare function createStory(title: string, sdlcRoot: string, options?: Partial<StoryFrontmatter>): 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 +97,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 +105,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 +118,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 +134,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 +213,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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"}