@unbrained/pm-cli 2026.9.19 → 2026.9.21

package/dist/cli/register-operations.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8428a95f-24d1-546c-82b6-40b182b491de")}catch(e2){}})();import{resolvePmCommandAlias,renderPmCommandAliasMigrationHint}from"../sdk/cli-contracts/command-aliases.js";import{setActiveCommandResult,EXIT_CODE,PmCliError,createUnknownSubcommandError,resolveAuthor,resolvePmRoot,readSettings}from"../sdk/runtime-primitives.js";import{runStartTask,runPauseTask,runCloseTask}from"../sdk/lifecycle/task-composition.js";import{parseStatsAnalyticsJson}from"./stats-analytics-json.js";import{createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,restoreWorkspaceSnapshotWithRecovery,WORKSPACE_SNAPSHOT_ACTIONS}from"../sdk/workspace-snapshot.js";import{readWorkspacePosition}from"../sdk/governance/workspace-position.js";import{runClaim,runClaimNext,runRelease}from"./commands/claim.js";import{runContracts}from"./commands/contracts.js";import{runDuplicates}from"./commands/duplicates.js";import{runGc}from"./commands/gc.js";import{runHealth}from"./commands/health.js";import{runStats}from"./commands/stats.js";import{runTelemetry}from"./commands/telemetry.js";import{runTest}from"./commands/test.js";import{runTestAll}from"./commands/test-all.js";import{runStartBackgroundRun,runTestRunsWorker}from"./commands/test-runs.js";import{runValidate}from"./commands/validate.js";import{buildBackgroundTestAllCommandArgs,applyActiveCommandResultService,buildBackgroundTestCommandArgs,addHiddenOption,collect,getGlobalOptions,invalidateSearchCachesForMutation,printError,printResult,readOptionString}from"./registration-helpers.js";import{registerAssuranceCommand}from"./register-assurance.js";function resolveTelemetrySubcommand(namespaceOrSubcommand,subcommand){const normalizedNamespace=namespaceOrSubcommand?.trim().toLowerCase();const normalizedSubcommand=subcommand?.trim().toLowerCase();if(normalizedNamespace===void 0||normalizedNamespace.length===0){return normalizedSubcommand}if(normalizedNamespace==="local-analytics"){return normalizedSubcommand&&normalizedSubcommand.length>0?normalizedSubcommand:"status"}if(normalizedSubcommand!==void 0&&normalizedSubcommand.length>0){throw createUnknownSubcommandError({command_path:"telemetry",token:`${namespaceOrSubcommand} ${subcommand}`,allowed:["status","flush","stats","clear","local-analytics"],token_kind:"path",examples:["pm telemetry stats --limit 10","pm telemetry local-analytics status --json"]})}return normalizedNamespace}function collectTestMutationValues(options){return{addValues:Array.isArray(options.add)?options.add:[],addJsonValues:Array.isArray(options.addJson)?options.addJson:[],removeValues:Array.isArray(options.remove)?options.remove:[],removeIndexValues:Array.isArray(options.removeIndex)?options.removeIndex:[]}}function validateBackgroundTestOptions(options,values){if(options.background!==true){return}if(options.run!==true){throw new PmCliError("--background requires --run",EXIT_CODE.USAGE)}if(options.acknowledgeLinkedTests===true){throw new PmCliError("--background cannot be combined with --acknowledge-linked-tests; acknowledgement is a non-executing foreground operation",EXIT_CODE.USAGE)}if(values.addValues.length>0||values.addJsonValues.length>0||values.removeValues.length>0||values.removeIndexValues.length>0){throw new PmCliError("--background does not support --add/--add-json/--remove/--remove-index; update linked tests first, then run in background",EXIT_CODE.USAGE)}}async function runBackgroundLinkedTests(id,options,globalOptions,values){const result=await runStartBackgroundRun({kind:"test",commandArgs:buildBackgroundTestCommandArgs(id,{...options,add:values.addValues,addJson:values.addJsonValues,remove:values.removeValues,removeIndex:values.removeIndexValues}),targetId:id,author:typeof options.author==="string"?options.author:void 0,noExtensions:globalOptions.noExtensions===true},globalOptions);printResult(result,globalOptions)}function buildRunTestOptions(options,values){return{add:values.addValues,addJson:values.addJsonValues,remove:values.removeValues,removeIndex:values.removeIndexValues,list:Boolean(options.list),run:Boolean(options.run),match:typeof options.match==="string"?options.match:void 0,onlyIndex:typeof options.onlyIndex==="string"||typeof options.onlyIndex==="number"?options.onlyIndex:void 0,onlyLast:Boolean(options.onlyLast),timeout:typeof options.timeout==="string"?options.timeout:void 0,progress:Boolean(options.progress),envSet:Array.isArray(options.envSet)?options.envSet:[],envClear:Array.isArray(options.envClear)?options.envClear:[],sharedHostSafe:Boolean(options.sharedHostSafe),pmContext:typeof options.pmContext==="string"?options.pmContext:void 0,overrideLinkedPmContext:Boolean(options.overrideLinkedPmContext),workspaceContext:typeof options.workspaceContext==="string"?options.workspaceContext:void 0,overrideLinkedWorkspaceContext:Boolean(options.overrideLinkedWorkspaceContext),allowUntrustedLinkedTests:Boolean(options.allowUntrustedLinkedTests),acknowledgeLinkedTests:Boolean(options.acknowledgeLinkedTests),failOnContextMismatch:Boolean(options.failOnContextMismatch),failOnSkipped:Boolean(options.failOnSkipped),failOnEmptyTestRun:Boolean(options.failOnEmptyTestRun),requireAssertionsForPm:Boolean(options.requireAssertionsForPm),checkContext:Boolean(options.checkContext),autoPmContext:Boolean(options.autoPmContext),author:typeof options.author==="string"?options.author:void 0,message:typeof options.message==="string"?options.message:void 0,force:Boolean(options.force),measure:Array.isArray(options.measure)?options.measure:[],metricBelow:typeof options.metricBelow==="string"?options.metricBelow:void 0,metricDiff:typeof options.metricDiff==="string"?options.metricDiff:void 0}}const _testOnlyRegisterOperations={buildRunTestOptions,buildRunTestAllOptions,runWorkspacePositionAction,validateBackgroundTestOptions};async function runForegroundLinkedTests(id,options,globalOptions,values){const result=await runTest(id,buildRunTestOptions(options,values),globalOptions);if(values.addValues.length>0||values.addJsonValues.length>0||values.removeValues.length>0||options.run===true||values.removeIndexValues.length>0){await invalidateSearchCachesForMutation(globalOptions,result)}printResult(result,globalOptions);if(result.run_results.some(entry=>entry.status==="failed")||result.fail_on_skipped_triggered===true){process.exitCode=EXIT_CODE.DEPENDENCY_FAILED}}async function runTestCommandAction(id,options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const values=collectTestMutationValues(options);validateBackgroundTestOptions(options,values);if(options.background===true){await runBackgroundLinkedTests(id,options,globalOptions,values)}else{await runForegroundLinkedTests(id,options,globalOptions,values)}if(globalOptions.profile){printError(`profile:command=test took_ms=${Date.now()-startedAt}`)}}function buildLifecycleMutationOptions(options){const author=readOptionString(options,"author");const assignee=readOptionString(options,"assignee");if(author!==void 0&&assignee!==void 0&&author!==assignee){throw new PmCliError("Lifecycle ownership received conflicting --author and --assignee values; use one actor value for both aliases.",EXIT_CODE.USAGE,{code:"conflicting_lifecycle_owner",examples:["pm claim pm-123","pm claim pm-123 --start","pm release pm-123"]})}return{author:author??assignee,message:readOptionString(options,"message")}}async function runTestAllAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const runInBackground=options.background===true;if(runInBackground){const result2=await runStartBackgroundRun({kind:"test-all",commandArgs:buildBackgroundTestAllCommandArgs(options),statusFilter:readOptionString(options,"status"),noExtensions:globalOptions.noExtensions===true},globalOptions);printResult(result2,globalOptions);if(globalOptions.profile){printError(`profile:command=test-all took_ms=${Date.now()-startedAt}`)}return}const result=await runTestAll(buildRunTestAllOptions(options),globalOptions);await invalidateSearchCachesForMutation(globalOptions,{ids:result.results.map(entry=>entry.id)});printResult(result,globalOptions);if(result.failed>0||result.fail_on_skipped_triggered===true){process.exitCode=EXIT_CODE.DEPENDENCY_FAILED}if(globalOptions.profile){printError(`profile:command=test-all took_ms=${Date.now()-startedAt}`)}}function buildRunTestAllOptions(options){return{status:readOptionString(options,"status"),limit:readOptionString(options,"limit"),offset:readOptionString(options,"offset"),timeout:readOptionString(options,"timeout"),progress:Boolean(options.progress),envSet:Array.isArray(options.envSet)?options.envSet:[],envClear:Array.isArray(options.envClear)?options.envClear:[],sharedHostSafe:Boolean(options.sharedHostSafe),pmContext:readOptionString(options,"pmContext"),overrideLinkedPmContext:Boolean(options.overrideLinkedPmContext),workspaceContext:readOptionString(options,"workspaceContext"),overrideLinkedWorkspaceContext:Boolean(options.overrideLinkedWorkspaceContext),allowUntrustedLinkedTests:Boolean(options.allowUntrustedLinkedTests),failOnContextMismatch:Boolean(options.failOnContextMismatch),failOnSkipped:Boolean(options.failOnSkipped),failOnEmptyTestRun:Boolean(options.failOnEmptyTestRun),requireAssertionsForPm:Boolean(options.requireAssertionsForPm),checkContext:Boolean(options.checkContext),autoPmContext:Boolean(options.autoPmContext)}}async function runTelemetryAction(namespaceOrSubcommand,subcommand,options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runTelemetry({subcommand:resolveTelemetrySubcommand(namespaceOrSubcommand,subcommand),limit:readOptionString(options,"limit")},globalOptions);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=telemetry took_ms=${Date.now()-startedAt}`)}}async function runStatsAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const analytics=parseStatsAnalyticsJson(readOptionString(options,"analytics"));const result=await runStats(globalOptions,{includeEmpty:options.includeEmpty===true,storage:options.storage===true,metadataCoverage:options.metadataCoverage===true,byAssignee:options.byAssignee===true,byTag:options.byTag===true,byPriority:options.byPriority===true,tagPrefix:readOptionString(options,"tagPrefix"),fieldUtilization:options.fieldUtilization===true,...analytics});if(result.recorded_observations?.some(entry=>entry.changed)===true){await invalidateSearchCachesForMutation(globalOptions,{ids:result.recorded_observations?.flatMap(entry=>entry.observation.item_id?[entry.observation.item_id]:[])})}printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=stats took_ms=${Date.now()-startedAt}`)}}async function runDuplicatesAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const threshold=readOptionString(options,"threshold");const limit=readOptionString(options,"limit");const result=await runDuplicates(globalOptions,{...options.exhaustive===true?{exhaustive:true}:{},status:Array.isArray(options.status)&&options.status.length>0?options.status:void 0,since:readOptionString(options,"since"),...threshold===void 0?{}:{threshold:Number(threshold)},...limit===void 0?{}:{limit:Number(limit)}});printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=duplicates took_ms=${Date.now()-startedAt}`)}}async function runHealthAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const strictExit=Boolean(options.strictExit)||Boolean(options.failOnWarn);const result=await runHealth(globalOptions,{strictExit,strictDirectories:Boolean(options.strictDirectories),requireMergeDrivers:Boolean(options.requireMergeDrivers),checkOnly:Boolean(options.checkOnly),checkTelemetry:Boolean(options.checkTelemetry),noRefresh:Boolean(options.noRefresh),refreshVectors:Boolean(options.refreshVectors),verboseStaleItems:Boolean(options.verboseStaleItems),verboseAuthorEvents:Boolean(options.verboseAuthorEvents),brief:Boolean(options.brief),summary:Boolean(options.summary)||strictExit,skipVectors:Boolean(options.skipVectors),skipIntegrity:Boolean(options.skipIntegrity),skipDrift:Boolean(options.skipDrift),full:Boolean(options.full)});printResult(result,globalOptions);if(strictExit&&!result.ok){setActiveCommandResult({...result,exit_code:EXIT_CODE.GENERIC_FAILURE,error_code:"health_findings",error_category:"validation",command_resolution:"health_findings",resolution_stage:"execute"});process.exitCode=EXIT_CODE.GENERIC_FAILURE}if(globalOptions.profile){printError(`profile:command=health took_ms=${Date.now()-startedAt}`)}}async function runValidateAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runValidate({checkMetadata:Boolean(options.checkMetadata),metadataProfile:readOptionString(options,"metadataProfile"),checkResolution:Boolean(options.checkResolution),checkCompleteness:Boolean(options.checkCompleteness),checkLifecycle:Boolean(options.checkLifecycle),checkStaleBlockers:Boolean(options.checkStaleBlockers),dependencyCycleSeverity:readOptionString(options,"dependencyCycleSeverity"),parentCycleSeverity:readOptionString(options,"parentCycleSeverity"),checkFiles:Boolean(options.checkFiles),checkCommandReferences:Boolean(options.checkCommandReferences),scanMode:readOptionString(options,"scanMode"),includePmInternals:Boolean(options.includePmInternals),verboseFileLists:Boolean(options.verboseFileLists),verboseDiagnostics:Boolean(options.verboseDiagnostics),allAffectedIds:Boolean(options.allAffectedIds),checkHistoryDrift:Boolean(options.checkHistoryDrift),checkStorageIntegrity:Boolean(options.checkStorageIntegrity),fixHints:Boolean(options.fixHints),autoFix:Boolean(options.autoFix),dryRun:Boolean(options.dryRun),fixScope:Array.isArray(options.fixScope)?options.fixScope:void 0,pruneMissing:Boolean(options.pruneMissing),counts:Boolean(options.counts),full:Boolean(options.full)},globalOptions);printResult(result,globalOptions);const strictExit=Boolean(options.strictExit)||Boolean(options.failOnWarn);if(strictExit&&(result.has_warnings||!result.ok)){setActiveCommandResult({...result,exit_code:EXIT_CODE.GENERIC_FAILURE,error_code:"validation_findings",error_category:"validation",command_resolution:"validation_findings",resolution_stage:"execute"});process.exitCode=EXIT_CODE.GENERIC_FAILURE}if(globalOptions.profile){printError(`profile:command=validate took_ms=${Date.now()-startedAt}`)}}async function runGcAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runGc(globalOptions,{dryRun:options.dryRun===true,scope:Array.isArray(options.scope)?options.scope:[]});printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=gc took_ms=${Date.now()-startedAt}`)}}async function runWorkspaceSnapshotAction(action,target,options,command){const globalOptions=getGlobalOptions(command);const pmRoot=resolvePmRoot(process.cwd(),globalOptions.path);const normalizedAction=action.trim().toLowerCase();if(!WORKSPACE_SNAPSHOT_ACTIONS.some(entry=>entry===normalizedAction)){throw createUnknownSubcommandError({command_path:"workspace snapshot",token:action,allowed:WORKSPACE_SNAPSHOT_ACTIONS,display_name:"workspace snapshot",token_kind:"action",examples:["pm workspace snapshot create before-migration","pm workspace snapshot restore before-migration"]})}if(normalizedAction==="list"){printResult(await listWorkspaceSnapshots(pmRoot),globalOptions);return}if(normalizedAction==="create"){printResult(await createWorkspaceSnapshot(pmRoot,target===void 0?{}:{name:target}),globalOptions);return}if(target===void 0){throw new PmCliError(`pm workspace snapshot ${normalizedAction} requires a snapshot name or fingerprint`,EXIT_CODE.USAGE)}if(normalizedAction==="inspect"){printResult(await inspectWorkspaceSnapshot(pmRoot,target),globalOptions);return}if(normalizedAction==="restore"){if(options.dryRun===true){printResult(await planWorkspaceSnapshotRestore(pmRoot,target),globalOptions);return}const settings=await readSettings(pmRoot);printResult(await restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:options.force===true,author:resolveAuthor(readOptionString(options,"author"),settings.author_default),message:readOptionString(options,"message"),lockTtlSeconds:settings.locks.ttl_seconds,lockWaitMs:settings.locks.wait_ms}),globalOptions);return}printResult(await deleteWorkspaceSnapshot(pmRoot,target),globalOptions)}async function runWorkspacePositionAction(_options,command){const globalOptions=getGlobalOptions(command);printResult(await readWorkspacePosition(globalOptions),globalOptions)}async function runContractsAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runContracts({action:readOptionString(options,"action"),command:readOptionString(options,"command"),summary:Boolean(options.summary),schemaOnly:Boolean(options.schemaOnly),flagsOnly:Boolean(options.flagsOnly),availabilityOnly:Boolean(options.availabilityOnly),runtimeOnly:Boolean(options.runtimeOnly)||Boolean(options.activeOnly),full:Boolean(options.full)},globalOptions);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=contracts took_ms=${Date.now()-startedAt}`)}}async function runClaimAction(id,options,command){if(options.start===true){requireClaimTarget(id,false);await runStartTaskAction(id,options,command);return}const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const lifecycleOptions={...buildLifecycleMutationOptions(options),ifAvailable:options.ifAvailable===true,maxAttempts:options.maxAttempts};requireClaimTarget(id,options.next===true);const result=options.next===true?await runClaimNext(Boolean(options.force),globalOptions,lifecycleOptions,{type:typeof options.type==="string"?options.type:void 0,tag:typeof options.tag==="string"?options.tag:void 0,priority:options.priority,assigneeFilter:typeof options.assigneeFilter==="string"?options.assigneeFilter:void 0,parent:typeof options.parent==="string"?options.parent:void 0,sprint:typeof options.sprint==="string"?options.sprint:void 0,release:typeof options.release==="string"?options.release:void 0,includeDecisions:options.includeDecisions===true,includeGates:options.includeGates===true,includeContainers:options.includeContainers===true,tokenBudget:options.tokenBudget??options.token_budget,explainRanking:options.explainRanking===true||options.explain_ranking===true}):await runClaim(id,Boolean(options.force),globalOptions,lifecycleOptions);await invalidateSearchCachesForMutation(globalOptions,result);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=claim took_ms=${Date.now()-startedAt}`)}}function requireClaimTarget(id,next){if(!next&&!id)throw new PmCliError("Specify an item id or pass --next",EXIT_CODE.USAGE);if(next&&id)throw new PmCliError("Specify either an item id or --next, not both",EXIT_CODE.USAGE)}async function runReleaseAction(id,options,command){if(options.pause===true){await runPauseTaskAction(id,options,command);return}const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runRelease(id,Boolean(options.force),globalOptions,{...buildLifecycleMutationOptions(options),ownershipReleaseBypass:options.ownershipReleaseBypass===true});await invalidateSearchCachesForMutation(globalOptions,result);printResult(await applyActiveCommandResultService("release",[id],options,globalOptions,result),globalOptions);if(globalOptions.profile){printError(`profile:command=release took_ms=${Date.now()-startedAt}`)}}async function printLifecycleAliasHint(command){const global2=getGlobalOptions(command);const alias=resolvePmCommandAlias(command.name());if(!alias||global2.json||global2.quiet)return;const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path));if(settings.ux?.deprecation_hints)printError(renderPmCommandAliasMigrationHint(alias))}async function runStartTaskAction(id,options,command){await printLifecycleAliasHint(command);const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runStartTask(id,{...buildLifecycleMutationOptions(options),force:Boolean(options.force),next:options.next===true,ifAvailable:options.ifAvailable===true},globalOptions);await invalidateSearchCachesForMutation(globalOptions,result.update);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=start-task took_ms=${Date.now()-startedAt}`)}}async function runPauseTaskAction(id,options,command){await printLifecycleAliasHint(command);const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runPauseTask(id,{...buildLifecycleMutationOptions(options),force:Boolean(options.force)},globalOptions);await invalidateSearchCachesForMutation(globalOptions,result.release);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=pause-task took_ms=${Date.now()-startedAt}`)}}async function runCloseTaskAction(id,reason,options,command){await printLifecycleAliasHint(command);const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runCloseTask(id,reason,{...buildLifecycleMutationOptions(options),validateClose:readOptionString(options,"validateClose"),force:Boolean(options.force)},globalOptions);await invalidateSearchCachesForMutation(globalOptions,result.release);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=close-task took_ms=${Date.now()-startedAt}`)}}function addLinkedTestExecutionOptions(command){return command.option("--background","Run linked tests in managed background mode").option("--timeout <seconds>","Default run timeout in seconds").option("--progress","Emit linked-test progress to stderr (always shown in TTY, opt-in for non-TTY)").option("--env-set <value>","Set environment variable(s) for linked-test runs (KEY=VALUE, repeatable)",collect).option("--env-clear <value>","Clear environment variable(s) for linked-test runs (NAME, repeatable)",collect).option("--shared-host-safe","Apply additive shared-host-safe runtime defaults for linked-test runs").option("--pm-context <mode>","PM linked-test context mode: schema|tracker|auto (default: schema)").option("--override-linked-pm-context","Force run-level --pm-context to override per-linked-test pm_context_mode metadata").option("--workspace-context <mode>","Source-workspace mode: source|isolated|snapshot (default: source)").option("--override-linked-workspace-context","Force run-level --workspace-context over per-linked-test metadata").option("--allow-untrusted-linked-tests","Execute untrusted linked commands when project policy also permits it").option("--fail-on-context-mismatch","Fail linked PM commands when context item counts differ").option("--fail-on-skipped","Treat skipped linked tests as dependency failures").option("--fail-on-empty-test-run","Treat successful linked-test commands that report zero executed tests as failures").option("--require-assertions-for-pm","Require assertion metadata for linked PM command tests").option("--check-context","Preflight linked PM command context diagnostics before executing commands").option("--auto-pm-context","Auto-remediate PM tracker-read context mismatches by routing those linked commands through tracker context")}function registerOperationCommands(program){registerAssuranceCommand(program);const testCommand=program.command("test").argument("<id>","Item id").option("--add <value>","Add verified isolated test (CSV/markdown or stdin)",collect).option("--add-json <value>","Add verified isolated test (JSON object/array or stdin)",collect).option("--remove <value>","Remove linked test entry by exact command/path (command=<value> and path=<value> preserve commas and equals signs; or - for stdin)",collect).option("--remove-index <n>","Remove the 1-based linked-test index from --list order (repeatable)",collect).option("--list","List linked tests without mutating").option("--run","Run linked test commands").option("--match <value>","Run only linked tests whose command/path contains this substring").option("--only-index <n>","Run only the 1-based linked-test index from --list order").option("--only-last","Run only the most recently added linked test");testCommand.option("--acknowledge-linked-tests","Trust the item's current linked commands in this clone without executing them");addLinkedTestExecutionOptions(testCommand).option("--measure <value>","Record name=value[,unit=...][,threshold=...] evidence; repeatable",collect).option("--metric-below <value>","Return evidence below name=value").option("--metric-diff <name>","Diff the latest two values").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force ownership override").description("Manage tests linked to an item and optionally run them.").action(runTestCommandAction);const testAllCommand=program.command("test-all").description("Run linked tests across matching items.").option("--status <value>","Filter items by status before running tests").option("--limit <n>","Limit matching items before running linked tests").option("--offset <n>","Skip matching items before running linked tests");addLinkedTestExecutionOptions(testAllCommand).action(runTestAllAction);program.command("test-runs-worker",{hidden:true}).argument("<runId>","Background run id").description("Internal background worker command.").action(async(runId,_options,command)=>{const globalOptions=getGlobalOptions(command);await runTestRunsWorker(runId,globalOptions)});program.command("telemetry").argument("[namespace-or-subcommand]","Telemetry subcommand: status, flush, stats, clear (default: status)").argument("[subcommand]","Compatibility alias target for local-analytics: status, flush, stats, clear").option("--limit <n>","Maximum command groups returned by telemetry stats").description("Inspect and manage local telemetry queue/runtime state.").action(runTelemetryAction);program.command("duplicates").description("Find duplicate clusters across all statuses.").option("--status <value>","Statuses (repeatable or comma-separated)",collect,[]).option("--since <value>","Created at or after this time").option("--threshold <value>","Minimum similarity (0-1)").option("--limit <n>","Maximum clusters").option("--exhaustive","Score all pairs within the safety bound").action(runDuplicatesAction);program.command("stats").description("Show project tracker statistics.").option("--include-empty","Restore zero-count registered item-type and lifecycle-status buckets").option("--storage","Include aggregate history-stream storage metrics (total streams/lines/bytes, largest + deepest streams, oldest/newest entries)").option("--metadata-coverage","Include metadata coverage % (acceptance_criteria, estimated_minutes, resolution, tags, parent) overall and by type").option("--by-assignee","Include a lifecycle-bucketed item breakdown grouped by assignee").option("--by-tag","Include a lifecycle-bucketed item breakdown grouped by tag").option("--by-priority","Include a lifecycle-bucketed item breakdown grouped by priority").option("--tag-prefix <value>","With --by-tag: only count tags starting with this prefix (e.g. domain:)").option("--field-utilization","Report content-field utilization rates (notes/learnings/files/docs/tests/comments/deps/body) for governance analysis").option("--analytics <json>","Improvement ledger/history analytics JSON").action(runStatsAction);program.command("health").description("Show project tracker health checks.").option("--strict-directories","Treat optional item-type directories as required failures").option("--require-merge-drivers","Treat absent clone-local merge drivers as a required health failure").option("--check-only","Run read-only health diagnostics without refreshing vectors").option("--check-telemetry","Probe telemetry endpoint health and include network diagnostics").option("--no-refresh","Disable automatic vector refresh attempts during health checks").option("--refresh-vectors","Explicitly enable vector refresh attempts during health checks").option("--verbose-stale-items","Include full stale vectorization ID lists in health output").option("--verbose-author-events","Include every actionable unknown-author event coordinate for review or disposition").option("--brief","Emit compact health details for low-token agent checks").option("--summary","Emit one-line-style health status with check names and warning count").option("--skip-vectors","Skip vectorization check for a faster run").option("--skip-integrity","Skip item/history file integrity check for a faster run").option("--skip-drift","Skip history drift hash check for a faster run").option("--full","Run all checks including slow integrity, drift, and vectorization checks").option("--strict-exit","Return non-zero exit when health is not ok and default to actionable summary output; use --full for complete details").option("--fail-on-warn","Alias for --strict-exit").action(runHealthAction);program.command("validate").description("Validate metadata, lifecycle policies, files, command references, and history.").option("--check-metadata","Run metadata completeness checks").option("--metadata-profile <value>","Metadata profile (core|strict|custom)").option("--check-resolution","Run closed-item resolution metadata checks").option("--check-completeness","Check declarative lifecycle field requirements").option("--check-lifecycle","Run active-item lifecycle governance drift checks").option("--check-stale-blockers","Include stale blocker-pattern diagnostics in lifecycle checks").option("--dependency-cycle-severity <value>","Set dependency-cycle warning policy for lifecycle checks (off|warn|error)").option("--parent-cycle-severity <value>","Set parent-hierarchy cycle warning policy for lifecycle checks (off|warn|error)").option("--check-files","Run linked-file and orphaned-file checks").option("--check-command-references","Run linked-command PM-ID reference checks").option("--scan-mode <value>","Select file candidate scan mode for --check-files (default|tracked-all|tracked-all-strict)").option("--include-pm-internals","Include PM storage internals in tracked-all candidate scans").option("--verbose-file-lists","Include full file-path lists for validate --check-files details").option("--verbose-diagnostics","Include full diagnostic ID lists").option("--all-affected-ids","Emit complete missing_* affected-ID lists with no truncation (implied by --json)").option("--strict-exit","Return non-zero exit when validation warnings are present").option("--fail-on-warn","Alias for --strict-exit").option("--fix-hints","Add a machine-executable fix_hints[] of pm commands to each failing check's details").option("--auto-fix","Apply safe, deterministic field backfills").option("--dry-run","Preview planned --auto-fix/--prune-missing fixes without applying them").option("--fix-scope <scope>","Grant --auto-fix scopes (metadata, resolution, lifecycle; comma-separated or repeatable). Default: metadata, resolution; lifecycle must be named explicitly",collect).option("--prune-missing","Remove deleted-path file/doc links; preserves real files").option("--check-history-drift","Run item/history hash drift checks").option("--check-storage-integrity","Run the post-merge storage-integrity check (unreadable items, history conflict markers, resurrected deletes, unparseable config/schema)").option("--counts","Keep validation counts and totals while omitting per-item diagnostic arrays").option("--full","Return the complete validation diagnostic projection").action(runValidateAction);program.command("gc").option("--dry-run","Preview cleanup targets without deleting files; without this flag, pm gc deletes matched artifacts").option("--scope <value>","Limit cleanup to one or more scopes (comma-separated or repeatable): index, embeddings, runtime, locks, checkpoints, transactions",collect).description("Delete optional cache artifacts by default (including expired lock debris) and show a summary.").action(runGcAction);const workspaceCommand=program.command("workspace").description("Inspect workspace state and snapshots.");workspaceCommand.command("position").description("Show merge and history readiness.").action(runWorkspacePositionAction);workspaceCommand.command("snapshot").argument("<action>","Action: create, list, inspect, restore, delete").argument("[target]","Optional name for create; name or fingerprint otherwise").description("Manage content-addressed tracker snapshots.").option("--dry-run","Preview restore file, item, stream, and history-entry impact without mutating state").option("--force","Explicitly confirm a whole-workspace snapshot restore").option("--author <value>","Actor recorded on the restore audit event").option("--message <value>","Human-readable restore rationale").action(runWorkspaceSnapshotAction);program.command("contracts").description("Show machine-readable command and schema contracts for agents.").option("--action <value>","Filter tool schema branches to a specific action").option("--command <value>","Scope contracts output to one CLI command (narrow-by-default)").option("--summary","Return one command+intent row per top-level command for cheap agent bootstrap").option("--schema-only","Return schema-focused output only").option("--flags-only","Return command flag contracts only").option("--availability-only","Return action availability surface only").option("--runtime-only","Include only actions invocable in the current runtime").option("--active-only","Alias for --runtime-only").option("--full","Include full schema and command-flag surfaces (large; default brief output omits heavy sections for unfiltered queries)").action(runContractsAction);const claimCommand=program.command("claim").option("--start","Claim and start an explicit item").argument("[id]","Item id (omit with --next)").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force claim override").option("--if-available","Skip another author's claim (skipped=true)").option("--next","Atomically claim the next caller-available actionable item").option("--type <value>","Filter --next candidates by type").option("--tag <value>","Filter --next candidates by tag").option("--priority <value>","Filter --next candidates by priority").option("--assignee-filter <value>","Filter --next candidates: assigned|unassigned").option("--parent <id>","Scope --next candidates to a subtree").option("--sprint <value>","Filter --next candidates by sprint").option("--release <value>","Filter --next candidates by release").option("--max-attempts <n>","Bound the --next candidate walk (default 10; maximum 100)").option("--include-decisions","Allow --next to claim human-gated Decision items").option("--include-gates","Allow --next to claim outcome gates").option("--include-containers","Allow --next to claim containers with unfinished descendants").option("--token-budget <n>","Bound the estimated tokens used to rank --next candidates").option("--explain-ranking","Include ranking provenance for --next selection").description("Claim an item for active work.").action(runClaimAction);addHiddenOption(claimCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");addHiddenOption(claimCommand,"--token_budget <n>","Alias for --token-budget");addHiddenOption(claimCommand,"--explain_ranking","Alias for --explain-ranking");const releaseCommand=program.command("release").option("--pause","Use open status").argument("<id>","Item id").option("--author <value>","Author").option("--message <value>","Message").option("--force","Override ownership").description("Release ownership.").action(runReleaseAction);addHiddenOption(releaseCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");const startTaskCommand=program.command("start-task",{hidden:true}).argument("<id>","Item id").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force ownership or terminal override when required").description("Lifecycle alias: claim an item and move it to in_progress.").action(runStartTaskAction);addHiddenOption(startTaskCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");const pauseTaskCommand=program.command("pause-task",{hidden:true}).argument("<id>","Item id").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force ownership override when required").description("Lifecycle alias: move an item to open and release its claim.").action(runPauseTaskAction);addHiddenOption(pauseTaskCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");const closeTaskCommand=program.command("close-task",{hidden:true}).argument("<id>","Item id").argument("[reason]","Close reason text").option("--author <value>","Mutation author").option("--message <value>","History message").option("--validate-close <value>","Close-time validation mode: off|warn|strict").option("--force","Force ownership or terminal override when required").description("Lifecycle alias: close an item and release assignment metadata.").action(runCloseTaskAction);addHiddenOption(closeTaskCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands")}export{_testOnlyRegisterOperations,registerOperationCommands,requireClaimTarget};
+!(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]="c5ff47ea-87e0-5c51-b84a-6b1c03d62ed9")}catch(e2){}})();import{resolvePmCommandAlias,renderPmCommandAliasMigrationHint}from"../sdk/cli-contracts/command-aliases.js";import{setActiveCommandResult,EXIT_CODE,PmCliError,createUnknownSubcommandError,resolveAuthor,resolvePmRoot,readSettings}from"../sdk/runtime-primitives.js";import{runStartTask,runPauseTask,runCloseTask}from"../sdk/lifecycle/task-composition.js";import{parseStatsAnalyticsJson}from"./stats-analytics-json.js";import{createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,restoreWorkspaceSnapshotWithRecovery,WORKSPACE_SNAPSHOT_ACTIONS}from"../sdk/workspace-snapshot.js";import{readWorkspacePosition}from"../sdk/governance/workspace-position.js";import{runClaim,runClaimNext,runRelease}from"./commands/claim.js";import{runContracts}from"./commands/contracts.js";import{runDuplicates}from"./commands/duplicates.js";import{runGc}from"./commands/gc.js";import{runHealth}from"./commands/health.js";import{runStats}from"./commands/stats.js";import{runTelemetry}from"./commands/telemetry.js";import{runTest}from"./commands/test.js";import{runTestAll}from"./commands/test-all.js";import{runStartBackgroundRun,runTestRunsWorker}from"./commands/test-runs.js";import{runValidate}from"./commands/validate.js";import{buildBackgroundTestAllCommandArgs,applyActiveCommandResultService,buildBackgroundTestCommandArgs,addHiddenOption,collect,getGlobalOptions,invalidateSearchCachesForMutation,printError,printResult,readOptionString}from"./registration-helpers.js";import{registerAssuranceCommand}from"./register-assurance.js";function resolveTelemetrySubcommand(namespaceOrSubcommand,subcommand){const normalizedNamespace=namespaceOrSubcommand?.trim().toLowerCase();const normalizedSubcommand=subcommand?.trim().toLowerCase();if(normalizedNamespace===void 0||normalizedNamespace.length===0){return normalizedSubcommand}if(normalizedNamespace==="local-analytics"){return normalizedSubcommand&&normalizedSubcommand.length>0?normalizedSubcommand:"status"}if(normalizedSubcommand!==void 0&&normalizedSubcommand.length>0){throw createUnknownSubcommandError({command_path:"telemetry",token:`${namespaceOrSubcommand} ${subcommand}`,allowed:["status","flush","stats","clear","local-analytics"],token_kind:"path",examples:["pm telemetry stats --limit 10","pm telemetry local-analytics status --json"]})}return normalizedNamespace}function collectTestMutationValues(options){return{addValues:Array.isArray(options.add)?options.add:[],addJsonValues:Array.isArray(options.addJson)?options.addJson:[],removeValues:Array.isArray(options.remove)?options.remove:[],removeIndexValues:Array.isArray(options.removeIndex)?options.removeIndex:[]}}function validateBackgroundTestOptions(options,values){if(options.background!==true){return}if(options.run!==true){throw new PmCliError("--background requires --run",EXIT_CODE.USAGE)}if(options.acknowledgeLinkedTests===true){throw new PmCliError("--background cannot be combined with --acknowledge-linked-tests; acknowledgement is a non-executing foreground operation",EXIT_CODE.USAGE)}if(values.addValues.length>0||values.addJsonValues.length>0||values.removeValues.length>0||values.removeIndexValues.length>0){throw new PmCliError("--background does not support --add/--add-json/--remove/--remove-index; update linked tests first, then run in background",EXIT_CODE.USAGE)}}async function runBackgroundLinkedTests(id,options,globalOptions,values){const result=await runStartBackgroundRun({kind:"test",commandArgs:buildBackgroundTestCommandArgs(id,{...options,add:values.addValues,addJson:values.addJsonValues,remove:values.removeValues,removeIndex:values.removeIndexValues}),targetId:id,author:typeof options.author==="string"?options.author:void 0,noExtensions:globalOptions.noExtensions===true},globalOptions);printResult(result,globalOptions)}function buildRunTestOptions(options,values){return{add:values.addValues,addJson:values.addJsonValues,remove:values.removeValues,removeIndex:values.removeIndexValues,list:Boolean(options.list),run:Boolean(options.run),match:typeof options.match==="string"?options.match:void 0,onlyIndex:typeof options.onlyIndex==="string"||typeof options.onlyIndex==="number"?options.onlyIndex:void 0,onlyLast:Boolean(options.onlyLast),timeout:typeof options.timeout==="string"?options.timeout:void 0,progress:Boolean(options.progress),envSet:Array.isArray(options.envSet)?options.envSet:[],envClear:Array.isArray(options.envClear)?options.envClear:[],sharedHostSafe:Boolean(options.sharedHostSafe),pmContext:typeof options.pmContext==="string"?options.pmContext:void 0,overrideLinkedPmContext:Boolean(options.overrideLinkedPmContext),workspaceContext:typeof options.workspaceContext==="string"?options.workspaceContext:void 0,overrideLinkedWorkspaceContext:Boolean(options.overrideLinkedWorkspaceContext),allowUntrustedLinkedTests:Boolean(options.allowUntrustedLinkedTests),acknowledgeLinkedTests:Boolean(options.acknowledgeLinkedTests),failOnContextMismatch:Boolean(options.failOnContextMismatch),failOnSkipped:Boolean(options.failOnSkipped),failOnEmptyTestRun:Boolean(options.failOnEmptyTestRun),requireAssertionsForPm:Boolean(options.requireAssertionsForPm),checkContext:Boolean(options.checkContext),autoPmContext:Boolean(options.autoPmContext),author:typeof options.author==="string"?options.author:void 0,message:typeof options.message==="string"?options.message:void 0,force:Boolean(options.force),measure:Array.isArray(options.measure)?options.measure:[],metricBelow:typeof options.metricBelow==="string"?options.metricBelow:void 0,metricDiff:typeof options.metricDiff==="string"?options.metricDiff:void 0}}const _testOnlyRegisterOperations={buildRunTestOptions,buildRunTestAllOptions,runWorkspacePositionAction,validateBackgroundTestOptions};async function runForegroundLinkedTests(id,options,globalOptions,values){const result=await runTest(id,buildRunTestOptions(options,values),globalOptions);if(values.addValues.length>0||values.addJsonValues.length>0||values.removeValues.length>0||options.run===true||values.removeIndexValues.length>0){await invalidateSearchCachesForMutation(globalOptions,result)}printResult(result,globalOptions);if(result.run_results.some(entry=>entry.status==="failed")||result.fail_on_skipped_triggered===true){process.exitCode=EXIT_CODE.DEPENDENCY_FAILED}}async function runTestCommandAction(id,options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const values=collectTestMutationValues(options);validateBackgroundTestOptions(options,values);if(options.background===true){await runBackgroundLinkedTests(id,options,globalOptions,values)}else{await runForegroundLinkedTests(id,options,globalOptions,values)}if(globalOptions.profile){printError(`profile:command=test took_ms=${Date.now()-startedAt}`)}}function buildLifecycleMutationOptions(options){const author=readOptionString(options,"author");const assignee=readOptionString(options,"assignee");if(author!==void 0&&assignee!==void 0&&author!==assignee){throw new PmCliError("Lifecycle ownership received conflicting --author and --assignee values; use one actor value for both aliases.",EXIT_CODE.USAGE,{code:"conflicting_lifecycle_owner",examples:["pm claim pm-123","pm claim pm-123 --start","pm release pm-123"]})}return{author:author??assignee,message:readOptionString(options,"message")}}async function runTestAllAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const runInBackground=options.background===true;if(runInBackground){const result2=await runStartBackgroundRun({kind:"test-all",commandArgs:buildBackgroundTestAllCommandArgs(options),statusFilter:readOptionString(options,"status"),noExtensions:globalOptions.noExtensions===true},globalOptions);printResult(result2,globalOptions);if(globalOptions.profile){printError(`profile:command=test-all took_ms=${Date.now()-startedAt}`)}return}const result=await runTestAll(buildRunTestAllOptions(options),globalOptions);await invalidateSearchCachesForMutation(globalOptions,{ids:result.results.map(entry=>entry.id)});printResult(result,globalOptions);if(result.failed>0||result.fail_on_skipped_triggered===true){process.exitCode=EXIT_CODE.DEPENDENCY_FAILED}if(globalOptions.profile){printError(`profile:command=test-all took_ms=${Date.now()-startedAt}`)}}function buildRunTestAllOptions(options){return{status:readOptionString(options,"status"),limit:readOptionString(options,"limit"),offset:readOptionString(options,"offset"),timeout:readOptionString(options,"timeout"),progress:Boolean(options.progress),envSet:Array.isArray(options.envSet)?options.envSet:[],envClear:Array.isArray(options.envClear)?options.envClear:[],sharedHostSafe:Boolean(options.sharedHostSafe),pmContext:readOptionString(options,"pmContext"),overrideLinkedPmContext:Boolean(options.overrideLinkedPmContext),workspaceContext:readOptionString(options,"workspaceContext"),overrideLinkedWorkspaceContext:Boolean(options.overrideLinkedWorkspaceContext),allowUntrustedLinkedTests:Boolean(options.allowUntrustedLinkedTests),failOnContextMismatch:Boolean(options.failOnContextMismatch),failOnSkipped:Boolean(options.failOnSkipped),failOnEmptyTestRun:Boolean(options.failOnEmptyTestRun),requireAssertionsForPm:Boolean(options.requireAssertionsForPm),checkContext:Boolean(options.checkContext),autoPmContext:Boolean(options.autoPmContext)}}async function runTelemetryAction(namespaceOrSubcommand,subcommand,options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runTelemetry({subcommand:resolveTelemetrySubcommand(namespaceOrSubcommand,subcommand),limit:readOptionString(options,"limit")},globalOptions);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=telemetry took_ms=${Date.now()-startedAt}`)}}async function runStatsAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const analytics=parseStatsAnalyticsJson(readOptionString(options,"analytics"));const result=await runStats(globalOptions,{includeEmpty:options.includeEmpty===true,storage:options.storage===true,metadataCoverage:options.metadataCoverage===true,byAssignee:options.byAssignee===true,byTag:options.byTag===true,byPriority:options.byPriority===true,tagPrefix:readOptionString(options,"tagPrefix"),fieldUtilization:options.fieldUtilization===true,...analytics});if(result.recorded_observations?.some(entry=>entry.changed)===true){await invalidateSearchCachesForMutation(globalOptions,{ids:result.recorded_observations?.flatMap(entry=>entry.observation.item_id?[entry.observation.item_id]:[])})}printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=stats took_ms=${Date.now()-startedAt}`)}}async function runDuplicatesAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const threshold=readOptionString(options,"threshold");const limit=readOptionString(options,"limit");const result=await runDuplicates(globalOptions,{...options.exhaustive===true?{exhaustive:true}:{},status:Array.isArray(options.status)&&options.status.length>0?options.status:void 0,since:readOptionString(options,"since"),...threshold===void 0?{}:{threshold:Number(threshold)},...limit===void 0?{}:{limit:Number(limit)}});printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=duplicates took_ms=${Date.now()-startedAt}`)}}async function runHealthAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const strictExit=Boolean(options.strictExit)||Boolean(options.failOnWarn);const result=await runHealth(globalOptions,{strictExit,strictDirectories:Boolean(options.strictDirectories),requireMergeDrivers:Boolean(options.requireMergeDrivers),checkOnly:Boolean(options.checkOnly),checkTelemetry:Boolean(options.checkTelemetry),noRefresh:Boolean(options.noRefresh),refreshVectors:Boolean(options.refreshVectors),verboseStaleItems:Boolean(options.verboseStaleItems),verboseAuthorEvents:Boolean(options.verboseAuthorEvents),brief:Boolean(options.brief),summary:Boolean(options.summary)||strictExit,skipVectors:Boolean(options.skipVectors),skipIntegrity:Boolean(options.skipIntegrity),skipDrift:Boolean(options.skipDrift),full:Boolean(options.full)});printResult(result,globalOptions);if(strictExit&&!result.ok){setActiveCommandResult({...result,exit_code:EXIT_CODE.GENERIC_FAILURE,error_code:"health_findings",error_category:"validation",command_resolution:"health_findings",resolution_stage:"execute"});process.exitCode=EXIT_CODE.GENERIC_FAILURE}if(globalOptions.profile){printError(`profile:command=health took_ms=${Date.now()-startedAt}`)}}async function runValidateAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runValidate({checkMetadata:Boolean(options.checkMetadata),metadataProfile:readOptionString(options,"metadataProfile"),checkResolution:Boolean(options.checkResolution),checkCompleteness:Boolean(options.checkCompleteness),checkLifecycle:Boolean(options.checkLifecycle),checkStaleBlockers:Boolean(options.checkStaleBlockers),dependencyCycleSeverity:readOptionString(options,"dependencyCycleSeverity"),parentCycleSeverity:readOptionString(options,"parentCycleSeverity"),checkFiles:Boolean(options.checkFiles),checkCommandReferences:Boolean(options.checkCommandReferences),scanMode:readOptionString(options,"scanMode"),includePmInternals:Boolean(options.includePmInternals),verboseFileLists:Boolean(options.verboseFileLists),verboseDiagnostics:Boolean(options.verboseDiagnostics),allAffectedIds:Boolean(options.allAffectedIds),checkHistoryDrift:Boolean(options.checkHistoryDrift),checkStorageIntegrity:Boolean(options.checkStorageIntegrity),fixHints:Boolean(options.fixHints),autoFix:Boolean(options.autoFix),dryRun:Boolean(options.dryRun),fixScope:Array.isArray(options.fixScope)?options.fixScope:void 0,pruneMissing:Boolean(options.pruneMissing),counts:Boolean(options.counts),full:Boolean(options.full)},globalOptions);printResult(result,globalOptions);const strictExit=Boolean(options.strictExit)||Boolean(options.failOnWarn);if(strictExit&&(result.has_warnings||!result.ok)){setActiveCommandResult({...result,exit_code:EXIT_CODE.GENERIC_FAILURE,error_code:"validation_findings",error_category:"validation",command_resolution:"validation_findings",resolution_stage:"execute"});process.exitCode=EXIT_CODE.GENERIC_FAILURE}if(globalOptions.profile){printError(`profile:command=validate took_ms=${Date.now()-startedAt}`)}}async function runGcAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runGc(globalOptions,{dryRun:options.dryRun===true,scope:Array.isArray(options.scope)?options.scope:[]});printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=gc took_ms=${Date.now()-startedAt}`)}}async function runWorkspaceSnapshotAction(action,target,options,command){const globalOptions=getGlobalOptions(command);const pmRoot=resolvePmRoot(process.cwd(),globalOptions.path);const normalizedAction=action.trim().toLowerCase();if(!WORKSPACE_SNAPSHOT_ACTIONS.some(entry=>entry===normalizedAction)){throw createUnknownSubcommandError({command_path:"workspace snapshot",token:action,allowed:WORKSPACE_SNAPSHOT_ACTIONS,display_name:"workspace snapshot",token_kind:"action",examples:["pm workspace snapshot create before-migration","pm workspace snapshot restore before-migration"]})}if(normalizedAction==="list"){printResult(await listWorkspaceSnapshots(pmRoot),globalOptions);return}if(normalizedAction==="create"){printResult(await createWorkspaceSnapshot(pmRoot,target===void 0?{}:{name:target}),globalOptions);return}if(target===void 0){throw new PmCliError(`pm workspace snapshot ${normalizedAction} requires a snapshot name or fingerprint`,EXIT_CODE.USAGE)}if(normalizedAction==="inspect"){printResult(await inspectWorkspaceSnapshot(pmRoot,target),globalOptions);return}if(normalizedAction==="restore"){if(options.dryRun===true){printResult(await planWorkspaceSnapshotRestore(pmRoot,target),globalOptions);return}const settings=await readSettings(pmRoot);printResult(await restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:options.force===true,author:resolveAuthor(readOptionString(options,"author"),settings.author_default),message:readOptionString(options,"message"),lockTtlSeconds:settings.locks.ttl_seconds,lockWaitMs:settings.locks.wait_ms}),globalOptions);return}printResult(await deleteWorkspaceSnapshot(pmRoot,target),globalOptions)}async function runWorkspacePositionAction(_options,command){const globalOptions=getGlobalOptions(command);printResult(await readWorkspacePosition(globalOptions),globalOptions)}async function runContractsAction(options,command){const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runContracts({action:readOptionString(options,"action"),command:readOptionString(options,"command"),summary:Boolean(options.summary),schemaOnly:Boolean(options.schemaOnly),flagsOnly:Boolean(options.flagsOnly),availabilityOnly:Boolean(options.availabilityOnly),runtimeOnly:Boolean(options.runtimeOnly)||Boolean(options.activeOnly),full:Boolean(options.full)},globalOptions);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=contracts took_ms=${Date.now()-startedAt}`)}}async function runClaimAction(id,options,command){if(options.start===true){requireClaimTarget(id,false);await runStartTaskAction(id,options,command);return}const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const lifecycleOptions={...buildLifecycleMutationOptions(options),ifAvailable:options.ifAvailable===true,maxAttempts:options.maxAttempts};requireClaimTarget(id,options.next===true);const result=options.next===true?await runClaimNext(Boolean(options.force),globalOptions,lifecycleOptions,{type:typeof options.type==="string"?options.type:void 0,tag:typeof options.tag==="string"?options.tag:void 0,priority:options.priority,assigneeFilter:typeof options.assigneeFilter==="string"?options.assigneeFilter:void 0,parent:typeof options.parent==="string"?options.parent:void 0,sprint:typeof options.sprint==="string"?options.sprint:void 0,release:typeof options.release==="string"?options.release:void 0,includeDecisions:options.includeDecisions===true,includeGates:options.includeGates===true,includeContainers:options.includeContainers===true,tokenBudget:options.tokenBudget??options.token_budget,explainRanking:options.explainRanking===true||options.explain_ranking===true}):await runClaim(id,Boolean(options.force),globalOptions,lifecycleOptions);await invalidateSearchCachesForMutation(globalOptions,result);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=claim took_ms=${Date.now()-startedAt}`)}}function requireClaimTarget(id,next){if(!next&&!id)throw new PmCliError("Specify an item id or pass --next",EXIT_CODE.USAGE);if(next&&id)throw new PmCliError("Specify either an item id or --next, not both",EXIT_CODE.USAGE)}async function runReleaseAction(id,options,command){if(options.pause===true){await runPauseTaskAction(id,options,command);return}const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runRelease(id,Boolean(options.force),globalOptions,{...buildLifecycleMutationOptions(options),ownershipReleaseBypass:options.ownershipReleaseBypass===true});await invalidateSearchCachesForMutation(globalOptions,result);printResult(await applyActiveCommandResultService("release",[id],options,globalOptions,result),globalOptions);if(globalOptions.profile){printError(`profile:command=release took_ms=${Date.now()-startedAt}`)}}async function printLifecycleAliasHint(command){const global2=getGlobalOptions(command);const alias=resolvePmCommandAlias(command.name());if(!alias||global2.json||global2.quiet)return;const settings=await readSettings(resolvePmRoot(process.cwd(),global2.path));if(settings.ux?.deprecation_hints)printError(renderPmCommandAliasMigrationHint(alias))}async function runStartTaskAction(id,options,command){await printLifecycleAliasHint(command);const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runStartTask(id,{...buildLifecycleMutationOptions(options),force:Boolean(options.force),next:options.next===true,ifAvailable:options.ifAvailable===true},globalOptions);await invalidateSearchCachesForMutation(globalOptions,result.update);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=start-task took_ms=${Date.now()-startedAt}`)}}async function runPauseTaskAction(id,options,command){await printLifecycleAliasHint(command);const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runPauseTask(id,{...buildLifecycleMutationOptions(options),force:Boolean(options.force)},globalOptions);await invalidateSearchCachesForMutation(globalOptions,result.release);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=pause-task took_ms=${Date.now()-startedAt}`)}}async function runCloseTaskAction(id,reason,options,command){await printLifecycleAliasHint(command);const globalOptions=getGlobalOptions(command);const startedAt=Date.now();const result=await runCloseTask(id,reason,{...buildLifecycleMutationOptions(options),validateClose:readOptionString(options,"validateClose"),force:Boolean(options.force)},globalOptions);await invalidateSearchCachesForMutation(globalOptions,result.release);printResult(result,globalOptions);if(globalOptions.profile){printError(`profile:command=close-task took_ms=${Date.now()-startedAt}`)}}function addLinkedTestExecutionOptions(command){return command.option("--background","Run linked tests in managed background mode").option("--timeout <seconds>","Default run timeout in seconds").option("--progress","Emit linked-test progress to stderr (always shown in TTY, opt-in for non-TTY)").option("--env-set <value>","Set environment variable(s) for linked-test runs (KEY=VALUE, repeatable)",collect).option("--env-clear <value>","Clear environment variable(s) for linked-test runs (NAME, repeatable)",collect).option("--shared-host-safe","Apply additive shared-host-safe runtime defaults for linked-test runs").option("--pm-context <mode>","PM linked-test context mode: schema|tracker|auto (default: schema)").option("--override-linked-pm-context","Force run-level --pm-context to override per-linked-test pm_context_mode metadata").option("--workspace-context <mode>","Source-workspace mode: source|isolated|snapshot (default: source)").option("--override-linked-workspace-context","Force run-level --workspace-context over per-linked-test metadata").option("--allow-untrusted-linked-tests","Execute untrusted linked commands when project policy also permits it").option("--fail-on-context-mismatch","Fail linked PM commands when context item counts differ").option("--fail-on-skipped","Treat skipped linked tests as dependency failures").option("--fail-on-empty-test-run","Treat successful linked-test commands that report zero executed tests as failures").option("--require-assertions-for-pm","Require assertion metadata for linked PM command tests").option("--check-context","Preflight linked PM command context diagnostics before executing commands").option("--auto-pm-context","Auto-remediate PM tracker-read context mismatches by routing those linked commands through tracker context")}function registerOperationCommands(program){registerAssuranceCommand(program);const testCommand=program.command("test").argument("<id>","Item id").option("--add <value>","Add verified isolated test (CSV/markdown or stdin)",collect).option("--add-json <value>","Add verified isolated test (JSON object/array or stdin)",collect).option("--remove <value>","Remove linked test entry by exact command/path (command=<value> and path=<value> preserve commas and equals signs; or - for stdin)",collect).option("--remove-index <n>","Remove the 1-based linked-test index from --list order (repeatable)",collect).option("--list","List linked tests without mutating").option("--run","Run linked test commands").option("--match <value>","Run only linked tests whose command/path contains this substring").option("--only-index <n>","Run only the 1-based linked-test index from --list order").option("--only-last","Run only the most recently added linked test");testCommand.option("--acknowledge-linked-tests","Trust the item's current linked commands in this clone without executing them");addLinkedTestExecutionOptions(testCommand).option("--measure <value>","Record name=value[,unit=...][,threshold=...] evidence; repeatable",collect).option("--metric-below <value>","Return evidence below name=value").option("--metric-diff <name>","Diff the latest two values").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force ownership override").description("Manage tests linked to an item and optionally run them.").action(runTestCommandAction);const testAllCommand=program.command("test-all").description("Run linked tests across matching items.").option("--status <value>","Filter items by status before running tests").option("--limit <n>","Limit matching items before running linked tests").option("--offset <n>","Skip matching items before running linked tests");addLinkedTestExecutionOptions(testAllCommand).action(runTestAllAction);program.command("test-runs-worker",{hidden:true}).argument("<runId>","Background run id").description("Internal background worker command.").action(async(runId,_options,command)=>{const globalOptions=getGlobalOptions(command);await runTestRunsWorker(runId,globalOptions)});program.command("telemetry").argument("[namespace-or-subcommand]","Telemetry subcommand: status, flush, stats, clear (default: status)").argument("[subcommand]","Compatibility alias target for local-analytics: status, flush, stats, clear").option("--limit <n>","Maximum command groups returned by telemetry stats").description("Inspect and manage local telemetry queue/runtime state.").action(runTelemetryAction);program.command("duplicates").description("Find duplicate clusters across all statuses.").option("--status <value>","Statuses (repeatable or comma-separated)",collect,[]).option("--since <value>","Created at or after this time").option("--threshold <value>","Minimum similarity (0-1)").option("--limit <n>","Maximum clusters").option("--exhaustive","Score all pairs within the safety bound").action(runDuplicatesAction);program.command("stats").description("Show project tracker statistics.").option("--include-empty","Restore zero-count registered item-type and lifecycle-status buckets").option("--storage","Include aggregate history-stream storage metrics (total streams/lines/bytes, largest + deepest streams, oldest/newest entries)").option("--metadata-coverage","Include metadata coverage % (acceptance_criteria, estimated_minutes, resolution, tags, parent) overall and by type").option("--by-assignee","Include a lifecycle-bucketed item breakdown grouped by assignee").option("--by-tag","Include a lifecycle-bucketed item breakdown grouped by tag").option("--by-priority","Include a lifecycle-bucketed item breakdown grouped by priority").option("--tag-prefix <value>","With --by-tag: only count tags starting with this prefix (e.g. domain:)").option("--field-utilization","Report content-field utilization rates (notes/learnings/files/docs/tests/comments/deps/body) for governance analysis").option("--analytics <json>","Improvement ledger/history analytics JSON").action(runStatsAction);program.command("health").description("Show project tracker health checks.").option("--strict-directories","Treat optional item-type directories as required failures").option("--require-merge-drivers","Treat absent clone-local merge drivers as a required health failure").option("--check-only","Run read-only health diagnostics without refreshing vectors").option("--check-telemetry","Probe telemetry endpoint health and include network diagnostics").option("--no-refresh","Disable automatic vector refresh attempts during health checks").option("--refresh-vectors","Explicitly enable vector refresh attempts during health checks").option("--verbose-stale-items","Include full stale vectorization ID lists in health output").option("--verbose-author-events","Include every actionable unknown-author event coordinate for review or disposition").option("--brief","Emit compact health details for low-token agent checks").option("--summary","Emit one-line-style health status with check names and warning count").option("--skip-vectors","Skip vectorization check for a faster run").option("--skip-integrity","Skip item/history file integrity check for a faster run").option("--skip-drift","Skip history drift hash check for a faster run").option("--full","Run all checks including slow integrity, drift, and vectorization checks").option("--strict-exit","Return non-zero exit when health is not ok and default to actionable summary output; use --full for complete details").option("--fail-on-warn","Alias for --strict-exit").action(runHealthAction);program.command("validate").description("Validate metadata, lifecycle policies, files, command references, and history.").option("--check-metadata","Run metadata completeness checks").option("--metadata-profile <value>","Metadata profile (core|strict|custom)").option("--check-resolution","Run closed-item resolution metadata checks").option("--check-completeness","Check declarative lifecycle field requirements").option("--check-lifecycle","Run active-item lifecycle governance drift checks").option("--check-stale-blockers","Include stale blocker-pattern diagnostics in lifecycle checks").option("--dependency-cycle-severity <value>","Set dependency-cycle warning policy for lifecycle checks (off|warn|error)").option("--parent-cycle-severity <value>","Set parent-hierarchy cycle warning policy for lifecycle checks (off|warn|error)").option("--check-files","Run linked-file and orphaned-file checks").option("--check-command-references","Run linked-command PM-ID reference checks").option("--scan-mode <value>","Select file candidate scan mode for --check-files (default|tracked-all|tracked-all-strict)").option("--include-pm-internals","Include PM storage internals in tracked-all candidate scans").option("--verbose-file-lists","Include full file-path lists for validate --check-files details").option("--verbose-diagnostics","Include full diagnostic ID lists").option("--all-affected-ids","Emit complete missing_* affected-ID lists with no truncation (implied by --json)").option("--strict-exit","Return non-zero exit when validation warnings are present").option("--fail-on-warn","Alias for --strict-exit").option("--fix-hints","Add a machine-executable fix_hints[] of pm commands to each failing check's details").option("--auto-fix","Apply safe, deterministic field backfills").option("--dry-run","Preview planned --auto-fix/--prune-missing fixes without applying them").option("--fix-scope <scope>","Grant --auto-fix scopes (metadata, resolution, estimates, timestamps, lifecycle; comma-separated or repeatable). Default: metadata, resolution; other scopes require explicit opt-in",collect).option("--prune-missing","Remove deleted-path file/doc links; preserves real files").option("--check-history-drift","Run item/history hash drift checks").option("--check-storage-integrity","Run the post-merge storage-integrity check (unreadable items, history conflict markers, resurrected deletes, unparseable config/schema)").option("--counts","Keep validation counts and totals while omitting per-item diagnostic arrays").option("--full","Return the complete validation diagnostic projection").action(runValidateAction);program.command("gc").option("--dry-run","Preview cleanup targets without deleting files; without this flag, pm gc deletes matched artifacts").option("--scope <value>","Limit cleanup to one or more scopes (comma-separated or repeatable): index, embeddings, runtime, locks, checkpoints, transactions",collect).description("Delete optional cache artifacts by default (including expired lock debris) and show a summary.").action(runGcAction);const workspaceCommand=program.command("workspace").description("Inspect workspace state and snapshots.");workspaceCommand.command("position").description("Show merge and history readiness.").action(runWorkspacePositionAction);workspaceCommand.command("snapshot").argument("<action>","Action: create, list, inspect, restore, delete").argument("[target]","Optional name for create; name or fingerprint otherwise").description("Manage content-addressed tracker snapshots.").option("--dry-run","Preview restore file, item, stream, and history-entry impact without mutating state").option("--force","Explicitly confirm a whole-workspace snapshot restore").option("--author <value>","Actor recorded on the restore audit event").option("--message <value>","Human-readable restore rationale").action(runWorkspaceSnapshotAction);program.command("contracts").description("Show machine-readable command and schema contracts for agents.").option("--action <value>","Filter tool schema branches to a specific action").option("--command <value>","Scope contracts output to one CLI command (narrow-by-default)").option("--summary","Return one command+intent row per top-level command for cheap agent bootstrap").option("--schema-only","Return schema-focused output only").option("--flags-only","Return command flag contracts only").option("--availability-only","Return action availability surface only").option("--runtime-only","Include only actions invocable in the current runtime").option("--active-only","Alias for --runtime-only").option("--full","Include full schema and command-flag surfaces (large; default brief output omits heavy sections for unfiltered queries)").action(runContractsAction);const claimCommand=program.command("claim").option("--start","Claim and start an explicit item").argument("[id]","Item id (omit with --next)").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force claim override").option("--if-available","Skip another author's claim (skipped=true)").option("--next","Atomically claim the next caller-available actionable item").option("--type <value>","Filter --next candidates by type").option("--tag <value>","Filter --next candidates by tag").option("--priority <value>","Filter --next candidates by priority").option("--assignee-filter <value>","Filter --next candidates: assigned|unassigned").option("--parent <id>","Scope --next candidates to a subtree").option("--sprint <value>","Filter --next candidates by sprint").option("--release <value>","Filter --next candidates by release").option("--max-attempts <n>","Bound the --next candidate walk (default 10; maximum 100)").option("--include-decisions","Allow --next to claim human-gated Decision items").option("--include-gates","Allow --next to claim outcome gates").option("--include-containers","Allow --next to claim containers with unfinished descendants").option("--token-budget <n>","Bound the estimated tokens used to rank --next candidates").option("--explain-ranking","Include ranking provenance for --next selection").description("Claim an item for active work.").action(runClaimAction);addHiddenOption(claimCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");addHiddenOption(claimCommand,"--token_budget <n>","Alias for --token-budget");addHiddenOption(claimCommand,"--explain_ranking","Alias for --explain-ranking");const releaseCommand=program.command("release").option("--pause","Use open status").argument("<id>","Item id").option("--author <value>","Author").option("--message <value>","Message").option("--force","Override ownership").description("Release ownership.").action(runReleaseAction);addHiddenOption(releaseCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");const startTaskCommand=program.command("start-task",{hidden:true}).argument("<id>","Item id").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force ownership or terminal override when required").description("Lifecycle alias: claim an item and move it to in_progress.").action(runStartTaskAction);addHiddenOption(startTaskCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");const pauseTaskCommand=program.command("pause-task",{hidden:true}).argument("<id>","Item id").option("--author <value>","Mutation author").option("--message <value>","History message").option("--force","Force ownership override when required").description("Lifecycle alias: move an item to open and release its claim.").action(runPauseTaskAction);addHiddenOption(pauseTaskCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands");const closeTaskCommand=program.command("close-task",{hidden:true}).argument("<id>","Item id").argument("[reason]","Close reason text").option("--author <value>","Mutation author").option("--message <value>","History message").option("--validate-close <value>","Close-time validation mode: off|warn|strict").option("--force","Force ownership or terminal override when required").description("Lifecycle alias: close an item and release assignment metadata.").action(runCloseTaskAction);addHiddenOption(closeTaskCommand,"--assignee <value>","Alias for --author on lifecycle ownership commands")}export{_testOnlyRegisterOperations,registerOperationCommands,requireClaimTarget};
 //# sourceMappingURL=register-operations.js.map

