@unbrained/pm-cli 2026.8.6 → 2026.8.8

package/dist/sdk/environment/source-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module sdk/environment/source-context
+ *
+ * Defines the inherited source-workspace access contract used by sandboxed
+ * commands that retain read-only project identity.
+ */
+/** Environment key declaring how a child may use inherited source coordinates. */
+export declare const SOURCE_CONTEXT_ACCESS_ENV = "PM_SOURCE_CONTEXT_ACCESS";
+/** Environment key permitting one explicit source-context write invocation. */
+export declare const SOURCE_CONTEXT_WRITE_OVERRIDE_ENV = "PM_ALLOW_SOURCE_CONTEXT_WRITES";
+/** Supported inherited source-context access modes. */
+export type SourceContextAccessMode = "read_only" | "write";
+/** Structured policy used by SDK adapters before selecting source coordinates. */
+export interface SourceContextWritePolicy {
+    /** Declared access mode, with absent legacy context retaining write behavior. */
+    access: SourceContextAccessMode;
+    /** Whether the one-invocation write override was accepted. */
+    write_override_applied: boolean;
+    /** Whether a mutation may select inherited source coordinates. */
+    source_writes_allowed: boolean;
+}
+/** Resolve inherited source-coordinate write policy without reading filesystem state. */
+export declare function resolveSourceContextWritePolicy(environment: Readonly<Record<string, string | undefined>>): SourceContextWritePolicy;

package/dist/sdk/environment/source-context.js

@@ -0,0 +1,29 @@
+/**
+ * @module sdk/environment/source-context
+ *
+ * Defines the inherited source-workspace access contract used by sandboxed
+ * commands that retain read-only project identity.
+ */
+/** Environment key declaring how a child may use inherited source coordinates. */
+
+!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]="f97516b2-f75c-5ce0-82dc-f850466284c7")}catch(e){}}();
+export const SOURCE_CONTEXT_ACCESS_ENV = "PM_SOURCE_CONTEXT_ACCESS";
+/** Environment key permitting one explicit source-context write invocation. */
+export const SOURCE_CONTEXT_WRITE_OVERRIDE_ENV = "PM_ALLOW_SOURCE_CONTEXT_WRITES";
+/** Resolve inherited source-coordinate write policy without reading filesystem state. */
+export function resolveSourceContextWritePolicy(environment) {
+    const declaredAccess = environment[SOURCE_CONTEXT_ACCESS_ENV];
+    const access = declaredAccess === undefined ||
+        declaredAccess.trim().toLowerCase() === "write"
+        ? "write"
+        : "read_only";
+    const writeOverrideApplied = access === "read_only" &&
+        environment[SOURCE_CONTEXT_WRITE_OVERRIDE_ENV]?.trim() === "1";
+    return {
+        access,
+        write_override_applied: writeOverrideApplied,
+        source_writes_allowed: access === "write" || writeOverrideApplied,
+    };
+}
+//# sourceMappingURL=source-context.js.map
+//# debugId=f97516b2-f75c-5ce0-82dc-f850466284c7

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

@@ -43,8 +43,14 @@ export interface PmErrorCodeContract {
     sources: string[];
     /** CLI command roots inferred from executable declaration ownership. */
     emitting_commands: string[];
+    /** Canonical machine identifier for this compatibility group. */
+    canonical_code?: string;
+    /** Stable compatibility spellings that resolve to this canonical code. */
+    aliases?: string[];
 }
 /** Validate, normalize, sort, and freeze an error-code catalog. */
 export declare function definePmErrorCodeCatalog(declarations: readonly PmErrorCodeContract[]): readonly PmErrorCodeContract[];
+/** Resolve an emitted code through its stable compatibility alias group. */
+export declare function resolveCanonicalPmErrorCodeContract(code: string, catalog: readonly PmErrorCodeContract[]): PmErrorCodeContract;
 /** Resolve one declared error contract and fail closed for unknown vocabulary. */
 export declare function resolvePmErrorCodeContract(code: string, catalog: readonly PmErrorCodeContract[]): PmErrorCodeContract;

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

