auq-mcp-server 2.4.0 → 2.6.0

package/dist/src/update/__tests__/index.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import * as updateModule from "../index.js";
+describe("update module exports", () => {
+    it("exports UpdateChecker class", () => {
+        expect(typeof updateModule.UpdateChecker).toBe("function");
+    });
+    it("exports fetchChangelog function", () => {
+        expect(typeof updateModule.fetchChangelog).toBe("function");
+    });
+    it("exports cache functions", () => {
+        expect(typeof updateModule.readCache).toBe("function");
+        expect(typeof updateModule.writeCache).toBe("function");
+        expect(typeof updateModule.clearUpdateCache).toBe("function");
+        expect(typeof updateModule.isCacheFresh).toBe("function");
+        expect(typeof updateModule.shouldSkipVersion).toBe("function");
+        expect(typeof updateModule.getCachePath).toBe("function");
+    });
+    it("exports CACHE_TTL as 3600000", () => {
+        expect(updateModule.CACHE_TTL).toBe(3600000);
+    });
+    it("exports installer functions", () => {
+        expect(typeof updateModule.installUpdate).toBe("function");
+        expect(typeof updateModule.getManualCommand).toBe("function");
+    });
+    it("exports package manager functions", () => {
+        expect(typeof updateModule.detectPackageManager).toBe("function");
+    });
+    it("exports PACKAGE_NAME as auq-mcp-server", () => {
+        expect(updateModule.PACKAGE_NAME).toBe("auq-mcp-server");
+    });
+    it("exports version utilities", () => {
+        expect(typeof updateModule.parseVersion).toBe("function");
+        expect(typeof updateModule.isNewer).toBe("function");
+        expect(typeof updateModule.getUpdateType).toBe("function");
+        expect(typeof updateModule.getCurrentVersion).toBe("function");
+    });
+});

package/dist/src/update/__tests__/installer.test.js

