@mflrevan/ucp 0.5.2 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # @mflrevan/ucp
 
-Version `0.5.2` of the Unity Control Protocol CLI.
+Version `0.6.1` of the Unity Control Protocol CLI.
 
 This package installs the `ucp` command, downloads the matching published binary for your platform during `postinstall`, and ships the matching Unity bridge payload inside the npm package.
 

package/bridge/com.ucp.bridge/Editor/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("UCP.Bridge.Editor.Tests")]

package/bridge/com.ucp.bridge/Editor/AssemblyInfo.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: a1b2c3d4e5f60718293a4b5c6d7e8f90

package/bridge/com.ucp.bridge/Editor/Bridge/BridgeServer.cs

@@ -26,7 +26,7 @@ namespace UCP.Bridge
         private const int DefaultPort = 21342;
         private const int MaxPort = 21352;
         private const int MaxConnections = 4;
-        private const string ProtocolVersion = "0.5.2";
+        private const string ProtocolVersion = "0.6.1";
 
         private static TcpListener s_listener;
         private static CancellationTokenSource s_cts;
@@ -36,6 +36,13 @@ namespace UCP.Bridge
         private static string s_token;
         private static bool s_running;
 
+        // Handshake payload, captured once on the main thread at startup. `Application.dataPath`
+        // and friends are main-thread-only, which is the sole reason the handshake used to be
+        // queued behind `EditorApplication.update` -- see the socket-thread fast path in Dispatch.
+        private static string s_unityVersion = string.Empty;
+        private static string s_projectName = string.Empty;
+        private static string s_projectPath = string.Empty;
+
         // Main-thread action queue
         private static readonly ConcurrentQueue<Action> s_mainThreadQueue = new();
 
@@ -71,6 +78,7 @@ namespace UCP.Bridge
 
             try
             {
+                CaptureEditorIdentity();
                 RegisterHandlers();
                 LogsController.SeedHistoryFromConsole();
 
@@ -88,18 +96,31 @@ namespace UCP.Bridge
             }
         }
 
+        /// <summary>
+        /// Read the editor/project identity once, on the main thread, so the handshake handler is
+        /// pure and can run anywhere.
+        /// </summary>
+        private static void CaptureEditorIdentity()
+        {
+            s_unityVersion = Application.unityVersion;
+            s_projectName = Application.productName;
+            s_projectPath = Path.GetDirectoryName(Application.dataPath);
+        }
+
         private static void RegisterHandlers()
         {
             // Handshake
             s_router.Register("handshake", (paramsJson) =>
             {
+                // Touches no Unity API -- see CaptureEditorIdentity. Keep it that way: the
+                // socket-thread fast path in Dispatch depends on it.
                 return new
                 {
                     serverVersion = ProtocolVersion,
                     protocolVersion = ProtocolVersion,
-                    unityVersion = Application.unityVersion,
-                    projectName = Application.productName,
-                    projectPath = Path.GetDirectoryName(Application.dataPath)
+                    unityVersion = s_unityVersion,
+                    projectName = s_projectName,
+                    projectPath = s_projectPath
                 };
             });
 
@@ -145,6 +166,15 @@ namespace UCP.Bridge
             // Hierarchy Operations
             HierarchyController.Register(s_router);
 
+            // Transform authoring (move/rotate/scale/look-at, bulk read)
+            TransformController.Register(s_router);
+
+            // Spatial queries (raycast/overlap/bounds/ground/nearest)
+            SpatialController.Register(s_router);
+
+            // Composed visual perception (capture/isolate/orbit)
+            ViewController.Register(s_router);
+
             // Asset Management
             AssetController.Register(s_router);
             ImporterController.Register(s_router);
@@ -384,12 +414,22 @@ namespace UCP.Bridge
                 lock (s_clientLock) { s_logSubscribers.Remove(ws); }
             }
 
-            // Dispatch on main thread
             var capturedId = id;
             var capturedMethod = method;
             var capturedParams = paramsJson;
             var capturedWs = ws;
 
