@unbrained/pm-cli 2026.8.18 → 2026.8.20

package/dist/sdk/query/get.js

@@ -4,9 +4,10 @@
  * Implements the SDK-owned item query shared by every surface.
  */
 
-!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]="c35e787c-a9a1-5ffa-9dcf-62780fceed4c")}catch(e){}}();
-import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+!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]="16d0a1cf-467d-5041-ab36-e2a9033a9342")}catch(e){}}();
+import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
+import { renderPmCommand } from "../command-line.js";
 import { recordContextUsageTouches } from "../context-usage.js";
 import { buildItemChildrenRollup, } from "../item-children.js";
 import { buildItemSchedule, } from "../item-schedule.js";
@@ -14,7 +15,8 @@ import { getItemAt } from "../history-read.js";
 import { parseIntegerLimit } from "./parsers.js";
 import { runList } from "./list.js";
 import { registerOutputMaterialFieldGroups } from "../output-projection.js";
-const GET_DEPTH_VALUES = ["brief", "standard", "deep"];
+import { GET_DEPTH_VALUES, listGetProjectionFields, } from "./projection-contracts.js";
+export { GET_DEPTH_VALUES, listGetProjectionFields, } from "./projection-contracts.js";
 const AUTOMATIC_CHILD_ROLLUP_TYPES = new Set([
     "epic",
     "feature",
@@ -142,52 +144,24 @@ function parseGetFields(raw) {
 function normalizeGetField(field) {
     return field.startsWith("item.") ? field.slice("item.".length) : field;
 }
-function validateGetFields(fields, runtimeMetadataKeys) {
+function validateGetFields(fields, runtimeMetadataKeys, id) {
     if (fields === null) {
         return;
     }
-    const itemFields = new Set([
-        ...ITEM_METADATA_KEY_ORDER,
-        ...runtimeMetadataKeys,
-        "notes_count",
-        "tests_count",
-        "collection_counts",
-    ]);
-    const allowedRootFields = new Set([
-        "body",
-        "linked",
-        "claim_state",
-        "children",
-        "schedule",
-    ]);
-    const allowedLinkedFields = new Set([
-        "linked.files",
-        "linked.tests",
-        "linked.docs",
-    ]);
-    const allowedClaimStateFields = new Set([
-        "claim_state.claimed",
-        "claim_state.assignee",
-        "claim_state.last_claim",
-        "claim_state.last_release",
-    ]);
-    const allowedScheduleFields = new Set([
-        "schedule.deadline",
-        "schedule.start_at",
-        "schedule.end_at",
-        "schedule.location",
-        "schedule.reminders",
-        "schedule.events",
-    ]);
+    const allowedValues = listGetProjectionFields(runtimeMetadataKeys);
+    const allowed = new Set(allowedValues);
     const unknown = fields.filter((field) => {
         const normalized = normalizeGetField(field);
-        return (!itemFields.has(normalized) &&
-            !allowedRootFields.has(normalized) &&
-            !allowedLinkedFields.has(normalized) &&
-            !allowedClaimStateFields.has(normalized) &&
-            !allowedScheduleFields.has(normalized));
+        return (!allowed.has(field) &&
+            !allowed.has(normalized));
     });
     if (unknown.length > 0) {
+        const suggestedRetryArguments = [
+            "get",
+            id,
+            "--fields",
+            "id,title,status",
+        ];
         throw new PmCliError(`Unknown get --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
             code: "unknown_field_projection",
             examples: [
@@ -195,6 +169,11 @@ function validateGetFields(fields, runtimeMetadataKeys) {
                 "pm get <id> --fields id,title,claim_state",
                 "pm get <id> --fields id,title,body,linked.files",
             ],
+            recovery: {
+                allowed_values: allowedValues,
+                suggested_retry: renderPmCommand(suggestedRetryArguments),
+                suggested_retry_args: suggestedRetryArguments,
+            },
         });
     }
 }
@@ -256,10 +235,16 @@ function fieldsIncludeRoot(fields, name) {
         return normalized === name || normalized.startsWith(`${name}.`);
     });
 }
-function resolveGetProjection(options) {
+function resolveGetProjection(options, id) {
     if (options.full &&
         (options.fields !== undefined || options.depth !== undefined)) {
-        throw new PmCliError("Get projection options are mutually exclusive; remove the extra projection flag and retry.", EXIT_CODE.USAGE);
+        throw new PmCliError("Get projection options are mutually exclusive; remove the extra projection flag and retry.", EXIT_CODE.USAGE, {
+            code: "projection_options_mutually_exclusive",
+            recovery: {
+                suggested_retry: renderPmCommand(["get", id, "--full"]),
+                suggested_retry_args: ["get", id, "--full"],
+            },
+        });
     }
     if (options.tree !== true && options.treeDepth !== undefined) {
         throw new PmCliError("Get --tree-depth requires --tree", EXIT_CODE.USAGE);
@@ -309,9 +294,9 @@ async function loadGetItemContext(id, global, at) {
         body: loaded.document.body,
     };
 }
-function validateGetProjectionFields(fields, settings, historical) {
+function validateGetProjectionFields(fields, settings, historical, id) {
     const runtimeMetadataKeys = resolveRuntimeFieldRegistry(settings.schema).definitions.map((field) => field.metadata_key);
-    validateGetFields(fields, runtimeMetadataKeys);
+    validateGetFields(fields, runtimeMetadataKeys, id);
     if (historical && fieldsIncludeRoot(fields ?? [], "children")) {
         throw new PmCliError("Get --at cannot project children because workspace-level historical relationships are not yet indexed.", EXIT_CODE.USAGE);
     }
@@ -395,9 +380,9 @@ async function buildGetTree(context, options, treeDepth, global) {
 }
 /** Implements run get for the public runtime surface of this module. */
 export async function runGet(id, global, options = {}) {
-    const projection = resolveGetProjection(options);
+    const projection = resolveGetProjection(options, id);
     const context = await loadGetItemContext(id, global, options.at);
-    validateGetProjectionFields(projection.fields, context.settings, context.historical !== undefined);
+    validateGetProjectionFields(projection.fields, context.settings, context.historical !== undefined, context.locatedId);
     const includeBody = shouldIncludeGetField({ ...projection, field: "body" });
     const includeLinked = shouldIncludeGetField({
         ...projection,
@@ -463,4 +448,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=c35e787c-a9a1-5ffa-9dcf-62780fceed4c
+//# debugId=16d0a1cf-467d-5041-ab36-e2a9033a9342

package/dist/sdk/query/list.d.ts

@@ -5,6 +5,8 @@ import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js"
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import type { ItemMetadata, ItemStatus } from "../../types/index.js";
 import type { SharedItemFilterOptions } from "./item-filter-options.js";
+import { type ListCommandName, type ListProjectionMode } from "./projection-contracts.js";
+export { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, listListProjectionFields, type ListCommandName, type ListProjectionMode, } from "./projection-contracts.js";
 /** Documents the list options payload exchanged by command, SDK, and package integrations. */
 export interface ListOptions extends SharedItemFilterOptions {
     /** Value that configures or reports ids for this contract. */
@@ -62,6 +64,10 @@ export interface ListOptions extends SharedItemFilterOptions {
     /** Value that configures or reports filter metadata missing for this contract. */
     filterMetadataMissing?: boolean;
 }
+/** Adapter-only list context that never expands the public SDK options contract. */
+interface ListRuntimeOptions extends ListOptions {
+    projectionCommand?: ListCommandName;
+}
 /** Extract the missing-metadata selection filters from list/update-many options. */
 export declare const resolveMissingMetadataFilters: (options: {
     filterAcMissing?: boolean;
@@ -114,8 +120,6 @@ export interface ListProjectedItemCore {
 export type ListProjectedItem = ListProjectedItemCore & Record<string, unknown>;
 /** Honest union of item shapes returned by the list engine. */
 export type ListResultItem = ListedItem | ListTreeItem | ListProjectedItem;
-/** Stable projection names emitted by list envelopes and command contracts. */
-export type ListProjectionMode = "full" | "compact" | "brief" | "fields";
 interface ListProjectionConfig {
     mode: ListProjectionMode;
     fields: string[];
@@ -128,23 +132,6 @@ export type ListSortField = (typeof LIST_SORT_FIELDS)[number];
 export declare const LIST_SORT_ORDER_VALUES: readonly ["asc", "desc"];
 /** Restricts list sort order values accepted by command, SDK, and storage contracts. */
 export type ListSortOrder = (typeof LIST_SORT_ORDER_VALUES)[number];
-/** Stable field order for the compact list projection. */
-export declare const DEFAULT_COMPACT_LIST_FIELDS: readonly ["id", "title", "status", "type", "priority", "parent", "updated_at"];
-/** Stable field order for the agent-optimized brief list projection. */
-export declare const BRIEF_LIST_FIELDS: readonly ["id", "status", "type", "title"];
-/** Machine-readable default projection contract for every list command. */
-export declare const LIST_COMMAND_DEFAULT_PROJECTIONS: {
-    readonly list: "brief";
-    readonly "list-all": "full";
-    readonly "list-draft": "full";
-    readonly "list-open": "brief";
-    readonly "list-in-progress": "brief";
-    readonly "list-blocked": "brief";
-    readonly "list-closed": "full";
-    readonly "list-canceled": "full";
-};
-/** Command names whose output defaults are described by the list projection contract. */
-export type ListCommandName = keyof typeof LIST_COMMAND_DEFAULT_PROJECTIONS;
 interface ListResultBase {
     items: ListResultItem[];
     count: number;
@@ -244,7 +231,7 @@ declare function resolveListUpdatedAfter(options: ListOptions): string | undefin
 declare function parseIdsFilter(raw: unknown): Set<string> | undefined;
 declare function parseOffset(raw: string | undefined): number | undefined;
 declare function parseFieldSelectors(raw: string | undefined): string[] | undefined;
-declare function parseProjectionConfig(options: ListOptions): ListProjectionConfig;
+declare function parseProjectionConfig(options: ListRuntimeOptions, invokedCommand?: ListCommandName): ListProjectionConfig;
 declare function normalizeProjectionField(field: string): string;
 declare function parseSortField(raw: string | undefined): ListSortField | undefined;
 declare function parseSortOrder(raw: string | undefined): ListSortOrder | undefined;
@@ -309,4 +296,3 @@ export declare const _testOnly: {
     trimNonEmpty: typeof trimNonEmpty;
     withTreeMetadata: typeof withTreeMetadata;
 };
-export {};

package/dist/sdk/query/list.js

@@ -4,7 +4,7 @@
  * Implements the pm list command surface and its agent-facing runtime behavior.
  */
 
-!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]="41f54a9b-b7ba-52c1-bd84-76aa57021827")}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]="67c5ff91-1c04-5506-ae5b-32f6552f1d07")}catch(e){}}();
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { toItemRecord } from "../../core/item/item-record.js";
@@ -18,7 +18,7 @@ import { collectRuntimeFilterValues, matchesRuntimeFilters, } from "../../core/s
 import { hasMissingMetadataFilter, itemMatchesMissingMetadata, lifecycleClassifierFromStatusRegistry, } from "../../core/governance/metadata-coverage.js";
 import { contentFiltersNeedBody, contentFiltersNeedCollections, hasContentFieldFilter, itemMatchesContentFilters, } from "../../core/governance/content-fields.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
-import { EXIT_CODE, ITEM_METADATA_KEY_ORDER, } from "../../core/shared/constants.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { compareTimestampStrings, matchesTimestampFilters, nowIso, resolveIsoOrRelative, } from "../../core/shared/time.js";
 import { listAllItemMetadata, listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
@@ -28,6 +28,8 @@ import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { LIST_FILTER_FLAG_CONTRACTS } from "../cli-contracts/flag-contracts.js";
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, selectCursorSemanticOptions, } from "../pagination.js";
+import { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, listListProjectionFields, } from "./projection-contracts.js";
+export { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, listListProjectionFields, } from "./projection-contracts.js";
 /** Extract the missing-metadata selection filters from list/update-many options. */
 export const resolveMissingMetadataFilters = (options) => {
     return {
@@ -134,35 +136,6 @@ export const LIST_SORT_FIELDS = [
 ];
 /** Supported values accepted by the list sort order contract. */
 export const LIST_SORT_ORDER_VALUES = ["asc", "desc"];
-/** Stable field order for the compact list projection. */
-export const DEFAULT_COMPACT_LIST_FIELDS = [
-    "id",
-    "title",
-    "status",
-    "type",
-    "priority",
-    "parent",
-    "updated_at",
-];
-/** Stable field order for the agent-optimized brief list projection. */
-export const BRIEF_LIST_FIELDS = ["id", "status", "type", "title"];
-/** Machine-readable default projection contract for every list command. */
-export const LIST_COMMAND_DEFAULT_PROJECTIONS = {
-    list: "brief",
-    "list-all": "full",
-    "list-draft": "full",
-    "list-open": "brief",
-    "list-in-progress": "brief",
-    "list-blocked": "brief",
-    "list-closed": "full",
-    "list-canceled": "full",
-};
-const TREE_METADATA_FIELDS = [
-    "tree_depth",
-    "tree_parent",
-    "tree_children",
-    "tree_title",
-];
 // A projection that selects any heavy collection field (or `--full`, which returns
 // items verbatim) must load the full metadata; everything else takes the light path.
 // Sourced from the single HEAVY_METADATA_KEYS definition in the cache layer so the
@@ -479,7 +452,7 @@ function parseFieldSelectors(raw) {
     }
     return [...new Set(selectors)];
 }
-function parseProjectionConfig(options) {
+function parseProjectionConfig(options, invokedCommand = options.projectionCommand ?? "list") {
     const compactRequested = options.compact === true;
     const briefRequested = options.brief === true;
     const fullRequested = options.full === true;
@@ -489,7 +462,13 @@ function parseProjectionConfig(options) {
         Number(fullRequested) +
         Number(fieldSelectors !== undefined);
     if (enabledModes > 1) {
-        throw new PmCliError("List projection options are mutually exclusive. Use one of --compact, --brief, --full, or --fields.", EXIT_CODE.USAGE);
+        throw new PmCliError("List projection options are mutually exclusive. Use one of --compact, --brief, --full, or --fields.", EXIT_CODE.USAGE, {
+            code: "projection_options_mutually_exclusive",
+            recovery: {
+                suggested_retry: `pm ${invokedCommand} --brief`,
+                suggested_retry_args: [invokedCommand, "--brief"],
+            },
+        });
     }
     if (fullRequested) {
         return {
@@ -512,7 +491,9 @@ function parseProjectionConfig(options) {
     if (fieldSelectors) {
         return {
             mode: "fields",
-            fields: fieldSelectors,
+            fields: [
+                ...new Set(fieldSelectors.map((field) => normalizeProjectionField(field))),
+            ],
         };
     }
     return {
@@ -523,16 +504,12 @@ function parseProjectionConfig(options) {
 function normalizeProjectionField(field) {
     return field.startsWith("item.") ? field.slice("item.".length) : field;
 }
-function validateListProjectionFields(projection, runtimeMetadataKeys) {
+function validateListProjectionFields(projection, runtimeMetadataKeys, invokedCommand) {
     if (projection.mode !== "fields") {
         return;
     }
-    const allowed = new Set([
-        ...ITEM_METADATA_KEY_ORDER,
-        "body",
-        ...TREE_METADATA_FIELDS,
-        ...runtimeMetadataKeys,
-    ]);
+    const allowedValues = listListProjectionFields(runtimeMetadataKeys);
+    const allowed = new Set(allowedValues.map((field) => normalizeProjectionField(field)));
     const unknown = projection.fields.filter((field) => !allowed.has(normalizeProjectionField(field)));
     if (unknown.length > 0) {
         throw new PmCliError(`Unknown list --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
@@ -542,6 +519,17 @@ function validateListProjectionFields(projection, runtimeMetadataKeys) {
                 "pm list --fields id,title,parent,priority --limit 10",
                 "pm list-all --fields id,title,body --limit 5",
             ],
+            recovery: {
+                allowed_values: allowedValues,
+                suggested_retry: `pm ${invokedCommand} --fields id,title,status --limit 10`,
+                suggested_retry_args: [
+                    invokedCommand,
+                    "--fields",
+                    "id,title,status",
+                    "--limit",
+                    "10",
+                ],
+            },
         });
     }
 }
@@ -909,8 +897,9 @@ async function resolveListRuntimeContext(options, global) {
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
-    const projection = parseProjectionConfig(options);
-    validateListProjectionFields(projection, runtimeMetadataKeysForProjection(runtimeFieldRegistry.definitions));
+    const invokedCommand = options.projectionCommand ?? "list";
+    const projection = parseProjectionConfig(options, invokedCommand);
+    validateListProjectionFields(projection, runtimeMetadataKeysForProjection(runtimeFieldRegistry.definitions), invokedCommand);
     return {
         pmRoot,
         settings,
@@ -1021,7 +1010,18 @@ async function tryLoadIndexedListPage(params) {
         "stream",
         "includeBody",
         "excludeTerminal",
+        "dependencyBlocked",
         "noTruncate",
+        "projectionCommand",
+        "truncate",
+        "notes",
+        "learnings",
+        "files",
+        "docs",
+        "tests",
+        "comments",
+        "deps",
+        "linkedCommand",
     ]);
     const projectionNeedsHeavyData = [
         runtime.projection.mode === "full",
@@ -1243,4 +1243,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=41f54a9b-b7ba-52c1-bd84-76aa57021827
+//# debugId=67c5ff91-1c04-5506-ae5b-32f6552f1d07

package/dist/sdk/query/projection-contracts.d.ts

@@ -0,0 +1,33 @@
+/** Stable projection names emitted by list envelopes and command contracts. */
+export type ListProjectionMode = "full" | "compact" | "brief" | "fields";
+/** Stable field order for the compact list projection. */
+export declare const DEFAULT_COMPACT_LIST_FIELDS: readonly ["id", "title", "status", "type", "priority", "parent", "updated_at"];
+/** Stable field order for the agent-optimized brief list projection. */
+export declare const BRIEF_LIST_FIELDS: readonly ["id", "status", "type", "title"];
+/** Machine-readable default projection contract for every list command. */
+export declare const LIST_COMMAND_DEFAULT_PROJECTIONS: {
+    readonly list: "brief";
+    readonly "list-all": "full";
+    readonly "list-draft": "full";
+    readonly "list-open": "brief";
+    readonly "list-in-progress": "brief";
+    readonly "list-blocked": "brief";
+    readonly "list-closed": "full";
+    readonly "list-canceled": "full";
+};
+/** Command names whose output defaults are described by the list projection contract. */
+export type ListCommandName = keyof typeof LIST_COMMAND_DEFAULT_PROJECTIONS;
+/** Return every accepted list projection selector for core and runtime metadata. */
+export declare function listListProjectionFields(runtimeMetadataKeys?: Iterable<string>): string[];
+/** Canonical get depth values. The CLI also accepts full as an alias for deep. */
+export declare const GET_DEPTH_VALUES: readonly ["brief", "standard", "deep"];
+/** Return every accepted get projection selector for core and runtime metadata. */
+export declare function listGetProjectionFields(runtimeMetadataKeys?: Iterable<string>): string[];
+/** Stable field order for compact search results. */
+export declare const DEFAULT_COMPACT_SEARCH_FIELDS: readonly ["id", "title", "status", "type", "priority", "updated_at", "score", "matched_fields"];
+/** Search-result fields that live beside the nested item projection. */
+export declare const SEARCH_HIT_FIELD_KEYS: readonly ["score", "matched_fields", "highlights"];
+/** Core item fields accepted by explicit search projections. */
+export declare const SEARCH_ITEM_FIELD_KEYS: readonly ["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"];
+/** Return every accepted search projection selector for core and runtime metadata. */
+export declare function listSearchProjectionFields(runtimeMetadataKeys?: Iterable<string>): string[];

package/dist/sdk/query/projection-contracts.js

@@ -0,0 +1,185 @@
+/**
+ * @module sdk/query/projection-contracts
+ *
+ * Declares dependency-light projection vocabularies for list, get, and search
+ * so contract-only SDK imports do not initialize query runtimes or storage.
+ */
+
+!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]="5bb71ec1-7eb1-558e-a965-acd779570c2e")}catch(e){}}();
+import { ITEM_METADATA_KEY_ORDER } from "../../core/shared/item-metadata-contract.js";
+/** Stable field order for the compact list projection. */
+export const DEFAULT_COMPACT_LIST_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "parent",
+    "updated_at",
+];
+/** Stable field order for the agent-optimized brief list projection. */
+export const BRIEF_LIST_FIELDS = ["id", "status", "type", "title"];
+/** Machine-readable default projection contract for every list command. */
+export const LIST_COMMAND_DEFAULT_PROJECTIONS = {
+    list: "brief",
+    "list-all": "full",
+    "list-draft": "full",
+    "list-open": "brief",
+    "list-in-progress": "brief",
+    "list-blocked": "brief",
+    "list-closed": "full",
+    "list-canceled": "full",
+};
+const TREE_METADATA_FIELDS = [
+    "tree_depth",
+    "tree_parent",
+    "tree_children",
+    "tree_title",
+];
+/** Return every accepted list projection selector for core and runtime metadata. */
+export function listListProjectionFields(runtimeMetadataKeys = []) {
+    return [
+        ...new Set([
+            ...ITEM_METADATA_KEY_ORDER,
+            "body",
+            ...TREE_METADATA_FIELDS,
+            ...runtimeMetadataKeys,
+        ]),
+    ]
+        .flatMap((field) => [field, `item.${field}`])
+        .sort();
+}
+/** Canonical get depth values. The CLI also accepts full as an alias for deep. */
+export const GET_DEPTH_VALUES = ["brief", "standard", "deep"];
+const GET_ROOT_PROJECTION_FIELDS = [
+    "body",
+    "linked",
+    "claim_state",
+    "children",
+    "schedule",
+];
+const GET_LINKED_PROJECTION_FIELDS = [
+    "linked.files",
+    "linked.tests",
+    "linked.docs",
+];
+const GET_CLAIM_STATE_PROJECTION_FIELDS = [
+    "claim_state.claimed",
+    "claim_state.assignee",
+    "claim_state.last_claim",
+    "claim_state.last_release",
+];
+const GET_SCHEDULE_PROJECTION_FIELDS = [
+    "schedule.deadline",
+    "schedule.start_at",
+    "schedule.end_at",
+    "schedule.location",
+    "schedule.reminders",
+    "schedule.events",
+];
+/** Return every accepted get projection selector for core and runtime metadata. */
+export function listGetProjectionFields(runtimeMetadataKeys = []) {
+    const itemFields = [
+        ...new Set([
+            ...ITEM_METADATA_KEY_ORDER,
+            ...runtimeMetadataKeys,
+            "notes_count",
+            "tests_count",
+            "collection_counts",
+        ]),
+    ];
+    return [
+        ...itemFields.flatMap((field) => [field, `item.${field}`]),
+        ...GET_ROOT_PROJECTION_FIELDS,
+        ...GET_LINKED_PROJECTION_FIELDS,
+        ...GET_CLAIM_STATE_PROJECTION_FIELDS,
+        ...GET_SCHEDULE_PROJECTION_FIELDS,
+    ].sort();
+}
+/** Stable field order for compact search results. */
+export const DEFAULT_COMPACT_SEARCH_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "updated_at",
+    "score",
+    "matched_fields",
+];
+/** Search-result fields that live beside the nested item projection. */
+export const SEARCH_HIT_FIELD_KEYS = [
+    "score",
+    "matched_fields",
+    "highlights",
+];
+/** Core item fields accepted by explicit search projections. */
+export const SEARCH_ITEM_FIELD_KEYS = [
+    "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",
+];
+/** Return every accepted search projection selector for core and runtime metadata. */
+export function listSearchProjectionFields(runtimeMetadataKeys = []) {
+    const runtimeKeys = [...new Set(runtimeMetadataKeys)];
+    return [
+        ...SEARCH_HIT_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS.map((field) => `item.${field}`),
+        ...runtimeKeys,
+        ...runtimeKeys.map((field) => `item.${field}`),
+    ].sort();
+}
+//# sourceMappingURL=projection-contracts.js.map
+//# debugId=5bb71ec1-7eb1-558e-a965-acd779570c2e