@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { EventEmitter } from "node:events";
+// Mock node:child_process
+vi.mock("node:child_process", () => ({
+    spawn: vi.fn(),
+}));
+import { spawn } from "node:child_process";
+import { installUpdate, getManualCommand } from "../installer.js";
+describe("installer", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe("installUpdate", () => {
+        function createMockChild() {
+            const child = new EventEmitter();
+            return child;
+        }
+        it("should return true when exit code is 0", async () => {
+            const child = createMockChild();
+            vi.mocked(spawn).mockReturnValue(child);
+            const promise = installUpdate({
+                name: "npm",
+                installCommand: "npm install -g",
+            });
+            child.emit("close", 0);
+            const result = await promise;
+            expect(result).toBe(true);
+        });
+        it("should return false when exit code is 1", async () => {
+            const child = createMockChild();
+            vi.mocked(spawn).mockReturnValue(child);
+            const promise = installUpdate({
+                name: "npm",
+                installCommand: "npm install -g",
+            });
+            child.emit("close", 1);
+            const result = await promise;
+            expect(result).toBe(false);
+        });
+        it("should return false on spawn error", async () => {
+            const child = createMockChild();
+            vi.mocked(spawn).mockReturnValue(child);
+            const promise = installUpdate({
+                name: "npm",
+                installCommand: "npm install -g",
+            });
+            child.emit("error", new Error("ENOENT"));
+            const result = await promise;
+            expect(result).toBe(false);
+        });
+        it("should use correct args for npm", async () => {
+            const child = createMockChild();
+            vi.mocked(spawn).mockReturnValue(child);
+            const pm = {
+                name: "npm",
+                installCommand: "npm install -g",
+            };
+            const promise = installUpdate(pm);
+            child.emit("close", 0);
+            await promise;
+            expect(spawn).toHaveBeenCalledWith("npm", ["install", "-g", "auq-mcp-server"], expect.objectContaining({ stdio: ["ignore", "pipe", "pipe"] }));
+        });
+        it("should use correct args for bun", async () => {
+            const child = createMockChild();
+            vi.mocked(spawn).mockReturnValue(child);
+            const pm = {
+                name: "bun",
+                installCommand: "bun add -g",
+            };
+            const promise = installUpdate(pm);
+            child.emit("close", 0);
+            await promise;
+            expect(spawn).toHaveBeenCalledWith("bun", ["add", "-g", "auq-mcp-server"], expect.objectContaining({ stdio: ["ignore", "pipe", "pipe"] }));
+        });
+        it("should use correct args for yarn", async () => {
+            const child = createMockChild();
+            vi.mocked(spawn).mockReturnValue(child);
+            const pm = {
+                name: "yarn",
+                installCommand: "yarn global add",
+            };
+            const promise = installUpdate(pm);
+            child.emit("close", 0);
+            await promise;
+            expect(spawn).toHaveBeenCalledWith("yarn", ["global", "add", "auq-mcp-server"], expect.objectContaining({ stdio: ["ignore", "pipe", "pipe"] }));
+        });
+        it("should use correct args for pnpm", async () => {
+            const child = createMockChild();
+            vi.mocked(spawn).mockReturnValue(child);
+            const pm = {
+                name: "pnpm",
+                installCommand: "pnpm add -g",
+            };
+            const promise = installUpdate(pm);
+            child.emit("close", 0);
+            await promise;
+            expect(spawn).toHaveBeenCalledWith("pnpm", ["add", "-g", "auq-mcp-server"], expect.objectContaining({ stdio: ["ignore", "pipe", "pipe"] }));
+        });
+    });
+    describe("getManualCommand", () => {
+        it("should return correct command for npm", () => {
+            expect(getManualCommand({ name: "npm", installCommand: "npm install -g" })).toBe("npm install -g auq-mcp-server");
+        });
+        it("should return correct command for bun", () => {
+            expect(getManualCommand({ name: "bun", installCommand: "bun add -g" })).toBe("bun add -g auq-mcp-server");
+        });
+        it("should return correct command for yarn", () => {
+            expect(getManualCommand({ name: "yarn", installCommand: "yarn global add" })).toBe("yarn global add auq-mcp-server");
+        });
+        it("should return correct command for pnpm", () => {
+            expect(getManualCommand({ name: "pnpm", installCommand: "pnpm add -g" })).toBe("pnpm add -g auq-mcp-server");
+        });
+    });
+});

package/dist/src/update/__tests__/package-manager.test.js

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { detectPackageManager, PACKAGE_NAME } from "../package-manager.js";
+describe("package manager detection", () => {
+    const originalEnv = { ...process.env };
+    const originalExecPath = process.execPath;
+    beforeEach(() => {
+        // Clear relevant env vars so each test starts clean
+        delete process.env.npm_config_user_agent;
+        delete process.env.npm_execpath;
+    });
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        Object.defineProperty(process, "execPath", { value: originalExecPath });
+    });
+    describe("PACKAGE_NAME", () => {
+        it("should equal auq-mcp-server", () => {
+            expect(PACKAGE_NAME).toBe("auq-mcp-server");
+        });
+    });
+    describe("detectPackageManager", () => {
+        it("should detect bun from npm_config_user_agent", () => {
+            process.env.npm_config_user_agent = "bun/1.0.0 linux x64";
+            const result = detectPackageManager();
+            expect(result.name).toBe("bun");
+            expect(result.installCommand).toBe("bun add -g");
+        });
+        it("should detect yarn from npm_config_user_agent", () => {
+            process.env.npm_config_user_agent = "yarn/4.0.0 node/v20.0.0";
+            const result = detectPackageManager();
+            expect(result.name).toBe("yarn");
+            expect(result.installCommand).toBe("yarn global add");
+        });
+        it("should detect pnpm from npm_config_user_agent", () => {
+            process.env.npm_config_user_agent = "pnpm/8.0.0 node/v20.0.0";
+            const result = detectPackageManager();
+            expect(result.name).toBe("pnpm");
+            expect(result.installCommand).toBe("pnpm add -g");
+        });
+        it("should detect npm from npm_config_user_agent", () => {
+            process.env.npm_config_user_agent = "npm/10.2.0 node/v20.9.0 darwin arm64";
+            const result = detectPackageManager();
+            expect(result.name).toBe("npm");
+            expect(result.installCommand).toBe("npm install -g");
+        });
+        it("should fallback to npm_execpath when user_agent is empty", () => {
+            process.env.npm_config_user_agent = "";
+            process.env.npm_execpath = "/usr/local/lib/yarn/bin/yarn.js";
+            const result = detectPackageManager();
+            expect(result.name).toBe("yarn");
+        });
+        it("should fallback to process.execPath for bun detection", () => {
+            process.env.npm_config_user_agent = "";
+            process.env.npm_execpath = "";
+            Object.defineProperty(process, "execPath", {
+                value: "/home/user/.bun/bin/bun",
+                configurable: true,
+            });
+            const result = detectPackageManager();
+            expect(result.name).toBe("bun");
+        });
+        it("should default to npm when no indicators found", () => {
+            process.env.npm_config_user_agent = "";
+            process.env.npm_execpath = "";
+            Object.defineProperty(process, "execPath", {
+                value: "/usr/local/bin/node",
+                configurable: true,
+            });
+            const result = detectPackageManager();
+            expect(result.name).toBe("npm");
+            expect(result.installCommand).toBe("npm install -g");
+        });
+    });
+});

