@unbrained/pm-cli 2026.8.4 → 2026.8.6

package/dist/sdk/extension/scaffold.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Scaffold.
  */
 
-!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]="50f2e5c4-c7fe-5e29-ae2a-60b1b1957756")}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]="30dfc6e4-27c5-56c0-981b-94e85b780f1f")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists } from "../../core/fs/fs-utils.js";
@@ -276,8 +276,9 @@ const PACKAGE_CAPABILITY_README_SECTIONS = {
         "",
         "## Preflight Override",
         "`index.ts` registers a preflight override through `api.registerPreflight`. pm",
-        "calls it before every command to compute the migration/format gate decision —",
-        "the last registered override wins. Return only the decision keys you want to",
+        "calls it only for its declared command ownership to compute the migration/format",
+        "gate decision. Overlapping or legacy global ownership is diagnosed. Return only",
+        "the decision keys you want to",
         "change; this starter echoes the current decision unchanged (a safe no-op) so",
         "installing the package does not alter gate behavior. The `preflight`",
         "capability in `manifest.json` grants the registration.",
@@ -765,15 +766,19 @@ function buildActivateBodyLines(extensionName, commandName, capability) {
             ...commandLines,
             "",
             "  // Preflight overrides adjust pm's pre-run gate decision (extension",
-            "  // migrations + item-format checks) before EVERY command — the last",
-            "  // registered override wins. Return a delta of the keys you want to change",
+            "  // migrations + item-format checks) for the commands it owns. Disjoint",
+            "  // packages compose; overlapping or legacy global ownership is diagnosed.",
+            "  // Return a delta of the keys you want to change",
             "  // (enforce_item_format_gate, run_preflight_item_format_sync,",
             "  // run_extension_migrations, enforce_mandatory_migration_gate); returning",
             "  // context.decision unchanged is a safe no-op so installing the package does",
             "  // not alter gate behavior — replace it with your policy, e.g.",
             "  // `{ run_extension_migrations: false }`. The `preflight` capability in",
             "  // manifest.json grants the registration.",
-            "  api.registerPreflight((context) => context.decision);",
+            "  api.registerPreflight({",
+            `    commands: [${JSON.stringify(commandName)}],`,
+            "    run: (context) => context.decision,",
+            "  });",
         ];
     }
     if (capability === "services") {
@@ -1339,7 +1344,7 @@ function buildDeclarativeBlueprintSurface(extensionName, commandName, capability
             break;
         case "preflight":
             builderImports.push("definePreflightOverride");
-            definitions.push("", "// Preflight overrides adjust pm's pre-run gate decision (extension migrations +", "// item-format checks) before EVERY command - the last registered override wins.", "// Return a delta of the keys you want to change (enforce_item_format_gate,", "// run_preflight_item_format_sync, run_extension_migrations,", "// enforce_mandatory_migration_gate); returning context.decision unchanged is a", "// safe no-op - replace it with your policy, e.g. { run_extension_migrations: false }.", "export const preflightOverride = definePreflightOverride((context) => context.decision);");
+            definitions.push("", "// Preflight overrides adjust pm's pre-run gate decision (extension migrations +", "// item-format checks) for the commands it owns. Scoped ownership composes with", "// other packages; overlapping or legacy global ownership is diagnosed.", "// Return a delta of the keys you want to change (enforce_item_format_gate,", "// run_preflight_item_format_sync, run_extension_migrations,", "// enforce_mandatory_migration_gate); returning context.decision unchanged is a", "// safe no-op - replace it with your policy, e.g. { run_extension_migrations: false }.", "export const preflightOverride = definePreflightOverride({", `  commands: [${JSON.stringify(commandName)}],`, "  run: (context) => context.decision,", "});");
             blueprintFields.push("  preflights: [preflightOverride],");
             break;
         case "services":
@@ -1963,7 +1968,7 @@ function buildDefineBuilderExports(extensionName, commandName, capability, names
         lines.push("", "export const pingParser = defineParserOverride((context) => {", "  const options = { ...context.options };", "  if (options.shout === true) options.upper = true;", "  delete options.shout;", "  return { options };", "});");
     }
     if (capability === "preflight") {
-        lines.push("", "// Return a delta of the gate-decision keys you want to change; returning", "// context.decision unchanged is a safe no-op (e.g. { run_extension_migrations: false }).", "export const preflightOverride = definePreflightOverride((context) => context.decision);");
+        lines.push("", "// Return a delta of the gate-decision keys you want to change; returning", "// context.decision unchanged is a safe no-op (e.g. { run_extension_migrations: false }).", "export const preflightOverride = definePreflightOverride({", `  commands: [${JSON.stringify(commandName)}],`, "  run: (context) => context.decision,", "});");
     }
     if (capability === "services") {
         lines.push("", "export const outputService = defineServiceOverride((context) => {", `  if (context.command !== ${JSON.stringify(commandName)}) return { handled: false };`, `  return { rendered_by: ${JSON.stringify(extensionName)}, payload: context.payload };`, "});");
@@ -2295,4 +2300,4 @@ export async function scaffoldExtensionProject(target, vocabulary = "extension",
     };
 }
 //# sourceMappingURL=scaffold.js.map
-//# debugId=50f2e5c4-c7fe-5e29-ae2a-60b1b1957756
+//# debugId=30dfc6e4-27c5-56c0-981b-94e85b780f1f

package/dist/sdk/extension/source-resolution.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module sdk/extension/source-resolution
+ *
+ * Resolves install-source identity without executing package code.
+ */
+import { type InstallSource } from "./install-sources.js";
+/** Selected install-source identity. */
+export interface ExtensionInstallSourceSelection {
+    /** Selected source family. */
+    kind: "builtin" | "local" | "github" | "npm";
+    /** Canonical source input used for resolution. */
+    input: string;
+    /** Canonical package name when known. */
+    package?: string;
+}
+/** One source candidate and the explicit command that selects it. */
+export interface ExtensionInstallSourceCandidate extends ExtensionInstallSourceSelection {
+    /** Installed candidate version when known. */
+    version?: string;
+    /** Installed candidate directory when relevant. */
+    directory?: string;
+    /** Unambiguous CLI command that selects this candidate. */
+    command: string;
+}
+/** Machine-readable explanation of how one install target resolved. */
+export interface ExtensionInstallSourceResolution {
+    /** Exact target supplied by the caller. */
+    requested: string;
+    /** Source selected by the deterministic resolver. */
+    selected: ExtensionInstallSourceSelection;
+    /** Whether another locally available source could satisfy the same bare name. */
+    ambiguous: boolean;
+    /** Stable precedence rule used for the selection. */
+    precedence: "bundled_alias_before_installed_npm";
+    /** Every matching candidate and its explicit install command. */
+    candidates: ExtensionInstallSourceCandidate[];
+}
+/** Complete result of resolving one extension install target. */
+export interface ResolvedExtensionInstallSource {
+    /** Normalized bundled alias, or null for non-bundled sources. */
+    bundledAliasName: string | null;
+    /** Bundled package name, or null when unavailable. */
+    bundledPackageName: string | null;
+    /** Parsed source passed to the install resolver. */
+    installSource: InstallSource;
+    /** Observable source-selection decision. */
+    sourceResolution: ExtensionInstallSourceResolution;
+}
+/** Resolve bundled-alias provenance and competing installed npm identity. */
+export declare function resolveExtensionInstallSourceIdentity(explicitSourceInput: string, githubOption: string | undefined, ref: string | undefined): Promise<ResolvedExtensionInstallSource>;

package/dist/sdk/extension/source-resolution.js

@@ -0,0 +1,66 @@
+/**
+ * @module sdk/extension/source-resolution
+ *
+ * Resolves install-source identity without executing package code.
+ */
+
+!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]="39bc7f14-2d32-5b58-97ab-647f9f238273")}catch(e){}}();
+import { findInstalledNpmPackageCandidate, parseExtensionInstallSource, } from "./install-sources.js";
+import { resolveBundledExtensionAliasSource, resolveBundledPackageNpmName, } from "./bundled-catalog.js";
+/** Resolve bundled-alias provenance and competing installed npm identity. */
+export async function resolveExtensionInstallSourceIdentity(explicitSourceInput, githubOption, ref) {
+    const bundledAliasSource = typeof githubOption === "string"
+        ? null
+        : await resolveBundledExtensionAliasSource(explicitSourceInput);
+    const bundledAliasName = bundledAliasSource === null
+        ? null
+        : explicitSourceInput.trim().toLowerCase();
+    const bundledPackageName = bundledAliasName === null
+        ? null
+        : await resolveBundledPackageNpmName(bundledAliasName);
+    const installSource = parseExtensionInstallSource(bundledAliasSource ?? explicitSourceInput, { forceGithub: typeof githubOption === "string", ref });
+    const installedNpmCandidate = bundledAliasName === null
+        ? null
+        : await findInstalledNpmPackageCandidate(explicitSourceInput);
+    return {
+        bundledAliasName,
+        bundledPackageName,
+        installSource,
+        sourceResolution: {
+            requested: explicitSourceInput,
+            selected: {
+                kind: bundledAliasName === null ? installSource.kind : "builtin",
+                input: bundledAliasName ?? installSource.input,
+                ...(bundledPackageName === null ? {} : { package: bundledPackageName }),
+            },
+            ambiguous: installedNpmCandidate !== null,
+            precedence: "bundled_alias_before_installed_npm",
+            candidates: [
+                ...(bundledAliasName === null
+                    ? []
+                    : [{
+                            kind: "builtin",
+                            input: bundledAliasName,
+                            ...(bundledPackageName === null
+                                ? {}
+                                : { package: bundledPackageName }),
+                            command: `pm install ${bundledAliasName}`,
+                        }]),
+                ...(installedNpmCandidate === null
+                    ? []
+                    : [{
+                            kind: "npm",
+                            input: `npm:${installedNpmCandidate.package}`,
+                            package: installedNpmCandidate.package,
+                            ...(installedNpmCandidate.version === undefined
+                                ? {}
+                                : { version: installedNpmCandidate.version }),
+                            directory: installedNpmCandidate.directory,
+                            command: `pm install npm:${installedNpmCandidate.package}`,
+                        }]),
+            ],
+        },
+    };
+}
+//# sourceMappingURL=source-resolution.js.map
+//# debugId=39bc7f14-2d32-5b58-97ab-647f9f238273

