kanban-ai 0.22.0 → 0.22.2

package/dist/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CACHE_SUBDIR_BINARY = exports.CACHE_DIR_NAME = exports.KANBANAI_ASSUME_NO_ENV = exports.KANBANAI_ASSUME_YES_ENV = exports.KANBANAI_NO_UPDATE_CHECK_ENV = exports.KANBANAI_GITHUB_REPO_ENV = exports.KANBANAI_BINARY_VERSION_ENV = exports.KANBANAI_HOME_ENV = exports.DEFAULT_GITHUB_REPO = void 0;
+exports.CACHE_SUBDIR = exports.CONFIG_SUBDIR = exports.CACHE_SUBDIR_BINARY = exports.CACHE_DIR_NAME = exports.XDG_CACHE_HOME_ENV = exports.XDG_CONFIG_HOME_ENV = exports.KANBANAI_ASSUME_NO_ENV = exports.KANBANAI_ASSUME_YES_ENV = exports.KANBANAI_NO_UPDATE_CHECK_ENV = exports.KANBANAI_GITHUB_REPO_ENV = exports.KANBANAI_BINARY_VERSION_ENV = exports.KANBANAI_HOME_ENV = exports.DEFAULT_GITHUB_REPO = void 0;
 exports.DEFAULT_GITHUB_REPO = 'activadee/kanban-ai';
 exports.KANBANAI_HOME_ENV = 'KANBANAI_HOME';
 exports.KANBANAI_BINARY_VERSION_ENV = 'KANBANAI_BINARY_VERSION';
@@ -8,5 +8,12 @@ exports.KANBANAI_GITHUB_REPO_ENV = 'KANBANAI_GITHUB_REPO';
 exports.KANBANAI_NO_UPDATE_CHECK_ENV = 'KANBANAI_NO_UPDATE_CHECK';
 exports.KANBANAI_ASSUME_YES_ENV = 'KANBANAI_ASSUME_YES';
 exports.KANBANAI_ASSUME_NO_ENV = 'KANBANAI_ASSUME_NO';
+// XDG Base Directory Specification environment variables
+exports.XDG_CONFIG_HOME_ENV = 'XDG_CONFIG_HOME';
+exports.XDG_CACHE_HOME_ENV = 'XDG_CACHE_HOME';
+// Legacy directory name for backward compatibility
 exports.CACHE_DIR_NAME = '.kanbanAI';
 exports.CACHE_SUBDIR_BINARY = 'binary';
+// New XDG-compliant subdirectory names
+exports.CONFIG_SUBDIR = 'kanban-ai';
+exports.CACHE_SUBDIR = 'kanban-ai';

package/dist/constants.test.js

@@ -13,5 +13,9 @@ const constants_1 = require("./constants");
         (0, vitest_1.expect)(constants_1.KANBANAI_ASSUME_NO_ENV).toBe('KANBANAI_ASSUME_NO');
         (0, vitest_1.expect)(constants_1.CACHE_DIR_NAME).toBe('.kanbanAI');
         (0, vitest_1.expect)(constants_1.CACHE_SUBDIR_BINARY).toBe('binary');
+        (0, vitest_1.expect)(constants_1.XDG_CONFIG_HOME_ENV).toBe('XDG_CONFIG_HOME');
+        (0, vitest_1.expect)(constants_1.XDG_CACHE_HOME_ENV).toBe('XDG_CACHE_HOME');
+        (0, vitest_1.expect)(constants_1.CONFIG_SUBDIR).toBe('kanban-ai');
+        (0, vitest_1.expect)(constants_1.CACHE_SUBDIR).toBe('kanban-ai');
     });
 });

package/dist/env.js

