@unbrained/pm-cli 2026.8.4 → 2026.8.6

package/dist/sdk/define.d.ts

@@ -32,7 +32,7 @@
  * non-generic signature lets TypeScript type the handler parameter from the
  * declared function type.
  */
-import type { AfterCommandHook, BeforeCommandHook, BeforeMutationHook, CommandDefinition, CommandOverride, Exporter, ExtensionManifest, FlagDefinition, Importer, OnIndexHook, OnReadHook, OnWriteHook, ParserOverride, PreflightOverride, RendererOverride, ScopedRendererOverrideDefinition, SchemaFieldDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SearchProviderDefinition, ServiceOverride, ServiceOverrideDecision, VectorStoreAdapterDefinition } from "../core/extensions/loader.js";
+import type { AfterCommandHook, BeforeCommandHook, BeforeMutationHook, CommandDefinition, CommandOverride, Exporter, ExtensionManifest, FlagDefinition, Importer, OnIndexHook, OnReadHook, OnWriteHook, ParserOverride, PreflightOverride, ScopedPreflightOverrideDefinition, RendererOverride, ScopedRendererOverrideDefinition, SchemaFieldDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SearchProviderDefinition, ServiceOverride, ServiceOverrideDecision, VectorStoreAdapterDefinition } from "../core/extensions/loader.js";
 import type { ProjectProfileDefinition } from "../core/profile/profile-presets.js";
 type ExactDefinition<TDefinition, TContract> = TDefinition & Record<Exclude<keyof TDefinition, keyof TContract>, never>;
 type FlagAuthoringDefinition = Pick<FlagDefinition, "long" | "short" | "value_name" | "description" | "required" | "enabled" | "visible" | "value_type" | "type" | "list" | "default">;
@@ -145,6 +145,8 @@ export declare function defineParserOverride(override: ParserOverride): ParserOv
  * package's pre-run validation override is checked at the definition site.
  */
 export declare function definePreflightOverride(override: PreflightOverride): PreflightOverride;
+/** Type a scoped preflight definition while preserving literal command ownership. */
+export declare function definePreflightOverride<TDefinition extends ScopedPreflightOverrideDefinition>(override: ExactDefinition<TDefinition, ScopedPreflightOverrideDefinition>): TDefinition;
 /**
  * Type a service-override handler for `api.registerService(service, override)`.
  *

package/dist/sdk/define.js

@@ -9,7 +9,7 @@
  * to keep `capabilities` matched to the surfaces the extension actually registers.
  */
 
-!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]="9212673f-1a9f-50b8-92a2-4fd30ce54351")}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]="7fc669d4-1db2-5636-8304-2c111a684726")}catch(e){}}();
 export function defineExtensionManifest(manifest) {
     return manifest;
 }
@@ -119,12 +119,7 @@ export function defineCommandOverride(override) {
 export function defineParserOverride(override) {
     return override;
 }
-/**
- * Type a preflight-override handler for `api.registerPreflight(override)`.
- *
- * Contextually types the `context` parameter and the returned gate decision so a
- * package's pre-run validation override is checked at the definition site.
- */
+/** Implement the preflight authoring identity for callbacks and scoped definitions. */
 export function definePreflightOverride(override) {
     return override;
 }
@@ -223,4 +218,4 @@ export function defineOnIndexHook(hook) {
     return hook;
 }
 //# sourceMappingURL=define.js.map
-//# debugId=9212673f-1a9f-50b8-92a2-4fd30ce54351
+//# debugId=7fc669d4-1db2-5636-8304-2c111a684726

package/dist/sdk/dependency-provenance.d.ts

@@ -1,5 +1,7 @@
 /** Provenance value declaring that a dependency id belongs to another workspace. */
 export declare const EXTERNAL_DEPENDENCY_SOURCE_KIND = "global";
+/** Human-facing alias accepted wherever external dependency provenance is parsed. */
+export declare const EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS = "external";
 /** Return whether a dependency provenance value identifies an external workspace target. */
 export declare function isExternalDependencySourceKind(sourceKind: string | undefined): boolean;
 /** Canonicalize external provenance while preserving other named source kinds. */

package/dist/sdk/dependency-provenance.js

@@ -5,13 +5,17 @@
  * items outside the current workspace.
  */
 
-!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]="187a7342-71fc-5432-9f30-c40e444d4611")}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]="1b2f1ac3-82b3-58a2-9f40-2dd95ab1b2bc")}catch(e){}}();
 import { normalizeItemId } from "../core/item/id.js";
 /** Provenance value declaring that a dependency id belongs to another workspace. */
 export const EXTERNAL_DEPENDENCY_SOURCE_KIND = "global";