package/dist/sdk/query/search-contracts.d.ts

@@ -1,6 +1,7 @@
 import type { RuntimeFieldRegistry } from "../../core/schema/runtime-schema.js";
 import type { SharedItemFilterOptions } from "./item-filter-options.js";
 import type { SearchMode } from "./search-rendering.js";
+export { DEFAULT_COMPACT_SEARCH_FIELDS, SEARCH_HIT_FIELD_KEYS, SEARCH_ITEM_FIELD_KEYS, listSearchProjectionFields, } from "./projection-contracts.js";
 /** Documents the search options payload exchanged by command, SDK, and package integrations. */
 export interface SearchOptions extends SharedItemFilterOptions {
     /** Value that configures or reports mode for this contract. */
@@ -60,9 +61,9 @@ export declare function normalizeSearchPhrase(value: string): string;
 /** Parse an optional deadline filter. */
 export declare function parseSearchDeadline(raw: string | undefined, fieldLabel: string): string | undefined;
 /** Resolve mutually exclusive compact, full, or explicit-field projection. */
-export declare function parseSearchProjection(options: SearchOptions): SearchProjectionConfig;
+export declare function parseSearchProjection(options: SearchOptions, query?: string): SearchProjectionConfig;
 /** Validate explicit projection fields against core and runtime metadata. */
-export declare function validateSearchProjectionFields(projection: SearchProjectionConfig, runtimeFieldRegistry: RuntimeFieldRegistry): void;
+export declare function validateSearchProjectionFields(projection: SearchProjectionConfig, runtimeFieldRegistry: RuntimeFieldRegistry, query?: string): void;
 /** Parse a non-empty normalized query into lexical tokens. */
 export declare function parseSearchTokens(query: string): string[];
 /** Documents the search tuning payload exchanged by command, SDK, and package integrations. */