package/dist/cli/runtime/activation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module cli/runtime/activation
+ * Selects extension activation from static contributions and the requested command path.
+ */
+import { Command } from "commander";
+import { type ExtensionDiscoveryResult } from "../../sdk/runtime-primitives.js";
+/** Normalized command path, arguments and provided options used to select extension activation without importing extension code. */
+interface RuntimeExtensionActivationProbe {
+    commandPath?: string;
+    commandArgs?: string[];
+    allowCommandPrefixMatch?: boolean;
+}
+/** Collect positional words before the first option to probe the requested command path. */
+declare function collectLeadingCommandArgs(commandArgs: readonly string[] | undefined): string[];
+/** Match leading command paths against both native history spellings and stable extension operation identities. */
+declare function collectActivationCommandCandidates(probe: RuntimeExtensionActivationProbe): string[];
+/** Compare an extension activation command with the normalized invocation probe. */
+declare function activationCommandMatchesProbe(command: string, probe: RuntimeExtensionActivationProbe): boolean;
+/** Read and normalize the command paths declared by an extension activation manifest. */
+declare function extensionActivationCommands(extension: ExtensionDiscoveryResult["effective"][number]): string[];
+/** Collect the capabilities declared by one discovered extension. */
+declare function extensionCapabilities(extension: ExtensionDiscoveryResult["effective"][number]): Set<string>;
+/** Test whether any declared capability belongs to the capability family required by an invocation. */
+declare function hasAnyCapability(capabilities: Set<string>, expected: Set<string>): boolean;
+/** Identify command paths that require search provider or vector-store registrations. */
+declare function commandPathNeedsSearchExtensions(commandPath: string | undefined): boolean;
+/** Check the provided invocation flags against one activation-sensitive flag family. */
+declare function probeUsesAnyFlag(probe: RuntimeExtensionActivationProbe, flags: Set<string>): boolean;
+/** Identify invocations that consume extension-provided create templates. */
+declare function commandPathNeedsTemplateExtensions(probe: RuntimeExtensionActivationProbe): boolean;
+/** Recognize runtime template contributions that require extension activation. */
+declare function extensionProvidesTemplatesRuntime(commands: readonly string[]): boolean;
+/** Match direct command paths plus the built-in create-template bridge. */
+declare function matchesStaticExtensionCommand(commands: readonly string[], probe: RuntimeExtensionActivationProbe): boolean;
+/** Identify contribution surfaces that participate in global runtime behavior. */
+declare function hasGlobalExtensionContributions(contributions: NonNullable<ExtensionDiscoveryResult["effective"][number]["contributions"]>): boolean;
+/** Resolve an exact activation verdict from declared commands and contributions. */
+declare function resolveStaticExtensionActivationDecision(extension: ExtensionDiscoveryResult["effective"][number], probe: RuntimeExtensionActivationProbe): boolean | undefined;
+/** Combine static contributions and capability fallbacks to decide whether one extension must activate. */
+declare function extensionNeedsActivationForProbe(extension: ExtensionDiscoveryResult["effective"][number], probe: RuntimeExtensionActivationProbe): boolean;
+/** Decide whether installed providers must activate for a targeted invocation or complete command discovery. */
+declare function discoveryNeedsActivationForProbe(discovery: ExtensionDiscoveryResult, probe: RuntimeExtensionActivationProbe): boolean;
+/** Build a deterministic activation scope; completion and unconstrained discovery include every installed command provider. */
+declare function buildRuntimeExtensionActivationScope(probe: RuntimeExtensionActivationProbe): string;
+/** Create the loader predicate for extensions needed by the current invocation. */
+declare function buildRuntimeExtensionFilterForProbe(probe: RuntimeExtensionActivationProbe): ((extension: ExtensionDiscoveryResult["effective"][number]) => boolean) | undefined;
+/** Build an activation probe from bootstrap argv before Commander registration. */
+declare function buildBootstrapActivationProbe(invocationArgv: string[]): RuntimeExtensionActivationProbe;
+/** Collect the command arguments retained by Commander for an activation probe. */
+declare function collectParsedActivationCommandArgs(command: Command): string[];
+export { RuntimeExtensionActivationProbe, activationCommandMatchesProbe, buildBootstrapActivationProbe, buildRuntimeExtensionActivationScope, buildRuntimeExtensionFilterForProbe, collectActivationCommandCandidates, collectLeadingCommandArgs, collectParsedActivationCommandArgs, commandPathNeedsSearchExtensions, commandPathNeedsTemplateExtensions, discoveryNeedsActivationForProbe, extensionActivationCommands, extensionCapabilities, extensionNeedsActivationForProbe, extensionProvidesTemplatesRuntime, hasAnyCapability, hasGlobalExtensionContributions, matchesStaticExtensionCommand, probeUsesAnyFlag, resolveStaticExtensionActivationDecision };

