akm-cli 0.0.20 → 0.0.22

package/dist/stash-add.js

@@ -1,15 +1,77 @@
 import fs from "node:fs";
+import path from "node:path";
 import { resolveStashDir } from "./common";
-import { loadConfig } from "./config";
+import { loadConfig, saveConfig } from "./config";
 import { UsageError } from "./errors";
 import { agentikitIndex } from "./indexer";
 import { upsertLockEntry } from "./lockfile";
-import { installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
+import { detectStashRoot, installRegistryRef, upsertInstalledRegistryEntry } from "./registry-install";
+import { parseRegistryRef } from "./registry-resolve";
 export async function agentikitAdd(input) {
     const ref = input.ref.trim();
     if (!ref)
         throw new UsageError("Install ref or local directory is required.");
     const stashDir = resolveStashDir();
+    // Detect local directory refs and route them to stashes[] instead of installed[]
+    try {
+        const parsed = parseRegistryRef(ref);
+        if (parsed.source === "local") {
+            return addLocalStashSource(ref, parsed.sourcePath, stashDir);
+        }
+    }
+    catch {
+        // Not a local ref — fall through to registry install
+    }
+    return addRegistryKit(ref, stashDir);
+}
+/**
+ * Add a local directory as a filesystem stash source.
+ * Creates a stashes[] entry instead of an installed[] entry.
+ */
+async function addLocalStashSource(ref, sourcePath, stashDir) {
+    const stashRoot = detectStashRoot(sourcePath);
+    const resolvedPath = path.resolve(stashRoot);
+    const config = loadConfig();
+    // Check for duplicates in stashes[]
+    const stashes = [...(config.stashes ?? [])];
+    const existing = stashes.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
+    if (!existing) {
+        const entry = {
+            type: "filesystem",
+            path: resolvedPath,
+            name: toReadableId(resolvedPath),
+        };
+        stashes.push(entry);
+        saveConfig({ ...config, stashes });
+    }
+    const index = await agentikitIndex({ stashDir });
+    const updatedConfig = loadConfig();
+    return {
+        schemaVersion: 1,
+        stashDir,
+        ref,
+        stashSource: {
+            type: "filesystem",
+            path: resolvedPath,
+            name: toReadableId(resolvedPath),
+            stashRoot: resolvedPath,
+        },
+        config: {
+            searchPaths: updatedConfig.searchPaths,
+            installedKitCount: updatedConfig.installed?.length ?? 0,
+        },
+        index: {
+            mode: index.mode,
+            totalEntries: index.totalEntries,
+            directoriesScanned: index.directoriesScanned,
+            directoriesSkipped: index.directoriesSkipped,
+        },
+    };
+}
+/**
+ * Install a kit from a registry (npm, github, git).
+ */
+async function addRegistryKit(ref, stashDir) {
     const installed = await installRegistryRef(ref);
     const replaced = (loadConfig().installed ?? []).find((entry) => entry.id === installed.id);
     const config = upsertInstalledRegistryEntry({
@@ -23,16 +85,16 @@ export async function agentikitAdd(input) {
         cacheDir: installed.cacheDir,
         installedAt: installed.installedAt,
     });
-    upsertLockEntry({
+    await upsertLockEntry({
         id: installed.id,
         source: installed.source,
         ref: installed.ref,
         resolvedVersion: installed.resolvedVersion,
         resolvedRevision: installed.resolvedRevision,
-        integrity: installed.integrity ?? (installed.source === "local" ? "local" : undefined),
+        integrity: installed.integrity,
     });
-    // Clean up old cache directory on re-install (skip for local sources — no cache to clean)
-    if (replaced && replaced.source !== "local" && replaced.cacheDir !== installed.cacheDir) {
+    // Clean up old cache directory on re-install
+    if (replaced && replaced.cacheDir !== installed.cacheDir) {
         try {
             fs.rmSync(replaced.cacheDir, { recursive: true, force: true });
         }
@@ -69,3 +131,10 @@ export async function agentikitAdd(input) {
         },
     };
 }
+function toReadableId(resolvedPath) {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (home && resolvedPath.startsWith(home + path.sep)) {
+        return `~${resolvedPath.slice(home.length)}`;
+    }
+    return resolvedPath;
+}

package/dist/stash-clone.js

@@ -47,7 +47,7 @@ export async function agentikitClone(options) {
     let lastError;
     for (const source of searchSources) {
         try {
-            sourcePath = resolveAssetPath(source.path, parsed.type, parsed.name);
+            sourcePath = await resolveAssetPath(source.path, parsed.type, parsed.name);
             break;
         }
         catch (err) {

package/dist/stash-provider-factory.js

@@ -0,0 +1,52 @@
+/**
+ * Stash provider factory map.
+ *
+ * Maps stash source type identifiers (e.g. "filesystem", "openviking") to
+ * factory functions that create StashProvider instances from a StashConfigEntry.
+ *
+ * "Stash providers" are runtime data sources for the search and show commands —
+ * distinct from the kit-discovery registries (registry-factory.ts) and the
+ * installed-kit operations (installed-kits.ts).
+ */
+import { createProviderRegistry } from "./create-provider-registry";
+// ── Factory map ─────────────────────────────────────────────────────────────
+const registry = createProviderRegistry();
+export function registerStashProvider(type, factory) {
+    registry.register(type, factory);
+}
+export function resolveStashProviderFactory(type) {
+    return registry.resolve(type);
+}
+/**
+ * Resolve all non-filesystem stash providers from config.
+ * Sources come from `stashes` (new) or `remoteStashSources` (legacy).
+ * Filesystem entries are excluded — they are handled by resolveStashSources().
+ */
+export function resolveStashProviders(config) {
+    const providers = [];
+    // New config: stashes[]
+    if (config.stashes) {
+        for (const entry of config.stashes) {
+            if (entry.enabled === false)
+                continue;
+            if (entry.type === "filesystem")
+                continue;
+            const factory = registry.resolve(entry.type);
+            if (factory) {
+                providers.push(factory(entry));
+            }
+        }
+    }
+    // Legacy config: remoteStashSources[] → map to stash providers
+    if (!config.stashes && config.remoteStashSources) {
+        for (const entry of config.remoteStashSources) {
+            if (entry.enabled === false)
+                continue;
+            const factory = registry.resolve(entry.type ?? "openviking");
+            if (factory) {
+                providers.push(factory(entry));
+            }
+        }
+    }
+    return providers;
+}

package/dist/stash-provider.js

@@ -0,0 +1 @@
+export {};

package/dist/stash-providers/filesystem.js

@@ -0,0 +1,42 @@
+import { resolveStashDir } from "../common";
+import { loadConfig } from "../config";
+import { searchLocal } from "../local-search";
+import { registerStashProvider } from "../stash-provider-factory";
+import { showLocal } from "../stash-show";
+import { resolveStashSources } from "../stash-source";
+class FilesystemStashProvider {
+    type = "filesystem";
+    name;
+    stashDir;
+    config;
+    constructor(entry) {
+        this.config = loadConfig();
+        this.stashDir = entry.path ?? resolveStashDir();
+        this.name = entry.name ?? this.stashDir;
+    }
+    async search(options) {
+        const sources = resolveStashSources(this.stashDir, this.config);
+        const result = await searchLocal({
+            query: options.query.toLowerCase(),
+            searchType: options.type ?? "any",
+            limit: options.limit,
+            stashDir: this.stashDir,
+            sources,
+            config: this.config,
+        });
+        return {
+            hits: result.hits,
+            warnings: result.warnings,
+            embedMs: result.embedMs,
+            rankMs: result.rankMs,
+        };
+    }
+    async show(ref, view) {
+        return showLocal({ ref, view });
+    }
+    canShow(ref) {
+        return !ref.trim().startsWith("viking://");
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerStashProvider("filesystem", (config) => new FilesystemStashProvider(config));

package/dist/stash-providers/index.js

@@ -0,0 +1,9 @@
+/**
+ * Centralized stash provider registration.
+ *
+ * Import this module (side-effect import) to register all built-in stash
+ * providers with the provider registry. This replaces the individual
+ * side-effect imports that were duplicated in stash-search.ts and stash-show.ts.
+ */
+import "./filesystem";
+import "./openviking";

package/dist/stash-providers/openviking.js

@@ -0,0 +1,337 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fetchWithRetry } from "../common";
+import { ConfigError, NotFoundError } from "../errors";
+import { getRegistryIndexCacheDir } from "../paths";
+import { registerStashProvider } from "../stash-provider-factory";
+/** Strip terminal control characters from untrusted strings. */
+function sanitizeString(value, maxLength = 255) {
+    if (typeof value !== "string")
+        return "";
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — strip control chars from untrusted remote data
+    return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, maxLength);
+}
+/** Per-query cache TTL in milliseconds (5 minutes). */
+const QUERY_CACHE_TTL_MS = 5 * 60 * 1000;
+/** Maximum age before query cache is considered stale but still usable (1 hour). */
+const QUERY_CACHE_STALE_MS = 60 * 60 * 1000;
+/**
+ * Single source of truth for OpenViking type → agentikit asset type mapping.
+ * Used by both search hit mapping and show response mapping.
+ */
+const OV_TYPE_MAP = {
+    skill: "skill",
+    skills: "skill",
+    memory: "memory",
+    memories: "memory",
+    resource: "knowledge",
+    resources: "knowledge",
+    knowledge: "knowledge",
+    agent: "agent",
+    agents: "agent",
+    command: "command",
+    commands: "command",
+    script: "script",
+    scripts: "script",
+};
+class OpenVikingStashProvider {
+    type = "openviking";
+    name;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.name = config.name ?? "openviking";
+        // Validate baseUrl scheme to prevent SSRF via file:// or other non-HTTP schemes
+        const rawUrl = config.url ?? "";
+        if (rawUrl) {
+            try {
+                const parsed = new URL(rawUrl);
+                if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                    throw new ConfigError(`OpenViking baseUrl must use http:// or https://, got "${parsed.protocol}" in "${rawUrl}"`);
+                }
+            }
+            catch (err) {
+                if (err instanceof ConfigError)
+                    throw err;
+                throw new ConfigError(`OpenViking baseUrl is not a valid URL: "${rawUrl}"`);
+            }
+        }
+    }
+    async search(options) {
+        try {
+            const entries = await this.fetchResults(options.query, options.limit);
+            const limited = entries.slice(0, options.limit);
+            const hits = this.mapToStashHits(limited);
+            return { hits };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { hits: [], warnings: [`Stash ${this.name}: ${message}`] };
+        }
+    }
+    async show(ref, _view) {
+        const uri = ref.trim();
+        const baseUrl = this.baseUrl;
+        const headers = this.authHeaders;
+        const [statResult, contentResult] = await Promise.all([
+            fetchOVJson(`${baseUrl}/api/v1/fs/stat?uri=${encodeURIComponent(uri)}`, headers),
+            fetchOVJson(`${baseUrl}/api/v1/content/read?uri=${encodeURIComponent(uri)}&offset=0&limit=-1`, headers),
+        ]);
+        if (statResult == null && contentResult == null) {
+            throw new NotFoundError(`Could not fetch remote asset "${uri}". The OpenViking server at ${baseUrl} may be unreachable or the resource does not exist.`);
+        }
+        if (contentResult == null) {
+            throw new NotFoundError(`Content not found for remote asset "${uri}". The server returned metadata but no content.`);
+        }
+        const stat = (typeof statResult === "object" && statResult !== null ? statResult : {});
+        const uriPath = uri.replace(/^viking:\/\//, "");
+        // Sanitize untrusted fields to strip terminal control characters
+        const name = sanitizeString(stat.name) || uriPath.split("/").pop() || "unknown";
+        const ovType = sanitizeString(stat.type) || inferTypeFromUri(uri);
+        const assetType = OV_TYPE_MAP[ovType] ?? "knowledge";
+        const content = typeof contentResult === "string" ? contentResult : "";
+        const description = sanitizeString(stat.abstract, 1000) || undefined;
+        return {
+            type: assetType,
+            name,
+            path: uri,
+            action: `Remote content from OpenViking — ${uri}`,
+            content,
+            description,
+            editable: false,
+            origin: "remote",
+        };
+    }
+    canShow(ref) {
+        return ref.trim().startsWith("viking://");
+    }
+    get baseUrl() {
+        return (this.config.url ?? "").replace(/\/+$/, "");
+    }
+    get authHeaders() {
+        const headers = {};
+        const apiKey = this.config.options?.apiKey ?? undefined;
+        if (apiKey)
+            headers.Authorization = `Bearer ${apiKey}`;
+        return headers;
+    }
+    async fetchResults(query, limit) {
+        const cachePath = this.queryCachePath(query, limit);
+        const cached = this.readQueryCache(cachePath);
+        if (cached && !isExpired(cached.mtime, QUERY_CACHE_TTL_MS)) {
+            return cached.entries;
+        }
+        const baseUrl = this.baseUrl;
+        const searchType = this.config.options?.searchType ?? "semantic";
+        try {
+            let url;
+            let body;
+            if (searchType === "text") {
+                url = `${baseUrl}/api/v1/search/grep`;
+                body = JSON.stringify({ uri: "viking://", pattern: query, case_insensitive: true });
+            }
+            else {
+                url = `${baseUrl}/api/v1/search/find`;
+                body = JSON.stringify({ query, limit });
+            }
+            const headers = { "Content-Type": "application/json", ...this.authHeaders };
+            const response = await fetchWithRetry(url, { method: "POST", headers, body }, { timeout: 10_000, retries: 1 });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const data = (await response.json());
+            if (data.status !== "ok") {
+                throw new Error(data.error ?? "OpenViking returned error status");
+            }
+            const entries = parseOVSearchResponse(data.result);
+            this.writeQueryCache(cachePath, entries);
+            return entries;
+        }
+        catch (err) {
+            if (cached && !isExpired(cached.mtime, QUERY_CACHE_STALE_MS)) {
+                return cached.entries;
+            }
+            throw err;
+        }
+    }
+    mapToStashHits(entries) {
+        if (entries.length === 0)
+            return [];
+        const maxScore = entries.reduce((max, e) => Math.max(max, e.score), 0.01);
+        return entries.map((entry) => {
+            const name = sanitizeString(entry.name);
+            const abstract = sanitizeString(entry.abstract, 1000);
+            const type = sanitizeString(entry.type);
+            const uri = sanitizeString(entry.uri, 2048);
+            const assetType = OV_TYPE_MAP[type] ?? "knowledge";
+            const ref = uriToVikingRef(uri);
+            return {
+                type: assetType,
+                name,
+                path: ref,
+                ref,
+                origin: this.type,
+                editable: false,
+                description: abstract || undefined,
+                action: `akm show ${ref}`,
+                score: Math.round((entry.score / maxScore) * 1000) / 1000,
+            };
+        });
+    }
+    queryCachePath(query, limit) {
+        const cacheDir = getRegistryIndexCacheDir();
+        const hasher = new Bun.CryptoHasher("md5");
+        hasher.update(this.config.url ?? "");
+        hasher.update("\0");
+        hasher.update(query.trim().toLowerCase());
+        hasher.update("\0");
+        hasher.update(String(limit));
+        hasher.update("\0");
+        const searchType = this.config.options?.searchType ?? "semantic";
+        hasher.update(searchType);
+        hasher.update("\0");
+        const apiKey = this.config.options?.apiKey ?? "";
+        hasher.update(apiKey);
+        const hash = hasher.digest("hex");
+        return path.join(cacheDir, `openviking-search-${hash}.json`);
+    }
+    readQueryCache(cachePath) {
+        try {
+            const stat = fs.statSync(cachePath);
+            const raw = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+            if (!Array.isArray(raw))
+                return null;
+            const entries = raw.filter(isValidOVEntry);
+            return { entries, mtime: stat.mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    }
+    writeQueryCache(cachePath, entries) {
+        try {
+            const dir = path.dirname(cachePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${cachePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+            // 0o600: owner read/write only — cache may contain search terms tied to API keys
+            fs.writeFileSync(tmpPath, JSON.stringify(entries), { encoding: "utf8", mode: 0o600 });
+            fs.renameSync(tmpPath, cachePath);
+        }
+        catch {
+            // Best-effort caching
+        }
+    }
+}
+// ── Self-register ───────────────────────────────────────────────────────────
+registerStashProvider("openviking", (config) => new OpenVikingStashProvider(config));
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function uriToVikingRef(uri) {
+    if (uri.startsWith("viking://"))
+        return uri;
+    return `viking://${uri.replace(/^\/+/, "")}`;
+}
+function parseOVSearchResponse(result) {
+    if (Array.isArray(result))
+        return result.filter(isValidOVEntry);
+    if (typeof result !== "object" || result === null)
+        return [];
+    const grouped = result;
+    if (Array.isArray(grouped.matches)) {
+        return deduplicateGrepMatches(grouped.matches);
+    }
+    const entries = [];
+    for (const [category, items] of Object.entries(grouped)) {
+        if (category === "total")
+            continue;
+        if (!Array.isArray(items))
+            continue;
+        for (const item of items) {
+            if (!isValidOVSearchItem(item))
+                continue;
+            entries.push({
+                uri: item.uri,
+                name: extractNameFromUri(item.uri),
+                score: item.score,
+                type: item.context_type ?? category,
+                abstract: item.abstract ?? undefined,
+            });
+        }
+    }
+    return entries;
+}
+function isValidGrepMatch(item) {
+    if (typeof item !== "object" || item === null)
+        return false;
+    const obj = item;
+    return typeof obj.uri === "string" && typeof obj.content === "string";
+}
+function deduplicateGrepMatches(matches) {
+    const byUri = new Map();
+    for (const m of matches) {
+        if (!isValidGrepMatch(m))
+            continue;
+        const existing = byUri.get(m.uri);
+        if (existing) {
+            existing.count++;
+        }
+        else {
+            const pathSegment = m.uri.replace(/^viking:\/\//, "").split("/")[0] ?? "";
+            byUri.set(m.uri, { content: m.content, count: 1, type: pathSegment });
+        }
+    }
+    const maxCount = Math.max(...[...byUri.values()].map((v) => v.count), 1);
+    const entries = [];
+    for (const [uri, { content, count, type }] of byUri) {
+        entries.push({
+            uri,
+            name: extractNameFromUri(uri),
+            score: count / maxCount,
+            type,
+            abstract: content.slice(0, 200),
+        });
+    }
+    entries.sort((a, b) => b.score - a.score);
+    return entries;
+}
+function isValidOVEntry(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+        return false;
+    const obj = entry;
+    return typeof obj.uri === "string" && typeof obj.name === "string" && typeof obj.score === "number";
+}
+function isValidOVSearchItem(item) {
+    if (typeof item !== "object" || item === null || Array.isArray(item))
+        return false;
+    const obj = item;
+    return typeof obj.uri === "string" && typeof obj.score === "number";
+}
+function extractNameFromUri(uri) {
+    const uriPath = uri.replace(/^viking:\/\//, "");
+    const segments = uriPath.split("/").filter(Boolean);
+    const last = segments[segments.length - 1] ?? "unknown";
+    return last.replace(/\.[^.]+$/, "");
+}
+function isExpired(mtimeMs, ttlMs) {
+    return Date.now() - mtimeMs > ttlMs;
+}
+async function fetchOVJson(url, headers) {
+    try {
+        const response = await fetchWithRetry(url, { headers }, { timeout: 10_000, retries: 1 });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        if (data.status !== "ok")
+            return null;
+        return data.result ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function inferTypeFromUri(uri) {
+    const uriPath = uri.replace(/^viking:\/\//, "");
+    const firstSegment = uriPath.split("/")[0] ?? "";
+    return OV_TYPE_MAP[firstSegment] ?? "knowledge";
+}
+// ── Exports for testing ─────────────────────────────────────────────────────
+export { OpenVikingStashProvider, uriToVikingRef, parseOVSearchResponse };

package/dist/stash-resolve.js

@@ -1,13 +1,25 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS } from "./asset-spec";
+import { deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, resolveAssetPathFromName, TYPE_DIRS, } from "./asset-spec";
 import { hasErrnoCode, isWithin } from "./common";
 import { NotFoundError, UsageError } from "./errors";
+import { runMatchers } from "./file-context";
+import { walkStashFlat } from "./walker";
 /**
  * Resolve an asset path from a stash directory, type, and name.
  */
-export function resolveAssetPath(stashDir, type, name) {
-    return resolveInTypeDir(stashDir, TYPE_DIRS[type], type, name);
+export async function resolveAssetPath(stashDir, type, name) {
+    try {
+        return resolveInTypeDir(stashDir, TYPE_DIRS[type], type, name);
+    }
+    catch (error) {
+        if (!(error instanceof NotFoundError))
+            throw error;
+        const fallback = await resolveByCanonicalName(stashDir, type, name);
+        if (fallback)
+            return fallback;
+        throw error;
+    }
 }
 /**
  * Try to resolve an asset path within a specific type directory.
@@ -53,3 +65,21 @@ function readTypeRootStat(root, type, name) {
         throw error;
     }
 }
+async function resolveByCanonicalName(stashDir, type, name) {
+    const normalizedName = name.replace(/\\/g, "/");
+    for (const ctx of walkStashFlat(stashDir)) {
+        const match = await runMatchers(ctx);
+        if (!match || match.type !== type)
+            continue;
+        const canonicalName = deriveCanonicalAssetNameFromStashRoot(type, stashDir, ctx.absPath);
+        if (canonicalName !== normalizedName)
+            continue;
+        const realTarget = fs.realpathSync(ctx.absPath);
+        const resolvedRoot = fs.realpathSync(stashDir);
+        if (!isWithin(realTarget, resolvedRoot)) {
+            throw new UsageError("Ref resolves outside the stash root.");
+        }
+        return realTarget;
+    }
+    return undefined;
+}