@unbrained/pm-cli 2026.7.3 → 2026.7.5

package/dist/cli-bundle/chunks/{chunk-4WB6S4YX.js → chunk-57C2RLW5.js}

@@ -1,45 +1,51 @@
 
-!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]="c1ba30e7-4db1-564b-a399-af5da0c99b7e")}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]="c9a5ce7b-7b83-549d-bddc-c6f8ce8564b8")}catch(e){}}();
 import {
   canonicalDocument,
+  normalizeItemId,
+  normalizeRawItemId,
   parseItemDocument,
   serializeItemDocument
-} from "./chunk-YSDFIY7N.js";
+} from "./chunk-HK72NWAD.js";
 import {
-  evictOldestMemoEntries,
   nowIso
-} from "./chunk-CXR3CMBQ.js";
+} from "./chunk-FJRKQREY.js";
+import {
+  PmCliError,
+  getActiveExtensionRegistrations,
+  hasActiveOnReadHooks,
+  orderObject,
+  projectAfterCommandItemSnapshot,
+  recordAfterCommandAffectedItem,
+  resolveGovernanceKnobs,
+  runActiveOnReadHooks,
+  runActiveOnWriteHooks,
+  runActiveServiceOverride,
+  sha256Hex,
+  stableStringify
+} from "./chunk-US3T3W5J.js";
+import {
+  evictOldestMemoEntries
+} from "./chunk-NNHHXJB2.js";
 import {
   EMPTY_CANONICAL_DOCUMENT,
   EXIT_CODE,
   FRONT_MATTER_KEY_ORDER,
   ITEM_FILE_EXTENSIONS,
-  PmCliError,
   TYPE_TO_FOLDER,
   appendLineAtomic,
   ensureDir,
-  getActiveExtensionRegistrations,
   getHistoryPath,
   getItemFormatFromPath,
   getItemPath,
   getLockPath,
-  hasActiveOnReadHooks,
   levenshteinDistanceWithinLimit,
   normalizeItemFieldType,
-  orderObject,
   pathExists,
-  projectAfterCommandItemSnapshot,
-  recordAfterCommandAffectedItem,
-  resolveGovernanceKnobs,
   resolveItemTypeRegistry,
-  runActiveOnReadHooks,
-  runActiveOnWriteHooks,
-  runActiveServiceOverride,
-  sha256Hex,
-  stableStringify,
   toErrorMessage,
   writeFileAtomic
-} from "./chunk-L4SLHV6G.js";
+} from "./chunk-YD5FML7K.js";
 
 // dist/core/extensions/item-fields.js
 var RESERVED_ITEM_FIELD_NAMES = new Set(FRONT_MATTER_KEY_ORDER);
@@ -234,17 +240,17 @@ var EMPTY_LEGACY_HASH_DOCUMENT = {
   front_matter: {},
   body: ""
 };