package/dist/cli/runtime/activation.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="697f96fe-38a0-5530-b54b-22cb442c130f")}catch(e2){}})();import{resolvePmCommandOperation}from"../../sdk/cli-contracts/command-aliases.js";import{parseBootstrapHelpRequest,stripGlobalBootstrapTokens}from"../bootstrap-args.js";import{normalizeExtensionCommandPath}from"../extension-command-help.js";import{getCommandPath}from"../registration-helpers.js";function collectLeadingCommandArgs(commandArgs){const leading=[];for(const arg of commandArgs??[]){if(arg.startsWith("-")){break}const normalized=normalizeExtensionCommandPath(arg);if(normalized.length===0){continue}leading.push(normalized)}return leading}function collectActivationCommandCandidates(probe){const commandPath=normalizeExtensionCommandPath(probe.commandPath??"");if(commandPath.length===0){return[]}const candidates=[commandPath];const parts=commandPath.split(" ").filter(part=>part.length>0);for(const arg of collectLeadingCommandArgs(probe.commandArgs)){parts.push(...arg.split(" ").filter(part=>part.length>0));candidates.push(parts.join(" "))}return[...new Set(candidates.flatMap(candidate=>[candidate,resolvePmCommandOperation(candidate)]))]}function activationCommandMatchesProbe(command,probe){const normalized=normalizeExtensionCommandPath(command);if(normalized.length===0){return false}const candidates=collectActivationCommandCandidates(probe);for(const candidate of candidates){if(candidate===normalized||candidate.startsWith(`${normalized} `)){return true}}if(probe.allowCommandPrefixMatch===true){return candidates.some(candidate=>normalized.startsWith(`${candidate} `))}return false}function extensionActivationCommands(extension){const explicitCommands=extension.activation?.commands;if(explicitCommands){return explicitCommands}const contributions=extension.contributions;if(!contributions){return[]}return[...entriesOrEmpty(contributions.commands),...entriesOrEmpty(contributions.command_handlers),...entriesOrEmpty(contributions.command_overrides),...entriesOrEmpty(contributions.flag_commands),...entriesOrEmpty(contributions.parser_overrides),...ownershipCommands(contributions.preflight_ownership),...ownershipCommands(contributions.renderer_ownership)]}function entriesOrEmpty(entries){return entries??[]}function ownershipCommands(entries){return entriesOrEmpty(entries).flatMap(entry=>entry.commands)}function extensionCapabilities(extension){return new Set((extension.capabilities??[]).map(capability=>capability.trim().toLowerCase()))}const GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES=new Set(["hooks","parser","preflight","renderers"]);const CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES=new Set(["commands","schema","services","importers"]);const SEARCH_EXTENSION_ACTIVATION_COMMANDS=new Set(["reindex","search","search-advanced"]);const CREATE_TEMPLATE_FLAGS=new Set(["--template"]);function hasAnyCapability(capabilities,expected){for(const capability of expected){if(capabilities.has(capability)){return true}}return false}function commandPathNeedsSearchExtensions(commandPath){const normalized=normalizeExtensionCommandPath(commandPath??"");if(normalized.length===0){return false}const[topLevel]=normalized.split(" ");return SEARCH_EXTENSION_ACTIVATION_COMMANDS.has(topLevel??normalized)}function probeUsesAnyFlag(probe,flags){for(const arg of probe.commandArgs??[]){if(!arg.startsWith("--")){continue}const[flagName]=arg.split("=",1);if(flags.has(flagName)){return true}}return false}function commandPathNeedsTemplateExtensions(probe){return normalizeExtensionCommandPath(probe.commandPath??"")==="create"&&probeUsesAnyFlag(probe,CREATE_TEMPLATE_FLAGS)}function extensionProvidesTemplatesRuntime(commands){return commands.some(command=>{const normalized=normalizeExtensionCommandPath(command);return normalized==="templates"||normalized.startsWith("templates ")})}function matchesStaticExtensionCommand(commands,probe){return commands.some(command=>activationCommandMatchesProbe(command,probe))||commandPathNeedsTemplateExtensions(probe)&&extensionProvidesTemplatesRuntime(commands)}function hasGlobalExtensionContributions(contributions){const contributionCounts=[entriesOrEmpty(contributions.hooks).length,(contributions.preflight_overrides??0)-entriesOrEmpty(contributions.preflight_ownership).length,entriesOrEmpty(contributions.item_types).length,entriesOrEmpty(contributions.item_fields).length,entriesOrEmpty(contributions.relationship_kinds).length,entriesOrEmpty(contributions.service_overrides).length,entriesOrEmpty(contributions.assurance_providers).length,entriesOrEmpty(contributions.renderer_overrides).length-entriesOrEmpty(contributions.renderer_ownership).length];return contributionCounts.some(count=>count>0)}function resolveStaticExtensionActivationDecision(extension,probe){const explicitCommands=extension.activation?.commands??[];if(explicitCommands.length>0){return matchesStaticExtensionCommand(explicitCommands,probe)}const commands=extensionActivationCommands(extension);if(matchesStaticExtensionCommand(commands,probe))return true;if(extensionCapabilities(extension).has("search")&&commandPathNeedsSearchExtensions(probe.commandPath)){return true}if(extension.contributions){return hasGlobalExtensionContributions(extension.contributions)}return void 0}function extensionNeedsActivationForProbe(extension,probe){const staticDecision=resolveStaticExtensionActivationDecision(extension,probe);if(staticDecision!==void 0)return staticDecision;const capabilities=extensionCapabilities(extension);if(hasAnyCapability(capabilities,GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES)){return true}if(hasAnyCapability(capabilities,CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES)){return true}return false}function discoveryNeedsActivationForProbe(discovery,probe){if(discovery.effective.length===0){return false}const hasCommandProbe=buildRuntimeExtensionActivationScope(probe)!=="all";if(!hasCommandProbe){return discovery.effective.some(extension=>{const capabilities=extensionCapabilities(extension);return extensionActivationCommands(extension).length>0||hasAnyCapability(capabilities,GLOBAL_EXTENSION_ACTIVATION_CAPABILITIES)||hasAnyCapability(capabilities,CONSERVATIVE_EXTENSION_ACTIVATION_CAPABILITIES)||capabilities.has("search")})}return discovery.effective.some(extension=>extensionNeedsActivationForProbe(extension,probe))}function buildRuntimeExtensionActivationScope(probe){if(normalizeExtensionCommandPath(probe.commandPath??"").split(" ")[0]==="completion"){return"all"}const commandPath=collectActivationCommandCandidates(probe).filter(candidate=>candidate.split(" ").every(part=>!part.startsWith("-"))).sort((left,right)=>right.length-left.length)[0]??normalizeExtensionCommandPath(probe.commandPath??"");if(commandPath.length===0){return"all"}const args=commandPathNeedsTemplateExtensions(probe)?"--template":"";const prefix=probe.allowCommandPrefixMatch===true?"prefix":"exact";return`${prefix}:${commandPath}:${args}`}function buildRuntimeExtensionFilterForProbe(probe){return buildRuntimeExtensionActivationScope(probe)==="all"?void 0:extension=>extensionNeedsActivationForProbe(extension,probe)}function buildBootstrapActivationProbe(invocationArgv){const helpRequest=parseBootstrapHelpRequest(invocationArgv);if(helpRequest.requested&&helpRequest.commandPathTokens.length>0){const[commandPath,...commandArgs]=helpRequest.commandPathTokens;return{commandPath,commandArgs,allowCommandPrefixMatch:true}}const stripped=stripGlobalBootstrapTokens(invocationArgv);const commandIndex=stripped.findIndex(token=>token.trim().length>0&&!token.startsWith("-"));if(commandIndex<0){return{}}return{commandPath:stripped[commandIndex],commandArgs:stripped.slice(commandIndex+1),allowCommandPrefixMatch:helpRequest.requested}}function collectParsedActivationCommandArgs(command){const commandArgs=command.args.map(String);const commandPath=normalizeExtensionCommandPath(getCommandPath(command));if(commandPath==="create"){const options=command.optsWithGlobals();if(typeof options.template==="string"&&options.template.trim().length>0){commandArgs.push("--template")}}return commandArgs}export{activationCommandMatchesProbe,buildBootstrapActivationProbe,buildRuntimeExtensionActivationScope,buildRuntimeExtensionFilterForProbe,collectActivationCommandCandidates,collectLeadingCommandArgs,collectParsedActivationCommandArgs,commandPathNeedsSearchExtensions,commandPathNeedsTemplateExtensions,discoveryNeedsActivationForProbe,extensionActivationCommands,extensionCapabilities,extensionNeedsActivationForProbe,extensionProvidesTemplatesRuntime,hasAnyCapability,hasGlobalExtensionContributions,matchesStaticExtensionCommand,probeUsesAnyFlag,resolveStaticExtensionActivationDecision};
+//# sourceMappingURL=activation.js.map

