@needle-tools/gltf-build-pipeline 3.0.0-next.73f1606 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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] - 2026-06-23
+
+First stable 3.0 release. Summary of the headline changes across the 3.0 alpha/beta cycle.
+
+### Breaking
+- The CLI now requires JWT authentication via `--auth-token`. A missing, malformed, or expired token aborts the run with a clear message that includes the pipeline version.
+- The package ships as a CLI only.
+
+### Added
+- **Job cache**: a 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; already-lossy formats pass through unchanged.
+- **PMREM CLI command**: `needle-gltf pmrem <input>` converts EXR and Radiance HDR files to PMREM KTX2.
+- **Multiple file inputs**: `transform` accepts comma-separated paths (e.g. `needle-gltf transform a.glb,b.glb out/`).
+- **Diagnostic logging**: authentication failures (with secrets redacted) and pipeline errors — compression failures and unhandled exceptions — are written to a log file to make issues easier to diagnose.
+
+### Fixed
+- VRM thumbnails (and other textures referenced only through an opaque extension) no longer dangle to the wrong image after prune/dedup re-indexing. A stale `KHR_texture_basisu.source` could point past the end of the image array and crash three.js on load (`Cannot read properties of undefined (reading 'uri')`), or silently resolve to a neighbouring image. Re-running the pipeline on an already-compressed VRM is now covered by tests.
+- Audio URIs use forward slashes on every platform; on Windows a `path.join`-built clip path produced backslashes that loaders could not resolve (only affected audio in a subfolder).
+- 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 gated by `ensureHashReady`.
+- LOD file detection no longer matches against directory names.
+- toktx now probes the `ktx` binary to match what the compression step actually runs.
+- `getConfig` returns a fresh copy instead of a shared mutable reference.
+- `stats` tolerates undefined errors/warnings in `addFrom` and exits with code 0.
+- Material-only GLBs are no longer incorrectly pruned.
+- `createOpaqueExtension` return type fixed, downstream casts removed.
+
+## [3.0.0-beta.3] - 2026-06-10
+
+### Added
+- Pipeline errors (including compression failures and unhandled exceptions) are now written to the log file to aid diagnosis.
+
+## [3.0.0-beta.2] - 2026-06-10
+
+### Added
+- Authentication failures are now written to a log file (with secrets redacted) to make auth issues easier to diagnose.
+
+### Changed
+- The "Auth failed" message now includes the pipeline version.
+
+## [3.0.0-beta.1] - 2026-06-10
+
+### Fixed
+- VRM thumbnail (and other textures referenced only through an opaque extension) no longer dangle to the wrong image after prune/dedup re-indexing. When an image was deduped, an extension-carried `KHR_texture_basisu.source` was copied verbatim and left stale — the thumbnail's source could point past the end of the image array and crash three.js on load (`Cannot read properties of undefined (reading 'uri')`), while other affected textures silently resolved to a neighbouring image. Re-running the pipeline on an already-compressed VRM is now covered by tests.
+- Audio URIs now use forward slashes on every platform. On Windows the rewritten clip path was built with `path.join`, producing backslashes that loaders cannot resolve (only affected audio assets in a subfolder).
+
 ## [3.0.0-alpha] - 2026-05-26
 
 ### Breaking

package/dist/cli/index.js

@@ -8,7 +8,7 @@ import path5 from "path";
 import { Logger, NodeIO as NodeIO2, PropertyType as PropertyType12, Verbosity as Verbosity2 } from "@gltf-transform/core";
 import { ALL_EXTENSIONS as ALL_EXTENSIONS3 } from "@gltf-transform/extensions";
 import draco3d2 from "draco3dgltf";
-import { existsSync as existsSync11, readFileSync as readFileSync8, statSync as statSync5, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync8, statSync as statSync6, writeFileSync as writeFileSync6 } from "fs";
 import { MeshoptDecoder as MeshoptDecoder2, MeshoptEncoder as MeshoptEncoder3 } from "meshoptimizer";
 import { dedup as dedup2, metalRough as metalRough2, prune as prune2, resample } from "@gltf-transform/functions";
 
@@ -689,7 +689,11 @@ var GenericWriter = class {
     }
     this.debug && console.log("Could not find texture, creating a new one: " + this._debugName);
     let extensions = this.inputDefinition.extensions ? { ...this.inputDefinition.extensions } : void 0;