package/dist/sdk/extension.d.ts

@@ -16,7 +16,7 @@ export { parseExtensionManifest, validateExtensionDirectory, readManagedExtensio
 export type { ManagedExtensionSource, ManagedExtensionRecord, ManagedExtensionState, };
 export type { ManagedExtensionStateReadResult } from "./extension/managed-state.js";
 /** Restricts extension command action values accepted by command, SDK, and storage contracts. */
-export type ExtensionCommandAction = "install" | "uninstall" | "explore" | "manage" | "describe" | "reload" | "doctor" | "catalog" | "adopt" | "adopt-all" | "activate" | "deactivate" | "init";
+export type ExtensionCommandAction = "install" | "uninstall" | "explore" | "manage" | "describe" | "reload" | "doctor" | "catalog" | "adopt" | "adopt-all" | "activate" | "deactivate" | "migrate" | "init";
 /** Restricts extension scope values accepted by command, SDK, and storage contracts. */
 export type ExtensionScope = "project" | "global";
 /** Restricts extension activation status values accepted by command, SDK, and storage contracts. */
@@ -59,6 +59,8 @@ export interface ExtensionCommandOptions {
     activate?: boolean;
     /** Value that configures or reports deactivate for this contract. */
     deactivate?: boolean;
+    /** Plan or apply active extension migrations. */
+    migrate?: boolean;
     /** Value that configures or reports project for this contract. */
     project?: boolean;
     /** Value that configures or reports local for this contract. */
@@ -93,6 +95,8 @@ export interface ExtensionCommandOptions {
     declarative?: boolean;
     /** Value that configures or reports vocabulary for this contract. */
     vocabulary?: "extension" | "package";
+    /** Plan migration work without invoking extension code. */
+    dryRun?: boolean;
 }
 /** Documents the managed extension summary payload exchanged by command, SDK, and package integrations. */
 export interface ManagedExtensionSummary {

package/dist/sdk/extension.js

@@ -4,7 +4,7 @@
  * Implements the pm extension 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]="4fb93ad8-845c-5b71-93eb-c95481f101b7")}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]="f4f1a871-b632-5263-aec0-cb00bcdbe1b3")}catch(e){}}();
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -30,7 +30,7 @@ import { ensureTypeFolderScaffold } from "./schema.js";
 import { normalizeStringList, normalizeExtensionNameForMatch, normalizeManagedDirectoryName, parseExtensionManifest, validateExtensionDirectory, } from "./extension/shared.js";
 import { sortManagedEntries, managedExtensionSourcesEquivalent, readManagedExtensionState, writeManagedExtensionState, upsertManagedEntry, persistManagedContributionInventory, resolveManagedExtensionStatePath, } from "./extension/managed-state.js";
 import { parseExtensionInstallSource, resolveInstallSource, areDirectoriesEquivalent, } from "./extension/install-sources.js";