package/dist/cli/runtime/invocation-options.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module cli/runtime/invocation-options
+ * Preserves global-option boundaries, contributed flag schemas and read-output provenance.
+ */
+import { Command } from "commander";
+import { type FlagDefinition, type GlobalOptions, createEmptyExtensionRegistrationRegistry } from "../../sdk/runtime-primitives.js";
+import { type ExtensionCommandHelpDescriptor } from "../extension-command-help.js";
+import { type LooseCommandFlagDefinition } from "../extension-command-options.js";
+/** Record the exact compatibility flags present in the raw CLI invocation. */
+declare function recordCliReadOutputInvocationProvenance(actionCommand: Command, commandPath: string, commandOptions: Record<string, unknown>): void;
+/**
+ * Hand canonical `--output-include` projection modes to the command that owns
+ * them, leaving only field selectors for post-execution projection.
+ *
+ * `--output-include brief` must be the exact behaviour of `--brief`, which the
+ * emitted migration hint promises; a mode can only be honoured before the
+ * command computes its rows, so it cannot be resolved by the output layer.
+ */
+declare function forwardReadOutputIncludeModes(actionCommand: Command, commandPath: string, globalOptions: GlobalOptions, commandOptions: Record<string, unknown>): void;
+/** Separate handler options from global controls, then validate and coerce contributed flags against the command's declared schema. */
+declare function extractCommandScopedOptions(command: Command, commandArgs: string[], extensionFlagDefinitions?: LooseCommandFlagDefinition[]): Record<string, unknown>;
+/** Join contributed flags by stable operation identity so canonical and compatibility command paths share the same schema. */
+declare function collectExtensionFlagDefinitionsForCommand(registrations: ReturnType<typeof createEmptyExtensionRegistrationRegistry>, commandPath: string): FlagDefinition[];
+/** Collect contributed flag definitions for the command paths traversed by this invocation. */
+declare function collectExtensionFlagDefinitionsForInvocation(registrations: ReturnType<typeof createEmptyExtensionRegistrationRegistry>, commandPath: string, commandArgs: string[]): FlagDefinition[];
+/** Read contributed positional argument definitions for a dynamic command. */
+declare function dynamicCommandArguments(descriptor: ExtensionCommandHelpDescriptor): ExtensionCommandHelpDescriptor["arguments"];
+/**
+ * Reports whether {@link commandPath} is the generated command path of a
+ * registered importer (`<name> import`) or exporter (`<name> export`). Importers
+ * and exporters read/write a source/destination via flags and take no positional
+ * operand, so an unexpected positional is a usage error; free-form
+ * `registerCommand` commands intentionally accept positionals via `context.args`
+ * and are excluded.
+ */
+declare function isImporterOrExporterCommandPath(registrations: ReturnType<typeof createEmptyExtensionRegistrationRegistry> | null, commandPath: string): boolean;
+/** Reject missing required or excess positional arguments before invoking a contributed handler. */
+declare function validateDynamicExtensionCommandArgs(descriptor: ExtensionCommandHelpDescriptor, args: string[]): void;
+/** Validate contributed arguments and options together before extension dispatch. */
+declare function validateDynamicExtensionCommandInvocation(descriptor: ExtensionCommandHelpDescriptor | undefined, args: string[], options: Record<string, unknown>, extensionFlagDefinitions: LooseCommandFlagDefinition[]): void;
+export { collectExtensionFlagDefinitionsForCommand, collectExtensionFlagDefinitionsForInvocation, dynamicCommandArguments, extractCommandScopedOptions, forwardReadOutputIncludeModes, isImporterOrExporterCommandPath, recordCliReadOutputInvocationProvenance, validateDynamicExtensionCommandArgs, validateDynamicExtensionCommandInvocation };

