roport 1.0.0 → 1.2.0

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/MODULE_ARCHITECTURE.md

@@ -0,0 +1,88 @@
+# Project Architecture
+
+## Modules
+
+### Server Modules (`src/server/modules`)
+- **ProfileService**: DataStore wrapper for session-locked player data.
+- **ReplicaService**: Server-side state replication system.
+
+### Client Modules (`src/client/modules`)
+- **ReplicaController**: Client-side state replication system (counterpart to ReplicaService).
+
+### Shared Modules (`src/shared/modules`)
+- **ByteNet**: High-performance, buffer-based networking library.
+- **Cmdr**: Extensible command console and admin system.
+- **Flipper**: Animation library for UI and motors.
+- **Fusion**: Modern reactive UI library.
+- **Llama**: Functional programming utility library for immutable data.
+- **Matter**: Entity Component System (ECS) library.
+- **Nevermore**: Comprehensive game framework containing hundreds of utility modules (Camera, Octree, etc.).
+- **Promise**: Promise implementation for Lua.
+- **MadworkMaid**: Cleanup utility (dependency of ReplicaService).
+- **MadworkScriptSignal**: Signal implementation (dependency of ReplicaService).
+- **RateLimiter**: Network rate limiter (dependency of ReplicaService).
+- **Janitor**: Cleanup utility.
+- **Signal**: Signal implementation.
+
+## Usage
+
+### Networking (ByteNet)
+Used for high-performance networking.
+```lua
+local ByteNet = require(game:GetService("ReplicatedStorage").Shared.modules.ByteNet)
+```
+
+### UI (Fusion)
+Used for creating reactive UI.
+```lua
+local Fusion = require(game:GetService("ReplicatedStorage").Shared.modules.Fusion)
+```
+
+### ECS (Matter)
+Used for game logic and systems.
+```lua
+local Matter = require(game:GetService("ReplicatedStorage").Shared.modules.Matter)
+```
+
+### Animation (Flipper)
+Used for spring-based animations.
+```lua
+local Flipper = require(game:GetService("ReplicatedStorage").Shared.modules.Flipper)
+```
+
+### Utilities (Llama)
+Used for table and list manipulation.
+```lua
+local Llama = require(game:GetService("ReplicatedStorage").Shared.modules.Llama)
+```
+
+### Console (Cmdr)
+Used for admin commands and debugging.
+```lua
+local Cmdr = require(game:GetService("ReplicatedStorage").Shared.modules.Cmdr)
+```
+
+### Framework (Nevermore)
+A massive collection of utilities.
+```lua
+local Nevermore = require(game:GetService("ReplicatedStorage").Shared.modules.Nevermore)
+-- Example: local Camera = require(Nevermore.Camera)
+```
+
+### ProfileService
+Used for saving player data safely.
+```lua
+local ProfileService = require(game:GetService("ServerScriptService").Server.modules.ProfileService)
+```
+
+### ReplicaService
+Used for replicating game state to clients.
+```lua
+local ReplicaService = require(game:GetService("ServerScriptService").Server.modules.ReplicaService)
+```
+
+### Promise
+Used for asynchronous operations.
+```lua
+local Promise = require(game:GetService("ReplicatedStorage").Shared.modules.Promise)
+```

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).