@needle-tools/gltf-build-pipeline 3.0.0-next.03f5d79 → 3.0.0-next.3fbb1fc

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [3.0.0-alpha] - 2026-05-26
+
+### Breaking
+- CLI now requires JWT authentication via `--auth-token`
+- The package ships as a CLI-only right now
+
+### Added
+- **Job cache**: file-level cache that skips an entire transform when the same input + config was already processed
+- **Audio compression**: external audio references are re-encoded to Opus/OGG; supported input formats are WAV, FLAC, and AIFF (lossy formats pass through unchanged)
+- **PMREM standalone CLI command**: `needle-gltf pmrem <input>` converts EXR and Radiance HDR files to PMREM KTX2
+- **Multiple file inputs**: `transform` now accepts comma-separated paths (e.g. `needle-gltf transform a.glb,b.glb out/`)
+- Auth surfaces clean "token expired" message when the JWT `exp` claim is past
+
+### Fixed
+- Cache restore now also restores external files (KTX2, PMREM) alongside the main GLB
+- PMREM NaN generation that caused artifacts in certain EXR files
+- xxHash WASM init race condition, now resolved with `ensureHashReady` gate
+- LOD file detection no longer matches against directory names
+- toktx: probes `ktx` binary to match what the compression step actually runs
+- `getConfig` now returns a fresh copy instead of a shared mutable reference
+- `stats` tolerates undefined errors/warnings in `addFrom`
+- Material-only GLBs are no longer incorrectly pruned
+- `createOpaqueExtension` return type fixed, downstream casts removed
+- `stats` command exits with code 0
+
 ## [2.15.0] - 2026-03-20
 - add: EXR environment map compression (PMREM / FASTHDR) for Needle Engine, supporting both Unity and Blender exports
 - fix: cache hashing stability (circular reference handling)

package/README.md

