@gorilla-engine-sdk/gorilla-engine-scripts 1.3.4

package/lib/assets.js

@@ -0,0 +1,188 @@
+import { copyFile, mkdir, readdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import {
+  assertNoSymlinksWithinBase,
+  resolveExistingWithinBase,
+  resolveWithinBase,
+  ts,
+} from './utils.js';
+import { getDeployFunction } from './crypto.js';
+
+/**
+ * Recursively syncs a source directory to a destination, removing entries that
+ * no longer exist in the source.
+ */
+export async function syncAssetPath(sourcePath, destPath, destinationRoot = destPath) {
+  try {
+    const sourceEntries = await readdir(sourcePath, { withFileTypes: true });
+    await assertNoSymlinksWithinBase(destinationRoot, destPath);
+    await mkdir(destPath, { recursive: true });
+    await assertNoSymlinksWithinBase(destinationRoot, destPath);
+
+    const sourceNames = new Set();
+    for (const sourceEntry of sourceEntries) {
+      if (sourceEntry.isSymbolicLink()) {
+        throw new Error(`Refusing to deploy symbolic link "${path.join(sourcePath, sourceEntry.name)}"`);
+      }
+      sourceNames.add(sourceEntry.name);
+      const childSourcePath = path.join(sourcePath, sourceEntry.name);
+      const childDestPath = path.join(destPath, sourceEntry.name);
+      if (sourceEntry.isDirectory()) {
+        await syncAssetPath(childSourcePath, childDestPath, destinationRoot);
+      } else {
+        await assertNoSymlinksWithinBase(destinationRoot, childDestPath);
+        await mkdir(path.dirname(childDestPath), { recursive: true });
+        await copyFile(childSourcePath, childDestPath);
+      }
+    }
+
+    const destEntries = await readdir(destPath, { withFileTypes: true });
+    for (const destEntry of destEntries) {
+      if (!sourceNames.has(destEntry.name)) {
+        const staleDestPath = path.join(destPath, destEntry.name);
+        await assertNoSymlinksWithinBase(destinationRoot, staleDestPath);
+        await rm(staleDestPath, { recursive: true, force: true });
+      }
+    }
+  } catch (error) {
+    if (error.code !== 'ENOTDIR') throw error;
+    // sourcePath is a file but destPath is a directory (or vice versa) — replace it
+    await assertNoSymlinksWithinBase(destinationRoot, destPath);
+    await rm(destPath, { recursive: true, force: true });
+    await mkdir(path.dirname(destPath), { recursive: true });
+    await copyFile(sourcePath, destPath);
+  }
+}
+
+function resolvePresetDestPath(outputFolder, presetPath) {
+  const normalizedPresetPath = presetPath.replaceAll('\\', '/');
+  const pathParts = normalizedPresetPath.split('/').filter(Boolean);
+  const presetsPartIndex = pathParts.findIndex((part) => part.toLowerCase() === 'presets');
+
+  if (presetsPartIndex >= 0) {
+    const relativePresetPath = pathParts.slice(presetsPartIndex + 1);
+    return resolveWithinBase(outputFolder, 'Presets', ...relativePresetPath);
+  }
+
+  return resolveWithinBase(outputFolder, 'Presets', path.basename(normalizedPresetPath));
+}
+
+async function deployContentFiles(ugepFolder, destinationRoot, entries, resolveDestPath) {
+  for (const { path: sourcePath } of entries) {
+    const unresolvedSourcePath = resolveWithinBase(ugepFolder, sourcePath);
+    const contentDestPath = resolveDestPath(sourcePath);
+    if (!existsSync(unresolvedSourcePath)) {
+      await assertNoSymlinksWithinBase(destinationRoot, contentDestPath);
+      await rm(contentDestPath, { recursive: true, force: true });
+      continue;
+    }
+    const contentSourcePath = await resolveExistingWithinBase(ugepFolder, sourcePath);
+    await syncAssetPath(contentSourcePath, contentDestPath, destinationRoot);
+  }
+}
+
+export function deployAssetFilesToOutput({ ugepContent, ugepFolder, outputRoot, outputFolder }) {
+  return deployContentFiles(
+    ugepFolder,
+    outputRoot ?? outputFolder,
+    ugepContent.assetFiles ?? [],
+    (assetPath) => {
+      const assetDestPath = resolveWithinBase(outputFolder, assetPath);
+      if (assetDestPath === path.resolve(outputFolder)) {
+        throw new Error('Refusing to synchronize assets to the plugin output root');
+      }
+      return assetDestPath;
+    },
+  );
+}
+
+export function deployPresetFilesToOutput({ ugepContent, ugepFolder, outputRoot, outputFolder }) {
+  return deployContentFiles(
+    ugepFolder,
+    outputRoot ?? outputFolder,
+    ugepContent.presets ?? [],
+    (presetPath) => resolvePresetDestPath(outputFolder, presetPath),
+  );
+}
+
+/** Encrypts/copies the built JS + YAML + asset files to the plugin output folder. */
+export async function deployAll(config) {
+  const { ugepContent, ugepFolder, outputRoot, outputFolder, pluginName } = config;
+  const deployFn = await getDeployFunction(config);
+  const promises = [];
+
+  if (ugepContent.ymlFiles?.length > 0) {
+    const yamlSourcePath = await resolveExistingWithinBase(
+      ugepFolder,
+      ugepContent.ymlFiles[0].path,
+    );
+    const yamlDestPath = resolveWithinBase(outputFolder, `${pluginName}.yaml`);
+    await assertNoSymlinksWithinBase(outputRoot ?? outputFolder, yamlDestPath);
+    promises.push(deployFn(yamlSourcePath, yamlDestPath));
+  }
+
+  const scriptDestPath = resolveWithinBase(outputFolder, `${pluginName}.js`);
+  await assertNoSymlinksWithinBase(outputRoot ?? outputFolder, scriptDestPath);
+  promises.push(deployFn(`./esbuild/${pluginName}.js`, scriptDestPath));
+  promises.push(deployAssetFilesToOutput(config));
+  promises.push(deployPresetFilesToOutput(config));
+
+  await Promise.all(promises);
+}
+
+/**
+ * Manages debounced asset deployment triggered by file-system watch events.
+ * Exposes a `suppressWatcher` flag used by InstrumentExporter to avoid
+ * double-deploying when it writes new blobs.
+ */
+export class AssetDeployer {
+  suppressWatcher = false;
+
+  #config;
+  #standaloneManager;
+  #timer = null;
+  #inProgress = false;
+  #rerun = false;
+
+  constructor(config, standaloneManager) {
+    this.#config = config;
+    this.#standaloneManager = standaloneManager;
+  }
+
+  schedule() {
+    clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      void this.#run();
+    }, 250);
+  }
+
+  clearTimer() {
+    clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+
+  async #run() {
+    if (this.#inProgress) {
+      this.#rerun = true;
+      return;
+    }
+    this.#inProgress = true;
+    try {
+      console.log(`[${ts()}] Asset changes detected - deploying`);
+      await deployAssetFilesToOutput(this.#config);
+      await deployPresetFilesToOutput(this.#config);
+      console.log(`[${ts()}] Asset deploy finished\n`);
+      if (this.#config.flags.standalone) await this.#standaloneManager.restart();
+    } catch (error) {
+      console.error(`[${ts()}] Asset deploy failed: ${error.message}`);
+    } finally {
+      this.#inProgress = false;
+      if (this.#rerun) {
+        this.#rerun = false;
+        void this.#run();
+      }
+    }
+  }
+}

package/lib/build.js

@@ -0,0 +1,77 @@
+import * as esbuild from 'esbuild';
+import esbuildPluginTsc from 'esbuild-plugin-tsc';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const externalizeNativeAddonsPlugin = {
+  name: 'externalize-native-addons',
+  setup(build) {
+    build.onResolve({ filter: /\.node$/ }, (args) => ({
+      path: args.path,
+      external: true,
+    }));
+
+    build.onResolve({ filter: /^[^./]/ }, async (args) => {
+      if (args.pluginData?.externalizeNativeAddons) return;
+
+      const result = await build.resolve(args.path, {
+        importer: args.importer,
+        kind: args.kind,
+        namespace: args.namespace,
+        resolveDir: args.resolveDir,
+        pluginData: {
+          ...args.pluginData,
+          externalizeNativeAddons: true,
+        },
+      });
+
+      if (result.path.endsWith('.node')) {
+        return {
+          path: args.path,
+          external: true,
+        };
+      }
+    });
+  },
+};
+
+/**
+ * Creates an esbuild incremental build context for the plugin.
+ * @param {object} config - Resolved plugin config
+ * @param {object} callbacks
+ * @param {() => void} callbacks.onBuildStarted  - Called when a build begins
+ * @param {() => Promise<void>} callbacks.onBuildFinished - Called when a build ends
+ */
+export async function createBuildContext(config, { onBuildStarted, onBuildFinished }) {
+  const { flags, ugepFolder, pluginName } = config;
+
+  return esbuild.context({
+    entryPoints: [flags.entryPoint],
+    minify: false,
+    outfile: path.resolve(ugepFolder, `./esbuild/${pluginName}.js`),
+    bundle: true,
+    sourcemap: 'inline',
+    sourceRoot: pathToFileURL(path.resolve(ugepFolder, 'esbuild') + path.sep).toString(),
+    platform: 'node',
+    alias: {
+      // Prevent esbuild from bundling react — it must be resolved at runtime.
+      // See: https://stackoverflow.com/a/31170775 & https://esbuild.github.io/api/#alias
+      react: 'react',
+    },
+    plugins: [
+      externalizeNativeAddonsPlugin,
+      esbuildPluginTsc({
+        force: true,
+        tsx: true,
+        tsconfigPath: path.resolve(ugepFolder, 'tsconfig.json'),
+      }),
+      {
+        name: 'build-events',
+        setup({ onEnd, onStart }) {
+          onEnd(onBuildFinished);
+          onStart(onBuildStarted);
+        },
+      },
+    ],
+  });
+}

package/lib/cli.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+
+export function printUsage(exit) {
+  let programName;
+  if (/node(?:.exe)?$/.test(process.argv[0])) {
+    programName = `node ${path.basename(process.argv[1])}`;
+  } else {
+    programName = path.basename(process.argv[0]);
+  }
+
+  console.log(`
+Usage:
+    ${programName} --ugep <ugep-file> --entry-point <js-entry-point-file>
+
+${programName} will encrypt and deploy files for use with GE-Shell.
+Example:
+${programName} --ugep my-plugin.ugep --entry-point src/index.tsx
+
+ -u, --ugep <FILE>            Deploy JS, node_modules and YAML according to ugep file
+ -e, --entry-point <FILE>     The JS entry point file
+ -1, --one-shot               Build once, do not watch for changes
+  --build-ui-only          With --one-shot, build only the UI bundle
+  --sync-instruments-only  With --one-shot, sync only instrument blobs and typings
+ -nd, --no-deploy             Do not deploy to the plugin folder
+ -s, --standalone             Start/restart the standalone app after each deploy and stop it on exit
+    `);
+  if (typeof exit !== 'undefined') {
+    process.exit(exit);
+  }
+}
+
+export function getFlags() {
+  const scriptFlags = process.argv.slice(2);
+  let currentArg;
+  const flags = { deploy: true };
+
+  while ((currentArg = scriptFlags.shift())) {
+    if (!currentArg.startsWith('-')) {
+      console.log('Unknown option:', currentArg);
+      printUsage(1);
+    } else if (currentArg === '-h' || currentArg === '--help') {
+      printUsage(0);
+    } else if (currentArg === '-u' || currentArg === '--ugep') {
+      flags.ugepFile = scriptFlags.shift();
+      if (!existsSync(flags.ugepFile)) {
+        console.error(`ugep file does not exist`);
+        process.exit(2);
+      }
+    } else if (currentArg === '-e' || currentArg === '--entry-point') {
+      flags.entryPoint = scriptFlags.shift();
+      if (!existsSync(flags.entryPoint)) {
+        console.error(`entry point file does not exist`);
+        process.exit(2);
+      }
+    } else if (currentArg === '-1' || currentArg === '--one-shot' || currentArg === '--oneshot') {
+      flags.oneShot = true;
+    } else if (currentArg === '--build-ui-only') {
+      flags.buildUiOnly = true;
+    } else if (currentArg === '--sync-instruments-only') {
+      flags.syncInstrumentsOnly = true;
+    } else if (currentArg === '-nd' || currentArg === '--no-deploy') {
+      flags.deploy = false;
+    } else if (currentArg === '-s' || currentArg === '--standalone') {
+      flags.standalone = true;
+    } else {
+      console.log('Unknown option:', currentArg);
+      printUsage(1);
+    }
+  }
+
+  if (!flags.ugepFile || !flags.entryPoint) {
+    console.error(`ERROR: --ugep|-u AND --entry-point|-e are mandatory`);
+    printUsage(1);
+  }
+
+  if (flags.buildUiOnly && flags.syncInstrumentsOnly) {
+    console.error(`ERROR: --build-ui-only and --sync-instruments-only cannot be combined`);
+    printUsage(1);
+  }
+
+  if ((flags.buildUiOnly || flags.syncInstrumentsOnly) && !flags.oneShot) {
+    console.error(`ERROR: --build-ui-only and --sync-instruments-only require --one-shot`);
+    printUsage(1);
+  }
+
+  return flags;
+}

package/lib/config.js

@@ -0,0 +1,122 @@
+import * as path from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+export const isMac = process.platform === 'darwin';
+
+/**
+ * Ensures a ugep-supplied name is a single, safe path segment (no separators,
+ * no ".."), since it is used to build the output folder path that is later
+ * recursively chown'd/synced.
+ */
+function assertSafeName(value, label) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value.includes('/') ||
+    value.includes('\\') ||
+    value === '.' ||
+    value === '..'
+  ) {
+    throw new Error(
+      `Invalid ${label} "${value}" in ugep file: must be a non-empty name without path separators or "..".`,
+    );
+  }
+  return value;
+}
+
+function canRunBlobExportFromPath() {
+  const result = spawnSync('blob-export', ['-h'], { stdio: 'ignore' });
+  return !result.error;
+}
+
+function resolveBlobExport() {
+  const defaultPath = isMac
+    ? '/Applications/Gorilla Engine SDK/Tools/blob-export'
+    : `${process.env['SystemDrive']}\\Program Files\\Gorilla Engine SDK\\Tools\\blob-export.exe`;
+
+  if (existsSync(defaultPath)) {
+    return {
+      blobExportPath: defaultPath,
+      blobExportAvailable: true,
+      blobExportDefaultPath: defaultPath,
+    };
+  }
+
+  if (canRunBlobExportFromPath()) {
+    return {
+      blobExportPath: 'blob-export',
+      blobExportAvailable: true,
+      blobExportDefaultPath: defaultPath,
+    };
+  }
+
+  return {
+    blobExportPath: 'blob-export',
+    blobExportAvailable: false,
+    blobExportDefaultPath: defaultPath,
+  };
+}
+
+/**
+ * Creates a resolved configuration object from CLI flags and ugep file content.
+ * @param {object} flags - Parsed CLI flags
+ * @param {object} ugepContent - Parsed ugep JSON content
+ */
+export function createConfig(flags, ugepContent) {
+  const ugepFolder = path.dirname(flags.ugepFile);
+  const { name: pluginName, manufacturer: manufacturerName } = ugepContent.pluginConfig;
+  assertSafeName(pluginName, 'pluginConfig.name');
+  assertSafeName(manufacturerName, 'pluginConfig.manufacturer');
+  const { blobExportPath, blobExportAvailable, blobExportDefaultPath } = resolveBlobExport();
+
+  const instrumentSourceFolder = path.resolve(ugepFolder, 'instrument');
+  const instrumentAssetFolder = path.resolve(
+    ugepFolder,
+    ugepContent.assetFiles.find(
+      ({ name, path: assetPath }) =>
+        name === 'instruments' || /(?:^|[\\/])instruments$/.test(assetPath),
+    )?.path ?? 'assets/instruments',
+  );
+  const assetSourceFolders = [
+    ...new Set(
+      (ugepContent.assetFiles ?? []).map(({ path: assetPath }) =>
+        path.resolve(ugepFolder, assetPath),
+      ),
+    ),
+  ];
+  const presetSourceFolders = [
+    ...new Set(
+      (ugepContent.presets ?? []).map(({ path: presetPath }) =>
+        path.resolve(ugepFolder, presetPath),
+      ),
+    ),
+  ];
+  const generatedInstrumentTypesPath = path.resolve(
+    ugepFolder,
+    'src/generated/gorilla-instrument-types.d.ts',
+  );
+  const outputRoot = isMac
+    ? '/Library/Application Support'
+    : `${process.env['SystemDrive']}/ProgramData`;
+  const outputFolder = path.join(outputRoot, manufacturerName, pluginName);
+
+  return {
+    flags,
+    ugepContent,
+    ugepFolder,
+    pluginName,
+    manufacturerName,
+    instrumentSourceFolder,
+    instrumentAssetFolder,
+    assetSourceFolders,
+    presetSourceFolders,
+    blobExportPath,
+    blobExportAvailable,
+    blobExportDefaultPath,
+    generatedInstrumentTypesPath,
+    outputRoot,
+    outputFolder,
+    isMac,
+  };
+}