+            // Answer the handshake straight off the socket thread. Everything it returns is
+            // cached, so queueing it only bought a wait for the next `EditorApplication.update`
+            // tick -- roughly 90 ms on an idle editor, paid by *every* CLI command before its
+            // real request could even be dispatched.
+            if (capturedMethod == "handshake")
+            {
+                SendResponse(capturedWs, s_router.Dispatch(capturedMethod, capturedId, capturedParams));
+                return;
+            }
+
+            // Dispatch on main thread
             s_mainThreadQueue.Enqueue(() =>
             {
                 var response = s_router.Dispatch(capturedMethod, capturedId, capturedParams);

package/bridge/com.ucp.bridge/Editor/Compatibility/UnityObjectCompat.cs

@@ -1,13 +1,39 @@
 using UnityEditor;
 using UnityEngine;
+using UnityEngine.SceneManagement;
 
 namespace UCP.Bridge
 {
     internal static class UnityObjectCompat
     {
+        public static int GetId(this Object obj)
+        {
+#if UNITY_6000_5_OR_NEWER
+            return unchecked((int)EntityId.ToULong(obj.GetEntityId()));
+#else
+            return obj.GetInstanceID();
+#endif
+        }
+
+        public static long GetSceneHandle(Scene scene)
+        {
+#if UNITY_6000_5_OR_NEWER
+            return unchecked((long)scene.handle.GetRawData());
+#else
+            // On 6000.0–6000.4, Scene.handle is a SceneHandle with implicit int and
+            // uint operators; widening straight to long is ambiguous (CS0457). Pin the
+            // int conversion explicitly — handles are 32-bit on these versions.
+            return (int)scene.handle;
+#endif
+        }
+
         public static Object ResolveByInstanceId(int instanceId)
         {
+#if UNITY_6000_5_OR_NEWER
+            return EditorUtility.EntityIdToObject(EntityId.FromULong(unchecked((ulong)instanceId)));
+#else
             return EditorUtility.InstanceIDToObject(instanceId);
+#endif
         }
 
         public static T ResolveByInstanceId<T>(int instanceId) where T : Object

package/bridge/com.ucp.bridge/Editor/Controllers/AssetController.cs

@@ -125,7 +125,7 @@ namespace UCP.Bridge
                 ["name"] = asset.name,
                 ["type"] = asset.GetType().Name,
                 ["fullType"] = asset.GetType().FullName,
-                ["instanceId"] = asset.GetInstanceID(),
+                ["instanceId"] = asset.GetId(),
                 ["guid"] = AssetDatabase.AssetPathToGUID(assetPath)
             };
 
@@ -496,7 +496,7 @@ namespace UCP.Bridge
                 ["status"] = "ok",
                 ["path"] = assetPath,
                 ["type"] = soType.Name,
-                ["instanceId"] = instance.GetInstanceID()
+                ["instanceId"] = instance.GetId()
             };
         }
 

package/bridge/com.ucp.bridge/Editor/Controllers/CompilationController.cs

@@ -9,19 +9,86 @@ namespace UCP.Bridge
 {
     public static class CompilationController
     {
+        // SessionState survives domain reloads within one editor session. That is exactly the
+        // window we need: a compile that SUCCEEDS reloads the domain, a compile that FAILS keeps
+        // the old domain (no reload), and in both cases the captured diagnostics must still be
+        // readable by the CLI after the editor settles. CompileDiagnosticsTracker writes here;
+        // HandleDiagnostics reads it back.
+        internal const string DiagStateKey = "ucp.compile.diagnostics.state";
+        internal const string DiagRequestKey = "ucp.compile.diagnostics.requestId";
+        private const int MaxDiagnosticMessages = 200;
+
         public static void Register(CommandRouter router)
         {
             router.Register("compile", HandleCompile);
+            router.Register("compile/diagnostics", HandleDiagnostics);
             router.Register("refresh-assets", HandleRefresh);
             router.Register("script/doctor", HandleScriptDoctor);
         }
 
         private static object HandleCompile(string paramsJson)
         {
+            // Stamp a fresh request id and reset the diagnostics buffer so the CLI can tell THIS
+            // compile's result apart from a stale one. CompileDiagnosticsTracker fills in the
+            // per-assembly CompilerMessages as compilation progresses and finishes.
+            var requestId = SessionState.GetInt(DiagRequestKey, 0) + 1;
+            SessionState.SetInt(DiagRequestKey, requestId);
+            SessionState.SetString(DiagStateKey, MiniJson.Serialize(new Dictionary<string, object>
+            {
+                ["status"] = "requested",
+                ["requestId"] = requestId,
+                ["errorCount"] = 0,
+                ["warningCount"] = 0,
+                ["messages"] = new List<object>()
+            }));
+
             AssetDatabase.Refresh(ImportAssetOptions.ForceSynchronousImport);
             CompilationPipeline.RequestScriptCompilation();
             TrySyncSolution();
-            return new { status = "ok", message = "Asset database refreshed and compilation requested" };
+            return new Dictionary<string, object>
+            {
+                ["status"] = "ok",
+                ["message"] = "Asset database refreshed and compilation requested",
+                ["requestId"] = requestId
+            };
+        }
+
+        private static object HandleDiagnostics(string paramsJson)
+        {
+            var raw = SessionState.GetString(DiagStateKey, string.Empty);
+            if (string.IsNullOrEmpty(raw)
+                || !(MiniJson.Deserialize(raw) is Dictionary<string, object> state))
+            {
+                return new Dictionary<string, object>
+                {
+                    ["status"] = "idle",
+                    ["requestId"] = SessionState.GetInt(DiagRequestKey, 0),
+                    ["errorCount"] = 0,
+                    ["warningCount"] = 0,
+                    ["messages"] = new List<object>(),
+                    ["compiling"] = EditorApplication.isCompiling
+                };
+            }
+
+            // Surface live compile state too: a "completed" buffer while isCompiling is true means
+            // another compilation has already started after the one the CLI asked about.
+            state["compiling"] = EditorApplication.isCompiling;
+            return state;
+        }
+
+        internal static void WriteDiagnosticsState(string status, int errorCount, int warningCount, List<object> messages)
+        {
+            var truncated = messages.Count > MaxDiagnosticMessages;
+            var trimmed = truncated ? messages.GetRange(0, MaxDiagnosticMessages) : messages;
+            SessionState.SetString(DiagStateKey, MiniJson.Serialize(new Dictionary<string, object>
+            {
+                ["status"] = status,
+                ["requestId"] = SessionState.GetInt(DiagRequestKey, 0),
+                ["errorCount"] = errorCount,
+                ["warningCount"] = warningCount,
+                ["truncated"] = truncated,
+                ["messages"] = new List<object>(trimmed)
+            }));
         }
 
         private static object HandleRefresh(string paramsJson)
@@ -110,4 +177,73 @@ namespace UCP.Bridge
             }
         }
     }
