azul-sync 1.3.0

package/src/index.ts

@@ -0,0 +1,450 @@
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import * as http from "http";
+import { IPCServer } from "./ipc/server.js";
+import { HttpPollingServer } from "./ipc/httpPolling.js";
+import { TreeManager, TreeNode } from "./fs/treeManager.js";
+import { FileWriter } from "./fs/fileWriter.js";
+import { FileWatcher } from "./fs/watcher.js";
+import { SourcemapGenerator } from "./sourcemap/generator.js";
+import { log } from "./util/log.js";
+import { config, initializeConfig } from "./config.js";
+import type { StudioMessage } from "./ipc/messages.js";
+
+/**
+ * Main orchestrator for the Azul daemon
+ */
+export class SyncDaemon {
+  private ipc: IPCServer;
+  private httpPolling: HttpPollingServer;
+  private httpServer: http.Server;
+  private tree: TreeManager;
+  private fileWriter: FileWriter;
+  private fileWatcher: FileWatcher;
+  private sourcemapGenerator: SourcemapGenerator;
+  private batchDepth = 0; // Tracks nested batch processing
+  private batchNeedsSourcemapRegen = false; // Defer regen until batch ends
+
+  constructor() {
+    this.tree = new TreeManager();
+    this.fileWriter = new FileWriter(config.syncDir);
+    this.fileWatcher = new FileWatcher();
+    this.sourcemapGenerator = new SourcemapGenerator();
+    this.httpPolling = new HttpPollingServer();
+
+    // Create HTTP server that handles both WebSocket upgrades and HTTP polling
+    this.httpServer = http.createServer((req, res) => {
+      const handled = this.httpPolling.handleRequest(req, res);
+      if (!handled) {
+        res.writeHead(404);
+        res.end("Not found");
+      }
+    });
+
+    this.ipc = new IPCServer(config.port, this.httpServer);
+
+    this.setupHandlers();
+    this.httpServer.listen(config.port);
+  }
+
+  /**
+   * Set up all event handlers
+   */
+  private setupHandlers(): void {
+    // Handle messages from Studio (WebSocket)
+    this.ipc.onMessage((message) => this.handleStudioMessage(message));
+
+    // Handle messages from Studio (HTTP polling)
+    this.httpPolling.onMessage((message) => this.handleStudioMessage(message));
+
+    // Handle file changes from filesystem
+    this.fileWatcher.onChange((filePath, source) => {
+      this.handleFileChange(filePath, source);
+    });
+  }
+
+  /**
+   * Handle incoming messages from Studio
+   */
+  private handleStudioMessage(message: StudioMessage): void {
+    if (message.type === "batch") {
+      this.batchDepth += 1;
+      try {
+        for (const payload of message.messages) {
+          this.handleStudioMessage(payload);
+        }
+      } finally {
+        this.batchDepth -= 1;
+
+        // If any delete in this batch missed its prune, only regenerate once at the end
+        if (this.batchDepth === 0 && this.batchNeedsSourcemapRegen) {
+          this.regenerateSourcemap();
+          this.batchNeedsSourcemapRegen = false;
+        }
+      }
+      return;
+    }
+
+    switch (message.type) {
+      case "fullSnapshot":
+        this.handleFullSnapshot(message.data);
+        break;
+
+      case "scriptChanged":
+        this.handleScriptChanged(message.data);
+        break;
+
+      case "instanceUpdated":
+        this.handleInstanceUpdated(message.data);
+        break;
+
+      case "deleted":
+        this.handleDeleted(message.data);
+        break;
+
+      case "ping":
+        this.ipc.send({ type: "pong" });
+        break;
+
+      case "clientDisconnect":
+        log.info("Studio requested to close the connection");
+        this.ipc.close();
+        break;
+
+      default:
+        log.warn("Unknown message type:", (message as any).type);
+    }
+  }
+
+  /**
+   * Handle full snapshot from Studio
+   */
+  private handleFullSnapshot(data: any[]): void {
+    log.info("Received full snapshot from Studio");
+
+    // Update tree
+    this.tree.applyFullSnapshot(data);
+
+    // Write all scripts to filesystem
+    this.fileWriter.writeTree(this.tree.getAllNodes());
+
+    // Remove any pre-existing files that are no longer mapped (optional)
+    this.cleanupOrphanFiles();
+
+    // Start file watching
+    this.fileWatcher.watch(this.fileWriter.getBaseDir());
+
+    // Generate sourcemap
+    this.regenerateSourcemap();
+
+    // Log statistics
+    const stats = this.tree.getStats();
+    log.success(
+      `Sync complete: ${stats.scriptNodes} scripts, ${stats.totalNodes} total nodes`,
+    );
+  }
+
+  /**
+   * Handle script source change
+   */
+  private handleScriptChanged(message: {
+    guid: string;
+    source: string;
+    path: string[];
+    className: string;
+  }): void {
+    const { guid, source, path: instancePath, className } = message;
+
+    // Update tree
+    this.tree.updateScriptSource(guid, source);
+
+    // Get or create node
+    let node = this.tree.getNode(guid);
+    if (!node) {
+      // Create new node if it doesn't exist
+      this.tree.updateInstance({
+        guid,
+        className,
+        name: instancePath[instancePath.length - 1],
+        path: instancePath,
+        source,
+      });
+      node = this.tree.getNode(guid);
+    }
+
+    if (node) {
+      // Precompute path and suppress watcher before writing to avoid race conditions
+      const filePath = this.fileWriter.getFilePath(node);
+      this.fileWatcher.suppressNextChange(filePath);
+
+      // Write to filesystem
+      this.fileWriter.writeScript(node);
+
+      // Incrementally update sourcemap entry for this script
+      this.sourcemapGenerator.upsertSubtree(
+        node,
+        this.tree.getAllNodes(),
+        this.fileWriter.getAllMappings(),
+        config.sourcemapPath,
+        undefined,
+        false,
+      );
+    }
+  }
+
+  /**
+   * Handle instance update (rename, move, etc.)
+   */
+  private handleInstanceUpdated(data: any): void {
+    const update = this.tree.updateInstance(data);
+    const node = update?.node;
+
+    if (!node) {
+      return;
+    }
+
+    const scriptsToUpdate: Map<string, TreeNode> = new Map();
+
+    if (this.isScriptClass(node.className)) {
+      scriptsToUpdate.set(node.guid, node);
+    }
+
+    if (update.pathChanged || update.nameChanged || update.parentChanged) {
+      for (const child of this.tree.getDescendantScripts(node.guid)) {
+        scriptsToUpdate.set(child.guid, child);
+      }
+    }
+
+    for (const scriptNode of scriptsToUpdate.values()) {
+      const filePath = this.fileWriter.getFilePath(scriptNode);
+      this.fileWatcher.suppressNextChange(filePath);
+      this.fileWriter.writeScript(scriptNode);
+    }
+
+    const shouldUpdateSourcemap =
+      update.isNew ||
+      update.pathChanged ||
+      update.nameChanged ||
+      update.parentChanged ||
+      this.isScriptClass(node.className);
+
+    if (shouldUpdateSourcemap) {
+      this.sourcemapGenerator.upsertSubtree(
+        node,
+        this.tree.getAllNodes(),
+        this.fileWriter.getAllMappings(),
+        config.sourcemapPath,
+        update.prevPath,
+        update.isNew,
+      );
+    }
+
+    this.fileWriter.cleanupEmptyDirectories();
+  }
+
+  /**
+   * Handle instance deletion
+   */
+  private handleDeleted(message: { guid: string }): void {
+    const { guid } = message;
+    const node = this.tree.getNode(guid);
+
+    // If the node is already gone (e.g., child deletes after parent delete), fall back to full cleanup
+    if (!node) {
+      log.debug(`Delete ignored for unknown guid: ${guid}`);
+      this.fileWriter.deleteScript(guid);
+      // this.regenerateSourcemap();
+      this.fileWriter.cleanupEmptyDirectories();
+      return;
+    }
+
+    // Capture all script descendants (and the node itself if script) before we delete the tree nodes
+    const scriptsToDelete: { guid: string; filePath: string | null }[] = [];
+    const collectScript = (scriptNode: TreeNode): void => {
+      const filePath = this.fileWriter.getFilePath(scriptNode);
+      scriptsToDelete.push({ guid: scriptNode.guid, filePath });
+    };
+
+    if (this.isScriptClass(node.className)) {
+      collectScript(node);
+    }
+    for (const child of this.tree.getDescendantScripts(node.guid)) {
+      collectScript(child);
+    }
+
+    const pathSegments = node.path;
+
+    // Delete from tree (removes node and descendants)
+    this.tree.deleteInstance(guid);
+
+    // Delete files for all affected scripts
+    for (const entry of scriptsToDelete) {
+      const removed = this.fileWriter.deleteScript(entry.guid);
+      if (!removed && entry.filePath) {
+        this.fileWriter.deleteFilePath(entry.filePath);
+      }
+    }
+
+    // Remove subtree from sourcemap
+    const outputPath = config.sourcemapPath;
+    const pruned = this.sourcemapGenerator.prunePath(
+      pathSegments,
+      outputPath,
+      this.tree.getAllNodes(),
+      this.fileWriter.getAllMappings(),
+      node.className,
+      node.guid,
+    );
+
+    // If prune failed to find the path (e.g., sourcemap drift), rebuild once to stay consistent
+    if (!pruned) {
+      if (this.batchDepth > 0) {
+        // Defer regeneration until the batch completes to avoid repeated full rebuilds
+        this.batchNeedsSourcemapRegen = true;
+        log.debug("Regenerating sourcemap after batched prune miss");
+      } else {
+        log.debug("Regenerating sourcemap due to prune miss");
+        this.regenerateSourcemap();
+      }
+    }
+
+    this.fileWriter.cleanupEmptyDirectories();
+  }
+
+  /**
+   * Handle file change from filesystem
+   */
+  private handleFileChange(filePath: string, source: string): void {
+    // Find the GUID for this file
+    const guid = this.fileWriter.getGuidByPath(filePath);
+
+    if (guid) {
+      log.info(
+        `File changed externally: ${path.relative(this.fileWriter.getBaseDir(), filePath)}.`,
+      );
+
+      // Update tree
+      this.tree.updateScriptSource(guid, source);
+
+      // Send patch to Studio (both WebSocket and HTTP polling clients)
+      this.ipc.patchScript(guid, source);
+      this.httpPolling.broadcast({ type: "patchScript", guid, source });
+    } else {
+      log.warn(`No mapping found for file: ${filePath}`);
+    }
+  }
+
+  /**
+   * Regenerate the sourcemap
+   */
+  private regenerateSourcemap(): void {
+    // Write sourcemap into the sync directory so Luau-LSP can find it
+    const outputPath = config.sourcemapPath;
+    this.sourcemapGenerator.generateAndWrite(
+      this.tree.getAllNodes(),
+      this.fileWriter.getAllMappings(),
+      outputPath,
+    );
+  }
+
+  /**
+   * Start the daemon
+   */
+  public start(): void {
+    log.info("🚀 Azul daemon starting...");
+    log.info(`Sync directory: ${config.syncDir}`);
+    log.info(`HTTP/WebSocket port: ${config.port}`);
+    log.info("");
+    log.success(`Server listening on http://localhost:${config.port}`);
+    log.info("Waiting for Studio connection...");
+  }
+
+  /**
+   * Stop the daemon
+   */
+  public async stop(): Promise<void> {
+    log.info("Stopping daemon...");
+    await this.fileWatcher.stop();
+    this.ipc.close();
+    this.httpServer.close();
+    log.info("Daemon stopped");
+  }
+
+  private isScriptClass(className: string): boolean {
+    return (
+      className === "Script" ||
+      className === "LocalScript" ||
+      className === "ModuleScript"
+    );
+  }
+
+  /**
+   * Delete files under syncDir that are not mapped to any instance (opt-in).
+   */
+  private cleanupOrphanFiles(): void {
+    if (!config.deleteOrphansOnConnect) {
+      return;
+    }
+
+    const baseDir = this.fileWriter.getBaseDir();
+    const mapped = new Set<string>();
+
+    for (const mapping of this.fileWriter.getAllMappings().values()) {
+      mapped.add(path.resolve(mapping.filePath));
+    }
+
+    let removedFiles: string[] = [];
+
+    const walk = (dir: string): void => {
+      if (!fs.existsSync(dir)) return;
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else {
+          if (!mapped.has(path.resolve(fullPath))) {
+            try {
+              fs.unlinkSync(fullPath);
+              removedFiles.push(entry.name);
+            } catch (error) {
+              log.warn("Failed to delete orphan file:", fullPath, error);
+            }
+          }
+        }
+      }
+    };
+
+    walk(baseDir);
+    if (removedFiles.length > 0) {
+      this.fileWriter.cleanupEmptyDirectories();
+      log.success(
+        `Removed ${removedFiles.length} orphan file(s) from sync directory (${removedFiles.join(", ")})`,
+      );
+    }
+  }
+}
+
+// Allow direct execution (`node dist/index.js`) while preventing side effects when imported by the CLI
+const isDirectRun =
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+
+if (isDirectRun) {
+  initializeConfig();
+  const daemon = new SyncDaemon();
+  daemon.start();
+
+  // Handle graceful shutdown
+  process.on("SIGINT", async () => {
+    console.log("\n");
+    await daemon.stop();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", async () => {
+    await daemon.stop();
+    process.exit(0);
+  });
+}

