akm-cli 0.5.0 → 0.6.0-rc2

package/dist/{lockfile.js → integrations/lockfile.js}

@@ -1,9 +1,35 @@
 import fs from "node:fs";
 import path from "node:path";
-import { getConfigDir } from "./config";
+import { getConfigDir } from "../core/config";
 // ── Paths ───────────────────────────────────────────────────────────────────
+const LOCKFILE_NAME = "akm.lock";
+const LEGACY_LOCKFILE_NAME = "stash.lock";
 function getLockfilePath() {
-    return path.join(getConfigDir(), "stash.lock");
+    return path.join(getConfigDir(), LOCKFILE_NAME);
+}
+function getLegacyLockfilePath() {
+    return path.join(getConfigDir(), LEGACY_LOCKFILE_NAME);
+}
+/**
+ * One-time migration: if the new `akm.lock` does not exist but the legacy
+ * `stash.lock` does, copy it across so installed-stash tracking survives the
+ * rename. Best-effort; failures are silent because the lockfile loader treats
+ * a missing file as an empty lockfile.
+ */
+function migrateLegacyLockfileIfNeeded() {
+    const newPath = getLockfilePath();
+    const legacyPath = getLegacyLockfilePath();
+    try {
+        if (fs.existsSync(newPath))
+            return;
+        if (!fs.existsSync(legacyPath))
+            return;
+        fs.mkdirSync(path.dirname(newPath), { recursive: true });
+        fs.copyFileSync(legacyPath, newPath);
+    }
+    catch {
+        /* best-effort — fall through to empty lockfile */
+    }
 }
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -74,6 +100,7 @@ function releaseLockSentinel() {
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
+    migrateLegacyLockfileIfNeeded();
     const lockfilePath = getLockfilePath();
     try {
         const raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));

package/dist/{llm.js → llm/client.js}

