auq-mcp-server 0.1.0

package/dist/bin/auq.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import { exec } from "child_process";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { Box, render, Text, useApp, useInput } from "ink";
+import React, { useEffect, useState } from "react";
+import { SessionManager } from "../src/session/SessionManager.js";
+import { ensureDirectoryExists, getSessionDirectory, } from "../src/session/utils.js";
+import { Header } from "../src/tui/components/Header.js";
+import { StepperView } from "../src/tui/components/StepperView.js";
+import { Toast } from "../src/tui/components/Toast.js";
+import { WaitingScreen } from "../src/tui/components/WaitingScreen.js";
+import { createTUIWatcher } from "../src/tui/session-watcher.js";
+// import { goodbyeText } from "../src/tui/utils/gradientText.js";
+// Handle command-line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+// Display help
+if (command === "--help" || command === "-h") {
+    console.log(`
+AUQ MCP Server - Ask User Questions
+
+Usage:
+  auq [command] [options]
+
+Commands:
+  (default)     Start the TUI (Terminal User Interface)
+  server        Start the MCP server (for use with MCP clients)
+
+Options:
+  --help, -h    Show this help message
+  --version, -v Show version information
+
+Examples:
+  auq                    # Start TUI (wait for questions from AI)
+  auq server             # Start MCP server (for Claude Desktop, etc.)
+  auq --help             # Show this help message
+
+For more information, visit:
+  https://github.com/paulp-o/ask-user-question-mcp
+`);
+    process.exit(0);
+}
+// Display version
+if (command === "--version" || command === "-v") {
+    // Read version from package.json
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    const packageJsonPath = join(__dirname, "..", "package.json");
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    console.log(`auq-mcp-server v${packageJson.version}`);
+    process.exit(0);
+}
+// Handle 'server' command
+if (command === "server") {
+    console.log("Starting MCP server...");
+    const serverProcess = exec("node dist/src/server.js", (error, stdout, stderr) => {
+        if (error) {
+            console.error(`Error starting server: ${error.message}`);
+            process.exit(1);
+        }
+        if (stderr) {
+            console.error(stderr);
+        }
+        console.log(stdout);
+    });
+    // Forward signals
+    process.on("SIGINT", () => {
+        serverProcess.kill("SIGINT");
+        process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+        serverProcess.kill("SIGTERM");
+        process.exit(0);
+    });
+    // Keep process alive
+    await new Promise(() => { });
+}
+const App = () => {
+    const { exit } = useApp();
+    const [state, setState] = useState({ mode: "WAITING" });
+    const [sessionQueue, setSessionQueue] = useState([]);
+    const [isInitialized, setIsInitialized] = useState(false);
+    const [toast, setToast] = useState(null);
+    const [showSessionLog, setShowSessionLog] = useState(true);
+    // Get session directory for logging
+    const sessionDir = getSessionDirectory();
+    // Auto-hide session log after 3 seconds
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            setShowSessionLog(false);
+        }, 3000);
+        return () => clearTimeout(timer);
+    }, []);
+    // Initialize: Load existing sessions + start persistent watcher
+    useEffect(() => {
+        let watcherInstance = null;
+        const initialize = async () => {
+            try {
+                // Step 0: Ensure session directory exists
+                await ensureDirectoryExists(sessionDir);
+                // Step 1: Load existing pending sessions
+                const watcher = createTUIWatcher();
+                const sessionIds = await watcher.getPendingSessions();
+                const sessionData = await Promise.all(sessionIds.map(async (sessionId) => {
+                    const sessionRequest = await watcher.getSessionRequest(sessionId);
+                    if (!sessionRequest)
+                        return null;
+                    return {
+                        sessionId,
+                        sessionRequest,
+                        timestamp: new Date(sessionRequest.timestamp),
+                    };
+                }));
+                // Filter out null entries and sort by timestamp (FIFO - oldest first)
+                const validSessions = sessionData
+                    .filter((s) => s !== null)
+                    .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+                setSessionQueue(validSessions);
+                setIsInitialized(true);
+                // Step 2: Start persistent watcher for new sessions
+                watcherInstance = createTUIWatcher({ autoLoadData: true });
+                watcherInstance.startEnhancedWatching((event) => {
+                    // Add new session to queue (FIFO - append to end)
+                    setSessionQueue((prev) => {
+                        // Check for duplicates
+                        if (prev.some((s) => s.sessionId === event.sessionId)) {
+                            return prev;
+                        }
+                        // Add to end of queue
+                        return [
+                            ...prev,
+                            {
+                                sessionId: event.sessionId,
+                                sessionRequest: event.sessionRequest,
+                                timestamp: new Date(event.timestamp),
+                            },
+                        ];
+                    });
+                });
+            }
+            catch (error) {
+                console.error("Failed to initialize:", error);
+                setIsInitialized(true); // Continue even if initialization fails
+            }
+        };
+        initialize();
+        // Cleanup: stop watcher on unmount
+        return () => {
+            if (watcherInstance) {
+                watcherInstance.stop();
+            }
+        };
+    }, []);
+    // Auto-transition: WAITING → PROCESSING when queue has items
+    useEffect(() => {
+        if (!isInitialized)
+            return;
+        if (state.mode === "WAITING" && sessionQueue.length > 0) {
+            const [nextSession, ...rest] = sessionQueue;
+            setSessionQueue(rest);
+            setState({ mode: "PROCESSING", session: nextSession });
+        }
+    }, [state, sessionQueue, isInitialized]);
+    // Global 'q' to quit anytime
+    useInput((input) => {
+        if (input === "q") {
+            // If processing a session, reject it before exiting
+            if (state.mode === "PROCESSING") {
+                const sessionManager = new SessionManager();
+                sessionManager
+                    .rejectSession(state.session.sessionId)
+                    .catch((error) => {
+                    console.error("Failed to reject session on quit:", error);
+                })
+                    .finally(() => {
+                    exit();
+                });
+            }
+            else {
+                exit();
+            }
+        }
+    });
+    // Show toast notification
+    const showToast = (message, type = "success") => {
+        setToast({ message, type });
+    };
+    // Handle session completion
+    const handleSessionComplete = (wasRejected = false) => {
+        // Show appropriate toast
+        if (wasRejected) {
+            showToast("Question set rejected", "info");
+        }
+        else {
+            showToast("✓ Answers submitted successfully!", "success");
+        }
+        if (sessionQueue.length > 0) {
+            // Auto-load next session
+            const [nextSession, ...rest] = sessionQueue;
+            setSessionQueue(rest);
+            setState({ mode: "PROCESSING", session: nextSession });
+        }
+        else {
+            // Return to WAITING
+            setState({ mode: "WAITING" });
+        }
+    };
+    // Render based on state
+    if (!isInitialized) {
+        return React.createElement(Text, null, "Loading...");
+    }
+    let mainContent;
+    if (state.mode === "WAITING") {
+        mainContent = React.createElement(WaitingScreen, { queueCount: sessionQueue.length });
+    }
+    else {
+        // PROCESSING mode
+        const { session } = state;
+        mainContent = (React.createElement(StepperView, { key: session.sessionId, onComplete: handleSessionComplete, sessionId: session.sessionId, sessionRequest: session.sessionRequest }));
+    }
+    // Render with header, toast overlay, and main content
+    return (React.createElement(Box, { flexDirection: "column", paddingX: 1 },
+        React.createElement(Header, { pendingCount: sessionQueue.length }),
+        toast && (React.createElement(Box, { marginBottom: 1, marginTop: 1 },
+            React.createElement(Toast, { message: toast.message, onDismiss: () => setToast(null), type: toast.type }))),
+        mainContent,
+        showSessionLog && (React.createElement(Box, { marginTop: 1 },
+            React.createElement(Text, { dimColor: true },
+                "[AUQ] Session directory: ",
+                sessionDir)))));
+};
+// Clear terminal before showing app
+console.clear();
+const { waitUntilExit } = render(React.createElement(App, null));
+// Handle Ctrl+C gracefully
+process.on("SIGINT", () => {
+    process.exit(0);
+});
+// Show goodbye after Ink unmounts
+waitUntilExit().then(() => {
+    process.stdout.write("\n");
+    console.log("👋 Goodbye! See you next time.");
+});

