auq-mcp-server 0.1.0

package/dist/src/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);
+        }
+    }
+}

package/dist/src/session/file-watcher.js

@@ -0,0 +1,227 @@
+/**
+ * File System Watching Module
+ *
+ * Provides cross-platform file system watching capabilities for both
+ * MCP server and TUI coordination with proper debouncing and error handling.
+ */
+import { EventEmitter } from "events";
+import { watch } from "fs";
+import { join } from "path";
+import { fileExists } from "./utils.js";
+import { resolveSessionDirectory } from "./utils.js";
+/**
+ * Promise-based file watcher for specific file patterns
+ */
+export class PromiseFileWatcher extends EventEmitter {
+    config;
+    debounceTimers = new Map();
+    isWatching = false;
+    watchers = new Map();
+    constructor(config = {}) {
+        super();
+        this.config = {
+            debounceMs: config.debounceMs ?? 100,
+            ignoreInitial: config.ignoreInitial ?? true,
+            timeoutMs: config.timeoutMs ?? 30000, // 30 seconds default
+        };
+    }
+    /**
+     * Check if currently watching
+     */
+    active() {
+        return this.isWatching;
+    }
+    /**
+     * Clean up all watchers and timers
+     */
+    cleanup() {
+        // Clear all debounce timers
+        for (const timer of this.debounceTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.debounceTimers.clear();
+        // Close all file watchers
+        for (const watcher of this.watchers.values()) {
+            watcher.close();
+        }
+        this.watchers.clear();
+        this.isWatching = false;
+        this.removeAllListeners();
+    }
+    /**
+     * Watch for a specific file to be created or modified
+     * Returns a promise that resolves when the file is detected
+     */
+    async waitForFile(watchPath, fileName) {
+        const fullPath = join(watchPath, fileName);
+        // Fast-path: if file already exists, resolve immediately
+        if (await fileExists(fullPath)) {
+            return fullPath;
+        }
+        return new Promise((resolve, reject) => {
+            const timeoutId = this.config.timeoutMs > 0
+                ? setTimeout(() => {
+                    this.cleanup();
+                    reject(new Error(`Timeout waiting for file: ${fullPath}`));
+                }, this.config.timeoutMs)
+                : undefined;
+            try {
+                // Set up file watcher
+                const watcher = watch(watchPath, { persistent: false }, (eventType, filename) => {
+                    if (!filename)
+                        return;
+                    const eventPath = join(watchPath, filename);
+                    // Check if this is the file we're waiting for
+                    if (filename === fileName || eventPath === fullPath) {
+                        this.handleFileEvent(eventType, eventPath);
+                        // Verify file exists and is accessible; resolve on create or write
+                        if (eventType === "rename" || eventType === "change") {
+                            // Ensure the file actually exists before resolving
+                            fileExists(fullPath).then((exists) => {
+                                if (!exists)
+                                    return;
+                                if (timeoutId)
+                                    clearTimeout(timeoutId);
+                                this.cleanup();
+                                resolve(fullPath);
+                            });
+                        }
+                    }
+                });
+                this.watchers.set(watchPath, watcher);
+                // Handle watcher errors
+                watcher.on("error", (error) => {
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    this.cleanup();
+                    reject(new Error(`File watcher error: ${error.message}`));
+                });
+                this.isWatching = true;
+            }
+            catch (error) {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                reject(new Error(`File watcher setup error: ${error}`));
+            }
+        });
+    }
+    /**
+     * Watch a directory for new session directories
+     * Emits events when new directories are created
+     */
+    watchForSessions(sessionDirPath, onSessionCreated) {
+        try {
+            const watcher = watch(sessionDirPath, { persistent: false }, (eventType, filename) => {
+                if (!filename || eventType !== "rename")
+                    return;
+                const fullPath = join(sessionDirPath, filename);
+                // Debounce rapid events
+                this.debounceEvent(fullPath, () => {
+                    // Check if this is a new directory (potential session)
+                    this.handleSessionEvent(fullPath, onSessionCreated);
+                });
+            });
+            this.watchers.set(sessionDirPath, watcher);
+            watcher.on("error", (error) => {
+                this.emit("error", new Error(`Session watcher error: ${error.message}`));
+            });
+            this.isWatching = true;
+        }
+        catch (error) {
+            this.emit("error", new Error(`Session watcher setup error: ${error}`));
+        }
+    }
+    /**
+     * Debounce file system events to prevent duplicates
+     */
+    debounceEvent(eventKey, callback) {
+        // Clear existing timer for this event
+        const existingTimer = this.debounceTimers.get(eventKey);
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+        }
+        // Set new timer
+        const timer = setTimeout(() => {
+            this.debounceTimers.delete(eventKey);
+            callback();
+        }, this.config.debounceMs);
+        this.debounceTimers.set(eventKey, timer);
+    }
+    /**
+     * Handle file system events with debouncing
+     */
+    handleFileEvent(eventType, filePath) {
+        const event = {
+            eventType: eventType,
+            filePath,
+            timestamp: Date.now(),
+        };
+        this.emit("fileEvent", event);
+    }
+    /**
+     * Handle new session directory creation
+     */
+    async handleSessionEvent(sessionPath, onSessionCreated) {
+        try {
+            // Check if this is actually a directory and has session files
+            const stats = await import("fs").then((fs) => fs.promises.stat(sessionPath));
+            if (!stats.isDirectory())
+                return;
+            // Extract session ID from directory name
+            const sessionId = sessionPath.split("/").pop() ?? "";
+            if (!sessionId)
+                return;
+            // Verify it's a valid session (has request.json)
+            const requestFile = join(sessionPath, "request.json");
+            try {
+                await import("fs").then((fs) => fs.promises.access(requestFile));
+                onSessionCreated(sessionId, sessionPath);
+            }
+            catch {
+                // Not a valid session directory
+                return;
+            }
+        }
+        catch {
+            // Error accessing directory - ignore
+            return;
+        }
+    }
+}
+/**
+ * TUI Session Watcher -专门用于 TUI 检测新会话
+ */
+export class TUISessionWatcher {
+    /**
+     * Get the session directory path being watched
+     */
+    get watchedPath() {
+        return this.sessionDirPath;
+    }
+    fileWatcher;
+    sessionDirPath;
+    constructor(config) {
+        // Resolve session directory using XDG-compliant path
+        const sessionConfig = {
+            baseDir: config?.baseDir ?? "~/.local/share/auq/sessions",
+        };
+        this.sessionDirPath = resolveSessionDirectory(sessionConfig.baseDir);
+        this.fileWatcher = new PromiseFileWatcher({
+            debounceMs: config?.debounceMs ?? 200,
+            ignoreInitial: config?.ignoreInitial ?? true,
+            timeoutMs: config?.timeoutMs ?? 60000, // 1 minute for TUI
+        });
+    }
+    /**
+     * Start watching for new sessions
+     */
+    startWatching(onNewSession) {
+        this.fileWatcher.watchForSessions(this.sessionDirPath, onNewSession);
+    }
+    /**
+     * Stop watching and clean up
+     */
+    stop() {
+        this.fileWatcher.cleanup();
+    }
+}

package/dist/src/session/index.js

@@ -0,0 +1,7 @@
+/**
+ * Session module exports for AskUserQuestions MCP server
+ */
+export * from "./atomic-operations.js";
+export { SessionManager } from "./SessionManager.js";
+export * from "./types.js";
+export * from "./utils.js";

package/dist/src/session/types.js

@@ -0,0 +1,20 @@
+/**
+ * Session-related TypeScript interfaces and types for AskUserQuestions MCP server
+ */
+/**
+ * File names for session storage
+ */
+export const SESSION_FILES = {
+    ANSWERS: "answers.json",
+    REQUEST: "request.json",
+    STATUS: "status.json",
+};
+/**
+ * Default session configuration
+ */
+export const DEFAULT_SESSION_CONFIG = {
+    baseDir: "~/.local/share/auq/sessions", // Will be resolved to actual path
+    maxSessions: 100,
+    retentionPeriod: 604800000, // 7 days in milliseconds
+    sessionTimeout: 0, // 0 = infinite timeout (wait indefinitely for user)
+};