akm-cli 0.5.0-rc3 → 0.5.0-rc4

package/dist/cli.js

@@ -320,6 +320,12 @@ function formatPlain(command, result, detail) {
         case "index": {
             const indexResult = result;
             let out = `Indexed ${indexResult.totalEntries ?? 0} entries from ${indexResult.directoriesScanned ?? 0} directories (mode: ${indexResult.mode ?? "unknown"})`;
+            const warnings = indexResult.warnings;
+            if (Array.isArray(warnings) && warnings.length > 0) {
+                out += `\nWarnings (${warnings.length}):`;
+                for (const message of warnings)
+                    out += `\n  - ${String(message)}`;
+            }
             const verification = indexResult.verification;
             if (verification?.ok === false && verification.message) {
                 out += `\nVerification: ${String(verification.message)}`;
@@ -458,6 +464,8 @@ function formatPlain(command, result, detail) {
                 const ver = typeof src.version === "string" ? ` v${src.version}` : "";
                 const prov = typeof src.provider === "string" ? ` (${src.provider})` : "";
                 const flags = [];
+                if (typeof src.wiki === "string")
+                    flags.push(`wiki:${src.wiki}`);
                 if (src.updatable === true)
                     flags.push("updatable");
                 if (src.writable === true)
@@ -472,6 +480,12 @@ function formatPlain(command, result, detail) {
             const scanned = index?.directoriesScanned ?? 0;
             const total = index?.totalEntries ?? 0;
             const lines = [`Installed ${r.ref} (${scanned} directories scanned, ${total} total assets indexed)`];
+            const warnings = index?.warnings;
+            if (Array.isArray(warnings) && warnings.length > 0) {
+                lines.push(`Warnings (${warnings.length}):`);
+                for (const message of warnings)
+                    lines.push(`  - ${String(message)}`);
+            }
             const installed = r.installed;
             const audit = installed?.audit;
             if (audit && typeof audit === "object") {
@@ -2483,7 +2497,7 @@ const wikiCreateCommand = defineCommand({
 const wikiRegisterCommand = defineCommand({
     meta: {
         name: "register",
-        description: "Register an existing directory or repo as a first-class wiki without copying or mutating it",
+        description: "Register an existing directory or repo as a first-class wiki without copying or mutating it; refreshes source and wiki search state immediately",
     },
     args: {
         name: { type: "positional", description: "Wiki name (lowercase, digits, hyphens)", required: true },
@@ -2543,7 +2557,7 @@ const wikiShowCommand = defineCommand({
 const wikiRemoveCommand = defineCommand({
     meta: {
         name: "remove",
-        description: "Remove a wiki. Preserves raw/ by default; pass --with-sources to also delete raw/",
+        description: "Remove a wiki and refresh the index. Preserves raw/ by default; pass --with-sources to also delete raw/",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
@@ -2565,8 +2579,10 @@ const wikiRemoveCommand = defineCommand({
             }
             const withSources = Boolean(args["with-sources"]);
             const { removeWiki } = await import("./wiki.js");
+            const { akmIndex } = await import("./indexer");
             const stashDir = resolveStashDir();
             const result = removeWiki(stashDir, args.name, { withSources });
+            await akmIndex({ stashDir });
             output("wiki-remove", result);
         });
     },
@@ -2591,7 +2607,7 @@ const wikiPagesCommand = defineCommand({
 const wikiSearchCommand = defineCommand({
     meta: {
         name: "search",
-        description: "Search wiki pages within a single wiki (scoped wrapper over `akm search --type wiki`; excludes raw/schema/index/log)",
+        description: "Search wiki pages within a single wiki (scoped wrapper over `akm search --type wiki`; excludes raw/schema/index/log and returns canonical wiki refs)",
     },
     args: {
         name: { type: "positional", description: "Wiki name", required: true },
@@ -2744,7 +2760,18 @@ const main = defineCommand({
 });
 const CONFIG_SUBCOMMAND_SET = new Set(["path", "list", "get", "set", "unset"]);
 const VAULT_SUBCOMMAND_SET = new Set(["list", "show", "create", "set", "unset", "load"]);
-const WIKI_SUBCOMMAND_SET = new Set(["create", "list", "show", "remove", "pages", "search", "stash", "lint", "ingest"]);
+const WIKI_SUBCOMMAND_SET = new Set([
+    "create",
+    "register",
+    "list",
+    "show",
+    "remove",
+    "pages",
+    "search",
+    "stash",
+    "lint",
+    "ingest",
+]);
 const SHOW_VIEW_MODES = new Set(["toc", "frontmatter", "full", "section", "lines"]);
 // citty reads process.argv directly and does not accept a custom argv array,
 // so we must replace process.argv with the normalized version before runMain.

package/dist/indexer.js

@@ -80,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, allStashSources, isIncremental, builtAtMs, doFullDelete);
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allStashSources, isIncremental, builtAtMs, doFullDelete);
         onProgress({
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -166,6 +166,7 @@ export async function akmIndex(options) {
             mode: isIncremental ? "incremental" : "full",
             directoriesScanned: scannedDirs,
             directoriesSkipped: skippedDirs,
+            ...(warnings.length > 0 ? { warnings } : {}),
             verification,
             timing: {
                 totalMs: tEnd - t0,
@@ -185,6 +186,7 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
+    const warnings = [];
     const seenPaths = new Set();
     const dirsNeedingLlm = [];
     const dirRecords = [];
@@ -261,6 +263,8 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
                 const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
                 if (uncoveredFiles.length > 0) {
                     const generated = await generateMetadataFlat(currentStashDir, uncoveredFiles);
+                    if (generated.warnings?.length)
+                        warnings.push(...generated.warnings);
                     if (generated.entries.length > 0) {
                         stash = { entries: [...stash.entries, ...generated.entries] };
                         generatedCount += generated.entries.length;
@@ -269,6 +273,8 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
             }
             if (!stash) {
                 const generated = await generateMetadataFlat(currentStashDir, files);
+                if (generated.warnings?.length)
+                    warnings.push(...generated.warnings);
                 if (generated.entries.length > 0) {
                     stash = { entries: generated.entries };
                     generatedCount += generated.entries.length;
@@ -351,7 +357,7 @@ async function indexEntries(db, allStashSources, isIncremental, builtAtMs, doFul
         }
     });
     insertTransaction();
-    return { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm };
+    return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
 }
 async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     if (!config.llm || dirsNeedingLlm.length === 0)

package/dist/installed-kits.js

@@ -29,6 +29,7 @@ export async function akmListSources(input) {
         sources.push({
             name,
             kind,
+            wiki: stash.wikiName,
             path: stash.path,
             provider: isRemote ? stash.type : undefined,
             updatable: false,
@@ -44,6 +45,7 @@ export async function akmListSources(input) {
         sources.push({
             name: entry.id,
             kind,
+            wiki: entry.wikiName,
             path: entry.stashRoot,
             ref: entry.ref,
             version: entry.resolvedVersion,

package/dist/local-search.js

@@ -29,6 +29,15 @@ export function buildLocalAction(type, ref) {
     const builder = ACTION_BUILDERS[type];
     return builder ? builder(ref) : `akm show ${ref}`;
 }
+function resolveSearchHitRef(entry, refName, source) {
+    if (source?.wikiName) {
+        return makeAssetRef(entry.type, entry.name);
+    }
+    return makeAssetRef(entry.type, refName, source?.registryId);
+}
+function resolveSearchHitOrigin(source) {
+    return source?.wikiName ? null : (source?.registryId ?? null);
+}
 // ── Main search entrypoint ───────────────────────────────────────────────────
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
@@ -448,20 +457,21 @@ export async function buildDbHit(input) {
     const score = Math.round(input.score * 10000) / 10000;
     const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost, input.utilityBoosted);
     const source = findSourceForPath(input.path, input.sources);
+    const ref = resolveSearchHitRef(input.entry, refName, source);
     const editable = isEditable(input.path, input.config);
     const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
     const hit = {
         type: input.entry.type,
         name: input.entry.name,
         path: input.path,
-        ref: makeAssetRef(input.entry.type, refName, source?.registryId),
-        origin: source?.registryId ?? null,
+        ref,
+        origin: resolveSearchHitOrigin(source),
         editable,
         ...(!editable ? { editHint: buildEditHint(input.path, input.entry.type, refName, source?.registryId) } : {}),
         description: input.entry.description,
         tags: input.entry.tags,
         size: deriveSize(input.entry.fileSize),
-        action: buildLocalAction(input.entry.type, makeAssetRef(input.entry.type, refName, source?.registryId)),
+        action: buildLocalAction(input.entry.type, ref),
         score,
         whyMatched,
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
@@ -523,7 +533,7 @@ rankingMode, qualityBoost, confidenceBoost, utilityBoosted) {
 async function assetToSearchHit(asset, stashDir, sources, config, score) {
     const source = findSourceForPath(asset.path, sources);
     const editable = isEditable(asset.path, config);
-    const ref = makeAssetRef(asset.entry.type, asset.entry.name, source?.registryId);
+    const ref = resolveSearchHitRef(asset.entry, asset.entry.name, source);
     const fileSize = readFileSize(asset.path);
     const size = deriveSize(fileSize);
     const estimatedTokens = typeof fileSize === "number" ? Math.round(fileSize / 4) : undefined;
@@ -532,7 +542,7 @@ async function assetToSearchHit(asset, stashDir, sources, config, score) {
         name: asset.entry.name,
         path: asset.path,
         ref,
-        origin: source?.registryId ?? null,
+        origin: resolveSearchHitOrigin(source),
         editable,
         ...(!editable
             ? { editHint: buildEditHint(asset.path, asset.entry.type, asset.entry.name, source?.registryId) }

package/dist/metadata.js

@@ -362,6 +362,7 @@ function mergeParameters(existing, additional) {
 // ── Metadata Generation ─────────────────────────────────────────────────────
 export async function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
+    const warnings = [];
     const pkgMeta = extractPackageMetadata(dirPath);
     for (const file of files) {
         const ext = path.extname(file).toLowerCase();
@@ -428,7 +429,13 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
             const renderer = await getRenderer(match.renderer);
             if (renderer?.extractMetadata) {
                 const renderCtx = buildRenderContext(fileCtx, match, [typeRoot]);
-                renderer.extractMetadata(entry, renderCtx);
+                try {
+                    renderer.extractMetadata(entry, renderCtx);
+                }
+                catch (error) {
+                    warnings.push(buildMetadataSkipWarning(file, assetType, error));
+                    continue;
+                }
             }
         }
         // Priority 4: Filename heuristics (fallback)
@@ -447,7 +454,7 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
         entry.filename = path.basename(file);
         entries.push(entry);
     }
-    return { entries };
+    return warnings.length > 0 ? { entries, warnings } : { entries };
 }
 /**
  * Generate metadata for files using the matcher system instead of a fixed asset type.
@@ -458,6 +465,7 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
  */
 export async function generateMetadataFlat(stashRoot, files) {
     const entries = [];
+    const warnings = [];
     const pkgMetaCache = new Map();
     for (const file of files) {
         if (!shouldIndexStashFile(stashRoot, file))
@@ -534,7 +542,13 @@ export async function generateMetadataFlat(stashRoot, files) {
         const renderer = await getRenderer(match.renderer);
         if (renderer?.extractMetadata) {
             const renderCtx = buildRenderContext(ctx, match, [stashRoot]);
-            renderer.extractMetadata(entry, renderCtx);
+            try {
+                renderer.extractMetadata(entry, renderCtx);
+            }
+            catch (error) {
+                warnings.push(buildMetadataSkipWarning(file, assetType, error));
+                continue;
+            }
         }
         // Filename heuristics fallback
         if (!entry.description) {
@@ -550,7 +564,13 @@ export async function generateMetadataFlat(stashRoot, files) {
         entry.filename = path.basename(file);
         entries.push(entry);
     }
-    return { entries };
+    return warnings.length > 0 ? { entries, warnings } : { entries };
+}
+function buildMetadataSkipWarning(filePath, assetType, error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const warning = `Skipped malformed ${assetType} asset at ${filePath}: ${detail}`;
+    warn(warning);
+    return warning;
 }
 function normalizeTerms(values) {
     const normalized = new Set();

package/dist/stash-add.js

@@ -72,31 +72,36 @@ async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
     // Check for duplicates in stashes[]
     const stashes = [...(config.stashes ?? [])];
     const existing = stashes.find((s) => s.type === "filesystem" && s.path && path.resolve(s.path) === resolvedPath);
+    let persistedEntry;
     if (!existing) {
-        const entry = {
+        persistedEntry = {
             type: "filesystem",
             path: resolvedPath,
             name: wikiName ?? toReadableId(resolvedPath),
             ...(wikiName ? { wikiName } : {}),
         };
-        stashes.push(entry);
+        stashes.push(persistedEntry);
         saveConfig({ ...config, stashes });
     }
-    else if (wikiName && existing.wikiName !== wikiName) {
-        existing.wikiName = wikiName;
-        saveConfig({ ...config, stashes });
+    else {
+        if (wikiName && existing.wikiName !== wikiName) {
+            existing.wikiName = wikiName;
+            saveConfig({ ...config, stashes });
+        }
+        persistedEntry = existing;
     }
     const index = await akmIndex({ stashDir });
     const updatedConfig = loadConfig();
     return {
         schemaVersion: 1,
         stashDir,
-        ref,
+        ref: wikiName ?? ref,
         stashSource: {
             type: "filesystem",
             path: resolvedPath,
-            name: toReadableId(resolvedPath),
+            name: persistedEntry.name ?? toReadableId(resolvedPath),
             stashRoot: resolvedPath,
+            ...(persistedEntry.wikiName ? { wiki: persistedEntry.wikiName } : {}),
         },
         config: {
             stashCount: updatedConfig.stashes?.length ?? 0,
@@ -107,6 +112,7 @@ async function addLocalStashSource(ref, sourcePath, stashDir, wikiName) {
             totalEntries: index.totalEntries,
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
+            ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
 }
@@ -145,12 +151,13 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
     return {
         schemaVersion: 1,
         stashDir,
-        ref,
+        ref: wikiName ?? ref,
         stashSource: {
             type: "website",
             url: normalizedUrl,
             name: entry.name,
             stashRoot: cachePaths.stashDir,
+            ...(entry.wikiName ? { wiki: entry.wikiName } : {}),
         },
         config: {
             stashCount: updatedConfig.stashes?.length ?? 0,
@@ -161,6 +168,7 @@ async function addWebsiteStashSource(ref, stashDir, name, options, wikiName) {
             totalEntries: index.totalEntries,
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
+            ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
 }
@@ -227,6 +235,7 @@ async function addRegistryKit(ref, stashDir, trustThisInstall, writable, wikiNam
             totalEntries: index.totalEntries,
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
+            ...(index.warnings?.length ? { warnings: index.warnings } : {}),
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.5.0-rc3",
+  "version": "0.5.0-rc4",
   "type": "module",
   "description": "akm (Agent Kit Manager) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [