@quenty/studio-bridge 0.7.0 → 0.8.0

package/templates/studio-bridge-plugin/src/StudioBridgePlugin.server.lua

@@ -1,83 +1,188 @@
 --[[
-	StudioBridge plugin — injected at runtime by @quenty/studio-bridge.
+	StudioBridge unified plugin entry point — Layer 2 Roblox glue.
 
-	Connects to a local WebSocket server, streams LogService output, and
-	executes embedded Luau scripts. Template placeholders are substituted
-	by the Node.js side before writing this file to the Studio plugins folder.
+	Supports two boot modes:
+	  - Ephemeral: build constants substituted by the CLI, connects directly.
+	  - Persistent: template strings intact, uses DiscoveryStateMachine to
+	    scan ports and auto-connect to a running studio-bridge server.
+
+	All protocol logic, state machine logic, action routing, and message
+	buffering live in Layer 1 modules under Shared/. This file is thin
+	glue that wires those modules to Roblox services.
 ]]
 
 local HttpService = game:GetService("HttpService")
 local LogService = game:GetService("LogService")
 local RunService = game:GetService("RunService")
-local Workspace = game:GetService("Workspace")
 
+-- Layer 1 modules (pure logic, no Roblox deps)
+local ActionRouter = require(script.Parent.Shared.ActionRouter)
+local DiscoveryStateMachine = require(script.Parent.Shared.DiscoveryStateMachine)
+local MessageBuffer = require(script.Parent.Shared.MessageBuffer)
+
+-- Actions are pushed dynamically over the wire via registerAction.
+-- No static action requires needed.
+
+-- Build constants (Handlebars templates substituted at build time)
 local PORT = "{{PORT}}"
 local SESSION_ID = "{{SESSION_ID}}"
+local IS_EPHEMERAL = ("{{EPHEMERAL}}" == "true")
 
--- Only run inside Studio
+-- Only run inside Studio edit context. Plugin instances spawned by play
+-- mode (client/server) cannot make HTTP requests, so they cannot discover
+-- the bridge. The edit-context instance stays alive during play mode.
 if not RunService:IsStudio() or RunService:IsRunning() then
 	return
 end
 
-local thisPlaceSessionId = Workspace:GetAttribute("StudioBridgeSessionId")
-if thisPlaceSessionId ~= SESSION_ID then
-	return
+-- ---------------------------------------------------------------------------
+-- Context detection
+-- ---------------------------------------------------------------------------
+
+local function detectContext()
+	if RunService:IsRunning() then
+		if RunService:IsClient() then
+			return "client"
+		else
+			return "server"
+		end
+	end
+	return "edit"
 end
 
-local WS_URL = "ws://localhost:" .. PORT .. "/" .. SESSION_ID
+-- ---------------------------------------------------------------------------
+-- Instance / session ID helpers
+-- ---------------------------------------------------------------------------
+
+-- Short unique nonce for disambiguating unpublished places with the same name.
+-- Generated once per plugin lifecycle so the session ID stays stable across reconnects.
+local _nonce: string = string.sub(HttpService:GenerateGUID(false), 1, 8)
+
+local function getInstanceId()
+	if game.GameId ~= 0 or game.PlaceId ~= 0 then
+		return `{game.GameId}-{game.PlaceId}`
+	end
+	-- Unpublished place: use sanitized place name + nonce for uniqueness
+	local name = string.lower(game.Name or "untitled")
+	name = string.gsub(name, "%s+", "-")
+	name = string.gsub(name, "[^%w%-]", "")
+	if name == "" then
+		name = "untitled"
+	end
+	return `local-{name}-{_nonce}`
+end
+
+local function getSessionId()
+	return `{getInstanceId()}-{detectContext()}`
+end
 
 -- ---------------------------------------------------------------------------
--- Helpers
+-- JSON helpers (HttpService wrappers for Roblox environment)
 -- ---------------------------------------------------------------------------
 
 local function jsonEncode(tbl)
 	return HttpService:JSONEncode(tbl)
 end
 
