auq-mcp-server 0.1.0

package/dist/session/file-watcher.js

@@ -0,0 +1,218 @@
+/**
+ * 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 { 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) {
+        return new Promise((resolve, reject) => {
+            const fullPath = join(watchPath, fileName);
+            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
+                        if (eventType === "rename") {
+                            // File was created - resolve the promise
+                            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/session/index.js

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

package/dist/session/types.js

@@ -0,0 +1,20 @@
+/**
+ * Session-related TypeScript interfaces and types for AskUserQuery 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)
+};

package/dist/session/utils.js

@@ -0,0 +1,125 @@
+/**
+ * Utility functions for session management
+ */
+import { constants } from "fs";
+import { promises as fs } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+/**
+ * Create a safe filename from a session ID (basic validation)
+ */
+export function createSafeFilename(sessionId, filename) {
+    if (!sanitizeSessionId(sessionId)) {
+        throw new Error(`Invalid session ID format: ${sessionId}`);
+    }
+    return filename;
+}
+/**
+ * Ensure a directory exists with proper permissions
+ */
+export async function ensureDirectoryExists(dirPath) {
+    try {
+        await fs.access(dirPath, constants.W_OK);
+    }
+    catch {
+        await fs.mkdir(dirPath, { mode: 0o700, recursive: true });
+    }
+}
+/**
+ * Check if a file exists and is readable
+ */
+export async function fileExists(filePath) {
+    try {
+        await fs.access(filePath, constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the current timestamp in ISO format
+ */
+export function getCurrentTimestamp() {
+    return new Date().toISOString();
+}
+/**
+ * Check if a timestamp is older than the specified timeout in milliseconds
+ */
+export function isTimestampExpired(timestamp, timeoutMs) {
+    const now = new Date().getTime();
+    const timestampTime = new Date(timestamp).getTime();
+    return now - timestampTime > timeoutMs;
+}
+/**
+ * Resolve session directory path using XDG Base Directory specification
+ * Falls back to user home directory if XDG is not available
+ */
+export function resolveSessionDirectory(baseDir) {
+    if (baseDir) {
+        // If baseDir is provided, expand any ~ to home directory
+        if (baseDir.startsWith("~")) {
+            return join(homedir(), baseDir.slice(1));
+        }
+        return baseDir;
+    }
+    // Default XDG-compliant paths
+    const home = homedir();
+    const platform = process.platform;
+    if (platform === "darwin") {
+        // macOS: ~/Library/Application Support/
+        return join(home, "Library", "Application Support", "auq", "sessions");
+    }
+    else if (platform === "win32") {
+        // Windows: %APPDATA%/auq/sessions/
+        const appData = process.env.APPDATA;
+        if (appData) {
+            return join(appData, "auq", "sessions");
+        }
+        // Fallback to user profile
+        const userProfile = process.env.USERPROFILE || home;
+        return join(userProfile, "auq", "sessions");
+    }
+    else {
+        // Linux/Unix: ~/.local/share/ (XDG Base Directory)
+        // Check for XDG_DATA_HOME environment variable
+        const xdgDataHome = process.env.XDG_DATA_HOME;
+        if (xdgDataHome) {
+            return join(xdgDataHome, "auq", "sessions");
+        }
+        // Fallback to ~/.local/share/
+        return join(home, ".local", "share", "auq", "sessions");
+    }
+}
+/**
+ * Safely parse JSON with error handling
+ */
+export function safeJsonParse(json, fallback) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Validate that a session ID follows UUID v4 format
+ */
+export function sanitizeSessionId(sessionId) {
+    // Basic validation - UUID v4 format
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(sessionId);
+}
+/**
+ * Validate that a session directory exists and is accessible
+ */
+export async function validateSessionDirectory(baseDir) {
+    try {
+        await fs.access(baseDir, constants.R_OK | constants.W_OK);
+        const stat = await fs.stat(baseDir);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/session-manager.js

@@ -0,0 +1,171 @@
+import { promises as fs } from "fs";
+import { join } from "path";
+import { v4 as uuidv4 } from "uuid";
+import { ensureDir, readJsonFile, writeJsonAtomically } from "./file-utils.js";
+import { waitForAnswers } from "./session-watcher.js";
+// Base directory for all sessions
+const SESSION_BASE_DIR = "/tmp/auq/sessions";
+/**
+ * Manages session directories and files for coordinating between MCP server and TUI
+ */
+export class SessionManager {
+    /**
+     * Create a new session with the provided questions
+     */
+    async createSession(questions) {
+        const sessionId = uuidv4();
+        const sessionDir = this.getSessionDir(sessionId);
+        // Create session directory with secure permissions
+        await ensureDir(sessionDir, 0o700);
+        // Create session objects
+        const now = new Date().toISOString();
+        const request = { questions };
+        const status = {
+            createdAt: now,
+            state: "pending",
+            updatedAt: now,
+        };
+        const session = {
+            answers: {},
+            id: sessionId,
+            request,
+            status,
+        };
+        // Write session files atomically
+        await this.writeRequestFile(sessionId, request);
+        await this.writeStatusFile(sessionId, status);
+        return session;
+    }
+    /**
+     * Get all existing session IDs
+     */
+    async getAllSessionIds() {
+        try {
+            const entries = await fs.readdir(SESSION_BASE_DIR, {
+                withFileTypes: true,
+            });
+            return entries
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name);
+        }
+        catch (error) {
+            // If the directory doesn't exist yet, return an empty array
+            if (error.code === "ENOENT") {
+                return [];
+            }
+            throw error;
+        }
+    }
+    /**
+     * Initialize the session manager, ensuring the base directory exists
+     */
+    async initialize() {
+        try {
+            await ensureDir(SESSION_BASE_DIR, 0o700);
+        }
+        catch (error) {
+            throw new Error(`Failed to create session directory: ${error}`);
+        }
+    }
+    /**
+     * Read the answers.json file for a session
+     */
+    async readAnswersFile(sessionId) {
+        const filePath = this.getSessionFilePath(sessionId, "answers.json");
+        try {
+            return (await readJsonFile(filePath));
+        }
+        catch (error) {
+            throw new Error(`Failed to read answers file for session ${sessionId}: ${error}`);
+        }
+    }
+    /**
+     * Read the request.json file for a session
+     */
+    async readRequestFile(sessionId) {
+        const filePath = this.getSessionFilePath(sessionId, "request.json");
+        try {
+            return (await readJsonFile(filePath));
+        }
+        catch (error) {
+            throw new Error(`Failed to read request file for session ${sessionId}: ${error}`);
+        }
+    }
+    /**
+     * Read the status.json file for a session
+     */
+    async readStatusFile(sessionId) {
+        const filePath = this.getSessionFilePath(sessionId, "status.json");
+        try {
+            return (await readJsonFile(filePath));
+        }
+        catch (error) {
+            throw new Error(`Failed to read status file for session ${sessionId}: ${error}`);
+        }
+    }
+    /**
+     * Check if a session exists
+     */
+    async sessionExists(sessionId) {
+        try {
+            const sessionDir = this.getSessionDir(sessionId);
+            const stats = await fs.stat(sessionDir);
+            return stats.isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Start a new session and wait for user answers
+     */
+    async startSession(questions, timeoutMs = 300000 // 5 minutes default
+    ) {
+        const session = await this.createSession(questions);
+        // Wait for answers using the watcher
+        await waitForAnswers(session.id, this.getSessionDir(session.id), timeoutMs);
+        // Read the answers file
+        const answers = await this.readAnswersFile(session.id);
+        // Update session status to completed
+        await this.updateSessionStatus(session.id, "completed");
+        return { answers, session };
+    }
+    /**
+     * Update the status of a session
+     */
+    async updateSessionStatus(sessionId, state) {
+        const currentStatus = await this.readStatusFile(sessionId);
+        const updatedStatus = {
+            ...currentStatus,
+            state,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.writeStatusFile(sessionId, updatedStatus);
+    }
+    /**
+     * Get the full path for a session directory
+     */
+    getSessionDir(sessionId) {
+        return join(SESSION_BASE_DIR, sessionId);
+    }
+    /**
+     * Get the path for a specific session file
+     */
+    getSessionFilePath(sessionId, filename) {
+        return join(this.getSessionDir(sessionId), filename);
+    }
+    /**
+     * Write the request.json file for a session
+     */
+    async writeRequestFile(sessionId, request) {
+        const filePath = this.getSessionFilePath(sessionId, "request.json");
+        await writeJsonAtomically(filePath, request, 0o600);
+    }
+    /**
+     * Write the status.json file for a session
+     */
+    async writeStatusFile(sessionId, status) {
+        const filePath = this.getSessionFilePath(sessionId, "status.json");
+        await writeJsonAtomically(filePath, status, 0o600);
+    }
+}

package/dist/session-watcher.js

@@ -0,0 +1,110 @@
+import { EventEmitter } from "events";
+import { watch } from "fs";
+import { join } from "path";
+/**
+ * Debounce utility to prevent multiple rapid calls
+ */
+function debounce(func, delay) {
+    let timeoutId = null;
+    return (eventType, fullPath) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            func(eventType, fullPath);
+            timeoutId = null;
+        }, delay);
+    };
+}
+/**
+ * Watches for session directory changes for TUI client
+ */
+export class SessionWatcher extends EventEmitter {
+    baseDir;
+    debounceDelay;
+    /**
+     * Handle changes to session directories
+     */
+    handleSessionChange = debounce((eventType, fullPath) => {
+        const sessionId = fullPath.split("/").pop();
+        if (!sessionId)
+            return;
+        if (eventType === "rename") {
+            // Check if it's a new directory being created
+            this.emit("newSession", sessionId);
+        }
+    }, this.debounceDelay);
+    watchers = new Map();
+    constructor(baseDir, debounceDelay = 300) {
+        super();
+        this.baseDir = baseDir;
+        this.debounceDelay = debounceDelay;
+    }
+    /**
+     * Start watching for session directory changes
+     */
+    start() {
+        // Watch for base sessions directory for new subdirectories
+        const baseWatcher = watch(this.baseDir, { recursive: false }, (eventType, filename) => {
+            if (filename) {
+                const fullPath = join(this.baseDir, filename);
+                this.handleSessionChange(eventType, fullPath);
+            }
+        });
+        this.watchers.set("base", baseWatcher);
+    }
+    /**
+     * Stop all watching
+     */
+    stop() {
+        for (const [, watcher] of this.watchers) {
+            watcher.close();
+        }
+        this.watchers.clear();
+    }
+    /**
+     * Stop watching a specific session
+     */
+    stopWatchingSession(sessionId) {
+        const watcher = this.watchers.get(sessionId);
+        if (watcher) {
+            watcher.close();
+            this.watchers.delete(sessionId);
+        }
+    }
+    /**
+     * Watch a specific session for file changes
+     */
+    watchSession(sessionId) {
+        const sessionDir = join(this.baseDir, sessionId);
+        // Watch for answers.json file creation/modification
+        const watcher = watch(sessionDir, (eventType, filename) => {
+            if (filename === "answers.json") {
+                this.emit("sessionUpdated", sessionId, filename);
+            }
+        });
+        this.watchers.set(sessionId, watcher);
+    }
+}
+/**
+ * Watch for answers.json file creation for MCP server
+ */
+export function waitForAnswers(sessionId, sessionDir, timeoutMs = 300000 // 5 minutes default
+) {
+    return new Promise((resolve, reject) => {
+        let timeoutId;
+        // Start watching for answers.json
+        const watcher = watch(sessionDir, (eventType, filename) => {
+            if (filename === "answers.json") {
+                clearTimeout(timeoutId);
+                watcher.close();
+                resolve();
+            }
+        });
+        // Set timeout
+        timeoutId = setTimeout(() => {
+            watcher.close();
+            reject(new Error(`Timeout waiting for answers for session ${sessionId}`));
+        }, timeoutMs);
+    });
+}