+
+    /// <summary>
+    /// Captures per-assembly compiler messages so `compile` can report whether the build actually
+    /// succeeded instead of always claiming success. Subscribes once per domain load; accumulates
+    /// messages for the in-flight compilation in static fields (safe because a domain reload only
+    /// happens AFTER compilationFinished) and flushes them to SessionState, which persists across
+    /// the reload for the CLI to read once the editor settles.
+    /// </summary>
+    [InitializeOnLoad]
+    internal static class CompileDiagnosticsTracker
+    {
+        private static readonly List<object> s_messages = new List<object>();
+        private static int s_errorCount;
+        private static int s_warningCount;
+
+        static CompileDiagnosticsTracker()
+        {
+            CompilationPipeline.compilationStarted += OnCompilationStarted;
+            CompilationPipeline.assemblyCompilationFinished += OnAssemblyCompilationFinished;
+            CompilationPipeline.compilationFinished += OnCompilationFinished;
+        }
+
+        private static void OnCompilationStarted(object context)
+        {
+            s_messages.Clear();
+            s_errorCount = 0;
+            s_warningCount = 0;
+            CompilationController.WriteDiagnosticsState("compiling", 0, 0, s_messages);
+        }
+
+        private static void OnAssemblyCompilationFinished(string assemblyPath, CompilerMessage[] messages)
+        {
+            if (messages == null) return;
+            var assembly = Path.GetFileNameWithoutExtension(assemblyPath);
+            foreach (var message in messages)
+            {
+                string type;
+                switch (message.type)
+                {
+                    case CompilerMessageType.Error:
+                        type = "error";
+                        s_errorCount++;
+                        break;
+                    case CompilerMessageType.Warning:
+                        type = "warning";
+                        s_warningCount++;
+                        break;
+                    default:
+                        type = "info";
+                        break;
+                }
+
+                s_messages.Add(new Dictionary<string, object>
+                {
+                    ["assembly"] = assembly,
+                    ["type"] = type,
+                    ["message"] = message.message ?? string.Empty,
+                    ["file"] = message.file ?? string.Empty,
+                    ["line"] = message.line,
+                    ["column"] = message.column
+                });
+            }
+        }
+
+        private static void OnCompilationFinished(object context)
+        {
+            CompilationController.WriteDiagnosticsState("completed", s_errorCount, s_warningCount, s_messages);
+        }
+    }
 }