-local function jsonDecode(str)
-	local ok, result = pcall(function()
-		return HttpService:JSONDecode(str)
-	end)
+local function jsonDecode(raw)
+	local ok, result = pcall(HttpService.JSONDecode, HttpService, raw)
 	if ok then
 		return result
 	end
 	return nil
 end
 
-local function send(client, msgType, payload)
-	local ok, err = pcall(function()
-		client:Send(jsonEncode({
-			type = msgType,
-			sessionId = SESSION_ID,
-			payload = payload,
-		}))
-	end)
-	if not ok then
-		warn("[StudioBridge] Send failed: " .. tostring(err))
+-- ---------------------------------------------------------------------------
+-- Shared state
+-- ---------------------------------------------------------------------------
+
+local router = ActionRouter.new()
+local logBuffer = MessageBuffer.new(1000)
+
+-- Pre-load the PNG encoder and expose it to dynamically loaded actions
+-- via router._vendorPng. The screenshot action reads this in its register().
+local _pngOk, _pngModule = pcall(function()
+	return require(script.Parent.Vendor.png)
+end)
+if _pngOk and _pngModule then
+	router._vendorPng = _pngModule
+end
+
+-- Wire outgoing messages (set after WebSocket is connected)
+local sendMessageFn = nil
+
+-- Callback that forwards messages through the active WebSocket
+local function sendMessage(msg)
+	if sendMessageFn then
+		sendMessageFn(msg)
 	end
 end
 
--- ---------------------------------------------------------------------------
--- Output batching — collect LogService messages and flush every 0.1s
--- ---------------------------------------------------------------------------
+-- Register the built-in registerAction handler. This allows the bridge
+-- server to push Luau action modules over the wire after a plugin connects.
+router:register("registerAction", function(payload, requestId, sessionId)
+	local name = payload.name
+	local source = payload.source
+	local responseType = payload.responseType
+	local hash = payload.hash -- optional content hash for skip-on-same-hash
+
+	if type(name) ~= "string" or type(source) ~= "string" then
+		return {
+			name = name or "unknown",
+			success = false,
+			error = "Invalid registerAction payload: name and source are required strings",
+		}
+	end
 
-local outputBuffer = {}
-local bufferLock = false
+	-- Check for hash-based skip before full registration
+	if type(hash) == "string" and router._actions[name] and router._actions[name].hash == hash then
+		return {
+			name = name,
+			success = true,
+			skipped = true,
+			hash = hash,
+			handlers = router._actions[name].handlerNames,
+		}
+	end
 
-local function flushOutput(client)
-	if #outputBuffer == 0 or bufferLock then
-		return
+	local success, err = router:registerAction(name, source, sendMessage, logBuffer, responseType, hash)
+
+	-- Build response with handler list from _actions if available
+	local handlers = {}
+	if success and router._actions[name] then
+		handlers = router._actions[name].handlerNames
+	end
+
+	return {
+		name = name,
+		success = success,
+		skipped = false,
+		hash = hash,
+		handlers = handlers,
+		error = err,
+	}
+end)
+router:setResponseType("registerAction", "registerActionResult")
+
+-- Register the built-in syncActions handler. This allows the bridge server
+-- to query which actions need updating by comparing content hashes.
+router:register("syncActions", function(payload, requestId, sessionId)
+	local clientActions = payload.actions or {}
+	local installed = router:getInstalledActions()
+	local needed = {}
+
+	for name, clientHash in clientActions do
+		if installed[name] ~= clientHash then
+			table.insert(needed, name)
+		end
 	end
 
-	bufferLock = true
-	local batch = outputBuffer
-	outputBuffer = {}
-	bufferLock = false
+	return { needed = needed, installed = installed }
+end)
+router:setResponseType("syncActions", "syncActionsResult")
 
-	send(client, "output", { messages = batch })
-end
+local connected = false
 