@@ -7,10 +7,14 @@ exports.resolveEnvOptions = resolveEnvOptions;
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const constants_1 = require("./constants");
+const paths_1 = require("./paths");
 function resolveEnvOptions() {
+    // Determine home directory - prefer KANBANAI_HOME for legacy compatibility
     const homeEnv = process.env[constants_1.KANBANAI_HOME_ENV] || process.env.HOME || process.env.USERPROFILE;
     const home = homeEnv || node_os_1.default.homedir();
-    const baseCacheDir = node_path_1.default.join(home, constants_1.CACHE_DIR_NAME, constants_1.CACHE_SUBDIR_BINARY);
+    // Resolve XDG-compliant paths
+    const configDir = (0, paths_1.getConfigDir)(home);
+    const baseCacheDir = node_path_1.default.join((0, paths_1.getCacheDir)(home), constants_1.CACHE_SUBDIR_BINARY);
     const githubRepo = process.env[constants_1.KANBANAI_GITHUB_REPO_ENV] || constants_1.DEFAULT_GITHUB_REPO;
     const binaryVersionOverride = process.env[constants_1.KANBANAI_BINARY_VERSION_ENV] || undefined;
     const noUpdateCheck = toBoolEnv(process.env[constants_1.KANBANAI_NO_UPDATE_CHECK_ENV]);
@@ -19,6 +23,7 @@ function resolveEnvOptions() {
     return {
         githubRepo,
         baseCacheDir,
+        configDir,
         binaryVersionOverride,
         noUpdateCheck,
         assumeYes,

package/dist/env.test.js

@@ -20,9 +20,12 @@ const originalEnv = { ...process.env };
         delete process.env.KANBANAI_NO_UPDATE_CHECK;
         delete process.env.KANBANAI_ASSUME_YES;
         delete process.env.KANBANAI_ASSUME_NO;
+        delete process.env.XDG_CONFIG_HOME;
+        delete process.env.XDG_CACHE_HOME;
         const env = (0, env_1.resolveEnvOptions)();
         (0, vitest_1.expect)(env.githubRepo).toBe('activadee/kanban-ai');
-        (0, vitest_1.expect)(env.baseCacheDir.endsWith(node_path_1.default.join('.kanbanAI', 'binary'))).toBe(true);
+        (0, vitest_1.expect)(env.baseCacheDir.endsWith(node_path_1.default.join('.cache', 'kanban-ai', 'binary'))).toBe(true);
+        (0, vitest_1.expect)(env.configDir.endsWith(node_path_1.default.join('.config', 'kanban-ai'))).toBe(true);
         (0, vitest_1.expect)(env.binaryVersionOverride).toBeUndefined();
         (0, vitest_1.expect)(env.noUpdateCheck).toBe(false);
         (0, vitest_1.expect)(env.assumeYes).toBe(false);
@@ -35,12 +38,31 @@ const originalEnv = { ...process.env };
         process.env.KANBANAI_NO_UPDATE_CHECK = 'true';
         process.env.KANBANAI_ASSUME_YES = '1';
         process.env.KANBANAI_ASSUME_NO = 'yes';
+        process.env.XDG_CONFIG_HOME = '/custom/config';
+        process.env.XDG_CACHE_HOME = '/custom/cache';
         const env = (0, env_1.resolveEnvOptions)();
         (0, vitest_1.expect)(env.githubRepo).toBe('someone/else');
-        (0, vitest_1.expect)(env.baseCacheDir).toBe(node_path_1.default.join('/tmp/kanbanai-home', '.kanbanAI', 'binary'));
+        (0, vitest_1.expect)(env.baseCacheDir).toBe('/custom/cache/kanban-ai/binary');
+        (0, vitest_1.expect)(env.configDir).toBe('/custom/config/kanban-ai');
         (0, vitest_1.expect)(env.binaryVersionOverride).toBe('1.2.3');
         (0, vitest_1.expect)(env.noUpdateCheck).toBe(true);
         (0, vitest_1.expect)(env.assumeYes).toBe(true);
         (0, vitest_1.expect)(env.assumeNo).toBe(true);
     });
+    (0, vitest_1.it)('uses KANBANAI_HOME for home directory when set', () => {
+        process.env.KANBANAI_HOME = '/custom/home';
+        delete process.env.XDG_CONFIG_HOME;
+        delete process.env.XDG_CACHE_HOME;
+        const env = (0, env_1.resolveEnvOptions)();
+        (0, vitest_1.expect)(env.baseCacheDir).toBe('/custom/home/.cache/kanban-ai/binary');
+        (0, vitest_1.expect)(env.configDir).toBe('/custom/home/.config/kanban-ai');
+    });
+    (0, vitest_1.it)('respects XDG environment variables', () => {
+        delete process.env.KANBANAI_HOME;
+        process.env.XDG_CONFIG_HOME = '/xdg/config';
+        process.env.XDG_CACHE_HOME = '/xdg/cache';
+        const env = (0, env_1.resolveEnvOptions)();
+        (0, vitest_1.expect)(env.configDir).toBe('/xdg/config/kanban-ai');
+        (0, vitest_1.expect)(env.baseCacheDir).toBe('/xdg/cache/kanban-ai/binary');
+    });
 });

