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

package/lib/instruments.js

@@ -0,0 +1,355 @@
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+import { ts } from './utils.js';
+import { deployAssetFilesToOutput } from './assets.js';
+
+function toTypeIdentifier(value) {
+  const identifier = value
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join('');
+
+  if (!identifier) return 'Instrument';
+  return /^\d/.test(identifier) ? `Instrument${identifier}` : identifier;
+}
+
+function toUnionLines(values, indent) {
+  if (values.length === 0) {
+    return [`${indent}never;`];
+  }
+
+  return values.map((value, index) => {
+    const suffix = index === values.length - 1 ? ';' : '';
+    return `${indent}| ${JSON.stringify(value)}${suffix}`;
+  });
+}
+
+function toLowerCaseNames(values) {
+  return [...new Set(values.map((value) => value.toLowerCase()))];
+}
+
+function toRuntimeParamKey(value) {
+  return value.toLowerCase();
+}
+
+function normalizeParameterInfo(parameterInfo) {
+  const seenNames = new Set();
+
+  return parameterInfo.filter((parameter) => {
+    if (!parameter || typeof parameter.name !== 'string' || typeof parameter.path !== 'string') {
+      return false;
+    }
+    if (seenNames.has(parameter.name)) {
+      return false;
+    }
+    seenNames.add(parameter.name);
+    return true;
+  });
+}
+
+function extractJsonArray(stdout, instrumentPath) {
+  const start = stdout.indexOf('[');
+  const end = stdout.lastIndexOf(']');
+
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`${path.basename(instrumentPath)} parameter info did not contain a JSON array`);
+  }
+
+  return stdout.slice(start, end + 1);
+}
+
+export function parseBlobExportCapabilities(helpOutput) {
+  const versionMatch = helpOutput.match(/Blob Export\s*-\s*Version:\s*([^\r\n]+)/i);
+  return {
+    version: versionMatch?.[1].trim() ?? 'unknown',
+    supportsParameterInfo: /(?:^|\s)--parameter-info(?:\s|$)/m.test(helpOutput),
+  };
+}
+
+async function getBlobExportCapabilities(blobExportPath, cwd) {
+  const helpOutput = await new Promise((resolve, reject) => {
+    let output = '';
+    const child = spawn(blobExportPath, ['-h'], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    child.stdout.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    child.on('error', reject);
+    child.on('exit', () => resolve(output));
+  });
+
+  return parseBlobExportCapabilities(helpOutput);
+}
+
+async function getInstrumentParameterInfo(blobExportPath, instrumentPath, cwd) {
+  const stdout = await new Promise((resolve, reject) => {
+    let output = '';
+    let errors = '';
+    const child = spawn(blobExportPath, ['--parameter-info', instrumentPath], {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+
+    child.stdout.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      errors += chunk.toString();
+    });
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve(output);
+        return;
+      }
+
+      const details = errors.trim() || output.trim();
+      reject(
+        new Error(
+          `${path.basename(blobExportPath)} failed to read parameter info for ${path.basename(instrumentPath)}${details ? `: ${details}` : ''}`,
+        ),
+      );
+    });
+  });
+
+  return normalizeParameterInfo(JSON.parse(extractJsonArray(stdout, instrumentPath)));
+}
+
+export function generateInstrumentTypes(instrumentDefinitions) {
+  const lines = [
+    '// This file is auto-generated by @gorilla-engine-sdk/gorilla-engine-scripts.',
+    '// Do not edit manually.',
+    '',
+    'export {};',
+    '',
+    'declare global {',
+    '  namespace GorillaEngine {',
+    '    namespace Runtime {',
+  ];
+
+  const allParams = [];
+  const pSeen = new Set();
+  for (const instrument of instrumentDefinitions) {
+    for (const parameter of instrument.parameters) {
+      const name = toRuntimeParamKey(parameter.name);
+      if (!pSeen.has(name)) {
+        pSeen.add(name);
+        allParams.push(name);
+      }
+    }
+  }
+
+  lines.push('      type ParamName =');
+  lines.push(...toUnionLines(allParams, '        '));
+  lines.push('');
+
+  lines.push('      interface ParameterMap {');
+  for (const name of allParams) {
+    lines.push(`        ${JSON.stringify(name)}: GorillaEngine.InstrumentProperty;`);
+  }
+  lines.push('      }');
+  lines.push('');
+
+  lines.push('      type Instrument = GorillaEngine.Instrument & ParameterMap;');
+  lines.push('');
+
+  lines.push(
+    '      type DynamicInstrument = GorillaEngine.Instrument & Partial<ParameterMap> & Record<string, GorillaEngine.InstrumentProperty | undefined>;',
+  );
+
+  lines.push('    }');
+  lines.push('  }');
+  lines.push('}');
+  lines.push('');
+
+  return `${lines.join('\n')}`;
+}
+
+async function writeInstrumentTypesFile(generatedInstrumentTypesPath, instrumentDefinitions) {
+  await mkdir(path.dirname(generatedInstrumentTypesPath), { recursive: true });
+  await writeFile(
+    generatedInstrumentTypesPath,
+    generateInstrumentTypes(instrumentDefinitions),
+    'utf8',
+  );
+}
+
+export async function runBlobExport(blobExportPath, instrumentPath, blobOutputPath, cwd) {
+  console.log(
+    `[${ts()}] Running ${path.basename(blobExportPath)} for ${path.basename(instrumentPath)}`,
+  );
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(
+      blobExportPath,
+      ['--reload-scripts-update', instrumentPath, blobOutputPath],
+      {
+        cwd,
+        stdio: ['ignore', 'inherit', 'inherit'],
+      },
+    );
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`${path.basename(blobExportPath)} exited with code ${code ?? 'unknown'}`));
+      }
+    });
+  });
+}
+
+/**
+ * Manages debounced instrument blob export triggered by file-system watch events.
+ * After exporting, it also re-deploys the updated asset files.
+ */
+export class InstrumentExporter {
+  suppressWatcher = false;
+
+  #config;
+  #assetDeployer;
+  #standaloneManager;
+  #timer = null;
+  #inProgress = false;
+  #rerun = false;
+  #warnedMissingBlobExport = false;
+
+  constructor(config, assetDeployer, standaloneManager) {
+    this.#config = config;
+    this.#assetDeployer = assetDeployer;
+    this.#standaloneManager = standaloneManager;
+  }
+
+  schedule() {
+    if (this.suppressWatcher) return;
+
+    clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => {
+      this.#timer = null;
+      void this.#run();
+    }, 250);
+  }
+
+  clearTimer() {
+    clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+
+  async runOnce() {
+    await this.#run('one-shot');
+  }
+
+  #warnBlobExportUnavailable() {
+    if (this.#warnedMissingBlobExport) return;
+
+    const { blobExportDefaultPath } = this.#config;
+    console.warn(
+      `[${ts()}] WARNING: blob-export was not found. Instrument blob export and generated typings are being skipped. Checked ${blobExportDefaultPath} and PATH.`,
+    );
+    this.#warnedMissingBlobExport = true;
+  }
+
+  async #run(trigger = 'watch') {
+    if (this.#inProgress) {
+      this.#rerun = true;
+      return;
+    }
+    this.#inProgress = true;
+
+    const {
+      instrumentSourceFolder,
+      instrumentAssetFolder,
+      blobExportPath,
+      blobExportAvailable,
+      generatedInstrumentTypesPath,
+      ugepFolder,
+      flags,
+    } = this.#config;
+
+    try {
+      if (!blobExportAvailable) {
+        this.#warnBlobExportUnavailable();
+        return;
+      }
+
+      this.suppressWatcher = true;
+      this.#assetDeployer.suppressWatcher = true;
+
+      const instrumentFiles = (await readdir(instrumentSourceFolder))
+        .filter((filename) => filename.toLowerCase().endsWith('.inst'))
+        .sort();
+
+      if (instrumentFiles.length === 0) return;
+
+      const blobExportCapabilities = await getBlobExportCapabilities(blobExportPath, ugepFolder);
+      if (!blobExportCapabilities.supportsParameterInfo) {
+        throw new Error(
+          `blob-export ${blobExportCapabilities.version} does not support --parameter-info. Install a newer version of the Gorilla Engine SDK that includes this option.`,
+        );
+      }
+
+      const instrumentDefinitions = [];
+      const usedTypeNames = new Map();
+
+      await mkdir(instrumentAssetFolder, { recursive: true });
+
+      const action =
+        trigger === 'watch'
+          ? 'Instrument changes detected - exporting blobs and regenerating typings'
+          : 'Syncing instrument blobs and regenerating typings';
+      console.log(`[${ts()}] ${action}`);
+
+      for (const instrumentFile of instrumentFiles) {
+        const instrumentPath = path.join(instrumentSourceFolder, instrumentFile);
+        const blobOutputPath = path.join(
+          instrumentAssetFolder,
+          `${path.parse(instrumentFile).name}.blob`,
+        );
+        const baseTypeName = toTypeIdentifier(path.parse(instrumentFile).name);
+        const nextCount = (usedTypeNames.get(baseTypeName) ?? 0) + 1;
+        usedTypeNames.set(baseTypeName, nextCount);
+
+        // Running blob-export also updates the embedded script in the inst file so this needs to be run first
+        await runBlobExport(blobExportPath, instrumentPath, blobOutputPath, ugepFolder);
+
+        instrumentDefinitions.push({
+          fileName: path.parse(instrumentFile).name,
+          typeName: nextCount === 1 ? baseTypeName : `${baseTypeName}${nextCount}`,
+          parameters: await getInstrumentParameterInfo(blobExportPath, instrumentPath, ugepFolder),
+        });
+      }
+
+      await writeInstrumentTypesFile(generatedInstrumentTypesPath, instrumentDefinitions);
+
+      if (flags.deploy) await deployAssetFilesToOutput(this.#config);
+
+      console.log(`[${ts()}] Instrument sync finished\n`);
+      if (flags.standalone) await this.#standaloneManager.restart();
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        this.#warnBlobExportUnavailable();
+        return;
+      }
+      console.error(`[${ts()}] Instrument sync failed: ${error.message}`);
+      if (trigger === 'one-shot') throw error;
+    } finally {
+      this.suppressWatcher = false;
+      this.#assetDeployer.suppressWatcher = false;
+      this.#inProgress = false;
+      if (this.#rerun) {
+        this.#rerun = false;
+        void this.#run('watch');
+      }
+    }
+  }
+}