-function decodeJsonPointer(path6) {
-  if (!path6 || path6 === "/") {
+function decodeJsonPointer(path5) {
+  if (!path5 || path5 === "/") {
     return [];
   }
-  if (!path6.startsWith("/")) {
+  if (!path5.startsWith("/")) {
     return [];
   }
-  return path6.slice(1).split("/").map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
+  return path5.slice(1).split("/").map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"));
 }
-function isDefinedPointerPath(document, path6) {
-  const segments = decodeJsonPointer(path6);
+function isDefinedPointerPath(document, path5) {
+  const segments = decodeJsonPointer(path5);
   if (segments.length === 0) {
     return true;
   }
@@ -455,6 +461,7 @@ async function enforceHistoryStreamPolicyForItems(params) {
 // dist/core/lock/lock.js
 import fs2 from "node:fs/promises";
 import path2 from "node:path";
+import { randomUUID } from "node:crypto";
 function parseLockInfo(raw) {
   let parsed;
   try {
@@ -549,7 +556,9 @@ async function unlinkLockWithHook(lockPath, op) {
   try {
     await fs2.unlink(lockPath);
     await emitLockWriteHook(lockPath, op);
+    return true;
   } catch {
+    return false;
   }
 }
 function isStaleLock(info, ttlSeconds) {
@@ -560,18 +569,210 @@ function isStaleLock(info, ttlSeconds) {
 function lockOwnerSuffix(info) {
   return info?.owner ? ` (owner ${info.owner})` : "";
 }
-async function handleExistingLock(lockPath, id, ttlSeconds, force, forceRequiredForStaleLock) {
-  const lockInfo = await readLockInfo(lockPath);
-  if (!isStaleLock(lockInfo.info, ttlSeconds)) {
-    throw new PmCliError(`Item ${id} is locked${lockOwnerSuffix(lockInfo.info)}`, EXIT_CODE.CONFLICT);
+var LOCK_WAIT_INITIAL_DELAY_MS = 25;
+var LOCK_WAIT_MAX_DELAY_MS = 200;
+var LOCK_CONFLICT_RETRY_HINT_MS = 250;
+var MAX_STALE_LOCK_REMOVALS = 3;
+var STALE_CLEANUP_GATE_SUFFIX = ".stale-cleanup";
+var STALE_CLEANUP_GATE_OWNER_FILE = "owner.json";
+var STALE_CLEANUP_GATE_STALE_MS = 1e4;
+var STALE_CLEANUP_GATE_MAX_ACTIVE_MS = 5 * 6e4;
+function parseNonNegativeIntegerWaitMs(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+      return void 0;
+    }
+    const parsed = Number(trimmed);
+    return Number.isSafeInteger(parsed) ? parsed : void 0;
+  }
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return Math.trunc(value);
+  }
+  return void 0;
+}
+function resolveLockWaitMs(waitMs) {
+  const envRaw = process.env.PM_LOCK_WAIT_MS;
+  const envParsed = parseNonNegativeIntegerWaitMs(envRaw);
+  if (envParsed !== void 0) {
+    return envParsed;
   }
-  if (!force && forceRequiredForStaleLock) {
+  const callerParsed = parseNonNegativeIntegerWaitMs(waitMs);
+  if (callerParsed !== void 0) {
+    return callerParsed;
+  }
+  return 0;
+}
+function sleepWithJitter(baseDelayMs) {
+  const jitteredMs = Math.max(1, Math.round(baseDelayMs * (0.5 + Math.random())));
+  return new Promise((resolve) => setTimeout(resolve, jitteredMs));
+}
+function buildLockConflictError(id, info, waitedMs) {
+  const waitedSuffix = waitedMs > 0 ? ` after waiting ${waitedMs}ms` : "";
+  return new PmCliError(`Item ${id} is locked${lockOwnerSuffix(info)}${waitedSuffix}`, EXIT_CODE.CONFLICT, {
+    code: "lock_conflict",
+    recovery: {
+      retry_after_ms: LOCK_CONFLICT_RETRY_HINT_MS
+    }
+  });
+}
+function resolveLockOverrideRelease(result) {
+  if (typeof result === "function") {
+    return result;
+  }
+  if (typeof result === "object" && result !== null && "release" in result) {
+    const release = result.release;
+    return typeof release === "function" ? release : null;
+  }
+  return null;
+}
+function throwIfStaleLockNeedsForce(id, lockInfo, force, forceRequired) {
+  if (!force && forceRequired) {
     const warningSuffix = lockInfo.warnings.length > 0 ? ` (${lockInfo.warnings.join(",")})` : "";
     throw new PmCliError(`Item ${id} lock is stale${warningSuffix}; rerun with --force when supported for this command`, EXIT_CODE.CONFLICT);
   }
-  await unlinkLockWithHook(lockPath, "lock:stale_remove");
 }
-async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRequiredForStaleLock = true) {
+function parseStaleCleanupGateOwner(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+  const candidate = parsed;
+  const pid = candidate.pid;
+  const token = candidate.token;
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0 || typeof token !== "string" || token.length === 0) {
+    return null;
+  }
+  return { pid, token };
+}
+async function readStaleCleanupGateOwner(gatePath) {
+  try {
+    return parseStaleCleanupGateOwner(await fs2.readFile(path2.join(gatePath, STALE_CLEANUP_GATE_OWNER_FILE), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (isErrno(error, "ESRCH")) {
+      return false;
+    }
+    return true;
+  }
+}
+async function removeStaleCleanupGateDirectory(gatePath) {
+  try {
+    await fs2.rm(gatePath, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function releaseStaleCleanupGate(gatePath, token) {
+  const owner = await readStaleCleanupGateOwner(gatePath);
+  if (owner === null || owner.token !== token) {
+    return;
+  }
+  await removeStaleCleanupGateDirectory(gatePath);
+}
+async function tryCreateStaleCleanupGate(gatePath) {
+  try {
+    await fs2.mkdir(gatePath);
+  } catch (error) {
+    if (isErrno(error, "EEXIST")) {
+      return null;
+    }
+    return null;
+  }
+  const owner = { pid: process.pid, token: randomUUID() };
+  try {
+    await fs2.writeFile(path2.join(gatePath, STALE_CLEANUP_GATE_OWNER_FILE), `${JSON.stringify(owner)}
+`, "utf8");
+  } catch {
+    await removeStaleCleanupGateDirectory(gatePath);
+    return null;
+  }
+  return owner;
+}
+async function removeExpiredStaleCleanupGate(gatePath) {
+  let gateAgeMs;
+  try {
+    const stats = await fs2.stat(gatePath);
+    gateAgeMs = Date.now() - stats.mtimeMs;
+    if (gateAgeMs <= STALE_CLEANUP_GATE_STALE_MS) {
+      return false;
+    }
+  } catch (error) {
+    return isErrno(error, "ENOENT");
+  }
+  const owner = await readStaleCleanupGateOwner(gatePath);
+  if (owner !== null && isProcessAlive(owner.pid) && gateAgeMs <= STALE_CLEANUP_GATE_MAX_ACTIVE_MS) {
+    return false;
+  }
+  return removeStaleCleanupGateDirectory(gatePath);
+}
+async function acquireStaleCleanupGate(lockPath, _id) {
+  const gatePath = `${lockPath}${STALE_CLEANUP_GATE_SUFFIX}`;
+  const owner = await tryCreateStaleCleanupGate(gatePath);
+  if (owner !== null) {
+    return async () => releaseStaleCleanupGate(gatePath, owner.token);
+  }
+  if (!await removeExpiredStaleCleanupGate(gatePath)) {
+    return null;
+  }
+  const recoveredOwner = await tryCreateStaleCleanupGate(gatePath);
+  if (recoveredOwner === null) {
+    return null;
+  }
+  return async () => releaseStaleCleanupGate(gatePath, recoveredOwner.token);
+}
+async function removeConfirmedStaleLock(params) {
+  const releaseCleanupGate = await acquireStaleCleanupGate(params.lockPath, params.id);
+  if (releaseCleanupGate === null) {
+    return {
+      lockInfo: params.fallbackLockInfo,
+      shouldRetryCreate: false,
+      staleRemovalCounted: false
+    };
+  }
+  try {
+    const currentLockInfo = await readLockInfo(params.lockPath);
+    if (currentLockInfo.info === null && currentLockInfo.warnings.length === 0) {
+      return {
+        lockInfo: currentLockInfo,
+        shouldRetryCreate: true,
+        staleRemovalCounted: false
+      };
+    }
+    if (!isStaleLock(currentLockInfo.info, params.ttlSeconds)) {
+      return {
+        lockInfo: currentLockInfo,
+        shouldRetryCreate: false,
+        staleRemovalCounted: false
+      };
+    }
+    throwIfStaleLockNeedsForce(params.id, currentLockInfo, params.force, params.forceRequiredForStaleLock);
+    if (params.staleRemovals >= MAX_STALE_LOCK_REMOVALS) {
+      throw buildLockConflictError(params.id, currentLockInfo.info, Date.now() - params.startedAtMs);
+    }
+    return {
+      lockInfo: currentLockInfo,
+      shouldRetryCreate: await unlinkLockWithHook(params.lockPath, "lock:stale_remove"),
+      staleRemovalCounted: true
+    };
+  } finally {
+    await releaseCleanupGate();
+  }
+}
+async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRequiredForStaleLock = true, waitMs) {
   const lockOverride = await runActiveServiceOverride("lock_acquire", {
     pm_root: pmRoot,
     id,
@@ -581,9 +782,7 @@ async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRe
     force_required_for_stale_lock: forceRequiredForStaleLock
   });
   if (lockOverride.handled) {
-    const releaseFromFunction = typeof lockOverride.result === "function" ? lockOverride.result : null;
-    const releaseFromObject = typeof lockOverride.result === "object" && lockOverride.result !== null && "release" in lockOverride.result && typeof lockOverride.result.release === "function" ? lockOverride.result.release : null;
-    const release = releaseFromFunction ?? releaseFromObject;
+    const release = resolveLockOverrideRelease(lockOverride.result);
     if (release) {
       return async () => {
         await Promise.resolve(release());
@@ -596,7 +795,11 @@ async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRe
     }
   }
   const lockPath = getLockPath(pmRoot, id);
-  for (let attempt = 0; attempt < 3; attempt += 1) {
+  const waitBudgetMs = resolveLockWaitMs(waitMs);
+  const startedAtMs = Date.now();
+  let staleRemovals = 0;
+  let backoffMs = LOCK_WAIT_INITIAL_DELAY_MS;
+  for (; ; ) {
     try {
       await createLockFile(lockPath, id, owner, ttlSeconds);
       return async () => {
@@ -611,74 +814,40 @@ async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRe
       if (!isErrno(error, "EEXIST")) {
         throw new PmCliError(`Failed to acquire lock for ${id}: ${toErrorMessage(error)}`, EXIT_CODE.GENERIC_FAILURE);
       }
-      await handleExistingLock(lockPath, id, ttlSeconds, force, forceRequiredForStaleLock);
-    }
-  }
-  throw new PmCliError(`Failed to acquire lock for ${id}`, EXIT_CODE.CONFLICT);
-}
-
-// dist/core/item/id.js
-import crypto from "node:crypto";
-import path3 from "node:path";
-function normalizePrefix(input) {
-  const normalized = (input ?? "").trim().toLowerCase();
-  if (!normalized)
-    return "pm-";
-  return normalized.endsWith("-") ? normalized : `${normalized}-`;
-}
-function normalizeRawItemId(input) {
-  let normalized = input.trim().toLowerCase();
-  if (normalized.startsWith("#")) {
-    normalized = normalized.slice(1);
-  }
-  return normalized;
-}
-function normalizeItemId(input, prefix) {
-  const canonicalPrefix = normalizePrefix(prefix);
-  const normalized = normalizeRawItemId(input);
-  if (normalized.startsWith(canonicalPrefix)) {
-    return normalized;
-  }
-  return `${canonicalPrefix}${normalized}`;
-}
-function randomToken(length) {
-  let token = "";
-  for (let index = 0; index < length; index += 1) {
-    token += crypto.randomInt(0, 36).toString(36);
-  }
-  return token;
-}
-async function idExists(pmRoot, id) {
-  const checks = Object.values(TYPE_TO_FOLDER).flatMap((folder) => [
-    path3.join(pmRoot, folder, `${id}.md`),
-    path3.join(pmRoot, folder, `${id}.toon`)
-  ]);
-  for (const target of checks) {
-    if (await pathExists(target)) {
-      return true;
-    }
-  }
-  return false;
-}
-async function generateItemId(pmRoot, prefix) {
-  let tokenLength = 4;
-  let attempts = 0;
-  while (tokenLength <= 10) {
-    for (let i = 0; i < 32; i += 1) {
-      const id = `${normalizePrefix(prefix)}${randomToken(tokenLength)}`;
-      if (!await idExists(pmRoot, id)) {
-        return id;
+      let lockInfo = await readLockInfo(lockPath);
+      if (isStaleLock(lockInfo.info, ttlSeconds)) {
+        const staleRemoval = await removeConfirmedStaleLock({
+          lockPath,
+          id,
+          ttlSeconds,
+          force,
+          forceRequiredForStaleLock,
+          staleRemovals,
+          waitBudgetMs,
+          startedAtMs,
+          fallbackLockInfo: lockInfo
+        });
+        lockInfo = staleRemoval.lockInfo;
+        if (staleRemoval.staleRemovalCounted) {
+          staleRemovals += 1;
+        }
+        if (staleRemoval.shouldRetryCreate) {
+          continue;
+        }
       }
-      attempts += 1;
+      const elapsedMs = Date.now() - startedAtMs;
+      if (waitBudgetMs === 0 || elapsedMs >= waitBudgetMs) {
+        throw buildLockConflictError(id, lockInfo.info, waitBudgetMs === 0 ? 0 : elapsedMs);
+      }
+      await sleepWithJitter(Math.min(backoffMs, waitBudgetMs - elapsedMs));
+      backoffMs = Math.min(backoffMs * 2, LOCK_WAIT_MAX_DELAY_MS);
     }
-    tokenLength += 1;
   }
-  throw new Error(`Unable to generate unique id after ${attempts} attempts`);
 }
 
 // dist/core/store/front-matter-cache.js
 import fs3 from "node:fs/promises";
-import path4 from "node:path";
+import path3 from "node:path";
 import { createHash } from "node:crypto";
 var CACHE_VERSION = 6;
 var CACHE_FILENAME = "metadata-cache.json";
@@ -727,13 +896,13 @@ function computeContextFingerprint(preferredFormat, typeToFolder, schema, extens
   return hash.digest("hex").slice(0, 16);
 }
 function getCachePath(pmRoot) {
-  return path4.join(pmRoot, "runtime", CACHE_FILENAME);
+  return path3.join(pmRoot, "runtime", CACHE_FILENAME);
 }
 function getBodyCachePath(pmRoot) {
-  return path4.join(pmRoot, "runtime", BODY_CACHE_FILENAME);
+  return path3.join(pmRoot, "runtime", BODY_CACHE_FILENAME);
 }
 function getCollectionsCachePath(pmRoot) {
-  return path4.join(pmRoot, "runtime", COLLECTIONS_CACHE_FILENAME);
+  return path3.join(pmRoot, "runtime", COLLECTIONS_CACHE_FILENAME);
 }
 var ENVELOPE_MEMO_MAX_ENTRIES = 24;
 var envelopeMemo = /* @__PURE__ */ new Map();
@@ -797,7 +966,7 @@ async function loadCollectionsCache(pmRoot) {
   });
 }
 async function persistCache(cachePath, envelope) {
-  await fs3.mkdir(path4.dirname(cachePath), { recursive: true });
+  await fs3.mkdir(path3.dirname(cachePath), { recursive: true });
   await writeFileAtomic(cachePath, JSON.stringify(envelope));
   try {
     const stat = await fs3.stat(cachePath);
@@ -824,7 +993,7 @@ function statMatches(signature, mtimeMs, ctimeMs, size) {
   return signature.mtime_ms === mtimeMs && signature.ctime_ms === ctimeMs && signature.size === size;
 }
 async function readItemDirectoryFiles(pmRoot, folder, warnings) {
-  const dirPath = path4.join(pmRoot, folder);
+  const dirPath = path3.join(pmRoot, folder);
   try {
     const files = await fs3.readdir(dirPath);
     return { folder, dirPath, files };
@@ -944,7 +1113,7 @@ async function processCachedDocumentFile(folder, filePath, relativePath, context
     const parts = await readCachedDocumentParts(filePath, relativePath, context);
     recordCachedDocumentCandidate(filePath, relativePath, context, parts);
   } catch {
-    appendWarning(context.warnings, `item_list_item_read_failed:${folder}/${path4.basename(filePath)}`);
+    appendWarning(context.warnings, `item_list_item_read_failed:${folder}/${path3.basename(filePath)}`);
   }
 }
 function selectPreviousMetadataEntries(existingCache, contextFingerprint) {
@@ -976,8 +1145,8 @@ function collectCachedDocumentParseTasks(dirResults, context) {
       if (!isItemDocumentFile(file)) {
         continue;
       }
-      const filePath = path4.join(dirPath, file);
-      const relativePath = path4.relative(context.pmRoot, filePath);
+      const filePath = path3.join(dirPath, file);
+      const relativePath = path3.relative(context.pmRoot, filePath);
       parseTasks.push(processCachedDocumentFile(folder, filePath, relativePath, context));
     }
   }
@@ -1083,7 +1252,7 @@ async function listAllDocumentsCachedLight(pmRoot, preferredFormat, typeToFolder
 
 // dist/core/store/item-store.js
 import fs4 from "node:fs/promises";
-import path5 from "node:path";
+import path4 from "node:path";
 async function fileExists(targetPath) {
   try {
     await fs4.access(targetPath);
@@ -1170,7 +1339,7 @@ async function listKnownItemIds(pmRoot, typeToFolder) {
   const allIds = [];
   await Promise.all([...folders].map(async (folder) => {
     try {
-      const entries = await fs4.readdir(path5.join(pmRoot, folder));
+      const entries = await fs4.readdir(path4.join(pmRoot, folder));
       for (const entry of entries) {
         for (const ext of ITEM_FILE_EXTENSIONS) {
           if (entry.toLowerCase().endsWith(ext)) {
@@ -1210,7 +1379,7 @@ async function prepareLockedItem(params) {
   if (!located) {
     throw await buildItemNotFoundError(params.pmRoot, params.id, params.settings.id_prefix, typeToFolder);
   }
-  const releaseLock = await acquireLock(params.pmRoot, located.id, params.settings.locks.ttl_seconds, params.author, Boolean(params.force), params.settings.governance.force_required_for_stale_lock);
+  const releaseLock = await acquireLock(params.pmRoot, located.id, params.settings.locks.ttl_seconds, params.author, Boolean(params.force), params.settings.governance.force_required_for_stale_lock, params.settings.locks.wait_ms);
   try {
     const warnings = [];
     const { raw: originalRaw, document } = await readLocatedItem(located, {
@@ -1519,10 +1688,6 @@ export {
   enforceHistoryStreamPolicyForItem,
   enforceHistoryStreamPolicyForItems,
   acquireLock,
-  normalizePrefix,
-  normalizeRawItemId,
-  normalizeItemId,
-  generateItemId,
   HEAVY_METADATA_KEYS,
   listAllDocumentCandidatesCached,
   locateItem,
@@ -1534,6 +1699,6 @@ export {
   mutateItem,
   deleteItem
 };
-//# sourceMappingURL=chunk-4WB6S4YX.js.map
+//# sourceMappingURL=chunk-57C2RLW5.js.map
 
-//# debugId=c1ba30e7-4db1-564b-a399-af5da0c99b7e
+//# debugId=c9a5ce7b-7b83-549d-bddc-c6f8ce8564b8