package/dist/index.js

@@ -40,7 +40,7 @@ async function runCli() {
     const platformArch = (0, platform_1.detectPlatformArch)();
     const binaryInfo = (0, platform_1.resolveBinaryInfo)(platformArch.platform, platformArch.arch);
     const githubApiCache = {
-        dir: node_path_1.default.join(node_path_1.default.dirname(effectiveEnv.baseCacheDir), "github-api"),
+        dir: node_path_1.default.join(effectiveEnv.configDir, "github-api"),
     };
     const explicitVersion = cliOptions.binaryVersion
         ? (0, version_1.cleanVersionTag)(cliOptions.binaryVersion)

package/dist/index.test.js

@@ -44,6 +44,7 @@ vitest_1.vi.mock("./env", () => ({
     resolveEnvOptions: () => ({
         githubRepo: "owner/repo",
         baseCacheDir: "/tmp/kanbanai",
+        configDir: "/tmp/kanbanai-config",
         binaryVersionOverride: undefined,
         noUpdateCheck: false,
         assumeYes: false,

package/dist/migration.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrationNeeded = migrationNeeded;
+exports.getMigrationItems = getMigrationItems;
+exports.migrateFromLegacy = migrateFromLegacy;
+exports.getMigrationStatus = getMigrationStatus;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+/**
+ * Check if migration is needed (legacy directory exists)
+ * @returns true if legacy directory exists and new directories don't
+ */
+function migrationNeeded() {
+    const legacyExists = node_fs_1.default.existsSync((0, paths_1.getLegacyDir)());
+    // Migration is needed if legacy exists and config doesn't
+    const configExists = node_fs_1.default.existsSync((0, paths_1.getConfigDir)());
+    return legacyExists && !configExists;
+}
+/**
+ * Get a list of files/directories that need to be migrated from legacy location
+ * @returns Object with configItems and cacheItems arrays
+ */
+function getMigrationItems() {
+    const legacyDir = (0, paths_1.getLegacyDir)();
+    const configItems = [];
+    const cacheItems = [];
+    try {
+        const entries = node_fs_1.default.readdirSync(legacyDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = node_path_1.default.join(legacyDir, entry.name);
+            // GitHub API cache should go to config
+            if (entry.name === 'github-api' && entry.isDirectory()) {
+                configItems.push(entry.name);
+            }
+            // Everything else (binary, worktrees) goes to cache
+            else {
+                cacheItems.push(entry.name);
+            }
+        }
+    }
+    catch (error) {
+        // Directory doesn't exist or can't be read
+        return { configItems: [], cacheItems: [] };
+    }
+    return { configItems, cacheItems };
+}
+/**
+ * Perform the migration from legacy .kanbanAI directory to XDG-compliant locations
+ * @param options Options for controlling migration behavior
+ * @returns MigrationResult with details about the migration
+ */
+async function migrateFromLegacy(options = {}) {
+    const { dryRun = false, force = false, onProgress } = options;
+    const result = {
+        success: false,
+        configMigrated: false,
+        cacheMigrated: false,
+        errors: [],
+    };
+    try {
+        const legacyDir = (0, paths_1.getLegacyDir)();
+        const configDir = (0, paths_1.getConfigDir)();
+        const cacheDir = (0, paths_1.getCacheDir)();
+        if (!node_fs_1.default.existsSync(legacyDir)) {
+            onProgress?.('No legacy directory found. Migration not needed.');
+            result.success = true;
+            return result;
+        }
+        if (node_fs_1.default.existsSync(configDir) && !force) {
+            onProgress?.('XDG-compliant directories already exist. Migration not needed.');
+            result.success = true;
+            return result;
+        }
+        onProgress?.(`Starting migration from ${legacyDir}`);
+        // Create directories if they don't exist
+        if (!dryRun) {
+            node_fs_1.default.mkdirSync(configDir, { recursive: true });
+            node_fs_1.default.mkdirSync(cacheDir, { recursive: true });
+        }
+        // Get items to migrate
+        const { configItems, cacheItems } = getMigrationItems();
+        if (configItems.length > 0) {
+            onProgress?.(`Migrating config items: ${configItems.join(', ')}`);
+            for (const item of configItems) {
+                const source = node_path_1.default.join(legacyDir, item);
+                const destination = node_path_1.default.join(configDir, item);
+                if (dryRun) {
+                    onProgress?.(`[DRY RUN] Would copy ${source} to ${destination}`);
+                }
+                else {
+                    onProgress?.(`Copying ${source} to ${destination}`);
+                    await copyRecursive(source, destination);
+                }
+            }
+            if (!dryRun) {
+                result.configMigrated = true;
+            }
+        }
+        if (cacheItems.length > 0) {
+            onProgress?.(`Migrating cache items: ${cacheItems.join(', ')}`);
+            for (const item of cacheItems) {
+                const source = node_path_1.default.join(legacyDir, item);
+                const destination = node_path_1.default.join(cacheDir, item);
+                if (dryRun) {
+                    onProgress?.(`[DRY RUN] Would copy ${source} to ${destination}`);
+                }
+                else {
+                    onProgress?.(`Copying ${source} to ${destination}`);
+                    await copyRecursive(source, destination);
+                }
+            }
+            if (!dryRun) {
+                result.cacheMigrated = true;
+            }
+        }
+        result.success = true;
+        onProgress?.('Migration completed successfully!');
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        result.errors.push(errorMessage);
+        onProgress?.(`Migration failed: ${errorMessage}`);
+    }
+    return result;
+}
+/**
+ * Copy a directory recursively
+ */
+async function copyRecursive(source, destination) {
+    // Check if source is a directory
+    const stats = node_fs_1.default.statSync(source);
+    if (stats.isDirectory()) {
+        // Create destination directory
+        node_fs_1.default.mkdirSync(destination, { recursive: true });
+        // Copy all contents
+        const entries = node_fs_1.default.readdirSync(source, { withFileTypes: true });
+        for (const entry of entries) {
+            const sourcePath = node_path_1.default.join(source, entry.name);
+            const destPath = node_path_1.default.join(destination, entry.name);
+            if (entry.isDirectory()) {
+                await copyRecursive(sourcePath, destPath);
+            }
+            else {
+                node_fs_1.default.copyFileSync(sourcePath, destPath);
+            }
+        }
+    }
+    else {
+        // It's a file, just copy it
+        node_fs_1.default.copyFileSync(source, destination);
+    }
+}
+/**
+ * Get the status of migration without performing it
+ * @returns Object describing current migration status
+ */
+function getMigrationStatus() {
+    const legacyDir = (0, paths_1.getLegacyDir)();
+    const configDir = (0, paths_1.getConfigDir)();
+    const cacheDir = (0, paths_1.getCacheDir)();
+    const legacyExists = node_fs_1.default.existsSync(legacyDir);
+    const configExists = node_fs_1.default.existsSync(configDir);
+    const cacheExists = node_fs_1.default.existsSync(cacheDir);
+    const needsMigration = legacyExists && (!configExists || !cacheExists);
+    let pendingItems = { configItems: [], cacheItems: [] };
+    if (needsMigration) {
+        pendingItems = getMigrationItems();
+    }
+    return {
+        legacyExists,
+        configExists,
+        cacheExists,
+        needsMigration,
+        pendingItems,
+    };
+}

package/dist/migration.test.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const migration_1 = require("./migration");
+(0, vitest_1.describe)('Migration', () => {
+    const testHome = '/tmp/kanban-ai-test';
+    const legacyDir = node_path_1.default.join(testHome, '.kanbanAI');
+    const configDir = node_path_1.default.join(testHome, '.config', 'kanban-ai');
+    const cacheDir = node_path_1.default.join(testHome, '.cache', 'kanban-ai');
+    (0, vitest_1.beforeEach)(() => {
+        // Create test directory structure
+        node_fs_1.default.mkdirSync(legacyDir, { recursive: true });
+        node_fs_1.default.mkdirSync(node_path_1.default.join(legacyDir, 'binary'), { recursive: true });
+        node_fs_1.default.mkdirSync(node_path_1.default.join(legacyDir, 'github-api'), { recursive: true });
+        node_fs_1.default.writeFileSync(node_path_1.default.join(legacyDir, 'binary', 'test'), 'test binary');
+        node_fs_1.default.writeFileSync(node_path_1.default.join(legacyDir, 'github-api', 'test'), 'test cache');
+    });
+    (0, vitest_1.afterEach)(() => {
+        // Cleanup test directories
+        node_fs_1.default.rmSync(testHome, { recursive: true, force: true });
+        vitest_1.vi.unstubAllEnvs();
+    });
+    (0, vitest_1.describe)('migrationNeeded', () => {
+        (0, vitest_1.test)('returns true when legacy exists but config does not', () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            (0, vitest_1.expect)((0, migration_1.migrationNeeded)()).toBe(true);
+        });
+        (0, vitest_1.test)('returns false when both legacy and config exist', () => {
+            node_fs_1.default.mkdirSync(configDir, { recursive: true });
+            vitest_1.vi.stubEnv('HOME', testHome);
+            (0, vitest_1.expect)((0, migration_1.migrationNeeded)()).toBe(false);
+        });
+        (0, vitest_1.test)('returns false when legacy does not exist', () => {
+            node_fs_1.default.rmSync(legacyDir, { recursive: true, force: true });
+            vitest_1.vi.stubEnv('HOME', testHome);
+            (0, vitest_1.expect)((0, migration_1.migrationNeeded)()).toBe(false);
+        });
+    });
+    (0, vitest_1.describe)('getMigrationItems', () => {
+        (0, vitest_1.test)('identifies github-api as config item', () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            const { configItems } = (0, migration_1.getMigrationItems)();
+            (0, vitest_1.expect)(configItems).toContain('github-api');
+        });
+        (0, vitest_1.test)('identifies binary as cache item', () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            const { cacheItems } = (0, migration_1.getMigrationItems)();
+            (0, vitest_1.expect)(cacheItems).toContain('binary');
+        });
+    });
+    (0, vitest_1.describe)('migrateFromLegacy', () => {
+        (0, vitest_1.test)('performs dry run without creating directories', async () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            const progress = [];
+            const result = await (0, migration_1.migrateFromLegacy)({
+                dryRun: true,
+                onProgress: (msg) => progress.push(msg),
+            });
+            (0, vitest_1.expect)(result.success).toBe(true);
+            (0, vitest_1.expect)(result.configMigrated).toBe(false);
+            (0, vitest_1.expect)(result.cacheMigrated).toBe(false);
+            (0, vitest_1.expect)(progress.some(msg => msg.includes('[DRY RUN]'))).toBe(true);
+        });
+        (0, vitest_1.test)('creates XDG directories when migrating', async () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            const result = await (0, migration_1.migrateFromLegacy)({ force: true });
+            (0, vitest_1.expect)(result.success).toBe(true);
+            (0, vitest_1.expect)(node_fs_1.default.existsSync(configDir)).toBe(true);
+            (0, vitest_1.expect)(node_fs_1.default.existsSync(cacheDir)).toBe(true);
+        });
+        (0, vitest_1.test)('copies github-api to config directory', async () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            await (0, migration_1.migrateFromLegacy)({ force: true });
+            const githubApiPath = node_path_1.default.join(configDir, 'github-api', 'test');
+            (0, vitest_1.expect)(node_fs_1.default.existsSync(githubApiPath)).toBe(true);
+        });
+        (0, vitest_1.test)('copies binary to cache directory', async () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            await (0, migration_1.migrateFromLegacy)({ force: true });
+            const binaryPath = node_path_1.default.join(cacheDir, 'binary', 'test');
+            (0, vitest_1.expect)(node_fs_1.default.existsSync(binaryPath)).toBe(true);
+        });
+    });
+    (0, vitest_1.describe)('getMigrationStatus', () => {
+        (0, vitest_1.test)('returns comprehensive status', () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            const status = (0, migration_1.getMigrationStatus)();
+            (0, vitest_1.expect)(status).toHaveProperty('legacyExists');
+            (0, vitest_1.expect)(status).toHaveProperty('configExists');
+            (0, vitest_1.expect)(status).toHaveProperty('cacheExists');
+            (0, vitest_1.expect)(status).toHaveProperty('needsMigration');
+            (0, vitest_1.expect)(status).toHaveProperty('pendingItems');
+        });
+        (0, vitest_1.test)('indicates migration is needed', () => {
+            vitest_1.vi.stubEnv('HOME', testHome);
+            const status = (0, migration_1.getMigrationStatus)();
+            (0, vitest_1.expect)(status.legacyExists).toBe(true);
+            (0, vitest_1.expect)(status.configExists).toBe(false);
+            (0, vitest_1.expect)(status.needsMigration).toBe(true);
+        });
+    });
+});