package/lib/permissions.js

@@ -0,0 +1,121 @@
+import { open, readdir } from 'node:fs/promises';
+import * as path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { userInfo } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { assertNoSymlinksWithinBase, askQuestion } from './utils.js';
+
+const execFileAsync = promisify(execFile);
+const windowsPermissionScript = fileURLToPath(
+  new URL('./repair-windows-permissions.ps1', import.meta.url),
+);
+
+export function getPermissionRepairInvocation({ isMac, username, outputFolder }) {
+  if (isMac) {
+    return {
+      file: 'sudo',
+      args: ['chown', '-R', '-P', username, outputFolder],
+    };
+  }
+
+  const encodeValue = (value) => Buffer.from(value, 'utf8').toString('base64');
+  const decodeValue = (value) =>
+    `[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodeValue(value)}'))`;
+  const permissionScript =
+    `$env:GORILLA_PERMISSION_FOLDER = ${decodeValue(outputFolder)}; ` +
+    `$env:GORILLA_PERMISSION_USER = ${decodeValue(username)}; ` +
+    `$scriptPath = ${decodeValue(windowsPermissionScript)}; ` +
+    '& $scriptPath; exit $LASTEXITCODE';
+  const encodedPermissionScript = Buffer.from(permissionScript, 'utf16le').toString('base64');
+  const elevationScript =
+    `$process = Start-Process -FilePath 'powershell.exe' -ArgumentList @('-NoProfile', '-NonInteractive', '-EncodedCommand', '${encodedPermissionScript}') -Verb RunAs -Wait -PassThru; ` +
+    "$exitCode = $process.ExitCode; if ($exitCode -ne 0) { [Console]::Error.WriteLine('Elevated permission repair exited with code ' + $exitCode) }; exit $exitCode";
+  return {
+    file: 'powershell',
+    args: ['-NoProfile', '-NonInteractive', '-Command', elevationScript],
+  };
+}
+
+async function isWriteable(filePath) {
+  const handle = await open(filePath, 'r+');
+  await handle.close();
+}
+
+export async function assertTreeWriteable(folderPath, checkFile = isWriteable) {
+  const entries = await readdir(folderPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(folderPath, entry.name);
+    if (entry.isSymbolicLink()) {
+      throw new Error(`Refusing to access symbolic link "${entryPath}"`);
+    }
+    if (entry.isDirectory()) {
+      await assertTreeWriteable(entryPath, checkFile);
+    } else {
+      await checkFile(entryPath);
+    }
+  }
+}
+
+/**
+ * Checks that the plugin's deployed files are writeable by the current user.
+ * If not, offers to take ownership via sudo (macOS) or grant access via icacls (Windows).
+ * Exits the process if permissions cannot be secured.
+ * @param {object} config - Resolved plugin config
+ */
+export async function ensureWriteable(config) {
+  const { outputRoot, outputFolder, pluginName, ugepContent, isMac } = config;
+  const scriptPath = path.join(outputFolder, `${pluginName}.js`);
+  await assertNoSymlinksWithinBase(outputRoot ?? outputFolder, scriptPath);
+  const yamlPath = path.join(outputFolder, `${pluginName}.yaml`);
+  if (ugepContent.ymlFiles.length > 0) {
+    await assertNoSymlinksWithinBase(outputRoot ?? outputFolder, yamlPath);
+  }
+
+  try {
+    if (isMac) {
+      await isWriteable(scriptPath);
+      if (ugepContent.ymlFiles.length > 0) {
+        await isWriteable(yamlPath);
+      }
+    } else {
+      await assertTreeWriteable(outputFolder);
+    }
+  } catch {
+    console.error(`${outputFolder} is *NOT* writeable!`);
+    const promptMsg = isMac
+      ? `Do you want to chown "${outputFolder}" to the current user? This requires sudo. [y/N] `
+      : `Do you want to make "${outputFolder}" writable for the current user? [y/N] `;
+
+    const answer = await askQuestion(promptMsg);
+    if (answer.trim().toLowerCase() === 'y') {
+      const username = userInfo().username;
+      try {
+        if (!isMac) {
+          console.log(
+            'UAC dialog for "icacls.exe" will come up. Please approve it to change the folder\'s permissions.',
+          );
+        }
+        const invocation = getPermissionRepairInvocation({
+          isMac,
+          username,
+          outputFolder,
+        });
+        await execFileAsync(invocation.file, invocation.args, invocation.options);
+        if (isMac) {
+          console.log(`Changed ownership of ${outputFolder} to ${username}`);
+        } else {
+          await assertTreeWriteable(outputFolder);
+          console.log(`Made ${outputFolder} writeable for ${username}`);
+        }
+      } catch (err) {
+        const failure = isMac ? 'Failed to change ownership' : 'Failed to make output files writeable';
+        console.error(`${failure}: ${err.message}`);
+        process.exit(2);
+      }
+    } else {
+      console.error(`Please make sure that it is writeable for this script to work`);
+      process.exit(2);
+    }
+  }
+}

