@unbrained/pm-cli 2026.7.14 → 2026.7.15

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

@@ -0,0 +1,269 @@
+/**
+ * @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]="ef5442ae-3385-544e-889f-d4d78ee473c1")}catch(e){}}();
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { 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 { 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");
+};
+/** 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()) => {
+    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 systemTempDirectory = path.resolve(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,
+        });
+        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 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 (!isErrnoCode(error, "ENOENT"))
+            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);
+    }
+};
+//# sourceMappingURL=install-runtime.js.map
+//# debugId=ef5442ae-3385-544e-889f-d4d78ee473c1

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

@@ -0,0 +1 @@
+{"version":3,"file":"install-runtime.js","sources":["sdk/extension/install-runtime.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/extension/install-runtime\n *\n * Provides cross-platform extension copy safety and owner-bound install locks.\n */\nimport { randomUUID } from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport os from \"node:os\";\nimport path from \"node:path\";\nimport { pathExists } from \"../../core/fs/fs-utils.js\";\nimport { isPathWithinDirectory } from \"../../core/fs/path-utils.js\";\nimport { EXIT_CODE } from \"../../core/shared/constants.js\";\nimport { PmCliError } from \"../../core/shared/errors.js\";\nimport { nowIso } from \"../../core/shared/time.js\";\n\nconst EXTENSION_INSTALL_COPY_ATTEMPTS = 3;\nconst EXTENSION_INSTALL_LOCK_ATTEMPTS = 120;\nconst EXTENSION_INSTALL_LOCK_DELAY_MS = 250;\nconst EXTENSION_INSTALL_LOCK_STALE_MS = 120_000;\nconst RETRIABLE_EXTENSION_INSTALL_COPY_CODES = new Set([\n  \"EEXIST\",\n  \"ENOTEMPTY\",\n  \"ENOENT\",\n]);\n\ninterface ExtensionInstallLockOwner {\n  pid: number;\n  token: string;\n  created_at: string;\n  destination: string;\n}\n\n/** Retry and lease timing overrides for one extension install lock. */\nexport interface ExtensionInstallLockOptions {\n  /** Maximum lock-acquisition attempts. */\n  attempts?: number;\n  /** Delay between contended acquisition attempts. */\n  delay_ms?: number;\n  /** Age after which an unchanged owner lease can be reclaimed. */\n  stale_ms?: number;\n  /** Lease heartbeat interval while the operation runs. */\n  heartbeat_ms?: number;\n}\n\n/** Return an errno-style code from an unknown failure when one is present. */\nconst errnoCode = (error: unknown): unknown =>\n  typeof error === \"object\" && error !== null && \"code\" in error\n    ? (error as { code?: unknown }).code\n    : undefined;\n\n/** Identify transient copy races that are safe to retry during extension installation. */\nexport const isRetriableExtensionInstallCopyError = (error: unknown): boolean =>\n  RETRIABLE_EXTENSION_INSTALL_COPY_CODES.has(String(errnoCode(error)));\n\n/** Test an unknown failure against one expected errno-style code. */\nexport const isErrnoCode = (error: unknown, code: string): boolean =>\n  errnoCode(error) === code;\n\n/** Delay an extension filesystem retry without blocking the event loop. */\nconst sleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n\n/** Ensure an installed extension carries an ESM package boundary marker. */\nexport const ensureExtensionModuleTypeMarker = async (\n  destinationDirectory: string,\n): Promise<void> => {\n  const markerPath = path.join(destinationDirectory, \"package.json\");\n  if (await pathExists(markerPath)) {\n    return;\n  }\n  await fs.writeFile(\n    markerPath,\n    `${JSON.stringify({ type: \"module\" }, null, 2)}\\n`,\n    \"utf8\",\n  );\n};\n\n/** Resolve a possibly partial extension destination through every existing symlink segment. */\nexport const resolveCanonicalExtensionInstallDestination = async (\n  destinationDirectory: string,\n): Promise<string> => {\n  const resolvedDestination = path.resolve(destinationDirectory);\n  const destinationParent = path.dirname(resolvedDestination);\n  const destinationRoot = path.parse(destinationParent).root;\n  let canonicalDestinationParent = await fs\n    .realpath(destinationRoot)\n    .catch(() => destinationRoot);\n  const relativeDestinationParent = path.relative(\n    destinationRoot,\n    destinationParent,\n  );\n  const destinationSegments =\n    relativeDestinationParent === \"\"\n      ? []\n      : relativeDestinationParent.split(path.sep);\n  for (const [index, segment] of destinationSegments.entries()) {\n    const candidate = path.join(canonicalDestinationParent, segment);\n    try {\n      canonicalDestinationParent = await fs.realpath(candidate);\n    } catch {\n      canonicalDestinationParent = path.join(\n        canonicalDestinationParent,\n        ...destinationSegments.slice(index),\n      );\n      break;\n    }\n  }\n  return path.join(\n    canonicalDestinationParent,\n    path.basename(resolvedDestination),\n  );\n};\n\n/** Copy an extension without recursively copying a destination nested below its source. */\nexport const copyExtensionDirectoryWithoutSelfNesting = async (\n  sourceDirectory: string,\n  destinationDirectory: string,\n  copyDirectory: typeof fs.cp,\n  temporaryDirectory = os.tmpdir(),\n): Promise<void> => {\n  const resolvedSource = path.resolve(sourceDirectory);\n  const canonicalSource = await fs\n    .realpath(resolvedSource)\n    .catch(() => resolvedSource);\n  const canonicalDestination =\n    await resolveCanonicalExtensionInstallDestination(destinationDirectory);\n  if (canonicalSource === canonicalDestination) {\n    return;\n  }\n  if (!isPathWithinDirectory(canonicalSource, canonicalDestination)) {\n    await copyDirectory(sourceDirectory, destinationDirectory, {\n      recursive: true,\n      force: true,\n    });\n    return;\n  }\n\n  const systemTempDirectory = path.resolve(temporaryDirectory);\n  const stagingBase = isPathWithinDirectory(\n    canonicalSource,\n    systemTempDirectory,\n  )\n    ? path.dirname(canonicalSource)\n    : systemTempDirectory;\n  if (isPathWithinDirectory(canonicalSource, stagingBase)) {\n    throw new PmCliError(\n      `Extension source \"${sourceDirectory}\" contains its install destination and no external staging directory is available. Install a narrower package directory instead.`,\n      EXIT_CODE.USAGE,\n      { code: \"extension_install_source_contains_destination\" },\n    );\n  }\n  const stagingRoot = await fs.mkdtemp(\n    path.join(stagingBase, \"pm-extension-copy-\"),\n  );\n  const stagedDirectory = path.join(stagingRoot, \"extension\");\n  try {\n    await copyDirectory(sourceDirectory, stagedDirectory, {\n      recursive: true,\n      force: true,\n    });\n    await copyDirectory(stagedDirectory, destinationDirectory, {\n      recursive: true,\n      force: true,\n    });\n  } finally {\n    await fs.rm(stagingRoot, { recursive: true, force: true });\n  }\n};\n\n/** Copy one extension directory with bounded transient-race retries. */\nexport const copyExtensionDirectoryForInstall = async (\n  sourceDirectory: string,\n  destinationDirectory: string,\n  copyDirectory: typeof fs.cp = fs.cp,\n): Promise<void> => {\n  for (\n    let attempt = 1;\n    attempt <= EXTENSION_INSTALL_COPY_ATTEMPTS;\n    attempt += 1\n  ) {\n    try {\n      await fs.rm(destinationDirectory, { recursive: true, force: true });\n      await copyExtensionDirectoryWithoutSelfNesting(\n        sourceDirectory,\n        destinationDirectory,\n        copyDirectory,\n      );\n      return;\n    } catch (error: unknown) {\n      if (\n        !isRetriableExtensionInstallCopyError(error) ||\n        attempt === EXTENSION_INSTALL_COPY_ATTEMPTS\n      ) {\n        throw error;\n      }\n      await sleep(EXTENSION_INSTALL_LOCK_DELAY_MS);\n    }\n  }\n};\n\n/** Read the unique owner token recorded for one extension scope lock. */\nconst readExtensionInstallLockOwnerToken = async (\n  lockPath: string,\n): Promise<string | null> => {\n  let ownerContents: string;\n  try {\n    ownerContents = await fs.readFile(\n      path.join(lockPath, \"owner.json\"),\n      \"utf8\",\n    );\n  } catch (error: unknown) {\n    if (!isErrnoCode(error, \"ENOENT\")) throw error;\n    return null;\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(ownerContents);\n  } catch {\n    return null;\n  }\n  if (typeof parsed !== \"object\" || parsed === null || !(\"token\" in parsed)) {\n    return null;\n  }\n  const token = (parsed as { token?: unknown }).token;\n  return typeof token === \"string\" && token.length > 0 ? token : null;\n};\n\n/** Remove an extension scope lock only while its persisted owner token still matches. */\nconst removeExtensionInstallLockIfOwned = async (\n  lockPath: string,\n  ownerToken: string,\n): Promise<boolean> => {\n  const currentOwnerToken = await readExtensionInstallLockOwnerToken(lockPath);\n  if (currentOwnerToken !== ownerToken) {\n    return false;\n  }\n  await fs.rm(lockPath, { recursive: true, force: true });\n  return true;\n};\n\n/** Reclaim an expired extension scope lock when its persisted owner remains unchanged. */\nconst reclaimStaleExtensionInstallLock = async (\n  lockPath: string,\n  staleMs: number,\n): Promise<boolean> => {\n  let stat: Awaited<ReturnType<typeof fs.stat>>;\n  try {\n    stat = await fs.stat(lockPath);\n  } catch {\n    return false;\n  }\n  if (Date.now() - stat.mtimeMs <= staleMs) {\n    return false;\n  }\n  const staleOwnerToken = await readExtensionInstallLockOwnerToken(lockPath);\n  if (staleOwnerToken === null) {\n    await fs.rm(lockPath, { recursive: true, force: true });\n    return true;\n  }\n  return removeExtensionInstallLockIfOwned(lockPath, staleOwnerToken);\n};\n\n/** Start an owner-bound lease heartbeat and return an async stop barrier. */\nconst startExtensionInstallLockHeartbeat = (\n  lockPath: string,\n  ownerToken: string,\n  intervalMs: number,\n): (() => Promise<void>) => {\n  let heartbeat = Promise.resolve();\n  const timer = setInterval(() => {\n    heartbeat = heartbeat\n      .then(async () => {\n        if (\n          (await readExtensionInstallLockOwnerToken(lockPath)) !== ownerToken\n        ) {\n          return;\n        }\n        const heartbeatAt = new Date();\n        await fs.utimes(lockPath, heartbeatAt, heartbeatAt);\n      })\n      .catch(() => undefined);\n  }, intervalMs);\n  timer.unref();\n  return async () => {\n    clearInterval(timer);\n    await heartbeat;\n  };\n};\n\n/** Create one owner-bound extension install lock, removing partial state on failure. */\nconst createExtensionInstallLock = async (\n  lockPath: string,\n  owner: ExtensionInstallLockOwner,\n): Promise<void> => {\n  await fs.mkdir(lockPath);\n  try {\n    await fs.writeFile(\n      path.join(lockPath, \"owner.json\"),\n      `${JSON.stringify(owner, null, 2)}\\n`,\n      \"utf8\",\n    );\n  } catch (error: unknown) {\n    await fs.rm(lockPath, { recursive: true, force: true }).catch(() => {});\n    throw error;\n  }\n};\n\n/** Retry owner-bound extension lock acquisition while reclaiming stale owners. */\nconst acquireExtensionInstallLock = async (\n  lockPath: string,\n  owner: ExtensionInstallLockOwner,\n  attempts: number,\n  delayMs: number,\n  staleMs: number,\n): Promise<boolean> => {\n  for (let attempt = 1; attempt <= attempts; attempt += 1) {\n    try {\n      await createExtensionInstallLock(lockPath, owner);\n      return true;\n    } catch (error: unknown) {\n      if (!isErrnoCode(error, \"EEXIST\")) {\n        throw error;\n      }\n      if (await reclaimStaleExtensionInstallLock(lockPath, staleMs)) {\n        attempt -= 1;\n      } else {\n        await sleep(delayMs);\n      }\n    }\n  }\n  return false;\n};\n\n/** Run one operation under an owner-bound extension install lock and heartbeat lease. */\nexport const withExtensionInstallLock = async <T>(\n  settingsRoot: string,\n  destinationDirectoryName: string,\n  run: () => Promise<T>,\n  options?: ExtensionInstallLockOptions,\n): Promise<T> => {\n  const lockRoot = path.join(\n    settingsRoot,\n    \"runtime\",\n    \"extension-install-locks\",\n  );\n  const lockPath = path.join(lockRoot, \"scope.lock\");\n  await fs.mkdir(lockRoot, { recursive: true });\n  const {\n    attempts: rawAttempts = EXTENSION_INSTALL_LOCK_ATTEMPTS,\n    delay_ms: rawDelayMs = EXTENSION_INSTALL_LOCK_DELAY_MS,\n    stale_ms: rawStaleMs = EXTENSION_INSTALL_LOCK_STALE_MS,\n    heartbeat_ms: rawHeartbeatMs,\n  } = options ?? {};\n  if (\n    ![rawAttempts, rawDelayMs, rawStaleMs, rawHeartbeatMs]\n      .filter((value): value is number => value !== undefined)\n      .every(Number.isFinite)\n  ) {\n    throw new PmCliError(\n      \"Extension install lock timings must be finite numbers.\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  const attempts = Math.max(1, Math.floor(rawAttempts));\n  const delayMs = Math.max(0, Math.floor(rawDelayMs));\n  const staleMs = Math.floor(rawStaleMs);\n  const heartbeatMs = Math.floor(rawHeartbeatMs ?? staleMs / 3);\n  if (staleMs <= 0 || heartbeatMs <= 0 || heartbeatMs >= staleMs) {\n    throw new PmCliError(\n      \"Extension install lock timings require stale_ms > 0 and 0 < heartbeat_ms < stale_ms.\",\n      EXIT_CODE.USAGE,\n    );\n  }\n  const owner: ExtensionInstallLockOwner = {\n    pid: process.pid,\n    token: randomUUID(),\n    created_at: nowIso(),\n    destination: destinationDirectoryName,\n  };\n  const acquired = await acquireExtensionInstallLock(\n    lockPath,\n    owner,\n    attempts,\n    delayMs,\n    staleMs,\n  );\n  if (!acquired) {\n    throw new PmCliError(\n      `Timed out waiting for extension install lock for \"${destinationDirectoryName}\".`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n\n  const stopHeartbeat = startExtensionInstallLockHeartbeat(\n    lockPath,\n    owner.token,\n    heartbeatMs,\n  );\n  try {\n    return await run();\n  } finally {\n    await stopHeartbeat();\n    await removeExtensionInstallLockIfOwned(lockPath, owner.token).catch(\n      () => false,\n    );\n  }\n};\n"],"names":[],"mappings":"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","debugId":"ef5442ae-3385-544e-889f-d4d78ee473c1"}

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

