@unbrained/pm-cli 2026.9.6 → 2026.9.8

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

@@ -0,0 +1,69 @@
+import { type ResolvedInstallSource } from "./install-sources.js";
+/** Limits filesystem enumeration independently of the size of the source tree. */
+export interface ExtensionCopyPlanOptions {
+    /** Maximum directory entries inspected; defaults to 10,000. */
+    maxEntries?: number;
+    /** Maximum directory nesting inspected; defaults to 64. */
+    maxDepth?: number;
+    /** Cancels between filesystem operations and closes every open directory handle. */
+    signal?: AbortSignal;
+}
+/** Observed logical file bytes, excluding dependency installation, metadata writes, and symlink targets. */
+export interface ExtensionCopyPlan {
+    /** Snapshot policy shared with the actual copy operation. */
+    copy_scope: "directory_snapshot" | "nested_filtered_snapshot" | "in_place";
+    /** Absolute source directory used by the copy. */
+    source_directory: string;
+    /** Absolute destination, resolved through existing parent symlinks. */
+    destination_directory: string;
+    /** Regular files included in the observed snapshot. */
+    files: number;
+    /** Sum of observed regular-file logical sizes; a lower bound when incomplete. */
+    bytes: number;
+    /** Included directories, excluding the source root. */
+    directories: number;
+    /** Included symlinks; targets are never traversed. */
+    symlinks: number;
+    /** Included special filesystem entries, whose copy support is platform dependent. */
+    other_entries: number;
+    /** Entries inspected, including exclusions. */
+    scanned_entries: number;
+    /** Entries excluded by the nested-destination policy. */
+    excluded_entries: number;
+    /** Included entries under conventional dependency, VCS, build, or coverage directories. */
+    development_entries: number;
+    /** True only when enumeration finished within both limits. */
+    complete: boolean;
+    /** Why enumeration ended; incomplete counts are never presented as totals. */
+    stop_reason: "complete" | "entry_limit" | "depth_limit";
+    /** Effective maximum directory entries inspected. */
+    max_entries: number;
+    /** Effective maximum directory nesting inspected. */
+    max_depth: number;
+}
+/** Source identity, copy cost, and a script-free packed alternative for one resolved install. */
+export interface ExtensionInstallPlan {
+    /** Distinguishes an explicit directory snapshot from an unpacked archive or remote source. */
+    source_mode: "directory" | "archive" | "npm" | "github";
+    /** Original archive size before unpacking, when supplied as a local file. */
+    archive_bytes?: number;
+    /** Bounded enumeration of the exact selected extension directory. */
+    copy: ExtensionCopyPlan;
+    /** Suggested argument-vector workflow; substitute the pack result filename before installation. */
+    packed_alternative?: {
+        cwd: string;
+        pack: {
+            command: "npm";
+            args: string[];
+        };
+        install: {
+            command: "pm";
+            args: string[];
+        };
+        archive_argument: "pack_result[0].filename";
+    };
+}
+/** Estimate a resolved install before destination writes. Source resolution may have prepared a temporary archive or remote tree. */
+export declare function buildExtensionInstallPlan(resolved: ResolvedInstallSource, destination: string, scope: "project" | "global", options?: ExtensionCopyPlanOptions): Promise<ExtensionInstallPlan>;
+/** Inspect one directory tree without copying files, executing code, following symlinks, or collecting an unbounded path list. */
+export declare function planExtensionDirectoryCopy(sourceDirectory: string, destinationDirectory: string, options?: ExtensionCopyPlanOptions): Promise<ExtensionCopyPlan>;

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

