auq-mcp-server 1.3.2 → 1.5.0

package/README.md

@@ -106,10 +106,7 @@ npm install auq-mcp-server
 
 ```
 
-**Session Storage:**
-
-- **Global install**: `~/Library/Application Support/auq/sessions` (macOS), `~/.local/share/auq/sessions` (Linux)
-- **Local install**: `.auq/sessions/` in your project root
+**Note:** Sessions are stored globally regardless of installation method. See [Troubleshooting](#troubleshooting) for session locations.
 
 ---
 
@@ -208,7 +205,7 @@ Add to `opencode.json`:
 
 ```json
 {
-  "plugin": ["@paulp-o/opencode-auq"]
+  "plugin": ["@paulp-o/opencode-auq@latest"]
 }
 ```
 
@@ -219,8 +216,8 @@ Add to `opencode.json`:
 ### Starting the CLI tool
 
 ```bash
-auq  # if you installed globally
-npx auq  # if you installed locally
+auq      # if installed globally (npm install -g)
+npx auq  # works from anywhere
 ```
 
 Then just start working with your coding agent or AI assistant. You may prompt to ask questions with the tool the agent got; it will mostly just get what you mean.
@@ -234,66 +231,101 @@ auq --version    # Show version
 auq --help       # Show help
 ```
 
+---
+
+### Manual session cleanup
+
+Sessions auto-clean after completion or timeout. However, you can manually clean them up if you want to.
+
+```bash
+rm -rf ~/Library/Application\ Support/auq/sessions/*  # macOS
+rm -rf ~/.local/share/auq/sessions/*                  # Linux
+```
+
+---
+
 <details>
-<summary><strong>🔍 auq ask 명령어 상세 설명 (클릭하여 펼치기)</strong></summary>
+<summary>Local Development & Testing</summary>
+
+To test the MCP server and CLI locally during development:
 
-<br>
+### 1. Start the MCP Server (Terminal 1)
 
-`auq ask`는 AI 코딩 에이전트가 사용자에게 질문을 할 때 사용하는 핵심 명령어입니다.
+```bash
+# Option A: Run with tsx (recommended for development)
+npm run start
+
+# Option B: Run with fastmcp dev mode (includes web inspector at http://localhost:6274)
+npm run dev
+
+# Option C: Run the built version
+npm run build && npm run server
+```
 
-#### 기본 사용법
+### 2. Create a Test Session (Terminal 2)
+
+Use the `auq ask` command to create a session and wait for answers:
 
 ```bash
-auq ask
+# Run directly with tsx during development
+npx tsx bin/auq.tsx ask '{"questions": [{"prompt": "Which language?", "title": "Lang", "options": [{"label": "TypeScript"}, {"label": "Python"}], "multiSelect": false}]}'
+
+# Or pipe JSON to stdin
+echo '{"questions": [{"prompt": "Which database?", "title": "DB", "options": [{"label": "PostgreSQL"}, {"label": "MongoDB"}], "multiSelect": false}]}' | npx tsx bin/auq.tsx ask
 ```
 
-이 명령어를 실행하면 대화형 터미널 인터페이스가 시작되어 AI 에이전트의 질문 세트를 기다립니다.
+This will create a session and wait for the TUI to provide answers.
 
-#### 작동 방식
+### 3. Answer with the TUI (Terminal 3)
 
-1. **질문 수신 대기**: AI 에이전트(MCP 클라이언트)가 질문을 보내면 자동으로 표시됩니다
-2. **질문 세트 처리**: 여러 개의 연관된 질문을 하나의 세트로 묶어서 처리
-3. **사용자 응답**: 각 질문에 대해 답변을 입력하거나 건너뛸 수 있음
-4. **응답 전송**: 모든 답변을 완료하면 AI 에이전트로 결과가 전송됩니다
+```bash
+# Run the TUI to answer pending questions
+npx tsx bin/auq.tsx
+```
 
-#### 주요 특징
+### Create Mock Sessions for TUI Testing
 