package/lib/crypto.js

@@ -0,0 +1,59 @@
+import { randomBytes, createCipheriv, createSign } from 'node:crypto';
+import { copyFile, readFile, writeFile } from 'node:fs/promises';
+import { resolveExistingWithinBase, ts } from './utils.js';
+
+const algorithm = 'aes-128-gcm';
+
+function encrypt(plaintext, key) {
+  const iv = randomBytes(16);
+  const cipher = createCipheriv(algorithm, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, encrypted]);
+}
+
+function sign(data, privateKey) {
+  const signer = createSign('RSA-SHA256');
+  signer.update(data);
+  const signature = signer.sign(privateKey);
+  return Buffer.concat([signature, data]);
+}
+
+async function encryptFile(src, dest, key, privateKey) {
+  const srcContent = await readFile(src);
+  await writeFile(dest, sign(encrypt(srcContent, key), privateKey));
+}
+
+/**
+ * Returns a function that either copies or encrypts+signs a file, depending on
+ * whether devRelease mode is enabled in the plugin config.
+ * @param {object} config - Resolved plugin config
+ */
+export async function getDeployFunction(config) {
+  const { pluginConfig } = config.ugepContent;
+
+  if (pluginConfig.devRelease_1c327a6c414fa896 === true) {
+    return (src, dest) => {
+      console.log(`[${ts()}] Copying ${src} to ${dest}`);
+      return copyFile(src, dest);
+    };
+  }
+
+  const keyPath = await resolveExistingWithinBase(
+    config.ugepFolder,
+    pluginConfig.installerOutputDir,
+    'jsEncryptionKey.bin',
+  );
+  const privateKeyPath = await resolveExistingWithinBase(
+    config.ugepFolder,
+    pluginConfig.installerOutputDir,
+    'signingPrivateKey.pem',
+  );
+  const key = await readFile(keyPath);
+  const privateKey = await readFile(privateKeyPath);
+
+  return (src, dest) => {
+    console.log(`[${ts()}] Encrypting ${src} to ${dest}`);
+    return encryptFile(src, dest, key, privateKey);
+  };
+}

