akm-cli 0.0.0 → 0.0.16

package/dist/common.js

@@ -0,0 +1,199 @@
+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";
+/**
+ * Normalize an asset type for output purposes.
+ * "tool" is a transparent alias for "script" -- all output should use "script".
+ */
+export function normalizeAssetType(type) {
+    return type === "tool" ? "script" : type;
+}
+// ── 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 (~/akm or ~/Documents/akm 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 Number.isNaN(seconds) ? undefined : seconds * 1000;
+}

package/dist/config-cli.js

@@ -0,0 +1,195 @@
+import { DEFAULT_CONFIG, } from "./config";
+import { UsageError } from "./errors";
+export function parseConfigValue(key, value) {
+    switch (key) {
+        case "stashDir":
+            return { stashDir: requireNonEmptyString(value, key) };
+        case "semanticSearch":
+            if (value !== "true" && value !== "false") {
+                throw new UsageError(`Invalid value for semanticSearch: expected "true" or "false"`);
+            }
+            return { semanticSearch: value === "true" };
+        case "searchPaths":
+            try {
+                const parsed = JSON.parse(value);
+                if (!Array.isArray(parsed))
+                    throw new UsageError("expected JSON array");
+                return { searchPaths: parsed.filter((d) => typeof d === "string") };
+            }
+            catch {
+                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) };
+        case "output.format":
+            return { output: { format: parseOutputFormat(value) } };
+        case "output.detail":
+            return { output: { detail: parseOutputDetail(value) } };
+        default:
+            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 "searchPaths":
+            return [...config.searchPaths];
+        case "embedding":
+            return config.embedding ?? null;
+        case "llm":
+            return config.llm ?? null;
+        case "output.format":
+            return config.output?.format ?? null;
+        case "output.detail":
+            return config.output?.detail ?? null;
+        default:
+            throw new UsageError(`Unknown config key: ${key}`);
+    }
+}
+export function setConfigValue(config, key, rawValue) {
+    switch (key) {
+        case "stashDir":
+        case "semanticSearch":
+        case "searchPaths":
+        case "embedding":
+        case "llm":
+        case "output.format":
+        case "output.detail":
+            return mergeConfigValue(config, parseConfigValue(key, rawValue));
+        default:
+            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 "llm":
+            return { ...config, llm: undefined };
+        case "output.format":
+            return { ...config, output: mergeOutputConfig(config.output, { format: undefined }) };
+        case "output.detail":
+            return { ...config, output: mergeOutputConfig(config.output, { detail: undefined }) };
+        default:
+            throw new UsageError(`Unknown or unsupported unset key: ${key}`);
+    }
+}
+export function listConfig(config) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...config,
+        output: mergeOutputConfig(DEFAULT_CONFIG.output, config.output) ?? null,
+        stashDir: config.stashDir ?? null,
+        embedding: config.embedding ?? null,
+        llm: config.llm ?? null,
+    };
+}
+function mergeConfigValue(config, partial) {
+    return {
+        ...config,
+        ...partial,
+        output: mergeOutputConfig(config.output, partial.output),
+    };
+}
+function mergeOutputConfig(base, override) {
+    const merged = {
+        ...(base ?? {}),
+        ...(override ?? {}),
+    };
+    return merged.format || merged.detail ? merged : undefined;
+}
+function parseOutputFormat(value) {
+    if (value === "json" || value === "yaml" || value === "text")
+        return value;
+    throw new UsageError(`Invalid value for output.format: expected one of json|yaml|text`);
+}
+function parseOutputDetail(value) {
+    if (value === "brief" || value === "normal" || value === "full")
+        return value;
+    throw new UsageError(`Invalid value for output.detail: expected one of brief|normal|full`);
+}
+function parseEmbeddingConnectionValue(value) {
+    if (value === "null" || value === "")
+        return undefined;
+    const parsed = parseJsonObject(value, "embedding", {
+        endpoint: "http://localhost:11434/v1/embeddings",
+        model: "nomic-embed-text",
+    });
+    const result = {
+        endpoint: asRequiredString(parsed.endpoint, "embedding", "endpoint"),
+        model: asRequiredString(parsed.model, "embedding", "model"),
+    };
+    if (typeof parsed.provider === "string" && parsed.provider)
+        result.provider = parsed.provider;
+    if (parsed.dimension !== undefined)
+        result.dimension = parseUnknownPositiveInteger(parsed.dimension, "embedding.dimension");
+    if (typeof parsed.apiKey === "string" && parsed.apiKey)
+        result.apiKey = parsed.apiKey;
+    return result;
+}
+function parseLlmConnectionValue(value) {
+    if (value === "null" || value === "")
+        return undefined;
+    const parsed = parseJsonObject(value, "llm", {
+        endpoint: "http://localhost:11434/v1/chat/completions",
+        model: "llama3.2",
+    });
+    const result = {
+        endpoint: asRequiredString(parsed.endpoint, "llm", "endpoint"),
+        model: asRequiredString(parsed.model, "llm", "model"),
+    };
+    if (typeof parsed.provider === "string" && parsed.provider)
+        result.provider = parsed.provider;
+    if (parsed.temperature !== undefined)
+        result.temperature = parseUnknownNumber(parsed.temperature, "llm.temperature");
+    if (parsed.maxTokens !== undefined)
+        result.maxTokens = parseUnknownPositiveInteger(parsed.maxTokens, "llm.maxTokens");
+    if (typeof parsed.apiKey === "string" && parsed.apiKey)
+        result.apiKey = parsed.apiKey;
+    return result;
+}
+function parseJsonObject(value, key, example) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        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 UsageError(`Invalid value for ${key}: expected a JSON object`);
+    }
+    return parsed;
+}
+function asRequiredString(value, key, field) {
+    if (typeof value !== "string" || !value) {
+        throw new UsageError(`Invalid value for ${key}: "${field}" is a required string field`);
+    }
+    return value;
+}
+function requireNonEmptyString(value, key) {
+    if (!value) {
+        throw new UsageError(`Invalid value for ${key}: expected a non-empty string`);
+    }
+    return value;
+}
+function parseUnknownNumber(value, key) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        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 UsageError(`Invalid value for ${key}: expected a positive integer`);
+    }
+    return value;
+}