akm-cli 0.4.1 → 0.5.0-rc2

package/dist/completions.js

@@ -4,8 +4,8 @@ import path from "node:path";
 import { getAssetTypes } from "./asset-spec";
 // ── Known flag values ────────────────────────────────────────────────────────
 const FLAG_VALUES = {
-    "--format": ["json", "text", "yaml"],
-    "--detail": ["brief", "normal", "full"],
+    "--format": ["json", "text", "yaml", "jsonl"],
+    "--detail": ["brief", "normal", "full", "summary"],
     "--type": () => [...getAssetTypes(), "any"],
     "--source": ["stash", "registry", "both"],
     "--shell": ["bash"],

package/dist/config-cli.js

@@ -36,6 +36,8 @@ export function parseConfigValue(key, value) {
             return { security: { installAudit: { registryAllowlist: parseStringArrayValue(value, key) } } };
         case "security.installAudit.registryWhitelist":
             return { security: { installAudit: { registryAllowlist: parseStringArrayValue(value, key) } } };
+        case "security.installAudit.allowedFindings":
+            return { security: { installAudit: { allowedFindings: parseAllowedFindingsValue(value, key) } } };
         default:
             throw new UsageError(`Unknown config key: ${key}`);
     }
@@ -70,6 +72,8 @@ export function getConfigValue(config, key) {
             return getInstallAuditAllowlist(config);
         case "security.installAudit.registryWhitelist":
             return getInstallAuditAllowlist(config);
+        case "security.installAudit.allowedFindings":
+            return config.security?.installAudit?.allowedFindings ?? null;
         default:
             throw new UsageError(`Unknown config key: ${key}`);
     }
@@ -89,6 +93,7 @@ export function setConfigValue(config, key, rawValue) {
         case "security.installAudit.blockUnlistedRegistries":
         case "security.installAudit.registryAllowlist":
         case "security.installAudit.registryWhitelist":
+        case "security.installAudit.allowedFindings":
             return mergeConfigValue(config, parseConfigValue(key, rawValue));
         default:
             throw new UsageError(`Unknown config key: ${key}`);
@@ -132,6 +137,13 @@ export function unsetConfigValue(config, key) {
                     installAudit: { registryAllowlist: undefined, registryWhitelist: undefined },
                 }),
             };
+        case "security.installAudit.allowedFindings":
+            return {
+                ...config,
+                security: mergeSecurityConfig(config.security, {
+                    installAudit: { allowedFindings: undefined },
+                }),
+            };
         default:
             throw new UsageError(`Unknown or unsupported unset key: ${key}`);
     }
