@unbrained/pm-cli 2026.8.5 → 2026.8.7

package/dist/sdk/completion.js

@@ -4,7 +4,7 @@
  * Implements the pm completion 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]="bba460dd-91d7-5444-b754-58c684a425fd")}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]="8acb405a-140e-532c-81c0-e8153ea30dc0")}catch(e){}}();
 import { EXIT_CODE, PmCliError } from "./runtime-primitives.js";
 import { listPmCommandsForTier } from "./agent-capability-contracts.js";
 import { SCAFFOLD_CAPABILITIES } from "./extension/scaffold.js";
@@ -787,6 +787,7 @@ _pm() {
     '--output-limit[Set the universal read row ceiling]:limit' \\
     '--output-budget[Set the universal estimated-token ceiling]:tokens' \\
     '--output-format[Select the universal read encoding]:(toon json)' \\
+    '--output-session[Carry cross-call read budget and served-item state]:state' \\
     '--no-changed-fields[Omit changed_fields array from mutation output]' \\
     '--pm-path[Explicit tracker storage path for this command]:path:_files -/' \\
     '--path[Compatibility alias for --pm-path]:path:_files -/' \\
@@ -1811,6 +1812,7 @@ complete -c pm -l output-include -d 'Retain comma-separated read fields or secti
 complete -c pm -l output-limit -d 'Set the universal read row ceiling' -r
 complete -c pm -l output-budget -d 'Set the universal estimated-token ceiling' -r
 complete -c pm -l output-format -d 'Select the universal read encoding' -r -a 'toon json'
+complete -c pm -l output-session -d 'Carry cross-call read budget and served-item state' -r
 complete -c pm -l no-changed-fields -d 'Omit changed_fields array from mutation output'
 complete -c pm -l id-only -d 'Print only id and status for single-item mutation output'
 complete -c pm -l pm-path -d 'Explicit tracker storage path for this command' -r
@@ -2484,6 +2486,7 @@ complete -c pm -n '__fish_seen_subcommand_from stats' -l by-assignee -d 'Lifecyc
 complete -c pm -n '__fish_seen_subcommand_from stats' -l by-tag -d 'Lifecycle-bucketed breakdown grouped by tag'
 complete -c pm -n '__fish_seen_subcommand_from stats' -l by-priority -d 'Lifecycle-bucketed breakdown grouped by priority'
 complete -c pm -n '__fish_seen_subcommand_from stats' -l tag-prefix -d 'With --by-tag: only count tags with this prefix' -r
+complete -c pm -n '__fish_seen_subcommand_from stats' -l analytics -d 'Improvement ledger/history analytics JSON' -r
 
 # append flags
 complete -c pm -n '__fish_seen_subcommand_from append' -s b -l body -d 'Item body' -r
@@ -2740,4 +2743,4 @@ export function runCompletion(shell, itemTypes = [], tags = [], eagerTagExpansio
     };
 }
 //# sourceMappingURL=completion.js.map
-//# debugId=bba460dd-91d7-5444-b754-58c684a425fd
+//# debugId=8acb405a-140e-532c-81c0-e8153ea30dc0

package/dist/sdk/compose.d.ts

@@ -25,7 +25,7 @@
  * declarative (`composeExtension`) authoring styles live together. Both are
  * re-exported from the SDK barrel, so the public API is unchanged.
  */
-import type { AfterCommandHook, BeforeCommandHook, BeforeMutationHook, CommandDefinition, CommandOverride, ExtensionApi, ExtensionCapability, ExtensionManifest, ExtensionServiceName, Exporter, FlagDefinition, ImportExportRegistrationOptions, Importer, OnIndexHook, OnReadHook, OnWriteHook, OutputRendererFormat, ParserOverride, PreflightOverride, RendererOverride, ScopedRendererOverrideDefinition, SchemaFieldDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SearchProviderDefinition, ServiceOverride, VectorStoreAdapterDefinition } from "../core/extensions/loader.js";
+import type { AfterCommandHook, BeforeCommandHook, BeforeMutationHook, CommandDefinition, CommandOverride, ExtensionApi, ExtensionCapability, ExtensionManifest, ExtensionServiceName, Exporter, FlagDefinition, ImportExportRegistrationOptions, Importer, OnIndexHook, OnReadHook, OnWriteHook, OutputRendererFormat, ParserOverride, PreflightOverride, ScopedPreflightOverrideDefinition, RendererOverride, ScopedRendererOverrideDefinition, SchemaFieldDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SearchProviderDefinition, ServiceOverride, VectorStoreAdapterDefinition } from "../core/extensions/loader.js";
 import type { ExtensionActivationSummary } from "../core/extensions/activation-summary.js";
 import type { ProjectProfileRegistrationInput } from "../core/profile/profile-presets.js";
 import type { PmMaxVersionExceededMode } from "../core/extensions/extension-types.js";
