@unbrained/pm-cli 2026.5.12 → 2026.5.14

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.5.14] - 2026-05-14
+
+### Added
+- Added shared `scripts/release/verify-published-release.mjs` and `pnpm release:verify-published` so maintainers and GitHub Actions run the same npm, `npx`, `bunx`, and GitHub Release verification logic.
+- Added installable first-party packages for calendar, templates, governance audit, guide shell, linked-test adapters, and advanced search workflows, with package catalog/list discovery and packed CLI smoke coverage.
+
+### Changed
+- Hardened daily release automation so empty `[Unreleased]` changelog content skips cleanly, generated release notes stay sourced from changelog plus pm evidence, and hosted Sentry severity thresholds match the current maintained baseline instead of blocking on known historical noise.
+- Continued the package-first refactor by moving optional workflows into bundled packages while keeping the bare CLI/SDK smaller and exposing runtime package actions through installed extension contracts.
+- Improved agent-facing command contracts, release gates, activity/audit flows, plugin launchers, and package runtime helper exports for more deterministic automation.
+
 ## [2026.5.12] - 2026-05-12
 
 ### Changed

package/PRD.md

@@ -2,7 +2,7 @@
 
 Status: Draft v1 (planning reference; pm data and runtime behavior are authoritative)
 Project: `pm` / `pm-cli`  
-Last Updated: 2026-05-01
+Last Updated: 2026-05-12
 
 ## Navigation
 
@@ -46,7 +46,6 @@ Existing trackers either rely on hosted backends, store state in non-diff-friend
 - Ship first-party installable package sources:
   - Beads import (`packages/pm-beads`, installed via `pm install`)
   - todos.ts import/export (`packages/pm-todos`, installed via `pm install`)
-  - Pi agent extension wrapper source module
 - Provide optional semantic search with provider + vector-store adapters.
 
 ## 3) Explicit Non-Goals
@@ -1377,34 +1376,14 @@ Behavior:
   - `type = "Task"`
   - `updated_at = created_at (or now if missing)`
 
-### C) Pi tool wrapper
+### C) External tool wrappers and package integrations
 
-Current baseline status (release-hardening):
+Current package-first baseline:
 
-- Implemented as a Pi agent extension source module at `.pi/extensions/pm-cli/index.ts` (outside the `pm` CLI command surface).
-- Registers one Pi tool named `pm` via Pi's extension API (`registerTool`) and maps `action` + command-shaped fields to `pm` CLI invocations.
-- Tool action enums and parameter JSON Schema are sourced from the shared command contract registry (`src/sdk/cli-contracts.ts`) to avoid drift with core CLI/completion surfaces.
-- Action dispatch currently covers the full v0.1 command-aligned set (`init`, `config`, `create`, `list`, `list-all`, `list-draft`, `list-open`, `list-in-progress`, `list-blocked`, `list-closed`, `list-canceled`, `calendar`, `context`, `get`, `search`, `reindex`, `history`, `activity`, `restore`, `update`, `close`, `delete`, `append`, `comments`, `notes`, `learnings`, `files`, `docs`, `deps`, `test`, `test-all`, `stats`, `health`, `validate`, `gc`, `completion`, `templates-save`, `templates-list`, `templates-show`, `claim`, `release`) plus extension lifecycle actions (`extension-install`, `extension-uninstall`, `extension-explore`, `extension-manage`, `extension-doctor`, `extension-adopt`, `extension-adopt-all`, `extension-activate`, `extension-deactivate`), extension action aliases (`beads-import`, `todos-import`, `todos-export`), and workflow presets (`start-task`, `pause-task`, `close-task`).
-- Invocation fallback order is deterministic for distribution resilience: attempt `pm` first, then fallback to packaged `node <package-root>/dist/cli.js` when `pm` is unavailable.
-
-- Expose one tool `pm`.
-- Parameters include:
-  - `action` enum mapped to CLI commands and workflow presets
-  - common fields (`id`, `title`, `status`, `tags`, `body`, etc.)
-  - completion parity field `shell` (`action=completion` -> `pm completion <shell>`)
-  - search-specific parity fields including `mode` and `includeLinked` (`--include-linked`)
-  - list/runtime parity fields including `offset` and `progress` where command surfaces support those flags
-  - close/validate parity fields including `validateClose`, `checkMetadata`, `checkResolution`, `checkLifecycle`, `checkStaleBlockers`, `checkFiles`, `scanMode`, `includePmInternals`, `strictExit`, `failOnWarn`, `checkHistoryDrift`, and `checkCommandReferences`
-  - contracts parity fields including `schemaOnly`, `runtimeOnly`, and `activeOnly`
-  - claim/release metadata parity fields including `author`, `message`, and `force` (`--author`, `--message`, `--force`)
-  - create/update scalar parity fields using camelCase wrapper parameters that forward to the canonical CLI flags for planning/workflow metadata (`parent`, `reviewer`, `risk`, `confidence`, `sprint`, `release`, `blockedBy`, `blockedReason`, `unblockNote`, `definitionOfReady`, `order`, `goal`, `objective`, `value`, `impact`, `outcome`, `whyNow`, `closeReason`) and issue metadata (`reporter`, `severity`, `environment`, `reproSteps`, `resolution`, `expectedResult`, `actualResult`, `affectedVersion`, `fixedVersion`, `component`, `regression`, `customerImpact`)
-  - explicit empty-string passthrough for empty-allowed CLI flags (for example `--description ""` and `--body ""`)
-  - numeric scalar parity for numeric CLI flags: wrapper accepts either JSON numbers or strings for `priority`, `estimate`, `limit`, and `timeout`, then stringifies values for deterministic CLI argument emission
-- Return object:
-  - `content: [{ type: "text", text: <TOON or JSON string> }]`
-  - `details: <structured object>`
-
-Wrapper behavior must remain aligned with CLI semantics and exit conditions.
+- The bare CLI and SDK expose provider-neutral contracts through `pm contracts` and the SDK exports in `src/sdk/cli-contracts.ts`.
+- External agent/tool wrappers should consume those contracts instead of importing internal CLI modules or embedding provider-specific action schemas in core.
+- Optional workflow bridges belong in installable pm packages that declare `pm.extensions` resources and can be installed, diagnosed, and upgraded with `pm install`, `pm package`, and `pm upgrade`.
+- The main repository can include first-party package sources, but direct provider-specific wrappers are not part of the bare core.
 
 Schema-capability registrations are also validated deterministically at activation-time:
 

package/README.md

@@ -17,7 +17,6 @@
 | Settings, storage, search, and output | [Configuration](docs/CONFIGURATION.md) |
 | Safe test execution and linked tests | [Testing](docs/TESTING.md) |
 | Package and extension authoring | [Packages and Extensions](docs/EXTENSIONS.md) and [SDK](docs/SDK.md) |
-| Pi native package | [Pi Package](docs/PI_PACKAGE.md) |
 | Codex native integration | [Codex Plugin](docs/CODEX_PLUGIN.md) |
 | Maintainer release process (daily auto-release + local parity) | [Releasing](docs/RELEASING.md) |
 | Contributor internals | [Architecture](docs/ARCHITECTURE.md) |
@@ -59,20 +58,14 @@ For Claude Code, install the native plugin (no `pm` CLI required):
 
 This registers 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents, hybrid TUI tracking, and a session-start context hook — all without shelling out to the `pm` CLI.
 
