akm-cli 0.1.1 → 0.1.2

package/dist/cli.js

@@ -41,6 +41,8 @@ const pkgVersion = (() => {
 const OUTPUT_FORMATS = ["json", "yaml", "text"];
 const DETAIL_LEVELS = ["brief", "normal", "full"];
 const NORMAL_DESCRIPTION_LIMIT = 250;
+const CONTEXT_HUB_ALIAS_REF = "context-hub";
+const CONTEXT_HUB_ALIAS_URL = "https://github.com/andrewyng/context-hub";
 function hasBunYAML(b) {
     // biome-ignore lint/suspicious/noExplicitAny: type guard for runtime feature detection
     return typeof b.YAML?.stringify === "function";
@@ -468,6 +470,15 @@ const addCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            if (args.ref.trim() === CONTEXT_HUB_ALIAS_REF) {
+                const result = addStash({
+                    target: CONTEXT_HUB_ALIAS_URL,
+                    providerType: "context-hub",
+                    name: "context-hub",
+                });
+                output("stash-add", result);
+                return;
+            }
             const result = await akmAdd({ ref: args.ref });
             output("add", result);
         });
@@ -1143,6 +1154,7 @@ akm search "<query>" --type skill             # Filter by type
 akm search "<query>" --source both            # Also search registries for installable kits
 akm show <ref>                                # View asset details
 akm add <ref>                                 # Install a kit (npm, GitHub, git, local)
+akm add context-hub                           # Shortcut for adding Context Hub as a stash provider
 akm clone <ref>                               # Copy an asset to the working stash (optional --dest arg to clone to specific location)
 akm registry search "<query>"                 # Search all registries
 \`\`\`
@@ -1213,6 +1225,7 @@ akm add <ref>                                 # Install a kit (smart router: loc
 akm add @scope/kit                            # From npm
 akm add owner/repo                            # From GitHub
 akm add ./path/to/local/kit                   # From local directory (adds as stash)
+akm add context-hub                           # Add the official Context Hub stash
 akm kit add <ref>                             # Install a kit (explicit)
 akm kit list                                  # List installed kits
 akm kit remove <target>                       # Remove a kit

package/dist/db.js

@@ -385,17 +385,22 @@ export function searchFts(db, query, limit, entryType) {
         return [];
     }
 }
-function sanitizeFtsQuery(query) {
-    const tokens = query
-        .replace(/[^a-zA-Z0-9\s]/g, " ")
-        .split(/\s+/)
-        .filter((t) => t.length >= 2);
+export function sanitizeFtsQuery(query) {
+    // Allow only characters safe in FTS5 queries: letters, digits, underscores,
+    // and whitespace. Everything else (hyphens, dots, quotes, parens, asterisks,
+    // colons, carets, @, !, etc.) is replaced with a space so that compound
+    // identifiers like "code-review" or "k8s.setup" become AND-joined tokens
+    // ("code review", "k8s setup") rather than triggering FTS5 syntax errors.
+    let sanitized = query.replace(/[^a-zA-Z0-9_\s]/g, " ");
+    // Neutralize the NEAR operator (FTS5 proximity syntax)
+    sanitized = sanitized.replace(/\bNEAR\b/g, " ");
+    const tokens = sanitized.split(/\s+/).filter((t) => t.length >= 1);
     if (tokens.length === 0)
         return "";
-    // MD-1: Use OR so that any matching token returns results (better recall for
-    // exploratory search). Use unquoted tokens so the porter stemmer can
-    // normalize word forms.
-    return tokens.join(" OR ");
+    // Use implicit AND (space-separated tokens) for precision. FTS5 treats
+    // space-separated tokens as an implicit AND, matching only rows that
+    // contain ALL terms.
+    return tokens.join(" ");
 }
 // ── All entries ─────────────────────────────────────────────────────────────
 export function getAllEntries(db, entryType) {

package/dist/embedder.js

@@ -30,6 +30,19 @@ async function embedLocal(text) {
     const result = await model(text, { pooling: "mean", normalize: true });
     return Array.from(result.data);
 }
+// ── Vector normalization ─────────────────────────────────────────────────────
+/**
+ * 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);
+}
 // ── OpenAI-compatible remote embedder ───────────────────────────────────────
 async function embedRemote(text, config) {
     const headers = { "Content-Type": "application/json" };
@@ -56,7 +69,7 @@ async function embedRemote(text, config) {
     if (!json.data?.[0]?.embedding) {
         throw new Error("Unexpected embedding response format: missing data[0].embedding");
     }
-    return json.data[0].embedding;
+    return l2Normalize(json.data[0].embedding);
 }
 // ── Public API ──────────────────────────────────────────────────────────────
 /**
@@ -118,11 +131,13 @@ async function embedRemoteBatch(texts, config) {
         if (!json.data || json.data.length !== batch.length) {
             throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}`);
         }
-        for (const [idx, d] of json.data.entries()) {
+        // 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(d.embedding);
+            results.push(l2Normalize(d.embedding));
         }
     }
     return results;