package/lib/repair-windows-permissions.ps1

@@ -0,0 +1,8 @@
+$ErrorActionPreference = 'Stop'
+
+$folder = $env:GORILLA_PERMISSION_FOLDER
+$user = $env:GORILLA_PERMISSION_USER
+$grant = $user + ':(OI)(CI)F'
+
+& icacls.exe $folder /grant $grant /T /L
+exit $LASTEXITCODE

package/lib/standalone.js

@@ -0,0 +1,44 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { ts } from './utils.js';
+
+export class StandaloneManager {
+  #config;
+  #process = null;
+
+  constructor(config) {
+    this.#config = config;
+  }
+
+  getAppPath() {
+    const { pluginName, manufacturerName, isMac } = this.#config;
+    if (isMac) {
+      return `/Applications/${manufacturerName}/${pluginName}.app`;
+    } else {
+      return `${process.env['ProgramFiles']}\\${manufacturerName}\\${pluginName}\\${pluginName}.exe`;
+    }
+  }
+
+  exists() {
+    return existsSync(this.getAppPath());
+  }
+
+  kill() {
+    this.#process?.kill();
+    this.#process = null;
+  }
+
+  async restart() {
+    if (!this.#config.ugepContent.pluginConfig.buildStandalone) return;
+    const { pluginName, isMac } = this.#config;
+    const appPath = this.getAppPath();
+    this.kill();
+    const binaryPath = isMac ? `${appPath}/Contents/MacOS/${pluginName}` : appPath;
+    this.#process = spawn(binaryPath, [], {
+      detached: true,
+      stdio: ['ignore', 'inherit', 'inherit'],
+    });
+    this.#process.unref();
+    console.log(`[${ts()}] Started ${pluginName} standalone`);
+  }
+}

