0xray 4.0.9 → 4.0.10

package/scripts/foundry/validate-release-docs.mjs

@@ -2,8 +2,8 @@
 /**
  * validate-release-docs.mjs — Blocking guard for release doc freshness.
  *
- * Ensures README, AGENTS, SKILLS, CHANGELOG, Docusaurus headers, and required
- * guides match package.json version and live framework counts before tag/publish.
+ * Ensures README, AGENTS, SKILLS, llms.txt, CHANGELOG, Docusaurus headers, and
+ * required guides match package.json version and mill law before tag/publish.
  *
  * Usage:
  *   npx @0xray/foundry docs-check
@@ -42,6 +42,24 @@ const REQUIRED_GUIDES = [
   'docs-site/docs/agents/README.md',
 ];
 
+function millLawLagErrors(content) {
+  const errors = [];
+  if (/Syncs \*\*45 framework skills\*\*/.test(content) || /syncs all 45 skills/i.test(content)) {
+    errors.push('lags mill law: default plant is mill+inspect, not 45-skill sync');
+  }
+  if (/SKILLS\.md \+ 45 skills → platform skill directories/.test(content)) {
+    errors.push('lags mill law: postinstall must not sync 45 skills as default plant');
+  }
+  return errors;
+}
+
+function millPlantMentionErrors(content) {
+  if (!content.includes('mill') || !content.includes('inspect')) {
+    return ['missing mill+inspect plant'];
+  }
+  return [];
+}
+
 const ROOT_DOC_CHECKS = [
   {
     rel: 'README.md',
@@ -62,6 +80,14 @@ const ROOT_DOC_CHECKS = [
       if (!content.includes('install-bridges') && !content.includes('installAllBridges')) {
         errors.push('missing install-bridges / installAllBridges reference');
       }
+      if (!content.includes('llms.txt')) {
+        errors.push('missing llms.txt agent-map reference');
+      }
+      if (!content.includes('shopPlant') && !content.includes('shop-extract')) {
+        errors.push('missing shop plant / shopPlant');
+      }
+      errors.push(...millPlantMentionErrors(content));
+      errors.push(...millLawLagErrors(content));
       return errors;
     },
   },
@@ -81,6 +107,11 @@ const ROOT_DOC_CHECKS = [
       if (!content.includes('SKILLS.md')) {
         errors.push('missing SKILLS.md link');
       }
+      if (!content.includes('llms.txt')) {
+        errors.push('missing llms.txt agent-map reference');
+      }
+      errors.push(...millPlantMentionErrors(content));
+      errors.push(...millLawLagErrors(content));
       return errors;
     },
   },
@@ -100,6 +131,11 @@ const ROOT_DOC_CHECKS = [
       if (!content.includes('AsideContext')) {
         errors.push('missing AsideContext section');
       }
+      if (!content.includes('shopPlant') && !content.includes('shop-extract')) {
+        errors.push('missing shop plant / shopPlant');
+      }
+      errors.push(...millPlantMentionErrors(content));
+      errors.push(...millLawLagErrors(content));
       return errors;
     },
   },
@@ -113,6 +149,37 @@ const ROOT_DOC_CHECKS = [
       if (!content.includes(`**${counts.skills} skills**`)) {
         errors.push(`skill count stale (expected **${counts.skills} skills**)`);
       }
+      errors.push(...millPlantMentionErrors(content));
+      errors.push(...millLawLagErrors(content));
+      return errors;
+    },
+  },
+  {
+    rel: 'llms.txt',
+    validate: (content) => {
+      const errors = [];
+      if (kernelLineHasPatchStamp(content)) {
+        errors.push('kernel header must be era (major.minor), not a patch stamp');
+      }
+      if (!content.includes('mill') || !content.includes('inspect')) {
+        errors.push('missing mill+inspect plant');
+      }
+      if (!content.includes('shopPlant') && !content.includes('shop-extract')) {
+        errors.push('missing hangar / shopPlant coexistence');
+      }
+      if (!content.includes('69')) {
+        errors.push('missing Codex 69');
+      }
+      if (!content.includes('xray-governance') || !content.includes('xray-orchestrator')) {
+        errors.push('missing 7 MCP agent map');
+      }
+      if (!content.toLowerCase().includes('costume')) {
+        errors.push('missing no-costume-dump law');
+      }
+      if (/^## Complete catalog/m.test(content) || content.includes('`api-design` · `architect-tools`')) {
+        errors.push('llms.txt must not costume-dump the 45-skill catalog');
+      }
+      errors.push(...millLawLagErrors(content));
       return errors;
     },
   },

