0xray 4.0.0 → 4.0.2

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();
+}

package/scripts/foundry/release-gate.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * release-gate.mjs — Single release checkpoint.
+ *
+ * Modes:
+ *   (default)     build + test + consumer smoke (fresh + upgrade merge)
+ *   --verify-only git + reconcile + release docs + consumer smoke — after push, before publish
+ *   --skip-smoke  skip consumer install smoke
+ *   --skip-docs   skip release docs validation (not recommended for publish)
+ *
+ * Usage:
+ *   npx @0xray/foundry gate
+ *   npx @0xray/foundry gate --verify-only
+ */
+
+import { execSync } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+import { isXrayExoRepo, millScript, readRootPackage, resolveMillRoot } from "./mill-root.mjs";
+
+const rootDir = resolveMillRoot();
+const verifyOnly = process.argv.includes("--verify-only");
+const skipSmoke = process.argv.includes("--skip-smoke");
+const skipDocs = process.argv.includes("--skip-docs");
+
+function step(label, cmd) {
+  console.log(`\n${"─".repeat(60)}\n🔄 ${label}\n${"─".repeat(60)}\n`);
+  execSync(cmd, { cwd: rootDir, stdio: "inherit", env: { ...process.env, FOUNDRY_ROOT: rootDir } });
+}
+
+function docsCheckCmd() {
+  return `${JSON.stringify(process.execPath)} ${JSON.stringify(millScript("validate-release-docs.mjs"))}`;
+}
+
+function runLightGate() {
+  const pkg = readRootPackage(rootDir);
+  if (verifyOnly) {
+    if (!skipDocs) step("1/1 Release docs (light)", docsCheckCmd());
+    return;
+  }
+  if (pkg.scripts.build) step("1/3 Build", "npm run build");
+  if (pkg.scripts.test) step("2/3 Tests", "npm test");
+  if (!skipDocs) step("3/3 Release docs (light)", docsCheckCmd());
+}
+
+function main() {
+  const mode = verifyOnly ? "verify" : "full";
+  console.log("\n╔════════════════════════════════════════════════════════╗");
+  console.log(`║        🛡️  0xRay Release Gate (${mode})`.padEnd(57) + "║");
+  console.log("╚════════════════════════════════════════════════════════╝");
+
+  try {
+    if (!isXrayExoRepo(rootDir)) {
+      runLightGate();
+    } else if (verifyOnly) {
+      step("1/5 Git + reconcile", "node scripts/node/pre-publish-guard.js --verify-only");
+      if (!skipDocs) {
+        step("2/5 Release docs", docsCheckCmd());
+      }
+      step(
+        "3/5 Plugin infrastructure",
+        "node scripts/test/validate-plugins-e2e.cjs --structural-only",
+      );
+      if (!skipSmoke) {
+        step("4/5 Consumer install smoke", "node scripts/node/consumer-install-smoke.mjs");
+      }
+    } else {
+      step("1/7 Build", "npm run build");
+      step("2/7 Tests", "npm test");
+      if (!skipDocs) {
+        step("3/7 Release docs", docsCheckCmd());
+      }
+      step(
+        "4/7 Consumer hook verifiers",
+        "npm run verify:pre-commit-diff && npm run verify:pre-push-diff && node scripts/mjs/verify-delegation-gate-core.mjs --host=grok && node scripts/mjs/verify-delegation-gate-core.mjs --host=hermes && node scripts/mjs/verify-delegation-gate-core.mjs --host=opencode && node scripts/mjs/verify-hermes-session-start.mjs && node scripts/mjs/verify-confer-core.mjs && npm run verify:user-aside && npm run build && node scripts/mjs/verify-pipeline-facets.mjs --package-only",
+      );
+      step(
+        "5/7 Plugin infrastructure",
+        "node scripts/test/validate-plugins-e2e.cjs --structural-only",
+      );
+      if (!skipSmoke) {
+        step("6/7 Consumer install smoke (fresh + upgrade)", "node scripts/node/consumer-install-smoke.mjs");
+      }
+    }
+
+    console.log("\n╔════════════════════════════════════════════════════════╗");
+    console.log("║  ✅ RELEASE GATE PASSED                                ║");
+    console.log("╚════════════════════════════════════════════════════════╝\n");
+  } catch {
+    console.error("\n❌ RELEASE GATE FAILED — do not tag or publish\n");
+    process.exit(1);
+  }
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main();
+}

