akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/indexer/metadata.js

@@ -1,20 +1,21 @@
 import fs from "node:fs";
 import path from "node:path";
 import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, } from "../core/asset-spec";
-import { isAssetType } from "../core/common";
-import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
+import { asNonEmptyString, isAssetType, writeFileAtomic } from "../core/common";
+import { parseFrontmatter } from "../core/frontmatter";
 import { isVerbose, warn } from "../core/warn";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
+import { applyMetadataContributors } from "./metadata-contributors";
 export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
 // ── Quality semantics (v1 spec §4.2) ────────────────────────────────────────
 /**
- * Well-known quality values. `generated` and `curated` are included in
+ * Well-known quality values. `generated`, `curated`, and `enriched` are included in
  * default search; `proposed` is excluded by default and opt-in via
  * `--include-proposed`. Unknown values warn once and remain searchable.
  */
-export const KNOWN_QUALITY_VALUES = new Set(["generated", "curated", "proposed"]);
+export const KNOWN_QUALITY_VALUES = new Set(["generated", "curated", "enriched", "proposed"]);
 /** Tracks unknown quality values we've already warned about (one warn per value per process). */
 const warnedUnknownQualityValues = new Set();
 /**
@@ -80,20 +81,7 @@ export function loadStashFile(dirPath, options) {
 }
 export function writeStashFile(dirPath, stash) {
     const filePath = stashFilePath(dirPath);
-    const tmpPath = `${filePath}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    try {
-        fs.writeFileSync(tmpPath, `${JSON.stringify(stash, null, 2)}\n`, "utf8");
-        fs.renameSync(tmpPath, filePath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+    writeFileAtomic(filePath, `${JSON.stringify(stash, null, 2)}\n`);
 }
 /**
  * Validate and normalize a raw object into a `StashEntry`.
@@ -185,20 +173,24 @@ export function validateStashEntry(entry) {
     if (typeof e.pageKind === "string" && e.pageKind.trim().length > 0) {
         result.pageKind = e.pageKind.trim();
     }
-    if (Array.isArray(e.xrefs)) {
-        const filtered = e.xrefs
-            .filter((x) => typeof x === "string" && x.trim().length > 0)
-            .map((x) => x.trim());
-        if (filtered.length > 0)
-            result.xrefs = filtered;
-    }
-    if (Array.isArray(e.sources)) {
-        const filtered = e.sources
-            .filter((s) => typeof s === "string" && s.trim().length > 0)
-            .map((s) => s.trim());
-        if (filtered.length > 0)
-            result.sources = filtered;
+    const xrefs = normalizeNonEmptyStringList(e.xrefs);
+    if (xrefs)
+        result.xrefs = xrefs;
+    const sources = normalizeNonEmptyStringList(e.sources);
+    if (sources)
+        result.sources = sources;
+    if (typeof e.beliefState === "string" && e.beliefState.trim().length > 0) {
+        result.beliefState = e.beliefState.trim();
     }
+    const supersededBy = normalizeNonEmptyStringList(e.supersededBy);
+    if (supersededBy)
+        result.supersededBy = supersededBy;
+    const contradictedBy = normalizeNonEmptyStringList(e.contradictedBy);
+    if (contradictedBy)
+        result.contradictedBy = contradictedBy;
+    const currentBeliefRefs = normalizeNonEmptyStringList(e.currentBeliefRefs);
+    if (currentBeliefRefs)
+        result.currentBeliefRefs = currentBeliefRefs;
     if (typeof e.scope === "object" && e.scope !== null && !Array.isArray(e.scope)) {
         const scope = normalizeScopeObject(e.scope);
         if (scope)
@@ -275,9 +267,9 @@ function normalizeIntent(value) {
         return undefined;
     const raw = value;
     const intent = {};
-    const when = toStringOrUndefined(raw.when);
-    const input = toStringOrUndefined(raw.input);
-    const output = toStringOrUndefined(raw.output);
+    const when = asNonEmptyString(raw.when);
+    const input = asNonEmptyString(raw.input);
+    const output = asNonEmptyString(raw.output);
     if (when)
         intent.when = when;
     if (input)
@@ -290,7 +282,7 @@ function normalizeStringListOrUndefined(value) {
     return normalizeNonEmptyStringList(value);
 }
 export function applyCuratedFrontmatter(entry, fmData) {
-    const description = toStringOrUndefined(fmData.description);
+    const description = asNonEmptyString(fmData.description);
     if (description) {
         entry.description = description;
         entry.source = "frontmatter";
@@ -311,18 +303,30 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const examples = normalizeStringListOrUndefined(fmData.examples);
     if (examples)
         entry.examples = examples;
-    const run = toStringOrUndefined(fmData.run);
+    const run = asNonEmptyString(fmData.run);
     if (run)
         entry.run = run;
-    const setup = toStringOrUndefined(fmData.setup);
+    const setup = asNonEmptyString(fmData.setup);
     if (setup)
         entry.setup = setup;
-    const cwd = toStringOrUndefined(fmData.cwd);
+    const cwd = asNonEmptyString(fmData.cwd);
     if (cwd)
         entry.cwd = cwd;
-    const quality = toStringOrUndefined(fmData.quality);
+    const quality = asNonEmptyString(fmData.quality);
     if (quality)
         entry.quality = normalizeQuality(quality);
+    const beliefState = asNonEmptyString(fmData.beliefState);
+    if (beliefState)
+        entry.beliefState = beliefState;
+    const supersededBy = normalizeStringListOrUndefined(fmData.supersededBy);
+    if (supersededBy)
+        entry.supersededBy = supersededBy;
+    const contradictedBy = normalizeStringListOrUndefined(fmData.contradictedBy);
+    if (contradictedBy)
+        entry.contradictedBy = contradictedBy;
+    const currentBeliefRefs = normalizeStringListOrUndefined(fmData.currentBeliefRefs);
+    if (currentBeliefRefs)
+        entry.currentBeliefRefs = currentBeliefRefs;
     const intent = normalizeIntent(fmData.intent);
     if (intent)
         entry.intent = intent;
@@ -416,6 +420,12 @@ export function shouldIndexStashFile(stashRoot, file, options) {
     const segments = relPath.split(/[\\/]+/).filter(Boolean);
     if (segments.length === 0)
         return true;
+    // Skip vault .env files that have a sibling .sensitive marker file.
+    if (segments[0] === "vaults" && (file.endsWith(".env") || path.basename(file) === ".env")) {
+        const markerPath = file.replace(/\.env$/, ".sensitive");
+        if (fs.existsSync(markerPath))
+            return false;
+    }
     if (options?.treatStashRootAsWikiRoot) {
         return !(segments.length === 1 && WIKI_INFRA_FILES.has(segments[0]));
     }
@@ -681,7 +691,137 @@ function mergeAliases(existing, generated) {
     const merged = normalizeTerms([...(existing ?? []), ...generated]);
     return merged.length > 0 ? merged : undefined;
 }
+// ── Enrichment Completeness ─────────────────────────────────────────────────
+/**
+ * Returns `true` when a stash entry already has enough LLM-quality metadata
+ * that calling the LLM would produce no meaningful improvement.
+ *
+ * An entry is considered complete when ALL of the following hold:
+ * - `description` is a non-empty string
+ * - `tags` is a non-empty array
+ * - `searchHints` is a non-empty array
+ *
+ * This predicate is used by `enhanceDirsWithLlm` to skip the LLM call for
+ * entries that were previously enriched and already carry all three fields.
+ * Pass `reEnrich = true` in the caller to bypass this check.
+ */
+export function isEnrichmentComplete(entry) {
+    const hasDescription = typeof entry.description === "string" && entry.description.trim().length > 0;
+    const hasTags = Array.isArray(entry.tags) && entry.tags.length > 0;
+    const hasSearchHints = Array.isArray(entry.searchHints) && entry.searchHints.length > 0;
+    return hasDescription && hasTags && hasSearchHints;
+}
 // ── Metadata Generation ─────────────────────────────────────────────────────
