roport 1.0.1 → 1.3.1

package/README.md

@@ -45,3 +45,19 @@ This will start a local server on port `3456` (default).
 3. Start the server with `roport serve`.
 4. Install the **Roport** plugin in Roblox Studio.
 5. Connect via the plugin in Roblox Studio.
+
+## Diagnostics
+
+When the Roport plugin loads in Roblox Studio, it will automatically run a diagnostic check and output the results to the Output window. This check verifies:
+- Connection to the Roport server.
+- Correct mapping of project folders (`Shared`, `Server`, `Client`).
+
+Look for the `[Roport]` prefix in the console to see the status.
+
+## Testing
+
+To run the integration test suite for the CLI:
+
+```bash
+node test/test_suite.js
+```

package/bin/roport.js

@@ -33,7 +33,8 @@ program
         await fs.copy(templateDir, targetDir);
         console.log(chalk.green('Success! Project initialized.'));
         console.log(chalk.white('Run `roport serve` to start the sync server.'));
-        console.log(chalk.white('Check AI_INSTRUCTIONS.md for usage details.'));
+        console.log(chalk.white('Check DOCUMENTATION.md for usage details.'));
+        console.log(chalk.white('Install RoportSyncPlugin.rbxmx in your Roblox Studio project.'));
       } else {
         console.error(chalk.red(`Error: Template directory not found at ${templateDir}`));
       }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "roport",
