azul-sync 1.3.0

package/.gitattributes

@@ -0,0 +1 @@
+plugin/StudioWidgets/** linguist-vendored

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: Ransomwave
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. Windows 11]
+ - Azul Version [e.g. 1.2.0]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/README.md

@@ -0,0 +1,142 @@
+# <span><img src="./docs/assets/logo.png" alt="Azul Logo" height="30"></span> Azul
+
+Azul is a two-way synchronization tool between Roblox Studio and your local filesystem with full Luau-LSP support, which allows code completion & type checking.
+
+Azul allows you to use professional-grade tools like Visual Studio Code in Roblox development.
+
+_Yes, the name is a pun on Rojo (Spanish for "red"). Azul means "blue"!_
+
+<a href="#quick-start"><b>Quick Start</b></a> — <a href="#why-azul"><b>Why Azul</b></a> — <a href="https://github.com/Ransomwave/azul/wiki"><b>Documentation</b></a>
+
+## Philosophy
+
+Azul treats **Studio as the source of truth**. The local filesystem mirrors what's in Studio, not the other way around.
+
+Azul avoids the complexity and ambiguity that can come with tools like Rojo: for example, deciding a new Script's parent class, properties, or attributes. Rather than trying to encode Studio state in extra files (e.g. `*.meta.json`), Azul lets Studio be the source of truth. This, in my opinion, leads to a much simpler and more intuitive workflow.
+
+Azul also allows pushing local files into Studio using the `azul build` command, which creates or overwrites instances in Studio based on your local files.
+
+## Features
+
+- - [x] 🔄 **Bi-directional sync**: Changes in Studio update files, and file edits update Studio
+- - [x] 🏗️ **[Build command](https://github.com/Ransomwave/azul/wiki/Getting-started#building-from-an-existing-project)**: `azul build` one-time pushes your local files into Studio (creates or overwrites, never deletes)
+- - [x] 📦 **[Push command](https://github.com/Ransomwave/azul/wiki/Commands#azul-push)**: `azul push` selectively pushes local files. Useful when importing external libraries or using package managers (i.e Wally)
+- - [x] 🔴 **Rojo compatibility mode**: Supports importing from Rojo projects with the `--rojo` flag.
+- - [x] 🌳 **DataModel mirroring**: Instance hierarchy 1:1 mapped to folder structure
+- - [x] 🎯 **No manual config / required structure**: Works out of the box with new and existing Roblox Studio projects, regardless of structure.
+- - [x] 🗺️ **Automatic sourcemap generation**: Generates a Rojo-compatible `sourcemap.json` so tools like Luau-lsp work out of the box.
+
+### Upcoming Features
+
+- [ ] 🏛️ **Fully hermetic builds**: Make Azul fully serialize `Instance` properties, allowing for fully reproducible 1:1 builds.
+
+## Why Azul?
+
+Because Azul is as simple as it gets: Run the azul command in your project folder, connect the companion plugin in Studio & start coding.
+
+Compatible with projects both old and new, no more extra worrying about how to “Rojo-ify” your project. Your code is literally 1:1 mapped to what’s in Studio.
+
+### Rojo already exists, why make another tool?
+
+While Rojo is a powerful tool, I don't believe it's always the best fit for every developer or project. Otherwise trivial tasks in Studio, like inserting a Script inside Tool or Model, suddenly become non-trivial challenges. Rojo just lacks the flexibility of Studio.
+
+Azul is my approach to solve these issues. I built Azul for workflows similar to mine: Studio-first developers who'd rather manage their projects in the dedicated environment instead of fighting with meta files.
+
+### Why not use the upcoming Script Sync feature?
+
+Azul offers several advantages over the upcoming Script Sync feature:
+
+- **Azul mirrors everything**: Script Sync can only sync specified folders and scripts, not entire projects. Azul directly mirrors the entire DataModel, meaning you don't have to worry about manually syncing specific parts of your project.
+
+- **Building from filesystem**: Script Sync only syncs changes made in Studio to the filesystem. Azul allows you to push changes from your local files into Studio using the `azul build` command.
+
+- **Pushing from filesystem**: Sync any code you have stored locally directly to your desired destination using `azul push`. Useful when importing external libraries (e.g. GitHub) or when using Package Managers (e.g. Wally, pesde)
+
+- **Rojo compatibility**: Azul can import existing Rojo projects using the `--rojo` & `--rojo-project=<ProjectFile>` flags, making Azul compatible with many existing open source projects.
+  - **Generates a Rojo-compatible `sourcemap.json`**: This allows any tooling that require Rojo-style sourcemaps _(like luau-lsp, the language server)_ to work seamlessly.
+
+- **You can use it today!**: Azul requires no commitment to a specific project structure. If you want to try out Script Sync (or any other tool) in the future, Azul won't get in your way.
+
+---
+
+## Quick Start
+
+### Auto-Install (Recommended)
+
+1. Install Node.js from [nodejs.org](https://nodejs.org/).
+2. Run the following command in your terminal:
+   ```ps1
+   npm install -g azul
+   ```
+3. Install the Azul Companion Plugin to Roblox Studio.
+   - **Guide: [Azul Plugin: Install Instructions](/plugin/README.md)**
+4. Create a new Folder to house your Azul project and open it in your IDE.
+5. With the terminal in your project folder, run:
+   ```
+   azul
+   ```
+6. In Roblox Studio, click on the "Connect" button in the Azul plugin.
+7. Start coding!
+8. _(Optional)_ For the best experience, check out the [Recommended Tools & Extensions](#recommended-tools--extensions).
+
+### Manual Install
+
+1. Clone this repository using Git:
+   ```ps1
+   git clone https://github.com/Ransomwave/azul.git
+   ```
+2. Install Node.js from [nodejs.org](https://nodejs.org/) or by using your system's package manager:
+   ```ps1
+   # Windows (using winget)
+   winget install OpenJS.NodeJS.LTS
+   # macOS (using Homebrew)
+   brew install node
+   # Linux (using apt)
+   sudo apt install nodejs npm
+   ```
+3. Install dependencies by running
+   ```ps1
+   npm install
+   ```
+4. Build the project
+   ```ps1
+   npm run build
+   ```
+5. Install the project globally
+   ```ps1
+   npm install -g .
+   ```
+6. Install the Azul Companion Plugin to Roblox Studio.
+   - **Guide: [Azul Plugin: Install Instructions](/plugin/README.md)**
+7. Create a new Folder to house your Azul project and open it in your IDE.
+8. With the terminal in your project folder, run:
+   ```ps1
+   azul
+   ```
+9. In Roblox Studio, click on the "Connect" button in the Azul plugin.
+
+## Recommended Tools & Extensions
+
+### VSCode with Luau-LSP
+
+To get the best experience, use [Visual Studio Code](https://code.visualstudio.com/) with the [Luau Language Server extension](https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.luau-lsp).
+
+To get IntelliSense working, open your `User Settings (JSON)` from the command palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) and make sure to set up luau-lsp like this:
+
+```json
+  "luau-lsp.plugin.enabled": true,
+  "luau-lsp.sourcemap.enabled": true,
+  "luau-lsp.sourcemap.autogenerate": false,
+  "luau-lsp.sourcemap.sourcemapFile": "sourcemap.json",
+  "luau-lsp.sourcemap.includeNonScripts": true,
+```
+
+This is my recommended setup for Azul projects. That said, Azul is compatible with any IDE or text editor that can edit `.luau` files. Luau-LSP is also available for other editors like [Neovim](https://github.com/lopi-py/luau-lsp.nvim).
+
+### VSCode with Verde
+
+[Verde](https://marketplace.visualstudio.com/items?itemName=Dvitash.verde) is a VSCode extension that mimics the Roblox Studio Explorer and Properties windows. It works great alongside Azul to provide a seamless development experience.
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests on GitHub. I want to make Azul the best it can be for myself and anybody who wants to use it.

package/dist/build.d.ts

@@ -0,0 +1,19 @@
+interface BuildOptions {
+    syncDir?: string;
+    rojoMode?: boolean;
+    rojoProjectFile?: string;
+    applySourcemap?: boolean;
+    fromSourcemap?: boolean;
+}
+export declare class BuildCommand {
+    private ipc;
+    private syncDir;
+    private rojoMode;
+    private rojoProjectFile?;
+    private applySourcemap;
+    private fromSourcemap;
+    constructor(options?: BuildOptions);
+    run(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAcA,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,aAAa,CAAU;gBAEnB,OAAO,GAAE,YAAiB;IAWzB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;CA8ElC"}

package/dist/build.js

@@ -0,0 +1,92 @@
+import path from "node:path";
+import fs from "node:fs";
+import { IPCServer } from "./ipc/server.js";
+import { config } from "./config.js";
+import { log } from "./util/log.js";
+import { SnapshotBuilder } from "./snapshot.js";
+import { RojoSnapshotBuilder } from "./snapshot/rojo.js";
+import { applySourcemapProperties, buildInstancesFromSourcemap, loadSourcemapPropertyIndex, } from "./sourcemap/propertyLoader.js";
+export class BuildCommand {
+    ipc;
+    syncDir;
+    rojoMode;
+    rojoProjectFile;
+    applySourcemap;
+    fromSourcemap;
+    constructor(options = {}) {
+        this.syncDir = path.resolve(options.syncDir ?? config.syncDir);
+        this.rojoMode = Boolean(options.rojoMode);
+        this.rojoProjectFile = options.rojoProjectFile;
+        this.applySourcemap = options.applySourcemap !== false;
+        this.fromSourcemap = options.fromSourcemap === true;
+        this.ipc = new IPCServer(config.port, undefined, {
+            requestSnapshotOnConnect: false,
+        });
+    }
+    async run() {
+        const builder = this.rojoMode
+            ? new RojoSnapshotBuilder({
+                projectFile: this.rojoProjectFile,
+                cwd: process.cwd(),
+                destPrefix: [],
+            })
+            : new SnapshotBuilder({
+                sourceDir: this.syncDir,
+                destPrefix: [],
+                skipSymlinks: true,
+            });
+        if (this.rojoMode) {
+            log.info(`Preparing Rojo compatibility build from ${this.rojoProjectFile ?? "default.project.json"}`);
+        }
+        else {
+            log.info(`Preparing build snapshot from ${this.syncDir}`);
+        }
+        let instances = [];
+        if (!this.rojoMode && this.fromSourcemap) {
+            const built = buildInstancesFromSourcemap(config.sourcemapPath);
+            if (!built) {
+                log.warn("Falling back to filesystem build because sourcemap import failed.");
+            }
+            else {
+                instances = built;
+            }
+        }
+        if (instances.length === 0) {
+            try {
+                instances = await builder.build();
+            }
+            catch (error) {
+                log.error(`${error}`);
+                return;
+            }
+        }
+        if (!this.rojoMode && this.applySourcemap && !this.fromSourcemap) {
+            const index = loadSourcemapPropertyIndex(config.sourcemapPath);
+            const applied = applySourcemapProperties(instances, index);
+            if (applied > 0) {
+                log.success(`Applied properties/attributes from sourcemap to ${applied} instance(s)`);
+            }
+            else {
+                if (!index && fs.existsSync(config.sourcemapPath)) {
+                    log.warn("Sourcemap present but could not be parsed; continuing without properties.");
+                }
+                else {
+                    log.info("No packed properties found in sourcemap; continuing with script/folder snapshot only.");
+                }
+            }
+        }
+        log.info(`Waiting for Studio to connect on port ${config.port}...`);
+        await new Promise((resolve) => {
+            this.ipc.onConnection(() => {
+                log.info("Studio connected. Sending build snapshot...");
+                this.ipc.send({ type: "buildSnapshot", data: instances });
+                log.success(`Sent ${instances.length} instances`);
+                setTimeout(() => {
+                    this.ipc.close();
+                    resolve();
+                }, 200);
+            });
+        });
+    }
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}