package/src/ipc/httpPolling.ts

@@ -0,0 +1,214 @@
+/**
+ * HTTP endpoints for plugin polling compatibility
+ */
+
+import { IncomingMessage, ServerResponse } from "http";
+import { log } from "../util/log.js";
+
+interface PollingClient {
+  id: string;
+  messageQueue: any[];
+  lastPoll: number;
+}
+
+/**
+ * Manages HTTP polling for Roblox Studio plugin compatibility
+ */
+export class HttpPollingServer {
+  private clients: Map<string, PollingClient> = new Map();
+  private messageHandler: ((message: any, clientId: string) => void) | null =
+    null;
+
+  /**
+   * Handle HTTP request
+   */
+  public handleRequest(req: IncomingMessage, res: ServerResponse): boolean {
+    const url = new URL(req.url || "", `http://${req.headers.host}`);
+
+    // Enable CORS
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(200);
+      res.end();
+      return true;
+    }
+
+    switch (url.pathname) {
+      case "/connect":
+        return this.handleConnect(req, res);
+      case "/send":
+        return this.handleSend(req, res);
+      case "/poll":
+        return this.handlePoll(req, res, url);
+      case "/disconnect":
+        return this.handleDisconnect(req, res);
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Handle connect request
+   */
+  private handleConnect(_req: IncomingMessage, res: ServerResponse): boolean {
+    const clientId = this.generateClientId();
+
+    this.clients.set(clientId, {
+      id: clientId,
+      messageQueue: [],
+      lastPoll: Date.now(),
+    });
+
+    log.info(`HTTP client connected: ${clientId}`);
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ clientId }));
+    return true;
+  }
+
+  /**
+   * Handle send request
+   */
+  private handleSend(req: IncomingMessage, res: ServerResponse): boolean {
+    let body = "";
+
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+
+    req.on("end", () => {
+      try {
+        const data = JSON.parse(body);
+        const { clientId, message } = data;
+
+        if (this.messageHandler) {
+          this.messageHandler(message, clientId);
+        }
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ success: true }));
+      } catch (error) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid JSON" }));
+      }
+    });
+
+    return true;
+  }
+
+  /**
+   * Handle poll request
+   */
+  private handlePoll(
+    _req: IncomingMessage,
+    res: ServerResponse,
+    url: URL
+  ): boolean {
+    const clientId = url.searchParams.get("clientId");
+
+    if (!clientId || !this.clients.has(clientId)) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Client not found" }));
+      return true;
+    }
+
+    const client = this.clients.get(clientId)!;
+    client.lastPoll = Date.now();
+
+    const messages = client.messageQueue.splice(0); // Take all messages
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(messages));
+    return true;
+  }
+
+  /**
+   * Handle disconnect request
+   */
+  private handleDisconnect(req: IncomingMessage, res: ServerResponse): boolean {
+    let body = "";
+
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+
+    req.on("end", () => {
+      try {
+        const data = JSON.parse(body);
+        const { clientId } = data;
+
+        if (clientId && this.clients.has(clientId)) {
+          this.clients.delete(clientId);
+          log.info(`HTTP client disconnected: ${clientId}`);
+        }
+
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ success: true }));
+      } catch (error) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid JSON" }));
+      }
+    });
+
+    return true;
+  }
+
+  /**
+   * Send message to a specific client
+   */
+  public sendToClient(clientId: string, message: any): boolean {
+    const client = this.clients.get(clientId);
+    if (!client) {
+      return false;
+    }
+
+    client.messageQueue.push(message);
+    return true;
+  }
+
+  /**
+   * Broadcast message to all clients
+   */
+  public broadcast(message: any): void {
+    for (const client of this.clients.values()) {
+      client.messageQueue.push(message);
+    }
+  }
+
+  /**
+   * Set message handler
+   */
+  public onMessage(handler: (message: any, clientId: string) => void): void {
+    this.messageHandler = handler;
+  }
+
+  /**
+   * Clean up stale clients
+   */
+  public cleanupStaleClients(timeoutMs: number = 60000): void {
+    const now = Date.now();
+    for (const [id, client] of this.clients.entries()) {
+      if (now - client.lastPoll > timeoutMs) {
+        this.clients.delete(id);
+        log.info(`Removed stale HTTP client: ${id}`);
+      }
+    }
+  }
+
+  /**
+   * Generate unique client ID
+   */
+  private generateClientId(): string {
+    return `client_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  /**
+   * Get active client count
+   */
+  public getClientCount(): number {
+    return this.clients.size;
+  }
+}