@unbrained/pm-cli 2026.5.18 → 2026.5.27

package/dist/cli/commands/search.js

@@ -1,8 +1,9 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5d7fe7a0-57cd-5bd9-ab50-36f6cc73ca5c")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7b4219a0-215b-5cfa-a437-f979968a70c4")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
+import { isPathWithinDirectory } from "../../core/fs/path-utils.js";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks } from "../../core/extensions/index.js";
 import { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../../core/extensions/runtime-registrations.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -13,7 +14,8 @@ import { executeVectorQuery, resolveVectorStores, } from "../../core/search/vect
 import { buildEventCorpus, buildPlanFlatCorpus, buildReminderCorpus } from "../../core/search/corpus.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
-import { normalizeStatusInput } from "../../core/item/status.js";
+import { toItemRecord } from "../../core/item/item-record.js";
+import { isTerminalStatus } from "../../core/item/status.js";
 import { collectRuntimeFilterValues, matchesRuntimeFilters } from "../../core/schema/runtime-field-filters.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -34,15 +36,68 @@ const DEFAULT_COMPACT_SEARCH_FIELDS = [
     "score",
     "matched_fields",
 ];
+const SEARCH_HIT_FIELD_KEYS = new Set(["score", "matched_fields"]);
+const SEARCH_ITEM_FIELD_KEYS = new Set([
+    "id",
+    "title",
+    "description",
+    "type",
+    "status",
+    "priority",
+    "tags",
+    "created_at",
+    "updated_at",
+    "deadline",
+    "assignee",
+    "author",
+    "estimated_minutes",
+    "acceptance_criteria",
+    "dependencies",
+    "comments",
+    "notes",
+    "learnings",
+    "reminders",
+    "events",
+    "files",
+    "tests",
+    "docs",
+    "close_reason",
+    "parent",
+    "reviewer",
+    "risk",
+    "confidence",
+    "sprint",
+    "release",
+    "blocked_by",
+    "blocked_reason",
+    "reporter",
+    "severity",
+    "environment",
+    "repro_steps",
+    "resolution",
+    "expected_result",
+    "actual_result",
+    "affected_version",
+    "fixed_version",
+    "component",
+    "regression",
+    "customer_impact",
+    "definition_of_ready",
+    "order",
+    "rank",
+    "goal",
+    "objective",
+    "value",
+    "impact",
+    "outcome",
+    "why_now",
+    "plan",
+]);
 const LONG_QUERY_TOKEN_THRESHOLD = 2;
 const LONG_QUERY_TITLE_EXACT_BONUS = 120;
 const LONG_QUERY_PHRASE_MULTIPLIER = 6;
 const IMPLICIT_HYBRID_EMBEDDING_TIMEOUT_MS = 8_000;
 const IMPLICIT_HYBRID_VECTOR_TIMEOUT_MS = 8_000;