package/dist/paths.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_DIR_NAME = exports.CACHE_SUBDIR = exports.CONFIG_SUBDIR = exports.XDG_CACHE_HOME_ENV = exports.XDG_CONFIG_HOME_ENV = void 0;
+exports.getConfigDir = getConfigDir;
+exports.getCacheDir = getCacheDir;
+exports.getLegacyDir = getLegacyDir;
+exports.legacyDirExists = legacyDirExists;
+exports.getConfigSubdirPath = getConfigSubdirPath;
+exports.getCacheSubdirPath = getCacheSubdirPath;
+exports.getPathInfo = getPathInfo;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+// XDG Base Directory Specification constants
+exports.XDG_CONFIG_HOME_ENV = 'XDG_CONFIG_HOME';
+exports.XDG_CACHE_HOME_ENV = 'XDG_CACHE_HOME';
+// Default subdirectory names
+exports.CONFIG_SUBDIR = 'kanban-ai';
+exports.CACHE_SUBDIR = 'kanban-ai';
+// Legacy directory name for migration detection
+exports.LEGACY_DIR_NAME = '.kanbanAI';
+/**
+ * Check if running on Windows platform
+ */
+function isWindows() {
+    return process.platform === 'win32';
+}
+/**
+ * Get the user's config directory following XDG Base Directory Specification
+ * On Windows, uses APPDATA if XDG_CONFIG_HOME is not set
+ * @param customHome Optional custom home directory (useful for testing)
+ * @returns The config directory path
+ */
+function getConfigDir(customHome) {
+    const home = customHome || node_os_1.default.homedir();
+    const xdgConfigHome = process.env[exports.XDG_CONFIG_HOME_ENV];
+    if (xdgConfigHome) {
+        return node_path_1.default.join(xdgConfigHome, exports.CONFIG_SUBDIR);
+    }
+    // On Windows, use APPDATA as the conventional location
+    if (isWindows()) {
+        const appData = process.env.APPDATA || node_path_1.default.join(home, 'AppData', 'Roaming');
+        return node_path_1.default.join(appData, exports.CONFIG_SUBDIR);
+    }
+    // On Unix/Linux, use XDG default
+    return node_path_1.default.join(home, '.config', exports.CONFIG_SUBDIR);
+}
+/**
+ * Get the user's cache directory following XDG Base Directory Specification
+ * On Windows, uses LOCALAPPDATA if XDG_CACHE_HOME is not set
+ * @param customHome Optional custom home directory (useful for testing)
+ * @returns The cache directory path
+ */
+function getCacheDir(customHome) {
+    const home = customHome || node_os_1.default.homedir();
+    const xdgCacheHome = process.env[exports.XDG_CACHE_HOME_ENV];
+    if (xdgCacheHome) {
+        return node_path_1.default.join(xdgCacheHome, exports.CACHE_SUBDIR);
+    }
+    // On Windows, use LOCALAPPDATA as the conventional location
+    if (isWindows()) {
+        const localAppData = process.env.LOCALAPPDATA || node_path_1.default.join(home, 'AppData', 'Local');
+        return node_path_1.default.join(localAppData, exports.CACHE_SUBDIR);
+    }
+    // On Unix/Linux, use XDG default
+    return node_path_1.default.join(home, '.cache', exports.CACHE_SUBDIR);
+}
+/**
+ * Get the legacy .kanbanAI directory path for migration detection
+ * @param customHome Optional custom home directory (useful for testing)
+ * @returns The legacy directory path
+ */
+function getLegacyDir(customHome) {
+    const home = customHome || node_os_1.default.homedir();
+    return node_path_1.default.join(home, exports.LEGACY_DIR_NAME);
+}
+/**
+ * Check if the legacy .kanbanAI directory exists
+ * @param customHome Optional custom home directory (useful for testing)
+ * @returns true if legacy directory exists
+ */
+function legacyDirExists(customHome) {
+    const legacyPath = getLegacyDir(customHome);
+    return node_fs_1.default.existsSync(legacyPath);
+}
+/**
+ * Get the path for a specific subdirectory within the config directory
+ * @param subdirName The subdirectory name
+ * @returns The full path to the subdirectory
+ */
+function getConfigSubdirPath(subdirName) {
+    return node_path_1.default.join(getConfigDir(), subdirName);
+}
+/**
+ * Get the path for a specific subdirectory within the cache directory
+ * @param subdirName The subdirectory name
+ * @returns The full path to the subdirectory
+ */
+function getCacheSubdirPath(subdirName) {
+    return node_path_1.default.join(getCacheDir(), subdirName);
+}
+/**
+ * Get comprehensive path information for debugging purposes
+ * @returns PathInfo object with all relevant paths
+ */
+function getPathInfo() {
+    return {
+        configDir: getConfigDir(),
+        cacheDir: getCacheDir(),
+        legacyDir: getLegacyDir(),
+        legacyExists: legacyDirExists(),
+        xdgConfigHome: process.env[exports.XDG_CONFIG_HOME_ENV],
+        xdgCacheHome: process.env[exports.XDG_CACHE_HOME_ENV],
+        platform: process.platform,
+    };
+}

