@rotor-rbx/rotor 1.4.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 uproot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+Third-party components vendored in this repository retain their own licenses:
+- tsgo/ — mirror of microsoft/typescript-go, Apache License 2.0 (see tsgo/LICENSE,
+  tsgo/NOTICE, and tsgo/MIRROR.md for the statement of changes)
+- reference/ — roblox-ts and @roblox-ts/luau-ast sources, MIT License (see the
+  LICENSE files within each directory)
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+<p align="center">
+  <img src="media/logo.png" alt="rotor — an all in one roblox toolchain" width="480">
+</p>
+
+<p align="center"><em>TypeScript in, Roblox out — at native speed.</em></p>
+
+<p align="center">
+  <a href="https://github.com/uproot/rotor/releases/latest"><img src="https://img.shields.io/github/v/release/uproot/rotor" alt="latest release"></a>
+  <a href="https://github.com/uproot/rotor/actions/workflows/ci.yml"><img src="https://github.com/uproot/rotor/actions/workflows/ci.yml/badge.svg" alt="ci"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+rotor is an all-in-one Roblox toolchain, written in Go. At its core is a native rewrite of the [roblox-ts](https://roblox-ts.com) compiler built on [typescript-go](https://github.com/microsoft/typescript-go) — a drop-in `rbxtsc` replacement with **byte-identical Luau output** — plus a native Luau toolchain and Open Cloud asset + deployment pipelines, all in one binary.
+
+```sh
+bun add -d @rotor-rbx/rotor    # or: npm i -D @rotor-rbx/rotor — see Install for more ways
+```
+
+📖 [Documentation](docs.md) · 🤝 [Contributing](CONTRIBUTING.md) · 🗺️ [Roadmap](roadmap.md)
+
+## Features
+
+**Compile & check** — the rbxtsc replacement:
+
+```sh
+rotor check ./my-game -w     # native full-strictness typecheck: 222 files in 161 ms
+rotor build ./my-game -w     # byte-identical Luau, watch mode, incremental rebuilds
+rotor doctor                 # diagnose tsconfig, @rbxts packages, plugins, Rojo, cloud setup
+```
+
+Same `tsconfig.json`, same `@rbxts/*` packages, same transformer plugins (Flamework etc.), same CLI flags. Plus built-in extensions rbxtsc doesn't have: **`$env`** (compile-time environment variables from `.env` — `$env.GAME_NAME`, `$env("KEY", "fallback")`, no plugin needed) and **`$getModuleTree` on folders** (no `index.ts` required).
+
+**Luau toolchain** — works on any Rojo project, no rbxts required:
+
+```sh
+rotor dev                    # watch + incremental compile + rojo serve to Studio
+rotor bundle entry.luau -o bundle.luau --minify   # inline a require graph, still runnable
+rotor minify file.luau       # strip comments/whitespace, keep --! directives
+rotor pack --as luau         # whole project -> one self-reconstructing script (or rbxm/rbxmx)
+rotor sourcemap -o sourcemap.json                 # Rojo-compatible, for luau-lsp
+```
+
+**Cloud** — assets and deployment from one typed config (see below):
+
+```sh
+rotor asset sync             # upload new/changed assets, lockfile, typed codegen
+rotor deploy plan -e prod    # diff config vs live state (terraform-style, no network writes)
+rotor deploy apply -e prod   # publish places, settings, badges — only what drifted
+```
+
+**Scaffolding** — `rotor init` runs an interactive wizard (template, Biome/oxlint, starter packages, asset/deploy config) or scripts cleanly with `--yes`/`--template`.
+
+## Configuration — `rotor.config.ts`
+
+One typed TypeScript config drives the cloud tools. rotor evaluates it natively (no Node needed), generates `rotor-config.d.ts` for editor typing, and refuses npm imports — it's config, not a program:
+
+```ts
+import { defineConfig } from "@rotor-rbx/rotor";
+
+export default defineConfig({
+	assets: {
+		paths: ["assets/**/*.png", "assets/**/*.ogg"],
+		output: { luau: "src/shared/assets.luau", types: "src/shared/assets.d.ts" },
+		creator: { type: "group", id: 12345 },
+	},
+	deploy: {
+		environments: {
+			dev: {
+				universeId: 111,
+				places: { start: { file: "build/game.rbxl", placeId: 222 } },
+			},
+			prod: {
+				universeId: 333,
+				places: { start: { file: "build/game.rbxl", placeId: 444 } },
+				experience: { name: "My Game", playability: "public" },
+				badges: { winner: { name: "Winner!", description: "Beat the game", icon: "assets/badge.png" } },
+			},
+		},
+	},
+});
+```
+
+- **`rotor asset sync`** scans the globs, uploads new/changed files via Open Cloud (SHA-256 lockfile `rotor-lock.json` — unchanged files never re-upload, updates keep asset ids stable), and generates `assets.luau` + `assets.d.ts`, so code references `assets.sounds.hit` instead of hardcoded `rbxassetid://` strings.
+- **`rotor deploy`** is infrastructure-as-code: it diffs the config against per-environment state (`.rotor/deploy/<env>.json`), shows a plan, and applies only the drift — place file publishing, experience settings, badges (icons upload automatically first). Deletes require `--allow-deletes`.
+- Auth is an Open Cloud key in **`ROBLOX_API_KEY`** (scopes: Assets R/W, Universe Places W, Universe R/W). `rotor doctor` checks your config and key setup.
+- Compile-time env vars come from `.env` / `.env.<NODE_ENV>` next to your tsconfig and are inlined by the `$env` macro; rotor writes `rotor-env.d.ts` so your editor sees the types.
+
+Full config shape and every command flag: [docs.md](docs.md).
+
+## Install
+
+Grab a binary from [GitHub Releases](https://github.com/uproot/rotor/releases), or use a toolchain manager:
+
+```sh
+# mise
+mise use -g github:uproot/rotor@1.4.0
+
+# rokit
+rokit add uproot/rotor@1.4.0
+```
+
+```toml
+# aftman.toml
+[tools]
+rotor = "uproot/rotor@1.4.0"
+
+# foreman.toml
+[tools]
+rotor = { github = "uproot/rotor", version = "1.4.0" }
+```
+
+### Install via npm / bun
+
+For rbxts projects that already live in the JS ecosystem, install [`@rotor-rbx/rotor`](https://www.npmjs.com/package/@rotor-rbx/rotor) as a dev dependency — a postinstall step downloads the prebuilt binary for your platform:
+
+```sh
+bun add -d @rotor-rbx/rotor
+npm i -D @rotor-rbx/rotor
+pnpm add -D @rotor-rbx/rotor
+yarn add -D @rotor-rbx/rotor
+```
+
+Installing straight from GitHub works too: `bun add -d github:uproot/rotor` (npm/pnpm/yarn equivalents likewise).
+
+> **bun note:** bun skips postinstall scripts by default. Either add `"trustedDependencies": ["@rotor-rbx/rotor"]` to your project's `package.json` (then `bun install`), or do nothing — the `rotor` shim downloads the binary on first run. pnpm similarly asks you to approve build scripts (`pnpm approve-builds`), with the same first-run fallback.
+
+Or build from source (Go 1.25+):
+
+```sh
+git clone https://github.com/uproot/rotor && cd rotor
+go build ./cmd/rotor
+```
+
+## Benchmarks
+
+Measured on real production rbxts games, with output byte-identical to `rbxtsc` 3.0.0:
+
+| Workload | rotor |
+|----------|------:|
+| Full strict typecheck — 222-file production game | **161 ms** |
+| Full build — 95-file production game | **355 ms** |
+| Incremental watch rebuild — same game | **180 ms** |
+
+The JS toolchain spends longer than this booting Node. The ~10× speedup is structural: rotor runs Microsoft's native, parallel TypeScript compiler ([typescript-go](https://github.com/microsoft/typescript-go)) instead of the single-threaded JS one.
+
+## Contributors
+
+<a href="https://github.com/uproot"><img src="https://github.com/uproot.png" width="56" height="56" alt="uproot"></a>
+<a href="https://github.com/Coyenn"><img src="https://github.com/Coyenn.png" width="56" height="56" alt="Coyenn"></a>
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE). rotor stands on [roblox-ts](https://github.com/roblox-ts/roblox-ts) (MIT) and [typescript-go](https://github.com/microsoft/typescript-go) (Apache-2.0) — see [credits](docs.md#credits--licenses).

package/bin/rotor.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// npm/bun shim for the rotor CLI. Resolves the platform binary downloaded by
+// scripts/install.js (postinstall); if it is missing — e.g. bun skipped the
+// postinstall because "rotor" is not in trustedDependencies — downloads it on
+// first run, then execs it with the original args.
+"use strict";
+
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+const { install, binaryPath } = require("../scripts/install.js");
+
+async function main() {
+  let bin = binaryPath();
+  if (!fs.existsSync(bin)) {
+    bin = await install();
+  }
+
+  const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+  if (result.error) throw result.error;
+  if (result.signal) {
+    // Re-raise the child's fatal signal so callers see the same termination.
+    process.kill(process.pid, result.signal);
+    return;
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+main().catch((err) => {
+  console.error(err && err.message ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rotor-rbx/rotor",
+  "version": "1.4.0",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "description": "All-in-one Roblox toolchain: native roblox-ts compiler, Luau bundler, minifier, dev loop, and packer. This package downloads the prebuilt rotor binary from GitHub Releases.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uproot/rotor.git"
+  },
+  "homepage": "https://github.com/uproot/rotor#readme",
+  "bugs": {
+    "url": "https://github.com/uproot/rotor/issues"
+  },
+  "keywords": [
+    "roblox",
+    "roblox-ts",
+    "luau",
+    "typescript",
+    "compiler",
+    "bundler"
+  ],
+  "bin": {
+    "rotor": "bin/rotor.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/install.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// Downloads the prebuilt rotor binary for the current platform from GitHub
+// Releases. Runs as the package's postinstall hook; also required as a module
+// by bin/rotor.js for a first-run download when the postinstall was skipped
+// (e.g. bun without trustedDependencies).
+//
+// Plain Node, no dependencies. Requires Node 18+ (global fetch) or Bun.
+//
+// Env:
+//   ROTOR_INSTALL_BASE_URL  override the download base URL (testing/proxies);
+//                           defaults to the GitHub release for pkg.version.
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const pkg = require(path.join(__dirname, "..", "package.json"));
+
+const PLATFORM_MAP = { win32: "windows", linux: "linux", darwin: "darwin" };
+const ARCH_MAP = { x64: "amd64", arm64: "arm64" };
+
+// Anything smaller than this is not a real rotor binary (real ones are >10MB).
+const MIN_BINARY_SIZE = 1024 * 1024;
+
+function targetInfo() {
+  const os = PLATFORM_MAP[process.platform];
+  const arch = ARCH_MAP[process.arch];
+  if (!os || !arch) {
+    throw new Error(
+      `rotor: unsupported platform ${process.platform}-${process.arch} ` +
+        `(supported: windows/linux/darwin on amd64/arm64). ` +
+        `Build from source instead: go build ./cmd/rotor`
+    );
+  }
+  return { os, arch, ext: os === "windows" ? ".exe" : "" };
+}
+
+// Where the platform binary lives inside the installed package.
+function binaryPath() {
+  const { os, arch, ext } = targetInfo();
+  return path.join(__dirname, "..", "bin", `rotor-${os}-${arch}${ext}`);
+}
+
+function assetUrl() {
+  const { os, arch, ext } = targetInfo();
+  const base = (
+    process.env.ROTOR_INSTALL_BASE_URL ||
+    `https://github.com/uproot/rotor/releases/download/v${pkg.version}`
+  ).replace(/\/+$/, "");
+  return `${base}/rotor-v${pkg.version}-${os}-${arch}-bin${ext}`;
+}
+
+async function install({ force = false, quiet = false } = {}) {
+  const dest = binaryPath();
+
+  if (!force) {
+    try {
+      if (fs.statSync(dest).size > MIN_BINARY_SIZE) return dest; // already installed
+    } catch {
+      /* not downloaded yet */
+    }
+  }
+
+  const url = assetUrl();
+  if (!quiet) console.error(`rotor: downloading ${url}`);
+
+  let res;
+  try {
+    res = await fetch(url, { redirect: "follow" });
+  } catch (err) {
+    throw new Error(
+      `rotor: download failed for ${url}\n  ${err && err.message ? err.message : err}`
+    );
+  }
+
+  if (res.status === 404) {
+    throw new Error(
+      `rotor: binary not found (HTTP 404):\n  ${url}\n` +
+        `The v${pkg.version} release may not be published yet, or the asset for ` +
+        `this platform is missing.\n` +
+        `Grab a binary from https://github.com/uproot/rotor/releases or build ` +
+        `from source: go build ./cmd/rotor`
+    );
+  }
+  if (!res.ok) {
+    throw new Error(`rotor: download failed (HTTP ${res.status}) for ${url}`);
+  }
+
+  const buf = Buffer.from(await res.arrayBuffer());
+
+  // Write to a temp name then rename so a torn download never looks installed.
+  const tmp = dest + ".download";
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(tmp, buf);
+  if (process.platform !== "win32") fs.chmodSync(tmp, 0o755);
+  fs.renameSync(tmp, dest);
+
+  if (!quiet) {
+    console.error(
+      `rotor: installed ${path.basename(dest)} (${(buf.length / 1048576).toFixed(1)} MB)`
+    );
+  }
+  return dest;
+}
+
+module.exports = { install, binaryPath, assetUrl, MIN_BINARY_SIZE };
+
+if (require.main === module) {
+  install().catch((err) => {
+    console.error(err && err.message ? err.message : err);
+    process.exit(1);
+  });
+}