package/dist/indexer.js

@@ -162,6 +162,13 @@ async function indexEntries(db, allStashDirs, _stashDir, isIncremental, builtAtM
         }
     }
     // Phase 2 (sync): write all pre-generated metadata inside a single transaction.
+    //
+    // Cross-stash dedup: track indexed assets by content identity
+    // (type + filename + description) so the same asset from a lower-priority
+    // stash root is skipped when a higher-priority root already covers it.
+    // Sources are ordered by priority (primary stash first), so the first
+    // occurrence wins.
+    const indexedAssetIdentities = new Set();
     const insertTransaction = db.transaction(() => {
         // HI-5: Perform the full-rebuild wipe as the FIRST step of the insert
         // transaction so delete and re-insert are atomic — a concurrent reader
@@ -190,8 +197,20 @@ async function indexEntries(db, allStashDirs, _stashDir, isIncremental, builtAtM
             // Delete old entries for this dir (will be re-inserted)
             deleteEntriesByDir(db, dirPath);
             if (stash) {
+                // Build a lookup for matching filename-less entries to actual files
+                const fileBasenameMap = buildFileBasenameMap(files);
                 for (const entry of stash.entries) {
-                    const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+                    const entryPath = entry.filename
+                        ? path.join(dirPath, entry.filename)
+                        : matchEntryToFile(entry.name, fileBasenameMap, files);
+                    if (!entryPath)
+                        continue; // skip unresolvable entries
+                    // 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 ?? ""}`;
+                    if (indexedAssetIdentities.has(identityKey))
+                        continue;
+                    indexedAssetIdentities.add(identityKey);
                     const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                     const searchText = buildSearchText(entry);
                     const entryWithSize = attachFileSize(entry, entryPath);
@@ -335,6 +354,43 @@ async function enhanceStashWithLlm(llmConfig, stash, _dirPath, files) {
     }
     return { entries: enhanced };
 }
+/**
+ * Build a map from base filename (without extension) to full path for quick lookups.
+ */
+export function buildFileBasenameMap(files) {
+    const map = new Map();
+    for (const file of files) {
+        const base = path.basename(file, path.extname(file));
+        // Only keep first match per base name to avoid ambiguity
+        if (!map.has(base))
+            map.set(base, file);
+    }
+    return map;
+}
+/**
+ * Try to match a filename-less entry to an actual file in the directory.
+ *
+ * Matching strategy (in priority order):
+ *   1. Exact basename match: entry.name === filename without extension
+ *   2. Last path segment match: for entries with names like "dir/sub-entry",
+ *      try matching the last segment
+ *   3. Fallback: first file in the directory, or null if no files are available
+ */
+export function matchEntryToFile(entryName, fileMap, files) {
+    // Exact match on entry name
+    const exact = fileMap.get(entryName);
+    if (exact)
+        return exact;
+    // Try last segment for hierarchical names (e.g. "corpus/agentic-patterns/foo")
+    const lastSegment = entryName.split("/").pop() ?? entryName;
+    if (lastSegment !== entryName) {
+        const segmentMatch = fileMap.get(lastSegment);
+        if (segmentMatch)
+            return segmentMatch;
+    }
+    // Fallback to first file, or null if no files are available
+    return files[0] || null;
+}
 export function buildSearchText(entry) {
     const parts = [entry.name.replace(/[-_]/g, " ")];
     if (entry.description)
@@ -347,6 +403,8 @@ export function buildSearchText(entry) {
         parts.push(entry.aliases.join(" "));
     if (entry.searchHints)
         parts.push(entry.searchHints.join(" "));
+    if (entry.usage)
+        parts.push(entry.usage.join(" "));
     if (entry.intent) {
         if (entry.intent.when)
             parts.push(entry.intent.when);

package/dist/local-search.js

@@ -99,7 +99,15 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
     if (!query) {
         const typeFilter = searchType === "any" ? undefined : searchType;
         const allEntries = getAllEntries(db, typeFilter);
-        const selected = allEntries.slice(0, limit);
+        // Deduplicate by file path — multiple entries can share the same file
+        const seenFilePaths = new Set();
+        const uniqueEntries = allEntries.filter((ie) => {
+            if (seenFilePaths.has(ie.filePath))
+                return false;
+            seenFilePaths.add(ie.filePath);
+            return true;
+        });
+        const selected = uniqueEntries.slice(0, limit);
         const hits = await Promise.all(selected.map((ie) => buildDbHit({
             entry: ie.entry,
             path: ie.filePath,
@@ -137,6 +145,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         }
     }
     // Merge results using RRF
+    // Issue #15: "hybrid" for results appearing in both FTS and vec results.
     const scored = [];
     const seenIds = new Set();
     // Process FTS results
@@ -146,7 +155,8 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
         const embedRank = embedRankMap.get(id);
         const embedRrf = embedRank !== undefined ? 1 / (RRF_K + embedRank) : 0;
         const rrfScore = ftsRrf + embedRrf;
-        const rankingMode = embedRrf > 0 ? "semantic" : "fts";
+        // Issue #15: combined FTS+vec results are "hybrid", not "semantic"
+        const rankingMode = embedRrf > 0 ? "hybrid" : "fts";
         scored.push({ id, entry: result.entry, filePath: result.filePath, score: rrfScore, rankingMode });
     }
     // Add vec-only results not already in FTS results
@@ -172,45 +182,63 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allStashDi
             }
         }
     }
-    // Apply boosts as multiplicative factors
+    // Apply boosts as multiplicative factors (all boosts in a single phase
+    // so that sort order and displayed scores are always consistent — Issue #1).
     const queryTokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     for (const item of scored) {
         const entry = item.entry;
         let boostSum = 0;
-        // Tag boost
+        // Tag boost — capped at 0.30 (Issue #7)
         if (entry.tags) {
+            let tagBoost = 0;
             for (const tag of entry.tags) {
                 if (queryTokens.some((t) => tag.toLowerCase() === t)) {
-                    boostSum += 0.15;
+                    tagBoost += 0.15;
                 }
             }
+            boostSum += Math.min(0.3, tagBoost);
         }
-        // Search hint boost
+        // Search hint boost — capped at 0.24 (Issue #7)
         if (entry.searchHints) {
+            let hintBoost = 0;
             for (const hint of entry.searchHints) {
                 const hintLower = hint.toLowerCase();
                 for (const token of queryTokens) {
                     if (hintLower.includes(token)) {
-                        boostSum += 0.12;
+                        hintBoost += 0.12;
                         break;
                     }
                 }
             }
+            boostSum += Math.min(0.24, hintBoost);
         }
         // Name boost
         const nameLower = entry.name.toLowerCase().replace(/[-_]/g, " ");
         if (queryTokens.some((t) => nameLower.includes(t))) {
             boostSum += 0.1;
         }
+        // Quality boost (Issue #1: moved from buildDbHit to single-phase)
+        const qualityBoost = entry.quality === "generated" ? 0 : 0.05;
+        boostSum += qualityBoost;
+        // Confidence boost (Issue #1: moved from buildDbHit to single-phase)
+        const confidenceBoost = typeof entry.confidence === "number" ? Math.min(0.05, Math.max(0, entry.confidence) * 0.05) : 0;
+        boostSum += confidenceBoost;
         item.score = item.score * (1 + boostSum);
     }
-    scored.sort((a, b) => b.score - a.score);
+    // Issue #14: deterministic tiebreaker on equal scores
+    scored.sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name));
+    // Deduplicate by file path — keep only the highest-scored entry per file.
+    // Multiple .stash.json entries can map to the same file (e.g. entries without
+    // a filename field all collapse to files[0]). Showing the same path/ref
+    // multiple times clutters results.
+    const deduped = deduplicateByPath(scored);
     const rankMs = Date.now() - tRank0;
-    const selected = scored.slice(0, limit);
+    const selected = deduped.slice(0, limit);
     const hits = await Promise.all(selected.map(({ entry, filePath, score, rankingMode }) => buildDbHit({
         entry,
         path: filePath,
-        score: Math.round(score * 100) / 100,
+        // Issue #8: round to 4 decimal places instead of 2
+        score: Math.round(score * 10000) / 10000,
         query,
         rankingMode,
         defaultStashDir: stashDir,
@@ -233,9 +261,10 @@ async function tryVecScores(db, query, k, config) {
         const vecResults = searchVec(db, queryEmbedding, k);
         const scores = new Map();
         for (const { id, distance } of vecResults) {
-            // Convert L2 distance to cosine similarity (vectors are normalized)
-            const cosineSim = 1 - (distance * distance) / 2;
-            scores.set(id, Math.max(0, cosineSim));
+            // Convert L2 distance to cosine similarity (vectors are normalized).
+            // Issue #3: guard against NaN/Infinity from sqlite-vec edge cases.
+            const raw = 1 - (distance * distance) / 2;
+            scores.set(id, Number.isFinite(raw) ? Math.max(0, raw) : 0);
         }
         return scores;
     }
@@ -249,15 +278,18 @@ async function substringSearch(query, searchType, limit, stashDir, sources, conf
     const assets = await indexAssets(stashDir, searchType);
     const matched = assets.filter((asset) => !query || buildSearchText(asset.entry).includes(query));
     if (!query) {
-        return Promise.all(matched
-            .sort(compareAssets)
-            .slice(0, limit)
-            .map((asset) => assetToSearchHit(asset, query, stashDir, sources, config)));
+        const sorted = matched.sort(compareAssets);
+        const unique = deduplicateAssetsByPath(sorted);
+        return Promise.all(unique.slice(0, limit).map((asset) => assetToSearchHit(asset, query, stashDir, sources, config)));
     }
     // Score and sort by relevance
     const scored = matched.map((asset) => ({ asset, score: scoreSubstringMatch(asset.entry, query) }));
     scored.sort((a, b) => b.score - a.score || compareAssets(a.asset, b.asset));
-    return Promise.all(scored.slice(0, limit).map(({ asset, score }) => assetToSearchHit(asset, query, stashDir, sources, config, score)));
+    // Deduplicate by path — keep highest-scored entry per file
+    const dedupedScored = deduplicateByPath(scored.map((s) => ({ ...s, filePath: s.asset.path })));
+    return Promise.all(dedupedScored
+        .slice(0, limit)
+        .map(({ asset, score }) => assetToSearchHit(asset, query, stashDir, sources, config, score)));
 }
 function scoreSubstringMatch(entry, query) {
     const tokens = query.split(/\s+/).filter(Boolean);
@@ -282,16 +314,22 @@ function scoreSubstringMatch(entry, query) {
     if (tokens.some((t) => descLower.includes(t))) {
         score += 0.05;
     }
-    return Math.round(Math.min(1, score) * 100) / 100;
+    // Issue #8: round to 4 decimal places instead of 2
+    return Math.round(Math.min(1, score) * 10000) / 10000;
 }
 // ── Hit building ────────────────────────────────────────────────────────────
 export async function buildDbHit(input) {
     const entryStashDir = findSourceForPath(input.path, input.sources)?.path ?? input.defaultStashDir;
     const canonical = deriveCanonicalAssetNameFromStashRoot(input.entry.type, entryStashDir, input.path);
     const refName = canonical && !canonical.startsWith("../") && !canonical.startsWith("..\\") ? canonical : input.entry.name;
+    // Issue #1: Quality and confidence boosts are now applied in the main scoring
+    // phase (searchDatabase). buildDbHit receives the already-final score and
+    // passes it through without further multiplication. We still compute the
+    // boost values here for buildWhyMatched reporting.
     const qualityBoost = input.entry.quality === "generated" ? 0 : 0.05;
     const confidenceBoost = typeof input.entry.confidence === "number" ? Math.min(0.05, Math.max(0, input.entry.confidence) * 0.05) : 0;
-    const score = Math.round(input.score * (1 + qualityBoost + confidenceBoost) * 100) / 100;
+    // Issue #8: round to 4 decimal places, no boost multiplication
+    const score = Math.round(input.score * 10000) / 10000;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost);
     const source = findSourceForPath(input.path, input.sources);
     const editable = isEditable(input.path, input.config);
@@ -316,13 +354,24 @@ export async function buildDbHit(input) {
     }
     return hit;
 }
-export function buildWhyMatched(entry, query, rankingMode, qualityBoost, confidenceBoost) {
-    const reasons = [rankingMode === "semantic" ? "semantic similarity" : "fts bm25 relevance"];
+export function buildWhyMatched(entry, query, 
+// Issue #15: added "hybrid" ranking mode
+rankingMode, qualityBoost, confidenceBoost) {
+    // Issue #15: "hybrid" label for combined FTS+vec results
+    const reasons = [
+        rankingMode === "hybrid"
+            ? "hybrid (fts + semantic)"
+            : rankingMode === "semantic"
+                ? "semantic similarity"
+                : "fts bm25 relevance",
+    ];
     const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
     const name = entry.name.toLowerCase();
     const tags = entry.tags?.join(" ").toLowerCase() ?? "";
     const searchHints = entry.searchHints?.join(" ").toLowerCase() ?? "";
     const aliases = entry.aliases?.join(" ").toLowerCase() ?? "";
+    // Issue #12: include description in match reasons
+    const desc = entry.description?.toLowerCase() ?? "";
     if (tokens.some((t) => name.includes(t)))
         reasons.push("matched name tokens");
     if (tokens.some((t) => tags.includes(t)))
@@ -331,6 +380,9 @@ export function buildWhyMatched(entry, query, rankingMode, qualityBoost, confide
         reasons.push("matched searchHints");
     if (tokens.some((t) => aliases.includes(t)))
         reasons.push("matched aliases");
+    // Issue #12: report description matches
+    if (tokens.some((t) => desc.includes(t)))
+        reasons.push("matched description");
     if (qualityBoost > 0)
         reasons.push("curated metadata boost");
     if (confidenceBoost > 0)
@@ -413,10 +465,27 @@ async function indexAssets(stashDir, type) {
                 continue;
             stash = generated;
         }
+        // Build a lookup for matching filename-less entries to actual files
+        const fileBasenameMap = new Map();
+        for (const file of files) {
+            const base = path.basename(file, path.extname(file));
+            if (!fileBasenameMap.has(base))
+                fileBasenameMap.set(base, file);
+        }
         for (const entry of stash.entries) {
             if (filterType && entry.type !== filterType)
                 continue;
-            const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+            let entryPath;
+            if (entry.filename) {
+                entryPath = path.join(dirPath, entry.filename);
+            }
+            else {
+                // Try matching entry name to a file by basename
+                entryPath =
+                    fileBasenameMap.get(entry.name) ??
+                        fileBasenameMap.get(entry.name.split("/").pop() ?? "") ??
+                        (files[0] || dirPath);
+            }
             assets.push({ entry, path: entryPath });
         }
     }
@@ -427,3 +496,31 @@ function compareAssets(a, b) {
         return a.entry.type.localeCompare(b.entry.type);
     return a.entry.name.localeCompare(b.entry.name);
 }
+/**
+ * Deduplicate scored results by file path, keeping only the highest-scored
+ * entry per unique path. Sorts by score descending internally to ensure the
+ * precondition is always met regardless of caller (Issue #4).
+ */
+function deduplicateByPath(items) {
+    // Issue #4: sort inside to enforce the descending-score precondition
+    const sorted = [...items].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const seen = new Set();
+    return sorted.filter((item) => {
+        if (seen.has(item.filePath))
+            return false;
+        seen.add(item.filePath);
+        return true;
+    });
+}
+/**
+ * Deduplicate IndexedAsset[] by path, keeping the first (highest-priority) entry.
+ */
+function deduplicateAssetsByPath(assets) {
+    const seen = new Set();
+    return assets.filter((asset) => {
+        if (seen.has(asset.path))
+            return false;
+        seen.add(asset.path);
+        return true;
+    });
+}

package/dist/stash-providers/context-hub.js

@@ -0,0 +1,389 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fetchWithRetry } from "../common";
+import { ConfigError, NotFoundError, UsageError } from "../errors";
+import { parseFrontmatter, toStringOrUndefined } from "../frontmatter";
+import { extractFrontmatterOnly, extractLineRange, extractSection, formatToc, parseMarkdownToc } from "../markdown";
+import { getRegistryIndexCacheDir } from "../paths";
+import { extractTarGzSecure } from "../registry-install";
+import { registerStashProvider } from "../stash-provider-factory";
+/** Cache TTL before refreshing the mirrored repo (12 hours). */
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+/** Maximum stale age allowed when refresh fails (7 days). */
+const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+const CONTEXT_HUB_REF_PREFIX = "context-hub://";
+class ContextHubStashProvider {
+    type = "context-hub";
+    name;
+    repo;
+    constructor(config) {
+        this.repo = parseContextHubRepoUrl(config.url ?? "");
+        this.name = config.name ?? `${this.repo.owner}/${this.repo.repo}`;
+    }
+    async search(options) {
+        try {
+            const entries = await this.loadEntries();
+            const filtered = entries
+                .filter((entry) => matchesType(entry, options.type))
+                .map((entry) => ({ entry, score: scoreEntry(entry, options.query) }))
+                .filter(({ score }) => options.query.trim() === "" || score > 0)
+                .sort((a, b) => b.score - a.score || a.entry.sortName.localeCompare(b.entry.sortName))
+                .slice(0, options.limit);
+            return {
+                hits: filtered.map(({ entry, score }) => entryToHit(entry, score)),
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { hits: [], warnings: [`Stash ${this.name}: ${message}`] };
+        }
+    }
+    async show(ref, view) {
+        const filePath = parseContextHubRef(ref);
+        const repoDir = await this.loadRepoDir();
+        const resolved = resolveCachedFilePath(repoDir, filePath);
+        if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+            throw new NotFoundError(`Context Hub asset not found: ${filePath}`);
+        }
+        const raw = fs.readFileSync(resolved, "utf8");
+        const parsed = parseFrontmatter(raw);
+        const relFromContent = path.posix.normalize(path.relative(path.join(repoDir, "content"), resolved).replace(/\\/g, "/"));
+        const author = sanitizeString(relFromContent.split("/")[0] ?? "") || "unknown";
+        const name = sanitizeString(toStringOrUndefined(parsed.data.name) ?? path.basename(path.dirname(resolved)));
+        const description = sanitizeString(toStringOrUndefined(parsed.data.description), 1000);
+        const assetType = path.basename(resolved) === "SKILL.md" ? "skill" : "knowledge";
+        const content = renderContentForView(raw, view);
+        return {
+            type: assetType,
+            name: `${author}/${name}`,
+            path: ref,
+            content,
+            description,
+            editable: false,
+            origin: this.type,
+            action: `Context Hub content from ${this.repo.canonicalUrl}`,
+        };
+    }
+    canShow(ref) {
+        return ref.trim().startsWith(CONTEXT_HUB_REF_PREFIX);
+    }
+    async loadEntries() {
+        const cachePaths = getCachePaths(this.repo.canonicalUrl);
+        const index = await ensureContextHubMirror(this.repo, cachePaths);
+        return index.entries;
+    }
+    async loadRepoDir() {
+        const cachePaths = getCachePaths(this.repo.canonicalUrl);
+        await ensureContextHubMirror(this.repo, cachePaths, { requireRepoDir: true });
+        return cachePaths.repoDir;
+    }
+}
+registerStashProvider("context-hub", (config) => new ContextHubStashProvider(config));
+function getCachePaths(repoUrl) {
+    const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
+    const rootDir = path.join(getRegistryIndexCacheDir(), `context-hub-${key}`);
+    return {
+        rootDir,
+        archivePath: path.join(rootDir, "repo.tar.gz"),
+        repoDir: path.join(rootDir, "repo"),
+        indexPath: path.join(rootDir, "index.json"),
+    };
+}
+async function ensureContextHubMirror(repo, cachePaths, options) {
+    const requireRepoDir = options?.requireRepoDir === true;
+    const cached = readCachedIndex(cachePaths.indexPath);
+    if (cached && !isExpired(cached.mtime, CACHE_TTL_MS) && (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+        return { entries: cached.entries };
+    }
+    try {
+        fs.mkdirSync(cachePaths.rootDir, { recursive: true });
+        await downloadArchive(buildTarballUrl(repo), cachePaths.archivePath);
+        extractTarGzSecure(cachePaths.archivePath, cachePaths.repoDir);
+        const entries = buildContextHubIndex(cachePaths.repoDir);
+        writeCachedIndex(cachePaths.indexPath, entries);
+        return { entries };
+    }
+    catch (err) {
+        if (cached &&
+            !isExpired(cached.mtime, CACHE_STALE_MS) &&
+            (!requireRepoDir || hasExtractedRepo(cachePaths.repoDir))) {
+            return { entries: cached.entries };
+        }
+        throw err;
+    }
+}
+function hasExtractedRepo(repoDir) {
+    try {
+        return fs.statSync(repoDir).isDirectory() && fs.statSync(path.join(repoDir, "content")).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function readCachedIndex(indexPath) {
+    try {
+        const stat = fs.statSync(indexPath);
+        const raw = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+        if (!Array.isArray(raw))
+            return null;
+        const entries = raw.filter(isContextHubEntry);
+        return { entries, mtime: stat.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+function writeCachedIndex(indexPath, entries) {
+    const dir = path.dirname(indexPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = `${indexPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(entries), { encoding: "utf8", mode: 0o600 });
+    fs.renameSync(tmpPath, indexPath);
+}
+async function downloadArchive(url, destination) {
+    const response = await fetchWithRetry(url, undefined, { timeout: 120_000, retries: 1 });
+    if (!response.ok) {
+        throw new Error(`Failed to download Context Hub archive (${response.status}) from ${url}`);
+    }
+    const BunRuntime = globalThis.Bun;
+    if (BunRuntime?.write) {
+        await BunRuntime.write(destination, response);
+        return;
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    fs.writeFileSync(destination, Buffer.from(arrayBuffer));
+}
+function buildContextHubIndex(repoDir) {
+    const contentDir = path.join(repoDir, "content");
+    if (!fs.existsSync(contentDir) || !fs.statSync(contentDir).isDirectory()) {
+        throw new Error(`Context Hub repo at ${repoDir} is missing a content/ directory`);
+    }
+    const files = findEntryFiles(contentDir);
+    const entries = [];
+    for (const filePath of files) {
+        const entry = buildEntry(repoDir, contentDir, filePath);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+function findEntryFiles(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...findEntryFiles(full));
+        }
+        else if (entry.name === "DOC.md" || entry.name === "SKILL.md") {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function buildEntry(repoDir, contentDir, fullPath) {
+    const raw = fs.readFileSync(fullPath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const relPath = path.posix.normalize(path.relative(repoDir, fullPath).replace(/\\/g, "/"));
+    const relFromContent = path.posix.normalize(path.relative(contentDir, fullPath).replace(/\\/g, "/"));
+    const segments = relFromContent.split("/");
+    const author = sanitizeString(segments[0] ?? "");
+    if (!author)
+        return null;
+    const name = sanitizeString(toStringOrUndefined(parsed.data.name) ?? path.basename(path.dirname(fullPath)));
+    if (!name)
+        return null;
+    const metadata = (parsed.data.metadata ?? {});
+    const tags = parseCsv(metadata.tags);
+    const language = sanitizeString(toStringOrUndefined(metadata.languages));
+    const version = sanitizeString(toStringOrUndefined(metadata.versions));
+    const id = `${author}/${name}`;
+    const assetType = path.basename(fullPath) === "SKILL.md" ? "skill" : "knowledge";
+    return {
+        id,
+        ref: makeContextHubRef(relPath),
+        assetType,
+        filePath: relPath,
+        description: sanitizeString(toStringOrUndefined(parsed.data.description), 1000),
+        tags,
+        language: language || undefined,
+        version: version || undefined,
+        sortName: `${id}:${language ?? ""}:${version ?? ""}`,
+    };
+}
+function scoreEntry(entry, query) {
+    const trimmed = query.trim().toLowerCase();
+    if (!trimmed)
+        return 1;
+    const tokens = trimmed.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return 1;
+    const haystacks = [
+        { text: entry.id.toLowerCase(), weight: 4 },
+        { text: entry.description?.toLowerCase() ?? "", weight: 2 },
+        { text: (entry.tags ?? []).join(" ").toLowerCase(), weight: 2 },
+        { text: entry.language?.toLowerCase() ?? "", weight: 1 },
+        { text: entry.version?.toLowerCase() ?? "", weight: 1 },
+    ];
+    let matched = 0;
+    let score = 0;
+    for (const token of tokens) {
+        let tokenScore = 0;
+        for (const { text, weight } of haystacks) {
+            if (!text)
+                continue;
+            if (text === token)
+                tokenScore = Math.max(tokenScore, weight * 2);
+            else if (text.includes(token))
+                tokenScore = Math.max(tokenScore, weight);
+        }
+        if (tokenScore > 0) {
+            matched++;
+            score += tokenScore;
+        }
+    }
+    if (matched === 0)
+        return 0;
+    const coverage = matched / tokens.length;
+    return Math.round((score * coverage + (entry.id.toLowerCase() === trimmed ? 5 : 0)) * 1000) / 1000;
+}
+function matchesType(entry, requested) {
+    if (!requested || requested === "any")
+        return true;
+    return entry.assetType === requested;
+}
+function entryToHit(entry, score) {
+    const details = [entry.language, entry.version].filter(Boolean).join(" • ");
+    const description = [entry.description, details].filter(Boolean).join(" — ") || undefined;
+    return {
+        type: entry.assetType,
+        name: entry.id,
+        path: entry.ref,
+        ref: entry.ref,
+        origin: "context-hub",
+        editable: false,
+        description,
+        tags: entry.tags,
+        action: `akm show ${entry.ref}`,
+        score,
+    };
+}
+function renderContentForView(content, view) {
+    if (!view || view.mode === "full")
+        return content;
+    switch (view.mode) {
+        case "toc":
+            return formatToc(parseMarkdownToc(content));
+        case "frontmatter":
+            return extractFrontmatterOnly(content) ?? "(no frontmatter)";
+        case "section": {
+            const section = extractSection(content, view.heading);
+            if (!section) {
+                throw new UsageError(`Section not found: ${view.heading}`);
+            }
+            return section.content;
+        }
+        case "lines":
+            return extractLineRange(content, view.start, view.end);
+        default:
+            return content;
+    }
+}
+function resolveCachedFilePath(repoDir, filePath) {
+    const normalized = path.posix.normalize(filePath.replace(/\\/g, "/"));
+    if (!normalized.startsWith("content/")) {
+        throw new UsageError(`Invalid Context Hub ref: ${filePath}`);
+    }
+    const resolved = path.resolve(repoDir, normalized);
+    const root = path.resolve(repoDir);
+    if (!resolved.startsWith(root + path.sep)) {
+        throw new UsageError(`Invalid Context Hub ref: ${filePath}`);
+    }
+    return resolved;
+}
+function buildTarballUrl(repo) {
+    return `https://github.com/${repo.owner}/${repo.repo}/archive/refs/heads/${repo.ref}.tar.gz`;
+}
+function parseContextHubRepoUrl(rawUrl) {
+    if (!rawUrl) {
+        throw new ConfigError("Context Hub provider requires a GitHub repository URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError(`Context Hub URL is not valid: "${rawUrl}"`);
+    }
+    if (parsed.protocol !== "https:") {
+        throw new ConfigError(`Context Hub URL must use https://, got "${parsed.protocol}"`);
+    }
+    if (parsed.hostname !== "github.com") {
+        throw new ConfigError(`Context Hub provider only supports github.com URLs, got "${parsed.hostname}"`);
+    }
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    if (segments.length < 2) {
+        throw new ConfigError(`Context Hub URL must point to a GitHub repository, got "${rawUrl}"`);
+    }
+    const owner = sanitizeString(segments[0]);
+    const repo = sanitizeString(segments[1].replace(/\.git$/i, ""));
+    let ref = "main";
+    if (segments[2] === "tree" && segments.length >= 4) {
+        ref = sanitizeString(segments.slice(3).join("/"), 255) || "main";
+    }
+    if (!owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) {
+        throw new ConfigError(`Unsupported Context Hub repository URL: "${rawUrl}"`);
+    }
+    if (!ref || ref.includes("..") || !/^[A-Za-z0-9._/-]+$/.test(ref)) {
+        throw new ConfigError(`Unsupported Context Hub branch/ref in URL: "${rawUrl}"`);
+    }
+    return {
+        owner,
+        repo,
+        ref,
+        canonicalUrl: `https://github.com/${owner}/${repo}/tree/${ref}`,
+    };
+}
+function makeContextHubRef(filePath) {
+    return `${CONTEXT_HUB_REF_PREFIX}${path.posix.normalize(filePath)}`;
+}
+function parseContextHubRef(ref) {
+    const trimmed = ref.trim();
+    if (!trimmed.startsWith(CONTEXT_HUB_REF_PREFIX)) {
+        throw new UsageError(`Invalid Context Hub ref: ${ref}`);
+    }
+    const filePath = trimmed.slice(CONTEXT_HUB_REF_PREFIX.length);
+    if (!filePath) {
+        throw new UsageError(`Invalid Context Hub ref: ${ref}`);
+    }
+    return filePath;
+}
+function parseCsv(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const items = value
+        .split(",")
+        .map((item) => sanitizeString(item.trim(), 100))
+        .filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+function sanitizeString(value, maxLength = 255) {
+    if (typeof value !== "string")
+        return "";
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: strips untrusted control chars from remote metadata
+    return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, maxLength);
+}
+function isExpired(mtimeMs, ttlMs) {
+    return Date.now() - mtimeMs > ttlMs;
+}
+function isContextHubEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const obj = value;
+    return (typeof obj.id === "string" &&
+        typeof obj.ref === "string" &&
+        (obj.assetType === "knowledge" || obj.assetType === "skill") &&
+        typeof obj.filePath === "string" &&
+        typeof obj.sortName === "string");
+}
+export { ContextHubStashProvider, buildContextHubIndex, makeContextHubRef, parseContextHubRef, parseContextHubRepoUrl };

package/dist/stash-providers/index.js

@@ -6,4 +6,5 @@
  * side-effect imports that were duplicated in stash-search.ts and stash-show.ts.
  */
 import "./filesystem";
+import "./context-hub";
 import "./openviking";

package/dist/stash-search.js

@@ -128,12 +128,37 @@ export function registerActionBuilder(type, builder) {
 // Re-export for consumers that were already importing from stash-search
 export { buildLocalAction, rendererForType };
 // ── Helpers ──────────────────────────────────────────────────────────────────
-function mergeStashHits(localHits, additionalHits, limit) {
+/**
+ * Merge hits from local stash and additional providers using Reciprocal Rank
+ * Fusion (RRF). Each list is already internally sorted by relevance. RRF
+ * assigns scores based on rank position rather than raw score values, so
+ * sources with incompatible score scales (e.g. RRF ~0.01-0.03 vs 0-1 or
+ * 0-100) are merged fairly.
+ */
+export function mergeStashHits(localHits, additionalHits, limit) {
     if (additionalHits.length === 0)
         return localHits.slice(0, limit);
-    const all = [...localHits, ...additionalHits];
-    all.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
-    return all.slice(0, limit);
+    const RRF_K = 60;
+    const scoreMap = new Map();
+    const applyRankedList = (hits) => {
+        for (let i = 0; i < hits.length; i++) {
+            const key = hits[i].path ?? hits[i].ref ?? hits[i].name;
+            const rrf = 1 / (RRF_K + i + 1);
+            const existing = scoreMap.get(key);
+            if (existing) {
+                existing.score += rrf;
+            }
+            else {
+                scoreMap.set(key, { hit: hits[i], score: rrf });
+            }
+        }
+    };
+    applyRankedList(localHits);
+    applyRankedList(additionalHits);
+    return [...scoreMap.values()]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map((v) => ({ ...v.hit, score: Math.round(v.score * 10000) / 10000 }));
 }
 function normalizeLimit(limit) {
     if (typeof limit !== "number" || Number.isNaN(limit) || limit <= 0) {
@@ -151,8 +176,46 @@ export function parseSearchSource(source) {
         return "stash";
     throw new UsageError(`Invalid value for --source: ${String(source)}. Expected one of: stash|registry|both`);
 }
-function mergeSearchHits(localHits, registryHits, limit) {
-    const all = [...localHits, ...registryHits];
-    all.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
-    return all.slice(0, limit);
+/**
+ * Merge stash hits and registry hits using RRF, same rationale as mergeStashHits.
+ */
+export function mergeSearchHits(localHits, registryHits, limit) {
+    if (registryHits.length === 0)
+        return localHits.slice(0, limit);
+    if (localHits.length === 0)
+        return registryHits.slice(0, limit);
+    const RRF_K = 60;
+    const scoreMap = new Map();
+    const applyStashList = (hits) => {
+        for (let i = 0; i < hits.length; i++) {
+            const key = hits[i].path ?? hits[i].ref ?? hits[i].name;
+            const rrf = 1 / (RRF_K + i + 1);
+            const existing = scoreMap.get(key);
+            if (existing) {
+                existing.score += rrf;
+            }
+            else {
+                scoreMap.set(key, { hit: hits[i], score: rrf });
+            }
+        }
+    };
+    const applyRegistryList = (hits) => {
+        for (let i = 0; i < hits.length; i++) {
+            const key = `registry:${hits[i].id ?? hits[i].name}`;
+            const rrf = 1 / (RRF_K + i + 1);
+            const existing = scoreMap.get(key);
+            if (existing) {
+                existing.score += rrf;
+            }
+            else {
+                scoreMap.set(key, { hit: hits[i], score: rrf });
+            }
+        }
+    };
+    applyStashList(localHits);
+    applyRegistryList(registryHits);
+    return [...scoreMap.values()]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map((v) => ({ ...v.hit, score: Math.round(v.score * 10000) / 10000 }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "CLI tool to search, open, and run extension assets from an akm stash directory.",
   "keywords": [