package/scripts/foundry/release.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+/**
+ * Canonical 0xRay release script.
+ *
+ * 1. Bump version from npm registry baseline (reconcile-version)
+ * 2. Release artifacts (CHANGELOG / README / AGENTS / docs) — before gate so docs tests pass
+ * 3. Release gate (build + test + consumer smoke)
+ * 4. Commit release artifacts → push
+ * 5. Verify gate (reconcile + git + release docs + smoke)
+ * 6. npm publish (idempotent — skip if version already on registry)
+ * 7. Tag → push tag (only after successful publish)
+ *
+ * Usage:
+ *   npx @0xray/foundry release [patch|minor|major] --dry-run
+ *   npx @0xray/foundry release [patch|minor|major] --i-mean-it
+ *   npx @0xray/foundry release --publish-only --dry-run
+ *   npx @0xray/foundry release --publish-only --i-mean-it
+ *
+ * Live bump/commit/push/publish requires --i-mean-it or FOUNDRY_RELEASE=1.
+ */
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { getReleaseArtifactPaths } from "./version-manager.mjs";
+import {
+  isXrayExoRepo,
+  millScript,
+  readRootPackage,
+  resolveMillRoot,
+} from "./mill-root.mjs";
+
+const rootDir = resolveMillRoot();
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const publishOnly = args.includes("--publish-only");
+const releaseType = args.find((a) => ["major", "minor", "patch"].includes(a));
+const optedIn = args.includes("--i-mean-it") || process.env.FOUNDRY_RELEASE === "1";
+
+function writeReleaseTrap() {
+  process.stderr.write(
+    "npx @0xray/foundry release bumps, commits, pushes, and publishes the milled cwd.\n" +
+      "Pass --i-mean-it or set FOUNDRY_RELEASE=1. Preview with --dry-run.\n",
+  );
+}
+
+function run(cmd, label) {
+  console.log(`\n> ${cmd}`);
+  if (dryRun) {
+    console.log(`  (dry-run skip: ${label})`);
+    return;
+  }
+  execSync(cmd, {
+    cwd: rootDir,
+    stdio: "inherit",
+    encoding: "utf-8",
+    env: { ...process.env, FOUNDRY_ROOT: rootDir },
+  });
+}
+
+function runMill(script, extraArgs, label) {
+  const quoted = [millScript(script), ...extraArgs].map((a) => JSON.stringify(a)).join(" ");
+  run(`${JSON.stringify(process.execPath)} ${quoted}`, label);
+}
+
+function readVersion() {
+  return JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf-8")).version;
+}
+
+function packageName() {
+  const name = readRootPackage(rootDir).name;
+  if (!name) {
+    process.stderr.write("package.json name is required to mill publish\n");
+    process.exit(1);
+  }
+  return name;
+}
+
+function npmPublishCmd() {
+  const pkg = readRootPackage(rootDir);
+  if (isXrayExoRepo(rootDir) || pkg.name === "@0xray/foundry") {
+    return "npm publish --access public";
+  }
+  return "npm publish";
+}
+
+function currentBranch() {
+  return execSync("git rev-parse --abbrev-ref HEAD", { cwd: rootDir, encoding: "utf-8" }).trim();
+}
+
+function npmVersionPublished(version) {
+  try {
+    const out = execSync(`npm view ${packageName()}@${version} version`, {
+      cwd: rootDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return out === version;
+  } catch {
+    return false;
+  }
+}
+
+function publishIdempotent(version) {
+  if (dryRun) {
+    console.log(`  would: ${npmPublishCmd()} (check ${packageName()}@${version} first)`);
+    return;
+  }
+  if (npmVersionPublished(version)) {
+    console.log(`ℹ️  ${packageName()}@${version} already on npm — skipping publish`);
+    return;
+  }
+  execSync(npmPublishCmd(), { cwd: rootDir, stdio: "inherit", encoding: "utf-8" });
+  console.log(`✅ Published ${packageName()}@${version}`);
+}
+
+async function main() {
+  const live = (publishOnly || Boolean(releaseType)) && !dryRun;
+  if (live && !optedIn) {
+    writeReleaseTrap();
+    process.exit(1);
+  }
+
+  if (publishOnly) {
+    packageName();
+    const version = readVersion();
+    runMill("release-gate.mjs", [], "release gate");
+    if (isXrayExoRepo(rootDir)) {
+      run("npm run prepare-consumer && npm run build", "safe-publish");
+    } else if (readRootPackage(rootDir).scripts.build) {
+      run("npm run build", "build");
+    }
+    publishIdempotent(version);
+    if (!dryRun) {
+      try {
+        execSync(`git tag -a v${version} -m "Release v${version}"`, {
+          cwd: rootDir,
+          stdio: "inherit",
+        });
+      } catch (e) {
+        const msg = String(e.stderr || e.message || "");
+        if (!msg.includes("already exists")) throw e;
+      }
+    }
+    run(`git push origin v${version}`, "push tag");
+    return;
+  }
+
+  if (!releaseType || !["major", "minor", "patch"].includes(releaseType)) {
+    process.stderr.write(
+      "Usage: npx @0xray/foundry release [patch|minor|major] [--dry-run|--i-mean-it]\n",
+    );
+    process.stderr.write(
+      "       npx @0xray/foundry release --publish-only [--dry-run|--i-mean-it]\n",
+    );
+    process.exit(1);
+  }
+
+  console.log("╔════════════════════════════════════════════════════════╗");
+  console.log("║        🚀 0xRay Release (canonical)                   ║");
+  console.log("╚════════════════════════════════════════════════════════╝");
+  if (dryRun) console.log("\n⚠️  DRY RUN — no writes, commits, tags, or publish\n");
+
+  // 1. Version bump from npm SSOT
+  console.log(`\n📦 Step 1: Bump ${releaseType} from npm baseline`);
+  if (dryRun) {
+    runMill("reconcile-version.mjs", [releaseType], "version bump (dry)");
+  } else {
+    runMill("reconcile-version.mjs", [releaseType, "--apply"], "version bump");
+  }
+  const newVersion = dryRun
+    ? execSync(
+        `${JSON.stringify(process.execPath)} ${JSON.stringify(millScript("reconcile-version.mjs"))} ${JSON.stringify(releaseType)} --print-target`,
+        {
+          cwd: rootDir,
+          encoding: "utf-8",
+          env: { ...process.env, FOUNDRY_ROOT: rootDir },
+        },
+      ).trim()
+    : readVersion();
+  console.log(`📌 Release version: ${newVersion}`);
+
+  // 2. Artifacts BEFORE gate (docs vitest matches package.json version)
+  console.log("\n📦 Step 2: Release artifacts (CHANGELOG, README, AGENTS, docs)");
+  runMill("version-manager.mjs", ["--artifacts-only"], "release artifacts");
+
+  // 3. Gate
+  console.log("\n📦 Step 3: Release gate (build + test + smoke)");
+  runMill("release-gate.mjs", [], "release gate");
+
+  // 4. Commit + push
+  console.log("\n📦 Step 4: Commit & push");
+  const releaseFiles = getReleaseArtifactPaths();
+  if (!dryRun) {
+    run(`git add ${releaseFiles.join(" ")}`, "git add");
+    try {
+      execSync(`git commit --no-verify -m "release: v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
+    } catch (e) {
+      const out = String(e.stdout || e.stderr || "");
+      if (!out.includes("nothing to commit")) throw e;
+      console.log("ℹ️  Nothing to commit (release files unchanged)");
+    }
+  } else {
+    console.log(`  would: git add ${releaseFiles.join(" ")} && git commit -m "release: v${newVersion}"`);
+  }
+
+  const branch = currentBranch();
+  run(`git push origin ${branch}`, "git push");
+
+  // 5. Post-push verify before publish
+  console.log("\n📦 Step 5: Verify gate (reconcile + git + docs + smoke)");
+  runMill("release-gate.mjs", ["--verify-only"], "verify gate");
+
+  // 6. Publish (idempotent)
+  console.log("\n📦 Step 6: npm publish");
+  publishIdempotent(newVersion); // name from package.json via packageName()
+
+  // 7. Tag after publish
+  console.log("\n📦 Step 7: Tag");
+  if (!dryRun) {
+    try {
+      execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, { cwd: rootDir, stdio: "inherit" });
+      console.log(`✅ Created tag v${newVersion}`);
+    } catch (e) {
+      const msg = String(e.stderr || e.message || "");
+      if (msg.includes("already exists")) {
+        console.log(`ℹ️  Tag v${newVersion} already exists`);
+      } else {
+        throw e;
+      }
+    }
+  } else {
+    console.log(`  would: git tag -a v${newVersion}`);
+  }
+  run(`git push origin v${newVersion}`, "push tag");
+
+  console.log("\n╔════════════════════════════════════════════════════════╗");
+  console.log("║        ✅ Release Complete!                            ║");
+  console.log("╚════════════════════════════════════════════════════════╝");
+  if (!dryRun) {
+    process.stdout.write(`\n📦 ${packageName()}@${newVersion}  🏷  v${newVersion}\n`);
+    if (isXrayExoRepo(rootDir)) {
+      const tweetPath = path.join(rootDir, "tweets", `v${newVersion}.md`);
+      if (!fs.existsSync(tweetPath)) {
+        fs.mkdirSync(path.join(rootDir, "tweets"), { recursive: true });
+        fs.writeFileSync(
+          tweetPath,
+          `🎉 0xRay v${newVersion} is LIVE - consumer-safe upgrades!\n...\n\`\`\`\nnpm install 0xray@latest\n\`\`\`\n`,
+        );
+        process.stdout.write(`📝 Tweet template: tweets/v${newVersion}.md\n`);
+      }
+    }
+  }
+}
+
+const isMain =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  main().catch((err) => {
+    process.stderr.write(`\n❌ Release failed: ${err.message}\n`);
+    process.exit(1);
+  });
+}