@unbrained/pm-cli 2026.5.11 → 2026.5.12

package/dist/sdk/cli-contracts.js

@@ -86,6 +86,10 @@ export const PM_CORE_COMMAND_NAMES = [
     "init",
     "config",
     "extension",
+    "package",
+    "packages",
+    "install",
+    "upgrade",
     "create",
     "list",
     "list-all",
@@ -153,6 +157,20 @@ export const PM_TOOL_ACTIONS = [
     "extension-activate",
     "extension-deactivate",
     "extension",
+    "package-init",
+    "package-install",
+    "package-uninstall",
+    "package-explore",
+    "package-manage",
+    "package-reload",
+    "package-doctor",
+    "package-adopt",
+    "package-adopt-all",
+    "package-activate",
+    "package-deactivate",
+    "package",
+    "install",
+    "upgrade",
     "create",
     "list",
     "list-all",
@@ -228,7 +246,7 @@ export function isPmExtensionPolicyModeContract(value) {
 export function isPmExtensionPolicySurfaceContract(value) {
     return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
 }
-export const PI_LIST_FILTER_OPTION_CONTRACTS = [
+export const TOOL_LIST_FILTER_OPTION_CONTRACTS = [
     { param: "type", flag: "--type" },
     { param: "tag", flag: "--tag" },
     { param: "priority", flag: "--priority" },
@@ -245,7 +263,7 @@ export const PI_LIST_FILTER_OPTION_CONTRACTS = [
     { param: "sort", flag: "--sort" },
     { param: "order", flag: "--order" },
 ];
-export const PI_AGGREGATE_OPTION_CONTRACTS = [
+export const TOOL_AGGREGATE_OPTION_CONTRACTS = [
     { param: "groupBy", flag: "--group-by" },
     { param: "status", flag: "--status" },
     { param: "type", flag: "--type" },
@@ -259,7 +277,7 @@ export const PI_AGGREGATE_OPTION_CONTRACTS = [
     { param: "sprint", flag: "--sprint" },
     { param: "release", flag: "--release" },
 ];
-export const PI_DEDUPE_AUDIT_OPTION_CONTRACTS = [
+export const TOOL_DEDUPE_AUDIT_OPTION_CONTRACTS = [
     { param: "mode", flag: "--mode" },
     { param: "limit", flag: "--limit" },
     { param: "threshold", flag: "--threshold" },
@@ -275,7 +293,7 @@ export const PI_DEDUPE_AUDIT_OPTION_CONTRACTS = [
     { param: "sprint", flag: "--sprint" },
     { param: "release", flag: "--release" },
 ];
-export const PI_SEARCH_FILTER_OPTION_CONTRACTS = [
+export const TOOL_SEARCH_FILTER_OPTION_CONTRACTS = [
     { param: "type", flag: "--type" },
     { param: "tag", flag: "--tag" },
     { param: "priority", flag: "--priority" },
@@ -284,7 +302,7 @@ export const PI_SEARCH_FILTER_OPTION_CONTRACTS = [
     { param: "fields", flag: "--fields" },
     { param: "limit", flag: "--limit" },
 ];
-export const PI_SHARED_CREATE_UPDATE_OPTION_CONTRACTS = [
+export const TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS = [
     { param: "parent", flag: "--parent" },
     { param: "reviewer", flag: "--reviewer" },
     { param: "risk", flag: "--risk" },
@@ -315,7 +333,7 @@ export const PI_SHARED_CREATE_UPDATE_OPTION_CONTRACTS = [
     { param: "outcome", flag: "--outcome" },
     { param: "whyNow", flag: "--why-now" },
 ];
-export const PI_CREATE_OPTION_CONTRACTS = [
+export const TOOL_CREATE_OPTION_CONTRACTS = [
     { param: "title", flag: "--title" },
     { param: "description", flag: "--description", allowEmpty: true },
     { param: "type", flag: "--type" },
@@ -355,7 +373,7 @@ export const PI_CREATE_OPTION_CONTRACTS = [
     { param: "clearTypeOptions", flag: "--clear-type-options" },
     { param: "allowAuditUpdate", flag: "--allow-audit-update" },
 ];
-export const PI_UPDATE_OPTION_CONTRACTS = [
+export const TOOL_UPDATE_OPTION_CONTRACTS = [
     { param: "title", flag: "--title" },
     { param: "description", flag: "--description", allowEmpty: true },
     { param: "body", flag: "--body", allowEmpty: true },
@@ -396,7 +414,7 @@ export const PI_UPDATE_OPTION_CONTRACTS = [
     { param: "clearTypeOptions", flag: "--clear-type-options" },
     { param: "allowAuditDepUpdate", flag: "--allow-audit-dep-update" },
 ];
-export const PI_UPDATE_MANY_FILTER_OPTION_CONTRACTS = [
+export const TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS = [
     { param: "filterStatus", flag: "--filter-status" },
     { param: "filterType", flag: "--filter-type" },
     { param: "filterTag", flag: "--filter-tag" },
@@ -411,8 +429,8 @@ export const PI_UPDATE_MANY_FILTER_OPTION_CONTRACTS = [
     { param: "limit", flag: "--limit" },
     { param: "offset", flag: "--offset" },
 ];
-export const PI_NORMALIZE_FILTER_OPTION_CONTRACTS = [...PI_UPDATE_MANY_FILTER_OPTION_CONTRACTS];
-export const PI_CALENDAR_OPTION_CONTRACTS = [
+export const TOOL_NORMALIZE_FILTER_OPTION_CONTRACTS = [...TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS];
+export const TOOL_CALENDAR_OPTION_CONTRACTS = [
     { param: "view", flag: "--view" },
     { param: "date", flag: "--date" },
     { param: "from", flag: "--from" },
@@ -432,7 +450,7 @@ export const PI_CALENDAR_OPTION_CONTRACTS = [
     { param: "limit", flag: "--limit" },
     { param: "format", flag: "--format" },
 ];
-export const PI_ACTIVITY_OPTION_CONTRACTS = [
+export const TOOL_ACTIVITY_OPTION_CONTRACTS = [
     { param: "id", flag: "--id" },
     { param: "op", flag: "--op" },
     { param: "author", flag: "--author" },
@@ -440,7 +458,7 @@ export const PI_ACTIVITY_OPTION_CONTRACTS = [
     { param: "to", flag: "--to" },
     { param: "limit", flag: "--limit" },
 ];
-export const PI_CONTEXT_OPTION_CONTRACTS = [
+export const TOOL_CONTEXT_OPTION_CONTRACTS = [
     { param: "date", flag: "--date" },
     { param: "from", flag: "--from" },
     { param: "to", flag: "--to" },
@@ -458,7 +476,7 @@ export const PI_CONTEXT_OPTION_CONTRACTS = [
     { param: "activityLimit", flag: "--activity-limit" },
     { param: "staleThreshold", flag: "--stale-threshold" },
 ];
-export const PI_DEPS_OPTION_CONTRACTS = [
+export const TOOL_DEPS_OPTION_CONTRACTS = [
     { param: "format", flag: "--format" },
     { param: "maxDepth", flag: "--max-depth" },
     { param: "collapse", flag: "--collapse" },
@@ -655,6 +673,17 @@ export const EXTENSION_FLAG_CONTRACTS = [
     { flag: "--strict-exit" },
     { flag: "--fail-on-warn" },
 ];
+export const UPGRADE_FLAG_CONTRACTS = [
+    { flag: "--dry-run" },
+    { flag: "--cli-only" },
+    { flag: "--packages-only" },
+    { flag: "--project" },
+    { flag: "--local" },
+    { flag: "--global" },
+    { flag: "--repair" },
+    { flag: "--tag" },
+    { flag: "--package-name" },
+];
 export const REINDEX_FLAG_CONTRACTS = [
     { flag: "--mode" },
     { flag: "--progress" },
@@ -1253,7 +1282,12 @@ export function resolveSubcommandFlagContractsForCommand(commandName) {
         case "config":
             return withSubcommandGlobalFlags(CONFIG_FLAG_CONTRACTS);
         case "extension":
+        case "package":
+        case "packages":
+        case "install":
             return withSubcommandGlobalFlags(EXTENSION_FLAG_CONTRACTS);
+        case "upgrade":
+            return withSubcommandGlobalFlags(UPGRADE_FLAG_CONTRACTS);
         case "create":
             return withSubcommandGlobalFlags(CREATE_FLAG_CONTRACTS);
         case "aggregate":
@@ -1727,6 +1761,10 @@ const PM_TOOL_PARAMETER_PROPERTIES = {
     allowAuditDepUpdate: { type: "boolean" },
     allowAuditRelease: { type: "boolean" },
     dryRun: { type: "boolean" },
+    cliOnly: { type: "boolean" },
+    packagesOnly: { type: "boolean" },
+    repair: { type: "boolean" },
+    packageName: { type: "string" },
     rollback: { type: "string" },
     noCheckpoint: { type: "boolean" },
     force: { type: "boolean" },
@@ -1796,8 +1834,8 @@ function toSchemaKeyList(values) {
     return normalizeUniqueStringList(values);
 }
 const CREATE_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_CREATE_OPTION_CONTRACTS.map((entry) => entry.param),
-    ...PI_SHARED_CREATE_UPDATE_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_CREATE_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS.map((entry) => entry.param),
     "assignee",
 ]);
 const TEMPLATE_SAVE_UNSUPPORTED_PARAMETER_KEYS = new Set([
@@ -1817,19 +1855,19 @@ const TEMPLATE_SAVE_UNSUPPORTED_PARAMETER_KEYS = new Set([
 ]);
 const TEMPLATE_SAVE_CONTRACT_PARAMETER_KEYS = toSchemaKeyList(CREATE_CONTRACT_PARAMETER_KEYS.filter((key) => !TEMPLATE_SAVE_UNSUPPORTED_PARAMETER_KEYS.has(key)));
 const UPDATE_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_UPDATE_OPTION_CONTRACTS.map((entry) => entry.param),
-    ...PI_SHARED_CREATE_UPDATE_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_UPDATE_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS.map((entry) => entry.param),
     "force",
 ]);
 const UPDATE_MANY_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_UPDATE_MANY_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
     ...UPDATE_CONTRACT_PARAMETER_KEYS,
     "dryRun",
     "rollback",
     "noCheckpoint",
 ]);
 const NORMALIZE_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_NORMALIZE_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_NORMALIZE_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
     "dryRun",
     "apply",
     "author",
@@ -1838,30 +1876,30 @@ const NORMALIZE_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     "force",
 ]);
 const CALENDAR_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_CALENDAR_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_CALENDAR_OPTION_CONTRACTS.map((entry) => entry.param),
     "past",
     "fullPeriod",
 ]);
 const CONTEXT_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_CONTEXT_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_CONTEXT_OPTION_CONTRACTS.map((entry) => entry.param),
     "past",
     "section",
 ]);
 const ACTIVITY_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_ACTIVITY_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_ACTIVITY_OPTION_CONTRACTS.map((entry) => entry.param),
     "stream",
 ]);
 const LIST_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_LIST_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_LIST_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
     "includeBody",
     "compact",
 ]);
 const AGGREGATE_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
-    ...PI_AGGREGATE_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_AGGREGATE_OPTION_CONTRACTS.map((entry) => entry.param),
     "count",
     "includeUnparented",
 ]);
-const DEDUPE_AUDIT_CONTRACT_PARAMETER_KEYS = toSchemaKeyList(PI_DEDUPE_AUDIT_OPTION_CONTRACTS.map((entry) => entry.param));
+const DEDUPE_AUDIT_CONTRACT_PARAMETER_KEYS = toSchemaKeyList(TOOL_DEDUPE_AUDIT_OPTION_CONTRACTS.map((entry) => entry.param));
 const SEARCH_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     "query",
     "keywords",
@@ -1871,7 +1909,7 @@ const SEARCH_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     "phraseExact",
     "compact",
     "full",
-    ...PI_SEARCH_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
+    ...TOOL_SEARCH_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
 ]);
 const AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS = ["author", "message", "force"];
 const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
@@ -1920,6 +1958,53 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "failOnWarn",
         ],
     },
+    "package-init": { required: ["target"], optional: ["scope"] },
+    "package-install": {
+        optional: ["target", "github", "scope", "ref"],
+        anyOfRequired: [["target"], ["github"]],
+    },
+    "package-uninstall": { required: ["target"], optional: ["scope"] },
+    "package-explore": { optional: ["scope"] },
+    "package-manage": { optional: ["scope", "runtimeProbe", "fixManagedState"] },
+    "package-reload": { optional: ["scope", "watch"] },
+    "package-doctor": { optional: ["scope", "detail", "trace", "fixManagedState", "strictExit", "failOnWarn"] },
+    "package-adopt": { required: ["target"], optional: ["scope", "github", "ref"] },
+    "package-adopt-all": { optional: ["scope"] },
+    "package-activate": { required: ["target"], optional: ["scope"] },
+    "package-deactivate": { required: ["target"], optional: ["scope"] },
+    package: {
+        optional: [
+            "target",
+            "scope",
+            "github",
+            "ref",
+            "init",
+            "install",
+            "uninstall",
+            "explore",
+            "manage",
+            "reload",
+            "doctor",
+            "adopt",
+            "adoptAll",
+            "activate",
+            "deactivate",
+            "runtimeProbe",
+            "fixManagedState",
+            "detail",
+            "trace",
+            "watch",
+            "strictExit",
+            "failOnWarn",
+        ],
+    },
+    install: {
+        optional: ["target", "github", "scope", "ref"],
+        anyOfRequired: [["target"], ["github"]],
+    },
+    upgrade: {
+        optional: ["target", "scope", "dryRun", "cliOnly", "packagesOnly", "repair", "tag", "packageName"],
+    },
     create: {
         required: ["title", "description", "type", "status", "priority", "message"],
         optional: CREATE_CONTRACT_PARAMETER_KEYS,
@@ -2148,17 +2233,34 @@ const PM_TOOL_PARAMETER_METADATA = {
         description: "When true for extension-manage/extension-doctor, adopt unmanaged extensions before diagnostics/update checks.",
     },
     target: {
-        description: "Positional target argument for the selected action (ID, source, or extension name).",
+        description: "Positional target argument for the selected action (ID, source, package source, or extension name).",
         examples: ["pm-a1b2", ".agents/pm/extensions/sample", "sample-extension"],
     },
     github: {
-        description: "GitHub shorthand owner/repo[/path] source for extension install actions.",
-        examples: ["unbraind/pm-cli/pi"],
+        description: "GitHub shorthand owner/repo[/path] source for package/extension install actions.",
+        examples: ["org/repo/extensions/sample"],
     },
     ref: {
         description: "Git ref/branch/tag used when installing from GitHub shorthand/URL sources.",
         examples: ["main", "v1.0.0"],
     },
+    cliOnly: {
+        description: "Restrict upgrade to the pm CLI/SDK npm package.",
+    },
+    packagesOnly: {
+        description: "Restrict upgrade to managed installable pm packages.",
+    },
+    repair: {
+        description: "Force npm global reinstall semantics when upgrading the pm CLI/SDK.",
+    },
+    tag: {
+        description: "npm version or dist-tag used for CLI and registry package upgrades.",
+        examples: ["latest", "next", "2026.5.11"],
+    },
+    packageName: {
+        description: "Override the pm CLI package name for self-upgrade automation and tests.",
+        examples: ["@unbrained/pm-cli"],
+    },
     json: {
         description: "Emit machine-readable JSON output.",
     },
@@ -2175,7 +2277,7 @@ const PM_TOOL_PARAMETER_METADATA = {
         description: "Emit deterministic timing diagnostics to stderr.",
     },
     timeoutMs: {
-        description: "Pi wrapper execution timeout in milliseconds.",
+        description: "Tool execution timeout in milliseconds.",
         examples: [120000],
     },
     id: {
@@ -2646,8 +2748,8 @@ function buildActionScopedToolSchema(action) {
 }
 export const PM_TOOL_PARAMETERS_SCHEMA = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
-    $id: "https://unbrained.dev/schemas/pm-cli/tool-parameters-v4.schema.json",
-    title: "pm-cli Pi wrapper parameters (action-scoped strict schema)",
+    $id: "https://schema.unbrained.dev/pm-cli/tool-parameters-v4.schema.json",
+    title: "pm-cli tool parameters (action-scoped strict schema)",
     "x-schema-version": "4.0.1",
     type: "object",
     oneOf: PM_TOOL_ACTIONS.map((action) => buildActionScopedToolSchema(action)),
@@ -2672,7 +2774,7 @@ function toProviderCompatibleParameterDefinition(key, definition) {
         type: "string",
     };
 }
-function buildProviderCompatiblePiToolSchema() {
+function buildProviderCompatibleToolSchema() {
     const properties = {
         action: {
             type: "string",
@@ -2688,7 +2790,7 @@ function buildProviderCompatiblePiToolSchema() {
         properties[key] = toProviderCompatibleParameterDefinition(key, PM_TOOL_PARAMETER_PROPERTIES[key]);
     }
     return {
-        title: "pm-cli Pi tool parameters (provider-compatible flat schema)",
+        title: "pm-cli tool parameters (provider-compatible flat schema)",
         "x-schema-version": "1.0.0",
         type: "object",
         additionalProperties: false,
@@ -2696,5 +2798,5 @@ function buildProviderCompatiblePiToolSchema() {
         properties,
     };
 }
-export const PM_PI_TOOL_PARAMETERS_SCHEMA = buildProviderCompatiblePiToolSchema();
+export const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA = buildProviderCompatibleToolSchema();
 //# sourceMappingURL=cli-contracts.js.map