@unbrained/pm-cli 2026.5.14 → 2026.5.24

package/dist/cli/commands/contracts.js

@@ -1,12 +1,14 @@
+
+!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){}}();
 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";
+import { activateExtensions, getActiveExtensionRegistrations, loadExtensions, } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
-import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, } from "../../core/item/type-registry.js";
 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, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_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, PM_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_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, 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";
 const LIST_COMMAND_NAMES = new Set([
     "list",
     "list-all",
@@ -55,6 +57,38 @@ const PACKAGE_OWNED_COMMANDS = new Set([
     "test-runs stop",
     "test-runs resume",
 ]);
+const PACKAGE_OWNED_COMMAND_INSTALL_HINTS = new Map([
+    ["cal", "calendar"],
+    ["calendar", "calendar"],
+    ["comments-audit", "governance-audit"],
+    ["completion", "guide-shell"],
+    ["completion-tags", "guide-shell"],
+    ["dedupe-audit", "governance-audit"],
+    ["guide", "guide-shell"],
+    ["normalize", "governance-audit"],
+    ["reindex", "search-advanced"],
+    ["templates", "templates"],
+    ["templates list", "templates"],
+    ["templates save", "templates"],
+    ["templates show", "templates"],
+    ["test-runs", "linked-test-adapters"],
+    ["test-runs list", "linked-test-adapters"],
+    ["test-runs status", "linked-test-adapters"],
+    ["test-runs logs", "linked-test-adapters"],
+    ["test-runs stop", "linked-test-adapters"],
+    ["test-runs resume", "linked-test-adapters"],
+]);
+const CANONICAL_COMMAND_ALIASES = [
+    {
+        canonical: "context",
+        aliases: ["ctx"],
+    },
+    {
+        canonical: "package",
+        aliases: ["extension", "packages", "install"],
+    },
+];
+const COMMAND_ALIAS_TO_CANONICAL = new Map(CANONICAL_COMMAND_ALIASES.flatMap((entry) => entry.aliases.map((alias) => [alias, entry.canonical])));
 function resolveActionCommandPath(action) {
     if (PM_CORE_COMMAND_NAMES.includes(action)) {
         return normalizeCommandPath(action);
@@ -77,11 +111,18 @@ function actionDescriptorMatchesSelectedCommand(descriptor, selectedCommand) {
     if (descriptor.command_path === null) {
         return false;
     }
-    const commandPath = normalizeCommandPath(descriptor.command_path);
-    if (commandPath === selectedCommand) {
-        return true;
-    }
-    return commandPath.startsWith(`${selectedCommand} `);
+    return splitCommandPathAliases(descriptor.command_path).some((commandPath) => {
+        if (commandPath === selectedCommand) {
+            return true;
+        }
+        return commandPath.startsWith(`${selectedCommand} `);
+    });
+}
+function splitCommandPathAliases(commandPath) {
+    return commandPath
+        .split("|")
+        .map((entry) => normalizeCommandPath(entry))
+        .filter((entry) => entry.length > 0);
 }
 function resolveScopedCommandsFromActionDescriptors(descriptors, commandCatalog) {
     const commandSet = new Set(commandCatalog);
@@ -90,18 +131,19 @@ function resolveScopedCommandsFromActionDescriptors(descriptors, commandCatalog)
         if (!descriptor.command_path) {
             continue;
         }
-        const commandPath = normalizeCommandPath(descriptor.command_path);
-        const tokens = commandPath.split(" ").filter((entry) => entry.length > 0);
-        if (tokens.length === 0) {
-            continue;
-        }
-        for (let end = tokens.length; end > 0; end -= 1) {
-            const candidate = tokens.slice(0, end).join(" ");
-            if (!commandSet.has(candidate)) {
+        for (const commandPath of splitCommandPathAliases(descriptor.command_path)) {
+            const tokens = commandPath.split(" ").filter((entry) => entry.length > 0);
+            if (tokens.length === 0) {
                 continue;
             }
-            scoped.add(candidate);
-            break;
+            for (let end = tokens.length; end > 0; end -= 1) {
+                const candidate = tokens.slice(0, end).join(" ");
+                if (!commandSet.has(candidate)) {
+                    continue;
+                }
+                scoped.add(candidate);
+                break;
+            }
         }
     }
     return [...scoped].sort((left, right) => left.localeCompare(right));
@@ -197,8 +239,12 @@ function normalizeStringList(values) {
 function toExtensionFlagContract(definition) {
     const longName = toOptionalTrimmedString(definition.long);
     const shortName = toOptionalTrimmedString(definition.short);
-    const normalizedLong = longName && longName.startsWith("--") && longName.length > 2 ? longName : null;
-    const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--") ? shortName : null;
+    const normalizedLong = longName && longName.startsWith("--") && longName.length > 2
+        ? longName
+        : null;
+    const normalizedShort = shortName && shortName.startsWith("-") && !shortName.startsWith("--")
+        ? shortName
+        : null;
     const flag = normalizedLong ?? normalizedShort;
     if (!flag) {
         return null;
@@ -207,6 +253,28 @@ function toExtensionFlagContract(definition) {
     if (normalizedShort && normalizedLong) {
         contract.short = normalizedShort;
     }
+    const description = toOptionalTrimmedString(definition.description);
+    if (description) {
+        contract.description = description;
+    }
+    if (definition.required === true) {
+        contract.required = true;
+    }
+    if (definition.repeatable === true) {
+        contract.repeatable = true;
+    }
+    const valueName = toOptionalTrimmedString(definition.value_name);
+    if (valueName) {
+        contract.value_name = valueName;
+    }
+    const rawValueType = [
+        toOptionalTrimmedString(definition.value_type),
+        toOptionalTrimmedString(definition.type),
+        valueName ? "string" : null,
+    ].find((candidate) => candidate === "string" || candidate === "number" || candidate === "boolean");
+    if (rawValueType) {
+        contract.value_type = rawValueType;
+    }
     return contract;
 }
 function collectExtensionFlagContractsByCommand(registrations) {
@@ -253,7 +321,7 @@ function collectExtensionFlagContractsByCommand(registrations) {
                 if (layerOrder !== 0) {
                     return layerOrder;
                 }
-                return left.name.localeCompare(right.name);
+                return (left.name ?? "").localeCompare(right.name ?? "");
             }),
         });
     }
@@ -267,7 +335,8 @@ function collectExtensionCommandContracts(runtimeProbe) {
         if (command.length === 0) {
             continue;
         }
-        const action = toOptionalTrimmedString(definition.action) ?? normalizeActionNameFromCommand(command);
+        const action = toOptionalTrimmedString(definition.action) ??
+            normalizeActionNameFromCommand(command);
         const args = Array.isArray(definition.arguments)
             ? definition.arguments
                 .map((argument) => {
@@ -315,7 +384,9 @@ function collectExtensionCommandContracts(runtimeProbe) {
         if (definition) {
             contracts.push({
                 ...definition,
-                flags: definition.flags.length > 0 ? definition.flags : flagsByCommand.get(command)?.flags ?? [],
+                flags: definition.flags.length > 0
+                    ? definition.flags
+                    : (flagsByCommand.get(command)?.flags ?? []),
             });
             continue;
         }
@@ -343,11 +414,17 @@ function extensionSchemaPropertyNameFromFlag(flag) {
     return cleaned.length > 0 ? cleaned : null;
 }
 function buildExtensionActionSchemaBranch(contract) {
+    const commands = contract.command
+        .split("|")
+        .map((command) => command.trim())
+        .filter((command) => command.length > 0);
     const properties = {
         action: {
             type: "string",
             const: contract.action,
-            description: contract.intent ?? contract.description ?? `Invoke extension command '${contract.command}'.`,
+            description: contract.intent ??
+                contract.description ??
+                `Invoke extension command '${contract.command}'.`,
         },
     };
     const required = ["action"];
@@ -356,13 +433,15 @@ function buildExtensionActionSchemaBranch(contract) {
             properties[argument.name] = {
                 type: "array",
                 items: { type: "string" },
-                description: argument.description ?? `Variadic argument '${argument.name}' for extension action '${contract.action}'.`,
+                description: argument.description ??
+                    `Variadic argument '${argument.name}' for extension action '${contract.action}'.`,
             };
         }
         else {
             properties[argument.name] = {
                 type: "string",
-                description: argument.description ?? `Argument '${argument.name}' for extension action '${contract.action}'.`,
+                description: argument.description ??
+                    `Argument '${argument.name}' for extension action '${contract.action}'.`,
             };
         }
         if (argument.required) {
@@ -374,11 +453,16 @@ function buildExtensionActionSchemaBranch(contract) {
         if (!propertyName || properties[propertyName] !== undefined) {
             continue;
         }
-        const isBooleanFlag = !flag.flag.includes(" ");
+        const valueType = flag.value_type ?? "boolean";
+        const schemaType = valueType === "boolean" ? "boolean" : valueType === "number" ? ["number", "string"] : "string";
         properties[propertyName] = {
-            type: isBooleanFlag ? ["boolean", "string"] : "string",
-            description: `Extension option '${flag.flag}' for action '${contract.action}'.`,
+            type: flag.repeatable ? "array" : schemaType,
+            ...(flag.repeatable ? { items: { type: schemaType } } : {}),
+            description: flag.description ?? `Extension option '${flag.flag}' for action '${contract.action}'.`,
         };
+        if (flag.required === true) {
+            required.push(propertyName);
+        }
     }
     return {
         type: "object",
@@ -386,9 +470,57 @@ function buildExtensionActionSchemaBranch(contract) {
         required,
         additionalProperties: true,
         "x-extension-source": contract.source,
-        "x-extension-command": contract.command,
+        "x-extension-command": commands[0] ?? contract.command,
+        "x-extension-commands": commands,
     };
 }
+function mergeExtensionFlagContract(existing, incoming) {
+    existing.description ??= incoming.description;
+    existing.value_name ??= incoming.value_name;
+    existing.value_type ??= incoming.value_type;
+    if (incoming.required === true) {
+        existing.required = true;
+    }
+    if (incoming.repeatable === true) {
+        existing.repeatable = true;
+    }
+}
+function mergeExtensionContractsByAction(contracts) {
+    const byAction = new Map();
+    for (const contract of contracts) {
+        const existing = byAction.get(contract.action);
+        if (!existing) {
+            byAction.set(contract.action, {
+                ...contract,
+                flags: [...contract.flags],
+                examples: [...contract.examples],
+                failure_hints: [...contract.failure_hints],
+            });
+            continue;
+        }
+        existing.command = [...new Set([existing.command, contract.command])]
+            .sort((left, right) => left.localeCompare(right))
+            .join("|");
+        existing.arguments = existing.arguments.length >= contract.arguments.length ? existing.arguments : contract.arguments;
+        const flagKeys = new Set(existing.flags.map((flag) => `${flag.flag}|${flag.short ?? ""}`));
+        for (const flag of contract.flags) {
+            const key = `${flag.flag}|${flag.short ?? ""}`;
+            if (!flagKeys.has(key)) {
+                flagKeys.add(key);
+                existing.flags.push(flag);
+            }
+            else {
+                const existingFlag = existing.flags.find((candidate) => `${candidate.flag}|${candidate.short ?? ""}` === key);
+                if (existingFlag) {
+                    mergeExtensionFlagContract(existingFlag, flag);
+                }
+            }
+        }
+        existing.examples = [...new Set([...existing.examples, ...contract.examples])];
+        existing.failure_hints = [...new Set([...existing.failure_hints, ...contract.failure_hints])];
+    }
+    return [...byAction.values()].sort((left, right) => left.action.localeCompare(right.action));
+}
 async function resolveRuntimeExtensionActionProbe(global) {
     const defaultPolicyState = {
         mode: SETTINGS_DEFAULTS.extensions.policy.mode,
@@ -401,6 +533,7 @@ async function resolveRuntimeExtensionActionProbe(global) {
             disabledReason: "extensions_disabled",
             commandDefinitions: [],
             flagRegistrations: [],
+            registrations: null,
             policyState: defaultPolicyState,
         };
     }
@@ -411,6 +544,7 @@ async function resolveRuntimeExtensionActionProbe(global) {
             disabledReason: null,
             commandDefinitions: [],
             flagRegistrations: [],
+            registrations: null,
             policyState: defaultPolicyState,
         };
     }
@@ -432,6 +566,7 @@ async function resolveRuntimeExtensionActionProbe(global) {
             disabledReason: null,
             commandDefinitions: activationResult.registrations.commands,
             flagRegistrations: activationResult.registrations.flags,
+            registrations: activationResult.registrations,
             policyState: {
                 mode: loadResult.policy.mode,
                 trust_mode: loadResult.policy.trust_mode,
@@ -445,6 +580,7 @@ async function resolveRuntimeExtensionActionProbe(global) {
             disabledReason: "extension_runtime_probe_failed",
             commandDefinitions: [],
             flagRegistrations: [],
+            registrations: null,
             policyState: defaultPolicyState,
         };
     }
@@ -474,7 +610,7 @@ function collectActionContractDescriptors(extensionContracts) {
             command_path: normalizeCommandPath(contract.command),
         });
     }
-    return [...descriptors.values()].sort((left, right) => left.action.localeCompare(right.action));
+    return [...descriptors.values()].sort((left, right) => (left.action ?? "").localeCompare(right.action ?? ""));
 }
 function resolveActionAvailability(descriptor, runtimeProbe) {
     if (descriptor.provider === "core" && !descriptor.requires_extension) {
@@ -489,8 +625,10 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
             cli_exposed: descriptor.command_path !== null,
         };
     }
-    const commandPath = descriptor.command_path ? normalizeCommandPath(descriptor.command_path) : "";
-    const extensionCommandAvailable = commandPath.length > 0 && runtimeProbe.handlers.has(commandPath);
+    const commandPaths = descriptor.command_path
+        ? splitCommandPathAliases(descriptor.command_path)
+        : [];
+    const extensionCommandAvailable = commandPaths.some((commandPath) => runtimeProbe.handlers.has(commandPath));
     const invocable = runtimeProbe.disabledReason === null && extensionCommandAvailable;
     return {
         action: descriptor.action,
@@ -498,7 +636,9 @@ function resolveActionAvailability(descriptor, runtimeProbe) {
         available: invocable,
         requires_extension: true,
         provider: "extension",
-        disabled_reason: invocable ? null : runtimeProbe.disabledReason ?? "extension_command_not_registered",
+        disabled_reason: invocable
+            ? null
+            : (runtimeProbe.disabledReason ?? "extension_command_not_registered"),
         command_path: descriptor.command_path,
         cli_exposed: extensionCommandAvailable,
         policy_state: {
@@ -509,12 +649,20 @@ 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" || command === "install") {
+    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;
     }
@@ -536,6 +684,9 @@ function resolveCoreCommandFlags(command) {
     if (command === "context" || command === "ctx") {
         return CONTEXT_FLAG_CONTRACTS;
     }
+    if (command === "get") {
+        return GET_FLAG_CONTRACTS;
+    }
     if (command === "search") {
         return SEARCH_FLAG_CONTRACTS;
     }
@@ -557,6 +708,18 @@ function resolveCoreCommandFlags(command) {
     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;
     }
@@ -682,13 +845,20 @@ function buildRuntimeFieldFlagContracts(fieldRegistry) {
         if (!primaryFlag) {
             continue;
         }
-        const shortAlias = definition.cli_aliases.map((alias) => toRuntimeShortFlagToken(alias)).find((alias) => alias !== null);
+        const shortAlias = definition.cli_aliases
+            .map((alias) => toRuntimeShortFlagToken(alias))
+            .find((alias) => alias !== null);
         const longAliases = definition.cli_aliases
             .map((alias) => toRuntimeLongFlagToken(alias))
             .filter((alias) => alias !== null && alias !== primaryFlag);
         for (const command of definition.commands) {
-            const bucket = buckets.get(command) ?? { flags: [], seen: new Set() };
-            const primaryContract = shortAlias ? { flag: primaryFlag, short: shortAlias } : { flag: primaryFlag };
+            const bucket = buckets.get(command) ?? {
+                flags: [],
+                seen: new Set(),
+            };
+            const primaryContract = shortAlias
+                ? { flag: primaryFlag, short: shortAlias }
+                : { flag: primaryFlag };
             const primaryKey = `${primaryContract.flag}|${primaryContract.short ?? ""}`;
             if (!bucket.seen.has(primaryKey)) {
                 bucket.seen.add(primaryKey);
@@ -727,8 +897,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 = PM_CORE_COMMAND_NAMES.includes(command) && !PACKAGE_OWNED_COMMANDS.has(command);
         const coreFlags = isCoreCommand ? resolveCoreCommandFlags(command) : [];
         const runtimeFlags = runtimeFieldFlagMap.get(normalizeCommandForRuntimeFieldFlags(command)) ?? [];
         const extensionFlags = extensionFlagMap.get(command);
@@ -748,6 +917,25 @@ function buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap
     })
         .sort((left, right) => left.command.localeCompare(right.command));
 }
+function compactCommandAliasSurface(commands) {
+    const commandSet = new Set(commands);
+    const result = [];
+    for (const command of commands) {
+        const canonical = COMMAND_ALIAS_TO_CANONICAL.get(command);
+        if (canonical && commandSet.has(canonical)) {
+            continue;
+        }
+        result.push(command);
+    }
+    return result;
+}
+function buildCommandAliasSurface(commands) {
+    const commandSet = new Set(commands);
+    return CANONICAL_COMMAND_ALIASES.map((entry) => ({
+        canonical: entry.canonical,
+        aliases: entry.aliases.filter((alias) => commandSet.has(alias)),
+    })).filter((entry) => commandSet.has(entry.canonical) && entry.aliases.length > 0);
+}
 function buildCommanderAliasSurface() {
     return {
         create_string_options: CREATE_COMMANDER_STRING_OPTION_CONTRACTS,
@@ -762,7 +950,7 @@ function buildCommanderAliasSurface() {
     };
 }
 function resolveCreateRequiredOptionContract(typeDefinition, createMode) {
-    const baseRequiredOptions = new Set(["title", "description", "type"]);
+    const baseRequiredOptions = new Set(["title", "type"]);
     if (createMode === "strict") {
         for (const field of typeDefinition.required_create_fields) {
             baseRequiredOptions.add(field);
@@ -773,8 +961,14 @@ function resolveCreateRequiredOptionContract(typeDefinition, createMode) {
     }
     const policyState = resolveCommandOptionPolicyState(typeDefinition, "create", baseRequiredOptions);
     const requiredOptionKeys = [...new Set(policyState.required)].sort((left, right) => left.localeCompare(right));
-    const requiredFlags = [...new Set(requiredOptionKeys.map((option) => commandOptionFlagLabel("create", option)))].sort((left, right) => left.localeCompare(right));
-    const requiredTypeOptions = [...new Set(typeDefinition.options.filter((option) => option.required === true).map((option) => option.key))].sort((left, right) => left.localeCompare(right));
+    const requiredFlags = [
+        ...new Set(requiredOptionKeys.map((option) => commandOptionFlagLabel("create", option))),
+    ].sort((left, right) => left.localeCompare(right));
+    const requiredTypeOptions = [
+        ...new Set(typeDefinition.options
+            .filter((option) => option.required === true)
+            .map((option) => option.key)),
+    ].sort((left, right) => left.localeCompare(right));
     return {
         required_option_keys: requiredOptionKeys,
         required_flags: requiredFlags,
@@ -841,7 +1035,19 @@ export async function runContracts(options, global) {
     const flagsOnly = options.flagsOnly === true;
     const availabilityOnly = options.availabilityOnly === true;
     const runtimeOnly = options.runtimeOnly === true;
-    const projectionFlagsEnabled = [schemaOnly, flagsOnly, availabilityOnly].filter((value) => value).length;
+    const fullOutput = options.full === true;
+    const unfilteredDefaultBriefMode = !fullOutput && !schemaOnly && !flagsOnly && !availabilityOnly && !selectedAction && !selectedCommand;
+    // Agent token-cost guard: when no filter and no projection flag and not --full,
+    // skip the giant schema oneOf union (the 200KB+ chunk). Restore via --full
+    // or by scoping to a specific --command/--action.
+    const omitUnfilteredSchema = unfilteredDefaultBriefMode;
+    const omitUnfilteredCommandFlags = unfilteredDefaultBriefMode;
+    const omitUnfilteredCommanderAliases = unfilteredDefaultBriefMode;
+    const projectionFlagsEnabled = [
+        schemaOnly,
+        flagsOnly,
+        availabilityOnly,
+    ].filter((value) => value).length;
     if (projectionFlagsEnabled > 1) {
         throw new PmCliError("Choose only one projection flag: --schema-only, --flags-only, or --availability-only.", EXIT_CODE.USAGE);
     }
@@ -853,15 +1059,16 @@ export async function runContracts(options, global) {
     catch {
         settings = structuredClone(SETTINGS_DEFAULTS);
     }
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
+    const runtimeProbe = await resolveRuntimeExtensionActionProbe(global);
+    const typeRegistry = resolveItemTypeRegistry(settings, runtimeProbe.registrations ?? getActiveExtensionRegistrations());
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
     const runtimeFieldFlagMap = buildRuntimeFieldFlagContracts(runtimeFieldRegistry);
     const createRequiredOptionContracts = buildCreateRequiredOptionContracts(typeRegistry);
-    const runtimeProbe = await resolveRuntimeExtensionActionProbe(global);
     const extensionContracts = collectExtensionCommandContracts(runtimeProbe);
+    const mergedExtensionContracts = mergeExtensionContractsByAction(extensionContracts);
     const extensionFlagMap = collectExtensionFlagContractsByCommand(runtimeProbe.flagRegistrations);
-    const actionDescriptors = collectActionContractDescriptors(extensionContracts);
+    const actionDescriptors = collectActionContractDescriptors(mergedExtensionContracts);
     const actionNames = new Set(actionDescriptors.map((entry) => entry.action));
     if (selectedAction && !actionNames.has(selectedAction)) {
         throw new PmCliError(`Unknown action: "${options.action}".`, EXIT_CODE.USAGE);
@@ -869,7 +1076,7 @@ export async function runContracts(options, global) {
     const commandCatalog = [
         ...new Set([
             ...PM_CORE_COMMAND_NAMES.filter((entry) => !PACKAGE_OWNED_COMMANDS.has(entry)),
-            ...extensionContracts.map((entry) => entry.command),
+            ...mergedExtensionContracts.flatMap((entry) => entry.command.split("|")),
         ]),
     ]
         .map((entry) => normalizeCommandPath(entry))
@@ -877,6 +1084,16 @@ export async function runContracts(options, global) {
         .sort((left, right) => left.localeCompare(right));
     const commandNames = new Set(commandCatalog);
     if (selectedCommand && !commandNames.has(selectedCommand)) {
+        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, {
+                examples: [`pm install ${packageHint} --project`, `pm contracts --command ${selectedCommand} --flags-only --json`],
+                nextSteps: [`Install the optional package first: pm install ${packageHint} --project`],
+                recovery: {
+                    suggested_retry: `pm install ${packageHint} --project`,
+                },
+            });
+        }
         throw new PmCliError(`Unknown command: "${options.command}".`, EXIT_CODE.USAGE);
     }
     const commandScopedDescriptors = selectedCommand
@@ -903,7 +1120,7 @@ export async function runContracts(options, global) {
         return typeof actionConst === "string" ? actionConst : null;
     })
         .filter((entry) => entry !== null));
-    const extensionBranches = extensionContracts
+    const extensionBranches = mergedExtensionContracts
         .filter((contract) => !schemaActionSet.has(contract.action))
         .map((contract) => buildExtensionActionSchemaBranch(contract));
     const mergedSchema = extensionBranches.length > 0
@@ -916,7 +1133,9 @@ export async function runContracts(options, global) {
         ? commandScopedDescriptors.filter((descriptor) => descriptor.action === selectedAction)
         : commandScopedDescriptors;
     const allActionAvailability = scopedActionDescriptors.map((descriptor) => resolveActionAvailability(descriptor, runtimeProbe));
-    const actionAvailability = runtimeOnly && !selectedAction ? allActionAvailability.filter((entry) => entry.invocable) : allActionAvailability;
+    const actionAvailability = runtimeOnly && !selectedAction
+        ? allActionAvailability.filter((entry) => entry.invocable)
+        : allActionAvailability;
     const actions = actionAvailability.map((entry) => entry.action);
     const descriptorActionSet = new Set(actionDescriptors.map((descriptor) => descriptor.action));
     let filteredSchema = selectedAction
@@ -936,14 +1155,23 @@ export async function runContracts(options, global) {
         : selectedAction
             ? resolveScopedCommandsFromActionDescriptors(scopedActionDescriptors, commandCatalog)
             : commandCatalog;
+    const outputCommands = flagsOnly && selectedCommand === undefined && selectedAction === undefined
+        ? compactCommandAliasSurface(commands)
+        : commands;
+    const commandAliases = buildCommandAliasSurface(commands);
     const extensionCommandContracts = selectedCommand
         ? extensionContracts.filter((entry) => entry.command === selectedCommand)
         : selectedAction
-            ? extensionContracts.filter((entry) => commands.includes(normalizeCommandPath(entry.command)))
+            ? extensionContracts.filter((entry) => outputCommands.includes(normalizeCommandPath(entry.command)))
             : extensionContracts;
+    const includeRuntimeContractSections = !(flagsOnly && !fullOutput);
     const result = {
-        schema_version: typeof mergedSchema["x-schema-version"] === "string" ? mergedSchema["x-schema-version"] : null,
-        schema_id: typeof mergedSchema.$id === "string" ? mergedSchema.$id : null,
+        schema_version: typeof mergedSchema["x-schema-version"] === "string"
+            ? mergedSchema["x-schema-version"]
+            : null,
+        schema_id: typeof mergedSchema.$id === "string"
+            ? mergedSchema.$id
+            : null,
         selected: {
             action: selectedAction ?? null,
             command: selectedCommand ?? null,
@@ -953,8 +1181,10 @@ export async function runContracts(options, global) {
             runtime_only: runtimeOnly,
             command_scoped: selectedCommand !== undefined,
         },
-        commands,
-        runtime_schema: {
+        commands: outputCommands,
+    };
+    if (includeRuntimeContractSections) {
+        result.runtime_schema = {
             statuses: statusRegistry.definitions.map((definition) => definition.id),
             open_status: statusRegistry.open_status,
             close_status: statusRegistry.close_status,
@@ -962,10 +1192,12 @@ export async function runContracts(options, global) {
             types: [...typeRegistry.types],
             fields_by_command: Object.fromEntries([...runtimeFieldRegistry.command_to_fields.entries()].map(([command, definitions]) => [
                 command,
-                [...new Set(definitions.map((definition) => `--${definition.cli_flag}`))].sort((left, right) => left.localeCompare(right)),
+                [
+                    ...new Set(definitions.map((definition) => `--${definition.cli_flag}`)),
+                ].sort((left, right) => left.localeCompare(right)),
             ])),
-        },
-        extension_contracts: {
+        };
+        result.extension_contracts = {
             capabilities: [...PM_EXTENSION_CAPABILITY_CONTRACTS],
             services: [...PM_EXTENSION_SERVICE_NAME_CONTRACTS],
             policy_modes: [...PM_EXTENSION_POLICY_MODE_CONTRACTS],
@@ -978,22 +1210,40 @@ export async function runContracts(options, global) {
                 previous: ["v1"],
                 breaking_strategy: "versioned_breaking",
             },
-        },
-    };
+        };
+    }
     if (!flagsOnly) {
         result.actions = actions;
         result.action_availability = actionAvailability;
     }
-    if (includeSchemaSurface) {
+    if (includeSchemaSurface && !omitUnfilteredSchema) {
         result.schema = filteredSchema;
         result.extension_commands = extensionCommandContracts;
     }
+    else if (includeSchemaSurface && omitUnfilteredSchema) {
+        result.schema_omitted_reason = "unfiltered_default_brief";
+        result.extension_commands = extensionCommandContracts;
+    }
     if (!schemaOnly && !availabilityOnly) {
-        result.command_flags = buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap);
+        if (!omitUnfilteredCommandFlags) {
+            result.command_flags = buildCommandFlagSurface(outputCommands, extensionFlagMap, runtimeFieldFlagMap);
+        }
+        else {
+            result.command_flags_omitted_reason = "unfiltered_default_brief";
+        }
+        if (commandAliases.length > 0) {
+            result.command_aliases = commandAliases;
+        }
     }
     if (!schemaOnly && !flagsOnly && !availabilityOnly) {
-        result.commander_aliases = buildCommanderAliasSurface();
+        if (!omitUnfilteredCommanderAliases) {
+            result.commander_aliases = buildCommanderAliasSurface();
+        }
+        else {
+            result.commander_aliases_omitted_reason = "unfiltered_default_brief";
+        }
     }
     return result;
 }
-//# sourceMappingURL=contracts.js.map
+//# sourceMappingURL=contracts.js.map
+//# debugId=478936e5-660a-5f89-b15d-93b37468c7ed