@@ -6,7 +6,7 @@
  */
 /** 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]="479dd590-7f54-54ae-bbaf-8f183fd6b6b4")}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]="393243a5-dd90-52c1-a9c1-588fd33f8b6a")}catch(e){}}();
 export const PM_ERROR_CODE_EXIT_CLASS_CONTRACTS = [
     { exit_code: 1, class: "generic_failure" },
     { exit_code: 2, class: "usage" },
@@ -21,6 +21,55 @@ function normalizeContractList(values) {
         ...new Set(values.map((value) => value.trim()).filter(Boolean)),
     ].sort();
 }
+function isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases) {
+    return ![
+        [1, 2, 3, 4, 5].includes(declaration.exit_code),
+        declaration.meaning.trim().length > 0,
+        declaration.recovery.trim().length > 0,
+        sources.length > 0,
+        emittingCommands.length > 0,
+        /^[a-z][a-z0-9_]*$/.test(canonicalCode),
+        aliases.every((alias) => /^[a-z][a-z0-9_]*$/.test(alias)),
+        ERROR_CLASS_BY_EXIT_CODE.get(declaration.exit_code) === declaration.class,
+    ].includes(false);
+}
+function resolveCanonicalErrorCodeDeclaration(declaration, byCode) {
+    let current = declaration;
+    const path = new Set();
+    while (current.canonical_code !== current.code) {
+        if (path.has(current.code)) {
+            throw new TypeError(`Alias cycle in pm error code catalog: ${declaration.code}`);
+        }
+        path.add(current.code);
+        const target = byCode.get(current.canonical_code);
+        if (!target) {
+            throw new TypeError(`Invalid pm error code contract: ${declaration.code}`);
+        }
+        current = target;
+    }
+    return current;
+}
+function validateErrorCodeAliases(declarations) {
+    const byCode = new Map(declarations.map((entry) => [entry.code, entry]));
+    for (const declaration of declarations) {
+        const canonical = resolveCanonicalErrorCodeDeclaration(declaration, byCode);
+        if (canonical.exit_code !== declaration.exit_code ||
+            canonical.class !== declaration.class) {
+            throw new TypeError(`Alias transport mismatch for pm error code: ${declaration.code}`);
+        }
+        const expectedAliases = declarations
+            .filter((candidate) => candidate.code !== canonical.code &&
+            candidate.canonical_code === canonical.code)
+            .map((candidate) => candidate.code)
+            .sort();
+        if (declaration.code === canonical.code
+            ? JSON.stringify(declaration.aliases) !==
+                JSON.stringify(expectedAliases)
+            : declaration.aliases.length > 0) {
+            throw new TypeError(`Invalid pm error code contract: ${declaration.code}`);
+        }
+    }
+}
 /** Validate, normalize, sort, and freeze an error-code catalog. */
 export function definePmErrorCodeCatalog(declarations) {
     const seen = new Set();
@@ -35,12 +84,9 @@ export function definePmErrorCodeCatalog(declarations) {
         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 ||
-            sources.length === 0 ||
-            emittingCommands.length === 0 ||
-            ERROR_CLASS_BY_EXIT_CODE.get(declaration.exit_code) !== declaration.class) {
+        const canonicalCode = (declaration.canonical_code ?? code).trim();
+        const aliases = normalizeContractList(declaration.aliases ?? []);
+        if (!isValidNormalizedErrorCodeContract(declaration, sources, emittingCommands, canonicalCode, aliases)) {
             throw new TypeError(`Invalid pm error code contract: ${code}`);
         }
         return Object.freeze({
@@ -50,10 +96,18 @@ export function definePmErrorCodeCatalog(declarations) {
             recovery: declaration.recovery.trim(),
             sources,
             emitting_commands: emittingCommands,
+            canonical_code: canonicalCode,
+            aliases,
         });
     });
+    validateErrorCodeAliases(normalized);
     return Object.freeze(normalized.sort((left, right) => left.code.localeCompare(right.code)));
 }
+/** Resolve an emitted code through its stable compatibility alias group. */
+export function resolveCanonicalPmErrorCodeContract(code, catalog) {
+    const emitted = resolvePmErrorCodeContract(code, catalog);
+    return resolvePmErrorCodeContract(emitted.canonical_code ?? emitted.code, catalog);
+}
 /** Resolve one declared error contract and fail closed for unknown vocabulary. */
 export function resolvePmErrorCodeContract(code, catalog) {
     const normalized = code.trim();
@@ -64,4 +118,4 @@ export function resolvePmErrorCodeContract(code, catalog) {
     return contract;
 }
 //# sourceMappingURL=error-code-catalog.js.map
-//# debugId=479dd590-7f54-54ae-bbaf-8f183fd6b6b4
+//# debugId=393243a5-dd90-52c1-a9c1-588fd33f8b6a

package/dist/sdk/extension.js

@@ -4,9 +4,8 @@
  * Implements the pm extension command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f4f1a871-b632-5263-aec0-cb00bcdbe1b3")}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]="f4b47053-cc05-51f2-b5cb-cc6dba3365c2")}catch(e){}}();
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { activateExtensions, createSerialQueue, loadExtensions, nextExtensionReloadToken, } from "../core/extensions/index.js";
 import { describeExtensionActivation } from "../core/extensions/activation-summary.js";
@@ -643,10 +642,10 @@ const resolveInstallRuntimeActivationStatus = (extensionName, scope, runtimeInst
         (installActivationFailure ? "failed" : "unknown"));
 };
 /** Probe a temporary installed extension for runtime command registrations. */
