quantum-forge 2.0.2

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "quantum-forge",
+  "version": "2.0.2",
+  "description": "Quantum Forge WASM loader, property manager, and Vite plugin for quantum game development (Qutrit Edition d3n12 + Qubit Edition d2n20). See LICENSE-BINARY.md for binary terms.",
+  "type": "module",
+  "exports": {
+    "./quantum": {
+      "types": "./dist/lib/quantum.d.ts",
+      "import": "./dist/lib/quantum.js"
+    },
+    "./logging": {
+      "types": "./dist/lib/logging.d.ts",
+      "import": "./dist/lib/logging.js"
+    },
+    "./vite-plugin": {
+      "types": "./dist/lib/vite-plugin.d.ts",
+      "import": "./dist/lib/vite-plugin.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "scripts/prepare.mjs",
+    "scripts/copy-quantum-forge.mjs",
+    "scripts/build-quantum-forge-variant.mjs",
+    "LICENSE.md",
+    "LICENSE-BINARY.md",
+    "LICENSING.md"
+  ],
+  "scripts": {
+    "prepare": "node scripts/prepare.mjs",
+    "build:lib": "tsup",
+    "build:quantum-forge": "cd ../../wrappers/web && npm install && npm run build:medium && cd ../../framework/packages/core && node scripts/copy-quantum-forge.mjs",
+    "build:quantum-forge:small": "cd ../../wrappers/web && npm install && npm run build:small && cd ../../framework/packages/core && node scripts/copy-quantum-forge.mjs",
+    "build:quantum-forge:custom": "cd ../../wrappers/web && npm install && npm run build:custom -- --max-dimension 3 --max-qudits 32 && npm run build && cd ../../framework/packages/core && node scripts/copy-quantum-forge.mjs",
+    "build:quantum-forge:variant": "node scripts/build-quantum-forge-variant.mjs"
+  },
+  "peerDependencies": {
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "quantum",
+    "quantum-forge",
+    "quantum-computing",
+    "wasm",
+    "webassembly",
+    "game",
+    "vite-plugin",
+    "qubit",
+    "qutrit",
+    "free"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quantum-native/quantum-forge.git"
+  },
+  "author": "Chris Cantwell",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/build-quantum-forge-variant.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+/**
+ * Build a named Quantum Forge WASM variant with custom dimension/qudit limits.
+ *
+ * Artifacts land in dist/quantum-forge-{name}/ so multiple configurations
+ * can coexist. The Vite plugin auto-discovers them.
+ *
+ * Usage:
+ *   node scripts/build-quantum-forge-variant.mjs --name d7n10 --max-dimension 7 --max-qudits 10
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, "..");
+
+// ---- Argument parsing ----
+
+const args = process.argv.slice(2);
+let name = "";
+let maxDimension = "";
+let maxQudits = "";
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--name" && args[i + 1]) {
+    name = args[i + 1];
+    i++;
+  } else if (args[i] === "--max-dimension" && args[i + 1]) {
+    maxDimension = args[i + 1];
+    i++;
+  } else if (args[i] === "--max-qudits" && args[i + 1]) {
+    maxQudits = args[i + 1];
+    i++;
+  } else if (args[i] === "--help" || args[i] === "-h") {
+    console.log(`Usage: node scripts/build-quantum-forge-variant.mjs [options]
+
+Options:
+  --name <string>          Variant name (lowercase alphanumeric + hyphens, e.g. "d7n10")
+  --max-dimension <number> Maximum quantum property dimension (>= 2)
+  --max-qudits <number>    Maximum number of qudits (>= 1)
+  --help, -h               Show this help message
+
+Example:
+  node scripts/build-quantum-forge-variant.mjs --name d7n10 --max-dimension 7 --max-qudits 10
+`);
+    process.exit(0);
+  }
+}
+
+// ---- Validation ----
+
+if (!name) {
+  console.error("❌ --name is required");
+  process.exit(1);
+}
+
+if (!maxDimension) {
+  console.error("❌ --max-dimension is required");
+  process.exit(1);
+}
+
+if (!maxQudits) {
+  console.error("❌ --max-qudits is required");
+  process.exit(1);
+}
+
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+if (!NAME_PATTERN.test(name)) {
+  console.error(`❌ Invalid variant name "${name}". Must match ${NAME_PATTERN} (e.g. "d7n10", "high-dim")`);
+  process.exit(1);
+}
+
+const RESERVED_NAMES = ["lib", "core", "packages", "systems", "src", "scripts", "esm", "cjs"];
+if (RESERVED_NAMES.includes(name)) {
+  console.error(`❌ "${name}" is a reserved name. Choose a different variant name.`);
+  process.exit(1);
+}
+
+const maxDimensionNum = parseInt(maxDimension, 10);
+const maxQuditsNum = parseInt(maxQudits, 10);
+
+if (isNaN(maxDimensionNum) || maxDimensionNum < 2) {
+  console.error("❌ --max-dimension must be a number >= 2");
+  process.exit(1);
+}
+
+if (isNaN(maxQuditsNum) || maxQuditsNum < 1) {
+  console.error("❌ --max-qudits must be a number >= 1");
+  process.exit(1);
+}
+
+// ---- Paths ----
+
+const webWrapperDir = path.join(ROOT, "..", "..", "..", "wrappers", "web");
+const cmakeBuildDir = path.join(webWrapperDir, "build");
+const esmOutputDir = path.join(webWrapperDir, "dist", "esm");
+const variantDir = path.join(ROOT, "dist", `quantum-forge-${name}`);
+
+// Artifacts to copy from the ESM build
+const ARTIFACTS = [
+  "quantum-forge-web-esm.mjs",
+  "quantum-forge-web-esm.wasm",
+  "quantum-forge-web-api.mjs",
+  "quantum-forge-web-api.d.mts",
+];
+
+// ---- Build ----
+
+function run(cmd, opts = {}) {
+  console.log(`> ${cmd}`);
+  execSync(cmd, { stdio: "inherit", ...opts });
+}
+
+function rmrf(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+console.log(`\n🔧 Building Quantum Forge variant "${name}"`);
+console.log(`   MAX_DIMENSION: ${maxDimension}`);
+console.log(`   MAX_QUDITS:    ${maxQudits}`);
+console.log(`   Output:        dist/quantum-forge-${name}/\n`);
+
+// Clean cmake build dir and esm output to force fresh build with new params
+console.log("🧹 Cleaning previous build artifacts...");
+rmrf(cmakeBuildDir);
+rmrf(esmOutputDir);
+
+// Run the WASM build via build-dist.js
+console.log("\n📦 Building WASM with custom parameters...");
+run(
+  `node scripts/build-dist.js --max-dimension ${maxDimension} --max-qudits ${maxQudits}`,
+  { cwd: webWrapperDir },
+);
+
+// Run tsup for TypeScript wrapper
+console.log("\n📦 Building TypeScript wrapper...");
+run("npx tsup", { cwd: webWrapperDir });
+
+// Copy artifacts to variant directory
+console.log(`\n📁 Copying artifacts to dist/quantum-forge-${name}/...`);
+if (!fs.existsSync(variantDir)) {
+  fs.mkdirSync(variantDir, { recursive: true });
+}
+
+let copied = 0;
+for (const file of ARTIFACTS) {
+  const src = path.join(esmOutputDir, file);
+  const dest = path.join(variantDir, file);
+  if (fs.existsSync(src)) {
+    fs.copyFileSync(src, dest);
+    console.log(`   ✅ ${file}`);
+    copied++;
+  } else {
+    console.warn(`   ⚠️  Not found: ${file}`);
+  }
+}
+
+if (copied === 0) {
+  console.error("\n❌ No artifacts were copied. Build may have failed.");
+  process.exit(1);
+}
+
+// ---- Done ----
+
+console.log(`\n🎉 Variant "${name}" built successfully!`);
+console.log(`\n📖 Usage in your game:\n`);
+console.log(`   import { useQuantumForgeBuild, ensureLoaded } from "@quantum-native/quantum-forge/quantum";`);
+console.log(`   useQuantumForgeBuild("${name}");`);
+console.log(`   await ensureLoaded();\n`);
+console.log(`   The Vite plugin will serve it automatically at /quantum-forge-${name}/\n`);

package/scripts/copy-quantum-forge.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+/**
+ * Copy quantum-forge build artifacts to dist directory
+ */
+import { copyFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+console.log("🔧 Copying Quantum Forge artifacts...");
+
+// Define source and destination paths
+const quantumSrcDir = "../../../wrappers/web/dist/esm";
+const distDir = "dist";
+
+// Check if quantum forge is built
+if (!existsSync(quantumSrcDir)) {
+  console.error(
+    "❌ Quantum Forge not built yet. Run 'npm run build:quantum-forge' first.",
+  );
+  console.error("   Build output not found at:", quantumSrcDir);
+  process.exit(1);
+}
+
+// Ensure dist directory exists
+if (!existsSync(distDir)) {
+  mkdirSync(distDir, { recursive: true });
+  console.log(`✅ Created directory: ${distDir}`);
+}
+
+// Files to copy from the ESM build directory
+const quantumFiles = [
+  "quantum-forge-web-esm.mjs",
+  "quantum-forge-web-esm.wasm",
+  "quantum-forge-web-api.mjs",
+  "quantum-forge-web-api.d.mts", // TypeScript definitions
+];
+
+// Copy to dist
+for (const file of quantumFiles) {
+  const srcPath = join(quantumSrcDir, file);
+  const destPath = join(distDir, file);
+
+  if (existsSync(srcPath)) {
+    copyFileSync(srcPath, destPath);
+    console.log(`✅ Copied ${file} to ${distDir}`);
+  } else {
+    console.warn(`⚠️  File not found: ${srcPath}`);
+  }
+}
+
+// Also copy type declarations to core/quantum/ so they ship with the package
+const typeDeclSrc = join(distDir, "quantum-forge-web-api.d.mts");
+const typeDeclDest = join("src", "quantum", "quantum-forge-api.d.mts");
+if (existsSync(typeDeclSrc)) {
+  copyFileSync(typeDeclSrc, typeDeclDest);
+  console.log(`✅ Copied type declarations to ${typeDeclDest}`);
+} else {
+  console.warn(`⚠️  Type declarations not found at ${typeDeclSrc}`);
+}
+
+console.log("🎉 Quantum Forge artifacts copied successfully!");

package/scripts/prepare.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+
+/**
+ * Smart prepare script for @quantum-native/quantum-forge
+ *
+ * When run in the dev repo (monorepo with wrappers present): builds TypeScript library only.
+ * When run as a dependency (installed via npm): builds TypeScript library, then
+ * downloads pre-built WASM artifacts from the matching GitHub release.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { spawnSync } from "child_process";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, "..");
+
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+};
+
+function log(message, color = "reset") {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function run(cmd, opts = {}) {
+  try {
+    const result = spawnSync("sh", ["-c", cmd], {
+      cwd: opts.cwd || ROOT,
+      env: { ...process.env, ...opts.env },
+      stdio: opts.stdio || "pipe",
+      encoding: "utf-8",
+      timeout: opts.timeout || 120_000,
+    });
+    return {
+      ok: result.status === 0,
+      stdout: (result.stdout || "").trim(),
+      stderr: (result.stderr || "").trim(),
+    };
+  } catch {
+    return { ok: false, stdout: "", stderr: "command failed" };
+  }
+}
+
+// ─── TypeScript library build ────────────────────────────────────────────────
+
+function buildLib() {
+  log("  Building TypeScript library...", "dim");
+  const result = run("npm run build:lib", { timeout: 60_000 });
+  if (!result.ok) {
+    log("  TypeScript build failed.", "red");
+    if (result.stderr) log(`  ${result.stderr}`, "red");
+    process.exit(1);
+  }
+  log("  TypeScript library built.", "green");
+}
+
+// ─── Dev detection ───────────────────────────────────────────────────────────
+
+function isDevRepo() {
+  // When installed as a dependency, INIT_CWD is the consumer's project dir
+  const initCwd = process.env.INIT_CWD;
+  if (initCwd && path.resolve(initCwd) !== ROOT) {
+    return false;
+  }
+  // ROOT is packages/core/, monorepo root is ../../.. (framework/../)
+  return fs.existsSync(
+    path.join(ROOT, "..", "..", "..", "wrappers"),
+  );
+}
+
+// ─── WASM file list ──────────────────────────────────────────────────────────
+
+const WASM_FILES = [
+  "quantum-forge-web-esm.mjs",
+  "quantum-forge-web-esm.wasm",
+  "quantum-forge-web-api.mjs",
+  "quantum-forge-web-api.d.mts",
+];
+
+function wasmFilesExist() {
+  const distDir = path.join(ROOT, "dist");
+  return WASM_FILES.every((f) => fs.existsSync(path.join(distDir, f)));
+}
+
+// ─── Repository info ─────────────────────────────────────────────────────────
+
+function getRepoInfo() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(ROOT, "package.json"), "utf-8"),
+    );
+    const url = pkg.repository?.url || "";
+    // Parse owner/repo from git URL formats:
+    //   git+ssh://git@github.com/owner/repo.git
+    //   https://github.com/owner/repo.git
+    //   git@github.com:owner/repo.git
+    const match = url.match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/);
+    if (match) {
+      return { owner: match[1], repo: match[2], version: pkg.version };
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+// ─── Release tag resolution ──────────────────────────────────────────────────
+
+function resolveTag(version) {
+  // Try exact tag at HEAD
+  const git = run("git describe --tags --exact-match HEAD 2>/dev/null");
+  if (git.ok && git.stdout.startsWith("v")) {
+    return git.stdout;
+  }
+
+  // Fall back to version from package.json
+  if (version) {
+    return `v${version}`;
+  }
+
+  return "latest";
+}
+
+// ─── WASM download: gh CLI (primary) ─────────────────────────────────────────
+
+function hasGhCli() {
+  return run("gh --version").ok;
+}
+
+function downloadWithGh(owner, repo, tag, distDir) {
+  // Try exact tag first
+  let result = run(
+    `gh release download "${tag}" --repo "${owner}/${repo}" --pattern "quantum-forge-web-*" --dir "${distDir}"`,
+    { timeout: 60_000 },
+  );
+  if (result.ok) return true;
+
+  // If exact tag fails, try latest
+  if (tag !== "latest") {
+    log(`  Release ${tag} not found, trying latest...`, "yellow");
+    result = run(
+      `gh release download --repo "${owner}/${repo}" --pattern "quantum-forge-web-*" --dir "${distDir}"`,
+      { timeout: 60_000 },
+    );
+    if (result.ok) return true;
+  }
+
+  return false;
+}
+
+// ─── WASM download: fetch API (fallback) ─────────────────────────────────────
+
+function getToken() {
+  return process.env.GITHUB_TOKEN || process.env.GH_TOKEN || null;
+}
+
+function getAuthHeaders() {
+  const token = getToken();
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "quantum-forge-prepare",
+  };
+  if (token) {
+    headers.Authorization = `token ${token}`;
+  }
+  return headers;
+}
+
+async function downloadWithFetch(owner, repo, tag, distDir) {
+  const headers = getAuthHeaders();
+
+  // Try exact tag first
+  const url =
+    tag === "latest"
+      ? `https://api.github.com/repos/${owner}/${repo}/releases/latest`
+      : `https://api.github.com/repos/${owner}/${repo}/releases/tags/${tag}`;
+
+  let response = await fetch(url, { headers });
+
+  // If exact tag fails, try latest
+  if (!response.ok && tag !== "latest") {
+    log(`  Release ${tag} not found, trying latest...`, "yellow");
+    const latestUrl = `https://api.github.com/repos/${owner}/${repo}/releases/latest`;
+    response = await fetch(latestUrl, { headers });
+  }
+
+  if (!response.ok) return false;
+
+  const release = await response.json();
+  let downloaded = 0;
+
+  for (const fileName of WASM_FILES) {
+    const asset = release.assets?.find((a) => a.name === fileName);
+    if (!asset) {
+      log(`  Asset not found in release: ${fileName}`, "yellow");
+      continue;
+    }
+
+    const dlHeaders = { ...getAuthHeaders(), Accept: "application/octet-stream" };
+    const dlResponse = await fetch(asset.url, { headers: dlHeaders });
+    if (!dlResponse.ok) {
+      log(`  Failed to download ${fileName}: ${dlResponse.status}`, "yellow");
+      continue;
+    }
+
+    const buffer = Buffer.from(await dlResponse.arrayBuffer());
+    fs.writeFileSync(path.join(distDir, fileName), buffer);
+    downloaded++;
+  }
+
+  return downloaded === WASM_FILES.length;
+}
+
+// ─── WASM download flow ─────────────────────────────────────────────────────
+
+async function downloadWasm() {
+  if (wasmFilesExist()) {
+    log("  WASM files already present in dist/, skipping download.", "green");
+    return;
+  }
+
+  const info = getRepoInfo();
+  if (!info) {
+    log("  Could not determine repository from package.json.", "yellow");
+    log("  Quantum features will not be available.", "yellow");
+    return;
+  }
+
+  const tag = resolveTag(info.version);
+  const distDir = path.join(ROOT, "dist");
+  if (!fs.existsSync(distDir)) {
+    fs.mkdirSync(distDir, { recursive: true });
+  }
+
+  log(`  Downloading WASM from ${info.owner}/${info.repo} release ${tag}...`, "cyan");
+
+  // Try gh CLI first (uses its own auth, works with private repos)
+  if (hasGhCli()) {
+    log("  Using gh CLI...", "dim");
+    if (downloadWithGh(info.owner, info.repo, tag, distDir)) {
+      if (wasmFilesExist()) {
+        log("  All WASM assets downloaded.", "green");
+        return;
+      }
+    }
+    log("  gh CLI download failed, trying fetch API...", "yellow");
+  }
+
+  // Fall back to fetch with GITHUB_TOKEN/GH_TOKEN
+  try {
+    if (await downloadWithFetch(info.owner, info.repo, tag, distDir)) {
+      log("  All WASM assets downloaded.", "green");
+      return;
+    }
+  } catch (err) {
+    log(`  Fetch failed: ${err.message}`, "yellow");
+  }
+
+  if (wasmFilesExist()) {
+    log("  WASM assets downloaded (partial methods).", "green");
+  } else {
+    log("  Could not download WASM assets.", "yellow");
+    log("  Quantum features will not be available.", "yellow");
+    log("  Ensure 'gh' is authenticated or set GITHUB_TOKEN.", "dim");
+  }
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  log("@quantum-native/quantum-forge — prepare", "bright");
+
+  if (isDevRepo()) {
+    log("  Dev repository detected (monorepo).", "dim");
+    buildLib();
+    return;
+  }
+
+  log("  Dependency install detected.", "dim");
+  // Library is pre-built in the published tarball — only download WASM
+  await downloadWasm();
+}
+
+main().catch((err) => {
+  log(`  Prepare error: ${err.message}`, "red");
+  // Don't exit(1) — non-quantum features should still work
+});