ai-sdlc 0.2.0-alpha.5 → 0.2.0-alpha.51

package/dist/agents/refinement.js

@@ -1,5 +1,6 @@
 import { parseStory, writeStory, updateStoryStatus } from '../core/story.js';
 import { runAgentQuery } from '../core/client.js';
+import { getLogger } from '../core/logger.js';
 import path from 'path';
 const REFINEMENT_SYSTEM_PROMPT = `You are a product refinement specialist. Your job is to take raw story ideas from the backlog and transform them into well-defined, actionable user stories.
 
@@ -22,8 +23,14 @@ At the end of your response, include:
  * ready-to-implement user story.
  */
 export async function runRefinementAgent(storyPath, sdlcRoot, options = {}) {
+    const logger = getLogger();
+    const startTime = Date.now();
     const story = parseStory(storyPath);
     const changesMade = [];
+    logger.info('refinement', 'Starting refinement phase', {
+        storyId: story.frontmatter.id,
+        status: story.frontmatter.status,
+    });
     try {
         const prompt = `Please refine this story:
 
@@ -65,10 +72,16 @@ Format your response as markdown that will replace the story content.`;
         // Update timestamp
         story.frontmatter.updated = new Date().toISOString().split('T')[0];
         // Write the story
-        writeStory(story);
+        await writeStory(story);
         // Update status to ready
-        const movedStory = updateStoryStatus(story, 'ready');
+        const movedStory = await updateStoryStatus(story, 'ready');
         changesMade.push('Updated status to ready');
+        logger.info('refinement', 'Refinement phase complete', {
+            storyId: story.frontmatter.id,
+            durationMs: Date.now() - startTime,
+            newStatus: 'ready',
+            changesCount: changesMade.length,
+        });
         return {
             success: true,
             story: movedStory,
@@ -76,11 +89,17 @@ Format your response as markdown that will replace the story content.`;
         };
     }
     catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error('refinement', 'Refinement phase failed', {
+            storyId: story.frontmatter.id,
+            durationMs: Date.now() - startTime,
+            error: errorMessage,
+        });
         return {
             success: false,
             story,
             changesMade,
-            error: error instanceof Error ? error.message : String(error),
+            error: errorMessage,
         };
     }
 }

package/dist/agents/refinement.js.map

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

package/dist/agents/research.d.ts

@@ -1,5 +1,5 @@
 import { AgentProgressCallback } from '../core/client.js';
-import { AgentResult } from '../types/index.js';
+import { Story, AgentResult, FARScore } from '../types/index.js';
 export interface AgentOptions {
     /** Context from a previous review failure - must address these issues */
     reworkContext?: string;
@@ -13,4 +13,88 @@ export interface AgentOptions {
  * and gathering relevant information.
  */
 export declare function runResearchAgent(storyPath: string, sdlcRoot: string, options?: AgentOptions): Promise<AgentResult>;
+/**
+ * Gather context about the codebase for research.
+ *
+ * Collects information about:
+ * - Project configuration files (package.json, tsconfig.json, etc.)
+ * - Directory structure
+ * - Source files
+ * - Test files (for understanding testing patterns)
+ * - Configuration files (for discovering config patterns)
+ *
+ * @param sdlcRoot - Path to the .ai-sdlc directory
+ * @returns Formatted context string with codebase information
+ */
+export declare function gatherCodebaseContext(sdlcRoot: string): Promise<string>;
+/**
+ * Determine if web research would add value based on story content and codebase context.
+ *
+ * Web research is triggered when:
+ * 1. External dependencies are referenced (libraries, APIs, frameworks)
+ * 2. Unfamiliar APIs/patterns are mentioned
+ * 3. Library-specific documentation is needed
+ * 4. Best practices are requested
+ *
+ * Web research is skipped when:
+ * - Topic is purely internal (refactoring, moving code, internal utilities)
+ * - No external dependencies mentioned
+ */
+export declare function shouldPerformWebResearch(story: Story, codebaseContext: string): boolean;
+/**
+ * Sanitize web research content for safe storage and display.
+ * Removes ANSI escape sequences, control characters, and potential injection vectors.
+ *
+ * Security rationale: Web research content comes from external sources (LLM, web tools)
+ * and must be sanitized before storage to prevent:
+ * - ANSI injection (terminal control sequence attacks)
+ * - Markdown injection (malicious formatting)
+ * - Control character injection (null bytes, bell characters, etc.)
+ *
+ * @param text - Raw web research content from external source
+ * @returns Sanitized text safe for storage in markdown files
+ */
+export declare function sanitizeWebResearchContent(text: string): string;
+/**
+ * Sanitize text for logging to prevent log injection attacks.
+ * Replaces newlines with spaces and truncates for readability.
+ *
+ * Security rationale: Log injection attacks use newlines to inject fake log entries.
+ * By replacing newlines with spaces, we ensure each log() call produces exactly one log line.
+ *
+ * @param text - Raw text that will be logged
+ * @returns Sanitized text safe for logging (single line, truncated)
+ */
+export declare function sanitizeForLogging(text: string): string;
+/**
+ * Sanitize codebase context before including in LLM prompts.
+ * Escapes dangerous patterns that could cause prompt injection.
+ *
+ * Security rationale: Codebase files may contain malicious content from:
+ * - Compromised dependencies
+ * - Malicious commits
+ * - Untrusted contributors
+ *
+ * We must prevent prompt injection by escaping patterns that could:
+ * - Terminate the prompt early (triple backticks)
+ * - Inject commands or instructions
+ * - Confuse the LLM's understanding of structure
+ *
+ * @param text - Raw codebase context
+ * @returns Sanitized text safe for LLM prompts
+ */
+export declare function sanitizeCodebaseContext(text: string): string;
+/**
+ * Parse FAR evaluation from web research finding text.
+ * Expected format from LLM:
+ * **FAR Score**: Factuality: 5, Actionability: 4, Relevance: 5
+ * **Justification**: Official documentation provides...
+ *
+ * Returns default scores (2, 2, 2) with parsingSucceeded: false if parsing fails.
+ * Default of 2 (rather than 3) indicates uncertainty rather than average quality.
+ *
+ * @param finding - Web research finding text to parse
+ * @returns FARScore with parsed or default values and parsing status
+ */
+export declare function evaluateFAR(finding: string): FARScore;
 //# sourceMappingURL=research.d.ts.map

package/dist/agents/research.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../../src/agents/research.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAS,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAavD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAsEtB"}
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../../src/agents/research.ts"],"names":[],"mappings":"AAIA,OAAO,EAAiB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAgLjE,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAsGtB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmG7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAiCvF;AAeD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA8B/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA6B5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAuDrD"}