@@ -1,4 +1,13 @@
-import { fetchWithTimeout } from "./common";
+/**
+ * Low-level OpenAI-compatible chat completions client and capability probing.
+ *
+ * Split out of `llm.ts` to keep the transport-layer concerns (HTTP request,
+ * response parsing, JSON-fence stripping, capability probe, availability
+ * check) separate from higher-level metadata-enhancement workflows.
+ *
+ * `llm.ts` re-exports everything from this module for backward compatibility.
+ */
+import { fetchWithTimeout } from "../core/common";
 export async function chatCompletion(config, messages, options) {
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {
@@ -22,7 +31,7 @@ export async function chatCompletion(config, messages, options) {
     return json.choices?.[0]?.message?.content?.trim() ?? "";
 }
 /** Strip leading/trailing markdown code fences from an LLM response. */
-function stripJsonFences(raw) {
+export function stripJsonFences(raw) {
     return raw
         .trim()
         .replace(/^```(?:json)?\s*\n?/i, "")
@@ -38,52 +47,7 @@ export function parseJsonResponse(raw) {
         return undefined;
     }
 }
-// ── Metadata Enhancement ────────────────────────────────────────────────────
-const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
-/**
- * Use an LLM to enhance a stash entry's metadata: improve description,
- * generate searchHints, and suggest tags.
- */
-export async function enhanceMetadata(config, entry, fileContent) {
-    const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
-    if (entry.description)
-        contextParts.push(`Current description: ${entry.description}`);
-    if (entry.tags?.length)
-        contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
-    if (fileContent) {
-        // Limit content to first 2000 chars to stay within token limits
-        const truncated = fileContent.length > 2000 ? `${fileContent.slice(0, 2000)}\n... (truncated)` : fileContent;
-        contextParts.push(`File content:\n${truncated}`);
-    }
-    const userPrompt = `${contextParts.join("\n")}
-
-Generate improved metadata for this ${entry.type}. Return JSON with these fields:
-- "description": a clear, concise one-sentence description of what this does
-- "searchHints": an array of 3-6 natural language task phrases an agent might use to find this (e.g. "deploy a docker container", "run database migrations")
-- "tags": an array of 3-8 relevant keyword tags
-
-Return ONLY the JSON object, no explanation.`;
-    const raw = await chatCompletion(config, [
-        { role: "system", content: SYSTEM_PROMPT },
-        { role: "user", content: userPrompt },
-    ]);
-    const parsed = parseJsonResponse(raw);
-    if (!parsed)
-        return {};
-    const result = {};
-    if (typeof parsed.description === "string" && parsed.description) {
-        result.description = parsed.description;
-    }
-    if (Array.isArray(parsed.searchHints)) {
-        result.searchHints = parsed.searchHints
-            .filter((s) => typeof s === "string" && s.trim().length > 0)
-            .slice(0, 8);
-    }
-    if (Array.isArray(parsed.tags)) {
-        result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
-    }
-    return result;
-}
+// ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check if the LLM endpoint is reachable.
  */

package/dist/llm/embedder.js

@@ -0,0 +1,127 @@
+/**
+ * Backward-compatible facade for the embedder module.
+ *
+ * The implementation has been split into:
+ * - `./embedders/types`  — `EmbeddingVector`, `Embedder`, `EmbeddingCheckResult`
+ * - `./embedders/local`  — `LocalEmbedder`, `DEFAULT_LOCAL_MODEL`,
+ *                          `isTransformersAvailable`
+ * - `./embedders/remote` — `RemoteEmbedder`, `hasRemoteEndpoint`
+ * - `./embedders/cache`  — LRU `embedCache`, `clearEmbeddingCache`,
+ *                          `embedCacheKey`
+ *
+ * This module wires them together: it picks the right implementation from the
+ * (optional) embedding config, applies the cache layer, and re-exports the
+ * existing public API so call sites (`db-search.ts`, `indexer.ts`, `db.ts`,
+ * `setup.ts`, `semantic-status.ts`, tests) keep working unmodified.
+ *
+ * Tests can construct fresh `LocalEmbedder` / `RemoteEmbedder` instances
+ * directly from their submodules to avoid module-level state pollution.
+ */
+import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache";
+import { isTransformersAvailable, LocalEmbedder } from "./embedders/local";
+import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote";
+// ── Re-exports (public API) ─────────────────────────────────────────────────
+export { clearEmbeddingCache } from "./embedders/cache";
+export { DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedders/local";
+// ── Singleton local embedder ────────────────────────────────────────────────
+// `localEmbedder` is an intentional module-level singleton. The underlying
+// @huggingface/transformers pipeline is expensive to initialise (model download
+// + WASM compilation) and is safe to share across calls because it is
+// stateless once created. Storing it here avoids re-initialising on every
+// embed() call.
+const localEmbedder = new LocalEmbedder();
+/**
+ * Reset the cached local embedder pipeline. Used by tests that want a fresh
+ * pipeline construction (e.g. to assert the dtype-fallback retry logic).
+ */
+export function resetLocalEmbedder() {
+    localEmbedder.reset();
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Generate an embedding for the given text.
+ * If embeddingConfig has a remote endpoint, uses the configured OpenAI-compatible endpoint.
+ * Otherwise falls back to local @huggingface/transformers using the model from
+ * `embeddingConfig.localModel` or `DEFAULT_LOCAL_MODEL`.
+ *
+ * Results are cached in an LRU cache (max ~100 entries) keyed by query text
+ * and embedding config. Repeated identical queries return the cached vector.
+ */
+export async function embed(text, embeddingConfig) {
+    const key = embedCacheKey(text, embeddingConfig);
+    const cached = getCachedEmbedding(key);
+    if (cached)
+        return cached;
+    const result = embeddingConfig && hasRemoteEndpoint(embeddingConfig)
+        ? await new RemoteEmbedder(embeddingConfig).embed(text)
+        : await localEmbedder.embedWithModel(text, embeddingConfig?.localModel);
+    setCachedEmbedding(key, result);
+    return result;
+}
+/**
+ * Generate embeddings for multiple texts in batch.
+ * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
+ * Falls back to sequential embedding for the local transformer pipeline.
+ */
+export async function embedBatch(texts, embeddingConfig) {
+    if (texts.length === 0)
+        return [];
+    if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
+        return new RemoteEmbedder(embeddingConfig).embedBatch(texts);
+    }
+    // Local transformer: process sequentially (pipeline handles one at a time)
+    const localModel = embeddingConfig?.localModel;
+    const results = [];
+    for (const text of texts) {
+        results.push(await localEmbedder.embedWithModel(text, localModel));
+    }
+    return results;
+}
+// ── Similarity ──────────────────────────────────────────────────────────────
+// `cosineSimilarity` was moved to `./embedders/types.ts` so importers
+// (notably `db.ts`) can pull the math function without dragging in this
+// facade and its `@huggingface/transformers` import chain. Re-export
+// preserves the existing public API.
+export { cosineSimilarity } from "./embedders/types";
+// ── Availability check ──────────────────────────────────────────────────────
+/**
+ * Check whether embedding is available with a detailed reason on failure.
+ */
+export async function checkEmbeddingAvailability(embeddingConfig) {
+    if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
+        try {
+            await new RemoteEmbedder(embeddingConfig).embed("test");
+            return { available: true };
+        }
+        catch (err) {
+            return {
+                available: false,
+                reason: "remote-unreachable",
+                message: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    // Check if the package is importable before attempting the model download.
+    if (!isTransformersAvailable()) {
+        return {
+            available: false,
+            reason: "missing-package",
+            message: "@huggingface/transformers is not installed.",
+        };
+    }
+    try {
+        await localEmbedder.getPipeline(embeddingConfig?.localModel);
+        return { available: true };
+    }
+    catch (err) {
+        return {
+            available: false,
+            reason: "model-download-failed",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export async function isEmbeddingAvailable(embeddingConfig) {
+    const result = await checkEmbeddingAvailability(embeddingConfig);
+    return result.available;
+}

package/dist/llm/embedders/cache.js

@@ -0,0 +1,47 @@
+/**
+ * LRU embedding cache shared by the embedder facade.
+ *
+ * Caches query embeddings to avoid redundant computation for repeated
+ * queries. Uses a simple Map with LRU eviction (delete + re-insert to move
+ * an entry to the most-recently-used end).
+ */
+const EMBED_CACHE_MAX = 100;
+const embedCache = new Map();
+/**
+ * Build a cache key from query text and optional config.
+ * Different endpoints/models should not share cached embeddings.
+ * apiKey deliberately excluded: same endpoint+model produce identical embeddings regardless of auth.
+ */
+export function embedCacheKey(text, config) {
+    if (!config)
+        return `local::${text}`;
+    const endpoint = config.endpoint || "";
+    const model = config.model || config.localModel || "";
+    return `${endpoint}:${model}:${text}`;
+}
+export function getCachedEmbedding(key) {
+    const cached = embedCache.get(key);
+    if (cached === undefined)
+        return undefined;
+    // Move to end (most recently used) for LRU ordering
+    embedCache.delete(key);
+    embedCache.set(key, cached);
+    return cached;
+}
+export function setCachedEmbedding(key, value) {
+    // Evict oldest entry if at capacity
+    if (embedCache.size >= EMBED_CACHE_MAX) {
+        const oldest = embedCache.keys().next().value;
+        if (oldest !== undefined) {
+            embedCache.delete(oldest);
+        }
+    }
+    embedCache.set(key, value);
+}
+/**
+ * Clear the embedding cache. Call when the embedding model changes
+ * or when you want to force fresh embeddings.
+ */
+export function clearEmbeddingCache() {
+    embedCache.clear();
+}

package/dist/llm/embedders/local.js

@@ -0,0 +1,152 @@
+/**
+ * Local @huggingface/transformers embedder.
+ *
+ * Encapsulates the transformer pipeline lifecycle as instance state on a
+ * `LocalEmbedder` so tests can construct fresh instances without leaking
+ * pipelines across tests. The facade in `../embedder.ts` keeps a single
+ * shared instance for the production code path.
+ */
+import path from "node:path";
+import { getCacheDir } from "../../core/paths";
+import { warn } from "../../core/warn";
+/**
+ * Default local transformer model for embeddings.
+ * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous
+ * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
+ */
+export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
+const LOCAL_EMBEDDER_DTYPE = "fp32";
+const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
+/**
+ * Return the local model name that will be used for embedding.
+ * When `overrideModel` is provided it takes precedence; otherwise
+ * the default model is returned.
+ */
+function resolveLocalModelName(overrideModel) {
+    return overrideModel || DEFAULT_LOCAL_MODEL;
+}
+export class LocalEmbedder {
+    defaultModel;
+    /**
+     * Cache the *promise* (not the resolved result) so concurrent calls share
+     * the same initialisation work and never download the model twice. Keyed
+     * by model name so switching models gets a fresh pipeline.
+     */
+    pipelinePromise;
+    pipelineModelName;
+    constructor(defaultModel) {
+        this.defaultModel = defaultModel;
+    }
+    /** Reset the cached pipeline (used by tests and by `resetLocalEmbedder()`). */
+    reset() {
+        this.pipelinePromise = undefined;
+        this.pipelineModelName = undefined;
+    }
+    async embed(text) {
+        return this.embedWithModel(text, this.defaultModel);
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const results = [];
+        for (const text of texts) {
+            results.push(await this.embedWithModel(text, this.defaultModel));
+        }
+        return results;
+    }
+    /** Embed using a model name override (used by the facade for per-call model overrides). */
+    async embedWithModel(text, modelName) {
+        const pipeline = await this.getPipeline(modelName);
+        const result = await pipeline(text, { pooling: "mean", normalize: true });
+        return Array.from(result.data);
+    }
+    /**
+     * Eagerly load (or return the cached) underlying pipeline. Used by
+     * availability checks that want to surface model-download failures
+     * without performing a real embed call.
+     */
+    async getPipeline(modelName) {
+        const resolvedModel = resolveLocalModelName(modelName);
+        if (this.pipelinePromise && this.pipelineModelName !== resolvedModel) {
+            this.pipelinePromise = undefined;
+            this.pipelineModelName = undefined;
+        }
+        if (!this.pipelinePromise) {
+            this.pipelineModelName = resolvedModel;
+            this.pipelinePromise = (async () => {
+                // Ensure HuggingFace model cache lives in a stable location outside
+                // node_modules so it survives package reinstalls.
+                if (!process.env.HF_HOME) {
+                    process.env.HF_HOME = path.join(getCacheDir(), "models");
+                }
+                let pipeline;
+                try {
+                    const mod = await import("@huggingface/transformers");
+                    pipeline = mod.pipeline;
+                }
+                catch (importError) {
+                    const msg = importError instanceof Error ? importError.message : String(importError);
+                    if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
+                        throw new Error("Semantic search requires @huggingface/transformers. Install it with: bun add @huggingface/transformers");
+                    }
+                    throw new Error(`Failed to load embedding runtime: ${msg}. Check platform compatibility.`);
+                }
+                const pipelineFn = pipeline;
+                return createLocalPipeline(pipelineFn, resolvedModel);
+            })();
+            // HI-13: Clear the cached promise on failure so the next call retries
+            // instead of permanently rejecting every subsequent call with the same error.
+            this.pipelinePromise.catch(() => {
+                this.pipelinePromise = undefined;
+                this.pipelineModelName = undefined;
+            });
+        }
+        return this.pipelinePromise;
+    }
+}
+async function createLocalPipeline(pipelineFn, modelName) {
+    try {
+        return await pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_DTYPE });
+    }
+    catch (error) {
+        if (!shouldRetryWithoutExplicitDtype(error)) {
+            throw error;
+        }
+        warn('Local embedding model "%s" rejected explicit dtype "%s"; retrying with explicit fallback dtype "%s".', modelName, LOCAL_EMBEDDER_DTYPE, LOCAL_EMBEDDER_FALLBACK_DTYPE);
+        return pipelineFn("feature-extraction", modelName, { dtype: LOCAL_EMBEDDER_FALLBACK_DTYPE });
+    }
+}
+function shouldRetryWithoutExplicitDtype(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /dtype|fp32|precision|quant/i.test(message);
+}
+/**
+ * Check whether the `@huggingface/transformers` package can be resolved.
+ * Uses `Bun.resolveSync` so we never load the module (which would trigger
+ * heavy WASM/model side-effects) just to test availability.
+ *
+ * Falls back to `require.resolve` when `Bun.resolveSync` is unavailable
+ * (e.g. running under Node), so the function still works in mixed runtimes.
+ */
+export function isTransformersAvailable() {
+    try {
+        if (typeof Bun !== "undefined" && typeof Bun.resolveSync === "function") {
+            Bun.resolveSync("@huggingface/transformers", import.meta.dir);
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    try {
+        const req = globalThis.require;
+        if (req && typeof req.resolve === "function") {
+            req.resolve("@huggingface/transformers");
+            return true;
+        }
+    }
+    catch {
+        return false;
+    }
+    return false;
+}

package/dist/llm/embedders/remote.js

@@ -0,0 +1,121 @@
+/**
+ * OpenAI-compatible remote embedder.
+ *
+ * Calls the configured `/embeddings` endpoint and L2-normalizes the returned
+ * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
+ */
+import { fetchWithTimeout, isHttpUrl } from "../../core/common";
+const REMOTE_BATCH_SIZE = 100;
+export class RemoteEmbedder {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async embed(text) {
+        const headers = this.buildHeaders();
+        const body = {
+            input: text,
+            model: this.config.model,
+        };
+        if (this.config.dimension) {
+            body.dimensions = this.config.dimension;
+        }
+        const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errBody = await response.text().catch(() => "");
+            throw new Error(`Embedding request failed (${response.status}): ${errBody}`);
+        }
+        const json = (await response.json());
+        if (!json.data?.[0]?.embedding) {
+            throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(this.config.endpoint)}`);
+        }
+        return l2Normalize(json.data[0].embedding);
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const results = [];
+        const headers = this.buildHeaders();
+        for (let i = 0; i < texts.length; i += REMOTE_BATCH_SIZE) {
+            const batch = texts.slice(i, i + REMOTE_BATCH_SIZE);
+            const body = {
+                input: batch,
+                model: this.config.model,
+            };
+            if (this.config.dimension) {
+                body.dimensions = this.config.dimension;
+            }
+            const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const respBody = await response.text().catch(() => "");
+                throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
+            }
+            const json = (await response.json());
+            if (!json.data || json.data.length !== batch.length) {
+                throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(this.config.endpoint)}`);
+            }
+            // Sort by index to guarantee correct order (OpenAI API doesn't guarantee order)
+            const sorted = [...json.data].sort((a, b) => a.index - b.index);
+            for (const [idx, d] of sorted.entries()) {
+                if (!Array.isArray(d.embedding)) {
+                    throw new Error(`Unexpected embedding at batch index ${idx}: missing or invalid`);
+                }
+                results.push(l2Normalize(d.embedding));
+            }
+        }
+        return results;
+    }
+    buildHeaders() {
+        const headers = { "Content-Type": "application/json" };
+        if (this.config.apiKey) {
+            headers.Authorization = `Bearer ${this.config.apiKey}`;
+        }
+        return headers;
+    }
+}
+/**
+ * L2-normalize a vector to unit length.
+ * Required for remote embeddings because the scoring pipeline's L2-to-cosine
+ * conversion formula (1 - distance^2/2) is only correct for unit vectors.
+ * The local embedder already normalizes via `normalize: true`.
+ */
+function l2Normalize(vec) {
+    const norm = Math.sqrt(vec.reduce((sum, v) => sum + v * v, 0));
+    if (norm === 0)
+        return vec;
+    return vec.map((v) => v / norm);
+}
+export function normalizeEmbeddingEndpoint(endpoint) {
+    let parsed;
+    try {
+        parsed = new URL(endpoint);
+    }
+    catch {
+        return endpoint;
+    }
+    const normalizedPath = parsed.pathname.replace(/\/+$/, "");
+    if (normalizedPath.endsWith("/embeddings")) {
+        return parsed.toString();
+    }
+    parsed.pathname = normalizedPath ? `${normalizedPath}/embeddings` : "/embeddings";
+    return parsed.toString();
+}
+function embeddingEndpointPathHint(endpoint) {
+    const normalizedEndpoint = normalizeEmbeddingEndpoint(endpoint);
+    if (normalizedEndpoint !== endpoint) {
+        return ` Check that your endpoint includes the full embeddings path (for example "${normalizedEndpoint}", not just "${endpoint}").`;
+    }
+    return "";
+}
+/** Check whether an EmbeddingConnectionConfig has a valid remote endpoint. */
+export function hasRemoteEndpoint(config) {
+    return isHttpUrl(config.endpoint);
+}

package/dist/llm/embedders/types.js

@@ -0,0 +1,39 @@
+/**
+ * Shared embedder types.
+ *
+ * Pulled out of `embedder.ts` so concrete implementations (`local.ts`,
+ * `remote.ts`) and the cache layer can depend on a small, stable types
+ * module without dragging in the facade or a sibling implementation.
+ */
+/**
+ * Cosine similarity between two embedding vectors.
+ *
+ * Lives next to {@link EmbeddingVector} so importers (notably `db.ts`)
+ * can pull just the math without dragging in the embedder facade and its
+ * transitive `@huggingface/transformers` import chain.
+ *
+ * Returns 0 when the vectors have different dimensions — silently
+ * computing on a truncated view would produce meaningless scores.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        warn("cosineSimilarity: vector dimension mismatch (%d vs %d) — re-index recommended", a.length, b.length);
+        return 0;
+    }
+    const len = a.length;
+    if (len === 0)
+        return 0;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}
+// Imported lazily to keep this types module dependency-free where possible;
+// `warn` is a thin printf wrapper so the cost is negligible.
+import { warn } from "../../core/warn";

package/dist/llm/metadata-enhance.js

@@ -0,0 +1,53 @@
+/**
+ * LLM-driven metadata enhancement for stash entries.
+ *
+ * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
+ * improve descriptions/tags/searchHints) lives separately from the low-level
+ * transport client in `client.ts`.
+ */
+import { chatCompletion, parseJsonResponse } from "./client";
+const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
+/**
+ * Use an LLM to enhance a stash entry's metadata: improve description,
+ * generate searchHints, and suggest tags.
+ */
+export async function enhanceMetadata(config, entry, fileContent) {
+    const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
+    if (entry.description)
+        contextParts.push(`Current description: ${entry.description}`);
+    if (entry.tags?.length)
+        contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
+    if (fileContent) {
+        // Limit content to first 2000 chars to stay within token limits
+        const truncated = fileContent.length > 2000 ? `${fileContent.slice(0, 2000)}\n... (truncated)` : fileContent;
+        contextParts.push(`File content:\n${truncated}`);
+    }
+    const userPrompt = `${contextParts.join("\n")}
+
+Generate improved metadata for this ${entry.type}. Return JSON with these fields:
+- "description": a clear, concise one-sentence description of what this does
+- "searchHints": an array of 3-6 natural language task phrases an agent might use to find this (e.g. "deploy a docker container", "run database migrations")
+- "tags": an array of 3-8 relevant keyword tags
+
+Return ONLY the JSON object, no explanation.`;
+    const raw = await chatCompletion(config, [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: userPrompt },
+    ]);
+    const parsed = parseJsonResponse(raw);
+    if (!parsed)
+        return {};
+    const result = {};
+    if (typeof parsed.description === "string" && parsed.description) {
+        result.description = parsed.description;
+    }
+    if (Array.isArray(parsed.searchHints)) {
+        result.searchHints = parsed.searchHints
+            .filter((s) => typeof s === "string" && s.trim().length > 0)
+            .slice(0, 8);
+    }
+    if (Array.isArray(parsed.tags)) {
+        result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+    }
+    return result;
+}