-  "version": "1.0.1",
-  "description": "A sync server for Roblox development. Works with the Roport Roblox Plugin.",
+  "version": "1.3.1",
+  "description": "A sync server for Roblox development. Works with the Roport Roblox Plugin. Features AI integration and full project sync.",
   "main": "src/server.js",
   "bin": {
     "roport": "./bin/roport.js"

package/src/server.js

@@ -19,6 +19,7 @@ function startServer(port) {
     // State for two-way sync
     let changedFiles = new Set();
     let commandQueue = []; // Queue for commands to be sent to Roblox
+    let executionResults = new Map(); // Store results of executed scripts
     let isWriting = false; // Lock to prevent loops (Roblox -> File -> Watcher -> Roblox)
 
     // Watch for file changes locally
@@ -26,11 +27,11 @@ function startServer(port) {
         console.log(chalk.gray(`Starting file watcher on ${projectRoot}...`));
         fs.watch(projectRoot, { recursive: true }, (eventType, filename) => {
             if (filename && !isWriting) {
-                // Ignore system folders and the cli folder itself if we are watching root
-                if (filename.includes('node_modules') || filename.includes('.git') || filename.startsWith('cli')) return;
-                
                 // Normalize path to forward slashes
                 const relativePath = filename.replace(/\\/g, '/');
+
+                // Check ignore rules
+                if (isIgnored(relativePath)) return;
                 
                 // Debounce/Deduplicate slightly
                 if (!changedFiles.has(relativePath)) {
@@ -46,6 +47,125 @@ function startServer(port) {
     // Increase limit for large file batches
     app.use(express.json({ limit: '50mb' }));
 
+    // Ignore Logic
+    let ignoreRules = [];
+
+    function loadIgnoreRules() {
+        ignoreRules = [];
+        const ignoreFiles = ['.rojoignore', '.gitignore'];
+        
+        for (const file of ignoreFiles) {
+            const ignorePath = path.join(projectRoot, file);
+            if (fs.existsSync(ignorePath)) {
+                try {
+                    const content = fs.readFileSync(ignorePath, 'utf8');
+                    const lines = content.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+                    ignoreRules.push(...lines);
+                    console.log(chalk.gray(`Loaded ${lines.length} ignore rules from ${file}`));
+                } catch (e) {
+                    console.warn(chalk.yellow(`Failed to read ${file}:`), e);
+                }
+            }
+        }
+        // Always ignore internal folders
+        ignoreRules.push('.git', 'node_modules', 'cli');
+    }
+    loadIgnoreRules();
+
+    function isIgnored(filePath) {
+        // Normalize path
+        const relativePath = filePath.replace(/\\/g, '/');
+        
+        for (const rule of ignoreRules) {
+            // Simple glob matching
+            // 1. Exact match
+            if (relativePath === rule) return true;
+            
+            // 2. Directory match (rule ends with /)
+            if (rule.endsWith('/') && relativePath.startsWith(rule)) return true;
+            
+            // 3. Extension match (*.lua)
+            if (rule.startsWith('*.') && relativePath.endsWith(rule.slice(1))) return true;
+            
+            // 4. Folder match (node_modules) - check if it's a segment
+            if (!rule.includes('/') && !rule.includes('*')) {
+                const segments = relativePath.split('/');
+                if (segments.includes(rule)) return true;
+            }
+
+            // 5. Basic wildcard (src/*)
+            if (rule.endsWith('/*')) {
+                const base = rule.slice(0, -2);
+                if (relativePath.startsWith(base + '/') && relativePath.split('/').length === base.split('/').length + 1) return true;
+            }
+            
+            // 6. Recursive wildcard (src/**)
+            if (rule.endsWith('/**')) {
+                const base = rule.slice(0, -3);
+                if (relativePath.startsWith(base + '/')) return true;
+            }
+        }
+        return false;
+    }
+
+    // Project Configuration Parsing
+    function getProjectConfig() {
+        const configPath = path.join(projectRoot, 'default.project.json');
+        if (fs.existsSync(configPath)) {
+            try {
+                const config = fs.readJsonSync(configPath);
+                const mounts = [];
+                
+                function traverse(node, currentPath) {
+                    if (node.$path) {
+                        mounts.push({
+                            robloxPath: currentPath,
+                            filePath: node.$path,
+                            className: node.$className
+                        });
+                    }
+                    
+                    for (const key in node) {
+                        if (!key.startsWith('$') && typeof node[key] === 'object') {
+                            traverse(node[key], [...currentPath, key]);
+                        }
+                    }
+                }
+                
+                if (config.tree) {
+                    traverse(config.tree, []);
+                }
+                
+                return { name: config.name, mounts };
+            } catch (e) {
+                console.error(chalk.red("Failed to parse default.project.json:"), e);
+            }
+        }
+        return null;
+    }
+
+    app.get('/config', (req, res) => {
+        const config = getProjectConfig();
+        if (config) {
+            res.send(config);
+        } else {
+            // Fallback for legacy projects without config
+            res.send({
+                mounts: [
+                    { robloxPath: ["ServerScriptService"], filePath: "src/server" },
+                    { robloxPath: ["ReplicatedStorage"], filePath: "src/shared" },
+                    { robloxPath: ["StarterPlayer", "StarterPlayerScripts"], filePath: "src/client" },
+                    { robloxPath: ["Workspace"], filePath: "src/workspace" },
+                    { robloxPath: ["StarterGui"], filePath: "src/interface" },
+                    { robloxPath: ["StarterPack"], filePath: "src/tools" },
+                    { robloxPath: ["Lighting"], filePath: "src/lighting" },
+                    { robloxPath: ["ReplicatedFirst"], filePath: "src/first" },
+                    { robloxPath: ["SoundService"], filePath: "src/sounds" }
+                ]
+            });
+        }
+    });
+
     app.get('/ping', (req, res) => {
         res.send('pong');
     });
@@ -100,17 +220,48 @@ function startServer(port) {
     });
 
     app.post('/log', (req, res) => {
-        const { message, stack, timestamp } = req.body;
-        const timeStr = new Date(timestamp * 1000).toLocaleTimeString();
+        const { message, type, timestamp } = req.body;
+        const timeStr = new Date((timestamp || Date.now() / 1000) * 1000).toLocaleTimeString();
         
-        console.log(chalk.red(`[ROBLOX ERROR ${timeStr}]`));
-        console.log(chalk.red(message));
-        if (stack) {
-            console.log(chalk.gray(stack));
-        }
+        let color = chalk.white;
+        if (type === 2 || type === 'Error') color = chalk.red; // Error
+        else if (type === 1 || type === 'Warning') color = chalk.yellow; // Warning
+        
+        console.log(chalk.gray(`[STUDIO ${timeStr}]`) + " " + color(message));
+        res.send({ success: true });
+    });
+
+    // AI Interface: Remote Execution
+    app.post('/execute', (req, res) => {
+        const { code } = req.body;
+        if (!code) return res.status(400).send('Missing code');
+        
+        const id = Date.now().toString();
+        commandQueue.push({ type: 'EXECUTE', id, code });
+        console.log(chalk.blue(`Queued execution ${id}`));
+        
+        // Wait for result (long polling implementation could be better, but simple polling works for now)
+        res.send({ id, status: 'queued' });
+    });
+
+    app.post('/execute-result', (req, res) => {
+        const { id, success, result, error } = req.body;
+        executionResults.set(id, { success, result, error });
+        console.log(chalk.blue(`Received result for ${id}: ${success ? 'Success' : 'Failed'}`));
         res.send({ success: true });
     });
 
+    app.get('/execute/:id', (req, res) => {
+        const { id } = req.params;
+        if (executionResults.has(id)) {
+            const result = executionResults.get(id);
+            executionResults.delete(id); // Consume result
+            res.send({ status: 'completed', ...result });
+        } else {
+            res.send({ status: 'pending' });
+        }
+    });
+
     app.post('/command', (req, res) => {
         const { type, path } = req.body;
         if (!type) return res.status(400).send('Missing command type');
@@ -141,6 +292,11 @@ function startServer(port) {
                     continue;
                 }
 
+                if (isIgnored(filePath)) {
+                    console.log(chalk.gray(`Skipping ignored file: ${filePath}`));
+                    continue;
+                }
+
                 if (filePath.endsWith('.json')) {
                     try {
                         const json = JSON.parse(content);
@@ -181,6 +337,11 @@ function startServer(port) {
                     continue;
                 }
 
+                if (isIgnored(filePath)) {
+                    console.log(chalk.gray(`Skipping ignored file deletion: ${filePath}`));
+                    continue;
+                }
+
                 if (await fs.pathExists(safePath)) {
                     await fs.remove(safePath);
                     console.log(chalk.magenta(`Deleted: ${filePath}`));

package/templates/default/DOCUMENTATION.md

@@ -0,0 +1,309 @@
+# Roport Documentation
+
+Roport is a two-way synchronization tool for Roblox development, designed to bridge the gap between Visual Studio Code and Roblox Studio. It allows developers to write code in external editors and have it instantly reflected in Roblox Studio, and vice versa.
+
+This documentation provides a comprehensive reference for the CLI, Server API, Plugin features, and configuration formats.
+
+---
+
+## 1. Command Line Interface (CLI)
+
+The `roport` CLI is the entry point for managing projects and running the sync server.
+
+### `roport init`
+Initializes a new Roport project in the current directory.
+
+**Description:**
+Scaffolds a standard project structure including:
+- `default.project.json`: The project configuration file.
+- `src/`: A standard directory structure for Roblox services (server, client, shared, etc.).
+- `RoportSyncPlugin.rbxmx`: The Roblox Studio plugin file.
+- `README.md`: Basic usage instructions.
+
+**Usage:**
+```bash
+roport init
+```
+
+### `roport serve`
+Starts the synchronization server.
+
+**Description:**
+Launches an HTTP server that listens for connections from the Roblox Studio plugin. It also starts a file watcher to detect changes in the local file system.
+
+**Options:**
+- `-p, --port <number>`: Specifies the port to run the server on. Default is `3456`.
+
+**Usage:**
+```bash
+roport serve
+roport serve --port 8080
+```
+
+---
+
+## 2. Server API Reference
+
+The Roport server exposes a RESTful API used by the Roblox Studio plugin. All endpoints accept and return JSON.
+
+### `GET /config`
+Retrieves the project configuration.
+
+**Description:**
+Parses the `default.project.json` file and returns a flattened list of "mounts". A mount maps a Roblox service path (e.g., `ServerScriptService`) to a local file system path (e.g., `src/server`).
+
+**Response:**
+```json
+{
+  "name": "ProjectName",
+  "mounts": [
+    {
+      "robloxPath": ["ServerScriptService"],
+      "filePath": "src/server",
+      "className": "Folder"
+    }
+  ]
+}
+```
+
+### `GET /poll`
+Checks for updates from the file system.
+
+**Description:**
+Called periodically by the plugin (Long Polling). Returns a list of files that have changed or been deleted locally since the last poll, and any queued commands.
+
+**Response:**
+```json
+{
+  "changes": [
+    { "filePath": "src/server/script.server.luau", "content": "print('Hello')" },
+    { "filePath": "src/server/folder", "isDirectory": true }
+  ],
+  "deletions": [
+    "src/server/old_script.server.luau"
+  ],
+  "commands": []
+}
+```
+
+### `POST /batch`
+Uploads a batch of files from Roblox Studio to the file system.
+
+**Description:**
+Used during "Sync All" or "Auto-Sync" from Studio. Writes multiple files to disk.
+
+**Request Body:**
+```json
+{
+  "files": [
+    { "filePath": "src/server/script.server.luau", "content": "..." }
+  ]
+}
+```
+
+### `POST /delete`
+Deletes files from the file system.
+
+**Description:**
+Triggered when an instance is deleted or renamed in Roblox Studio.
+
+**Request Body:**
+```json
+{
+  "files": [
+    "src/server/deleted_script.server.luau"
+  ]
+}
+```
+
+### `POST /command`
+Queues a command to be executed by the plugin.
+
+**Description:**
+Allows external tools to trigger actions in Roblox Studio (e.g., starting a playtest).
+
+**Request Body:**
+```json
+{
+  "type": "PLAYTEST_START",
+  "path": null
+}
+```
+
+### `POST /log`
+Logs a message from Roblox Studio to the server console.
+
+**Description:**
+Useful for debugging plugin issues or forwarding Studio output to the terminal.
+
+**Request Body:**
+```json
+{
+  "message": "Error in script...",
+  "stack": "Stack trace...",
+  "timestamp": 1678888888
+}
+```
+
+### `GET /ping`
+Health check endpoint.
+
+**Description:**
+Returns `pong`. Used by the plugin to detect if the server is online.
+
+---
+
+## 3. AI Agent Integration
+
+Roport includes features specifically designed to allow AI agents to control Roblox Studio autonomously.
+
+### Log Streaming
+The plugin automatically hooks into `LogService.MessageOut` and streams all Studio output to the Roport server console.
+
+- **Format:** `[STUDIO HH:MM:SS] Message`
+- **Colors:**
+    - White: Standard Output (`print`)
+    - Yellow: Warnings (`warn`)
+    - Red: Errors (`error`)
+
+**Usage for AI:**
+An AI agent running the server can monitor `stdout` to see runtime errors, debugging information, or game state printed by scripts.
+
+### Remote Execution (REPL)
+Allows an AI to execute arbitrary Luau code in the running Roblox Studio instance.
+
+#### 1. Execute Code
+**Endpoint:** `POST /execute`
+
+**Request Body:**
+```json
+{
+  "code": "return workspace.Part.Position"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "1678889999000",
+  "status": "queued"
+}
+```
+
+#### 2. Get Result
+**Endpoint:** `GET /execute/:id`
+
+**Response (Pending):**
+```json
+{ "status": "pending" }
+```
+
+**Response (Completed):**
+```json
+{
+  "status": "completed",
+  "success": true,
+  "result": "{\"X\":0,\"Y\":10,\"Z\":0}",
+  "error": null
+}
+```
+
+**Usage for AI:**
+1.  **Inspect State:** Check properties of objects that aren't easily visible in files (e.g., physics state, player count).
+2.  **Unit Testing:** Run test functions and check the output.
+3.  **Manipulation:** Create temporary parts or modify the environment to test mechanics.
+
+---
+
+## 4. Plugin Features
+
+The `RoportSyncPlugin` is a Roblox Studio plugin that connects to the Roport server.
+
+### Sync Panel
+The main interface for the plugin.
+- **Connect:** Establishes a connection to the server.
+- **Sync All (Push):** Scans the entire Roblox workspace (based on configured mounts) and uploads all scripts and supported instances to the file system.
+- **Pull Changes:** Manually fetches pending changes from the server.
+- **Auto-Sync:** Toggles automatic uploading of changes made in Studio (scripts, properties, hierarchy) to the file system.
+- **Auto-Pull:** Toggles automatic polling for changes made in the file system.
+
+### Settings
+Configurable via the "Settings" button in the panel.
+- **Server Port:** Must match the port used in `roport serve`. Default: `3456`.
+- **Sync Interval:** How often (in seconds) Auto-Sync checks for dirty scripts. Default: `2`.
+
+### Synchronization Logic
+- **Path Resolution:** The plugin uses the configuration from `/config` to determine where instances belong.
+- **Two-Way Sync:**
+    - **Studio -> Disk:** Listens to `ScriptEditorService`, `AncestryChanged`, and `PropertyChangedSignal`.
+    - **Disk -> Studio:** Polls `/poll` for file changes and applies them using `Script.Source` or property updates.
+
+---
+
+## 4. Configuration
+
+### `default.project.json`
+Defines the mapping between the file system and the Roblox DataModel.
+
+**Structure:**
+```json
+{
+  "name": "MyProject",
+  "tree": {
+    "$className": "DataModel",
+    "ServerScriptService": {
+      "$className": "ServerScriptService",
+      "$path": "src/server"
+    },
+    "ReplicatedStorage": {
+      "$className": "ReplicatedStorage",
+      "$path": "src/shared"
+    }
+    // ... other services
+  }
+}
+```
+- **$path:** The local directory path relative to the project root.
+- **$className:** The Roblox ClassName for the container (usually a Service or Folder).
+
+### `.rojoignore` / `.gitignore`
+Specifies files and directories to exclude from synchronization.
+
+**Supported Patterns:**
+- `*.txt`: Ignore all text files.
+- `dist/`: Ignore the `dist` directory.
+- `src/private/**`: Recursive ignore.
+- `node_modules`: Exact folder match.
+
+**Default Ignores:**
+- `.git`
+- `node_modules`
+- `cli`
+
+---
+
+## 5. File Type Support
+
+Roport maps file extensions to Roblox Instance types.
+
+### Scripts
+- **`.server.luau` / `.server.lua`**: Creates a `Script` (RunContext=Legacy/Server).
+- **`.client.luau` / `.client.lua`**: Creates a `LocalScript`.
+- **`.luau` / `.lua`**: Creates a `ModuleScript`.
+- **`init.server.luau`**: Creates a `Script` that is the parent of its directory's contents.
+
+### Data
+- **`.json`**: Creates a `ModuleScript` returning the JSON table (unless it is a meta file).
+- **`.txt`**: Creates a `StringValue`.
+
+### Models
+- **`.rbxmx`**: Parses the Roblox XML Model format and reconstructs the Instance tree. Supports complex properties like `Vector3`, `Color3`, `UDim2`.
+
+### Metadata
+- **`.meta.json`**: Defines properties for a folder or specific instance.
+    - Example: `Folder/init.meta.json` sets properties for `Folder`.
+- **`.model.json`**: Similar to meta, used for defining class types and properties for generic files.
+
+**Supported Properties in JSON/XML:**
+- Primitives: `string`, `boolean`, `number`
+- Complex: `Vector3`, `Color3`, `UDim2`, `UDim`, `Rect`, `NumberRange`

package/templates/default/README.md

@@ -0,0 +1,35 @@
+# Roport Project
+
+This project was initialized with [Roport](https://github.com/Rydaguy101/RojoExportPlugin).
+
+## Getting Started
+
+1.  **Install the Plugin:**
+    *   Open Roblox Studio.
+    *   Drag and drop `RoportSyncPlugin.rbxmx` into the 3D view.
+    *   Right-click the created folder/script in the workspace and "Save as Local Plugin" (or just keep it in ServerStorage if you prefer).
+
+2.  **Start the Server:**
+    *   Run `roport serve` in this directory.
+    *   The server will start on port 3456.
+
+3.  **Connect:**
+    *   In Roblox Studio, open the "Roport Sync" panel (Plugins tab).
+    *   Click "Connect".
+    *   Click "Sync All" to push the initial project structure to Roblox.
+
+## Project Structure
+
+*   `src/server`: Server-side scripts (`ServerScriptService`).
+*   `src/client`: Client-side scripts (`StarterPlayerScripts`).
+*   `src/shared`: Shared modules (`ReplicatedStorage`).
+*   `default.project.json`: Configuration for file paths.
+
+## Features
+
+*   **Two-Way Sync:** Edits in VS Code sync to Studio. Edits in Studio sync to VS Code (if Auto-Sync is on).
+*   **AI Integration:** Logs from Studio are streamed to the terminal. You can execute code remotely via the API.
+
+## Documentation
+
+For full details on the CLI, API, and Configuration, see [DOCUMENTATION.md](./DOCUMENTATION.md).