omni-dsh-plugins 1.0.1 → 1.0.3

package/README.md

@@ -22,7 +22,7 @@ never ships here.
 - Node.js 20 or newer.
 - The official `dsh` executable on `PATH` for add, update and remove operations.
 - Network access for discovery. With no `--catalog`, the CLI reads the snapshot published at
-  <https://dsh-plugins.omniroute.online/catalog.snapshot.json> and accepts the revision that
+  <https://dsh-plugins.omniskill.online/catalog.snapshot.json> and accepts the revision that
   snapshot declares, so a plugin merged today is findable today. Passing `--revision` turns the
   fetch into an exact-commit demand and rejects any snapshot declaring a different one.
 
@@ -136,7 +136,7 @@ granting `--allow-code-execution`.
 
 `--catalog` accepts a local catalog directory, a local
 `omni-dsh-catalog-snapshot-v1` JSON file, or one of two allowlisted HTTPS URLs: the stable
-site-hosted snapshot `https://dsh-plugins.omniroute.online/catalog.snapshot.json` (the
+site-hosted snapshot `https://dsh-plugins.omniskill.online/catalog.snapshot.json` (the
 operational remote source) or the raw GitHub form embedding the revision in its path.
 Remote snapshots require `--revision <40-character-commit-sha>` and the snapshot document must
 declare exactly that SHA. Redirects, alternate hosts, traversal, symlinks, oversized inputs,
@@ -144,6 +144,21 @@ and revision mismatches are rejected before catalog validation.
 
 ```bash
 npx omni-dsh-plugins search tui \
-  --catalog https://dsh-plugins.omniroute.online/catalog.snapshot.json \
+  --catalog https://dsh-plugins.omniskill.online/catalog.snapshot.json \
   --revision <published-catalog-revision>
 ```
+
+## Releasing (maintainers)
+
+Releases are tag-driven and fail closed. The npm artifact is built from the tagged commit —
+never from a branch tip:
+
+1. Land the release commit (with the final `cli/package.json` version) on `main` through a
+   reviewed pull request.
+2. Tag that commit `cli-v<version>` (the version must equal `cli/package.json` of the tagged
+   commit) and push the tag. The push triggers `.github/workflows/release-npm.yml`, which
+   verifies the tag/version match, verifies the commit is an ancestor of `main`, runs tests,
+   checks the exact tarball manifest, smoke-runs the packed binary, and publishes with npm
+   provenance.
+3. `workflow_dispatch` exists only as a re-run fallback: it refuses to publish unless the
+   `cli-v<version>` tag already exists and points at exactly the commit checked out by the run.

package/dist/bin.js

@@ -22989,6 +22989,70 @@ var import_semver = __toESM(require_semver2(), 1);
 var import_spdx_expression_parse = __toESM(require_spdx_expression_parse(), 1);
 var import_ssri = __toESM(require_lib(), 1);
 var import_yaml = __toESM(require_dist2(), 1);
+var MAX_MEDIA_ITEMS = 6;
+var MAX_MEDIA_ALT_LENGTH = 120;
+var REPOSITORY_URL = /^https:\/\/github\.com\/([^/]+)\/([^/]+)$/u;
+var RAW_URL = /^https:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)(\/.*)$/u;
+var ASSET_URL = /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/assets(\/.*)$/u;
+var MEDIA_PATH = /^(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._@+-]+)+$/u;
+function repositorySlug(repository) {
+  const match = REPOSITORY_URL.exec(String(repository ?? ""));
+  return match === null ? null : { owner: match[1], repo: match[2] };
+}
+function classifyMediaUrl(url, kind, slug, commit) {
+  const raw = RAW_URL.exec(url);
+  if (raw !== null) {
+    if (!MEDIA_PATH.test(raw[4])) return "unusable";
+    if (commit === "" || raw[3] !== commit) return "not-pinned";
+    return slug !== null && raw[1] === slug.owner && raw[2] === slug.repo ? "ok" : "wrong-repository";
+  }
+  const asset = kind === "video" ? ASSET_URL.exec(url) : null;
+  if (asset !== null) {
+    if (!MEDIA_PATH.test(asset[3])) return "unusable";
+    return slug !== null && asset[1] === slug.owner && asset[2] === slug.repo ? "ok" : "wrong-repository";
+  }
+  return "unusable";
+}
+function validateMediaField(media, source) {
+  if (media === void 0) {
+    return [];
+  }
+  if (!Array.isArray(media)) {
+    return ["media must be an array"];
+  }
+  if (media.length === 0) {
+    return ["media must not be an empty list"];
+  }
+  const errors = [];
+  if (media.length > MAX_MEDIA_ITEMS) {
+    errors.push(`media has more than ${MAX_MEDIA_ITEMS} items`);
+  }
+  const slug = repositorySlug(source.repository);
+  const commit = String(source.commit ?? "");
+  media.forEach((item, index) => {
+    const value = typeof item === "object" && item !== null ? item : {};
+    if (value.kind !== "screenshot" && value.kind !== "video") {
+      errors.push(`media[${index}].kind must be "screenshot" or "video"`);
+    }
+    if (typeof value.alt !== "string" || value.alt.trim() === "" || value.alt.length > MAX_MEDIA_ALT_LENGTH) {
+      errors.push(`media[${index}].alt must be 1-${MAX_MEDIA_ALT_LENGTH} characters`);
+    }
+    const url = typeof value.url === "string" ? value.url : "";
+    switch (classifyMediaUrl(url, value.kind, slug, commit)) {
+      case "ok":
+        return;
+      case "not-pinned":
+        errors.push(`media[${index}].url must pin the entry commit, not a branch`);
+        return;
+      case "wrong-repository":
+        errors.push(`media[${index}].url must reference the entry's own repository`);
+        return;
+      default:
+        errors.push(`media[${index}].url must be a GitHub URL pinned to the entry commit`);
+    }
+  });
+  return errors;
+}
 function parseSpdx(value) {
   try {
     return (0, import_spdx_expression_parse.default)(value);
@@ -23170,6 +23234,9 @@ function semanticIssues(entry) {
       }
     }
   }