@@ -137,7 +137,7 @@ export interface ExtensionBlueprint {
     /** Service overrides keyed by service name, registered via `api.registerService(service, override)`. */
     services?: Partial<Record<ExtensionServiceName, ServiceOverride>>;
     /** Preflight overrides registered via `api.registerPreflight(override)`. */
-    preflights?: PreflightOverride[];
+    preflights?: Array<PreflightOverride | ScopedPreflightOverrideDefinition>;
     /** Custom item types registered in a single `api.registerItemTypes(types)` call. */
     itemTypes?: SchemaItemTypeDefinition[];
     /** Custom item-metadata fields registered in a single `api.registerItemFields(fields)` call. */

package/dist/sdk/compose.js

@@ -1,5 +1,5 @@
 
-!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]="60463c2e-f904-5199-87b0-8a17f0e2ee0f")}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]="142a413a-35a6-5861-9063-0c196a176eaa")}catch(e){}}();
 import { normalizeKnownExtensionCapability, resolveLegacyExtensionCapabilityAlias, } from "../core/extensions/extension-capability-aliases.js";
 import { normalizeCommandName } from "../core/extensions/extension-runtime-helpers.js";
 import { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
@@ -531,6 +531,11 @@ function collectBlueprintSurfaceSummary(blueprint, importers, exporters) {
         renderer_overrides: sortUnique(Object.keys(blueprint.renderers ?? {}).map((format) => String(format).trim().toLowerCase())),
         ...collectBlueprintRendererOwnership(blueprint.renderers),
         preflight_overrides: (blueprint.preflights ?? []).length,
+        preflight_ownership: (blueprint.preflights ?? []).map((preflight) => ({
+            commands: [
+                ...(preflight.commands ?? []),
+            ],
+        })),
     };
 }
 /**
@@ -1052,4 +1057,4 @@ export function preflightExtension(blueprint, options = {}) {
     };
 }
 //# sourceMappingURL=compose.js.map
-//# debugId=60463c2e-f904-5199-87b0-8a17f0e2ee0f
+//# debugId=142a413a-35a6-5861-9063-0c196a176eaa

package/dist/sdk/contracts.d.ts

@@ -11,3 +11,4 @@ export * from "./flag-invocation-contracts.js";
 export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionState, } from "./read-output-session.js";

package/dist/sdk/contracts.js

@@ -4,7 +4,7 @@
  * Exposes command and action contract data without loading SDK runtime 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]="2962656f-386f-59a0-8dc1-411ae382dddb")}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]="8c442738-13e6-5bf5-b60d-1439c3255f1a")}catch(e){}}();
 export * from "./cli-contracts.js";
 export * from "./context-intent-contracts.js";
 export * from "./error-code-catalog.js";
@@ -14,4 +14,4 @@ export * from "./output-token-accounting.js";
 export * from "./output-contracts.js";
 export * from "./read-output-contracts.js";
 //# sourceMappingURL=contracts.js.map
-//# debugId=2962656f-386f-59a0-8dc1-411ae382dddb
+//# debugId=8c442738-13e6-5bf5-b60d-1439c3255f1a

package/dist/sdk/core.d.ts

@@ -6,6 +6,8 @@
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, type AggregateOptions, type AggregateResult, type AggregateRow, type AppendCommandOptions, type AppendResult, type ClaimNextOptions, type ClaimResult, type CloseResult, type CommentsCommandOptions, type CommentsResult, type ContextOptions, type ContextResult, type CopyResult, type CreateResult, type Dependency, type DeleteResult, type DepsCommandOptions, type DepsResult, type DocsCommandOptions, type DocsResult, type FilesCommandOptions, type FilesDiscoverOptions, type FilesDiscoverResult, type FilesResult, type FocusResult, type GetOptions, type GetResult, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, type LearningsCommandOptions, type LearningsResult, type ListOptions, type ListResult, type NextOptions, type NextResult, type NotesCommandOptions, type NotesResult, type PmActionInput, type PmActionName, type PmActionOptions, type PmClientOptions, type ReleaseResult, type RestoreResult, type SearchOptions, type SearchResult, type UpdateResult, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
-export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputDimension, PmReadOutputLegacyAlias, PmReadOutputOptions, PmReadOutputReceipt, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurface, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionReference, PmReadOutputSessionState, } from "./read-output-session.js";
 export type { ItemDocument, ItemMetadata, ItemStatus, ItemType, PmSettings, } from "../types/index.js";

package/dist/sdk/core.js

@@ -4,10 +4,11 @@
  * Provides the stable item lifecycle client and universal project data types.
  */
 
-!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]="d70db3d9-b094-52fd-8f0f-47eed9f6e7f0")}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]="54d31df7-e708-585d-9fb2-3c5ddfcc6138")}catch(e){}}();
 export { BASELINE_ITEM_FORMAT_VERSION, BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, CURRENT_ITEM_FORMAT_VERSION, DEPENDENCY_KIND_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, PM_CLI_EXPECTED_ERROR_NAME, PmCliError, PmClient, RISK_VALUES, STATUS_VALUES, canonicalDocument, classifyItemFormatVersion, createPmCliExpectedError, effectiveItemFormatVersion, emptyImportedDocument, isPmCliExpectedError, normalizeItemFormatVersion, normalizeItemId, normalizeStatusInput, nowIso, runAction, serializeItemDocument, aggregate, append, claim, claimNext, close, comments, context, copy, create, deleteItem, deps, docs, files, filesDiscover, focus, get, graph, learnings, list, next, notes, release, restore, search, update, } from "./runtime.js";
 export * from "./core-governance.js";
 export * from "./agent-session-context.js";
-export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { PM_READ_OUTPUT_DIMENSIONS, PM_READ_OUTPUT_OPTION_FLAGS, PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS, PM_READ_OUTPUT_SURFACE_CONTRACTS, applyReadOutputDimensions, isReadOutputBudgetExceeded, resolveReadOutputDimensions, resolveReadOutputEncoding, resolveReadOutputSurface, validateReadOutputOptions, } from "./read-output-contracts.js";
+export { applyReadOutputSessionReferences, attachReadOutputSessionReceipt, parseReadOutputSession, readOutputSessionRemainingTokens, } from "./read-output-session.js";
 //# sourceMappingURL=core.js.map
-//# debugId=d70db3d9-b094-52fd-8f0f-47eed9f6e7f0
+//# debugId=54d31df7-e708-585d-9fb2-3c5ddfcc6138

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/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