package/dist/bin/test-session-menu.js

@@ -0,0 +1,28 @@
+import { render, Box, Text } from "ink";
+!/usr/bin / env;
+node;
+import React from "react";
+import { SessionSelectionMenu } from "../src/tui/components/SessionSelectionMenu.js";
+const TestSessionMenu = () => {
+    const [selectedSession, setSelectedSession] = React.useState(null);
+    if (selectedSession) {
+        return (React.createElement(Box, { flexDirection: "column", padding: 1 },
+            React.createElement(Text, { bold: true, color: "green" }, "\u2713 Session Selected!"),
+            React.createElement(Box, { marginTop: 1 }),
+            React.createElement(Text, null,
+                "Session ID: ",
+                selectedSession.sessionId),
+            React.createElement(Text, null,
+                "Questions: ",
+                selectedSession.sessionRequest.questions.length),
+            React.createElement(Box, { marginTop: 1 }),
+            React.createElement(Text, { dimColor: true }, "Integration with StepperView will happen in the next subtask (7.5)")));
+    }
+    return (React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Box, { marginBottom: 1 },
+            React.createElement(Text, { bold: true, color: "cyan" }, "SessionSelectionMenu Component Test")),
+        React.createElement(SessionSelectionMenu, { onSessionSelect: (sessionId, sessionRequest) => {
+                setSelectedSession({ sessionId, sessionRequest });
+            } })));
+};
+render(React.createElement(TestSessionMenu, null));