-import { resolveBundledExtensionAliasSource, resolveBundledPackageNpmName, isBundledPackageInstallAllTarget, listBundledPackageAliases, resolveBundledAliasManifestName, buildBundledPackageCatalog, } from "./extension/bundled-catalog.js";
+import { resolveBundledExtensionAliasSource, isBundledPackageInstallAllTarget, listBundledPackageAliases, resolveBundledAliasManifestName, buildBundledPackageCatalog, } from "./extension/bundled-catalog.js";
 import { scaffoldExtensionProject } from "./extension/scaffold.js";
 import { buildExtensionDescribeResult } from "./extension/describe.js";
 import { applyDoctorRuntimeActivationState, classifyDoctorLoadFailureWarnings, classifyDoctorActivationFailureWarnings, classifyUnusedCapabilityWarnings, buildExtensionTriageSummary, parseDoctorDetailMode, collectUnknownCapabilityGuidance, buildCapabilityContractMetadata, buildDoctorConsistencySummary, summarizeExtensionFailures, } from "./extension/doctor.js";
@@ -40,6 +40,8 @@ import { summarizeRuntimeCommandPathsForExtension } from "./extension/runtime-su
 import { collectGlobalOutputOverrideDoctorWarnings } from "./extension/output-ownership.js";
 import { collectMcpCustomFieldCollisionDoctorWarnings } from "./extension/custom-field-collisions.js";
 import { checkGithubUpdate } from "./extension/update-check.js";
