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

package/LICENSE.md

@@ -0,0 +1,64 @@
+**IMPORTANT NOTICE: PLEASE READ CAREFULLY BEFORE DOWNLOADING, INSTALLING OR USING THE GORILLA ENGINE SDK:**
+
+- BY SIGNING THIS AGREEMENT, OR CLICKING ON THE “ACCEPT” BUTTON BELOW (IF AVAILABLE), OR BY DOWNLOADING, INSTALLING, OR USING THE GORILLA ENGINE SDK, YOU AGREE TO THE TERMS OF THIS AGREEMENT, AND ALL INCORPORATED TERMS INCLUDING GORILLA ENGINE’S PRIVACY POLICY, AS APPLICABLE, WHICH WILL BIND YOU.
+
+- IF YOU DO NOT AGREE TO THE TERMS OF THIS AGREEMENT, WE WILL NOT LICENSE THE GORILLA ENGINE SDK TO YOU AND YOU MUST DISCONTINUE THE INSTALLATION OR DOWNLOAD PROCESS OR CEASE USE OF THE UJAM GORILLA ENGINE SDK.
+
+**GORILLA ENGINE FREE TIER LICENSE**
+
+This Gorilla Engine Free Tier License ("Agreement") is entered between UJAM, Inc., a Delaware corporation (hereinafter "UJAM" or "we") and you (“Licensee” or “you”) and becomes effective once you download, install, or use the GORILLA ENGINE SDK.
+
+1. OBJECT OF AGREEMENT. This Agreement governs UJAM’s GORILLA ENGINE SDK (“SDK”) and all related software and documentation and any update, upgrades or bug fixes (collectively referred to as the "UJAM GORILLA ENGINE SDK SERVICE").
+
+2. GRANT OF LICENSE: Subject to your full compliance with all of the terms and conditions of this Agreement, we grant you a non-exclusive, revocable, nonsublicensable (except as specifically provided herein), non-transferable license to use the UJAM GORILLA ENGINE SDK SERVICE solely to: (i) download, install, and use the UJAM GORILLA ENGINE SDK SERVICE for the sole purpose of building audio plugins such as virtual instruments and effects ("Application") and using such Application for music productions and live performances. **HOWEVER, YOU MUST NOT SHARE OR OTHERWISE EXPLOIT YOUR GORILLA ENGINE BASED APPLICATION WITH ANY THIRD PARTY UNTIL YOU HAVE ACQUIRED ONE OF THE ADD-ON LICENSES AS FURTHER DESCRIBED IN SECTION 8 OF THIS AGREEMENT.** If you have any questions regarding this license and allowed uses of the SDK, please reach out to us via email at support@gorilla-engine.com.
+
+3. LICENSE RESTRICTIONS AND OBLIGATIONS: Except as expressly and unambiguously authorized under this Agreement, you must not
+   1. copy, rent, lease, sell, transfer, assign, sublicense, disassemble, reverse engineer or decompile (except to the limited extent expressly authorized by applicable statutory law), modify, create derivative works from, or alter any part of the UJAM GORILLA ENGINE SDK SERVICE;
+   2. sublicense your Application to end-users until you have acquired a license as further described in Section 8 of this Agreement.
+   3. use any automated means, including, without limitation, agents, robots, scripts or spiders, to access the UJAM GORILLA ENGINE SDK SERVICE or bypass the UJAM GORILLA ENGINE SDK SERVICE or to interfere or attempt to interfere with the proper working of the UJAM GORILLA ENGINE SDK SERVICE;
+   4. use the UJAM GORILLA ENGINE SDK SERVICE as a dynamic-link library (for clarity: the SDK shall solely be used as a statically linked library); (g) use the SDK or any part of the SDK in connection with building or distributing your own or a third-party SDK or framework; or (h) use the Licensed Software to train artificial intelligence, your own or a third-party algorithm, and/or any other kind of machine learning processes.
+   5. use the UJAM GORILLA ENGINE SDK SERVICE for the benefit of a third party, other than end users of your Applications as expressly authorized by this Agreement;
+   6. use the UJAM GORILLA ENGINE SDK SERVICE to implement or enhance a product or service that is competitive with the UJAM GORILLA ENGINE SDK SERVICE;
+   7. modify and/or rename the UJAM binary libraries; or
+   8. otherwise engage in activity that interrupts the proper working of the UJAM GORILLA ENGINE SDK SERVICE or is otherwise fraudulent or illegal.
+
+Furthermore, you agree
+
+9. display attribution on all embodiments and uses of the Gorilla Engine SDK by displaying the language “powered by Gorilla Engine” ; and  
+   10. to contact UJAM once you intend to Distribute (as defined in Section 8\) your Application to obtain the appropriate license to do so – which you agree is required for such a scenario (as further described in Section 8 below).
+
+   We reserve the right to discontinue, modify, cease support of, and alter the pricing structure of this Agreement (the Gorilla Engine Free Tier License) of the UJAM GORILLA ENGINE SDK SERVICE.
+
+10. LICENSE TO UJAM: You hereby grant to us the non-exclusive, perpetual, worldwide, royalty-free right and license to any and all content ("Content") provided by you or your end users in connection with your use or your end users' use of the SDK, including but not limited to feedback or other contributions made towards the UJAM GORILLA ENGINE SDK SERVICE (including so-called re-usable components, made available by UJAM via its repositories), in order for us to provide and improve the UJAM GORILLA ENGINE SDK SERVICE. You represent and warrant that all Content provided by you shall not violate any third party rights and shall be free of any and all claims.
+
+11. REPRESENTATIONS AND WARRANTIES: You represent and warrant that you: (i) are fully authorized to enter into this agreement; (ii) shall use the UJAM GORILLA ENGINE SDK SERVICE in compliance with all applicable local, state, national and foreign laws, treaties and regulations, including those related to data privacy, international communications, export laws and the transmission of technical or personal data laws; (iii) shall not (and shall not permit any third party, including a permitted sublicensee to), directly or indirectly, take any action or upload, download, post, submit or otherwise distribute or facilitate distribution of Content or any material on or through the UJAM GORILLA ENGINE SDK SERVICE, that: (a) infringes any patent, trademark, trade secret, copyright, right of publicity/privacy or other right of any third party or induces infringement thereof; (b) breaches any third party contract or obligation; (c) is unlawful, threatening, abusive, harassing, defamatory, deceptive, fraudulent, invasive of another's privacy, tortious, obscene, offensive, or profane.
+
+12. OWNERSHIP AND PROPRIETARY RIGHTS: As between UJAM and Licensee (and any permitted sublicensees), the SDK and all intellectual property rights in and to the UJAM GORILLA ENGINE SDK SERVICE, are and shall at all times remain the sole and exclusive property of UJAM and are protected by applicable intellectual property laws and treaties. You shall not obscure, remove or otherwise alter our copyright or trademark notices or other proprietary rights' notices affixed to or within the SDK or elsewhere.
+
+13. SUPPORT AND UPGRADES: This Agreement does not entitle you to any support for the SDK, unless you enter into a separate agreement with us in writing, either signed by both parties or agreed upon via click-through agreement. Any such support provided by us shall be subject to the terms and disclaimers of this Agreement.
+
+14. ADD-ON LICENSES FOR A PERMITTED DISTRIBUTION OF GORILLA ENGINE BASED APPLICATION:
+    1. **Add-On Licenses (Upgrade to Pro Tier):** You agree to contact UJAM to obtain one of our commercial license (including the so-called “Pro Tier” License, including available optional Add-On upgrades which can be ) (collectively referred to as “Add-On Licenses”), whichever deemed to be appropriate for your intended use of the SDK, to Distribute (as defined below in subsection ii.) your Gorilla Engine based Application to end-users. Such Add-On License shall supersede this Agreement, as agreed to by the parties.
+    2. **Failure to comply with Section 8:** If you fail to comply with Section 8(i) by Distributing the SDK as part of an Application beyond the allowed use under this Agreement, you shall immediately contact UJAM and pay to UJAM a royalty per each Distribution (as defined below) in an amount as solely determined by UJAM. A Distribution refers to either an embedded, pre-bundled, pre-installed platform application or software application that is downloaded, delivered, or served to a user or device by any means of distribution including directly from you or through any platform, including cloud based platforms. In avoidance of doubt, any subscription or rental shall be considered a Distribution.
+    3. **Audit Rights**: Should (i) you fail to obtain an Add-On License and distribute the SDK as part of an Application, or should (ii) UJAM believe that you distribute the Application without having obtained an Add-On License, then UJAM shall have the right, upon reasonable notice, to audit/inspect any premises, computer(s), and networks on or in which the SDK is installed or used to monitor compliance with the terms of this Agreement, including but not limited to confirming the number of Distributions of the Application. If an audit reveals any unauthorized use, in addition to all other remedies available to UJAM, you shall be responsible to UJAM for all reasonable expenses related to the audit.
+    4. **Third Party Libraries:** You acknowledge that certain third-party libraries, including JUCE 6 ([https://juce.com/legal/juce-6-license/](https://juce.com/legal/juce-6-license/)), may be used in connection with the SDK, subject to their respective license agreements as further disclosed by UJAM. It is your sole responsibility to abide to such third-party terms, which may include your obligations, amongst others, to provide certain disclosures accompanying your Gorilla Engine based Software and/or acquiring a JUCE license (if applicable).
+
+15. DATA PROTECTION AND PRIVACY: We may collect and process information about you and your use of the Gorilla Engine SDK, some of which may amount to personal data, subject to Gorilla Engine’s Privacy Policy.
+
+16. TRADE SECRETS AND CONFIDENTIAL INFORMATION: You acknowledges that the SDK contains valuable trade secrets of UJAM and, should you access any such trade secrets in violation of this Agreement, you agree to maintain the confidentiality of the trade secrets of the SDK using at least the same degree of care that you use with your own confidential information.
+
+17. WARRANTY DISCLAIMER: THE UJAM GORILLA ENGINE SDK SERVICE, INCLUDING THE SDK, IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, WE DISCLAIM ALL WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, REGARDING THE UJAM GORILLA ENGINE SDK SERVICE, INCLUDING WITHOUT LIMITATION ANY AND ALL IMPLIED WARRANTIES OF MERCHANTABILITY, ACCURACY, RESULTS OF USE, RELIABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AVAILABILITY, PERFORMANCE, BANDWIDTH, AND NON-INFRINGEMENT OF THIRD-PARTY RIGHTS. FURTHER, WE DISCLAIM ANY WARRANTY THAT LICENSEE'S USE OF THE UJAM GORILLA ENGINE SDK SERVICE WILL BE AVAILABLE, UNINTERRUPTED OR ERROR FREE.
+
+18. LIABILITY LIMITATION: REGARDLESS OF WHETHER ANY REMEDY SET FORTH HEREIN FAILS OF ITS ESSENTIAL PURPOSE OR OTHERWISE, AND EXCEPT FOR BODILY INJURY, IN NO EVENT WILL WE OR OUR CONTRACTORS, EMPLOYEES OR AFFILIATES BE LIABLE TO YOU OR TO ANY THIRD PARTY UNDER ANY TORT, CONTRACT, NEGLIGENCE, STRICT LIABILITY OR OTHER LEGAL OR EQUITABLE THEORY FOR ANY LOST PROFITS, LOST OR CORRUPTED DATA, COMPUTER FAILURE OR MALFUNCTION, INFRINGEMENT, INTERRUPTION OF BUSINESS, OR OTHER SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING OUT OF THE USE OR INABILITY TO USE THE UJAM GORILLA ENGINE SDK SERVICE, EVEN IF WE HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSS OR DAMAGES AND WHETHER OR NOT SUCH LOSS OR DAMAGES ARE FORESEEABLE. IN NO EVENT SHALL OUR TOTAL LIABILITY TO YOU OR ANY THIRD PARTY EXCEED TEN USD DOLLARS. ANY CLAIM ARISING OUT OF OR RELATING TO THIS AGREEMENT MUST BE BROUGHT WITHIN ONE (1) YEAR AFTER THE OCCURRENCE OF THE EVENT GIVING RISE TO SUCH CLAIM.
+
+19. INDEMNITY: You agree that we shall have no liability whatsoever for your or your end users of the UJAM GORILLA ENGINE SDK SERVICE. You shall indemnify, defend and hold us harmless from any and all claims, damages, liabilities, costs, and fees (including reasonable attorneys' fees) arising from your or your end users' use of the UJAM GORILLA ENGINE SDK SERVICE or for any breach of this Agreement, including any breach of the representations and warranties you made herein.
+
+20. TERM AND TERMINATION: This Agreement shall continue until terminated as set forth in this Section. Either party may terminate this Agreement at any time, for any reason, or for no reason including, but not limited to, if you violate any provision of this Agreement. We reserve the right to cancel, amend, or modify the SDK at any time. Any termination of this Agreement shall also terminate the license granted hereunder. Upon termination of this Agreement for any reason, you shall immediately destroy and remove from all computers, hard drives, networks, and other storage media all copies of the SDK, and shall so certify to us that such actions have occurred (including all cached ephemeral copies). Sections 5 (“REPRESENTATIONS AND WARRANTIES”), 6 (“OWNERSHIP AND PROPRIETARY RIGHTS”), 10 (“TRADE SECRETS AND CONFIDENTIAL INFORMATION”), 11 (“WARRANTY DISCLAIMER”), 12 (“LIABILITY LIMITATION”), 13 (“INDEMNITY”), 16 (“GOVERNING LAW”), 18 (“GENERAL PROVISIONS”) shall survive termination of this Agreement.
+
+21. EXPORT CONTROLS: You shall comply with all applicable export laws and restrictions and regulations and you shall not export, or allow the export or re-export of the SDK in violation of any such restrictions, laws, or regulations.
+
+22. GOVERNING LAW: This Agreement shall be governed by New York law, excluding conflict of law provisions. The parties agree to and submit to the exclusive jurisdiction of courts located in New York City, New York. The application of the United Nations Convention of Contracts for the International Sale of Goods is expressly excluded.
+
+23. PREVAILING PARTY. Notwithstanding Section 12 (“LIABILITY LIMITATION”), in the event of any court action relating to enforcement of this Agreement, including injunctive relief, the non-prevailing party shall reimburse the prevailing party for all reasonable attorneys’ fees and costs, including expert witness fees, resulting therefrom.
+
+24. GENERAL PROVISIONS. If any part of this Agreement is found void or unenforceable, it will not affect the validity of the balance of the Agreement, which shall remain valid and enforceable according to its terms. This Agreement may only be modified by written agreement between the Parties. Updates to the UJAM GORILLA ENGINE SDK SERVICE may be licensed to you by UJAM with additional or different terms. UJAM further reserves rights, in its discretion, not to license updates. This is the entire Agreement between UJAM and you relating to the UJAM GORILLA ENGINE SDK SERVICE and it supersedes any prior representations, discussions, undertakings, communications, or advertising relating to the UJAM GORILLA ENGINE SDK SERVICE. This Agreement is not assignable by you.

package/README.md

@@ -0,0 +1,107 @@
+# @gorilla-engine-sdk/gorilla-engine-scripts
+
+Build and deployment scripts for Gorilla Engine plugins. Provides two CLI tools:
+
+- **`gorilla-engine-scripts-deploy`** — Bundles your plugin's TypeScript/TSX entry point with esbuild, encrypts/signs the output, deploys JS, YAML, and asset files to the plugin folder, exports instrument blobs, regenerates instrument typings, and watches for changes in development.
+- **`gorilla-engine-scripts-build`** — Runs `gorilla-compiler` on a `.ugep` file to produce an installer, with optional auto-install after a successful build.
+
+## Install
+
+```bash
+npm install @gorilla-engine-sdk/gorilla-engine-scripts
+```
+
+## Usage
+
+### Deploy (development workflow)
+
+> **Prerequisite:** The plugin must be built and installed at least once via `gorilla-engine-scripts-build --install` before the deploy workflow can be used. The deploy script writes into the plugin's installed output folder and, when `--standalone` is used, launches the installed standalone binary.
+
+```bash
+gorilla-engine-scripts-deploy --ugep <ugep-file> --entry-point <js-entry-point-file>
+```
+
+**Options:**
+
+| Flag                      | Short | Description                                                            |
+| ------------------------- | ----- | ---------------------------------------------------------------------- |
+| `--ugep <FILE>`           | `-u`  | Path to the `.ugep` project file                                       |
+| `--entry-point <FILE>`    | `-e`  | TypeScript/TSX entry point of the plugin UI                            |
+| `--one-shot`              | `-1`  | Build once and exit (no file watching)                                 |
+| `--build-ui-only`         |       | With `--one-shot`, bundle only the UI JS                               |
+| `--sync-instruments-only` |       | With `--one-shot`, sync only instrument blobs and generated typings    |
+| `--no-deploy`             | `-nd` | Skip deployment to the plugin folder                                   |
+| `--standalone`            | `-s`  | Start/restart the standalone app after each deploy and stop it on exit |
+
+**Example:**
+
+```bash
+gorilla-engine-scripts-deploy --ugep my-plugin.ugep --entry-point src/index.tsx
+```
+
+By default the command watches for changes and redeploys automatically. It also watches the `instrument/` folder and re-exports blobs plus regenerates `src/generated/gorilla-instrument-types.d.ts` when instrument sources change.
+
+When run with `--one-shot`, the command performs both the one-shot UI bundle and the one-shot instrument sync before exiting. Use `--build-ui-only` or `--sync-instruments-only` to run just one half of that workflow. If `blob-export` is unavailable, the command prints a warning and continues with the rest of the deploy workflow.
+
+**Output locations:**
+
+- macOS: `/Library/Application Support/<manufacturer>/<pluginName>/`
+- Windows: `<SystemDrive>/ProgramData/<manufacturer>/<pluginName>/`
+
+If the output folder is not writable, the script will interactively offer to fix permissions (`sudo chown` on macOS, `icacls` on Windows).
+
+### Build (produce installer)
+
+```bash
+gorilla-engine-scripts-build --ugep <ugep-file> [--credentials <credentials-file>]
+```
+
+**Options:**
+
+| Flag                   | Short | Description                                                                             |
+| ---------------------- | ----- | --------------------------------------------------------------------------------------- |
+| `--ugep <FILE>`        | `-u`  | Path to the `.ugep` project file                                                        |
+| `--credentials <FILE>` | `-c`  | Optional JSON file with `{ "username": "...", "password": "..." }` for gorilla-compiler |
+| `--install`            | `-i`  | Install the built plugin after a successful build                                       |
+
+**Example:**
+
+```bash
+gorilla-engine-scripts-build --ugep my-plugin.ugep --credentials buildCredentials.json
+```
+
+If `--credentials` is not provided, the build command resolves credentials in this order:
+
+1. `<ugep-directory>/buildCredentials.json`
+2. `GORILLA_BUILD_USERNAME` + `GORILLA_BUILD_PASSWORD`
+3. `GORILLA_BUILD_CREDENTIALS_FILE`
+4. `~/.gorilla-engine/credentials.json`
+
+When no credentials are found and the command runs in an interactive terminal, it will prompt once and save credentials to `~/.gorilla-engine/credentials.json`.
+
+User-wide credential path by platform:
+
+- macOS: `/Users/<you>/.gorilla-engine/credentials.json`
+- Windows: `C:\\Users\\<you>\\.gorilla-engine\\credentials.json`
+
+## Encryption
+
+Deployed JS and YAML files are encrypted based on the setting in the `.ugep` file.
+
+## Typical `package.json` Integration
+
+```json
+{
+  "scripts": {
+    "start": "gorilla-engine-scripts-deploy --ugep MyPlugin.ugep --entry-point src/index.tsx",
+    "build:ui": "gorilla-engine-scripts-deploy --ugep MyPlugin.ugep --entry-point src/index.tsx --one-shot --no-deploy --build-ui-only",
+    "sync:instruments": "gorilla-engine-scripts-deploy --ugep MyPlugin.ugep --entry-point src/index.tsx --one-shot --no-deploy --sync-instruments-only",
+    "prepare:artifacts": "npm run build:ui && npm run sync:instruments",
+    "build": "gorilla-engine-scripts-build --ugep MyPlugin.ugep --install"
+  }
+}
+```
+
+## License
+
+[GORILLA ENGINE FREE TIER LICENSE](./LICENSE.md)

package/build.js

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+
+import { execFileSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import os from 'node:os';
+import * as path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+import { requireInstalledGorillaCompilerPath } from './compiler-detection.js';
+import { resolveInstallerPath } from './lib/installer.js';
+
+const compilerOpts = { stdio: 'inherit' };
+const isMac = process.platform === 'darwin';
+const CREDENTIALS_FILENAME = 'buildCredentials.json';
+const USER_CREDENTIALS_ENV_FILE = 'GORILLA_BUILD_CREDENTIALS_FILE';
+const USERNAME_ENV = 'GORILLA_BUILD_USERNAME';
+const PASSWORD_ENV = 'GORILLA_BUILD_PASSWORD';
+
+function print_usage(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|-u <ugep-file> [--credentials|-c <credentials-file>]
+
+${programName} will run gorilla-compiler on the ugep file.
+Example:
+${programName} --ugep my-plugin.ugep
+
+-u, --ugep <FILE>            the ugep file to run gorilla-compiler on
+-c, --credentials <FILE>     optional path to json file that contains the gorilla-compiler 
+                             credentials: {"username": "...","password": "..."}
+-i, --install                install the built installer after a successful build
+
+Credential fallback order (first match wins):
+  1) --credentials <FILE>
+  2) <ugep-directory>/${CREDENTIALS_FILENAME}
+  3) ${USERNAME_ENV} + ${PASSWORD_ENV}
+  4) ${USER_CREDENTIALS_ENV_FILE}
+  5) ~/.gorilla-engine/credentials.json
+
+If no credentials are found and this runs in an interactive terminal, you will be prompted once
+and credentials will be saved to ~/.gorilla-engine/credentials.json.
+  `);
+  if (typeof exit != 'undefined') {
+    process.exit(exit);
+  }
+}
+
+async function main() {
+  console.log('Starting build...');
+  const compilerPath = requireInstalledGorillaCompilerPath();
+
+  const flags = getFlags();
+  const { username, password, credentialsPathToSave } = await resolveCredentials(flags);
+  const compilerArgs = ['-d', '-p', flags.ugepFile, '-i', '-e', username, '-s', password];
+  if (flags.meta) {
+    compilerArgs.push('-m');
+  }
+  try {
+    execFileSync(compilerPath, compilerArgs, compilerOpts);
+  } catch {
+    throw new Error('gorilla-compiler failed. See output above for details.');
+  }
+
+  if (credentialsPathToSave) {
+    writeUserCredentials(credentialsPathToSave, { username, password });
+    console.log(`Saved build credentials to ${credentialsPathToSave}`);
+  }
+
+  console.log('Build complete');
+
+  if (flags.install) {
+    installPlugin(flags.ugepFile);
+  }
+}
+
+function getDefaultUserCredentialsPath() {
+  return path.join(os.homedir(), '.gorilla-engine', 'credentials.json');
+}
+
+function normalizeCredentials(rawCredentials) {
+  if (
+    rawCredentials === null ||
+    typeof rawCredentials !== 'object' ||
+    Array.isArray(rawCredentials)
+  ) {
+    return null;
+  }
+
+  const username =
+    typeof rawCredentials.username === 'string' ? rawCredentials.username.trim() : undefined;
+  const password =
+    typeof rawCredentials.password === 'string' ? rawCredentials.password.trim() : undefined;
+
+  if (!username || !password) {
+    return null;
+  }
+
+  return { username, password };
+}
+
+function readCredentialsFile(credentialsPath, { strict, sourceDescription }) {
+  if (!existsSync(credentialsPath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(credentialsPath, 'utf-8'));
+    const credentials = normalizeCredentials(parsed);
+    if (!credentials) {
+      if (strict) {
+        throw new Error(
+          `${sourceDescription} is missing a non-empty username/password pair: ${credentialsPath}`,
+        );
+      }
+      return null;
+    }
+    return credentials;
+  } catch (error) {
+    if (strict) {
+      throw new Error(
+        `Failed to read ${sourceDescription} at ${credentialsPath}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+    return null;
+  }
+}
+
+function readCredentialsFromEnvironment() {
+  const username = process.env[USERNAME_ENV]?.trim();
+  const password = process.env[PASSWORD_ENV]?.trim();
+
+  if (username && password) {
+    return { username, password };
+  }
+
+  return null;
+}
+
+class MutableOutputStream extends Writable {
+  constructor(target) {
+    super();
+    this.target = target;
+    this.muted = false;
+  }
+
+  _write(chunk, encoding, callback) {
+    if (!this.muted) {
+      this.target.write(chunk, encoding);
+    }
+    callback();
+  }
+}
+
+async function promptForCredentials() {
+  const mutableOutput = new MutableOutputStream(process.stdout);
+  const rl = createInterface({ input: process.stdin, output: mutableOutput, terminal: true });
+
+  try {
+    let username = '';
+    while (!username) {
+      username = (await rl.question('Gorilla Compiler username: ')).trim();
+      if (!username) {
+        console.error('Username is required.');
+      }
+    }
+
+    let password = '';
+    while (!password) {
+      process.stdout.write('Gorilla Compiler password: ');
+      mutableOutput.muted = true;
+      password = (await rl.question('')).trim();
+      mutableOutput.muted = false;
+      process.stdout.write('\n');
+      if (!password) {
+        console.error('Password is required.');
+      }
+    }
+
+    return { username, password };
+  } finally {
+    rl.close();
+  }
+}
+
+function writeUserCredentials(credentialsPath, credentials) {
+  const credentialsDirectory = path.dirname(credentialsPath);
+  mkdirSync(credentialsDirectory, { recursive: true });
+
+  const tmpPath = `${credentialsPath}.tmp-${process.pid}-${Date.now()}`;
+  const serialized = `${JSON.stringify(credentials, null, 2)}\n`;
+
+  try {
+    writeFileSync(tmpPath, serialized, { encoding: 'utf-8', mode: 0o600 });
+    renameSync(tmpPath, credentialsPath);
+    if (process.platform !== 'win32') {
+      chmodSync(credentialsPath, 0o600);
+    }
+  } catch (error) {
+    if (existsSync(tmpPath)) {
+      unlinkSync(tmpPath);
+    }
+    throw error;
+  }
+}
+
+async function resolveCredentials(flags) {
+  if (flags.credentialsFile) {
+    return readCredentialsFile(flags.credentialsFile, {
+      strict: true,
+      sourceDescription: 'credentials file from --credentials',
+    });
+  }
+
+  const ugepDir = path.dirname(path.resolve(flags.ugepFile));
+  const projectCredentialsPath = path.join(ugepDir, CREDENTIALS_FILENAME);
+  const projectCredentials = readCredentialsFile(projectCredentialsPath, {
+    strict: false,
+    sourceDescription: `project ${CREDENTIALS_FILENAME}`,
+  });
+  if (projectCredentials) {
+    return projectCredentials;
+  }
+
+  const environmentCredentials = readCredentialsFromEnvironment();
+  if (environmentCredentials) {
+    return environmentCredentials;
+  }
+
+  const envCredentialsPath = process.env[USER_CREDENTIALS_ENV_FILE];
+  if (envCredentialsPath) {
+    const environmentCredentialsFile = readCredentialsFile(envCredentialsPath, {
+      strict: false,
+      sourceDescription: `${USER_CREDENTIALS_ENV_FILE}`,
+    });
+    if (environmentCredentialsFile) {
+      return environmentCredentialsFile;
+    }
+  }
+
+  const defaultUserCredentialsPath = getDefaultUserCredentialsPath();
+  const userCredentials = readCredentialsFile(defaultUserCredentialsPath, {
+    strict: false,
+    sourceDescription: 'user-wide credentials',
+  });
+  if (userCredentials) {
+    return userCredentials;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error(
+      `Build credentials were not found. Provide --credentials, set ${USERNAME_ENV}/${PASSWORD_ENV}, or create ${defaultUserCredentialsPath}.`,
+    );
+  }
+
+  console.log('No build credentials found. Running one-time setup...');
+  const promptedCredentials = await promptForCredentials();
+
+  return { ...promptedCredentials, credentialsPathToSave: defaultUserCredentialsPath };
+}
+
+function installPlugin(ugepFile) {
+  const ugepContent = JSON.parse(readFileSync(ugepFile, 'utf-8'));
+  const { pluginConfig } = ugepContent;
+
+  if (isMac) {
+    const { installerName, installerPath } = resolveInstallerPath(ugepFile, pluginConfig, 'pkg');
+    console.log(`Installing ${installerName}...`);
+    console.log('Your system password is required to install the plugin.');
+    execFileSync('sudo', ['installer', '-pkg', installerPath, '-target', '/'], compilerOpts);
+  } else {
+    const { installerName, installerPath } = resolveInstallerPath(ugepFile, pluginConfig, 'exe');
+    console.log(`Installing ${installerName}...`);
+    execFileSync(installerPath, ['/SILENT', '/VERYSILENT'], compilerOpts);
+  }
+
+  console.log('Installation complete');
+}
+
+function getFlags() {
+  const scriptFlags = process.argv.slice(2);
+  let current_arg;
+  const flags = {};
+  while ((current_arg = scriptFlags.shift())) {
+    if (!current_arg.startsWith('-')) {
+      console.error(`Unknown option: ${current_arg}`);
+      print_usage(1);
+
+      // Show help
+    } else if (current_arg === '-h' || current_arg === '--help') {
+      print_usage(0);
+
+      // Use ugep file to deploy
+    } else if (current_arg === '-u' || current_arg === '--ugep') {
+      flags.ugepFile = scriptFlags.shift();
+      if (!existsSync(flags.ugepFile)) {
+        console.error(`ugep file does not exist`);
+        process.exit(2);
+      }
+
+      // Use ugep file to deploy
+    } else if (current_arg === '-c' || current_arg === '--credentials') {
+      flags.credentialsFile = scriptFlags.shift();
+      if (!existsSync(flags.credentialsFile)) {
+        console.error(`credentials file does not exist`);
+        process.exit(3);
+      }
+
+      // Create installer-meta.json
+    } else if (current_arg === '-m' || current_arg === '--meta') {
+      flags.meta = true;
+
+      // Install after building
+    } else if (current_arg === '-i' || current_arg === '--install') {
+      flags.install = true;
+
+      // Not handled in previous ifs => unknown option
+    } else {
+      console.error(`Unknown option: ${current_arg}`);
+      print_usage(1);
+    }
+  }
+
+  if (!flags.ugepFile) {
+    console.error(`ERROR: --ugep|-u is mandatory`);
+    print_usage(1);
+  }
+
+  return flags;
+}
+
+await main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/compiler-detection.js

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+const isMac = process.platform === 'darwin';
+
+const MAC_COMPILER_PATH = '/Applications/Gorilla Compiler.app/Contents/MacOS/Gorilla Compiler';
+
+function getWindowsCompilerPaths() {
+  const systemDrive = process.env.SystemDrive ?? 'C:';
+  const appData = process.env.APPDATA;
+
+  const sdkCompilerPath = `${systemDrive}\\Program Files\\Gorilla Engine SDK\\Gorilla Compiler\\Gorilla Compiler.exe`;
+  const standaloneCompilerPath = appData
+    ? path.resolve(appData, '..\\Local\\Programs\\gorilla-compiler\\Gorilla Compiler.exe')
+    : null;
+
+  return [sdkCompilerPath, standaloneCompilerPath].filter(Boolean);
+}
+
+export function getGorillaCompilerCandidatePaths() {
+  if (isMac) {
+    return [MAC_COMPILER_PATH];
+  }
+
+  return getWindowsCompilerPaths();
+}
+
+export function findInstalledGorillaCompilerPath() {
+  return (
+    getGorillaCompilerCandidatePaths().find((compilerPath) => existsSync(compilerPath)) ?? null
+  );
+}
+
+export function getGorillaCompilerNotFoundMessage() {
+  const candidates = getGorillaCompilerCandidatePaths();
+
+  return [
+    'Gorilla SDK not found. Please download from https://gorilla-engine.com, install and try again',
+    `Checked locations:\n- ${candidates.join('\n- ')}`,
+  ].join('\n\n');
+}
+
+export function requireInstalledGorillaCompilerPath() {
+  const compilerPath = findInstalledGorillaCompilerPath();
+  if (compilerPath) {
+    return compilerPath;
+  }
+
+  throw new Error(getGorillaCompilerNotFoundMessage());
+}