-- **비차단 방식**: AI가 질문을 보내는 동안에도 계속 작업할 수 있음
-- **다중 에이전트 지원**: 여러 AI 에이전트의 질문을 동시에 처리
-- **세션 관리**: 각 질문 세트는 독립적인 세션으로 관리됨
-- **타임아웃 처리**: 일정 시간 동안 응답이 없으면 세션이 자동 종료
+To test the TUI with multiple pending sessions:
 
-#### 예시 워크플로우
+```bash
+# Create 3 mock sessions (default)
+npx tsx scripts/create-mock-session.ts
 
+# Create a specific number of sessions
+npx tsx scripts/create-mock-session.ts 5
 ```
-1. AI 에이전트가 복잡한 코드를 작성 중
-2. AI가 "이 함수의 반환 타입을 어떻게 할까요?"라고 질문
-3. auq ask가 실행되어 질문이 터미널에 표시
-4. 사용자가 답변 입력
-5. AI가 답변을 받아서 코드 작성 계속 진행
+
+Then run the TUI to see and answer them:
+
+```bash
+npx tsx bin/auq.tsx
 ```
 
-#### 문제 해결
+### Verify MCP and CLI Use Same Session Directory
+
+Both components should report the same session directory path. Check the logs:
 
-- **질문이 표시되지 않음**: MCP 서버가 제대로 실행되고 있는지 확인
-- **응답이 전송되지 않음**: 네트워크 연결과 세션 상태 확인
-- **세션이 중단됨**: 타임아웃 설정이나 세션 관리 확인
+- MCP server logs session directory on startup
+- `auq ask` prints `[AUQ] Session directory: <path>` to stderr
+
+On macOS, both should use: `~/Library/Application Support/auq/sessions`
 
 </details>
 
----
+## Troubleshooting
 
-### Manual session cleanup
+### Session Storage
 
-Sessions auto-clean after completion or timeout. However, you can manually clean them up if you want to.
+Sessions are stored in platform-specific global locations:
 