+import { runExtensionMigrateAction } from "./extension/migrations.js";
+import { resolveExtensionInstallSourceIdentity, } from "./extension/source-resolution.js";
 import { captureExtensionInstallSnapshot, readOptionalMetadataFile, restoreExtensionInstallSnapshot, } from "./extension/install-snapshot.js";
 // Re-export the public surface that lives in sibling modules but was previously
 // exported from this file (used by sdk barrels, upgrade.ts, and tests).
@@ -61,6 +63,7 @@ const LIFECYCLE_ACTION_TARGETS = [
     ["adopt-all", "adopt-all", "--adopt-all"],
     ["activate", "activate", "--activate"],
     ["deactivate", "deactivate", "--deactivate"],
+    ["migrate", "migrate", "--migrate"],
 ];
 const LIFECYCLE_ACTION_FLAG_HINT = LIFECYCLE_ACTION_TARGETS.map(([, , flag]) => flag)
     .filter((flag, index, flags) => flags.indexOf(flag) === index)
@@ -78,6 +81,7 @@ const LIFECYCLE_ACTION_FLAGS = {
     "adopt-all": "--adopt-all",
     activate: "--activate",
     deactivate: "--deactivate",
+    migrate: "--migrate",
     init: "--init",
 };
 const NATIVE_OUTPUT_MARKER = "__pm_native_output";
@@ -353,6 +357,7 @@ const EXTENSION_ACTION_FLAG_SELECTORS = [
     ["adoptAll", "adopt-all"],
     ["activate", "activate"],
     ["deactivate", "deactivate"],
+    ["migrate", "migrate"],
 ];
 /** Positional lifecycle shorthand mapped to the canonical extension action. */
 const IMPLICIT_EXTENSION_ACTIONS = {
@@ -363,6 +368,7 @@ const IMPLICIT_EXTENSION_ACTIONS = {
     scaffold: "init",
     explore: "explore",
     manage: "manage",
+    migrate: "migrate",
     list: "explore",
     "": "explore",
 };
@@ -889,6 +895,11 @@ const assertExtensionActionOptionScope = (action, options) => {
             allowed: action === "init",
             message: "--declarative is only valid with --init/--scaffold.",
         },
+        {
+            triggered: options.dryRun === true,
+            allowed: action === "migrate",
+            message: "--dry-run is only valid with --migrate.",
+        },
     ];
     const invalidGuard = guards.find((guard) => guard.triggered && !guard.allowed);
     if (invalidGuard) {
@@ -1302,6 +1313,7 @@ const performExtensionInstallUnderLock = async (ctx, input) => {
             directory: destinationDirectoryName,
         },
         source: persisted.sourceRecord,
+        source_resolution: input.sourceResolution,
         destination_path: persisted.destinationDirectory,
         overwritten: [
             persisted.destinationExists,
@@ -1357,6 +1369,7 @@ const runBundledExtensionInstallAll = async (ctx) => {
                 ok: entry.result.ok,
                 extension: details.extension,
                 source: details.source,
+                source_resolution: details.source_resolution,
                 destination_path: details.destination_path,
                 activated: details.activated,
                 settings_changed: details.settings_changed,
@@ -1371,32 +1384,14 @@ const runBundledExtensionInstallAll = async (ctx) => {
         }),
     }, installedAll);
 };
