azul-sync 1.3.0

package/plugin/sync/ReplicatedFirst/AzulCompanionPlugin/UI.luau

@@ -0,0 +1,425 @@
+--!strict
+--[[
+	Azul UI Module
+	Manages the companion plugin's dock widget and settings interface
+]]
+
+local UI = {}
+
+local Config = require("./Config")
+local Enums = require("./Enums")
+
+UI.__index = UI
+
+export type CallbackFunctions = {
+	onStartSync: () -> (),
+	onStopSync: () -> (),
+	onDebugModeChanged: (boolean) -> ()?,
+	onSilentModeChanged: (boolean) -> ()?,
+	onConfigChanged: (string, any) -> (),
+	onSettingsScopeChanged: (number) -> (),
+	onClearGuids: () -> (),
+	onSourcemapReload: () -> (),
+}
+
+type SelfType = {
+	plugin: Plugin,
+	config: { any },
+	callbacks: CallbackFunctions,
+	LOGO: string,
+	LOGO_SYNCED: string,
+	settingsScope: string,
+	debugPrint: (...string) -> (),
+	infoPrint: (...string) -> (),
+	saveSettings: () -> (),
+	loadSettings: () -> (),
+	rebuildServiceSet: () -> (),
+
+	isSyncEnabled: boolean,
+
+	azulWidget: DockWidgetPluginGui,
+	connectButton: PluginToolbarButton,
+	titleImageLabel: ImageLabel,
+	syncButton: any,
+	debugModeCheckbox: any,
+	silentModeCheckbox: any,
+	settingsScopeDropdown: any,
+	websocketUrlLabel: any,
+	heartbeatIntervalLabel: any,
+	listTypeLabel: any,
+	serviceListLabel: any,
+	excludedParentsLabel: any,
+	clearGuidsButton: any,
+	reloadSourcemapButton: any,
+
+	GetSyncState: (SelfType) -> boolean,
+	UpdateSyncState: (SelfType, boolean) -> (),
+	UpdateConfig: (SelfType) -> (),
+	SetSettingsScope: (SelfType, any) -> (),
+}
+
+UI.logo = "rbxassetid://134336592598474"
+UI.syncedLogo = "rbxassetid://103599828888609"
+
+local function createInfoLabel(text: string)
+	local label = Instance.new("TextLabel")
+	label.Name = "InfoLabel"
+	label.RichText = true
+	label.AutomaticSize = Enum.AutomaticSize.Y
+	label.TextWrapped = true
+	label.Size = UDim2.new(1, 0, 0, 15)
+	label.BackgroundTransparency = 1
+	label.TextColor3 = Color3.new(0.5, 0.5, 0.5)
+	label.Font = Enum.Font.SourceSans
+	label.TextSize = 15
+	label.Text = `{text}<br/>`
+	label.TextXAlignment = Enum.TextXAlignment.Left
+
+	local padding = Instance.new("UIPadding")
+	padding.PaddingLeft = UDim.new(0, 30)
+	padding.PaddingRight = UDim.new(0, 30)
+	padding.Parent = label
+
+	return label
+end
+
+--[=[
+	Initialize the UI widget
+	
+	Parameters:
+	- plugin: The plugin object from the Roblox plugin API
+	- config: Reference to the CONFIG table
+	- settingsScope: Reference to the settingsScope variable`
+	- callbacks: Table with callbacks:
+	  - onStartSync: Called when user clicks Connect
+	  - onStopSync: Called when user clicks Disconnect
+	  - onDebugModeChanged: Called when debug mode checkbox changes
+	  - onSilentModeChanged: Called when silent mode checkbox changes
+	  - onConfigChanged: Called when any config value changes (receives {key, value})
+	  - onSettingsScopeChanged: Called when scope changes
+	  - onClearGuids: Called when clear GUIDs button is clicked
+	- helpers: Table with helper functions:
+	  - debugPrint: Debug print function
+	  - infoPrint: Info print function
+	  - saveSettings: Save settings function
+	  - loadSettings: Load settings function
+	  - rebuildServiceSet: Rebuild service set function
+	
+	Returns: Table with methods:
+	- updateSyncState(enabled: boolean): Update UI to reflect sync state
+	- updateConfig(): Refresh UI with current CONFIG values
+]=]
+function UI.new(plugin, callbacks, settingsScope, helpers): SelfType
+	local self = {} :: SelfType
+	setmetatable(self, UI)
+
+	-- Store references
+	self.plugin = plugin
+	self.callbacks = callbacks
+	self.LOGO = UI.logo
+	self.LOGO_SYNCED = UI.syncedLogo
+	self.settingsScope = settingsScope
+	self.debugPrint = helpers.debugPrint
+	self.infoPrint = helpers.infoPrint
+	self.saveSettings = helpers.saveSettings
+	self.loadSettings = helpers.loadSettings
+	self.rebuildServiceSet = helpers.rebuildServiceSet
+
+	-- Track sync enabled state locally (PluginToolbarButton has SetActive but no GetActive)
+	self.isSyncEnabled = false
+
+	-- Import UI components
+	local VerticalScrollingFrame = require("./StudioWidgets/Components/VerticalScrollingFrame")
+	local CollapsibleTitledSection = require("./StudioWidgets/Components/CollapsibleTitledSection")
+	local CustomTextButton = require("./StudioWidgets/Components/CustomTextButton")
+	local LabeledCheckbox = require("./StudioWidgets/Components/LabeledCheckbox")
+	local LabeledMultiChoice = require("./StudioWidgets/Components/LabeledMultiChoice")
+	local LabeledTextInput = require("./StudioWidgets/Components/LabeledTextInput")
+	local DropdownMenu = require("./StudioWidgets/Components/DropdownMenu")
+
+	-- Create toolbar button
+	local toolbar = plugin:CreateToolbar("Azul")
+	self.connectButton = toolbar:CreateButton("Azul", "Connect/disconnect from sync daemon", self.LOGO)
+
+	-- Create widget
+	local widgetInfo = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, true, 345, 640, 300, 300)
+
+	local azulWidget = plugin:CreateDockWidgetPluginGuiAsync("azulWidget", widgetInfo)
+	azulWidget.Name = "AzulCompanionPlugin"
+	azulWidget.Title = "Azul"
+	self.azulWidget = azulWidget
+
+	-- Create main scroll frame
+	local mainScrollFrame = VerticalScrollingFrame.new("main")
+	mainScrollFrame:GetContentsFrame().Parent = azulWidget
+
+	local mainSectionListLayout = Instance.new("UIListLayout")
+	mainSectionListLayout.Parent = mainScrollFrame:GetSectionFrame()
+	mainSectionListLayout.Padding = UDim.new(0, 0)
+	mainSectionListLayout.SortOrder = Enum.SortOrder.LayoutOrder
+	mainSectionListLayout.HorizontalAlignment = Enum.HorizontalAlignment.Center
+
+	-- Main section
+	local mainSection = CollapsibleTitledSection.new("mainSection", "Azul Companion Plugin", true, false, false, false)
+	mainSection:GetSectionFrame().LayoutOrder = 0
+	mainSection:GetSectionFrame().Parent = mainScrollFrame:GetContentsFrame()
+
+	-- Title image
+	local imageContainer = Instance.new("Frame")
+	imageContainer.Size = UDim2.new(1, 0, 0, 70)
+	imageContainer.BackgroundTransparency = 1
+
+	local imageContainerListLayout = Instance.new("UIListLayout")
+	imageContainerListLayout.FillDirection = Enum.FillDirection.Horizontal
+	imageContainerListLayout.HorizontalAlignment = Enum.HorizontalAlignment.Center
+	imageContainerListLayout.VerticalAlignment = Enum.VerticalAlignment.Center
+	imageContainerListLayout.Parent = imageContainer
+
+	local titleImageLabel = Instance.new("ImageLabel")
+	titleImageLabel.Size = UDim2.fromScale(0.2, 1)
+	titleImageLabel.AutomaticSize = Enum.AutomaticSize.X
+	titleImageLabel.BackgroundTransparency = 1
+	titleImageLabel.Image = self.LOGO
+	titleImageLabel.ScaleType = Enum.ScaleType.Fit
+	titleImageLabel.LayoutOrder = 0
+	titleImageLabel.Parent = imageContainer
+
+	local azulText = Instance.new("TextLabel")
+	azulText.Text = "<b>Azul</b>"
+	azulText.RichText = true
+	azulText.Font = Enum.Font.RobotoMono
+	azulText.TextSize = 36
+	azulText.TextScaled = true
+	azulText.Size = UDim2.fromScale(0.1, 1)
+	azulText.AutomaticSize = Enum.AutomaticSize.X
+	azulText.TextColor3 = Color3.fromRGB(255, 255, 255)
+	azulText.BackgroundTransparency = 1
+	azulText.LayoutOrder = 1
+	azulText.Parent = imageContainer
+
+	local padding = Instance.new("UIPadding")
+	padding.PaddingTop = UDim.new(0, 10)
+	padding.PaddingBottom = UDim.new(0, 10)
+	padding.Parent = imageContainer
+
+	mainSection:AddChild(imageContainer, 0)
+	self.titleImageLabel = titleImageLabel
+
+	-- Sync button
+	local syncButton = CustomTextButton.new("toggleSync", "Connect", false)
+	syncButton.Parent = mainScrollFrame:GetContentsFrame()
+	syncButton:SetSize(UDim2.fromScale(1, 0.2))
+
+	local syncButtonPadding = Instance.new("UIPadding")
+	syncButtonPadding.PaddingLeft = UDim.new(0.1, 0)
+	syncButtonPadding.PaddingRight = UDim.new(0.1, 0)
+	syncButtonPadding.Parent = syncButton:GetFrame()
+
+	syncButton:SetClickedFunction(function()
+		if self.isSyncEnabled then
+			syncButton:GetButton().Text = "Stopping..."
+			self.callbacks.onStopSync()
+		else
+			syncButton:GetButton().Text = "Connecting..."
+			self.callbacks.onStartSync()
+		end
+	end)
+	mainSection:AddChild(syncButton:GetFrame())
+	self.syncButton = syncButton
+
+	-- Silent Mode checkbox
+	local silentModeCheckbox = LabeledCheckbox.new("silentMode", "Silent Mode", Config.SILENT_MODE, false)
+	silentModeCheckbox:SetValue(Config.SILENT_MODE)
+	silentModeCheckbox:SetValueChangedFunction(function(newValue)
+		Config.SILENT_MODE = newValue
+		helpers.infoPrint(`[🐛 AzulUI]: Silent mode set to: {newValue}`)
+	end)
+	mainSection:AddChild(silentModeCheckbox:GetFrame())
+	mainSection:AddChild(createInfoLabel("Silent mode suppresses all console output except errors."))
+	self.silentModeCheckbox = silentModeCheckbox
+
+	-- Debug Mode checkbox
+	local debugModeCheckbox = LabeledCheckbox.new("debugMode", "Debug Mode", Config.DEBUG_MODE, false)
+	debugModeCheckbox:SetValue(Config.DEBUG_MODE)
+	debugModeCheckbox:SetValueChangedFunction(function(newValue)
+		Config.DEBUG_MODE = newValue
+		helpers.debugPrint(`[🐛 AzulUI]: Debug mode set to: {newValue}`)
+	end)
+	mainSection:AddChild(debugModeCheckbox:GetFrame())
+	mainSection:AddChild(createInfoLabel("Debug mode enables verbose logging to the output console."))
+	self.debugModeCheckbox = debugModeCheckbox
+
+	-- Settings section
+	local settingsSection = CollapsibleTitledSection.new("settings", "Plugin Settings", true, true, true)
+	settingsSection:GetSectionFrame().LayoutOrder = 1
+	settingsSection:GetSectionFrame().Parent = mainScrollFrame:GetContentsFrame()
+
+	-- Settings scope dropdown
+	local scopeChoices = {
+		{ Id = 1, Text = "Global" },
+		{ Id = 2, Text = "Project" },
+	}
+	local settingsScopeDropdown = DropdownMenu.new("settingsScope", "Scope", scopeChoices, "Select ...")
+	settingsSection:AddChild(settingsScopeDropdown:GetSectionFrame())
+	self.settingsScopeDropdown = settingsScopeDropdown
+
+	-- WebSocket URL input
+	local websocketUrlLabel = LabeledTextInput.new("websocketUrl", "WebSocket URL:", Config.WS_URL)
+	websocketUrlLabel:SetValue(Config.WS_URL)
+	websocketUrlLabel:SetValueChangedFunction(function(newValue)
+		Config.WS_URL = newValue
+		self.callbacks.onConfigChanged("WS_URL", newValue)
+	end)
+	settingsSection:AddChild(websocketUrlLabel:GetFrame())
+	self.websocketUrlLabel = websocketUrlLabel
+
+	-- Heartbeat Interval input
+	local heartbeatIntervalLabel =
+		LabeledTextInput.new("heartbeatInterval", "Heartbeat Interval (s):", tostring(Config.HEARTBEAT_INTERVAL))
+	heartbeatIntervalLabel:SetValue(tostring(Config.HEARTBEAT_INTERVAL))
+	heartbeatIntervalLabel:SetValueChangedFunction(function(newValue)
+		local interval = tonumber(newValue)
+		if interval and interval > 0 then
+			Config.HEARTBEAT_INTERVAL = interval
+			self.callbacks.onConfigChanged("HEARTBEAT_INTERVAL", interval)
+		end
+	end)
+	settingsSection:AddChild(heartbeatIntervalLabel:GetFrame())
+	settingsSection:AddChild(createInfoLabel("Interval in seconds between heartbeat pings to the daemon."))
+	self.heartbeatIntervalLabel = heartbeatIntervalLabel
+
+	-- List type dropdown
+	local listTypeLabel = LabeledMultiChoice.new("listType", "Service List Type:", {
+		{ Id = "WHITELIST", Text = "Whitelist" },
+		{ Id = "BLACKLIST", Text = "Blacklist" },
+	}, if Config.LIST_TYPE == Enums.listType.WHITELIST then 1 else 2)
+	listTypeLabel:SetValueChangedFunction(function(newIndex)
+		if newIndex == 1 then
+			Config.LIST_TYPE = Enums.listType.WHITELIST
+		else
+			Config.LIST_TYPE = Enums.listType.BLACKLIST
+		end
+		self.callbacks.onConfigChanged("LIST_TYPE", Config.LIST_TYPE)
+	end)
+	settingsSection:AddChild(listTypeLabel:GetFrame())
+	settingsSection:AddChild(
+		createInfoLabel(
+			"Whitelist: only services in the list are synced.<br />Blacklist: services in the list are excluded."
+		)
+	)
+	self.listTypeLabel = listTypeLabel
+
+	-- Service List input
+	local serviceListLabel =
+		LabeledTextInput.new("serviceList", "Service List:", table.concat(Config.SERVICE_LIST, ", "))
+	serviceListLabel:SetMaxGraphemes(9999)
+	serviceListLabel:SetValue(table.concat(Config.SERVICE_LIST, ", "))
+	serviceListLabel:SetValueChangedFunction(function(newValue)
+		local services = {}
+		for serviceName in string.gmatch(newValue, "([^,%s]+)") do
+			table.insert(services, serviceName)
+		end
+		Config.SERVICE_LIST = services
+		self.rebuildServiceSet()
+		self.callbacks.onConfigChanged("SERVICE_LIST", services)
+	end)
+	settingsSection:AddChild(serviceListLabel:GetFrame())
+	settingsSection:AddChild(createInfoLabel("List of services to include/exclude based on the selected List Type."))
+	self.serviceListLabel = serviceListLabel
+
+	-- Excluded Parents input
+	local excludedParentsLabel =
+		LabeledTextInput.new("excludedParents", "Excluded Parents:", table.concat(Config.EXCLUDED_PARENTS, ", "))
+	excludedParentsLabel:SetValue(table.concat(Config.EXCLUDED_PARENTS, ", "))
+	excludedParentsLabel:SetValueChangedFunction(function(newValue)
+		local excluded = {}
+		for parentName in string.gmatch(newValue, "([^,%s]+)") do
+			table.insert(excluded, parentName)
+		end
+		Config.EXCLUDED_PARENTS = excluded
+		self.callbacks.onConfigChanged("EXCLUDED_PARENTS", excluded)
+	end)
+	settingsSection:AddChild(excludedParentsLabel:GetFrame())
+	settingsSection:AddChild(createInfoLabel("List of parent paths to exclude from syncing, separated by commas."))
+	self.excludedParentsLabel = excludedParentsLabel
+
+	settingsScopeDropdown:SetValue(if self.settingsScope == Enums.scope.GLOBAL then 1 else 2)
+
+	-- Settings scope callback
+	settingsScopeDropdown:SetValueChangedFunction(function(newValue: number | string, newText: string)
+		helpers.debugPrint("[🐛 AzulUI]: Settings scope changed to:", newText)
+
+		local newScope
+		if newValue == 1 then
+			newScope = Enums.scope.GLOBAL
+		elseif newValue == 2 then
+			newScope = Enums.scope.PROJECT
+		else
+			return
+		end
+
+		self.callbacks.onSettingsScopeChanged(newScope)
+	end)
+
+	-- Reload sourcemap button
+	local reloadSourcemapButton = CustomTextButton.new("reloadSourcemap", "Reload Sourcemap", false)
+	reloadSourcemapButton:SetClickedFunction(function()
+		self.callbacks.onSourcemapReload()
+	end)
+	reloadSourcemapButton:SetSize(UDim2.fromScale(1, 0.07))
+
+	local clearButtonPadding = Instance.new("UIPadding")
+	clearButtonPadding.PaddingLeft = UDim.new(0.1, 0)
+	clearButtonPadding.PaddingRight = UDim.new(0.1, 0)
+	clearButtonPadding.Parent = reloadSourcemapButton:GetFrame()
+
+	settingsSection:AddChild(reloadSourcemapButton:GetFrame())
+	settingsSection:AddChild(
+		createInfoLabel("Something's not right? Force reload the sourcemap to reset the sync state.")
+	)
+	self.reloadSourcemapButton = reloadSourcemapButton
+
+	-- Connect button click handler
+	self.connectButton.Click:Connect(function()
+		azulWidget.Enabled = not azulWidget.Enabled
+	end)
+
+	return (self :: any) :: SelfType
+end
+
+function UI:GetSyncState()
+	return self.isSyncEnabled
+end
+
+function UI:UpdateSyncState(enabled: boolean)
+	self.isSyncEnabled = enabled
+	self.connectButton:SetActive(enabled)
+	if enabled then
+		self.connectButton.Icon = self.LOGO_SYNCED
+		self.syncButton:GetButton().Text = "Disconnect"
+		self.titleImageLabel.Image = self.LOGO_SYNCED
+	else
+		self.connectButton.Icon = self.LOGO
+		self.syncButton:GetButton().Text = "Connect"
+		self.titleImageLabel.Image = self.LOGO
+	end
+end
+
+function UI:SetSettingsScope(scope)
+	self.settingsScope = scope
+end
+
+function UI:UpdateConfig()
+	self = self :: SelfType
+
+	self.debugModeCheckbox:SetValue(Config.DEBUG_MODE)
+	self.silentModeCheckbox:SetValue(Config.SILENT_MODE)
+	self.settingsScopeDropdown:SetValue(if self.settingsScope == Enums.scope.GLOBAL then 1 else 2)
+	self.websocketUrlLabel:SetValue(Config.WS_URL)
+	self.heartbeatIntervalLabel:SetValue(tostring(Config.HEARTBEAT_INTERVAL))
+	self.listTypeLabel:SetSelectedIndex(if Config.LIST_TYPE == Enums.listType.WHITELIST then 1 else 2)
+	self.serviceListLabel:SetValue(table.concat(Config.SERVICE_LIST, ", "))
+	self.excludedParentsLabel:SetValue(table.concat(Config.EXCLUDED_PARENTS, ", "))
+end
+
+return UI

package/plugin/sync/ReplicatedFirst/AzulCompanionPlugin/WebSocketClient.luau

@@ -0,0 +1,161 @@
+--!strict
+--[[
+	WebSocket Client for Roblox Studio
+	
+	Uses Roblox Studio's native WebSocket support (WebStreamClient) for real-time
+	bidirectional communication with the sync daemon.
+
+	Ransomwave 2025
+]]
+
+local HttpService = game:GetService("HttpService")
+
+local WebSocketClient = {}
+WebSocketClient.__index = WebSocketClient
+
+type configType = {
+	debugMode: boolean?,
+	silentMode: boolean?,
+}
+
+-- self type
+type WebSocketClient = {
+	url: string,
+	client: WebStreamClient,
+	connected: boolean,
+	messageHandlers: { [string]: (any) -> () },
+	config: configType,
+
+	new: (url: string?) -> WebSocketClient,
+	on: (self: WebSocketClient, event: string, handler: (any) -> ()) -> (),
+	connect: (self: WebSocketClient) -> boolean,
+	handleMessage: (self: WebSocketClient, message: string) -> (),
+	send: (self: WebSocketClient, message: string) -> boolean,
+	disconnect: (self: WebSocketClient) -> (),
+	debugPrint: (self: WebSocketClient, ...any) -> (),
+	infoPrint: (self: WebSocketClient, ...any) -> (),
+}
+
+function WebSocketClient.new(url, config: configType?)
+	local self = setmetatable({}, WebSocketClient)
+	self.url = url or "ws://localhost:8080"
+	self.client = nil
+	self.connected = false
+	self.messageHandlers = {}
+	self.onClosed = Instance.new("BindableEvent")
+	self.config = config or {
+		debugMode = false,
+		silentMode = true,
+	}
+
+	if self.config.debugMode then print("[🐛 WebSocket]: Debug mode is enabled!") end
+
+	return (self :: any) :: WebSocketClient
+end
+
+function WebSocketClient:debugPrint(...)
+	self = self :: WebSocketClient
+	if self.config.silentMode or not self.config.debugMode then return end
+	print(...)
+end
+
+function WebSocketClient:infoPrint(...)
+	self = self :: WebSocketClient
+	if self.config.silentMode then return end
+	print(...)
+end
+
+function WebSocketClient:on(event, handler)
+	self = self :: WebSocketClient
+	self.messageHandlers[event] = handler
+end
+
+function WebSocketClient:connect()
+	self = self :: WebSocketClient
+	if self.connected then return true end
+
+	-- Create WebSocket client using CreateWebStreamClient
+	local success, result = pcall(function()
+		return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, {
+			Url = self.url,
+		})
+	end)
+
+	if not success then
+		warn("[WebSocket]: Connection failed:", result)
+		if self.messageHandlers.error then self.messageHandlers.error(result) end
+		return false
+	end
+
+	self.client = result
+	self.connected = true
+
+	-- Set up message handler (only MessageReceived is documented)
+	self.client.MessageReceived:Connect(function(message)
+		local parseSuccess, parseError = pcall(function()
+			self:handleMessage(message)
+		end)
+		if not parseSuccess then warn("[WebSocket]: Error handling message:", parseError) end
+	end)
+
+	-- Notify connection established
+	self:debugPrint("[🐛 WebSocket]: Connected to", self.url)
+	if self.messageHandlers.connect then task.defer(function()
+		self.messageHandlers.connect()
+	end) end
+
+	return true
+end
+
+function WebSocketClient:handleMessage(message)
+	self = self :: WebSocketClient
+	if not message or message == "" then return end
+
+	self:debugPrint("[🐛 WebSocket]: Received message:", string.sub(message, 1, 100))
+
+	local success, data = pcall(function()
+		return HttpService:JSONDecode(message)
+	end)
+
+	if success and self.messageHandlers.message then
+		self.messageHandlers.message(data)
+	elseif not success then
+		warn("[WebSocket]: Failed to parse message:", message)
+	end
+end
+
+function WebSocketClient:send(message)
+	self = self :: WebSocketClient
+	if not self.connected or not self.client then
+		warn("[WebSocket]: Cannot send: not connected")
+		return false
+	end
+
+	self:debugPrint("[🐛 WebSocket]: Sending:", string.sub(message, 1, 200))
+
+	local success, err = pcall(function()
+		self.client:Send(message)
+	end)
+
+	if not success then
+		warn("[WebSocket]: Send failed:", err)
+		return false
+	end
+
+	return true
+end
+
+function WebSocketClient:disconnect()
+	self = self :: WebSocketClient
+
+	if not self.connected or not self.client then return end
+
+	self.connected = false
+
+	self.client:Close()
+	-- self.client = nil
+
+	if self.messageHandlers.disconnect then self.messageHandlers.disconnect() end
+end
+
+return WebSocketClient

package/src/build.ts

@@ -0,0 +1,120 @@
+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 type { InstanceData } from "./ipc/messages.js";
+import {
+  applySourcemapProperties,
+  buildInstancesFromSourcemap,
+  loadSourcemapPropertyIndex,
+} from "./sourcemap/propertyLoader.js";
+
+interface BuildOptions {
+  syncDir?: string;
+  rojoMode?: boolean;
+  rojoProjectFile?: string;
+  applySourcemap?: boolean;
+  fromSourcemap?: boolean;
+}
+
+export class BuildCommand {
+  private ipc: IPCServer;
+  private syncDir: string;
+  private rojoMode: boolean;
+  private rojoProjectFile?: string;
+  private applySourcemap: boolean;
+  private fromSourcemap: boolean;
+
+  constructor(options: BuildOptions = {}) {
+    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,
+    });
+  }
+
+  public async run(): Promise<void> {
+    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: InstanceData[] = [];
+
+    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<void>((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);
+      });
+    });
+  }
+}