-For Pi, install the native package integration after publish:
-
-```bash
-pi install npm:@unbrained/pm-cli
-```
-
-This registers a native `pm` tool, custom TUI panels/renderers (`/pm-board`, `/pm-item`, `/pm-history`), Pi skills, prompt templates, and optional pi-subagents setup without requiring Pi to run the `pm` shell command.
-
 `pm` packages use the same package-first vocabulary:
 
 ```bash
+pm install '*'
 pm install ./my-package
 pm package manage --project
 pm package doctor --detail summary
+pm upgrade --dry-run
 ```
 
 The legacy `pm extension ...` command remains available for existing automation.

package/dist/cli/commander-usage.js

@@ -13,6 +13,20 @@ import { normalizeBootstrapInvocation, parseBootstrapGlobalOptions, parseBootstr
 import { extractProvidedOptionFlags, normalizeLongFlag, renderPmCommand, } from "./argv-utils.js";
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
 export const BUILTIN_TYPE_HELP_VALUES = BUILTIN_ITEM_TYPE_VALUES.join("|");
+const OPTIONAL_PACKAGE_INSTALL_HINTS = {
+    calendar: "calendar",
+    cal: "calendar",
+    reindex: "search-advanced",
+    "dedupe-audit": "governance-audit",
+    "comments-audit": "governance-audit",
+    normalize: "governance-audit",
+    guide: "guide-shell",
+    completion: "guide-shell",
+    templates: "templates",
+    "test-runs": "linked-test-adapters",
+    beads: "beads",
+    todos: "todos",
+};
 export function collectRuntimeCommandPaths(root, extensionDescriptors) {
     const commandPaths = new Set();
     const queue = [...root.commands];
@@ -64,6 +78,17 @@ function toComparableFlag(flag) {
 function renderAttemptedCommand(argv) {
     return renderPmCommand(argv);
 }
+function resolveOptionalPackageInstallHint(commandPath) {
+    const topLevel = commandPath.split(" ")[0]?.trim().toLowerCase();
+    if (!topLevel) {
+        return null;
+    }
+    const packageAlias = OPTIONAL_PACKAGE_INSTALL_HINTS[topLevel];
+    if (!packageAlias) {
+        return null;
+    }
+    return `If this command comes from an optional package, install it with: pm install ${packageAlias}`;
+}
 function collectKnownLongFlags(commandName) {
     const flags = new Set();
     const contracts = resolveSubcommandFlagContractsForCommand(commandName);
@@ -156,11 +181,13 @@ export function buildUnknownCommandGuidanceFromRuntime(rawMessage, root, extensi
     fallbackTopLevel.sort((left, right) => left.localeCompare(right));
     const suggestedPaths = (rankedCandidates.length > 0 ? rankedCandidates : fallbackTopLevel).slice(0, 3);
     const examples = [...new Set(["pm --help", ...suggestedPaths.map((path) => `pm ${path} --help`)])];
+    const optionalPackageHint = resolveOptionalPackageInstallHint(normalizedUnknown);
     return {
         unknownCommandExamples: examples,
         unknownCommandNextSteps: [
             'Run "pm --help" to list commands available in this runtime, including active extensions.',
             "Use one of the suggested command paths above with --help to inspect valid flags and usage.",
+            ...(optionalPackageHint ? [optionalPackageHint] : []),
         ],
     };
 }

package/dist/cli/commander-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"commander-usage.js","sourceRoot":"/","sources":["cli/commander-usage.ts"],"names":[],"mappings":"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","sourcesContent":["import { Command } from \"commander\";\nimport { pathExists } from \"../core/fs/fs-utils.js\";\nimport { resolveItemTypeRegistry } from \"../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../core/shared/constants.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../core/store/paths.js\";\nimport { readSettings } from \"../core/store/settings.js\";\nimport { BUILTIN_ITEM_TYPE_VALUES } from \"../types/index.js\";\nimport {\n  getActiveExtensionRegistrations,\n  runActiveServiceOverride,\n} from \"../core/extensions/index.js\";\nimport { resolveSubcommandFlagContractsForCommand } from \"../sdk/cli-contracts.js\";\nimport {\n  type CommanderGuidanceContext,\n  formatCommanderErrorForDisplay,\n  formatCommanderErrorForJson,\n} from \"./error-guidance.js\";\nimport { normalizeHelpCommandPath } from \"./help-content.js\";\nimport { getCommandPath } from \"./registration-helpers.js\";\nimport {\n  normalizeBootstrapInvocation,\n  parseBootstrapGlobalOptions,\n  parseBootstrapCommandName,\n} from \"./bootstrap-args.js\";\nimport {\n  extractProvidedOptionFlags,\n  normalizeLongFlag,\n  renderPmCommand,\n} from \"./argv-utils.js\";\nimport { levenshteinDistanceWithinLimit } from \"../core/shared/levenshtein.js\";\nimport type { ExtensionCommandHelpDescriptor } from \"./extension-command-help.js\";\n\nexport const BUILTIN_TYPE_HELP_VALUES = BUILTIN_ITEM_TYPE_VALUES.join(\"|\");\n\nexport interface CommanderUsageContext extends CommanderGuidanceContext {\n  message: string;\n  commandName: string | undefined;\n  allowedTypes: string;\n}\n\nexport function collectRuntimeCommandPaths(\n  root: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): string[] {\n  const commandPaths = new Set<string>();\n  const queue: Command[] = [...root.commands];\n  while (queue.length > 0) {\n    const current = queue.shift();\n    if (!current) {\n      continue;\n    }\n    const normalizedPath = normalizeHelpCommandPath(getCommandPath(current));\n    const hasInternalSegment = normalizedPath.split(\" \").some((segment) => segment.startsWith(\"_\"));\n    if (normalizedPath.length > 0 && !hasInternalSegment) {\n      commandPaths.add(normalizedPath);\n    }\n    queue.push(...current.commands);\n  }\n  for (const descriptorPath of extensionDescriptors.keys()) {\n    const normalizedPath = normalizeHelpCommandPath(descriptorPath);\n    const hasInternalSegment = normalizedPath.split(\" \").some((segment) => segment.startsWith(\"_\"));\n    if (normalizedPath.length > 0 && !hasInternalSegment) {\n      commandPaths.add(normalizedPath);\n    }\n  }\n  return [...commandPaths].sort((left, right) => left.localeCompare(right));\n}\n\nexport function scoreCommandPathMatch(commandPath: string, queryToken: string): number {\n  const normalizedPath = commandPath.trim().toLowerCase();\n  const normalizedToken = queryToken.trim().toLowerCase();\n  if (normalizedToken.length === 0) {\n    return Number.POSITIVE_INFINITY;\n  }\n  const pathSegments = normalizedPath.split(\" \");\n  if (normalizedPath === normalizedToken) {\n    return 0;\n  }\n  if (pathSegments.includes(normalizedToken)) {\n    return 1;\n  }\n  if (pathSegments.some((segment) => segment.startsWith(normalizedToken))) {\n    return 2;\n  }\n  if (normalizedPath.includes(normalizedToken)) {\n    return 3;\n  }\n  return Number.POSITIVE_INFINITY;\n}\n\nfunction toComparableFlag(flag: string): string {\n  return normalizeLongFlag(flag).slice(2).replace(/-/g, \"\");\n}\n\nfunction renderAttemptedCommand(argv: string[]): string {\n  return renderPmCommand(argv);\n}\n\nfunction collectKnownLongFlags(commandName: string | undefined): string[] {\n  const flags = new Set<string>();\n  const contracts = resolveSubcommandFlagContractsForCommand(commandName);\n  for (const contract of contracts) {\n    if (contract.flag.startsWith(\"--\")) {\n      flags.add(normalizeLongFlag(contract.flag));\n    }\n    for (const alias of contract.aliases ?? []) {\n      if (alias.startsWith(\"--\")) {\n        flags.add(normalizeLongFlag(alias));\n      }\n    }\n  }\n  return [...flags].sort((left, right) => left.localeCompare(right));\n}\n\nfunction suggestNearestLongFlags(unknownOption: string, knownFlags: string[]): string[] {\n  if (!unknownOption.startsWith(\"--\")) {\n    return [];\n  }\n  const unknownComparable = toComparableFlag(unknownOption);\n  const maxDistance = unknownComparable.length >= 8 ? 2 : 1;\n  const candidates: Array<{ flag: string; distance: number }> = [];\n  for (const flag of knownFlags) {\n    const distance = levenshteinDistanceWithinLimit(unknownComparable, toComparableFlag(flag), maxDistance);\n    if (distance === null) {\n      continue;\n    }\n    if (distance <= 0) {\n      continue;\n    }\n    candidates.push({ flag, distance });\n  }\n  return candidates\n    .sort((left, right) => {\n      if (left.distance !== right.distance) {\n        return left.distance - right.distance;\n      }\n      return left.flag.localeCompare(right.flag);\n    })\n    .map((entry) => entry.flag)\n    .slice(0, 3);\n}\n\nfunction rewriteUnknownOptionArgv(argv: string[], unknownOption: string, replacementFlag: string): string[] | undefined {\n  for (let index = 0; index < argv.length; index += 1) {\n    const token = argv[index];\n    if (!token.startsWith(\"--\")) {\n      continue;\n    }\n    const equalsIndex = token.indexOf(\"=\");\n    const key = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;\n    if (normalizeLongFlag(key) !== normalizeLongFlag(unknownOption)) {\n      continue;\n    }\n    const next = [...argv];\n    next[index] = equalsIndex >= 0 ? `${replacementFlag}${token.slice(equalsIndex)}` : replacementFlag;\n    return next;\n  }\n  return undefined;\n}\n\nexport function buildUnknownCommandGuidanceFromRuntime(\n  rawMessage: string,\n  root: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): CommanderGuidanceContext | undefined {\n  const unknownCommandMatch = rawMessage.match(/unknown command '([^']+)'/i);\n  if (!unknownCommandMatch || typeof unknownCommandMatch[1] !== \"string\") {\n    return undefined;\n  }\n  const normalizedUnknown = normalizeHelpCommandPath(unknownCommandMatch[1]);\n  if (normalizedUnknown.length === 0) {\n    return undefined;\n  }\n  const commandPaths = collectRuntimeCommandPaths(root, extensionDescriptors);\n  if (commandPaths.length === 0) {\n    return undefined;\n  }\n\n  const primaryToken = normalizedUnknown.split(\" \")[0] ?? normalizedUnknown;\n  const rankedCandidates = commandPaths\n    .map((commandPath) => {\n      const directScore = scoreCommandPathMatch(commandPath, normalizedUnknown);\n      const fallbackScore =\n        primaryToken !== normalizedUnknown ? scoreCommandPathMatch(commandPath, primaryToken) : Number.POSITIVE_INFINITY;\n      const score = Math.min(directScore, fallbackScore);\n      return { commandPath, score };\n    })\n    .filter((entry) => Number.isFinite(entry.score))\n    .sort((left, right) => {\n      if (left.score !== right.score) {\n        return left.score - right.score;\n      }\n      return left.commandPath.localeCompare(right.commandPath);\n    })\n    .map((entry) => entry.commandPath);\n\n  const fallbackTopLevel = [...new Set(commandPaths.map((commandPath) => commandPath.split(\" \")[0]).filter((segment) => segment.length > 0))];\n  fallbackTopLevel.sort((left, right) => left.localeCompare(right));\n  const suggestedPaths = (rankedCandidates.length > 0 ? rankedCandidates : fallbackTopLevel).slice(0, 3);\n  const examples = [...new Set([\"pm --help\", ...suggestedPaths.map((path) => `pm ${path} --help`)])];\n\n  return {\n    unknownCommandExamples: examples,\n    unknownCommandNextSteps: [\n      'Run \"pm --help\" to list commands available in this runtime, including active extensions.',\n      \"Use one of the suggested command paths above with --help to inspect valid flags and usage.\",\n    ],\n  };\n}\n\nexport function resolveChildCommandByToken(parent: Command, token: string): Command | undefined {\n  const normalizedToken = token.trim().toLowerCase();\n  return parent.commands.find((candidate) => {\n    if (candidate.name().trim().toLowerCase() === normalizedToken) {\n      return true;\n    }\n    const aliases = typeof candidate.aliases === \"function\" ? candidate.aliases() : [];\n    return aliases.some((alias) => alias.trim().toLowerCase() === normalizedToken);\n  });\n}\n\nexport function isKnownHelpCommandPath(root: Command, commandPathTokens: string[]): boolean {\n  if (commandPathTokens.length === 0) {\n    return true;\n  }\n  let current = root;\n  let matchedAny = false;\n  for (const token of commandPathTokens) {\n    const next = resolveChildCommandByToken(current, token);\n    if (!next) {\n      return matchedAny;\n    }\n    matchedAny = true;\n    current = next;\n  }\n  return matchedAny;\n}\n\nexport async function resolveCommanderUsageContext(\n  error: unknown,\n  rootProgram: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): Promise<CommanderUsageContext> {\n  const rawMessage = typeof error === \"object\" && error !== null ? (error as { message?: string }).message : undefined;\n  const message = rawMessage ?? \"Invalid command usage\";\n  const invocationArgv = normalizeBootstrapInvocation(process.argv.slice(2)).argv;\n  const bootstrapGlobal = parseBootstrapGlobalOptions(invocationArgv);\n  const commandName = parseBootstrapCommandName(invocationArgv);\n  const attemptedCommand = renderAttemptedCommand(invocationArgv);\n  const providedOptionFlags = extractProvidedOptionFlags(invocationArgv);\n  let allowedTypes = BUILTIN_TYPE_HELP_VALUES;\n  try {\n    const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);\n    if (await pathExists(getSettingsPath(pmRoot))) {\n      const settings = await readSettings(pmRoot);\n      const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n      if (typeRegistry.types.length > 0) {\n        allowedTypes = typeRegistry.types.join(\"|\");\n      }\n    }\n  } catch {\n    // Fall back to built-in type guidance when settings cannot be read.\n  }\n  const unknownCommandGuidance = buildUnknownCommandGuidanceFromRuntime(message, rootProgram, extensionDescriptors);\n  const unknownOptionMatch = message.match(/unknown option '([^']+)'/i);\n  const unknownOptionSuggestions =\n    unknownOptionMatch && commandName\n      ? suggestNearestLongFlags(unknownOptionMatch[1], collectKnownLongFlags(commandName))\n      : undefined;\n  let suggestedRetryCommand: string | undefined;\n  if (unknownOptionMatch && unknownOptionSuggestions && unknownOptionSuggestions.length > 0) {\n    const rewritten = rewriteUnknownOptionArgv(invocationArgv, unknownOptionMatch[1], unknownOptionSuggestions[0]);\n    if (rewritten) {\n      suggestedRetryCommand = renderAttemptedCommand(rewritten);\n    }\n  }\n  if (!suggestedRetryCommand) {\n    const missingRequiredOption = message.match(/required option '([^']+)' not specified/i);\n    const requiredOptionToken = missingRequiredOption?.[1]?.trim().split(/\\s+/)[0]?.replace(/[,:;]+$/g, \"\");\n    if (requiredOptionToken?.startsWith(\"--\")) {\n      const hasFlag = invocationArgv.some((token) => token.startsWith(requiredOptionToken));\n      if (!hasFlag) {\n        suggestedRetryCommand = renderAttemptedCommand([...invocationArgv, requiredOptionToken, \"<value>\"]);\n      }\n    }\n  }\n  return {\n    message,\n    commandName,\n    allowedTypes,\n    attemptedCommand,\n    normalizedInvocationArgs: [...invocationArgv],\n    providedOptionFlags,\n    unknownOptionSuggestions,\n    suggestedRetryCommand,\n    ...(unknownCommandGuidance ?? {}),\n  };\n}\n\nexport async function formatCommanderUsageMessage(\n  error: unknown,\n  rootProgram: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): Promise<string> {\n  const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors);\n  const {\n    message,\n    commandName,\n    allowedTypes,\n    unknownCommandExamples,\n    unknownCommandNextSteps,\n    attemptedCommand,\n    normalizedInvocationArgs,\n    providedOptionFlags,\n    unknownOptionSuggestions,\n    suggestedRetryCommand,\n  } = usageContext;\n  const formatted = formatCommanderErrorForDisplay(message, commandName, allowedTypes, {\n    unknownCommandExamples,\n    unknownCommandNextSteps,\n    attemptedCommand,\n    normalizedInvocationArgs,\n    providedOptionFlags,\n    unknownOptionSuggestions,\n    suggestedRetryCommand,\n  });\n  const serviceOverride = await runActiveServiceOverride(\"help_format\", {\n    message: formatted,\n    command: commandName,\n    allowed_types: allowedTypes,\n  });\n  if (serviceOverride.handled && typeof serviceOverride.result === \"string\") {\n    return serviceOverride.result;\n  }\n  return formatted;\n}\n\nexport async function formatCommanderUsageJson(\n  error: unknown,\n  rootProgram: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): Promise<string> {\n  const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors);\n  const envelope = formatCommanderErrorForJson(\n    usageContext.message,\n    usageContext.commandName,\n    usageContext.allowedTypes,\n    EXIT_CODE.USAGE,\n    {\n      unknownCommandExamples: usageContext.unknownCommandExamples,\n      unknownCommandNextSteps: usageContext.unknownCommandNextSteps,\n      attemptedCommand: usageContext.attemptedCommand,\n      normalizedInvocationArgs: usageContext.normalizedInvocationArgs,\n      providedOptionFlags: usageContext.providedOptionFlags,\n      unknownOptionSuggestions: usageContext.unknownOptionSuggestions,\n      suggestedRetryCommand: usageContext.suggestedRetryCommand,\n    },\n  );\n  return JSON.stringify(envelope, null, 2);\n}\n"]}
+{"version":3,"file":"commander-usage.js","sourceRoot":"/","sources":["cli/commander-usage.ts"],"names":[],"mappings":"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","sourcesContent":["import { Command } from \"commander\";\nimport { pathExists } from \"../core/fs/fs-utils.js\";\nimport { resolveItemTypeRegistry } from \"../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../core/shared/constants.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../core/store/paths.js\";\nimport { readSettings } from \"../core/store/settings.js\";\nimport { BUILTIN_ITEM_TYPE_VALUES } from \"../types/index.js\";\nimport {\n  getActiveExtensionRegistrations,\n  runActiveServiceOverride,\n} from \"../core/extensions/index.js\";\nimport { resolveSubcommandFlagContractsForCommand } from \"../sdk/cli-contracts.js\";\nimport {\n  type CommanderGuidanceContext,\n  formatCommanderErrorForDisplay,\n  formatCommanderErrorForJson,\n} from \"./error-guidance.js\";\nimport { normalizeHelpCommandPath } from \"./help-content.js\";\nimport { getCommandPath } from \"./registration-helpers.js\";\nimport {\n  normalizeBootstrapInvocation,\n  parseBootstrapGlobalOptions,\n  parseBootstrapCommandName,\n} from \"./bootstrap-args.js\";\nimport {\n  extractProvidedOptionFlags,\n  normalizeLongFlag,\n  renderPmCommand,\n} from \"./argv-utils.js\";\nimport { levenshteinDistanceWithinLimit } from \"../core/shared/levenshtein.js\";\nimport type { ExtensionCommandHelpDescriptor } from \"./extension-command-help.js\";\n\nexport const BUILTIN_TYPE_HELP_VALUES = BUILTIN_ITEM_TYPE_VALUES.join(\"|\");\n\nconst OPTIONAL_PACKAGE_INSTALL_HINTS: Record<string, string> = {\n  calendar: \"calendar\",\n  cal: \"calendar\",\n  reindex: \"search-advanced\",\n  \"dedupe-audit\": \"governance-audit\",\n  \"comments-audit\": \"governance-audit\",\n  normalize: \"governance-audit\",\n  guide: \"guide-shell\",\n  completion: \"guide-shell\",\n  templates: \"templates\",\n  \"test-runs\": \"linked-test-adapters\",\n  beads: \"beads\",\n  todos: \"todos\",\n};\n\nexport interface CommanderUsageContext extends CommanderGuidanceContext {\n  message: string;\n  commandName: string | undefined;\n  allowedTypes: string;\n}\n\nexport function collectRuntimeCommandPaths(\n  root: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): string[] {\n  const commandPaths = new Set<string>();\n  const queue: Command[] = [...root.commands];\n  while (queue.length > 0) {\n    const current = queue.shift();\n    if (!current) {\n      continue;\n    }\n    const normalizedPath = normalizeHelpCommandPath(getCommandPath(current));\n    const hasInternalSegment = normalizedPath.split(\" \").some((segment) => segment.startsWith(\"_\"));\n    if (normalizedPath.length > 0 && !hasInternalSegment) {\n      commandPaths.add(normalizedPath);\n    }\n    queue.push(...current.commands);\n  }\n  for (const descriptorPath of extensionDescriptors.keys()) {\n    const normalizedPath = normalizeHelpCommandPath(descriptorPath);\n    const hasInternalSegment = normalizedPath.split(\" \").some((segment) => segment.startsWith(\"_\"));\n    if (normalizedPath.length > 0 && !hasInternalSegment) {\n      commandPaths.add(normalizedPath);\n    }\n  }\n  return [...commandPaths].sort((left, right) => left.localeCompare(right));\n}\n\nexport function scoreCommandPathMatch(commandPath: string, queryToken: string): number {\n  const normalizedPath = commandPath.trim().toLowerCase();\n  const normalizedToken = queryToken.trim().toLowerCase();\n  if (normalizedToken.length === 0) {\n    return Number.POSITIVE_INFINITY;\n  }\n  const pathSegments = normalizedPath.split(\" \");\n  if (normalizedPath === normalizedToken) {\n    return 0;\n  }\n  if (pathSegments.includes(normalizedToken)) {\n    return 1;\n  }\n  if (pathSegments.some((segment) => segment.startsWith(normalizedToken))) {\n    return 2;\n  }\n  if (normalizedPath.includes(normalizedToken)) {\n    return 3;\n  }\n  return Number.POSITIVE_INFINITY;\n}\n\nfunction toComparableFlag(flag: string): string {\n  return normalizeLongFlag(flag).slice(2).replace(/-/g, \"\");\n}\n\nfunction renderAttemptedCommand(argv: string[]): string {\n  return renderPmCommand(argv);\n}\n\nfunction resolveOptionalPackageInstallHint(commandPath: string): string | null {\n  const topLevel = commandPath.split(\" \")[0]?.trim().toLowerCase();\n  if (!topLevel) {\n    return null;\n  }\n  const packageAlias = OPTIONAL_PACKAGE_INSTALL_HINTS[topLevel];\n  if (!packageAlias) {\n    return null;\n  }\n  return `If this command comes from an optional package, install it with: pm install ${packageAlias}`;\n}\n\nfunction collectKnownLongFlags(commandName: string | undefined): string[] {\n  const flags = new Set<string>();\n  const contracts = resolveSubcommandFlagContractsForCommand(commandName);\n  for (const contract of contracts) {\n    if (contract.flag.startsWith(\"--\")) {\n      flags.add(normalizeLongFlag(contract.flag));\n    }\n    for (const alias of contract.aliases ?? []) {\n      if (alias.startsWith(\"--\")) {\n        flags.add(normalizeLongFlag(alias));\n      }\n    }\n  }\n  return [...flags].sort((left, right) => left.localeCompare(right));\n}\n\nfunction suggestNearestLongFlags(unknownOption: string, knownFlags: string[]): string[] {\n  if (!unknownOption.startsWith(\"--\")) {\n    return [];\n  }\n  const unknownComparable = toComparableFlag(unknownOption);\n  const maxDistance = unknownComparable.length >= 8 ? 2 : 1;\n  const candidates: Array<{ flag: string; distance: number }> = [];\n  for (const flag of knownFlags) {\n    const distance = levenshteinDistanceWithinLimit(unknownComparable, toComparableFlag(flag), maxDistance);\n    if (distance === null) {\n      continue;\n    }\n    if (distance <= 0) {\n      continue;\n    }\n    candidates.push({ flag, distance });\n  }\n  return candidates\n    .sort((left, right) => {\n      if (left.distance !== right.distance) {\n        return left.distance - right.distance;\n      }\n      return left.flag.localeCompare(right.flag);\n    })\n    .map((entry) => entry.flag)\n    .slice(0, 3);\n}\n\nfunction rewriteUnknownOptionArgv(argv: string[], unknownOption: string, replacementFlag: string): string[] | undefined {\n  for (let index = 0; index < argv.length; index += 1) {\n    const token = argv[index];\n    if (!token.startsWith(\"--\")) {\n      continue;\n    }\n    const equalsIndex = token.indexOf(\"=\");\n    const key = equalsIndex >= 0 ? token.slice(0, equalsIndex) : token;\n    if (normalizeLongFlag(key) !== normalizeLongFlag(unknownOption)) {\n      continue;\n    }\n    const next = [...argv];\n    next[index] = equalsIndex >= 0 ? `${replacementFlag}${token.slice(equalsIndex)}` : replacementFlag;\n    return next;\n  }\n  return undefined;\n}\n\nexport function buildUnknownCommandGuidanceFromRuntime(\n  rawMessage: string,\n  root: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): CommanderGuidanceContext | undefined {\n  const unknownCommandMatch = rawMessage.match(/unknown command '([^']+)'/i);\n  if (!unknownCommandMatch || typeof unknownCommandMatch[1] !== \"string\") {\n    return undefined;\n  }\n  const normalizedUnknown = normalizeHelpCommandPath(unknownCommandMatch[1]);\n  if (normalizedUnknown.length === 0) {\n    return undefined;\n  }\n  const commandPaths = collectRuntimeCommandPaths(root, extensionDescriptors);\n  if (commandPaths.length === 0) {\n    return undefined;\n  }\n\n  const primaryToken = normalizedUnknown.split(\" \")[0] ?? normalizedUnknown;\n  const rankedCandidates = commandPaths\n    .map((commandPath) => {\n      const directScore = scoreCommandPathMatch(commandPath, normalizedUnknown);\n      const fallbackScore =\n        primaryToken !== normalizedUnknown ? scoreCommandPathMatch(commandPath, primaryToken) : Number.POSITIVE_INFINITY;\n      const score = Math.min(directScore, fallbackScore);\n      return { commandPath, score };\n    })\n    .filter((entry) => Number.isFinite(entry.score))\n    .sort((left, right) => {\n      if (left.score !== right.score) {\n        return left.score - right.score;\n      }\n      return left.commandPath.localeCompare(right.commandPath);\n    })\n    .map((entry) => entry.commandPath);\n\n  const fallbackTopLevel = [...new Set(commandPaths.map((commandPath) => commandPath.split(\" \")[0]).filter((segment) => segment.length > 0))];\n  fallbackTopLevel.sort((left, right) => left.localeCompare(right));\n  const suggestedPaths = (rankedCandidates.length > 0 ? rankedCandidates : fallbackTopLevel).slice(0, 3);\n  const examples = [...new Set([\"pm --help\", ...suggestedPaths.map((path) => `pm ${path} --help`)])];\n  const optionalPackageHint = resolveOptionalPackageInstallHint(normalizedUnknown);\n\n  return {\n    unknownCommandExamples: examples,\n    unknownCommandNextSteps: [\n      'Run \"pm --help\" to list commands available in this runtime, including active extensions.',\n      \"Use one of the suggested command paths above with --help to inspect valid flags and usage.\",\n      ...(optionalPackageHint ? [optionalPackageHint] : []),\n    ],\n  };\n}\n\nexport function resolveChildCommandByToken(parent: Command, token: string): Command | undefined {\n  const normalizedToken = token.trim().toLowerCase();\n  return parent.commands.find((candidate) => {\n    if (candidate.name().trim().toLowerCase() === normalizedToken) {\n      return true;\n    }\n    const aliases = typeof candidate.aliases === \"function\" ? candidate.aliases() : [];\n    return aliases.some((alias) => alias.trim().toLowerCase() === normalizedToken);\n  });\n}\n\nexport function isKnownHelpCommandPath(root: Command, commandPathTokens: string[]): boolean {\n  if (commandPathTokens.length === 0) {\n    return true;\n  }\n  let current = root;\n  let matchedAny = false;\n  for (const token of commandPathTokens) {\n    const next = resolveChildCommandByToken(current, token);\n    if (!next) {\n      return matchedAny;\n    }\n    matchedAny = true;\n    current = next;\n  }\n  return matchedAny;\n}\n\nexport async function resolveCommanderUsageContext(\n  error: unknown,\n  rootProgram: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): Promise<CommanderUsageContext> {\n  const rawMessage = typeof error === \"object\" && error !== null ? (error as { message?: string }).message : undefined;\n  const message = rawMessage ?? \"Invalid command usage\";\n  const invocationArgv = normalizeBootstrapInvocation(process.argv.slice(2)).argv;\n  const bootstrapGlobal = parseBootstrapGlobalOptions(invocationArgv);\n  const commandName = parseBootstrapCommandName(invocationArgv);\n  const attemptedCommand = renderAttemptedCommand(invocationArgv);\n  const providedOptionFlags = extractProvidedOptionFlags(invocationArgv);\n  let allowedTypes = BUILTIN_TYPE_HELP_VALUES;\n  try {\n    const pmRoot = resolvePmRoot(process.cwd(), bootstrapGlobal.path);\n    if (await pathExists(getSettingsPath(pmRoot))) {\n      const settings = await readSettings(pmRoot);\n      const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n      if (typeRegistry.types.length > 0) {\n        allowedTypes = typeRegistry.types.join(\"|\");\n      }\n    }\n  } catch {\n    // Fall back to built-in type guidance when settings cannot be read.\n  }\n  const unknownCommandGuidance = buildUnknownCommandGuidanceFromRuntime(message, rootProgram, extensionDescriptors);\n  const unknownOptionMatch = message.match(/unknown option '([^']+)'/i);\n  const unknownOptionSuggestions =\n    unknownOptionMatch && commandName\n      ? suggestNearestLongFlags(unknownOptionMatch[1], collectKnownLongFlags(commandName))\n      : undefined;\n  let suggestedRetryCommand: string | undefined;\n  if (unknownOptionMatch && unknownOptionSuggestions && unknownOptionSuggestions.length > 0) {\n    const rewritten = rewriteUnknownOptionArgv(invocationArgv, unknownOptionMatch[1], unknownOptionSuggestions[0]);\n    if (rewritten) {\n      suggestedRetryCommand = renderAttemptedCommand(rewritten);\n    }\n  }\n  if (!suggestedRetryCommand) {\n    const missingRequiredOption = message.match(/required option '([^']+)' not specified/i);\n    const requiredOptionToken = missingRequiredOption?.[1]?.trim().split(/\\s+/)[0]?.replace(/[,:;]+$/g, \"\");\n    if (requiredOptionToken?.startsWith(\"--\")) {\n      const hasFlag = invocationArgv.some((token) => token.startsWith(requiredOptionToken));\n      if (!hasFlag) {\n        suggestedRetryCommand = renderAttemptedCommand([...invocationArgv, requiredOptionToken, \"<value>\"]);\n      }\n    }\n  }\n  return {\n    message,\n    commandName,\n    allowedTypes,\n    attemptedCommand,\n    normalizedInvocationArgs: [...invocationArgv],\n    providedOptionFlags,\n    unknownOptionSuggestions,\n    suggestedRetryCommand,\n    ...(unknownCommandGuidance ?? {}),\n  };\n}\n\nexport async function formatCommanderUsageMessage(\n  error: unknown,\n  rootProgram: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): Promise<string> {\n  const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors);\n  const {\n    message,\n    commandName,\n    allowedTypes,\n    unknownCommandExamples,\n    unknownCommandNextSteps,\n    attemptedCommand,\n    normalizedInvocationArgs,\n    providedOptionFlags,\n    unknownOptionSuggestions,\n    suggestedRetryCommand,\n  } = usageContext;\n  const formatted = formatCommanderErrorForDisplay(message, commandName, allowedTypes, {\n    unknownCommandExamples,\n    unknownCommandNextSteps,\n    attemptedCommand,\n    normalizedInvocationArgs,\n    providedOptionFlags,\n    unknownOptionSuggestions,\n    suggestedRetryCommand,\n  });\n  const serviceOverride = await runActiveServiceOverride(\"help_format\", {\n    message: formatted,\n    command: commandName,\n    allowed_types: allowedTypes,\n  });\n  if (serviceOverride.handled && typeof serviceOverride.result === \"string\") {\n    return serviceOverride.result;\n  }\n  return formatted;\n}\n\nexport async function formatCommanderUsageJson(\n  error: unknown,\n  rootProgram: Command,\n  extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>,\n): Promise<string> {\n  const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors);\n  const envelope = formatCommanderErrorForJson(\n    usageContext.message,\n    usageContext.commandName,\n    usageContext.allowedTypes,\n    EXIT_CODE.USAGE,\n    {\n      unknownCommandExamples: usageContext.unknownCommandExamples,\n      unknownCommandNextSteps: usageContext.unknownCommandNextSteps,\n      attemptedCommand: usageContext.attemptedCommand,\n      normalizedInvocationArgs: usageContext.normalizedInvocationArgs,\n      providedOptionFlags: usageContext.providedOptionFlags,\n      unknownOptionSuggestions: usageContext.unknownOptionSuggestions,\n      suggestedRetryCommand: usageContext.suggestedRetryCommand,\n    },\n  );\n  return JSON.stringify(envelope, null, 2);\n}\n"]}

package/dist/cli/commands/activity.js

@@ -31,6 +31,9 @@ function parseRangeBound(raw, nowValue, fieldLabel) {
     return resolveIsoOrRelative(normalized, new Date(nowValue), fieldLabel);
 }
 function includeByTimeWindow(entry, from, to) {
+    if (entry.ts.length === 0 && (from || to)) {
+        return false;
+    }
     if (from && compareTimestampStrings(entry.ts, from) < 0) {
         return false;
     }
@@ -44,6 +47,21 @@ function limitEntries(values, limit) {
         return values;
     return values.slice(0, limit);
 }
+function readActivityString(value, fallback = "") {
+    return typeof value === "string" ? value : fallback;
+}
+function normalizeActivityEntry(id, entry) {
+    return {
+        ...entry,
+        id,
+        ts: readActivityString(entry.ts),
+        author: readActivityString(entry.author, "unknown"),
+        op: readActivityString(entry.op, "unknown"),
+        patch: Array.isArray(entry.patch) ? entry.patch : [],
+        before_hash: readActivityString(entry.before_hash),
+        after_hash: readActivityString(entry.after_hash),
+    };
+}
 function sortActivity(entries) {
     return [...entries].sort((a, b) => {
         const byTimestamp = b.ts.localeCompare(a.ts);
@@ -113,10 +131,7 @@ export async function runActivity(options, global) {
             if (authorFilter && entry.author !== authorFilter) {
                 continue;
             }
-            const candidate = {
-                id,
-                ...entry,
-            };
+            const candidate = normalizeActivityEntry(id, entry);
             if (!includeByTimeWindow(candidate, fromBound, toBound)) {
                 continue;
             }

package/dist/cli/commands/activity.js.map

@@ -1 +1 @@
-{"version":3,"file":"activity.js","sourceRoot":"/","sources":["cli/commands/activity.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { getActiveExtensionRegistrations, runActiveOnReadHooks } from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { enforceHistoryStreamPolicyForItems } from \"../../core/history/history-stream-policy.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { compareTimestampStrings, nowIso, resolveIsoOrRelative } from \"../../core/shared/time.js\";\nimport { listAllFrontMatter } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { readHistoryEntries } from \"./history.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { HistoryEntry } from \"../../types/index.js\";\n\nexport interface ActivityCommandOptions {\n  id?: string;\n  op?: string;\n  author?: string;\n  from?: string;\n  to?: string;\n  limit?: string;\n  compact?: boolean;\n}\n\nexport interface ActivityEntry extends HistoryEntry {\n  id: string;\n}\n\nexport interface CompactActivityEntry {\n  id: string;\n  op: string;\n  ts: string;\n  author: string;\n  msg?: string;\n}\n\nexport interface ActivityResult {\n  activity: ActivityEntry[];\n  compact_activity?: CompactActivityEntry[];\n  compact: boolean;\n  count: number;\n  limit: number | null;\n}\n\nfunction parseNonEmptyFilter(raw: string | undefined, flagLabel: string): string | undefined {\n  if (raw === undefined) return undefined;\n  const normalized = raw.trim();\n  if (normalized.length === 0) {\n    throw new PmCliError(`${flagLabel} must not be empty`, EXIT_CODE.USAGE);\n  }\n  return normalized;\n}\n\nfunction parseRangeBound(raw: string | undefined, nowValue: string, fieldLabel: string): string | undefined {\n  if (raw === undefined) return undefined;\n  const normalized = raw.trim();\n  if (normalized.length === 0) {\n    throw new PmCliError(\"Activity time bounds must not be empty\", EXIT_CODE.USAGE);\n  }\n  return resolveIsoOrRelative(normalized, new Date(nowValue), fieldLabel);\n}\n\nfunction includeByTimeWindow(entry: ActivityEntry, from: string | undefined, to: string | undefined): boolean {\n  if (from && compareTimestampStrings(entry.ts, from) < 0) {\n    return false;\n  }\n  if (to && compareTimestampStrings(entry.ts, to) >= 0) {\n    return false;\n  }\n  return true;\n}\n\nfunction limitEntries<T>(values: T[], limit: number | undefined): T[] {\n  if (limit === undefined) return values;\n  return values.slice(0, limit);\n}\n\nfunction sortActivity(entries: ActivityEntry[]): ActivityEntry[] {\n  return [...entries].sort((a, b) => {\n    const byTimestamp = b.ts.localeCompare(a.ts);\n    if (byTimestamp !== 0) return byTimestamp;\n    const byId = a.id.localeCompare(b.id);\n    if (byId !== 0) return byId;\n    return a.op.localeCompare(b.op);\n  });\n}\n\nasync function listHistoryFiles(historyDir: string): Promise<string[]> {\n  try {\n    return (await fs.readdir(historyDir))\n      .filter((entry) => entry.endsWith(\".jsonl\"))\n      .sort((a, b) => a.localeCompare(b));\n  } catch (error: unknown) {\n    // Activity should degrade gracefully when optional history storage is absent.\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return [];\n    }\n    throw error;\n  }\n}\n\nexport async function runActivity(options: ActivityCommandOptions, global: GlobalOptions): Promise<ActivityResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n\n  const nowValue = nowIso();\n  const idFilter = parseNonEmptyFilter(options.id, \"Activity --id\");\n  const opFilter = parseNonEmptyFilter(options.op, \"Activity --op\");\n  const authorFilter = parseNonEmptyFilter(options.author, \"Activity --author\");\n  const fromBound = parseRangeBound(options.from, nowValue, \"--from\");\n  const toBound = parseRangeBound(options.to, nowValue, \"--to\");\n  if (fromBound && toBound && compareTimestampStrings(fromBound, toBound) >= 0) {\n    throw new PmCliError(\"Activity --from must be before --to\", EXIT_CODE.USAGE);\n  }\n  const limit = parseLimit(options.limit);\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const items = await listAllFrontMatter(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);\n  await enforceHistoryStreamPolicyForItems({\n    pmRoot,\n    settings,\n    itemIds: items.map((item) => item.id),\n    commandLabel: \"activity\",\n  });\n  const historyDir = path.join(pmRoot, \"history\");\n  await runActiveOnReadHooks({\n    path: historyDir,\n    scope: \"project\",\n  });\n  const historyFiles = await listHistoryFiles(historyDir);\n\n  const combined: ActivityEntry[] = [];\n  for (const file of historyFiles) {\n    const id = file.slice(0, -\".jsonl\".length);\n    if (idFilter && id !== idFilter) {\n      continue;\n    }\n    const entries = await readHistoryEntries(path.join(historyDir, file), id);\n    for (const entry of entries) {\n      if (opFilter && entry.op !== opFilter) {\n        continue;\n      }\n      if (authorFilter && entry.author !== authorFilter) {\n        continue;\n      }\n      const candidate: ActivityEntry = {\n        id,\n        ...entry,\n      };\n      if (!includeByTimeWindow(candidate, fromBound, toBound)) {\n        continue;\n      }\n      combined.push({\n        ...candidate,\n      });\n    }\n  }\n\n  const activity = limitEntries(sortActivity(combined), limit);\n  const compact = options.compact === true;\n  const compactActivity = compact\n    ? activity.map((entry): CompactActivityEntry => ({\n        id: entry.id,\n        op: entry.op,\n        ts: entry.ts,\n        author: entry.author,\n        ...(entry.message ? { msg: entry.message } : {}),\n      }))\n    : undefined;\n  return {\n    activity: compact ? [] : activity,\n    compact_activity: compactActivity,\n    compact,\n    count: activity.length,\n    limit: limit ?? null,\n  };\n}\n"]}
+{"version":3,"file":"activity.js","sourceRoot":"/","sources":["cli/commands/activity.ts"],"names":[],"mappings":"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","sourcesContent":["import fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { getActiveExtensionRegistrations, runActiveOnReadHooks } from \"../../core/extensions/index.js\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { enforceHistoryStreamPolicyForItems } from \"../../core/history/history-stream-policy.js\";\nimport { resolveItemTypeRegistry } from \"../../core/item/type-registry.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport type { GlobalOptions } from \"../../core/shared/command-types.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { compareTimestampStrings, nowIso, resolveIsoOrRelative } from \"../../core/shared/time.js\";\nimport { listAllFrontMatter } from \"../../core/store/item-store.js\";\nimport { getSettingsPath, resolvePmRoot } from \"../../core/store/paths.js\";\nimport { readSettings } from \"../../core/store/settings.js\";\nimport { readHistoryEntries } from \"./history.js\";\nimport { parseLimit } from \"../shared-parsers.js\";\nimport type { HistoryEntry } from \"../../types/index.js\";\n\nexport interface ActivityCommandOptions {\n  id?: string;\n  op?: string;\n  author?: string;\n  from?: string;\n  to?: string;\n  limit?: string;\n  compact?: boolean;\n}\n\nexport interface ActivityEntry extends HistoryEntry {\n  id: string;\n}\n\nexport interface CompactActivityEntry {\n  id: string;\n  op: string;\n  ts: string;\n  author: string;\n  msg?: string;\n}\n\nexport interface ActivityResult {\n  activity: ActivityEntry[];\n  compact_activity?: CompactActivityEntry[];\n  compact: boolean;\n  count: number;\n  limit: number | null;\n}\n\nfunction parseNonEmptyFilter(raw: string | undefined, flagLabel: string): string | undefined {\n  if (raw === undefined) return undefined;\n  const normalized = raw.trim();\n  if (normalized.length === 0) {\n    throw new PmCliError(`${flagLabel} must not be empty`, EXIT_CODE.USAGE);\n  }\n  return normalized;\n}\n\nfunction parseRangeBound(raw: string | undefined, nowValue: string, fieldLabel: string): string | undefined {\n  if (raw === undefined) return undefined;\n  const normalized = raw.trim();\n  if (normalized.length === 0) {\n    throw new PmCliError(\"Activity time bounds must not be empty\", EXIT_CODE.USAGE);\n  }\n  return resolveIsoOrRelative(normalized, new Date(nowValue), fieldLabel);\n}\n\nfunction includeByTimeWindow(entry: ActivityEntry, from: string | undefined, to: string | undefined): boolean {\n  if (entry.ts.length === 0 && (from || to)) {\n    return false;\n  }\n  if (from && compareTimestampStrings(entry.ts, from) < 0) {\n    return false;\n  }\n  if (to && compareTimestampStrings(entry.ts, to) >= 0) {\n    return false;\n  }\n  return true;\n}\n\nfunction limitEntries<T>(values: T[], limit: number | undefined): T[] {\n  if (limit === undefined) return values;\n  return values.slice(0, limit);\n}\n\nfunction readActivityString(value: unknown, fallback = \"\"): string {\n  return typeof value === \"string\" ? value : fallback;\n}\n\nfunction normalizeActivityEntry(id: string, entry: HistoryEntry): ActivityEntry {\n  return {\n    ...entry,\n    id,\n    ts: readActivityString(entry.ts),\n    author: readActivityString(entry.author, \"unknown\"),\n    op: readActivityString(entry.op, \"unknown\"),\n    patch: Array.isArray(entry.patch) ? entry.patch : [],\n    before_hash: readActivityString(entry.before_hash),\n    after_hash: readActivityString(entry.after_hash),\n  };\n}\n\nfunction sortActivity(entries: ActivityEntry[]): ActivityEntry[] {\n  return [...entries].sort((a, b) => {\n    const byTimestamp = b.ts.localeCompare(a.ts);\n    if (byTimestamp !== 0) return byTimestamp;\n    const byId = a.id.localeCompare(b.id);\n    if (byId !== 0) return byId;\n    return a.op.localeCompare(b.op);\n  });\n}\n\nasync function listHistoryFiles(historyDir: string): Promise<string[]> {\n  try {\n    return (await fs.readdir(historyDir))\n      .filter((entry) => entry.endsWith(\".jsonl\"))\n      .sort((a, b) => a.localeCompare(b));\n  } catch (error: unknown) {\n    // Activity should degrade gracefully when optional history storage is absent.\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return [];\n    }\n    throw error;\n  }\n}\n\nexport async function runActivity(options: ActivityCommandOptions, global: GlobalOptions): Promise<ActivityResult> {\n  const pmRoot = resolvePmRoot(process.cwd(), global.path);\n  if (!(await pathExists(getSettingsPath(pmRoot)))) {\n    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);\n  }\n\n  const nowValue = nowIso();\n  const idFilter = parseNonEmptyFilter(options.id, \"Activity --id\");\n  const opFilter = parseNonEmptyFilter(options.op, \"Activity --op\");\n  const authorFilter = parseNonEmptyFilter(options.author, \"Activity --author\");\n  const fromBound = parseRangeBound(options.from, nowValue, \"--from\");\n  const toBound = parseRangeBound(options.to, nowValue, \"--to\");\n  if (fromBound && toBound && compareTimestampStrings(fromBound, toBound) >= 0) {\n    throw new PmCliError(\"Activity --from must be before --to\", EXIT_CODE.USAGE);\n  }\n  const limit = parseLimit(options.limit);\n  const settings = await readSettings(pmRoot);\n  const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());\n  const items = await listAllFrontMatter(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);\n  await enforceHistoryStreamPolicyForItems({\n    pmRoot,\n    settings,\n    itemIds: items.map((item) => item.id),\n    commandLabel: \"activity\",\n  });\n  const historyDir = path.join(pmRoot, \"history\");\n  await runActiveOnReadHooks({\n    path: historyDir,\n    scope: \"project\",\n  });\n  const historyFiles = await listHistoryFiles(historyDir);\n\n  const combined: ActivityEntry[] = [];\n  for (const file of historyFiles) {\n    const id = file.slice(0, -\".jsonl\".length);\n    if (idFilter && id !== idFilter) {\n      continue;\n    }\n    const entries = await readHistoryEntries(path.join(historyDir, file), id);\n    for (const entry of entries) {\n      if (opFilter && entry.op !== opFilter) {\n        continue;\n      }\n      if (authorFilter && entry.author !== authorFilter) {\n        continue;\n      }\n      const candidate = normalizeActivityEntry(id, entry);\n      if (!includeByTimeWindow(candidate, fromBound, toBound)) {\n        continue;\n      }\n      combined.push({\n        ...candidate,\n      });\n    }\n  }\n\n  const activity = limitEntries(sortActivity(combined), limit);\n  const compact = options.compact === true;\n  const compactActivity = compact\n    ? activity.map((entry): CompactActivityEntry => ({\n        id: entry.id,\n        op: entry.op,\n        ts: entry.ts,\n        author: entry.author,\n        ...(entry.message ? { msg: entry.message } : {}),\n      }))\n    : undefined;\n  return {\n    activity: compact ? [] : activity,\n    compact_activity: compactActivity,\n    compact,\n    count: activity.length,\n    limit: limit ?? null,\n  };\n}\n"]}

package/dist/cli/commands/calendar.js

@@ -724,6 +724,9 @@ export async function runCalendar(options, global) {
     const hasExplicitBounds = options.to !== undefined || explicitLookahead !== undefined || occurrenceLimit !== undefined;
     const eventsOnlyCapApplied = eventsOnly && !hasExplicitBounds;
     const recurrenceLookaheadDays = eventsOnlyCapApplied ? DEFAULT_EVENTS_ONLY_LOOKAHEAD_DAYS : explicitLookahead;
+    const recurrenceLookbackWindowDays = eventsOnlyCapApplied && recurrenceLookbackDays === undefined
+        ? 0
+        : recurrenceLookbackDays;
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
@@ -731,11 +734,11 @@ export async function runCalendar(options, global) {
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const listWarnings = [];
     if (eventsOnlyCapApplied) {
-        listWarnings.push(`recurring_events_default_cap_applied:${DEFAULT_EVENTS_ONLY_LOOKAHEAD_DAYS}d -- use --recurrence-lookahead-days or --to for wider range`);
+        listWarnings.push(`recurring_events_default_cap_applied:lookback=0d,lookahead=${DEFAULT_EVENTS_ONLY_LOOKAHEAD_DAYS}d -- use --recurrence-lookback-days/--recurrence-lookahead-days or --to for wider range`);
     }
     const items = await listAllFrontMatter(pmRoot, settings.item_format, typeRegistry.type_to_folder, listWarnings, settings.schema);
     const filteredItems = filterItems(items, options, typeRegistry, statusRegistry, runtimeFieldFilters);
-    const recurringWindow = buildRecurringEventWindow(rangeBounds.start, rangeBounds.end, nowValue, recurrenceLookbackDays, recurrenceLookaheadDays);
+    const recurringWindow = buildRecurringEventWindow(rangeBounds.start, rangeBounds.end, nowValue, recurrenceLookbackWindowDays, recurrenceLookaheadDays);
     const seededEvents = buildEventSeed(filteredItems, recurringWindow, includeSources, occurrenceLimit);
     const rangedEvents = seededEvents.filter((event) => includeEventInWindow(event, rangeBounds.start, rangeBounds.end));
     const limitedEvents = limit === undefined ? rangedEvents : rangedEvents.slice(0, limit);