@unbrained/pm-cli 2026.10.4 → 2026.10.6

package/dist/cli/help-content.js

@@ -1,3 +1,6 @@
-!(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]="63db65f1-fdbe-513d-b71a-87490ec9b69e")}catch(e2){}})();import{parseBootstrapHelpRequest}from"./bootstrap-args.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{listPmCommandsForTier,measurePmCoreHelp,PM_CORE_HELP_OPTION_FLAGS,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";import{PM_COMMAND_ALIAS_CONTRACTS,PM_RELOCATED_COMMAND_ALIASES,renderPmCommandAliasMigrationHint}from"../sdk/cli-contracts.js";const COMMAND_HELP_VISIBILITY_TIERS=new WeakMap;function setPmCommandHelpVisibilityTier(command,tier){COMMAND_HELP_VISIBILITY_TIERS.set(command,tier)}function getPmCommandHelpVisibilityTier(command){return COMMAND_HELP_VISIBILITY_TIERS.get(command)}function firstExampleOrEmpty(examples){return examples.length>0?[examples[0]]:[]}function renderCompactHelpBundle(bundle){const lines=["","Intent:",`  ${bundle.why}`];const compactExamples=firstExampleOrEmpty(bundle.examples);if(compactExamples.length>0){lines.push("","Example:");lines.push(`  ${compactExamples[0]}`)}lines.push("","Need deeper rationale and more examples?");lines.push("  Re-run with --explain.");return lines.join("\n")}function renderDetailedHelpBundle(bundle){const lines=["","Why use this command:",`  ${bundle.why}`,"","Examples:",...bundle.examples.map(example=>`  ${example}`)];if(bundle.tips&&bundle.tips.length>0){lines.push("","Tips:");lines.push(...bundle.tips.map(tip=>`  - ${tip}`))}return lines.join("\n")}function renderHelpBundle(bundle,detailMode){if(detailMode==="detailed"){return renderDetailedHelpBundle(bundle)}return renderCompactHelpBundle(bundle)}function normalizeHelpCommandPath(commandPath){return commandPath.trim().toLowerCase().split(/\s+/).filter(part=>part.length>0).join(" ")}const HELP_PATH_ALIASES={cal:"calendar",ctx:"context"};function findDirectChildCommand(parent,name){return parent.commands.find(entry=>entry.name()===name)??null}function findCommandByPath(root,pathParts){let current=root;for(const part of pathParts){const next=findDirectChildCommand(current,part);if(!next){return null}current=next}return current}function attachBundleByPath(root,commandPath,bundle,detailMode){const command=findCommandByPath(root,commandPath.split(" ").filter(part=>part.length>0));if(!command){return}command.addHelpText("after",renderHelpBundle(bundle,detailMode))}function resolveHelpDetailMode(argv){if(argv.includes("--explain")){return"detailed"}return"compact"}function isFullHelpDiscovery(argv){return argv.includes("--all")||argv.includes("--explain")}const HELP_BY_COMMAND_PATH={ops:{why:"Groups workspace diagnostics, quality checks, and maintenance under one discoverable command.",examples:["pm ops health --summary","pm ops validate --check-history-drift","pm ops --help"]},init:{why:"Bootstraps tracker storage and settings so all other commands can run safely.",examples:["pm init","pm init acme","pm init ./pm-sandbox --defaults","pm init --preset minimal","pm init --agent-guidance add","pm init --defaults --with-packages"],tips:["Run this once per repository before create/list/update commands.","A path-like positional (`./dir`, `/tmp/dir`) initializes that tracker path; a plain word remains an id prefix.","Rewriting id prefix, governance preset, or default author on an existing tracker requires --force.","Use --preset for non-interactive automation; omit it in a TTY to use the setup wizard.","Use --agent-guidance add to inject compact AGENTS/CLAUDE workflow guidance, or --agent-guidance status to inspect missing guidance without modifying files.","Use --with-packages when agents need bundled commands such as calendar and templates available immediately."]},config:{why:"Reads or updates project/global settings such as definition-of-done, item format, telemetry, and policy toggles.",examples:["pm config project get definition-of-done",'pm config project set definition-of-done --criterion "tests pass"',"pm config project set item-format --format toon","pm config project set sprint-release-format-policy --policy strict_error","pm config project set governance-preset --policy minimal","pm config project set governance-ownership-enforcement --policy none","pm config project set test-result-tracking --policy enabled","pm config global set telemetry-tracking --policy disabled"]},extension:{why:"Compatibility command for package-backed runtime extension lifecycle operations across project or global scope.",examples:["pm install ./my-package --project","pm install '*' --project","pm package doctor --project --detail summary","pm package manage --global","pm package activate sample-ext --project","pm package deactivate sample-ext --project","pm package uninstall sample-ext --global","pm extension explore --project","pm extension manage --global","pm extension describe sample-ext --project","pm extension doctor --detail deep"],tips:["Prefer pm install and pm package in new user-facing automation.","Use pm extension when maintaining existing extension-specific scripts or debugging the compatibility runtime directly.","Bundled aliases beads and todos resolve to package-shipped extension sources.","Use --gh/--github shorthand for GitHub sources and --ref to pin a branch, tag, or ref.","Install updates settings activation state automatically unless extension allowlist mode is unchanged.","Use --adopt for single-extension adoption and --adopt-all to bulk-register unmanaged installs as managed without reinstalling.","Use --manage for concise triage summaries and remediation-oriented diagnostics alongside full extension details.","Use --describe to map exactly what each loaded extension registers (commands, hooks, item types, providers, overrides) in one call.","Use --doctor for consolidated diagnostics with warning codes, remediation hints, and optional deep detail payloads."]},package:{why:"Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.",examples:["pm install npm:@scope/pm-package --project","pm package install ./my-package --project","pm package doctor --project --detail deep","pm package manage --project --runtime-probe","pm package describe --project","pm package activate sample-ext --project","pm upgrade --packages-only --dry-run"],tips:["Prefer package vocabulary for user-facing workflows; extension vocabulary remains available for compatibility.","Use pm package describe [name] to map every surface a package registers without reading its manifest or running diagnostics.","Use pm upgrade to refresh the CLI/SDK and managed packages from their recorded sources.","Use --dry-run before upgrade when automation needs a deterministic plan."]},"package init":{why:"Generates an installable starter pm package with package metadata and a root extension entrypoint.",examples:["pm package init ./my-package","pm package init ./my-hook-package --capability hooks","pm package init ./my-search-package --capability search","pm package init ./my-sync-package --capability importers","pm package init ./my-domain-package --capability schema","pm package init ./my-output-package --capability renderers","pm install ./my-sync-package --project","pm package doctor --project --detail summary"],tips:["Use --capability hooks for a starter after_command lifecycle reactor with runnable SDK testing coverage.","Use --capability search for a starter search provider/vector-store adapter with runnable SDK testing coverage.","Use --capability importers for paired import/export commands that move project context across systems.","Use --capability schema for a starter custom item type, field, and migration so pm models your project domain.","Use --capability renderers/parser/preflight/services for starter override surfaces (output renderer, parsed-option rewrite, pre-run gate decision, built-in service) \u2014 one runnable starter per SDK capability.","The generated package is local-install safe; add SDK runtime imports only after declaring dependencies and validating with package doctor.","Use package doctor after changes to verify activation, policy, and collision diagnostics."]},"package install":{why:"Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.",examples:["pm package install ./my-package --project","pm install npm:pm-changelog --project","pm package install --github org/repo/packages/my-pm-package --ref main"],tips:["Prefer the top-level pm install alias in scripts when only installation is needed.","Run pm package manage or pm package doctor after installing external packages."]},"package doctor":{why:"Diagnoses package activation, policy, collision, and managed-state health for project or global package scopes.",examples:["pm package doctor --project --detail summary","pm package doctor --project --detail deep --trace","pm package doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed package registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global package state: PM_GLOBAL_PATH=$(mktemp -d) pm package doctor --project --detail deep --trace.","Non-isolated project diagnostics include global registrations and emit remediation when global package state can affect the result."]},"package catalog":{why:"Lists bundled first-party package catalog metadata and compact field projections.",examples:["pm package catalog --project","pm package catalog --project --fields alias,installed,install_command","pm package list --project --fields alias,package_name,category"],tips:["Use --fields for low-token package discovery in agent loops.","External npm package discovery still belongs to npm search."]},"extension init":{why:"Generates an installable starter runtime extension with manifest and entrypoint files.",examples:["pm extension init ./my-extension","pm extension init ./my-hook-extension --capability hooks","pm extension init ./my-search-extension --capability search","pm extension init ./my-sync-extension --capability importers","pm extension init ./my-domain-extension --capability schema","pm extension init ./my-output-extension --capability renderers","pm extension --install --project ./my-sync-extension","pm extension --doctor --project --detail summary"],tips:["Use --capability hooks when the extension should react to command lifecycle events.","Use --capability search when the extension should register retrieval primitives.","Use --capability importers when the extension should register project-context import/export commands.","Use --capability schema when the extension should register custom item types, fields, and migrations.","Use --capability renderers/parser/preflight/services to override pm's output rendering, parsed options, pre-run gate, or a built-in service.","Use package init for new distributable package workflows; extension init is the compatibility-level runtime scaffold."]},"extension install":{why:"Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.",examples:["pm extension install ./my-extension --project","pm extension --install --project ./my-extension","pm extension doctor --project --detail summary"],tips:["Prefer pm install or pm package install for new package-first automation."]},"extension doctor":{why:"Diagnoses compatibility extension activation, policy, collision, and managed-state health for project or global extension scopes.",examples:["pm extension doctor --project --detail summary","pm extension doctor --project --detail deep --trace","pm extension doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed extension registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global extension state: PM_GLOBAL_PATH=$(mktemp -d) pm extension doctor --project --detail deep --trace.","Prefer pm package doctor in new package-first workflows."]},"extension catalog":{why:"Compatibility view of bundled package catalog metadata.",examples:["pm extension catalog --project","pm extension catalog --project --fields alias,installed,install_command"],tips:["Prefer pm package catalog in new user-facing workflows."]},install:{why:"Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.",examples:["pm install '*' --project","pm install ./packages/pm-todos --project","pm install npm:@scope/pm-package --global","pm install --github org/repo/packages/my-pm-package --ref main"],tips:["Installed packages are recorded in managed state and can be inspected with pm package manage."]},upgrade:{why:"Updates the global pm CLI/SDK and refreshes managed pm packages from recorded install sources.",examples:["pm upgrade --dry-run","pm upgrade --packages-only --project","pm upgrade todos --dry-run","pm upgrade --cli-only --repair","pm upgrade --tag next --dry-run"],tips:["Omit target to include the CLI/SDK plus all managed packages in the selected scope.","Pass a target to refresh one managed package by name, directory, package name, or source.","Use --packages-only in repository automation when the global CLI should not be changed."]},create:{why:"Creates a new planning item with deterministic metadata and history.",examples:['pm create --title "Harden lock flow" --description "Improve stale lock handling" --type Task --status open --priority 1 --message "Create lock hardening task" --create-mode progressive','pm create --title "Weekly planning sync" --description "Recurring coordination meeting" --type Meeting --schedule-preset lightweight','pm create --title "Asset: Hero model" --description "Track playable model asset" --type Asset --status open --priority 1 --message "Create asset item" --type-option category=Character --dep "id=pm-epic01,kind=parent,created_at=now" --comment "created_at=now,text=Why this asset item exists." --note "created_at=now,text=Initial implementation note." --learning "created_at=now,text=Durable lesson placeholder." --file "path=src/assets/hero.glb,note=tracked asset" --test "command=node scripts/run-tests.mjs test,timeout_seconds=240" --doc "path=README.md,note=asset docs"'],tips:["Use --schedule-preset lightweight for Reminder/Meeting/Event when you want minimal required create inputs.","Use --type <value> to load type-aware policy guidance in --help output."]},focus:{why:"Sets a session focused item so new pm create items default their --parent to it (project management = context management).",examples:["pm focus pm-epic1","pm focus","pm focus --clear"],tips:["Focus is session-local (stored in .agents/pm/runtime/session.json, gitignored) \u2014 it never affects teammates.",'An explicit --parent on pm create always overrides the focused item; use --parent "" to create with no parent.',"A stale focused item produces the same missing-parent validation as an explicit stale --parent."]},update:{why:"Mutates existing item fields while preserving history and lock safety.",examples:['pm update pm-a1b2 --status in_progress --message "Start implementation"','pm update pm-a1b2 --unset close-reason --message "Clear stale close reason after reopen"','pm update pm-a1b2 --unset assignee --deadline +2d --message "Replan ownership and deadline"','pm update pm-a1b2 --body "Backfilled body text for legacy item" --message "Normalize missing body"'],tips:['Use "pm close <ID> <TEXT>" to close items instead of --status closed.',"When reopening from closed to a non-terminal status, update clears stale close_reason unless explicitly set via --close-reason.",'Use "pm append <ID> --body <text>" for additive notes; use update --body to replace body content.']},"update-many":{why:"Bulk-updates matched item sets with dry-run previews and rollback checkpoints for safe large-scale metadata changes.",examples:["pm update-many --filter-status open --status in_progress --dry-run",'pm update-many --filter-tag wave:7 --replace-tests --test "command=node scripts/run-tests.mjs test -- tests/core/history.spec.ts,timeout_seconds=240"','pm update-many --filter-tag governance --reviewer maintainer-review --message "Normalize reviewer metadata"',"pm update-many --rollback ckpt-abc123"],tips:["Use --dry-run first to inspect proposed changes before apply mode.","Linked-array mutation flags mirror pm update semantics (for example --replace-tests, --clear-files, and repeatable --doc/--note seeds).","Checkpoints are enabled by default for apply mode and can be restored with --rollback."]},"close-many":{why:"Bulk-closes matched items with a shared reason routed through full pm close semantics (close validation, active-child orphan checks, blocked-edge cleanup) plus dry-run previews and rollback checkpoints \u2014 unlike update-many --status closed, which bypasses close validation.",examples:['pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run','pm close-many --filter-tag wave:7 --reason "Superseded by redesign" --validate-close warn','pm close-many --ids pm-a,pm-b,pm-c --reason "Closed in batch" --resolution "Verified by integration suite"',"pm close-many --rollback close-many-20260604-abc123"],tips:["At least one filter (--filter-* or --ids) is required so close-many never matches every item.","Already-terminal matches are skipped by default; pass --force to re-close them.","Use --dry-run to preview matches plus per-item skip reasons and active-child orphan warnings before applying.","Checkpoints are enabled by default for apply mode; restore with --rollback <checkpoint-id>."]},templates:{why:"Saves, lists, and inspects reusable create option bundles for repeatable workflows.",examples:['pm templates save triage-default --title "Triage item" --description "..." --type Task --status open --priority 2 --message "Seed triage template"',"pm templates list","pm templates show triage-default"],tips:["Template names are positional arguments (`pm templates save <name>` and `pm templates show <name>`), not --name flags.","Combine templates with explicit create flags; explicit flags always override template defaults."]},deps:{why:"Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.",examples:["pm deps pm-a1b2","pm deps pm-a1b2 --format graph","pm deps pm-a1b2 --max-depth 2 --collapse repeated --summary"],tips:["Use --summary for lightweight counts when full graph payloads are unnecessary."]},list:{why:"Lists active items with deterministic filtering and ordering.",examples:["pm list --limit 20","pm list --type Task --priority 0 --tag release --status in_progress","pm list --compact --sort deadline --order asc","pm list --fields id,title,parent,type --sort parent --order asc"]},"list-all":{why:"Lists all item states (including terminal states) when you need full visibility.",examples:["pm list-all --limit 50","pm list-all --type Issue --include-body"]},"list-open":{why:"Shows work that is ready to claim and start.",examples:["pm list-open --priority 0 --limit 10"]},"list-in-progress":{why:"Tracks active execution and owner progress.",examples:["pm list-in-progress --priority 0 --limit 20"]},"list-blocked":{why:"Surfaces blocked work that needs intervention.",examples:["pm list-blocked --limit 20"]},"list-closed":{why:"Reviews completed work and closure outcomes.",examples:["pm list-closed --limit 20 --type Task"]},"list-canceled":{why:"Audits intentionally discontinued work.",examples:["pm list-canceled --limit 20"]},"list-draft":{why:"Finds incompletely defined items that need refinement before execution.",examples:["pm list-draft --limit 20"]},aggregate:{why:"Runs grouped aggregation queries for governance checks such as decomposition by parent/type or triage by status/priority.",examples:["pm aggregate --group-by parent,type --count","pm aggregate --group-by type,status --count","pm aggregate --group-by parent,type --count --status open --parent pm-feature01"],tips:["Current aggregate mode is grouped counts only, so pass --count explicitly."]},guide:{why:"Routes local progressive-disclosure documentation so agents can fetch only the context they need.",examples:["pm install guide-shell --project","pm guide","pm guide quickstart","pm guide commands --depth standard","pm guide skills --depth deep --format markdown","pm guide release --json"],tips:["Use brief depth for minimal token footprint, standard for excerpted docs, and deep for full local document rendering.","Use --list to force topic index output even when topic parsing is ambiguous."]},calendar:{why:"Provides deadline/reminder/event scheduling views for planning and coordination.",examples:["pm calendar","pm calendar --view agenda --from +0d --to +7d --tag release","pm calendar --view week --date 2026-04-06 --full-period --include deadlines,events","pm calendar --view month --tag release --format json"],tips:["Day/week/month views are anchored period windows; default mode clips the start to now unless --past or --full-period is set.","--full-period applies only to day/week/month views; use --from/--to to bound agenda windows."]},context:{why:"Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.",examples:["pm context","pm ctx --depth standard --limit 10","pm ctx --depth deep --tag release","pm ctx --section hierarchy --section progress --section blockers","pm context --depth standard --activity-limit 20 --stale-threshold 14d","pm context --from +0d --to +7d --format markdown --depth deep"],tips:["High-level focus contains Epics/Features and low-level focus contains Tasks/Issues/Chores/Decisions/Event/Reminder/Milestone/Meeting/Plan.","When no open or in-progress work exists, blocked items are shown as fallback context.","--depth brief (default) shows focus+agenda; standard adds hierarchy/activity/progress/workload; deep adds blockers/files/staleness/tests.","--section overrides --depth and selects specific sections: hierarchy, activity, progress, blockers, files, workload, staleness, tests.","Configure defaults via pm config project set context --default-depth standard --activity-limit 15."]},next:{why:"Answers 'what should I work on now?' with the highest-priority ready item, rationale, and ranked ready and blocked queues.",examples:["pm next","pm next --json","pm next --limit 3 --ready-only","pm next --parent pm-mpbb","pm next --tag release --format markdown"],tips:["Ready = active status, no open blockers, and no open children (a concrete leaf); the recommendation resumes in-progress work before starting new work.","An item is blocked when its scalar blocked_by or a blocked_by dependency points at a non-terminal item; the blocked list names the blockers to clear.","Containers (Epics/Features with open children) are never recommended directly \u2014 the actionable leaf beneath them is.","Use --parent to scope to one epic's subtree, or --ready-only to drop the blocked companion list for the tightest output."]},search:{why:"Finds relevant items by keyword, semantic, or hybrid retrieval modes.",examples:['pm search "lock stale retry" --mode keyword --limit 10','pm search "extension migration blockers" --mode hybrid --type Task --priority 0','pm search "Cross-Epic Realism Dependency Council" --mode keyword --title-exact'],tips:["Use --title-exact to require exact normalized title parity, or --phrase-exact to require full-phrase matches in item text fields.","Use --include-linked when linked docs/files/tests should influence scoring."]},eval:{why:"Measures search relevance against a curated golden-query set so retrieval regressions are caught, not guessed.",examples:["pm eval --json","pm eval --mode hybrid --k 10","pm eval --fail-under 0.6 --json","pm eval --queries ./my-eval.json --mode semantic"],tips:["Curate ground truth in <pmRoot>/search/eval-queries.json as an array of {query, relevant_ids, mode?} objects.","Wire --fail-under into CI to fail the build when aggregate nDCG@k drops below your baseline."]},reindex:{why:"Rebuilds search artifacts after large changes to item corpus or provider/vector config.",examples:["pm reindex --mode keyword","pm reindex --mode hybrid --progress --json"],tips:["Use --progress for non-interactive visibility during local embedding runs.","JSON output includes semantic stale/unchanged/embed/upsert counts so agents can gate long reindex work without parsing stderr."]},get:{why:"Shows details for one item by ID, with optional lower-token projections for agent loops.",examples:["pm get pm-a1b2","pm get pm-a1b2 --depth brief --json","pm get pm-a1b2 --fields id,title,status,parent,type --json","pm get pm-a1b2 --at 7 --fields id,title,status,body --json"],tips:["Default depth is standard for body plus linked artifacts without append-only logs; use brief for metadata-only checks or --full for complete history-heavy metadata.","Use --fields for the smallest deterministic item metadata payload when an agent only needs specific fields.","Schedule metadata is normalized under schedule; request schedule.start_at or schedule.location for narrow calendar reads.","Children are type-agnostic and include bounded deterministic samples plus continuation metadata when a parent has direct children.","Use --at <version|timestamp> for a verified read-only historical projection; reconstructed/as_of fields distinguish it from current state.","JSON output shape is { item, linked, claim_state, schedule, children }; body is nested at item.body (parity with list --include-body)."]},history:{why:"Inspects item mutation timeline and audit trail.",examples:["pm history pm-a1b2 --limit 20","pm history pm-a1b2 --full --verify"]},"history-compact":{why:"Compacts long history streams into a synthetic checkpoint while preserving replay integrity. Pass an item id for one stream, or a bulk selector (--ids/--all-over/--closed/--all-streams) to sweep many.",examples:["pm history-compact pm-a1b2 --dry-run",'pm history-compact pm-a1b2 --before 25 --message "Compact early history"',"pm history-compact --all-over 500 --dry-run","pm history-compact --closed","pm history-compact --ids pm-a1b2,pm-c3d4 --dry-run"]},activity:{why:"Reviews recent tracker-wide activity across items.",examples:["pm activity --limit 50","pm activity --full --id pm-a1b2 --limit 50","pm activity --id pm-a1b2 --op update --from -7d --to now","pm activity --json --stream rows --limit 200"],tips:["Use --stream with --json for line-delimited automation output; --from is inclusive and --to is exclusive."]},restore:{why:"Restores an item to a prior timestamp/version with history replay safety.",examples:['pm restore pm-a1b2 2026-04-01T00:00:00.000Z --message "Rollback to known-good state"']},close:{why:"Transitions work to terminal closed state with explicit rationale.",examples:['pm close pm-a1b2 "Done" --release-assignment --validate-close warn','pm close pm-a1b2 "Done" --validate-close','pm close pm-a1b2 "Done" --validate-close off','pm close pm-a1b2 "Done" --validate-close strict']},delete:{why:"Removes an item while preserving history evidence and lock/ownership checks.",examples:['pm delete pm-a1b2 --message "Remove duplicate item"']},append:{why:"Adds implementation notes to body without replacing existing content.",examples:['pm append pm-a1b2 --body "Implemented retry with bounded backoff." --message "Record implementation detail"']},comments:{why:"Adds or reviews lightweight status updates linked to an item.",examples:['pm comments pm-a1b2 "Verified fix on Linux and macOS"','pm comments pm-a1b2 --add "Verified fix on Linux and macOS"','printf "%s\\n" "## Verification" "- linux pass" "- mac pass" | pm comments pm-a1b2 --stdin',"pm comments pm-a1b2 --file docs/release-evidence.md",'pm comments pm-a1b2 --add "text: verification note with commas, key-like words, and parser details"','pm comments pm-a1b2 --add "Follow-up needed after review" --force',"pm comments pm-a1b2 --limit 10"],tips:["Use exactly one comment source at a time: positional [text], --add, --stdin, or --file.","Use --force when adding comments to items currently assigned to a different owner.","When --add payload resembles CSV-like key fragments (for example text=hello,scope:project), plain-text fallback is intentional; use explicit text=..., markdown text: ..., or stdin token - for structured intent."]},notes:{why:"Adds or reviews durable implementation notes linked to an item.",examples:['pm notes pm-a1b2 --add "Investigated parser edge case and documented fallback logic."','pm notes pm-a1b2 --add "text: parser rationale with commas, colons, and key-like wording"','pm notes pm-a1b2 --edit 1 --add "Corrected durable note"',"pm notes pm-a1b2 --delete 2","pm notes pm-a1b2 --limit 10"],tips:["CSV-like add payloads with extra key fragments are treated as plain text by design; use explicit text keys (text= or text:) when structured parsing is required."]},learnings:{why:"Adds or reviews post-implementation learnings for future work.",examples:['pm learnings pm-a1b2 --add "Avoid direct test-runner commands in linked tests; use sandbox runner."','pm learnings pm-a1b2 --add "text: lesson with commas, key-like words, and punctuation-safe context"',"pm learnings pm-a1b2 --edit 1 --file docs/corrected-learning.md","pm learnings pm-a1b2 --delete 2","pm learnings pm-a1b2 --limit 10"],tips:["If you intended structured parsing for a key-like payload, prefer explicit text=..., markdown text: ..., or stdin token -; ambiguous CSV-like forms intentionally remain plain text."]},files:{why:"Associates changed source files with tracker items for reproducibility.",examples:['pm files pm-a1b2 --add "path=src/cli/main.ts,note=help orchestration"','pm files pm-a1b2 --add src/cli/main.ts --note "help orchestration"',"pm files discover pm-a1b2",'pm files discover pm-a1b2 --apply --note "discovered from item text"']},docs:{why:"Associates relevant documentation paths with tracker items.",examples:['pm docs pm-a1b2 --add "path=README.md,note=user-facing command guidance"','pm docs pm-a1b2 --add README.md --note "user-facing command guidance"']},test:{why:"Links test commands/paths and optionally executes them for one item.",examples:['pm test pm-a1b2 --add "command=node scripts/run-tests.mjs test -- tests/unit/output.spec.ts,timeout_seconds=2400"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,assert_stdout_contains=count:,assert_stdout_regex=count:\\s+\\d+"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,pm_context_mode=auto"',"pm test pm-a1b2 --run --timeout 2400 --env-set PORT=0 --env-clear PLAYWRIGHT_BASE_URL --shared-host-safe --pm-context tracker --fail-on-context-mismatch --fail-on-skipped","pm test pm-a1b2 --run --timeout 2400 --pm-context auto","pm test pm-a1b2 --run --background --timeout 2400 --progress"]},"test-all":{why:"Runs linked tests in bulk for release/readiness sweeps.",examples:["pm test-all --status in_progress --limit 5 --offset 10 --timeout 2400","pm test-all --status closed --timeout 3600 --progress --env-set PORT=0 --shared-host-safe --fail-on-skipped","pm test-all --status in_progress --pm-context tracker --fail-on-context-mismatch --require-assertions-for-pm","pm test-all --status in_progress --pm-context auto --fail-on-context-mismatch","pm test-all --status in_progress --background --timeout 3600"]},"test-runs":{why:"Manages background linked-test runs with lifecycle controls and log/status inspection.",examples:["pm test-runs list --status running --limit 20","pm test-runs status tr-abc123","pm test-runs logs tr-abc123 --stream stderr --tail 200","pm test-runs stop tr-abc123","pm test-runs resume tr-abc123"]},stats:{why:"Reports tracker-level totals and distribution by type/status.",examples:["pm stats","pm stats --json"]},telemetry:{why:"Inspects and manages local telemetry queue/runtime state for observability diagnostics.",examples:["pm telemetry status","pm telemetry stats --limit 10","pm telemetry flush","pm telemetry clear"]},health:{why:"Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.",examples:["pm health","pm health --check-only --summary --json","pm health --brief --json","pm health --no-refresh","pm health --refresh-vectors"]},validate:{why:"Runs standalone metadata, resolution, lifecycle (including dependency-cycle diagnostics), linked-file, linked-command reference, and history drift checks with default remediation hints for resolution gaps.",examples:["pm validate","pm validate --check-resolution --json","pm validate --check-lifecycle --dependency-cycle-severity error","pm validate --check-lifecycle --parent-cycle-severity error","pm validate --check-files --scan-mode tracked-all","pm validate --check-files --scan-mode tracked-all-strict --include-pm-internals","pm validate --check-command-references","pm validate --check-resolution --fail-on-warn --json"],tips:["Resolution-gap warnings include default `pm update <id> ...` remediation hint templates in check details."]},gc:{why:"Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.",examples:["pm gc --dry-run","pm gc"]},claim:{why:"Claims an item to signal active ownership and reduce conflicts.",examples:["pm claim pm-a1b2 --start",'pm claim pm-a1b2 --force --message "Take over terminal item"','pm claim pm-a1b2 --author "release-service" --message "Explicit non-agent identity override"'],tips:["Claim takeover for non-terminal items does not require --force; --force is reserved for terminal/lock overrides.","Harness identity is automatic; use --author only to assert an intentional external principal."]},release:{why:"Releases an active claim when paused, handed off, or completed.",examples:["pm release pm-a1b2 --pause"]},"start-task":{why:"Lifecycle alias that claims an item and sets status to in_progress.",examples:['pm start-task pm-a1b2 --message "Start implementation"']},"pause-task":{why:"Lifecycle alias that sets status to open and releases active assignment.",examples:['pm pause-task pm-a1b2 --message "Pause for dependency unblock"']},"close-task":{why:"Lifecycle alias that closes with reason text and clears assignment metadata.",examples:['pm close-task pm-a1b2 "All acceptance criteria met" --message "Close and handoff"']},meet:{why:"Shortcut to create a Meeting from friendly time flags (start/duration) without structured --event CSV.",examples:['pm meet "Sprint Planning" --start +1h --duration 1h','pm meet "1:1" --start 2026-07-01T15:00:00Z --end 2026-07-01T15:30:00Z --location "Room A"'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},event:{why:"Shortcut to create an Event from friendly time flags (start/duration) without structured --event CSV.",examples:['pm event "Release v2" --start 2026-07-01T10:00:00Z --duration 2h','pm event "Conference" --start 2026-08-01 --all-day'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},remind:{why:"Shortcut to create a Reminder from a single point in time without structured --reminder CSV.",examples:['pm remind "Review PR" --at +2d','pm remind "Follow up" --at 2026-07-01T09:00:00Z --text "Ping the team"'],tips:["The reminder time defaults to +1d and the reminder text defaults to the title."]},completion:{why:"Generates shell completion scripts for faster and more reliable command entry.",examples:["pm completion bash","pm completion zsh","pm completion fish","pm completion bash --eager-tags"],tips:["Default scripts resolve tag suggestions lazily at completion time; use --eager-tags to embed current tags directly."]},contracts:{why:"Exposes machine-readable CLI command and tool schema contracts for agent integrations.",examples:["pm contracts","pm contracts --command list --runtime-only","pm contracts --command update --flags-only","pm contracts --availability-only --runtime-only","pm contracts --action create","pm contracts --schema-only"],tips:["Use --command to narrow actions/schema to one CLI surface; combine with --flags-only or --availability-only for lighter payloads."]}};for(const{alias,canonical}of PM_RELOCATED_COMMAND_ALIASES){const bundle=HELP_BY_COMMAND_PATH[alias];if(bundle){HELP_BY_COMMAND_PATH[canonical]={...bundle,examples:bundle.examples.map(example=>example.replace(`pm ${alias}`,`pm ${canonical}`))}}}const ROOT_HELP_BUNDLE={why:"Provides deterministic project management workflows for humans and coding agents.",examples:["pm init","pm install guide-shell --project","pm list-open --limit 10",'pm create --title "..." --description "..." --type Task --status open --priority 1 --message "..." --create-mode progressive'],tips:["Use <command> --help for command-specific guidance and examples.","Install guide-shell before using pm guide for local docs and skills routing.","Use --json for machine parsing and integration flows.","Use --no-pager to force direct help output in CI and other non-interactive shells."]};const deprecatedHelpAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(entry=>entry.lifecycle==="deprecated");for(const contract of deprecatedHelpAliases){const bundle=HELP_BY_COMMAND_PATH[contract.alias];HELP_BY_COMMAND_PATH[contract.alias]={...bundle,why:`Deprecated: use pm ${contract.canonical_argv.join(" ")}. ${bundle.why}`}}for(const bundle of[ROOT_HELP_BUNDLE,...Object.values(HELP_BY_COMMAND_PATH)]){bundle.examples=bundle.examples.map(example=>{for(const contract of deprecatedHelpAliases){const alias=contract.alias.replace(/[.*+?^${}()|[\]\\]/g,"\\$&");example=example.replaceAll(new RegExp(`\\bpm ${alias}(?![\\w-])`,"g"),`pm ${contract.canonical_argv.join(" ")}`)}return example})}function resolveCanonicalHelpPath(commandPath){const normalized=normalizeHelpCommandPath(commandPath??"");if(!normalized){return""}return HELP_PATH_ALIASES[normalized]??normalized}function resolveHelpBundleForPath(commandPath){const canonicalPath=resolveCanonicalHelpPath(commandPath);if(!canonicalPath){return ROOT_HELP_BUNDLE}return HELP_BY_COMMAND_PATH[canonicalPath]??ROOT_HELP_BUNDLE}function resolveHelpNarrative(commandPath,detailMode){const bundle=resolveHelpBundleForPath(commandPath);return{intent:bundle.why,examples:detailMode==="detailed"?[...bundle.examples]:firstExampleOrEmpty(bundle.examples),tips:detailMode==="detailed"?[...bundle.tips??[]]:[],detail_mode:detailMode}}function renderFullCommandAliasHelp(){const permanentAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="permanent");const deprecatedAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="deprecated");return["","Command aliases:",...permanentAliases.map(({alias,canonical_argv:canonicalArgv})=>`  ${alias} -> pm ${canonicalArgv.join(" ")}`),"","Deprecated aliases:",...deprecatedAliases.map(contract=>`  ${contract.alias} -> pm ${contract.canonical_argv.join(" ")} (${renderPmCommandAliasMigrationHint(contract)})`)].join("\n")}function configureTieredHelpVisibility(program,baselineHelp,fullDiscovery,selectedRootCommands){const coreOptions=new Set(PM_CORE_HELP_OPTION_FLAGS);program.configureHelp({visibleCommands(command){const visible=baselineHelp.visibleCommands(command);if(!fullDiscovery){if(command!==program)return visible;return visible.filter(candidate=>selectedRootCommands.has(candidate))}return visible.filter(candidate=>{const declaredTier=getPmCommandHelpVisibilityTier(candidate);return(declaredTier??resolvePmCommandVisibilityTier(candidate.name()))!=="internal"})},visibleOptions(command){const visible=baselineHelp.visibleOptions(command);if(command!==program||fullDiscovery)return visible;return visible.filter(option=>coreOptions.has(option.flags))}})}function selectBudgetedRootCommands(program,baselineHelp,selectedRootCommands,rootHelpText){const coreCommands=new Set(listPmCommandsForTier("core"));const budgetHelp=program.createHelp();budgetHelp.prepareContext({error:false,helpWidth:80,outputHasColors:false});const renderBudgetHelp=()=>`${budgetHelp.formatHelp(program,budgetHelp)}${rootHelpText}
-`;const rootCandidates=baselineHelp.visibleCommands(program);for(const candidate of rootCandidates){const declaredTier=getPmCommandHelpVisibilityTier(candidate);if(declaredTier===void 0&&(candidate.name()==="help"||coreCommands.has(candidate.name()))){selectedRootCommands.add(candidate)}}for(const candidate of rootCandidates){if(getPmCommandHelpVisibilityTier(candidate)!=="core")continue;selectedRootCommands.add(candidate);if(!measurePmCoreHelp(renderBudgetHelp()).within_budget){selectedRootCommands.delete(candidate)}}}function attachRichHelpText(program,argv=process.argv.slice(2)){const baselineHelp=program.createHelp();const fullDiscovery=isFullHelpDiscovery(argv);const selectedRootCommands=new Set;configureTieredHelpVisibility(program,baselineHelp,fullDiscovery,selectedRootCommands);const detailMode=resolveHelpDetailMode(argv);const rootHelpText=renderHelpBundle(ROOT_HELP_BUNDLE,detailMode);program.addHelpText("after",rootHelpText);if(fullDiscovery){program.addHelpText("after",renderFullCommandAliasHelp())}selectBudgetedRootCommands(program,baselineHelp,selectedRootCommands,rootHelpText);for(const[commandPath,bundle]of Object.entries(HELP_BY_COMMAND_PATH)){attachBundleByPath(program,commandPath,bundle,detailMode)}const requestedPath=normalizeHelpCommandPath(parseBootstrapHelpRequest(argv).commandPathTokens.join(" "));const positionalAction=resolvePmPositionalActionContract(requestedPath);if(positionalAction){attachBundleByPath(program,positionalAction.parent,{why:positionalAction.description,examples:[positionalAction.example],tips:[`Action path: pm ${positionalAction.command}`,formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]},detailMode);return}const positionalActions=PM_POSITIONAL_ACTION_CONTRACTS.filter(({parent})=>parent===requestedPath);if(positionalActions.length>0){attachBundleByPath(program,requestedPath,{why:`Dispatches one declared positional action: ${positionalActions.map(({action})=>action).join("|")}.`,examples:positionalActions.map(({example})=>example),tips:[`Inspect one action directly with pm ${requestedPath} <action> --help --json.`]},detailMode)}}const _testOnly={renderCompactHelpBundle,renderDetailedHelpBundle};export{ROOT_HELP_BUNDLE,_testOnly,attachRichHelpText,firstExampleOrEmpty,getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,resolveHelpBundleForPath,resolveHelpDetailMode,resolveHelpNarrative,setPmCommandHelpVisibilityTier};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6ec548d1-a26d-5e72-9a7b-0fbd74a86601")}catch{}})();import{parseBootstrapHelpRequest}from"./bootstrap-args.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{listPmCommandsForTier,measurePmCoreHelp,PM_CORE_HELP_OPTION_FLAGS,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";import{PM_COMMAND_ALIAS_CONTRACTS,PM_RELOCATED_COMMAND_ALIASES,renderPmCommandAliasMigrationHint}from"../sdk/cli-contracts.js";const COMMAND_HELP_VISIBILITY_TIERS=new WeakMap;function setPmCommandHelpVisibilityTier(command,tier){COMMAND_HELP_VISIBILITY_TIERS.set(command,tier)}function getPmCommandHelpVisibilityTier(command){return COMMAND_HELP_VISIBILITY_TIERS.get(command)}function firstExampleOrEmpty(examples){return examples.length>0?[examples[0]]:[]}function renderCompactHelpBundle(bundle){const lines=["","Intent:",`  ${bundle.why}`],compactExamples=firstExampleOrEmpty(bundle.examples);return compactExamples.length>0&&(lines.push("","Example:"),lines.push(`  ${compactExamples[0]}`)),lines.push("","Need deeper rationale and more examples?"),lines.push("  Re-run with --explain."),lines.join(`
+`)}function renderDetailedHelpBundle(bundle){const lines=["","Why use this command:",`  ${bundle.why}`,"","Examples:",...bundle.examples.map(example=>`  ${example}`)];return bundle.tips&&bundle.tips.length>0&&(lines.push("","Tips:"),lines.push(...bundle.tips.map(tip=>`  - ${tip}`))),lines.join(`
+`)}function renderHelpBundle(bundle,detailMode){return detailMode==="detailed"?renderDetailedHelpBundle(bundle):renderCompactHelpBundle(bundle)}function normalizeHelpCommandPath(commandPath){return commandPath.trim().toLowerCase().split(/\s+/).filter(part=>part.length>0).join(" ")}const HELP_PATH_ALIASES={cal:"calendar",ctx:"context"};function findDirectChildCommand(parent,name){return parent.commands.find(entry=>entry.name()===name)??null}function findCommandByPath(root,pathParts){let current=root;for(const part of pathParts){const next=findDirectChildCommand(current,part);if(!next)return null;current=next}return current}function attachBundleByPath(root,commandPath,bundle,detailMode){const command=findCommandByPath(root,commandPath.split(" ").filter(part=>part.length>0));command&&command.addHelpText("after",renderHelpBundle(bundle,detailMode))}function resolveHelpDetailMode(argv){return argv.includes("--explain")?"detailed":"compact"}function isFullHelpDiscovery(argv){return argv.includes("--all")||argv.includes("--explain")}const HELP_BY_COMMAND_PATH={ops:{why:"Groups workspace diagnostics, quality checks, and maintenance under one discoverable command.",examples:["pm ops health --summary","pm ops validate --check-history-drift","pm ops --help"]},init:{why:"Bootstraps tracker storage and settings so all other commands can run safely.",examples:["pm init","pm init acme","pm init ./pm-sandbox --defaults","pm init --preset minimal","pm init --agent-guidance add","pm init --defaults --with-packages"],tips:["Run this once per repository before create/list/update commands.","A path-like positional (`./dir`, `/tmp/dir`) initializes that tracker path; a plain word remains an id prefix.","Rewriting id prefix, governance preset, or default author on an existing tracker requires --force.","Use --preset for non-interactive automation; omit it in a TTY to use the setup wizard.","Use --agent-guidance add to inject compact AGENTS/CLAUDE workflow guidance, or --agent-guidance status to inspect missing guidance without modifying files.","Use --with-packages when agents need bundled commands such as calendar and templates available immediately."]},config:{why:"Reads or updates project/global settings such as definition-of-done, item format, telemetry, and policy toggles.",examples:["pm config project get definition-of-done",'pm config project set definition-of-done --criterion "tests pass"',"pm config project set item-format --format toon","pm config project set sprint-release-format-policy --policy strict_error","pm config project set governance-preset --policy minimal","pm config project set governance-ownership-enforcement --policy none","pm config project set test-result-tracking --policy enabled","pm config global set telemetry-tracking --policy disabled"]},extension:{why:"Compatibility command for package-backed runtime extension lifecycle operations across project or global scope.",examples:["pm install ./my-package --project","pm install '*' --project","pm package doctor --project --detail summary","pm package manage --global","pm package activate sample-ext --project","pm package deactivate sample-ext --project","pm package uninstall sample-ext --global","pm extension explore --project","pm extension manage --global","pm extension describe sample-ext --project","pm extension doctor --detail deep"],tips:["Prefer pm install and pm package in new user-facing automation.","Use pm extension when maintaining existing extension-specific scripts or debugging the compatibility runtime directly.","Bundled aliases beads and todos resolve to package-shipped extension sources.","Use --gh/--github shorthand for GitHub sources and --ref to pin a branch, tag, or ref.","Install updates settings activation state automatically unless extension allowlist mode is unchanged.","Use --adopt for single-extension adoption and --adopt-all to bulk-register unmanaged installs as managed without reinstalling.","Use --manage for concise triage summaries and remediation-oriented diagnostics alongside full extension details.","Use --describe to map exactly what each loaded extension registers (commands, hooks, item types, providers, overrides) in one call.","Use --doctor for consolidated diagnostics with warning codes, remediation hints, and optional deep detail payloads."]},package:{why:"Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.",examples:["pm install npm:@scope/pm-package --project","pm package install ./my-package --project","pm package doctor --project --detail deep","pm package manage --project --runtime-probe","pm package describe --project","pm package activate sample-ext --project","pm upgrade --packages-only --dry-run"],tips:["Prefer package vocabulary for user-facing workflows; extension vocabulary remains available for compatibility.","Use pm package describe [name] to map every surface a package registers without reading its manifest or running diagnostics.","Use pm upgrade to refresh the CLI/SDK and managed packages from their recorded sources.","Use --dry-run before upgrade when automation needs a deterministic plan."]},"package init":{why:"Generates an installable starter pm package with package metadata and a root extension entrypoint.",examples:["pm package init ./my-package","pm package init ./my-hook-package --capability hooks","pm package init ./my-search-package --capability search","pm package init ./my-sync-package --capability importers","pm package init ./my-domain-package --capability schema","pm package init ./my-output-package --capability renderers","pm install ./my-sync-package --project","pm package doctor --project --detail summary"],tips:["Use --capability hooks for a starter after_command lifecycle reactor with runnable SDK testing coverage.","Use --capability search for a starter search provider/vector-store adapter with runnable SDK testing coverage.","Use --capability importers for paired import/export commands that move project context across systems.","Use --capability schema for a starter custom item type, field, and migration so pm models your project domain.","Use --capability renderers/parser/preflight/services for starter override surfaces (output renderer, parsed-option rewrite, pre-run gate decision, built-in service) \u2014 one runnable starter per SDK capability.","The generated package is local-install safe; add SDK runtime imports only after declaring dependencies and validating with package doctor.","Use package doctor after changes to verify activation, policy, and collision diagnostics."]},"package install":{why:"Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.",examples:["pm package install ./my-package --project","pm install npm:pm-changelog --project","pm package install --github org/repo/packages/my-pm-package --ref main"],tips:["Prefer the top-level pm install alias in scripts when only installation is needed.","Run pm package manage or pm package doctor after installing external packages."]},"package doctor":{why:"Diagnoses package activation, policy, collision, and managed-state health for project or global package scopes.",examples:["pm package doctor --project --detail summary","pm package doctor --project --detail deep --trace","pm package doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed package registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global package state: PM_GLOBAL_PATH=$(mktemp -d) pm package doctor --project --detail deep --trace.","Non-isolated project diagnostics include global registrations and emit remediation when global package state can affect the result."]},"package catalog":{why:"Lists bundled first-party package catalog metadata and compact field projections.",examples:["pm package catalog --project","pm package catalog --project --fields alias,installed,install_command","pm package list --project --fields alias,package_name,category"],tips:["Use --fields for low-token package discovery in agent loops.","External npm package discovery still belongs to npm search."]},"extension init":{why:"Generates an installable starter runtime extension with manifest and entrypoint files.",examples:["pm extension init ./my-extension","pm extension init ./my-hook-extension --capability hooks","pm extension init ./my-search-extension --capability search","pm extension init ./my-sync-extension --capability importers","pm extension init ./my-domain-extension --capability schema","pm extension init ./my-output-extension --capability renderers","pm extension --install --project ./my-sync-extension","pm extension --doctor --project --detail summary"],tips:["Use --capability hooks when the extension should react to command lifecycle events.","Use --capability search when the extension should register retrieval primitives.","Use --capability importers when the extension should register project-context import/export commands.","Use --capability schema when the extension should register custom item types, fields, and migrations.","Use --capability renderers/parser/preflight/services to override pm's output rendering, parsed options, pre-run gate, or a built-in service.","Use package init for new distributable package workflows; extension init is the compatibility-level runtime scaffold."]},"extension install":{why:"Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.",examples:["pm extension install ./my-extension --project","pm extension --install --project ./my-extension","pm extension doctor --project --detail summary"],tips:["Prefer pm install or pm package install for new package-first automation."]},"extension doctor":{why:"Diagnoses compatibility extension activation, policy, collision, and managed-state health for project or global extension scopes.",examples:["pm extension doctor --project --detail summary","pm extension doctor --project --detail deep --trace","pm extension doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed extension registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global extension state: PM_GLOBAL_PATH=$(mktemp -d) pm extension doctor --project --detail deep --trace.","Prefer pm package doctor in new package-first workflows."]},"extension catalog":{why:"Compatibility view of bundled package catalog metadata.",examples:["pm extension catalog --project","pm extension catalog --project --fields alias,installed,install_command"],tips:["Prefer pm package catalog in new user-facing workflows."]},install:{why:"Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.",examples:["pm install '*' --project","pm install ./packages/pm-todos --project","pm install npm:@scope/pm-package --global","pm install --github org/repo/packages/my-pm-package --ref main"],tips:["Installed packages are recorded in managed state and can be inspected with pm package manage."]},upgrade:{why:"Updates the global pm CLI/SDK and refreshes managed pm packages from recorded install sources.",examples:["pm upgrade --dry-run","pm upgrade --packages-only --project","pm upgrade todos --dry-run","pm upgrade --cli-only --repair","pm upgrade --tag next --dry-run"],tips:["Omit target to include the CLI/SDK plus all managed packages in the selected scope.","Pass a target to refresh one managed package by name, directory, package name, or source.","Use --packages-only in repository automation when the global CLI should not be changed."]},create:{why:"Creates a new planning item with deterministic metadata and history.",examples:['pm create --title "Harden lock flow" --description "Improve stale lock handling" --type Task --status open --priority 1 --message "Create lock hardening task" --create-mode progressive','pm create --title "Weekly planning sync" --description "Recurring coordination meeting" --type Meeting --schedule-preset lightweight','pm create --title "Asset: Hero model" --description "Track playable model asset" --type Asset --status open --priority 1 --message "Create asset item" --type-option category=Character --dep "id=pm-epic01,kind=parent,created_at=now" --comment "created_at=now,text=Why this asset item exists." --note "created_at=now,text=Initial implementation note." --learning "created_at=now,text=Durable lesson placeholder." --file "path=src/assets/hero.glb,note=tracked asset" --test "command=node scripts/run-tests.mjs test,timeout_seconds=240" --doc "path=README.md,note=asset docs"'],tips:["Use --schedule-preset lightweight for Reminder/Meeting/Event when you want minimal required create inputs.","Use --type <value> to load type-aware policy guidance in --help output."]},focus:{why:"Sets a session focused item so new pm create items default their --parent to it (project management = context management).",examples:["pm focus pm-epic1","pm focus","pm focus --clear"],tips:["Focus is session-local (stored in .agents/pm/runtime/session.json, gitignored) \u2014 it never affects teammates.",'An explicit --parent on pm create always overrides the focused item; use --parent "" to create with no parent.',"A stale focused item produces the same missing-parent validation as an explicit stale --parent."]},update:{why:"Mutates existing item fields while preserving history and lock safety.",examples:['pm update pm-a1b2 --status in_progress --message "Start implementation"','pm update pm-a1b2 --unset close-reason --message "Clear stale close reason after reopen"','pm update pm-a1b2 --unset assignee --deadline +2d --message "Replan ownership and deadline"','pm update pm-a1b2 --body "Backfilled body text for legacy item" --message "Normalize missing body"'],tips:['Use "pm close <ID> <TEXT>" to close items instead of --status closed.',"When reopening from closed to a non-terminal status, update clears stale close_reason unless explicitly set via --close-reason.",'Use "pm append <ID> --body <text>" for additive notes; use update --body to replace body content.']},"update-many":{why:"Bulk-updates matched item sets with dry-run previews and rollback checkpoints for safe large-scale metadata changes.",examples:["pm update-many --filter-status open --status in_progress --dry-run",'pm update-many --filter-tag wave:7 --replace-tests --test "command=node scripts/run-tests.mjs test -- tests/core/history.spec.ts,timeout_seconds=240"','pm update-many --filter-tag governance --reviewer maintainer-review --message "Normalize reviewer metadata"',"pm update-many --rollback ckpt-abc123"],tips:["Use --dry-run first to inspect proposed changes before apply mode.","Linked-array mutation flags mirror pm update semantics (for example --replace-tests, --clear-files, and repeatable --doc/--note seeds).","Checkpoints are enabled by default for apply mode and can be restored with --rollback."]},"close-many":{why:"Bulk-closes matched items with a shared reason routed through full pm close semantics (close validation, active-child orphan checks, blocked-edge cleanup) plus dry-run previews and rollback checkpoints \u2014 unlike update-many --status closed, which bypasses close validation.",examples:['pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run','pm close-many --filter-tag wave:7 --reason "Superseded by redesign" --validate-close warn','pm close-many --ids pm-a,pm-b,pm-c --reason "Closed in batch" --resolution "Verified by integration suite"',"pm close-many --rollback close-many-20260604-abc123"],tips:["At least one filter (--filter-* or --ids) is required so close-many never matches every item.","Already-terminal matches are skipped by default; pass --force to re-close them.","Use --dry-run to preview matches plus per-item skip reasons and active-child orphan warnings before applying.","Checkpoints are enabled by default for apply mode; restore with --rollback <checkpoint-id>."]},templates:{why:"Saves, lists, and inspects reusable create option bundles for repeatable workflows.",examples:['pm templates save triage-default --title "Triage item" --description "..." --type Task --status open --priority 2 --message "Seed triage template"',"pm templates list","pm templates show triage-default"],tips:["Template names are positional arguments (`pm templates save <name>` and `pm templates show <name>`), not --name flags.","Combine templates with explicit create flags; explicit flags always override template defaults."]},deps:{why:"Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.",examples:["pm deps pm-a1b2","pm deps pm-a1b2 --format graph","pm deps pm-a1b2 --max-depth 2 --collapse repeated --summary"],tips:["Use --summary for lightweight counts when full graph payloads are unnecessary."]},list:{why:"Lists active items with deterministic filtering and ordering.",examples:["pm list --limit 20","pm list --type Task --priority 0 --tag release --status in_progress","pm list --compact --sort deadline --order asc","pm list --fields id,title,parent,type --sort parent --order asc"]},"list-all":{why:"Lists all item states (including terminal states) when you need full visibility.",examples:["pm list-all --limit 50","pm list-all --type Issue --include-body"]},"list-open":{why:"Shows work that is ready to claim and start.",examples:["pm list-open --priority 0 --limit 10"]},"list-in-progress":{why:"Tracks active execution and owner progress.",examples:["pm list-in-progress --priority 0 --limit 20"]},"list-blocked":{why:"Surfaces blocked work that needs intervention.",examples:["pm list-blocked --limit 20"]},"list-closed":{why:"Reviews completed work and closure outcomes.",examples:["pm list-closed --limit 20 --type Task"]},"list-canceled":{why:"Audits intentionally discontinued work.",examples:["pm list-canceled --limit 20"]},"list-draft":{why:"Finds incompletely defined items that need refinement before execution.",examples:["pm list-draft --limit 20"]},aggregate:{why:"Runs grouped aggregation queries for governance checks such as decomposition by parent/type or triage by status/priority.",examples:["pm aggregate --group-by parent,type --count","pm aggregate --group-by type,status --count","pm aggregate --group-by parent,type --count --status open --parent pm-feature01"],tips:["Current aggregate mode is grouped counts only, so pass --count explicitly."]},guide:{why:"Routes local progressive-disclosure documentation so agents can fetch only the context they need.",examples:["pm install guide-shell --project","pm guide","pm guide quickstart","pm guide commands --depth standard","pm guide skills --depth deep --format markdown","pm guide release --json"],tips:["Use brief depth for minimal token footprint, standard for excerpted docs, and deep for full local document rendering.","Use --list to force topic index output even when topic parsing is ambiguous."]},calendar:{why:"Provides deadline/reminder/event scheduling views for planning and coordination.",examples:["pm calendar","pm calendar --view agenda --from +0d --to +7d --tag release","pm calendar --view week --date 2026-04-06 --full-period --include deadlines,events","pm calendar --view month --tag release --format json"],tips:["Day/week/month views are anchored period windows; default mode clips the start to now unless --past or --full-period is set.","--full-period applies only to day/week/month views; use --from/--to to bound agenda windows."]},context:{why:"Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.",examples:["pm context","pm ctx --depth standard --limit 10","pm ctx --depth deep --tag release","pm ctx --section hierarchy --section progress --section blockers","pm context --depth standard --activity-limit 20 --stale-threshold 14d","pm context --from +0d --to +7d --format markdown --depth deep"],tips:["High-level focus contains Epics/Features and low-level focus contains Tasks/Issues/Chores/Decisions/Event/Reminder/Milestone/Meeting/Plan.","When no open or in-progress work exists, blocked items are shown as fallback context.","--depth brief (default) shows focus+agenda; standard adds hierarchy/activity/progress/workload; deep adds blockers/files/staleness/tests.","--section overrides --depth and selects specific sections: hierarchy, activity, progress, blockers, files, workload, staleness, tests.","Configure defaults via pm config project set context --default-depth standard --activity-limit 15."]},next:{why:"Answers 'what should I work on now?' with the highest-priority ready item, rationale, and ranked ready and blocked queues.",examples:["pm next","pm next --json","pm next --limit 3 --ready-only","pm next --parent pm-mpbb","pm next --tag release --format markdown"],tips:["Ready = active status, no open blockers, and no open children (a concrete leaf); the recommendation resumes in-progress work before starting new work.","An item is blocked when its scalar blocked_by or a blocked_by dependency points at a non-terminal item; the blocked list names the blockers to clear.","Containers (Epics/Features with open children) are never recommended directly \u2014 the actionable leaf beneath them is.","Use --parent to scope to one epic's subtree, or --ready-only to drop the blocked companion list for the tightest output."]},search:{why:"Finds relevant items by keyword, semantic, or hybrid retrieval modes.",examples:['pm search "lock stale retry" --mode keyword --limit 10','pm search "extension migration blockers" --mode hybrid --type Task --priority 0','pm search "Cross-Epic Realism Dependency Council" --mode keyword --title-exact'],tips:["Use --title-exact to require exact normalized title parity, or --phrase-exact to require full-phrase matches in item text fields.","Use --include-linked when linked docs/files/tests should influence scoring."]},eval:{why:"Measures search relevance against a curated golden-query set so retrieval regressions are caught, not guessed.",examples:["pm eval --json","pm eval --mode hybrid --k 10","pm eval --fail-under 0.6 --json","pm eval --queries ./my-eval.json --mode semantic"],tips:["Curate ground truth in <pmRoot>/search/eval-queries.json as an array of {query, relevant_ids, mode?} objects.","Wire --fail-under into CI to fail the build when aggregate nDCG@k drops below your baseline."]},reindex:{why:"Rebuilds search artifacts after large changes to item corpus or provider/vector config.",examples:["pm reindex --mode keyword","pm reindex --mode hybrid --progress --json"],tips:["Use --progress for non-interactive visibility during local embedding runs.","JSON output includes semantic stale/unchanged/embed/upsert counts so agents can gate long reindex work without parsing stderr."]},get:{why:"Shows details for one item by ID, with optional lower-token projections for agent loops.",examples:["pm get pm-a1b2","pm get pm-a1b2 --depth brief --json","pm get pm-a1b2 --fields id,title,status,parent,type --json","pm get pm-a1b2 --at 7 --fields id,title,status,body --json"],tips:["Default depth is standard for body plus linked artifacts without append-only logs; use brief for metadata-only checks or --full for complete history-heavy metadata.","Use --fields for the smallest deterministic item metadata payload when an agent only needs specific fields.","Schedule metadata is normalized under schedule; request schedule.start_at or schedule.location for narrow calendar reads.","Children are type-agnostic and include bounded deterministic samples plus continuation metadata when a parent has direct children.","Use --at <version|timestamp> for a verified read-only historical projection; reconstructed/as_of fields distinguish it from current state.","JSON output shape is { item, linked, claim_state, schedule, children }; body is nested at item.body (parity with list --include-body)."]},history:{why:"Inspects item mutation timeline and audit trail.",examples:["pm history pm-a1b2 --limit 20","pm history pm-a1b2 --full --verify"]},"history-compact":{why:"Compacts long history streams into a synthetic checkpoint while preserving replay integrity. Pass an item id for one stream, or a bulk selector (--ids/--all-over/--closed/--all-streams) to sweep many.",examples:["pm history-compact pm-a1b2 --dry-run",'pm history-compact pm-a1b2 --before 25 --message "Compact early history"',"pm history-compact --all-over 500 --dry-run","pm history-compact --closed","pm history-compact --ids pm-a1b2,pm-c3d4 --dry-run"]},activity:{why:"Reviews recent tracker-wide activity across items.",examples:["pm activity --limit 50","pm activity --full --id pm-a1b2 --limit 50","pm activity --id pm-a1b2 --op update --from -7d --to now","pm activity --json --stream rows --limit 200"],tips:["Use --stream with --json for line-delimited automation output; --from is inclusive and --to is exclusive."]},restore:{why:"Restores an item to a prior timestamp/version with history replay safety.",examples:['pm restore pm-a1b2 2026-04-01T00:00:00.000Z --message "Rollback to known-good state"']},close:{why:"Transitions work to terminal closed state with explicit rationale.",examples:['pm close pm-a1b2 "Done" --release-assignment --validate-close warn','pm close pm-a1b2 "Done" --validate-close','pm close pm-a1b2 "Done" --validate-close off','pm close pm-a1b2 "Done" --validate-close strict']},delete:{why:"Removes an item while preserving history evidence and lock/ownership checks.",examples:['pm delete pm-a1b2 --message "Remove duplicate item"']},append:{why:"Adds implementation notes to body without replacing existing content.",examples:['pm append pm-a1b2 --body "Implemented retry with bounded backoff." --message "Record implementation detail"']},comments:{why:"Adds or reviews lightweight status updates linked to an item.",examples:['pm comments pm-a1b2 "Verified fix on Linux and macOS"','pm comments pm-a1b2 --add "Verified fix on Linux and macOS"','printf "%s\\n" "## Verification" "- linux pass" "- mac pass" | pm comments pm-a1b2 --stdin',"pm comments pm-a1b2 --file docs/release-evidence.md",'pm comments pm-a1b2 --add "text: verification note with commas, key-like words, and parser details"','pm comments pm-a1b2 --add "Follow-up needed after review" --force',"pm comments pm-a1b2 --limit 10"],tips:["Use exactly one comment source at a time: positional [text], --add, --stdin, or --file.","Use --force when adding comments to items currently assigned to a different owner.","When --add payload resembles CSV-like key fragments (for example text=hello,scope:project), plain-text fallback is intentional; use explicit text=..., markdown text: ..., or stdin token - for structured intent."]},notes:{why:"Adds or reviews durable implementation notes linked to an item.",examples:['pm notes pm-a1b2 --add "Investigated parser edge case and documented fallback logic."','pm notes pm-a1b2 --add "text: parser rationale with commas, colons, and key-like wording"','pm notes pm-a1b2 --edit 1 --add "Corrected durable note"',"pm notes pm-a1b2 --delete 2","pm notes pm-a1b2 --limit 10"],tips:["CSV-like add payloads with extra key fragments are treated as plain text by design; use explicit text keys (text= or text:) when structured parsing is required."]},learnings:{why:"Adds or reviews post-implementation learnings for future work.",examples:['pm learnings pm-a1b2 --add "Avoid direct test-runner commands in linked tests; use sandbox runner."','pm learnings pm-a1b2 --add "text: lesson with commas, key-like words, and punctuation-safe context"',"pm learnings pm-a1b2 --edit 1 --file docs/corrected-learning.md","pm learnings pm-a1b2 --delete 2","pm learnings pm-a1b2 --limit 10"],tips:["If you intended structured parsing for a key-like payload, prefer explicit text=..., markdown text: ..., or stdin token -; ambiguous CSV-like forms intentionally remain plain text."]},files:{why:"Associates changed source files with tracker items for reproducibility.",examples:['pm files pm-a1b2 --add "path=src/cli/main.ts,note=help orchestration"','pm files pm-a1b2 --add src/cli/main.ts --note "help orchestration"',"pm files discover pm-a1b2",'pm files discover pm-a1b2 --apply --note "discovered from item text"']},docs:{why:"Associates relevant documentation paths with tracker items.",examples:['pm docs pm-a1b2 --add "path=README.md,note=user-facing command guidance"','pm docs pm-a1b2 --add README.md --note "user-facing command guidance"']},test:{why:"Links test commands/paths and optionally executes them for one item.",examples:['pm test pm-a1b2 --add "command=node scripts/run-tests.mjs test -- tests/unit/output.spec.ts,timeout_seconds=2400"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,assert_stdout_contains=count:,assert_stdout_regex=count:\\s+\\d+"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,pm_context_mode=auto"',"pm test pm-a1b2 --run --timeout 2400 --env-set PORT=0 --env-clear PLAYWRIGHT_BASE_URL --shared-host-safe --pm-context tracker --fail-on-context-mismatch --fail-on-skipped","pm test pm-a1b2 --run --timeout 2400 --pm-context auto","pm test pm-a1b2 --run --background --timeout 2400 --progress"]},"test-all":{why:"Runs linked tests in bulk for release/readiness sweeps.",examples:["pm test-all --status in_progress --limit 5 --offset 10 --timeout 2400","pm test-all --status closed --timeout 3600 --progress --env-set PORT=0 --shared-host-safe --fail-on-skipped","pm test-all --status in_progress --pm-context tracker --fail-on-context-mismatch --require-assertions-for-pm","pm test-all --status in_progress --pm-context auto --fail-on-context-mismatch","pm test-all --status in_progress --background --timeout 3600"]},"test-runs":{why:"Manages background linked-test runs with lifecycle controls and log/status inspection.",examples:["pm test-runs list --status running --limit 20","pm test-runs status tr-abc123","pm test-runs logs tr-abc123 --stream stderr --tail 200","pm test-runs stop tr-abc123","pm test-runs resume tr-abc123"]},stats:{why:"Reports tracker-level totals and distribution by type/status.",examples:["pm stats","pm stats --json"]},telemetry:{why:"Inspects and manages local telemetry queue/runtime state for observability diagnostics.",examples:["pm telemetry status","pm telemetry stats --limit 10","pm telemetry flush","pm telemetry clear"]},health:{why:"Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.",examples:["pm health","pm health --check-only --summary --json","pm health --brief --json","pm health --no-refresh","pm health --refresh-vectors"]},validate:{why:"Runs standalone metadata, resolution, lifecycle (including dependency-cycle diagnostics), linked-file, linked-command reference, and history drift checks with default remediation hints for resolution gaps.",examples:["pm validate","pm validate --check-resolution --json","pm validate --check-lifecycle --dependency-cycle-severity error","pm validate --check-lifecycle --parent-cycle-severity error","pm validate --check-files --scan-mode tracked-all","pm validate --check-files --scan-mode tracked-all-strict --include-pm-internals","pm validate --check-command-references","pm validate --check-resolution --fail-on-warn --json"],tips:["Resolution-gap warnings include default `pm update <id> ...` remediation hint templates in check details."]},gc:{why:"Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.",examples:["pm gc --dry-run","pm gc"]},claim:{why:"Claims an item to signal active ownership and reduce conflicts.",examples:["pm claim pm-a1b2 --start",'pm claim pm-a1b2 --force --message "Take over terminal item"','pm claim pm-a1b2 --author "release-service" --message "Explicit non-agent identity override"'],tips:["Claim takeover for non-terminal items does not require --force; --force is reserved for terminal/lock overrides.","Harness identity is automatic; use --author only to assert an intentional external principal."]},release:{why:"Releases an active claim when paused, handed off, or completed.",examples:["pm release pm-a1b2 --pause"]},"start-task":{why:"Lifecycle alias that claims an item and sets status to in_progress.",examples:['pm start-task pm-a1b2 --message "Start implementation"']},"pause-task":{why:"Lifecycle alias that sets status to open and releases active assignment.",examples:['pm pause-task pm-a1b2 --message "Pause for dependency unblock"']},"close-task":{why:"Lifecycle alias that closes with reason text and clears assignment metadata.",examples:['pm close-task pm-a1b2 "All acceptance criteria met" --message "Close and handoff"']},meet:{why:"Shortcut to create a Meeting from friendly time flags (start/duration) without structured --event CSV.",examples:['pm meet "Sprint Planning" --start +1h --duration 1h','pm meet "1:1" --start 2026-07-01T15:00:00Z --end 2026-07-01T15:30:00Z --location "Room A"'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},event:{why:"Shortcut to create an Event from friendly time flags (start/duration) without structured --event CSV.",examples:['pm event "Release v2" --start 2026-07-01T10:00:00Z --duration 2h','pm event "Conference" --start 2026-08-01 --all-day'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},remind:{why:"Shortcut to create a Reminder from a single point in time without structured --reminder CSV.",examples:['pm remind "Review PR" --at +2d','pm remind "Follow up" --at 2026-07-01T09:00:00Z --text "Ping the team"'],tips:["The reminder time defaults to +1d and the reminder text defaults to the title."]},completion:{why:"Generates shell completion scripts for faster and more reliable command entry.",examples:["pm completion bash","pm completion zsh","pm completion fish","pm completion bash --eager-tags"],tips:["Default scripts resolve tag suggestions lazily at completion time; use --eager-tags to embed current tags directly."]},contracts:{why:"Exposes machine-readable CLI command and tool schema contracts for agent integrations.",examples:["pm contracts","pm contracts --command list --runtime-only","pm contracts --command update --flags-only","pm contracts --availability-only --runtime-only","pm contracts --action create","pm contracts --schema-only"],tips:["Use --command to narrow actions/schema to one CLI surface; combine with --flags-only or --availability-only for lighter payloads."]}};for(const{alias,canonical}of PM_RELOCATED_COMMAND_ALIASES){const bundle=HELP_BY_COMMAND_PATH[alias];bundle&&(HELP_BY_COMMAND_PATH[canonical]={...bundle,examples:bundle.examples.map(example=>example.replace(`pm ${alias}`,`pm ${canonical}`))})}const ROOT_HELP_BUNDLE={why:"Provides deterministic project management workflows for humans and coding agents.",examples:["pm init","pm install guide-shell --project","pm list-open --limit 10",'pm create --title "..." --description "..." --type Task --status open --priority 1 --message "..." --create-mode progressive'],tips:["Use <command> --help for command-specific guidance and examples.","Install guide-shell before using pm guide for local docs and skills routing.","Use --json for machine parsing and integration flows.","Use --no-pager to force direct help output in CI and other non-interactive shells."]},deprecatedHelpAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(entry=>entry.lifecycle==="deprecated");for(const contract of deprecatedHelpAliases){const bundle=HELP_BY_COMMAND_PATH[contract.alias];HELP_BY_COMMAND_PATH[contract.alias]={...bundle,why:`Deprecated: use pm ${contract.canonical_argv.join(" ")}. ${bundle.why}`}}for(const bundle of[ROOT_HELP_BUNDLE,...Object.values(HELP_BY_COMMAND_PATH)])bundle.examples=bundle.examples.map(example=>{for(const contract of deprecatedHelpAliases){const alias=contract.alias.replace(/[.*+?^${}()|[\]\\]/g,"\\$&");example=example.replaceAll(new RegExp(`\\bpm ${alias}(?![\\w-])`,"g"),`pm ${contract.canonical_argv.join(" ")}`)}return example});function resolveCanonicalHelpPath(commandPath){const normalized=normalizeHelpCommandPath(commandPath??"");return normalized?HELP_PATH_ALIASES[normalized]??normalized:""}function resolveHelpBundleForPath(commandPath){const canonicalPath=resolveCanonicalHelpPath(commandPath);return canonicalPath?HELP_BY_COMMAND_PATH[canonicalPath]??ROOT_HELP_BUNDLE:ROOT_HELP_BUNDLE}function resolveHelpNarrative(commandPath,detailMode){const bundle=resolveHelpBundleForPath(commandPath);return{intent:bundle.why,examples:detailMode==="detailed"?[...bundle.examples]:firstExampleOrEmpty(bundle.examples),tips:detailMode==="detailed"?[...bundle.tips??[]]:[],detail_mode:detailMode}}function renderFullCommandAliasHelp(){const permanentAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="permanent"),deprecatedAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="deprecated");return["","Command aliases:",...permanentAliases.map(({alias,canonical_argv:canonicalArgv})=>`  ${alias} -> pm ${canonicalArgv.join(" ")}`),"","Deprecated aliases:",...deprecatedAliases.map(contract=>`  ${contract.alias} -> pm ${contract.canonical_argv.join(" ")} (${renderPmCommandAliasMigrationHint(contract)})`)].join(`
+`)}function configureTieredHelpVisibility(program,baselineHelp,fullDiscovery,selectedRootCommands){const coreOptions=new Set(PM_CORE_HELP_OPTION_FLAGS);program.configureHelp({visibleCommands(command){const visible=baselineHelp.visibleCommands(command);return fullDiscovery?visible.filter(candidate=>(getPmCommandHelpVisibilityTier(candidate)??resolvePmCommandVisibilityTier(candidate.name()))!=="internal"):command!==program?visible:visible.filter(candidate=>selectedRootCommands.has(candidate))},visibleOptions(command){const visible=baselineHelp.visibleOptions(command);return command!==program||fullDiscovery?visible:visible.filter(option=>coreOptions.has(option.flags))}})}function selectBudgetedRootCommands(program,baselineHelp,selectedRootCommands,rootHelpText){const coreCommands=new Set(listPmCommandsForTier("core")),budgetHelp=program.createHelp();budgetHelp.prepareContext({error:!1,helpWidth:80,outputHasColors:!1});const renderBudgetHelp=()=>`${budgetHelp.formatHelp(program,budgetHelp)}${rootHelpText}
+`,rootCandidates=baselineHelp.visibleCommands(program);for(const candidate of rootCandidates)getPmCommandHelpVisibilityTier(candidate)===void 0&&(candidate.name()==="help"||coreCommands.has(candidate.name()))&&selectedRootCommands.add(candidate);for(const candidate of rootCandidates)getPmCommandHelpVisibilityTier(candidate)==="core"&&(selectedRootCommands.add(candidate),measurePmCoreHelp(renderBudgetHelp()).within_budget||selectedRootCommands.delete(candidate))}function attachRichHelpText(program,argv=process.argv.slice(2)){const baselineHelp=program.createHelp(),fullDiscovery=isFullHelpDiscovery(argv),selectedRootCommands=new Set;configureTieredHelpVisibility(program,baselineHelp,fullDiscovery,selectedRootCommands);const detailMode=resolveHelpDetailMode(argv),rootHelpText=renderHelpBundle(ROOT_HELP_BUNDLE,detailMode);program.addHelpText("after",rootHelpText),fullDiscovery&&program.addHelpText("after",renderFullCommandAliasHelp()),selectBudgetedRootCommands(program,baselineHelp,selectedRootCommands,rootHelpText);for(const[commandPath,bundle]of Object.entries(HELP_BY_COMMAND_PATH))attachBundleByPath(program,commandPath,bundle,detailMode);const requestedPath=normalizeHelpCommandPath(parseBootstrapHelpRequest(argv).commandPathTokens.join(" ")),positionalAction=resolvePmPositionalActionContract(requestedPath);if(positionalAction){attachBundleByPath(program,positionalAction.parent,{why:positionalAction.description,examples:[positionalAction.example],tips:[`Action path: pm ${positionalAction.command}`,formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]},detailMode);return}const positionalActions=PM_POSITIONAL_ACTION_CONTRACTS.filter(({parent})=>parent===requestedPath);positionalActions.length>0&&attachBundleByPath(program,requestedPath,{why:`Dispatches one declared positional action: ${positionalActions.map(({action})=>action).join("|")}.`,examples:positionalActions.map(({example})=>example),tips:[`Inspect one action directly with pm ${requestedPath} <action> --help --json.`]},detailMode)}const _testOnly={renderCompactHelpBundle,renderDetailedHelpBundle};export{ROOT_HELP_BUNDLE,_testOnly,attachRichHelpText,firstExampleOrEmpty,getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,resolveHelpBundleForPath,resolveHelpDetailMode,resolveHelpNarrative,setPmCommandHelpVisibilityTier};
 //# sourceMappingURL=help-content.js.map

package/dist/cli/help-json-payload.js

@@ -1,5 +1,8 @@
-!(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]="6fa59b21-fcd4-5056-ae4c-379d57bb7757")}catch(e2){}})();import{hasSubcommandFlagContractsForCommand,PM_COMMAND_ALIAS_CONTRACTS,PM_CORE_COMMAND_NAMES,resolvePmCommandAlias,resolvePmCommandOperation}from"../sdk/cli-contracts.js";import{commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveTypeDefinition,EXIT_CODE,writeStderr,writeStdout}from"../sdk/runtime-primitives.js";import{buildDynamicExtensionHelpOptionSummaries,mergeHelpOptionSummaries,findCommandByPath,findDirectChildCommand,commandAliases}from"./extension-command-help.js";import{getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,resolveHelpBundleForPath,resolveHelpDetailMode,resolveHelpNarrative,ROOT_HELP_BUNDLE}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{parseBootstrapGlobalOptions,parseBootstrapHelpRequest,parseBootstrapCommandName,parseBootstrapTypeValue}from"./bootstrap-args.js";import{extractProvidedOptionFlags,renderPmCommand}from"./argv-utils.js";import{formatCommanderErrorForJson}from"./error-guidance.js";import{BUILTIN_TYPE_HELP_VALUES,buildUnknownCommandGuidanceFromRuntime,isKnownHelpCommandPath}from"./commander-usage.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{resolveCreateExplicitEmptyFlag}from"../sdk/agent/create-option-policy.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{resolvePmCommandCapabilityFamily,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";const EXTENSION_TIER_ORDER={core:0,standard:1,full:2,internal:3};function resolveExtensionCommandSurface(commandPath,descriptors,allowDescendants=true){const exact=descriptors.get(resolvePmCommandOperation(commandPath));if(exact)return exact;if(!allowDescendants)return void 0;const descendants=[...descriptors.entries()].filter(([path])=>path.startsWith(`${commandPath} `)).map(([,descriptor])=>descriptor);if(descendants.length===0)return void 0;const tier=descendants.reduce((selected,descriptor)=>EXTENSION_TIER_ORDER[descriptor.tier]<EXTENSION_TIER_ORDER[selected]?descriptor.tier:selected,"internal");const families=new Set(descendants.map(({family})=>family));return{tier,family:families.size===1?descendants[0].family:"extensions"}}function resolveCommandFromPathTokens(root,pathTokens){if(pathTokens.length===0){return root}const exactCommand=findCommandByPath(root,pathTokens);if(exactCommand){return exactCommand}const requestedPath=pathTokens.join(" ");if(resolvePmCommandOperation(requestedPath)!==requestedPath)return null;if(!PM_CORE_COMMAND_NAMES.some(commandName=>commandName===requestedPath)&&!hasSubcommandFlagContractsForCommand(requestedPath)&&!resolvePmPositionalActionContract(requestedPath)&&!isKnownHelpCommandPath(root,pathTokens)){return null}for(let length=pathTokens.length-1;length>0;length-=1){const positionalParent=findCommandByPath(root,pathTokens.slice(0,length));if(positionalParent){return positionalParent}}return pathTokens.length===1?root:null}function extractOptionValueName(flags){const match=flags.match(/[<[]([^>\]]+)[>\]]/);if(!match){return null}const value=match[1]?.trim();return value&&value.length>0?value:null}function readOptionAttributeName(option){const optionRecord=option;if(typeof optionRecord.attributeName==="function"){const value=optionRecord.attributeName();return typeof value==="string"&&value.trim().length>0?value.trim():null}if(typeof optionRecord.attributeName==="string"&&optionRecord.attributeName.trim().length>0){return optionRecord.attributeName.trim()}return null}function buildOptionAliasMap(options){const aliasMap=new Map;for(const option of options){const optionRecord=option;const attributeName=readOptionAttributeName(option);if(!attributeName||typeof optionRecord.long!=="string"||optionRecord.long.trim().length===0){continue}const existing=aliasMap.get(attributeName)??[];existing.push(optionRecord.long.trim());aliasMap.set(attributeName,existing)}for(const[attributeName,values]of aliasMap.entries()){aliasMap.set(attributeName,[...new Set(values.map(value=>value.trim()).filter(value=>value.length>0))].sort((left,right)=>left.localeCompare(right)))}return aliasMap}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function buildHelpOptionSummaries(command){const options=command.options??[];const optionAliasMap=buildOptionAliasMap(options);return options.map(option=>{const optionRecord=option;const flags=typeof optionRecord.flags==="string"?optionRecord.flags.trim():"";const description=typeof optionRecord.description==="string"?optionRecord.description.trim():"";const attributeName=readOptionAttributeName(option);const aliasCandidates=attributeName?optionAliasMap.get(attributeName)??[]:[];const aliases=aliasCandidates.filter(entry=>entry!==optionRecord.long).map(entry=>entry.trim()).filter(entry=>entry.length>0);const aliasForMatch=description.match(/^Alias for ([^ ]+)/i);const aliasFor=aliasForMatch&&aliasForMatch[1]?aliasForMatch[1].trim():null;const required=optionRecord.mandatory===true||description.includes("[required]")||description.toLowerCase().includes("required;");const valueRequired=flags.includes("<");const takesValue=valueRequired||flags.includes("[");const summary={flags,long:typeof optionRecord.long==="string"?optionRecord.long:null,short:typeof optionRecord.short==="string"?optionRecord.short:null,description,takes_value:takesValue,value_required:valueRequired,value_name:extractOptionValueName(flags),variadic:optionRecord.variadic===true,required,aliases,alias_for:aliasFor};if(optionRecord.defaultValue!==void 0){summary.default_value=optionRecord.defaultValue}return summary})}function compactHelpOptionAliases(options){const canonicalByLong=new Map;const aliasOptions=[];for(const option of options){if(option.alias_for&&option.long){aliasOptions.push(option);continue}if(option.long){canonicalByLong.set(option.long,option)}}for(const aliasOption of aliasOptions){const aliasFor=aliasOption.alias_for;const canonical=canonicalByLong.get(aliasFor);if(!canonical){continue}const aliasLong=aliasOption.long;const aliases=new Set([...canonical.aliases??[],aliasLong]);canonical.aliases=[...aliases].sort((left,right)=>left.localeCompare(right))}return options.filter(option=>{if(!option.alias_for||!option.long){return true}return!canonicalByLong.has(option.alias_for)})}function buildHelpArgumentSummaries(command){const commandRecord=command;const argumentsList=Array.isArray(commandRecord.registeredArguments)?commandRecord.registeredArguments:Array.isArray(commandRecord._args)?commandRecord._args:[];return argumentsList.map(argument=>{const rawName=typeof argument.name==="function"?argument.name():typeof argument.name==="string"?argument.name:"argument";const description=typeof argument.description==="string"&&argument.description.trim().length>0?argument.description.trim():null;return{name:rawName.trim(),required:argument.required===true||description?.toLowerCase().startsWith("required;")===true,variadic:argument.variadic===true,description}})}function buildHelpSubcommandSummaries(command,extensionDescriptors=new Map,includeAll=false){const visible=command.createHelp().visibleCommands(command);const candidates=includeAll?[...new Set([...visible,...command.commands])]:visible;return candidates.filter(entry=>entry.name()!=="help"||command.parent===null).filter(entry=>!includeAll||(getPmCommandHelpVisibilityTier(entry)??resolvePmCommandVisibilityTier(entry.name()))!=="internal").map(entry=>{const commandPath=normalizeHelpCommandPath(getCommandPath(entry));const rootCommand=commandPath;const declaredTier=getPmCommandHelpVisibilityTier(entry);const extensionDescriptor=resolveExtensionCommandSurface(commandPath,extensionDescriptors,declaredTier!==void 0);const aliasContract=PM_COMMAND_ALIAS_CONTRACTS.find(({alias})=>alias===commandPath);return{name:entry.name().trim(),aliases:commandAliases(entry),description:entry.description().trim(),tier:extensionDescriptor?.tier??declaredTier??resolvePmCommandVisibilityTier(rootCommand),family:extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommand),...aliasContract?{alias_for:aliasContract.canonical,alias_lifecycle:aliasContract.lifecycle,...aliasContract.lifecycle==="deprecated"?{deprecated:true}:{}}:{}}}).sort((left,right)=>left.name.localeCompare(right.name))}function buildJsonHelpNarrative(detailMode,fallbackNarrative,extensionDescriptor){if(!extensionDescriptor){return fallbackNarrative}const extensionExamples=extensionDescriptor.examples??[];const extensionFailureHints=extensionDescriptor.failure_hints??[];return{intent:extensionDescriptor.intent??extensionDescriptor.description??fallbackNarrative.intent,examples:detailMode==="detailed"?extensionExamples.length>0?[...extensionExamples]:[...fallbackNarrative.examples]:extensionExamples.length>0?[extensionExamples[0]]:[...fallbackNarrative.examples],tips:detailMode==="detailed"?extensionFailureHints.length>0?[...extensionFailureHints]:[...fallbackNarrative.tips]:[],detail_mode:detailMode}}function resolveJsonHelpNarrative(commandPath,commandDescription,detailMode,extensionDescriptor,hasPositionalAction){const isRootFallback=commandPath!==void 0&&resolveHelpBundleForPath(commandPath)===ROOT_HELP_BUNDLE;const fallback=isRootFallback?{intent:commandDescription,examples:[`pm ${commandPath} --help`],tips:[],detail_mode:detailMode}:resolveHelpNarrative(commandPath,detailMode);const intentSource=hasPositionalAction?"positional_action":extensionDescriptor?.intent||extensionDescriptor?.description?"extension":isRootFallback?commandDescription?"command_description":"unavailable":commandPath?"help_bundle":"root_help_bundle";return{narrative:buildJsonHelpNarrative(detailMode,fallback,extensionDescriptor),intentSource}}function resolveJsonHelpVisibilityTier(rootCommandPath,extensionDescriptor){if(rootCommandPath===void 0)return null;return extensionDescriptor?.tier??resolvePmCommandVisibilityTier(rootCommandPath)}function resolveJsonHelpCapabilityFamily(rootCommandPath,extensionDescriptor){if(rootCommandPath===void 0)return null;return extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommandPath)}function projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery){if(targetCommand!==rootProgram||!fullDiscovery)return void 0;return PM_COMMAND_ALIAS_CONTRACTS.map(contract=>({alias:contract.alias,canonical:contract.canonical,canonical_argv:[...contract.canonical_argv],available:resolveCommandFromPathTokens(rootProgram,contract.canonical.split(" "))!==null,lifecycle:contract.lifecycle,hidden:contract.hidden,deprecated:contract.lifecycle==="deprecated"}))}function buildPositionalActionHelpProjection(action,targetCommand,resolvedPath,allOptions,extensionDescriptors=new Map,includeAll=false){if(!action){const argumentsList=buildHelpArgumentSummaries(targetCommand);const registeredSubcommands=buildHelpSubcommandSummaries(targetCommand,extensionDescriptors,includeAll);const registeredSubcommandNames=new Set(registeredSubcommands.map(({name})=>name));return{arguments:argumentsList,options:allOptions,subcommands:[...registeredSubcommands,...PM_POSITIONAL_ACTION_CONTRACTS.filter(({parent,action:name})=>parent===resolvedPath&&!registeredSubcommandNames.has(name)).map(({action:name,description})=>({name,aliases:[],description,tier:resolvePmCommandVisibilityTier(resolvedPath.split(" ")[0]),family:resolvePmCommandCapabilityFamily(resolvedPath.split(" ")[0])}))].sort((left,right)=>left.name.localeCompare(right.name)),usage:[resolvedPath,argumentsList.reduce((usage,argument)=>argument.required?usage.replace(`[${argument.name}${argument.variadic?"...":""}]`,`<${argument.name}${argument.variadic?"...":""}>`):usage,targetCommand.usage())].filter(token=>token.length>0).join(" ")}}const acceptedFlags=new Set(action.accepted_flags);return{arguments:action.slots.map(({name,required,variadic,value_kind:valueKind,polymorphic})=>({name,required,variadic,description:polymorphic?`Polymorphic ${valueKind} value; inspect the action contract before mutation.`:`${valueKind.replaceAll("_"," ")} value.`})),options:allOptions.filter(({long,aliases})=>long!==null&&acceptedFlags.has(long)||aliases.some(alias=>acceptedFlags.has(alias))),subcommands:[],usage:[action.command,...action.slots.map(({name,required,variadic})=>{const token=variadic?`${name}...`:name;return required?`<${token}>`:`[${token}]`})].join(" ")}}function buildJsonHelpPayload(rootProgram,targetCommand,argv,requestedPath,extensionDescriptors){const detailMode=resolveHelpDetailMode(argv);const fullDiscovery=isFullHelpDiscovery(argv);const commanderPath=normalizeHelpCommandPath(getCommandPath(targetCommand));const requestedCommandPath=normalizeHelpCommandPath(requestedPath.join(" "));const resolvedPath=requestedCommandPath.length>commanderPath.length?requestedCommandPath:commanderPath;const positionalAction=resolvePmPositionalActionContract(resolvedPath);const projectedPath=positionalAction?.command??commanderPath;const commandPath=projectedPath.length>0?projectedPath:void 0;const rootCommandPath=commandPath;const extensionDescriptor=commandPath?extensionDescriptors.get(resolvePmCommandOperation(commandPath)):void 0;const extensionSurface=commandPath?resolveExtensionCommandSurface(commandPath,extensionDescriptors,getPmCommandHelpVisibilityTier(targetCommand)!==void 0):void 0;const{narrative,intentSource}=resolveJsonHelpNarrative(commandPath,targetCommand.description().trim(),detailMode,extensionDescriptor,positionalAction!==void 0);const allOptionSummaries=compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand),buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));const projection=buildPositionalActionHelpProjection(positionalAction,targetCommand,projectedPath,allOptionSummaries,extensionDescriptors,fullDiscovery);const fullCommandAliases=projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery);return{format:"pm_help_v1",detail_mode:detailMode,root_command:rootProgram.name(),requested_path:requestedPath,resolved_path:projectedPath.length>0?projectedPath:rootProgram.name(),visibility_tier:resolveJsonHelpVisibilityTier(rootCommandPath,extensionSurface),capability_family:resolveJsonHelpCapabilityFamily(rootCommandPath,extensionSurface),description:positionalAction?.description??targetCommand.description(),usage:projection.usage,intent:positionalAction?.description??narrative.intent,intent_source:intentSource,examples:positionalAction?[positionalAction.example]:narrative.examples,tips:positionalAction?[formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]:narrative.tips,arguments:projection.arguments,options:projection.options,subcommands:projection.subcommands,has_subcommands:projection.subcommands.length>0,...fullCommandAliases===void 0?{}:{command_aliases:fullCommandAliases}}}async function maybeRenderBootstrapJsonHelp(rootProgram,argv,extensionDescriptors,requestedArgv=argv){const bootstrapGlobal=parseBootstrapGlobalOptions(argv);if(!bootstrapGlobal.json){return false}const helpRequest=parseBootstrapHelpRequest(argv);if(!helpRequest.requested){return false}const targetCommand=resolveCommandFromPathTokens(rootProgram,helpRequest.commandPathTokens);if(!targetCommand){if(!bootstrapGlobal.quiet){const unknownMessage=`unknown command '${resolvePmCommandOperation(helpRequest.commandPathTokens.join(" "))}'`;const runtimeContext=buildUnknownCommandGuidanceFromRuntime(unknownMessage,rootProgram,extensionDescriptors);const envelope=formatCommanderErrorForJson(unknownMessage,"help",BUILTIN_TYPE_HELP_VALUES,EXIT_CODE.USAGE,{...runtimeContext,attemptedCommand:renderAttemptedCommand(argv),normalizedInvocationArgs:[...argv],providedOptionFlags:extractProvidedOptionFlags(argv)});const output=bootstrapGlobal.tokenAccounting?attachOutputTokenAccounting(envelope,value=>`${JSON.stringify(value,null,2)}
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6bca8bb8-c8f8-5bf5-bd3a-1e3089571238")}catch{}})();import{hasSubcommandFlagContractsForCommand,PM_COMMAND_ALIAS_CONTRACTS,PM_CORE_COMMAND_NAMES,resolvePmCommandAlias,resolvePmCommandOperation}from"../sdk/cli-contracts.js";import{commandOptionFlagLabel,resolveCommandOptionPolicyState,resolveTypeDefinition,EXIT_CODE,writeStderr,writeStdout}from"../sdk/runtime-primitives.js";import{buildDynamicExtensionHelpOptionSummaries,mergeHelpOptionSummaries,findCommandByPath,findDirectChildCommand,commandAliases}from"./extension-command-help.js";import{getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,resolveHelpBundleForPath,resolveHelpDetailMode,resolveHelpNarrative,ROOT_HELP_BUNDLE}from"./help-content.js";import{getCommandPath}from"./registration-helpers.js";import{parseBootstrapGlobalOptions,parseBootstrapHelpRequest,parseBootstrapCommandName,parseBootstrapTypeValue}from"./bootstrap-args.js";import{extractProvidedOptionFlags,renderPmCommand}from"./argv-utils.js";import{formatCommanderErrorForJson}from"./error-guidance.js";import{BUILTIN_TYPE_HELP_VALUES,buildUnknownCommandGuidanceFromRuntime,isKnownHelpCommandPath}from"./commander-usage.js";import{attachOutputTokenAccounting}from"../sdk/output-token-accounting.js";import{resolveCreateExplicitEmptyFlag}from"../sdk/agent/create-option-policy.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{resolvePmCommandCapabilityFamily,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";const EXTENSION_TIER_ORDER={core:0,standard:1,full:2,internal:3};function resolveExtensionCommandSurface(commandPath,descriptors,allowDescendants=!0){const exact=descriptors.get(resolvePmCommandOperation(commandPath));if(exact)return exact;if(!allowDescendants)return;const descendants=[...descriptors.entries()].filter(([path])=>path.startsWith(`${commandPath} `)).map(([,descriptor])=>descriptor);if(descendants.length===0)return;const tier=descendants.reduce((selected,descriptor)=>EXTENSION_TIER_ORDER[descriptor.tier]<EXTENSION_TIER_ORDER[selected]?descriptor.tier:selected,"internal"),families=new Set(descendants.map(({family})=>family));return{tier,family:families.size===1?descendants[0].family:"extensions"}}function resolveCommandFromPathTokens(root,pathTokens){if(pathTokens.length===0)return root;const exactCommand=findCommandByPath(root,pathTokens);if(exactCommand)return exactCommand;const requestedPath=pathTokens.join(" ");if(resolvePmCommandOperation(requestedPath)!==requestedPath||!PM_CORE_COMMAND_NAMES.some(commandName=>commandName===requestedPath)&&!hasSubcommandFlagContractsForCommand(requestedPath)&&!resolvePmPositionalActionContract(requestedPath)&&!isKnownHelpCommandPath(root,pathTokens))return null;for(let length=pathTokens.length-1;length>0;length-=1){const positionalParent=findCommandByPath(root,pathTokens.slice(0,length));if(positionalParent)return positionalParent}return pathTokens.length===1?root:null}function extractOptionValueName(flags){const match=flags.match(/[<[]([^>\]]+)[>\]]/);if(!match)return null;const value=match[1]?.trim();return value&&value.length>0?value:null}function readOptionAttributeName(option){const optionRecord=option;if(typeof optionRecord.attributeName=="function"){const value=optionRecord.attributeName();return typeof value=="string"&&value.trim().length>0?value.trim():null}return typeof optionRecord.attributeName=="string"&&optionRecord.attributeName.trim().length>0?optionRecord.attributeName.trim():null}function buildOptionAliasMap(options){const aliasMap=new Map;for(const option of options){const optionRecord=option,attributeName=readOptionAttributeName(option);if(!attributeName||typeof optionRecord.long!="string"||optionRecord.long.trim().length===0)continue;const existing=aliasMap.get(attributeName)??[];existing.push(optionRecord.long.trim()),aliasMap.set(attributeName,existing)}for(const[attributeName,values]of aliasMap.entries())aliasMap.set(attributeName,[...new Set(values.map(value=>value.trim()).filter(value=>value.length>0))].sort((left,right)=>left.localeCompare(right)));return aliasMap}function renderAttemptedCommand(argv){return renderPmCommand(argv)}function buildHelpOptionSummaries(command){const options=command.options??[],optionAliasMap=buildOptionAliasMap(options);return options.map(option=>{const optionRecord=option,flags=typeof optionRecord.flags=="string"?optionRecord.flags.trim():"",description=typeof optionRecord.description=="string"?optionRecord.description.trim():"",attributeName=readOptionAttributeName(option),aliases=(attributeName?optionAliasMap.get(attributeName)??[]:[]).filter(entry=>entry!==optionRecord.long).map(entry=>entry.trim()).filter(entry=>entry.length>0),aliasForMatch=description.match(/^Alias for ([^ ]+)/i),aliasFor=aliasForMatch&&aliasForMatch[1]?aliasForMatch[1].trim():null,required=optionRecord.mandatory===!0||description.includes("[required]")||description.toLowerCase().includes("required;"),valueRequired=flags.includes("<"),takesValue=valueRequired||flags.includes("["),summary={flags,long:typeof optionRecord.long=="string"?optionRecord.long:null,short:typeof optionRecord.short=="string"?optionRecord.short:null,description,takes_value:takesValue,value_required:valueRequired,value_name:extractOptionValueName(flags),variadic:optionRecord.variadic===!0,required,aliases,alias_for:aliasFor};return optionRecord.defaultValue!==void 0&&(summary.default_value=optionRecord.defaultValue),summary})}function compactHelpOptionAliases(options){const canonicalByLong=new Map,aliasOptions=[];for(const option of options){if(option.alias_for&&option.long){aliasOptions.push(option);continue}option.long&&canonicalByLong.set(option.long,option)}for(const aliasOption of aliasOptions){const aliasFor=aliasOption.alias_for,canonical=canonicalByLong.get(aliasFor);if(!canonical)continue;const aliasLong=aliasOption.long,aliases=new Set([...canonical.aliases??[],aliasLong]);canonical.aliases=[...aliases].sort((left,right)=>left.localeCompare(right))}return options.filter(option=>!option.alias_for||!option.long?!0:!canonicalByLong.has(option.alias_for))}function buildHelpArgumentSummaries(command){const commandRecord=command;return(Array.isArray(commandRecord.registeredArguments)?commandRecord.registeredArguments:Array.isArray(commandRecord._args)?commandRecord._args:[]).map(argument=>{const rawName=typeof argument.name=="function"?argument.name():typeof argument.name=="string"?argument.name:"argument",description=typeof argument.description=="string"&&argument.description.trim().length>0?argument.description.trim():null;return{name:rawName.trim(),required:argument.required===!0||description?.toLowerCase().startsWith("required;")===!0,variadic:argument.variadic===!0,description}})}function buildHelpSubcommandSummaries(command,extensionDescriptors=new Map,includeAll=!1){const visible=command.createHelp().visibleCommands(command);return(includeAll?[...new Set([...visible,...command.commands])]:visible).filter(entry=>entry.name()!=="help"||command.parent===null).filter(entry=>!includeAll||(getPmCommandHelpVisibilityTier(entry)??resolvePmCommandVisibilityTier(entry.name()))!=="internal").map(entry=>{const commandPath=normalizeHelpCommandPath(getCommandPath(entry)),rootCommand=commandPath,declaredTier=getPmCommandHelpVisibilityTier(entry),extensionDescriptor=resolveExtensionCommandSurface(commandPath,extensionDescriptors,declaredTier!==void 0),aliasContract=PM_COMMAND_ALIAS_CONTRACTS.find(({alias})=>alias===commandPath);return{name:entry.name().trim(),aliases:commandAliases(entry),description:entry.description().trim(),tier:extensionDescriptor?.tier??declaredTier??resolvePmCommandVisibilityTier(rootCommand),family:extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommand),...aliasContract?{alias_for:aliasContract.canonical,alias_lifecycle:aliasContract.lifecycle,...aliasContract.lifecycle==="deprecated"?{deprecated:!0}:{}}:{}}}).sort((left,right)=>left.name.localeCompare(right.name))}function buildJsonHelpNarrative(detailMode,fallbackNarrative,extensionDescriptor){if(!extensionDescriptor)return fallbackNarrative;const extensionExamples=extensionDescriptor.examples??[],extensionFailureHints=extensionDescriptor.failure_hints??[];return{intent:extensionDescriptor.intent??extensionDescriptor.description??fallbackNarrative.intent,examples:detailMode==="detailed"?extensionExamples.length>0?[...extensionExamples]:[...fallbackNarrative.examples]:extensionExamples.length>0?[extensionExamples[0]]:[...fallbackNarrative.examples],tips:detailMode==="detailed"?extensionFailureHints.length>0?[...extensionFailureHints]:[...fallbackNarrative.tips]:[],detail_mode:detailMode}}function resolveJsonHelpNarrative(commandPath,commandDescription,detailMode,extensionDescriptor,hasPositionalAction){const isRootFallback=commandPath!==void 0&&resolveHelpBundleForPath(commandPath)===ROOT_HELP_BUNDLE,fallback=isRootFallback?{intent:commandDescription,examples:[`pm ${commandPath} --help`],tips:[],detail_mode:detailMode}:resolveHelpNarrative(commandPath,detailMode),intentSource=hasPositionalAction?"positional_action":extensionDescriptor?.intent||extensionDescriptor?.description?"extension":isRootFallback?commandDescription?"command_description":"unavailable":commandPath?"help_bundle":"root_help_bundle";return{narrative:buildJsonHelpNarrative(detailMode,fallback,extensionDescriptor),intentSource}}function resolveJsonHelpVisibilityTier(rootCommandPath,extensionDescriptor){return rootCommandPath===void 0?null:extensionDescriptor?.tier??resolvePmCommandVisibilityTier(rootCommandPath)}function resolveJsonHelpCapabilityFamily(rootCommandPath,extensionDescriptor){return rootCommandPath===void 0?null:extensionDescriptor?.family??resolvePmCommandCapabilityFamily(rootCommandPath)}function projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery){if(!(targetCommand!==rootProgram||!fullDiscovery))return PM_COMMAND_ALIAS_CONTRACTS.map(contract=>({alias:contract.alias,canonical:contract.canonical,canonical_argv:[...contract.canonical_argv],available:resolveCommandFromPathTokens(rootProgram,contract.canonical.split(" "))!==null,lifecycle:contract.lifecycle,hidden:contract.hidden,deprecated:contract.lifecycle==="deprecated"}))}function buildPositionalActionHelpProjection(action,targetCommand,resolvedPath,allOptions,extensionDescriptors=new Map,includeAll=!1){if(!action){const argumentsList=buildHelpArgumentSummaries(targetCommand),registeredSubcommands=buildHelpSubcommandSummaries(targetCommand,extensionDescriptors,includeAll),registeredSubcommandNames=new Set(registeredSubcommands.map(({name})=>name));return{arguments:argumentsList,options:allOptions,subcommands:[...registeredSubcommands,...PM_POSITIONAL_ACTION_CONTRACTS.filter(({parent,action:name})=>parent===resolvedPath&&!registeredSubcommandNames.has(name)).map(({action:name,description})=>({name,aliases:[],description,tier:resolvePmCommandVisibilityTier(resolvedPath.split(" ")[0]),family:resolvePmCommandCapabilityFamily(resolvedPath.split(" ")[0])}))].sort((left,right)=>left.name.localeCompare(right.name)),usage:[resolvedPath,argumentsList.reduce((usage,argument)=>argument.required?usage.replace(`[${argument.name}${argument.variadic?"...":""}]`,`<${argument.name}${argument.variadic?"...":""}>`):usage,targetCommand.usage())].filter(token=>token.length>0).join(" ")}}const acceptedFlags=new Set(action.accepted_flags);return{arguments:action.slots.map(({name,required,variadic,value_kind:valueKind,polymorphic})=>({name,required,variadic,description:polymorphic?`Polymorphic ${valueKind} value; inspect the action contract before mutation.`:`${valueKind.replaceAll("_"," ")} value.`})),options:allOptions.filter(({long,aliases})=>long!==null&&acceptedFlags.has(long)||aliases.some(alias=>acceptedFlags.has(alias))),subcommands:[],usage:[action.command,...action.slots.map(({name,required,variadic})=>{const token=variadic?`${name}...`:name;return required?`<${token}>`:`[${token}]`})].join(" ")}}function buildJsonHelpPayload(rootProgram,targetCommand,argv,requestedPath,extensionDescriptors){const detailMode=resolveHelpDetailMode(argv),fullDiscovery=isFullHelpDiscovery(argv),commanderPath=normalizeHelpCommandPath(getCommandPath(targetCommand)),requestedCommandPath=normalizeHelpCommandPath(requestedPath.join(" ")),resolvedPath=requestedCommandPath.length>commanderPath.length?requestedCommandPath:commanderPath,positionalAction=resolvePmPositionalActionContract(resolvedPath),projectedPath=positionalAction?.command??commanderPath,commandPath=projectedPath.length>0?projectedPath:void 0,rootCommandPath=commandPath,extensionDescriptor=commandPath?extensionDescriptors.get(resolvePmCommandOperation(commandPath)):void 0,extensionSurface=commandPath?resolveExtensionCommandSurface(commandPath,extensionDescriptors,getPmCommandHelpVisibilityTier(targetCommand)!==void 0):void 0,{narrative,intentSource}=resolveJsonHelpNarrative(commandPath,targetCommand.description().trim(),detailMode,extensionDescriptor,positionalAction!==void 0),allOptionSummaries=compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand),buildDynamicExtensionHelpOptionSummaries(extensionDescriptor))),projection=buildPositionalActionHelpProjection(positionalAction,targetCommand,projectedPath,allOptionSummaries,extensionDescriptors,fullDiscovery),fullCommandAliases=projectFullCommandAliases(rootProgram,targetCommand,fullDiscovery);return{format:"pm_help_v1",detail_mode:detailMode,root_command:rootProgram.name(),requested_path:requestedPath,resolved_path:projectedPath.length>0?projectedPath:rootProgram.name(),visibility_tier:resolveJsonHelpVisibilityTier(rootCommandPath,extensionSurface),capability_family:resolveJsonHelpCapabilityFamily(rootCommandPath,extensionSurface),description:positionalAction?.description??targetCommand.description(),usage:projection.usage,intent:positionalAction?.description??narrative.intent,intent_source:intentSource,examples:positionalAction?[positionalAction.example]:narrative.examples,tips:positionalAction?[formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]:narrative.tips,arguments:projection.arguments,options:projection.options,subcommands:projection.subcommands,has_subcommands:projection.subcommands.length>0,...fullCommandAliases===void 0?{}:{command_aliases:fullCommandAliases}}}async function maybeRenderBootstrapJsonHelp(rootProgram,argv,extensionDescriptors,requestedArgv=argv){const bootstrapGlobal=parseBootstrapGlobalOptions(argv);if(!bootstrapGlobal.json)return!1;const helpRequest=parseBootstrapHelpRequest(argv);if(!helpRequest.requested)return!1;const targetCommand=resolveCommandFromPathTokens(rootProgram,helpRequest.commandPathTokens);if(!targetCommand){if(!bootstrapGlobal.quiet){const unknownMessage=`unknown command '${resolvePmCommandOperation(helpRequest.commandPathTokens.join(" "))}'`,runtimeContext=buildUnknownCommandGuidanceFromRuntime(unknownMessage,rootProgram,extensionDescriptors),envelope=formatCommanderErrorForJson(unknownMessage,"help",BUILTIN_TYPE_HELP_VALUES,EXIT_CODE.USAGE,{...runtimeContext,attemptedCommand:renderAttemptedCommand(argv),normalizedInvocationArgs:[...argv],providedOptionFlags:extractProvidedOptionFlags(argv)}),output=bootstrapGlobal.tokenAccounting?attachOutputTokenAccounting(envelope,value=>`${JSON.stringify(value,null,2)}
 `):envelope;writeStderr(`${JSON.stringify(output,null,2)}
-`)}process.exitCode=EXIT_CODE.USAGE;return true}if(!bootstrapGlobal.quiet){const payload=buildJsonHelpPayload(rootProgram,targetCommand,argv,helpRequest.commandPathTokens,extensionDescriptors);const originalPath=parseBootstrapHelpRequest(requestedArgv).commandPathTokens;payload.requested_path=originalPath;const alias=resolvePmCommandAlias(originalPath.join(" "));if(alias)payload.resolved_path=alias.canonical;if(targetCommand===rootProgram&&!isFullHelpDiscovery(argv)){payload.omission_receipt={has_omissions:true,omitted_field_group_count:1,omitted_field_groups:[{name:"command_aliases",restore_with:"--all"}]}}writeStdout(`${JSON.stringify(payload,null,2)}
-`)}process.exitCode=EXIT_CODE.SUCCESS;return true}function buildCreateUpdatePolicyIntro(commandName,typeRegistry){const lines=["","Type-aware option policies:","  pass --type <value> with --help to render required/disabled/hidden option policy details for that type.",`  active type values: ${typeRegistry.types.join("|")}`];if(commandName==="create"){lines.push("  scheduling shortcut: use --schedule-preset lightweight for Reminder/Meeting/Event minimal create flows.")}return lines.join("\n")}function appendTypeOptionHelpLines(lines,typeDefinition){if(typeDefinition.options.length===0){lines.push("  type options: none");return}lines.push("  type options:");for(const option of typeDefinition.options){const requiredLabel=option.required?" (required)":"";const aliases=option.aliases??[];lines.push(`    - ${option.key}${requiredLabel}`);lines.push(`      values: ${option.values.length>0?option.values.join("|"):"any non-empty string"}`);lines.push(`      aliases: ${aliases.length>0?aliases.join("|"):"none"}`);if(option.description&&option.description.trim().length>0){lines.push(`      description: ${option.description.trim()}`)}}}function buildCreatePolicyRequiredSets(commandName,typeDefinition){const progressive=commandName==="create"?new Set(["title","type"]):new Set;const strict=new Set(progressive);if(commandName==="create"){for(const option of[...typeDefinition.required_create_fields,...typeDefinition.required_create_repeatables]){strict.add(option)}}return{progressive,strict}}function appendStrictCreatePolicyHelpLines(lines,typeDefinition,progressiveRequired,strictRequired){const progressive=new Set(progressiveRequired);const strictOnly=strictRequired.filter(option=>!progressive.has(option));const toFlags=options=>options.length>0?options.map(option=>commandOptionFlagLabel("create",option)).join(", "):"none";lines.push(`  required in strict mode: ${toFlags(strictOnly)}`);const explicitEmptyFlags=strictOnly.map(resolveCreateExplicitEmptyFlag).filter(flag=>flag!==void 0);lines.push(`  explicit empty assertion: ${explicitEmptyFlags.length>0?explicitEmptyFlags.join(", "):"none"}`);if(["Reminder","Meeting","Event"].includes(typeDefinition.name)){lines.push("  schedule preset: --schedule-preset lightweight switches schedule artifacts to progressive required-option policy.");lines.push("  strict parity remains available via --create-mode strict.")}}function buildCreateUpdatePolicyHelpText(commandName,typeRegistry,argv){const selectedTypeRaw=parseBootstrapTypeValue(argv);if(!selectedTypeRaw){return buildCreateUpdatePolicyIntro(commandName,typeRegistry)}const typeDefinition=resolveTypeDefinition(selectedTypeRaw,typeRegistry);if(!typeDefinition){const allowed=typeRegistry.types.join("|");return["",`Type-aware option policies: type "${selectedTypeRaw}" is not in the active registry.`,`  active type values: ${allowed}`].join("\n")}const argumentTerminatorIndex=argv.indexOf("--");const optionArgv=argumentTerminatorIndex<0?argv:argv.slice(0,argumentTerminatorIndex);const createModeTokenIndex=optionArgv.findIndex(token=>token==="--create-mode"||token.startsWith("--create-mode="));const createModeToken=createModeTokenIndex<0?void 0:optionArgv[createModeTokenIndex]?.startsWith("--create-mode=")?optionArgv[createModeTokenIndex]?.slice("--create-mode=".length):optionArgv[createModeTokenIndex+1];const strictCreateMode=commandName==="create"&&createModeToken?.toLowerCase()==="strict";const requiredSets=buildCreatePolicyRequiredSets(commandName,typeDefinition);const progressivePolicyState=resolveCommandOptionPolicyState(typeDefinition,commandName,requiredSets.progressive);const policyState=resolveCommandOptionPolicyState(typeDefinition,commandName,strictCreateMode?requiredSets.strict:requiredSets.progressive);const toFlags=options=>options.length>0?options.map(option=>commandOptionFlagLabel(commandName,option)).join(", "):"none";const lines=["",`Type-aware option policies for ${typeDefinition.name}:`,`  required: ${toFlags(policyState.required)}`,`  disabled: ${toFlags(policyState.disabled)}`,`  hidden: ${toFlags(policyState.hidden)}`];if(commandName==="create"){const strictPolicyState=resolveCommandOptionPolicyState(typeDefinition,commandName,requiredSets.strict);appendStrictCreatePolicyHelpLines(lines,typeDefinition,progressivePolicyState.required,strictPolicyState.required)}appendTypeOptionHelpLines(lines,typeDefinition);if(policyState.errors.length>0){lines.push(`  config errors: ${policyState.errors.join("; ")}`)}return lines.join("\n")}function attachCreateUpdatePolicyHelpText(rootProgram,typeRegistry,argv){const bootstrapCommand=parseBootstrapCommandName(argv);if(bootstrapCommand!=="create"&&bootstrapCommand!=="update"){return}const command=findDirectChildCommand(rootProgram,bootstrapCommand);if(!command){return}command.addHelpText("after",buildCreateUpdatePolicyHelpText(bootstrapCommand,typeRegistry,argv))}const _testOnly={attachCreateUpdatePolicyHelpText,buildCreateUpdatePolicyHelpText,buildJsonHelpPayload,buildPositionalActionHelpProjection,buildHelpArgumentSummaries,buildHelpOptionSummaries,buildHelpSubcommandSummaries,buildOptionAliasMap,compactHelpOptionAliases,readOptionAttributeName,resolveCommandFromPathTokens,resolveExtensionCommandSurface};export{_testOnly,attachCreateUpdatePolicyHelpText,maybeRenderBootstrapJsonHelp};
+`)}return process.exitCode=EXIT_CODE.USAGE,!0}if(!bootstrapGlobal.quiet){const payload=buildJsonHelpPayload(rootProgram,targetCommand,argv,helpRequest.commandPathTokens,extensionDescriptors),originalPath=parseBootstrapHelpRequest(requestedArgv).commandPathTokens;payload.requested_path=originalPath;const alias=resolvePmCommandAlias(originalPath.join(" "));alias&&(payload.resolved_path=alias.canonical),targetCommand===rootProgram&&!isFullHelpDiscovery(argv)&&(payload.omission_receipt={has_omissions:!0,omitted_field_group_count:1,omitted_field_groups:[{name:"command_aliases",restore_with:"--all"}]}),writeStdout(`${JSON.stringify(payload,null,2)}
+`)}return process.exitCode=EXIT_CODE.SUCCESS,!0}function buildCreateUpdatePolicyIntro(commandName,typeRegistry){const lines=["","Type-aware option policies:","  pass --type <value> with --help to render required/disabled/hidden option policy details for that type.",`  active type values: ${typeRegistry.types.join("|")}`];return commandName==="create"&&lines.push("  scheduling shortcut: use --schedule-preset lightweight for Reminder/Meeting/Event minimal create flows."),lines.join(`
+`)}function appendTypeOptionHelpLines(lines,typeDefinition){if(typeDefinition.options.length===0){lines.push("  type options: none");return}lines.push("  type options:");for(const option of typeDefinition.options){const requiredLabel=option.required?" (required)":"",aliases=option.aliases??[];lines.push(`    - ${option.key}${requiredLabel}`),lines.push(`      values: ${option.values.length>0?option.values.join("|"):"any non-empty string"}`),lines.push(`      aliases: ${aliases.length>0?aliases.join("|"):"none"}`),option.description&&option.description.trim().length>0&&lines.push(`      description: ${option.description.trim()}`)}}function buildCreatePolicyRequiredSets(commandName,typeDefinition){const progressive=commandName==="create"?new Set(["title","type"]):new Set,strict=new Set(progressive);if(commandName==="create")for(const option of[...typeDefinition.required_create_fields,...typeDefinition.required_create_repeatables])strict.add(option);return{progressive,strict}}function appendStrictCreatePolicyHelpLines(lines,typeDefinition,progressiveRequired,strictRequired){const progressive=new Set(progressiveRequired),strictOnly=strictRequired.filter(option=>!progressive.has(option)),toFlags=options=>options.length>0?options.map(option=>commandOptionFlagLabel("create",option)).join(", "):"none";lines.push(`  required in strict mode: ${toFlags(strictOnly)}`);const explicitEmptyFlags=strictOnly.map(resolveCreateExplicitEmptyFlag).filter(flag=>flag!==void 0);lines.push(`  explicit empty assertion: ${explicitEmptyFlags.length>0?explicitEmptyFlags.join(", "):"none"}`),["Reminder","Meeting","Event"].includes(typeDefinition.name)&&(lines.push("  schedule preset: --schedule-preset lightweight switches schedule artifacts to progressive required-option policy."),lines.push("  strict parity remains available via --create-mode strict."))}function buildCreateUpdatePolicyHelpText(commandName,typeRegistry,argv){const selectedTypeRaw=parseBootstrapTypeValue(argv);if(!selectedTypeRaw)return buildCreateUpdatePolicyIntro(commandName,typeRegistry);const typeDefinition=resolveTypeDefinition(selectedTypeRaw,typeRegistry);if(!typeDefinition){const allowed=typeRegistry.types.join("|");return["",`Type-aware option policies: type "${selectedTypeRaw}" is not in the active registry.`,`  active type values: ${allowed}`].join(`
+`)}const argumentTerminatorIndex=argv.indexOf("--"),optionArgv=argumentTerminatorIndex<0?argv:argv.slice(0,argumentTerminatorIndex),createModeTokenIndex=optionArgv.findIndex(token=>token==="--create-mode"||token.startsWith("--create-mode=")),createModeToken=createModeTokenIndex<0?void 0:optionArgv[createModeTokenIndex]?.startsWith("--create-mode=")?optionArgv[createModeTokenIndex]?.slice(14):optionArgv[createModeTokenIndex+1],strictCreateMode=commandName==="create"&&createModeToken?.toLowerCase()==="strict",requiredSets=buildCreatePolicyRequiredSets(commandName,typeDefinition),progressivePolicyState=resolveCommandOptionPolicyState(typeDefinition,commandName,requiredSets.progressive),policyState=resolveCommandOptionPolicyState(typeDefinition,commandName,strictCreateMode?requiredSets.strict:requiredSets.progressive),toFlags=options=>options.length>0?options.map(option=>commandOptionFlagLabel(commandName,option)).join(", "):"none",lines=["",`Type-aware option policies for ${typeDefinition.name}:`,`  required: ${toFlags(policyState.required)}`,`  disabled: ${toFlags(policyState.disabled)}`,`  hidden: ${toFlags(policyState.hidden)}`];if(commandName==="create"){const strictPolicyState=resolveCommandOptionPolicyState(typeDefinition,commandName,requiredSets.strict);appendStrictCreatePolicyHelpLines(lines,typeDefinition,progressivePolicyState.required,strictPolicyState.required)}return appendTypeOptionHelpLines(lines,typeDefinition),policyState.errors.length>0&&lines.push(`  config errors: ${policyState.errors.join("; ")}`),lines.join(`
+`)}function attachCreateUpdatePolicyHelpText(rootProgram,typeRegistry,argv){const bootstrapCommand=parseBootstrapCommandName(argv);if(bootstrapCommand!=="create"&&bootstrapCommand!=="update")return;const command=findDirectChildCommand(rootProgram,bootstrapCommand);command&&command.addHelpText("after",buildCreateUpdatePolicyHelpText(bootstrapCommand,typeRegistry,argv))}const _testOnly={attachCreateUpdatePolicyHelpText,buildCreateUpdatePolicyHelpText,buildJsonHelpPayload,buildPositionalActionHelpProjection,buildHelpArgumentSummaries,buildHelpOptionSummaries,buildHelpSubcommandSummaries,buildOptionAliasMap,compactHelpOptionAliases,readOptionAttributeName,resolveCommandFromPathTokens,resolveExtensionCommandSurface};export{_testOnly,attachCreateUpdatePolicyHelpText,maybeRenderBootstrapJsonHelp};
 //# sourceMappingURL=help-json-payload.js.map