package/scripts/foundry/version-manager.mjs

@@ -348,6 +348,7 @@ export function getReleaseArtifactPaths(baseDir = resolveMillRoot()) {
     'AGENTS.md',
     'AGENTS-consumer.md',
     'SKILLS.md',
+    'llms.txt',
     '.grok-plugin/plugin.json',
     'docs/README.md',
     'docs-site/docs/index.md',
@@ -366,6 +367,9 @@ export function getReleaseArtifactPaths(baseDir = resolveMillRoot()) {
     'docs-site/docs/architecture/GROK_GUIDE.md',
     'docs-site/sidebars.ts',
     'xray/features.json',
+    '.xray/features.json',
+    'docs/PIPELINE-FACET-SNAPSHOT.json',
+    'src/integrations/openclaw/plugin/xray-pre-tool/package.json',
   ];
   return candidates.filter((rel) => fs.existsSync(path.join(baseDir, rel)));
 }

package/scripts/node/bridge-mcp-wiring.cjs

@@ -39,6 +39,17 @@ function resolveRepertoireMcp(targetDir) {
   const candidates = [
     path.join(targetDir, "node_modules", "@0xray", "repertoire", "dist", "mcp", "server.js"),
     path.join(targetDir, "vendor", "@0xray", "repertoire", "dist", "mcp", "server.js"),
+    path.join(
+      targetDir,
+      "node_modules",
+      "0xray",
+      "vendor",
+      "@0xray",
+      "repertoire",
+      "dist",
+      "mcp",
+      "server.js",
+    ),
     isRepertoirePackageRoot(selfRoot) ? path.join(selfRoot, "dist", "mcp", "server.js") : null,
     isRepertoirePackageRoot(siblingRoot) ? path.join(siblingRoot, "dist", "mcp", "server.js") : null,
   ];
@@ -66,8 +77,20 @@ function resolveRepertoireProvider(targetDir) {
     "provider",
     "memory-routing-provider.js",
   );
+  const packedVendorProvider = path.join(
+    targetDir,
+    "node_modules",
+    "0xray",
+    "vendor",
+    "@0xray",
+    "repertoire",
+    "dist",
+    "provider",
+    "memory-routing-provider.js",
+  );
   if (fs.existsSync(nmProvider)) return nmProvider;
   if (fs.existsSync(vendorProvider)) return vendorProvider;
+  if (fs.existsSync(packedVendorProvider)) return packedVendorProvider;
   if (isRepertoirePackageRoot(siblingRoot) && fs.existsSync(siblingProvider)) return siblingProvider;
   return null;
 }

package/scripts/node/consumer-install-smoke.mjs

@@ -15,6 +15,7 @@ import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
 import { createRequire } from "module";
+import { proveSuitAfterInstall } from "./pack-tmp-suit-proof.mjs";
 
 const require = createRequire(import.meta.url);
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -39,6 +40,64 @@ function run(cmd, cwd, { inherit = false } = {}) {
   return inherit ? "" : String(result).trim();
 }
 
