@unbrained/pm-cli 2026.9.25 → 2026.9.27

package/.agents/skills/README.md

@@ -24,6 +24,7 @@ it. `docs/COMMANDS.md` is ~29k tokens and `docs/SDK.md` is ~45k.
 | Skill                             | Use when                                              |
 | --------------------------------- | ------------------------------------------------------ |
 | [`pm-developer`](pm-developer/SKILL.md) | Changing code, docs, tests, or release gates      |
+| [`pm-test-audit`](pm-test-audit/SKILL.md) | Writing, reviewing, or auditing tests and their regression value |
 | [`pm-user`](pm-user/SKILL.md)     | Intake, triage, prioritization, planning, reporting    |
 | [`pm-extensions`](pm-extensions/SKILL.md) | Package and extension lifecycle and authoring  |
 | [`pm-sdk`](pm-sdk/SKILL.md)       | Integrations, embedding, and domain packs on the SDK   |

package/.agents/skills/pm-developer/SKILL.md

@@ -106,6 +106,9 @@ Always read the `omission_receipt` before treating a result as complete. See
 
 ## Verification Defaults
 
+For test authoring, review, or cleanup, apply [pm-test-audit](../pm-test-audit/SKILL.md)
+to preserve independent contracts while removing low-value duplication.
+
 ```bash
 pnpm build
 node scripts/run-tests.mjs test -- <targets>

package/.agents/skills/pm-test-audit/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/.agents/skills/pm-test-audit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: pm-test-audit
+description: Use when writing, changing, reviewing, or auditing pm-cli tests. Checks regression value, duplicate coverage, implementation coupling, and test-only production seams while preserving SDK contracts, sandbox isolation, and exact coverage gates.
+license: MIT
+compatibility: Repository development with Node.js, pnpm, and the checkout-built pm CLI.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: test-quality
+---
+
+# pm Test Audit
+
+Tracker: [pm-xvibt6](../../pm/tasks/pm-xvibt6.toon).
+Adapted from OpenClaw's [test-audit skill](https://github.com/openclaw/openclaw/blob/e0d80000067d224e93af6107ed093a21e046879f/.agents/skills/test-audit/SKILL.md);
+upstream copyright and terms are in [LICENSE.txt](LICENSE.txt).
+
+Use alongside [pm-developer](../pm-developer/SKILL.md). Project management is
+context management: retain why a test exists, its contract owner, and the
+regression evidence so the next audit need not rediscover them.
+
+## Choose the Scope
+
+- **Authoring:** apply the four questions below before adding or changing tests.
+- **Audit:** read [audit evidence](references/AUDIT.md) before proposing removals.
+- **Campaign:** also read [campaign procedure](references/CAMPAIGN.md) for a broad sweep.
+
+Do not expand a focused request into a repository-wide deletion campaign.
+
+## Four Questions Before Editing
+
+1. What observable behavior, invariant, or independent contract does this prove?
+2. What credible regression makes it fail? For a bug fix, demonstrate the intended
+   failure before the fix and success afterward with the same test and harness.
+3. Why does existing coverage not catch it? Choose one primary owner at the
+   strongest useful boundary. An additional layer needs a distinct risk, such as
+   CLI parsing, MCP transport, persistence, or package installation. Extend a
+   table or shared fixture when the behavior and setup are already covered.
+4. Does it demand a production export, flag, wrapper, or injection hook solely
+   to observe private details? Prefer exercising the real boundary. Published
+   `@unbrained/pm-cli/sdk/testing` helpers are public contracts, not automatically
+   disposable test-only seams.
+
+Domain semantics belong in the SDK; thin CLI/MCP adapters need their own transport
+proof, not copies of every SDK case. Read complete tests and production owners
+before editing, plus relevant callers, neighboring tests, history, and scoped
+`AGENTS.md`. Inspect actual dependency types in `node_modules`; do not guess APIs.
+
+## Verification and Safety
+
+Follow [Testing](../../../docs/TESTING.md) for the affected surface. Use the
+repository runner, which isolates tracker roots and builds the checkout:
+
+```bash
+node scripts/run-tests.mjs test -- <target>
+node scripts/run-tests.mjs coverage
+```
+
+- Never run tests against the real `.agents/pm`. Manual dogfood uses a temporary
+  workspace outside this checkout and its ancestor workspaces, with both
+  `PM_PATH` and `PM_GLOBAL_PATH` isolated. Clean up only directories you created.
+- Do not edit source while a runner or build owns it. Negative controls and
+  pre-fix comparisons belong in an isolated copy/worktree with temporary
+  `PM_PATH` and `PM_GLOBAL_PATH` set for every direct stateful CLI command,
+  including linked-test metadata commands. A nested worktree alone does not
+  isolate tracker discovery. Keep these test roots separate from intentional
+  repository tracking below. Change the intended condition; unrelated setup
+  failures do not establish regression sensitivity.
+- Keep canonical full-source coverage at **100/100/100/100**. Do not shrink the
+  denominator, add ignore directives, lower gates, or duplicate assertions to
+  recover a number. Restore meaningful behavioral proof when coverage drops.
+- Mocks may isolate external boundaries; they must not implement the behavior
+  being tested. Use real temporary persistence when proving writes or recovery.
+- Run relevant functional, integration, package, performance, and acceptance
+  gates according to the changed contract. A focused green run is not a full
+  suite result. [Quality evidence](../../../docs/QUALITY_EVIDENCE.md) defines the
+  bounded mutation gate; do not describe it as whole-repository mutation proof.
+- Preserve static quality, docstring, security, release, and public-surface gates.
+  This skill does not grant exceptions to repository coding rules.
+
+## PM Evidence and Handoff
+
+Bootstrap and orient using root `AGENTS.md`; search all statuses before creating
+work. Read the selected item's full metadata and history, follow omission
+receipts, then claim/start only items actually being edited. Keep investigation
+read-only until there is a justified change. Use typed relationships for real
+ownership, dependencies, or verification; never manufacture graph depth.
+
+Link files, docs, and sandbox-safe test commands through `pm`. Record retained
+contracts, removed duplication, pre-fix failure and post-fix proof, commands and
+results, and limitations. Reuse canonical follow-up items for product defects;
+never delete a failing regression merely to make the suite green. Close with
+structured evidence and release the claim, or return paused work to an appropriate
+non-active state. Delivery and review follow the user's authorized scope and
+[review loop](../../../docs/PR_REVIEW_LOOP.md).
+
+For current command flags use command-specific help/contracts. Optional deeper
+workflow guidance is available after installing guide-shell:
+
+```bash
+pm package install guide-shell --project
+pm guide workflows --depth brief
+```

package/.agents/skills/pm-test-audit/references/AUDIT.md

@@ -0,0 +1,54 @@
+# Evidence Before Removing a Test
+
+Start with read-only discovery. Test count, runtime, coverage percentage, or a
+suspicious name is a lead, not proof that a test is low-value.
+
+## Candidates to Investigate
+
+- Assertion-free probes, self-comparisons, or expected values calculated by the
+  same implementation under test.
+- Copied export/manifest inventories or source-text checks without an independent
+  compatibility, packaging, security, or architecture contract.
+- Private predicate, mock-call-shape, and wiring assertions that repeat stronger
+  observable behavior coverage.
+- Identical scenarios across SDK, CLI, MCP, and packages without distinct
+  boundary failure modes; prefer a named keeper over another copy.
+- Fixtures that pre-seed the receipt, ordering, admission, or callback result the
+  production owner should produce; persistence tests that never write anything.
+- Tests that assert a flag was forwarded but never prove its promised behavior.
+- Test-only production exports, globals, wrappers, dead branches, or injected
+  switches with no supported consumer contract.
+- Negative controls that fail at an unrelated guard, and names claiming behavior
+  that their assertions never observe.
+
+Read the complete test and production owner, trace non-test callers and relevant
+callees, and inspect overlapping tests, CI routing, history, and configuration.
+Do not assume no in-repo caller means a published SDK export is unused.
+
+## Reasons to Retain
+
+Keep independent public SDK, protocol, configuration, migration, storage,
+security, platform, default, package/release, and generated cross-language
+contracts. Observable ordering can be a contract. Static inspection can be the
+cheapest independent architectural guard; ask whether it survives harmless
+identifier refactoring. Slowness and use of mocks are not deletion criteria on
+their own. A previously failing retained test may expose a product defect.
+
+## Candidate Ledger
+
+For each candidate, record:
+
+| Evidence | Required detail |
+| --- | --- |
+| Identity | Exact path and test/table row; production owner and callers |
+| Failure | Credible regression the assertion can detect |
+| Contract | Independent external obligation, or why none exists |
+| Overlap | Named keeper and distinct behavior it still proves |
+| Seam | Production change deletion would permit, or none |
+| Decision | Retain, repair, consolidate, or delete, with rationale |
+| Verification | Exact command, negative control where appropriate, and result |
+
+Establish the keeper before removing duplicates. Remove private obsolete seams
+only after caller and public-contract checks. Prefer simpler production code,
+but do not use net lines deleted as a success quota. Avoid trivial one-use
+wrappers or test helpers that merely mirror the implementation.

package/.agents/skills/pm-test-audit/references/CAMPAIGN.md

@@ -0,0 +1,47 @@
+# Broad Test Audit Campaign
+
+Use only for an authorized broad sweep. Adapted from the upstream
+[campaign procedure](https://github.com/openclaw/openclaw/blob/e0d80000067d224e93af6107ed093a21e046879f/.agents/skills/test-audit/CAMPAIGN.md).
+
+1. **Pin a baseline.** Record the commit, test inventory, full-suite outcomes,
+   coverage, and existing failures in the canonical pm item. Baseline failures
+   are investigations, not permission to discard tests. Check all-status lineage
+   before creating follow-ups.
+2. **Partition by owner.** Include SDK domains, CLI/MCP adapters, packages,
+   release scripts, plugins, and shared harnesses within the requested scope.
+   Assign each test one lane. If delegation is authorized, use read-only
+   discovery lanes first and a single integration owner for shared harnesses.
+3. **Build the ledger.** Apply [audit evidence](AUDIT.md) to every declaration in
+   scope; distinguish table rows with different contracts. Mark retain, repair,
+   consolidate, or delete. Record uncovered/unread inventory explicitly instead
+   of claiming a complete sweep.
+4. **Consolidate with proof.** Name and strengthen the keeper first. Preserve
+   real SDK behavior and distinct CLI/MCP serialization, error, lifecycle,
+   persistence, package, and release guarantees. A fake external service can be
+   useful; a mock implementing the production algorithm proves nothing.
+5. **Integrate coherently.** Serialize shared build/harness edits, remove only
+   obsolete private seams, and update routing/inventory when required. Preserve
+   the canonical coverage denominator and every mandatory gate. Do not weaken
+   caps, thresholds, documentation requirements, or lint rules to pass.
+6. **Check preservation independently.** Revisit each removed contract against
+   the keeper and current production boundary. Use targeted mutations or pre-fix
+   controls in an isolated copy with temporary `PM_PATH` and `PM_GLOBAL_PATH`
+   for every direct stateful CLI command to establish meaningful failure. Record exact
+   changed bytes, failure reason, restoration, and passing rerun. Never mutate
+   the working tree under a running test command.
+7. **Handle product defects explicitly.** Track a real defect separately within
+   the coherent delivery, with failing-before/passing-after proof and the
+   repository's structured defect evidence. Reuse existing lineage; do not hide
+   unrelated repairs inside mass test deletion.
+8. **Reconcile and verify.** Incorporate upstream changes without force-pushing
+   shared history. Reassess newly introduced contracts rather than blindly
+   preserving deletions. Run focused tests, full suite/coverage, static quality,
+   and affected acceptance/package/performance gates on the integrated tree.
+9. **Hand off honestly.** Report baseline and final counts, covered lanes, named
+   keepers, production seams removed, regressions demonstrated, full commands,
+   results, and remaining risks. A review inventory is not a correctness
+   certificate. Follow the authorized PR workflow; unavailable reviewers are
+   unavailable evidence, not approval.
+
+Update pm files/docs/tests/comments and durable learnings as evidence accrues.
+Close only implemented work with structured results and release ownership.

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.9.25"
+    "version": "2026.9.27"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.9.25",
+      "version": "2026.9.27",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 2026.9.27 - 2026-09-27
+
+### Fixed
+
+- SDK complete-list receipt falsely reports legacy aliases for canonical helper ([pm-vf9iaf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-vf9iaf.toon))
+
+### Security
+
+- Expose static extension inventory for hosted and agent reads ([pm-lhhnx9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-lhhnx9.toon))
+
+### Other
+
+- Consolidate workspace customization discovery and commands under workspace with permanent compatibility aliases ([pm-npr3](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-npr3.toon))
+- Declare workspace, templates and guide ownership with bounded agent orientation ([pm-uk9dwh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-uk9dwh.toon))
+- Dispatch daily releases at 04:45 Europe/Vienna with the hosted schedule as fallback ([pm-9url9h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-9url9h.toon))
+
+## 2026.9.26 - 2026-09-26
+
+### Fixed
+
+- Refuse unsupported schema dry-run flags before mutation ([pm-s74dca](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-s74dca.toon))
+- Releases from the default branch are supported with analyzer evidence ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
+
+### Other
+
+- Adapt OpenClaw test-audit skill to pm SDK and repository test governance ([pm-xvibt6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-xvibt6.toon))
+- Bound embedding requests, enforce retrieval floors, and protect schema previews ([pm-g0b88h](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/changesets/pm-g0b88h.toon))
+
 ## 2026.9.25 - 2026-09-25
 
 ### Fixed
@@ -350,7 +378,6 @@
 - Metadata index rebuilds and mutations repeatedly scan an unindexed FTS identity column ([pm-gtw5zh](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gtw5zh.toon))
 - Read sessions emit invalid continuation identities from workspace activity rows ([pm-s8ybl9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-s8ybl9.toon))
 - Scale fixtures silently omit unregistered Story items from metadata reads ([pm-fx80w2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-fx80w2.toon))
-- Releases from the default branch are supported with analyzer evidence ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
 
 ### Other
 

package/dist/cli/commander-usage.js

@@ -1,4 +1,4 @@
-!(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]="d5db626f-7623-552b-8458-bfe83a065dfb")}catch(e2){}})();import{pathExists,resolveItemTypeRegistry,EXIT_CODE,getSettingsPath,resolvePmRoot,readSettings,getActiveExtensionRegistrations,locateItem,runActiveServiceOverride,levenshteinDistanceWithinLimit}from"../sdk/runtime-primitives.js";import{BUILTIN_ITEM_TYPE_VALUES}from"../types/index.js";import{PM_CORE_COMMAND_NAMES,resolveSubcommandFlagContractsForCommand}from"../sdk/cli-contracts.js";import{formatCommanderErrorForDisplay,formatCommanderErrorForJson,projectLeanErrorEnvelope}from"./error-guidance.js";import{normalizeHelpCommandPath}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{EXECUTABLE_COMMAND_ALIASES,findBootstrapCommandTokenIndex,normalizeBootstrapInvocation,parseBootstrapHelpRequest,parseBootstrapGlobalOptions,parseBootstrapCommandName}from"./bootstrap-args.js";import{extractProvidedOptionFlags,normalizeLongFlag,renderPmCommand}from"./argv-utils.js";import{normalizeExtensionNameForMatch}from"./commands/extension/shared.js";import{canonicalizeCommandSuggestions,rankCommandPaths}from"../sdk/agent/command-suggestions.js";import{renderMissingOptionRetry}from"../sdk/agent/command-recovery.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{findPmNamespacedCommand,resolvePmCommandAlias}from"../sdk/cli-contracts/command-aliases.js";const BUILTIN_TYPE_HELP_VALUES=BUILTIN_ITEM_TYPE_VALUES.join("|");const OPTIONAL_PACKAGE_INSTALL_HINTS={calendar:"calendar",cal:"calendar",reindex:"search-advanced","search-advanced":"search-advanced",guide:"guide-shell",completion:"guide-shell",templates:"templates","test-runs":"linked-test-adapters",beads:"beads",todos:"todos"};const SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS={comments:{"--body":["--add"],"--text":["--add"],"--comment":["--add"]},notes:{"--body":["--add"],"--text":["--add"],"--note":["--add"]},learnings:{"--body":["--add"],"--text":["--add"],"--learning":["--add"]},update:{"--add-tag":["--add-tags"],"--remove-tag":["--remove-tags"],"--tag":["--tags"]},create:{"--add-tag":["--add-tags"],"--tag":["--tags"]}};const SCHEMA_SUBCOMMAND_VALUES=["add-field","add-status","add-type","apply-preset","list","list-fields","remap-status","remove-field","remove-status","remove-type","rename-field","rename-type","show","show-field","show-status"];function getSemanticUnknownOptionSuggestions(commandName,unknownOption){const commandSuggestions=SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];if(!commandSuggestions){return[]}const normalizedUnknown=normalizeLongFlag(unknownOption);for(const[flag,suggestions]of Object.entries(commandSuggestions)){if(normalizeLongFlag(flag)===normalizedUnknown){return suggestions}}return[]}function appendCommanderExtensionFailures(renderedUsage,json,failures){if(failures.length===0){return renderedUsage}if(json){const primaryFailure2=failures.find(entry=>entry.declared_command_match===true);const{token_accounting:priorAccounting,...usage}=JSON.parse(renderedUsage);const enriched={...usage,...primaryFailure2?{extension_command_failure:{code:"extension_command_activation_failed",extension:primaryFailure2.name,layer:primaryFailure2.layer,error:primaryFailure2.error,recovery_commands:primaryFailure2.recovery_commands??[]}}:{},failed_extensions:failures};return JSON.stringify(priorAccounting===void 0?enriched:attachOutputTokenAccounting(enriched,value=>`${JSON.stringify(value,null,2)}
+!(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]="667ad638-d21d-5a49-a00e-1335cb3f10be")}catch(e2){}})();import{pathExists,resolveItemTypeRegistry,EXIT_CODE,getSettingsPath,resolvePmRoot,readSettings,getActiveExtensionRegistrations,locateItem,runActiveServiceOverride,levenshteinDistanceWithinLimit}from"../sdk/runtime-primitives.js";import{BUILTIN_ITEM_TYPE_VALUES}from"../types/index.js";import{PM_CORE_COMMAND_NAMES,resolveSubcommandFlagContractsForCommand}from"../sdk/cli-contracts.js";import{formatCommanderErrorForDisplay,formatCommanderErrorForJson,projectLeanErrorEnvelope}from"./error-guidance.js";import{normalizeHelpCommandPath}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{EXECUTABLE_COMMAND_ALIASES,findBootstrapCommandTokenIndex,normalizeBootstrapInvocation,parseBootstrapHelpRequest,parseBootstrapGlobalOptions,parseBootstrapCommandName}from"./bootstrap-args.js";import{extractProvidedOptionFlags,normalizeLongFlag,renderPmCommand}from"./argv-utils.js";import{normalizeExtensionNameForMatch}from"./commands/extension/shared.js";import{canonicalizeCommandSuggestions,rankCommandPaths}from"../sdk/agent/command-suggestions.js";import{renderMissingOptionRetry}from"../sdk/agent/command-recovery.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{findPmNamespacedCommand,resolvePmCommandAlias}from"../sdk/cli-contracts/command-aliases.js";const BUILTIN_TYPE_HELP_VALUES=BUILTIN_ITEM_TYPE_VALUES.join("|");const OPTIONAL_PACKAGE_INSTALL_HINTS={calendar:"calendar",cal:"calendar",reindex:"search-advanced","search-advanced":"search-advanced",guide:"guide-shell",completion:"guide-shell",templates:"templates","test-runs":"linked-test-adapters",beads:"beads",todos:"todos"};const SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS={comments:{"--body":["--add"],"--text":["--add"],"--comment":["--add"]},notes:{"--body":["--add"],"--text":["--add"],"--note":["--add"]},learnings:{"--body":["--add"],"--text":["--add"],"--learning":["--add"]},update:{"--add-tag":["--add-tags"],"--remove-tag":["--remove-tags"],"--tag":["--tags"]},create:{"--add-tag":["--add-tags"],"--tag":["--tags"]}};const SCHEMA_SUBCOMMAND_VALUES=["add-field","add-status","add-type","apply-preset","list","list-fields","remap-status","remove-field","remove-status","remove-type","rename-field","rename-type","show","show-field","show-status"];function getSemanticUnknownOptionSuggestions(commandName,unknownOption){const commandSuggestions=SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];if(!commandSuggestions){return[]}const normalizedUnknown=normalizeLongFlag(unknownOption);for(const[flag,suggestions]of Object.entries(commandSuggestions)){if(normalizeLongFlag(flag)===normalizedUnknown){return suggestions}}return[]}function appendCommanderExtensionFailures(renderedUsage,json,failures){if(failures.length===0){return renderedUsage}if(json){const primaryFailure2=failures.find(entry=>entry.declared_command_match===true);const{token_accounting:priorAccounting,...usage}=JSON.parse(renderedUsage);const enriched={...usage,...primaryFailure2?{extension_command_failure:{code:"extension_command_activation_failed",extension:primaryFailure2.name,layer:primaryFailure2.layer,error:primaryFailure2.error,recovery_commands:primaryFailure2.recovery_commands??[]}}:{},failed_extensions:failures};return JSON.stringify(priorAccounting===void 0?enriched:attachOutputTokenAccounting(enriched,value=>`${JSON.stringify(value,null,2)}
 `),null,2)}const details=failures.map(entry=>`- ${entry.layer}:${entry.name}: ${entry.error}`).join("\n");const primaryFailure=failures.find(entry=>entry.declared_command_match===true);if(!primaryFailure){return`${renderedUsage}
 Extension activation failures:
 ${details}`}const recovery=(primaryFailure.recovery_commands??[]).map(command=>`- ${command}`).join("\n");return`Extension command unavailable: ${primaryFailure.layer}:${primaryFailure.name}