package/bridge/com.ucp.bridge/Editor/Controllers/EditorModalGuard.cs

@@ -0,0 +1,60 @@
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine.SceneManagement;
+
+namespace UCP.Bridge
+{
+    /// <summary>
+    /// Centralizes editor operations that must stay non-blocking when the bridge drives
+    /// the editor headlessly.
+    ///
+    /// Bridge commands run on the main thread via EditorApplication.update. Any modal
+    /// dialog (EditorSceneManager.SaveCurrentModifiedScenesIfUserWantsTo,
+    /// EditorUtility.DisplayDialog, file/folder panels, ...) blocks that loop with no user
+    /// present to dismiss it, hanging every queued command and timing out the CLI. Bridge
+    /// code must therefore never call a modal API. Scene saving is the most common trap, so
+    /// it lives here behind a single audited, modal-free implementation shared by every
+    /// controller instead of being copy-pasted per controller.
+    /// </summary>
+    internal static class EditorModalGuard
+    {
+        /// <summary>
+        /// Saves every loaded dirty scene without prompting. Dirty untitled scenes have no
+        /// path to save to; they are discarded (replaced with a fresh empty scene) when
+        /// <paramref name="discardUntitled"/> is true, otherwise an exception is thrown so
+        /// the caller surfaces a clear error instead of silently losing work or blocking on
+        /// a save dialog.
+        /// </summary>
+        public static void SaveOpenDirtyScenes(bool saveDirtyScenes, bool discardUntitled)
+        {
+            if (!saveDirtyScenes)
+                return;
+
+            var requiresUntitledDiscard = false;
+
+            for (var index = 0; index < SceneManager.sceneCount; index++)
+            {
+                var scene = SceneManager.GetSceneAt(index);
+                if (!scene.isLoaded || !scene.isDirty)
+                    continue;
+
+                if (string.IsNullOrEmpty(scene.path))
+                {
+                    if (!discardUntitled)
+                        throw new System.InvalidOperationException("Dirty untitled scene cannot be auto-saved. Retry with discardUntitled=true.");
+
+                    requiresUntitledDiscard = true;
+                    continue;
+                }
+
+                if (!EditorSceneManager.SaveScene(scene))
+                    throw new System.InvalidOperationException($"Failed to auto-save dirty scene: {scene.path}");
+
+                SceneChangeTracker.ClearScene(scene);
+            }
+
+            if (requiresUntitledDiscard)
+                EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
+        }
+    }
+}

package/bridge/com.ucp.bridge/Editor/Controllers/EditorModalGuard.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6

package/bridge/com.ucp.bridge/Editor/Controllers/HierarchyController.cs

@@ -26,7 +26,19 @@ namespace UCP.Bridge
             if (p != null && p.TryGetValue("name", out var nameObj) && nameObj != null)
                 name = nameObj.ToString();
 
-            var go = new GameObject(name);
+            // Optional primitive: build a Cube/Sphere/etc. with mesh + collider in one step.
+            // Without this an agent has to hand-assemble MeshFilter + MeshRenderer and somehow
+            // reference the built-in mesh, which is not practical over the CLI.
+            GameObject go;
+            if (p != null && p.TryGetValue("primitive", out var primObj) && primObj != null)
+            {
+                go = GameObject.CreatePrimitive(ParsePrimitive(primObj.ToString()));
+                go.name = name;
+            }
+            else
+            {
+                go = new GameObject(name);
+            }
             Undo.RegisterCreatedObjectUndo(go, "UCP Create GameObject");
 
             // Optional parent