package/dist/cli/runtime/invocation-options.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4584c97a-4e3c-551e-95a4-2f63a7fc152e")}catch(e2){}})();import{resolveSubcommandFlagContractsForCommand}from"../../sdk/cli-contracts.js";import{resolvePmCommandOperation}from"../../sdk/cli-contracts/command-aliases.js";import{PM_READ_OUTPUT_SURFACE_CONTRACTS,applyReadOutputIncludeModes,readOutputIncludeModeOptions,resolveReadOutputSurface}from"../../sdk/read-output-contracts.js";import{EXIT_CODE,PmCliError}from"../../sdk/runtime-primitives.js";import{extractProvidedOptionFlags}from"../argv-utils.js";import{normalizeExtensionCommandPath}from"../extension-command-help.js";import{coerceLooseCommandOptionsWithFlagDefinitions,collectLooseCommandOptionKeysForDefinitions,parseLooseCommandOptions,validateLooseCommandOptionsWithFlagDefinitions}from"../extension-command-options.js";import{getCommandPath,setResolvedGlobalOptions}from"../registration-helpers.js";const READ_OUTPUT_INVOCATION_PROVENANCE=Symbol.for("pm.readOutputInvocationProvenance");function copyReadOutputInvocationProvenance(source,target){const provenance=Reflect.get(source,READ_OUTPUT_INVOCATION_PROVENANCE);if(provenance!==void 0){Reflect.set(target,READ_OUTPUT_INVOCATION_PROVENANCE,provenance)}}function recordCliReadOutputInvocationProvenance(actionCommand,commandPath,commandOptions){const surface=resolveReadOutputSurface(commandPath,commandOptions);if(!surface)return;let rootCommand=actionCommand;while(rootCommand.parent)rootCommand=rootCommand.parent;const rawArgs=rootCommand.rawArgs;const providedFlags=new Set(extractProvidedOptionFlags(rawArgs.slice(2)));const contract=PM_READ_OUTPUT_SURFACE_CONTRACTS.find(candidate=>candidate.command===surface);const explicitLegacyAliases=Object.values(contract.dimensions).flatMap(dimension=>dimension.legacy_aliases.flatMap(alias=>providedFlags.has(alias.flag)?[alias.flag]:[]));const previous=Reflect.get(commandOptions,READ_OUTPUT_INVOCATION_PROVENANCE);Reflect.set(commandOptions,READ_OUTPUT_INVOCATION_PROVENANCE,{canonical_include_modes:previous?.canonical_include_modes??[],explicit_legacy_aliases:explicitLegacyAliases,cli_invocation_observed:true});copyReadOutputInvocationProvenance(commandOptions,actionCommand)}function forwardReadOutputIncludeModes(actionCommand,commandPath,globalOptions,commandOptions){recordCliReadOutputInvocationProvenance(actionCommand,commandPath,commandOptions);const requested=globalOptions.outputInclude;if(requested===void 0)return;const{selectors,modes}=applyReadOutputIncludeModes(commandPath,requested,commandOptions);if(commandPath==="get"&&typeof commandOptions.fields==="string"){actionCommand.setOptionValueWithSource("fields",commandOptions.fields,"cli")}if(modes.length===0)return;copyReadOutputInvocationProvenance(commandOptions,actionCommand);const modeOptions=readOutputIncludeModeOptions(commandPath);for(const mode of modes){const key=modeOptions.get(mode);const value=commandOptions[key];actionCommand.setOptionValueWithSource(key,value,"cli")}const residual=selectors.length>0?selectors.join(","):void 0;if(residual===void 0){delete globalOptions.outputInclude}else{globalOptions.outputInclude=residual}for(let scope=actionCommand;scope;scope=scope.parent){scope.setOptionValueWithSource("outputInclude",residual,"cli")}setResolvedGlobalOptions(actionCommand,globalOptions)}function collectCommandInvocationOptions(command){const allOptions=command.optsWithGlobals();const commandPath=getCommandPath(command);if(resolvePmCommandOperation(commandPath)===commandPath)return allOptions;const ownOptions=command.opts();for(let parent=command.parent;parent?.parent;parent=parent.parent){for(const key of Object.keys(parent.opts())){if(!(key in ownOptions)&&parent.getOptionValueSource(key)==="default")delete allOptions[key]}}return allOptions}function extractCommandScopedOptions(command,commandArgs,extensionFlagDefinitions=[]){const allOptions=collectCommandInvocationOptions(command);const scoped={...allOptions};copyReadOutputInvocationProvenance(command,scoped);delete scoped.json;delete scoped.quiet;delete scoped.path;delete scoped.pmPath;delete scoped.noExtensions;delete scoped.extensions;delete scoped.profile;delete scoped.pager;delete scoped.changedFields;delete scoped.fullChangedFields;delete scoped.idOnly;delete scoped.lean;delete scoped.tokenAccounting;delete scoped.outputInclude;delete scoped.outputLimit;delete scoped.outputBudget;delete scoped.outputFormat;delete scoped.outputSession;const looseOptions=parseLooseCommandOptions(commandArgs);for(const[key,value]of Object.entries(looseOptions)){if(scoped[key]===void 0){scoped[key]=value}}if(extensionFlagDefinitions.length>0){const extensionOptionKeys=collectLooseCommandOptionKeysForDefinitions(extensionFlagDefinitions);const coreFlagDefinitions=resolveSubcommandFlagContractsForCommand(getCommandPath(command)).map(contract=>({long:contract.flag,short:contract.short,aliases:contract.aliases}));const optionsToValidate={...looseOptions};for(const key of extensionOptionKeys){if(scoped[key]!==void 0){optionsToValidate[key]=scoped[key]}}validateLooseCommandOptionsWithFlagDefinitions(optionsToValidate,[...coreFlagDefinitions,...extensionFlagDefinitions],getCommandPath(command));return coerceLooseCommandOptionsWithFlagDefinitions(scoped,extensionFlagDefinitions,looseOptions)}return scoped}function collectExtensionFlagDefinitionsForCommand(registrations,commandPath){const normalizedCommandPath=normalizeExtensionCommandPath(commandPath);if(normalizedCommandPath.length===0){return[]}return registrations.flags.filter(entry=>resolvePmCommandOperation(normalizeExtensionCommandPath(entry.target_command))===resolvePmCommandOperation(normalizedCommandPath)).flatMap(entry=>entry.flags)}function collectExtensionFlagDefinitionsForInvocation(registrations,commandPath,commandArgs){const exact=collectExtensionFlagDefinitionsForCommand(registrations,commandPath);const pathParts=[commandPath];let nestedMatch=[];for(const arg of commandArgs){if(arg.startsWith("-")){break}pathParts.push(arg);const nested=collectExtensionFlagDefinitionsForCommand(registrations,pathParts.join(" "));if(nested.length>0){nestedMatch=nested}}return nestedMatch.length>0?nestedMatch:exact}function dynamicCommandArguments(descriptor){return descriptor.arguments??[]}function formatDynamicCommandUsage(descriptor){const argumentSuffix=dynamicCommandArguments(descriptor).map(argument=>{const label=argument.variadic?`${argument.name}...`:argument.name;return argument.required?`<${label}>`:`[${label}]`}).join(" ");return`pm ${descriptor.command}${argumentSuffix?` ${argumentSuffix}`:""}`}function isImporterOrExporterCommandPath(registrations,commandPath){if(!registrations){return false}const normalized=normalizeExtensionCommandPath(commandPath);return registrations.importers.some(entry=>normalizeExtensionCommandPath(`${entry.importer} import`)===normalized)||registrations.exporters.some(entry=>normalizeExtensionCommandPath(`${entry.exporter} export`)===normalized)}function validateDynamicExtensionCommandArgs(descriptor,args){const descriptorArguments=dynamicCommandArguments(descriptor);const requiredCount=descriptorArguments.filter(argument=>argument.required).length;const variadic=descriptorArguments.some(argument=>argument.variadic);const maxCount=variadic?Number.POSITIVE_INFINITY:descriptorArguments.length;const failureHints=descriptor.failure_hints??[];const hintSuffix=failureHints.length>0?` ${failureHints.join(" ")}`:"";if(args.length<requiredCount){throw new PmCliError(`Missing required argument for extension command '${descriptor.command}'. Usage: ${formatDynamicCommandUsage(descriptor)}${hintSuffix}`,EXIT_CODE.USAGE)}if(args.length>maxCount){const extra=args.slice(maxCount).join(" ");throw new PmCliError(`Too many arguments for extension command '${descriptor.command}': ${extra}. Usage: ${formatDynamicCommandUsage(descriptor)}${hintSuffix}`,EXIT_CODE.USAGE)}}function formatDynamicOptionFlag(optionKey){return`--${optionKey.replace(/([a-z0-9])([A-Z])/g,"$1-$2").replace(/_/g,"-").toLowerCase()}`}function validateDynamicExtensionCommandOptions(descriptor,options,extensionFlagDefinitions){if(extensionFlagDefinitions.length>0){validateLooseCommandOptionsWithFlagDefinitions(options,extensionFlagDefinitions,descriptor.command);return}const unknownOptions=Object.keys(options).filter(key=>options[key]!==void 0).sort();if(unknownOptions.length===0){return}throw new PmCliError(`Unknown option '${unknownOptions.map(formatDynamicOptionFlag).join(", ")}' for extension command '${descriptor.command}'. This command does not define extension flags.`,EXIT_CODE.USAGE)}function validateDynamicExtensionCommandInvocation(descriptor,args,options,extensionFlagDefinitions){if(!descriptor){return}validateDynamicExtensionCommandArgs(descriptor,args);validateDynamicExtensionCommandOptions(descriptor,options,extensionFlagDefinitions)}export{collectExtensionFlagDefinitionsForCommand,collectExtensionFlagDefinitionsForInvocation,dynamicCommandArguments,extractCommandScopedOptions,forwardReadOutputIncludeModes,isImporterOrExporterCommandPath,recordCliReadOutputInvocationProvenance,validateDynamicExtensionCommandArgs,validateDynamicExtensionCommandInvocation};
+//# sourceMappingURL=invocation-options.js.map