@@ -0,0 +1,23 @@
+/** Exact filesystem and metadata state captured before an extension install. */
+export interface ExtensionInstallSnapshot {
+    /** Temporary copy of the prior destination directory. */
+    backupDirectory: string;
+    /** Extension destination being installed. */
+    destinationDirectory: string;
+    /** Whether the destination existed before installation. */
+    destinationExists: boolean;
+    /** Managed-extension state file path. */
+    managedStatePath: string;
+    /** Exact prior managed-extension state contents. */
+    managedStateContents: Buffer | null;
+    /** Project settings file path. */
+    settingsPath: string;
+    /** Exact prior project settings contents. */
+    settingsContents: Buffer | null;
+}
+/** Capture one optional metadata file without weakening non-ENOENT failures. */
+export declare const readOptionalMetadataFile: (filePath: string) => Promise<Buffer | null>;
+/** Capture extension files and metadata before applying an install mutation. */
+export declare const captureExtensionInstallSnapshot: (selectedRoot: string, settingsRoot: string, destinationDirectory: string, destinationExists: boolean, backupDirectory: string) => Promise<ExtensionInstallSnapshot>;
+/** Restore directory and metadata snapshots after a partially persisted install. */
+export declare const restoreExtensionInstallSnapshot: (snapshot: ExtensionInstallSnapshot) => Promise<void>;

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