-    extensions && (delete extensions[NEEDLE_progressive_texture_settings.EXTENSION_NAME], extensions.EXT_texture_exr && this.inputObject.getMimeType() !== "image/exr" && delete extensions.EXT_texture_exr, Object.keys(extensions).length === 0 && (extensions = void 0));
+    if (extensions && (delete extensions[NEEDLE_progressive_texture_settings.EXTENSION_NAME], extensions.EXT_texture_exr && this.inputObject.getMimeType() !== "image/exr" && delete extensions.EXT_texture_exr, Object.keys(extensions).length === 0 && (extensions = void 0)), extensions)
+      for (let key of Object.keys(extensions)) {
+        let extDef = extensions[key];
+        extDef?.source !== void 0 && (extensions[key] = { ...extDef, source: imgIndex });
+      }
     let textureDef = {
       source: extensions && Object.keys(extensions).some((key) => extensions[key]?.source !== void 0) ? void 0 : imgIndex,
       sampler: this.findOrCreateSampler(context.jsonDoc.json),
@@ -1190,7 +1194,7 @@ function registerExtensions(node) {
 import { createTransform } from "@gltf-transform/functions";
 
 // src/utils/version.gen.ts
-var version = "3.0.0-next.73f1606";
+var version = "3.0.0";
 
 // src/utils/version.ts
 function getVersion(_marklocal = !0) {
@@ -3600,15 +3604,38 @@ function needle_audio_transform(options) {
 }
 function computeOpusOggUri(sourceUri) {
   let dir = dirname6(sourceUri), ext = extname(sourceUri), newName = `${basename3(sourceUri, ext)}.opus.ogg`;
-  return dir === "." || dir === "" ? newName : join6(dir, newName);
+  return (dir === "." || dir === "" ? newName : `${dir}/${newName}`).replaceAll("\\", "/");
+}
+
+// src/utils/logfile.ts
+import { appendFileSync, existsSync as existsSync11, mkdirSync as mkdirSync8, renameSync, statSync as statSync5 } from "fs";
+import { join as join7 } from "path";
+import { homedir } from "os";
+var LOG_DIR = join7(homedir(), ".needle", "optimization-pipeline", "logs"), LOG_FILE = join7(LOG_DIR, "pipeline.log"), PREV_LOG_FILE = join7(LOG_DIR, "pipeline.prev.log"), MAX_LOG_BYTES = 1024 * 1024;
+function redactSecrets(message) {
+  return message.replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]+@/gi, "$1").replace(/\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "[REDACTED_JWT]").replace(/\bnc_[A-Za-z0-9_-]{6,}\b/g, "[REDACTED_TOKEN]");
+}
+function logToFile(message) {
+  try {
+    mkdirSync8(LOG_DIR, { recursive: !0 });
+    try {
+      existsSync11(LOG_FILE) && statSync5(LOG_FILE).size > MAX_LOG_BYTES && renameSync(LOG_FILE, PREV_LOG_FILE);
+    } catch {
+    }
+    appendFileSync(LOG_FILE, `[${(/* @__PURE__ */ new Date()).toISOString()}] ${redactSecrets(message)}
+`);
+  } catch {
+  }
 }
 
 // src/scripts/pack-gltf.ts
 async function packGLTF(inputFile, outputFile, options) {
   options.logger || (options.logger = new Logger(Verbosity2.INFO));
   let { debug, stats, packedFiles, useCache, logger } = options;
-  if (!existsSync11(inputFile))
-    return logger.error(`WARN: can not pack, file does not exist: "${inputFile}"`), !1;
+  if (!existsSync12(inputFile)) {
+    let message = `WARN: can not pack, file does not exist: "${inputFile}"`;
+    return logger.error(message), logToFile(message), !1;
+  }
   let cacheKey;
   if (useCache && isMeshLOD(inputFile)) {
     let existing = readFileSync8(inputFile);
@@ -3624,7 +3651,7 @@ async function packGLTF(inputFile, outputFile, options) {
   try {
     let config = options.config;
     outputFile ? outputFile = getOutputPath(inputFile, outputFile) : outputFile = inputFile;
-    let prevSizeInMB = statSync5(inputFile).size / 1024 / 1024;
+    let prevSizeInMB = statSync6(inputFile).size / 1024 / 1024;
     logger.debug(`\u2192 Compressing ${prevSizeInMB.toFixed(1)} MB: ${inputFile}`);
     let startTime = Date.now(), io = new NodeIO2().registerExtensions(ALL_EXTENSIONS3).registerExtensions(ALL_EXTENSIONS).registerExtensions([
       NEEDLE_compression_texture,
@@ -3686,32 +3713,32 @@ async function packGLTF(inputFile, outputFile, options) {
         let uri = tex.getURI();
         if (uri && !uri.startsWith("data:")) {
           let absPath = path5.resolve(outDir, uri);
-          existsSync11(absPath) && options.externalFiles.push(absPath);
+          existsSync12(absPath) && options.externalFiles.push(absPath);
         }
       }
       for (let buf of root.listBuffers()) {
         let uri = buf.getURI();
         if (uri && !uri.startsWith("data:")) {
           let absPath = path5.resolve(outDir, uri);
-          existsSync11(absPath) && options.externalFiles.push(absPath);
+          existsSync12(absPath) && options.externalFiles.push(absPath);
         }
       }
       for (let ref of listAudioRefs()) {
         let uri = ref.newUri ?? ref.sourceUri, absPath = path5.resolve(outDir, uri);
-        existsSync11(absPath) && options.externalFiles.push(absPath);
+        existsSync12(absPath) && options.externalFiles.push(absPath);
       }
     }
-    logger.debug(`\u2190 Writing to ${outputFile}`), await writeNodeIO(io, outputFile, document), useCache && cacheKey != null && existsSync11(outputFile) && addToCache(cacheKey, readFileSync8(outputFile));
-    let duration = Date.now() - startTime, sizeInMB = statSync5(outputFile).size / 1024 / 1024, filename = path5.basename(outputFile), gpuMemoryInMB = totalGPUTextureMemory / 1024 / 1024;
+    logger.debug(`\u2190 Writing to ${outputFile}`), await writeNodeIO(io, outputFile, document), useCache && cacheKey != null && existsSync12(outputFile) && addToCache(cacheKey, readFileSync8(outputFile));
+    let duration = Date.now() - startTime, sizeInMB = statSync6(outputFile).size / 1024 / 1024, filename = path5.basename(outputFile), gpuMemoryInMB = totalGPUTextureMemory / 1024 / 1024;
     return logger.info(`\u2190 Compressed '${filename}' ${prevSizeInMB.toFixed(1)} MB \u2192 ${sizeInMB.toFixed(1)} MB (GPU: ${gpuMemoryInMB.toFixed(1)} MB textures) in ${(duration / 1e3).toFixed(1)} sec`), stats && (stats.totalFilesProcessed++, stats.totalFileSizeInMB += sizeInMB, stats.totalFileSizeInMBBefore += prevSizeInMB, stats.totalGPUMemoryInMB += gpuMemoryInMB), !0;
   } catch (err) {
     if (err instanceof TestAssertionError) throw err;
     let shortedStackTrace = err instanceof Error && err.stack ? err.stack.split(`
 `).slice(0, 2).join(`
-`) : "";
-    if (logger.error(`Packing of "${path5.basename(inputFile)}" using version ${getVersion()} failed with error:
+`) : "", message = `Packing of "${path5.basename(inputFile)}" using version ${getVersion()} failed with error:
 ${err instanceof Error ? err.message : String(err)}
-${shortedStackTrace}`), debug) throw err;
+${shortedStackTrace}`;
+    if (logger.error(message), logToFile(message), debug) throw err;
     return !1;
   }
 }
@@ -3733,7 +3760,7 @@ async function calculateStats(inputfile, options) {
 
 // src/config/index.ts
 import { Logger as Logger3, Verbosity as Verbosity4 } from "@gltf-transform/core";
-import { existsSync as existsSync12, readFileSync as readFileSync9, statSync as statSync6 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync9, statSync as statSync7 } from "fs";
 import path6, { dirname as dirname7, resolve as resolve2 } from "path";
 var UsecaseOptions = ["product", "world"], defaultConfig = {
   usecase: "default"
@@ -3748,9 +3775,9 @@ function createConfig(usecase) {
 function getConfig(configPath, fallbackSearchDirectory, opts) {
   let logger = opts?.logger;
   if (logger || (logger = new Logger3(Verbosity4.WARN)), configPath != null) {
-    if (configPath = resolve2(process.cwd(), configPath), !existsSync12(configPath))
+    if (configPath = resolve2(process.cwd(), configPath), !existsSync13(configPath))
       throw new Error(`No config found at "${configPath}"`);
-    if (statSync6(configPath).isDirectory()) {
+    if (statSync7(configPath).isDirectory()) {
       let res2 = searchConfig(configPath, logger);
       if (res2)
         return res2;
@@ -3771,9 +3798,9 @@ function getConfig(configPath, fallbackSearchDirectory, opts) {
 }
 var _cachedConfig;
 function searchConfig(directory, logger) {
-  for (statSync6(directory).isFile() && (directory = dirname7(directory)), directory = directory.replaceAll("\\", "/"); directory.length > 0; ) {
+  for (statSync7(directory).isFile() && (directory = dirname7(directory)), directory = directory.replaceAll("\\", "/"); directory.length > 0; ) {
     let configPath = path6.join(directory, "needle.config.json");
-    if (existsSync12(configPath)) {
+    if (existsSync13(configPath)) {
       let content = readFileSync9(configPath, "utf8"), config = resolveConfig(configPath, content, logger);
       if (config)
         return config;
@@ -3805,7 +3832,7 @@ function resolveConfig(filename, content, logger) {
 }
 
 // src/cli/index.ts
-import { existsSync as existsSync13, readFileSync as readFileSync10, readdirSync as readdirSync3, statSync as statSync7, writeFileSync as writeFileSync7 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync11, readdirSync as readdirSync3, statSync as statSync8, writeFileSync as writeFileSync7 } from "fs";
 import path7, { basename as basename4, dirname as dirname8, resolve as resolve3 } from "path";
 
 // src/constants.ts
@@ -3871,6 +3898,13 @@ function trackError(error, context) {
     return;
   }
   recentErrors.set(key, { time: now, count: (cached?.count || 0) + 1 });
+  let ctx = [
+    context?.mode && `mode=${context.mode}`,
+    context?.usecase && `usecase=${context.usecase}`,
+    context?.file && `file=${context.file}`
+  ].filter(Boolean).join(", ");
+  logToFile(`[error] ${errorName}: ${message}${ctx ? ` (${ctx})` : ""}${stack ? `
+${stack}` : ""}`);
   let properties = {
     version: getVersion(),
     error_name: errorName + (cached && cached.count > 1 ? ` x${cached.count}` : ""),
@@ -3922,23 +3956,42 @@ var PROD_KEYS = [
 var trusted = [...PROD_KEYS], TRUSTED_KEYS = trusted;
 
 // src/auth/verify.ts
+import { readFileSync as readFileSync10, existsSync as existsSync14 } from "fs";
+import { join as join9 } from "path";
+import { homedir as homedir2 } from "os";
 var AuthError = class extends Error {
   constructor(message) {
     super(message), this.name = "AuthError";
   }
 }, LOCAL_FETCH_TIMEOUT_MS = 2e3;
+function getLocalServerToken() {
+  try {
+    let file = join9(homedir2(), ".needle", "local-server-token");
+    if (!existsSync14(file)) return null;
+    let data = JSON.parse(readFileSync10(file, "utf-8"));
+    return typeof data.token == "string" ? data.token : null;
+  } catch (err) {
+    return logToFile(`[auth] failed reading local-server-token (${err instanceof Error ? err.name : "unknown error"})`), null;
+  }
+}
 async function tryFetchLocalToken(org) {
+  let baseUrl = process.env.NEEDLE_LICENSE_SERVER_URL || "http://localhost:8424/api/license", safeServer = "local license server";
   try {
-    let baseUrl = process.env.NEEDLE_LICENSE_SERVER_URL || "http://localhost:8424/api/license", url = new URL(baseUrl);
-    org && url.searchParams.set("org", org);
+    let url = new URL(baseUrl);
+    org && url.searchParams.set("org", org), safeServer = `${url.origin}${url.pathname}`;
+    let headers = {}, serverToken = getLocalServerToken();
+    serverToken && (headers.Authorization = `Bearer ${serverToken}`);
     let res = await fetch(url, {
-      signal: AbortSignal.timeout(LOCAL_FETCH_TIMEOUT_MS)
+      signal: AbortSignal.timeout(LOCAL_FETCH_TIMEOUT_MS),
+      headers
     });
-    if (!res.ok) return null;
+    if (!res.ok)
+      return logToFile(`[auth] license server (${safeServer}) returned HTTP ${res.status} ${res.statusText}${org ? ` \u2014 verify the --org value "${org}"` : ""}`), null;
     let jwt = (await res.json()).needle_license_jwt;
-    return typeof jwt == "string" && jwt.length > 0 ? jwt : null;
-  } catch {
-    return null;
+    return typeof jwt == "string" && jwt.length > 0 ? jwt : (logToFile(`[auth] license server (${safeServer}) responded without a license token${org ? ` for org "${org}"` : ""}`), null);
+  } catch (err) {
+    let msg = err instanceof Error ? err.message : String(err);
+    return logToFile(`[auth] could not reach license server (${safeServer})${org ? ` for org "${org}"` : ""}: ${msg}`), null;
   }
 }
 async function verifyWithKey(token, key) {
@@ -3983,21 +4036,31 @@ async function requireAuth(cliToken, org) {
   let token = typeof cliToken == "string" && cliToken.length > 0 ? cliToken : process.env.NEEDLE_CLOUD_TOKEN;
   if ((!token || typeof token == "string" && token.length === 0) && (token = await tryFetchLocalToken(org ?? process.env.NEEDLE_CLOUD_ORG)), !token)
     throw new AuthError(
-      "No valid auth token found. Provide one via --auth-token, NEEDLE_CLOUD_TOKEN env, or log in to the needle-cloud CLI (npx needle-cloud@version-1 start --restart). If you are logged in but still see this error, try updating: npx needle-cloud@version-1 start --restart"
+      "No valid auth token found. Provide one via --auth-token, NEEDLE_CLOUD_TOKEN env, or log in to the needle-cloud CLI (npx needle-cloud@version-2 start --restart). If you are logged in but still see this error, try updating: npx needle-cloud@version-2 start --restart"
     );
   await verifyAuthToken(token);
 }
 
 // src/cli/index.ts
+function warnUnknownOptions(options, logger) {
+  if (!process.env.NEEDLE_WORKER) return;
+  let knownKeys = new Set(Object.keys(options));
+  for (let arg of process.argv) {
+    if (!arg.startsWith("--")) continue;
+    let raw = arg.split("=")[0].replace(/^--/, ""), key = raw.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    knownKeys.has(key) || logger.warn(`[Needle Build Pipeline] v${getVersion()} Unknown option --${raw}, ignoring.`);
+  }
+}
 async function gateAuth(authToken, org, logger) {
   try {
     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);
+    logger.error(`[Needle Build Pipeline] v${getVersion()} Auth failed: ${message}`), logToFile(`[Needle Build Pipeline] v${getVersion()} Auth failed: ${message}`), process.exit(ERROR_CODES.AUTH_FAILED);
   }
 }
 program.cast(!1);
+process.env.NEEDLE_WORKER && program.strict(!1);
 program.command("version", "Print current version").action(async ({ logger }) => {
   logger.info(getVersion());
 }).command("clear-caches", "Clear all caches").help(`Clears all cached files
@@ -4005,8 +4068,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 }).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 + '"');
+`).argument("<input>", "Path to a glTF, GLB or VRM file OR a directory").argument("<output>", "Output path for the stats", { default: "", 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 }) => {
+  warnUnknownOptions(options, logger), 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 });
@@ -4017,9 +4080,9 @@ 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. 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.
+`).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: "", 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) {
+  if (warnUnknownOptions(options, logger), 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;
   }
@@ -4047,7 +4110,7 @@ When caching is enabled then previously processed files will be detected and loa
   }
   let set = /* @__PURE__ */ new Set(), useCache = options.cache !== !1, debug = options.debug === !0, verbose = options.verbose === !0;
   await foreachGLTF(inputPaths, async (file) => {
-    if (existsSync13(file)) {
+    if (existsSync15(file)) {
       if (file != input && options.progressive === !0 && isLOD(file)) {
         logger.debug(`\u2192 Ignore existing LOD file at ${file}`);
         return;
@@ -4063,12 +4126,12 @@ When caching is enabled then previously processed files will be detected and loa
       config
     }, file) : void 0;
     if (jobKey) {
-      let outputDir = output ? existsSync13(output) && isDirectory(output) ? output : dirname8(output) : dirname8(file), restored = tryRestoreJobResult(jobKey, outputDir, logger);
+      let outputDir = output ? existsSync15(output) && isDirectory(output) ? output : dirname8(output) : dirname8(file), restored = tryRestoreJobResult(jobKey, outputDir, logger);
       if (restored) {
-        let inputFileSize = statSync7(file).size / 1024 / 1024;
+        let inputFileSize = statSync8(file).size / 1024 / 1024;
         for (let f of restored)
           if (set.add(f), stats) {
-            let sizeInMB = statSync7(f).size / 1024 / 1024;
+            let sizeInMB = statSync8(f).size / 1024 / 1024;
             stats.totalFilesProcessed++, stats.totalFileSizeInMB += sizeInMB, stats.totalFileSizeInMBBefore += inputFileSize;
           }
         logger.info(`\u2192 [CACHE] Restored ${restored.length} file(s) for job ${jobKey}`);
@@ -4136,16 +4199,16 @@ 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 }).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();
+`).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: "", 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 }) => {
+  warnUnknownOptions(options, logger), 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));
+  existsSync15(input) || (logger.error(`Input does not exist: ${input}`), process.exit(ERROR_CODES.INVALID_ARGS));
   let inputFiles = [], inputIsDirectory = isDirectory(input);
   if (inputIsDirectory ? collectPmremInputFiles(input, inputFiles) : isPmremInputFile(input) ? inputFiles.push(input) : (logger.error(`Input is not an .exr/.hdr file or directory: ${input}`), process.exit(ERROR_CODES.INVALID_ARGS)), inputFiles.length === 0) {
     logger.warn(`No .exr/.hdr files found in ${input}`);
     return;
   }
-  let rawOutput = args.output?.toString() || null, outputArg = rawOutput && rawOutput !== "null" ? rawOutput : null;
+  let outputArg = args.output?.toString() || null;
   if (outputArg && !path7.isAbsolute(outputArg)) {
     let base = inputIsDirectory ? input : dirname8(input);
     outputArg = resolve3(base, outputArg);
@@ -4158,7 +4221,7 @@ raw .exr / .hdr inputs.
     for (let inPath of inputFiles) {
       let outPath = resolvePmremOutputPath(inPath, input, inputIsDirectory, outputArg);
       logger.info(`\u2192 pmrem ${inPath} \u2192 ${outPath}`);
-      let srcBytes = readFileSync10(inPath), bytes = new Uint8Array(srcBytes.buffer, srcBytes.byteOffset, srcBytes.byteLength), ktx2Bytes = await (inPath.toLowerCase().endsWith(".hdr") ? convertHdrBytesToPmremKtx2 : convertExrBytesToPmremKtx2)(
+      let srcBytes = readFileSync11(inPath), bytes = new Uint8Array(srcBytes.buffer, srcBytes.byteOffset, srcBytes.byteLength), ktx2Bytes = await (inPath.toLowerCase().endsWith(".hdr") ? convertHdrBytesToPmremKtx2 : convertExrBytesToPmremKtx2)(
         runtime,
         bytes,
         { useCache, logLabel: `pmrem ${basename4(inPath)}` }
@@ -4178,7 +4241,7 @@ function collectPmremInputFiles(dir, out) {
   for (let entry of readdirSync3(dir)) {
     if (entry === "node_modules" || entry.startsWith(".")) continue;
     let full = path7.join(dir, entry);
-    statSync7(full).isDirectory() ? collectPmremInputFiles(full, out) : isPmremInputFile(entry) && out.push(full);
+    statSync8(full).isDirectory() ? collectPmremInputFiles(full, out) : isPmremInputFile(entry) && out.push(full);
   }
 }
 function resolvePmremOutputPath(srcPath, input, inputIsDirectory, outputArg) {
@@ -4189,7 +4252,7 @@ function resolvePmremOutputPath(srcPath, input, inputIsDirectory, outputArg) {
     let rel = path7.relative(input, srcPath), relDir = dirname8(rel), outDir = relDir === "." ? outputArg : path7.join(outputArg, relDir);
     return ensureIsDirectory(outDir), path7.join(outDir, outName);
   }
-  return existsSync13(outputArg) && isDirectory(outputArg) ? path7.join(outputArg, outName) : outputArg.toLowerCase().endsWith(".ktx2") ? (ensureIsDirectory(dirname8(outputArg)), outputArg) : (ensureIsDirectory(outputArg), path7.join(outputArg, outName));
+  return existsSync15(outputArg) && isDirectory(outputArg) ? path7.join(outputArg, outName) : outputArg.toLowerCase().endsWith(".ktx2") ? (ensureIsDirectory(dirname8(outputArg)), outputArg) : (ensureIsDirectory(outputArg), path7.join(outputArg, outName));
 }
 program.run().catch((err) => {
   if (!(err.message.includes("Unknown command") && !err.message.includes("Did you mean")))

package/package.json

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