@@ -8,6 +8,6 @@ ${recovery}`:""}
 
 ${renderedUsage}
 Extension activation failures:
-${details}`}function resolveUnknownCommanderToken(invocationArgv){const helpRequest=parseBootstrapHelpRequest(invocationArgv);return helpRequest.commandPathTokens[0]??parseBootstrapCommandName(invocationArgv)??"<command>"}function collectRuntimeCommandPaths(root,extensionDescriptors){const commandPaths=new Set;const queue=[...root.commands];while(queue.length>0){const current=queue.shift();if(!current){continue}const normalizedPath=normalizeHelpCommandPath(getCommandPath(current));const hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));if(normalizedPath.length>0&&!hasInternalSegment){commandPaths.add(normalizedPath)}queue.push(...current.commands)}for(const descriptorPath of extensionDescriptors.keys()){const normalizedPath=normalizeHelpCommandPath(descriptorPath);const hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));if(normalizedPath.length>0&&!hasInternalSegment){commandPaths.add(normalizedPath)}}return[...commandPaths].sort((left,right)=>left.localeCompare(right))}function scoreCommandPathMatch(commandPath,queryToken){const normalizedPath=commandPath.trim().toLowerCase();const normalizedToken=queryToken.trim().toLowerCase();if(normalizedToken.length===0){return Number.POSITIVE_INFINITY}const pathSegments=normalizedPath.split(" ");if(normalizedPath===normalizedToken){return 0}if(pathSegments.includes(normalizedToken)){return 1}if(pathSegments.some(segment=>segment.startsWith(normalizedToken))){return 2}if(normalizedPath.includes(normalizedToken)){return 3}const maxDistance=normalizedToken.length>=5?2:1;let bestDistance=Number.POSITIVE_INFINITY;for(const segment of pathSegments){const distance=levenshteinDistanceWithinLimit(segment,normalizedToken,maxDistance);if(distance!==null){bestDistance=Math.min(bestDistance,distance)}}if(Number.isFinite(bestDistance)){return 4+bestDistance}return Number.POSITIVE_INFINITY}function toComparableFlag(flag){return normalizeLongFlag(flag).slice(2).replace(/-/g,"")}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function resolveOptionalPackageInstallHint(commandPath){const canonicalPath=resolvePmCommandAlias(commandPath)?.canonical??EXECUTABLE_COMMAND_ALIASES[commandPath]??commandPath;const topLevel=canonicalPath.split(" ")[0]?.trim().toLowerCase();if(!topLevel){return null}const packageAlias=OPTIONAL_PACKAGE_INSTALL_HINTS[topLevel];if(!packageAlias){return null}return{packageAlias,canonicalPath,installCommand:`pm package install ${packageAlias} --project`}}function normalizePackageCommandAliasToken(value){let normalized=normalizeExtensionNameForMatch(value);for(const prefix of["@unbrained/","builtin-","pm-"]){if(normalized.startsWith(prefix)){normalized=normalized.slice(prefix.length)}}return normalized}function collectInstalledPackageCommandPathHints(unknownToken,extensionDescriptors){const normalizedUnknown=normalizePackageCommandAliasToken(unknownToken);if(normalizedUnknown.length===0){return[]}const hints=[];for(const descriptor of extensionDescriptors.values()){const identifiers=new Set;const source=descriptor.source;if(source){for(const identifier of[source.name,source.package]){const normalizedIdentifier=normalizePackageCommandAliasToken(identifier??"");if(normalizedIdentifier.length>0){identifiers.add(normalizedIdentifier)}}}if(identifiers.size===0){continue}const matches=[...identifiers].some(identifier=>identifier===normalizedUnknown||identifier.includes(normalizedUnknown)||normalizedUnknown.includes(identifier));if(matches){hints.push(descriptor.command)}}return[...new Set(hints)].sort((left,right)=>left.localeCompare(right))}function collectKnownLongFlags(commandName,contractsOverride){const flags=new Set;const contracts=contractsOverride??resolveSubcommandFlagContractsForCommand(commandName);for(const contract of contracts){if(contract.flag.startsWith("--")){flags.add(normalizeLongFlag(contract.flag))}for(const alias of contract.aliases??[]){if(alias.startsWith("--")){flags.add(normalizeLongFlag(alias))}}}return[...flags].sort((left,right)=>left.localeCompare(right))}function suggestNearestLongFlags(unknownOption,knownFlags){if(!unknownOption.startsWith("--")){return[]}const unknownComparable=toComparableFlag(unknownOption);if(unknownComparable.length===0){return[]}const maxDistance=unknownComparable.length>=8?2:1;const candidates=[];for(const flag of knownFlags){const flagComparable=toComparableFlag(flag);if(flagComparable===unknownComparable){continue}if(unknownComparable.length>=3&&flagComparable.startsWith(unknownComparable)){candidates.push({flag,rank:0,distance:flagComparable.length-unknownComparable.length});continue}const distance=levenshteinDistanceWithinLimit(unknownComparable,flagComparable,maxDistance);if(distance===null||distance<=0){continue}candidates.push({flag,rank:1,distance})}return candidates.sort((left,right)=>{if(left.rank!==right.rank){return left.rank-right.rank}if(left.distance!==right.distance){return left.distance-right.distance}return left.flag.localeCompare(right.flag)}).map(entry=>entry.flag).slice(0,3)}let crossCommandFlagIndexCache;const CROSS_COMMAND_FLAG_EXCLUSIONS=new Set(["ctx","packages","list-draft","list-open","list-in-progress","list-blocked","list-closed","list-canceled","start-task","pause-task","close-task","help"]);function getCrossCommandFlagIndex(){if(crossCommandFlagIndexCache){return crossCommandFlagIndexCache}const index=new Map;for(const command of PM_CORE_COMMAND_NAMES){if(CROSS_COMMAND_FLAG_EXCLUSIONS.has(command)){continue}for(const flag of collectKnownLongFlags(command)){const commands=index.get(flag)??[];commands.push(command);index.set(flag,commands)}}crossCommandFlagIndexCache=index;return crossCommandFlagIndexCache}function findOtherCommandsForFlag(unknownOption,currentCommand){if(!unknownOption.startsWith("--")){return[]}const commands=getCrossCommandFlagIndex().get(normalizeLongFlag(unknownOption));if(!commands){return[]}const normalizedCurrent=currentCommand?.trim().toLowerCase();const currentFlags=new Set(collectKnownLongFlags(normalizedCurrent));return[...new Set(commands.filter(command=>command!==normalizedCurrent).map(command=>({command,sharedFlagCount:collectKnownLongFlags(command).filter(flag=>currentFlags.has(flag)).length})).sort((left,right)=>left.sharedFlagCount!==right.sharedFlagCount?right.sharedFlagCount-left.sharedFlagCount:left.command.localeCompare(right.command)).map(({command})=>resolvePmCommandAlias(command)?.canonical??command))]}function rewriteUnknownOptionArgv(argv,unknownOption,replacementFlag){for(let index=0;index<argv.length;index+=1){const token=argv[index];if(!token.startsWith("--")){continue}const equalsIndex=token.indexOf("=");const key=equalsIndex>=0?token.slice(0,equalsIndex):token;if(normalizeLongFlag(key)!==normalizeLongFlag(unknownOption)){continue}const next=[...argv];next[index]=equalsIndex>=0?`${replacementFlag}${token.slice(equalsIndex)}`:replacementFlag;return next}return void 0}function scoreRuntimeCommandCandidates(params){const commandPathSet=new Set(params.commandPaths);const scoreAgainstUnknown=candidatePath=>Math.min(scoreCommandPathMatch(candidatePath,params.normalizedUnknown),params.primaryToken!==params.normalizedUnknown?scoreCommandPathMatch(candidatePath,params.primaryToken):Number.POSITIVE_INFINITY);const scoresByCommandPath=new Map;const recordCandidateScore=(commandPath,score)=>{if(!Number.isFinite(score)||!commandPathSet.has(commandPath)){return}const existing=scoresByCommandPath.get(commandPath);if(existing===void 0||score<existing){scoresByCommandPath.set(commandPath,score)}};for(const commandPath of params.commandPaths){recordCandidateScore(commandPath,scoreAgainstUnknown(commandPath))}for(const[aliasToken,canonicalPath]of Object.entries(EXECUTABLE_COMMAND_ALIASES)){if(aliasToken==="read"){continue}recordCandidateScore(canonicalPath,scoreAgainstUnknown(aliasToken))}return[...scoresByCommandPath.entries()].sort(([leftPath,leftScore],[rightPath,rightScore])=>leftScore!==rightScore?leftScore-rightScore:leftPath.localeCompare(rightPath)).map(([commandPath])=>commandPath)}function resolveUnknownCommandCandidates(params){const exactAlias=resolvePmCommandAlias(params.normalizedUnknown);const semanticCandidates=rankCommandPaths(params.commandPaths,params.primaryToken);const rankedCandidates=scoreRuntimeCommandCandidates(params);const installedPackageCandidates=collectInstalledPackageCommandPathHints(params.primaryToken,params.extensionDescriptors).filter(commandPath=>params.commandPaths.includes(commandPath));return canonicalizeCommandSuggestions([...exactAlias&&params.commandPaths.includes(exactAlias.canonical)?[exactAlias.canonical_argv.join(" ")]:[],...semanticCandidates,...rankedCandidates,...installedPackageCandidates],params.commandPaths,params.primaryToken).filter(path=>!params.normalizedUnknown.includes(" ")||path!==params.normalizedUnknown)}function resolveUnknownCommandFallbacks(commandPaths){const topLevel=[...new Set(commandPaths.map(commandPath=>commandPath.split(" ")[0]).filter(segment=>segment.length>0))];return topLevel.sort((left,right)=>left.localeCompare(right))}function buildUnknownCommandExamples(suggestedPaths,hasConcreteCandidates){const suggestedExamples=suggestedPaths.map(path=>`pm ${path} --help`);if(hasConcreteCandidates){return[...new Set([...suggestedExamples,"pm --help --all"])]}return[...new Set(["pm --help --all",...suggestedExamples])]}function buildUnknownCommandGuidanceFromRuntime(rawMessage,root,extensionDescriptors){const unknownCommandMatch=rawMessage.match(/unknown command '([^']+)'/i);if(!unknownCommandMatch||typeof unknownCommandMatch[1]!=="string"){return void 0}const normalizedUnknown=normalizeHelpCommandPath(unknownCommandMatch[1]);if(normalizedUnknown.length===0){return void 0}const commandPaths=collectRuntimeCommandPaths(root,extensionDescriptors);if(commandPaths.length===0){return void 0}const optionalPackageHint=resolveOptionalPackageInstallHint(normalizedUnknown);if(optionalPackageHint&&!commandPaths.includes(optionalPackageHint.canonicalPath.split(" ")[0])){return{unknownCommandExamples:[optionalPackageHint.installCommand,`pm ${optionalPackageHint.canonicalPath} --help`,"pm --help --all"],unknownCommandNextSteps:[`"${normalizedUnknown}" is provided by the "${optionalPackageHint.packageAlias}" package. Install it with: ${optionalPackageHint.installCommand}. Command after installation: pm ${optionalPackageHint.canonicalPath}.`],suggestedRetryCommand:optionalPackageHint.installCommand}}const primaryToken=normalizedUnknown.split(" ")[0];const combinedCandidates=resolveUnknownCommandCandidates({commandPaths,normalizedUnknown,primaryToken,extensionDescriptors});const fallbackTopLevel=resolveUnknownCommandFallbacks(commandPaths);const suggestedPaths=(combinedCandidates.length>0?combinedCandidates:canonicalizeCommandSuggestions(fallbackTopLevel,commandPaths)).slice(0,3);const examples=buildUnknownCommandExamples(suggestedPaths,combinedCandidates.length>0);const didYouMean=combinedCandidates.length>0?`Did you mean: ${suggestedPaths.join(", ")}?`:null;return{unknownCommandExamples:examples,unknownCommandNextSteps:[...didYouMean?[didYouMean]:[],'Run "pm --help --all" to list every command available in this runtime, including active extensions.',...didYouMean?["Use one of the suggested command paths above with --help to inspect valid flags and usage."]:[]]}}function dedupeStrings(values){return Array.from(new Set(values))}function firstWhitespaceSeparatedToken(input){let token="";for(const character of input){if(character===" "||character==="	"||character==="\n"||character==="\r"||character==="\f"||character==="\v"){break}token+=character}return token}function trimTrailingPunctuationToken(token){let end=token.length;while(end>0){const character=token[end-1];if(character!==","&&character!==":"&&character!==";"){break}end-=1}return token.slice(0,end)}function resolveChildCommandByToken(parent,token){const normalizedToken=token.trim().toLowerCase();return parent.commands.find(candidate=>{if(candidate.name().trim().toLowerCase()===normalizedToken){return true}const aliases=typeof candidate.aliases==="function"?candidate.aliases():[];return aliases.some(alias=>alias.trim().toLowerCase()===normalizedToken)})}function isKnownHelpCommandPath(root,commandPathTokens){if(commandPathTokens.length===0){return true}let current=root;for(const[tokenIndex,token]of commandPathTokens.entries()){const next=resolveChildCommandByToken(current,token);if(!next){const declaredArguments=current.registeredArguments;return declaredArguments.length>0&&(current.commands.length===0||declaredArguments[0]?.required===true)&&(declaredArguments.at(-1)?.variadic===true||commandPathTokens.length-tokenIndex<=declaredArguments.length)}current=next}return true}async function resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName){try{const pmRoot=resolvePmRoot(process.cwd(),bootstrapGlobal.path);if(!await pathExists(getSettingsPath(pmRoot))){return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}const settings=await readSettings(pmRoot);const extensionRegistrations=bootstrapGlobal.noExtensions?void 0:getActiveExtensionRegistrations();const typeRegistry=resolveItemTypeRegistry(settings,extensionRegistrations);let verifiedCollectionItemId;if(/too many arguments/i.test(message)&&["comments","docs","files","learnings","notes","test"].includes(commandName??"")){const commandIndex=invocationArgv.findIndex(token=>token===commandName);const candidate=invocationArgv[commandIndex+2];if(invocationArgv[commandIndex+1]?.toLowerCase()==="add"&&candidate!==void 0&&!candidate.startsWith("-")){try{verifiedCollectionItemId=(await locateItem(pmRoot,candidate,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder))?.id}catch{}}}return{allowedTypes:typeRegistry.types.length>0?typeRegistry.types.join("|"):BUILTIN_TYPE_HELP_VALUES,pmRoot,settings,typeToFolder:typeRegistry.type_to_folder,verifiedCollectionItemId}}catch{return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}}function resolveUnknownOptionSuggestions(message,commandName){const match=message.match(/unknown option '([^']+)'/i);const suggestions=match&&commandName?dedupeStrings([...getSemanticUnknownOptionSuggestions(commandName,match[1]),...suggestNearestLongFlags(match[1],collectKnownLongFlags(commandName))]):void 0;const otherCommands=match?findOtherCommandsForFlag(match[1],commandName):[];const declaredOnPath=match!==null&&collectKnownLongFlags(commandName).includes(normalizeLongFlag(match[1]));return{match,suggestions,otherCommands,scope:declaredOnPath?"declared_on_path":otherCommands.length>0?"declared_elsewhere":"declared_nowhere"}}function resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOptionMatch,unknownOptionSuggestions){if(!unknownOptionMatch||!unknownOptionSuggestions||unknownOptionSuggestions.length===0){return void 0}const rewritten=rewriteUnknownOptionArgv(invocationArgv,unknownOptionMatch[1],unknownOptionSuggestions[0]);return rewritten?renderAttemptedCommand(rewritten):void 0}function resolveSuggestedRetryForMissingOption(message,invocationArgv){const missingRequiredOption=message.match(/required option '([^']+)' not specified/i);const requiredOptionToken=missingRequiredOption?.[1]?trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim())):void 0;if(!requiredOptionToken?.startsWith("--")){return void 0}const commandName=parseBootstrapCommandName(invocationArgv);if(!commandName){return void 0}return renderMissingOptionRetry(invocationArgv,commandName,[requiredOptionToken])}function resolveSplitSchemaSubcommand(message,invocationArgv){if(!/too many arguments/i.test(message)){return void 0}if(parseBootstrapCommandName(invocationArgv)!=="schema"){return void 0}const schemaIndex=findBootstrapCommandTokenIndex(invocationArgv);const verb=invocationArgv[schemaIndex+1]?.trim().toLowerCase();const noun=invocationArgv[schemaIndex+2]?.trim().toLowerCase();if(!verb||!noun){return void 0}const joined=`${verb}-${noun}`;if(!SCHEMA_SUBCOMMAND_VALUES.includes(joined)){return void 0}const rewritten=[...invocationArgv.slice(0,schemaIndex+1),joined,...invocationArgv.slice(schemaIndex+3)];return{unknownSubcommandPath:"schema",unknownSubcommandToken:`${verb} ${noun}`,unknownSubcommandAllowedValues:[...SCHEMA_SUBCOMMAND_VALUES],suggestedRetryCommand:renderAttemptedCommand(rewritten)}}async function resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides={}){const rawMessage=typeof error==="object"&&error!==null?error.message:void 0;const message=rawMessage??"Invalid command usage";const invocationArgv=normalizeBootstrapInvocation(process.argv.slice(2)).argv;const bootstrapGlobal=parseBootstrapGlobalOptions(invocationArgv);const commandIndex=findBootstrapCommandTokenIndex(invocationArgv);const commandName=findPmNamespacedCommand(invocationArgv.slice(commandIndex))?.alias??parseBootstrapCommandName(invocationArgv);const attemptedCommand=renderAttemptedCommand(invocationArgv);const providedOptionFlags=extractProvidedOptionFlags(invocationArgv);const workspaceUsage=await resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName);const allowedTypes=workspaceUsage.allowedTypes;const unknownCommandGuidance=buildUnknownCommandGuidanceFromRuntime(message,rootProgram,extensionDescriptors);const unknownOption=resolveUnknownOptionSuggestions(message,commandName);const splitSchemaSubcommand=resolveSplitSchemaSubcommand(message,invocationArgv);const suggestedRetryCommand=splitSchemaSubcommand?.suggestedRetryCommand??resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOption.match,unknownOption.suggestions)??resolveSuggestedRetryForMissingOption(message,invocationArgv);return{message,commandName,allowedTypes,attemptedCommand,normalizedInvocationArgs:[...invocationArgv],providedOptionFlags,unknownOptionSuggestions:unknownOption.suggestions,unknownOptionOtherCommands:unknownOption.otherCommands.length>0?unknownOption.otherCommands.slice(0,12):void 0,unknownOptionOtherCommandsTotal:unknownOption.otherCommands.length>0?unknownOption.otherCommands.length:void 0,unknownOptionOtherCommandsTruncated:unknownOption.otherCommands.length>12||void 0,unknownOptionScope:unknownOption.scope,suggestedRetryCommand,verifiedCollectionItemId:workspaceUsage.verifiedCollectionItemId,...splitSchemaSubcommand,...unknownCommandGuidance,...guidanceOverrides}}async function formatCommanderUsageMessage(error,rootProgram,extensionDescriptors,guidanceOverrides={}){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides);const{message,commandName,allowedTypes,unknownCommandExamples,unknownCommandNextSteps,attemptedCommand,normalizedInvocationArgs,providedOptionFlags,unknownOptionSuggestions,unknownOptionOtherCommands,unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated,unknownOptionScope,unknownSubcommandPath,unknownSubcommandToken,unknownSubcommandAllowedValues,suggestedRetryCommand,verifiedCollectionItemId,failedExtensions}=usageContext;const formatted=formatCommanderErrorForDisplay(message,commandName,allowedTypes,{unknownCommandExamples,unknownCommandNextSteps,attemptedCommand,normalizedInvocationArgs,providedOptionFlags,unknownOptionSuggestions,unknownOptionOtherCommands,unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated,unknownOptionScope,unknownSubcommandPath,unknownSubcommandToken,unknownSubcommandAllowedValues,suggestedRetryCommand,verifiedCollectionItemId,failedExtensions});const serviceOverride=await runActiveServiceOverride("help_format",{message:formatted,command:commandName,allowed_types:allowedTypes});if(serviceOverride.handled&&typeof serviceOverride.result==="string"){return serviceOverride.result}return formatted}async function formatCommanderUsageJson(error,rootProgram,extensionDescriptors,lean=false,guidanceOverrides={}){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides);const envelope=formatCommanderErrorForJson(usageContext.message,usageContext.commandName,usageContext.allowedTypes,EXIT_CODE.USAGE,{unknownCommandExamples:usageContext.unknownCommandExamples,unknownCommandNextSteps:usageContext.unknownCommandNextSteps,attemptedCommand:usageContext.attemptedCommand,normalizedInvocationArgs:usageContext.normalizedInvocationArgs,providedOptionFlags:usageContext.providedOptionFlags,unknownOptionSuggestions:usageContext.unknownOptionSuggestions,unknownOptionOtherCommands:usageContext.unknownOptionOtherCommands,unknownOptionOtherCommandsTotal:usageContext.unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated:usageContext.unknownOptionOtherCommandsTruncated,unknownOptionScope:usageContext.unknownOptionScope,unknownSubcommandPath:usageContext.unknownSubcommandPath,unknownSubcommandToken:usageContext.unknownSubcommandToken,unknownSubcommandAllowedValues:usageContext.unknownSubcommandAllowedValues,suggestedRetryCommand:usageContext.suggestedRetryCommand,verifiedCollectionItemId:usageContext.verifiedCollectionItemId,failedExtensions:usageContext.failedExtensions});const projected=lean?projectLeanErrorEnvelope(envelope):envelope;const accountingRequested=parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).tokenAccounting===true;return JSON.stringify(accountingRequested?attachOutputTokenAccounting(projected,value=>`${JSON.stringify(value,null,2)}
+${details}`}function resolveUnknownCommanderToken(invocationArgv){const helpRequest=parseBootstrapHelpRequest(invocationArgv);return helpRequest.commandPathTokens[0]??parseBootstrapCommandName(invocationArgv)??"<command>"}function collectRuntimeCommandPaths(root,extensionDescriptors){const commandPaths=new Set;const queue=[...root.commands];while(queue.length>0){const current=queue.shift();if(!current){continue}const normalizedPath=normalizeHelpCommandPath(getCommandPath(current));const hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));if(normalizedPath.length>0&&!hasInternalSegment){commandPaths.add(normalizedPath)}queue.push(...current.commands)}for(const descriptorPath of extensionDescriptors.keys()){const normalizedPath=normalizeHelpCommandPath(descriptorPath);const hasInternalSegment=normalizedPath.split(" ").some(segment=>segment.startsWith("_"));if(normalizedPath.length>0&&!hasInternalSegment){commandPaths.add(normalizedPath)}}return[...commandPaths].sort((left,right)=>left.localeCompare(right))}function scoreCommandPathMatch(commandPath,queryToken){const normalizedPath=commandPath.trim().toLowerCase();const normalizedToken=queryToken.trim().toLowerCase();if(normalizedToken.length===0){return Number.POSITIVE_INFINITY}const pathSegments=normalizedPath.split(" ");if(normalizedPath===normalizedToken){return 0}if(pathSegments.includes(normalizedToken)){return 1}if(pathSegments.some(segment=>segment.startsWith(normalizedToken))){return 2}if(normalizedPath.includes(normalizedToken)){return 3}const maxDistance=normalizedToken.length>=5?2:1;let bestDistance=Number.POSITIVE_INFINITY;for(const segment of pathSegments){const distance=levenshteinDistanceWithinLimit(segment,normalizedToken,maxDistance);if(distance!==null){bestDistance=Math.min(bestDistance,distance)}}if(Number.isFinite(bestDistance)){return 4+bestDistance}return Number.POSITIVE_INFINITY}function toComparableFlag(flag){return normalizeLongFlag(flag).slice(2).replace(/-/g,"")}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function resolveOptionalPackageInstallHint(commandPath){const canonicalPath=resolvePmCommandAlias(commandPath)?.canonical??EXECUTABLE_COMMAND_ALIASES[commandPath]??commandPath;const topLevel=canonicalPath.split(" ")[0]?.trim().toLowerCase();if(!topLevel){return null}const packageAlias=OPTIONAL_PACKAGE_INSTALL_HINTS[topLevel];if(!packageAlias){return null}return{packageAlias,canonicalPath,installCommand:`pm package install ${packageAlias} --project`}}function normalizePackageCommandAliasToken(value){let normalized=normalizeExtensionNameForMatch(value);for(const prefix of["@unbrained/","builtin-","pm-"]){if(normalized.startsWith(prefix)){normalized=normalized.slice(prefix.length)}}return normalized}function collectInstalledPackageCommandPathHints(unknownToken,extensionDescriptors){const normalizedUnknown=normalizePackageCommandAliasToken(unknownToken);if(normalizedUnknown.length===0){return[]}const hints=[];for(const descriptor of extensionDescriptors.values()){const identifiers=new Set;const source=descriptor.source;if(source){for(const identifier of[source.name,source.package]){const normalizedIdentifier=normalizePackageCommandAliasToken(identifier??"");if(normalizedIdentifier.length>0){identifiers.add(normalizedIdentifier)}}}if(identifiers.size===0){continue}const matches=[...identifiers].some(identifier=>identifier===normalizedUnknown||identifier.includes(normalizedUnknown)||normalizedUnknown.includes(identifier));if(matches){hints.push(descriptor.command)}}return[...new Set(hints)].sort((left,right)=>left.localeCompare(right))}function collectKnownLongFlags(commandName,contractsOverride){const flags=new Set;const contracts=contractsOverride??resolveSubcommandFlagContractsForCommand(commandName);for(const contract of contracts){if(contract.flag.startsWith("--")){flags.add(normalizeLongFlag(contract.flag))}for(const alias of contract.aliases??[]){if(alias.startsWith("--")){flags.add(normalizeLongFlag(alias))}}}return[...flags].sort((left,right)=>left.localeCompare(right))}function suggestNearestLongFlags(unknownOption,knownFlags){if(!unknownOption.startsWith("--")){return[]}const unknownComparable=toComparableFlag(unknownOption);if(unknownComparable.length===0){return[]}const maxDistance=unknownComparable.length>=8?2:1;const candidates=[];for(const flag of knownFlags){const flagComparable=toComparableFlag(flag);if(flagComparable===unknownComparable){continue}if(unknownComparable.length>=3&&flagComparable.startsWith(unknownComparable)){candidates.push({flag,rank:0,distance:flagComparable.length-unknownComparable.length});continue}const distance=levenshteinDistanceWithinLimit(unknownComparable,flagComparable,maxDistance);if(distance===null||distance<=0){continue}candidates.push({flag,rank:1,distance})}return candidates.sort((left,right)=>{if(left.rank!==right.rank){return left.rank-right.rank}if(left.distance!==right.distance){return left.distance-right.distance}return left.flag.localeCompare(right.flag)}).map(entry=>entry.flag).slice(0,3)}let crossCommandFlagIndexCache;const CROSS_COMMAND_FLAG_EXCLUSIONS=new Set(["ctx","packages","list-draft","list-open","list-in-progress","list-blocked","list-closed","list-canceled","start-task","pause-task","close-task","help"]);function getCrossCommandFlagIndex(){if(crossCommandFlagIndexCache){return crossCommandFlagIndexCache}const index=new Map;for(const command of PM_CORE_COMMAND_NAMES){if(CROSS_COMMAND_FLAG_EXCLUSIONS.has(command)){continue}for(const flag of collectKnownLongFlags(command)){const commands=index.get(flag)??[];commands.push(command);index.set(flag,commands)}}crossCommandFlagIndexCache=index;return crossCommandFlagIndexCache}function findOtherCommandsForFlag(unknownOption,currentCommand){if(!unknownOption.startsWith("--")){return[]}const commands=getCrossCommandFlagIndex().get(normalizeLongFlag(unknownOption));if(!commands){return[]}const normalizedCurrent=currentCommand?.trim().toLowerCase();const currentFlags=new Set(collectKnownLongFlags(normalizedCurrent));return[...new Set(commands.filter(command=>command!==normalizedCurrent).map(command=>({command,sharedFlagCount:collectKnownLongFlags(command).filter(flag=>currentFlags.has(flag)).length})).sort((left,right)=>left.sharedFlagCount!==right.sharedFlagCount?right.sharedFlagCount-left.sharedFlagCount:left.command.localeCompare(right.command)).map(({command})=>resolvePmCommandAlias(command)?.canonical??command))]}function rewriteUnknownOptionArgv(argv,unknownOption,replacementFlag){for(let index=0;index<argv.length;index+=1){const token=argv[index];if(!token.startsWith("--")){continue}const equalsIndex=token.indexOf("=");const key=equalsIndex>=0?token.slice(0,equalsIndex):token;if(normalizeLongFlag(key)!==normalizeLongFlag(unknownOption)){continue}const next=[...argv];next[index]=equalsIndex>=0?`${replacementFlag}${token.slice(equalsIndex)}`:replacementFlag;return next}return void 0}function scoreRuntimeCommandCandidates(params){const commandPathSet=new Set(params.commandPaths);const scoreAgainstUnknown=candidatePath=>Math.min(scoreCommandPathMatch(candidatePath,params.normalizedUnknown),params.primaryToken!==params.normalizedUnknown?scoreCommandPathMatch(candidatePath,params.primaryToken):Number.POSITIVE_INFINITY);const scoresByCommandPath=new Map;const recordCandidateScore=(commandPath,score)=>{if(!Number.isFinite(score)||!commandPathSet.has(commandPath)){return}const existing=scoresByCommandPath.get(commandPath);if(existing===void 0||score<existing){scoresByCommandPath.set(commandPath,score)}};for(const commandPath of params.commandPaths){recordCandidateScore(commandPath,scoreAgainstUnknown(commandPath))}for(const[aliasToken,canonicalPath]of Object.entries(EXECUTABLE_COMMAND_ALIASES)){if(aliasToken==="read"){continue}recordCandidateScore(canonicalPath,scoreAgainstUnknown(aliasToken))}return[...scoresByCommandPath.entries()].sort(([leftPath,leftScore],[rightPath,rightScore])=>leftScore!==rightScore?leftScore-rightScore:leftPath.localeCompare(rightPath)).map(([commandPath])=>commandPath)}function resolveUnknownCommandCandidates(params){const exactAlias=resolvePmCommandAlias(params.normalizedUnknown);const semanticCandidates=rankCommandPaths(params.commandPaths,params.primaryToken);const rankedCandidates=scoreRuntimeCommandCandidates(params);const installedPackageCandidates=collectInstalledPackageCommandPathHints(params.primaryToken,params.extensionDescriptors).filter(commandPath=>params.commandPaths.includes(commandPath));return canonicalizeCommandSuggestions([...exactAlias&&params.commandPaths.includes(exactAlias.canonical)?[exactAlias.canonical_argv.join(" ")]:[],...semanticCandidates,...rankedCandidates,...installedPackageCandidates],params.commandPaths,params.primaryToken).filter(path=>!params.normalizedUnknown.includes(" ")||path!==params.normalizedUnknown)}function resolveUnknownCommandFallbacks(commandPaths){const topLevel=[...new Set(commandPaths.map(commandPath=>commandPath.split(" ")[0]).filter(segment=>segment.length>0))];return topLevel.sort((left,right)=>left.localeCompare(right))}function buildUnknownCommandExamples(suggestedPaths,hasConcreteCandidates){const suggestedExamples=suggestedPaths.map(path=>`pm ${path} --help`);if(hasConcreteCandidates){return[...new Set([...suggestedExamples,"pm --help --all"])]}return[...new Set(["pm --help --all",...suggestedExamples])]}function buildUnknownCommandGuidanceFromRuntime(rawMessage,root,extensionDescriptors){const unknownCommandMatch=rawMessage.match(/unknown command '([^']+)'/i);if(!unknownCommandMatch||typeof unknownCommandMatch[1]!=="string"){return void 0}const normalizedUnknown=normalizeHelpCommandPath(unknownCommandMatch[1]);if(normalizedUnknown.length===0){return void 0}const commandPaths=collectRuntimeCommandPaths(root,extensionDescriptors);if(commandPaths.length===0){return void 0}const optionalPackageHint=resolveOptionalPackageInstallHint(normalizedUnknown);if(optionalPackageHint&&!commandPaths.includes(optionalPackageHint.canonicalPath.split(" ")[0])){return{unknownCommandExamples:[optionalPackageHint.installCommand,`pm ${optionalPackageHint.canonicalPath} --help`,"pm --help --all"],unknownCommandNextSteps:[`"${normalizedUnknown}" is provided by the "${optionalPackageHint.packageAlias}" package. Install it with: ${optionalPackageHint.installCommand}. Command after installation: pm ${optionalPackageHint.canonicalPath}.`],suggestedRetryCommand:optionalPackageHint.installCommand}}const primaryToken=normalizedUnknown.split(" ")[0];const combinedCandidates=resolveUnknownCommandCandidates({commandPaths,normalizedUnknown,primaryToken,extensionDescriptors});const fallbackTopLevel=resolveUnknownCommandFallbacks(commandPaths);const suggestedPaths=(combinedCandidates.length>0?combinedCandidates:canonicalizeCommandSuggestions(fallbackTopLevel,commandPaths)).slice(0,3);const examples=buildUnknownCommandExamples(suggestedPaths,combinedCandidates.length>0);const didYouMean=combinedCandidates.length>0?`Did you mean: ${suggestedPaths.join(", ")}?`:null;return{unknownCommandExamples:examples,unknownCommandNextSteps:[...didYouMean?[didYouMean]:[],'Run "pm --help --all" to list every command available in this runtime, including active extensions.',...didYouMean?["Use one of the suggested command paths above with --help to inspect valid flags and usage."]:[]]}}function dedupeStrings(values){return Array.from(new Set(values))}function firstWhitespaceSeparatedToken(input){let token="";for(const character of input){if(character===" "||character==="	"||character==="\n"||character==="\r"||character==="\f"||character==="\v"){break}token+=character}return token}function trimTrailingPunctuationToken(token){let end=token.length;while(end>0){const character=token[end-1];if(character!==","&&character!==":"&&character!==";"){break}end-=1}return token.slice(0,end)}function resolveChildCommandByToken(parent,token){const normalizedToken=token.trim().toLowerCase();return parent.commands.find(candidate=>{if(candidate.name().trim().toLowerCase()===normalizedToken){return true}const aliases=typeof candidate.aliases==="function"?candidate.aliases():[];return aliases.some(alias=>alias.trim().toLowerCase()===normalizedToken)})}function isKnownHelpCommandPath(root,commandPathTokens){if(commandPathTokens.length===0){return true}let current=root;for(const[tokenIndex,token]of commandPathTokens.entries()){const next=resolveChildCommandByToken(current,token);if(!next){const declaredArguments=current.registeredArguments;return declaredArguments.length>0&&(current.commands.length===0||declaredArguments[0]?.required===true)&&(declaredArguments.at(-1)?.variadic===true||commandPathTokens.length-tokenIndex<=declaredArguments.length)}current=next}return true}async function resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName){try{const pmRoot=resolvePmRoot(process.cwd(),bootstrapGlobal.path);if(!await pathExists(getSettingsPath(pmRoot))){return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}const settings=await readSettings(pmRoot);const extensionRegistrations=bootstrapGlobal.noExtensions?void 0:getActiveExtensionRegistrations();const typeRegistry=resolveItemTypeRegistry(settings,extensionRegistrations);let verifiedCollectionItemId;if(/too many arguments/i.test(message)&&["comments","docs","files","learnings","notes","test"].includes(commandName??"")){const commandIndex=invocationArgv.findIndex(token=>token===commandName);const candidate=invocationArgv[commandIndex+2];if(invocationArgv[commandIndex+1]?.toLowerCase()==="add"&&candidate!==void 0&&!candidate.startsWith("-")){try{verifiedCollectionItemId=(await locateItem(pmRoot,candidate,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder))?.id}catch{}}}return{allowedTypes:typeRegistry.types.length>0?typeRegistry.types.join("|"):BUILTIN_TYPE_HELP_VALUES,pmRoot,settings,typeToFolder:typeRegistry.type_to_folder,verifiedCollectionItemId}}catch{return{allowedTypes:BUILTIN_TYPE_HELP_VALUES}}}function resolveUnknownOptionSuggestions(message,commandName){const match=message.match(/unknown option '([^']+)'/i);const suggestions=match&&commandName?dedupeStrings([...getSemanticUnknownOptionSuggestions(commandName,match[1]),...suggestNearestLongFlags(match[1],collectKnownLongFlags(commandName))]):void 0;const otherCommands=match?findOtherCommandsForFlag(match[1],commandName):[];const declaredOnPath=match!==null&&collectKnownLongFlags(commandName).includes(normalizeLongFlag(match[1]));return{match,suggestions,otherCommands,scope:declaredOnPath?"declared_on_path":otherCommands.length>0?"declared_elsewhere":"declared_nowhere"}}function resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOptionMatch,unknownOptionSuggestions){if(!unknownOptionMatch||!unknownOptionSuggestions||unknownOptionSuggestions.length===0){return void 0}const rewritten=rewriteUnknownOptionArgv(invocationArgv,unknownOptionMatch[1],unknownOptionSuggestions[0]);return rewritten?renderAttemptedCommand(rewritten):void 0}function resolveSuggestedRetryForMissingOption(message,invocationArgv){const missingRequiredOption=message.match(/required option '([^']+)' not specified/i);const requiredOptionToken=missingRequiredOption?.[1]?trimTrailingPunctuationToken(firstWhitespaceSeparatedToken(missingRequiredOption[1].trim())):void 0;if(!requiredOptionToken?.startsWith("--")){return void 0}const commandName=parseBootstrapCommandName(invocationArgv);if(!commandName){return void 0}return renderMissingOptionRetry(invocationArgv,commandName,[requiredOptionToken])}function resolveSplitSchemaSubcommand(message,invocationArgv){if(!/too many arguments/i.test(message)){return void 0}const commandIndex=findBootstrapCommandTokenIndex(invocationArgv);const namespaced=findPmNamespacedCommand(invocationArgv.slice(commandIndex));if(namespaced?.alias!=="schema"){return void 0}const schemaIndex=commandIndex+namespaced.canonical_argv.length-1;const verb=invocationArgv[schemaIndex+1]?.trim().toLowerCase();const noun=invocationArgv[schemaIndex+2]?.trim().toLowerCase();if(!verb||!noun){return void 0}const joined=`${verb}-${noun}`;if(!SCHEMA_SUBCOMMAND_VALUES.includes(joined)){return void 0}const rewritten=[...invocationArgv.slice(0,schemaIndex+1),joined,...invocationArgv.slice(schemaIndex+3)];return{unknownSubcommandPath:"schema",unknownSubcommandToken:`${verb} ${noun}`,unknownSubcommandAllowedValues:[...SCHEMA_SUBCOMMAND_VALUES],suggestedRetryCommand:renderAttemptedCommand(rewritten)}}async function resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides={}){const rawMessage=typeof error==="object"&&error!==null?error.message:void 0;const message=rawMessage??"Invalid command usage";const invocationArgv=normalizeBootstrapInvocation(process.argv.slice(2)).argv;const bootstrapGlobal=parseBootstrapGlobalOptions(invocationArgv);const commandIndex=findBootstrapCommandTokenIndex(invocationArgv);const commandName=findPmNamespacedCommand(invocationArgv.slice(commandIndex))?.alias??parseBootstrapCommandName(invocationArgv);const attemptedCommand=renderAttemptedCommand(invocationArgv);const providedOptionFlags=extractProvidedOptionFlags(invocationArgv);const workspaceUsage=await resolveWorkspaceUsageContext(bootstrapGlobal,message,invocationArgv,commandName);const allowedTypes=workspaceUsage.allowedTypes;const unknownCommandGuidance=buildUnknownCommandGuidanceFromRuntime(message,rootProgram,extensionDescriptors);const unknownOption=resolveUnknownOptionSuggestions(message,commandName);const splitSchemaSubcommand=resolveSplitSchemaSubcommand(message,invocationArgv);const suggestedRetryCommand=splitSchemaSubcommand?.suggestedRetryCommand??resolveSuggestedRetryForUnknownOption(invocationArgv,unknownOption.match,unknownOption.suggestions)??resolveSuggestedRetryForMissingOption(message,invocationArgv);return{message,commandName,allowedTypes,attemptedCommand,normalizedInvocationArgs:[...invocationArgv],providedOptionFlags,unknownOptionSuggestions:unknownOption.suggestions,unknownOptionOtherCommands:unknownOption.otherCommands.length>0?unknownOption.otherCommands.slice(0,12):void 0,unknownOptionOtherCommandsTotal:unknownOption.otherCommands.length>0?unknownOption.otherCommands.length:void 0,unknownOptionOtherCommandsTruncated:unknownOption.otherCommands.length>12||void 0,unknownOptionScope:unknownOption.scope,suggestedRetryCommand,verifiedCollectionItemId:workspaceUsage.verifiedCollectionItemId,...splitSchemaSubcommand,...unknownCommandGuidance,...guidanceOverrides}}async function formatCommanderUsageMessage(error,rootProgram,extensionDescriptors,guidanceOverrides={}){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides);const{message,commandName,allowedTypes,unknownCommandExamples,unknownCommandNextSteps,attemptedCommand,normalizedInvocationArgs,providedOptionFlags,unknownOptionSuggestions,unknownOptionOtherCommands,unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated,unknownOptionScope,unknownSubcommandPath,unknownSubcommandToken,unknownSubcommandAllowedValues,suggestedRetryCommand,verifiedCollectionItemId,failedExtensions}=usageContext;const formatted=formatCommanderErrorForDisplay(message,commandName,allowedTypes,{unknownCommandExamples,unknownCommandNextSteps,attemptedCommand,normalizedInvocationArgs,providedOptionFlags,unknownOptionSuggestions,unknownOptionOtherCommands,unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated,unknownOptionScope,unknownSubcommandPath,unknownSubcommandToken,unknownSubcommandAllowedValues,suggestedRetryCommand,verifiedCollectionItemId,failedExtensions});const serviceOverride=await runActiveServiceOverride("help_format",{message:formatted,command:commandName,allowed_types:allowedTypes});if(serviceOverride.handled&&typeof serviceOverride.result==="string"){return serviceOverride.result}return formatted}async function formatCommanderUsageJson(error,rootProgram,extensionDescriptors,lean=false,guidanceOverrides={}){const usageContext=await resolveCommanderUsageContext(error,rootProgram,extensionDescriptors,guidanceOverrides);const envelope=formatCommanderErrorForJson(usageContext.message,usageContext.commandName,usageContext.allowedTypes,EXIT_CODE.USAGE,{unknownCommandExamples:usageContext.unknownCommandExamples,unknownCommandNextSteps:usageContext.unknownCommandNextSteps,attemptedCommand:usageContext.attemptedCommand,normalizedInvocationArgs:usageContext.normalizedInvocationArgs,providedOptionFlags:usageContext.providedOptionFlags,unknownOptionSuggestions:usageContext.unknownOptionSuggestions,unknownOptionOtherCommands:usageContext.unknownOptionOtherCommands,unknownOptionOtherCommandsTotal:usageContext.unknownOptionOtherCommandsTotal,unknownOptionOtherCommandsTruncated:usageContext.unknownOptionOtherCommandsTruncated,unknownOptionScope:usageContext.unknownOptionScope,unknownSubcommandPath:usageContext.unknownSubcommandPath,unknownSubcommandToken:usageContext.unknownSubcommandToken,unknownSubcommandAllowedValues:usageContext.unknownSubcommandAllowedValues,suggestedRetryCommand:usageContext.suggestedRetryCommand,verifiedCollectionItemId:usageContext.verifiedCollectionItemId,failedExtensions:usageContext.failedExtensions});const projected=lean?projectLeanErrorEnvelope(envelope):envelope;const accountingRequested=parseBootstrapGlobalOptions(usageContext.normalizedInvocationArgs).tokenAccounting===true;return JSON.stringify(accountingRequested?attachOutputTokenAccounting(projected,value=>`${JSON.stringify(value,null,2)}
 `):projected,null,2)}const _testOnly={collectKnownLongFlags,collectInstalledPackageCommandPathHints,resolveOptionalPackageInstallHint,resolveSuggestedRetryForMissingOption,suggestNearestLongFlags};export{BUILTIN_TYPE_HELP_VALUES,_testOnly,appendCommanderExtensionFailures,buildUnknownCommandGuidanceFromRuntime,collectRuntimeCommandPaths,formatCommanderUsageJson,formatCommanderUsageMessage,isKnownHelpCommandPath,resolveChildCommandByToken,resolveCommanderUsageContext,resolveUnknownCommanderToken,scoreCommandPathMatch};
 //# sourceMappingURL=commander-usage.js.map