package/dist/cli/runtime/selection.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module cli/runtime/selection
+ * Selects core registration families and refuses implicit corrections of mutating flags.
+ */
+import { Command } from "commander";
+import { normalizeBootstrapInvocation } from "../bootstrap-args.js";
+/** Core read command names used to select the list/query registration family. */
+declare const LIST_QUERY_COMMAND_NAMES: Set<string>;
+/** Registration-family switches computed from one CLI invocation. */
+interface CoreCommandRegistrationSelection {
+    setup: boolean;
+    listQuery: boolean;
+    mutation: boolean;
+    operation: boolean;
+    targetCommandName?: string;
+}
+/** Recognize version requests before loading command families. */
+declare function invocationRequestsVersion(invocationArgv: string[]): boolean;
+/** Load only the selected core registration family, retaining complete discovery for help and unknown paths. */
+declare function resolveCoreCommandRegistrationSelection(invocationArgv: string[]): CoreCommandRegistrationSelection;
+/** Decide whether the invocation needs the expanded help text attached to registered commands. */
+declare function shouldAttachRichHelpTextForInvocation(invocationArgv: string[]): boolean;
+/** Decide whether extension command paths must be registered for this invocation. */
+declare function shouldRegisterDynamicExtensionPaths(_rootProgram: Command, invocationArgv: string[]): boolean;
+/** Decide whether the invocation needs flags supplied by the runtime item schema. */
+declare function shouldRegisterRuntimeSchemaFlags(invocationArgv: string[]): boolean;
+/** Refuse unknown flags with correction guidance while requiring an explicit retry for mutations. */
+declare function enforceExplicitRetryForFlagTypos(bootstrapInvocation: ReturnType<typeof normalizeBootstrapInvocation>): void;
+export { CoreCommandRegistrationSelection, LIST_QUERY_COMMAND_NAMES, enforceExplicitRetryForFlagTypos, invocationRequestsVersion, resolveCoreCommandRegistrationSelection, shouldAttachRichHelpTextForInvocation, shouldRegisterDynamicExtensionPaths, shouldRegisterRuntimeSchemaFlags };

