auq-mcp-server 0.1.0

package/dist/session/ResponseFormatter.js

@@ -0,0 +1,130 @@
+/**
+ * Response Formatter
+ *
+ * Formats user answers according to PRD specification for returning to AI models
+ */
+/**
+ * ResponseFormatter - Formats session answers into human-readable text
+ * according to the PRD specification
+ */
+export class ResponseFormatter {
+    /**
+     * Format user answers into PRD-compliant text response
+     *
+     * Format specification:
+     * - Header: "Here are the user's answers:"
+     * - Numbered questions: "1. {prompt}"
+     * - Arrow symbol for answers: "→ {label} — {description}"
+     * - Custom text: "→ Other: '{customText}'"
+     * - Double newline separation between questions
+     *
+     * @param answers - Session answer data containing user responses
+     * @param questions - Original questions asked to the user
+     * @returns Formatted text response ready to send to AI model
+     */
+    static formatUserResponse(answers, questions) {
+        // Validate that we have matching questions and answers
+        if (answers.answers.length === 0) {
+            throw new Error("No answers provided in session");
+        }
+        if (questions.length === 0) {
+            throw new Error("No questions provided");
+        }
+        // Start with header
+        const lines = ["Here are the user's answers:", ""];
+        // Format each question and its answer
+        const formattedQuestions = [];
+        for (let i = 0; i < questions.length; i++) {
+            const question = questions[i];
+            const answer = answers.answers.find((a) => a.questionIndex === i);
+            if (!answer) {
+                // If no answer found for this question, skip it
+                // (This shouldn't happen in normal operation, but handle gracefully)
+                continue;
+            }
+            // Format the question and answer
+            const formattedQA = this.formatQuestion(question, answer, i + 1);
+            formattedQuestions.push(formattedQA);
+        }
+        // Join formatted questions with blank lines between them
+        lines.push(formattedQuestions.join("\n\n"));
+        return lines.join("\n");
+    }
+    /**
+     * Validate that answers match the questions
+     *
+     * @param answers - Session answer data
+     * @param questions - Original questions
+     * @throws Error if validation fails
+     */
+    static validateAnswers(answers, questions) {
+        // Check that we have answers
+        if (!answers || !answers.answers || answers.answers.length === 0) {
+            throw new Error("No answers provided");
+        }
+        // Check that we have questions
+        if (!questions || questions.length === 0) {
+            throw new Error("No questions provided");
+        }
+        // Check each answer references a valid question
+        for (const answer of answers.answers) {
+            if (answer.questionIndex < 0 ||
+                answer.questionIndex >= questions.length) {
+                throw new Error(`Answer references invalid question index: ${answer.questionIndex}`);
+            }
+            // Check that answer has either selectedOption or customText
+            if (!answer.selectedOption && !answer.customText) {
+                throw new Error(`Answer for question ${answer.questionIndex} has neither selectedOption nor customText`);
+            }
+            // If selectedOption is provided, verify it exists in the question's options
+            if (answer.selectedOption) {
+                const question = questions[answer.questionIndex];
+                const optionExists = question.options.some((opt) => opt.label === answer.selectedOption);
+                if (!optionExists) {
+                    throw new Error(`Answer for question ${answer.questionIndex} references non-existent option: ${answer.selectedOption}`);
+                }
+            }
+        }
+    }
+    /**
+     * Format a single question and its answer
+     *
+     * @param question - The question data
+     * @param answer - The user's answer
+     * @param index - Question number (1-indexed for display)
+     * @returns Formatted string for this question/answer pair
+     */
+    static formatQuestion(question, answer, index) {
+        const lines = [];
+        // Add question with number
+        lines.push(`${index}. ${question.prompt}`);
+        // Format the answer
+        if (answer.customText) {
+            // Custom text answer - escape single quotes for display
+            const escapedText = answer.customText.replace(/'/g, "\\'");
+            lines.push(`→ Other: '${escapedText}'`);
+        }
+        else if (answer.selectedOption) {
+            // Selected option - find the option details
+            const option = question.options.find((opt) => opt.label === answer.selectedOption);
+            if (option) {
+                // Format with description if available
+                if (option.description) {
+                    lines.push(`→ ${option.label} — ${option.description}`);
+                }
+                else {
+                    lines.push(`→ ${option.label}`);
+                }
+            }
+            else {
+                // Option not found - shouldn't happen, but handle gracefully
+                lines.push(`→ ${answer.selectedOption}`);
+            }
+        }
+        else {
+            // No answer provided - this shouldn't happen
+            lines.push("→ No answer provided");
+        }
+        return lines.join("\n");
+    }
+}

package/dist/session/SessionManager.js

@@ -0,0 +1,474 @@
+/**
+ * SessionManager - Core session management for AskUserQuery MCP server
+ */
+import { promises as fs } from "fs";
+import { join } from "path";
+import { v4 as uuidv4 } from "uuid";
+import { atomicDeleteFile, AtomicReadError, atomicReadFile, AtomicWriteError, atomicWriteFile, } from "./atomic-operations.js";
+import { PromiseFileWatcher } from "./file-watcher.js";
+import { ResponseFormatter } from "./ResponseFormatter.js";
+import { DEFAULT_SESSION_CONFIG, SESSION_FILES } from "./types.js";
+import { createSafeFilename, ensureDirectoryExists, fileExists, getCurrentTimestamp, isTimestampExpired, resolveSessionDirectory, sanitizeSessionId, validateSessionDirectory, } from "./utils.js";
+export class SessionManager {
+    baseDir;
+    config;
+    fileWatcher;
+    sessionsDir;
+    constructor(config = {}) {
+        this.config = {
+            ...DEFAULT_SESSION_CONFIG,
+            ...config,
+        };
+        // Resolve the directory path using XDG-compliant resolution
+        this.baseDir = resolveSessionDirectory(this.config.baseDir);
+        this.sessionsDir = this.baseDir;
+    }
+    /**
+     * Clean up old sessions that have exceeded the retention period (garbage collection)
+     * This is different from session timeout - retention period determines when old
+     * sessions are permanently deleted, regardless of their completion status.
+     */
+    async cleanupExpiredSessions() {
+        try {
+            const sessionIds = await this.getAllSessionIds();
+            let cleanedCount = 0;
+            for (const sessionId of sessionIds) {
+                const status = await this.getSessionStatus(sessionId);
+                if (status && this.isSessionRetentionExpired(status)) {
+                    await this.deleteSession(sessionId);
+                    cleanedCount++;
+                }
+            }
+            return cleanedCount;
+        }
+        catch (error) {
+            console.warn("Failed to cleanup expired sessions:", error);
+            return 0;
+        }
+    }
+    /**
+     * Create a new session with unique ID
+     */
+    async createSession(questions) {
+        if (!questions || questions.length === 0) {
+            throw new Error("At least one question is required to create a session");
+        }
+        const sessionId = uuidv4();
+        const sessionDir = this.getSessionDir(sessionId);
+        // Create session directory with secure permissions
+        await ensureDirectoryExists(sessionDir);
+        const timestamp = getCurrentTimestamp();
+        // Create session request
+        const sessionRequest = {
+            questions,
+            sessionId,
+            status: "pending",
+            timestamp,
+        };
+        // Create session status
+        const sessionStatus = {
+            createdAt: timestamp,
+            lastModified: timestamp,
+            sessionId,
+            status: "pending",
+            totalQuestions: questions.length,
+        };
+        // Write session files
+        await Promise.all([
+            this.writeSessionFile(sessionId, SESSION_FILES.REQUEST, sessionRequest),
+            this.writeSessionFile(sessionId, SESSION_FILES.STATUS, sessionStatus),
+        ]);
+        return sessionId;
+    }
+    /**
+     * Delete a session directory and all files using atomic operations
+     */
+    async deleteSession(sessionId) {
+        if (!this.isValidSessionId(sessionId)) {
+            throw new Error(`Invalid session ID format: ${sessionId}`);
+        }
+        const sessionDir = this.getSessionDir(sessionId);
+        try {
+            // Delete session files atomically
+            const filesToDelete = [
+                SESSION_FILES.REQUEST,
+                SESSION_FILES.STATUS,
+                SESSION_FILES.ANSWERS,
+            ];
+            for (const filename of filesToDelete) {
+                const filePath = join(sessionDir, createSafeFilename(sessionId, filename));
+                try {
+                    await atomicDeleteFile(filePath);
+                }
+                catch (error) {
+                    // Ignore file not found errors during cleanup
+                    if (!error?.cause?.message.includes("ENOENT")) {
+                        console.warn(`Warning: Failed to delete session file ${filename}: ${error}`);
+                    }
+                }
+            }
+            // Delete session directory
+            await fs.rm(sessionDir, { force: true, recursive: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to delete session ${sessionId}: ${error}`);
+        }
+    }
+    /**
+     * Get all session IDs
+     */
+    async getAllSessionIds() {
+        try {
+            return await fs.readdir(this.sessionsDir);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Get session answers
+     */
+    async getSessionAnswers(sessionId) {
+        return this.readSessionFile(sessionId, SESSION_FILES.ANSWERS);
+    }
+    /**
+     * Get session count
+     */
+    async getSessionCount() {
+        const sessionIds = await this.getAllSessionIds();
+        return sessionIds.length;
+    }
+    /**
+     * Get session request (questions)
+     */
+    async getSessionRequest(sessionId) {
+        return this.readSessionFile(sessionId, SESSION_FILES.REQUEST);
+    }
+    /**
+     * Get session status
+     */
+    async getSessionStatus(sessionId) {
+        return this.readSessionFile(sessionId, SESSION_FILES.STATUS);
+    }
+    /**
+     * Initialize the session manager - create base directories
+     */
+    async initialize() {
+        try {
+            await ensureDirectoryExists(this.sessionsDir);
+            // Validate the directory was created and is accessible
+            const isValid = await validateSessionDirectory(this.sessionsDir);
+            if (!isValid) {
+                throw new Error(`Failed to create or access session directory: ${this.sessionsDir}`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize session directories: ${error}`);
+        }
+    }
+    /**
+     * Check if maximum session limit is reached
+     */
+    async isSessionLimitReached() {
+        const maxSessions = this.config.maxSessions || 100;
+        const currentCount = await this.getSessionCount();
+        return currentCount >= maxSessions;
+    }
+    /**
+     * Save session answers
+     */
+    async saveSessionAnswers(sessionId, answers) {
+        const exists = await this.sessionExists(sessionId);
+        if (!exists) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        await this.writeSessionFile(sessionId, SESSION_FILES.ANSWERS, answers);
+        // Update session status to completed
+        await this.updateSessionStatus(sessionId, "completed");
+    }
+    /**
+     * Check if session exists
+     */
+    async sessionExists(sessionId) {
+        // First validate session ID format
+        if (!this.isValidSessionId(sessionId)) {
+            return false;
+        }
+        const sessionDir = this.getSessionDir(sessionId);
+        return await fileExists(sessionDir);
+    }
+    /**
+     * Start a complete session lifecycle from creation to formatted response
+     *
+     * This is the main orchestration method that:
+     * 1. Creates a new session with the provided questions
+     * 2. Waits for user to submit answers (with optional timeout)
+     * 3. Reads and validates the answers
+     * 4. Formats the response according to PRD specification
+     * 5. Updates session status to completed
+     * 6. Returns the formatted response for the AI model
+     *
+     * @param questions - Array of questions to ask the user
+     * @returns Object containing sessionId and formatted response text
+     * @throws Error if timeout occurs, validation fails, or file operations fail
+     */
+    async startSession(questions) {
+        // Step 1: Create the session
+        const sessionId = await this.createSession(questions);
+        try {
+            // Step 2: Calculate timeouts
+            const sessionTimeout = this.config.sessionTimeout ?? 0; // 0 = infinite
+            const watcherTimeout = sessionTimeout > 0
+                ? Math.floor(sessionTimeout * 0.9) // 90% of session timeout
+                : 0; // Also infinite if session is infinite
+            // Step 3: Wait for answers with timeout
+            try {
+                await this.waitForAnswers(sessionId, watcherTimeout);
+            }
+            catch (error) {
+                // Watcher timeout occurred
+                await this.updateSessionStatus(sessionId, "timed_out");
+                throw new Error(`Session ${sessionId} timed out waiting for user response: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Step 4: Read and validate answers
+            let answers;
+            try {
+                answers = await this.getSessionAnswers(sessionId);
+            }
+            catch (error) {
+                // Handle JSON parse errors or other read failures
+                await this.updateSessionStatus(sessionId, "abandoned");
+                throw error;
+            }
+            if (!answers) {
+                await this.updateSessionStatus(sessionId, "abandoned");
+                throw new Error(`Answers file was created but is invalid for session ${sessionId}`);
+            }
+            const request = await this.getSessionRequest(sessionId);
+            if (!request) {
+                await this.updateSessionStatus(sessionId, "abandoned");
+                throw new Error(`Session request not found: ${sessionId}`);
+            }
+            // Step 5: Validate answers match questions
+            try {
+                ResponseFormatter.validateAnswers(answers, request.questions);
+            }
+            catch (error) {
+                await this.updateSessionStatus(sessionId, "abandoned");
+                throw new Error(`Answer validation failed for session ${sessionId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            // Step 6: Format the response according to PRD specification
+            const formattedResponse = ResponseFormatter.formatUserResponse(answers, request.questions);
+            // Step 7: Update final status
+            await this.updateSessionStatus(sessionId, "completed");
+            // Step 8: Return results
+            return {
+                formattedResponse,
+                sessionId,
+            };
+        }
+        catch (error) {
+            // Ensure any errors are properly propagated with session context
+            if (error instanceof Error) {
+                throw error;
+            }
+            throw new Error(`Session ${sessionId} failed: ${String(error)}`);
+        }
+    }
+    /**
+     * Update session status
+     */
+    async updateSessionStatus(sessionId, status, additionalData) {
+        // First validate session ID format
+        if (!this.isValidSessionId(sessionId)) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const currentStatus = await this.getSessionStatus(sessionId);
+        if (!currentStatus) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        const updatedStatus = {
+            ...currentStatus,
+            lastModified: getCurrentTimestamp(),
+            status,
+            ...additionalData,
+        };
+        await this.writeSessionFile(sessionId, SESSION_FILES.STATUS, updatedStatus);
+    }
+    /**
+     * Validate session data integrity
+     */
+    async validateSession(sessionId) {
+        const issues = [];
+        // Check if session exists
+        if (!(await this.sessionExists(sessionId))) {
+            issues.push("Session directory does not exist");
+            return { issues, isValid: false };
+        }
+        // Check required files
+        const requiredFiles = [SESSION_FILES.REQUEST, SESSION_FILES.STATUS];
+        for (const filename of requiredFiles) {
+            const filePath = join(this.getSessionDir(sessionId), createSafeFilename(sessionId, filename));
+            if (!(await fileExists(filePath))) {
+                issues.push(`Required file missing: ${filename}`);
+            }
+        }
+        // If any required files are missing, don't try to read them
+        if (issues.length > 0) {
+            return {
+                issues,
+                isValid: false,
+            };
+        }
+        // Validate session status consistency
+        const status = await this.getSessionStatus(sessionId);
+        const request = await this.getSessionRequest(sessionId);
+        if (status && request) {
+            if (status.sessionId !== sessionId) {
+                issues.push("Session ID mismatch in status file");
+            }
+            if (request.sessionId !== sessionId) {
+                issues.push("Session ID mismatch in request file");
+            }
+            if (status.totalQuestions !== request.questions.length) {
+                issues.push("Question count mismatch between status and request");
+            }
+        }
+        else {
+            issues.push("Could not read session status or request");
+        }
+        return {
+            issues,
+            isValid: issues.length === 0,
+        };
+    }
+    /**
+     * Wait for user answers to be submitted for a specific session
+     * Returns the session ID when answers are detected, or rejects on timeout
+     */
+    async waitForAnswers(sessionId, timeoutMs) {
+        if (!this.fileWatcher) {
+            this.fileWatcher = new PromiseFileWatcher({
+                debounceMs: 100,
+                ignoreInitial: true,
+                timeoutMs: timeoutMs ?? 0, // 0 means infinite wait time by default
+            });
+        }
+        const sessionDir = this.getSessionDir(sessionId);
+        try {
+            const answersPath = await this.fileWatcher.waitForFile(sessionDir, SESSION_FILES.ANSWERS);
+            // Clean up the watcher after successful wait
+            this.fileWatcher.cleanup();
+            this.fileWatcher = undefined;
+            // Verify the answers file exists and return the session ID
+            console.debug(`Answers file created: ${answersPath}`);
+            return sessionId;
+        }
+        catch (error) {
+            // Clean up on error
+            if (this.fileWatcher) {
+                this.fileWatcher.cleanup();
+                this.fileWatcher = undefined;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get session directory path for a given session ID
+     */
+    getSessionDir(sessionId) {
+        return join(this.sessionsDir, sessionId);
+    }
+    /**
+     * Check if a session is expired based on timeout
+     */
+    isSessionExpired(status) {
+        const timeout = this.config.sessionTimeout || 0;
+        if (timeout <= 0)
+            return false;
+        return isTimestampExpired(status.lastModified, timeout);
+    }
+    /**
+     * Check if a session has exceeded the retention period and should be garbage collected
+     */
+    isSessionRetentionExpired(status) {
+        const retentionPeriod = this.config.retentionPeriod ?? 604800000; // Default 7 days
+        if (retentionPeriod <= 0)
+            return false;
+        // Check the more recent timestamp (lastModified or createdAt)
+        // to determine if session is old enough for cleanup
+        const recentTimestamp = status.lastModified > status.createdAt
+            ? status.lastModified
+            : status.createdAt;
+        return isTimestampExpired(recentTimestamp, retentionPeriod);
+    }
+    /**
+     * Validate session ID format
+     */
+    isValidSessionId(sessionId) {
+        return sanitizeSessionId(sessionId);
+    }
+    /**
+     * Read data from a session file using atomic operations
+     */
+    async readSessionFile(sessionId, filename, fallback = null) {
+        // First validate session ID format
+        if (!this.isValidSessionId(sessionId)) {
+            return fallback;
+        }
+        const safeFilename = createSafeFilename(sessionId, filename);
+        const filePath = join(this.getSessionDir(sessionId), safeFilename);
+        try {
+            const content = await atomicReadFile(filePath, {
+                encoding: "utf8",
+                maxRetries: 3,
+                retryDelay: 100,
+            });
+            try {
+                return JSON.parse(content);
+            }
+            catch (parseError) {
+                throw new Error(`Failed to parse JSON from session file ${filename} for session ${sessionId}: ${parseError}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof AtomicReadError) {
+                // Check if the error is just that the file doesn't exist
+                if (error.cause?.message.includes("File does not exist") ||
+                    error.message.includes("File does not exist")) {
+                    return fallback;
+                }
+                throw new Error(`Failed to read session file ${filename} for session ${sessionId}: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Write data to a session file using atomic operations
+     */
+    async writeSessionFile(sessionId, filename, data) {
+        const safeFilename = createSafeFilename(sessionId, filename);
+        const filePath = join(this.getSessionDir(sessionId), safeFilename);
+        try {
+            await atomicWriteFile(filePath, JSON.stringify(data, null, 2), {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+        }
+        catch (error) {
+            if (error instanceof AtomicWriteError) {
+                throw new Error(`Failed to write session file ${filename} for session ${sessionId}: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}