auq-mcp-server 2.3.0 → 2.4.0

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

@@ -0,0 +1,282 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "fs";
+import { join } from "path";
+import { runSessionsCommand } from "../sessions.js";
+import { SessionManager } from "../../../session/SessionManager.js";
+const TEST_BASE_DIR = "/tmp/auq-test-cli-sessions";
+const TEST_ARCHIVE_DIR = "/tmp/auq-test-cli-sessions-archive";
+/**
+ * Helper: create a session with a given createdAt timestamp
+ */
+async function createTestSession(manager, opts = {}) {
+    const questionCount = opts.questionCount ?? 1;
+    const questions = Array.from({ length: questionCount }, (_, i) => ({
+        title: `Q${i}`,
+        prompt: `Question ${i}?`,
+        options: [
+            { label: "A", description: "Option A" },
+            { label: "B", description: "Option B" },
+        ],
+    }));
+    const sessionId = await manager.createSession(questions);
+    // Patch createdAt if requested
+    if (opts.createdAt) {
+        const status = await manager.getSessionStatus(sessionId);
+        if (status) {
+            await manager.updateSessionStatus(sessionId, status.status, {
+                createdAt: opts.createdAt,
+            });
+        }
+    }
+    // Transition status if requested
+    if (opts.status && opts.status !== "pending") {
+        await manager.updateSessionStatus(sessionId, opts.status);
+    }
+    return sessionId;
+}
+describe("sessions command", () => {
+    let consoleLogSpy;
+    let consoleErrorSpy;
+    let consoleWarnSpy;
+    let sessionManager;
+    const originalEnv = { ...process.env };
+    beforeEach(async () => {
+        // Clean up test dirs
+        await fs.rm(TEST_BASE_DIR, { force: true, recursive: true });
+        await fs.rm(TEST_ARCHIVE_DIR, { force: true, recursive: true });
+        // Point to test directories
+        process.env.AUQ_SESSION_DIR = TEST_BASE_DIR;
+        process.env.XDG_DATA_HOME = "/tmp/auq-test-cli-sessions-archive";
+        process.exitCode = undefined;
+        consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => { });
+        consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        consoleWarnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+        // Create a SessionManager for setting up test fixtures
+        sessionManager = new SessionManager({ baseDir: TEST_BASE_DIR });
+        await sessionManager.initialize();
+    });
+    afterEach(async () => {
+        consoleLogSpy.mockRestore();
+        consoleErrorSpy.mockRestore();
+        consoleWarnSpy.mockRestore();
+        vi.restoreAllMocks();
+        process.exitCode = undefined;
+        process.env = { ...originalEnv };
+        // Clean up
+        await fs.rm(TEST_BASE_DIR, { force: true, recursive: true }).catch(() => { });
+        await fs.rm(TEST_ARCHIVE_DIR, { force: true, recursive: true }).catch(() => { });
+    });
+    // ── Sessions List ─────────────────────────────────────────────────
+    describe("sessions list", () => {
+        it("should list pending sessions by default", async () => {
+            const id1 = await createTestSession(sessionManager);
+            const id2 = await createTestSession(sessionManager, {
+                status: "completed",
+            });
+            await runSessionsCommand(["list"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(id1);
+            expect(allOutput).not.toContain(id2);
+        });
+        it("should show empty message when no sessions", async () => {
+            await runSessionsCommand(["list"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain("No sessions found");
+        });
+        it("should list in-progress sessions with default filter", async () => {
+            const id1 = await createTestSession(sessionManager, {
+                status: "in-progress",
+            });
+            await runSessionsCommand(["list"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(id1);
+        });
+        it("should show only stale sessions with --stale flag", async () => {
+            // Create a stale session (3 hours ago)
+            const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+            const staleId = await createTestSession(sessionManager, {
+                createdAt: threeHoursAgo,
+            });
+            // Create a fresh session
+            const freshId = await createTestSession(sessionManager);
+            await runSessionsCommand(["list", "--stale"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(staleId);
+            expect(allOutput).not.toContain(freshId);
+        });
+        it("should show all sessions with --all flag", async () => {
+            const pendingId = await createTestSession(sessionManager);
+            const completedId = await createTestSession(sessionManager, {
+                status: "completed",
+            });
+            const abandonedId = await createTestSession(sessionManager, {
+                status: "abandoned",
+            });
+            await runSessionsCommand(["list", "--all"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(pendingId);
+            expect(allOutput).toContain(completedId);
+            expect(allOutput).toContain(abandonedId);
+        });
+        it("should show --pending as same as default", async () => {
+            const pendingId = await createTestSession(sessionManager);
+            const completedId = await createTestSession(sessionManager, {
+                status: "completed",
+            });
+            await runSessionsCommand(["list", "--pending"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain(pendingId);
+            expect(allOutput).not.toContain(completedId);
+        });
+        it("should sort sessions newest first", async () => {
+            const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString();
+            const oneHourAgo = new Date(Date.now() - 1 * 60 * 60 * 1000).toISOString();
+            const oldId = await createTestSession(sessionManager, {
+                createdAt: twoHoursAgo,
+            });
+            const newId = await createTestSession(sessionManager, {
+                createdAt: oneHourAgo,
+            });
+            await runSessionsCommand(["list"]);
+            // Find which order they appear in output
+            const calls = consoleLogSpy.mock.calls.map((c) => String(c[0]));
+            const oldIdx = calls.findIndex((c) => c.includes(oldId));
+            const newIdx = calls.findIndex((c) => c.includes(newId));
+            expect(newIdx).toBeLessThan(oldIdx);
+        });
+        it("should show stale indicator for stale sessions", async () => {
+            const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+            const staleId = await createTestSession(sessionManager, {
+                createdAt: threeHoursAgo,
+            });
+            await runSessionsCommand(["list"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain("\u26a0");
+        });
+        it("should output valid JSON array with --json flag", async () => {
+            const id = await createTestSession(sessionManager, {
+                questionCount: 3,
+            });
+            await runSessionsCommand(["list", "--json"]);
+            expect(consoleLogSpy).toHaveBeenCalledTimes(1);
+            const output = consoleLogSpy.mock.calls[0][0];
+            const parsed = JSON.parse(output);
+            expect(Array.isArray(parsed)).toBe(true);
+            expect(parsed.length).toBe(1);
+            expect(parsed[0].sessionId).toBe(id);
+            expect(parsed[0].status).toBe("pending");
+            expect(parsed[0].createdAt).toBeDefined();
+            expect(parsed[0].age).toBeDefined();
+            expect(typeof parsed[0].stale).toBe("boolean");
+            expect(parsed[0].questionCount).toBe(3);
+        });
+        it("should include question count in output", async () => {
+            await createTestSession(sessionManager, {
+                questionCount: 5,
+            });
+            await runSessionsCommand(["list"]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain("questions: 5");
+        });
+    });
+    // ── Sessions Dismiss ──────────────────────────────────────────────
+    describe("sessions dismiss", () => {
+        it("should dismiss a stale session successfully", async () => {
+            const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+            const sessionId = await createTestSession(sessionManager, {
+                createdAt: threeHoursAgo,
+            });
+            await runSessionsCommand(["dismiss", sessionId]);
+            expect(process.exitCode).toBeUndefined();
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain("dismissed");
+            expect(allOutput).toContain("archived");
+        });
+        it("should archive files to correct directory", async () => {
+            const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+            const sessionId = await createTestSession(sessionManager, {
+                createdAt: threeHoursAgo,
+            });
+            await runSessionsCommand(["dismiss", sessionId]);
+            // Check archive directory contains files
+            const archiveDir = join(TEST_ARCHIVE_DIR, "auq", "archive", sessionId);
+            const archivedFiles = await fs.readdir(archiveDir);
+            expect(archivedFiles.length).toBeGreaterThan(0);
+            expect(archivedFiles).toContain("status.json");
+            expect(archivedFiles).toContain("request.json");
+        });
+        it("should remove session from active directory after dismiss", async () => {
+            const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+            const sessionId = await createTestSession(sessionManager, {
+                createdAt: threeHoursAgo,
+            });
+            await runSessionsCommand(["dismiss", sessionId]);
+            // Session should no longer exist in active
+            const exists = await sessionManager.sessionExists(sessionId);
+            expect(exists).toBe(false);
+        });
+        it("should error on non-stale session without --force", async () => {
+            const sessionId = await createTestSession(sessionManager);
+            await runSessionsCommand(["dismiss", sessionId]);
+            expect(process.exitCode).toBe(1);
+            const errorOutput = consoleErrorSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(errorOutput).toContain("not stale");
+        });
+        it("should dismiss non-stale session with --force", async () => {
+            const sessionId = await createTestSession(sessionManager);
+            await runSessionsCommand(["dismiss", sessionId, "--force"]);
+            expect(process.exitCode).toBeUndefined();
+            const exists = await sessionManager.sessionExists(sessionId);
+            expect(exists).toBe(false);
+        });
+        it("should error on non-existent session", async () => {
+            const fakeId = "00000000-0000-4000-a000-000000000000";
+            await runSessionsCommand(["dismiss", fakeId]);
+            expect(process.exitCode).toBe(1);
+            const errorOutput = consoleErrorSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(errorOutput).toContain("not found");
+        });
+        it("should error when sessionId is missing", async () => {
+            await runSessionsCommand(["dismiss"]);
+            expect(process.exitCode).toBe(1);
+            const errorOutput = consoleErrorSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(errorOutput).toContain("Missing session ID");
+        });
+        it("should output valid JSON with --json flag", async () => {
+            const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
+            const sessionId = await createTestSession(sessionManager, {
+                createdAt: threeHoursAgo,
+            });
+            await runSessionsCommand(["dismiss", sessionId, "--json"]);
+            expect(consoleLogSpy).toHaveBeenCalled();
+            // Find the JSON output (outputResult uses console.log)
+            const jsonCalls = consoleLogSpy.mock.calls.filter((c) => {
+                try {
+                    JSON.parse(c[0]);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            expect(jsonCalls.length).toBeGreaterThanOrEqual(1);
+            const parsed = JSON.parse(jsonCalls[0][0]);
+            expect(parsed.success).toBe(true);
+            expect(parsed.sessionId).toBe(sessionId);
+            expect(parsed.archivedTo).toBeDefined();
+            expect(parsed.archivedTo).toContain(sessionId);
+        });
+    });
+    // ── Sessions help ─────────────────────────────────────────────────
+    describe("sessions help", () => {
+        it("should show usage help when no subcommand provided", async () => {
+            await runSessionsCommand([]);
+            const allOutput = consoleLogSpy.mock.calls.map((c) => c[0]).join("\n");
+            expect(allOutput).toContain("Usage");
+        });
+        it("should set exitCode for unknown subcommand", async () => {
+            await runSessionsCommand(["unknown"]);
+            expect(process.exitCode).toBe(1);
+        });
+    });
+});

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

@@ -0,0 +1,128 @@
+/**
+ * CLI Answer Command — `auq answer <sessionId>`
+ * Allows answering or rejecting sessions programmatically.
+ */
+import { SessionManager } from "../../session/SessionManager.js";
+import { getSessionDirectory } from "../../session/utils.js";
+import { outputResult, parseFlags } from "../utils.js";
+/**
+ * Run the `auq answer` command.
+ *
+ * Usage:
+ *   auq answer <sessionId> --answers '{"0": {"selectedOption": "opt1"}}'
+ *   auq answer <sessionId> --reject [--reason "..."]
+ *   auq answer <sessionId> --answers '...' --force   # force-answer abandoned session
+ *   auq answer <sessionId> --reject --json
+ */
+export async function runAnswerCommand(args) {
+    const { flags, positionals } = parseFlags(args);
+    const jsonMode = flags.json === true;
+    const sessionId = positionals[0];
+    // ── Validate sessionId ───────────────────────────────────────────
+    if (!sessionId) {
+        outputResult({
+            success: false,
+            error: "Missing session ID. Usage: auq answer <sessionId> --answers '{...}' | --reject [--reason \"...\"]'",
+        }, jsonMode);
+        process.exit(1);
+        return; // unreachable, keeps TS happy
+    }
+    // ── Initialise SessionManager ─────────────────────────────────────
+    const sessionManager = new SessionManager({
+        baseDir: getSessionDirectory(),
+    });
+    await sessionManager.initialize();
+    // ── Verify session exists ────────────────────────────────────────
+    const exists = await sessionManager.sessionExists(sessionId);
+    if (!exists) {
+        outputResult({ success: false, error: `Session not found: ${sessionId}` }, jsonMode);
+        process.exit(1);
+        return;
+    }
+    // ── Check for abandoned status ───────────────────────────────────
+    const status = await sessionManager.getSessionStatus(sessionId);
+    if (status?.status === "abandoned" && !flags.force) {
+        outputResult({
+            success: false,
+            error: "Warning: AI disconnected. Use --force to answer anyway.",
+        }, jsonMode);
+        process.exit(1);
+        return;
+    }
+    if (status?.status === "abandoned" && flags.force) {
+        // Proceed with a warning in human-readable mode
+        if (!jsonMode) {
+            console.warn("Warning: AI disconnected, proceeding with --force.");
+        }
+    }
+    // ── Reject path ──────────────────────────────────────────────────
+    if (flags.reject) {
+        const reason = typeof flags.reason === "string" ? flags.reason : undefined;
+        await sessionManager.rejectSession(sessionId, reason);
+        outputResult({ success: true, sessionId, status: "rejected" }, jsonMode);
+        if (!jsonMode) {
+            console.log(`Session ${sessionId} rejected.`);
+        }
+        return;
+    }
+    // ── Answer path ──────────────────────────────────────────────────
+    const answersRaw = flags.answers;
+    if (!answersRaw || typeof answersRaw !== "string") {
+        outputResult({
+            success: false,
+            error: "Either --answers or --reject is required. Usage: auq answer <sessionId> --answers '{...}'",
+        }, jsonMode);
+        process.exit(1);
+        return;
+    }
+    // Parse the answers JSON
+    let parsed;
+    try {
+        parsed = JSON.parse(answersRaw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("Answers must be a JSON object with numeric keys.");
+        }
+    }
+    catch (err) {
+        outputResult({
+            success: false,
+            error: `Invalid answers JSON: ${err instanceof Error ? err.message : String(err)}`,
+        }, jsonMode);
+        process.exit(1);
+        return;
+    }
+    // Read session request to get expected questions
+    const request = await sessionManager.getSessionRequest(sessionId);
+    if (!request) {
+        outputResult({ success: false, error: `Session request not found: ${sessionId}` }, jsonMode);
+        process.exit(1);
+        return;
+    }
+    // Transform answers to UserAnswer[] format
+    const answers = Object.entries(parsed).map(([idx, ans]) => {
+        const a = ans;
+        return {
+            questionIndex: parseInt(idx, 10),
+            selectedOption: typeof a.selectedOption === "string"
+                ? a.selectedOption
+                : undefined,
+            selectedOptions: Array.isArray(a.selectedOptions)
+                ? a.selectedOptions
+                : undefined,
+            customText: typeof a.customText === "string" ? a.customText : undefined,
+            timestamp: new Date().toISOString(),
+        };
+    });
+    // Save answers through SessionManager
+    const callId = status?.callId;
+    await sessionManager.saveSessionAnswers(sessionId, {
+        sessionId,
+        timestamp: new Date().toISOString(),
+        answers,
+        ...(callId && { callId }),
+    });
+    outputResult({ success: true, sessionId, status: "completed" }, jsonMode);
+    if (!jsonMode) {
+        console.log(`Session ${sessionId} answered successfully.`);
+    }
+}

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

@@ -0,0 +1,263 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+import { AUQConfigSchema } from "../../config/types.js";
+import { getConfigPaths, loadConfig } from "../../config/ConfigLoader.js";
+import { outputResult, parseFlags } from "../utils.js";
+/**
+ * Get all valid config key paths, including dot-notated nested keys.
+ * E.g. ["maxOptions", "notifications.enabled", "notifications.sound", ...]
+ */
+function getValidConfigKeys() {
+    const shape = AUQConfigSchema.shape;
+    const keys = [];
+    for (const key of Object.keys(shape)) {
+        const fieldSchema = shape[key];
+        // Check if this is a nested object schema (z.object wrapped in z.ZodDefault)
+        const inner = getInnerSchema(fieldSchema);
+        if (inner && "shape" in inner && typeof inner.shape === "object") {
+            // It's a nested object — add dot-notated keys
+            for (const subKey of Object.keys(inner.shape)) {
+                keys.push(`${key}.${subKey}`);
+            }
+        }
+        else {
+            keys.push(key);
+        }
+    }
+    return keys;
+}
+/**
+ * Unwrap a Zod schema from wrappers like ZodDefault, ZodOptional, etc.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getInnerSchema(schema) {
+    if (!schema)
+        return schema;
+    // ZodDefault wraps an inner schema in _def.innerType
+    if (schema._def?.innerType) {
+        return getInnerSchema(schema._def.innerType);
+    }
+    return schema;
+}
+/**
+ * Get a value from a config object by dot-notated key.
+ */
+function getNestedValue(obj, key) {
+    const parts = key.split(".");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Set a value in a config object by dot-notated key.
+ */
+function setNestedValue(obj, key, value) {
+    const parts = key.split(".");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (current[part] === undefined ||
+            current[part] === null ||
+            typeof current[part] !== "object") {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+/**
+ * Coerce a string value to the correct type based on the key's schema.
+ * Handles numbers, booleans, and enum strings.
+ */
+function coerceValue(key, rawValue) {
+    const parts = key.split(".");
+    const shape = AUQConfigSchema.shape;
+    // Get the Zod schema for this key
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let fieldSchema = shape[parts[0]];
+    if (!fieldSchema)
+        return rawValue;
+    // Unwrap nested path
+    if (parts.length > 1) {
+        const innerObj = getInnerSchema(fieldSchema);
+        if (innerObj?.shape) {
+            fieldSchema = innerObj.shape[parts[1]];
+        }
+    }
+    const inner = getInnerSchema(fieldSchema);
+    if (!inner)
+        return rawValue;
+    // Detect type using Zod schema type property (works with Zod v4+)
+    const schemaType = inner._def?.type || inner.type || "";
+    // Boolean
+    if (schemaType === "boolean" || schemaType === "ZodBoolean") {
+        if (rawValue === "true")
+            return true;
+        if (rawValue === "false")
+            return false;
+        return rawValue; // let Zod validation catch invalid values
+    }
+    // Number
+    if (schemaType === "number" || schemaType === "ZodNumber") {
+        const num = Number(rawValue);
+        if (!Number.isNaN(num))
+            return num;
+        return rawValue; // let Zod validation catch it
+    }
+    // Enum or string — keep as string
+    return rawValue;
+}
+/**
+ * Build a partial config object from a single key=value pair,
+ * suitable for Zod partial validation.
+ */
+function buildPartialConfig(key, value) {
+    const obj = {};
+    setNestedValue(obj, key, value);
+    return obj;
+}
+/**
+ * Read an existing config file or return empty object.
+ */
+function readConfigFileForWrite(filePath) {
+    try {
+        if (existsSync(filePath)) {
+            const content = readFileSync(filePath, "utf-8");
+            return JSON.parse(content);
+        }
+    }
+    catch {
+        // File doesn't exist or invalid — start fresh
+    }
+    return {};
+}
+// ── Config Get ──────────────────────────────────────────────────────
+async function configGet(args) {
+    const { flags, positionals } = parseFlags(args);
+    const jsonMode = flags.json === true;
+    const key = positionals[0];
+    const config = loadConfig();
+    if (key) {
+        // Validate that key is known
+        const validKeys = getValidConfigKeys();
+        if (!validKeys.includes(key)) {
+            outputResult({
+                success: false,
+                error: `Unknown config key: "${key}". Valid keys: ${validKeys.join(", ")}`,
+            }, jsonMode);
+            process.exitCode = 1;
+            return;
+        }
+        const value = getNestedValue(config, key);
+        if (jsonMode) {
+            console.log(JSON.stringify({ success: true, key, value }, null, 2));
+        }
+        else {
+            console.log(`${key} = ${typeof value === "object" ? JSON.stringify(value) : String(value)}`);
+        }
+        return;
+    }
+    // Show all config values
+    if (jsonMode) {
+        console.log(JSON.stringify({ success: true, config }, null, 2));
+    }
+    else {
+        const validKeys = getValidConfigKeys();
+        for (const k of validKeys) {
+            const value = getNestedValue(config, k);
+            console.log(`${k} = ${typeof value === "object" ? JSON.stringify(value) : String(value)}`);
+        }
+    }
+}
+// ── Config Set ──────────────────────────────────────────────────────
+async function configSet(args) {
+    const { flags, positionals } = parseFlags(args);
+    const jsonMode = flags.json === true;
+    const isGlobal = flags.global === true;
+    const key = positionals[0];
+    const rawValue = positionals[1];
+    if (!key || rawValue === undefined) {
+        outputResult({
+            success: false,
+            error: "Usage: auq config set <key> <value> [--global] [--json]",
+        }, jsonMode);
+        process.exitCode = 1;
+        return;
+    }
+    // Validate key
+    const validKeys = getValidConfigKeys();
+    if (!validKeys.includes(key)) {
+        outputResult({
+            success: false,
+            error: `Unknown config key: "${key}". Valid keys: ${validKeys.join(", ")}`,
+        }, jsonMode);
+        process.exitCode = 1;
+        return;
+    }
+    // Coerce value to correct type
+    const coerced = coerceValue(key, rawValue);
+    // Validate with Zod
+    const partial = buildPartialConfig(key, coerced);
+    const partialSchema = AUQConfigSchema.partial();
+    const validation = partialSchema.safeParse(partial);
+    if (!validation.success) {
+        const issues = validation.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ");
+        outputResult({
+            success: false,
+            error: `Invalid value for "${key}": ${issues}`,
+        }, jsonMode);
+        process.exitCode = 1;
+        return;
+    }
+    // Determine target file
+    const paths = getConfigPaths();
+    const targetFile = isGlobal ? paths.global : paths.local;
+    // Ensure directory exists
+    const targetDir = dirname(targetFile);
+    if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true });
+    }
+    // Read existing config, merge, and write
+    const existing = readConfigFileForWrite(targetFile);
+    setNestedValue(existing, key, coerced);
+    writeFileSync(targetFile, JSON.stringify(existing, null, 2) + "\n");
+    outputResult({
+        success: true,
+        key,
+        value: coerced,
+        file: targetFile,
+    }, jsonMode);
+}
+// ── Config Command Dispatcher ───────────────────────────────────────
+export async function runConfigCommand(args) {
+    const subcommand = args[0];
+    switch (subcommand) {
+        case "get":
+            return configGet(args.slice(1));
+        case "set":
+            return configSet(args.slice(1));
+        default:
+            console.log(`Usage: auq config <subcommand>`, "\n");
+            console.log("Subcommands:");
+            console.log("  get [key] [--json]          Show config values");
+            console.log("  set <key> <value> [--global] [--json]  Set a config value");
+            console.log("");
+            console.log("Examples:");
+            console.log("  auq config get");
+            console.log("  auq config get staleThreshold --json");
+            console.log("  auq config set staleThreshold 3600000");
+            console.log("  auq config set notifyOnStale false --global");
+            if (subcommand !== undefined) {
+                process.exitCode = 1;
+            }
+            break;
+    }
+}