@@ -61,7 +73,7 @@ namespace UCP.Bridge
             return new Dictionary<string, object>
             {
                 ["status"] = "ok",
-                ["instanceId"] = go.GetInstanceID(),
+                ["instanceId"] = go.GetId(),
                 ["name"] = go.name
             };
         }
@@ -140,7 +152,12 @@ namespace UCP.Bridge
                 string prefabPath = prefabObj.ToString();
                 var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(prefabPath);
                 if (prefab == null)
-                    throw new ArgumentException($"Prefab not found: {prefabPath}");
+                {
+                    var hint = LooksLikePrimitive(prefabPath)
+                        ? " To create a built-in primitive, use object create with a primitive instead (e.g. `ucp object create MyCube --primitive Cube`); instantiate is only for prefab assets under Assets/."
+                        : string.Empty;
+                    throw new ArgumentException($"Prefab not found: {prefabPath}.{hint}");
+                }
                 source = prefab;
             }
             // Instantiate from existing scene object (clone)
@@ -192,7 +209,7 @@ namespace UCP.Bridge
             return new Dictionary<string, object>
             {
                 ["status"] = "ok",
-                ["instanceId"] = instance.GetInstanceID(),
+                ["instanceId"] = instance.GetId(),
                 ["name"] = instance.name
             };
         }
@@ -267,6 +284,40 @@ namespace UCP.Bridge
             };
         }
 
+        private static bool LooksLikePrimitive(string path)
+        {
+            if (string.IsNullOrEmpty(path)) return false;
+            var token = path.Replace("PrimitiveType.", "").Trim();
+            switch (token.ToLowerInvariant())
+            {
+                case "cube":
+                case "sphere":
+                case "capsule":
+                case "cylinder":
+                case "plane":
+                case "quad":
+                    return true;
+                default:
+                    return path.IndexOf("PrimitiveType", System.StringComparison.OrdinalIgnoreCase) >= 0;
+            }
+        }
+
+        private static PrimitiveType ParsePrimitive(string value)
+        {
+            switch (value.Trim().ToLowerInvariant())
+            {
+                case "cube": return PrimitiveType.Cube;
+                case "sphere": return PrimitiveType.Sphere;
+                case "capsule": return PrimitiveType.Capsule;
+                case "cylinder": return PrimitiveType.Cylinder;
+                case "plane": return PrimitiveType.Plane;
+                case "quad": return PrimitiveType.Quad;
+                default:
+                    throw new ArgumentException(
+                        $"Unknown primitive '{value}'. Use one of: Cube, Sphere, Capsule, Cylinder, Plane, Quad.");
+            }
+        }
+
         private static Type ResolveComponentType(string typeName)
         {
             // Try exact match first
@@ -314,7 +365,7 @@ namespace UCP.Bridge
 
         private static GameObject FindInHierarchy(GameObject go, int instanceId)
         {
-            if (go.GetInstanceID() == instanceId) return go;
+            if (go.GetId() == instanceId) return go;
             for (int i = 0; i < go.transform.childCount; i++)
             {
                 var found = FindInHierarchy(go.transform.GetChild(i).gameObject, instanceId);

package/bridge/com.ucp.bridge/Editor/Controllers/MaterialController.cs

@@ -50,7 +50,7 @@ namespace UCP.Bridge
                 ["path"] = path,
                 ["name"] = material.name,
                 ["shader"] = shader.name,
-                ["instanceId"] = material.GetInstanceID()
+                ["instanceId"] = material.GetId()
             };
         }
 
@@ -278,7 +278,7 @@ namespace UCP.Bridge
                         {
                             ["name"] = tex.name,
                             ["path"] = texPath,
-                            ["instanceId"] = tex.GetInstanceID()
+                            ["instanceId"] = tex.GetId()
                         };
                     }
                     return null;