-/** Resolve bundled-alias provenance before installing one extension source. */
-const resolveSingleExtensionInstallSource = async (explicitSourceInput, githubOption, ref) => {
-    /* c8 ignore start -- github/local alias-source split is exercised in install-action integration tests */
-    const bundledAliasSource = typeof githubOption === "string"
-        ? null
-        : await resolveBundledExtensionAliasSource(explicitSourceInput);
-    /* c8 ignore stop */
-    const bundledAliasName = bundledAliasSource === null
-        ? null
-        : explicitSourceInput.trim().toLowerCase();
-    const bundledPackageName = bundledAliasName === null
-        ? null
-        : await resolveBundledPackageNpmName(bundledAliasName);
-    const sourceInput = bundledAliasSource ?? explicitSourceInput;
-    /* c8 ignore start -- install-source branch combinations are covered in install-sources focused tests */
-    const installSource = parseExtensionInstallSource(sourceInput, {
-        forceGithub: typeof githubOption === "string",
-        ref,
-    });
-    /* c8 ignore stop */
-    return { bundledAliasName, bundledPackageName, installSource };
-};
 /** Install one resolved source and clean transient source material afterward. */
 const runSingleExtensionInstall = async (ctx, explicitSourceInput, githubOption) => {
     const { resolvedRoots } = ctx;
-    const { bundledAliasName, bundledPackageName, installSource } = await resolveSingleExtensionInstallSource(explicitSourceInput, githubOption, ctx.options.ref);
+    const { bundledAliasName, bundledPackageName, installSource, sourceResolution, } = await resolveExtensionInstallSourceIdentity(explicitSourceInput, githubOption, ctx.options.ref);
+    if (sourceResolution.ambiguous) {
+        const npmCandidate = sourceResolution.candidates.find((candidate) => candidate.kind === "npm");
+        ctx.warnings.push(`extension_install_source_ambiguous:${explicitSourceInput}:builtin:${bundledAliasName}:npm:${npmCandidate.package}`);
+    }
     const resolvedSource = await resolveInstallSource(installSource);
     try {
         const validated = await validateExtensionDirectory(resolvedSource.directory, {
@@ -1410,6 +1405,7 @@ const runSingleExtensionInstall = async (ctx, explicitSourceInput, githubOption)
             destinationDirectoryName,
             bundledAliasName,
             bundledPackageName,
+            sourceResolution,
             installSource,
             resolvedSource,
         }));
@@ -2147,6 +2143,7 @@ const EXTENSION_ACTION_HANDLERS = {
     "adopt-all": runExtensionAdoptAllAction,
     activate: runExtensionActivateDeactivateAction,
     deactivate: runExtensionActivateDeactivateAction,
+    migrate: runExtensionMigrateAction,
 };
 /** Identify lifecycle actions that mutate shared settings or managed-extension state. */
 const requiresExtensionStateLock = (ctx) => [
@@ -2156,6 +2153,7 @@ const requiresExtensionStateLock = (ctx) => [
     ctx.action === "adopt-all",
     ctx.action === "activate",
     ctx.action === "deactivate",
+    ctx.action === "migrate",
     [ctx.action === "doctor", ctx.options.fixManagedState === true].every(Boolean),
 ].some(Boolean);
 /** Dispatch one normalized lifecycle action through the complete handler table. */
@@ -2194,4 +2192,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=4fb93ad8-845c-5b71-93eb-c95481f101b7
+//# debugId=f4f1a871-b632-5263-aec0-cb00bcdbe1b3