@unbrained/pm-cli 2026.7.7 → 2026.7.9

package/dist/cli/commands/contracts.d.ts

@@ -9,6 +9,7 @@ import { PM_TOOL_ACTIONS, type CliFlagContract, type CommanderOptionAliasContrac
 export interface ContractsCommandOptions {
     action?: string;
     command?: string;
+    summary?: boolean;
     schemaOnly?: boolean;
     flagsOnly?: boolean;
     availabilityOnly?: boolean;
@@ -37,6 +38,7 @@ export interface ContractsResult {
     selected: {
         action: string | null;
         command: string | null;
+        summary: boolean;
         schema_only: boolean;
         flags_only: boolean;
         availability_only: boolean;
@@ -54,6 +56,7 @@ export interface ContractsResult {
     command_aliases?: CommandAliasSurface[];
     commander_aliases?: Record<string, CommanderOptionAliasContract[]>;
     extension_commands?: ExtensionCommandContract[];
+    command_summaries?: CommandSummarySurface[];
     runtime_schema?: {
         statuses: string[];
         open_status: string;
@@ -128,6 +131,10 @@ interface ExtensionCommandContract {
     examples: string[];
     failure_hints: string[];
 }
+interface CommandSummarySurface {
+    command: string;
+    intent: string;
+}
 declare function packageOwnedActionForCommand(command: string): string;
 declare function resolveActionCommandPath(action: PmToolAction): string | null;
 declare function actionDescriptorMatchesSelectedCommand(descriptor: ActionContractDescriptor, selectedCommand: string): boolean;
@@ -138,6 +145,7 @@ declare function filterSchemaByAction(schema: Record<string, unknown>, action: s
 declare function filterSchemaByActions(schema: Record<string, unknown>, actions: ReadonlySet<string>): Record<string, unknown>;
 declare function normalizeCommandPath(value: string): string;
 declare function normalizeActionNameFromCommand(commandPath: string): string;
+declare function normalizeExtensionFlagName(value: unknown, kind: "long" | "short"): string | null;
 declare function collectExtensionFlagContractsByCommand(registrations: RegisteredExtensionFlagDefinitions[]): Map<string, {
     flags: CliFlagContract[];
     sources: Array<{
@@ -166,6 +174,7 @@ declare function toRuntimeLongFlagToken(token: string): string | null;
 declare function toRuntimeShortFlagToken(token: string): string | null;
 declare function buildRuntimeFieldFlagContracts(fieldRegistry: RuntimeFieldRegistry): Map<string, CliFlagContract[]>;
 declare function attachCreateRequiredOptionContracts(schema: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>;
+declare function buildCommandSummarySurface(commands: readonly string[]): CommandSummarySurface[];
 /**
  * Implements run contracts for the public runtime surface of this module.
  */
@@ -174,6 +183,7 @@ export declare const _testOnlyContractsCommand: {
     actionDescriptorMatchesSelectedCommand: typeof actionDescriptorMatchesSelectedCommand;
     attachCreateRequiredOptionContracts: typeof attachCreateRequiredOptionContracts;
     buildExtensionActionSchemaBranch: typeof buildExtensionActionSchemaBranch;
+    buildCommandSummarySurface: typeof buildCommandSummarySurface;
     buildRuntimeFieldFlagContracts: typeof buildRuntimeFieldFlagContracts;
     collectActionContractDescriptors: typeof collectActionContractDescriptors;
     collectExtensionCommandContracts: typeof collectExtensionCommandContracts;
@@ -184,6 +194,7 @@ export declare const _testOnlyContractsCommand: {
     filterSchemaByActions: typeof filterSchemaByActions;
     isCoreCommandPath: typeof isCoreCommandPath;
     mergeExtensionContractsByAction: typeof mergeExtensionContractsByAction;
+    normalizeExtensionFlagName: typeof normalizeExtensionFlagName;
     normalizeActionNameFromCommand: typeof normalizeActionNameFromCommand;
     normalizeCommandForRuntimeFieldFlags: typeof normalizeCommandForRuntimeFieldFlags;
     normalizeCommandPath: typeof normalizeCommandPath;

package/dist/cli/commands/contracts.js

@@ -4,7 +4,7 @@
  * Implements the pm contracts command surface and its agent-facing runtime behavior.
  */
 
-!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]="24d15738-45bd-5dd2-95e1-699f9c6061bd")}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]="1b0d78ea-6245-5c11-9a0a-2740289b0b1a")}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";
@@ -123,6 +123,52 @@ const CANONICAL_COMMAND_ALIASES = [
 const COMMAND_ALIAS_TO_CANONICAL = new Map(CANONICAL_COMMAND_ALIASES.flatMap((entry) => entry.aliases.map((alias) => [alias, entry.canonical])));
 const COMMAND_NAMESPACE_DISPLAY_LIMIT = 10;
 const COMMAND_NAMESPACE_FALLBACK_LIMIT = 20;
+const COMMAND_INTENTS = new Map([
+    ["activity", "Read activity."],
+    ["aggregate", "Group counts."],
+    ["append", "Append body."],
+    ["claim", "Claim work."],
+    ["close", "Close work."],
+    ["comments", "Manage comments."],
+    ["completion", "Generate shell completions."],
+    ["config", "Manage settings."],
+    ["context", "Build context."],
+    ["contracts", "Inspect contracts."],
+    ["copy", "Copy work."],
+    ["create", "Create work."],
+    ["delete", "Delete work."],
+    ["deps", "Manage deps."],
+    ["docs", "Link docs."],
+    ["files", "Link files."],
+    ["focus", "Manage focus."],
+    ["gc", "Clean caches."],
+    ["get", "Read item."],
+    ["guide", "Show user guides."],
+    ["health", "Check health."],
+    ["help", "Show help."],
+    ["history", "Inspect history."],
+    ["init", "Initialize workspace."],
+    ["install", "Install packages."],
+    ["learnings", "Manage learnings."],
+    ["list", "List work."],
+    ["next", "Pick next work."],
+    ["notes", "Manage notes."],
+    ["ops", "Run operations."],
+    ["package", "Manage packages."],
+    ["plan", "Manage plans."],
+    ["profile", "Manage profiles."],
+    ["reindex", "Refresh search index."],
+    ["release", "Release claim."],
+    ["restore", "Restore history."],
+    ["schema", "Customize schema."],
+    ["search", "Search work."],
+    ["stats", "Show stats."],
+    ["telemetry", "Manage telemetry."],
+    ["test", "Run linked tests."],
+    ["update", "Update work."],
+    ["upgrade", "Upgrade packages."],
+    ["validate", "Validate data."],
+]);
 // Lifecycle subcommand flag contracts for `pm extension`. Only `init` differs
 // between extension and package: `pm package init` / `pm packages init`
 // additionally accept the package-only `--declarative` flag, so the package
@@ -381,15 +427,25 @@ function assignExtensionFlagBoolean(contract, key, enabled) {
         contract[key] = true;
     }
 }
+function normalizeExtensionFlagName(value, kind) {
+    if (value == null) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        throw new TypeError("Expected string for extension flag name.");
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    if (kind === "long") {
+        return trimmed.startsWith("--") && trimmed.length > 2 ? trimmed : null;
+    }
+    return trimmed.startsWith("-") && !trimmed.startsWith("--") && trimmed.length > 1 ? trimmed : null;
+}
 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 = normalizeExtensionFlagName(definition.long, "long");
+    const normalizedShort = normalizeExtensionFlagName(definition.short, "short");
     const flag = normalizedLong ?? normalizedShort;
     if (!flag) {
         return null;
@@ -1064,6 +1120,7 @@ function attachCreateRequiredOptionContracts(schema, metadata) {
     };
 }
 function resolveContractsSelection(options) {
+    const summary = options.summary === true;
     const schemaOnly = options.schemaOnly === true;
     const flagsOnly = options.flagsOnly === true;
     const availabilityOnly = options.availabilityOnly === true;
@@ -1071,10 +1128,11 @@ function resolveContractsSelection(options) {
     const fullOutput = options.full === true;
     const selectedAction = normalizeToken(options.action);
     const selectedCommand = normalizeToken(options.command);
-    const unfilteredDefaultBriefMode = !fullOutput && !schemaOnly && !flagsOnly && !availabilityOnly && !selectedAction && !selectedCommand;
+    const unfilteredDefaultBriefMode = !summary && !fullOutput && !schemaOnly && !flagsOnly && !availabilityOnly && !selectedAction && !selectedCommand;
     return {
         selectedAction,
         selectedCommand,
+        summary,
         schemaOnly,
         flagsOnly,
         availabilityOnly,
@@ -1087,12 +1145,13 @@ function resolveContractsSelection(options) {
 }
 function assertSingleContractsProjection(selection) {
     const projectionFlagsEnabled = [
+        selection.summary,
         selection.schemaOnly,
         selection.flagsOnly,
         selection.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);
+        throw new PmCliError("Choose only one projection flag: --summary, --schema-only, --flags-only, or --availability-only.", EXIT_CODE.USAGE);
     }
 }
 async function readContractsSettings(pmRoot) {
@@ -1345,6 +1404,37 @@ function resolveOutputCommands(selection, commands) {
         ? compactCommandAliasSurface(commands)
         : commands;
 }
+function summarizeCommandIntent(command) {
+    const rootCommand = command.split(" ")[0];
+    return COMMAND_INTENTS.get(command) ??
+        COMMAND_INTENTS.get(rootCommand) ??
+        "Inspect flags.";
+}
+function canonicalSummaryCommand(command) {
+    const rootCommand = command.split(" ")[0];
+    if (rootCommand.startsWith("list-")) {
+        return "list";
+    }
+    if (rootCommand.startsWith("history-")) {
+        return "history";
+    }
+    if (rootCommand === "ctx") {
+        return "context";
+    }
+    if (rootCommand === "packages") {
+        return "package";
+    }
+    return COMMAND_ALIAS_TO_CANONICAL.get(rootCommand) ?? rootCommand;
+}
+function buildCommandSummarySurface(commands) {
+    const rootCommands = [...new Set(commands.map((command) => canonicalSummaryCommand(command)))]
+        .filter((command) => command.length > 0)
+        .sort((left, right) => left.localeCompare(right));
+    return rootCommands.map((command) => ({
+        command,
+        intent: summarizeCommandIntent(command),
+    }));
+}
 function resolveExtensionCommandContracts(selection, runtime, outputCommands) {
     if (selection.selectedCommand) {
         return runtime.extensionContracts.filter((entry) => splitCommandPathAliases(entry.command).includes(selection.selectedCommand));
@@ -1370,14 +1460,15 @@ function createContractsResult(selection, schemaContext, actionContext, outputCo
         selected: {
             action: selection.selectedAction ?? null,
             command: selection.selectedCommand ?? null,
+            summary: selection.summary,
             schema_only: selection.schemaOnly,
             flags_only: selection.flagsOnly,
             availability_only: selection.availabilityOnly,
             runtime_only: selection.runtimeOnly,
             command_scoped: selection.selectedCommand !== undefined,
         },
-        commands: outputCommands,
-        ...(!selection.flagsOnly
+        commands: selection.summary ? [] : outputCommands,
+        ...(!selection.summary && !selection.flagsOnly
             ? {
                 actions: actionContext.actions,
                 action_availability: actionContext.actionAvailability,
@@ -1460,9 +1551,13 @@ export async function runContracts(options, global) {
     const schemaContext = resolveContractsSchemaContext(selection, runtime, actionContext);
     const commands = resolveContractsCommands(selection, actionContext);
     const outputCommands = resolveOutputCommands(selection, commands);
+    const result = createContractsResult(selection, schemaContext, actionContext, outputCommands);
+    if (selection.summary) {
+        result.command_summaries = buildCommandSummarySurface(outputCommands);
+        return result;
+    }
     const commandAliases = buildCommandAliasSurface(commands);
     const extensionCommandContracts = resolveExtensionCommandContracts(selection, runtime, outputCommands);
-    const result = createContractsResult(selection, schemaContext, actionContext, outputCommands);
     if (!(selection.flagsOnly && !selection.fullOutput)) {
         attachRuntimeContractsResult(result, runtime);
     }
@@ -1481,6 +1576,7 @@ export const _testOnlyContractsCommand = {
     actionDescriptorMatchesSelectedCommand,
     attachCreateRequiredOptionContracts,
     buildExtensionActionSchemaBranch,
+    buildCommandSummarySurface,
     buildRuntimeFieldFlagContracts,
     collectActionContractDescriptors,
     collectExtensionCommandContracts,
@@ -1491,6 +1587,7 @@ export const _testOnlyContractsCommand = {
     filterSchemaByActions,
     isCoreCommandPath,
     mergeExtensionContractsByAction,
+    normalizeExtensionFlagName,
     normalizeActionNameFromCommand,
     normalizeCommandForRuntimeFieldFlags,
     normalizeCommandPath,
@@ -1504,4 +1601,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=contracts.js.map
-//# debugId=24d15738-45bd-5dd2-95e1-699f9c6061bd
+//# debugId=1b0d78ea-6245-5c11-9a0a-2740289b0b1a