akm-cli 0.5.0 → 0.6.0-rc1

package/dist/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 "../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/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 "../warn";

package/dist/errors.js

@@ -4,30 +4,41 @@
  * - ConfigError  -> exit 78  (configuration / environment problems)
  * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
  * - NotFoundError -> exit 1  (requested resource missing)
+ *
+ * Each error carries a machine-readable `code` field. Codes are stable
+ * identifiers safe to consume from scripts and JSON output. Existing throw
+ * sites without an explicit code receive a default code per error class so
+ * older call sites continue to compile and behave unchanged.
  */
 /** Raised when configuration or environment is invalid or missing. */
 export class ConfigError extends Error {
-    constructor(msg) {
+    code;
+    constructor(msg, code = "INVALID_CONFIG_FILE") {
         super(msg);
         this.name = "ConfigError";
+        this.code = code;
         // Fixes `instanceof` checks under ES5 transpilation targets.
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 /** Raised when the user supplies invalid arguments or input. */
 export class UsageError extends Error {
-    constructor(msg) {
+    code;
+    constructor(msg, code = "INVALID_FLAG_VALUE") {
         super(msg);
         this.name = "UsageError";
+        this.code = code;
         // Fixes `instanceof` checks under ES5 transpilation targets.
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 /** Raised when a requested resource (asset, entry, file) is not found. */
 export class NotFoundError extends Error {
-    constructor(msg) {
+    code;
+    constructor(msg, code = "ASSET_NOT_FOUND") {
         super(msg);
         this.name = "NotFoundError";
+        this.code = code;
         // Fixes `instanceof` checks under ES5 transpilation targets.
         Object.setPrototypeOf(this, new.target.prototype);
     }

package/dist/frontmatter.js

@@ -11,10 +11,8 @@
  *
  * **Limitations**: This is a hand-rolled YAML-subset parser with intentional
  * constraints for simplicity and safety:
- * - **No list support**: YAML block sequences (`- item`) and flow arrays
- *   (`[a, b, c]`) are silently ignored. List-valued frontmatter keys will
- *   produce an empty string or be skipped. Callers must NOT rely on list-
- *   valued frontmatter.
+ * - **List support**: YAML block sequences (`- item`) and flow arrays
+ *   (`[a, b, c]`) are both supported for top-level list-valued keys.
  * - **No nested objects beyond one level**: Only a single level of indented
  *   key-value pairs is supported.
  * - **Scalar values only**: string, boolean, and number scalars are supported.
@@ -26,28 +24,75 @@ export function parseFrontmatter(raw) {
     }
     const data = {};
     let currentKey = null;
+    /** "scalar" | "list" | "object" | "pending" — "pending" means empty value, mode determined by next line */
+    let mode = "scalar";
     let nested = null;
+    let currentList = null;
+    const flushPending = () => {
+        // Called when we start a new top-level key and the previous key was still "pending".
+        // An empty-value key followed by another top-level key means it was an empty scalar.
+        if (mode === "pending" && currentKey !== null) {
+            data[currentKey] = "";
+        }
+    };
     for (const line of parsedBlock.frontmatter.split(/\r?\n/)) {
+        // Block-sequence item: "- value" or "  - value" (optional 2-space indent)
+        // Only match when the current key is in list or pending mode.
+        const seqItem = line.match(/^(?: {2})?- (.*)$/);
+        if (seqItem && currentKey !== null && (mode === "list" || mode === "pending")) {
+            if (mode === "pending") {
+                // First block-sequence item after an empty-value key — switch to list mode
+                currentList = [];
+                data[currentKey] = currentList;
+                mode = "list";
+            }
+            currentList.push(parseYamlScalar(seqItem[1].trim()));
+            continue;
+        }
+        // Indented nested key-value (object under a key with empty value)
         const indented = line.match(/^ {2}(\w[\w-]*):\s*(.+)$/);
-        if (indented && currentKey && nested) {
+        if (indented && currentKey !== null && (mode === "object" || mode === "pending")) {
+            if (mode === "pending") {
+                // First indented k-v after an empty-value key — switch to object mode
+                nested = {};
+                data[currentKey] = nested;
+                mode = "object";
+            }
             nested[indented[1]] = parseYamlScalar(indented[2].trim());
             continue;
         }
+        // Top-level key (possibly with inline value)
         const top = line.match(/^(\w[\w-]*):\s*(.*)$/);
         if (!top) {
             continue;
         }
+        // Starting a new top-level key — flush any pending empty-value key
+        flushPending();
         currentKey = top[1];
         const value = top[2].trim();
         if (value === "") {
-            nested = {};
-            data[currentKey] = nested;
+            // Defer mode decision until we see the next line
+            mode = "pending";
+            nested = null;
+            currentList = null;
+            // Don't store anything yet — flushPending will set "" if no continuation
+        }
+        else if (value.startsWith("[") && value.endsWith("]")) {
+            // Inline flow array: tags: [ops, networking]
+            mode = "list";
+            nested = null;
+            currentList = parseFlowArray(value);
+            data[currentKey] = currentList;
         }
         else {
+            mode = "scalar";
             nested = null;
+            currentList = null;
             data[currentKey] = parseYamlScalar(value);
         }
     }
+    // Flush the last key if it was still pending (empty value, no continuation)
+    flushPending();
     return {
         data,
         content: parsedBlock.content,
@@ -55,6 +100,15 @@ export function parseFrontmatter(raw) {
         bodyStartLine: parsedBlock.bodyStartLine,
     };
 }
+/**
+ * Parse a YAML flow array string like `[a, b, c]` into an array of scalars.
+ */
+function parseFlowArray(value) {
+    const inner = value.slice(1, -1).trim();
+    if (!inner)
+        return [];
+    return inner.split(",").map((item) => parseYamlScalar(item.trim()));
+}
 export function parseFrontmatterBlock(raw) {
     // Handle both LF and CRLF line endings throughout.
     // The closing --- may be preceded by \r\n; capture and strip trailing \r

package/dist/indexer.js

@@ -95,9 +95,15 @@ export async function akmIndex(options) {
                 : "LLM enhancement disabled.",
         });
         const tLlmEnd = Date.now();
-        // Rebuild FTS after all inserts
-        rebuildFts(db);
-        onProgress({ phase: "fts", message: "Rebuilt full-text search index." });
+        // Rebuild FTS after all inserts. Use incremental mode when this whole
+        // index run is incremental — only entries touched by `upsertEntry`
+        // since the last rebuild are re-indexed, instead of re-scanning every
+        // row on every `akm index` invocation.
+        rebuildFts(db, { incremental: isIncremental });
+        onProgress({
+            phase: "fts",
+            message: isIncremental ? "Rebuilt full-text search index (dirty rows only)." : "Rebuilt full-text search index.",
+        });
         const tFtsEnd = Date.now();
         // Re-link detached usage_events to their new entry_ids via entry_ref.
         // entry_ref is "type:name" (e.g., "skill:code-review"), entry_key is "stashDir:type:name".
@@ -362,13 +368,17 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
 async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     if (!config.llm || dirsNeedingLlm.length === 0)
         return;
+    // Aggregate per-entry failures so a misconfigured LLM endpoint surfaces
+    // as a single visible warning instead of silently degrading every entry
+    // and leaving the user wondering why nothing got enhanced.
+    const summary = { attempted: 0, succeeded: 0, failureSamples: [] };
     for (const { dirPath, files, currentStashDir, stash: originalStash } of dirsNeedingLlm) {
         // Only enhance generated entries; user-provided overrides should not be overwritten
         const generatedEntries = originalStash.entries.filter((e) => e.quality === "generated");
         if (generatedEntries.length === 0)
             continue;
         const generatedStash = { entries: generatedEntries };
-        const enhanced = await enhanceStashWithLlm(config.llm, generatedStash, files);
+        const enhanced = await enhanceStashWithLlm(config.llm, generatedStash, files, summary);
         // Re-upsert the enhanced entries in a single transaction so a crash
         // cannot leave half the entries updated and the rest stale.
         db.transaction(() => {
@@ -380,6 +390,16 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
             }
         })();
     }
+    if (summary.attempted > 0 && summary.succeeded === 0) {
+        const sample = summary.failureSamples.length ? ` Example: ${summary.failureSamples[0]}` : "";
+        warn(`LLM enhancement failed for all ${summary.attempted} attempted entries — index built without LLM enrichment.` +
+            ` Check llm.endpoint and llm.model in your config.${sample}`);
+    }
+    else if (summary.attempted > 0 && summary.succeeded < summary.attempted) {
+        const failed = summary.attempted - summary.succeeded;
+        const sample = summary.failureSamples.length ? ` Examples: ${summary.failureSamples.join("; ")}` : "";
+        warn(`LLM enhancement failed for ${failed}/${summary.attempted} entries — they were left un-enhanced.${sample}`);
+    }
 }
 async function generateEmbeddingsForDb(db, config, onProgress) {
     if (config.semanticSearchMode === "off") {
@@ -569,10 +589,12 @@ function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
     }
     return false;
 }
-async function enhanceStashWithLlm(llmConfig, stash, files) {
+async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
     const { enhanceMetadata } = await import("./llm.js");
     const enhanced = [];
+    const seenSamples = new Set();
     for (const entry of stash.entries) {
+        summary.attempted++;
         try {
             const entryFile = entry.filename
                 ? (files.find((f) => path.basename(f) === entry.filename) ?? files[0])
@@ -595,9 +617,15 @@ async function enhanceStashWithLlm(llmConfig, stash, files) {
             if (improvements.tags?.length)
                 updated.tags = improvements.tags;
             enhanced.push(updated);
+            summary.succeeded++;
         }
-        catch {
+        catch (err) {
             enhanced.push(entry);
+            const msg = err instanceof Error ? err.message : String(err);
+            if (summary.failureSamples.length < 3 && !seenSamples.has(msg)) {
+                summary.failureSamples.push(msg);
+                seenSamples.add(msg);
+            }
         }
     }
     return { entries: enhanced };
@@ -639,7 +667,10 @@ export function matchEntryToFile(entryName, fileMap, files) {
     // Fallback to first file, or null if no files are available
     return files[0] || null;
 }
-export { buildSearchFields, buildSearchText } from "./search-fields";
+// `buildSearchFields` and `buildSearchText` were previously re-exported from
+// here for backwards compatibility. Importers should now pull them directly
+// from `./search-fields` to avoid loading the indexer's full dependency
+// graph (LLM client, embedder facade) when only the text builder is needed.
 // ── Utility score recomputation ──────────────────────────────────────────────
 /** Retention window for usage events: events older than this are purged. */
 const USAGE_EVENT_RETENTION_DAYS = 90;

package/dist/info.js

@@ -13,8 +13,8 @@ import { pkgVersion } from "./version";
  */
 export function assembleInfo(options) {
     const config = loadConfig();
-    // Asset types
-    const assetTypes = getAssetTypes();
+    // Asset types (copy into a mutable array — `getAssetTypes()` returns readonly)
+    const assetTypes = [...getAssetTypes()];
     const semanticRuntime = readSemanticStatus();
     const semanticStatus = getEffectiveSemanticStatus(config, semanticRuntime);
     // Search modes

package/dist/install-audit.js

@@ -346,16 +346,31 @@ function splitAllowedFindings(findings, ref, allowedFindings) {
     return { findings: active, waivedFindings: waived };
 }
 function matchesAllowedFinding(finding, ref, allowedFindings) {
+    // Normalize paths so a waiver written against `scripts/setup.sh` matches
+    // a finding emitted as `./scripts/setup.sh` or `scripts//setup.sh`. On
+    // Windows we also fold case, mirroring `isWithin`'s comparison rules.
+    const findingPathNormalized = normalizeWaiverPath(finding.file);
     return allowedFindings.some((allowed) => {
         if (allowed.id !== finding.id)
             return false;
         if (allowed.ref && allowed.ref !== ref)
             return false;
-        if (allowed.path && allowed.path !== finding.file)
+        if (allowed.path && normalizeWaiverPath(allowed.path) !== findingPathNormalized)
             return false;
         return true;
     });
 }
+function normalizeWaiverPath(value) {
+    if (!value)
+        return value;
+    // Strip a leading `./`, collapse duplicate slashes via path.normalize, and
+    // POSIX-ify so Windows path separators don't trigger spurious mismatches.
+    const normalized = path
+        .normalize(value)
+        .replace(/\\/g, "/")
+        .replace(/^\.\/+/, "");
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
 function addUrlLabels(labels, rawUrl) {
     if (!rawUrl)
         return;

package/dist/{installed-kits.js → installed-stashes.js}

@@ -10,9 +10,11 @@ import { resolveStashDir } from "./common";
 import { loadConfig } from "./config";
 import { NotFoundError, UsageError } from "./errors";
 import { akmIndex } from "./indexer";
+import { auditInstallCandidate, deriveRegistryLabels, enforceRegistryInstallPolicy, formatInstallAuditFailure, } from "./install-audit";
 import { removeLockEntry, upsertLockEntry } from "./lockfile";
-import { installRegistryRef, removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./registry-install";
 import { parseRegistryRef } from "./registry-resolve";
+import { removeInstalledRegistryEntry, upsertInstalledRegistryEntry } from "./stash-add";
+import { syncFromRef } from "./stash-providers/sync-from-ref";
 import { removeStash } from "./stash-source-manage";
 export async function akmListSources(input) {
     const stashDir = input?.stashDir ?? resolveStashDir();
@@ -64,7 +66,7 @@ export async function akmListSources(input) {
 export async function akmRemove(input) {
     const target = input.target.trim();
     if (!target)
-        throw new UsageError("Target is required. Provide the source id, ref, path, URL, or name (e.g. `akm remove npm:@scope/kit` or `akm remove ~/my-stash`).");
+        throw new UsageError("Target is required. Provide the source id, ref, path, URL, or name (e.g. `akm remove npm:@scope/stash` or `akm remove ~/my-stash`).");
     const stashDir = input.stashDir ?? resolveStashDir();
     const config = loadConfig();
     const installed = config.installed ?? [];
@@ -138,26 +140,58 @@ export async function akmUpdate(input) {
     const force = input?.force === true;
     const installedEntries = loadConfig().installed ?? [];
     const selectedEntries = selectTargets(installedEntries, target, all);
+    const auditConfig = loadConfig();
     const processed = [];
     for (const entry of selectedEntries) {
         if (force && shouldCleanupCache(entry)) {
             cleanupDirectoryBestEffort(entry.cacheDir);
         }
-        const installed = await installRegistryRef(entry.ref);
-        upsertInstalledRegistryEntry(toInstalledEntry(installed));
+        const synced = await syncFromRef(entry.ref, { force });
+        // Mirror the post-sync audit hook from akmAdd so `akm update` can't
+        // silently land malicious content during refresh.
+        const registryLabels = deriveRegistryLabels({
+            source: synced.source,
+            ref: synced.ref,
+            artifactUrl: synced.artifactUrl,
+        });
+        enforceRegistryInstallPolicy(registryLabels, auditConfig, entry.ref);
+        const audit = auditInstallCandidate({
+            rootDir: synced.extractedDir,
+            source: synced.source,
+            ref: synced.ref,
+            registryLabels,
+            config: auditConfig,
+        });
+        if (audit.blocked) {
+            throw new Error(formatInstallAuditFailure(synced.ref, audit));
+        }
+        const installedEntry = {
+            id: synced.id,
+            source: synced.source,
+            ref: synced.ref,
+            artifactUrl: synced.artifactUrl,
+            resolvedVersion: synced.resolvedVersion,
+            resolvedRevision: synced.resolvedRevision,
+            stashRoot: synced.contentDir,
+            cacheDir: synced.cacheDir,
+            installedAt: synced.syncedAt,
+            writable: synced.writable ?? entry.writable,
+            ...(entry.wikiName ? { wikiName: entry.wikiName } : {}),
+        };
+        upsertInstalledRegistryEntry(installedEntry);
         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),
+            id: synced.id,
+            source: synced.source,
+            ref: synced.ref,
+            resolvedVersion: synced.resolvedVersion,
+            resolvedRevision: synced.resolvedRevision,
+            integrity: synced.integrity ?? (synced.source === "local" ? "local" : undefined),
         });
-        if (entry.cacheDir !== installed.cacheDir && shouldCleanupCache(entry)) {
+        if (entry.cacheDir !== synced.cacheDir && shouldCleanupCache(entry)) {
             cleanupDirectoryBestEffort(entry.cacheDir);
         }
-        const versionChanged = (entry.resolvedVersion ?? "") !== (installed.resolvedVersion ?? "");
-        const revisionChanged = (entry.resolvedRevision ?? "") !== (installed.resolvedRevision ?? "");
+        const versionChanged = (entry.resolvedVersion ?? "") !== (synced.resolvedVersion ?? "");
+        const revisionChanged = (entry.resolvedRevision ?? "") !== (synced.resolvedRevision ?? "");
         processed.push({
             id: entry.id,
             source: entry.source,
@@ -167,7 +201,7 @@ export async function akmUpdate(input) {
                 resolvedRevision: entry.resolvedRevision,
                 cacheDir: entry.cacheDir,
             },
-            installed: toInstallStatus(installed),
+            installed: { ...installedEntry, extractedDir: synced.extractedDir, audit },
             changed: {
                 version: versionChanged,
                 revision: revisionChanged,
@@ -250,14 +284,6 @@ function tryResolveInstalledTarget(installed, target) {
     }
     return undefined;
 }
-function toInstalledEntry(status) {
-    // KitInstallStatus extends InstalledKitEntry; omit transient install-only fields.
-    const { extractedDir: _extractedDir, audit: _audit, ...base } = status;
-    return base;
-}
-function toInstallStatus(status) {
-    return { ...status };
-}
 function cleanupDirectoryBestEffort(target) {
     try {
         fs.rmSync(target, { recursive: true, force: true });

package/dist/llm-client.js

@@ -0,0 +1,92 @@
+/**
+ * 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 "./common";
+export async function chatCompletion(config, messages, options) {
+    const headers = { "Content-Type": "application/json" };
+    if (config.apiKey) {
+        headers.Authorization = `Bearer ${config.apiKey}`;
+    }
+    const response = await fetchWithTimeout(config.endpoint, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            model: config.model,
+            messages,
+            temperature: options?.temperature ?? config.temperature ?? 0.3,
+            max_tokens: options?.maxTokens ?? config.maxTokens ?? 512,
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`LLM request failed (${response.status}): ${body}`);
+    }
+    const json = (await response.json());
+    return json.choices?.[0]?.message?.content?.trim() ?? "";
+}
+/** Strip leading/trailing markdown code fences from an LLM response. */
+export function stripJsonFences(raw) {
+    return raw
+        .trim()
+        .replace(/^```(?:json)?\s*\n?/i, "")
+        .replace(/\n?```\s*$/i, "")
+        .trim();
+}
+/** Parse a possibly-fenced JSON response. Returns undefined if invalid. */
+export function parseJsonResponse(raw) {
+    try {
+        return JSON.parse(stripJsonFences(raw));
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Availability check ──────────────────────────────────────────────────────
+/**
+ * Check if the LLM endpoint is reachable.
+ */
+export async function isLlmAvailable(config) {
+    try {
+        const result = await chatCompletion(config, [{ role: "user", content: "Respond with just the word: ok" }]);
+        return result.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Capability probe ────────────────────────────────────────────────────────
+/**
+ * Ask the model to emit a strict JSON object so we know whether the knowledge
+ * wiki ingest/lint flows can rely on structured output. Failure is non-fatal —
+ * the caller can fall back to assist-only mode.
+ */
+export async function probeLlmCapabilities(config) {
+    try {
+        const raw = await chatCompletion(config, [
+            {
+                role: "system",
+                content: "You return only valid JSON. No prose, no markdown fences.",
+            },
+            {
+                role: "user",
+                content: 'Return exactly this JSON object and nothing else: {"ok": true, "ingest": true, "lint": true}',
+            },
+        ], { maxTokens: 64, temperature: 0 });
+        if (!raw)
+            return { reachable: false, structuredOutput: false, error: "empty response" };
+        const parsed = parseJsonResponse(raw);
+        return {
+            reachable: true,
+            structuredOutput: Boolean(parsed && parsed.ok === true),
+        };
+    }
+    catch (err) {
+        return { reachable: false, structuredOutput: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}