@@ -213,6 +225,35 @@ function parseStringArrayValue(value, key) {
 function getInstallAuditAllowlist(config) {
     return config.security?.installAudit?.registryAllowlist ?? config.security?.installAudit?.registryWhitelist ?? null;
 }
+function parseAllowedFindingsValue(value, key) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new UsageError(`Invalid value for ${key}: expected a JSON array of {id, ref?, path?, reason?} objects`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new UsageError(`Invalid value for ${key}: expected a JSON array`);
+    }
+    return parsed.map((entry, i) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            throw new UsageError(`Invalid value for ${key}[${i}]: expected an object with an "id" field`);
+        }
+        const obj = entry;
+        if (typeof obj.id !== "string" || !obj.id) {
+            throw new UsageError(`Invalid value for ${key}[${i}]: "id" is required`);
+        }
+        const result = { id: obj.id };
+        if (typeof obj.ref === "string" && obj.ref)
+            result.ref = obj.ref;
+        if (typeof obj.path === "string" && obj.path)
+            result.path = obj.path;
+        if (typeof obj.reason === "string" && obj.reason)
+            result.reason = obj.reason;
+        return result;
+    });
+}
 function parseRegistriesValue(value) {
     if (value === "null" || value === "")
         return undefined;

package/dist/config.js

@@ -187,6 +187,9 @@ function pickKnownKeys(raw) {
     const output = parseOutputConfig(raw.output);
     if (output)
         config.output = output;
+    if (typeof raw.writable === "boolean") {
+        config.writable = raw.writable;
+    }
     return config;
 }
 function readNormalizedConfig(configPath) {
@@ -401,6 +404,24 @@ function parseLlmConfig(value) {
     if (typeof obj.apiKey === "string" && obj.apiKey) {
         result.apiKey = obj.apiKey;
     }
+    if (typeof obj.contextWindow === "number" &&
+        Number.isFinite(obj.contextWindow) &&
+        Number.isInteger(obj.contextWindow) &&
+        obj.contextWindow > 0) {
+        result.contextWindow = obj.contextWindow;
+    }
+    if (typeof obj.capabilities === "object" && obj.capabilities !== null && !Array.isArray(obj.capabilities)) {
+        const capsRaw = obj.capabilities;
+        const caps = {};
+        if (typeof capsRaw.structuredOutput === "boolean")
+            caps.structuredOutput = capsRaw.structuredOutput;
+        if (typeof capsRaw.longContext === "boolean")
+            caps.longContext = capsRaw.longContext;
+        if (typeof capsRaw.toolUse === "boolean")
+            caps.toolUse = capsRaw.toolUse;
+        if (Object.keys(caps).length > 0)
+            result.capabilities = caps;
+    }
     return result;
 }
 function parseInstalledEntries(value) {
@@ -433,12 +454,17 @@ function parseInstalledKitEntry(value) {
         cacheDir,
         installedAt,
     };
+    if (typeof obj.writable === "boolean")
+        entry.writable = obj.writable;
     const resolvedVersion = asNonEmptyString(obj.resolvedVersion);
     if (resolvedVersion)
         entry.resolvedVersion = resolvedVersion;
     const resolvedRevision = asNonEmptyString(obj.resolvedRevision);
     if (resolvedRevision)
         entry.resolvedRevision = resolvedRevision;
+    const wikiName = asNonEmptyString(obj.wikiName);
+    if (wikiName)
+        entry.wikiName = wikiName;
     return entry;
 }
 function asNonEmptyString(value) {
@@ -491,8 +517,39 @@ function parseInstallAuditConfig(value) {
     if (rawAllowlist) {
         config.registryAllowlist = rawAllowlist;
     }
+    const allowedFindings = parseInstallAuditAllowedFindings(obj.allowedFindings);
+    if (allowedFindings) {
+        config.allowedFindings = allowedFindings;
+    }
     return Object.keys(config).length > 0 ? config : undefined;
 }
+function parseInstallAuditAllowedFindings(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const findings = value
+        .map((entry) => parseInstallAuditAllowedFinding(entry))
+        .filter((entry) => entry !== undefined);
+    return findings.length > 0 ? findings : undefined;
+}
+function parseInstallAuditAllowedFinding(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const obj = value;
+    const id = asNonEmptyString(obj.id);
+    if (!id)
+        return undefined;
+    const finding = { id };
+    const ref = asNonEmptyString(obj.ref);
+    if (ref)
+        finding.ref = ref;
+    const entryPath = asNonEmptyString(obj.path);
+    if (entryPath)
+        finding.path = entryPath;
+    const reason = asNonEmptyString(obj.reason);
+    if (reason)
+        finding.reason = reason;
+    return finding;
+}
 function parseStashConfigEntry(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return undefined;
@@ -512,9 +569,14 @@ function parseStashConfigEntry(value) {
         entry.name = name;
     if (typeof obj.enabled === "boolean")
         entry.enabled = obj.enabled;
+    if (typeof obj.writable === "boolean")
+        entry.writable = obj.writable;
     if (typeof obj.options === "object" && obj.options !== null && !Array.isArray(obj.options)) {
         entry.options = obj.options;
     }
+    const wikiName = asNonEmptyString(obj.wikiName);
+    if (wikiName)
+        entry.wikiName = wikiName;
     return entry;
 }
 function parseRegistryConfigEntry(value) {

package/dist/file-context.js

@@ -155,10 +155,11 @@ export async function runMatchers(ctx) {
  * Build a RenderContext by merging a FileContext with its winning MatchResult
  * and the list of stash search paths.
  */
-export function buildRenderContext(ctx, match, stashDirs) {
+export function buildRenderContext(ctx, match, stashDirs, origin) {
     return {
         ...ctx,
         matchResult: match,
         stashDirs,
+        origin,
     };
 }

package/dist/github.js

@@ -1,5 +1,24 @@
+import * as childProcess from "node:child_process";
 export const GITHUB_API_BASE = "https://api.github.com";
 const GITHUB_TOKEN_DOMAINS = new Set(["api.github.com", "github.com", "uploads.github.com"]);
+function readGithubTokenFromEnv() {
+    const token = process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim();
+    return token || undefined;
+}
+function readGithubTokenFromGhCli() {
+    const result = childProcess.spawnSync("gh", ["auth", "token"], {
+        encoding: "utf8",
+        timeout: 5_000,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.status !== 0)
+        return undefined;
+    const token = result.stdout.trim();
+    return token || undefined;
+}
+function resolveGithubToken() {
+    return readGithubTokenFromEnv() ?? readGithubTokenFromGhCli();
+}
 /**
  * Build headers for GitHub API requests.
  * When a `url` is provided, the Authorization header is only included if the
@@ -7,7 +26,7 @@ const GITHUB_TOKEN_DOMAINS = new Set(["api.github.com", "github.com", "uploads.g
  * to third-party hosts.
  */
 export function githubHeaders(url) {
-    const token = process.env.GITHUB_TOKEN?.trim();
+    const token = resolveGithubToken();
     const headers = {
         Accept: "application/vnd.github+json",
         "User-Agent": "akm-registry",

package/dist/indexer.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { isHttpUrl, resolveStashDir } from "./common";
 import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
-import { generateMetadataFlat, loadStashFile } from "./metadata";
+import { generateMetadataFlat, loadStashFile, shouldIndexStashFile } from "./metadata";
 import { getDbPath } from "./paths";
 import { buildSearchText } from "./search-fields";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./semantic-status";
@@ -18,9 +18,10 @@ export async function akmIndex(options) {
     const config = loadConfig();
     // Ensure git stash caches are extracted before resolving stash dirs,
     // so their content directories exist on disk for the walker to discover.
-    const { ensureStashCaches, resolveAllStashDirs } = await import("./search-source.js");
+    const { ensureStashCaches, resolveStashSources } = await import("./search-source.js");
     await ensureStashCaches(config);
-    const allStashDirs = resolveAllStashDirs(stashDir);
+    const allStashSources = resolveStashSources(stashDir, config);
+    const allStashDirs = allStashSources.map((s) => s.path);
     const t0 = Date.now();
     // Open database — pass embedding dimension from config if available
     const dbPath = getDbPath();
@@ -79,7 +80,7 @@ export async function akmIndex(options) {
         // doFullDelete=true merges the wipe into the same transaction as the
         // inserts so readers never see an empty database mid-rebuild.
         const doFullDelete = options?.full || !isIncremental;
-        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = await indexEntries(db, allStashDirs, isIncremental, builtAtMs, doFullDelete);
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm } = await indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete);
         onProgress({
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -117,6 +118,18 @@ export async function akmIndex(options) {
         }
         // Recompute utility scores from usage_events after FTS rebuild
         recomputeUtilityScores(db);
+        // Regenerate each wiki's index.md from its pages' frontmatter. Best-effort
+        // — errors are caught inside regenerateAllWikiIndexes and never block the
+        // index run. The primary stash is the only target: additional sources
+        // are read-only caches, and regenerating their indexes would mutate
+        // cache content.
+        try {
+            const { regenerateAllWikiIndexes } = await import("./wiki.js");
+            regenerateAllWikiIndexes(stashDir);
+        }
+        catch {
+            /* best-effort */
+        }
         // Generate embeddings if semantic search is enabled
         const embeddingResult = await generateEmbeddingsForDb(db, config, onProgress);
         const tEmbedEnd = Date.now();
@@ -168,15 +181,54 @@ export async function akmIndex(options) {
     }
 }
 // ── Extracted helpers for indexing ────────────────────────────────────────────
-async function indexEntries(db, allStashDirs, isIncremental, builtAtMs, doFullDelete = false) {
+async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete = false) {
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
     const seenPaths = new Set();
     const dirsNeedingLlm = [];
     const dirRecords = [];
-    for (const currentStashDir of allStashDirs) {
+    for (const stashSource of allStashSources) {
+        const currentStashDir = stashSource.path;
         const fileContexts = walkStashFlat(currentStashDir);
+        // Wiki-root stashes: all .md files are indexed as wiki pages under wikiName
+        if (stashSource.wikiName) {
+            const wikiName = stashSource.wikiName;
+            const wikiDirGroups = new Map();
+            for (const ctx of fileContexts) {
+                if (ctx.ext !== ".md")
+                    continue;
+                if (!shouldIndexStashFile(currentStashDir, ctx.absPath, { treatStashRootAsWikiRoot: true }))
+                    continue;
+                const relNoExt = ctx.relPath.replace(/\.md$/, "");
+                const entry = {
+                    name: `${wikiName}/${relNoExt}`,
+                    type: "wiki",
+                    filename: ctx.fileName,
+                    description: ctx.frontmatter()?.description,
+                    source: "frontmatter",
+                };
+                const dir = ctx.parentDirAbs;
+                const group = wikiDirGroups.get(dir);
+                if (group) {
+                    group.files.push(ctx.absPath);
+                    group.entries.push(entry);
+                }
+                else {
+                    wikiDirGroups.set(dir, { files: [ctx.absPath], entries: [entry] });
+                }
+            }
+            for (const [dirPath, { files, entries }] of wikiDirGroups) {
+                if (seenPaths.has(path.resolve(dirPath))) {
+                    dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true });
+                    continue;
+                }
+                seenPaths.add(path.resolve(dirPath));
+                scannedDirs++;
+                dirRecords.push({ dirPath, currentStashDir, files, stash: { entries }, skip: false });
+            }
+            continue;
+        }
         const dirGroups = new Map();
         for (const ctx of fileContexts) {
             const dir = ctx.parentDirAbs;
@@ -278,6 +330,8 @@ async function indexEntries(db, allStashDirs, isIncremental, builtAtMs, doFullDe
                         : matchEntryToFile(entry.name, fileBasenameMap, files);
                     if (!entryPath)
                         continue; // skip unresolvable entries
+                    if (!shouldIndexStashFile(currentStashDir, entryPath))
+                        continue;
                     // Skip if a higher-priority stash root already indexed this asset
                     const basename = path.basename(entryPath);
                     const identityKey = `${entry.type}\0${basename}\0${entry.description ?? ""}`;

package/dist/init.js

@@ -4,6 +4,7 @@
  * Creates the working stash directory structure, persists the stashDir
  * in config.json, and ensures ripgrep is available.
  */
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { TYPE_DIRS } from "./asset-spec";
@@ -23,6 +24,8 @@ export async function akmInit(options) {
             fs.mkdirSync(subDir, { recursive: true });
         }
     }
+    // Ensure the default stash is a local git repo (no remote required)
+    ensureGitRepo(stashDir);
     // Persist stashDir in config.json
     const configPath = getConfigPath();
     const existing = loadUserConfig();
@@ -41,3 +44,11 @@ export async function akmInit(options) {
     }
     return { stashDir, created, configPath, ripgrep };
 }
+/** Initialise `dir` as a git repository if it is not already one. */
+function ensureGitRepo(dir) {
+    const gitDir = path.join(dir, ".git");
+    if (fs.existsSync(gitDir))
+        return;
+    // Non-fatal: git may not be available in all environments
+    spawnSync("git", ["init", dir], { encoding: "utf8", timeout: 15_000 });
+}

package/dist/install-audit.js

@@ -6,6 +6,7 @@ const DEFAULT_INSTALL_AUDIT_CONFIG = {
     blockOnCritical: true,
     blockUnlistedRegistries: false,
     registryAllowlist: [],
+    allowedFindings: [],
 };
 const MAX_SCANNED_FILE_BYTES = 256 * 1024;
 const LIFECYCLE_SCRIPT_NAMES = new Set([
@@ -36,6 +37,7 @@ const TEXT_FILE_EXTENSIONS = new Set([
     ".yaml",
     ".yml",
 ]);
+const BLOCKED_PACKAGE_DIRECTORIES = new Set(["node_modules", "venv", ".venv", "site-packages"]);
 const CONTENT_RULES = [
     {
         id: "prompt-ignore-previous-instructions",
@@ -49,7 +51,7 @@ const CONTENT_RULES = [
         severity: "critical",
         category: "prompt-injection",
         message: "Contains instructions to reveal hidden prompts or secrets.",
-        pattern: /\b(reveal|print|dump|show|exfiltrat(?:e|ion))\b[^.\n]{0,120}\b(system prompt|hidden instructions?|developer message|api key|token|secret|password)\b/i,
+        pattern: /\b(?:reveal|print|dump|show|output|return|exfiltrat(?:e|ion))\b[^.\n]{0,60}\b(?:your|the)\b[^.\n]{0,40}\b(system prompt|hidden instructions?|developer message|api key|token|secret|password)\b/i,
     },
     {
         id: "prompt-bypass-guardrails",
@@ -97,6 +99,7 @@ export function resolveInstallAuditConfig(config) {
         blockOnCritical: installAudit?.blockOnCritical ?? DEFAULT_INSTALL_AUDIT_CONFIG.blockOnCritical,
         blockUnlistedRegistries: installAudit?.blockUnlistedRegistries ?? DEFAULT_INSTALL_AUDIT_CONFIG.blockUnlistedRegistries,
         registryAllowlist: allowlist.map((entry) => entry.trim().toLowerCase()),
+        allowedFindings: installAudit?.allowedFindings ?? DEFAULT_INSTALL_AUDIT_CONFIG.allowedFindings,
     };
 }
 export function enforceRegistryInstallPolicy(registryLabels, config, ref) {
@@ -118,6 +121,7 @@ export function auditInstallCandidate(input) {
             enabled: false,
             passed: true,
             blocked: false,
+            trusted: false,
             registryLabels: [...input.registryLabels],
             findings: [],
             scannedFiles: 0,
@@ -128,17 +132,20 @@ export function auditInstallCandidate(input) {
     const findings = [];
     const counters = { scannedFiles: 0, scannedBytes: 0 };
     scanDirectory(input.rootDir, input.rootDir, findings, counters);
-    const summary = buildSummary(findings);
-    const blocked = resolved.blockOnCritical && summary.critical > 0;
+    const { findings: activeFindings, waivedFindings } = splitAllowedFindings(findings, input.ref, resolved.allowedFindings);
+    const summary = buildSummary(activeFindings);
+    const blocked = !input.trustThisInstall && resolved.blockOnCritical && summary.critical > 0;
     return {
         enabled: true,
-        passed: findings.length === 0,
+        passed: activeFindings.length === 0,
         blocked,
+        trusted: Boolean(input.trustThisInstall),
         registryLabels: [...input.registryLabels],
-        findings,
+        findings: activeFindings,
         scannedFiles: counters.scannedFiles,
         scannedBytes: counters.scannedBytes,
         summary,
+        ...(waivedFindings.length > 0 ? { waivedFindings } : {}),
     };
 }
 export function formatInstallAuditFailure(ref, report) {
@@ -149,7 +156,8 @@ export function formatInstallAuditFailure(ref, report) {
     if (report.findings.length > 5) {
         lines.push(`- ${report.findings.length - 5} more finding(s) omitted`);
     }
-    lines.push("Disable blocking with `security.installAudit.blockOnCritical = false`, or disable audits with `security.installAudit.enabled = false`.");
+    lines.push("Disable blocking with `security.installAudit.blockOnCritical = false`, or disable audits with `security.installAudit.enabled = false`." +
+        " Or pass --trust on a one-off 'akm add' to bypass this audit for this install only.");
     return lines.join("\n");
 }
 export function formatInstallAuditSummary(report) {
@@ -165,7 +173,9 @@ export function formatInstallAuditSummary(report) {
     if (report.summary.low > 0)
         severitySummary.push(`${report.summary.low} low`);
     const detail = severitySummary.length > 0 ? severitySummary.join(", ") : "no findings";
-    return `Audit: ${report.blocked ? "blocked" : report.passed ? "passed" : "warnings"} (${detail}; scanned ${report.scannedFiles} file${report.scannedFiles === 1 ? "" : "s"})`;
+    const status = report.blocked ? "blocked" : report.passed ? "passed" : report.trusted ? "trusted" : "warnings";
+    const waived = report.waivedFindings?.length ? `; waived ${report.waivedFindings.length}` : "";
+    return `Audit: ${status} (${detail}; scanned ${report.scannedFiles} file${report.scannedFiles === 1 ? "" : "s"}${waived})`;
 }
 export function deriveRegistryLabels(input) {
     const labels = new Set();
@@ -190,10 +200,22 @@ function scanDirectory(dir, rootDir, findings, counters) {
         return;
     }
     for (const entry of entries) {
-        if (entry.name === ".git" || entry.name === "node_modules")
+        if (entry.name === ".git")
             continue;
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
+            if (BLOCKED_PACKAGE_DIRECTORIES.has(entry.name)) {
+                const relativePath = path.relative(rootDir, fullPath) || entry.name;
+                findings.push({
+                    id: "bundled-package-directory",
+                    severity: "critical",
+                    category: "vendored-dependency",
+                    message: `Contains bundled dependency directory "${entry.name}".`,
+                    file: relativePath,
+                    snippet: relativePath,
+                });
+                continue;
+            }
             scanDirectory(fullPath, rootDir, findings, counters);
             continue;
         }
@@ -311,6 +333,29 @@ function buildSummary(findings) {
     }
     return summary;
 }
+function splitAllowedFindings(findings, ref, allowedFindings) {
+    const active = [];
+    const waived = [];
+    for (const finding of findings) {
+        if (matchesAllowedFinding(finding, ref, allowedFindings)) {
+            waived.push(finding);
+            continue;
+        }
+        active.push(finding);
+    }
+    return { findings: active, waivedFindings: waived };
+}
+function matchesAllowedFinding(finding, ref, allowedFindings) {
+    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)
+            return false;
+        return true;
+    });
+}
 function addUrlLabels(labels, rawUrl) {
     if (!rawUrl)
         return;

package/dist/installed-kits.js

@@ -32,6 +32,7 @@ export async function akmListSources(input) {
             path: stash.path,
             provider: isRemote ? stash.type : undefined,
             updatable: false,
+            writable: stash.writable === true,
             status: { exists: stash.path ? directoryExists(stash.path) : true },
         });
     }
@@ -47,6 +48,7 @@ export async function akmListSources(input) {
             ref: entry.ref,
             version: entry.resolvedVersion,
             updatable: true,
+            writable: entry.writable === true,
             status: { exists: directoryExists(entry.stashRoot) },
         });
     }

package/dist/llm.js

@@ -1,5 +1,5 @@
 import { fetchWithTimeout } from "./common";
-async function chatCompletion(config, messages) {
+export async function chatCompletion(config, messages, options) {
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {
         headers.Authorization = `Bearer ${config.apiKey}`;
@@ -10,8 +10,8 @@ async function chatCompletion(config, messages) {
         body: JSON.stringify({
             model: config.model,
             messages,
-            temperature: config.temperature ?? 0.3,
-            max_tokens: config.maxTokens ?? 512,
+            temperature: options?.temperature ?? config.temperature ?? 0.3,
+            max_tokens: options?.maxTokens ?? config.maxTokens ?? 512,
         }),
     });
     if (!response.ok) {
@@ -21,6 +21,23 @@ async function chatCompletion(config, messages) {
     const json = (await response.json());
     return json.choices?.[0]?.message?.content?.trim() ?? "";
 }
+/** Strip leading/trailing markdown code fences from an LLM response. */
+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;
+    }
+}
 // ── 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.`;
 /**
@@ -50,28 +67,22 @@ Return ONLY the JSON object, no explanation.`;
         { role: "system", content: SYSTEM_PROMPT },
         { role: "user", content: userPrompt },
     ]);
-    try {
-        // Strip markdown code fences if present
-        const cleaned = raw.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "");
-        const parsed = JSON.parse(cleaned);
-        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;
-    }
-    catch {
-        // LLM returned unparseable output, return empty
+    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;
 }
 /**
  * Check if the LLM endpoint is reachable.
@@ -85,3 +96,33 @@ export async function isLlmAvailable(config) {
         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) };
+    }
+}