+function assertPackedPackageHasNoFileDeps(tarballPath) {
+  const packedJson = run(`tar -xOf ${JSON.stringify(tarballPath)} package/package.json`);
+  const packed = JSON.parse(packedJson);
+  const buckets = ["dependencies", "optionalDependencies", "peerDependencies"];
+  for (const bucket of buckets) {
+    const entries = packed[bucket] || {};
+    for (const [name, spec] of Object.entries(entries)) {
+      if (String(spec).startsWith("file:")) {
+        throw new Error(
+          `packed package.json must not ship file: ${bucket} ${name}=${spec} (consumers resolve file: from their root)`,
+        );
+      }
+    }
+  }
+  if (!String(packedJson).includes("vendor/@0xray/repertoire/")) {
+    const listing = run(`tar -tzf ${JSON.stringify(tarballPath)}`);
+    if (!listing.includes("package/vendor/@0xray/repertoire/package.json")) {
+      throw new Error("packed tarball missing vendor/@0xray/repertoire/package.json");
+    }
+  }
+  console.log("  ✅ packed package.json has no file: deps; vendor organ is in the tarball");
+}
+
+function assertOrganRequire(tmpRoot) {
+  const consumerRequire = createRequire(path.join(tmpRoot, "package.json"));
+  let organPkg;
+  try {
+    organPkg = consumerRequire("@0xray/repertoire/package.json");
+  } catch (err) {
+    throw new Error(`require('@0xray/repertoire') failed: ${err.message}`);
+  }
+  if (organPkg.name !== "@0xray/repertoire") {
+    throw new Error(`required organ name ${organPkg.name}`);
+  }
+  if (organPkg.version !== "0.2.0") {
+    throw new Error(`required organ version ${organPkg.version}`);
+  }
+  if (fs.existsSync(path.join(tmpRoot, "vendor"))) {
+    throw new Error("consumer install must not create or require a consumer-root vendor/ tree");
+  }
+  console.log("  ✅ require('@0xray/repertoire') from consumer cwd (no consumer vendor/)");
+}
+
+function writeBareConsumerManifest(tmpRoot) {
+  fs.writeFileSync(
+    path.join(tmpRoot, "package.json"),
+    `${JSON.stringify(
+      {
+        name: "xray-consumer-test",
+        version: "0.0.1",
+        private: true,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
 function assertFreshInstallDefaults(tmpRoot, version) {
   const consumerFeaturesPath = path.join(tmpRoot, ".xray", "features.json");
   if (!fs.existsSync(consumerFeaturesPath)) {
@@ -188,25 +247,30 @@ function main() {
       throw new Error(`Tarball not found: ${tarballPath}`);
     }
 
-    const consumerPkg = {
-      name: "0xray-smoke-consumer",
-      private: true,
-      version: "1.0.0",
-      dependencies: {
-        "0xray": `file:${tarballPath}`,
-      },
-    };
-    fs.writeFileSync(
-      path.join(tmpRoot, "package.json"),
-      JSON.stringify(consumerPkg, null, 2) + "\n",
-    );
+    assertPackedPackageHasNoFileDeps(tarballPath);
+
+    writeBareConsumerManifest(tmpRoot);
 
-    console.log("📥 npm install (runs postinstall)...");
-    run("npm install", tmpRoot, { inherit: true });
+    console.log("📥 npm install tarball into bare consumer (exact ENOENT repro)...");
+    run(`npm install ${JSON.stringify(tarballPath)}`, tmpRoot, { inherit: true });
+
+    const installLinksRoot = fs.mkdtempSync(path.join(os.tmpdir(), "0xray-smoke-links-"));
+    writeBareConsumerManifest(installLinksRoot);
+    console.log("📥 npm install tarball --install-links (file: ENOENT path)...");
+    run(`npm install ${JSON.stringify(tarballPath)} --install-links`, installLinksRoot, {
+      inherit: true,
+    });
+    assertOrganRequire(installLinksRoot);
+    try {
+      fs.rmSync(installLinksRoot, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
 
     const nmRoot = path.join(tmpRoot, "node_modules", "0xray");
     const requiredFiles = [
       "scripts/node/install-bridges.cjs",
+      "scripts/node/wear-vendored-repertoire.cjs",
       "scripts/node/postinstall.cjs",
       "scripts/foundry/mint-suit.cjs",
       "scripts/foundry/hooks.mjs",
@@ -274,6 +338,7 @@ function main() {
     console.log(`  ✅ .mcp.json has ${XRAY_MCP_NAMES.length} npx MCP servers`);
 
     assertFreshInstallDefaults(tmpRoot, version);
+    assertOrganRequire(tmpRoot);
 
     const schemaInPackage = path.join(nmRoot, "xray", "features.schema.json");
     if (!fs.existsSync(schemaInPackage)) {
@@ -283,6 +348,9 @@ function main() {
 
     runUpgradeMergeSmoke(tmpRoot, nmRoot, version);
 
+    console.log("\n📋 Pack → tmp mill fasten + hangar shop plant (not costume)...");
+    proveSuitAfterInstall(tmpRoot, path.join(nmRoot, "scripts", "foundry"));
+
     console.log("\n✅ Consumer install smoke passed\n");
   } catch (err) {
     console.error(`\n❌ Consumer smoke failed: ${err.message}\n`);

package/scripts/node/install-bridges.cjs

@@ -9,6 +9,7 @@ const path = require("path");
 const os = require("os");
 const { execSync } = require("child_process");
 const { wantsCostume, isIsolatedHome, machineHome } = require("../foundry/mint-suit.cjs");
+const { wearVendoredRepertoire } = require("./wear-vendored-repertoire.cjs");
 const {
   wireHermesBridge,
   wireOpencodeBridge,
@@ -742,6 +743,8 @@ function installAllBridges(opts) {
       /* noop */
     });
 
+  wearVendoredRepertoire(packageRoot, targetDir, log);
+
   if (!isConsumerInstall(packageRoot, targetDir)) {
     log("install-bridges", "framework dogfood wear", "info");
     installFrameworkDogfoodWear(packageRoot, log);
@@ -779,4 +782,5 @@ module.exports = {
   isEphemeralInstallRoot,
   isIsolatedHome,
   installFrameworkDogfoodWear,
+  wearVendoredRepertoire,
 };

package/scripts/node/pack-tmp-suit-proof.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+/**
+ * pack-tmp-suit-proof.mjs — Clean-room pack → tmp install → mill fasten → hangar plant → inspect.
+ *
+ * Asserts (Task B):
+ *   1. `npm install` of the packed 0xray tgz works
+ *   2. `foundry mint --skip-live` fastens mill+inspect (not 45/42 costume)
+ *   3. groover-hangar factory shops + inspect do not costume-dump
+ *
+ * Usage:
+ *   node scripts/node/pack-tmp-suit-proof.mjs
+ *   npm run pack:tmp-proof
+ *
+ * Playwright / UI: n/a (mill CLI).
+ */
+
+import { execSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "../..");
+
+export const FACTORY_SHOP_SKILLS = ["shop-extract", "shop-witness", "shop-pin"];
+export const MILL_PLANT_SKILLS = ["mill", "inspect"];
+
+function run(cmd, cwd, { inherit = false } = {}) {
+  const result = execSync(cmd, {
+    cwd,
+    encoding: inherit ? undefined : "utf-8",
+    stdio: inherit ? "inherit" : "pipe",
+  });
+  return inherit ? "" : String(result).trim();
+}
+
+export function foundryCliPath(millRoot) {
+  return path.join(millRoot, "cli.js");
+}
+
+export function runFoundryCli(millRoot, consumerRoot, args) {
+  const isolatedHome = path.join(consumerRoot, ".proof-home");
+  fs.mkdirSync(isolatedHome, { recursive: true });
+  return spawnSync(process.execPath, [foundryCliPath(millRoot), ...args], {
+    cwd: consumerRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      FOUNDRY_ROOT: consumerRoot,
+      HOME: isolatedHome,
+    },
+  });
+}
+
+export function lastJsonObject(text) {
+  const src = String(text || "");
+  for (let end = src.length - 1; end >= 0; end -= 1) {
+    if (src[end] !== "}") continue;
+    let depth = 0;
+    for (let start = end; start >= 0; start -= 1) {
+      const ch = src[start];
+      if (ch === "}") depth += 1;
+      else if (ch === "{") {
+        depth -= 1;
+        if (depth === 0) {
+          try {
+            return JSON.parse(src.slice(start, end + 1));
+          } catch {
+            break;
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+export function plantHangarFactoryShops(consumerRoot) {
+  for (const name of FACTORY_SHOP_SKILLS) {
+    const dir = path.join(consumerRoot, ".opencode", "skills", name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "SKILL.md"), `groover-hangar plant ${name}\n`);
+  }
+}
+
+export function wornSkillNames(consumerRoot) {
+  const skillsDir = path.join(consumerRoot, ".opencode", "skills");
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs.readdirSync(skillsDir).filter((name) =>
+    fs.existsSync(path.join(skillsDir, name, "SKILL.md")),
+  );
+}
+
+export function assertFastenedMillPlant(consumerRoot) {
+  const inventoryPath = path.join(consumerRoot, ".xray", "foundry-inventory.json");
+  if (!fs.existsSync(inventoryPath)) {
+    throw new Error("foundry-inventory.json missing — mill did not fasten");
+  }
+  const inventory = JSON.parse(fs.readFileSync(inventoryPath, "utf8"));
+  if (inventory.costume === true) {
+    throw new Error("inventory.costume is true — costume dump is not default mill plant");
+  }
+  const millSkills = inventory.millPlant?.skills || [];
+  for (const name of MILL_PLANT_SKILLS) {
+    if (!millSkills.includes(name)) {
+      throw new Error(`mill plant missing ${name} (got ${millSkills.join(",")})`);
+    }
+    if (!fs.existsSync(path.join(consumerRoot, ".opencode", "skills", name, "SKILL.md"))) {
+      throw new Error(`worn mill plant missing ${name}`);
+    }
+  }
+  const foundry = path.join(consumerRoot, "foundry.json");
+  if (fs.existsSync(foundry)) {
+    const extra = JSON.parse(fs.readFileSync(foundry, "utf8"));
+    if (extra.costume === true) {
+      throw new Error("foundry.json costume:true is not the mill+inspect path");
+    }
+  }
+  const worn = wornSkillNames(consumerRoot);
+  const extras = worn.filter(
+    (name) => !MILL_PLANT_SKILLS.includes(name) && !FACTORY_SHOP_SKILLS.includes(name),
+  );
+  if (extras.length > 0) {
+    throw new Error(`costume dump extras before hangar plant: ${extras.join(",")}`);
+  }
+  return inventory;
+}
+
+export function proveSuitAfterInstall(consumerRoot, millRoot) {
+  if (!fs.existsSync(foundryCliPath(millRoot))) {
+    throw new Error(`foundry CLI missing at ${foundryCliPath(millRoot)}`);
+  }
+
+  console.log("  ⚒️  foundry mint --skip-live (fasten mill+inspect)...");
+  const mint = runFoundryCli(millRoot, consumerRoot, ["mint", "--skip-live"]);
+  if (mint.status !== 0) {
+    throw new Error(`foundry mint --skip-live failed:\n${mint.stdout}\n${mint.stderr}`);
+  }
+  const inventory = assertFastenedMillPlant(consumerRoot);
+  if (inventory.suit !== "fastened" && inventory.suit !== "overlay") {
+    throw new Error(`expected fastened/overlay suit, got ${inventory.suit}`);
+  }
+  console.log(`  ✅ mint fastened mill+inspect (suit=${inventory.suit}, costume=${inventory.costume === true})`);
+
+  console.log("  🏭 groover-hangar plant factory shops (not costume)...");
+  plantHangarFactoryShops(consumerRoot);
+  for (const name of FACTORY_SHOP_SKILLS) {
+    if (!fs.existsSync(path.join(consumerRoot, ".opencode", "skills", name, "SKILL.md"))) {
+      throw new Error(`hangar plant missing ${name}`);
+    }
+  }
+
+  console.log("  🔍 foundry inspect --skip-live (shop plant must not costume-dump)...");
+  const inspect = runFoundryCli(millRoot, consumerRoot, ["inspect", "--skip-live"]);
+  const report = lastJsonObject(inspect.stdout);
+  if (inspect.status !== 0 || !report?.ok) {
+    throw new Error(
+      `inspect failed after hangar plant (costume dump?):\n${inspect.stdout}\n${inspect.stderr}`,
+    );
+  }
+  const plantVsWorn = (report.checks || []).find((c) => c.id === "plant-vs-worn");
+  if (!plantVsWorn?.ok) {
+    throw new Error(`plant-vs-worn failed: ${JSON.stringify(plantVsWorn)}`);
+  }
+  const shopPlant = plantVsWorn.shopPlant || [];
+  for (const name of FACTORY_SHOP_SKILLS) {
+    if (!shopPlant.includes(name)) {
+      throw new Error(`inspect shopPlant missing ${name} (got ${shopPlant.join(",")})`);
+    }
+  }
+  if (Array.isArray(plantVsWorn.extraSkills) && plantVsWorn.extraSkills.length > 0) {
+    throw new Error(`inspect extraSkills after hangar plant: ${plantVsWorn.extraSkills.join(",")}`);
+  }
+  const after = assertFastenedMillPlant(consumerRoot);
+  if (after.costume === true) {
+    throw new Error("costume flipped true after hangar plant");
+  }
+  console.log("  ✅ hangar factory shops + inspect OK (costume false, no dump)");
+  return { inventory: after, report };
+}
+
+export function packXrayTgz(xrayRoot = repoRoot) {
+  const packOut = run("npm pack --silent", xrayRoot);
+  const tarball = packOut.split("\n").filter(Boolean).pop();
+  const tarballPath = path.join(xrayRoot, tarball);
+  if (!fs.existsSync(tarballPath)) {
+    throw new Error(`Tarball not found: ${tarballPath}`);
+  }
+  return tarballPath;
+}
+
+export function writeBareConsumerManifest(tmpRoot) {
+  fs.writeFileSync(
+    path.join(tmpRoot, "package.json"),
+    `${JSON.stringify({ name: "xray-pack-tmp-proof", version: "0.0.1", private: true }, null, 2)}\n`,
+  );
+}
+
+export function runPackTmpProof(xrayRoot = repoRoot) {
+  console.log("\n=== Pack → tmp suit proof ===\n");
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "0xray-pack-tmp-proof-"));
+  let tarballPath = null;
+  try {
+    console.log("📦 npm pack...");
+    tarballPath = packXrayTgz(xrayRoot);
+    writeBareConsumerManifest(tmpRoot);
+    console.log("📥 npm install tgz into clean tmp...");
+    run(`npm install ${JSON.stringify(tarballPath)}`, tmpRoot, { inherit: true });
+    const millRoot = path.join(tmpRoot, "node_modules", "0xray", "scripts", "foundry");
+    proveSuitAfterInstall(tmpRoot, millRoot);
+    console.log("\n✅ Pack → tmp suit proof passed (Playwright n/a — mill CLI)\n");
+    return { tmpRoot, tarballPath };
+  } catch (err) {
+    console.error(`\n❌ Pack → tmp suit proof failed: ${err.message}\n`);
+    throw err;
+  } finally {
+    if (tarballPath) {
+      try {
+        fs.unlinkSync(tarballPath);
+      } catch {
+        /* best-effort */
+      }
+    }
+    try {
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  try {
+    runPackTmpProof();
+  } catch {
+    process.exit(1);
+  }
+}

package/scripts/node/wear-vendored-repertoire.cjs

@@ -0,0 +1,120 @@
+/**
+ * wear-vendored-repertoire.cjs — Materialize @0xray/repertoire from the
+ * packed vendor tree. Published 0xray must not ship a `file:` dependency:
+ * npm --install-links, pnpm, and yarn resolve that path from the consumer
+ * root (ENOENT on vendor/@0xray/repertoire), not from node_modules/0xray.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+function resolveVendoredRepertoire(packageRoot) {
+  const vendor = path.join(packageRoot, "vendor", "@0xray", "repertoire");
+  if (fs.existsSync(path.join(vendor, "package.json"))) return vendor;
+  return null;
+}
+
+function repertoirePackageName(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    return pkg.name || null;
+  } catch {
+    return null;
+  }
+}
+
+function destAlreadyWorn(dest, vendor) {
+  try {
+    if (!fs.existsSync(path.join(dest, "package.json"))) return false;
+    if (repertoirePackageName(dest) !== "@0xray/repertoire") return false;
+    return fs.realpathSync(dest) === fs.realpathSync(vendor);
+  } catch {
+    return false;
+  }
+}
+
+function destIsUsableRepertoire(dest) {
+  return repertoirePackageName(dest) === "@0xray/repertoire";
+}
+
+function removeBrokenDest(dest) {
+  try {
+    const st = fs.lstatSync(dest);
+    if (st.isSymbolicLink() && !fs.existsSync(dest)) {
+      fs.unlinkSync(dest);
+    }
+  } catch {
+    /* dest absent */
+  }
+}
+
+function wearOne(vendor, dest, log) {
+  removeBrokenDest(dest);
+  if (destAlreadyWorn(dest, vendor)) return true;
+  if (fs.existsSync(dest) && destIsUsableRepertoire(dest)) return true;
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  const rel = path.relative(path.dirname(dest), vendor);
+  const linkType = process.platform === "win32" ? "junction" : "dir";
+  try {
+    fs.symlinkSync(rel, dest, linkType);
+    return true;
+  } catch (linkErr) {
+    try {
+      fs.cpSync(vendor, dest, { recursive: true });
+      return true;
+    } catch (copyErr) {
+      if (typeof log === "function") {
+        log("wear-repertoire", "failed to wear vendored organ", "warning", {
+          dest,
+          linkError: linkErr.message,
+          copyError: copyErr.message,
+        });
+      }
+      return false;
+    }
+  }
+}
+
+function wearDestinations(packageRoot, targetDir) {
+  const dests = [path.join(packageRoot, "node_modules", "@0xray", "repertoire")];
+  if (targetDir && path.resolve(targetDir) !== path.resolve(packageRoot)) {
+    dests.push(path.join(targetDir, "node_modules", "@0xray", "repertoire"));
+  }
+  return dests;
+}
+
+function wearVendoredRepertoire(packageRoot, targetDir, log) {
+  const vendor = resolveVendoredRepertoire(packageRoot);
+  if (!vendor) return { worn: [], vendor: null };
+
+  const worn = [];
+  for (const dest of wearDestinations(packageRoot, targetDir)) {
+    if (wearOne(vendor, dest, log)) worn.push(dest);
+  }
+  if (worn.length && typeof log === "function") {
+    log("wear-repertoire", "vendored @0xray/repertoire worn", "info", {
+      vendor,
+      dests: worn,
+    });
+  }
+  return { worn, vendor };
+}
+
+function hasFileProtocolDependency(pkg) {
+  const buckets = [pkg.dependencies, pkg.optionalDependencies, pkg.peerDependencies];
+  for (const bucket of buckets) {
+    if (!bucket || typeof bucket !== "object") continue;
+    for (const spec of Object.values(bucket)) {
+      if (String(spec).startsWith("file:")) return true;
+    }
+  }
+  return false;
+}
+
+module.exports = {
+  resolveVendoredRepertoire,
+  wearVendoredRepertoire,
+  wearDestinations,
+  hasFileProtocolDependency,
+};