auq-mcp-server 0.1.0

package/dist/session/__tests__/workflow.integration.test.js

@@ -0,0 +1,334 @@
+/**
+ * Integration tests for complete session workflow
+ */
+import { promises as fs } from "fs";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { SessionManager } from "../SessionManager.js";
+import { SESSION_FILES } from "../types.js";
+describe("Complete Session Workflow Integration", () => {
+    const testDir = "/tmp/auq-workflow-test";
+    const sessionManager = new SessionManager({ baseDir: testDir });
+    const sampleQuestions = [
+        {
+            prompt: "What is your preferred development environment?",
+            options: [
+                { label: "VS Code", description: "Microsoft's popular editor" },
+                { label: "Vim", description: "Classic text editor" },
+                { label: "JetBrains IDE", description: "Professional IDE suite" },
+            ],
+        },
+        {
+            prompt: "How do you handle version control?",
+            options: [
+                { label: "Git", description: "Distributed version control" },
+                { label: "SVN", description: "Centralized version control" },
+                { label: "Other", description: "Different system" },
+            ],
+        },
+    ];
+    beforeEach(async () => {
+        // Clean up test directory before each test
+        await fs.rm(testDir, { force: true, recursive: true }).catch(() => { });
+        await sessionManager.initialize();
+    });
+    afterEach(async () => {
+        // Clean up test directory after each test
+        await fs.rm(testDir, { force: true, recursive: true }).catch(() => { });
+    });
+    describe("completeSessionWorkflow", () => {
+        it("should execute complete workflow from creation to formatted response", async () => {
+            // Start the workflow in background
+            const workflowPromise = sessionManager.completeSessionWorkflow(sampleQuestions);
+            // Give it a moment to start and create the session
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Get the session ID that was created
+            const sessionIds = await sessionManager.getAllSessionIds();
+            expect(sessionIds.length).toBe(1);
+            const sessionId = sessionIds[0];
+            // Simulate user answers
+            const userAnswers = {
+                sessionId,
+                timestamp: new Date().toISOString(),
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "VS Code",
+                        timestamp: new Date().toISOString(),
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "Git",
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            };
+            // Save answers to trigger workflow completion
+            const sessionDir = sessionManager.getSessionDir(sessionId);
+            await fs.writeFile(join(sessionDir, SESSION_FILES.ANSWERS), JSON.stringify(userAnswers, null, 2));
+            // Wait for workflow to complete
+            const result = await workflowPromise;
+            // Verify the result structure
+            expect(result).toHaveProperty("formatted_response");
+            expect(result).toHaveProperty("sessionId");
+            expect(typeof result.formatted_response).toBe("string");
+            expect(typeof result.sessionId).toBe("string");
+            // Verify the formatted response content
+            expect(result.formatted_response).toContain("Here are the user's answers:");
+            expect(result.formatted_response).toContain("1. What is your preferred development environment?");
+            expect(result.formatted_response).toContain("2. How do you handle version control?");
+            // Verify session was created properly
+            const sessionExists = await sessionManager.sessionExists(result.sessionId);
+            expect(sessionExists).toBe(true);
+            // Verify session status is completed
+            const sessionStatus = await sessionManager.getSessionStatus(result.sessionId);
+            expect(sessionStatus?.status).toBe("completed");
+        }, 15000); // Longer timeout for workflow test
+        it("should handle workflow with custom answers", async () => {
+            // Start the workflow in background
+            const workflowPromise = sessionManager.completeSessionWorkflow(sampleQuestions);
+            // Give it a moment to start and create the session
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Get the session ID that was created
+            const sessionIds = await sessionManager.getAllSessionIds();
+            expect(sessionIds.length).toBe(1);
+            const sessionId = sessionIds[0];
+            // Simulate user answers with custom text
+            const userAnswers = {
+                sessionId,
+                timestamp: new Date().toISOString(),
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "VS Code",
+                        timestamp: new Date().toISOString(),
+                    },
+                    {
+                        questionIndex: 1,
+                        customText: "I use Git with custom aliases and hooks",
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            };
+            // Save answers to trigger workflow completion
+            const sessionDir = sessionManager.getSessionDir(sessionId);
+            await fs.writeFile(join(sessionDir, SESSION_FILES.ANSWERS), JSON.stringify(userAnswers, null, 2));
+            // Wait for workflow to complete
+            const result = await workflowPromise;
+            // Verify the formatted response includes custom answer
+            expect(result.formatted_response).toContain("→ VS Code — Microsoft's popular editor");
+            expect(result.formatted_response).toContain("→ Other: 'I use Git with custom aliases and hooks'");
+        }, 15000);
+        it("should handle workflow with timeout", async () => {
+            const timeoutMs = 1000; // 1 second timeout
+            try {
+                // Start workflow but don't provide answers - should timeout
+                const workflowPromise = sessionManager.completeSessionWorkflow(sampleQuestions, timeoutMs);
+                await workflowPromise;
+                expect.fail("Should have timed out");
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(Error);
+                expect(error.message).toContain("Timeout");
+            }
+        }, 3000);
+        it("should handle empty questions array", async () => {
+            try {
+                await sessionManager.completeSessionWorkflow([]);
+                expect.fail("Should have thrown error for empty questions");
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(Error);
+                expect(error.message).toContain("At least one question is required");
+            }
+        });
+        it("should update session status throughout workflow", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            // Initial status should be pending
+            let status = await sessionManager.getSessionStatus(sessionId);
+            expect(status?.status).toBe("pending");
+            // After workflow completion, status should be completed
+            // Note: This test might be timing-sensitive since we can't easily test intermediate states
+            // without more complex mocking
+        });
+    });
+    describe("Session State Transitions", () => {
+        it("should properly transition through all states", async () => {
+            // Start workflow in background
+            const workflowPromise = sessionManager.completeSessionWorkflow(sampleQuestions);
+            // Give it a moment to start and create the session
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Get session ID by checking existing sessions
+            const sessionIds = await sessionManager.getAllSessionIds();
+            expect(sessionIds.length).toBe(1);
+            const sessionId = sessionIds[0];
+            // Should be in-progress or processing state
+            const status = await sessionManager.getSessionStatus(sessionId);
+            expect(["in-progress", "processing"]).toContain(status?.status || "");
+            // Now complete the workflow by providing answers
+            const sessionDir = sessionManager.getSessionDir(sessionId);
+            const userAnswers = {
+                sessionId,
+                timestamp: new Date().toISOString(),
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "JetBrains IDE",
+                        timestamp: new Date().toISOString(),
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "Git",
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            };
+            await fs.writeFile(join(sessionDir, SESSION_FILES.ANSWERS), JSON.stringify(userAnswers, null, 2));
+            // Wait for workflow to complete
+            const result = await workflowPromise;
+            // Final status should be completed
+            const finalStatus = await sessionManager.getSessionStatus(sessionId);
+            expect(finalStatus?.status).toBe("completed");
+            expect(result.sessionId).toBe(sessionId);
+        }, 10000);
+        it("should handle workflow failure and mark session as abandoned", async () => {
+            // Start workflow in background
+            const workflowPromise = sessionManager.completeSessionWorkflow(sampleQuestions);
+            // Give it a moment to start and create the session
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Get the session ID that was created
+            const sessionIds = await sessionManager.getAllSessionIds();
+            expect(sessionIds.length).toBe(1);
+            const sessionId = sessionIds[0];
+            // Simulate corrupted answers file
+            const sessionDir = sessionManager.getSessionDir(sessionId);
+            await fs.writeFile(join(sessionDir, SESSION_FILES.ANSWERS), "invalid json content");
+            // Give file system time to register
+            await new Promise(resolve => setTimeout(resolve, 100));
+            try {
+                // This should fail due to invalid JSON
+                await workflowPromise;
+                expect.fail("Should have failed due to invalid answers");
+            }
+            catch (error) {
+                // Session should be marked as abandoned
+                const status = await sessionManager.getSessionStatus(sessionId);
+                expect(status?.status).toBe("abandoned");
+                expect(status?.error).toBeTruthy();
+            }
+        });
+    });
+    describe("Session Metadata and Debugging", () => {
+        it("should provide enhanced session metadata", async () => {
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            // Get enhanced metadata
+            const metadata = await sessionManager.getSessionStatusWithMetadata(sessionId);
+            expect(metadata).toHaveProperty("status");
+            expect(metadata).toHaveProperty("request");
+            expect(metadata.status?.sessionId).toBe(sessionId);
+            expect(metadata.request?.questions).toEqual(sampleQuestions);
+            // Answer should be undefined initially (no answers file exists yet)
+            expect(metadata.answer).toBeUndefined();
+            expect(metadata.formattedResponse).toBeUndefined();
+        });
+        it("should include formatted response when answers exist", async () => {
+            // Create session and provide answers
+            const sessionId = await sessionManager.createSession(sampleQuestions);
+            const sessionDir = sessionManager.getSessionDir(sessionId);
+            const userAnswers = {
+                sessionId,
+                timestamp: new Date().toISOString(),
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "Vim",
+                        timestamp: new Date().toISOString(),
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "Git",
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            };
+            await fs.writeFile(join(sessionDir, SESSION_FILES.ANSWERS), JSON.stringify(userAnswers, null, 2));
+            // Get enhanced metadata
+            const metadata = await sessionManager.getSessionStatusWithMetadata(sessionId);
+            expect(metadata.answer).toBeTruthy();
+            expect(metadata.formattedResponse).toBeTruthy();
+            expect(metadata.formattedResponse).toContain("→ Vim — Classic text editor");
+            expect(metadata.formattedResponse).toContain("→ Git — Distributed version control");
+        });
+    });
+    describe("Error Recovery and Edge Cases", () => {
+        it("should handle multiple session workflows", async () => {
+            // Note: Testing truly concurrent workflows reveals a shared resource issue with fileWatcher
+            // For now, test sequential workflows which should work fine
+            // First workflow
+            const workflow1Promise = sessionManager.completeSessionWorkflow(sampleQuestions);
+            // Wait for first session to be created
+            await new Promise(resolve => setTimeout(resolve, 100));
+            let sessionIds = await sessionManager.getAllSessionIds();
+            expect(sessionIds.length).toBe(1);
+            const sessionId1 = sessionIds[0];
+            // Complete first workflow
+            const sessionDir1 = sessionManager.getSessionDir(sessionId1);
+            const userAnswers1 = {
+                sessionId: sessionId1,
+                timestamp: new Date().toISOString(),
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "VS Code",
+                        timestamp: new Date().toISOString(),
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "Git",
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            };
+            await fs.writeFile(join(sessionDir1, SESSION_FILES.ANSWERS), JSON.stringify(userAnswers1, null, 2));
+            const result1 = await workflow1Promise;
+            // Second workflow (after first completes)
+            const workflow2Promise = sessionManager.completeSessionWorkflow(sampleQuestions);
+            // Wait for second session to be created
+            await new Promise(resolve => setTimeout(resolve, 100));
+            sessionIds = await sessionManager.getAllSessionIds();
+            expect(sessionIds.length).toBe(2);
+            const sessionId2 = sessionIds.find(id => id !== sessionId1);
+            // Complete second workflow
+            const sessionDir2 = sessionManager.getSessionDir(sessionId2);
+            const userAnswers2 = {
+                sessionId: sessionId2,
+                timestamp: new Date().toISOString(),
+                answers: [
+                    {
+                        questionIndex: 0,
+                        selectedOption: "JetBrains IDE",
+                        timestamp: new Date().toISOString(),
+                    },
+                    {
+                        questionIndex: 1,
+                        selectedOption: "SVN",
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            };
+            await fs.writeFile(join(sessionDir2, SESSION_FILES.ANSWERS), JSON.stringify(userAnswers2, null, 2));
+            const result2 = await workflow2Promise;
+            // Verify both workflows completed successfully with different results
+            expect(result1.sessionId).not.toBe(result2.sessionId);
+            expect(result1.formatted_response).toContain("→ VS Code");
+            expect(result1.formatted_response).toContain("→ Git");
+            expect(result2.formatted_response).toContain("→ JetBrains IDE");
+            expect(result2.formatted_response).toContain("→ SVN");
+            // Both sessions should be marked as completed
+            const status1 = await sessionManager.getSessionStatus(result1.sessionId);
+            const status2 = await sessionManager.getSessionStatus(result2.sessionId);
+            expect(status1?.status).toBe("completed");
+            expect(status2?.status).toBe("completed");
+        }, 15000);
+    });
+});

package/dist/session/atomic-operations.js

@@ -0,0 +1,307 @@
+/**
+ * Atomic file operations for session management
+ * Provides truly atomic read/write operations to prevent data corruption
+ */
+import { constants, copyFile, rename } from "fs";
+import { promises as fs } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { fileExists } from "./utils.js";
+/**
+ * Error types for atomic operations
+ */
+export class AtomicOperationError extends Error {
+    operation;
+    filePath;
+    cause;
+    constructor(message, operation, filePath, cause) {
+        super(message);
+        this.operation = operation;
+        this.filePath = filePath;
+        this.cause = cause;
+        this.name = "AtomicOperationError";
+    }
+}
+export class AtomicReadError extends AtomicOperationError {
+    constructor(filePath, cause) {
+        super(`Atomic read failed: ${filePath}`, "read", filePath, cause);
+        this.name = "AtomicReadError";
+    }
+}
+export class AtomicWriteError extends AtomicOperationError {
+    constructor(filePath, cause) {
+        super(`Atomic write failed: ${filePath}`, "write", filePath, cause);
+        this.name = "AtomicWriteError";
+    }
+}
+export class FileLockError extends AtomicOperationError {
+    constructor(filePath, cause) {
+        super(`Failed to acquire file lock: ${filePath}`, "write", filePath, cause);
+        this.name = "FileLockError";
+    }
+}
+const DEFAULT_WRITE_OPTIONS = {
+    encoding: "utf8",
+    flag: "w",
+    maxRetries: 3,
+    mode: 0o600,
+    retryDelay: 100,
+    tmpDir: tmpdir(),
+};
+const DEFAULT_READ_OPTIONS = {
+    encoding: "utf8",
+    flag: "r",
+    maxRetries: 3,
+    retryDelay: 100,
+};
+/**
+ * Atomic file copy operation
+ */
+export async function atomicCopyFile(sourcePath, destPath, options = {}) {
+    const opts = { ...DEFAULT_WRITE_OPTIONS, ...options };
+    try {
+        // Acquire destination lock
+        await acquireLock(destPath);
+        // Perform atomic copy
+        await new Promise((resolve, reject) => {
+            copyFile(sourcePath, destPath, constants.COPYFILE_EXCL, (error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+        // Set correct permissions on destination
+        await fs.chmod(destPath, opts.mode);
+    }
+    catch (error) {
+        throw new AtomicOperationError(`Atomic copy failed: ${sourcePath} -> ${destPath}`, "write", destPath, error);
+    }
+    finally {
+        await releaseLock(destPath);
+    }
+}
+/**
+ * Atomic file delete operation
+ */
+export async function atomicDeleteFile(filePath) {
+    try {
+        await acquireLock(filePath);
+        await fs.unlink(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            // File doesn't exist, that's okay for delete
+            return;
+        }
+        throw new AtomicOperationError(`Atomic delete failed: ${filePath}`, "write", filePath, error);
+    }
+    finally {
+        await releaseLock(filePath);
+    }
+}
+/**
+ * Atomic read operation with retry logic
+ */
+export async function atomicReadFile(filePath, options = {}) {
+    const opts = { ...DEFAULT_READ_OPTIONS, ...options };
+    let lastError = null;
+    for (let attempt = 0; attempt < opts.maxRetries; attempt++) {
+        try {
+            // Check if file exists
+            if (!(await fileExists(filePath))) {
+                throw new AtomicReadError(filePath, new Error("File does not exist"));
+            }
+            // Acquire read lock (shared lock)
+            await acquireLock(filePath);
+            try {
+                const data = await fs.readFile(filePath, {
+                    encoding: opts.encoding,
+                    flag: opts.flag,
+                });
+                return data;
+            }
+            finally {
+                await releaseLock(filePath);
+            }
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry on certain errors
+            if (error instanceof AtomicReadError ||
+                error.code === "ENOENT" ||
+                error.code === "EACCES") {
+                break;
+            }
+            // Wait before retrying
+            if (attempt < opts.maxRetries - 1) {
+                await new Promise((resolve) => setTimeout(resolve, opts.retryDelay * Math.pow(2, attempt)));
+            }
+        }
+    }
+    throw new AtomicReadError(filePath, lastError || new Error("Unknown error"));
+}
+/**
+ * Atomic write operation using temporary file and rename
+ */
+export async function atomicWriteFile(filePath, data, options = {}) {
+    const opts = { ...DEFAULT_WRITE_OPTIONS, ...options };
+    const tempPath = generateTempPath(filePath, opts.tmpDir);
+    try {
+        // Acquire file lock
+        await acquireLock(filePath);
+        // Write to temporary file first
+        await fs.writeFile(tempPath, data, {
+            encoding: opts.encoding,
+            flag: opts.flag,
+            mode: opts.mode,
+        });
+        // Verify the temporary file was written correctly
+        const verificationData = await fs.readFile(tempPath, opts.encoding);
+        if (verificationData !== data) {
+            throw new AtomicWriteError(filePath, new Error("Data verification failed after write"));
+        }
+        // Atomic rename operation
+        await new Promise((resolve, reject) => {
+            rename(tempPath, filePath, (error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+        // Verify the final file exists and has correct permissions
+        try {
+            await fs.access(filePath, constants.F_OK);
+            const stats = await fs.stat(filePath);
+            // Check if mode is correct (at least read/write for owner)
+            if ((stats.mode & 0o600) !== 0o600) {
+                await fs.chmod(filePath, opts.mode);
+            }
+        }
+        catch (error) {
+            throw new AtomicWriteError(filePath, new Error(`File verification failed after rename: ${error}`));
+        }
+    }
+    catch (error) {
+        // Clean up temporary file on failure
+        try {
+            await fs.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw new AtomicWriteError(filePath, error);
+    }
+    finally {
+        // Always release the lock
+        await releaseLock(filePath);
+    }
+}
+/**
+ * Check if a file is locked
+ */
+export async function isFileLocked(filePath) {
+    const lockPath = `${filePath}.lock`;
+    return await fileExists(lockPath);
+}
+/**
+ * Wait for a file to become unlocked (with timeout)
+ */
+export async function waitForFileUnlock(filePath, timeout = 10000) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        if (!(await isFileLocked(filePath))) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new FileLockError(filePath, new Error("Timeout waiting for file unlock"));
+}
+/**
+ * Simple file lock implementation using lock files
+ */
+async function acquireLock(filePath, timeout = 5000) {
+    const lockPath = `${filePath}.lock`;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout) {
+        try {
+            // Try to create lock file (O_EXCL ensures atomic creation)
+            await fs.writeFile(lockPath, process.pid.toString(), {
+                encoding: "utf8",
+                flag: "wx", // Write and fail if file exists
+                mode: 0o600,
+            });
+            return; // Lock acquired
+        }
+        catch (error) {
+            if (error.code === "EEXIST") {
+                // Lock file exists, check if it's stale
+                try {
+                    const lockContent = await fs.readFile(lockPath, "utf8");
+                    const lockPid = parseInt(lockContent.trim(), 10);
+                    // Check if process with PID still exists
+                    try {
+                        process.kill(lockPid, 0); // Signal 0 just checks if process exists
+                    }
+                    catch {
+                        // Process doesn't exist, remove stale lock
+                        await fs.unlink(lockPath);
+                        continue;
+                    }
+                }
+                catch {
+                    // Can't read lock file, try to remove it
+                    try {
+                        await fs.unlink(lockPath);
+                        continue;
+                    }
+                    catch {
+                        // Can't remove lock file, continue waiting
+                    }
+                }
+                // Lock is active, wait and retry
+                await new Promise((resolve) => setTimeout(resolve, 50));
+                continue;
+            }
+            throw error; // Other error occurred
+        }
+    }
+    throw new FileLockError(filePath, new Error("Lock acquisition timeout"));
+}
+/**
+ * Get the base filename from a path
+ */
+function basename(path) {
+    return path.split(/[\\/]/).pop() || "";
+}
+/**
+ * Generate a unique temporary file path
+ */
+function generateTempPath(originalPath, tmpDir) {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2);
+    const filename = `${timestamp}-${random}-${basename(originalPath)}.tmp`;
+    return join(tmpDir, filename);
+}
+/**
+ * Release a file lock
+ */
+async function releaseLock(filePath) {
+    const lockPath = `${filePath}.lock`;
+    try {
+        await fs.unlink(lockPath);
+    }
+    catch (error) {
+        // Lock file might not exist or we don't have permission
+        // Don't throw error as this is cleanup
+        // Only log if it's not ENOENT (file not found)
+        if (error.code !== "ENOENT") {
+            console.warn(`Warning: Could not release lock for ${filePath}:`, error);
+        }
+    }
+}