package/dist/src/update/__tests__/version.test.js

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { parseVersion, isNewer, getUpdateType } from "../version.js";
+describe("version utilities", () => {
+    describe("parseVersion", () => {
+        it("should parse a standard semver string", () => {
+            const result = parseVersion("2.5.0");
+            expect(result).toEqual({ major: 2, minor: 5, patch: 0 });
+        });
+        it("should strip a leading 'v' prefix", () => {
+            const result = parseVersion("v1.2.3");
+            expect(result).toEqual({ major: 1, minor: 2, patch: 3 });
+        });
+        it("should treat two-part versions as patch 0", () => {
+            const result = parseVersion("2.5");
+            expect(result).toEqual({ major: 2, minor: 5, patch: 0 });
+        });
+        it("should capture prerelease identifiers", () => {
+            const result = parseVersion("1.0.0-beta.1");
+            expect(result).toEqual({
+                major: 1,
+                minor: 0,
+                patch: 0,
+                prerelease: "beta.1",
+            });
+        });
+        it("should throw on completely invalid input 'abc'", () => {
+            expect(() => parseVersion("abc")).toThrow("Invalid version string");
+        });
+        it("should parse empty string as 0.0.0 (all parts default to 0)", () => {
+            const result = parseVersion("");
+            expect(result).toEqual({ major: 0, minor: 0, patch: 0 });
+        });
+        it("should throw on version with non-numeric parts", () => {
+            expect(() => parseVersion("1.x.3")).toThrow("Invalid version string");
+        });
+    });
+    describe("isNewer", () => {
+        it("should detect a newer patch version", () => {
+            expect(isNewer("2.4.0", "2.4.1")).toBe(true);
+        });
+        it("should detect a newer minor version", () => {
+            expect(isNewer("2.4.0", "2.5.0")).toBe(true);
+        });
+        it("should detect a newer major version", () => {
+            expect(isNewer("2.4.0", "3.0.0")).toBe(true);
+        });
+        it("should return false when versions are the same", () => {
+            expect(isNewer("2.4.0", "2.4.0")).toBe(false);
+        });
+        it("should return false when latest is older", () => {
+            expect(isNewer("2.5.0", "2.4.0")).toBe(false);
+        });
+        it("should treat prerelease as older than same release version", () => {
+            expect(isNewer("2.5.0-beta.1", "2.5.0")).toBe(true);
+        });
+        it("should treat release as newer than same prerelease version", () => {
+            expect(isNewer("2.5.0", "2.5.0-beta.1")).toBe(false);
+        });
+    });
+    describe("getUpdateType", () => {
+        it("should return 'patch' for patch-level update", () => {
+            expect(getUpdateType("2.4.0", "2.4.1")).toBe("patch");
+        });
+        it("should return 'minor' for minor-level update", () => {
+            expect(getUpdateType("2.4.0", "2.5.0")).toBe("minor");
+        });
+        it("should return 'major' for major-level update", () => {
+            expect(getUpdateType("2.4.0", "3.0.0")).toBe("major");
+        });
+        it("should return 'major' when major differs even with other changes", () => {
+            expect(getUpdateType("1.0.0", "2.1.3")).toBe("major");
+        });
+    });
+});