-const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled, global) => {
+const probeRuntimeCommandPathsForInstall = (pmRoot, parent, settings, refreshedInstalled, global) => {
     return extensionRuntimeProbeQueue.enqueue(async () => {
         const originalPackageRoot = process.env.PM_CLI_PACKAGE_ROOT;
-        const moduleGraphSnapshotRoot = await fs.mkdtemp(path.join(os.tmpdir(), "pm-extension-module-graph-"));
+        const snapshotRoot = await fs.mkdtemp(path.join(parent, ".pm-module-graph-"));
         process.env.PM_CLI_PACKAGE_ROOT = resolvePmPackageRootFromModule(import.meta.url, ["../.."]);
         try {
             const loadResult = await loadExtensions({
@@ -656,11 +655,10 @@ const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled
                 noExtensions: global.noExtensions === true,
                 reload_token: nextExtensionReloadToken(),
                 cache_bust: true,
-                module_graph_snapshot_root: moduleGraphSnapshotRoot,
+                module_graph_snapshot_root: snapshotRoot,
             });
             const activationResult = await activateExtensions({
                 ...loadResult,
-                loaded: loadResult.loaded,
             });
             const runtimeFailures = [
                 ...loadResult.failed.map((failure) => ({
@@ -687,7 +685,7 @@ const probeRuntimeCommandPathsForInstall = (pmRoot, settings, refreshedInstalled
             };
         }
         finally {
-            await fs.rm(moduleGraphSnapshotRoot, { recursive: true, force: true });
+            await fs.rm(snapshotRoot, { recursive: true, force: true });
             if (originalPackageRoot === undefined) {
                 delete process.env.PM_CLI_PACKAGE_ROOT;
             }
@@ -1275,7 +1273,7 @@ const buildInstalledExtensionActivation = (ctx, extensionName, runtimeProbe, com
             registered_commands: commandSummary.command_paths,
             registered_actions: commandSummary.action_paths,
             registered_item_types: installedItemTypes,
-            module_graph_verification: "fresh_snapshot",
+            module_graph_verification: "fresh_in_topology_snapshot",
             health: healthByActivation[String(activated)],
         },
     };
@@ -1287,7 +1285,7 @@ const performExtensionInstallUnderLock = async (ctx, input) => {
     const persisted = await persistExtensionInstall(ctx, input);
     const refreshedInstalled = await listInstalledExtensions(resolvedRoots.selected_root, scope, persisted.settings, persisted.managedState);
     warnings.push(...refreshedInstalled.warnings);
-    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, persisted.settings, refreshedInstalled.extensions, global);
+    const runtimeProbe = await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, path.dirname(resolvedRoots.selected_root), persisted.settings, refreshedInstalled.extensions, global);
     warnings.push(...runtimeProbe.warnings);
     // Scaffold the folders for any item types the installed package contributes
     // so the tracker is immediately healthy — matching `pm schema add-type` and
@@ -1636,7 +1634,7 @@ const runExtensionActivateDeactivateAction = async (ctx) => {
         await writeSettings(resolvedRoots.settings_root, settings, "settings:write");
     }
     const activationFailure = action === "activate"
-        ? await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, settings, [candidate], global).then((probe) => {
+        ? await probeRuntimeCommandPathsForInstall(resolvedRoots.pm_root, path.dirname(resolvedRoots.selected_root), settings, [candidate], global).then((probe) => {
             warnings.push(...probe.warnings);
             return findActivationFailureByName(candidate.name, probe.activation_failures, ctx.scope);
         })
@@ -2192,4 +2190,4 @@ export const _testOnly = {
     withExtensionInstallLock,
 };
 //# sourceMappingURL=extension.js.map
-//# debugId=f4f1a871-b632-5263-aec0-cb00bcdbe1b3
+//# debugId=f4b47053-cc05-51f2-b5cb-cc6dba3365c2