@unbrained/pm-cli 2026.8.5 → 2026.8.6

package/dist/sdk/extension/install-sources.js

@@ -4,7 +4,7 @@
  * Implements extension package-management support for Install Sources.
  */
 
-!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]="0c87e77d-e7c5-5f0c-aad6-b047e33ccb25")}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]="8994c8e2-8e3a-5e00-a3ca-7bd553c045d7")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -29,6 +29,39 @@ const LOCAL_PACKAGE_ARCHIVE_LIMITS = {
     maxEntryBytes: 64 * 1024 * 1024,
 };
 let bundledPackageAliasesCache;
+/** Resolve an already-installed npm package without executing package code. */
+export async function findInstalledNpmPackageCandidate(packageName, cwd = process.cwd()) {
+    const normalized = packageName.trim();
+    if (!/^(@[^/\\\s]+\/[^/\\\s]+|[^@/\\\s][^/\\\s]*)$/u.test(normalized)) {
+        return null;
+    }
+    let current = path.resolve(cwd);
+    while (true) {
+        const directory = path.join(current, "node_modules", ...normalized.split("/"));
+        const manifestPath = path.join(directory, "package.json");
+        if (await pathExists(manifestPath)) {
+            try {
+                const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+                if (manifest.name === normalized) {
+                    return {
+                        package: normalized,
+                        ...(typeof manifest.version === "string"
+                            ? { version: manifest.version }
+                            : {}),
+                        directory,
+                    };
+                }
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
 function parseGithubPathSpec(pathSpec, input, refOverride) {
     const segments = pathSpec
         .split("/")
@@ -916,6 +949,7 @@ export const _testOnlyInstallSources = {
     resolveNpmSourceDirectoryWithRunner,
     resolveNpmSourceDirectory,
     resolveNpmPackSpec,
+    findInstalledNpmPackageCandidate,
     resolvePackageExtensionDirectory,
     runtimeDependencyInstallSpecs,
     hasHostedPmCliDependency,
@@ -925,4 +959,4 @@ export const _testOnlyInstallSources = {
     runNpmCommand,
 };
 //# sourceMappingURL=install-sources.js.map
-//# debugId=0c87e77d-e7c5-5f0c-aad6-b047e33ccb25
+//# debugId=8994c8e2-8e3a-5e00-a3ca-7bd553c045d7

package/dist/sdk/extension/migrations.d.ts

@@ -0,0 +1,114 @@
+import type { RegisteredExtensionSchemaMigrationDefinition } from "../../core/extensions/extension-types.js";
+import type { ExtensionCommandResult, ExtensionScope } from "../extension.js";
+/** Durable lifecycle state of one extension migration in one workspace. */
+export type ExtensionMigrationOutcomeStatus = "applied" | "failed";
+/** One durable extension-migration outcome. */
+export interface ExtensionMigrationStateEntry {
+    /** Stable layer/name/id identity. */
+    key: string;
+    /** Extension installation layer. */
+    layer: "global" | "project";
+    /** Owning extension name. */
+    extension: string;
+    /** Migration identifier declared by the extension. */
+    id: string;
+    /** Last durable outcome. */
+    status: ExtensionMigrationOutcomeStatus;
+    /** ISO timestamp for the last attempt. */
+    attempted_at: string;
+    /** Failure text retained only for failed outcomes. */
+    error?: string;
+}
+/** Versioned workspace state for extension migrations. */
+export interface ExtensionMigrationState {
+    /** Storage schema version. */
+    version: 1;
+    /** Last state change timestamp. */
+    updated_at: string;
+    /** Deterministically sorted outcomes. */
+    entries: ExtensionMigrationStateEntry[];
+}
+/** Planned or executed row returned for one registered migration. */
+export interface ExtensionMigrationReceipt {
+    /** Stable layer/name/id identity. */
+    key: string;
+    /** Extension installation layer. */
+    layer: "global" | "project";
+    /** Owning extension name. */
+    extension: string;
+    /** Migration identifier. */
+    id: string;
+    /** State observed before this invocation. */
+    before: "pending" | ExtensionMigrationOutcomeStatus;
+    /** Invocation outcome. */
+    outcome: "pending" | "applied" | "skipped" | "failed";
+    /** Failure text for failed execution. */
+    error?: string;
+}
+/** Structured plan/application envelope for extension migrations. */
+export interface ExtensionMigrationRunResult {
+    /** Whether the invocation executed no failing migration. */
+    ok: boolean;
+    /** Whether execution was suppressed. */
+    dry_run: boolean;
+    /** Durable state path. */
+    state_path: string;
+    /** Total registered migrations in scope. */
+    total: number;
+    /** Pending rows in the returned receipt. */
+    pending_count: number;
+    /** Applied rows in the returned receipt. */
+    applied_count: number;
+    /** Already-applied rows skipped idempotently. */
+    skipped_count: number;
+    /** Failed rows in the returned receipt. */
+    failed_count: number;
+    /** Deterministically ordered per-migration receipts. */
+    migrations: ExtensionMigrationReceipt[];
+}
+/** Options for planning or applying active extension migrations. */
+export interface RunExtensionMigrationsOptions {
+    /** Tracker root that owns durable migration state. */
+    pmRoot: string;
+    /** Active runtime registrations. */
+    migrations: RegisteredExtensionSchemaMigrationDefinition[];
+    /** Audit author written to workspace history. */
+    author: string;
+    /** Report pending work without invoking extension code. */
+    dryRun?: boolean;
+    /** Limit execution and receipts to one installation layer. */
+    scope?: "global" | "project";
+}
+/** Minimal lifecycle context required by the migration action dispatcher. */
+export interface ExtensionMigrationActionContext {
+    /** Selected package scope. */
+    scope: ExtensionScope;
+    /** Tracker and settings roots for the invocation. */
+    resolvedRoots: {
+        pm_root: string;
+        settings_root: string;
+    };
+    /** Mutable warning collection shared with the lifecycle result. */
+    warnings: string[];
+    /** Migration-specific command options. */
+    options: {
+        dryRun?: boolean;
+    };
+    /** Relevant global runtime options. */
+    global: {
+        noExtensions?: boolean;
+        author?: string;
+    };
+    /** Construct the standard extension lifecycle result envelope. */
+    withResult: (details: Record<string, unknown>, ok?: boolean) => ExtensionCommandResult;
+}
+/** Return the durable workspace path for extension migration state. */
+export declare function resolveExtensionMigrationStatePath(pmRoot: string): string;
+/** Read durable extension migration outcomes, degrading absent state to empty. */
+export declare function readExtensionMigrationState(pmRoot: string): Promise<ExtensionMigrationState>;
+/** Overlay durable outcomes onto freshly activated migration definitions. */
+export declare function applyStoredExtensionMigrationState(pmRoot: string, migrations: RegisteredExtensionSchemaMigrationDefinition[]): Promise<ExtensionMigrationState>;
+/** Plan or apply active extension migrations with durable idempotency receipts. */
+export declare function runExtensionMigrations(options: RunExtensionMigrationsOptions): Promise<ExtensionMigrationRunResult>;
+/** Load active registrations and execute the extension lifecycle migrate action. */
+export declare function runExtensionMigrateAction(context: ExtensionMigrationActionContext): Promise<ExtensionCommandResult>;

package/dist/sdk/extension/migrations.js

@@ -0,0 +1,175 @@
+/**
+ * @module sdk/extension/migrations
+ *
+ * Provides durable planning and execution for extension-owned schema migrations.
+ */
+
+!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]="56290db9-933c-590d-8b9f-df62ff45e515")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathExists } from "../../core/fs/fs-utils.js";
+import { activateExtensions, loadExtensions } from "../../core/extensions/index.js";
+import { writeWorkspaceJsonWithHistory } from "../../core/history/workspace-history.js";
+import { readSettings } from "../../core/store/settings.js";
+/** Return the durable workspace path for extension migration state. */
+export function resolveExtensionMigrationStatePath(pmRoot) {
+    return path.join(pmRoot, "extension-migrations.json");
+}
+function migrationId(migration, index) {
+    const id = migration.definition.id;
+    return typeof id === "string" && id.trim().length > 0
+        ? id.trim()
+        : `migration-${String(index + 1).padStart(3, "0")}`;
+}
+function migrationKey(migration, id) {
+    return `${migration.layer}:${migration.name}:${id}`;
+}
+/** Read durable extension migration outcomes, degrading absent state to empty. */
+export async function readExtensionMigrationState(pmRoot) {
+    const statePath = resolveExtensionMigrationStatePath(pmRoot);
+    if (!(await pathExists(statePath))) {
+        return { version: 1, updated_at: "", entries: [] };
+    }
+    const parsed = JSON.parse(await fs.readFile(statePath, "utf8"));
+    return {
+        version: 1,
+        updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : "",
+        entries: Array.isArray(parsed.entries)
+            ? parsed.entries.filter((entry) => typeof entry?.key === "string" &&
+                (entry.status === "applied" || entry.status === "failed"))
+            : [],
+    };
+}
+/** Overlay durable outcomes onto freshly activated migration definitions. */
+export async function applyStoredExtensionMigrationState(pmRoot, migrations) {
+    const state = await readExtensionMigrationState(pmRoot);
+    const byKey = new Map(state.entries.map((entry) => [entry.key, entry]));
+    migrations.forEach((migration, index) => {
+        const id = migrationId(migration, index);
+        const entry = byKey.get(migrationKey(migration, id));
+        if (!entry)
+            return;
+        migration.definition.status = entry.status;
+        if (entry.status === "failed") {
+            migration.definition.reason = entry.error;
+        }
+        else {
+            delete migration.definition.reason;
+            delete migration.definition.error;
+            delete migration.definition.message;
+        }
+    });
+    return state;
+}
+/** Plan or apply active extension migrations with durable idempotency receipts. */
+export async function runExtensionMigrations(options) {
+    const state = await applyStoredExtensionMigrationState(options.pmRoot, options.migrations);
+    const stateByKey = new Map(state.entries.map((entry) => [entry.key, entry]));
+    const receipts = [];
+    let changed = false;
+    const scopedMigrations = options.migrations
+        .map((migration, index) => ({ migration, index }))
+        .filter(({ migration }) => options.scope === undefined || migration.layer === options.scope);
+    for (const { migration, index } of scopedMigrations) {
+        const id = migrationId(migration, index);
+        const key = migrationKey(migration, id);
+        const stored = stateByKey.get(key);
+        const declaredStatus = String(migration.definition.status ?? "pending").toLowerCase();
+        const before = stored?.status ?? (declaredStatus === "applied" || declaredStatus === "failed" ? declaredStatus : "pending");
+        if (before === "applied") {
+            receipts.push({ key, layer: migration.layer, extension: migration.name, id, before, outcome: "skipped" });
+            continue;
+        }
+        if (options.dryRun === true) {
+            receipts.push({ key, layer: migration.layer, extension: migration.name, id, before, outcome: "pending" });
+            continue;
+        }
+        const run = migration.runtime_definition?.run ?? migration.definition.run;
+        if (typeof run !== "function") {
+            receipts.push({ key, layer: migration.layer, extension: migration.name, id, before, outcome: "pending" });
+            continue;
+        }
+        const attemptedAt = new Date().toISOString();
+        try {
+            await Promise.resolve(run({ id, command: "migration", layer: migration.layer, extension: migration.name, pm_root: options.pmRoot, status: before }));
+            const entry = { key, layer: migration.layer, extension: migration.name, id, status: "applied", attempted_at: attemptedAt };
+            stateByKey.set(key, entry);
+            migration.definition.status = "applied";
+            delete migration.definition.reason;
+            delete migration.definition.error;
+            delete migration.definition.message;
+            receipts.push({ key, layer: migration.layer, extension: migration.name, id, before, outcome: "applied" });
+            changed = true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const entry = { key, layer: migration.layer, extension: migration.name, id, status: "failed", attempted_at: attemptedAt, error: message };
+            stateByKey.set(key, entry);
+            migration.definition.status = "failed";
+            migration.definition.reason = message;
+            receipts.push({ key, layer: migration.layer, extension: migration.name, id, before, outcome: "failed", error: message });
+            changed = true;
+        }
+    }
+    if (changed) {
+        const settings = await readSettings(options.pmRoot);
+        const nextState = {
+            version: 1,
+            updated_at: new Date().toISOString(),
+            entries: [...stateByKey.values()].sort((left, right) => left.key.localeCompare(right.key)),
+        };
+        await writeWorkspaceJsonWithHistory({
+            pmRoot: options.pmRoot,
+            filePath: resolveExtensionMigrationStatePath(options.pmRoot),
+            raw: `${JSON.stringify(nextState, null, 2)}\n`,
+            op: "extension_migrations_apply",
+            author: options.author,
+            lockTtlSeconds: settings.locks.ttl_seconds,
+            lockWaitMs: settings.locks.wait_ms,
+        });
+    }
+    const pendingCount = receipts.filter((receipt) => receipt.outcome === "pending").length;
+    const appliedCount = receipts.filter((receipt) => receipt.outcome === "applied").length;
+    const skippedCount = receipts.filter((receipt) => receipt.outcome === "skipped").length;
+    const failedCount = receipts.filter((receipt) => receipt.outcome === "failed").length;
+    return {
+        ok: failedCount === 0,
+        dry_run: options.dryRun === true,
+        state_path: resolveExtensionMigrationStatePath(options.pmRoot),
+        total: receipts.length,
+        pending_count: pendingCount,
+        applied_count: appliedCount,
+        skipped_count: skippedCount,
+        failed_count: failedCount,
+        migrations: receipts,
+    };
+}
+/** Load active registrations and execute the extension lifecycle migrate action. */
+export async function runExtensionMigrateAction(context) {
+    const settings = await readSettings(context.resolvedRoots.settings_root);
+    const loaded = await loadExtensions({
+        pmRoot: context.resolvedRoots.pm_root,
+        settings,
+        cwd: process.cwd(),
+        noExtensions: context.global.noExtensions === true,
+    });
+    const activated = await activateExtensions(loaded);
+    context.warnings.push(...loaded.warnings, ...activated.warnings);
+    const migration = await runExtensionMigrations({
+        pmRoot: context.resolvedRoots.pm_root,
+        migrations: activated.registrations.migrations,
+        author: typeof context.global.author === "string" &&
+            context.global.author.trim().length > 0
+            ? context.global.author.trim()
+            : "pm-extension-migration",
+        dryRun: context.options.dryRun === true,
+        ...(context.scope === "global" ? { scope: "global" } : {}),
+    });
+    return context.withResult({
+        migration,
+        load_failure_count: loaded.failed.length,
+        activation_failure_count: activated.failed.length,
+    }, migration.ok);
+}
+//# sourceMappingURL=migrations.js.map
+//# debugId=56290db9-933c-590d-8b9f-df62ff45e515

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 {