+/**
+ * Shared pipeline (steps 2-6) for building a single StashEntry from a file.
+ *
+ * Both `generateMetadata` and `generateMetadataFlat` perform identical work
+ * once the initial `entry` object has been seeded with type and canonical name.
+ * This helper encapsulates that shared pipeline so the two callers only differ
+ * in how they determine the asset type and canonical name (step 1):
+ *
+ *  - `generateMetadata`     — explicit `assetType` arg + `deriveCanonicalAssetName`
+ *  - `generateMetadataFlat` — type from `runMatchers()` + `deriveCanonicalAssetNameFromStashRoot`
+ *
+ * @param file        Absolute path to the file being processed.
+ * @param assetType   Resolved asset type string (already validated by caller).
+ * @param canonicalName Resolved canonical name (already computed by caller).
+ * @param dirPath     Directory containing the file (used for tag fallback).
+ * @param pkgMeta     Pre-loaded package.json metadata for this directory (may be null/undefined).
+ * @param stashRoot   Stash root used for renderer search hints context.
+ * @param ctx         FileContext for the file (may be pre-built by the caller).
+ * @param match       Pre-resolved MatchResult when available (from `generateMetadataFlat`).
+ * @returns The populated entry, or `{ skip: true, warning: string }` when the
+ *          renderer throws and the file should be dropped.
+ */
+async function buildEntryFromFile(file, assetType, canonicalName, dirPath, pkgMeta, stashRoot, ctx, match) {
+    const ext = path.extname(file).toLowerCase();
+    const baseName = path.basename(file, ext);
+    const entry = {
+        name: canonicalName,
+        type: assetType,
+        quality: "generated",
+        confidence: 0.55,
+        source: "filename",
+    };
+    // Priority 1: Package.json metadata
+    if (pkgMeta) {
+        if (pkgMeta.description && !entry.description) {
+            entry.description = pkgMeta.description;
+            entry.source = "package";
+            entry.confidence = 0.8;
+        }
+        if (pkgMeta.keywords && pkgMeta.keywords.length > 0)
+            entry.tags = normalizeTerms(pkgMeta.keywords);
+    }
+    // Priority 2: Frontmatter (for .md files -- overrides package.json description)
+    if (ext === ".md") {
+        const content = ctx.content();
+        const parsed = parseFrontmatter(content);
+        applyCuratedFrontmatter(entry, parsed.data);
+        // Extract parameters from frontmatter params: key
+        const fmParams = extractFrontmatterParameters(parsed.data);
+        if (fmParams)
+            entry.parameters = fmParams;
+        // Pass wiki-pattern frontmatter through onto the entry
+        applyWikiFrontmatter(entry, parsed.data);
+        // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
+        if (entry.type === "command") {
+            const cmdParams = extractCommandParameters(parsed.content);
+            if (cmdParams) {
+                entry.parameters = mergeParameters(entry.parameters, cmdParams);
+            }
+        }
+    }
+    // Extract @param from script files.
+    // Vault files (.env) are deliberately excluded — their contents are secrets
+    // and must never be parsed for @param or any other metadata that could
+    // embed a value into the entry.
+    if (ext !== ".md" && assetType !== "vault") {
+        const content = ctx.content();
+        const scriptParams = extractScriptParameters(file, content);
+        if (scriptParams)
+            entry.parameters = scriptParams;
+        applyCommentMetadata(entry, extractCommentMetadata(file, content));
+    }
+    // Priority 3: Renderer metadata extraction
+    // When no pre-resolved match is available (generateMetadata path), run
+    // matchers now so the renderer can extract type-specific metadata.
+    const resolvedMatch = match ?? (await runMatchers(ctx));
+    if (resolvedMatch) {
+        const renderer = await getRenderer(resolvedMatch.renderer);
+        if (renderer) {
+            const renderCtx = buildRenderContext(ctx, resolvedMatch, [stashRoot]);
+            try {
+                await applyMetadataContributors(entry, {
+                    rendererName: renderer.name,
+                    renderContext: renderCtx,
+                });
+            }
+            catch (error) {
+                return {
+                    skip: true,
+                    warning: buildMetadataSkipWarning(file, assetType, error),
+                };
+            }
+        }
+    }
+    // Priority 4: Filename heuristics (fallback)
+    if (!entry.description) {
+        entry.description = fileNameToDescription(baseName);
+        entry.source = "filename";
+        entry.confidence = Math.min(entry.confidence ?? 0.55, 0.55);
+    }
+    if (!entry.tags || entry.tags.length === 0) {
+        entry.tags = extractTagsFromPath(file, dirPath);
+    }
+    entry.tags = normalizeTerms(entry.tags ?? []);
+    entry.aliases = mergeAliases(entry.aliases, buildAliases(canonicalName, entry.tags));
+    // Search hints are only generated when LLM is configured (via enhanceStashWithLlm)
+    // Heuristic search hints are too noisy to be useful for search quality
+    entry.filename = path.basename(file);
+    return entry;
+}
 export async function generateMetadata(dirPath, assetType, files, typeRoot = dirPath) {
     const entries = [];
     const warnings = [];
@@ -694,84 +834,16 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
         if (!isRelevantAssetFile(assetType, fileName))
             continue;
         const canonicalName = deriveCanonicalAssetName(assetType, typeRoot, file) ?? baseName;
-        const entry = {
-            name: canonicalName,
-            type: assetType,
-            quality: "generated",
-            confidence: 0.55,
-            source: "filename",
-        };
-        // Priority 1: Package.json metadata
-        if (pkgMeta) {
-            if (pkgMeta.description && !entry.description) {
-                entry.description = pkgMeta.description;
-                entry.source = "package";
-                entry.confidence = 0.8;
-            }
-            if (pkgMeta.keywords && pkgMeta.keywords.length > 0)
-                entry.tags = normalizeTerms(pkgMeta.keywords);
-        }
-        // Priority 2: Frontmatter (for .md files -- overrides package.json description)
-        if (ext === ".md") {
-            const content = fs.readFileSync(file, "utf8");
-            const parsed = parseFrontmatter(content);
-            applyCuratedFrontmatter(entry, parsed.data);
-            // Extract parameters from frontmatter params: key
-            const fmParams = extractFrontmatterParameters(parsed.data);
-            if (fmParams)
-                entry.parameters = fmParams;
-            // Pass wiki-pattern frontmatter through onto the entry
-            applyWikiFrontmatter(entry, parsed.data);
-            // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
-            if (entry.type === "command") {
-                const cmdParams = extractCommandParameters(parsed.content);
-                if (cmdParams) {
-                    entry.parameters = mergeParameters(entry.parameters, cmdParams);
-                }
-            }
-        }
-        // Extract @param from script files.
-        // Vault files (.env) are deliberately excluded — their contents are secrets
-        // and must never be parsed for @param or any other metadata that could
-        // embed a value into the entry.
-        if (ext !== ".md" && assetType !== "vault") {
-            const content = fs.readFileSync(file, "utf8");
-            const scriptParams = extractScriptParameters(file, content);
-            if (scriptParams)
-                entry.parameters = scriptParams;
-            applyCommentMetadata(entry, extractCommentMetadata(file, content));
-        }
-        // Priority 3: Type-specific metadata extraction (e.g. TOC for knowledge, comments for scripts)
+        // Build file context with typeRoot as the stash root so renderer context
+        // and search hints are scoped to the type directory.
         const fileCtx = buildFileContext(typeRoot, file);
-        const match = await runMatchers(fileCtx);
-        if (match) {
-            const renderer = await getRenderer(match.renderer);
-            if (renderer?.extractMetadata) {
-                const renderCtx = buildRenderContext(fileCtx, match, [typeRoot]);
-                try {
-                    renderer.extractMetadata(entry, renderCtx);
-                }
-                catch (error) {
-                    warnings.push(buildMetadataSkipWarning(file, assetType, error));
-                    continue;
-                }
-            }
-        }
-        // Priority 4: Filename heuristics (fallback)
-        if (!entry.description) {
-            entry.description = fileNameToDescription(baseName);
-            entry.source = "filename";
-            entry.confidence = Math.min(entry.confidence ?? 0.55, 0.55);
-        }
-        if (!entry.tags || entry.tags.length === 0) {
-            entry.tags = extractTagsFromPath(file, dirPath);
+        // Step 1: type is explicit; delegate steps 2-6 to the shared pipeline.
+        const result = await buildEntryFromFile(file, assetType, canonicalName, dirPath, pkgMeta, typeRoot, fileCtx, null);
+        if ("skip" in result) {
+            warnings.push(result.warning);
+            continue;
         }
-        entry.tags = normalizeTerms(entry.tags ?? []);
-        entry.aliases = mergeAliases(entry.aliases, buildAliases(canonicalName, entry.tags));
-        // Search hints are only generated when LLM is configured (via enhanceStashWithLlm)
-        // Heuristic search hints are too noisy to be useful for search quality
-        entry.filename = path.basename(file);
-        entries.push(entry);
+        entries.push(result);
     }
     return warnings.length > 0 ? { entries, warnings } : { entries };
 }
