@quenty/studio-bridge 0.7.1 → 0.8.0

package/src/commands/explorer/query/query-data-model.luau

@@ -0,0 +1,206 @@
+--[[
+	QueryDataModel action handler for the studio-bridge plugin.
+
+	Resolves a dot-separated path to a Roblox Instance and serializes it
+	into a DataModelInstance response with optional properties, attributes,
+	and children up to a specified depth.
+
+	Protocol:
+	  Request:  { type: "queryDataModel", path: "Workspace.SpawnLocation", depth: 1, properties: [], includeAttributes: true }
+	  Response: { type: "dataModelResult", payload: { instance: DataModelInstance } }
+]]
+
+local QueryDataModelAction = {}
+
+-- ---------------------------------------------------------------------------
+-- Property serialization
+-- ---------------------------------------------------------------------------
+
+local SKIP_PROPERTIES = {
+	Parent = true,
+}
+
+local function serializeValue(value: any): any
+	local t = typeof(value)
+
+	if t == "string" or t == "number" or t == "boolean" then
+		return value
+	elseif t == "nil" then
+		return nil
+	elseif t == "Vector3" then
+		return { type = "Vector3", value = { value.X, value.Y, value.Z } }
+	elseif t == "Vector2" then
+		return { type = "Vector2", value = { value.X, value.Y } }
+	elseif t == "CFrame" then
+		return { type = "CFrame", value = { value:GetComponents() } }
+	elseif t == "Color3" then
+		return { type = "Color3", value = { value.R, value.G, value.B } }
+	elseif t == "UDim2" then
+		return { type = "UDim2", value = { value.X.Scale, value.X.Offset, value.Y.Scale, value.Y.Offset } }
+	elseif t == "UDim" then
+		return { type = "UDim", value = { value.Scale, value.Offset } }
+	elseif t == "BrickColor" then
+		return { type = "BrickColor", name = value.Name, value = value.Number }
+	elseif t == "EnumItem" then
+		return { type = "EnumItem", enum = tostring(value.EnumType), name = value.Name, value = value.Value }
+	elseif t == "Instance" then
+		return { type = "Instance", className = value.ClassName, path = value:GetFullName() }
+	else
+		return { type = "Unsupported", typeName = t, toString = tostring(value) }
+	end
+end
+
+local function serializeProperties(instance: Instance, propertyFilter: { string }?): { [string]: any }
+	local result = {}
+
+	-- If a filter is provided and empty, return no properties
+	if propertyFilter and #propertyFilter == 0 then
+		return result
+	end
+
+	-- Use API dump approach: read common properties via pcall
+	-- Since Roblox doesn't expose a property list, we read known safe properties
+	-- and any specifically requested ones
+	if propertyFilter then
+		for _, propName in propertyFilter do
+			if not SKIP_PROPERTIES[propName] then
+				local ok, value = pcall(function()
+					return (instance :: any)[propName]
+				end)
+				if ok then
+					result[propName] = serializeValue(value)
+				end
+			end
+		end
+	else
+		-- No filter: read common properties
+		local commonProps = { "Name", "ClassName" }
+		for _, propName in commonProps do
+			local ok, value = pcall(function()
+				return (instance :: any)[propName]
+			end)
+			if ok then
+				result[propName] = serializeValue(value)
+			end
+		end
+	end
+
+	return result
+end
+
+local function serializeAttributes(instance: Instance): { [string]: any }
+	local result = {}
+	local ok, attrs = pcall(function()
+		return instance:GetAttributes()
+	end)
+	if ok and attrs then
+		for key, value in attrs do
+			result[key] = serializeValue(value)
+		end
+	end
+	return result
+end
+
+-- ---------------------------------------------------------------------------
+-- Instance serialization
+-- ---------------------------------------------------------------------------
+
+local function serializeInstance(
+	instance: Instance,
+	depth: number,
+	propertyFilter: { string }?,
+	includeAttributes: boolean
+): { [string]: any }
+	local children = instance:GetChildren()
+	local node: { [string]: any } = {
+		name = instance.Name,
+		className = instance.ClassName,
+		path = instance:GetFullName(),
+		properties = serializeProperties(instance, propertyFilter),
+		attributes = if includeAttributes then serializeAttributes(instance) else {},
+		childCount = #children,
+	}
+
+	if depth > 0 then
+		local serializedChildren = {}
+		for _, child in children do
+			table.insert(serializedChildren, serializeInstance(child, depth - 1, propertyFilter, includeAttributes))
+		end
+		node.children = serializedChildren
+	end
+
+	return node
+end
+
+-- ---------------------------------------------------------------------------
+-- Path resolution
+-- ---------------------------------------------------------------------------
+
+local function resolveInstance(path: string): Instance?
+	-- Split path by dots, resolve from game
+	local parts = string.split(path, ".")
+	local startIndex = 1
+
+	-- Skip leading "game" since we start from game
+	if parts[1] == "game" then
+		startIndex = 2
+	end
+
+	local current: any = game
+	for i = startIndex, #parts do
+		local part = parts[i]
+		-- Try as a service first (e.g. "Workspace", "ReplicatedStorage")
+		local ok, child = pcall(function()
+			return current:FindFirstChild(part)
+		end)
+		if not ok or not child then
+			-- Try GetService for top-level services
+			if current == game then
+				local serviceOk, service = pcall(function()
+					return game:GetService(part)
+				end)
+				if serviceOk and service then
+					current = service
+					continue
+				end
+			end
+			return nil
+		end
+		current = child
+	end
+
+	return current
+end
+
+-- ---------------------------------------------------------------------------
+-- Public API
+-- ---------------------------------------------------------------------------
+
+function QueryDataModelAction.register(router: any)
+	router:setResponseType("queryDataModel", "dataModelResult")
+	router:register("queryDataModel", function(payload: { [string]: any }, _requestId: string, _sessionId: string)
+		local path = payload.path
+		if not path or type(path) ~= "string" then
+			return nil -- ActionRouter will return UNKNOWN_REQUEST for nil
+		end
+
+		local depth = payload.depth or 0
+		local propertyFilter = payload.properties -- nil means common props, {} means none
+		local includeAttributes = payload.includeAttributes == true
+
+		local instance = resolveInstance(path)
+		if not instance then
+			return {
+				success = false,
+				code = "INSTANCE_NOT_FOUND",
+				message = `Instance not found at path: {path}`,
+			}
+		end
+
+		return {
+			instance = serializeInstance(instance, depth, propertyFilter, includeAttributes),
+		}
+	end)
+end
+
+return QueryDataModelAction