+  for (const message of validateMediaField(entry.media, entry.source)) {
+    issues.push({ code: "invalid-media", message });
+  }
   if (entry.verification.smokeTest !== null) {
     try {
       parseExactSemver(entry.verification.smokeTest.check.version);
@@ -23251,6 +23318,9 @@ function isContained2(root, candidate) {
 function hasErrorCode(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
+function creatorSlug(creatorGithub) {
+  return creatorGithub.toLowerCase().replaceAll(/[^a-z0-9]+/gu, "-");
+}
 function safeEntryLabel(fileName) {
   const safeName = fileName.replaceAll(/[^A-Za-z0-9._-]/gu, "_");
   return `${ENTRY_DIRECTORY}/${safeName || "invalid-entry"}`;
@@ -23347,6 +23417,9 @@ async function loadCatalog(input) {
     entryDirectory = await containedRealPath(root, requestedEntryDirectory) ?? "";
   } catch (error) {
     if (hasErrorCode(error, "ENOENT")) {
+      if (normalized.source.kind === "snapshot") {
+        diagnostics.push(degenerateSnapshotDiagnostic());
+      }
       return snapshotResult(normalized.source, [], diagnostics);
     }
     diagnostics.push({
@@ -23430,6 +23503,28 @@ async function loadCatalog(input) {
       continue;
     }
     const entry = parsed;
+    const baseName = directoryEntry.name.slice(0, -".yaml".length);
+    let violatesIdConvention = false;
+    if (entry.id !== baseName) {
+      violatesIdConvention = true;
+      diagnostics.push({
+        file,
+        code: "id-filename-mismatch",
+        message: "public ID must equal the catalog file's basename"
+      });
+    }
+    const expectedPrefix = `${creatorSlug(entry.creator.github)}-`;
+    if (!entry.id.startsWith(expectedPrefix)) {
+      violatesIdConvention = true;
+      diagnostics.push({
+        file,
+        code: "id-creator-prefix",
+        message: `public ID must start with the creator slug prefix "${expectedPrefix}"`
+      });
+    }
+    if (violatesIdConvention) {
+      continue;
+    }
     try {
       candidates.push({
         canonicalKey: canonicalPluginKey(entry.source.repositoryNodeId, entry.source.subpath),
@@ -23462,8 +23557,18 @@ async function loadCatalog(input) {
     ...duplicateKeys.rejectedFiles
   ]);
   const entries = candidates.filter((candidate) => !rejectedFiles.has(candidate.file)).map((candidate) => candidate.entry).sort((left, right) => compareText2(left.id, right.id));
+  if (normalized.source.kind === "snapshot" && entries.length === 0 && diagnostics.length === 0) {
+    diagnostics.push(degenerateSnapshotDiagnostic());
+  }
   return snapshotResult(normalized.source, entries, diagnostics);
 }
+function degenerateSnapshotDiagnostic() {
+  return {
+    file: ENTRY_DIRECTORY,
+    code: "degenerate-snapshot",
+    message: "materialized snapshot contains no plugin entries; the published catalog is never empty, so this snapshot is broken or truncated"
+  };
+}
 
 // src/catalogSnapshot.ts
 import { constants } from "node:fs";
@@ -23669,17 +23774,17 @@ function sanitizedErrorMessage(error) {
 // src/catalogSnapshot.ts
 var CATALOG_SNAPSHOT_FORMAT_V1 = "omni-dsh-catalog-snapshot-v1";
 var PUBLIC_CATALOG_RAW_ORIGIN = "https://raw.githubusercontent.com/diegosouzapw/awesome-omni-dsh-plugins";
-var PUBLIC_SNAPSHOT_SITE_URL = "https://dsh-plugins.omniroute.online/catalog.snapshot.json";
+var PUBLIC_SNAPSHOT_SITE_URL = "https://dsh-plugins.omniskill.online/catalog.snapshot.json";
 var CATALOG_SNAPSHOT_LIMITS = Object.freeze({
-  snapshotBytes: 10 * 1024 * 1024,
-  totalFileBytes: 8 * 1024 * 1024,
+  snapshotBytes: 128 * 1024 * 1024,
+  totalFileBytes: 128 * 1024 * 1024,
   fileBytes: 1024 * 1024,
-  files: 2048,
-  directoryEntries: 4096,
+  files: 32768,
+  directoryEntries: 32768,
   pathBytes: 512,
   redirects: 3,
   gitOutputBytes: 64 * 1024,
-  gitTreeBytes: 2 * 1024 * 1024,
+  gitTreeBytes: 32 * 1024 * 1024,
   pathDepth: 16
 });
 var CATALOG_DEADLINE_DEFAULTS = Object.freeze({
@@ -24465,8 +24570,8 @@ async function materializeSelection(selection2, dependencies) {
 
 // src/commands/catalog.ts
 var import_yaml3 = __toESM(require_dist2(), 1);
-import { readFile as readFile3, realpath as realpath4 } from "node:fs/promises";
-import { isAbsolute as isAbsolute4, relative as relative4, resolve as resolve4, sep as sep4 } from "node:path";
+import { readdir as readdir2, readFile as readFile3, realpath as realpath4 } from "node:fs/promises";
+import { isAbsolute as isAbsolute4, join as join2, relative as relative4, resolve as resolve4, sep as sep4 } from "node:path";
 function sortedDiagnostics(diagnostics) {
   return [...diagnostics].sort(
     (left, right) => left.file.localeCompare(right.file) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message)
@@ -24560,6 +24665,64 @@ function hasBalancedMarkdownFences(content) {
   }
   return open4 === null;
 }
+var TRANSLATED_DOCUMENTS = [
+  "README.md",
+  "CONTRIBUTING.md",
+  "SECURITY.md",
+  "docs/SCHEMA.md",
+  "docs/CLI.md",
+  "docs/GOVERNANCE.md",
+  "docs/CATEGORIES.md",
+  "docs/CREDIT.md",
+  "docs/RANKING.md",
+  "docs/UNOFFICIAL.md"
+];
+var LOCALE_NAME = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$/u;
+function documentShape(content) {
+  const lines = content.split(/\r?\n/u);
+  return {
+    sections: lines.filter((line) => line.startsWith("## ")).length,
+    subsections: lines.filter((line) => line.startsWith("### ")).length,
+    rows: lines.filter((line) => line.startsWith("| ")).length
+  };
+}
+async function translationShapeDiagnostics(root) {
+  let locales;
+  try {
+    locales = (await readdir2(join2(root, "docs", "i18n"), { withFileTypes: true })).filter((entry) => entry.isDirectory() && LOCALE_NAME.test(entry.name)).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+  const diagnostics = [];
+  for (const document of TRANSLATED_DOCUMENTS) {
+    let english;
+    try {
+      english = documentShape(await readContained(root, document));
+    } catch {
+      continue;
+    }
+    for (const locale of locales) {
+      const file = `docs/i18n/${locale}/${document.split("/").at(-1)}`;
+      let translated;
+      try {
+        translated = documentShape(await readContained(root, file));
+      } catch {
+        continue;
+      }
+      const drift = ["sections", "subsections", "rows"].filter(
+        (part) => translated[part] !== english[part]
+      );
+      if (drift.length > 0) {
+        diagnostics.push({
+          file,
+          code: "docs",
+          message: `translation does not match the shape of ${document}: ` + drift.map((part) => `${part} ${translated[part]} != ${english[part]}`).join(", ")
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
 function tableValues(content, heading) {
   const start = content.indexOf(`## ${heading}`);
   if (start < 0) {
@@ -24585,7 +24748,7 @@ function schemaEnum(document, property) {
 function sameValues(left, right) {
   return [...left].sort().join("\0") === [...right].sort().join("\0");
 }
-async function docsCheckCommand(context, rootInput) {
+async function docsCheckCommand(context, rootInput, options = {}) {
   let root;
   try {
     root = await canonicalRoot(rootInput);
@@ -24624,6 +24787,7 @@ async function docsCheckCommand(context, rootInput) {
       diagnostics.push({ file, code: "docs", message: "unbalanced Markdown fence" });
     }
   }
+  diagnostics.push(...await translationShapeDiagnostics(root));
   try {
     const categories = contents.get("docs/CATEGORIES.md");
     const schema = (0, import_yaml3.parse)(await readContained(root, "schemas/plugin.schema.yaml"), {
@@ -24658,7 +24822,7 @@ async function docsCheckCommand(context, rootInput) {
   const snapshot = await context.loadCatalog({ root: rootInput });
   diagnostics.push(...snapshot.diagnostics);
   const readme = contents.get("README.md");
-  if (readme !== void 0 && !readme.includes(`**${snapshot.entries.length} plugins merged.**`)) {
+  if (options.skipCount !== true && readme !== void 0 && !readme.includes(`**${snapshot.entries.length} plugins merged.**`)) {
     diagnostics.push({
       file: "README.md",
       code: "docs",
@@ -24882,12 +25046,12 @@ async function openArtifactDeliveryChannel(lease, options) {
 // src/dsh/installState.ts
 import { randomUUID } from "node:crypto";
 import { homedir, hostname as localHostname } from "node:os";
-import { join as join3, resolve as resolve6 } from "node:path";
-import { lstat as lstat4, mkdir as mkdir3, readFile as readFile4, readdir as readdir2, realpath as realpath6, rename, rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join4, resolve as resolve6 } from "node:path";
+import { lstat as lstat4, mkdir as mkdir3, readFile as readFile4, readdir as readdir3, realpath as realpath6, rename, rm as rm2, writeFile as writeFile2 } from "node:fs/promises";
 
 // src/dsh/paths.ts
 import { lstat as lstat3, mkdir as mkdir2, realpath as realpath5 } from "node:fs/promises";
-import { isAbsolute as isAbsolute5, join as join2, relative as relative5, resolve as resolve5, sep as sep5 } from "node:path";
+import { isAbsolute as isAbsolute5, join as join3, relative as relative5, resolve as resolve5, sep as sep5 } from "node:path";
 var SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 function isPathWithin(root, candidate) {
   const child = relative5(root, candidate);
@@ -24916,7 +25080,7 @@ async function ensureContainedDirectory(canonicalRoot2, ...segments) {
   let current = canonicalRoot2;
   for (const segment of segments) {
     assertSafeCacheSegment(segment, "managed path segment");
-    const candidate = join2(current, segment);
+    const candidate = join3(current, segment);
     if (!isPathWithin(canonicalRoot2, candidate)) {
       throw new CliSafetyError("managed path escapes its root");
     }
@@ -25060,7 +25224,7 @@ function parseRecoveryMarker(value) {
 }
 function resolveDshHome(env = process.env) {
   const configured = env.DSH_HOME?.trim();
-  return resolve6(configured === void 0 || configured === "" ? join3(homedir(), ".dsh") : configured);
+  return resolve6(configured === void 0 || configured === "" ? join4(homedir(), ".dsh") : configured);
 }
 function safeRelativeCachePath(value) {
   const segments = value.split("/");
@@ -25138,7 +25302,7 @@ async function readInstallState(home) {
     }
     throw error;
   }
-  const statePath = join3(canonicalHome, ".dsh-plugins", "state.json");
+  const statePath = join4(canonicalHome, ".dsh-plugins", "state.json");
   try {
     const info = await lstat4(statePath);
     if (info.isSymbolicLink() || !info.isFile()) {
@@ -25207,7 +25371,7 @@ async function readStateWriterOwner(lockPath) {
     if (info.isSymbolicLink() || !info.isDirectory()) {
       throw new CliSafetyError("install state publication lock path is unsafe");
     }
-    const source = await readFile4(join3(lockPath, "owner.json"), "utf8");
+    const source = await readFile4(join4(lockPath, "owner.json"), "utf8");
     if (source.length > 4096) throw new Error("oversized-owner");
     const value = JSON.parse(source);
     if (value.version !== 1 || typeof value.ownerToken !== "string" || !SAFE_WRITER_TOKEN.test(value.ownerToken) || !Number.isSafeInteger(value.fencingToken) || (value.fencingToken ?? 0) < 0 || !Number.isFinite(value.acquiredAt) || !Number.isFinite(value.leaseMs) || (value.leaseMs ?? 0) <= 0 || !Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0 || typeof value.processStartIdentity !== "string" || !SAFE_PROCESS_IDENTITY.test(value.processStartIdentity) || typeof value.hostname !== "string" || value.hostname.length === 0 || value.hostname.length > 255) {
@@ -25248,7 +25412,7 @@ async function writeStateWriterFence(path, value) {
   }
 }
 async function writeStateWriterOwner(lockPath, owner) {
-  const temporary = join3(lockPath, `.owner-${randomUUID()}.tmp`);
+  const temporary = join4(lockPath, `.owner-${randomUUID()}.tmp`);
   try {
     await writeFile2(temporary, `${JSON.stringify(owner)}
 `, {
@@ -25256,7 +25420,7 @@ async function writeStateWriterOwner(lockPath, owner) {
       mode: 384,
       flag: "wx"
     });
-    await rename(temporary, join3(lockPath, "owner.json"));
+    await rename(temporary, join4(lockPath, "owner.json"));
   } catch {
     await rm2(temporary, { force: true }).catch(() => void 0);
     throw new CliSafetyError("install state publication lock metadata could not be published");
@@ -25266,7 +25430,7 @@ async function latestStateWriterHeartbeat(lockPath, owner) {
   let latest = owner.acquiredAt;
   const prefix = `heartbeat-${owner.ownerToken}-`;
   try {
-    for (const entry of await readdir2(lockPath, { withFileTypes: true })) {
+    for (const entry of await readdir3(lockPath, { withFileTypes: true })) {
       if (!entry.isDirectory() || !entry.name.startsWith(prefix)) continue;
       const timestamp = Number(entry.name.slice(prefix.length));
       if (Number.isFinite(timestamp)) latest = Math.max(latest, timestamp);
@@ -25304,15 +25468,15 @@ async function acquireStateWriter(stateDirectory, options = {}) {
   if (!Number.isSafeInteger(pid) || pid <= 0 || !SAFE_PROCESS_IDENTITY.test(processStartIdentity) || hostname.length === 0 || hostname.length > 255) {
     throw new CliSafetyError("install state writer identity is invalid");
   }
-  const lockPath = join3(stateDirectory, ".state-write.lock");
-  const fencePath = join3(stateDirectory, ".state-write.fence.json");
+  const lockPath = join4(stateDirectory, ".state-write.lock");
+  const fencePath = join4(stateDirectory, ".state-write.fence.json");
   const startedAt = now();
   while (true) {
     const ownerToken = makeOwnerToken();
     if (!SAFE_WRITER_TOKEN.test(ownerToken)) {
       throw new CliSafetyError("install state writer owner token is invalid");
     }
-    const candidate = join3(stateDirectory, `.state-write.claim-${randomUUID()}`);
+    const candidate = join4(stateDirectory, `.state-write.claim-${randomUUID()}`);
     const provisionalOwner = {
       version: 1,
       ownerToken,
@@ -25327,7 +25491,7 @@ async function acquireStateWriter(stateDirectory, options = {}) {
     let fencingToken = 0;
     try {
       await mkdir3(candidate, { mode: 448 });
-      await writeFile2(join3(candidate, "owner.json"), `${JSON.stringify(provisionalOwner)}
+      await writeFile2(join4(candidate, "owner.json"), `${JSON.stringify(provisionalOwner)}
 `, {
         encoding: "utf8",
         mode: 384,
@@ -25341,7 +25505,7 @@ async function acquireStateWriter(stateDirectory, options = {}) {
     } catch (error) {
       await rm2(candidate, { recursive: true, force: true }).catch(() => void 0);
       if (claimed) {
-        const failedPath = join3(stateDirectory, `.state-write.failed-${randomUUID()}`);
+        const failedPath = join4(stateDirectory, `.state-write.failed-${randomUUID()}`);
         try {
           const current2 = await readStateWriterOwner(lockPath);
           if (current2?.ownerToken === ownerToken) {
@@ -25373,7 +25537,7 @@ async function acquireStateWriter(stateDirectory, options = {}) {
         if (leaseExpired && ownerProvenDead) {
           const confirmed = await readStateWriterOwner(lockPath);
           if (confirmed?.ownerToken === current.ownerToken && confirmed.fencingToken === current.fencingToken && now() - await latestStateWriterHeartbeat(lockPath, confirmed) > confirmed.leaseMs) {
-            const stalePath = join3(stateDirectory, `.state-write.stale-${randomUUID()}`);
+            const stalePath = join4(stateDirectory, `.state-write.stale-${randomUUID()}`);
             try {
               await rename(lockPath, stalePath);
               const detached = await readStateWriterOwner(stalePath);
@@ -25410,7 +25574,7 @@ async function acquireStateWriter(stateDirectory, options = {}) {
     const heartbeat = async () => {
       await assertOwned();
       try {
-        await mkdir3(join3(lockPath, `heartbeat-${ownerToken}-${now()}`), { mode: 448 });
+        await mkdir3(join4(lockPath, `heartbeat-${ownerToken}-${now()}`), { mode: 448 });
       } catch (error) {
         if (stateWriterErrorCode(error) !== "EEXIST") {
           lost = true;
@@ -25432,7 +25596,7 @@ async function acquireStateWriter(stateDirectory, options = {}) {
       if (current === null || current.ownerToken !== ownerToken || current.fencingToken !== fencingToken || current.processStartIdentity !== processStartIdentity) {
         return;
       }
-      const releasePath = join3(stateDirectory, `.state-write.release-${ownerToken}`);
+      const releasePath = join4(stateDirectory, `.state-write.release-${ownerToken}`);
       try {
         await rename(lockPath, releasePath);
         const detached = await readStateWriterOwner(releasePath);
@@ -25459,8 +25623,8 @@ async function writeInstallState(home, state, options) {
   const canonicalHome = await ensureCanonicalHome(home);
   const stateDirectory = await ensureContainedDirectory(canonicalHome, ".dsh-plugins");
   const writer = await acquireStateWriter(stateDirectory, options?.writer);
-  const target = join3(stateDirectory, "state.json");
-  const temporary = join3(stateDirectory, `.state-${randomUUID()}.tmp`);
+  const target = join4(stateDirectory, "state.json");
+  const temporary = join4(stateDirectory, `.state-${randomUUID()}.tmp`);
   try {
     const current = await readInstallState(canonicalHome);
     const currentGeneration = current.generation ?? 0;
@@ -25517,8 +25681,8 @@ async function writeInstallState(home, state, options) {
 // src/dsh/profileLock.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 import { hostname as localHostname2 } from "node:os";
-import { join as join4 } from "node:path";
-import { lstat as lstat5, mkdir as mkdir4, readFile as readFile5, readdir as readdir3, rename as rename2, rm as rm3, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join5 } from "node:path";
+import { lstat as lstat5, mkdir as mkdir4, readFile as readFile5, readdir as readdir4, rename as rename2, rm as rm3, writeFile as writeFile3 } from "node:fs/promises";
 var DEFAULT_LEASE_MS = 3e4;
 var DEFAULT_HEARTBEAT_MS = 1e4;
 var DEFAULT_ACQUIRE_TIMEOUT_MS = 3e4;
@@ -25560,7 +25724,7 @@ async function readOwner(lockPath) {
     if (info.isSymbolicLink() || !info.isDirectory()) {
       throw new CliSafetyError("profile mutation lock path is unsafe");
     }
-    const source = await readFile5(join4(lockPath, "owner.json"), "utf8");
+    const source = await readFile5(join5(lockPath, "owner.json"), "utf8");
     if (source.length > 4096) throw new Error("oversized-owner");
     const value = JSON.parse(source);
     if (value.version !== 1 || typeof value.ownerToken !== "string" || !SAFE_TOKEN.test(value.ownerToken) || !Number.isSafeInteger(value.fencingToken) || (value.fencingToken ?? 0) < 0 || typeof value.profile !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value.profile) || !Number.isFinite(value.acquiredAt) || !Number.isFinite(value.leaseMs) || !Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0 || typeof value.hostname !== "string" || value.hostname.length === 0 || value.hostname.length > 255) {
@@ -25574,7 +25738,7 @@ async function readOwner(lockPath) {
   }
 }
 async function writeOwner(lockPath, owner) {
-  const temporary = join4(lockPath, `.owner-${randomUUID2()}.tmp`);
+  const temporary = join5(lockPath, `.owner-${randomUUID2()}.tmp`);
   try {
     await writeFile3(temporary, `${JSON.stringify(owner)}
 `, {
@@ -25582,7 +25746,7 @@ async function writeOwner(lockPath, owner) {
       mode: 384,
       flag: "wx"
     });
-    await rename2(temporary, join4(lockPath, "owner.json"));
+    await rename2(temporary, join5(lockPath, "owner.json"));
   } catch {
     await rm3(temporary, { force: true }).catch(() => void 0);
     throw new CliSafetyError("profile mutation lock metadata could not be published");
@@ -25618,11 +25782,11 @@ async function writeFence(path, value) {
 async function readLegacyFenceMaximum(lockDirectory) {
   let maximum = 0;
   try {
-    for (const entry of await readdir3(lockDirectory, { withFileTypes: true })) {
+    for (const entry of await readdir4(lockDirectory, { withFileTypes: true })) {
       if (!entry.isFile() || !/^[a-z0-9]+(?:-[a-z0-9]+)*\.fence\.json$/u.test(entry.name)) {
         continue;
       }
-      maximum = Math.max(maximum, await readFence(join4(lockDirectory, entry.name)));
+      maximum = Math.max(maximum, await readFence(join5(lockDirectory, entry.name)));
     }
   } catch (error) {
     if (errorCode(error) !== "ENOENT") {
@@ -25635,7 +25799,7 @@ async function latestHeartbeat(lockPath, owner) {
   let latest = owner.acquiredAt;
   const prefix = `heartbeat-${owner.ownerToken}-`;
   try {
-    for (const entry of await readdir3(lockPath, { withFileTypes: true })) {
+    for (const entry of await readdir4(lockPath, { withFileTypes: true })) {
       if (!entry.isDirectory() || !entry.name.startsWith(prefix)) continue;
       const timestamp = Number(entry.name.slice(prefix.length));
       if (Number.isFinite(timestamp)) latest = Math.max(latest, timestamp);
@@ -25668,8 +25832,8 @@ async function acquireProfileLock(home, profile, options = {}) {
   const isProcessAlive = options.isProcessAlive ?? processAlive;
   const canonicalHome = await ensureCanonicalHome(home);
   const lockDirectory = await ensureContainedDirectory(canonicalHome, ".dsh-plugins", "locks");
-  const lockPath = join4(lockDirectory, "mutation.lock");
-  const fencePath = join4(lockDirectory, "mutation.fence.json");
+  const lockPath = join5(lockDirectory, "mutation.lock");
+  const fencePath = join5(lockDirectory, "mutation.fence.json");
   const startedAt = now();
   while (true) {
     const ownerToken = makeOwnerToken();
@@ -25677,7 +25841,7 @@ async function acquireProfileLock(home, profile, options = {}) {
       throw new CliSafetyError("profile mutation owner token is invalid");
     }
     let fencingToken = 0;
-    const candidate = join4(lockDirectory, `.mutation.claim-${randomUUID2()}`);
+    const candidate = join5(lockDirectory, `.mutation.claim-${randomUUID2()}`);
     const provisionalRecord = {
       version: 1,
       ownerToken,
@@ -25691,7 +25855,7 @@ async function acquireProfileLock(home, profile, options = {}) {
     let claimed = false;
     try {
       await mkdir4(candidate, { mode: 448 });
-      await writeFile3(join4(candidate, "owner.json"), `${JSON.stringify(provisionalRecord)}
+      await writeFile3(join5(candidate, "owner.json"), `${JSON.stringify(provisionalRecord)}
 `, {
         encoding: "utf8",
         mode: 384,
@@ -25708,7 +25872,7 @@ async function acquireProfileLock(home, profile, options = {}) {
     } catch (error) {
       await rm3(candidate, { recursive: true, force: true }).catch(() => void 0);
       if (claimed) {
-        const failedPath = join4(lockDirectory, `.mutation.failed-${randomUUID2()}`);
+        const failedPath = join5(lockDirectory, `.mutation.failed-${randomUUID2()}`);
         try {
           const current2 = await readOwner(lockPath);
           if (current2?.ownerToken === ownerToken) {
@@ -25727,7 +25891,7 @@ async function acquireProfileLock(home, profile, options = {}) {
         const leaseExpired = now() - await latestHeartbeat(lockPath, current) > current.leaseMs;
         const localOwnerAlive = current.hostname === hostname && isProcessAlive(current.pid);
         if (leaseExpired && !localOwnerAlive) {
-          const stalePath = join4(lockDirectory, `.mutation.stale-${randomUUID2()}`);
+          const stalePath = join5(lockDirectory, `.mutation.stale-${randomUUID2()}`);
           try {
             await rename2(lockPath, stalePath);
             await rm3(stalePath, { recursive: true, force: true });
@@ -25756,7 +25920,7 @@ async function acquireProfileLock(home, profile, options = {}) {
     const heartbeat = async () => {
       await assertOwned();
       try {
-        await mkdir4(join4(lockPath, `heartbeat-${ownerToken}-${now()}`), { mode: 448 });
+        await mkdir4(join5(lockPath, `heartbeat-${ownerToken}-${now()}`), { mode: 448 });
       } catch (error) {
         if (errorCode(error) !== "EEXIST") {
           lost = true;
@@ -25778,7 +25942,7 @@ async function acquireProfileLock(home, profile, options = {}) {
       if (current === null || current.ownerToken !== ownerToken || current.fencingToken !== fencingToken || current.profile !== profile) {
         return;
       }
-      const releasePath = join4(lockDirectory, `.mutation.release-${ownerToken}`);
+      const releasePath = join5(lockDirectory, `.mutation.release-${ownerToken}`);
       try {
         await rename2(lockPath, releasePath);
         const detached = await readOwner(releasePath);
@@ -25807,17 +25971,17 @@ async function acquireProfileLock(home, profile, options = {}) {
 
 // src/dsh/profileTransaction.ts
 import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
-import { join as join5 } from "node:path";
-import { cp, lstat as lstat6, readFile as readFile6, readdir as readdir4, rename as rename3, rm as rm4, writeFile as writeFile4 } from "node:fs/promises";
+import { join as join6 } from "node:path";
+import { cp, lstat as lstat6, readFile as readFile6, readdir as readdir5, rename as rename3, rm as rm4, writeFile as writeFile4 } from "node:fs/promises";
 async function profileFingerprint(root) {
   const hash = createHash2("sha512");
   let files = 0;
   let bytes = 0;
   const visit = async (directory, prefix) => {
-    const entries = await readdir4(directory, { withFileTypes: true });
+    const entries = await readdir5(directory, { withFileTypes: true });
     entries.sort((left, right) => Buffer.from(left.name).compare(Buffer.from(right.name)));
     for (const entry of entries) {
-      const path = join5(directory, entry.name);
+      const path = join6(directory, entry.name);
       const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
       const info = await lstat6(path);
       if (info.isSymbolicLink()) throw new CliSafetyError("profile backup contains a symlink");
@@ -25855,21 +26019,21 @@ async function activeExists(active) {
 async function recoverTransactions(profiles, active, profile, committedFencingToken, assertLockOwned) {
   const prefix = `.dsh-plugins-transaction-${profile}-`;
   const journals = [];
-  for (const entry of await readdir4(profiles, { withFileTypes: true })) {
+  for (const entry of await readdir5(profiles, { withFileTypes: true })) {
     if (!entry.isFile() || !entry.name.startsWith(prefix) || !entry.name.endsWith(".json")) continue;
     try {
-      const value = JSON.parse(await readFile6(join5(profiles, entry.name), "utf8"));
+      const value = JSON.parse(await readFile6(join6(profiles, entry.name), "utf8"));
       if (value.version !== 1 || value.profile !== profile || !Number.isSafeInteger(value.fencingToken) || typeof value.existed !== "boolean" || !value.backupName.startsWith(`.dsh-plugins-backup-${profile}-`) || value.backupName.includes("/") || value.backupName.includes("\\")) {
         throw new Error("invalid-journal");
       }
-      journals.push({ path: join5(profiles, entry.name), value });
+      journals.push({ path: join6(profiles, entry.name), value });
     } catch {
       throw new CliSafetyError("profile transaction journal requires manual recovery");
     }
   }
   journals.sort((left, right) => right.value.fencingToken - left.value.fencingToken);
   for (const journal of journals) {
-    const backup = join5(profiles, journal.value.backupName);
+    const backup = join6(profiles, journal.value.backupName);
     if (journal.value.fencingToken <= committedFencingToken) {
       await rm4(backup, { recursive: true, force: true }).catch(() => void 0);
       await rm4(journal.path, { force: true }).catch(() => void 0);
@@ -25894,7 +26058,7 @@ async function beginProfileTransaction(home, profile, options = {}) {
   await assertLockOwned();
   const canonicalHome = await ensureCanonicalHome(home);
   const profiles = await ensureContainedDirectory(canonicalHome, "profiles");
-  const active = join5(profiles, profile);
+  const active = join6(profiles, profile);
   await recoverTransactions(
     profiles,
     active,
@@ -25904,8 +26068,8 @@ async function beginProfileTransaction(home, profile, options = {}) {
   );
   const suffix = randomUUID3();
   const backupName = `.dsh-plugins-backup-${profile}-${suffix}`;
-  const backup = join5(profiles, backupName);
-  const journal = join5(profiles, `.dsh-plugins-transaction-${profile}-${suffix}.json`);
+  const backup = join6(profiles, backupName);
+  const journal = join6(profiles, `.dsh-plugins-transaction-${profile}-${suffix}.json`);
   const journalTemporary = `${journal}.tmp`;
   const existed = await activeExists(active);
   let backupFingerprint = null;
@@ -25983,9 +26147,9 @@ async function recoverProfileTransaction(home, reference, assertLockOwned) {
   }
   const canonicalHome = await ensureCanonicalHome(home);
   const profiles = await ensureContainedDirectory(canonicalHome, "profiles");
-  const journal = join5(canonicalHome, reference.journalRelativePath);
-  const backup = join5(canonicalHome, reference.backupRelativePath);
-  const active = join5(profiles, reference.profile);
+  const journal = join6(canonicalHome, reference.journalRelativePath);
+  const backup = join6(canonicalHome, reference.backupRelativePath);
+  const active = join6(profiles, reference.profile);
   const displaced = `${backup}.displaced`;
   let value;
   try {
@@ -26037,8 +26201,8 @@ async function finalizeProfileTransactionRecovery(home, reference, assertLockOwn
   assertSafeProfileName(reference.profile);
   const canonicalHome = await ensureCanonicalHome(home);
   await ensureContainedDirectory(canonicalHome, "profiles");
-  const journal = join5(canonicalHome, reference.journalRelativePath);
-  const backup = join5(canonicalHome, reference.backupRelativePath);
+  const journal = join6(canonicalHome, reference.journalRelativePath);
+  const backup = join6(canonicalHome, reference.backupRelativePath);
   await assertLockOwned();
   await rm4(backup, { recursive: true, force: true });
   await rm4(`${backup}.displaced`, { recursive: true, force: true });
@@ -26064,7 +26228,7 @@ import {
   rename as rename4,
   rm as rm5
 } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 var MutationRecoveryJournalDurabilityAmbiguousError = class extends CliSafetyError {
   possiblyPublished = true;
   constructor(operation) {
@@ -26131,8 +26295,8 @@ async function createPaths(home) {
   const recoveryRoot = await ensureContainedDirectory(canonicalHome, ".dsh-plugins", "recovery");
   return {
     recoveryRoot,
-    active: join6(recoveryRoot, "active"),
-    marker: join6(recoveryRoot, "active", "marker.json")
+    active: join7(recoveryRoot, "active"),
+    marker: join7(recoveryRoot, "active", "marker.json")
   };
 }
 async function existingPaths(home) {
@@ -26143,9 +26307,9 @@ async function existingPaths(home) {
     if (error.code === "ENOENT") return null;
     throw new CliSafetyError("mutation recovery journal could not be inspected safely");
   }
-  const dshPlugins = join6(canonicalHome, ".dsh-plugins");
-  const recoveryRoot = join6(dshPlugins, "recovery");
-  const active = join6(recoveryRoot, "active");
+  const dshPlugins = join7(canonicalHome, ".dsh-plugins");
+  const recoveryRoot = join7(dshPlugins, "recovery");
+  const active = join7(recoveryRoot, "active");
   try {
     for (const path of [dshPlugins, recoveryRoot, active]) {
       const info = await lstat7(path);
@@ -26158,7 +26322,7 @@ async function existingPaths(home) {
     if (error instanceof CliSafetyError) throw error;
     throw new CliSafetyError("mutation recovery journal could not be inspected safely");
   }
-  return { recoveryRoot, active, marker: join6(active, "marker.json") };
+  return { recoveryRoot, active, marker: join7(active, "marker.json") };
 }
 function safeRelative(value, prefix) {
   return typeof value === "string" && value.startsWith(prefix) && !value.includes("\\") && !value.includes("..") && !value.startsWith("/");
@@ -26198,7 +26362,7 @@ function parseJournal(value) {
   return record;
 }
 async function writeMarker(paths, value, dependencies = {}) {
-  const temporary = join6(paths.active, `.marker-${randomUUID4()}.tmp`);
+  const temporary = join7(paths.active, `.marker-${randomUUID4()}.tmp`);
   const handle = await open2(temporary, "wx", 384);
   try {
     await handle.writeFile(`${JSON.stringify(value)}
@@ -26270,7 +26434,7 @@ async function removeCompletedMutationRecoveryJournal(home, expected, dependenci
   if (current === null || current.revision !== expected.revision || current.ownerToken !== expected.ownerToken || current.fencingToken !== expected.fencingToken || current.phase !== "completed") {
     throw new CliSafetyError("durable recovery intent ownership changed; recovery required");
   }
-  const completed = join6(paths.recoveryRoot, `.completed-${randomUUID4()}`);
+  const completed = join7(paths.recoveryRoot, `.completed-${randomUUID4()}`);
   await dependencies.beforeRename?.();
   await rename4(paths.active, completed);
   try {
@@ -26707,14 +26871,14 @@ import {
   mkdtemp as mkdtemp2,
   open as open3,
   readlink,
-  readdir as readdir5,
+  readdir as readdir6,
   realpath as realpath8,
   rename as rename5,
   rm as rm6,
   writeFile as writeFile5
 } from "node:fs/promises";
 import { devNull } from "node:os";
-import { basename, dirname as dirname3, join as join7, relative as relative6, resolve as resolve7, sep as sep6 } from "node:path";
+import { basename, dirname as dirname3, join as join8, relative as relative6, resolve as resolve7, sep as sep6 } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { createGzip } from "node:zlib";
 var PACKAGE_NAME2 = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
@@ -27101,10 +27265,10 @@ async function createDeterministicSourceArchive(sourceRoot, pluginRoot, destinat
   try {
     await emit(tarHeader("package/", 0, 493, "directory"));
     const visit = async (directory, relativeDirectory) => {
-      const entries = await readdir5(directory, { withFileTypes: true });
+      const entries = await readdir6(directory, { withFileTypes: true });
       entries.sort((left, right) => Buffer.from(left.name).compare(Buffer.from(right.name)));
       for (const entry of entries) {
-        const candidate = join7(directory, entry.name);
+        const candidate = join8(directory, entry.name);
         const relativePath = relativeDirectory === "" ? entry.name : `${relativeDirectory}/${entry.name}`;
         const archivePath = `package/${relativePath}`;
         const info = await lstat8(candidate);
@@ -27160,8 +27324,8 @@ async function createDeterministicSourceArchive(sourceRoot, pluginRoot, destinat
 }
 async function createArtifactLease(cached, home, budgets) {
   const leasesRoot = await ensureContainedDirectory(home, ".dsh-plugins", "artifact-leases");
-  const leaseRoot = await mkdtemp2(join7(leasesRoot, ".lease-"));
-  const destination = join7(leaseRoot, "artifact.tgz");
+  const leaseRoot = await mkdtemp2(join8(leasesRoot, ".lease-"));
+  const destination = join8(leaseRoot, "artifact.tgz");
   let heldFd;
   try {
     const cache = cached[VERIFIED_CACHE];
@@ -27298,10 +27462,10 @@ async function inspectSourceTree(root, budgets) {
     if (before.isSymbolicLink() || !before.isDirectory()) {
       throw new CliSafetyError("source tree changed during verification");
     }
-    const entries = await readdir5(directory, { withFileTypes: true });
+    const entries = await readdir6(directory, { withFileTypes: true });
     entries.sort((left, right) => Buffer.from(left.name).compare(Buffer.from(right.name)));
     for (const entry of entries) {
-      const candidate = join7(directory, entry.name);
+      const candidate = join8(directory, entry.name);
       const relativePath = relative6(root, candidate).split(sep6).join("/");
       const candidateDepth = relativePath.split("/").length;
       assertTreeBudget(bytes, files, candidateDepth, budgets);
@@ -27359,9 +27523,9 @@ async function measureCheckout(root, budgets) {
   let files = 0;
   const visit = async (directory, depth) => {
     assertTreeBudget(bytes, files, depth, budgets);
-    const entries = await readdir5(directory, { withFileTypes: true });
+    const entries = await readdir6(directory, { withFileTypes: true });
     for (const entry of entries) {
-      const candidate = join7(directory, entry.name);
+      const candidate = join8(directory, entry.name);
       const candidateDepth = depth + 1;
       const info = await lstat8(candidate);
       if (info.isDirectory() && !info.isSymbolicLink()) {
@@ -27532,7 +27696,7 @@ async function stageNpm(entry, temporary, fetchImpl, budgets, signal) {
     throw new CliSafetyError("checksum verification failed");
   }
   const artifact = "artifact.tgz";
-  await writeFile5(join7(temporary, artifact), bytes, { mode: 384, flag: "wx" });
+  await writeFile5(join8(temporary, artifact), bytes, { mode: 384, flag: "wx" });
   return {
     packageName: entry.package.name,
     installRelativePath: artifact,
@@ -27545,7 +27709,7 @@ async function stageSource(entry, temporary, runProcess, budgets, signal) {
   }
   if (!SHA402.test(entry.source.commit)) throw new CliSafetyError("source commit pin is invalid");
   const subpath = safeSourceSubpath(entry.source.subpath);
-  const source = join7(temporary, "source");
+  const source = join8(temporary, "source");
   await mkdir6(source, { mode: 448 });
   await runGit2(runProcess, { args: ["init", "--quiet"], cwd: source }, budgets, signal);
   await runGit2(
@@ -27592,7 +27756,7 @@ async function stageSource(entry, temporary, runProcess, budgets, signal) {
   if (checkedCommit.toLowerCase() !== entry.source.commit.toLowerCase()) {
     throw new CliSafetyError("source checkout does not match the commit pin");
   }
-  await rm6(join7(source, ".git"), { recursive: true, force: true });
+  await rm6(join8(source, ".git"), { recursive: true, force: true });
   const tree = await inspectSourceTree(source, budgets);
   const pluginRoot = resolve7(source, subpath);
   const expectedRelativePath = subpath === "." ? "source" : `source/${subpath}`;
@@ -27615,7 +27779,7 @@ async function stageSource(entry, temporary, runProcess, budgets, signal) {
   let packageName;
   try {
     packageName = JSON.parse((await readRegularFile(
-      join7(canonicalPluginRoot, "package.json"),
+      join8(canonicalPluginRoot, "package.json"),
       budgets.metadataBytes,
       "source package manifest is unsafe"
     )).toString("utf8")).name;
@@ -27649,7 +27813,7 @@ async function readCached(finalRoot, id, hash, entry, budgets) {
       throw new CliSafetyError("staging cache key is invalid");
     }
     const metadata = JSON.parse((await readRegularFile(
-      join7(canonicalRoot2, "metadata.json"),
+      join8(canonicalRoot2, "metadata.json"),
       budgets.metadataBytes,
       "staging cache metadata is unsafe"
     )).toString("utf8"));
@@ -27690,7 +27854,7 @@ async function readCached(finalRoot, id, hash, entry, budgets) {
       if (metadata.artifact.kind !== "source" || metadata.artifact.commit !== entry.source.commit.toLowerCase() || metadata.installRelativePath !== expectedRelativePath) {
         throw new CliSafetyError("staging cache metadata is invalid");
       }
-      const sourceRoot = join7(canonicalRoot2, "source");
+      const sourceRoot = join8(canonicalRoot2, "source");
       const tree = await inspectSourceTree(sourceRoot, budgets);
       if (tree.digest !== metadata.artifact.treeSha512 || tree.bytes !== metadata.artifact.bytes || tree.files !== metadata.artifact.files) {
         throw new CliSafetyError("staging cache tree verification failed");
@@ -27700,7 +27864,7 @@ async function readCached(finalRoot, id, hash, entry, budgets) {
         throw new CliSafetyError("staging cache target is unsafe");
       }
       const packageInfo = JSON.parse((await readRegularFile(
-        join7(canonicalTarget, "package.json"),
+        join8(canonicalTarget, "package.json"),
         budgets.metadataBytes,
         "staging cache package manifest is unsafe"
       )).toString("utf8"));
@@ -27736,7 +27900,7 @@ async function readCached(finalRoot, id, hash, entry, budgets) {
   }
 }
 async function quarantineCache(finalRoot, idRoot, hash) {
-  const quarantine = join7(idRoot, `.quarantine-${hash}-${randomUUID5()}`);
+  const quarantine = join8(idRoot, `.quarantine-${hash}-${randomUUID5()}`);
   try {
     await rename5(finalRoot, quarantine);
   } catch (error) {
@@ -27752,7 +27916,7 @@ async function stageCatalogEntry(entry, options) {
   const budgets = stageBudgets(options.budgets);
   const home = await ensureCanonicalHome(options.dshHome);
   const idRoot = await ensureContainedDirectory(home, ".dsh-plugins", "cache", id);
-  const finalRoot = join7(idRoot, hash);
+  const finalRoot = join8(idRoot, hash);
   try {
     await lstat8(finalRoot);
     try {
@@ -27774,7 +27938,7 @@ async function stageCatalogEntry(entry, options) {
   if (options.offline === true) {
     throw new CliSafetyError("pinned artifact is not cached and offline mode forbids retrieval");
   }
-  const temporary = await mkdtemp2(join7(idRoot, ".stage-"));
+  const temporary = await mkdtemp2(join8(idRoot, ".stage-"));
   try {
     const staged = entry.package.ecosystem === "npm" ? await stageNpm(
       entry,
@@ -27795,7 +27959,7 @@ async function stageCatalogEntry(entry, options) {
       descriptorHash: hash,
       ...staged
     };
-    await writeFile5(join7(temporary, "metadata.json"), `${JSON.stringify(metadata)}
+    await writeFile5(join8(temporary, "metadata.json"), `${JSON.stringify(metadata)}
 `, {
       encoding: "utf8",
       mode: 384,
@@ -27823,7 +27987,7 @@ async function stageCatalogEntry(entry, options) {
     );
   } catch (error) {
     if (error instanceof GitProcessUnreapedError) {
-      const quarantine = join7(idRoot, `.unreaped-${hash}-${randomUUID5()}`);
+      const quarantine = join8(idRoot, `.unreaped-${hash}-${randomUUID5()}`);
       await rename5(temporary, quarantine).catch(() => void 0);
       throw error;
     }
@@ -29351,15 +29515,29 @@ function addMutationOptions(command) {
     "consent to DSH/pnpm lifecycle code (native Windows disabled; use WSL)"
   );
 }
+function parseManifestVersion(raw) {
+  const manifest = JSON.parse(raw);
+  const version = manifest.version;
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version)) {
+    throw new Error("the package manifest does not declare an exact version");
+  }
+  return version;
+}
 function publishedVersion() {
-  const manifest = JSON.parse(
-    readFileSync(new URL("../package.json", import.meta.url), "utf8")
-  );
-  return manifest.version;
+  return parseManifestVersion(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 }
 async function runCli(argv, dependencies = defaultDependencies3) {
   let result = 0;
-  const program2 = new Command().name("dsh-plugins").version(publishedVersion()).description("Unofficial catalog and safe installer for DeepSeek Harness plugins.").addHelpText(
+  let version;
+  try {
+    version = publishedVersion();
+  } catch (error) {
+    dependencies.stderr(`${sanitizedErrorMessage(error)}
+`);
+    dependencies.stderr("Command failed safely; no changes were made.\n");
+    return 1;
+  }
+  const program2 = new Command().name("dsh-plugins").version(version).description("Unofficial catalog and safe installer for DeepSeek Harness plugins.").addHelpText(
     "after",
     "\nUnofficial community project. Not affiliated with, endorsed by, or sponsored by DeepSeek.\nNative Windows add/update/remove with code execution are disabled; use WSL.\nDry-run and read-only catalog/search/info/list/doctor commands remain available.\nNative Windows recovery markers require documented manual recovery.\n"
   ).configureOutput({
@@ -29371,8 +29549,8 @@ async function runCli(argv, dependencies = defaultDependencies3) {
   addCatalogOptions(catalog.command("validate").description("validate catalog YAML and semantics")).action(async (options) => {
     result = await validateCatalogCommand(dependencies, selection(options), options.json === true);
   });
-  catalog.command("docs-check").description("check required public catalog documentation").argument("[root]", "public repository root", ".").action(async (root) => {
-    result = await docsCheckCommand(dependencies, root);
+  catalog.command("docs-check").description("check required public catalog documentation").argument("[root]", "public repository root", ".").option("--skip-count", "skip the exact README entry-count assertion (pull-request mode)").action(async (root, options) => {
+    result = await docsCheckCommand(dependencies, root, options);
   });
   catalog.command("github-forms-check").description("check structured public GitHub issue forms").argument("[root]", "public repository root", ".").action(async (root) => {
     result = await githubFormsCheckCommand(dependencies, root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omni-dsh-plugins",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Unofficial catalog and safe installer for DeepSeek Harness plugins",
   "type": "module",
   "license": "MIT",