@@ -61,7 +61,7 @@ The `gltf` value may also be a string shorthand for `usecase` — `"gltf": "prod
 | `usecase` | `"default" \| "product" \| "world"` | `"default"` | High-level optimisation profile. |
 | `textures.lods` | `boolean` | `true` | Generate progressive texture LODs. |
 | `meshes.lods` | `boolean` | `true` | Generate progressive mesh LODs. |
-| `audio.enabled` | `boolean` | `true` | Compress externally referenced `.wav` audio files to Opus in an `.ogg` container, rewriting the URIs in the glTF. Lossy formats (`.mp3`, `.ogg`, `.m4a`, `.aac`) pass through unchanged to avoid compounding compression artifacts. Requires `ffmpeg` with `libopus` on `PATH`; when missing the build logs a warning and leaves the audio files untouched. |
+| `audio.enabled` | `boolean` | `true` | Compress externally referenced lossless audio files (`.wav`, `.flac`, `.aiff`/`.aif`) to Opus in an `.ogg` container, rewriting the URIs in the glTF. Lossy formats (`.mp3`, `.ogg`, `.m4a`, `.aac`) pass through unchanged to avoid compounding compression artifacts. Requires `ffmpeg` with `libopus` on `PATH`; when missing the build logs a warning and leaves the audio files untouched. |
 | `audio.bitrate` | `number` (kbps) | `128` | Opus encoding bitrate. 96 is near-transparent for most music; 128 matches YouTube's music tier and is the safe "won't sound bad" default. Drop to 48–64 for known mono/UI-only assets. |
 | `exr.enabled` | `boolean` | `true` | Convert EXR textures to KTX2 HDR via PMREM. When `false`, EXR textures (bundled and externally referenced) are left as-is so a downstream step can handle them. |
 

package/dist/cli/index.js

@@ -138,7 +138,7 @@ function listAudioRefs() {
 function clearAudioRegistry() {
   _refs = [];
 }
-var AUDIO_EXTENSIONS = [".wav"], _audioRegex = new RegExp(`(${AUDIO_EXTENSIONS.map((e) => "\\" + e).join("|")})$`, "i");
+var AUDIO_EXTENSIONS = [".wav", ".flac", ".aiff", ".aif"], _audioRegex = new RegExp(`(${AUDIO_EXTENSIONS.map((e) => "\\" + e).join("|")})$`, "i");
 function isAudioUri(value) {
   return _audioRegex.test(value);
 }
@@ -1190,7 +1190,7 @@ function registerExtensions(node) {
 import { createTransform } from "@gltf-transform/functions";
 
 // src/utils/version.gen.ts
-var version = "3.0.0-next.03f5d79";
+var version = "3.0.0-next.3fbb1fc";
 
 // src/utils/version.ts
 function getVersion(_marklocal = !0) {
@@ -1406,6 +1406,11 @@ function getFileName(filepath) {
   let parts = filepath.replaceAll("\\", "/").split("/");
   return parts[parts.length - 1];
 }
+function parseInputPaths(raw) {
+  if (!raw.includes(",")) return [raw];
+  let segments = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return segments.length < 2 ? [raw] : !segments.some((s) => existsSync3(s)) && existsSync3(raw) ? [raw] : segments;
+}
 async function foreachGLTF(args, callback) {
   let initDir = process.env.INIT_CWD, context = {
     baseDirectory: initDir,
@@ -3896,7 +3901,7 @@ function trackPipelineEnd(info) {
 }
 
 // src/auth/verify.ts
-import { jwtVerify, importJWK } from "jose";
+import { jwtVerify, importJWK, decodeProtectedHeader } from "jose";
 
 // src/auth/keys.ts
 var PROD_KEYS = [
@@ -3921,28 +3926,51 @@ var AuthError = class extends Error {
   constructor(message) {
     super(message), this.name = "AuthError";
   }
-};
+}, LOCAL_LICENSE_URL = "http://localhost:8424/api/license", LOCAL_FETCH_TIMEOUT_MS = 2e3;
+async function tryFetchLocalToken(org) {
+  try {
+    let url = new URL(LOCAL_LICENSE_URL);
+    org && url.searchParams.set("org", org);
+    let res = await fetch(url, {
+      signal: AbortSignal.timeout(LOCAL_FETCH_TIMEOUT_MS)
+    });
+    if (!res.ok) return null;
+    let jwt = (await res.json()).needle_license_jwt;
+    return typeof jwt == "string" && jwt.length > 0 ? jwt : null;
+  } catch {
+    return null;
+  }
+}
+async function verifyWithKey(token, key, opts) {
+  if (!key.alg) throw new AuthError(`trusted key '${key.kid ?? "?"}' is missing 'alg'`);
+  let keyObj = await importJWK(key, key.alg);
+  await jwtVerify(token, keyObj, opts?.requireExp ? { requiredClaims: ["exp"] } : void 0);
+}
 async function verifyAuthToken(token) {
   if (!token)
     throw new AuthError("no token provided");
   if (token.startsWith("nc_"))
     throw new AuthError("NEEDLE_CLOUD_TOKEN is a needle-cloud access token (nc_*), not a JWT.");
   try {
-    await jwtVerify(token, async (header) => {
-      if (!header.kid)
-        throw new AuthError("token header missing 'kid'");
+    let header = decodeProtectedHeader(token);
+    if (header.kid) {
       let match = TRUSTED_KEYS.find((k) => k.kid === header.kid);
       if (!match)
         throw new AuthError(`token signed by unknown key '${header.kid}'`);
-      if (!match.alg)
-        throw new AuthError(`trusted key '${header.kid}' is missing 'alg'`);
-      return importJWK(match, match.alg);
-    }, {
-      // jose checks `exp` automatically when present; requiredClaims forces
-      // the issuer to include it. A token without `exp` would otherwise
-      // verify as never-expiring.
-      requiredClaims: ["exp"]
-    });
+      await verifyWithKey(token, match, { requireExp: !0 });
+    } else {
+      let lastError = null;
+      for (let key of TRUSTED_KEYS)
+        try {
+          await verifyWithKey(token, key);
+          return;
+        } catch (err) {
+          lastError = err;
+        }
+      if (lastError instanceof AuthError) throw lastError;
+      let message = lastError instanceof Error ? lastError.message : String(lastError);
+      throw new AuthError(message || "no trusted key could verify this token");
+    }
   } catch (err) {
     if (err instanceof AuthError) throw err;
     if (err && typeof err == "object" && "code" in err) {
@@ -3956,17 +3984,17 @@ async function verifyAuthToken(token) {
     throw new AuthError(message);
   }
 }
-async function requireAuth(cliToken) {
+async function requireAuth(cliToken, org) {
   let token = typeof cliToken == "string" && cliToken.length > 0 ? cliToken : process.env.NEEDLE_CLOUD_TOKEN;
-  if (!token)
-    throw new AuthError("pass --auth-token or set NEEDLE_CLOUD_TOKEN");
+  if ((!token || typeof token == "string" && token.length === 0) && (token = await tryFetchLocalToken(org ?? process.env.NEEDLE_CLOUD_ORG)), !token)
+    throw new AuthError("pass --auth-token or set NEEDLE_CLOUD_TOKEN (or log in to the needle-cloud CLI)");
   await verifyAuthToken(token);
 }
 
 // src/cli/index.ts
-async function gateAuth(authToken, logger) {
+async function gateAuth(authToken, org, logger) {
   try {
-    await requireAuth(authToken);
+    await requireAuth(authToken, typeof org == "string" ? org : void 0);
   } catch (err) {
     let message = err instanceof AuthError || err instanceof Error ? err.message : String(err);
     logger.error(`[Needle Build Pipeline] Auth failed: ${message}`), process.exit(ERROR_CODES.AUTH_FAILED);
@@ -3980,8 +4008,8 @@ Caches are limited to ${cacheSizeLimit} MB disc space by default.
 `).action(async ({ logger }) => {
   logger.info("Clearing caches"), clearCache(logger);
 }).command("stats", "Calculate glTF stats").help(`
-`).argument("<input>", "Path to a glTF, GLB or VRM file OR a directory").argument("<output>", "Output path for the stats", { default: null, validator: program.STRING }).option("--verbose", "Enable verbose output", { validator: program.BOOLEAN, default: !1 }).option("--auth-token <jwt>", "Required. A JWT minted by needle-cloud (alternatively set NEEDLE_CLOUD_TOKEN). Note: an `nc_*` needle-cloud access token is NOT a JWT and will be rejected.", { validator: program.STRING }).action(async ({ logger, args, options }) => {
-  await gateAuth(options.authToken, logger), logger.level = options.verbose ? "debug" : "info", await ensureHashReady(), logger.info('Calculating stats for "' + args.input + '"');
+`).argument("<input>", "Path to a glTF, GLB or VRM file OR a directory").argument("<output>", "Output path for the stats", { default: null, validator: program.STRING }).option("--verbose", "Enable verbose output", { validator: program.BOOLEAN, default: !1 }).option("--auth-token <jwt>", "Required. A JWT minted by needle-cloud (alternatively set NEEDLE_CLOUD_TOKEN). Note: an `nc_*` needle-cloud access token is NOT a JWT and will be rejected.", { validator: program.STRING }).option("--org <org>", "Organization ID for local license-server fallback (or set NEEDLE_CLOUD_ORG).", { validator: program.STRING }).action(async ({ logger, args, options }) => {
+  await gateAuth(options.authToken, options.org, logger), logger.level = options.verbose ? "debug" : "info", await ensureHashReady(), logger.info('Calculating stats for "' + args.input + '"');
   let input = args.input.toString(), filestats = new Array();
   await foreachGLTF(input, async (file) => {
     let stats = await calculateStats(file, { verbose: !!options.verbose });
@@ -3992,13 +4020,15 @@ Caches are limited to ${cacheSizeLimit} MB disc space by default.
 }).command("transform", "Transform (progressive loading) and compress glTF, GLB or VRM files").help(`
 This will produce multiple versions of the input file, each with a different level of optimization.   
 Each version will be compressed and written to the output directory.
-`).argument("<input>", "The input glTF, GLB or VRM file that should be compressed OR a directory that contains files to be compressed", { validator: program.STRING }).argument("<output>", "The output file or directory. It can be an absolute path or a relative path to the input file. If not provided, the input file will be overwritten.", { default: null, validator: program.STRING }).option("--compress", "When enabled files will be compressed", { validator: program.BOOLEAN, default: !0 }).option("--progressive", "When enabled files will processed to be progressively loaded", { validator: program.BOOLEAN, default: !0 }).option("--usecase <usecase>", `The usecase for the compression. This will set the compression settings. Possible options: [${UsecaseOptions.join(", ")}]`, { validator: program.STRING }).option("--config <config>", 'The path to a JSON file containing the compression settings. This can also be a needle.config.json file with a "compression" object or usecase string.', { validator: program.STRING }).option("--cache", `Use "--cache False" to disable caching.
-When caching is enabled then previously processed files will be detected and loaded from disc cache instead of being processed again if settings or the file contents have not changed.`, { validator: program.BOOLEAN, default: !0 }).option("--debug", 'Enable for more verbose outout with "--debug True"', { validator: program.BOOLEAN, default: !1 }).option("--verbose", 'Enable for more verbose outout with "--verbose True"', { validator: program.BOOLEAN, default: !1 }).option("--auth-token <jwt>", "Required. A JWT minted by needle-cloud (alternatively set NEEDLE_CLOUD_TOKEN). Note: an `nc_*` needle-cloud access token is NOT a JWT and will be rejected.", { validator: program.STRING }).action(async ({ logger, args, options }) => {
-  if (await gateAuth(options.authToken, logger), logger.level = options.debug || options.verbose ? "debug" : "info", options.compress === !1 && options.progressive === !1) {
+`).argument("<input>", "The input glTF, GLB or VRM file that should be compressed OR a directory that contains files to be compressed. Multiple files can be separated by commas.", { validator: program.STRING }).argument("<output>", "The output file or directory. It can be an absolute path or a relative path to the input file. If not provided, the input file will be overwritten.", { default: null, validator: program.STRING }).option("--compress", "When enabled files will be compressed", { validator: program.BOOLEAN, default: !0 }).option("--progressive", "When enabled files will processed to be progressively loaded", { validator: program.BOOLEAN, default: !0 }).option("--usecase <usecase>", `The usecase for the compression. This will set the compression settings. Possible options: [${UsecaseOptions.join(", ")}]`, { validator: program.STRING }).option("--config <config>", 'The path to a JSON file containing the compression settings. This can also be a needle.config.json file with a "compression" object or usecase string.', { validator: program.STRING }).option("--cache", `Use "--cache False" to disable caching.
+When caching is enabled then previously processed files will be detected and loaded from disc cache instead of being processed again if settings or the file contents have not changed.`, { validator: program.BOOLEAN, default: !0 }).option("--debug", 'Enable for more verbose outout with "--debug True"', { validator: program.BOOLEAN, default: !1 }).option("--verbose", 'Enable for more verbose outout with "--verbose True"', { validator: program.BOOLEAN, default: !1 }).option("--auth-token <jwt>", "Required. A JWT minted by needle-cloud (alternatively set NEEDLE_CLOUD_TOKEN). Note: an `nc_*` needle-cloud access token is NOT a JWT and will be rejected.", { validator: program.STRING }).option("--org <org>", "Organization ID for local license-server fallback (or set NEEDLE_CLOUD_ORG).", { validator: program.STRING }).action(async ({ logger, args, options }) => {
+  if (await gateAuth(options.authToken, options.org, logger), logger.level = options.debug || options.verbose ? "debug" : "info", options.compress === !1 && options.progressive === !1) {
     logger.error(`[Needle Build Pipeline] v${getVersion()} You need to enable at least one of the options: --compress or --progressive`);
     return;
   }
-  await ensureHashReady(), logger.info(`[Needle Build Pipeline] v${getVersion()} \u2014 Transform '${args.input}'`);
+  await ensureHashReady();
+  let inputPaths = parseInputPaths(args.input.toString()), input = inputPaths[0], isMultiInput = inputPaths.length > 1;
+  logger.info(`[Needle Build Pipeline] v${getVersion()} \u2014 Transform ${isMultiInput ? `${inputPaths.length} files` : `'${input}'`}`);
   let pipelineMode = [options.progressive && "progressive", options.compress && "compress"].filter(Boolean).join("+");
   trackPipelineStart({ mode: pipelineMode, usecase: options.usecase?.toString() });
   let stats = {
@@ -4007,19 +4037,19 @@ When caching is enabled then previously processed files will be detected and loa
     totalFilesProcessed: 0,
     totalFileSizeInMB: 0,
     totalFileSizeInMBBefore: 0
-  }, input = args.input.toString(), config = getConfig(options.config?.toString(), input, {
+  }, config = getConfig(options.config?.toString(), input, {
     logger
   });
   options.usecase && (logger.info("Using usecase: " + options.usecase), config = { ...createConfig(options.usecase.toString()), ...config }, config.usecase != "default" && config.usecase != options.usecase.toString() ? logger.warn(`Conflicting usecase. Your specific config at "${options.config}" has a different usecase than the one provided by the CLI: "${options.usecase}". Using the usecase from the config file.`) : config.usecase = options.usecase.toString());
-  let inputIsDirectory = isDirectory(input), output = args.output?.toString();
-  !inputIsDirectory && !output && (output = input);
+  let inputIsDirectory = !isMultiInput && isDirectory(input), output = args.output?.toString();
+  isMultiInput && output && !isDirectory(output) && (logger.error("When <input> contains multiple files then <output> must be a directory"), trackError(new Error("Invalid args: multi-input but output is not a directory"), { mode: pipelineMode }), process.exit(ERROR_CODES.INVALID_ARGS)), !inputIsDirectory && !isMultiInput && !output && (output = input);
   let outputIsDirectory = output && isDirectory(output);
   if (inputIsDirectory && output && !outputIsDirectory && (logger.error("When <input> is a directory then <output> must also be a directory"), trackError(new Error("Invalid args: input is directory but output is not"), { mode: pipelineMode }), process.exit(ERROR_CODES.INVALID_ARGS)), output && path7.isAbsolute(output) === !1) {
     let base = ensureIsDirectory(input);
     output = resolve3(base, output);
   }
   let set = /* @__PURE__ */ new Set(), useCache = options.cache !== !1, debug = options.debug === !0, verbose = options.verbose === !0;
-  await foreachGLTF(input, async (file) => {
+  await foreachGLTF(inputPaths, async (file) => {
     if (existsSync13(file)) {
       if (file != input && options.progressive === !0 && isLOD(file)) {
         logger.debug(`\u2192 Ignore existing LOD file at ${file}`);
@@ -4109,8 +4139,8 @@ When caching is enabled then previously processed files will be detected and loa
 producing <name>.pmrem.ktx2. This is the same processing the Needle build pipeline
 applies to EXR textures inside GLB/GLTF files, exposed as a standalone command for
 raw .exr / .hdr inputs.
-`).argument("<input>", "Path to a .exr/.hdr file OR a directory containing .exr/.hdr files (recursive)", { validator: program.STRING }).argument("<output>", "Output file (when input is a single .exr/.hdr) or output directory. Defaults to writing next to the input file.", { default: null, validator: program.STRING }).option("--cache", 'Use "--cache False" to disable caching.', { validator: program.BOOLEAN, default: !0 }).option("--debug", 'Enable verbose output with "--debug True"', { validator: program.BOOLEAN, default: !1 }).option("--verbose", 'Enable verbose output with "--verbose True"', { validator: program.BOOLEAN, default: !1 }).option("--auth-token <jwt>", "Required. A JWT minted by needle-cloud (alternatively set NEEDLE_CLOUD_TOKEN). Note: an `nc_*` needle-cloud access token is NOT a JWT and will be rejected.", { validator: program.STRING }).hide().action(async ({ logger, args, options }) => {
-  await gateAuth(options.authToken, logger), logger.level = options.debug || options.verbose ? "debug" : "info", await ensureHashReady();
+`).argument("<input>", "Path to a .exr/.hdr file OR a directory containing .exr/.hdr files (recursive)", { validator: program.STRING }).argument("<output>", "Output file (when input is a single .exr/.hdr) or output directory. Defaults to writing next to the input file.", { default: null, validator: program.STRING }).option("--cache", 'Use "--cache False" to disable caching.', { validator: program.BOOLEAN, default: !0 }).option("--debug", 'Enable verbose output with "--debug True"', { validator: program.BOOLEAN, default: !1 }).option("--verbose", 'Enable verbose output with "--verbose True"', { validator: program.BOOLEAN, default: !1 }).option("--auth-token <jwt>", "Required. A JWT minted by needle-cloud (alternatively set NEEDLE_CLOUD_TOKEN). Note: an `nc_*` needle-cloud access token is NOT a JWT and will be rejected.", { validator: program.STRING }).option("--org <org>", "Organization ID for local license-server fallback (or set NEEDLE_CLOUD_ORG).", { validator: program.STRING }).hide().action(async ({ logger, args, options }) => {
+  await gateAuth(options.authToken, options.org, logger), logger.level = options.debug || options.verbose ? "debug" : "info", await ensureHashReady();
   let input = args.input.toString();
   existsSync13(input) || (logger.error(`Input does not exist: ${input}`), process.exit(ERROR_CODES.INVALID_ARGS));
   let inputFiles = [], inputIsDirectory = isDirectory(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/gltf-build-pipeline",
-  "version": "3.0.0-next.03f5d79",
+  "version": "3.0.0-next.3fbb1fc",
   "description": "Pipeline and tools for optimizing gltf files using gltf-transform and compression settings within glTF extensions",
   "type": "module",
   "exports": {