@unbrained/pm-cli 2026.5.18 → 2026.5.24

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]="dc0f1970-8a30-56c5-827f-573784a38d54")}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]="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";
@@ -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, 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, 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",
@@ -57,6 +57,27 @@ 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",
@@ -90,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);
@@ -103,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));
@@ -224,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) {
@@ -363,6 +414,10 @@ 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",
@@ -398,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",
@@ -410,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,
@@ -425,6 +533,7 @@ async function resolveRuntimeExtensionActionProbe(global) {
             disabledReason: "extensions_disabled",
             commandDefinitions: [],
             flagRegistrations: [],
+            registrations: null,
             policyState: defaultPolicyState,
         };
     }
@@ -435,6 +544,7 @@ async function resolveRuntimeExtensionActionProbe(global) {
             disabledReason: null,
             commandDefinitions: [],
             flagRegistrations: [],
+            registrations: null,
             policyState: defaultPolicyState,
         };
     }
@@ -456,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,
@@ -469,6 +580,7 @@ async function resolveRuntimeExtensionActionProbe(global) {
             disabledReason: "extension_runtime_probe_failed",
             commandDefinitions: [],
             flagRegistrations: [],
+            registrations: null,
             policyState: defaultPolicyState,
         };
     }
@@ -513,10 +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,
@@ -599,6 +711,12 @@ function resolveCoreCommandFlags(command) {
     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;
     }
@@ -941,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);
@@ -957,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))
@@ -965,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
@@ -991,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
@@ -1035,6 +1164,7 @@ export async function runContracts(options, global) {
         : selectedAction
             ? 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"]
@@ -1052,7 +1182,9 @@ export async function runContracts(options, global) {
             command_scoped: selectedCommand !== undefined,
         },
         commands: outputCommands,
-        runtime_schema: {
+    };
+    if (includeRuntimeContractSections) {
+        result.runtime_schema = {
             statuses: statusRegistry.definitions.map((definition) => definition.id),
             open_status: statusRegistry.open_status,
             close_status: statusRegistry.close_status,
@@ -1064,8 +1196,8 @@ export async function runContracts(options, global) {
                     ...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],
@@ -1078,8 +1210,8 @@ export async function runContracts(options, global) {
                 previous: ["v1"],
                 breaking_strategy: "versioned_breaking",
             },
-        },
-    };
+        };
+    }
     if (!flagsOnly) {
         result.actions = actions;
         result.action_availability = actionAvailability;
@@ -1114,4 +1246,4 @@ export async function runContracts(options, global) {
     return result;
 }
 //# sourceMappingURL=contracts.js.map
-//# debugId=dc0f1970-8a30-56c5-827f-573784a38d54
+//# debugId=478936e5-660a-5f89-b15d-93b37468c7ed