-```bash
-# Global install
-rm -rf ~/Library/Application\ Support/auq/sessions/*  # macOS
-rm -rf ~/.local/share/auq/sessions/*                  # Linux
+- **macOS**: `~/Library/Application Support/auq/sessions`
+- **Linux**: `~/.local/share/auq/sessions` (or `$XDG_DATA_HOME/auq/sessions`)
+- **Windows**: `%APPDATA%\auq\sessions`
 
-# Local install
-rm -rf .auq/sessions/*
+To override the default location, set the `AUQ_SESSION_DIR` environment variable:
+
+```bash
+export AUQ_SESSION_DIR=/custom/path
 ```
 
 ---

package/dist/bin/auq.js

@@ -40,12 +40,11 @@ ASK COMMAND:
   - Multi-select mode (multiSelect: true): User can select MULTIPLE options
 
   USAGE NOTES:
-  - Always provide a descriptive 'title' field (max 12 chars) for each question
+  - Provide a descriptive 'title' field (max 12 chars) for each question
   - Use multiSelect: true when choices are not mutually exclusive
   - Option labels should be concise (1-5 words)
-  - Questions should end with a question mark
+  - To mark a recommended option, append '(recommended)' to its label
   - Don't include an 'Other' option - it's provided automatically
-  - Mark one option as recommended.
 
   Returns a formatted summary of all questions and answers.
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auq-mcp-server",
-    "version": "1.3.2",
+    "version": "1.5.0",
     "main": "dist/index.js",
     "bin": {
         "auq": "dist/bin/auq.js"
@@ -15,17 +15,16 @@
         "packages/opencode-plugin"
     ],
     "scripts": {
-        "build": "npm run sync-schemas && tsc",
+        "build": "npm run sync-plugin-schemas && tsc",
         "prepare": "npm run build",
         "postinstall": "node scripts/postinstall.cjs",
-        "deploy": "node scripts/deploy.mjs",
         "release": "semantic-release",
         "release:dry-run": "semantic-release --dry-run",
         "server": "node dist/src/server.js",
         "start": "tsx src/server.ts",
         "dev": "fastmcp dev src/server.ts",
         "lint": "prettier --check . && eslint . && tsc --noEmit",
-        "sync-schemas": "node scripts/sync-schemas.mjs",
+        "sync-plugin-schemas": "node scripts/sync-plugin-schemas.mjs",
         "test": "vitest run",
         "format": "prettier --write . && eslint --fix ."
     },
@@ -72,7 +71,12 @@
                     "changelogFile": "CHANGELOG.md"
                 }
             ],
-            "@semantic-release/npm",
+            [
+                "@semantic-release/npm",
+                {
+                    "workspaces": true
+                }
+            ],
             "@semantic-release/github"
         ]
     },

package/dist/src/server.js

@@ -1,6 +1,7 @@
 import { FastMCP } from "fastmcp";
 import { randomUUID } from "crypto";
 import { AskUserQuestionsParametersSchema, createAskUserQuestionsCore, } from "./core/ask-user-questions.js";
+import { TOOL_DESCRIPTION } from "./shared/schemas.js";
 const askUserQuestionsCore = createAskUserQuestionsCore();
 const server = new FastMCP({
     name: "AskUserQuestions",
@@ -17,27 +18,7 @@ server.addTool({
         readOnlyHint: false, // This tool waits for user input
         idempotentHint: true,
     },
-    description: "Use this tool when you need to ask the user questions during execution. " +
-        "This allows you to:\n" +
-        "1. Gather user preferences or requirements\n" +
-        "2. Clarify ambiguous instructions\n" +
-        "3. Get decisions on implementation choices as you work\n" +
-        "4. Offer choices to the user about what direction to take\n\n" +
-        "FEATURES:\n" +
-        "- Ask 1-4 structured questions via an interactive terminal interface\n" +
-        "- Each question includes 2-4 multiple-choice options with explanatory descriptions\n" +
-        "- Users can always provide custom free-text input as an alternative to predefined options\n" +
-        "- Single-select mode (default): User picks ONE option or provides custom text\n" +
-        "- Multi-select mode (multiSelect: true): User can select MULTIPLE options\n\n" +
-        "USAGE NOTES:\n" +
-        "- Always provide a descriptive 'title' field (max 12 chars) for each question\n" +
-        "- Use multiSelect: true when choices are not mutually exclusive\n" +
-        "- Option labels should be concise (1-5 words)\n" +
-        "- Questions should end with a question mark\n" +
-        "- Don't include an 'Other' option - it's provided automatically\n" +
-        "- Mark one option as recommended.\n\n" +
-        "- If user seems not aware how to answer the question, inform them that they need to install the 'auq' cli tool.\n\n" +
-        "Returns a formatted summary of all questions and answers.",
+    description: TOOL_DESCRIPTION,
     execute: async (args, ctx) => {
         const { log } = ctx;
         try {

package/dist/src/session/__tests__/utils.test.js

@@ -0,0 +1,152 @@
+/**
+ * Unit tests for session utility functions
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { homedir } from "os";
+import { getSessionDirectory, resolveSessionDirectory } from "../utils.js";
+describe("session utilities", () => {
+    const originalEnv = { ...process.env };
+    const originalPlatform = process.platform;
+    beforeEach(() => {
+        // Reset process.env to original state before each test
+        process.env = { ...originalEnv };
+        vi.restoreAllMocks();
+    });
+    afterEach(() => {
+        // Clean up process.env after each test
+        process.env = { ...originalEnv };
+    });
+    describe("getSessionDirectory", () => {
+        it("should return macOS XDG path when no env var is set", () => {
+            // Mock platform to macOS
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "darwin",
+            });
+            // Ensure AUQ_SESSION_DIR is not set
+            delete process.env.AUQ_SESSION_DIR;
+            const result = getSessionDirectory();
+            expect(result).toBe(`${homedir()}/Library/Application Support/auq/sessions`);
+        });
+        it("should return Linux XDG path when no env var is set", () => {
+            // Mock platform to Linux
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "linux",
+            });
+            // Ensure AUQ_SESSION_DIR is not set
+            delete process.env.AUQ_SESSION_DIR;
+            const result = getSessionDirectory();
+            expect(result).toBe(`${homedir()}/.local/share/auq/sessions`);
+        });
+        it("should use AUQ_SESSION_DIR env var when set", () => {
+            const customDir = "/custom/session/dir";
+            process.env.AUQ_SESSION_DIR = customDir;
+            const result = getSessionDirectory();
+            expect(result).toBe(customDir);
+        });
+        it("should expand tilde in AUQ_SESSION_DIR env var", () => {
+            process.env.AUQ_SESSION_DIR = "~/custom/sessions";
+            const result = getSessionDirectory();
+            expect(result).toBe(`${homedir()}/custom/sessions`);
+        });
+        it("should not expand tilde when AUQ_SESSION_DIR does not start with ~", () => {
+            const customDir = "/absolute/path/to/sessions";
+            process.env.AUQ_SESSION_DIR = customDir;
+            const result = getSessionDirectory();
+            expect(result).toBe(customDir);
+        });
+        it("should prefer AUQ_SESSION_DIR over XDG path", () => {
+            const customDir = "/custom/sessions";
+            process.env.AUQ_SESSION_DIR = customDir;
+            // Mock platform to macOS
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "darwin",
+            });
+            const result = getSessionDirectory();
+            // Should use env var, not the macOS default
+            expect(result).toBe(customDir);
+            expect(result).not.toBe(`${homedir()}/Library/Application Support/auq/sessions`);
+        });
+    });
+    describe("resolveSessionDirectory", () => {
+        it("should return macOS path when platform is darwin", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "darwin",
+            });
+            const result = resolveSessionDirectory();
+            expect(result).toBe(`${homedir()}/Library/Application Support/auq/sessions`);
+        });
+        it("should return Linux path when platform is linux", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "linux",
+            });
+            const result = resolveSessionDirectory();
+            expect(result).toBe(`${homedir()}/.local/share/auq/sessions`);
+        });
+        it("should return Windows path when platform is win32 with APPDATA", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "win32",
+                env: {
+                    ...process.env,
+                    APPDATA: "C:/Users/Test/AppData/Roaming",
+                },
+            });
+            const result = resolveSessionDirectory();
+            // Note: join() uses forward slashes when running on Unix systems
+            expect(result).toBe("C:/Users/Test/AppData/Roaming/auq/sessions");
+        });
+        it("should return Windows path with USERPROFILE fallback when APPDATA not set", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "win32",
+                env: {
+                    ...process.env,
+                    APPDATA: undefined,
+                    USERPROFILE: "C:/Users/Test",
+                },
+            });
+            const result = resolveSessionDirectory();
+            // Note: join() uses forward slashes when running on Unix systems
+            expect(result).toBe("C:/Users/Test/auq/sessions");
+        });
+        it("should return Linux XDG_DATA_HOME path when env var is set", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "linux",
+                env: {
+                    ...process.env,
+                    XDG_DATA_HOME: "/custom/xdg/data",
+                },
+            });
+            const result = resolveSessionDirectory();
+            expect(result).toBe("/custom/xdg/data/auq/sessions");
+        });
+        it("should expand tilde in provided baseDir", () => {
+            const result = resolveSessionDirectory("~/custom/base");
+            expect(result).toBe(`${homedir()}/custom/base`);
+        });
+        it("should use provided baseDir when it does not start with tilde", () => {
+            const result = resolveSessionDirectory("/absolute/custom/path");
+            expect(result).toBe("/absolute/custom/path");
+        });
+        it("should handle other Unix platforms (e.g., freebsd)", () => {
+            vi.stubGlobal("process", {
+                ...process,
+                platform: "freebsd",
+            });
+            const result = resolveSessionDirectory();
+            expect(result).toBe(`${homedir()}/.local/share/auq/sessions`);
+        });
+        it("should handle empty baseDir parameter", () => {
+            const result = resolveSessionDirectory("");
+            // Should treat empty string as falsy and use default XDG path
+            expect(result).toContain(homedir());
+            expect(result).toContain("auq/sessions");
+        });
+    });
+});

package/dist/src/session/utils.js

@@ -1,11 +1,10 @@
 /**
  * Utility functions for session management
  */
-import { constants, existsSync } from "fs";
+import { constants } from "fs";
 import { promises as fs } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-import { fileURLToPath } from "url";
 /**
  * Create a safe filename from a session ID (basic validation)
  */
@@ -125,39 +124,13 @@ export async function validateSessionDirectory(baseDir) {
     }
 }
 /**
- * Detect whether AUQ is installed globally or locally
- * by inspecting the module's location
- */
-export function detectInstallMode() {
-    try {
-        // Get current module's file path
-        const __filename = fileURLToPath(import.meta.url);
-        const parts = __filename.split(/[/\\]/); // Handle both Unix and Windows separators
-        // Find the last occurrence of 'node_modules' in the path
-        const nodeModulesIndex = parts.lastIndexOf("node_modules");
-        if (nodeModulesIndex === -1) {
-            // Not in node_modules (development or global install without node_modules in path)
-            return { mode: "global" };
-        }
-        // We're inside node_modules - check if there's a project package.json above
-        const potentialProjectRoot = parts.slice(0, nodeModulesIndex).join("/");
-        const packageJsonPath = join(potentialProjectRoot, "package.json");
-        if (existsSync(packageJsonPath)) {
-            // Found a package.json above node_modules → local install
-            return { mode: "local", projectRoot: potentialProjectRoot };
-        }
-        // In node_modules but no project context → global install
-        return { mode: "global" };
-    }
-    catch (error) {
-        // Fallback to global mode if detection fails
-        console.error("[AUQ] Failed to detect install mode:", error);
-        return { mode: "global" };
-    }
-}
-/**
- * Get the appropriate session directory based on installation mode
- * Supports environment variable override via AUQ_SESSION_DIR
+ * Get the session directory path.
+ * Always uses global XDG-compliant paths to ensure MCP server and CLI
+ * always find each other's sessions regardless of installation location.
+ *
+ * Priority:
+ * 1. AUQ_SESSION_DIR environment variable (if set)
+ * 2. Platform-specific XDG-compliant path
  */
 export function getSessionDirectory() {
     // Check for environment variable override first
@@ -169,12 +142,6 @@ export function getSessionDirectory() {
         }
         return envDir;
     }
-    // Auto-detect installation mode
-    const { mode, projectRoot } = detectInstallMode();
-    if (mode === "local" && projectRoot) {
-        // Local install: use project-relative .auq/sessions directory
-        return join(projectRoot, ".auq", "sessions");
-    }
-    // Global install: use XDG-compliant system paths
+    // Always use global XDG-compliant paths
     return resolveSessionDirectory();
 }

package/dist/src/shared/schemas.js

@@ -2,8 +2,8 @@ import { z } from "zod";
 export const OptionSchema = z.object({
     label: z
         .string()
-        .describe("The display text for this option that the user will see and select. " +
-        "Should be concise (1-5 words) and clearly describe the choice."),
+        .describe("The display text for this option. Should be concise (1-5 words). " +
+        "To mark as recommended, append '(recommended)' to the label text."),
     description: z
         .string()
         .optional()
@@ -38,13 +38,19 @@ export const QuestionsSchema = z.array(QuestionSchema).min(1).max(4);
 export const AskUserQuestionsParametersSchema = z.object({
     questions: QuestionsSchema.describe("Questions to ask the user (1-4 questions). " +
         "Each question must include: prompt (full question text), title (short label, max 12 chars), " +
-        "options (2-4 choices with labels and descriptions), and multiSelect (boolean). " +
-        "Mark one choice as recommended if possible."),
+        "options (2-4 choices with labels and descriptions), and multiSelect (boolean)."),
 });
-export const TOOL_DESCRIPTION = "Ask users structured questions during execution to gather preferences, clarify requirements, or make implementation decisions.\n\n" +
-    "FEATURES:\n" +
-    "- Non-blocking: doesn't halt AI workflow\n" +
-    "- 1-4 questions with 2-4 options each\n" +
-    "- Single/multi-select modes\n" +
-    "- Custom text input always available\n\n" +
-    "Returns formatted responses for continued reasoning.";
+/**
+ * Comprehensive tool description - single source of truth.
+ * Used by MCP server and should be synced to opencode-plugin.
+ */
+export const TOOL_DESCRIPTION = "Use this tool when you need to ask the user questions during execution. This allows you to:\n\n" +
+    "Gather user preferences or requirements\n" +
+    "Clarify ambiguous instructions\n" +
+    "Get decisions on implementation choices as you work\n" +
+    "Offer choices to the user about what direction to take.\n" +
+    "Usage notes:\n\n" +
+    "Users will always be able to select \"Other\" to provide custom text input\n" +
+    "Use multiSelect: true to allow multiple answers to be selected for a question\n" +
+    "Recommend an option unless absolutely necessary, make it the first option in the list and add \"(Recommended)\" at the end of the label\n" +
+    "Do NOT use this tool to ask \"Is my plan ready?\" or \"Should I proceed?\"";

package/dist/src/tui/components/Header.js

@@ -24,7 +24,7 @@ export const Header = ({ pendingCount }) => {
         return packageJson.version || "unknown";
     }, []);
     // Use the selected gradient theme from theme.ts
-    const headerText = gradient[theme.headerGradient](".𖥔 AUQ ⋆ Ask User Questions MCP ⋆ ");
+    const headerText = gradient[theme.headerGradient](".𖥔 AUQ ⋆ Ask User Questions ⋆ ");
     return (React.createElement(Box, { borderColor: theme.components.header.border, borderStyle: "single", flexDirection: "row", justifyContent: "space-between", paddingX: 1 },
         React.createElement(Text, { bold: true }, headerText),
         React.createElement(Box, null,

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

@@ -164,7 +164,7 @@ export class EnhancedTUISessionWatcher extends TUISessionWatcher {
 }
 /**
  * Create a simple TUI session watcher instance
- * Auto-detects session directory based on global vs local install
+ * Uses global XDG-compliant session directory path
  */
 export function createTUIWatcher(config) {
     // Auto-detect session directory if not provided in config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auq-mcp-server",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "main": "dist/index.js",
   "bin": {
     "auq": "dist/bin/auq.js"
@@ -15,17 +15,16 @@
     "packages/opencode-plugin"
   ],
   "scripts": {
-    "build": "npm run sync-schemas && tsc",
+    "build": "npm run sync-plugin-schemas && tsc",
     "prepare": "npm run build",
     "postinstall": "node scripts/postinstall.cjs",
-    "deploy": "node scripts/deploy.mjs",
     "release": "semantic-release",
     "release:dry-run": "semantic-release --dry-run",
     "server": "node dist/src/server.js",
     "start": "tsx src/server.ts",
     "dev": "fastmcp dev src/server.ts",
     "lint": "prettier --check . && eslint . && tsc --noEmit",
-    "sync-schemas": "node scripts/sync-schemas.mjs",
+    "sync-plugin-schemas": "node scripts/sync-plugin-schemas.mjs",
     "test": "vitest run",
     "format": "prettier --write . && eslint --fix ."
   },
@@ -72,7 +71,12 @@
           "changelogFile": "CHANGELOG.md"
         }
       ],
-      "@semantic-release/npm",
+      [
+        "@semantic-release/npm",
+        {
+          "workspaces": true
+        }
+      ],
       "@semantic-release/github"
     ]
   },