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

package/dist/core/logger.js

@@ -0,0 +1,221 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Log level priority for filtering
+ */
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Rolling file logger for ai-sdlc operations
+ *
+ * Features:
+ * - JSON Lines format (one JSON object per line)
+ * - Rolling by size (configurable, default 10MB)
+ * - Retains last N files (configurable, default 5)
+ * - Location: .ai-sdlc/logs/ai-sdlc-YYYY-MM-DD.log
+ */
+export class Logger {
+    projectRoot;
+    config;
+    logDir;
+    currentLogFile = null;
+    constructor(projectRoot, config) {
+        this.projectRoot = projectRoot;
+        this.config = config;
+        this.logDir = path.join(projectRoot, '.ai-sdlc', 'logs');
+        if (this.config.enabled) {
+            this.ensureLogDirectory();
+        }
+    }
+    /**
+     * Ensure the log directory exists
+     */
+    ensureLogDirectory() {
+        if (!fs.existsSync(this.logDir)) {
+            fs.mkdirSync(this.logDir, { recursive: true });
+        }
+    }
+    /**
+     * Get the current log file path based on today's date
+     */
+    getCurrentLogFile() {
+        const today = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+        return path.join(this.logDir, `ai-sdlc-${today}.log`);
+    }
+    /**
+     * Check if the current log file needs rotation based on size
+     */
+    needsRotation(logFile) {
+        if (!fs.existsSync(logFile)) {
+            return false;
+        }
+        const stats = fs.statSync(logFile);
+        const maxSizeBytes = this.config.maxFileSizeMb * 1024 * 1024;
+        return stats.size >= maxSizeBytes;
+    }
+    /**
+     * Rotate the log file by renaming it with a sequence number
+     */
+    rotateLogFile(logFile) {
+        const baseName = path.basename(logFile, '.log');
+        const dir = path.dirname(logFile);
+        // Find the next available sequence number
+        let seq = 1;
+        while (fs.existsSync(path.join(dir, `${baseName}.${seq}.log`))) {
+            seq++;
+        }
+        // Rename current file
+        fs.renameSync(logFile, path.join(dir, `${baseName}.${seq}.log`));
+        // Clean up old files
+        this.cleanupOldFiles();
+    }
+    /**
+     * Remove old log files beyond the retention limit
+     */
+    cleanupOldFiles() {
+        if (!fs.existsSync(this.logDir)) {
+            return;
+        }
+        const files = fs.readdirSync(this.logDir)
+            .filter(f => f.startsWith('ai-sdlc-') && f.endsWith('.log'))
+            .map(f => ({
+            name: f,
+            path: path.join(this.logDir, f),
+            mtime: fs.statSync(path.join(this.logDir, f)).mtime.getTime(),
+        }))
+            .sort((a, b) => b.mtime - a.mtime); // Newest first
+        // Keep only the configured number of files
+        const filesToDelete = files.slice(this.config.maxFiles);
+        for (const file of filesToDelete) {
+            try {
+                fs.unlinkSync(file.path);
+            }
+            catch {
+                // Ignore deletion errors
+            }
+        }
+    }
+    /**
+     * Check if the given level should be logged based on config
+     */
+    shouldLog(level) {
+        if (!this.config.enabled) {
+            return false;
+        }
+        return LOG_LEVEL_PRIORITY[level] >= LOG_LEVEL_PRIORITY[this.config.level];
+    }
+    /**
+     * Write a log entry to the current log file
+     */
+    write(entry) {
+        if (!this.config.enabled) {
+            return;
+        }
+        const logFile = this.getCurrentLogFile();
+        // Check for rotation
+        if (this.needsRotation(logFile)) {
+            this.rotateLogFile(logFile);
+        }
+        // Append log entry as JSON line
+        const line = JSON.stringify(entry) + '\n';
+        fs.appendFileSync(logFile, line, 'utf-8');
+    }
+    /**
+     * Create a log entry with common fields
+     */
+    createEntry(level, category, message, data) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            category,
+            message,
+        };
+        if (data !== undefined) {
+            entry.data = data;
+        }
+        return entry;
+    }
+    /**
+     * Log a debug message
+     */
+    debug(category, message, data) {
+        if (this.shouldLog('debug')) {
+            this.write(this.createEntry('debug', category, message, data));
+        }
+    }
+    /**
+     * Log an info message
+     */
+    info(category, message, data) {
+        if (this.shouldLog('info')) {
+            this.write(this.createEntry('info', category, message, data));
+        }
+    }
+    /**
+     * Log a warning message
+     */
+    warn(category, message, data) {
+        if (this.shouldLog('warn')) {
+            this.write(this.createEntry('warn', category, message, data));
+        }
+    }
+    /**
+     * Log an error message
+     */
+    error(category, message, data) {
+        if (this.shouldLog('error')) {
+            this.write(this.createEntry('error', category, message, data));
+        }
+    }
+    /**
+     * Get the path to the current log file
+     */
+    getLogFilePath() {
+        return this.getCurrentLogFile();
+    }
+    /**
+     * Get all log file paths
+     */
+    getLogFiles() {
+        if (!fs.existsSync(this.logDir)) {
+            return [];
+        }
+        return fs.readdirSync(this.logDir)
+            .filter(f => f.startsWith('ai-sdlc-') && f.endsWith('.log'))
+            .map(f => path.join(this.logDir, f))
+            .sort((a, b) => {
+            const statA = fs.statSync(a);
+            const statB = fs.statSync(b);
+            return statB.mtime.getTime() - statA.mtime.getTime();
+        });
+    }
+}
+// Singleton logger instance
+let globalLogger = null;
+/**
+ * Initialize the global logger instance
+ */
+export function initLogger(projectRoot, config) {
+    globalLogger = new Logger(projectRoot, config);
+    return globalLogger;
+}
+/**
+ * Get the global logger instance (or create a disabled one if not initialized)
+ */
+export function getLogger() {
+    if (!globalLogger) {
+        // Return a disabled logger if not initialized
+        globalLogger = new Logger(process.cwd(), {
+            enabled: false,
+            level: 'info',
+            maxFileSizeMb: 10,
+            maxFiles: 5,
+        });
+    }
+    return globalLogger;
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

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

package/dist/core/story-logger.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { LogLevel } from '../types/index.js';
+/**
+ * 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 declare class StoryLogger {
+    private logStream;
+    private storyId;
+    private logPath;
+    private closed;
+    /**
+     * 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: string, sdlcRoot: string, maxLogs?: number);
+    /**
+     * 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: LogLevel, message: string): void;
+    /**
+     * 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(): Promise<void>;
+    /**
+     * Get the path to the current log file
+     *
+     * @returns Absolute path to the current log file
+     */
+    getLogPath(): string;
+    /**
+     * 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
+     */
+    private sanitizeMessage;
+    /**
+     * 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
+     */
+    private rotateOldLogs;
+}
+/**
+ * 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 declare function getLatestLogPath(sdlcRoot: string, storyId: string): string | null;
+/**
+ * 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 declare function readLastLines(filePath: string, lines?: number): Promise<string>;
+/**
+ * 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 declare function tailLog(filePath: string): void;
+//# sourceMappingURL=story-logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"story-logger.d.ts","sourceRoot":"","sources":["../../src/core/story-logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAkB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAI7D;;;;;;;;GAQG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAkB;IAEhC;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,MAAU;IAwClE;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAwC3C;;;;;;;OAOG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAatB;;;;OAIG;IACH,UAAU,IAAI,MAAM;IAIpB;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IAgBvB;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;CAsBtB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBjF;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAKzF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAiC9C"}

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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"}