@@ -0,0 +1,2 @@
+!(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]="f4b9502f-f742-5f11-b341-56763bbed7c2")}catch(e2){}})();import fs from"node:fs/promises";import path from"node:path";import{isPathWithinDirectory}from"../../core/fs/path-utils.js";import{PmCliError}from"../../core/shared/errors.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{includesExtensionCopyPath}from"./copy-scope.js";import{resolveCanonicalExtensionInstallDestination}from"./install-runtime.js";import{pathExists}from"../../core/fs/fs-utils.js";import{areDirectoriesEquivalent}from"./install-sources.js";const DEVELOPMENT_DIRECTORIES=new Set(["node_modules",".git","dist","build","coverage"]);async function buildExtensionInstallPlan(resolved,destination,scope,options){const localStat=resolved.source.kind==="local"?await fs.stat(resolved.source.absolute_path):void 0;const sourceMode=resolved.source.kind==="local"?localStat.isDirectory()?"directory":"archive":resolved.source.kind;const copy=await planExtensionDirectoryCopy(resolved.directory,destination,options);const plan={source_mode:sourceMode,...sourceMode==="archive"?{archive_bytes:localStat.size}:{},copy};const packageRoot=resolved.source_root??resolved.directory;if(sourceMode==="directory"&&(!copy.complete||copy.development_entries>0||copy.bytes>=16*1024*1024)&&await pathExists(path.join(packageRoot,"package.json"))){plan.packed_alternative={cwd:packageRoot,pack:{command:"npm",args:["pack","--ignore-scripts","--json"]},install:{command:"pm",args:["package","install","<archive-filename>",`--${scope}`]},archive_argument:"pack_result[0].filename"}}return plan}async function planExtensionDirectoryCopy(sourceDirectory,destinationDirectory,options={}){const{maxEntries=1e4,maxDepth=64,signal}=options;if(![maxEntries,maxDepth].every(value=>Number.isSafeInteger(value)&&value>0)){throw new PmCliError("maxEntries and maxDepth must be positive safe integers.",EXIT_CODE.USAGE)}signal?.throwIfAborted();const source=await fs.realpath(sourceDirectory);const destination=await resolveCanonicalExtensionInstallDestination(destinationDirectory);const installInPlace=await areDirectoriesEquivalent(source,destination);signal?.throwIfAborted();const scope=installInPlace?"in_place":isPathWithinDirectory(source,destination)?"nested_filtered_snapshot":"directory_snapshot";const plan={copy_scope:scope,source_directory:source,destination_directory:destination,files:0,bytes:0,directories:0,symlinks:0,other_entries:0,scanned_entries:0,excluded_entries:0,development_entries:0,complete:true,stop_reason:"complete",max_entries:maxEntries,max_depth:maxDepth};if(scope==="in_place")return plan;await scanExtensionCopyDirectory(source,0,plan,signal);return plan}async function scanExtensionCopyDirectory(directory,depth,plan,signal){signal?.throwIfAborted();const handle=await fs.opendir(directory);for await(const entry of handle){signal?.throwIfAborted();if(plan.scanned_entries>=plan.max_entries){plan.complete=false;plan.stop_reason="entry_limit";return}plan.scanned_entries+=1;const candidate=path.join(directory,entry.name);if(plan.copy_scope==="nested_filtered_snapshot"&&!includesExtensionCopyPath(plan.source_directory,plan.destination_directory,candidate)){plan.excluded_entries+=1;continue}if(path.relative(plan.source_directory,candidate).split(path.sep).some(segment=>DEVELOPMENT_DIRECTORIES.has(segment)))plan.development_entries+=1;await countExtensionCopyEntry(candidate,depth,plan,signal);if(!plan.complete)return}}async function countExtensionCopyEntry(candidate,depth,plan,signal){const stat=await fs.lstat(candidate);signal?.throwIfAborted();if(stat.isDirectory()){plan.directories+=1;if(depth+1>=plan.max_depth){plan.complete=false;plan.stop_reason="depth_limit";return}await scanExtensionCopyDirectory(candidate,depth+1,plan,signal)}else if(stat.isFile()){plan.files+=1;plan.bytes+=stat.size}else if(stat.isSymbolicLink()){plan.symlinks+=1}else{plan.other_entries+=1}}export{buildExtensionInstallPlan,planExtensionDirectoryCopy};
+//# sourceMappingURL=install-plan.js.map

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

@@ -0,0 +1,7 @@
+/** @module sdk/extension/install-receipts Summarizes bundled install outcomes without repeating full package diagnostics. */
+import type { ExtensionCommandResult } from "../extension.js";
+/** Preserve per-package evidence while distinguishing planned and completed bundled installs. */
+export declare function buildBundledInstallReceipt(packages: ReadonlyArray<{
+    alias: string;
+    result: ExtensionCommandResult;
+}>, dryRun: boolean): Record<string, unknown>;

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

@@ -0,0 +1,2 @@
+!(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]="ee1bfa77-6687-578c-9cd6-639fc702c48c")}catch(e2){}})();function buildBundledInstallReceipt(packages,dryRun){const succeeded=packages.filter(entry=>entry.result.ok).length;return{installed_all:!dryRun&&succeeded===packages.length,installed_count:dryRun?0:succeeded,...dryRun?{dry_run:true,planned_count:succeeded}:{},failed_count:packages.length-succeeded,packages:packages.map(({alias,result})=>{const details=result.details;return{alias,ok:result.ok,extension:details.extension,source:details.source,source_resolution:details.source_resolution,install_plan:details.install_plan,dry_run:details.dry_run,destination_path:details.destination_path,activated:details.activated,settings_changed:details.settings_changed,command_paths:details.command_paths,action_paths:details.action_paths,command_discovery:details.command_discovery,verification:details.verification,runtime_activation_status:details.runtime_activation_status,activation_diagnostics:details.activation_diagnostics,warnings:result.warnings}})}}export{buildBundledInstallReceipt};
+//# sourceMappingURL=install-receipts.js.map

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

