@unbrained/pm-cli 2026.6.8 → 2026.6.10

package/packages/pm-command-kit/extensions/command-kit/index.js

@@ -0,0 +1,181 @@
+/**
+ * pm-command-kit — first-party exemplar for the `commands` capability surface.
+ *
+ * Demonstrates the three command-facing SDK registration APIs:
+ * 1. `registerCommand` with a FULL CommandDefinition (name, action, description,
+ *    intent, arguments, flags, examples, failure_hints, run).
+ * 2. `registerParser` to preprocess parsed options before the command handler runs.
+ * 3. `registerFlags` to inject an additional flag into an EXISTING command.
+ *
+ * The extension is intentionally pure: no filesystem, network, environment, or
+ * process access — so its manifest declares `sandbox_profile: "strict"` with all
+ * permissions false. Third-party authors can copy this package wholesale and
+ * replace the echo behavior with their own command logic.
+ *
+ * Hand-maintained alongside index.ts: this file is import-free so the extension
+ * stays loadable in extension-only installs without SDK module resolution.
+ */
+export const manifest = {
+  name: "builtin-command-kit",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema", "parser"],
+  activation: { commands: ["command-kit echo", "list"] },
+};
+
+export const ECHO_COMMAND = "command-kit echo";
+
+function toPositiveInteger(value, fallback) {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function toDecorationList(value) {
+  const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  const seen = new Set();
+  for (const entry of raw) {
+    const trimmed = String(entry).trim();
+    if (trimmed.length > 0) {
+      seen.add(trimmed);
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * registerParser exemplar: normalize parsed options BEFORE the command handler
+ * runs. Returns a delta — only the keys you set are merged over the parsed
+ * input. Here the deprecated `--shout` alias is rewritten to `--upper`,
+ * `--repeat` is coerced to a positive integer, and `--decorations` values are
+ * trimmed and de-duplicated.
+ *
+ * @param {{ command: string, args: string[], options: Record<string, unknown>, global: Record<string, unknown>, pm_root: string }} context
+ * @returns {{ options: Record<string, unknown> }}
+ */
+export function rewriteEchoOptions(context) {
+  const options = { ...context.options };
+  if (options.shout === true || options.shout === "true") {
+    options.upper = true;
+  }
+  delete options.shout;
+  options.repeat = toPositiveInteger(options.repeat, 1);
+  if (options.decorations !== undefined) {
+    options.decorations = toDecorationList(options.decorations);
+  }
+  return { options };
+}
+
+/**
+ * Command handler: pure compute, structured result rendered by the host.
+ *
+ * @param {{ command: string, args: string[], options: Record<string, unknown>, global: Record<string, unknown>, pm_root: string }} context
+ * @returns {Record<string, unknown>}
+ */
+export function runEchoCommand(context) {
+  const args = Array.isArray(context?.args) ? context.args : [];
+  const options =
+    context?.options && typeof context.options === "object" && !Array.isArray(context.options) ? context.options : {};
+  const message = args
+    .map((arg) => String(arg).trim())
+    .filter((arg) => arg.length > 0)
+    .join(" ");
+  if (message.length === 0) {
+    throw new Error('command-kit echo requires a message argument. Try: pm command-kit echo "hello world".');
+  }
+  const upper = options.upper === true || options.upper === "true";
+  const repeat = toPositiveInteger(options.repeat, 1);
+  const decorations = toDecorationList(options.decorations);
+  const rendered = upper ? message.toUpperCase() : message;
+  return {
+    action: "command-kit-echo",
+    message: rendered,
+    lines: Array.from({ length: repeat }, () => rendered),
+    repeat,
+    upper,
+    decorations,
+  };
+}
+
+const echoFlags = [
+  {
+    long: "--upper",
+    value_type: "boolean",
+    description: "Uppercase the echoed message.",
+  },
+  {
+    long: "--shout",
+    value_type: "boolean",
+    description: "Deprecated alias for --upper; rewritten to --upper by the registered parser.",
+  },
+  {
+    long: "--repeat",
+    value_name: "count",
+    value_type: "number",
+    default: 1,
+    description: "Echo the message this many times (minimum 1).",
+  },
+  {
+    long: "--decorations",
+    value_name: "csv",
+    value_type: "string",
+    list: true,
+    description: "Comma-separated decoration labels; repeated flags accumulate.",
+  },
+];
+
+/** registerCommand exemplar: a FULL CommandDefinition with every field populated. */
+export function buildEchoCommandDefinition() {
+  return {
+    name: ECHO_COMMAND,
+    action: "command-kit-echo",
+    description: "Echo a message as structured output (commands-capability exemplar).",
+    intent: "Demonstrate every CommandDefinition field: arguments, flags, examples, and failure hints.",
+    arguments: [
+      {
+        name: "message",
+        required: true,
+        variadic: true,
+        description: "Message words to echo back.",
+      },
+    ],
+    flags: [...echoFlags],
+    examples: [
+      'pm command-kit echo "hello world"',
+      "pm command-kit echo hello --upper --repeat 2",
+      "pm command-kit echo hello --decorations star,spark --decorations wave",
+    ],
+    failure_hints: [
+      "command-kit echo requires a message argument; pass words after the command name.",
+      "--repeat takes a positive integer; invalid values fall back to 1.",
+    ],
+    run: runEchoCommand,
+  };
+}
+
+/** registerFlags exemplar: inject an inert, namespaced flag into an existing core command. */
+export const injectedListFlags = [
+  {
+    long: "--kit-note",
+    value_name: "text",
+    value_type: "string",
+    description: "Inert exemplar flag injected into `pm list` by pm-command-kit; the core list handler ignores it.",
+  },
+];
+
+/**
+ * @param {import("../../../../src/sdk/index.js").ExtensionApi} api
+ */
+export function activate(api) {
+  api.registerCommand(buildEchoCommandDefinition());
+  api.registerParser(ECHO_COMMAND, rewriteEchoOptions);
+  api.registerFlags("list", injectedListFlags);
+}
+
+export default {
+  manifest,
+  activate,
+};

package/packages/pm-command-kit/extensions/command-kit/index.ts

@@ -0,0 +1,176 @@
+/**
+ * pm-command-kit — first-party exemplar for the `commands` capability surface.
+ *
+ * Demonstrates the three command-facing SDK registration APIs:
+ * 1. `registerCommand` with a FULL CommandDefinition (name, action, description,
+ *    intent, arguments, flags, examples, failure_hints, run).
+ * 2. `registerParser` to preprocess parsed options before the command handler runs.
+ * 3. `registerFlags` to inject an additional flag into an EXISTING command.
+ *
+ * The extension is intentionally pure: no filesystem, network, environment, or
+ * process access — so its manifest declares `sandbox_profile: "strict"` with all
+ * permissions false. Third-party authors can copy this package wholesale and
+ * replace the echo behavior with their own command logic.
+ */
+import type {
+  CommandDefinition,
+  CommandHandlerContext,
+  ExtensionApi,
+  FlagDefinition,
+  ParserOverrideContext,
+  ParserOverrideDelta,
+} from "../../../../src/sdk/index.js";
+
+export const manifest = {
+  name: "builtin-command-kit",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["commands", "schema", "parser"],
+  activation: { commands: ["command-kit echo", "list"] },
+};
+
+export const ECHO_COMMAND = "command-kit echo";
+
+function toPositiveInteger(value: unknown, fallback: number): number {
+  const parsed = typeof value === "number" ? value : Number.parseInt(String(value ?? ""), 10);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function toDecorationList(value: unknown): string[] {
+  const raw: unknown[] = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+  const seen = new Set<string>();
+  for (const entry of raw) {
+    const trimmed = String(entry).trim();
+    if (trimmed.length > 0) {
+      seen.add(trimmed);
+    }
+  }
+  return [...seen];
+}
+
+/**
+ * registerParser exemplar: normalize parsed options BEFORE the command handler
+ * runs. Returns a delta — only the keys you set are merged over the parsed
+ * input. Here the deprecated `--shout` alias is rewritten to `--upper`,
+ * `--repeat` is coerced to a positive integer, and `--decorations` values are
+ * trimmed and de-duplicated.
+ */
+export function rewriteEchoOptions(context: ParserOverrideContext): ParserOverrideDelta {
+  const options: Record<string, unknown> = { ...context.options };
+  if (options.shout === true || options.shout === "true") {
+    options.upper = true;
+  }
+  delete options.shout;
+  options.repeat = toPositiveInteger(options.repeat, 1);
+  if (options.decorations !== undefined) {
+    options.decorations = toDecorationList(options.decorations);
+  }
+  return { options };
+}
+
+/** Command handler: pure compute, structured result rendered by the host. */
+export function runEchoCommand(context: CommandHandlerContext): Record<string, unknown> {
+  const args = Array.isArray(context?.args) ? context.args : [];
+  const options =
+    context?.options && typeof context.options === "object" && !Array.isArray(context.options) ? context.options : {};
+  const message = args
+    .map((arg) => String(arg).trim())
+    .filter((arg) => arg.length > 0)
+    .join(" ");
+  if (message.length === 0) {
+    throw new Error('command-kit echo requires a message argument. Try: pm command-kit echo "hello world".');
+  }
+  const upper = options.upper === true || options.upper === "true";
+  const repeat = toPositiveInteger(options.repeat, 1);
+  const decorations = toDecorationList(options.decorations);
+  const rendered = upper ? message.toUpperCase() : message;
+  return {
+    action: "command-kit-echo",
+    message: rendered,
+    lines: Array.from({ length: repeat }, () => rendered),
+    repeat,
+    upper,
+    decorations,
+  };
+}
+
+const echoFlags: FlagDefinition[] = [
+  {
+    long: "--upper",
+    value_type: "boolean",
+    description: "Uppercase the echoed message.",
+  },
+  {
+    long: "--shout",
+    value_type: "boolean",
+    description: "Deprecated alias for --upper; rewritten to --upper by the registered parser.",
+  },
+  {
+    long: "--repeat",
+    value_name: "count",
+    value_type: "number",
+    default: 1,
+    description: "Echo the message this many times (minimum 1).",
+  },
+  {
+    long: "--decorations",
+    value_name: "csv",
+    value_type: "string",
+    list: true,
+    description: "Comma-separated decoration labels; repeated flags accumulate.",
+  },
+];
+
+/** registerCommand exemplar: a FULL CommandDefinition with every field populated. */
+export function buildEchoCommandDefinition(): CommandDefinition {
+  return {
+    name: ECHO_COMMAND,
+    action: "command-kit-echo",
+    description: "Echo a message as structured output (commands-capability exemplar).",
+    intent: "Demonstrate every CommandDefinition field: arguments, flags, examples, and failure hints.",
+    arguments: [
+      {
+        name: "message",
+        required: true,
+        variadic: true,
+        description: "Message words to echo back.",
+      },
+    ],
+    flags: [...echoFlags],
+    examples: [
+      'pm command-kit echo "hello world"',
+      "pm command-kit echo hello --upper --repeat 2",
+      "pm command-kit echo hello --decorations star,spark --decorations wave",
+    ],
+    failure_hints: [
+      "command-kit echo requires a message argument; pass words after the command name.",
+      "--repeat takes a positive integer; invalid values fall back to 1.",
+    ],
+    run: runEchoCommand,
+  };
+}
+
+/** registerFlags exemplar: inject an inert, namespaced flag into an existing core command. */
+export const injectedListFlags: FlagDefinition[] = [
+  {
+    long: "--kit-note",
+    value_name: "text",
+    value_type: "string",
+    description: "Inert exemplar flag injected into `pm list` by pm-command-kit; the core list handler ignores it.",
+  },
+];
+
+export function activate(api: ExtensionApi): void {
+  api.registerCommand(buildEchoCommandDefinition());
+  api.registerParser(ECHO_COMMAND, rewriteEchoOptions);
+  api.registerFlags("list", injectedListFlags);
+}
+
+export default {
+  manifest,
+  activate,
+};

package/packages/pm-command-kit/extensions/command-kit/manifest.json

@@ -0,0 +1,22 @@
+{
+  "name": "builtin-command-kit",
+  "version": "0.1.0",
+  "entry": "./index.js",
+  "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "strict",
+  "permissions": {
+    "fs_read": false,
+    "fs_write": false,
+    "network": false,
+    "env_read": false,
+    "env_write": false,
+    "process_spawn": false
+  },
+  "capabilities": ["commands", "schema", "parser"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": ["command-kit echo", "list"]
+  }
+}

package/packages/pm-command-kit/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@unbrained/pm-command-kit",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-command-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-command-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "sdk",
+    "commands",
+    "exemplar"
+  ],
+  "pm": {
+    "aliases": [
+      "command-kit"
+    ],
+    "extensions": [
+      "extensions/command-kit"
+    ],
+    "catalog": {
+      "display_name": "Command Kit Exemplar",
+      "category": "sdk",
+      "summary": "Copy-paste-able exemplar for registerCommand, registerFlags, and registerParser.",
+      "tags": [
+        "sdk",
+        "commands",
+        "parser",
+        "exemplar"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-command-kit#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-command-kit",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

package/packages/pm-governance-audit/extensions/governance-audit/manifest.json

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "restricted",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": true,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": ["commands", "schema", "hooks"],
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",

package/packages/pm-guide-shell/extensions/guide-shell/manifest.json

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "strict",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": false,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": ["commands", "schema", "services"],
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",

package/packages/pm-lifecycle-hooks/extensions/lifecycle-hooks/manifest.json

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "strict",
+  "permissions": {
+    "fs_read": false,
+    "fs_write": false,
+    "network": false,
+    "env_read": false,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": ["hooks"],
   "manifest_version": 1,
   "pm_min_version": "2026.5.0"

package/packages/pm-linked-test-adapters/extensions/linked-test-adapters/manifest.json

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "none",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": true,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": true
+  },
   "capabilities": ["commands", "schema"],
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",

package/packages/pm-search-advanced/extensions/search-advanced/index.js

@@ -195,6 +195,12 @@ const reindexFlags = [
     value_type: "string",
     description: "Reindex mode: keyword|semantic|hybrid.",
   },
+  {
+    long: "--full",
+    value_type: "boolean",
+    description:
+      "Force full semantic/hybrid embedding rebuild; by default semantic/hybrid reindex only embeds stale items.",
+  },
   {
     long: "--progress",
     value_type: "boolean",

package/packages/pm-search-advanced/extensions/search-advanced/index.ts

@@ -217,6 +217,12 @@ const reindexFlags = [
     value_type: "string",
     description: "Reindex mode: keyword|semantic|hybrid.",
   },
+  {
+    long: "--full",
+    value_type: "boolean",
+    description:
+      "Force full semantic/hybrid embedding rebuild; by default semantic/hybrid reindex only embeds stale items.",
+  },
   {
     long: "--progress",
     value_type: "boolean",

package/packages/pm-search-advanced/extensions/search-advanced/manifest.json

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "restricted",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": true,
+    "network": true,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": [
     "commands",
     "schema",

package/packages/pm-search-advanced/extensions/search-advanced/runtime.js

@@ -138,6 +138,7 @@ function normalizeAdvancedSearchOptions(rawOptions, args) {
 function normalizeReindexOptions(rawOptions) {
   return {
     mode: readStringOption(rawOptions, "mode"),
+    full: readBooleanOption(rawOptions, "full") === true ? true : undefined,
     progress: readBooleanOption(rawOptions, "progress") === true ? true : undefined,
   };
 }

package/packages/pm-search-advanced/extensions/search-advanced/runtime.ts

@@ -211,6 +211,7 @@ function normalizeAdvancedSearchOptions(rawOptions: Record<string, unknown>, arg
 function normalizeReindexOptions(rawOptions: Record<string, unknown>): ReindexOptions {
   return {
     mode: readStringOption(rawOptions, "mode"),
+    full: readBooleanOption(rawOptions, "full") === true ? true : undefined,
     progress: readBooleanOption(rawOptions, "progress") === true ? true : undefined,
   };
 }

package/packages/pm-templates/extensions/templates/manifest.json

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "restricted",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": true,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": ["commands", "schema"],
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",

package/packages/pm-todos/extensions/todos/manifest.json

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "restricted",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": true,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": [
     "commands",
     "schema",

package/dist/cli-bundle/chunks/activity-A3QKFSSF.js

@@ -1,16 +0,0 @@
-import {
-  runActivity
-} from "./chunk-UEXNNF3K.js";
-import "./chunk-2YPVCD7T.js";
-import "./chunk-MSH23UWO.js";
-import "./chunk-FGRJZVXD.js";
-import "./chunk-2HMD3JM2.js";
-import "./chunk-K62SNVVE.js";
-import "./chunk-M7UBTVFT.js";
-import "./chunk-2BYKYPWY.js";
-import "./chunk-QFVASU44.js";
-import "./chunk-3TXWDGPU.js";
-export {
-  runActivity
-};
-//# sourceMappingURL=activity-A3QKFSSF.js.map

package/dist/cli-bundle/chunks/aggregate-GBSHSXOB.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../../../../../cli/commands/aggregate.ts"],
-  "sourcesContent": ["import { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { splitCommaList } from \"../../core/shared/split-comma-list.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\nimport { normalizeStatusInput } from \"../../core/item/status.js\";\nimport { resolveRuntimeStatusRegistry, type RuntimeStatusRegistry } from \"../../core/schema/runtime-schema.js\";\nimport { resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { type ItemStatus } from \"../../types/index.js\";\nimport { runList } from \"./list.js\";\n\ntype AggregateGroupField = \"parent\" | \"type\" | \"priority\" | \"status\" | \"assignee\" | \"tags\" | \"sprint\" | \"release\";\ntype AggregateGroupValue = string | number | null;\ntype AggregateGroupRecord = Partial<Record<AggregateGroupField, AggregateGroupValue>>;\ntype AggregateListedItem = {\n  type: string;\n  status: ItemStatus;\n  priority: number;\n  parent?: string;\n  assignee?: string;\n  tags: string[];\n  sprint?: string;\n  release?: string;\n};\n\nconst AGGREGATE_GROUP_FIELDS: AggregateGroupField[] = [\n  \"parent\",\n  \"type\",\n  \"priority\",\n  \"status\",\n  \"assignee\",\n  \"tags\",\n  \"sprint\",\n  \"release\",\n];\n\nexport interface AggregateOptions {\n  groupBy?: string;\n  count?: boolean;\n  sum?: string;\n  avg?: string;\n  includeUnparented?: boolean;\n  status?: string;\n  type?: string;\n  tag?: string;\n  priority?: string;\n  deadlineBefore?: string;\n  deadlineAfter?: string;\n  assignee?: string;\n  assigneeFilter?: string;\n  parent?: string;\n  sprint?: string;\n  release?: string;\n}\n\nexport interface AggregateRow {\n  group: AggregateGroupRecord;\n  count: number;\n  null_count?: number;\n  sum?: number | null;\n  avg?: number | null;\n}\n\nexport interface AggregateResult {\n  groups: AggregateRow[];\n  count: number;\n  totals: {\n    items_considered: number;\n    items_grouped: number;\n    items_skipped_unparented: number;\n  };\n  filters: {\n    group_by: AggregateGroupField[];\n    count: boolean;\n    sum?: string | null;\n    avg?: string | null;\n    numeric_field?: string | null;\n    include_unparented: boolean;\n    status: ItemStatus | null;\n    type: string | null;\n    tag: string | null;\n    priority: string | null;\n    deadline_before: string | null;\n    deadline_after: string | null;\n    assignee: string | null;\n    assignee_filter: string | null;\n    parent: string | null;\n    sprint: string | null;\n    release: string | null;\n  };\n  now: string;\n  warnings?: string[];\n}\n\nfunction parseStatus(raw: string | undefined, statusRegistry: RuntimeStatusRegistry): ItemStatus | undefined {\n  if (raw === undefined) {\n    return undefined;\n  }\n  const normalized = normalizeStatusInput(raw, statusRegistry);\n  if (!normalized) {\n    throw new PmCliError(\n      `Status filter must be one of ${statusRegistry.definitions.map((definition) => definition.id).join(\"|\")}`,\n      EXIT_CODE.USAGE,\n    );\n  }\n  return normalized;\n}\n\ninterface NumericAggregation {\n  field: string;\n  sum: boolean;\n  avg: boolean;\n}\n\nfunction parseNumericAggregation(options: AggregateOptions): NumericAggregation | null {\n  const sumField = options.sum?.trim();\n  const avgField = options.avg?.trim();\n  const normalizedSum = sumField && sumField.length > 0 ? sumField : undefined;\n  const normalizedAvg = avgField && avgField.length > 0 ? avgField : undefined;\n  if (!normalizedSum && !normalizedAvg) {\n    return null;\n  }\n  if (normalizedSum && normalizedAvg && normalizedSum !== normalizedAvg) {\n    throw new PmCliError(\"Aggregate --sum and --avg must target the same numeric field\", EXIT_CODE.USAGE);\n  }\n  return {\n    field: normalizedSum ?? normalizedAvg ?? \"\",\n    sum: normalizedSum !== undefined,\n    avg: normalizedAvg !== undefined,\n  };\n}\n\nfunction parseGroupBy(raw: string | undefined): AggregateGroupField[] {\n  const value = raw?.trim() ?? \"status\";\n  if (value.length === 0) {\n    throw new PmCliError(\"--group-by requires at least one field name\", EXIT_CODE.USAGE);\n  }\n  const requested = splitCommaList(value);\n  if (requested.length === 0) {\n    throw new PmCliError(\"--group-by requires a comma-separated list of fields\", EXIT_CODE.USAGE);\n  }\n  for (const field of requested) {\n    if (!AGGREGATE_GROUP_FIELDS.includes(field as AggregateGroupField)) {\n      throw new PmCliError(\n        `Aggregate group fields must be one of ${AGGREGATE_GROUP_FIELDS.join(\"|\")}; received \"${field}\"`,\n        EXIT_CODE.USAGE,\n      );\n    }\n  }\n  return requested as AggregateGroupField[];\n}\n\nfunction normalizeTagGroupValue(tags: string[]): string | null {\n  const normalized = [...new Set(tags.map((tag) => tag.trim().toLowerCase()).filter((tag) => tag.length > 0))].sort((left, right) =>\n    left.localeCompare(right),\n  );\n  if (normalized.length === 0) {\n    return null;\n  }\n  return normalized.join(\",\");\n}\n\nfunction resolveGroupValue(field: AggregateGroupField, item: AggregateListedItem): AggregateGroupValue {\n  switch (field) {\n    case \"parent\":\n      return item.parent ?? null;\n    case \"type\":\n      return item.type;\n    case \"priority\":\n      return item.priority;\n    case \"status\":\n      return item.status;\n    case \"assignee\":\n      return item.assignee ?? null;\n    case \"tags\":\n      return normalizeTagGroupValue(item.tags);\n    case \"sprint\":\n      return item.sprint ?? null;\n    case \"release\":\n      return item.release ?? null;\n    default:\n      return null;\n  }\n}\n\nfunction compareNullableGroupValue(left: AggregateGroupValue | undefined, right: AggregateGroupValue | undefined): number {\n  const leftValue = left ?? null;\n  const rightValue = right ?? null;\n  if (leftValue === rightValue) {\n    return 0;\n  }\n  if (leftValue === null) {\n    return 1;\n  }\n  if (rightValue === null) {\n    return -1;\n  }\n  if (typeof leftValue === \"number\" && typeof rightValue === \"number\") {\n    return leftValue - rightValue;\n  }\n  return String(leftValue).localeCompare(String(rightValue));\n}\n\nfunction buildGroupKey(groupBy: AggregateGroupField[], group: AggregateGroupRecord): string {\n  return groupBy.map((field) => `${field}:${JSON.stringify(group[field] ?? null)}`).join(\"|\");\n}\n\nfunction compareAggregateRows(\n  left: AggregateRow,\n  right: AggregateRow,\n  groupBy: AggregateGroupField[],\n): number {\n  for (const field of groupBy) {\n    const byField = compareNullableGroupValue(left.group[field], right.group[field]);\n    if (byField !== 0) {\n      return byField;\n    }\n  }\n  return 0;\n}\n\nfunction readNumericAggregateValue(item: AggregateListedItem, field: string): number | null {\n  const source = item as unknown as Record<string, unknown>;\n  const raw = source[field];\n  if (typeof raw === \"number\" && Number.isFinite(raw)) {\n    return raw;\n  }\n  if (typeof raw === \"string\") {\n    const trimmed = raw.trim();\n    if (trimmed.length === 0) {\n      return null;\n    }\n    const parsed = Number(trimmed);\n    if (Number.isFinite(parsed)) {\n      return parsed;\n    }\n  }\n  return null;\n}\n\ninterface AggregateAccumulator {\n  row: AggregateRow;\n  numeric_count: number;\n  numeric_sum: number;\n  null_count: number;\n}\n\nexport async function runAggregate(options: AggregateOptions, global: GlobalOptions): Promise<AggregateResult> {\n  if (options.count === false) {\n    throw new PmCliError(\"Aggregate grouped counts are always enabled; omit count=false.\", EXIT_CODE.USAGE);\n  }\n\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  const settings = await readSettings(pmRoot);\n  const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);\n  const groupBy = parseGroupBy(options.groupBy);\n  const status = parseStatus(options.status, statusRegistry);\n  const numericAggregation = parseNumericAggregation(options);\n  const includeUnparented = options.includeUnparented === true;\n\n  const listed = await runList(\n    status,\n    {\n      type: options.type,\n      tag: options.tag,\n      priority: options.priority,\n      deadlineBefore: options.deadlineBefore,\n      deadlineAfter: options.deadlineAfter,\n      assignee: options.assignee,\n      assigneeFilter: options.assigneeFilter,\n      parent: options.parent,\n      sprint: options.sprint,\n      release: options.release,\n    },\n    global,\n  );\n\n  const grouped = new Map<string, AggregateAccumulator>();\n  let skippedUnparented = 0;\n  let groupedItemCount = 0;\n\n  for (const listedItem of listed.items) {\n    const item = listedItem as AggregateListedItem;\n    const group: AggregateGroupRecord = {};\n    for (const field of groupBy) {\n      group[field] = resolveGroupValue(field, item);\n    }\n    if (groupBy.includes(\"parent\") && group.parent === null && !includeUnparented) {\n      skippedUnparented += 1;\n      continue;\n    }\n    const key = buildGroupKey(groupBy, group);\n    const existing = grouped.get(key);\n    const numericValue =\n      numericAggregation === null\n        ? null\n        : readNumericAggregateValue(item, numericAggregation.field);\n    if (existing) {\n      existing.row.count += 1;\n      if (numericAggregation !== null) {\n        if (numericValue === null) {\n          existing.null_count += 1;\n        } else {\n          existing.numeric_count += 1;\n          existing.numeric_sum += numericValue;\n        }\n      }\n    } else {\n      grouped.set(key, {\n        row: {\n          group,\n          count: 1,\n        },\n        numeric_count: numericValue === null ? 0 : 1,\n        numeric_sum: numericValue ?? 0,\n        null_count: numericValue === null ? 1 : 0,\n      });\n    }\n    groupedItemCount += 1;\n  }\n\n  const groups = [...grouped.values()]\n    .map((entry) => {\n      if (numericAggregation === null) {\n        return entry.row;\n      }\n      const withNumeric: AggregateRow = {\n        ...entry.row,\n        null_count: entry.null_count,\n      };\n      if (numericAggregation.sum) {\n        withNumeric.sum = entry.numeric_sum;\n      }\n      if (numericAggregation.avg) {\n        withNumeric.avg = entry.numeric_count === 0 ? null : entry.numeric_sum / entry.numeric_count;\n      }\n      return withNumeric;\n    })\n    .sort((left, right) => compareAggregateRows(left, right, groupBy));\n  const warnings = listed.warnings && listed.warnings.length > 0 ? listed.warnings : undefined;\n\n  return {\n    groups,\n    count: groups.length,\n    totals: {\n      items_considered: listed.items.length,\n      items_grouped: groupedItemCount,\n      items_skipped_unparented: skippedUnparented,\n    },\n    filters: {\n      group_by: groupBy,\n      count: true,\n      include_unparented: includeUnparented,\n      status: status ?? null,\n      type: options.type ?? null,\n      tag: options.tag ?? null,\n      priority: options.priority ?? null,\n      deadline_before: options.deadlineBefore ?? null,\n      deadline_after: options.deadlineAfter ?? null,\n      assignee: options.assignee ?? null,\n      assignee_filter: options.assigneeFilter ?? null,\n      parent: options.parent ?? null,\n      sprint: options.sprint ?? null,\n      release: options.release ?? null,\n      ...(numericAggregation !== null\n        ? {\n            sum: options.sum ?? null,\n            avg: options.avg ?? null,\n            numeric_field: numericAggregation.field,\n          }\n        : {}),\n    },\n    now: nowIso(),\n    ...(warnings ? { warnings } : {}),\n  };\n}\n"],
-  "mappings": "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",
-  "names": ["global"]
-}