package/dist/bin/test-tabbar.js

@@ -0,0 +1,42 @@
+import { render, Box, Text } from "ink";
+!/usr/bin / env;
+node;
+import React, { useState, useEffect } from "react";
+import { TabBar } from "../src/tui/components/TabBar.js";
+const mockQuestions = [
+    {
+        options: [{ label: "JavaScript" }, { label: "TypeScript" }],
+        prompt: "Which programming language?",
+        title: "Language",
+    },
+    {
+        options: [{ label: "Web" }, { label: "CLI" }],
+        prompt: "What type of application?",
+        title: "App Type",
+    },
+    {
+        options: [{ label: "React" }, { label: "Vue" }],
+        prompt: "Which framework?",
+        title: "Framework",
+    },
+];
+const TestTabBar = () => {
+    const [currentIndex, setCurrentIndex] = useState(0);
+    useEffect(() => {
+        // Cycle through questions every 2 seconds to show highlighting
+        const timer = setInterval(() => {
+            setCurrentIndex((prev) => (prev + 1) % mockQuestions.length);
+        }, 2000);
+        return () => clearInterval(timer);
+    }, []);
+    return (React.createElement(Box, { flexDirection: "column", padding: 1 },
+        React.createElement(Text, { bold: true, color: "green" }, "TabBar Component Test"),
+        React.createElement(Text, { dimColor: true }, "(Cycles through questions every 2 seconds to show highlighting)"),
+        React.createElement(Box, { marginTop: 1 },
+            React.createElement(TabBar, { currentIndex: currentIndex, questions: mockQuestions })),
+        React.createElement(Box, { marginTop: 1 },
+            React.createElement(Text, { dimColor: true },
+                "Current question: ",
+                currentIndex + 1))));
+};
+render(React.createElement(TestTabBar, null));

package/dist/file-utils.js