package/lib/utils.js

@@ -0,0 +1,89 @@
+import { createInterface } from 'node:readline';
+import { lstat, realpath } from 'node:fs/promises';
+import * as path from 'node:path';
+
+export function ts() {
+  return new Date().toLocaleTimeString();
+}
+
+export function assertSafePathSegment(value, label) {
+  if (
+    typeof value !== 'string' ||
+    value.length === 0 ||
+    value === '.' ||
+    value === '..' ||
+    /[<>:"/\\|?*\u0000-\u001f]/.test(value) ||
+    /[. ]$/.test(value)
+  ) {
+    throw new Error(`${label} must be a safe file name: ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+/**
+ * Resolves `segments` against `baseDir` and throws if the result would land
+ * outside of `baseDir` (e.g. via ".." components or an absolute path segment).
+ * Use this whenever a destination path is built from untrusted input (ugep
+ * file contents) to prevent writes/deletes outside the intended folder.
+ */
+export function resolveWithinBase(baseDir, ...segments) {
+  const resolvedBase = path.resolve(baseDir);
+  const resolvedTarget = path.resolve(resolvedBase, ...segments);
+  if (resolvedTarget !== resolvedBase && !resolvedTarget.startsWith(resolvedBase + path.sep)) {
+    throw new Error(
+      `Refusing to access path outside of "${resolvedBase}" (resolved to "${resolvedTarget}")`,
+    );
+  }
+  return resolvedTarget;
+}
+
+export async function resolveExistingWithinBase(baseDir, ...segments) {
+  const resolvedTarget = resolveWithinBase(baseDir, ...segments);
+  const [realBase, realTarget] = await Promise.all([realpath(baseDir), realpath(resolvedTarget)]);
+  return resolveWithinBase(realBase, path.relative(realBase, realTarget));
+}
+
+export async function assertNoSymlinksWithinBase(baseDir, targetPath) {
+  const resolvedBase = path.resolve(baseDir);
+  const resolvedTarget = resolveWithinBase(resolvedBase, path.relative(resolvedBase, targetPath));
+  const relativeParts = path.relative(resolvedBase, resolvedTarget).split(path.sep).filter(Boolean);
+  const pathsToCheck = [
+    resolvedBase,
+    ...relativeParts.map((_, index) => path.join(resolvedBase, ...relativeParts.slice(0, index + 1))),
+  ];
+
+  for (const pathToCheck of pathsToCheck) {
+    try {
+      if ((await lstat(pathToCheck)).isSymbolicLink()) {
+        throw new Error(`Refusing to access symbolic link "${pathToCheck}"`);
+      }
+    } catch (error) {
+      if (error?.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+
+  return resolvedTarget;
+}
+
+export async function askQuestion(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) =>
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    }),
+  );
+}
+
+export function shouldIgnoreWatchedChange(filename) {
+  if (!filename) {
+    return false;
+  }
+  return (
+    filename.startsWith('.') ||
+    filename.endsWith('~') ||
+    filename.endsWith('.swp') ||
+    filename.endsWith('.tmp')
+  );
+}

package/lib/watchers.js

@@ -0,0 +1,59 @@
+import { watch } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { shouldIgnoreWatchedChange } from './utils.js';
+
+export function shouldIgnoreInstrumentChange(filename, suppressWatcher = false) {
+  return suppressWatcher || shouldIgnoreWatchedChange(filename?.toString());
+}
+
+/**
+ * Creates file-system watchers for asset folders and the instrument source folder.
+ * Returns an object with a `close()` method to tear down all watchers.
+ * @param {object} config - Resolved plugin config
+ * @param {import('./assets.js').AssetDeployer} assetDeployer
+ * @param {import('./instruments.js').InstrumentExporter} instrumentExporter
+ */
+export function createWatchers(config, assetDeployer, instrumentExporter) {
+  const { assetSourceFolders, presetSourceFolders, instrumentSourceFolder, flags } = config;
+  const watchers = [];
+
+  if (flags.deploy) {
+    const contentSourceFolders = [
+      ...new Set([...(assetSourceFolders ?? []), ...(presetSourceFolders ?? [])]),
+    ];
+    for (const folder of contentSourceFolders) {
+      if (!existsSync(folder)) continue;
+
+      const handler = (_eventType, filename) => {
+        if (assetDeployer.suppressWatcher || shouldIgnoreWatchedChange(filename?.toString())) {
+          return;
+        }
+        assetDeployer.schedule();
+      };
+
+      try {
+        watchers.push(watch(folder, { persistent: true, recursive: true }, handler));
+      } catch {
+        // Fallback for platforms that don't support recursive watching
+        watchers.push(watch(folder, { persistent: true }, handler));
+      }
+    }
+  }
+
+  if (existsSync(instrumentSourceFolder)) {
+    watchers.push(
+      watch(instrumentSourceFolder, { persistent: true }, (_eventType, filename) => {
+        if (shouldIgnoreInstrumentChange(filename, instrumentExporter.suppressWatcher)) return;
+        instrumentExporter.schedule();
+      }),
+    );
+  }
+
+  return {
+    close() {
+      for (const watcher of watchers) {
+        watcher.close();
+      }
+    },
+  };
+}