@@ -0,0 +1,66 @@
+/**
+ * @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]="b131d360-d3d1-54b1-800b-54d0ab0ad282")}catch(e){}}();
+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) => {
+    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) => {
+    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);
+        }
+    }
+};
+//# sourceMappingURL=install-snapshot.js.map
+//# debugId=b131d360-d3d1-54b1-800b-54d0ab0ad282

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

@@ -0,0 +1 @@
+{"version":3,"file":"install-snapshot.js","sources":["sdk/extension/install-snapshot.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/extension/install-snapshot\n *\n * Captures and restores extension files and metadata around install persistence.\n */\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { getSettingsPath } from \"../../core/store/paths.js\";\nimport { isErrnoCode } from \"./install-runtime.js\";\nimport { resolveManagedExtensionStatePath } from \"./managed-state.js\";\n\n/** Exact filesystem and metadata state captured before an extension install. */\nexport interface ExtensionInstallSnapshot {\n  /** Temporary copy of the prior destination directory. */\n  backupDirectory: string;\n  /** Extension destination being installed. */\n  destinationDirectory: string;\n  /** Whether the destination existed before installation. */\n  destinationExists: boolean;\n  /** Managed-extension state file path. */\n  managedStatePath: string;\n  /** Exact prior managed-extension state contents. */\n  managedStateContents: Buffer | null;\n  /** Project settings file path. */\n  settingsPath: string;\n  /** Exact prior project settings contents. */\n  settingsContents: Buffer | null;\n}\n\n/** Capture one optional metadata file without weakening non-ENOENT failures. */\nexport const readOptionalMetadataFile = async (\n  filePath: string,\n): Promise<Buffer | null> =>\n  fs.readFile(filePath).catch((error: unknown) => {\n    if (isErrnoCode(error, \"ENOENT\")) return null;\n    throw error;\n  });\n\n/** Capture extension files and metadata before applying an install mutation. */\nexport const captureExtensionInstallSnapshot = async (\n  selectedRoot: string,\n  settingsRoot: string,\n  destinationDirectory: string,\n  destinationExists: boolean,\n  backupDirectory: string,\n): Promise<ExtensionInstallSnapshot> => {\n  const managedStatePath = resolveManagedExtensionStatePath(selectedRoot);\n  const settingsPath = getSettingsPath(settingsRoot);\n  const [managedStateContents, settingsContents] = await Promise.all([\n    readOptionalMetadataFile(managedStatePath),\n    readOptionalMetadataFile(settingsPath),\n  ]);\n  if (destinationExists) {\n    await fs.cp(destinationDirectory, backupDirectory, {\n      recursive: true,\n      force: true,\n    });\n  }\n  return {\n    backupDirectory,\n    destinationDirectory,\n    destinationExists,\n    managedStatePath,\n    managedStateContents,\n    settingsPath,\n    settingsContents,\n  };\n};\n\n/** Restore directory and metadata snapshots after a partially persisted install. */\nexport const restoreExtensionInstallSnapshot = async (\n  snapshot: ExtensionInstallSnapshot,\n): Promise<void> => {\n  await fs.rm(snapshot.destinationDirectory, { recursive: true, force: true });\n  if (snapshot.destinationExists) {\n    await fs.cp(snapshot.backupDirectory, snapshot.destinationDirectory, {\n      recursive: true,\n      force: true,\n    });\n  }\n  for (const [filePath, contents] of [\n    [snapshot.managedStatePath, snapshot.managedStateContents],\n    [snapshot.settingsPath, snapshot.settingsContents],\n  ] as const) {\n    if (contents === null) {\n      await fs.rm(filePath, { force: true });\n    } else {\n      await fs.mkdir(path.dirname(filePath), { recursive: true });\n      await fs.writeFile(filePath, contents);\n    }\n  }\n};\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAC;AAoBtE,gFAAgF;AAChF,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,EAC3C,QAAgB,EACQ,EAAE,CAC1B,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC7C,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,KAAK,CAAC;AACd,CAAC,CAAC,CAAC;AAEL,gFAAgF;AAChF,MAAM,CAAC,MAAM,+BAA+B,GAAG,KAAK,EAClD,YAAoB,EACpB,YAAoB,EACpB,oBAA4B,EAC5B,iBAA0B,EAC1B,eAAuB,EACY,EAAE;IACrC,MAAM,gBAAgB,GAAG,gCAAgC,CAAC,YAAY,CAAC,CAAC;IACxE,MAAM,YAAY,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IACnD,MAAM,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACjE,wBAAwB,CAAC,gBAAgB,CAAC;QAC1C,wBAAwB,CAAC,YAAY,CAAC;KACvC,CAAC,CAAC;IACH,IAAI,iBAAiB,EAAE,CAAC;QACtB,MAAM,EAAE,CAAC,EAAE,CAAC,oBAAoB,EAAE,eAAe,EAAE;YACjD,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,eAAe;QACf,oBAAoB;QACpB,iBAAiB;QACjB,gBAAgB;QAChB,oBAAoB;QACpB,YAAY;QACZ,gBAAgB;KACjB,CAAC;AACJ,CAAC,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,MAAM,+BAA+B,GAAG,KAAK,EAClD,QAAkC,EACnB,EAAE;IACjB,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,oBAAoB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7E,IAAI,QAAQ,CAAC,iBAAiB,EAAE,CAAC;QAC/B,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,oBAAoB,EAAE;YACnE,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;IACL,CAAC;IACD,KAAK,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI;QACjC,CAAC,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,oBAAoB,CAAC;QAC1D,CAAC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,gBAAgB,CAAC;KAC1C,EAAE,CAAC;QACX,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;AACH,CAAC,CAAC","debugId":"b131d360-d3d1-54b1-800b-54d0ab0ad282"}

