quantum-forge 2.6.5 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quantum-forge",
-  "version": "2.6.5",
+  "version": "2.7.0",
   "description": "Quantum Forge WASM loader, property manager, and Vite plugin for quantum game development (Qutrit Edition d3n12 + Qubit Edition d2n20).",
   "type": "module",
   "exports": {
@@ -17,8 +17,12 @@
       "import": "./dist/lib/vite-plugin.js"
     }
   },
+  "bin": {
+    "quantum-forge": "scripts/cli.mjs"
+  },
   "files": [
     "dist/",
+    "scripts/cli.mjs",
     "scripts/prepare.mjs",
     "scripts/copy-quantum-forge.mjs",
     "scripts/build-quantum-forge-variant.mjs",

package/quantum-forge-sw.js

@@ -20,7 +20,7 @@
 // published. An unprocessed copy falls back to "dev", which still works — the
 // fetch handler revalidates in the background, so a deployment cannot pin old
 // artifacts forever even when the cache name never changes.
-const QF_VERSION = "2.6.5";
+const QF_VERSION = "2.7.0";
 
 // Scope the cache to this registration so two Quantum Forge games served from
 // the same origin (e.g. /game1/ and /game2/ on GitHub Pages) cannot delete

package/scripts/cli.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+
+/**
+ * The `quantum-forge` command.
+ *
+ * The CLI itself (init, add-system, validate, doctor) lives in the engine
+ * package: scaffolding needs the engine's templates and its vendored example.
+ * npx resolves a command by package name, so `npx quantum-forge init` fetched
+ * this package, found no executable, and died with "could not determine
+ * executable to run". This file is that executable. It hands every argument
+ * to the engine CLI:
+ *
+ *   1. An engine installed next to this package (a project's node_modules,
+ *      or the monorepo checkout) runs in this process.
+ *   2. Otherwise `npm exec` fetches the engine and runs its CLI, exactly as
+ *      `npx quantum-forge-engine ...` would.
+ *
+ * Both spellings therefore work everywhere:
+ *
+ *   npx quantum-forge init my-game
+ *   npx quantum-forge-engine init my-game
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { spawnSync } from "child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(__dirname, "..");
+
+function readPackageName() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_DIR, "package.json"), "utf-8"));
+    if (typeof pkg.name === "string" && pkg.name) return pkg.name;
+  } catch {
+    // fall through to the public name
+  }
+  return "quantum-forge";
+}
+
+// "quantum-forge" -> "quantum-forge-engine", and the scoped name to its scoped
+// sibling, so a GitHub Packages install never reaches for the public registry.
+const ENGINE = `${readPackageName()}-engine`;
+const ENGINE_CLI = path.join("scripts", "init.mjs");
+
+/**
+ * The engine's CLI script, if an engine is installed where this command can
+ * see it. The engine's `exports` map hides scripts/ from import resolution,
+ * so this walks the filesystem the way Node's resolver would.
+ */
+function findLocalEngineCli() {
+  const candidates = [];
+
+  // The project the command runs in, walking up to the filesystem root.
+  let dir = process.cwd();
+  for (;;) {
+    candidates.push(path.join(dir, "node_modules", ENGINE, ENGINE_CLI));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // The node_modules this package sits in: one level up for an unscoped
+  // install, two for a scoped one.
+  const scoped = path.basename(path.dirname(PACKAGE_DIR)).startsWith("@");
+  const modulesRoot = scoped ? path.dirname(path.dirname(PACKAGE_DIR)) : path.dirname(PACKAGE_DIR);
+  candidates.push(path.join(modulesRoot, ENGINE, ENGINE_CLI));
+
+  // The monorepo checkout: packages/core next to packages/engine.
+  candidates.push(path.join(path.dirname(PACKAGE_DIR), "engine", ENGINE_CLI));
+
+  return candidates.find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+/**
+ * How to invoke npm without a shell, so there is nothing to quote on Windows.
+ * npm and npx set `npm_execpath` for the processes they launch; pnpm and Yarn
+ * set it too, pointing at their own CLIs, which do not understand `npm exec`,
+ * so only npm's own files are accepted. Without it, npm sits next to the Node
+ * binary (or under libexec for Homebrew). On Unix the `npm` on PATH is a plain
+ * script, so it can be spawned by name as a last resort; on Windows it is a
+ * .cmd file that needs a shell, which is exactly what this avoids.
+ */
+function npmCommand() {
+  const candidates = [];
+  const execpath = process.env.npm_execpath;
+  if (execpath) {
+    const base = path.basename(execpath);
+    if (base === "npm-cli.js") candidates.push(execpath);
+    if (base === "npx-cli.js") candidates.push(path.join(path.dirname(execpath), "npm-cli.js"));
+  }
+  const nodeDir = path.dirname(process.execPath);
+  candidates.push(
+    // Windows: node.exe and node_modules/npm side by side.
+    path.join(nodeDir, "node_modules", "npm", "bin", "npm-cli.js"),
+    // Unix: bin/node next to lib/node_modules/npm.
+    path.join(nodeDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+    // Homebrew: the Cellar keeps npm under libexec.
+    path.join(nodeDir, "..", "libexec", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+  );
+  const cli = candidates.find((candidate) => fs.existsSync(candidate));
+  if (cli) return { file: process.execPath, prefix: [cli] };
+  if (process.platform !== "win32") return { file: "npm", prefix: [] };
+  return null;
+}
+
+const args = process.argv.slice(2);
+const localCli = findLocalEngineCli();
+
+if (localCli) {
+  // Same process, same argv: the engine CLI reads process.argv itself.
+  await import(pathToFileURL(localCli).href);
+} else {
+  const direct = `npx ${ENGINE} ${args.join(" ")}`.trim();
+  const npm = npmCommand();
+  if (!npm) {
+    process.stderr.write(
+      `quantum-forge: the CLI ships in ${ENGINE}, and npm could not be located to fetch it.\n` +
+        `Run it directly: ${direct}\n`,
+    );
+    process.exit(1);
+  }
+  process.stderr.write(`quantum-forge: the CLI ships in ${ENGINE}; fetching it with npm exec...\n`);
+  // `npm exec -- <pkg> [args]` runs the package's only bin, whatever it is
+  // named, and downloads the package first when it is not installed.
+  const result = spawnSync(npm.file, [...npm.prefix, "exec", "--yes", "--", ENGINE, ...args], {
+    stdio: "inherit",
+  });
+  if (result.error) {
+    process.stderr.write(
+      `quantum-forge: could not run npm (${result.error.message}).\nRun it directly: ${direct}\n`,
+    );
+    process.exit(1);
+  }
+  process.exit(result.status ?? 1);
+}