@@ -789,6 +861,7 @@ export async function generateMetadataFlat(stashRoot, files) {
     for (const file of files) {
         if (!shouldIndexStashFile(stashRoot, file))
             continue;
+        // Step 1: determine type and canonical name via the matcher system.
         const ctx = buildFileContext(stashRoot, file);
         const match = await runMatchers(ctx);
         if (!match)
@@ -802,83 +875,20 @@ export async function generateMetadataFlat(stashRoot, files) {
         const ext = path.extname(file).toLowerCase();
         const baseName = path.basename(file, ext);
         const canonicalName = deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, file) ?? baseName;
-        const entry = {
-            name: canonicalName,
-            type: assetType,
-            quality: "generated",
-            confidence: 0.55,
-            source: "filename",
-        };
-        // Package.json metadata
+        // Resolve package.json metadata with a per-directory cache.
         const dirPath = path.dirname(file);
         if (!pkgMetaCache.has(dirPath)) {
             pkgMetaCache.set(dirPath, extractPackageMetadata(dirPath));
         }
         const pkgMeta = pkgMetaCache.get(dirPath);
-        if (pkgMeta) {
-            if (pkgMeta.description && !entry.description) {
-                entry.description = pkgMeta.description;
-                entry.source = "package";
-                entry.confidence = 0.8;
-            }
-            if (pkgMeta.keywords?.length)
-                entry.tags = normalizeTerms(pkgMeta.keywords);
-        }
-        // Frontmatter
-        if (ext === ".md") {
-            const content = ctx.content();
-            const parsed = parseFrontmatter(content);
-            applyCuratedFrontmatter(entry, parsed.data);
-            // Extract parameters from frontmatter params: key
-            const fmParams = extractFrontmatterParameters(parsed.data);
-            if (fmParams)
-                entry.parameters = fmParams;
-            // Pass wiki-pattern frontmatter through onto the entry
-            applyWikiFrontmatter(entry, parsed.data);
-            // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
-            if (entry.type === "command") {
-                const cmdParams = extractCommandParameters(parsed.content);
-                if (cmdParams) {
-                    entry.parameters = mergeParameters(entry.parameters, cmdParams);
-                }
-            }
-        }
-        // Extract @param from script files.
-        // Vault files (.env) are deliberately excluded — their contents are secrets
-        // and must never be parsed for @param or any other metadata that could
-        // embed a value into the entry.
-        if (ext !== ".md" && assetType !== "vault") {
-            const content = ctx.content();
-            const scriptParams = extractScriptParameters(file, content);
-            if (scriptParams)
-                entry.parameters = scriptParams;
-            applyCommentMetadata(entry, extractCommentMetadata(file, content));
-        }
-        // Renderer metadata extraction
-        const renderer = await getRenderer(match.renderer);
-        if (renderer?.extractMetadata) {
-            const renderCtx = buildRenderContext(ctx, match, [stashRoot]);
-            try {
-                renderer.extractMetadata(entry, renderCtx);
-            }
-            catch (error) {
-                warnings.push(buildMetadataSkipWarning(file, assetType, error));
-                continue;
-            }
-        }
-        // Filename heuristics fallback
-        if (!entry.description) {
-            entry.description = fileNameToDescription(baseName);
-            entry.source = "filename";
-            entry.confidence = Math.min(entry.confidence ?? 0.55, 0.55);
-        }
-        if (!entry.tags || entry.tags.length === 0) {
-            entry.tags = extractTagsFromPath(file, dirPath);
+        // Steps 2-6: delegate to the shared pipeline; pass the pre-resolved match
+        // so we don't run matchers a second time.
+        const result = await buildEntryFromFile(file, assetType, canonicalName, dirPath, pkgMeta, stashRoot, ctx, match);
+        if ("skip" in result) {
+            warnings.push(result.warning);
+            continue;
         }
-        entry.tags = normalizeTerms(entry.tags ?? []);
-        entry.aliases = mergeAliases(entry.aliases, buildAliases(canonicalName, entry.tags));
-        entry.filename = path.basename(file);
-        entries.push(entry);
+        entries.push(result);
     }
     return warnings.length > 0 ? { entries, warnings } : { entries };
 }
@@ -980,17 +990,6 @@ export function extractDescriptionFromComments(filePath) {
         return hashLines.join(" ");
     return null;
 }
-export function extractFrontmatterDescription(filePath) {
-    let content;
-    try {
-        content = fs.readFileSync(filePath, "utf8");
-    }
-    catch {
-        return null;
-    }
-    const parsed = parseFrontmatter(content);
-    return toStringOrUndefined(parsed.data.description) ?? null;
-}
 export function extractPackageMetadata(dirPath) {
     const pkgPath = path.join(dirPath, "package.json");
     if (!fs.existsSync(pkgPath))

package/dist/indexer/path-resolver.js

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveAssetPathFromName, TYPE_DIRS } from "../core/asset-spec";
+import { isWithin } from "../core/common";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve";
+import { lookup } from "./indexer";
+import { resolveSourceEntries } from "./search-source";
+function normalizeRef(ref) {
+    return typeof ref === "string" ? parseAssetRef(ref) : ref;
+}
+function buildDiskCandidates(sourcePath, ref, preserveDirectNameFallback) {
+    const typeDir = path.join(sourcePath, TYPE_DIRS[ref.type] ?? `${ref.type}s`);
+    const candidates = [
+        resolveAssetPathFromName(ref.type, typeDir, ref.name),
+        path.join(sourcePath, ref.type, `${ref.name}.md`),
+        path.join(sourcePath, ref.type, ref.name),
+    ];
+    if (preserveDirectNameFallback) {
+        candidates.push(path.join(sourcePath, `${ref.name}.md`), path.join(sourcePath, ref.name));
+    }
+    return candidates;
+}
+function resolveDirectoryEntry(filePath, directoryIndexNames) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isFile())
+        return filePath;
+    if (!stat.isDirectory())
+        return null;
+    for (const indexName of directoryIndexNames) {
+        const candidate = path.join(filePath, indexName);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+            return candidate;
+    }
+    return null;
+}
+async function resolveViaIndex(ref) {
+    try {
+        const entry = await lookup(ref);
+        return entry?.filePath ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveViaDisk(ref, options) {
+    let sources = resolveSourceEntries(options.stashDir);
+    if (options.honorOrigin !== false) {
+        sources = resolveSourcesForOrigin(ref.origin, sources);
+    }
+    const directoryIndexNames = options.directoryIndexNames ?? ["SKILL.md"];
+    const preserveDirectNameFallback = options.preserveDirectNameFallback ?? true;
+    for (const source of sources) {
+        if (options.writableDirSet && !options.writableDirSet.has(path.resolve(source.path)))
+            continue;
+        const candidates = buildDiskCandidates(source.path, ref, preserveDirectNameFallback);
+        for (const candidate of candidates) {
+            if (!fs.existsSync(candidate))
+                continue;
+            const resolved = resolveDirectoryEntry(candidate, directoryIndexNames);
+            if (!resolved)
+                continue;
+            const resolvedRoot = fs.realpathSync(source.path);
+            const realTarget = fs.realpathSync(resolved);
+            if (!isWithin(realTarget, resolvedRoot))
+                continue;
+            return realTarget;
+        }
+    }
+    return null;
+}
+export async function resolveAssetPath(ref, options = {}) {
+    const parsed = normalizeRef(ref);
+    const mode = options.mode ?? "index-first";
+    if (mode !== "disk-only") {
+        const indexed = await resolveViaIndex(parsed);
+        if (indexed)
+            return indexed;
+        if (mode === "index-only")
+            return null;
+    }
+    return resolveViaDisk(parsed, options);
+}