@@ -0,0 +1,59 @@
+import { promises as fs } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+/**
+ * Ensure a directory exists with secure permissions
+ * @param dirPath Directory path to create
+ * @param mode File permissions (defaults to 0o700 for secure user-only access)
+ */
+export async function ensureDir(dirPath, mode = 0o700) {
+    try {
+        await fs.mkdir(dirPath, { recursive: true, mode });
+    }
+    catch (error) {
+        throw new Error(`Failed to create directory ${dirPath}: ${error}`);
+    }
+}
+/**
+ * Read and parse a JSON file with proper error handling
+ * @param filePath Path to the JSON file
+ * @returns Parsed JSON data
+ */
+export async function readJsonFile(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to read JSON file ${filePath}: ${error}`);
+    }
+}
+/**
+ * Write data to a file atomically to prevent corruption
+ * Creates a temporary file, writes to it, then renames to final destination
+ * @param filePath The final destination path
+ * @param data The data to write
+ * @param mode File permissions (defaults to 0o600 for secure user-only access)
+ */
+export async function writeJsonAtomically(filePath, data, mode = 0o600) {
+    const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+    const tempFile = join(tmpdir(), `temp-${Date.now()}-${Math.random().toString(36).substring(2)}.json`);
+    try {
+        // Ensure directory exists with proper permissions
+        await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+        // Write to temporary file first
+        await fs.writeFile(tempFile, JSON.stringify(data, null, 2), { mode });
+        // Atomically rename to final destination
+        await fs.rename(tempFile, filePath);
+    }
+    catch (error) {
+        // Clean up temp file if something went wrong
+        try {
+            await fs.unlink(tempFile);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}

package/dist/format/ResponseFormatter.js

@@ -0,0 +1,206 @@
+/**
+ * Response Formatter Module
+ *
+ * Formats user answers into PRD-compliant text for AI consumption.
+ * Implements numbered questions, arrow symbols, and proper "Other:" formatting.
+ */
+/**
+ * Response Formatter Class
+ *
+ * Converts user answers into human-readable, AI-friendly text format
+ * according to PRD specifications.
+ */
+export class ResponseFormatter {
+    static DEFAULT_PREAMBLE = "Here are the user's answers:\n\n";
+    static ARROW_SYMBOL = "→";
+    static OTHER_PREFIX = "Other:";
+    /**
+     * Format a complete session response according to PRD specifications
+     *
+     * @param sessionRequest - The original session request with questions
+     * @param sessionAnswer - The user's answers
+     * @param options - Optional formatting configuration
+     * @returns Formatted response ready for AI consumption
+     */
+    static formatResponse(sessionRequest, sessionAnswer, options = {}) {
+        const { includePreamble = true, preambleText = ResponseFormatter.DEFAULT_PREAMBLE, includeTimestamps = false, maxLineLength = 0, } = options;
+        const { questions } = sessionRequest;
+        const { answers } = sessionAnswer;
+        // Build the formatted response
+        let formattedText = includePreamble ? preambleText : "";
+        // Process each question and its answer
+        questions.forEach((question, index) => {
+            const questionNumber = index + 1;
+            const answer = answers.find((a) => a.questionIndex === index);
+            // Add question number and prompt
+            formattedText += `${questionNumber}. ${question.prompt}\n`;
+            if (answer) {
+                // Format the answer
+                const answerText = this.formatAnswer(question, answer, maxLineLength);
+                formattedText += `${ResponseFormatter.ARROW_SYMBOL} ${answerText}\n`;
+                // Add timestamp if requested
+                if (includeTimestamps) {
+                    formattedText += `   (Answered: ${new Date(answer.timestamp).toLocaleString()})\n`;
+                }
+            }
+            else {
+                // Handle unanswered question
+                formattedText += `${ResponseFormatter.ARROW_SYMBOL} [No answer provided]\n`;
+            }
+            formattedText += "\n"; // Add spacing between questions
+        });
+        // Calculate metadata
+        const metadata = {
+            totalQuestions: questions.length,
+            answeredQuestions: answers.length,
+            sessionDuration: this.calculateSessionDuration(sessionRequest, sessionAnswer),
+            hasCustomAnswers: answers.some((a) => a.customText && a.customText.trim().length > 0),
+        };
+        return {
+            formatted_response: formattedText.trim(), // Remove trailing whitespace
+            metadata,
+        };
+    }
+    /**
+     * Format a single answer according to PRD specifications
+     *
+     * @param question - The question being answered
+     * @param answer - The user's answer
+     * @param maxLineLength - Optional maximum line length for text wrapping
+     * @returns Formatted answer text
+     */
+    static formatAnswer(question, answer, maxLineLength) {
+        // If custom text is provided, use that (takes precedence)
+        if (answer.customText && answer.customText.trim().length > 0) {
+            const customText = answer.customText.trim();
+            const wrappedText = maxLineLength > 0 ? this.wrapText(customText, maxLineLength) : customText;
+            return `${ResponseFormatter.OTHER_PREFIX} '${wrappedText}'`;
+        }
+        // If a selected option is provided, find and format it
+        if (answer.selectedOption) {
+            const selectedOption = question.options.find((opt) => opt.label === answer.selectedOption);
+            if (selectedOption) {
+                // Format: "Label — Description" (if description exists)
+                let optionText = selectedOption.label;
+                if (selectedOption.description && selectedOption.description.trim().length > 0) {
+                    optionText += ` — ${selectedOption.description}`;
+                }
+                return optionText;
+            }
+        }
+        // Fallback for edge cases
+        return answer.selectedOption || "[Invalid answer]";
+    }
+    /**
+     * Calculate session duration in milliseconds
+     */
+    static calculateSessionDuration(sessionRequest, sessionAnswer) {
+        return new Date(sessionAnswer.timestamp).getTime() - new Date(sessionRequest.timestamp).getTime();
+    }
+    /**
+     * Wrap text to fit within specified line length
+     *
+     * @param text - Text to wrap
+     * @param maxLength - Maximum line length
+     * @returns Wrapped text with proper line breaks
+     */
+    static wrapText(text, maxLength) {
+        if (maxLength <= 0 || text.length <= maxLength) {
+            return text;
+        }
+        const words = text.split(" ");
+        const lines = [];
+        let currentLine = "";
+        for (const word of words) {
+            if ((currentLine + " " + word).length <= maxLength) {
+                currentLine = currentLine ? `${currentLine} ${word}` : word;
+            }
+            else {
+                if (currentLine) {
+                    lines.push(currentLine);
+                    currentLine = word;
+                }
+                else {
+                    // Word is longer than maxLength, break it
+                    lines.push(word.substring(0, maxLength));
+                    currentLine = word.substring(maxLength);
+                }
+            }
+        }
+        if (currentLine) {
+            lines.push(currentLine);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Validate that answers are complete and properly formatted
+     *
+     * @param sessionRequest - The original session request
+     * @param sessionAnswer - The user's answers
+     * @returns Validation result with any issues found
+     */
+    static validateAnswers(sessionRequest, sessionAnswer) {
+        const issues = [];
+        const warnings = [];
+        const { questions } = sessionRequest;
+        const { answers } = sessionAnswer;
+        // Check if all questions have answers
+        if (answers.length < questions.length) {
+            issues.push(`${questions.length - answers.length} question(s) were not answered`);
+        }
+        // Check for duplicate answers
+        const answeredIndices = answers.map((a) => a.questionIndex);
+        const uniqueIndices = [...new Set(answeredIndices)];
+        if (answeredIndices.length !== uniqueIndices.length) {
+            issues.push("Duplicate answers detected for some questions");
+        }
+        // Validate each answer
+        answers.forEach((answer, index) => {
+            // Check question index validity
+            if (answer.questionIndex < 0 || answer.questionIndex >= questions.length) {
+                issues.push(`Answer ${index + 1} references invalid question index: ${answer.questionIndex}`);
+                return;
+            }
+            const question = questions[answer.questionIndex];
+            // Check if answer has either selected option or custom text
+            if (!answer.selectedOption && (!answer.customText || answer.customText.trim().length === 0)) {
+                issues.push(`Answer ${index + 1} has no selected option or custom text`);
+            }
+            // Validate selected option exists in question
+            if (answer.selectedOption) {
+                const optionExists = question.options.some((opt) => opt.label === answer.selectedOption);
+                if (!optionExists) {
+                    issues.push(`Answer ${index + 1} references non-existent option: ${answer.selectedOption}`);
+                }
+            }
+            // Check for extremely long custom answers
+            if (answer.customText && answer.customText.length > 1000) {
+                warnings.push(`Answer ${index + 1} has very long custom text (${answer.customText.length} characters)`);
+            }
+        });
+        return {
+            isValid: issues.length === 0,
+            issues,
+            warnings,
+        };
+    }
+    /**
+     * Create a summary of the session for logging/debugging
+     *
+     * @param sessionRequest - The original session request
+     * @param sessionAnswer - The user's answers
+     * @returns Human-readable session summary
+     */
+    static createSessionSummary(sessionRequest, sessionAnswer) {
+        const { questions } = sessionRequest;
+        const { answers } = sessionAnswer;
+        const duration = this.calculateSessionDuration(sessionRequest, sessionAnswer);
+        return `Session Summary:
+- Session ID: ${sessionRequest.sessionId}
+- Total Questions: ${questions?.length || 0}
+- Answered Questions: ${answers?.length || 0}
+- Duration: ${Math.round(duration / 1000)}s
+- Custom Answers: ${(answers || []).filter((a) => a.customText && a.customText.trim().length > 0).length}
+- Status: ${sessionRequest.status}`;
+    }
+}