--- Map Roblox MessageType enum to string levels
 local LEVEL_MAP = {
 	[Enum.MessageType.MessageOutput] = "Print",
 	[Enum.MessageType.MessageInfo] = "Info",
@@ -85,124 +190,250 @@ local LEVEL_MAP = {
 	[Enum.MessageType.MessageError] = "Error",
 }
 
--- ---------------------------------------------------------------------------
--- Script execution
--- ---------------------------------------------------------------------------
+-- Hybrid clock: os.time() for absolute wall-clock, os.clock() deltas for sub-second precision
+local clockBase = os.clock()
+local timeBase = os.time()
 
-local function executeScript(client, source)
-	local fn, loadErr = loadstring(source)
-	if not fn then
-		send(client, "scriptComplete", {
-			success = false,
-			error = "loadstring failed: " .. tostring(loadErr),
-		})
+-- Capture logs from the moment the plugin loads, regardless of WebSocket state
+LogService.MessageOut:Connect(function(message, messageType)
+	if string.sub(message, 1, 14) == "[StudioBridge]" then
 		return
 	end
-
-	local ok, runErr = xpcall(fn, debug.traceback)
-
-	-- Small delay to let any final prints flush through LogService
-	task.wait(0.2)
-	flushOutput(client)
-
-	send(client, "scriptComplete", {
-		success = ok,
-		error = if ok then nil else tostring(runErr),
+	logBuffer:push({
+		level = LEVEL_MAP[messageType] or "Print",
+		body = message,
+		timestamp = timeBase + (os.clock() - clockBase),
 	})
-end
+end)
 
 -- ---------------------------------------------------------------------------
--- WebSocket connection
+-- Wire a WebSocket connection
 -- ---------------------------------------------------------------------------
 
-local function connectAsync()
-	local client
-
-	local ok, err = pcall(function()
-		client = HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, { Url = WS_URL })
-	end)
+local function wireConnection(ws, sessionId, connectLabel)
+	connected = true
 
-	if not ok or not client then
-		warn("[StudioBridge] Failed to create WebSocket client: " .. tostring(err))
-		return
+	-- Wire the sendMessage callback for action handlers
+	sendMessageFn = function(msg)
+		pcall(function()
+			ws:Send(jsonEncode(msg))
+		end)
 	end
 
-	-- Hook LogService before connecting so we don't miss early messages.
-	-- Filter out internal [StudioBridge] messages so they don't leak back
-	-- to the CLI as script output.
-	local logConnection = LogService.MessageOut:Connect(function(message, messageType)
-		if string.sub(message, 1, 14) == "[StudioBridge]" then
-			return
-		end
+	-- Send register message. The plugin only runs in edit context (the
+	-- early-return at top of file rejects play-mode instances), so state
+	-- is always "Edit". Capabilities include the dynamically-dispatchable
+	-- actions — the bridge pushes their source via registerAction after
+	-- this register completes, but the plugin is capable of handling any
+	-- of them.
+	ws:Send(jsonEncode({
+		type = "register",
+		sessionId = sessionId,
+		payload = {
+			pluginVersion = "0.7.0",
+			instanceId = getInstanceId(),
+			context = detectContext(),
+			placeName = game.Name or "Unknown",
+			placeId = game.PlaceId,
+			gameId = game.GameId,
+			state = "Edit",
+			capabilities = {
+				"registerAction",
+				"syncActions",
+				"heartbeat",
+				"execute",
+				"queryState",
+				"captureScreenshot",
+				"queryDataModel",
+				"queryLogs",
+			},
+		},
+	}))
+
+	-- Incoming messages -> ActionRouter dispatch
+	ws.MessageReceived:Connect(function(rawData)
+		local ok, err = pcall(function()
+			local msg = jsonDecode(rawData)
+			if not msg or type(msg.type) ~= "string" then
+				print(`[StudioBridge] Failed to decode message: {tostring(rawData):sub(1, 200)}`)
+				return
+			end
 
-		local level = LEVEL_MAP[messageType] or "Print"
-		table.insert(outputBuffer, {
-			level = level,
-			body = message,
-		})
-	end)
+			print(`[StudioBridge] Received: {msg.type} (requestId={tostring(msg.requestId):sub(1, 8)}...)`)
 
-	-- Periodic flush
-	local flushConnection = RunService.Heartbeat:Connect(function()
-		if #outputBuffer > 0 then
-			flushOutput(client)
+			if msg.type == "shutdown" then
+				connected = false
+				pcall(function()
+					ws:Close()
+				end)
+				return
+			end
+
+			local response = router:dispatch(msg)
+			if response then
+				local encoded = jsonEncode(response)
+				print(`[StudioBridge] Sending: {response.type} ({#encoded} bytes)`)
+				ws:Send(encoded)
+			else
+				print(`[StudioBridge] No response for: {msg.type}`)
+			end
+		end)
+		if not ok then
+			warn(`[StudioBridge] MessageReceived handler error: {tostring(err)}`)
 		end
 	end)
 
-	-- Connection opens automatically on CreateWebStreamClient — send hello
-	-- once the Opened event fires.
-	client.Opened:Connect(function(_responseStatusCode, _headers)
-		print("[StudioBridge] WebSocket opened, sending hello (session: " .. SESSION_ID .. ")")
-		send(client, "hello", {
-			sessionId = SESSION_ID,
-		})
+	ws.Closed:Connect(function()
+		connected = false
 	end)
 
-	-- Handle incoming messages from the server
-	client.MessageReceived:Connect(function(rawData)
-		local msg = jsonDecode(rawData)
-		if not msg or type(msg.type) ~= "string" then
-			return
+	-- Heartbeat coroutine
+	local heartbeatStart = os.clock()
+	task.spawn(function()
+		while connected do
+			pcall(function()
+				ws:Send(jsonEncode({
+					type = "heartbeat",
+					sessionId = sessionId,
+					payload = {
+						uptimeMs = math.floor((os.clock() - heartbeatStart) * 1000),
+						state = detectContext() == "edit" and "Edit" or detectContext(),
+						pendingRequests = 0,
+					},
+				}))
+			end)
+			task.wait(15)
 		end
+	end)
 
-		-- Validate session ID on every incoming message
-		if msg.sessionId ~= SESSION_ID then
-			warn("[StudioBridge] Ignoring message with wrong session ID")
-			return
-		end
+	print(`[StudioBridge] Connected to {connectLabel} as {sessionId}`)
+end
+
+-- ---------------------------------------------------------------------------
+-- Boot
+-- ---------------------------------------------------------------------------
 
-		if msg.type == "welcome" then
-			-- Handshake accepted — ready for execute messages
-			print("[StudioBridge] Connected, ready for commands")
-		elseif msg.type == "execute" then
-			-- Execute an additional script sent by the server
-			if msg.payload and type(msg.payload.script) == "string" then
-				task.spawn(function()
-					executeScript(client, msg.payload.script)
+if IS_EPHEMERAL then
+	-- Ephemeral mode: CLI substituted PORT and SESSION_ID, connect directly
+	local wsUrl = `ws://localhost:{PORT}/{SESSION_ID}`
+	local ok, ws = pcall(function()
+		return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, { Url = wsUrl })
+	end)
+	if ok and ws then
+		ws.Opened:Connect(function()
+			wireConnection(ws, SESSION_ID, `localhost:{PORT} (ephemeral)`)
+		end)
+		ws.Error:Connect(function(status, err)
+			warn(`[StudioBridge] WebSocket error ({status}): {err}`)
+		end)
+	else
+		warn("[StudioBridge] Failed to create WebSocket client")
+	end
+else
+	-- Persistent mode: discover server via port scanning
+	local POLL_INTERVAL_SEC = 2
+
+	-- Forward-declare so closures inside the callback table can reference it.
+	local discovery
+	discovery = DiscoveryStateMachine.new(nil, {
+		scanPortsAsync = function(ports, timeoutSec)
+			-- Scan all ports in parallel using task.spawn. The calling thread
+			-- yields and is resumed as soon as any port succeeds, all fail,
+			-- or the timeout expires. Use task.defer (not task.spawn) to resume
+			-- the caller so it has time to reach coroutine.yield() first.
+			local callerThread = coroutine.running()
+			local foundPort = nil
+			local foundBody = nil
+			local remaining = #ports
+			local settled = false
+			local threads = {}
+
+			for _, port in ports do
+				local thread = task.spawn(function()
+					local url = `http://localhost:{port}/health`
+					local ok2, body = pcall(HttpService.GetAsync, HttpService, url)
+					if ok2 and not settled then
+						foundPort = port
+						foundBody = body
+						settled = true
+						task.defer(callerThread)
+						return
+					end
+					remaining -= 1
+					if remaining <= 0 and not settled then
+						settled = true
+						task.defer(callerThread)
+					end
 				end)
+				table.insert(threads, thread)
 			end
-		elseif msg.type == "shutdown" then
-			-- Clean up
-			print("[StudioBridge] Shutdown requested")
-			logConnection:Disconnect()
-			flushConnection:Disconnect()
-			pcall(function()
-				client:Close()
+
+			-- Timeout: use the deadline from the poll loop
+			local timeoutThread = task.delay(timeoutSec, function()
+				if not settled then
+					settled = true
+					task.defer(callerThread)
+				end
 			end)
-		end
-	end)
 
-	client.Closed:Connect(function()
-		logConnection:Disconnect()
-		flushConnection:Disconnect()
-	end)
+			coroutine.yield()
+
+			-- Cancel remaining HTTP threads and the timeout
+			pcall(task.cancel, timeoutThread)
+			for _, thread in threads do
+				pcall(task.cancel, thread)
+			end
 
-	client.Error:Connect(function(responseStatusCode, errorMessage)
-		warn(
-			"[StudioBridge] WebSocket error (status " .. tostring(responseStatusCode) .. "): " .. tostring(errorMessage)
-		)
+			return foundPort, foundBody
+		end,
+		connectWebSocket = function(url)
+			local ok2, ws = pcall(function()
+				return HttpService:CreateWebStreamClient(Enum.WebStreamClientType.WebSocket, { Url = url })
+			end)
+			return ok2, ws
+		end,
+		onStateChange = function(oldState, newState)
+			if newState == "searching" and oldState == "idle" then
+				print("[StudioBridge] Searching for host on ports 38741-38744...")
+			end
+		end,
+		onConnected = function(ws, port)
+			local sessionId = getSessionId()
+			ws.Opened:Connect(function()
+				wireConnection(ws, sessionId, `localhost:{port}`)
+			end)
+			ws.Error:Connect(function(status, err)
+				warn(`[StudioBridge] WebSocket error ({status}): {err}`)
+			end)
+			ws.Closed:Connect(function()
+				connected = false
+				discovery:onDisconnect("closed")
+			end)
+		end,
+		onDisconnected = function(reason)
+			connected = false
+			print(`[StudioBridge] Disconnected ({reason}), searching...`)
+		end,
+	})
+	print(`[StudioBridge] Session ID: {getSessionId()}`)
+	discovery:start()
+
+	-- Drive the state machine with a simple polling loop.
+	-- Each iteration has a fixed time budget (POLL_INTERVAL_SEC). The
+	-- remaining time threads through pollAsync → scanPortsAsync so all
+	-- async operations complete within the budget.
+	task.spawn(function()
+		while true do
+			local startTime = os.clock()
+			discovery:pollAsync(POLL_INTERVAL_SEC)
+			-- Sleep for the remainder of the cycle
+			local elapsed = os.clock() - startTime
+			local remaining = POLL_INTERVAL_SEC - elapsed
+			if remaining > 0 then
+				task.wait(remaining)
+			else
+				task.wait() -- yield at least one frame
+			end
+		end
 	end)
 end
-
--- Run
-task.spawn(connectAsync)