package/dist/{cli/commands → sdk}/extension/install-sources.d.ts

@@ -1,10 +1,10 @@
 /**
- * @module cli/commands/extension/install-sources
+ * @module sdk/extension/install-sources
  *
  * Implements extension package-management support for Install Sources.
  */
 import { execFile } from "node:child_process";
-import { PmCliError, type PmCliErrorContext } from "../../../core/shared/errors.js";
+import { PmCliError, type PmCliErrorContext } from "../../core/shared/errors.js";
 declare const execFileAsync: typeof execFile.__promisify__;
 interface LocalInstallSource {
     kind: "local";
@@ -41,7 +41,7 @@ export declare function parseExtensionInstallSource(input: string, options?: {
     ref?: string;
 }): InstallSource;
 /** Implements run git command for the public runtime surface of this module. */
-export declare function runGitCommand(args: string[], execRunner?: typeof execFileAsync): Promise<string>;
+export declare function runGitCommand(args: string[], execRunner?: typeof execFileAsync, timeoutMs?: number): Promise<string>;
 /** Implements resolve npm command name for the public runtime surface of this module. */
 export declare function resolveNpmCommandName(platform?: NodeJS.Platform): "npm" | "npm.cmd";
 /** Implements should run npm command in shell for the public runtime surface of this module. */

package/dist/{cli/commands → sdk}/extension/install-sources.js

@@ -1,22 +1,22 @@
 /**
- * @module cli/commands/extension/install-sources
+ * @module sdk/extension/install-sources
  *
  * 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]="6e45b979-29e4-52c4-a8de-9d7dcd31f857")}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]="38193531-eca3-557b-ab40-d4af159b9192")}catch(e){}}();
 import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
-import { collectPackageExtensionDirectories } from "../../../core/packages/manifest.js";
-import { resolvePmPackageRootFromModule } from "../../../core/packages/root.js";
-import { 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 { collectPackageExtensionDirectories } from "../../core/packages/manifest.js";
+import { resolvePmPackageRootFromModule } from "../../core/packages/root.js";
+import { 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 { listBundledPackageAliases } from "./bundled-catalog.js";
 const execFileAsync = promisify(execFile);
 const PM_CLI_PACKAGE_NAME = "@unbrained/pm-cli";
@@ -129,9 +129,12 @@ export function parseExtensionInstallSource(input, options = {}) {
     };
 }
 /** Implements run git command for the public runtime surface of this module. */
-export async function runGitCommand(args, execRunner = execFileAsync) {
+export async function runGitCommand(args, execRunner = execFileAsync, timeoutMs) {
     try {
-        const result = await execRunner("git", args, { encoding: "utf8" });
+        const result = await execRunner("git", args, {
+            encoding: "utf8",
+            timeout: timeoutMs,
+        });
         return (result.stdout ?? "").trim();
     }
     catch (error) {
@@ -522,7 +525,7 @@ function removeHostedPmCliDependency(manifest) {
 }
 async function linkHostedPmCliDependency(packageRoot) {
     const hostPackageRoot = resolvePmPackageRootFromModule(import.meta.url, [
-        "../../../..",
+        "../../..",
     ]);
     const [scope, packageName] = PM_CLI_PACKAGE_NAME.split("/");
     const scopedDirectory = path.join(packageRoot, "node_modules", scope);
@@ -747,4 +750,4 @@ export const _testOnlyInstallSources = {
     runNpmCommand,
 };
 //# sourceMappingURL=install-sources.js.map
-//# debugId=6e45b979-29e4-52c4-a8de-9d7dcd31f857
+//# debugId=38193531-eca3-557b-ab40-d4af159b9192