+/** Human-facing alias accepted wherever external dependency provenance is parsed. */
+export const EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS = "external";
 /** Return whether a dependency provenance value identifies an external workspace target. */
 export function isExternalDependencySourceKind(sourceKind) {
-    return sourceKind?.trim().toLowerCase() === EXTERNAL_DEPENDENCY_SOURCE_KIND;
+    const normalized = sourceKind?.trim().toLowerCase();
+    return (normalized === EXTERNAL_DEPENDENCY_SOURCE_KIND ||
+        normalized === EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS);
 }
 /** Canonicalize external provenance while preserving other named source kinds. */
 export function normalizeDependencySourceKind(sourceKind) {
@@ -35,4 +39,4 @@ export function normalizeDependencySeedId(id, prefix, sourceKind) {
         : normalizeItemId(trimmed, prefix);
 }
 //# sourceMappingURL=dependency-provenance.js.map
-//# debugId=187a7342-71fc-5432-9f30-c40e444d4611
+//# debugId=1b2f1ac3-82b3-58a2-9f40-2dd95ab1b2bc

package/dist/sdk/error-code-catalog.d.ts

@@ -6,6 +6,25 @@
  */
 /** Compatibility promise attached to a machine-readable error code. */
 export type PmErrorCodeStability = "provisional" | "stable";
+/** Semantic process-exit class shared by shell and SDK consumers. */
+export type PmErrorCodeClass = "generic_failure" | "usage" | "not_found" | "conflict" | "dependency_failed";
+/** Stable shell exit-code taxonomy shared by every structured error. */
+export declare const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS: readonly [{
+    readonly exit_code: 1;
+    readonly class: "generic_failure";
+}, {
+    readonly exit_code: 2;
+    readonly class: "usage";
+}, {
+    readonly exit_code: 3;
+    readonly class: "not_found";
+}, {
+    readonly exit_code: 4;
+    readonly class: "conflict";
+}, {
+    readonly exit_code: 5;
+    readonly class: "dependency_failed";
+}];
 /** One machine-readable error and its portable recovery contract. */
 export interface PmErrorCodeContract {
     /** Stable snake_case identifier. */
@@ -16,10 +35,14 @@ export interface PmErrorCodeContract {
     stability: PmErrorCodeStability;
     /** Process exit code emitted by the CLI transport. */
     exit_code: 1 | 2 | 3 | 4 | 5;
+    /** Semantic class represented by the process exit code. */
+    class: PmErrorCodeClass;
     /** Actionable caller recovery guidance. */
     recovery: string;
     /** Subsystems that can emit the code. */
     sources: string[];
+    /** CLI command roots inferred from executable declaration ownership. */
+    emitting_commands: string[];
 }
 /** Validate, normalize, sort, and freeze an error-code catalog. */
 export declare function definePmErrorCodeCatalog(declarations: readonly PmErrorCodeContract[]): readonly PmErrorCodeContract[];

package/dist/sdk/error-code-catalog.js

@@ -4,9 +4,24 @@
  * Defines the stable, discoverable error vocabulary used across CLI, SDK, MCP,
  * packages, and generated contract surfaces.
  */
-/** Validate, normalize, sort, and freeze an error-code catalog. */
+/** Stable shell exit-code taxonomy shared by every structured error. */
 
-!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]="804df95b-c2fc-5ea7-bfb5-aea890a65abc")}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]="479dd590-7f54-54ae-bbaf-8f183fd6b6b4")}catch(e){}}();
+export const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS = [
+    { exit_code: 1, class: "generic_failure" },
+    { exit_code: 2, class: "usage" },
+    { exit_code: 3, class: "not_found" },
+    { exit_code: 4, class: "conflict" },
+    { exit_code: 5, class: "dependency_failed" },
+];
+const ERROR_CLASS_BY_EXIT_CODE = new Map(PM_ERROR_CODE_EXIT_CLASS_CONTRACTS.map((contract) => [contract.exit_code, contract.class]));
+/** Normalize a declared non-empty string set into stable contract order. */
+function normalizeContractList(values) {
+    return [
+        ...new Set(values.map((value) => value.trim()).filter(Boolean)),
+    ].sort();
+}
+/** Validate, normalize, sort, and freeze an error-code catalog. */
 export function definePmErrorCodeCatalog(declarations) {
     const seen = new Set();
     const normalized = declarations.map((declaration) => {
@@ -18,10 +33,14 @@ export function definePmErrorCodeCatalog(declarations) {
             throw new TypeError(`Duplicate pm error code: ${code}`);
         }
         seen.add(code);
+        const sources = normalizeContractList(declaration.sources);
+        const emittingCommands = normalizeContractList(declaration.emitting_commands);
         if (![1, 2, 3, 4, 5].includes(declaration.exit_code) ||
             declaration.meaning.trim().length === 0 ||
             declaration.recovery.trim().length === 0 ||
-            declaration.sources.length === 0) {
+            sources.length === 0 ||
+            emittingCommands.length === 0 ||
+            ERROR_CLASS_BY_EXIT_CODE.get(declaration.exit_code) !== declaration.class) {
             throw new TypeError(`Invalid pm error code contract: ${code}`);
         }
         return Object.freeze({
@@ -29,7 +48,8 @@ export function definePmErrorCodeCatalog(declarations) {
             code,
             meaning: declaration.meaning.trim(),
             recovery: declaration.recovery.trim(),
-            sources: [...new Set(declaration.sources.map((source) => source.trim()).filter(Boolean))].sort(),
+            sources,
+            emitting_commands: emittingCommands,
         });
     });
     return Object.freeze(normalized.sort((left, right) => left.code.localeCompare(right.code)));
@@ -44,4 +64,4 @@ export function resolvePmErrorCodeContract(code, catalog) {
     return contract;
 }
 //# sourceMappingURL=error-code-catalog.js.map
-//# debugId=804df95b-c2fc-5ea7-bfb5-aea890a65abc
+//# debugId=479dd590-7f54-54ae-bbaf-8f183fd6b6b4

package/dist/sdk/extension/install-sources.d.ts

@@ -13,36 +13,73 @@ interface LocalPackageArchiveLimits {
     maxExpandedBytes: number;
     maxEntryBytes: number;
 }
-interface LocalInstallSource {
+/** Parsed filesystem install source. */
+export interface LocalInstallSource {
+    /** Discriminator for a filesystem source. */
     kind: "local";
+    /** Exact caller-provided source text. */
     input: string;
+    /** Absolute normalized source path. */
     absolute_path: string;
 }
-interface GithubInstallSource {
+/** Parsed GitHub repository install source. */
+export interface GithubInstallSource {
+    /** Discriminator for a GitHub repository source. */
     kind: "github";
+    /** Exact caller-provided source text. */
     input: string;
+    /** Repository owner. */
     owner: string;
+    /** Repository name without a `.git` suffix. */
     repo: string;
+    /** Cloneable HTTPS repository URL. */
     repository: string;
+    /** Optional Git ref selected by the caller or URL. */
     ref?: string;
+    /** Optional repository-relative package directory. */
     subpath?: string;
 }
-interface NpmInstallSource {
+/** Parsed npm registry or package-spec install source. */
+export interface NpmInstallSource {
+    /** Discriminator for an npm package source. */
     kind: "npm";
+    /** Exact caller-provided source text. */
     input: string;
+    /** Validated npm package specification. */
     spec: string;
 }
-type InstallSource = LocalInstallSource | GithubInstallSource | NpmInstallSource;
-interface ResolvedInstallSource {
+/** Parsed extension install source accepted by the resolver. */
+export type InstallSource = LocalInstallSource | GithubInstallSource | NpmInstallSource;
+/** Materialized install source ready for extension validation. */
+export interface ResolvedInstallSource {
+    /** Parsed source that produced this directory. */
     source: InstallSource;
+    /** Absolute extension or package directory ready for validation. */
     directory: string;
+    /** Root unpacked or cloned source directory when different from `directory`. */
     source_root?: string;
+    /** Repository subpath selected after clone. */
     resolved_subpath?: string;
+    /** Resolved Git commit when the source is a repository. */
     commit?: string;
+    /** Canonical npm package name when the source is a registry package. */
     npm_package?: string;
+    /** Resolved npm package version. */
     npm_version?: string;
+    /** Releases temporary source material created during resolution. */
     cleanup?: () => Promise<void>;
 }
+/** Installed npm package that competes with a bare bundled install target. */
+export interface InstalledNpmPackageCandidate {
+    /** Package identity read from its package.json. */
+    package: string;
+    /** Installed package version when declared. */
+    version?: string;
+    /** Absolute package root selected by Node-style ancestor lookup. */
+    directory: string;
+}
+/** Resolve an already-installed npm package without executing package code. */
+export declare function findInstalledNpmPackageCandidate(packageName: string, cwd?: string): Promise<InstalledNpmPackageCandidate | null>;
 /** Implements parse extension install source for the public runtime surface of this module. */
 export declare function parseExtensionInstallSource(input: string, options?: {
     forceGithub?: boolean;
@@ -128,6 +165,7 @@ export declare const _testOnlyInstallSources: {
     resolveNpmSourceDirectoryWithRunner: typeof resolveNpmSourceDirectoryWithRunner;
     resolveNpmSourceDirectory: typeof resolveNpmSourceDirectory;
     resolveNpmPackSpec: typeof resolveNpmPackSpec;
+    findInstalledNpmPackageCandidate: typeof findInstalledNpmPackageCandidate;
     resolvePackageExtensionDirectory: typeof resolvePackageExtensionDirectory;
     runtimeDependencyInstallSpecs: typeof runtimeDependencyInstallSpecs;
     hasHostedPmCliDependency: typeof hasHostedPmCliDependency;

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