agentikit 0.0.13 → 0.0.15

package/dist/common.js

@@ -0,0 +1,192 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TYPE_DIRS } from "./asset-spec";
+import { ConfigError } from "./errors";
+import { getConfigPath, getDefaultStashDir } from "./paths";
+// ── Constants ───────────────────────────────────────────────────────────────
+export const IS_WINDOWS = process.platform === "win32";
+// ── Validators ──────────────────────────────────────────────────────────────
+export function isAssetType(type) {
+    return type in TYPE_DIRS;
+}
+// ── Utilities ───────────────────────────────────────────────────────────────
+/**
+ * Resolve the stash directory using a three-level fallback chain:
+ *   1. AKM_STASH_DIR environment variable (override for CI/scripts)
+ *   2. stashDir field in config.json
+ *   3. Platform default (~/agentikit or ~/Documents/agentikit on Windows)
+ *
+ * Throws if no valid stash directory is found.
+ */
+export function resolveStashDir(options) {
+    // 1. Env var override (for CI, scripts, testing)
+    const envDir = process.env.AKM_STASH_DIR?.trim();
+    if (envDir) {
+        const resolved = validateStashDir(envDir);
+        if (!options?.readOnly)
+            persistStashDirToConfig(resolved);
+        return resolved;
+    }
+    // 2. Config file stashDir field
+    const configStashDir = readStashDirFromConfig();
+    if (configStashDir)
+        return validateStashDir(configStashDir);
+    // 3. Platform default — use it if it exists
+    const defaultDir = getDefaultStashDir();
+    if (isValidDirectory(defaultDir)) {
+        return defaultDir;
+    }
+    throw new ConfigError(`No stash directory found. Run "akm init" to create one at ${defaultDir}, ` +
+        `or set stashDir in ${getConfigPath()}.`);
+}
+function validateStashDir(raw) {
+    const stashDir = path.resolve(raw);
+    let stat;
+    try {
+        stat = fs.statSync(stashDir);
+    }
+    catch {
+        throw new ConfigError(`Unable to read stash directory at "${stashDir}".`);
+    }
+    if (!stat.isDirectory()) {
+        throw new ConfigError(`Stash path must point to a directory: "${stashDir}".`);
+    }
+    return stashDir;
+}
+function isValidDirectory(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read stashDir directly from config.json without pulling in the full config
+ * module, to avoid circular dependencies.
+ */
+function readStashDirFromConfig() {
+    try {
+        const configPath = getConfigPath();
+        const text = fs.readFileSync(configPath, "utf8");
+        const raw = JSON.parse(text);
+        if (typeof raw === "object" && raw !== null && typeof raw.stashDir === "string" && raw.stashDir.trim()) {
+            return raw.stashDir.trim();
+        }
+    }
+    catch {
+        // Config doesn't exist or is invalid — fall through
+    }
+    return undefined;
+}
+/**
+ * Persist stashDir to config.json if not already set, so users can
+ * transition away from relying on the AKM_STASH_DIR env var.
+ */
+function persistStashDirToConfig(stashDir) {
+    try {
+        const configPath = getConfigPath();
+        let raw = {};
+        try {
+            const text = fs.readFileSync(configPath, "utf8");
+            const parsed = JSON.parse(text);
+            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+                raw = parsed;
+            }
+        }
+        catch {
+            // No existing config or invalid — start fresh
+        }
+        if (!raw.stashDir) {
+            raw.stashDir = stashDir;
+            const dir = path.dirname(configPath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = configPath + `.tmp.${process.pid}`;
+            fs.writeFileSync(tmpPath, JSON.stringify(raw, null, 2) + "\n", "utf8");
+            fs.renameSync(tmpPath, configPath);
+        }
+    }
+    catch {
+        // Non-fatal: best-effort persistence
+    }
+}
+export function toPosix(input) {
+    return input.replace(/\\/g, "/");
+}
+export function hasErrnoCode(error, code) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === code;
+}
+export function isWithin(candidate, root) {
+    const resolvedRoot = safeRealpath(root);
+    const resolvedCandidate = safeRealpath(candidate);
+    const normalizedRoot = normalizeFsPathForComparison(resolvedRoot);
+    const normalizedCandidate = normalizeFsPathForComparison(resolvedCandidate);
+    const rel = path.relative(normalizedRoot, normalizedCandidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function safeRealpath(p) {
+    try {
+        return fs.realpathSync(path.resolve(p));
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+function normalizeFsPathForComparison(value) {
+    return process.platform === "win32" ? value.toLowerCase() : value;
+}
+/**
+ * Fetch with an AbortController timeout.
+ * Defaults to 30 seconds if no timeout is specified.
+ */
+export async function fetchWithTimeout(url, opts, timeoutMs = 30_000) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...opts, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch with retry and exponential backoff.
+ * Retries on network errors, 429, and 5xx responses.
+ * Honors Retry-After header for 429 responses.
+ */
+export async function fetchWithRetry(url, init, options) {
+    const maxRetries = options?.retries ?? 3;
+    const baseDelay = options?.baseDelay ?? 500;
+    const timeout = options?.timeout ?? 30_000;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const response = await fetchWithTimeout(url, init, timeout);
+            if (attempt < maxRetries && shouldRetry(response.status)) {
+                const retryAfter = parseRetryAfter(response);
+                const delay = retryAfter ?? baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
+                await new Promise((r) => setTimeout(r, delay));
+                continue;
+            }
+            return response;
+        }
+        catch (err) {
+            if (attempt >= maxRetries)
+                throw err;
+            const delay = baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw new Error("fetchWithRetry: unreachable");
+}
+function shouldRetry(status) {
+    return status === 429 || status >= 500;
+}
+function parseRetryAfter(response) {
+    const header = response.headers.get("retry-after");
+    if (!header)
+        return undefined;
+    const seconds = parseInt(header, 10);
+    return isNaN(seconds) ? undefined : seconds * 1000;
+}

package/dist/{src/config-cli.js → config-cli.js}

@@ -1,5 +1,6 @@
 import { DEFAULT_CONFIG, } from "./config";
 import { EMBEDDING_DIM } from "./db";
+import { ConfigError, UsageError } from "./errors";
 const LOCAL_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
 const DEFAULT_LLM_TEMPERATURE = 0.3;
 const DEFAULT_LLM_MAX_TOKENS = 512;
@@ -59,35 +60,39 @@ const LLM_PROVIDER_PRESETS = {
 };
 export function parseConfigValue(key, value) {
     switch (key) {
+        case "stashDir":
+            return { stashDir: requireNonEmptyString(value, key) };
         case "semanticSearch":
             if (value !== "true" && value !== "false") {
-                throw new Error(`Invalid value for semanticSearch: expected "true" or "false"`);
+                throw new UsageError(`Invalid value for semanticSearch: expected "true" or "false"`);
             }
             return { semanticSearch: value === "true" };
-        case "mountedStashDirs":
+        case "searchPaths":
             try {
                 const parsed = JSON.parse(value);
                 if (!Array.isArray(parsed))
-                    throw new Error("expected JSON array");
-                return { mountedStashDirs: parsed.filter((d) => typeof d === "string") };
+                    throw new UsageError("expected JSON array");
+                return { searchPaths: parsed.filter((d) => typeof d === "string") };
             }
             catch {
-                throw new Error(`Invalid value for mountedStashDirs: expected JSON array (e.g. '["/path/a","/path/b"]')`);
+                throw new UsageError(`Invalid value for searchPaths: expected JSON array (e.g. '["/path/a","/path/b"]')`);
             }
         case "embedding":
             return { embedding: parseEmbeddingConnectionValue(value) };
         case "llm":
             return { llm: parseLlmConnectionValue(value) };
         default:
-            throw new Error(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`);
     }
 }
 export function getConfigValue(config, key) {
     switch (key) {
+        case "stashDir":
+            return config.stashDir ?? null;
         case "semanticSearch":
             return config.semanticSearch;
-        case "mountedStashDirs":
-            return [...config.mountedStashDirs];
+        case "searchPaths":
+            return [...config.searchPaths];
         case "embedding":
             return maskSecrets(getEmbeddingDisplayConfig(config));
         case "embedding.provider":
@@ -115,13 +120,14 @@ export function getConfigValue(config, key) {
         case "llm.apiKey":
             return maskSecret(getLlmDisplayConfig(config).apiKey) ?? null;
         default:
-            throw new Error(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`);
     }
 }
 export function setConfigValue(config, key, rawValue) {
     switch (key) {
+        case "stashDir":
         case "semanticSearch":
-        case "mountedStashDirs":
+        case "searchPaths":
         case "embedding":
         case "llm":
             return { ...config, ...parseConfigValue(key, rawValue) };
@@ -202,11 +208,13 @@ export function setConfigValue(config, key, rawValue) {
                 },
             };
         default:
-            throw new Error(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`);
     }
 }
 export function unsetConfigValue(config, key) {
     switch (key) {
+        case "stashDir":
+            return { ...config, stashDir: undefined };
         case "embedding":
             return { ...config, embedding: undefined };
         case "embedding.apiKey":
@@ -240,13 +248,14 @@ export function unsetConfigValue(config, key) {
                 return config;
             return { ...config, llm: omitKey(config.llm, "provider") };
         default:
-            throw new Error(`Unknown or unsupported unset key: ${key}`);
+            throw new UsageError(`Unknown or unsupported unset key: ${key}`);
     }
 }
 export function listConfig(config) {
     return {
         ...DEFAULT_CONFIG,
         ...maskSecrets(config),
+        stashDir: config.stashDir ?? null,
         embedding: maskSecrets(getEmbeddingDisplayConfig(config)),
         llm: maskSecrets(getLlmDisplayConfig(config)),
     };
@@ -265,7 +274,7 @@ export function useProvider(config, scope, providerName) {
     if (scope === "embedding") {
         const preset = EMBEDDING_PROVIDER_PRESETS[providerName];
         if (!preset) {
-            throw new Error(`Unknown embedding provider: ${providerName}`);
+            throw new UsageError(`Unknown embedding provider: ${providerName}`);
         }
         if (!preset.config) {
             return { ...config, embedding: undefined };
@@ -274,7 +283,7 @@ export function useProvider(config, scope, providerName) {
     }
     const preset = LLM_PROVIDER_PRESETS[providerName];
     if (!preset) {
-        throw new Error(`Unknown llm provider: ${providerName}`);
+        throw new UsageError(`Unknown llm provider: ${providerName}`);
     }
     if (!preset.config) {
         return { ...config, llm: undefined };
@@ -380,68 +389,65 @@ function parseJsonObject(value, key, example) {
         parsed = JSON.parse(value);
     }
     catch {
-        throw new Error(`Invalid value for ${key}: expected JSON object with endpoint and model`
-            + ` (e.g. '{"endpoint":"${example.endpoint}","model":"${example.model}"}')`);
+        throw new UsageError(`Invalid value for ${key}: expected JSON object with endpoint and model` +
+            ` (e.g. '{"endpoint":"${example.endpoint}","model":"${example.model}"}')`);
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new Error(`Invalid value for ${key}: expected a JSON object`);
+        throw new UsageError(`Invalid value for ${key}: expected a JSON object`);
     }
     return parsed;
 }
 function asRequiredString(value, key, field) {
     if (typeof value !== "string" || !value) {
-        throw new Error(`Invalid value for ${key}: "${field}" is a required string field`);
+        throw new UsageError(`Invalid value for ${key}: "${field}" is a required string field`);
     }
     return value;
 }
 function requireEmbeddingConfig(config) {
     if (!config.embedding) {
-        throw new Error("Embedding provider is using the built-in local default. Run `akm config use embedding <provider>` first.");
+        throw new ConfigError("Embedding provider is using the built-in local default. Run `akm config use embedding <provider>` first.");
     }
     return config.embedding;
 }
 function requireLlmConfig(config) {
     if (!config.llm) {
-        throw new Error("LLM provider is disabled. Run `akm config use llm <provider>` first.");
+        throw new ConfigError("LLM provider is disabled. Run `akm config use llm <provider>` first.");
     }
     return config.llm;
 }
 function requireNonEmptyString(value, key) {
     if (!value) {
-        throw new Error(`Invalid value for ${key}: expected a non-empty string`);
+        throw new UsageError(`Invalid value for ${key}: expected a non-empty string`);
     }
     return value;
 }
 function parseNumber(value, key) {
     const parsed = Number(value);
     if (!Number.isFinite(parsed)) {
-        throw new Error(`Invalid value for ${key}: expected a number`);
+        throw new UsageError(`Invalid value for ${key}: expected a number`);
     }
     return parsed;
 }
 function parsePositiveInteger(value, key) {
     const trimmed = value.trim();
     if (!/^[1-9]\d*$/.test(trimmed)) {
-        throw new Error(`Invalid value for ${key}: expected a positive integer`);
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
     }
     const parsed = Number(trimmed);
     if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) {
-        throw new Error(`Invalid value for ${key}: expected a positive integer`);
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
     }
     return parsed;
 }
 function parseUnknownNumber(value, key) {
     if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw new Error(`Invalid value for ${key}: expected a number`);
+        throw new UsageError(`Invalid value for ${key}: expected a number`);
     }
     return value;
 }
 function parseUnknownPositiveInteger(value, key) {
-    if (typeof value !== "number" ||
-        !Number.isFinite(value) ||
-        !Number.isInteger(value) ||
-        value <= 0) {
-        throw new Error(`Invalid value for ${key}: expected a positive integer`);
+    if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
     }
     return value;
 }

package/dist/{src/config.js → config.js}

@@ -1,37 +1,33 @@
 import fs from "node:fs";
 import path from "node:path";
+import { getConfigDir as _getConfigDir, getConfigPath as _getConfigPath } from "./paths";
 // ── Defaults ────────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = {
     semanticSearch: true,
-    mountedStashDirs: [],
+    searchPaths: [],
 };
 // ── Paths ───────────────────────────────────────────────────────────────────
-export function getConfigDir(env = process.env, platform = process.platform) {
-    if (platform === "win32") {
-        const appData = env.APPDATA?.trim();
-        if (appData)
-            return path.join(appData, "agentikit");
-        const userProfile = env.USERPROFILE?.trim();
-        if (!userProfile) {
-            throw new Error("Unable to determine config directory. Set APPDATA or USERPROFILE.");
-        }
-        return path.join(userProfile, "AppData", "Roaming", "agentikit");
-    }
-    const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
-    if (xdgConfigHome)
-        return path.join(xdgConfigHome, "agentikit");
-    const home = env.HOME?.trim();
-    if (!home) {
-        throw new Error("Unable to determine config directory. Set XDG_CONFIG_HOME or HOME.");
-    }
-    return path.join(home, ".config", "agentikit");
+export function getConfigDir(env, platform) {
+    return _getConfigDir(env, platform);
 }
 export function getConfigPath() {
-    return path.join(getConfigDir(), "config.json");
+    return _getConfigPath();
 }
 // ── Load / Save / Update ────────────────────────────────────────────────────
+let cachedConfig;
 export function loadConfig() {
     const configPath = getConfigPath();
+    try {
+        const stat = fs.statSync(configPath);
+        if (cachedConfig && cachedConfig.path === configPath && cachedConfig.mtime === stat.mtimeMs) {
+            return cachedConfig.config;
+        }
+    }
+    catch {
+        // File doesn't exist — return defaults below
+        cachedConfig = undefined;
+        return { ...DEFAULT_CONFIG };
+    }
     const raw = readConfigObject(configPath);
     const config = raw ? pickKnownKeys(raw) : { ...DEFAULT_CONFIG };
     // Inject API keys from environment variables.
@@ -47,9 +43,18 @@ export function loadConfig() {
         if (envKey)
             config.llm.apiKey = envKey;
     }
+    // Cache the parsed config with its path and mtime for subsequent calls
+    try {
+        const stat = fs.statSync(configPath);
+        cachedConfig = { config, path: configPath, mtime: stat.mtimeMs };
+    }
+    catch {
+        // If we can't stat (unlikely since we just read it), skip caching
+    }
     return config;
 }
 export function saveConfig(config) {
+    cachedConfig = undefined;
     const configPath = getConfigPath();
     const dir = path.dirname(configPath);
     fs.mkdirSync(dir, { recursive: true });
@@ -63,7 +68,9 @@ export function saveConfig(config) {
         try {
             fs.unlinkSync(tmpPath);
         }
-        catch { /* ignore cleanup failure */ }
+        catch {
+            /* ignore cleanup failure */
+        }
         throw err;
     }
 }
@@ -93,11 +100,23 @@ export function updateConfig(partial) {
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function pickKnownKeys(raw) {
     const config = { ...DEFAULT_CONFIG };
+    if (typeof raw.stashDir === "string" && raw.stashDir.trim()) {
+        config.stashDir = raw.stashDir.trim();
+    }
     if (typeof raw.semanticSearch === "boolean") {
         config.semanticSearch = raw.semanticSearch;
     }
+    if (Array.isArray(raw.searchPaths)) {
+        config.searchPaths = raw.searchPaths.filter((d) => typeof d === "string");
+    }
+    // Backward compat: merge legacy mountedStashDirs into searchPaths
     if (Array.isArray(raw.mountedStashDirs)) {
-        config.mountedStashDirs = raw.mountedStashDirs.filter((d) => typeof d === "string");
+        const legacy = raw.mountedStashDirs.filter((d) => typeof d === "string");
+        const existing = new Set(config.searchPaths);
+        for (const d of legacy) {
+            if (!existing.has(d))
+                config.searchPaths.push(d);
+        }
     }
     const embedding = parseEmbeddingConfig(raw.embedding);
     if (embedding)
@@ -115,7 +134,8 @@ function pickKnownKeys(raw) {
 }
 function readConfigObject(configPath) {
     try {
-        const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        const text = fs.readFileSync(configPath, "utf8");
+        const raw = JSON.parse(stripJsonComments(text));
         if (typeof raw !== "object" || raw === null || Array.isArray(raw))
             return undefined;
         return raw;
@@ -124,6 +144,54 @@ function readConfigObject(configPath) {
         return undefined;
     }
 }
+/**
+ * Strip JavaScript-style comments from a JSON string (JSONC support).
+ * Handles // line comments and /* block comments while preserving
+ * comment-like sequences inside quoted strings.
+ */
+export function stripJsonComments(text) {
+    let result = "";
+    let i = 0;
+    let inString = false;
+    let stringChar = "";
+    while (i < text.length) {
+        if (inString) {
+            if (text[i] === "\\") {
+                result += text[i] + (text[i + 1] ?? "");
+                i += 2;
+                continue;
+            }
+            if (text[i] === stringChar) {
+                inString = false;
+            }
+            result += text[i];
+            i++;
+            continue;
+        }
+        if (text[i] === '"' || text[i] === "'") {
+            inString = true;
+            stringChar = text[i];
+            result += text[i];
+            i++;
+            continue;
+        }
+        if (text[i] === "/" && text[i + 1] === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (text[i] === "/" && text[i + 1] === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i += 2;
+            continue;
+        }
+        result += text[i];
+        i++;
+    }
+    return result;
+}
 function parseEmbeddingConfig(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -230,5 +298,7 @@ function asNonEmptyString(value) {
     return typeof value === "string" && value ? value : undefined;
 }
 function asRegistrySource(value) {
-    return value === "npm" || value === "github" || value === "git" ? value : undefined;
+    if (value === "npm" || value === "github" || value === "git" || value === "local")
+        return value;
+    return undefined;
 }