package/deploy.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { getFlags } from './lib/cli.js';
+import { createConfig } from './lib/config.js';
+import { ensureWriteable } from './lib/permissions.js';
+import { StandaloneManager } from './lib/standalone.js';
+import { AssetDeployer, deployAll } from './lib/assets.js';
+import { InstrumentExporter } from './lib/instruments.js';
+import { createBuildContext } from './lib/build.js';
+import { createWatchers } from './lib/watchers.js';
+import { ts } from './lib/utils.js';
+
+const flags = getFlags();
+const ugepContent = JSON.parse(await readFile(flags.ugepFile));
+const config = createConfig(flags, ugepContent);
+const { pluginName, outputFolder } = config;
+
+const standaloneManager = new StandaloneManager(config);
+
+if (flags.standalone) {
+  if (!ugepContent.pluginConfig.buildStandalone) {
+    console.error(
+      `ERROR: --standalone was specified, but "buildStandalone" is not enabled in ${path.basename(flags.ugepFile)}.`,
+    );
+    console.error(`Set pluginConfig.buildStandalone to true in your ugep file to use this option.`);
+    process.exit(2);
+  }
+  if (!standaloneManager.exists()) {
+    console.error(`ERROR: --standalone was specified, but the standalone binary was not found at:`);
+    console.error(`  ${standaloneManager.getAppPath()}`);
+    console.error(`Make sure the plugin has been built and installed before using --standalone.`);
+    process.exit(2);
+  }
+}
+
+if (!flags.oneShot) {
+  await ensureWriteable(config);
+}
+
+const assetDeployer = new AssetDeployer(config, standaloneManager);
+const instrumentExporter = new InstrumentExporter(config, assetDeployer, standaloneManager);
+
+const shouldBuildUi = !flags.syncInstrumentsOnly;
+const shouldSyncInstruments = !flags.buildUiOnly;
+
+const esCtx = shouldBuildUi
+  ? await createBuildContext(config, {
+      onBuildStarted: () => {
+        if (flags.deploy) console.log(`[${ts()}] Changes detected - deploying`);
+      },
+      onBuildFinished: async () => {
+        if (flags.deploy) {
+          await deployAll(config);
+          console.log(`[${ts()}] Deploy finished\n`);
+          if (flags.standalone) await standaloneManager.restart();
+        }
+      },
+    })
+  : null;
+
+if (flags.oneShot) {
+  if (shouldSyncInstruments) {
+    await instrumentExporter.runOnce();
+  }
+  if (shouldBuildUi) {
+    await esCtx.rebuild();
+  }
+  process.exit();
+}
+
+const watchers = createWatchers(config, assetDeployer, instrumentExporter);
+
+function shutdown() {
+  assetDeployer.clearTimer();
+  instrumentExporter.clearTimer();
+  watchers.close();
+  console.log(`[${ts()}] Stopping ${pluginName} standalone`);
+  process.off('SIGINT', shutdown);
+  process.off('SIGTERM', shutdown);
+  standaloneManager.kill();
+}
+
+if (flags.standalone) {
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  process.on('exit', shutdown);
+}
+
+await esCtx.watch();
+console.log(`Watching for changes\n`);