package/dist/src/update/cache.js

@@ -0,0 +1,74 @@
+/**
+ * Cache management for update check results.
+ *
+ * Stores update check data in ~/.config/auq/update-check.json (XDG-compliant).
+ * Provides cache freshness checking and skip-version tracking.
+ */
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Cache time-to-live: 1 hour in milliseconds */
+export const CACHE_TTL = 3600000;
+/**
+ * Resolve the cache file path using XDG-compliant directory.
+ * Respects $XDG_CONFIG_HOME if set, otherwise uses ~/.config.
+ */
+export function getCachePath() {
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(xdgConfigHome, "auq", "update-check.json");
+}
+/**
+ * Read and parse the cached update check data.
+ * Returns null if the cache file is missing, unreadable, or contains invalid JSON.
+ */
+export async function readCache() {
+    try {
+        const cachePath = getCachePath();
+        const content = await readFile(cachePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write update check data to the cache file.
+ * Creates the parent directory if it doesn't exist.
+ * Silently handles write errors.
+ */
+export async function writeCache(cache) {
+    try {
+        const cachePath = getCachePath();
+        await mkdir(dirname(cachePath), { recursive: true });
+        await writeFile(cachePath, JSON.stringify(cache, null, 2), "utf-8");
+    }
+    catch {
+        // Silently handle write errors
+    }
+}
+/**
+ * Check if the cache is still fresh (within the TTL window).
+ * Returns true if lastCheck is within the last hour.
+ */
+export function isCacheFresh(cache) {
+    return Date.now() - cache.lastCheck < CACHE_TTL;
+}
+/**
+ * Check if the user has chosen to skip the given version.
+ */
+export function shouldSkipVersion(cache, version) {
+    return cache.skippedVersion === version;
+}
+/**
+ * Delete the cache file to force a fresh update check.
+ * Silently handles errors if the file doesn't exist or can't be deleted.
+ */
+export async function clearUpdateCache() {
+    try {
+        const cachePath = getCachePath();
+        await unlink(cachePath);
+    }
+    catch {
+        // Silently handle deletion errors
+    }
+}

package/dist/src/update/changelog.js

@@ -0,0 +1,63 @@
+/**
+ * GitHub Releases API changelog fetcher.
+ *
+ * Fetches release notes for a given version from the GitHub Releases API.
+ * Handles rate limiting (403/429) gracefully and caches results to reduce API calls.
+ * Always returns a fallback URL even when content is unavailable.
+ */
+import { readCache, writeCache } from "./cache.js";
+const GITHUB_API_URL = "https://api.github.com/repos/AlpacaLOS/auq/releases/tags";
+/**
+ * Fetch changelog content from GitHub Releases API for a specific version.
+ *
+ * Uses cached changelog if available for the requested version.
+ * Gracefully handles rate limits (HTTP 403/429) by returning null content
+ * with a fallback URL to the GitHub release page.
+ *
+ * @param version - The version to fetch changelog for (e.g., "2.5.0")
+ * @returns Changelog content and fallback URL
+ */
+export async function fetchChangelog(version) {
+    const fallbackUrl = `https://github.com/AlpacaLOS/auq/releases/tag/v${version}`;
+    try {
+        // Check cache first to avoid unnecessary API calls
+        const cache = await readCache();
+        if (cache?.changelog &&
+            cache?.changelogFetchedAt &&
+            cache.latestVersion === version) {
+            return { content: cache.changelog, fallbackUrl };
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const response = await fetch(`${GITHUB_API_URL}/v${version}`, {
+            headers: {
+                Accept: "application/vnd.github.v3+json",
+                "User-Agent": "auq-mcp-server",
+            },
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        // Handle rate limiting — return fallback without content
+        if (response.status === 403 || response.status === 429) {
+            return { content: null, fallbackUrl };
+        }
+        if (!response.ok) {
+            return { content: null, fallbackUrl };
+        }
+        const release = (await response.json());
+        const content = release.body || null;
+        // Cache the changelog alongside existing cache data
+        if (content && cache) {
+            await writeCache({
+                ...cache,
+                changelog: content,
+                changelogFetchedAt: Date.now(),
+            }).catch(() => { });
+        }
+        return { content, fallbackUrl };
+    }
+    catch {
+        // Network errors, timeouts, parse errors — return fallback
+        return { content: null, fallbackUrl };
+    }
+}

package/dist/src/update/checker.js

@@ -0,0 +1,121 @@
+/**
+ * Core update checker orchestrator.
+ *
+ * Uses a memoized promise pattern to deduplicate concurrent update checks.
+ * Reads cached data first, falls back to npm registry fetch with a 5-second
+ * timeout. Silently returns null on any error — update checks must never
+ * break the application.
+ */
+import { isNewer, getUpdateType, getCurrentVersion } from "./version.js";
+import { readCache, writeCache, isCacheFresh, shouldSkipVersion, clearUpdateCache, } from "./cache.js";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/auq-mcp-server";
+const GITHUB_RELEASES_URL = "https://github.com/AlpacaLOS/auq/releases/tag";
+export class UpdateChecker {
+    checkPromise = null;
+    currentVersion;
+    constructor(currentVersion) {
+        this.currentVersion = currentVersion || getCurrentVersion();
+    }
+    /**
+     * Check for available updates.
+     *
+     * Uses a memoized promise to prevent duplicate concurrent requests.
+     * Returns null if the check should be skipped (CI, env vars, etc.),
+     * if no update is available, or if any error occurs.
+     */
+    async check() {
+        if (this.shouldSkipCheck())
+            return null;
+        if (this.checkPromise)
+            return this.checkPromise;
+        this.checkPromise = this.performCheck();
+        return this.checkPromise;
+    }
+    /**
+     * Determine if the update check should be skipped entirely.
+     *
+     * Skips in CI environments, when NO_UPDATE_NOTIFIER is set,
+     * or when NODE_ENV is "test".
+     */
+    shouldSkipCheck() {
+        // CI environments
+        if (process.env.CI === "true" || process.env.CI === "1")
+            return true;
+        // Explicit opt-out via NO_UPDATE_NOTIFIER
+        if (process.env.NO_UPDATE_NOTIFIER === "1" ||
+            process.env.NO_UPDATE_NOTIFIER === "true")
+            return true;
+        // Test environment
+        if (process.env.NODE_ENV === "test")
+            return true;
+        return false;
+    }
+    /**
+     * Perform the actual update check.
+     *
+     * 1. Read cache — if fresh, use cached version info.
+     * 2. Fetch npm registry with 5s timeout for latest dist-tag.
+     * 3. Write updated cache (preserving skippedVersion and changelog).
+     * 4. Compare versions and return UpdateInfo or null.
+     */
+    async performCheck() {
+        try {
+            // 1. Check cache first
+            const cache = await readCache();
+            if (cache && isCacheFresh(cache)) {
+                if (!isNewer(this.currentVersion, cache.latestVersion))
+                    return null;
+                if (shouldSkipVersion(cache, cache.latestVersion))
+                    return null;
+                return {
+                    currentVersion: this.currentVersion,
+                    latestVersion: cache.latestVersion,
+                    updateType: getUpdateType(this.currentVersion, cache.latestVersion),
+                    changelogUrl: `${GITHUB_RELEASES_URL}/v${cache.latestVersion}`,
+                };
+            }
+            // 2. Fetch from npm registry
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            const response = await fetch(NPM_REGISTRY_URL, {
+                headers: { Accept: "application/vnd.npm.install-v1+json" },
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (!response.ok)
+                return null;
+            const data = (await response.json());
+            const latestVersion = data["dist-tags"]?.latest;
+            if (!latestVersion)
+                return null;
+            // 3. Write cache (preserve skippedVersion and changelog from old cache)
+            const newCache = {
+                lastCheck: Date.now(),
+                latestVersion,
+                skippedVersion: cache?.skippedVersion,
+                changelog: cache?.changelog,
+                changelogFetchedAt: cache?.changelogFetchedAt,
+            };
+            await writeCache(newCache).catch(() => { });
+            // 4. Compare versions
+            if (!isNewer(this.currentVersion, latestVersion))
+                return null;
+            if (cache && shouldSkipVersion(cache, latestVersion))
+                return null;
+            return {
+                currentVersion: this.currentVersion,
+                latestVersion,
+                updateType: getUpdateType(this.currentVersion, latestVersion),
+                changelogUrl: `${GITHUB_RELEASES_URL}/v${latestVersion}`,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Reset the memoized promise and clear the on-disk cache. */
+    clearCache() {
+        this.checkPromise = null;
+        clearUpdateCache().catch(() => { });
+    }
+}

package/dist/src/update/index.js

@@ -0,0 +1,15 @@
+/**
+ * Auto-update module for AUQ.
+ *
+ * Provides update checking against the npm registry, version comparison,
+ * XDG-compliant cache management, package manager detection, changelog
+ * fetching from GitHub Releases, and update installation.
+ *
+ * @module update
+ */
+export { UpdateChecker } from "./checker.js";
+export { fetchChangelog } from "./changelog.js";
+export { readCache, writeCache, clearUpdateCache, isCacheFresh, shouldSkipVersion, getCachePath, CACHE_TTL, } from "./cache.js";
+export { installUpdate, getManualCommand } from "./installer.js";
+export { detectPackageManager, PACKAGE_NAME } from "./package-manager.js";
+export { parseVersion, isNewer, getUpdateType, getCurrentVersion, } from "./version.js";

package/dist/src/update/installer.js

@@ -0,0 +1,51 @@
+/**
+ * Update installation executor.
+ *
+ * Spawns the detected package manager to install the latest version.
+ * Uses node:child_process for portability across Bun and Node.js runtimes.
+ */
+import { spawn } from "node:child_process";
+const PACKAGE_NAME = "auq-mcp-server";
+/**
+ * Install the latest version of the package using the detected package manager.
+ *
+ * Spawns the package manager's global install command as a child process.
+ * Returns true on success (exit code 0), false on any failure.
+ * Never rejects — all errors are caught and resolved as false.
+ *
+ * @param packageManager - Detected package manager info with install command
+ * @returns Whether the installation succeeded
+ */
+export async function installUpdate(packageManager) {
+    return new Promise((resolve) => {
+        try {
+            const [command, ...baseArgs] = packageManager.installCommand.split(" ");
+            const args = [...baseArgs, PACKAGE_NAME];
+            const child = spawn(command, args, {
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: process.platform === "win32",
+            });
+            child.on("error", () => {
+                resolve(false);
+            });
+            child.on("close", (code) => {
+                resolve(code === 0);
+            });
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/**
+ * Get the manual install command string for display to the user.
+ *
+ * Used as a fallback when automatic installation fails, allowing
+ * the user to copy and run the command manually.
+ *
+ * @param packageManager - Detected package manager info
+ * @returns Full install command string (e.g., "npm install -g auq-mcp-server")
+ */
+export function getManualCommand(packageManager) {
+    return `${packageManager.installCommand} ${PACKAGE_NAME}`;
+}