0xray 4.0.1 → 4.0.2

package/scripts/foundry/mill-root.mjs

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const millDir = path.dirname(fileURLToPath(import.meta.url));
+
+export function millPackageDir() {
+  return millDir;
+}
+
+export function millScript(basename) {
+  return path.join(millDir, basename);
+}
+
+/** Repo being milled: FOUNDRY_ROOT, else cwd. Not this package's __dirname. */
+export function resolveMillRoot() {
+  const env = process.env.FOUNDRY_ROOT;
+  if (typeof env === "string" && env.trim()) {
+    return path.resolve(env.trim());
+  }
+  return process.cwd();
+}
+
+/**
+ * Git hook installer. Dogfood is `scripts/hooks` next to `scripts/foundry`.
+ * Published mill lives in `node_modules/@0xray/foundry` — sibling `@0xray/hooks`
+ * does not exist. Use the worn 0xray garment installer instead.
+ */
+export function resolveHookInstaller(rootDir = resolveMillRoot(), millPkg = millPackageDir()) {
+  const candidates = [
+    path.join(millPkg, "..", "hooks", "install-hooks.cjs"),
+    path.join(rootDir, "node_modules", "0xray", "scripts", "hooks", "install-hooks.cjs"),
+    path.join(rootDir, "scripts", "hooks", "install-hooks.cjs"),
+  ];
+  return candidates.find((p) => fs.existsSync(p)) ?? null;
+}
+
+export function readRootPackage(rootDir = resolveMillRoot()) {
+  const pkgPath = path.join(rootDir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    return { name: null, version: null, scripts: {} };
+  }
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return {
+      name: typeof pkg.name === "string" ? pkg.name : null,
+      version: typeof pkg.version === "string" ? pkg.version : null,
+      scripts: pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {},
+    };
+  } catch {
+    return { name: null, version: null, scripts: {} };
+  }
+}
+
+export function hasDocsSite(rootDir = resolveMillRoot()) {
+  return fs.existsSync(path.join(rootDir, "docs-site"));
+}
+
+export function isXrayExoRepo(rootDir = resolveMillRoot()) {
+  const pkg = readRootPackage(rootDir);
+  return pkg.name === "0xray" && hasDocsSite(rootDir);
+}

package/scripts/foundry/mint-suit.cjs