package/dist/cli/runtime/selection.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4963b2d7-c720-51bb-a621-5f9d7e40b909")}catch(e2){}})();import{PM_RELOCATED_COMMAND_ALIASES,findPmNamespacedCommand}from"../../sdk/cli-contracts/command-aliases.js";import{EXIT_CODE,PmCliError}from"../../sdk/runtime-primitives.js";import{redactSensitiveCommandArgs,renderPmCommand}from"../argv-utils.js";import{parseBootstrapCommandName,parseBootstrapHelpRequest,stripGlobalBootstrapTokens}from"../bootstrap-args.js";import{isFullHelpDiscovery}from"../help-content.js";const VERSION_FLAG_TOKENS=new Set(["--version","-V"]);const SETUP_COMMAND_NAMES=new Set(["config","extension","init","install","package","packages","templates","upgrade"]);const LIST_QUERY_COMMAND_NAMES=new Set(["activity","aggregate","context","ctx","events","get","graph","history","list","list-all","list-blocked","list-canceled","list-closed","list-draft","list-in-progress","list-open","search"]);const MUTATION_COMMAND_NAMES=new Set(["append","close","close-many","comments","delete","deps","discover","docs","files","history-repair","history-redact","history-compact","learnings","notes","plan","restore","update","update-many","create"]);const OPERATION_COMMAND_NAMES=new Set(["claim","close-task","contracts","duplicates","gc","health","pause-task","release","start-task","stats","test","test-all","test-runs","test-runs-worker","validate"]);const MUTATING_OPERATION_COMMAND_NAMES=new Set(["claim","close-task","pause-task","release","start-task","test"]);const REGISTER_ALL_CORE_COMMAND_FAMILIES={setup:true,listQuery:true,mutation:true,operation:true};const RUNTIME_SCHEMA_FLAG_BOOTSTRAP_COMMANDS=new Set(["create","update","update-many","list","list-all","list-draft","list-open","list-in-progress","list-blocked","list-closed","list-canceled","search","calendar","context","templates"]);function invocationRequestsVersion(invocationArgv){return invocationArgv.some(token=>VERSION_FLAG_TOKENS.has(token))}function resolveCoreCommandRegistrationSelection(invocationArgv){if(invocationRequestsVersion(invocationArgv)){return{setup:false,listQuery:false,mutation:false,operation:false}}if(invocationArgv.length===0||parseBootstrapHelpRequest(invocationArgv).requested){return REGISTER_ALL_CORE_COMMAND_FAMILIES}const commandName=parseBootstrapCommandName(invocationArgv);if(!commandName){return REGISTER_ALL_CORE_COMMAND_FAMILIES}const normalizedCommand=commandName.trim().toLowerCase();const commandTokens=stripGlobalBootstrapTokens(invocationArgv);const semanticCommand=findPmNamespacedCommand(commandTokens)?.alias;if(PM_RELOCATED_COMMAND_ALIASES.some(alias=>alias.alias===semanticCommand)){return{...REGISTER_ALL_CORE_COMMAND_FAMILIES,targetCommandName:semanticCommand}}if(SETUP_COMMAND_NAMES.has(normalizedCommand)){return{setup:true,listQuery:false,mutation:false,operation:false,targetCommandName:normalizedCommand}}if(LIST_QUERY_COMMAND_NAMES.has(normalizedCommand)){return{setup:false,listQuery:true,mutation:false,operation:false,targetCommandName:normalizedCommand}}if(MUTATION_COMMAND_NAMES.has(normalizedCommand)){return{setup:false,listQuery:false,mutation:true,operation:false,targetCommandName:normalizedCommand}}if(OPERATION_COMMAND_NAMES.has(normalizedCommand)){return{setup:false,listQuery:false,mutation:false,operation:true,targetCommandName:normalizedCommand}}return REGISTER_ALL_CORE_COMMAND_FAMILIES}function shouldAttachRichHelpTextForInvocation(invocationArgv){return invocationArgv.length===0||parseBootstrapHelpRequest(invocationArgv).requested||invocationArgv.includes("--explain")&&parseBootstrapCommandName(invocationArgv)===void 0}function shouldRegisterDynamicExtensionPaths(_rootProgram,invocationArgv){if(invocationRequestsVersion(invocationArgv)){return false}if(isFullHelpDiscovery(invocationArgv)){return true}const helpRequest=parseBootstrapHelpRequest(invocationArgv);if(helpRequest.requested){return true}const commandName=parseBootstrapCommandName(invocationArgv);if(!commandName){return false}return true}function shouldRegisterRuntimeSchemaFlags(invocationArgv){if(invocationRequestsVersion(invocationArgv)){return false}const commandName=parseBootstrapCommandName(invocationArgv);if(!commandName){return false}return RUNTIME_SCHEMA_FLAG_BOOTSTRAP_COMMANDS.has(commandName)}function redactSensitiveFlagTypo(params){const rawTypoToken=String(params.rawFrom??"");const rawTypoEqualsIndex=rawTypoToken.indexOf("=");const rawTypoFlag=rawTypoEqualsIndex>=0?rawTypoToken.slice(0,rawTypoEqualsIndex):rawTypoToken;const sensitiveCanonicalFlag=params.normalizedTokens.map(token=>{const equalsIndex=token.indexOf("=");return equalsIndex>=0?token.slice(0,equalsIndex):token}).find(token=>token==="--literal"||token==="--regex"||token==="--replacement");const typoNormalizedArgv=sensitiveCanonicalFlag?params.argv.map(token=>{const equalsIndex=token.indexOf("=");const flag=equalsIndex>=0?token.slice(0,equalsIndex):token;return flag===rawTypoFlag?equalsIndex>=0?`${sensitiveCanonicalFlag}${token.slice(equalsIndex)}`:sensitiveCanonicalFlag:token}):params.argv;const safeArgv=redactSensitiveCommandArgs(typoNormalizedArgv);const safeTypoDisplay=sensitiveCanonicalFlag&&rawTypoEqualsIndex>=0?`${rawTypoFlag}=[redacted]`:rawTypoToken;const safeNormalizedDisplay=sensitiveCanonicalFlag&&params.normalizedDisplay.includes("=")?`${sensitiveCanonicalFlag}=[redacted]`:params.normalizedDisplay;return{argv:safeArgv,normalizedDisplay:safeNormalizedDisplay,sourceDisplay:safeTypoDisplay}}function enforceExplicitRetryForFlagTypos(bootstrapInvocation){const commandName=bootstrapInvocation.commandName;if(!commandName){return}const typoEvent=bootstrapInvocation.trace.find(entry=>entry.reason==="flag_typo");if(!typoEvent){return}const normalizedTokens=Array.isArray(typoEvent.to)?typoEvent.to:[String(typoEvent.to??"")].filter(entry=>entry.length>0);const normalizedDisplay=normalizedTokens.length>0?normalizedTokens.join(" "):"the canonical flag";const mutatingCommand=MUTATION_COMMAND_NAMES.has(commandName)||MUTATING_OPERATION_COMMAND_NAMES.has(commandName);const code=mutatingCommand?"mutating_flag_typo_requires_retry":"flag_typo_requires_retry";const commandScope=mutatingCommand?"mutating option":"option";const safeTypo=redactSensitiveFlagTypo({argv:bootstrapInvocation.argv,normalizedDisplay,normalizedTokens,rawFrom:typoEvent.from});throw new PmCliError(`Refusing to auto-correct ${commandScope} ${safeTypo.sourceDisplay} to ${safeTypo.normalizedDisplay}. Retry with the canonical flag so the command is explicit.`,EXIT_CODE.USAGE,{code,examples:[renderPmCommand(safeTypo.argv)],nextSteps:["Retry the command with the canonical flag shown in examples."],recovery:{normalized_args:safeTypo.argv,suggested_retry:renderPmCommand(safeTypo.argv)}})}export{LIST_QUERY_COMMAND_NAMES,enforceExplicitRetryForFlagTypos,invocationRequestsVersion,resolveCoreCommandRegistrationSelection,shouldAttachRichHelpTextForInvocation,shouldRegisterDynamicExtensionPaths,shouldRegisterRuntimeSchemaFlags};
+//# sourceMappingURL=selection.js.map

