roport 1.0.0 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # Roport CLI
 
-The companion server for the **Roport** Roblox plugin. This tool enables two-way syncing between Visual Studio Code and Roblox Studio.
+The companion server for the **Roport** Roblox plugin. This tool enables two-way syncing between Visual Studio Code and Roblox Studio and provides a "Gold Standard" development environment.
 
 ## Installation
 
@@ -12,7 +12,21 @@ npm install -g roport
 
 ## Usage
 
-Navigate to your project directory (where your `.meta.json` files are) and run:
+### Initialize a New Project
+To create a new project with the standard folder structure and pre-installed modules (ByteNet, Fusion, Matter, etc.):
+
+```bash
+roport init
+```
+
+This will create:
+- `src/`: Source code directory with `server`, `client`, and `shared` folders.
+- `default.project.json`: Rojo configuration.
+- `MODULE_ARCHITECTURE.md`: Documentation for the installed modules.
+- `AI_INSTRUCTIONS.md`: Guide for AI assistants and developers.
+
+### Start the Sync Server
+Navigate to your project directory and run:
 
 ```bash
 roport serve
@@ -27,6 +41,7 @@ This will start a local server on port `3456` (default).
 ## Setup with Roblox
 
 1. Install this CLI tool.
-2. Install the **Roport** plugin in Roblox Studio.
+2. Run `roport init` in your project folder.
 3. Start the server with `roport serve`.
-4. Connect via the plugin in Roblox Studio.
+4. Install the **Roport** plugin in Roblox Studio.
+5. Connect via the plugin in Roblox Studio.

package/bin/roport.js

@@ -1,7 +1,10 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { program } = require('commander');
 const { startServer } = require('../src/server');
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
 
 program
   .name('roport')
@@ -16,4 +19,27 @@ program
     startServer(parseInt(options.port));
   });
 
+program
+  .command('init')
+  .description('Initialize a new Roport project with standard modules')
+  .action(async () => {
+    const targetDir = process.cwd();
+    const templateDir = path.join(__dirname, '../templates/default');
+
+    console.log(chalk.blue(`Initializing Roport project in ${targetDir}...`));
+
+    try {
+      if (await fs.pathExists(templateDir)) {
+        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.'));
+      } else {
+        console.error(chalk.red(`Error: Template directory not found at ${templateDir}`));
+      }
+    } catch (err) {
+      console.error(chalk.red('Error initializing project:'), err);
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roport",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A sync server for Roblox development. Works with the Roport Roblox Plugin.",
   "main": "src/server.js",
   "bin": {
@@ -25,6 +25,7 @@
   "files": [
     "bin",
     "src",
+    "templates",
     "README.md"
   ],
   "dependencies": {

package/src/server.js

@@ -18,15 +18,13 @@ function startServer(port) {
 
     // State for two-way sync
     let changedFiles = new Set();
+    let commandQueue = []; // Queue for commands to be sent to Roblox
     let isWriting = false; // Lock to prevent loops (Roblox -> File -> Watcher -> Roblox)
 
     // Watch for file changes locally
     try {
         console.log(chalk.gray(`Starting file watcher on ${projectRoot}...`));
         fs.watch(projectRoot, { recursive: true }, (eventType, filename) => {
-            // Debug log
-            // console.log('Raw event:', 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;
@@ -54,34 +52,72 @@ function startServer(port) {
 
     // New endpoint for Roblox to poll for changes
     app.get('/poll', async (req, res) => {
-        if (changedFiles.size === 0) {
-            return res.send({ changes: [] });
+        const response = { changes: [], deletions: [], commands: [] };
+
+        // Handle Commands
+        if (commandQueue.length > 0) {
+            response.commands = [...commandQueue];
+            commandQueue = []; // Clear queue
+            console.log(chalk.magenta(`Sending ${response.commands.length} commands to Roblox`));
         }
 
-        const changes = [];
-        const filesToProcess = Array.from(changedFiles);
-        changedFiles.clear(); // Clear immediately so we don't send duplicates
-
-        for (const filePath of filesToProcess) {
-            try {
-                const fullPath = path.resolve(projectRoot, filePath);
-                // Only send if file still exists (it might have been deleted)
-                if (await fs.pathExists(fullPath)) {
-                    const stat = await fs.stat(fullPath);
-                    if (stat.isFile()) {
-                        const content = await fs.readFile(fullPath, 'utf8');
-                        changes.push({ filePath, content });
+        // Handle File Changes & Deletions
+        if (changedFiles.size > 0) {
+            const filesToProcess = Array.from(changedFiles);
+            changedFiles.clear(); // Clear immediately so we don't send duplicates
+
+            for (const filePath of filesToProcess) {
+                try {
+                    const fullPath = path.resolve(projectRoot, filePath);
+                    
+                    if (await fs.pathExists(fullPath)) {
+                        // File Exists -> Update
+                        const stat = await fs.stat(fullPath);
+                        if (stat.isFile()) {
+                            const content = await fs.readFile(fullPath, 'utf8');
+                            response.changes.push({ filePath, content });
+                        } else if (stat.isDirectory()) {
+                            response.changes.push({ filePath, isDirectory: true });
+                        }
+                    } else {
+                        // File Does Not Exist -> Deletion
+                        response.deletions.push(filePath);
                     }
+                } catch (e) {
+                    console.error(chalk.red(`Error reading changed file ${filePath}:`), e);
                 }
-            } catch (e) {
-                console.error(chalk.red(`Error reading changed file ${filePath}:`), e);
+            }
+            
+            if (response.changes.length > 0) {
+                console.log(chalk.magenta(`Sending ${response.changes.length} updates to Roblox`));
+            }
+            if (response.deletions.length > 0) {
+                console.log(chalk.magenta(`Sending ${response.deletions.length} deletions to Roblox`));
             }
         }
 
-        if (changes.length > 0) {
-            console.log(chalk.magenta(`Sending ${changes.length} updates to Roblox`));
+        res.send(response);
+    });
+
+    app.post('/log', (req, res) => {
+        const { message, stack, timestamp } = req.body;
+        const timeStr = new Date(timestamp * 1000).toLocaleTimeString();
+        
+        console.log(chalk.red(`[ROBLOX ERROR ${timeStr}]`));
+        console.log(chalk.red(message));
+        if (stack) {
+            console.log(chalk.gray(stack));
         }
-        res.send({ changes });
+        res.send({ success: true });
+    });
+
+    app.post('/command', (req, res) => {
+        const { type, path } = req.body;
+        if (!type) return res.status(400).send('Missing command type');
+        
+        commandQueue.push({ type, path });
+        console.log(chalk.blue(`Queued command: ${type}`));
+        res.send({ success: true });
     });
 
     app.post('/batch', async (req, res) => {

package/templates/default/AI_INSTRUCTIONS.md

@@ -0,0 +1,72 @@
+# Roport AI Instructions
+
+## Overview
+Roport is a Roblox development tool that combines a Rojo-compatible sync server with a "Gold Standard" set of pre-installed libraries. This document provides instructions for AI assistants and developers on how to use Roport effectively.
+
+## Commands
+
+### `roport init`
+Initializes a new Roport project in the current directory.
+- **Creates:**
+    - `default.project.json`: Rojo project configuration.
+    - `src/`: Source code directory containing standard folders (`server`, `client`, `shared`) and pre-installed modules.
+    - `MODULE_ARCHITECTURE.md`: Documentation of the installed architecture.
+    - `AI_INSTRUCTIONS.md`: This file.
+
+### `roport serve`
+Starts the sync server.
+- **Port:** Defaults to 3456.
+- **Usage:** Run this command in the terminal to allow the Roport Roblox Plugin to sync files from your filesystem into Roblox Studio.
+
+## Project Structure
+The project follows a standard Rojo structure:
+- `src/server`: Scripts that run on the server (`ServerScriptService`).
+- `src/client`: Scripts that run on the client (`StarterPlayerScripts`).
+- `src/shared`: Modules shared between client and server (`ReplicatedStorage`).
+
+## Pre-Installed Modules ("Gold Standard")
+Roport comes with a curated list of industry-standard libraries located in `src/shared/modules` (and `src/server/modules` for server-only libs).
+
+| Library | Type | Location | Description |
+| :--- | :--- | :--- | :--- |
+| **ByteNet** | Networking | `Shared/modules/ByteNet` | High-performance buffer-based networking. Use this instead of RemoteEvents for performance-critical data. |
+| **Fusion** | UI | `Shared/modules/Fusion` | Reactive UI library. Use this for creating modern, state-driven user interfaces. |
+| **Matter** | ECS | `Shared/modules/Matter` | Entity Component System. Use this for complex game logic and systems. |
+| **Flipper** | Animation | `Shared/modules/Flipper` | Spring and motor animation library. Essential for UI animations. |
+| **Llama** | Utility | `Shared/modules/Llama` | Functional programming utilities for tables and lists (immutable data). |
+| **Cmdr** | Admin | `Shared/modules/Cmdr` | Extensible command console. Use for admin commands and debug tools. |
+| **Nevermore** | Framework | `Shared/modules/Nevermore` | A massive collection of utilities (Camera, Octree, DataStore, etc.). |
+| **ProfileService** | Data | `Server/modules/ProfileService` | Session-locked DataStore wrapper. **Always** use this for player data. |
+| **ReplicaService** | Replication | `Server/modules/ReplicaService` | State replication system. Use for replicating game state to clients. |
+| **Promise** | Async | `Shared/modules/Promise` | Promise implementation. Use for handling asynchronous operations. |
+
+## Workflow Instructions
+
+### 1. Creating Parts and Scripts
+- **Filesystem First:** Create files in VS Code (or your editor) within the `src/` directory.
+- **Sync:** Ensure `roport serve` is running. The Roport plugin in Studio will automatically sync changes.
+- **Naming:**
+    - `.server.lua` / `.server.luau`: Server Scripts.
+    - `.client.lua` / `.client.luau`: Local Scripts.
+    - `.lua` / `.luau`: Module Scripts.
+
+### 2. Using Modules
+To use a module, require it using its path in the DataModel.
+**Example:**
+```lua
+-- Requiring a shared module (e.g., Promise)
+local Promise = require(game:GetService("ReplicatedStorage").Shared.modules.Promise)
+
+-- Requiring a server module (e.g., ProfileService)
+local ProfileService = require(game:GetService("ServerScriptService").Server.modules.ProfileService)
+```
+
+### 3. Developing Features
+- **UI:** Create Fusion components in `src/client/ui`.
+- **Data:** Define ProfileService templates in `src/server/data`.
+- **Networking:** Define ByteNet packets in `src/shared/network`.
+- **Game Logic:** Create Matter systems in `src/shared/systems` or `src/server/systems`.
+
+## Troubleshooting
+- **Sync Issues:** If files aren't appearing, check the `roport serve` terminal output for errors and ensure the plugin is connected.
+- **Missing Modules:** Verify `default.project.json` correctly maps `src/shared` to `ReplicatedStorage.Shared`.

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/default.project.json

@@ -0,0 +1,29 @@
+{
+  "name": "RojoExportPlugin",
+  "tree": {
+    "$className": "DataModel",
+    "ReplicatedStorage": {
+      "Shared": {
+        "$path": "src/shared"
+      }
+    },
+    "ServerScriptService": {
+      "Server": {
+        "$path": "src/server"
+      }
+    },
+    "StarterPlayer": {
+      "StarterPlayerScripts": {
+        "Client": {
+          "$path": "src/client"
+        }
+      }
+    },
+    "Lighting": {
+      "$path": "src/lighting"
+    },
+    "Workspace": {
+      "$path": "src/workspace"
+    }
+  }
+}

package/templates/default/src/Roport/Modules/Constants.lua

@@ -0,0 +1,90 @@
+--!strict
+local Constants = {}
+
+Constants.TOOLBAR_NAME = "Rojo Tools"
+Constants.BUTTON_NAME = "Open Sync Panel"
+
+Constants.COLORS = {
+	BG = Color3.fromRGB(37, 37, 37),
+	HEADER = Color3.fromRGB(45, 45, 45),
+	BUTTON = Color3.fromRGB(55, 55, 55),
+	BUTTON_HOVER = Color3.fromRGB(65, 65, 65),
+	ACCENT = Color3.fromRGB(0, 122, 204), -- VS Code Blue
+	TEXT = Color3.fromRGB(245, 245, 245),
+	SUBTEXT = Color3.fromRGB(180, 180, 180),
+	SUCCESS = Color3.fromRGB(90, 200, 90),
+	ERROR = Color3.fromRGB(220, 80, 80),
+	WARNING = Color3.fromRGB(220, 200, 80)
+}
+
+Constants.PROPERTY_MAP = {
+	Instance = {"Name", "Archivable", "ClassName"},
+	BasePart = {"Size", "Position", "Color", "Transparency", "Anchored", "CanCollide", "Material", "Reflectance", "CastShadow", "Locked", "Shape"},
+	GuiObject = {"Size", "Position", "AnchorPoint", "BackgroundColor3", "BackgroundTransparency", "BorderColor3", "BorderSizePixel", "Visible", "ZIndex", "LayoutOrder", "ClipsDescendants", "Rotation"},
+	TextLabel = {"Text", "TextColor3", "TextSize", "Font", "TextTransparency", "TextXAlignment", "TextYAlignment", "TextScaled", "TextWrapped", "RichText"},
+	TextButton = {"Text", "TextColor3", "TextSize", "Font", "TextTransparency", "TextXAlignment", "TextYAlignment", "TextScaled", "TextWrapped", "RichText"},
+	TextBox = {"Text", "TextColor3", "TextSize", "Font", "TextTransparency", "TextXAlignment", "TextYAlignment", "TextScaled", "TextWrapped", "PlaceholderText", "ClearTextOnFocus", "MultiLine"},
+	ImageLabel = {"Image", "ImageColor3", "ImageTransparency", "ScaleType", "SliceCenter", "TileSize"},
+	ImageButton = {"Image", "ImageColor3", "ImageTransparency", "ScaleType", "SliceCenter", "TileSize"},
+	ValueBase = {"Value"},
+	Sound = {"SoundId", "Volume", "PlaybackSpeed", "Looped", "Playing", "TimePosition"},
+	Animation = {"AnimationId"},
+	Decal = {"Texture", "Color3", "Transparency", "Face"},
+	Texture = {"Texture", "Color3", "Transparency", "Face", "StudsPerTileU", "StudsPerTileV", "OffsetStudsU", "OffsetStudsV"},
+	Light = {"Color", "Brightness", "Enabled", "Shadows", "Range"},
+	SpotLight = {"Angle", "Face"},
+	SurfaceLight = {"Angle", "Face"},
+	DataModelMesh = {"Scale", "Offset", "VertexColor"},
+	SpecialMesh = {"MeshId", "TextureId", "MeshType"},
+	Humanoid = {"Health", "MaxHealth", "WalkSpeed", "JumpPower", "DisplayName", "RigType", "HipHeight"},
+	Tool = {"RequiresHandle", "CanBeDropped", "ToolTip", "Enabled", "Grip"},
+	Accessory = {"AttachmentPoint"},
+	Clothing = {"Color3"},
+	Shirt = {"ShirtTemplate"},
+	Pants = {"PantsTemplate"},
+	ParticleEmitter = {"Color", "LightEmission", "LightInfluence", "Size", "Texture", "Transparency", "ZOffset", "EmissionDirection", "Enabled", "Lifetime", "Rate", "Rotation", "RotSpeed", "Speed", "SpreadAngle"},
+	Trail = {"Color", "Enabled", "FaceCamera", "Lifetime", "LightEmission", "LightInfluence", "MaxLength", "MinLength", "Texture", "TextureLength", "Transparency", "WidthScale"},
+	Beam = {"Color", "Enabled", "FaceCamera", "LightEmission", "LightInfluence", "Texture", "TextureLength", "TextureMode", "Transparency", "Width0", "Width1", "ZOffset"},
+	Fire = {"Color", "Enabled", "Heat", "Size", "SecondaryColor"},
+	Smoke = {"Color", "Enabled", "Opacity", "RiseVelocity", "Size"},
+	Sparkles = {"SparkleColor", "Enabled"},
+	PostEffect = {"Enabled"},
+	BlurEffect = {"Size"},
+	BloomEffect = {"Intensity", "Size", "Threshold"},
+	ColorCorrectionEffect = {"Brightness", "Contrast", "Saturation", "TintColor"},
+	SunRaysEffect = {"Intensity", "Spread"},
+	Atmosphere = {"Density", "Offset", "Haze", "Color", "Decay", "Glare"},
+	Sky = {"SkyboxBk", "SkyboxDn", "SkyboxFt", "SkyboxLf", "SkyboxRt", "SkyboxUp", "SunTextureId", "MoonTextureId", "StarCount"},
+	UICorner = {"CornerRadius"},
+	UIStroke = {"Color", "Thickness", "Transparency", "ApplyStrokeMode", "LineJoinMode"},
+	UIGradient = {"Color", "Offset", "Rotation", "Transparency"},
+	UIPadding = {"PaddingBottom", "PaddingLeft", "PaddingRight", "PaddingTop"},
+	UIScale = {"Scale"},
+	UIListLayout = {"Padding", "FillDirection", "HorizontalAlignment", "VerticalAlignment", "SortOrder", "ItemLineAlignment"},
+	UIGridLayout = {"CellPadding", "CellSize", "FillDirection", "HorizontalAlignment", "VerticalAlignment", "SortOrder", "StartCorner"},
+	UITableLayout = {"Padding", "FillDirection", "HorizontalAlignment", "VerticalAlignment", "SortOrder"},
+	UIPageLayout = {"Padding", "FillDirection", "HorizontalAlignment", "VerticalAlignment", "SortOrder", "Animated", "Circular", "EasingDirection", "EasingStyle", "GamepadInputEnabled", "ScrollWheelInputEnabled", "TouchInputEnabled", "TweenTime"},
+	
+	-- Phase 2 Additions
+	ScreenGui = {"DisplayOrder", "IgnoreGuiInset", "ResetOnSpawn", "ZIndexBehavior", "Enabled"},
+	BillboardGui = {"Active", "Adornee", "AlwaysOnTop", "Brightness", "ClipsDescendants", "DistanceLowerLimit", "DistanceUpperLimit", "ExtentsOffset", "ExtentsOffsetWorldSpace", "LightInfluence", "MaxDistance", "PlayerToHideFrom", "ResetOnSpawn", "Size", "SizeOffset", "StudsOffset", "StudsOffsetWorldSpace", "ZIndexBehavior"},
+	SurfaceGui = {"Active", "Adornee", "AlwaysOnTop", "Brightness", "CanvasSize", "ClipsDescendants", "Face", "LightInfluence", "PixelsPerStud", "ResetOnSpawn", "SizingMode", "ToolPunchThroughDistance", "ZIndexBehavior", "ZOffset"},
+	Model = {"PrimaryPart", "WorldPivot", "LevelOfDetail"},
+	ScrollingFrame = {"CanvasSize", "CanvasPosition", "ScrollBarThickness", "ScrollBarImageColor3", "ScrollBarImageTransparency", "ScrollingDirection", "ElasticBehavior", "VerticalScrollBarPosition", "HorizontalScrollBarInset"},
+	UIAspectRatioConstraint = {"AspectRatio", "AspectType", "DominantAxis"},
+	UISizeConstraint = {"MaxSize", "MinSize"},
+	SoundGroup = {"Volume"},
+	Animator = {},
+	AnimationController = {},
+	Attachment = {"CFrame", "Visible", "Axis", "SecondaryAxis"},
+	Weld = {"C0", "C1", "Part0", "Part1"},
+	Motor6D = {"C0", "C1", "Part0", "Part1", "MaxVelocity", "DesiredAngle", "CurrentAngle"},
+	ProximityPrompt = {"ActionText", "ObjectText", "KeyboardKeyCode", "HoldDuration", "MaxActivationDistance", "RequiresLineOfSight", "Exclusivity", "Style"},
+	Highlight = {"Adornee", "FillColor", "FillTransparency", "OutlineColor", "OutlineTransparency", "DepthMode"},
+	WrapTarget = {"Stiffness", "DebugMode"},
+	WrapLayer = {"Order", "Enabled", "Puffiness", "ShrinkFactor"},
+	Bone = {"Transform", "CFrame"},
+	HumanoidDescription = {"Head", "Torso", "LeftArm", "RightArm", "LeftLeg", "RightLeg", "GraphicTShirt", "Pants", "Shirt", "Face", "HeadColor", "TorsoColor", "LeftArmColor", "RightArmColor", "LeftLegColor", "RightLegColor"},
+}
+
+return Constants

package/templates/default/src/Roport/Modules/Paths.lua

@@ -0,0 +1,171 @@
+--!strict
+local Paths = {}
+
+function Paths.sanitize(name)
+	return name:gsub("[\\/:*?\"<>|]", "_")
+end
+
+function Paths.getPath(inst)
+	local p = {}
+	local c = inst
+	local s = nil
+	
+	-- Special case: If inst IS one of the services
+	if inst == game:GetService("ServerScriptService") then return "src/server" end
+	if inst == game:GetService("ReplicatedStorage") then return "src/shared" end
+	if inst == game:GetService("StarterPlayer").StarterPlayerScripts then return "src/client" end
+	if inst == game:GetService("Workspace") then return "src/workspace" end
+	if inst == game:GetService("StarterGui") then return "src/interface" end
+	if inst == game:GetService("StarterPack") then return "src/tools" end
+	if inst == game:GetService("Lighting") then return "src/lighting" end
+	if inst == game:GetService("ReplicatedFirst") then return "src/first" end
+	if inst == game:GetService("SoundService") then return "src/sounds" end
+	
+	-- Phase 3 Reverse Mappings
+	local RS = game:GetService("ReplicatedStorage")
+	local SSS = game:GetService("ServerScriptService")
+	if inst == RS:FindFirstChild("Prefabs") then return "src/prefabs" end
+	if inst == RS:FindFirstChild("Assets") then return "src/assets" end
+	if inst == SSS:FindFirstChild("WorldGen") then return "src/worldgen" end
+
+	while c and c~=game do
+		if c==game:GetService("ServerScriptService") then s="src/server" break
+		elseif c==game:GetService("ReplicatedStorage") then s="src/shared" break
+		elseif c==game:GetService("StarterPlayer").StarterPlayerScripts then s="src/client" break
+		elseif c==game:GetService("Workspace") then s="src/workspace" break
+		elseif c==game:GetService("StarterGui") then s="src/interface" break
+		elseif c==game:GetService("StarterPack") then s="src/tools" break
+		elseif c==game:GetService("Lighting") then s="src/lighting" break
+		elseif c==game:GetService("ReplicatedFirst") then s="src/first" break
+		elseif c==game:GetService("SoundService") then s="src/sounds" break
+		-- Phase 3 Reverse Loop
+		elseif c==RS:FindFirstChild("Prefabs") then s="src/prefabs" break
+		elseif c==RS:FindFirstChild("Assets") then s="src/assets" break
+		elseif c==SSS:FindFirstChild("WorldGen") then s="src/worldgen" break
+		end
+		
+		-- If we hit a service that isn't in our list, we might be in a weird spot
+		if c.Parent == game and not s then
+			return nil
+		end
+		
+		table.insert(p,1,(Paths.sanitize(c.Name)))
+		c=c.Parent
+	end
+	return s and (s.."/"..table.concat(p,"/"))
+end
+
+function Paths.findInstanceByPath(path)
+	-- Remove extension
+	local cleanPath = path:gsub("%.server%.luau$", ""):gsub("%.client%.luau$", ""):gsub("%.luau$", ""):gsub("/init%.meta%.json$", ""):gsub("%.json$", "")
+	
+	local parts = cleanPath:split("/")
+	if parts[1] ~= "src" then return nil end
+	
+	local current = nil
+	
+	-- Map src/xxx to Service
+	local serviceMap = {
+		workspace = game:GetService("Workspace"),
+		server = game:GetService("ServerScriptService"),
+		shared = game:GetService("ReplicatedStorage"),
+		client = game:GetService("StarterPlayer").StarterPlayerScripts,
+		interface = game:GetService("StarterGui"),
+		tools = game:GetService("StarterPack"),
+		lighting = game:GetService("Lighting"),
+		first = game:GetService("ReplicatedFirst"),
+		sounds = game:GetService("SoundService"),
+		-- Phase 3 Mappings
+		prefabs = game:GetService("ReplicatedStorage"):FindFirstChild("Prefabs") or (function() 
+			local f = Instance.new("Folder") f.Name = "Prefabs" f.Parent = game:GetService("ReplicatedStorage") return f 
+		end)(),
+		assets = game:GetService("ReplicatedStorage"):FindFirstChild("Assets") or (function() 
+			local f = Instance.new("Folder") f.Name = "Assets" f.Parent = game:GetService("ReplicatedStorage") return f 
+		end)(),
+		worldgen = game:GetService("ServerScriptService"):FindFirstChild("WorldGen") or (function() 
+			local f = Instance.new("Folder") f.Name = "WorldGen" f.Parent = game:GetService("ServerScriptService") return f 
+		end)()
+	}
+	
+	current = serviceMap[parts[2]]
+	if not current then return nil end
+	
+	for i = 3, #parts do
+		local name = parts[i]
+		current = current:FindFirstChild(name)
+		if not current then return nil end
+	end
+	
+	return current
+end
+
+function Paths.createInstanceByPath(path, content)
+	local cleanPath = path:gsub("%.server%.luau$", ""):gsub("%.client%.luau$", ""):gsub("%.luau$", ""):gsub("/init%.meta%.json$", ""):gsub("%.json$", "")
+	local parts = cleanPath:split("/")
+	if parts[1] ~= "src" then return nil end
+	
+	local serviceMap = {
+		workspace = game:GetService("Workspace"),
+		server = game:GetService("ServerScriptService"),
+		shared = game:GetService("ReplicatedStorage"),
+		client = game:GetService("StarterPlayer").StarterPlayerScripts,
+		interface = game:GetService("StarterGui"),
+		tools = game:GetService("StarterPack"),
+		lighting = game:GetService("Lighting"),
+		first = game:GetService("ReplicatedFirst"),
+		sounds = game:GetService("SoundService")
+	}
+	
+	local current = serviceMap[parts[2]]
+	if not current then return nil end
+	
+	for i = 3, #parts do
+		local name = parts[i]
+		local nextInst = current:FindFirstChild(name)
+		
+		if not nextInst then
+			local isLast = (i == #parts)
+			local className = "Folder"
+			
+			if isLast then
+				if path:match("%.server%.luau$") then className = "Script"
+				elseif path:match("%.client%.luau$") then className = "LocalScript"
+				elseif path:match("%.luau$") then className = "ModuleScript"
+				elseif path:match("%.json$") and content then
+					-- Try to peek className from content
+					local success, data = pcall(function() return HttpService:JSONDecode(content) end)
+					if success and data.className then
+						className = data.className
+					else
+						-- If no className, assume it's a Data Module
+						className = "ModuleScript"
+					end
+				end
+			end
+
+			-- Special Case: Remotes
+			if path:find("/remotes/") and isLast and className == "Folder" then
+				-- Default to RemoteEvent if not specified
+				if name:match("Function") then
+					className = "RemoteFunction"
+				else
+					className = "RemoteEvent"
+				end
+			end
+			
+			local success, newInst = pcall(function() return Instance.new(className) end)
+			if success and newInst then
+				newInst.Name = name
+				newInst.Parent = current
+				nextInst = newInst
+			else
+				warn("Roport: Failed to create " .. className .. " for " .. name)
+				return nil
+			end
+		end
+		current = nextInst
+	end
+	return current
+end
+
+return Paths