package/src/commands/explorer/query/query.test.ts

@@ -0,0 +1,297 @@
+/**
+ * Unit tests for the query command handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { queryDataModelHandlerAsync } from './query.js';
+
+function createMockSession(dataModelResult: {
+  instance: {
+    name: string;
+    className: string;
+    path: string;
+    properties: Record<string, unknown>;
+    attributes: Record<string, unknown>;
+    childCount: number;
+    children?: Array<{
+      name: string;
+      className: string;
+      path: string;
+      properties: Record<string, unknown>;
+      attributes: Record<string, unknown>;
+      childCount: number;
+    }>;
+  };
+}) {
+  return {
+    queryDataModelAsync: vi.fn().mockResolvedValue(dataModelResult),
+  } as any;
+}
+
+describe('queryDataModelHandlerAsync', () => {
+  it('returns node with summary', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'SpawnLocation',
+        className: 'SpawnLocation',
+        path: 'game.Workspace.SpawnLocation',
+        properties: { Anchored: true },
+        attributes: {},
+        childCount: 0,
+      },
+    });
+
+    const result = await queryDataModelHandlerAsync(session, {
+      path: 'Workspace.SpawnLocation',
+    });
+
+    expect(result.node.name).toBe('SpawnLocation');
+    expect(result.node.className).toBe('SpawnLocation');
+    expect(result.node.path).toBe('game.Workspace.SpawnLocation');
+    expect(result.summary).toContain('SpawnLocation');
+    expect(result.summary).toContain('game.Workspace.SpawnLocation');
+  });
+
+  it('prepends game. to path when not present', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+        properties: {},
+        attributes: {},
+        childCount: 5,
+      },
+    });
+
+    await queryDataModelHandlerAsync(session, { path: 'Workspace' });
+
+    expect(session.queryDataModelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ path: 'game.Workspace' })
+    );
+  });
+
+  it('does not double-prepend game. when already present', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+        properties: {},
+        attributes: {},
+        childCount: 0,
+      },
+    });
+
+    await queryDataModelHandlerAsync(session, { path: 'game.Workspace' });
+
+    expect(session.queryDataModelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ path: 'game.Workspace' })
+    );
+  });
+
+  it('passes children option as depth 1', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+        properties: {},
+        attributes: {},
+        childCount: 2,
+        children: [
+          {
+            name: 'Part1',
+            className: 'Part',
+            path: 'game.Workspace.Part1',
+            properties: {},
+            attributes: {},
+            childCount: 0,
+          },
+          {
+            name: 'Part2',
+            className: 'Part',
+            path: 'game.Workspace.Part2',
+            properties: {},
+            attributes: {},
+            childCount: 0,
+          },
+        ],
+      },
+    });
+
+    const result = await queryDataModelHandlerAsync(session, {
+      path: 'Workspace',
+      children: true,
+    });
+
+    expect(session.queryDataModelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ depth: 1 })
+    );
+    expect(result.node.children).toHaveLength(2);
+    expect(result.node.children![0].name).toBe('Part1');
+    expect(result.node.children![1].name).toBe('Part2');
+  });
+
+  it('passes descendants option with default depth', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+        properties: {},
+        attributes: {},
+        childCount: 0,
+      },
+    });
+
+    await queryDataModelHandlerAsync(session, {
+      path: 'Workspace',
+      descendants: true,
+    });
+
+    expect(session.queryDataModelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ depth: 10 })
+    );
+  });
+
+  it('respects explicit depth with descendants', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+        properties: {},
+        attributes: {},
+        childCount: 0,
+      },
+    });
+
+    await queryDataModelHandlerAsync(session, {
+      path: 'Workspace',
+      descendants: true,
+      depth: 3,
+    });
+
+    expect(session.queryDataModelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ depth: 3 })
+    );
+  });
+
+  it('includes properties when requested', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Part1',
+        className: 'Part',
+        path: 'game.Workspace.Part1',
+        properties: {
+          Anchored: true,
+          Position: { type: 'Vector3', value: [0, 5, 0] },
+        },
+        attributes: {},
+        childCount: 0,
+      },
+    });
+
+    const result = await queryDataModelHandlerAsync(session, {
+      path: 'Workspace.Part1',
+      properties: true,
+    });
+
+    expect(result.node.properties).toBeDefined();
+    expect(result.node.properties!['Anchored']).toBe(true);
+  });
+
+  it('includes attributes when requested', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Part1',
+        className: 'Part',
+        path: 'game.Workspace.Part1',
+        properties: {},
+        attributes: { health: 100, tag: 'enemy' },
+        childCount: 0,
+      },
+    });
+
+    const result = await queryDataModelHandlerAsync(session, {
+      path: 'Workspace.Part1',
+      attributes: true,
+    });
+
+    expect(result.node.attributes).toBeDefined();
+    expect(result.node.attributes!['health']).toBe(100);
+    expect(result.node.attributes!['tag']).toBe('enemy');
+  });
+
+  it('omits empty properties and attributes from node', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Folder',
+        className: 'Folder',
+        path: 'game.Workspace.Folder',
+        properties: {},
+        attributes: {},
+        childCount: 0,
+      },
+    });
+
+    const result = await queryDataModelHandlerAsync(session, {
+      path: 'Workspace.Folder',
+    });
+
+    expect(result.node.properties).toBeUndefined();
+    expect(result.node.attributes).toBeUndefined();
+    expect(result.node.children).toBeUndefined();
+  });
+
+  it('propagates errors from session', async () => {
+    const session = {
+      queryDataModelAsync: vi
+        .fn()
+        .mockRejectedValue(new Error('Instance not found')),
+    } as any;
+
+    await expect(
+      queryDataModelHandlerAsync(session, { path: 'Workspace.NonExistent' })
+    ).rejects.toThrow('Instance not found');
+  });
+
+  it('handles path "game" as standalone', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Game',
+        className: 'DataModel',
+        path: 'game',
+        properties: {},
+        attributes: {},
+        childCount: 10,
+      },
+    });
+
+    await queryDataModelHandlerAsync(session, { path: 'game' });
+
+    expect(session.queryDataModelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ path: 'game' })
+    );
+  });
+
+  it('without children or descendants uses depth 0', async () => {
+    const session = createMockSession({
+      instance: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+        properties: {},
+        attributes: {},
+        childCount: 5,
+      },
+    });
+
+    await queryDataModelHandlerAsync(session, { path: 'Workspace' });
+
+    expect(session.queryDataModelAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ depth: 0 })
+    );
+  });
+});

package/src/commands/explorer/query/query.ts

@@ -0,0 +1,157 @@
+/**
+ * `explorer query` — query the Roblox DataModel instance tree from a
+ * connected Studio session.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import type { BridgeSession } from '../../../bridge/index.js';
+import type {
+  DataModelResult as BridgeDataModelResult,
+  DataModelInstance,
+} from '../../../bridge/index.js';
+
+export type { DataModelInstance };
+
+export interface QueryOptions {
+  path: string;
+  children?: boolean;
+  descendants?: boolean;
+  depth?: number;
+  properties?: boolean;
+  attributes?: boolean;
+}
+
+export interface DataModelNode {
+  name: string;
+  className: string;
+  path: string;
+  properties?: Record<string, unknown>;
+  attributes?: Record<string, unknown>;
+  children?: DataModelNode[];
+}
+
+export interface QueryResult {
+  node: DataModelNode;
+  summary: string;
+}
+
+function normalizePath(path: string): string {
+  if (path.startsWith('game.') || path === 'game') {
+    return path;
+  }
+  return `game.${path}`;
+}
+
+function toDataModelNode(instance: DataModelInstance): DataModelNode {
+  const node: DataModelNode = {
+    name: instance.name,
+    className: instance.className,
+    path: instance.path,
+  };
+
+  if (instance.properties && Object.keys(instance.properties).length > 0) {
+    node.properties = instance.properties;
+  }
+
+  if (instance.attributes && Object.keys(instance.attributes).length > 0) {
+    node.attributes = instance.attributes;
+  }
+
+  if (instance.children && instance.children.length > 0) {
+    node.children = instance.children.map(toDataModelNode);
+  }
+
+  return node;
+}
+
+export async function queryDataModelHandlerAsync(
+  session: BridgeSession,
+  options: QueryOptions
+): Promise<QueryResult> {
+  const normalizedPath = normalizePath(options.path);
+
+  // --depth wins when explicitly set; otherwise fall back to flag-driven defaults.
+  const depth =
+    options.depth !== undefined
+      ? options.depth
+      : options.descendants
+      ? 10
+      : options.children
+      ? 1
+      : 0;
+
+  const result: BridgeDataModelResult = await session.queryDataModelAsync({
+    path: normalizedPath,
+    depth,
+    properties: options.properties ? undefined : [],
+    includeAttributes: options.attributes,
+  });
+
+  if (!result.instance) {
+    throw new Error(`Instance not found at path '${options.path}'`);
+  }
+
+  const node = toDataModelNode(result.instance);
+
+  return {
+    node,
+    summary: `${node.name} (${node.className}) at ${node.path}`,
+  };
+}
+
+function formatNode(node: DataModelNode, depth: number): string {
+  const indent = '  '.repeat(depth);
+  const lines = [
+    `${indent}${node.name} (${OutputHelper.formatDim(
+      node.className
+    )}) ${OutputHelper.formatDim(node.path)}`,
+  ];
+  if (node.properties) {
+    for (const [key, val] of Object.entries(node.properties)) {
+      lines.push(`${indent}  ${key}: ${JSON.stringify(val)}`);
+    }
+  }
+  if (node.attributes) {
+    for (const [key, val] of Object.entries(node.attributes)) {
+      lines.push(`${indent}  @${key}: ${JSON.stringify(val)}`);
+    }
+  }
+  for (const child of node.children ?? []) {
+    lines.push(formatNode(child, depth + 1));
+  }
+  return lines.join('\n');
+}
+
+export function formatQueryText(result: QueryResult): string {
+  return formatNode(result.node, 0);
+}
+
+export const queryCommand = defineCommand<QueryOptions, QueryResult>({
+  group: 'explorer',
+  name: 'query',
+  description: 'Query the Roblox DataModel instance tree',
+  category: 'execution',
+  safety: 'read',
+  scope: 'session',
+  args: {
+    path: arg.positional({
+      description: 'DataModel path (e.g. "Workspace" or "game.Workspace")',
+    }),
+    depth: arg.option({
+      description: 'Levels of descendants to include',
+      type: 'number',
+    }),
+    properties: arg.flag({ description: 'Include instance properties' }),
+    attributes: arg.flag({ description: 'Include instance attributes' }),
+    children: arg.flag({ description: 'Include direct children' }),
+    descendants: arg.flag({ description: 'Include all descendants' }),
+  },
+  cli: {
+    format: formatQueryText,
+  },
+  handler: async (session, args) => {
+    return queryDataModelHandlerAsync(session, args);
+  },
+});