package/dist/cli/runtime/telemetry-outcome.d.ts

@@ -0,0 +1,20 @@
+import { type TelemetryCommandOutcome, type TelemetryCommandResolution, type TelemetryErrorCategory, type TelemetryResolutionStage } from "../../sdk/runtime-primitives.js";
+/** Read a string-valued field from a structured command result without coercion. */
+declare function readRecordString(record: Record<string, unknown> | null, ...keys: string[]): string | undefined;
+/** Read a boolean-valued field from a structured command result without coercion. */
+declare function readRecordBoolean(record: Record<string, unknown> | null, ...keys: string[]): boolean | undefined;
+/** Read a number-valued field from a structured command result without coercion. */
+declare function readRecordNumber(record: Record<string, unknown> | null, ...keys: string[]): number | undefined;
+/** Accept only declared command-resolution values for telemetry receipts. */
+declare function normalizeTelemetryCommandResolution(value: string | undefined): TelemetryCommandResolution | undefined;
+/** Accept only declared resolution-stage values for telemetry receipts. */
+declare function normalizeTelemetryResolutionStage(value: string | undefined): TelemetryResolutionStage | undefined;
+/** Accept only declared error-category values for telemetry receipts. */
+declare function normalizeTelemetryErrorCategory(value: string | undefined): TelemetryErrorCategory | undefined;
+/** Derive a completion failure message from the command result and process outcome. */
+declare function inferPostActionFailureMessage(result: Record<string, unknown> | null): string | undefined;
+/** Derive the canonical completion error code from the structured result. */
+declare function inferPostActionErrorCode(ok: boolean, exitCode: number): string | undefined;
+/** Combine structured command receipts and exit state into a terminal telemetry outcome. */
+declare function buildPostActionTelemetryOutcome(): TelemetryCommandOutcome;
+export { buildPostActionTelemetryOutcome, inferPostActionErrorCode, inferPostActionFailureMessage, normalizeTelemetryCommandResolution, normalizeTelemetryErrorCategory, normalizeTelemetryResolutionStage, readRecordBoolean, readRecordNumber, readRecordString };

package/dist/cli/runtime/telemetry-outcome.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="afcf2608-3360-5030-b5ea-b101df5829e7")}catch(e2){}})();import{isPmSuccessfulExitCode}from"../../sdk/cli-contracts/command-exit-contracts.js";import{EXIT_CODE,asRecordOrNull,deriveTelemetryCommandResolution,getActiveCommandResult,resolveTelemetryErrorCategory}from"../../sdk/runtime-primitives.js";const TELEMETRY_COMMAND_RESOLUTION_SET=new Set(["success","nonexistent_command","invalid_option","missing_required_option","missing_required_argument","invalid_usage","validation_failed","health_findings","validation_findings","conflict","runtime_failed","unknown_failed"]);const TELEMETRY_RESOLUTION_STAGE_SET=new Set(["parse","preflight","execute","unknown"]);const TELEMETRY_ERROR_CATEGORY_SET=new Set(["usage","validation","conflict","runtime","unknown"]);function readRecordString(record,...keys){if(!record){return void 0}for(const key of keys){const candidate=record[key];if(typeof candidate==="string"){const normalized=candidate.trim();if(normalized.length>0){return normalized}}}return void 0}function readRecordBoolean(record,...keys){if(!record){return void 0}for(const key of keys){const candidate=record[key];if(typeof candidate==="boolean"){return candidate}}return void 0}function readRecordNumber(record,...keys){if(!record){return void 0}for(const key of keys){const candidate=record[key];if(typeof candidate==="number"&&Number.isFinite(candidate)){return Math.max(0,Math.trunc(candidate))}}return void 0}function normalizeTelemetryCommandResolution(value){if(!value){return void 0}const normalized=value.trim().toLowerCase();if(!TELEMETRY_COMMAND_RESOLUTION_SET.has(normalized)){return void 0}return normalized}function normalizeTelemetryResolutionStage(value){if(!value){return void 0}const normalized=value.trim().toLowerCase();if(!TELEMETRY_RESOLUTION_STAGE_SET.has(normalized)){return void 0}return normalized}function normalizeTelemetryErrorCategory(value){if(!value){return void 0}const normalized=value.trim().toLowerCase();if(!TELEMETRY_ERROR_CATEGORY_SET.has(normalized)){return void 0}return normalized}function inferPostActionFailureMessage(result){const explicit=readRecordString(result,"error","message");if(explicit){return explicit}const warnings=result?.warnings;if(Array.isArray(warnings)){const firstWarning=warnings.find(value=>typeof value==="string"&&value.trim().length>0);if(typeof firstWarning==="string"){return firstWarning.trim()}}const skippedTriggered=readRecordBoolean(result,"fail_on_skipped_triggered","failOnSkippedTriggered");if(skippedTriggered){return"linked_test_fail_on_skipped_triggered"}const failedCount=readRecordNumber(result,"failed");if(typeof failedCount==="number"&&failedCount>0){return`failed_runs:${failedCount}`}const runResults=result?.run_results;if(Array.isArray(runResults)){const failedRuns=runResults.filter(entry=>{const row=asRecordOrNull(entry);return row?.status==="failed"}).length;if(failedRuns>0){return`failed_runs:${failedRuns}`}}return void 0}function inferPostActionErrorCode(ok,exitCode){if(ok){return void 0}if(exitCode===EXIT_CODE.USAGE){return"invalid_command_usage"}if(exitCode===EXIT_CODE.NOT_FOUND){return"item_not_found"}if(exitCode===EXIT_CODE.CONFLICT){return"lock_conflict"}if(exitCode===EXIT_CODE.DEPENDENCY_FAILED){return"dependency_failed"}return"command_failed"}function buildPostActionTelemetryOutcome(){const result=asRecordOrNull(getActiveCommandResult());const processExitCode=typeof process.exitCode==="number"&&Number.isFinite(process.exitCode)?Math.max(0,Math.trunc(process.exitCode)):void 0;const resultExitCode=readRecordNumber(result,"exit_code","exitCode");const exitCode=processExitCode??resultExitCode??EXIT_CODE.SUCCESS;const ok=isPmSuccessfulExitCode(exitCode);const errorCode=readRecordString(result,"error_code","errorCode")??inferPostActionErrorCode(ok,exitCode);const errorCategory=normalizeTelemetryErrorCategory(readRecordString(result,"error_category","errorCategory"))??(!ok?resolveTelemetryErrorCategory(errorCode):void 0);const errorMessage=!ok?inferPostActionFailureMessage(result)??`command_exit_${exitCode}`:void 0;const commandResolution=normalizeTelemetryCommandResolution(readRecordString(result,"command_resolution","commandResolution"))??deriveTelemetryCommandResolution({ok,errorCode,errorCategory});const resolutionStage=normalizeTelemetryResolutionStage(readRecordString(result,"resolution_stage","resolutionStage"))??"execute";return{ok,error:errorMessage,exit_code:exitCode,error_code:errorCode,error_category:errorCategory,command_resolution:commandResolution,resolution_stage:resolutionStage}}export{buildPostActionTelemetryOutcome,inferPostActionErrorCode,inferPostActionFailureMessage,normalizeTelemetryCommandResolution,normalizeTelemetryErrorCategory,normalizeTelemetryResolutionStage,readRecordBoolean,readRecordNumber,readRecordString};
+//# sourceMappingURL=telemetry-outcome.js.map