auq-mcp-server 2.6.4 → 2.7.0

package/dist/src/cli/commands/__tests__/history.test.js

@@ -0,0 +1,211 @@
+/**
+ * Integration tests for the `auq history` CLI command.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "fs";
+import { SessionManager } from "../../../session/SessionManager.js";
+import { runHistoryCommand } from "../history.js";
+// ── Test directory ─────────────────────────────────────────────────────────
+const testBaseDir = `/tmp/auq-test-history-${process.pid}`;
+// Stub getSessionDirectory so the history command always targets our temp dir.
+vi.mock("../../../session/utils.js", async (importOriginal) => {
+    const actual = (await importOriginal());
+    return {
+        ...actual,
+        getSessionDirectory: () => testBaseDir,
+    };
+});
+// ── Test fixtures ───────────────────────────────────────────────────────────
+const sampleQuestions = [
+    {
+        title: "Database",
+        prompt: "Which database should we use?",
+        options: [
+            { label: "Postgres", description: "Relational, reliable" },
+            { label: "Redis", description: "In-memory cache" },
+        ],
+        multiSelect: false,
+    },
+    {
+        title: "Auth",
+        prompt: "Which auth method?",
+        options: [
+            { label: "JWT", description: "Stateless tokens" },
+            { label: "Cookies", description: "Server-side sessions" },
+        ],
+        multiSelect: false,
+    },
+];
+async function createCompletedSession(mgr, opts) {
+    const id = await mgr.createSession(sampleQuestions);
+    await mgr.saveSessionAnswers(id, {
+        sessionId: id,
+        timestamp: new Date().toISOString(),
+        answers: sampleQuestions.map((q, i) => ({
+            questionIndex: i,
+            timestamp: new Date().toISOString(),
+            selectedOption: q.options[0].label,
+        })),
+    });
+    await mgr.updateSessionStatus(id, "completed");
+    if (opts?.read) {
+        await mgr.markSessionAsRead(id);
+    }
+    return id;
+}
+async function createRejectedSession(mgr) {
+    const id = await mgr.createSession(sampleQuestions);
+    await mgr.rejectSession(id, "not relevant");
+    return id;
+}
+async function createAbandonedSession(mgr) {
+    const id = await mgr.createSession(sampleQuestions);
+    await mgr.updateSessionStatus(id, "abandoned");
+    return id;
+}
+// ── Test Suite ──────────────────────────────────────────────────────────────
+describe("history command", () => {
+    let sessionManager;
+    let consoleLogSpy;
+    let consoleErrorSpy;
+    beforeEach(async () => {
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+        sessionManager = new SessionManager({ baseDir: testBaseDir });
+        await sessionManager.initialize();
+        consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+        consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        process.exitCode = undefined;
+    });
+    afterEach(async () => {
+        consoleLogSpy.mockRestore();
+        consoleErrorSpy.mockRestore();
+        process.exitCode = undefined;
+        await fs.rm(testBaseDir, { force: true, recursive: true }).catch(() => { });
+    });
+    // ── List (default) ──────────────────────────────────────────────────────
+    describe("list (default)", () => {
+        it("should list non-abandoned sessions by default", async () => {
+            await createCompletedSession(sessionManager);
+            const abandonedId = await createAbandonedSession(sessionManager);
+            await runHistoryCommand([]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("completed");
+            // Abandoned session's short ID should not appear as a table row
+            expect(output).not.toContain(abandonedId.slice(0, 8));
+        });
+        it("should show abandoned hint when hidden", async () => {
+            await createCompletedSession(sessionManager);
+            await createAbandonedSession(sessionManager);
+            await runHistoryCommand([]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("abandoned hidden");
+            expect(output).toContain("--all");
+        });
+        it("should show all with --all flag", async () => {
+            await createCompletedSession(sessionManager);
+            const abandonedId = await createAbandonedSession(sessionManager);
+            await runHistoryCommand(["--all"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(abandonedId.slice(0, 8));
+        });
+        it("should show empty state message", async () => {
+            await runHistoryCommand([]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("No sessions found");
+        });
+        it("should limit output with --limit", async () => {
+            await createCompletedSession(sessionManager);
+            await createCompletedSession(sessionManager);
+            await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--limit", "2"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            // Match 8-character lowercase hex strings (UUID short IDs)
+            const matches = output.match(/[a-f0-9]{8}/g) || [];
+            const uniqueIds = [...new Set(matches)];
+            expect(uniqueIds.length).toBeLessThanOrEqual(2);
+        });
+        it("should filter unread with --unread", async () => {
+            const unreadId = await createCompletedSession(sessionManager);
+            await createCompletedSession(sessionManager, { read: true });
+            await runHistoryCommand(["--unread"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(unreadId.slice(0, 8));
+        });
+        it("should search with --search", async () => {
+            await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--search", "database"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("completed");
+        });
+        it("should output JSON with --json", async () => {
+            await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--json"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const parsed = JSON.parse(output);
+            expect(Array.isArray(parsed)).toBe(true);
+            expect(parsed[0]).toHaveProperty("sessionId");
+            expect(parsed[0]).toHaveProperty("status");
+            expect(parsed[0]).toHaveProperty("questionCount");
+        });
+        it("should find session with --session", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["--session", id.slice(0, 8)]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(id.slice(0, 8));
+        });
+        it("should error for --session with no match", async () => {
+            await runHistoryCommand(["--session", "00000000"]);
+            expect(process.exitCode).toBe(1);
+        });
+    });
+    // ── Show ────────────────────────────────────────────────────────────────
+    describe("show", () => {
+        it("should show session details", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(id);
+            expect(output).toContain("completed");
+            expect(output).toContain("Which database should we use?");
+        });
+        it("should show all options with (selected) prefix for answered options", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("(selected)");
+            expect(output).toContain("Postgres");
+            expect(output).toContain("Redis");
+        });
+        it("should resolve short session ID", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id.slice(0, 8)]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain(id);
+        });
+        it("should error for non-existent session", async () => {
+            await runHistoryCommand(["show", "nonexistent-id"]);
+            expect(process.exitCode).toBe(1);
+        });
+        it("should show rejected session", async () => {
+            const id = await createRejectedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("rejected");
+        });
+        it("should show abandoned session", async () => {
+            const id = await createAbandonedSession(sessionManager);
+            await runHistoryCommand(["show", id]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(output).toContain("abandoned");
+        });
+        it("should output JSON with --json", async () => {
+            const id = await createCompletedSession(sessionManager);
+            await runHistoryCommand(["show", id, "--json"]);
+            const output = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            const parsed = JSON.parse(output);
+            expect(parsed.sessionId).toBe(id);
+            expect(parsed.questions).toBeInstanceOf(Array);
+            expect(parsed.questions[0].options).toBeInstanceOf(Array);
+        });
+    });
+});

package/dist/src/cli/commands/answer.js

@@ -84,6 +84,17 @@ export async function runAnswerCommand(args) {
         }
     }
     catch (err) {
+        if (!jsonMode) {
+            process.stderr.write(`Error: Invalid --answers JSON format.\n\n` +
+                `Expected format:\n` +
+                `  auq answer <sessionId> --answers '{"0": {"selectedOption": "Label Name"}}'\n\n` +
+                `Answer object keys are question indices (0, 1, 2, ...). Each value can have:\n` +
+                `  \u2022 selectedOption: "Label"      \u2014 for single-select questions\n` +
+                `  \u2022 selectedOptions: ["A", "B"]  \u2014 for multi-select questions\n` +
+                `  \u2022 customText: "free text"       \u2014 for custom/other input\n\n` +
+                `Example (multi-question):\n` +
+                `  auq answer abc123 --answers '{"0": {"selectedOption": "Yes"}, "1": {"customText": "my input"}}'\n\n`);
+        }
         outputResult({
             success: false,
             error: `Invalid answers JSON: ${err instanceof Error ? err.message : String(err)}`,

package/dist/src/cli/commands/config.js

@@ -155,6 +155,36 @@ async function configGet(args) {
             return;
         }
         const value = getNestedValue(config, key);
+        // Special handling for renderer key: show env var override and source
+        if (key === "renderer") {
+            const envRenderer = process.env.AUQ_RENDERER;
+            let displayValue;
+            let source;
+            if (envRenderer) {
+                displayValue = envRenderer;
+                source = "AUQ_RENDERER";
+            }
+            else {
+                const paths = getConfigPaths();
+                const localConfig = readConfigFileForWrite(paths.local);
+                const globalConfig = readConfigFileForWrite(paths.global);
+                const explicitlySet = localConfig.renderer !== undefined || globalConfig.renderer !== undefined;
+                displayValue = String(value);
+                source = explicitlySet ? "config" : "default";
+            }
+            if (jsonMode) {
+                console.log(JSON.stringify({ success: true, key, value: displayValue, source }, null, 2));
+            }
+            else {
+                const suffix = source === "AUQ_RENDERER"
+                    ? " (from AUQ_RENDERER)"
+                    : source === "default"
+                        ? " (default)"
+                        : "";
+                console.log(`${key} = ${displayValue}${suffix}`);
+            }
+            return;
+        }
         if (jsonMode) {
             console.log(JSON.stringify({ success: true, key, value }, null, 2));
         }
@@ -210,6 +240,22 @@ async function configSet(args) {
         const issues = validation.error.issues
             .map((i) => `${i.path.join(".")}: ${i.message}`)
             .join("; ");
+        // Build key-specific hint for human-readable mode
+        if (!jsonMode) {
+            const hints = {
+                maxOptions: "Expected: number between 2 and 10",
+                maxQuestions: "Expected: number between 1 and 10",
+                sessionTimeout: "Expected: number (milliseconds, e.g. 300000 for 5 minutes)",
+                renderer: 'Expected: \"ink\" or \"opentui\"',
+                staleAction: 'Expected: \"warn\", \"remove\", or \"archive\"',
+                theme: "Expected: a valid theme name (see auq config get theme)",
+                language: "Expected: a language code (e.g. \"en\", \"ko\")",
+            };
+            const hint = hints[key];
+            process.stderr.write(`Error: Invalid value "${rawValue}" for key "${key}".\n\n` +
+                (hint ? `${hint}\n\n` : "") +
+                `Usage: auq config set ${key} <value> [--global]\n\n`);
+        }
         outputResult({
             success: false,
             error: `Invalid value for "${key}": ${issues}`,
@@ -255,6 +301,8 @@ export async function runConfigCommand(args) {
             console.log("  auq config get staleThreshold --json");
             console.log("  auq config set staleThreshold 3600000");
             console.log("  auq config set notifyOnStale false --global");
+            console.log("  auq config get renderer");
+            console.log("  auq config set renderer opentui");
             if (subcommand !== undefined) {
                 process.exitCode = 1;
             }

package/dist/src/cli/commands/fetch-answers.js

@@ -0,0 +1,205 @@
+/**
+ * CLI Fetch-Answers Command — `auq fetch-answers [<session-id>] [--blocking] [--json] [--unread]`
+ * Retrieves answers for a session asynchronously, or lists unread sessions.
+ */
+import { SessionManager } from "../../session/SessionManager.js";
+import { ResponseFormatter } from "../../session/ResponseFormatter.js";
+import { getSessionDirectory } from "../../session/utils.js";
+import { formatAge, outputResult, parseFlags } from "../utils.js";
+/**
+ * Run the `auq fetch-answers` command.
+ *
+ * Usage:
+ *   auq fetch-answers                        # list all unread sessions (default)
+ *   auq fetch-answers --unread               # same as above
+ *   auq fetch-answers <sessionId>            # fetch answers for specific session
+ *   auq fetch-answers <sessionId> --blocking # wait until answered, then fetch
+ *   auq fetch-answers <sessionId> --json     # output as JSON
+ */
+export async function runFetchAnswersCommand(args) {
+    const { flags, positionals } = parseFlags(args);
+    const jsonMode = flags.json === true;
+    const blockingMode = flags.blocking === true;
+    const unreadMode = flags.unread === true;
+    const sessionIdArg = positionals[0];
+    // ── Initialise SessionManager ─────────────────────────────────────
+    const sessionManager = new SessionManager({
+        baseDir: getSessionDirectory(),
+    });
+    await sessionManager.initialize();
+    // ── Mode B: List unread sessions ──────────────────────────────────
+    // Default (no session-id) OR explicit --unread flag
+    if (!sessionIdArg || unreadMode) {
+        // Guard: if --blocking was passed without a session ID, that's an error
+        if (blockingMode && !sessionIdArg) {
+            outputResult({ success: false, error: "--blocking requires a session ID.\n\nUsage:\n  auq fetch-answers <session-id> [--blocking] [--json]\n  auq fetch-answers --unread [--json]" }, jsonMode);
+            process.exitCode = 1;
+            return;
+        }
+        return listUnreadSessions(sessionManager, jsonMode);
+    }
+    // ── Mode A: Fetch specific session ────────────────────────────────
+    return fetchSession(sessionManager, sessionIdArg, blockingMode, jsonMode);
+}
+// ── List Unread Sessions ──────────────────────────────────────────────
+async function listUnreadSessions(sessionManager, jsonMode) {
+    const unreadIds = await sessionManager.getUnreadSessions();
+    if (jsonMode) {
+        const entries = await Promise.all(unreadIds.map(async (sessionId) => {
+            const status = await sessionManager.getSessionStatus(sessionId);
+            const request = await sessionManager.getSessionRequest(sessionId);
+            return {
+                sessionId,
+                status: status?.status ?? "unknown",
+                createdAt: status?.createdAt ?? null,
+                lastReadAt: null,
+                questionCount: request?.questions?.length ?? status?.totalQuestions ?? 0,
+            };
+        }));
+        console.log(JSON.stringify(entries, null, 2));
+        return;
+    }
+    if (unreadIds.length === 0) {
+        console.log("No unread sessions.");
+        return;
+    }
+    console.log("Unread sessions:");
+    console.log("");
+    // Build table rows
+    const rows = [];
+    for (const sessionId of unreadIds) {
+        const status = await sessionManager.getSessionStatus(sessionId);
+        const request = await sessionManager.getSessionRequest(sessionId);
+        rows.push({
+            id: sessionId.slice(0, 8),
+            status: status?.status ?? "unknown",
+            age: status ? formatAge(status.createdAt) : "?",
+            questions: request?.questions?.length ?? status?.totalQuestions ?? 0,
+        });
+    }
+    // Print header
+    console.log("ID        Status     Age     Questions");
+    for (const row of rows) {
+        const id = row.id.padEnd(10);
+        const status = row.status.padEnd(11);
+        const age = row.age.padEnd(8);
+        console.log(`${id}${status}${age}${row.questions}`);
+    }
+}
+// ── Fetch Specific Session ────────────────────────────────────────────
+async function fetchSession(sessionManager, sessionIdArg, blockingMode, jsonMode) {
+    // ── Resolve session ID (full UUID or 8-char short prefix) ─────────
+    let sessionId;
+    if (sessionIdArg.length === 8) {
+        // Try prefix resolution
+        const allIds = await sessionManager.getAllSessionIds();
+        const match = allIds.find((id) => id.startsWith(sessionIdArg));
+        if (!match) {
+            outputResult({ success: false, error: `Session not found: ${sessionIdArg}` }, jsonMode);
+            process.exitCode = 1;
+            return;
+        }
+        sessionId = match;
+    }
+    else {
+        // Treat as full UUID
+        const exists = await sessionManager.sessionExists(sessionIdArg);
+        if (!exists) {
+            outputResult({ success: false, error: `Session not found: ${sessionIdArg}` }, jsonMode);
+            process.exitCode = 1;
+            return;
+        }
+        sessionId = sessionIdArg;
+    }
+    // ── Get current status ────────────────────────────────────────────
+    let status = await sessionManager.getSessionStatus(sessionId);
+    if (!status) {
+        outputResult({ success: false, error: `Could not read session data for: ${sessionId}` }, jsonMode);
+        process.exitCode = 1;
+        return;
+    }
+    // ── Handle blocking wait for pending/in-progress sessions ─────────
+    const isPending = status.status === "pending" || status.status === "in-progress";
+    if (isPending && blockingMode) {
+        try {
+            await sessionManager.waitForAnswers(sessionId);
+            // Re-read status after wait
+            status = await sessionManager.getSessionStatus(sessionId);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            if (errMsg === "SESSION_REJECTED") {
+                // Will be handled below after re-reading status
+                status = await sessionManager.getSessionStatus(sessionId);
+            }
+            else {
+                outputResult({ success: false, error: `Error waiting for answers: ${errMsg}` }, jsonMode);
+                process.exitCode = 1;
+                return;
+            }
+        }
+    }
+    // Re-check status after potential wait
+    const currentStatus = status?.status ?? "unknown";
+    // ── Handle completed session ──────────────────────────────────────
+    if (currentStatus === "completed") {
+        const request = await sessionManager.getSessionRequest(sessionId);
+        let answersData = null;
+        try {
+            answersData = await sessionManager.getSessionAnswers(sessionId);
+        }
+        catch {
+            // answers.json may not exist yet, treat as pending
+        }
+        if (!answersData || !request) {
+            outputResult({ success: false, error: `Could not read answers for: ${sessionId}` }, jsonMode);
+            process.exitCode = 1;
+            return;
+        }
+        // Mark as read
+        await sessionManager.markSessionAsRead(sessionId);
+        const lastReadAt = new Date().toISOString();
+        if (jsonMode) {
+            console.log(JSON.stringify({
+                sessionId,
+                status: "completed",
+                answers: answersData.answers,
+                lastReadAt,
+            }, null, 2));
+            return;
+        }
+        const formatted = ResponseFormatter.formatUserResponse(answersData, request.questions, sessionId);
+        console.log(formatted);
+        return;
+    }
+    // ── Handle pending/in-progress (non-blocking) ─────────────────────
+    if (currentStatus === "pending" || currentStatus === "in-progress") {
+        if (jsonMode) {
+            console.log(JSON.stringify({ sessionId, status: currentStatus, answers: null, lastReadAt: null }, null, 2));
+            return;
+        }
+        console.log(ResponseFormatter.formatPendingStatus(sessionId));
+        return;
+    }
+    // ── Handle rejected session ───────────────────────────────────────
+    if (currentStatus === "rejected") {
+        if (jsonMode) {
+            console.log(JSON.stringify({
+                sessionId,
+                status: "rejected",
+                answers: null,
+                lastReadAt: null,
+                rejectionReason: status?.rejectionReason ?? null,
+            }, null, 2));
+            return;
+        }
+        console.log(ResponseFormatter.formatRejectedStatus(sessionId, status?.rejectionReason));
+        return;
+    }
+    // ── Handle abandoned / timed_out ──────────────────────────────────
+    if (jsonMode) {
+        console.log(JSON.stringify({ sessionId, status: currentStatus, answers: null, lastReadAt: null }, null, 2));
+        return;
+    }
+    console.log(ResponseFormatter.formatSessionStatus(sessionId, currentStatus));
+}