package/dist/cli/invocation-profile.js

@@ -1,3 +1,3 @@
-!(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]="a9e2b181-e669-5521-b48a-f22b91c745c9")}catch(e2){}})();function registerInvocationProfile(argv,host=process){const terminator=argv.indexOf("--");const options=terminator<0?argv:argv.slice(0,terminator);const emit=()=>{host.stderr.write(`profile:invocation total_ms=${(host.uptime()*1e3).toFixed(3)} scope=process_start_to_output_drain command_took_ms_scope=handler
-`)};if(options.includes("--profile"))host.once("beforeExit",emit);return()=>{host.off("beforeExit",emit)}}export{registerInvocationProfile};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6b507b02-12b9-5a35-87fa-bf1f52098432")}catch{}})();function registerInvocationProfile(argv,host=process){const terminator=argv.indexOf("--"),options=terminator<0?argv:argv.slice(0,terminator),emit=()=>{host.stderr.write(`profile:invocation total_ms=${(host.uptime()*1e3).toFixed(3)} scope=process_start_to_output_drain command_took_ms_scope=handler
+`)};return options.includes("--profile")&&host.once("beforeExit",emit),()=>{host.off("beforeExit",emit)}}export{registerInvocationProfile};
 //# sourceMappingURL=invocation-profile.js.map