@unbrained/pm-cli 2026.7.16 → 2026.7.17

package/dist/sdk/query/list.js

@@ -0,0 +1,1073 @@
+/**
+ * @module sdk/query/list
+ *
+ * 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]="255af95f-1741-5e74-a528-4fa8ae65ee4c")}catch(e){}}();
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
+import { toItemRecord } from "../../core/item/item-record.js";
+import { isTerminalStatus } from "../../core/item/status.js";
+import { isStatusAllFilterInput, parseStatusFilterCsv, } from "../../core/item/status-filter.js";
+import { resolveItemTypeRegistry, } from "../../core/item/type-registry.js";
+import { parseIntegerLimit, parsePriority, parseType } from "./parsers.js";
+import { collectRuntimeFilterValues, matchesRuntimeFilters, } from "../../core/schema/runtime-field-filters.js";
+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 { 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";
+import { HEAVY_METADATA_KEYS } from "../../core/store/item-metadata-cache.js";
+import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { readSettings } from "../../core/store/settings.js";
+import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, } from "../pagination.js";
+/** Extract the missing-metadata selection filters from list/update-many options. */
+export const resolveMissingMetadataFilters = (options) => {
+    return {
+        acMissing: options.filterAcMissing === true,
+        estimatesMissing: options.filterEstimatesMissing === true,
+        resolutionMissing: options.filterResolutionMissing === true,
+        metadataMissing: options.filterMetadataMissing === true,
+        reviewerMissing: options.filterReviewerMissing === true,
+        riskMissing: options.filterRiskMissing === true,
+        confidenceMissing: options.filterConfidenceMissing === true,
+        sprintMissing: options.filterSprintMissing === true,
+        releaseMissing: options.filterReleaseMissing === true,
+    };
+};
+const CONTENT_FIELD_FLAG_MAPPINGS = [
+    {
+        field: "notes",
+        presentKey: "hasNotes",
+        absentKey: "noNotes",
+        presentFlag: "--has-notes",
+        absentFlag: "--no-notes",
+    },
+    {
+        field: "learnings",
+        presentKey: "hasLearnings",
+        absentKey: "noLearnings",
+        presentFlag: "--has-learnings",
+        absentFlag: "--no-learnings",
+    },
+    {
+        field: "files",
+        presentKey: "hasFiles",
+        absentKey: "noFiles",
+        presentFlag: "--has-files",
+        absentFlag: "--no-files",
+    },
+    {
+        field: "docs",
+        presentKey: "hasDocs",
+        absentKey: "noDocs",
+        presentFlag: "--has-docs",
+        absentFlag: "--no-docs",
+    },
+    {
+        field: "tests",
+        presentKey: "hasTests",
+        absentKey: "noTests",
+        presentFlag: "--has-tests",
+        absentFlag: "--no-tests",
+    },
+    {
+        field: "comments",
+        presentKey: "hasComments",
+        absentKey: "noComments",
+        presentFlag: "--has-comments",
+        absentFlag: "--no-comments",
+    },
+    {
+        field: "deps",
+        presentKey: "hasDeps",
+        absentKey: "noDeps",
+        presentFlag: "--has-deps",
+        absentFlag: "--no-deps",
+    },
+    {
+        field: "body",
+        presentKey: "hasBody",
+        absentKey: "emptyBody",
+        presentFlag: "--has-body",
+        absentFlag: "--empty-body",
+    },
+    {
+        field: "linked_command",
+        presentKey: "hasLinkedCommand",
+        absentKey: "noLinkedCommand",
+        presentFlag: "--has-linked-command",
+        absentFlag: "--no-linked-command",
+    },
+];
+/** Resolve the content-field presence/absence selections from list/search options. A field requested both present AND absent is a usage error (the two selections are mutually exclusive). Returns an empty object when no content-field filter is active. */
+export const resolveContentFieldFilters = (options) => {
+    const conflict = CONTENT_FIELD_FLAG_MAPPINGS.find((mapping) => options[mapping.presentKey] === true &&
+        options[mapping.absentKey] === true);
+    if (conflict) {
+        throw new PmCliError(`Cannot combine ${conflict.presentFlag} with ${conflict.absentFlag} for the same field.`, EXIT_CODE.USAGE);
+    }
+    return Object.fromEntries(CONTENT_FIELD_FLAG_MAPPINGS.flatMap((mapping) => {
+        if (options[mapping.presentKey] === true) {
+            return [[mapping.field, "present"]];
+        }
+        return options[mapping.absentKey] === true
+            ? [[mapping.field, "absent"]]
+            : [];
+    }));
+};
+/** Public contract for list sort fields, shared by SDK and presentation-layer consumers. */
+export const LIST_SORT_FIELDS = [
+    "priority",
+    "deadline",
+    "updated_at",
+    "created_at",
+    "title",
+    "parent",
+];
+/** Supported values accepted by the list sort order contract. */
+export const LIST_SORT_ORDER_VALUES = ["asc", "desc"];
+const DEFAULT_COMPACT_LIST_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "parent",
+    "updated_at",
+];
+const BRIEF_LIST_FIELDS = ["id", "status", "type", "title"];
+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
+// light/heavy split can never drift between the cache and the projection routing.
+const HEAVY_PROJECTION_FIELDS = new Set(HEAVY_METADATA_KEYS);
+function isNonEmptyRecord(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length > 0);
+}
+// Active content-field filter flags, keyed by the options dest and the snake_case
+// summary key emitted in the filters echo (GH-242). Presence and absence are
+// distinct echo keys (has_notes vs no_notes; has_body vs empty_body).
+const CONTENT_FILTER_ECHO_ENTRIES = [
+    { key: "hasNotes", summaryKey: "has_notes" },
+    { key: "hasLearnings", summaryKey: "has_learnings" },
+    { key: "hasFiles", summaryKey: "has_files" },
+    { key: "hasDocs", summaryKey: "has_docs" },
+    { key: "hasTests", summaryKey: "has_tests" },
+    { key: "hasComments", summaryKey: "has_comments" },
+    { key: "hasDeps", summaryKey: "has_deps" },
+    { key: "hasBody", summaryKey: "has_body" },
+    { key: "hasLinkedCommand", summaryKey: "has_linked_command" },
+    { key: "noNotes", summaryKey: "no_notes" },
+    { key: "noLearnings", summaryKey: "no_learnings" },
+    { key: "noFiles", summaryKey: "no_files" },
+    { key: "noDocs", summaryKey: "no_docs" },
+    { key: "noTests", summaryKey: "no_tests" },
+    { key: "noComments", summaryKey: "no_comments" },
+    { key: "noDeps", summaryKey: "no_deps" },
+    { key: "emptyBody", summaryKey: "empty_body" },
+    { key: "noLinkedCommand", summaryKey: "no_linked_command" },
+];
+// Active governance-missing filter flags (GH-236), keyed by options dest and the
+// snake_case summary key emitted in the filters echo.
+const GOVERNANCE_MISSING_ECHO_ENTRIES = [
+    { key: "filterReviewerMissing", summaryKey: "filter_reviewer_missing" },
+    { key: "filterRiskMissing", summaryKey: "filter_risk_missing" },
+    { key: "filterConfidenceMissing", summaryKey: "filter_confidence_missing" },
+    { key: "filterSprintMissing", summaryKey: "filter_sprint_missing" },
+    { key: "filterReleaseMissing", summaryKey: "filter_release_missing" },
+];
+function applyContentFilterEcho(filters, options) {
+    for (const entry of CONTENT_FILTER_ECHO_ENTRIES) {
+        if (options[entry.key] === true) {
+            filters[entry.summaryKey] = true;
+        }
+    }
+}
+function applyGovernanceMissingFilterEcho(filters, options) {
+    for (const entry of GOVERNANCE_MISSING_ECHO_ENTRIES) {
+        if (options[entry.key] === true) {
+            filters[entry.summaryKey] = true;
+        }
+    }
+}
+/**
+ * Copies user-supplied option values into compact filter summaries.
+ *
+ * Compact list/search responses are optimized for agent context: they echo only
+ * filters the caller actually supplied. Keeping this helper shared prevents the
+ * list and search command summaries from drifting as new scalar filters are
+ * added.
+ */
+export function applyFilterValueEcho(filters, options, entries) {
+    for (const entry of entries) {
+        const value = options[entry.optionKey];
+        if (value !== undefined) {
+            filters[entry.summaryKey] = entry.normalize
+                ? entry.normalize(value)
+                : value;
+        }
+    }
+}
+/** Implements build content filter echo for the public runtime surface of this module. */
+export function buildContentFilterEcho(options) {
+    const echo = {};
+    applyContentFilterEcho(echo, options);
+    return echo;
+}
+/** Implements build governance missing filter echo for the public runtime surface of this module. */
+export function buildGovernanceMissingFilterEcho(options) {
+    const echo = {};
+    applyGovernanceMissingFilterEcho(echo, options);
+    return echo;
+}
+const COMPACT_LIST_VALUE_FILTER_ECHO_ENTRIES = [
+    { optionKey: "type", summaryKey: "type" },
+    { optionKey: "tag", summaryKey: "tag" },
+    { optionKey: "priority", summaryKey: "priority" },
+    { optionKey: "deadlineBefore", summaryKey: "deadline_before" },
+    { optionKey: "deadlineAfter", summaryKey: "deadline_after" },
+    { optionKey: "updatedAfter", summaryKey: "updated_after" },
+    { optionKey: "updatedBefore", summaryKey: "updated_before" },
+    { optionKey: "createdAfter", summaryKey: "created_after" },
+    { optionKey: "createdBefore", summaryKey: "created_before" },
+    { optionKey: "ids", summaryKey: "ids" },
+    { optionKey: "assignee", summaryKey: "assignee" },
+    { optionKey: "assigneeFilter", summaryKey: "assignee_filter" },
+    { optionKey: "parent", summaryKey: "parent" },
+    { optionKey: "sprint", summaryKey: "sprint" },
+    { optionKey: "release", summaryKey: "release" },
+];
+const VERBOSE_LIST_VALUE_FILTER_ECHO_ENTRIES = [
+    { optionKey: "type", summaryKey: "type" },
+    { optionKey: "tag", summaryKey: "tag" },
+    { optionKey: "priority", summaryKey: "priority" },
+    { optionKey: "deadlineBefore", summaryKey: "deadline_before" },
+    { optionKey: "deadlineAfter", summaryKey: "deadline_after" },
+    { optionKey: "updatedAfter", summaryKey: "updated_after" },
+    { optionKey: "updatedBefore", summaryKey: "updated_before" },
+    { optionKey: "createdAfter", summaryKey: "created_after" },
+    { optionKey: "createdBefore", summaryKey: "created_before" },
+    { optionKey: "ids", summaryKey: "ids" },
+    { optionKey: "assignee", summaryKey: "assignee" },
+    { optionKey: "assigneeFilter", summaryKey: "assignee_filter" },
+    { optionKey: "parent", summaryKey: "parent" },
+    { optionKey: "sprint", summaryKey: "sprint" },
+    { optionKey: "release", summaryKey: "release" },
+    { optionKey: "limit", summaryKey: "limit" },
+    { optionKey: "offset", summaryKey: "offset" },
+    { optionKey: "includeBody", summaryKey: "include_body" },
+    { optionKey: "compact", summaryKey: "compact" },
+    { optionKey: "fields", summaryKey: "fields" },
+];
+const VERBOSE_LIST_BOOLEAN_FILTER_ECHO_ENTRIES = [
+    { key: "filterAcMissing", summaryKey: "filter_ac_missing" },
+    { key: "filterEstimatesMissing", summaryKey: "filter_estimates_missing" },
+    { key: "filterResolutionMissing", summaryKey: "filter_resolution_missing" },
+    { key: "filterMetadataMissing", summaryKey: "filter_metadata_missing" },
+];
+const LIST_RECENT_WINDOW = "-7d";
+function buildCompactListFilterSummary(params) {
+    const { filtersStatus, options, treeEnabled, treeDepth, sortField, sortOrder, runtimeFieldFilters, } = params;
+    const filters = {};
+    if (filtersStatus !== null) {
+        filters.status = filtersStatus;
+    }
+    applyFilterValueEcho(filters, options, COMPACT_LIST_VALUE_FILTER_ECHO_ENTRIES);
+    applyListWindowFilterEcho(filters, options);
+    if (options.filterAcMissing === true) {
+        filters.filter_ac_missing = true;
+    }
+    if (options.filterEstimatesMissing === true) {
+        filters.filter_estimates_missing = true;
+    }
+    if (options.filterResolutionMissing === true) {
+        filters.filter_resolution_missing = true;
+    }
+    if (options.filterMetadataMissing === true) {
+        filters.filter_metadata_missing = true;
+    }
+    applyGovernanceMissingFilterEcho(filters, options);
+    applyContentFilterEcho(filters, options);
+    if (options.limit !== undefined) {
+        filters.limit = options.limit;
+    }
+    if (options.offset !== undefined) {
+        filters.offset = options.offset;
+    }
+    if (options.includeBody === true) {
+        filters.include_body = true;
+    }
+    if (options.fields !== undefined) {
+        filters.fields = options.fields;
+    }
+    if (treeEnabled) {
+        filters.tree = true;
+        if (treeDepth !== undefined) {
+            filters.tree_depth = treeDepth;
+        }
+    }
+    if (sortField !== undefined) {
+        filters.sort = sortField;
+        filters.order = sortOrder;
+    }
+    if (isNonEmptyRecord(runtimeFieldFilters)) {
+        filters.runtime_filters = runtimeFieldFilters;
+    }
+    return filters;
+}
+function compareDefaultSort(left, right, statusRegistry) {
+    const leftTerminal = isTerminalStatus(left.status, statusRegistry);
+    const rightTerminal = isTerminalStatus(right.status, statusRegistry);
+    if (leftTerminal !== rightTerminal) {
+        return leftTerminal ? 1 : -1;
+    }
+    const byPriority = left.priority - right.priority;
+    if (byPriority !== 0) {
+        return byPriority;
+    }
+    const byUpdated = compareTimestampStrings(right.updated_at, left.updated_at);
+    if (byUpdated !== 0) {
+        return byUpdated;
+    }
+    return (left.id ?? "").localeCompare(right.id ?? "");
+}
+function sortItemsDefault(items, statusRegistry) {
+    return [...items].sort((left, right) => compareDefaultSort(left, right, statusRegistry));
+}
+function parseDeadline(raw, fieldLabel) {
+    if (raw === undefined)
+        return undefined;
+    return resolveIsoOrRelative(raw, new Date(), fieldLabel);
+}
+// updated/created date-window filters share the deadline ISO+relative resolver
+// so agents doing incremental "what changed since my last context window" syncs
+// can pass either an ISO timestamp (the common case — feed back the previous
+// run's `now`) or a SIGNED relative offset where "-2h"/"-7d" reach into the
+// past and "+1d" into the future (units h/d/w/m, m = months — there is no
+// minutes unit, matching the deadline resolver).
+function parseTimestampWindow(raw, fieldLabel) {
+    if (raw == null)
+        return undefined;
+    const value = String(raw).trim();
+    if (value.length === 0)
+        return undefined;
+    return resolveIsoOrRelative(value, new Date(), fieldLabel);
+}
+function resolveListUpdatedAfter(options) {
+    const hasUpdatedAfter = options.updatedAfter != null &&
+        String(options.updatedAfter).trim().length > 0;
+    const selectedWindows = [
+        options.today === true,
+        options.recent === true,
+        hasUpdatedAfter,
+    ].filter((selected) => selected).length;
+    if (selectedWindows > 1) {
+        throw new PmCliError("Choose only one updated_at window: --today, --recent, or --updated-after.", EXIT_CODE.USAGE);
+    }
+    if (options.today === true) {
+        const today = new Date();
+        today.setHours(0, 0, 0, 0);
+        return today.toISOString();
+    }
+    if (options.recent === true) {
+        return parseTimestampWindow(LIST_RECENT_WINDOW, "recent");
+    }
+    return parseTimestampWindow(options.updatedAfter, "updated-after");
+}
+function applyListWindowFilterEcho(filters, options) {
+    if (options.today === true) {
+        filters.today = true;
+    }
+    if (options.recent === true) {
+        filters.recent = true;
+    }
+}
+function parseIdsFilter(raw) {
+    if (raw == null)
+        return undefined;
+    const value = String(raw).trim();
+    if (value.length === 0) {
+        throw new PmCliError("--ids requires at least one non-empty item ID", EXIT_CODE.USAGE);
+    }
+    const ids = value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (ids.length === 0) {
+        throw new PmCliError("--ids requires at least one non-empty item ID", EXIT_CODE.USAGE);
+    }
+    return new Set(ids);
+}
+function parseOffset(raw) {
+    if (raw === undefined)
+        return undefined;
+    const normalized = String(raw).trim();
+    const parsed = normalized.length === 0 ? Number.NaN : Number(normalized);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new PmCliError("Offset filter must be a non-negative integer", EXIT_CODE.USAGE);
+    }
+    return parsed;
+}
+function parseFieldSelectors(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const selectors = raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (selectors.length === 0) {
+        throw new PmCliError("List --fields requires a comma-separated list of field names", EXIT_CODE.USAGE);
+    }
+    return [...new Set(selectors)];
+}
+function parseProjectionConfig(options) {
+    const compactRequested = options.compact === true;
+    const briefRequested = options.brief === true;
+    const fullRequested = options.full === true;
+    const fieldSelectors = parseFieldSelectors(options.fields);
+    const enabledModes = Number(compactRequested) +
+        Number(briefRequested) +
+        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);
+    }
+    if (fullRequested) {
+        return {
+            mode: "full",
+            fields: [],
+        };
+    }
+    if (briefRequested) {
+        return {
+            mode: "compact",
+            fields: [...BRIEF_LIST_FIELDS],
+        };
+    }
+    if (compactRequested) {
+        return {
+            mode: "compact",
+            fields: [...DEFAULT_COMPACT_LIST_FIELDS],
+        };
+    }
+    if (fieldSelectors) {
+        return {
+            mode: "fields",
+            fields: fieldSelectors,
+        };
+    }
+    return {
+        mode: "full",
+        fields: [],
+    };
+}
+function normalizeProjectionField(field) {
+    return field.startsWith("item.") ? field.slice("item.".length) : field;
+}
+function validateListProjectionFields(projection, runtimeMetadataKeys) {
+    if (projection.mode !== "fields") {
+        return;
+    }
+    const allowed = new Set([
+        ...ITEM_METADATA_KEY_ORDER,
+        "body",
+        ...TREE_METADATA_FIELDS,
+        ...runtimeMetadataKeys,
+    ]);
+    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, {
+            code: "unknown_field_projection",
+            examples: [
+                "pm list-open --fields id,title,status,type,updated_at",
+                "pm list --fields id,title,parent,priority --limit 10",
+                "pm list-all --fields id,title,body --limit 5",
+            ],
+        });
+    }
+}
+// Convenience aliases so agents/humans who reach for the bare verb form
+// (e.g. `--sort updated`) land on the canonical timestamp fields instead of an error.
+// A Map (not a plain object) avoids prototype-chain lookups for keys like "__proto__".
+const LIST_SORT_FIELD_ALIASES = new Map([
+    ["updated", "updated_at"],
+    ["update", "updated_at"],
+    ["modified", "updated_at"],
+    ["created", "created_at"],
+    ["create", "created_at"],
+]);
+function parseSortField(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const normalized = raw.trim().toLowerCase();
+    const aliased = LIST_SORT_FIELD_ALIASES.get(normalized);
+    if (aliased) {
+        return aliased;
+    }
+    if (!LIST_SORT_FIELDS.includes(normalized)) {
+        throw new PmCliError(`Sort field must be one of ${LIST_SORT_FIELDS.join("|")} (aliases: updated->updated_at, created->created_at)`, EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+function parseSortOrder(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (!LIST_SORT_ORDER_VALUES.includes(normalized)) {
+        throw new PmCliError(`Sort order must be one of ${LIST_SORT_ORDER_VALUES.join("|")}`, EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+function parseTreeDepth(raw) {
+    return parseIntegerLimit(raw, "--tree-depth");
+}
+function parseAssigneeFilter(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (!normalized) {
+        throw new PmCliError("Assignee filter must be one of assigned|unassigned", EXIT_CODE.USAGE);
+    }
+    if (normalized !== "assigned" && normalized !== "unassigned") {
+        throw new PmCliError(`Invalid assignee filter "${raw}". Allowed: assigned|unassigned`, EXIT_CODE.USAGE);
+    }
+    return normalized;
+}
+// Resolve built-in, runtime, and workflow-group aliases through the shared
+// registry, rejecting typos instead of returning a misleading empty result.
+function resolveStatusFilter(status, statusRegistry) {
+    return parseStatusFilterCsv(status, statusRegistry, { strict: true });
+}
+function assertListAssigneeFilters(assigneeFilter, assigneeModeFilter) {
+    if (assigneeFilter &&
+        (assigneeFilter.toLowerCase() === "none" ||
+            assigneeFilter.toLowerCase() === "null")) {
+        throw new PmCliError('--assignee no longer accepts "none" or "null". Use --assignee-filter unassigned.', EXIT_CODE.USAGE);
+    }
+    if (assigneeFilter !== undefined && assigneeModeFilter === "unassigned") {
+        throw new PmCliError("Cannot combine --assignee with --assignee-filter unassigned", EXIT_CODE.USAGE);
+    }
+}
+function resolveListFilterSet(status, options, typeRegistry, statusRegistry) {
+    const assigneeFilter = options.assignee?.trim();
+    const assigneeModeFilter = parseAssigneeFilter(options.assigneeFilter);
+    assertListAssigneeFilters(assigneeFilter, assigneeModeFilter);
+    const missingMetadataFilters = resolveMissingMetadataFilters(options);
+    const contentFieldFilters = resolveContentFieldFilters(options);
+    return {
+        idsFilter: parseIdsFilter(options.ids),
+        statusSet: status && status.length > 0 ? new Set(status) : undefined,
+        excludeTerminal: options.excludeTerminal === true,
+        typeFilter: parseType(options.type, typeRegistry),
+        tagFilter: options.tag?.trim().toLowerCase(),
+        priorityFilter: parsePriority(options.priority),
+        deadlineBefore: parseDeadline(options.deadlineBefore, "deadline-before"),
+        deadlineAfter: parseDeadline(options.deadlineAfter, "deadline-after"),
+        updatedAfter: resolveListUpdatedAfter(options),
+        updatedBefore: parseTimestampWindow(options.updatedBefore, "updated-before"),
+        createdAfter: parseTimestampWindow(options.createdAfter, "created-after"),
+        createdBefore: parseTimestampWindow(options.createdBefore, "created-before"),
+        assigneeFilter,
+        assigneeModeFilter,
+        parentFilter: options.parent?.trim(),
+        treeEnabled: options.tree === true,
+        sprintFilter: options.sprint?.trim(),
+        releaseFilter: options.release?.trim(),
+        missingMetadataFilters,
+        missingMetadataActive: hasMissingMetadataFilter(missingMetadataFilters),
+        lifecycleClassifier: lifecycleClassifierFromStatusRegistry(statusRegistry),
+        contentFieldFilters,
+        contentFiltersActive: hasContentFieldFilter(contentFieldFilters),
+    };
+}
+function matchesListScalarFilters(item, filters, statusRegistry) {
+    return (matchesListIdentityFilters(item, filters, statusRegistry) &&
+        matchesListDateFilters(item, filters) &&
+        matchesListAssigneeFilterSet(item, filters) &&
+        matchesListScopeFilters(item, filters));
+}
+function matchesListIdentityFilters(item, filters, statusRegistry) {
+    if (filters.idsFilter && !filters.idsFilter.has(item.id))
+        return false;
+    if (filters.statusSet && !filters.statusSet.has(item.status))
+        return false;
+    if (filters.excludeTerminal && isTerminalStatus(item.status, statusRegistry))
+        return false;
+    if (filters.typeFilter && item.type !== filters.typeFilter)
+        return false;
+    if (filters.tagFilter && !(item.tags ?? []).includes(filters.tagFilter))
+        return false;
+    return (filters.priorityFilter === undefined ||
+        item.priority === filters.priorityFilter);
+}
+function matchesListDateFilters(item, filters) {
+    return matchesTimestampFilters(item, filters);
+}
+function matchesListAssigneeFilterSet(item, filters) {
+    if (filters.assigneeModeFilter === "assigned" && !item.assignee)
+        return false;
+    if (filters.assigneeModeFilter === "unassigned" && item.assignee)
+        return false;
+    return (filters.assigneeFilter === undefined ||
+        item.assignee === filters.assigneeFilter);
+}
+function matchesListScopeFilters(item, filters) {
+    if (filters.parentFilter !== undefined &&
+        !filters.treeEnabled &&
+        item.parent !== filters.parentFilter)
+        return false;
+    if (filters.sprintFilter !== undefined &&
+        item.sprint !== filters.sprintFilter)
+        return false;
+    return (filters.releaseFilter === undefined ||
+        item.release === filters.releaseFilter);
+}
+function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters) {
+    if (!matchesListScalarFilters(item, filters, statusRegistry)) {
+        return false;
+    }
+    if (filters.missingMetadataActive &&
+        !itemMatchesMissingMetadata(item, filters.missingMetadataFilters, filters.lifecycleClassifier)) {
+        return false;
+    }
+    if (filters.contentFiltersActive &&
+        !itemMatchesContentFilters(item, filters.contentFieldFilters)) {
+        return false;
+    }
+    if (!matchesRuntimeFilters(item, runtimeFieldFilters)) {
+        return false;
+    }
+    return true;
+}
+function applyFilters(items, status, options, typeRegistry, statusRegistry, runtimeFieldFilters) {
+    const filters = resolveListFilterSet(status, options, typeRegistry, statusRegistry);
+    return items.filter((item) => matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters));
+}
+function trimNonEmpty(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function withTreeMetadata(item, depth, childCount) {
+    const itemRecord = toItemRecord(item);
+    const title = typeof itemRecord.title === "string" ? itemRecord.title : "";
+    const parent = trimNonEmpty(typeof itemRecord.parent === "string" ? itemRecord.parent : undefined) ?? null;
+    return {
+        ...item,
+        tree_depth: depth,
+        tree_parent: parent,
+        tree_children: childCount,
+        tree_title: `${"  ".repeat(depth)}${title}`,
+    };
+}
+function orderItemsAsTree(sortedItems, parentRoot, maxDepth) {
+    const byId = new Map();
+    const childrenByParent = new Map();
+    for (const item of sortedItems) {
+        byId.set(item.id, item);
+        const parentId = trimNonEmpty(item.parent);
+        if (!parentId) {
+            continue;
+        }
+        const bucket = childrenByParent.get(parentId);
+        if (bucket) {
+            bucket.push(item);
+        }
+        else {
+            childrenByParent.set(parentId, [item]);
+        }
+    }
+    const roots = parentRoot
+        ? [...(childrenByParent.get(parentRoot) ?? [])]
+        : sortedItems.filter((item) => {
+            const parentId = trimNonEmpty(item.parent);
+            return !parentId || !byId.has(parentId);
+        });
+    const ordered = [];
+    const visited = new Set();
+    const pushNode = (node, depth) => {
+        if (visited.has(node.id)) {
+            return;
+        }
+        visited.add(node.id);
+        const children = childrenByParent.get(node.id) ?? [];
+        ordered.push(withTreeMetadata(node, depth, children.length));
+        if (maxDepth !== undefined && depth >= maxDepth) {
+            return;
+        }
+        for (const child of children) {
+            pushNode(child, depth + 1);
+        }
+    };
+    for (const root of roots) {
+        pushNode(root, 0);
+    }
+    return ordered;
+}
+function compareNullableString(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    if (left === null) {
+        return 1;
+    }
+    if (right === null) {
+        return -1;
+    }
+    return left.localeCompare(right);
+}
+function compareNullableTimestamp(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    if (left === null) {
+        return 1;
+    }
+    if (right === null) {
+        return -1;
+    }
+    return compareTimestampStrings(left, right);
+}
+function compareBySortField(left, right, field) {
+    switch (field) {
+        case "priority":
+            return left.priority - right.priority;
+        case "deadline":
+            return compareNullableTimestamp(left.deadline ?? null, right.deadline ?? null);
+        case "updated_at":
+            return compareTimestampStrings(left.updated_at, right.updated_at);
+        case "created_at":
+            return compareTimestampStrings(left.created_at, right.created_at);
+        case "title":
+            return (left.title ?? "").localeCompare(right.title ?? "");
+        case "parent":
+            return compareNullableString(left.parent ?? null, right.parent ?? null);
+        default:
+            return 0;
+    }
+}
+function sortItems(items, sortField, sortOrder, statusRegistry) {
+    if (!sortField) {
+        return sortItemsDefault(items, statusRegistry);
+    }
+    return [...items].sort((left, right) => {
+        const byField = compareBySortField(left, right, sortField);
+        if (byField !== 0) {
+            return sortOrder === "desc" ? -byField : byField;
+        }
+        const fallback = compareDefaultSort(left, right, statusRegistry);
+        return sortOrder === "desc" ? -fallback : fallback;
+    });
+}
+function readListFieldValue(item, field, treeMode = false) {
+    const normalized = normalizeProjectionField(field.trim());
+    if (normalized.length === 0) {
+        return null;
+    }
+    const itemRecord = toItemRecord(item);
+    if (treeMode &&
+        normalized === "title" &&
+        typeof itemRecord.tree_title === "string") {
+        return itemRecord.tree_title;
+    }
+    if (Object.prototype.hasOwnProperty.call(itemRecord, normalized)) {
+        return itemRecord[normalized] ?? null;
+    }
+    return null;
+}
+function projectListItems(items, projection, treeMode = false) {
+    if (projection.mode === "full") {
+        return items;
+    }
+    return items.map((item) => {
+        const projected = {};
+        for (const field of projection.fields) {
+            projected[field] = readListFieldValue(item, field, treeMode);
+        }
+        return projected;
+    });
+}
+function runtimeMetadataKeysForProjection(definitions) {
+    const keys = [];
+    for (const field of definitions) {
+        keys.push(field.metadata_key);
+    }
+    return keys;
+}
+function resolveListPageLimit(options, totalRows) {
+    if (options.noTruncate === true) {
+        return undefined;
+    }
+    return (parseIntegerLimit(options.limit) ?? (totalRows >= 10_000 ? 20 : undefined));
+}
+function resolveListPageStart(ordered, options, cursorFingerprint) {
+    if (options.after === undefined) {
+        return parseOffset(options.offset) ?? 0;
+    }
+    return resolveQueryCursorStart(ordered, options.after, cursorFingerprint, (item) => item.id);
+}
+function buildListPageExtras(limit, hasMore, nextCursor) {
+    return {
+        ...(limit !== undefined ? { applied_limit: limit } : {}),
+        ...(hasMore ? { has_more: true, truncated: true } : {}),
+        ...(nextCursor ? { next_cursor: nextCursor } : {}),
+    };
+}
+async function resolveListRuntimeContext(options, global) {
+    const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    if (!(await pathExists(getSettingsPath(pmRoot)))) {
+        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
+    }
+    const settings = await readSettings(pmRoot);
+    const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
+    const projection = parseProjectionConfig(options);
+    validateListProjectionFields(projection, runtimeMetadataKeysForProjection(runtimeFieldRegistry.definitions));
+    return {
+        pmRoot,
+        settings,
+        statusRegistry,
+        runtimeFieldFilters: collectRuntimeFilterValues(options, runtimeFieldRegistry, "list"),
+        typeRegistry: resolveItemTypeRegistry(settings, getActiveExtensionRegistrations()),
+        projection,
+    };
+}
+async function loadListItems(options, runtime, listWarnings) {
+    const projectionNeedsBody = runtime.projection.fields.some((field) => normalizeProjectionField(field) === "body");
+    const projectionNeedsCollections = runtime.projection.mode === "full" ||
+        runtime.projection.fields.some((field) => HEAVY_PROJECTION_FIELDS.has(normalizeProjectionField(field)));
+    const contentFieldFilters = resolveContentFieldFilters(options);
+    const contentNeedsCollections = contentFiltersNeedCollections(contentFieldFilters);
+    const contentNeedsBody = contentFiltersNeedBody(contentFieldFilters);
+    if (options.includeBody || projectionNeedsBody || contentNeedsBody) {
+        return await listAllItemMetadataWithBody(runtime.pmRoot, runtime.settings.item_format, runtime.typeRegistry.type_to_folder, listWarnings, runtime.settings.schema);
+    }
+    if (projectionNeedsCollections || contentNeedsCollections) {
+        return await listAllItemMetadata(runtime.pmRoot, runtime.settings.item_format, runtime.typeRegistry.type_to_folder, listWarnings, runtime.settings.schema);
+    }
+    return await listAllItemMetadataLight(runtime.pmRoot, runtime.settings.item_format, runtime.typeRegistry.type_to_folder, listWarnings, runtime.settings.schema);
+}
+function resolveListOrderingOptions(options) {
+    const sortField = parseSortField(options.sort);
+    const sortOrder = parseSortOrder(options.order) ?? "asc";
+    const treeEnabled = options.tree === true;
+    if (!treeEnabled && options.treeDepth !== undefined) {
+        throw new PmCliError("List --tree-depth requires --tree", EXIT_CODE.USAGE);
+    }
+    if (!sortField && options.order !== undefined) {
+        throw new PmCliError("List --order requires --sort", EXIT_CODE.USAGE);
+    }
+    return {
+        sortField,
+        sortOrder,
+        treeEnabled,
+        treeDepth: treeEnabled ? parseTreeDepth(options.treeDepth) : undefined,
+        parentRoot: treeEnabled ? trimNonEmpty(options.parent) : undefined,
+    };
+}
+function resolveListStatusSelection(status, options, statusRegistry) {
+    const explicitStatus = resolveStatusFilter(options.status, statusRegistry);
+    const resolvedStatus = explicitStatus ?? resolveStatusFilter(status, statusRegistry);
+    const explicitAllStatuses = isStatusAllFilterInput(options.status);
+    const effectiveOptions = explicitStatus || explicitAllStatuses
+        ? { ...options, excludeTerminal: false }
+        : options;
+    const filtersStatus = explicitAllStatuses
+        ? "all"
+        : resolvedStatus === undefined
+            ? null
+            : resolvedStatus.length === 1
+                ? resolvedStatus[0]
+                : resolvedStatus;
+    return {
+        resolvedStatus,
+        explicitAllStatuses,
+        effectiveOptions,
+        filtersStatus,
+    };
+}
+function pageAndProjectListItems(ordered, options, projection, treeEnabled, cursorFingerprint) {
+    if (options.after !== undefined && options.offset !== undefined) {
+        throw new PmCliError("List --after cannot be combined with --offset.", EXIT_CODE.USAGE);
+    }
+    const limit = resolveListPageLimit(options, ordered.length);
+    const offset = resolveListPageStart(ordered, options, cursorFingerprint);
+    const limited = limit === undefined
+        ? ordered.slice(offset)
+        : ordered.slice(offset, offset + limit);
+    const projected = projectListItems(limited, projection, treeEnabled);
+    const totalMatched = ordered.length;
+    const hasMore = limited.length > 0 && offset + limited.length < totalMatched;
+    const nextCursor = hasMore && limited.length > 0
+        ? encodeQueryCursor(cursorFingerprint, limited[limited.length - 1].id, offset + limited.length - 1)
+        : undefined;
+    return {
+        projected,
+        totalMatched,
+        truncationExtras: projected.length < totalMatched || offset > 0
+            ? { total: totalMatched }
+            : {},
+        pageExtras: buildListPageExtras(limit, hasMore, nextCursor),
+    };
+}
+function buildListCursorFingerprint(status, options, ordering) {
+    const normalizedOptions = { ...options };
+    delete normalizedOptions.after;
+    delete normalizedOptions.limit;
+    delete normalizedOptions.offset;
+    delete normalizedOptions.noTruncate;
+    delete normalizedOptions.includeBody;
+    delete normalizedOptions.compact;
+    delete normalizedOptions.brief;
+    delete normalizedOptions.full;
+    delete normalizedOptions.fields;
+    return createQueryFingerprint("list", {
+        status,
+        options: normalizedOptions,
+        sort: ordering.sortField ?? "default",
+        order: ordering.sortOrder,
+        tree: ordering.treeEnabled,
+        tree_depth: ordering.treeDepth ?? null,
+    });
+}
+function buildVerboseListFilters(params) {
+    const { filtersStatus, options, noTruncate, treeEnabled, treeDepth, sortField, sortOrder, runtimeFieldFilters, } = params;
+    const filters = { status: filtersStatus };
+    const optionRecord = options;
+    for (const entry of VERBOSE_LIST_VALUE_FILTER_ECHO_ENTRIES) {
+        filters[entry.summaryKey] = optionRecord[entry.optionKey] ?? null;
+    }
+    for (const entry of VERBOSE_LIST_BOOLEAN_FILTER_ECHO_ENTRIES) {
+        if (optionRecord[entry.key] === true) {
+            filters[entry.summaryKey] = true;
+        }
+    }
+    Object.assign(filters, buildGovernanceMissingFilterEcho(options), buildContentFilterEcho(options));
+    applyListWindowFilterEcho(filters, options);
+    if (noTruncate) {
+        filters.no_truncate = true;
+    }
+    if (treeEnabled) {
+        filters.tree = true;
+        filters.tree_depth = treeDepth ?? null;
+    }
+    filters.sort = sortField ?? null;
+    filters.order = sortField ? sortOrder : null;
+    filters.runtime_filters = runtimeFieldFilters;
+    return filters;
+}
+/** Execute a list query with projection-aware public result typing. */
+export async function runList(status, options, global) {
+    const runtime = await resolveListRuntimeContext(options, global);
+    const listWarnings = [];
+    const items = await loadListItems(options, runtime, listWarnings);
+    const ordering = resolveListOrderingOptions(options);
+    const statusSelection = resolveListStatusSelection(status, options, runtime.statusRegistry);
+    const filtered = applyFilters(items, statusSelection.resolvedStatus, statusSelection.effectiveOptions, runtime.typeRegistry, runtime.statusRegistry, runtime.runtimeFieldFilters);
+    const sorted = sortItems(filtered, ordering.sortField, ordering.sortOrder, runtime.statusRegistry);
+    const ordered = ordering.treeEnabled
+        ? orderItemsAsTree(sorted, ordering.parentRoot, ordering.treeDepth)
+        : sorted;
+    const noTruncate = options.noTruncate === true;
+    const page = pageAndProjectListItems(ordered, options, runtime.projection, ordering.treeEnabled, buildListCursorFingerprint(statusSelection.filtersStatus, options, ordering));
+    const now = nowIso();
+    const warnings = [...new Set(listWarnings)].sort((left, right) => left.localeCompare(right));
+    const projectionFields = runtime.projection.mode === "full" ? null : [...runtime.projection.fields];
+    const compactSummaryMode = runtime.projection.mode === "compact" && options.compact === true;
+    if (compactSummaryMode) {
+        const compactFilters = buildCompactListFilterSummary({
+            filtersStatus: statusSelection.filtersStatus,
+            options,
+            treeEnabled: ordering.treeEnabled,
+            treeDepth: ordering.treeDepth,
+            sortField: ordering.sortField,
+            sortOrder: ordering.sortOrder,
+            runtimeFieldFilters: runtime.runtimeFieldFilters,
+        });
+        return {
+            items: page.projected,
+            count: page.projected.length,
+            ...page.truncationExtras,
+            ...page.pageExtras,
+            filters: compactFilters,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    }
+    return {
+        items: page.projected,
+        count: page.projected.length,
+        ...page.truncationExtras,
+        ...page.pageExtras,
+        filters: buildVerboseListFilters({
+            filtersStatus: statusSelection.filtersStatus,
+            options,
+            noTruncate,
+            treeEnabled: ordering.treeEnabled,
+            treeDepth: ordering.treeDepth,
+            sortField: ordering.sortField,
+            sortOrder: ordering.sortOrder,
+            runtimeFieldFilters: runtime.runtimeFieldFilters,
+        }),
+        projection: {
+            mode: runtime.projection.mode,
+            fields: projectionFields,
+        },
+        sorting: {
+            sort: ordering.sortField ?? "default",
+            order: ordering.sortField ? ordering.sortOrder : "asc",
+        },
+        now,
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}
+/** Public contract for test only, shared by SDK and presentation-layer consumers. */
+export const _testOnly = {
+    applyFilters,
+    buildCompactListFilterSummary,
+    buildContentFilterEcho,
+    buildGovernanceMissingFilterEcho,
+    resolveContentFieldFilters,
+    resolveMissingMetadataFilters,
+    compareBySortField,
+    compareDefaultSort,
+    compareNullableString,
+    compareNullableTimestamp,
+    normalizeProjectionField,
+    parseAssigneeFilter,
+    parseFieldSelectors,
+    parseIdsFilter,
+    parseOffset,
+    parseProjectionConfig,
+    resolveListUpdatedAfter,
+    resolveListPageLimit,
+    parseSortField,
+    parseSortOrder,
+    orderItemsAsTree,
+    projectListItems,
+    readListFieldValue,
+    runtimeMetadataKeysForProjection,
+    sortItems,
+    trimNonEmpty,
+    withTreeMetadata,
+};
+//# sourceMappingURL=list.js.map
+//# debugId=255af95f-1741-5e74-a528-4fa8ae65ee4c