@@ -1,314 +1,4 @@
-/**
- * @module sdk/extension/install-runtime
- *
- * Provides cross-platform extension copy safety and owner-bound install locks.
- */
-
-!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]="b100fde9-412b-587b-85ac-532117e2253f")}catch(e){}}();
-import { withHostEnvironmentBoundary } from "../../core/fs/host-environment-errors.js";
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { isFileAbsentError, pathExists } from "../../core/fs/fs-utils.js";
-import { isPathWithinDirectory } from "../../core/fs/path-utils.js";
-import { EXIT_CODE } from "../../core/shared/constants.js";
-import { PmCliError } from "../../core/shared/errors.js";
-import { resolvePmPackageRootFromModule } from "../../core/packages/root.js";
-import { nowIso } from "../../core/shared/time.js";
-const EXTENSION_INSTALL_COPY_ATTEMPTS = 3;
-const EXTENSION_INSTALL_LOCK_ATTEMPTS = 120;
-const EXTENSION_INSTALL_LOCK_DELAY_MS = 250;
-const EXTENSION_INSTALL_LOCK_STALE_MS = 120_000;
-const RETRIABLE_EXTENSION_INSTALL_COPY_CODES = new Set([
-    "EEXIST",
-    "ENOTEMPTY",
-    "ENOENT",
-]);
-/** Return an errno-style code from an unknown failure when one is present. */
-const errnoCode = (error) => typeof error === "object" && error !== null && "code" in error
-    ? error.code
-    : undefined;
-/** Identify transient copy races that are safe to retry during extension installation. */
-export const isRetriableExtensionInstallCopyError = (error) => RETRIABLE_EXTENSION_INSTALL_COPY_CODES.has(String(errnoCode(error)));
-/** Test an unknown failure against one expected errno-style code. */
-export const isErrnoCode = (error, code) => errnoCode(error) === code;
-/** Delay an extension filesystem retry without blocking the event loop. */
-const sleep = (ms) => new Promise((resolve) => {
-    setTimeout(resolve, ms);
-});
-/** Ensure an installed extension carries an ESM package boundary marker. */
-export const ensureExtensionModuleTypeMarker = async (destinationDirectory) => {
-    const markerPath = path.join(destinationDirectory, "package.json");
-    if (await pathExists(markerPath)) {
-        return;
-    }
-    await fs.writeFile(markerPath, `${JSON.stringify({ type: "module" }, null, 2)}\n`, "utf8");
-};
-/**
- * Link an installed extension to the exact host SDK that activated it.
- *
- * Extension directories are copied out of their package root, so ordinary
- * package-manager dependency ancestry no longer exists after installation.
- * Installing this local link restores standard Node package resolution for
- * `@unbrained/pm-cli/sdk` and its public subpaths without environment-specific
- * absolute imports or duplicated runtime loaders.
- */
-export const ensureInstalledExtensionSdkLink = async (destinationDirectory) => {
-    const hostPackageRoot = resolvePmPackageRootFromModule(import.meta.url, [
-        "../../..",
-    ]);
-    const scopedDirectory = path.join(destinationDirectory, "node_modules", "@unbrained");
-    const linkPath = path.join(scopedDirectory, "pm-cli");
-    await fs.mkdir(scopedDirectory, { recursive: true });
-    await fs.rm(linkPath, { recursive: true, force: true });
-    await fs.symlink(hostPackageRoot, linkPath, process.platform === "win32" ? "junction" : "dir");
-};
-/** Resolve a possibly partial extension destination through every existing symlink segment. */
-export const resolveCanonicalExtensionInstallDestination = async (destinationDirectory) => {
-    const resolvedDestination = path.resolve(destinationDirectory);
-    const destinationParent = path.dirname(resolvedDestination);
-    const destinationRoot = path.parse(destinationParent).root;
-    let canonicalDestinationParent = await fs
-        .realpath(destinationRoot)
-        .catch(() => destinationRoot);
-    const relativeDestinationParent = path.relative(destinationRoot, destinationParent);
-    const destinationSegments = relativeDestinationParent === ""
-        ? []
-        : relativeDestinationParent.split(path.sep);
-    for (const [index, segment] of destinationSegments.entries()) {
-        const candidate = path.join(canonicalDestinationParent, segment);
-        try {
-            canonicalDestinationParent = await fs.realpath(candidate);
-        }
-        catch {
-            canonicalDestinationParent = path.join(canonicalDestinationParent, ...destinationSegments.slice(index));
-            break;
-        }
-    }
-    return path.join(canonicalDestinationParent, path.basename(resolvedDestination));
-};
-/** Copy an extension without recursively copying a destination nested below its source. */
-export const copyExtensionDirectoryWithoutSelfNesting = async (sourceDirectory, destinationDirectory, copyDirectory, temporaryDirectory = os.tmpdir()) => withHostEnvironmentBoundary("extension_install_copy", async () => {
-    const resolvedSource = path.resolve(sourceDirectory);
-    const canonicalSource = await fs
-        .realpath(resolvedSource)
-        .catch(() => resolvedSource);
-    const canonicalDestination = await resolveCanonicalExtensionInstallDestination(destinationDirectory);
-    if (canonicalSource === canonicalDestination) {
-        return;
-    }
-    if (!isPathWithinDirectory(canonicalSource, canonicalDestination)) {
-        await copyDirectory(sourceDirectory, destinationDirectory, {
-            recursive: true,
-            force: true,
-        });
-        return;
-    }
-    const shouldCopySourcePath = (sourcePath) => {
-        const resolvedCandidate = path.resolve(sourcePath);
-        if (resolvedCandidate !== resolvedSource &&
-            !isPathWithinDirectory(resolvedSource, resolvedCandidate)) {
-            return false;
-        }
-        const canonicalCandidate = path.resolve(canonicalSource, path.relative(resolvedSource, resolvedCandidate));
-        if (canonicalCandidate === canonicalDestination ||
-            isPathWithinDirectory(canonicalDestination, canonicalCandidate)) {
-            return false;
-        }
-        const relative = path.relative(canonicalSource, canonicalCandidate);
-        const segments = relative.split(path.sep);
-        if (segments.some((segment) => segment === "node_modules" ||
-            segment.startsWith(".pm-extension-install-backup-"))) {
-            return false;
-        }
-        return segments[0] !== ".agents";
-    };
-    const systemTempDirectory = await fs
-        .realpath(path.resolve(temporaryDirectory))
-        .catch(() => resolveCanonicalExtensionInstallDestination(temporaryDirectory));
-    const stagingBase = isPathWithinDirectory(canonicalSource, systemTempDirectory)
-        ? path.dirname(canonicalSource)
-        : systemTempDirectory;
-    if (isPathWithinDirectory(canonicalSource, stagingBase)) {
-        throw new PmCliError(`Extension source "${sourceDirectory}" contains its install destination and no external staging directory is available. Install a narrower package directory instead.`, EXIT_CODE.USAGE, { code: "extension_install_source_contains_destination" });
-    }
-    const stagingRoot = await fs.mkdtemp(path.join(stagingBase, "pm-extension-copy-"));
-    const stagedDirectory = path.join(stagingRoot, "extension");
-    try {
-        await copyDirectory(sourceDirectory, stagedDirectory, {
-            recursive: true,
-            force: true,
-            filter: shouldCopySourcePath,
-        });
-        await copyDirectory(stagedDirectory, destinationDirectory, {
-            recursive: true,
-            force: true,
-        });
-    }
-    finally {
-        await fs.rm(stagingRoot, { recursive: true, force: true });
-    }
-});
-/** Copy one extension directory with bounded transient-race retries. */
-export const copyExtensionDirectoryForInstall = async (sourceDirectory, destinationDirectory, copyDirectory = fs.cp) => {
-    for (let attempt = 1; attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS; attempt += 1) {
-        try {
-            await withHostEnvironmentBoundary("extension_install_copy", async () => {
-                await fs.rm(destinationDirectory, { recursive: true, force: true });
-                await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory, destinationDirectory, copyDirectory);
-            });
-            return;
-        }
-        catch (error) {
-            if (!isRetriableExtensionInstallCopyError(error) ||
-                attempt === EXTENSION_INSTALL_COPY_ATTEMPTS) {
-                throw error;
-            }
-            await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS);
-        }
-    }
-};
-/** Read the unique owner token recorded for one extension scope lock. */
-const readExtensionInstallLockOwnerToken = async (lockPath) => {
-    let ownerContents;
-    try {
-        ownerContents = await fs.readFile(path.join(lockPath, "owner.json"), "utf8");
-    }
-    catch (error) {
-        if (!isFileAbsentError(error))
-            throw error;
-        return null;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(ownerContents);
-    }
-    catch {
-        return null;
-    }
-    if (typeof parsed !== "object" || parsed === null || !("token" in parsed)) {
-        return null;
-    }
-    const token = parsed.token;
-    return typeof token === "string" && token.length > 0 ? token : null;
-};
-/** Remove an extension scope lock only while its persisted owner token still matches. */
-const removeExtensionInstallLockIfOwned = async (lockPath, ownerToken) => {
-    const currentOwnerToken = await readExtensionInstallLockOwnerToken(lockPath);
-    if (currentOwnerToken !== ownerToken) {
-        return false;
-    }
-    await fs.rm(lockPath, { recursive: true, force: true });
-    return true;
-};
-/** Reclaim an expired extension scope lock when its persisted owner remains unchanged. */
-const reclaimStaleExtensionInstallLock = async (lockPath, staleMs) => {
-    let stat;
-    try {
-        stat = await fs.stat(lockPath);
-    }
-    catch {
-        return false;
-    }
-    if (Date.now() - stat.mtimeMs <= staleMs) {
-        return false;
-    }
-    const staleOwnerToken = await readExtensionInstallLockOwnerToken(lockPath);
-    if (staleOwnerToken === null) {
-        await fs.rm(lockPath, { recursive: true, force: true });
-        return true;
-    }
-    return removeExtensionInstallLockIfOwned(lockPath, staleOwnerToken);
-};
-/** Start an owner-bound lease heartbeat and return an async stop barrier. */
-const startExtensionInstallLockHeartbeat = (lockPath, ownerToken, intervalMs) => {
-    let heartbeat = Promise.resolve();
-    const timer = setInterval(() => {
-        heartbeat = heartbeat
-            .then(async () => {
-            if ((await readExtensionInstallLockOwnerToken(lockPath)) !== ownerToken) {
-                return;
-            }
-            const heartbeatAt = new Date();
-            await fs.utimes(lockPath, heartbeatAt, heartbeatAt);
-        })
-            .catch(() => undefined);
-    }, intervalMs);
-    timer.unref();
-    return async () => {
-        clearInterval(timer);
-        await heartbeat;
-    };
-};
-/** Create one owner-bound extension install lock, removing partial state on failure. */
-const createExtensionInstallLock = async (lockPath, owner) => {
-    await fs.mkdir(lockPath);
-    try {
-        await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify(owner, null, 2)}\n`, "utf8");
-    }
-    catch (error) {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
-        throw error;
-    }
-};
-/** Retry owner-bound extension lock acquisition while reclaiming stale owners. */
-const acquireExtensionInstallLock = async (lockPath, owner, attempts, delayMs, staleMs) => {
-    for (let attempt = 1; attempt <= attempts; attempt += 1) {
-        try {
-            await createExtensionInstallLock(lockPath, owner);
-            return true;
-        }
-        catch (error) {
-            if (!isErrnoCode(error, "EEXIST")) {
-                throw error;
-            }
-            if (await reclaimStaleExtensionInstallLock(lockPath, staleMs)) {
-                attempt -= 1;
-            }
-            else {
-                await sleep(delayMs);
-            }
-        }
-    }
-    return false;
-};
-/** Run one operation under an owner-bound extension install lock and heartbeat lease. */
-export const withExtensionInstallLock = async (settingsRoot, destinationDirectoryName, run, options) => {
-    const lockRoot = path.join(settingsRoot, "runtime", "extension-install-locks");
-    const lockPath = path.join(lockRoot, "scope.lock");
-    await fs.mkdir(lockRoot, { recursive: true });
-    const { attempts: rawAttempts = EXTENSION_INSTALL_LOCK_ATTEMPTS, delay_ms: rawDelayMs = EXTENSION_INSTALL_LOCK_DELAY_MS, stale_ms: rawStaleMs = EXTENSION_INSTALL_LOCK_STALE_MS, heartbeat_ms: rawHeartbeatMs, } = options ?? {};
-    if (![rawAttempts, rawDelayMs, rawStaleMs, rawHeartbeatMs]
-        .filter((value) => value !== undefined)
-        .every(Number.isFinite)) {
-        throw new PmCliError("Extension install lock timings must be finite numbers.", EXIT_CODE.USAGE);
-    }
-    const attempts = Math.max(1, Math.floor(rawAttempts));
-    const delayMs = Math.max(0, Math.floor(rawDelayMs));
-    const staleMs = Math.floor(rawStaleMs);
-    const heartbeatMs = Math.floor(rawHeartbeatMs ?? staleMs / 3);
-    if (staleMs <= 0 || heartbeatMs <= 0 || heartbeatMs >= staleMs) {
-        throw new PmCliError("Extension install lock timings require stale_ms > 0 and 0 < heartbeat_ms < stale_ms.", EXIT_CODE.USAGE);
-    }
-    const owner = {
-        pid: process.pid,
-        token: randomUUID(),
-        created_at: nowIso(),
-        destination: destinationDirectoryName,
-    };
-    const acquired = await acquireExtensionInstallLock(lockPath, owner, attempts, delayMs, staleMs);
-    if (!acquired) {
-        throw new PmCliError(`Timed out waiting for extension install lock for "${destinationDirectoryName}".`, EXIT_CODE.CONFLICT);
-    }
-    const stopHeartbeat = startExtensionInstallLockHeartbeat(lockPath, owner.token, heartbeatMs);
-    try {
-        return await run();
-    }
-    finally {
-        await stopHeartbeat();
-        await removeExtensionInstallLockIfOwned(lockPath, owner.token).catch(() => false);
-    }
-};
+!(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]="67e85146-6994-5c3b-bcaa-d7001b9b1703")}catch(e2){}})();import{withHostEnvironmentBoundary}from"../../core/fs/host-environment-errors.js";import{includesExtensionCopyPath}from"./copy-scope.js";import{randomUUID}from"node:crypto";import fs from"node:fs/promises";import os from"node:os";import path from"node:path";import{isFileAbsentError,pathExists}from"../../core/fs/fs-utils.js";import{isPathWithinDirectory}from"../../core/fs/path-utils.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{resolvePmPackageRootFromModule}from"../../core/packages/root.js";import{nowIso}from"../../core/shared/time.js";const EXTENSION_INSTALL_COPY_ATTEMPTS=3;const EXTENSION_INSTALL_LOCK_ATTEMPTS=120;const EXTENSION_INSTALL_LOCK_DELAY_MS=250;const EXTENSION_INSTALL_LOCK_STALE_MS=12e4;const RETRIABLE_EXTENSION_INSTALL_COPY_CODES=new Set(["EEXIST","ENOTEMPTY","ENOENT"]);const errnoCode=error=>typeof error==="object"&&error!==null&&"code"in error?error.code:void 0;const isRetriableExtensionInstallCopyError=error=>RETRIABLE_EXTENSION_INSTALL_COPY_CODES.has(String(errnoCode(error)));const isErrnoCode=(error,code)=>errnoCode(error)===code;const sleep=ms=>new Promise(resolve=>{setTimeout(resolve,ms)});const ensureExtensionModuleTypeMarker=async destinationDirectory=>{const markerPath=path.join(destinationDirectory,"package.json");if(await pathExists(markerPath)){return}await fs.writeFile(markerPath,`${JSON.stringify({type:"module"},null,2)}
+`,"utf8")};const ensureInstalledExtensionSdkLink=async destinationDirectory=>{const hostPackageRoot=resolvePmPackageRootFromModule(import.meta.url,["../../.."]);const scopedDirectory=path.join(destinationDirectory,"node_modules","@unbrained");const linkPath=path.join(scopedDirectory,"pm-cli");await fs.mkdir(scopedDirectory,{recursive:true});await fs.rm(linkPath,{recursive:true,force:true});await fs.symlink(hostPackageRoot,linkPath,process.platform==="win32"?"junction":"dir")};const resolveCanonicalExtensionInstallDestination=async destinationDirectory=>{const resolvedDestination=path.resolve(destinationDirectory);const destinationParent=path.dirname(resolvedDestination);const destinationRoot=path.parse(destinationParent).root;let canonicalDestinationParent=await fs.realpath(destinationRoot).catch(()=>destinationRoot);const relativeDestinationParent=path.relative(destinationRoot,destinationParent);const destinationSegments=relativeDestinationParent===""?[]:relativeDestinationParent.split(path.sep);for(const[index,segment]of destinationSegments.entries()){const candidate=path.join(canonicalDestinationParent,segment);try{canonicalDestinationParent=await fs.realpath(candidate)}catch{canonicalDestinationParent=path.join(canonicalDestinationParent,...destinationSegments.slice(index));break}}return path.join(canonicalDestinationParent,path.basename(resolvedDestination))};const copyExtensionDirectoryWithoutSelfNesting=async(sourceDirectory,destinationDirectory,copyDirectory,temporaryDirectory=os.tmpdir())=>withHostEnvironmentBoundary("extension_install_copy",async()=>{const resolvedSource=path.resolve(sourceDirectory);const canonicalSource=await fs.realpath(resolvedSource).catch(()=>resolvedSource);const canonicalDestination=await resolveCanonicalExtensionInstallDestination(destinationDirectory);if(canonicalSource===canonicalDestination){return}if(!isPathWithinDirectory(canonicalSource,canonicalDestination)){await copyDirectory(canonicalSource,destinationDirectory,{recursive:true,force:true});return}const systemTempDirectory=await fs.realpath(path.resolve(temporaryDirectory)).catch(()=>resolveCanonicalExtensionInstallDestination(temporaryDirectory));const stagingBase=isPathWithinDirectory(canonicalSource,systemTempDirectory)?path.dirname(canonicalSource):systemTempDirectory;if(isPathWithinDirectory(canonicalSource,stagingBase)){throw new PmCliError(`Extension source "${sourceDirectory}" contains its install destination and no external staging directory is available. Install a narrower package directory instead.`,EXIT_CODE.USAGE,{code:"extension_install_source_contains_destination"})}const stagingRoot=await fs.mkdtemp(path.join(stagingBase,"pm-extension-copy-"));const stagedDirectory=path.join(stagingRoot,"extension");try{await copyDirectory(canonicalSource,stagedDirectory,{recursive:true,force:true,filter:sourcePath=>includesExtensionCopyPath(canonicalSource,canonicalDestination,path.resolve(sourcePath))});await copyDirectory(stagedDirectory,destinationDirectory,{recursive:true,force:true})}finally{await fs.rm(stagingRoot,{recursive:true,force:true})}});const copyExtensionDirectoryForInstall=async(sourceDirectory,destinationDirectory,copyDirectory=fs.cp)=>{for(let attempt=1;attempt<=EXTENSION_INSTALL_COPY_ATTEMPTS;attempt+=1){try{await withHostEnvironmentBoundary("extension_install_copy",async()=>{await fs.rm(destinationDirectory,{recursive:true,force:true});await copyExtensionDirectoryWithoutSelfNesting(sourceDirectory,destinationDirectory,copyDirectory)});return}catch(error){if(!isRetriableExtensionInstallCopyError(error)||attempt===EXTENSION_INSTALL_COPY_ATTEMPTS){throw error}await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS)}}};const readExtensionInstallLockOwnerToken=async lockPath=>{let ownerContents;try{ownerContents=await fs.readFile(path.join(lockPath,"owner.json"),"utf8")}catch(error){if(!isFileAbsentError(error))throw error;return null}let parsed;try{parsed=JSON.parse(ownerContents)}catch{return null}if(typeof parsed!=="object"||parsed===null||!("token"in parsed)){return null}const token=parsed.token;return typeof token==="string"&&token.length>0?token:null};const removeExtensionInstallLockIfOwned=async(lockPath,ownerToken)=>{const currentOwnerToken=await readExtensionInstallLockOwnerToken(lockPath);if(currentOwnerToken!==ownerToken){return false}await fs.rm(lockPath,{recursive:true,force:true});return true};const reclaimStaleExtensionInstallLock=async(lockPath,staleMs)=>{let stat;try{stat=await fs.stat(lockPath)}catch{return false}if(Date.now()-stat.mtimeMs<=staleMs){return false}const staleOwnerToken=await readExtensionInstallLockOwnerToken(lockPath);if(staleOwnerToken===null){await fs.rm(lockPath,{recursive:true,force:true});return true}return removeExtensionInstallLockIfOwned(lockPath,staleOwnerToken)};const startExtensionInstallLockHeartbeat=(lockPath,ownerToken,intervalMs)=>{let heartbeat=Promise.resolve();const timer=setInterval(()=>{heartbeat=heartbeat.then(async()=>{if(await readExtensionInstallLockOwnerToken(lockPath)!==ownerToken){return}const heartbeatAt=new Date;await fs.utimes(lockPath,heartbeatAt,heartbeatAt)}).catch(()=>void 0)},intervalMs);timer.unref();return async()=>{clearInterval(timer);await heartbeat}};const createExtensionInstallLock=async(lockPath,owner)=>{await fs.mkdir(lockPath);try{await fs.writeFile(path.join(lockPath,"owner.json"),`${JSON.stringify(owner,null,2)}
+`,"utf8")}catch(error){await fs.rm(lockPath,{recursive:true,force:true}).catch(()=>{});throw error}};const acquireExtensionInstallLock=async(lockPath,owner,attempts,delayMs,staleMs)=>{for(let attempt=1;attempt<=attempts;attempt+=1){try{await createExtensionInstallLock(lockPath,owner);return true}catch(error){if(!isErrnoCode(error,"EEXIST")){throw error}if(await reclaimStaleExtensionInstallLock(lockPath,staleMs)){attempt-=1}else{await sleep(delayMs)}}}return false};const withExtensionInstallLock=async(settingsRoot,destinationDirectoryName,run,options)=>{const lockRoot=path.join(settingsRoot,"runtime","extension-install-locks");const lockPath=path.join(lockRoot,"scope.lock");await fs.mkdir(lockRoot,{recursive:true});const{attempts:rawAttempts=EXTENSION_INSTALL_LOCK_ATTEMPTS,delay_ms:rawDelayMs=EXTENSION_INSTALL_LOCK_DELAY_MS,stale_ms:rawStaleMs=EXTENSION_INSTALL_LOCK_STALE_MS,heartbeat_ms:rawHeartbeatMs}=options??{};if(![rawAttempts,rawDelayMs,rawStaleMs,rawHeartbeatMs].filter(value=>value!==void 0).every(Number.isFinite)){throw new PmCliError("Extension install lock timings must be finite numbers.",EXIT_CODE.USAGE)}const attempts=Math.max(1,Math.floor(rawAttempts));const delayMs=Math.max(0,Math.floor(rawDelayMs));const staleMs=Math.floor(rawStaleMs);const heartbeatMs=Math.floor(rawHeartbeatMs??staleMs/3);if(staleMs<=0||heartbeatMs<=0||heartbeatMs>=staleMs){throw new PmCliError("Extension install lock timings require stale_ms > 0 and 0 < heartbeat_ms < stale_ms.",EXIT_CODE.USAGE)}const owner={pid:process.pid,token:randomUUID(),created_at:nowIso(),destination:destinationDirectoryName};const acquired=await acquireExtensionInstallLock(lockPath,owner,attempts,delayMs,staleMs);if(!acquired){throw new PmCliError(`Timed out waiting for extension install lock for "${destinationDirectoryName}".`,EXIT_CODE.CONFLICT)}const stopHeartbeat=startExtensionInstallLockHeartbeat(lockPath,owner.token,heartbeatMs);try{return await run()}finally{await stopHeartbeat();await removeExtensionInstallLockIfOwned(lockPath,owner.token).catch(()=>false)}};export{copyExtensionDirectoryForInstall,copyExtensionDirectoryWithoutSelfNesting,ensureExtensionModuleTypeMarker,ensureInstalledExtensionSdkLink,isErrnoCode,isRetriableExtensionInstallCopyError,resolveCanonicalExtensionInstallDestination,withExtensionInstallLock};
 //# sourceMappingURL=install-runtime.js.map
-//# debugId=b100fde9-412b-587b-85ac-532117e2253f

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

@@ -1,67 +1,2 @@
-/**
- * @module sdk/extension/install-snapshot
- *
- * Captures and restores extension files and metadata around install persistence.
- */
-
-!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]="58ec3f16-267a-5a31-abd2-df46bb82b716")}catch(e){}}();
-import { withHostEnvironmentBoundary } from "../../core/fs/host-environment-errors.js";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { getSettingsPath } from "../../core/store/paths.js";
-import { isErrnoCode } from "./install-runtime.js";
-import { resolveManagedExtensionStatePath } from "./managed-state.js";
-/** Capture one optional metadata file without weakening non-ENOENT failures. */
-export const readOptionalMetadataFile = async (filePath) => fs.readFile(filePath).catch((error) => {
-    if (isErrnoCode(error, "ENOENT"))
-        return null;
-    throw error;
-});
-/** Capture extension files and metadata before applying an install mutation. */
-export const captureExtensionInstallSnapshot = async (selectedRoot, settingsRoot, destinationDirectory, destinationExists, backupDirectory) => withHostEnvironmentBoundary("extension_install_backup", async () => {
-    const managedStatePath = resolveManagedExtensionStatePath(selectedRoot);
-    const settingsPath = getSettingsPath(settingsRoot);
-    const [managedStateContents, settingsContents] = await Promise.all([
-        readOptionalMetadataFile(managedStatePath),
-        readOptionalMetadataFile(settingsPath),
-    ]);
-    if (destinationExists) {
-        await fs.cp(destinationDirectory, backupDirectory, {
-            recursive: true,
-            force: true,
-        });
-    }
-    return {
-        backupDirectory,
-        destinationDirectory,
-        destinationExists,
-        managedStatePath,
-        managedStateContents,
-        settingsPath,
-        settingsContents,
-    };
-});
-/** Restore directory and metadata snapshots after a partially persisted install. */
-export const restoreExtensionInstallSnapshot = async (snapshot) => withHostEnvironmentBoundary("extension_install_rollback", async () => {
-    await fs.rm(snapshot.destinationDirectory, { recursive: true, force: true });
-    if (snapshot.destinationExists) {
-        await fs.cp(snapshot.backupDirectory, snapshot.destinationDirectory, {
-            recursive: true,
-            force: true,
-        });
-    }
-    for (const [filePath, contents] of [
-        [snapshot.managedStatePath, snapshot.managedStateContents],
-        [snapshot.settingsPath, snapshot.settingsContents],
-    ]) {
-        if (contents === null) {
-            await fs.rm(filePath, { force: true });
-        }
-        else {
-            await fs.mkdir(path.dirname(filePath), { recursive: true });
-            await fs.writeFile(filePath, contents);
-        }
-    }
-});
+!(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]="d7afb9a1-be35-5dfd-a52e-2525598b68d8")}catch(e2){}})();import{withHostEnvironmentBoundary}from"../../core/fs/host-environment-errors.js";import fs from"node:fs/promises";import path from"node:path";import{getSettingsPath}from"../../core/store/paths.js";import{isErrnoCode}from"./install-runtime.js";import{resolveManagedExtensionStatePath}from"./managed-state.js";const readOptionalMetadataFile=async filePath=>fs.readFile(filePath).catch(error=>{if(isErrnoCode(error,"ENOENT"))return null;throw error});const captureExtensionInstallSnapshot=async(selectedRoot,settingsRoot,destinationDirectory,destinationExists,backupDirectory)=>withHostEnvironmentBoundary("extension_install_backup",async()=>{const managedStatePath=resolveManagedExtensionStatePath(selectedRoot);const settingsPath=getSettingsPath(settingsRoot);const[managedStateContents,settingsContents]=await Promise.all([readOptionalMetadataFile(managedStatePath),readOptionalMetadataFile(settingsPath)]);if(destinationExists){await fs.cp(destinationDirectory,backupDirectory,{recursive:true,force:true})}return{backupDirectory,destinationDirectory,destinationExists,managedStatePath,managedStateContents,settingsPath,settingsContents}});const restoreExtensionInstallSnapshot=async snapshot=>withHostEnvironmentBoundary("extension_install_rollback",async()=>{await fs.rm(snapshot.destinationDirectory,{recursive:true,force:true});if(snapshot.destinationExists){await fs.cp(snapshot.backupDirectory,snapshot.destinationDirectory,{recursive:true,force:true})}for(const[filePath,contents]of[[snapshot.managedStatePath,snapshot.managedStateContents],[snapshot.settingsPath,snapshot.settingsContents]]){if(contents===null){await fs.rm(filePath,{force:true})}else{await fs.mkdir(path.dirname(filePath),{recursive:true});await fs.writeFile(filePath,contents)}}});export{captureExtensionInstallSnapshot,readOptionalMetadataFile,restoreExtensionInstallSnapshot};
 //# sourceMappingURL=install-snapshot.js.map
-//# debugId=58ec3f16-267a-5a31-abd2-df46bb82b716