@@ -0,0 +1,313 @@
+/**
+ * Mill overlay: their plant onto the hanger. Not PPE (evaluatePreToolGate).
+ *
+ * Default SSOT (override with foundry.json or .xray/foundry.json):
+ *   xray/codex.json, xray/features.json, xray/config.json,
+ *   src/skills/<name>/SKILL.md, src/opencode/agents/*.yml
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_PARAMS = {
+  codex: "xray/codex.json",
+  features: "xray/features.json",
+  config: "xray/config.json",
+  skills: "src/skills",
+  agents: "src/opencode/agents",
+  agentsCard: "xray/AGENTS.md",
+};
+
+function deepMerge(src, dest) {
+  if (typeof src !== "object" || src === null) return dest !== undefined ? dest : src;
+  if (Array.isArray(src)) return Array.isArray(dest) ? dest : src;
+  const result = {};
+  for (const key of Object.keys(src)) {
+    result[key] =
+      dest && typeof dest[key] !== "undefined" ? deepMerge(src[key], dest[key]) : src[key];
+  }
+  if (dest && typeof dest === "object") {
+    for (const key of Object.keys(dest)) {
+      if (!(key in src)) result[key] = dest[key];
+    }
+  }
+  return result;
+}
+
+function readPackageIdentity(pkgPath) {
+  if (!fs.existsSync(pkgPath)) return { name: null, version: null };
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return {
+      name: typeof pkg.name === "string" ? pkg.name : null,
+      version: typeof pkg.version === "string" ? pkg.version : null,
+    };
+  } catch {
+    return { name: null, version: null };
+  }
+}
+
+function isExoRepo(dir) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+    return pkg.name === "0xray" && fs.existsSync(path.join(dir, "docs-site"));
+  } catch {
+    return false;
+  }
+}
+
+function isDogfood(millPackageRoot, targetDir) {
+  if (path.resolve(millPackageRoot) === path.resolve(targetDir)) return true;
+  return isExoRepo(targetDir);
+}
+
+/** Rel must stay inside targetDir. Absolute and `..` escapes return null. */
+function resolveInside(targetDir, rel) {
+  if (typeof rel !== "string" || !rel.trim()) return null;
+  if (path.isAbsolute(rel)) return null;
+  const rootAbs = path.resolve(targetDir);
+  const resolved = path.resolve(rootAbs, rel);
+  const prefix = rootAbs.endsWith(path.sep) ? rootAbs : `${rootAbs}${path.sep}`;
+  if (resolved !== rootAbs && !resolved.startsWith(prefix)) return null;
+  return resolved;
+}
+
+function loadFoundryParams(targetDir) {
+  const candidates = [
+    path.join(targetDir, "foundry.json"),
+    path.join(targetDir, ".xray", "foundry.json"),
+  ];
+  let extra = {};
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) extra = parsed;
+    } catch {
+      extra = {};
+    }
+    break;
+  }
+  const params = { ...DEFAULT_PARAMS };
+  for (const key of ["codex", "features", "config", "skills", "agents", "agentsCard"]) {
+    if (typeof extra[key] === "string" && extra[key].trim()) params[key] = extra[key].trim();
+  }
+  return params;
+}
+
+function isDirectory(p) {
+  try {
+    return Boolean(p) && fs.existsSync(p) && fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Project skill hangers only. */
+function listSkillHangers(targetDir) {
+  const dests = [path.join(targetDir, ".opencode", "skills")];
+  const projectGrok = path.join(targetDir, ".grok", "plugins", "0xray", "skills");
+  if (isDirectory(projectGrok)) dests.push(projectGrok);
+  return dests;
+}
+
+function overlayJsonFacet(src, dest) {
+  if (!src || !fs.existsSync(src) || !fs.statSync(src).isFile()) return false;
+  if (path.resolve(src) === path.resolve(dest)) return false;
+  let theirs;
+  try {
+    theirs = JSON.parse(fs.readFileSync(src, "utf8"));
+  } catch {
+    return false;
+  }
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (!fs.existsSync(dest)) {
+    fs.writeFileSync(dest, `${JSON.stringify(theirs, null, 2)}\n`);
+    return true;
+  }
+  try {
+    const mill = JSON.parse(fs.readFileSync(dest, "utf8"));
+    const merged = deepMerge(mill, theirs);
+    fs.writeFileSync(dest, `${JSON.stringify(merged, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function listConsumerSkillNames(targetDir, skillsRel) {
+  const rel = skillsRel || DEFAULT_PARAMS.skills;
+  const skillsSrc = resolveInside(targetDir, rel);
+  if (!isDirectory(skillsSrc)) return [];
+  const names = [];
+  for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+    const skillMd = path.join(skillsSrc, entry.name, "SKILL.md");
+    if (!fs.existsSync(skillMd)) continue;
+    names.push(entry.name);
+  }
+  return names;
+}
+
+function listConsumerAgentFiles(targetDir, agentsRel) {
+  const rel = agentsRel || DEFAULT_PARAMS.agents;
+  const agentsSrc = resolveInside(targetDir, rel);
+  if (!isDirectory(agentsSrc)) return [];
+  return fs
+    .readdirSync(agentsSrc, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isFile() && (entry.name.endsWith(".yml") || entry.name.endsWith(".yaml")),
+    )
+    .map((entry) => entry.name);
+}
+
+const MANAGED_AGENTS_MARKER = "<!-- 0xray-managed -->";
+
+function overlayAgentsCard(targetDir, params) {
+  const src = resolveInside(targetDir, params.agentsCard || DEFAULT_PARAMS.agentsCard);
+  if (!src || !fs.existsSync(src) || !fs.statSync(src).isFile()) return false;
+  const dest = path.join(targetDir, "AGENTS.md");
+  if (path.resolve(src) === path.resolve(dest)) return false;
+  if (fs.existsSync(dest) && !fs.readFileSync(dest, "utf8").includes(MANAGED_AGENTS_MARKER)) {
+    return false;
+  }
+  fs.copyFileSync(src, dest);
+  return true;
+}
+
+function overlayConsumerTree(targetDir, log, params) {
+  const resolved = params || loadFoundryParams(targetDir);
+  const skillsRel = resolved.skills;
+  const agentsRel = resolved.agents;
+  const skills = listConsumerSkillNames(targetDir, skillsRel);
+  const agents = listConsumerAgentFiles(targetDir, agentsRel);
+  const skillsSrc = resolveInside(targetDir, skillsRel);
+  const agentsSrc = resolveInside(targetDir, agentsRel);
+  const skillHangers = listSkillHangers(targetDir);
+  const agentsDest = path.join(targetDir, ".opencode", "agents");
+
+  for (const hanger of skillHangers) {
+    for (const name of skills) {
+      const src = path.join(skillsSrc, name, "SKILL.md");
+      const destMd = path.join(hanger, name, "SKILL.md");
+      if (path.resolve(src) === path.resolve(destMd)) continue;
+      fs.mkdirSync(path.dirname(destMd), { recursive: true });
+      fs.copyFileSync(src, destMd);
+    }
+  }
+  for (const file of agents) {
+    const src = path.join(agentsSrc, file);
+    const dest = path.join(agentsDest, file);
+    if (path.resolve(src) === path.resolve(dest)) continue;
+    fs.mkdirSync(agentsDest, { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+
+  if (log && (skills.length > 0 || agents.length > 0)) {
+    log("foundry-mint", "Overlaid consumer skills/agents onto hangers", "info", {
+      skills: skills.length,
+      agents: agents.length,
+      skillHangers: skillHangers.length,
+    });
+  }
+  return { skills, agents, params: resolved };
+}
+
+function mintConsumerFromSsot(packageRoot, targetDir, log, tree) {
+  if (isDogfood(packageRoot, targetDir)) {
+    return { garment: "dogfood", skipped: true, consumer: readPackageIdentity(path.join(targetDir, "package.json")) };
+  }
+  const mill = readPackageIdentity(path.join(packageRoot, "package.json"));
+  const consumer = readPackageIdentity(path.join(targetDir, "package.json"));
+  const skills = Array.isArray(tree?.skills) ? tree.skills : [];
+  const agents = Array.isArray(tree?.agents) ? tree.agents : [];
+  const constitution = Boolean(tree?.codex);
+  const features = Boolean(tree?.features);
+  const config = Boolean(tree?.config);
+  const agentsCard = Boolean(tree?.agentsCard);
+  const overlayed =
+    skills.length > 0 ||
+    agents.length > 0 ||
+    constitution ||
+    features ||
+    config ||
+    agentsCard;
+  const garment = overlayed ? "overlay" : "copied-onto-hanger";
+  const inventory = {
+    mill: { name: mill.name || "@0xray/foundry", version: mill.version },
+    consumer: { name: consumer.name, version: consumer.version },
+    garment,
+    params: tree?.params || loadFoundryParams(targetDir),
+    tree: { skills, agents },
+    facets: {
+      constitution,
+      features,
+      config,
+      agentsCard,
+      skills,
+      agents,
+    },
+    mintedAt: new Date().toISOString(),
+  };
+  const xrayDir = path.join(targetDir, ".xray");
+  if (!fs.existsSync(xrayDir)) fs.mkdirSync(xrayDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(xrayDir, "foundry-inventory.json"),
+    `${JSON.stringify(inventory, null, 2)}\n`,
+  );
+  if (log) {
+    log("foundry-mint", "Minted foundry-inventory from consumer mill SSOT", "info", {
+      consumer: consumer.name,
+      version: consumer.version,
+      garment,
+    });
+  }
+  return inventory;
+}
+
+function mintConsumerSuit(millPackageRoot, targetDir, log) {
+  if (isDogfood(millPackageRoot, targetDir)) {
+    return { garment: "dogfood", skipped: true };
+  }
+  const params = loadFoundryParams(targetDir);
+  const tree = overlayConsumerTree(targetDir, log, params);
+  tree.codex = overlayJsonFacet(
+    resolveInside(targetDir, params.codex),
+    path.join(targetDir, ".xray", "codex.json"),
+  );
+  tree.features = overlayJsonFacet(
+    resolveInside(targetDir, params.features),
+    path.join(targetDir, ".xray", "features.json"),
+  );
+  tree.config = overlayJsonFacet(
+    resolveInside(targetDir, params.config),
+    path.join(targetDir, ".xray", "config.json"),
+  );
+  tree.agentsCard = overlayAgentsCard(targetDir, params);
+  if (log && (tree.codex || tree.features || tree.config)) {
+    log("foundry-mint", "Overlaid consumer suit facets onto .xray", "info", {
+      constitution: tree.codex,
+      features: tree.features,
+      config: tree.config,
+    });
+  }
+  return mintConsumerFromSsot(millPackageRoot, targetDir, log, tree);
+}
+
+module.exports = {
+  DEFAULT_PARAMS,
+  deepMerge,
+  loadFoundryParams,
+  resolveInside,
+  overlayJsonFacet,
+  overlayAgentsCard,
+  overlayConsumerTree,
+  listConsumerSkillNames,
+  listConsumerAgentFiles,
+  listSkillHangers,
+  mintConsumerFromSsot,
+  mintConsumerSuit,
+  isDogfood,
+  readPackageIdentity,
+};

package/scripts/foundry/mint.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Overlay their mill SSOT onto the hanger (cwd / FOUNDRY_ROOT).
+ * Not a fifth 0xray CLI. Not PPE.
+ */
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { millPackageDir, resolveMillRoot } from "./mill-root.mjs";
+
+const require = createRequire(import.meta.url);
+const { mintConsumerSuit } = require("./mint-suit.cjs");
+
+function main() {
+  const target = resolveMillRoot();
+  const millRoot = millPackageDir();
+  const inventory = mintConsumerSuit(millRoot, target, (component, action, status) => {
+    process.stdout.write(`${component} ${action} ${status}\n`);
+  });
+  if (inventory.skipped) {
+    process.stderr.write("mint: skipped dogfood / 0xray exo plant (not a consumer hanger)\n");
+    process.exit(0);
+  }
+  process.stdout.write(`${JSON.stringify(inventory, null, 2)}\n`);
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main();
+}

package/scripts/foundry/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@0xray/foundry",
+  "version": "0.1.4",
+  "private": false,
+  "type": "module",
+  "description": "0xRay mill: mint their suit params, stamp, gate, publish, CI report, git hooks. Not the worn exo.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xRayAI/xray.git",
+    "directory": "scripts/foundry"
+  },
+  "homepage": "https://github.com/0xRayAI/xray/tree/main/scripts/foundry",
+  "bugs": {
+    "url": "https://github.com/0xRayAI/xray/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "0xray-foundry": "cli.js"
+  },
+  "files": [
+    "*.mjs",
+    "*.cjs",
+    "cli.js",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./version-manager": "./version-manager.mjs",
+    "./validate-release-docs": "./validate-release-docs.mjs",
+    "./reconcile-version": "./reconcile-version.mjs",
+    "./release": "./release.mjs",
+    "./release-gate": "./release-gate.mjs",
+    "./mill-root": "./mill-root.mjs",
+    "./mint-suit": "./mint-suit.cjs",
+    "./ci-monitor": "./ci-monitor.mjs",
+    "./hooks": "./hooks.mjs",
+    "./docs-build": "./docs-build.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "0xray",
+    "foundry",
+    "mill",
+    "release",
+    "changelog"
+  ]
+}

package/scripts/foundry/reconcile-version.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * reconcile-version.mjs — Single version truth before bump/tag/publish.
+ *
+ * Sources: npm registry, package.json, latest git tag.
+ *
+ * Usage:
+ *   npx @0xray/foundry reconcile
+ *   npx @0xray/foundry reconcile --check
+ *   npx @0xray/foundry reconcile patch
+ *   npx @0xray/foundry reconcile patch --apply
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { readRootPackage, resolveMillRoot } from "./mill-root.mjs";
+
+const rootDir = resolveMillRoot();
+const pkgPath = path.join(rootDir, "package.json");
+
+const args = process.argv.slice(2);
+const checkMode = args.includes("--check");
+const applyMode = args.includes("--apply");
+const printTarget = args.includes("--print-target");
+const bumpType = args.find((a) => ["major", "minor", "patch"].includes(a)) || null;
+
+function run(cmd) {
+  try {
+    return execSync(cmd, { cwd: rootDir, encoding: "utf-8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function readLocalVersion() {
+  return JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
+}
+
+function readPublishedVersion() {
+  const name = readRootPackage(rootDir).name;
+  if (!name) return "0.0.0";
+  const v = run(`npm view ${name} version`);
+  return v || "0.0.0";
+}
+
+function readLatestTag() {
+  const tag = run('git describe --tags --abbrev=0 2>/dev/null');
+  if (!tag) return null;
+  return tag.replace(/^v/, "");
+}
+
+function parseVersion(version) {
+  const [major, minor, patch] = version.split(".").map((n) => parseInt(n, 10));
+  return { major, minor, patch };
+}
+
+function bumpVersion(version, type) {
+  const v = parseVersion(version);
+  switch (type) {
+    case "major":
+      return `${v.major + 1}.0.0`;
+    case "minor":
+      return `${v.major}.${v.minor + 1}.0`;
+    case "patch":
+      return `${v.major}.${v.minor}.${v.patch + 1}`;
+    default:
+      return version;
+  }
+}
+
+function compare(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (va.major !== vb.major) return va.major - vb.major;
+  if (va.minor !== vb.minor) return va.minor - vb.minor;
+  return va.patch - vb.patch;
+}
+
+function maxVersion(...versions) {
+  return versions.reduce((best, cur) => (compare(cur, best) > 0 ? cur : best));
+}
+
+function fail(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+function main() {
+  const local = readLocalVersion();
+  const npm = readPublishedVersion();
+  const tag = readLatestTag();
+
+  const baseline = maxVersion(npm, tag || "0.0.0");
+  const target = bumpType ? bumpVersion(baseline, bumpType) : local;
+
+  if (printTarget && bumpType) {
+    console.log(target);
+    return;
+  }
+
+  console.log("\n=== Version Reconcile ===\n");
+  console.log(`  npm registry : ${npm}`);
+  console.log(`  package.json : ${local}`);
+  console.log(`  latest tag   : ${tag ? `v${tag}` : "(none)"}`);
+  if (bumpType) {
+    console.log(`  bump ${bumpType}  : ${target} (from baseline ${baseline})`);
+  }
+
+  if (applyMode && bumpType) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    pkg.version = target;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    console.log(`\n✅ Updated package.json → ${target}`);
+  }
+
+  if (!checkMode) {
+    if (compare(local, npm) <= 0 && !bumpType) {
+      console.log("\n⚠️  Local version is not ahead of npm — bump before publishing.");
+    } else {
+      console.log("\n✅ Reconcile report complete.");
+    }
+    return;
+  }
+
+  // Strict checks for release gate / pre-tag
+  if (compare(local, npm) <= 0) {
+    fail(`package.json (${local}) must be > npm (${npm}). Run: npx @0xray/foundry reconcile patch --apply`);
+  }
+
+  if (tag && compare(local, tag) < 0) {
+    fail(`package.json (${local}) is behind latest tag v${tag}`);
+  }
+
+  if (tag && compare(local, tag) > 0 && compare(npm, tag) === 0) {
+    console.log(`✅ Ready to tag v${local} (npm at ${npm})`);
+  } else if (compare(local, npm) > 0) {
+    console.log(`✅ Ready to publish ${local} (npm at ${npm})`);
+  } else {
+    console.log("✅ Version reconcile OK");
+  }
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main();
+}