package/lib/installer.js

@@ -0,0 +1,28 @@
+import { realpathSync, statSync } from 'node:fs';
+import * as path from 'node:path';
+import { assertSafePathSegment, resolveWithinBase } from './utils.js';
+
+export function resolveInstallerPath(ugepFile, pluginConfig, extension) {
+  const installerName = pluginConfig.installerNameTemplate
+    .replace('{manufacturer}', pluginConfig.manufacturer)
+    .replace('{name}', pluginConfig.name)
+    .replace('{version}', pluginConfig.version);
+  assertSafePathSegment(installerName, 'installer name');
+  assertSafePathSegment(extension, 'installer extension');
+
+  const ugepDir = path.dirname(path.resolve(ugepFile));
+  const installerDir = resolveWithinBase(
+    ugepDir,
+    pluginConfig.installerOutputDir || 'installer',
+  );
+  const installerPath = resolveWithinBase(installerDir, `${installerName}.${extension}`);
+
+  const realUgepDir = realpathSync(ugepDir);
+  const realInstallerPath = realpathSync(installerPath);
+  resolveWithinBase(realUgepDir, path.relative(realUgepDir, realInstallerPath));
+  if (!statSync(realInstallerPath).isFile()) {
+    throw new Error(`Installer is not a regular file: ${installerPath}`);
+  }
+
+  return { installerName, installerPath: realInstallerPath };
+}