package/dist/paths.test.js

@@ -0,0 +1,154 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const paths_1 = require("./paths");
+(0, vitest_1.describe)('Path Resolution', () => {
+    const testHome = '/test/home';
+    (0, vitest_1.describe)('getConfigDir', () => {
+        (0, vitest_1.test)('uses XDG_CONFIG_HOME when set', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', '/custom/config');
+            (0, vitest_1.expect)((0, paths_1.getConfigDir)(testHome)).toBe('/custom/config/kanban-ai');
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('falls back to ~/.config when XDG_CONFIG_HOME not set', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', undefined);
+            (0, vitest_1.expect)((0, paths_1.getConfigDir)(testHome)).toBe('/test/home/.config/kanban-ai');
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('uses provided home directory', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', undefined);
+            (0, vitest_1.expect)((0, paths_1.getConfigDir)('/another/home')).toBe('/another/home/.config/kanban-ai');
+            vitest_1.vi.unstubAllEnvs();
+        });
+    });
+    (0, vitest_1.describe)('getCacheDir', () => {
+        (0, vitest_1.test)('uses XDG_CACHE_HOME when set', () => {
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', '/custom/cache');
+            (0, vitest_1.expect)((0, paths_1.getCacheDir)(testHome)).toBe('/custom/cache/kanban-ai');
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('falls back to ~/.cache when XDG_CACHE_HOME not set', () => {
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', undefined);
+            (0, vitest_1.expect)((0, paths_1.getCacheDir)(testHome)).toBe('/test/home/.cache/kanban-ai');
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('uses provided home directory', () => {
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', undefined);
+            (0, vitest_1.expect)((0, paths_1.getCacheDir)('/another/home')).toBe('/another/home/.cache/kanban-ai');
+            vitest_1.vi.unstubAllEnvs();
+        });
+    });
+    (0, vitest_1.describe)('getLegacyDir', () => {
+        (0, vitest_1.test)('returns ~/.kanbanAI', () => {
+            (0, vitest_1.expect)((0, paths_1.getLegacyDir)(testHome)).toBe('/test/home/.kanbanAI');
+        });
+    });
+    (0, vitest_1.describe)('legacyDirExists', () => {
+        (0, vitest_1.test)('returns false when legacy directory does not exist', () => {
+            vitest_1.vi.stubEnv('HOME', '/nonexistent');
+            (0, vitest_1.expect)((0, paths_1.legacyDirExists)()).toBe(false);
+            vitest_1.vi.unstubAllEnvs();
+        });
+    });
+    (0, vitest_1.describe)('getConfigSubdirPath', () => {
+        (0, vitest_1.test)('creates path for config subdirectory', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', undefined);
+            (0, vitest_1.expect)((0, paths_1.getConfigSubdirPath)('test')).toBe(node_path_1.default.join(node_os_1.default.homedir(), '.config', 'kanban-ai', 'test'));
+            vitest_1.vi.unstubAllEnvs();
+        });
+    });
+    (0, vitest_1.describe)('getCacheSubdirPath', () => {
+        (0, vitest_1.test)('creates path for cache subdirectory', () => {
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', undefined);
+            (0, vitest_1.expect)((0, paths_1.getCacheSubdirPath)('test')).toBe(node_path_1.default.join(node_os_1.default.homedir(), '.cache', 'kanban-ai', 'test'));
+            vitest_1.vi.unstubAllEnvs();
+        });
+    });
+    (0, vitest_1.describe)('getPathInfo', () => {
+        (0, vitest_1.test)('returns comprehensive path information', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', undefined);
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', undefined);
+            const info = (0, paths_1.getPathInfo)();
+            (0, vitest_1.expect)(info).toHaveProperty('configDir');
+            (0, vitest_1.expect)(info).toHaveProperty('cacheDir');
+            (0, vitest_1.expect)(info).toHaveProperty('legacyDir');
+            (0, vitest_1.expect)(info).toHaveProperty('legacyExists');
+            (0, vitest_1.expect)(info).toHaveProperty('xdgConfigHome');
+            (0, vitest_1.expect)(info).toHaveProperty('xdgCacheHome');
+            (0, vitest_1.expect)(info).toHaveProperty('platform');
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('includes XDG environment variables when set', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', '/custom/config');
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', '/custom/cache');
+            const info = (0, paths_1.getPathInfo)();
+            (0, vitest_1.expect)(info.xdgConfigHome).toBe('/custom/config');
+            (0, vitest_1.expect)(info.xdgCacheHome).toBe('/custom/cache');
+            vitest_1.vi.unstubAllEnvs();
+        });
+    });
+    (0, vitest_1.describe)('Windows Support', () => {
+        (0, vitest_1.test)('uses APPDATA for config on Windows when XDG not set', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', undefined);
+            vitest_1.vi.stubEnv('APPDATA', 'C:\\Users\\test\\AppData\\Roaming');
+            // Mock platform detection
+            const originalPlatform = process.platform;
+            Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+            const result = (0, paths_1.getConfigDir)('C:\\Users\\test');
+            // On Linux, path.join normalizes to forward slashes, but the path structure is correct
+            (0, vitest_1.expect)(result.toLowerCase()).toContain('appdata\\roaming'.toLowerCase());
+            (0, vitest_1.expect)(result).toContain('kanban-ai');
+            // Restore platform
+            Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('uses LOCALAPPDATA for cache on Windows when XDG not set', () => {
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', undefined);
+            vitest_1.vi.stubEnv('LOCALAPPDATA', 'C:\\Users\\test\\AppData\\Local');
+            // Mock platform detection
+            const originalPlatform = process.platform;
+            Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+            const result = (0, paths_1.getCacheDir)('C:\\Users\\test');
+            (0, vitest_1.expect)(result.toLowerCase()).toContain('appdata\\local'.toLowerCase());
+            (0, vitest_1.expect)(result).toContain('kanban-ai');
+            // Restore platform
+            Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('falls back to AppData\\Roaming when APPDATA not set on Windows', () => {
+            vitest_1.vi.stubEnv('XDG_CONFIG_HOME', undefined);
+            vitest_1.vi.stubEnv('APPDATA', undefined);
+            // Mock platform detection
+            const originalPlatform = process.platform;
+            Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+            const result = (0, paths_1.getConfigDir)('C:\\Users\\test');
+            // On Linux, path.join normalizes to forward slashes, so check for both with/without separator
+            const normalizedResult = result.toLowerCase().replace(/\\/g, '/');
+            (0, vitest_1.expect)(normalizedResult).toContain('appdata/roaming');
+            (0, vitest_1.expect)(result).toContain('kanban-ai');
+            // Restore platform
+            Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+            vitest_1.vi.unstubAllEnvs();
+        });
+        (0, vitest_1.test)('falls back to AppData\\Local when LOCALAPPDATA not set on Windows', () => {
+            vitest_1.vi.stubEnv('XDG_CACHE_HOME', undefined);
+            vitest_1.vi.stubEnv('LOCALAPPDATA', undefined);
+            // Mock platform detection
+            const originalPlatform = process.platform;
+            Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+            const result = (0, paths_1.getCacheDir)('C:\\Users\\test');
+            // On Linux, path.join normalizes to forward slashes, so check for both with/without separator
+            const normalizedResult = result.toLowerCase().replace(/\\/g, '/');
+            (0, vitest_1.expect)(normalizedResult).toContain('appdata/local');
+            (0, vitest_1.expect)(result).toContain('kanban-ai');
+            // Restore platform
+            Object.defineProperty(process, 'platform', { value: originalPlatform, configurable: true });
+            vitest_1.vi.unstubAllEnvs();
+        });
+    });
+});

package/dist/updates.test.js

@@ -47,6 +47,7 @@ const binaryInfo = {
 const baseEnv = {
     githubRepo: "owner/repo",
     baseCacheDir: "/tmp/kanbanai",
+    configDir: "/tmp/kanbanai-config",
     binaryVersionOverride: undefined,
     noUpdateCheck: false,
     assumeYes: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanban-ai",
-  "version": "0.22.0",
+  "version": "0.22.2",
   "description": "Thin CLI wrapper that downloads and runs the KanbanAI binary from GitHub releases.",
   "bin": {
     "kanban-ai": "dist/index.js"