@unbrained/pm-cli 2026.5.31 → 2026.6.5

package/dist/cli/commands/contracts.js

@@ -1,5 +1,5 @@
 
-!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]="478936e5-660a-5f89-b15d-93b37468c7ed")}catch(e){}}();
+!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]="1a1d092a-4cf8-54c6-aa4c-6a0b22690558")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { activateExtensions, getActiveExtensionRegistrations, loadExtensions, } from "../../core/extensions/index.js";
@@ -8,7 +8,7 @@ import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTyp
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
-import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMMENTS_AUDIT_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DEDUPE_AUDIT_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, } from "../../sdk/cli-contracts.js";
+import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMMENTS_AUDIT_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DEDUPE_AUDIT_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, NORMALIZE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, } from "../../sdk/cli-contracts.js";
 const LIST_COMMAND_NAMES = new Set([
     "list",
     "list-all",
@@ -41,7 +41,9 @@ const PACKAGE_OWNED_COMMANDS = new Set([
     "calendar",
     "comments-audit",
     "completion",
+    "completion-statuses",
     "completion-tags",
+    "completion-types",
     "dedupe-audit",
     "guide",
     "normalize",
@@ -62,7 +64,9 @@ const PACKAGE_OWNED_COMMAND_INSTALL_HINTS = new Map([
     ["calendar", "calendar"],
     ["comments-audit", "governance-audit"],
     ["completion", "guide-shell"],
+    ["completion-statuses", "guide-shell"],
     ["completion-tags", "guide-shell"],
+    ["completion-types", "guide-shell"],
     ["dedupe-audit", "governance-audit"],
     ["guide", "guide-shell"],
     ["normalize", "governance-audit"],
@@ -78,6 +82,24 @@ const PACKAGE_OWNED_COMMAND_INSTALL_HINTS = new Map([
     ["test-runs stop", "linked-test-adapters"],
     ["test-runs resume", "linked-test-adapters"],
 ]);
+const PACKAGE_OWNED_ACTION_COMMAND_PATHS = new Map([
+    ["calendar", "calendar|cal"],
+    ["dedupe-audit", "dedupe-audit"],
+    ["guide", "guide"],
+    ["reindex", "reindex"],
+    ["normalize", "normalize"],
+    ["comments-audit", "comments-audit"],
+    ["completion", "completion"],
+    ["test-runs-list", "test-runs|test-runs list"],
+    ["test-runs-status", "test-runs status"],
+    ["test-runs-logs", "test-runs logs"],
+    ["test-runs-stop", "test-runs stop"],
+    ["test-runs-resume", "test-runs resume"],
+    ["templates-list", "templates|templates list"],
+    ["templates-save", "templates save"],
+    ["templates-show", "templates show"],
+]);
+const PACKAGE_OWNED_COMMAND_ACTIONS = new Map([...PACKAGE_OWNED_ACTION_COMMAND_PATHS.entries()].flatMap(([action, commandPaths]) => splitCommandPathAliases(commandPaths).map((commandPath) => [commandPath, action])));
 const CANONICAL_COMMAND_ALIASES = [
     {
         canonical: "context",
@@ -89,6 +111,94 @@ const CANONICAL_COMMAND_ALIASES = [
     },
 ];
 const COMMAND_ALIAS_TO_CANONICAL = new Map(CANONICAL_COMMAND_ALIASES.flatMap((entry) => entry.aliases.map((alias) => [alias, entry.canonical])));
+const EXTENSION_PACKAGE_LIFECYCLE_FLAG_CONTRACTS = [
+    ["init", EXTENSION_INIT_FLAG_CONTRACTS],
+    ["install", EXTENSION_INSTALL_FLAG_CONTRACTS],
+    ["uninstall", EXTENSION_UNINSTALL_FLAG_CONTRACTS],
+    ["explore", EXTENSION_EXPLORE_FLAG_CONTRACTS],
+    ["manage", EXTENSION_MANAGE_FLAG_CONTRACTS],
+    ["reload", EXTENSION_RELOAD_FLAG_CONTRACTS],
+    ["doctor", EXTENSION_DOCTOR_FLAG_CONTRACTS],
+    ["catalog", EXTENSION_CATALOG_FLAG_CONTRACTS],
+    ["adopt", EXTENSION_ADOPT_FLAG_CONTRACTS],
+    ["adopt-all", EXTENSION_ADOPT_ALL_FLAG_CONTRACTS],
+    ["activate", EXTENSION_ACTIVATE_FLAG_CONTRACTS],
+    ["deactivate", EXTENSION_DEACTIVATE_FLAG_CONTRACTS],
+];
+const CORE_COMMAND_FLAG_CONTRACT_ENTRIES = [
+    ...EXTENSION_PACKAGE_LIFECYCLE_FLAG_CONTRACTS.flatMap(([subcommand, flags]) => [
+        [`extension ${subcommand}`, flags],
+        [`package ${subcommand}`, flags],
+        [`packages ${subcommand}`, flags],
+    ]),
+    ["init", INIT_FLAG_CONTRACTS],
+    ["config", CONFIG_FLAG_CONTRACTS],
+    ["extension", EXTENSION_FLAG_CONTRACTS],
+    ["package", EXTENSION_FLAG_CONTRACTS],
+    ["packages", EXTENSION_FLAG_CONTRACTS],
+    ["install", INSTALL_FLAG_CONTRACTS],
+    ["create", CREATE_FLAG_CONTRACTS],
+    ["update", UPDATE_FLAG_CONTRACTS],
+    ["update-many", UPDATE_MANY_FLAG_CONTRACTS],
+    ["upgrade", UPGRADE_FLAG_CONTRACTS],
+    ["normalize", NORMALIZE_FLAG_CONTRACTS],
+    ["calendar", CALENDAR_FLAG_CONTRACTS],
+    ["cal", CALENDAR_FLAG_CONTRACTS],
+    ["context", CONTEXT_FLAG_CONTRACTS],
+    ["ctx", CONTEXT_FLAG_CONTRACTS],
+    ["get", GET_FLAG_CONTRACTS],
+    ["search", SEARCH_FLAG_CONTRACTS],
+    ["aggregate", AGGREGATE_FLAG_CONTRACTS],
+    ["dedupe-audit", DEDUPE_AUDIT_FLAG_CONTRACTS],
+    ["deps", DEPS_FLAG_CONTRACTS],
+    ["guide", GUIDE_FLAG_CONTRACTS],
+    ["reindex", REINDEX_FLAG_CONTRACTS],
+    ["history", HISTORY_FLAG_CONTRACTS],
+    ["history-redact", HISTORY_REDACT_FLAG_CONTRACTS],
+    ["history-repair", HISTORY_REPAIR_FLAG_CONTRACTS],
+    ["schema", SCHEMA_FLAG_CONTRACTS],
+    ["plan", PLAN_FLAG_CONTRACTS],
+    ["restore", RESTORE_FLAG_CONTRACTS],
+    ["delete", DELETE_FLAG_CONTRACTS],
+    ["close", CLOSE_FLAG_CONTRACTS],
+    ["close-many", CLOSE_MANY_FLAG_CONTRACTS],
+    ["append", APPEND_FLAG_CONTRACTS],
+    ["claim", CLAIM_FLAG_CONTRACTS],
+    ["release", RELEASE_FLAG_CONTRACTS],
+    ["start-task", START_TASK_FLAG_CONTRACTS],
+    ["pause-task", PAUSE_TASK_FLAG_CONTRACTS],
+    ["close-task", CLOSE_TASK_FLAG_CONTRACTS],
+    ["comments", COMMENTS_FLAG_CONTRACTS],
+    ["notes", NOTES_FLAG_CONTRACTS],
+    ["learnings", LEARNINGS_FLAG_CONTRACTS],
+    ["files", FILES_FLAG_CONTRACTS],
+    ["docs", DOCS_FLAG_CONTRACTS],
+    ["test", TEST_FLAG_CONTRACTS],
+    ["test-all", TEST_ALL_FLAG_CONTRACTS],
+    ["test-runs", TEST_RUNS_FLAG_CONTRACTS],
+    ["gc", GC_FLAG_CONTRACTS],
+    ["validate", VALIDATE_FLAG_CONTRACTS],
+    ["comments-audit", COMMENTS_AUDIT_FLAG_CONTRACTS],
+    ["health", HEALTH_FLAG_CONTRACTS],
+    ["contracts", CONTRACTS_FLAG_CONTRACTS],
+    ["completion", COMPLETION_FLAG_CONTRACTS],
+    ["activity", ACTIVITY_FLAG_CONTRACTS],
+    ...[...LIST_COMMAND_NAMES].map((command) => [command, LIST_FILTER_FLAG_CONTRACTS]),
+];
+const CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map(CORE_COMMAND_FLAG_CONTRACT_ENTRIES);
+function packageOwnedActionForCommand(command) {
+    const exactAction = PACKAGE_OWNED_COMMAND_ACTIONS.get(command);
+    if (exactAction) {
+        return exactAction;
+    }
+    if (command.startsWith("test-runs ")) {
+        return `test-runs-${command.slice("test-runs ".length)}`;
+    }
+    if (command.startsWith("templates ")) {
+        return `templates-${command.slice("templates ".length)}`;
+    }
+    return command;
+}
 function resolveActionCommandPath(action) {
     if (PM_CORE_COMMAND_NAMES.includes(action)) {
         return normalizeCommandPath(action);
@@ -105,6 +215,9 @@ function resolveActionCommandPath(action) {
     if (action.startsWith("templates-")) {
         return normalizeCommandPath(`templates ${action.slice("templates-".length)}`);
     }
+    if (PACKAGE_OWNED_ACTIONS.has(action)) {
+        return PACKAGE_OWNED_ACTION_COMMAND_PATHS.get(action) ?? normalizeCommandPath(action);
+    }
     return null;
 }
 function actionDescriptorMatchesSelectedCommand(descriptor, selectedCommand) {
@@ -585,20 +698,34 @@ async function resolveRuntimeExtensionActionProbe(global) {
         };
     }
 }
-function collectActionContractDescriptors(extensionContracts) {
+function collectActionContractDescriptors(extensionContracts, options = {}) {
     const descriptors = new Map();
     for (const action of PM_TOOL_ACTIONS) {
-        if (PACKAGE_OWNED_ACTIONS.has(action)) {
+        const packageOwned = PACKAGE_OWNED_ACTIONS.has(action);
+        if (packageOwned && !options.includePackageOwnedActions) {
             continue;
         }
         const commandPath = resolveActionCommandPath(action);
         descriptors.set(action, {
             action,
-            provider: "core",
-            requires_extension: false,
+            provider: packageOwned ? "extension" : "core",
+            requires_extension: packageOwned,
             command_path: commandPath,
         });
     }
+    if (options.includePackageOwnedActions) {
+        for (const action of PACKAGE_OWNED_ACTIONS) {
+            if (descriptors.has(action)) {
+                continue;
+            }
+            descriptors.set(action, {
+                action,
+                provider: "extension",
+                requires_extension: true,
+                command_path: resolveActionCommandPath(action),
+            });
+        }
+    }
     for (const contract of extensionContracts) {
         if (descriptors.has(contract.action)) {
             continue;
@@ -629,6 +756,9 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
         ? splitCommandPathAliases(descriptor.command_path)
         : [];
     const extensionCommandAvailable = commandPaths.some((commandPath) => runtimeProbe.handlers.has(commandPath));
+    const optionalPackageHint = commandPaths
+        .map((commandPath) => PACKAGE_OWNED_COMMAND_INSTALL_HINTS.get(commandPath))
+        .find((hint) => typeof hint === "string");
     const invocable = runtimeProbe.disabledReason === null && extensionCommandAvailable;
     return {
         action: descriptor.action,
@@ -638,7 +768,7 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
         provider: "extension",
         disabled_reason: invocable
             ? null
-            : (runtimeProbe.disabledReason ?? "extension_command_not_registered"),
+            : (runtimeProbe.disabledReason ?? (optionalPackageHint ? `optional_package_not_installed:${optionalPackageHint}` : "extension_command_not_registered")),
         command_path: descriptor.command_path,
         cli_exposed: extensionCommandAvailable,
         policy_state: {
@@ -649,153 +779,13 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
     };
 }
 function resolveCoreCommandFlags(command) {
-    if (command === "init") {
-        return INIT_FLAG_CONTRACTS;
-    }
-    if (command === "config") {
-        return CONFIG_FLAG_CONTRACTS;
-    }
-    if (command === "extension" ||
-        command === "package" ||
-        command === "packages") {
-        return EXTENSION_FLAG_CONTRACTS;
-    }
-    if (command === "install") {
-        return INSTALL_FLAG_CONTRACTS;
-    }
-    if (command === "create") {
-        return CREATE_FLAG_CONTRACTS;
-    }
-    if (command === "update") {
-        return UPDATE_FLAG_CONTRACTS;
-    }
-    if (command === "update-many") {
-        return UPDATE_MANY_FLAG_CONTRACTS;
-    }
-    if (command === "upgrade") {
-        return UPGRADE_FLAG_CONTRACTS;
-    }
-    if (command === "normalize") {
-        return NORMALIZE_FLAG_CONTRACTS;
-    }
-    if (command === "calendar" || command === "cal") {
-        return CALENDAR_FLAG_CONTRACTS;
-    }
-    if (command === "context" || command === "ctx") {
-        return CONTEXT_FLAG_CONTRACTS;
-    }
-    if (command === "get") {
-        return GET_FLAG_CONTRACTS;
-    }
-    if (command === "search") {
-        return SEARCH_FLAG_CONTRACTS;
-    }
-    if (command === "aggregate") {
-        return AGGREGATE_FLAG_CONTRACTS;
-    }
-    if (command === "dedupe-audit") {
-        return DEDUPE_AUDIT_FLAG_CONTRACTS;
-    }
-    if (command === "deps") {
-        return DEPS_FLAG_CONTRACTS;
-    }
-    if (command === "guide") {
-        return GUIDE_FLAG_CONTRACTS;
-    }
-    if (command === "reindex") {
-        return REINDEX_FLAG_CONTRACTS;
-    }
-    if (command === "history") {
-        return HISTORY_FLAG_CONTRACTS;
-    }
-    if (command === "history-redact") {
-        return HISTORY_REDACT_FLAG_CONTRACTS;
-    }
-    if (command === "history-repair") {
-        return HISTORY_REPAIR_FLAG_CONTRACTS;
-    }
-    if (command === "schema") {
-        return SCHEMA_FLAG_CONTRACTS;
-    }
-    if (command === "plan") {
-        return PLAN_FLAG_CONTRACTS;
-    }
-    if (command === "restore") {
-        return RESTORE_FLAG_CONTRACTS;
-    }
-    if (command === "delete") {
-        return DELETE_FLAG_CONTRACTS;
-    }
-    if (command === "close") {
-        return CLOSE_FLAG_CONTRACTS;
-    }
-    if (command === "append") {
-        return APPEND_FLAG_CONTRACTS;
-    }
-    if (command === "claim") {
-        return CLAIM_FLAG_CONTRACTS;
-    }
-    if (command === "release") {
-        return RELEASE_FLAG_CONTRACTS;
-    }
-    if (command === "start-task") {
-        return START_TASK_FLAG_CONTRACTS;
-    }
-    if (command === "pause-task") {
-        return PAUSE_TASK_FLAG_CONTRACTS;
-    }
-    if (command === "close-task") {
-        return CLOSE_TASK_FLAG_CONTRACTS;
-    }
-    if (command === "comments") {
-        return COMMENTS_FLAG_CONTRACTS;
-    }
-    if (command === "notes") {
-        return NOTES_FLAG_CONTRACTS;
-    }
-    if (command === "learnings") {
-        return LEARNINGS_FLAG_CONTRACTS;
-    }
-    if (command === "files") {
-        return FILES_FLAG_CONTRACTS;
-    }
-    if (command === "docs") {
-        return DOCS_FLAG_CONTRACTS;
-    }
-    if (command === "test") {
-        return TEST_FLAG_CONTRACTS;
-    }
-    if (command === "test-all") {
-        return TEST_ALL_FLAG_CONTRACTS;
-    }
-    if (command === "test-runs") {
-        return TEST_RUNS_FLAG_CONTRACTS;
-    }
-    if (command === "gc") {
-        return GC_FLAG_CONTRACTS;
-    }
-    if (command === "validate") {
-        return VALIDATE_FLAG_CONTRACTS;
-    }
-    if (command === "comments-audit") {
-        return COMMENTS_AUDIT_FLAG_CONTRACTS;
-    }
-    if (command === "health") {
-        return HEALTH_FLAG_CONTRACTS;
-    }
-    if (command === "contracts") {
-        return CONTRACTS_FLAG_CONTRACTS;
-    }
-    if (command === "completion") {
-        return COMPLETION_FLAG_CONTRACTS;
-    }
-    if (command === "activity") {
-        return ACTIVITY_FLAG_CONTRACTS;
-    }
-    if (LIST_COMMAND_NAMES.has(command)) {
-        return LIST_FILTER_FLAG_CONTRACTS;
+    return CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.get(command) ?? GLOBAL_FLAG_CONTRACTS;
+}
+function isCoreCommandPath(command) {
+    if (PACKAGE_OWNED_COMMANDS.has(command)) {
+        return false;
     }
-    return GLOBAL_FLAG_CONTRACTS;
+    return CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.has(command);
 }
 function normalizeCommandForRuntimeFieldFlags(command) {
     if (LIST_COMMAND_NAMES.has(command)) {
@@ -808,7 +798,7 @@ function normalizeCommandForRuntimeFieldFlags(command) {
         return "context";
     }
     if (command === "update-many") {
-        return "update";
+        return "update_many";
     }
     return command;
 }
@@ -897,7 +887,7 @@ function mergeFlagContracts(primary, secondary) {
 function buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap) {
     return commands
         .map((command) => {
-        const isCoreCommand = PM_CORE_COMMAND_NAMES.includes(command) && !PACKAGE_OWNED_COMMANDS.has(command);
+        const isCoreCommand = isCoreCommandPath(command);
         const coreFlags = isCoreCommand ? resolveCoreCommandFlags(command) : [];
         const runtimeFlags = runtimeFieldFlagMap.get(normalizeCommandForRuntimeFieldFlags(command)) ?? [];
         const extensionFlags = extensionFlagMap.get(command);
@@ -1068,7 +1058,20 @@ export async function runContracts(options, global) {
     const extensionContracts = collectExtensionCommandContracts(runtimeProbe);
     const mergedExtensionContracts = mergeExtensionContractsByAction(extensionContracts);
     const extensionFlagMap = collectExtensionFlagContractsByCommand(runtimeProbe.flagRegistrations);
-    const actionDescriptors = collectActionContractDescriptors(mergedExtensionContracts);
+    const includePackageOwnedActions = (selectedAction !== undefined && PACKAGE_OWNED_ACTIONS.has(selectedAction) && availabilityOnly) ||
+        (selectedCommand !== undefined && PACKAGE_OWNED_COMMANDS.has(selectedCommand) && availabilityOnly);
+    const actionDescriptors = collectActionContractDescriptors(mergedExtensionContracts, { includePackageOwnedActions });
+    if (includePackageOwnedActions &&
+        selectedCommand !== undefined &&
+        PACKAGE_OWNED_COMMANDS.has(selectedCommand) &&
+        !actionDescriptors.some((entry) => entry.command_path === selectedCommand)) {
+        actionDescriptors.push({
+            action: packageOwnedActionForCommand(selectedCommand),
+            provider: "extension",
+            requires_extension: true,
+            command_path: selectedCommand,
+        });
+    }
     const actionNames = new Set(actionDescriptors.map((entry) => entry.action));
     if (selectedAction && !actionNames.has(selectedAction)) {
         throw new PmCliError(`Unknown action: "${options.action}".`, EXIT_CODE.USAGE);
@@ -1076,6 +1079,8 @@ export async function runContracts(options, global) {
     const commandCatalog = [
         ...new Set([
             ...PM_CORE_COMMAND_NAMES.filter((entry) => !PACKAGE_OWNED_COMMANDS.has(entry)),
+            ...[...CORE_COMMAND_FLAG_CONTRACTS_BY_COMMAND.keys()].filter((entry) => !PACKAGE_OWNED_COMMANDS.has(entry)),
+            ...actionDescriptors.flatMap((entry) => entry.command_path ? splitCommandPathAliases(entry.command_path) : []),
             ...mergedExtensionContracts.flatMap((entry) => entry.command.split("|")),
         ]),
     ]
@@ -1087,6 +1092,9 @@ export async function runContracts(options, global) {
         const packageHint = PACKAGE_OWNED_COMMAND_INSTALL_HINTS.get(selectedCommand);
         if (packageHint) {
             throw new PmCliError(`Unknown command: "${options.command}". Command "${selectedCommand}" is provided by the optional "${packageHint}" package. Run "pm install ${packageHint} --project" and retry.`, EXIT_CODE.USAGE, {
+                code: "unknown_command",
+                required: `Install the optional "${packageHint}" package, or choose a command from pm contracts --flags-only --json.`,
+                why: "Command contracts include core commands plus commands registered by active packages and extensions.",
                 examples: [`pm install ${packageHint} --project`, `pm contracts --command ${selectedCommand} --flags-only --json`],
                 nextSteps: [`Install the optional package first: pm install ${packageHint} --project`],
                 recovery: {
@@ -1094,10 +1102,24 @@ export async function runContracts(options, global) {
                 },
             });
         }
-        throw new PmCliError(`Unknown command: "${options.command}".`, EXIT_CODE.USAGE);
+        throw new PmCliError(`Unknown command: "${options.command}".`, EXIT_CODE.USAGE, {
+            code: "unknown_command",
+            required: "Use a command path listed by pm contracts --flags-only --json.",
+            why: "Command contracts are generated from the active core, package, and extension command registry.",
+            examples: ["pm contracts --flags-only --json", "pm --help"],
+            nextSteps: ["Verify spelling and active packages/extensions, then rerun with a known command path."],
+            recovery: {
+                suggested_retry: "pm contracts --flags-only --json",
+            },
+        });
     }
+    const selectedPackageOwnedAction = selectedCommand
+        ? PACKAGE_OWNED_COMMAND_ACTIONS.get(selectedCommand)
+        : undefined;
     const commandScopedDescriptors = selectedCommand
-        ? actionDescriptors.filter((descriptor) => actionDescriptorMatchesSelectedCommand(descriptor, selectedCommand))
+        ? actionDescriptors.filter((descriptor) => selectedPackageOwnedAction
+            ? descriptor.action === selectedPackageOwnedAction
+            : actionDescriptorMatchesSelectedCommand(descriptor, selectedCommand))
         : actionDescriptors;
     if (selectedCommand &&
         selectedAction &&
@@ -1132,11 +1154,18 @@ export async function runContracts(options, global) {
     const scopedActionDescriptors = selectedAction
         ? commandScopedDescriptors.filter((descriptor) => descriptor.action === selectedAction)
         : commandScopedDescriptors;
-    const allActionAvailability = scopedActionDescriptors.map((descriptor) => resolveActionAvailability(descriptor, runtimeProbe));
-    const actionAvailability = runtimeOnly && !selectedAction
+    const allActionAvailability = [
+        ...new Map(scopedActionDescriptors
+            .map((descriptor) => resolveActionAvailability(descriptor, runtimeProbe))
+            .map((entry) => [
+            selectedPackageOwnedAction ? entry.action : `${entry.action}|${entry.command_path ?? ""}`,
+            entry,
+        ])).values(),
+    ];
+    const actionAvailability = runtimeOnly && !selectedAction && !availabilityOnly
         ? allActionAvailability.filter((entry) => entry.invocable)
         : allActionAvailability;
-    const actions = actionAvailability.map((entry) => entry.action);
+    const actions = [...new Set(actionAvailability.map((entry) => entry.action))];
     const descriptorActionSet = new Set(actionDescriptors.map((descriptor) => descriptor.action));
     let filteredSchema = selectedAction
         ? filterSchemaByAction(mergedSchema, selectedAction)
@@ -1246,4 +1275,4 @@ export async function runContracts(options, global) {
     return result;
 }
 //# sourceMappingURL=contracts.js.map
-//# debugId=478936e5-660a-5f89-b15d-93b37468c7ed
+//# debugId=1a1d092a-4cf8-54c6-aa4c-6a0b22690558