-function isTerminal(status, statusRegistry) {
-    const normalized = normalizeStatusInput(status, statusRegistry) ?? status;
-    return statusRegistry.terminal_statuses.has(normalized);
-}
 function classifyImplicitSemanticFallbackReason(error) {
     const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
     if (message.includes("timed out") || message.includes("timeout")) {
@@ -67,9 +122,16 @@ function buildImplicitSemanticFallbackWarning(error) {
     }
     return "search_implicit_semantic_fallback:error:using_keyword_mode";
 }
-function parseMode(raw, context) {
+// Explicit --semantic/--hybrid searches must never hard-fail an agent when the
+// embedding/vector backend is unreachable or unconfigured: degrade to keyword
+// search and surface a machine-readable warning instead of an unknown_error.
+function buildExplicitSemanticFallbackWarning(requestedMode, error) {
+    const reason = classifyImplicitSemanticFallbackReason(error);
+    return `search_${requestedMode}_fallback:${reason}:using_keyword_mode`;
+}
+function parseMode(raw, _context) {
     if (raw === undefined) {
-        return context.hasProvider && context.hasVectorStore ? "hybrid" : "keyword";
+        return "keyword";
     }
     const normalized = raw.trim().toLowerCase();
     if (normalized !== "keyword" && normalized !== "semantic" && normalized !== "hybrid") {
@@ -141,6 +203,26 @@ function parseProjectionConfig(options) {
         fields: [],
     };
 }
+function validateSearchProjectionFields(projection, runtimeFieldRegistry) {
+    if (projection.mode !== "fields") {
+        return;
+    }
+    const runtimeKeys = new Set(runtimeFieldRegistry.definitions.flatMap((field) => [field.key, field.metadata_key]));
+    const unknown = projection.fields.filter((field) => {
+        const normalized = field.trim();
+        const itemKey = normalized.startsWith("item.") ? normalized.slice("item.".length) : normalized;
+        return !SEARCH_HIT_FIELD_KEYS.has(normalized) && !SEARCH_ITEM_FIELD_KEYS.has(itemKey) && !runtimeKeys.has(itemKey);
+    });
+    if (unknown.length > 0) {
+        throw new PmCliError(`Unknown search --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
+            examples: [
+                "pm search <query> --fields id,title,status,score",
+                "pm search <query> --fields id,title,item.description,matched_fields",
+            ],
+            nextSteps: ["Use item.<field> for explicit item metadata fields, or run pm search --help for projection examples."],
+        });
+    }
+}
 function parseTokens(query) {
     const normalized = normalizeSearchPhrase(query);
     if (!normalized) {
@@ -148,20 +230,36 @@ function parseTokens(query) {
     }
     return normalized.split(/\s+/).filter(Boolean);
 }
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function textEntries(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "object" && entry !== null && typeof entry.text === "string")
+        : [];
+}
+function dependencyEntries(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "object" &&
+            entry !== null &&
+            typeof entry.id === "string" &&
+            typeof entry.kind === "string")
+        : [];
+}
 function collectExactPhraseFields(document) {
     const item = document.metadata;
     return [
         item.title,
         item.description,
         item.status,
-        item.tags.join(" "),
+        stringArray(item.tags).join(" "),
         document.body,
-        (item.comments ?? []).map((entry) => entry.text).join(" "),
-        (item.notes ?? []).map((entry) => entry.text).join(" "),
-        (item.learnings ?? []).map((entry) => entry.text).join(" "),
+        textEntries(item.comments).map((entry) => entry.text).join(" "),
+        textEntries(item.notes).map((entry) => entry.text).join(" "),
+        textEntries(item.learnings).map((entry) => entry.text).join(" "),
         buildReminderCorpus(item).join(" "),
         buildEventCorpus(item).join(" "),
-        (item.dependencies ?? []).map((entry) => `${entry.id} ${entry.kind}`).join(" "),
+        dependencyEntries(item.dependencies).map((entry) => `${entry.id} ${entry.kind}`).join(" "),
         buildPlanFlatCorpus(item),
     ];
 }
@@ -192,7 +290,7 @@ function applyFilters(items, options, typeRegistry, runtimeFieldFilters) {
         const item = document.metadata;
         if (typeFilter && item.type !== typeFilter)
             return false;
-        if (tagFilter && !item.tags.includes(tagFilter))
+        if (tagFilter && !stringArray(item.tags).includes(tagFilter))
             return false;
         if (priorityFilter !== undefined && item.priority !== priorityFilter)
             return false;
@@ -244,13 +342,6 @@ function collectLinkedPaths(item) {
     }
     return [...deduped.values()];
 }
-function isPathWithinRoot(root, resolvedPath) {
-    const relative = path.relative(root, resolvedPath);
-    if (relative.length === 0) {
-        return true;
-    }
-    return !relative.startsWith("..") && !path.isAbsolute(relative);
-}
 async function resolveContainmentRoot(root) {
     const resolved = path.resolve(root);
     try {
@@ -283,7 +374,7 @@ async function loadLinkedCorpus(document, roots) {
             continue;
         }
         const resolved = path.resolve(containmentRoot.resolved, linkedPath.path);
-        if (!isPathWithinRoot(containmentRoot.resolved, resolved)) {
+        if (!isPathWithinDirectory(containmentRoot.resolved, resolved)) {
             continue;
         }
         let linkedRealpath;
@@ -293,7 +384,7 @@ async function loadLinkedCorpus(document, roots) {
         catch {
             continue;
         }
-        if (!isPathWithinRoot(containmentRoot.realpath, linkedRealpath)) {
+        if (!isPathWithinDirectory(containmentRoot.realpath, linkedRealpath)) {
             continue;
         }
         try {
@@ -318,17 +409,17 @@ function scoreDocument(document, tokens, normalizedQuery, linkedCorpus, tuning)
     const searchableFields = [
         { name: "title", value: item.title, weight: tuning.title_weight },
         { name: "description", value: item.description, weight: tuning.description_weight },
-        { name: "tags", value: item.tags.join(" "), weight: tuning.tags_weight },
-        { name: "status", value: item.status, weight: tuning.status_weight },
+        { name: "tags", value: stringArray(item.tags).join(" "), weight: tuning.tags_weight },
+        { name: "status", value: typeof item.status === "string" ? item.status : "", weight: tuning.status_weight },
         { name: "body", value: document.body, weight: tuning.body_weight },
-        { name: "comments", value: (item.comments ?? []).map((entry) => entry.text).join(" "), weight: tuning.comments_weight },
-        { name: "notes", value: (item.notes ?? []).map((entry) => entry.text).join(" "), weight: tuning.notes_weight },
-        { name: "learnings", value: (item.learnings ?? []).map((entry) => entry.text).join(" "), weight: tuning.learnings_weight },
+        { name: "comments", value: textEntries(item.comments).map((entry) => entry.text).join(" "), weight: tuning.comments_weight },
+        { name: "notes", value: textEntries(item.notes).map((entry) => entry.text).join(" "), weight: tuning.notes_weight },
+        { name: "learnings", value: textEntries(item.learnings).map((entry) => entry.text).join(" "), weight: tuning.learnings_weight },
         { name: "reminders", value: buildReminderCorpus(item).join(" "), weight: tuning.reminders_weight },
         { name: "events", value: buildEventCorpus(item).join(" "), weight: tuning.events_weight },
         {
             name: "dependencies",
-            value: (item.dependencies ?? []).map((entry) => `${entry.id} ${entry.kind}`).join(" "),
+            value: dependencyEntries(item.dependencies).map((entry) => `${entry.id} ${entry.kind}`).join(" "),
             weight: tuning.dependencies_weight,
         },
         { name: "plan", value: buildPlanFlatCorpus(item), weight: tuning.body_weight },
@@ -381,8 +472,8 @@ function sortHits(items, statusRegistry) {
         const byScore = b.score - a.score;
         if (byScore !== 0)
             return byScore;
-        const aTerminal = isTerminal(a.item.status, statusRegistry);
-        const bTerminal = isTerminal(b.item.status, statusRegistry);
+        const aTerminal = isTerminalStatus(a.item.status, statusRegistry);
+        const bTerminal = isTerminalStatus(b.item.status, statusRegistry);
         if (aTerminal !== bTerminal) {
             return aTerminal ? 1 : -1;
         }
@@ -678,10 +769,14 @@ async function computeSemanticOrHybridHits(context) {
     }
     const filteredById = new Map(context.filteredDocuments.map((document) => [document.metadata.id, document]));
     const { semanticHits, semanticScores } = buildSemanticHits(vectorHits, filteredById);
+    const vectorMatchCount = semanticScores.size;
     if (context.requestedMode === "semantic") {
-        return semanticHits;
+        return { hits: semanticHits, vectorMatchCount };
     }
-    return combineHybridHits(filteredById, semanticScores, context.keywordHits, context.hybridSemanticWeight);
+    return {
+        hits: combineHybridHits(filteredById, semanticScores, context.keywordHits, context.hybridSemanticWeight),
+        vectorMatchCount,
+    };
 }
 async function loadDocuments(pmRoot, itemFormat, typeToFolder, schema) {
     const readDocumentBody = async (metadata, preferredPath, preferredFormat) => {
@@ -760,11 +855,11 @@ function readSearchFieldValue(hit, field) {
         if (itemKey.length === 0) {
             return null;
         }
-        const itemRecord = hit.item;
+        const itemRecord = toItemRecord(hit.item);
         return itemRecord[itemKey] ?? null;
     }
     const hitRecord = hit;
-    const itemRecord = hit.item;
+    const itemRecord = toItemRecord(hit.item);
     if (Object.prototype.hasOwnProperty.call(itemRecord, normalized)) {
         return itemRecord[normalized] ?? null;
     }
@@ -803,6 +898,7 @@ export async function runSearch(query, options, global) {
     const settings = runtimeDefaultsResolution.settings;
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
+    validateSearchProjectionFields(projection, runtimeFieldRegistry);
     const runtimeFieldFilters = collectRuntimeFilterValues(options, runtimeFieldRegistry, "search");
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const maxResults = resolveSearchMaxResults(settings);
@@ -873,7 +969,7 @@ export async function runSearch(query, options, global) {
             if (hits === keywordHits) {
                 const implicitHybridMode = !modeWasExplicit && effectiveMode === "hybrid";
                 const { provider, vectorStore } = requireSemanticDependencies(effectiveMode, providerResolution, vectorResolution, extensionVectorAdapter !== null);
-                hits = await computeSemanticOrHybridHits({
+                const semanticResult = await computeSemanticOrHybridHits({
                     requestedMode: effectiveMode,
                     query,
                     filteredDocuments,
@@ -892,16 +988,32 @@ export async function runSearch(query, options, global) {
                         }
                         : {}),
                 });
+                hits = semanticResult.hits;
+                // The semantic/hybrid query ran without error, but vector ranking
+                // contributed no hits for this query/filter set. Pure semantic mode would
+                // otherwise return an empty set, so degrade to the locally computed
+                // keyword hits (hybrid already blends them in) and warn so agents do not
+                // mistake them for true vector ranking. The reported mode is left
+                // unchanged; the warning is the signal.
+                if (semanticResult.vectorMatchCount === 0) {
+                    if (effectiveMode === "semantic") {
+                        hits = keywordHits;
+                    }
+                    warnings.push(`search_${effectiveMode}_degraded:no_vector_matches:results_are_lexical`);
+                }
             }
         }
         catch (error) {
-            const canFallbackToKeyword = !modeWasExplicit && effectiveMode === "hybrid";
-            if (!canFallbackToKeyword) {
-                throw error;
-            }
+            // Any semantic/hybrid attempt that fails (backend down, timeout, or the
+            // project is not configured for semantic search) degrades to keyword mode
+            // so agents are never blocked. Keyword hits are always computed locally
+            // before this point, so the fallback is guaranteed to succeed.
+            const fallbackWarning = modeWasExplicit
+                ? buildExplicitSemanticFallbackWarning(effectiveMode, error)
+                : buildImplicitSemanticFallbackWarning(error);
             effectiveMode = "keyword";
             hits = keywordHits;
-            warnings.push(buildImplicitSemanticFallbackWarning(error));
+            warnings.push(fallbackWarning);
         }
     }
     const thresholded = hits.filter((entry) => entry.score >= scoreThreshold);
@@ -941,4 +1053,4 @@ export async function runSearch(query, options, global) {
     };
 }
 //# sourceMappingURL=search.js.map
-//# debugId=5d7fe7a0-57cd-5bd9-ab50-36f6cc73ca5c
+//# debugId=7b4219a0-215b-5cfa-a437-f979968a70c4