@quenty/studio-bridge 0.21.1 → 0.22.0

package/src/deploy/deploy-places.test.ts

@@ -0,0 +1,127 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, beforeEach, describe, it, expect } from 'vitest';
+import {
+  findInstancesShowingPlaceAsync,
+  tryFindFolderInstanceAsync,
+} from './deploy-places.js';
+
+let tempDir: string;
+
+beforeEach(async () => {
+  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'deploy-places-test-'));
+  await fs.writeFile(
+    path.join(tempDir, 'deploy.nevermore.json'),
+    JSON.stringify({
+      targets: {
+        test: { universeId: 9, placeId: 111, project: 'test.project.json' },
+        integration: {
+          places: [
+            {
+              name: 'hub',
+              universeId: 9,
+              placeId: 222,
+              project: 'hub.project.json',
+            },
+          ],
+        },
+      },
+    })
+  );
+});
+
+afterEach(async () => {
+  await fs.rm(tempDir, { recursive: true, force: true });
+});
+
+/** Studios by instance id, with the place id each registered and the one each has open now. */
+function createConnection(
+  studios: Record<string, { registered: number; live: number }>
+) {
+  const ids = Object.keys(studios);
+  return {
+    listInstances: () =>
+      ids.map((instanceId) => ({
+        instanceId,
+        placeId: studios[instanceId].registered,
+      })),
+    listSessions: () =>
+      ids.map((instanceId) => ({
+        instanceId,
+        sessionId: `${instanceId}-edit`,
+        context: 'edit',
+      })),
+    getSession: (sessionId: string) => ({
+      queryStateAsync: async () => ({
+        placeId: studios[sessionId.replace(/-edit$/, '')].live,
+      }),
+    }),
+  } as any;
+}
+
+describe('tryFindFolderInstanceAsync', () => {
+  it("picks the one Studio that has a place of the folder's config open", async () => {
+    const connection = createConnection({
+      'local-1a2b': { registered: 0, live: 0 },
+      'place1-3c4d': { registered: 0, live: 222 },
+    });
+
+    const found = await tryFindFolderInstanceAsync(connection, tempDir);
+
+    expect(found?.instanceId).toBe('place1-3c4d');
+    expect(found?.deployPlace.selector).toBe('integration');
+  });
+
+  it('leaves the choice alone when two Studios have the config open', async () => {
+    const connection = createConnection({
+      'place1-1a2b': { registered: 111, live: 111 },
+      'place1-3c4d': { registered: 222, live: 222 },
+    });
+
+    expect(
+      await tryFindFolderInstanceAsync(connection, tempDir)
+    ).toBeUndefined();
+  });
+
+  it('leaves a single Studio to the usual resolution', async () => {
+    const connection = createConnection({
+      'local-1a2b': { registered: 0, live: 0 },
+    });
+
+    expect(
+      await tryFindFolderInstanceAsync(connection, tempDir)
+    ).toBeUndefined();
+  });
+
+  it('does nothing outside a deploy.nevermore.json', async () => {
+    const empty = await fs.mkdtemp(
+      path.join(os.tmpdir(), 'deploy-places-empty-')
+    );
+    const connection = createConnection({
+      'place1-1a2b': { registered: 111, live: 111 },
+      'local-3c4d': { registered: 0, live: 0 },
+    });
+
+    try {
+      expect(
+        await tryFindFolderInstanceAsync(connection, empty)
+      ).toBeUndefined();
+    } finally {
+      await fs.rm(empty, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('findInstancesShowingPlaceAsync', () => {
+  it('reads a cloud place id live when it registered as 0', async () => {
+    const connection = createConnection({
+      'place1-1a2b': { registered: 0, live: 111 },
+      'place1-3c4d': { registered: 222, live: 222 },
+    });
+
+    expect(await findInstancesShowingPlaceAsync(connection, 111)).toEqual([
+      'place1-1a2b',
+    ]);
+  });
+});

package/src/deploy/deploy-places.ts

@@ -0,0 +1,229 @@
+/**
+ * Finds the places of the nearest `deploy.nevermore.json`, so commands run in
+ * a package or game folder can open or pick that project's Studio.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import {
+  formatTargetSelector,
+  loadDeployConfigAsync,
+  parseTargetSelector,
+  resolveDefaultTargetName,
+  resolveDeployTargetPlaces,
+  type DeployConfig,
+  type DeployTarget,
+} from '@quenty/nevermore-deploy';
+import type { BridgeConnection, InstanceInfo } from '../bridge/index.js';
+
+export const DEPLOY_CONFIG_FILE_NAME = 'deploy.nevermore.json';
+
+const PLACE_ID_QUERY_TIMEOUT_MS = 3_000;
+
+export interface DeployPlace {
+  /** The target selector naming this place, e.g. `test` or `integration.places.hub`. */
+  selector: string;
+  place: DeployTarget;
+  configPath: string;
+}
+
+/**
+ * The nearest `deploy.nevermore.json` at or above `startDir` that has targets.
+ * A repo root's config can hold only a shared `universeId`, so it is skipped.
+ */
+export async function findDeployConfigPathAsync(
+  startDir: string
+): Promise<string | undefined> {
+  let current = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(current, DEPLOY_CONFIG_FILE_NAME);
+    if (await hasTargetsAsync(candidate)) {
+      return candidate;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+}
+
+async function hasTargetsAsync(configPath: string): Promise<boolean> {
+  let content: string;
+  try {
+    content = await fs.readFile(configPath, 'utf-8');
+  } catch {
+    return false;
+  }
+  try {
+    return 'targets' in (JSON.parse(content) as object);
+  } catch {
+    // Loading it reports the parse error
+    return true;
+  }
+}
+
+/**
+ * The place a target names, from the config nearest `cwd`. Without `target`,
+ * uses the config's default target. Undefined when no config is found and no
+ * target was asked for.
+ */
+export async function resolveDeployPlaceAsync(
+  cwd: string,
+  target?: string
+): Promise<DeployPlace | undefined> {
+  const configPath = await findDeployConfigPathAsync(cwd);
+  if (!configPath) {
+    if (target !== undefined) {
+      throw new Error(
+        `No ${DEPLOY_CONFIG_FILE_NAME} in ${cwd} or its parents to find target '${target}' in`
+      );
+    }
+    return undefined;
+  }
+
+  const config = await loadDeployConfigAsync(configPath);
+  let selector = target;
+  if (selector === undefined) {
+    try {
+      selector = resolveDefaultTargetName(config);
+    } catch {
+      throw new Error(
+        `${configPath} has several targets and no default. Name one: ${Object.keys(
+          config.targets
+        ).join(', ')}`
+      );
+    }
+  }
+  const places = resolveDeployTargetPlaces(config, selector);
+  if (places.length > 1) {
+    const { targetName } = parseTargetSelector(selector);
+    const choices = places
+      .map((place) =>
+        place.name
+          ? `  - ${formatTargetSelector({ targetName, placeName: place.name })}`
+          : `  - place ${place.placeId}`
+      )
+      .join('\n');
+    throw new Error(
+      `Target '${targetName}' has ${places.length} places. Pick one:\n${choices}`
+    );
+  }
+
+  return { selector, place: places[0], configPath };
+}
+
+/** Every place in `config`, each under the selector that names it. */
+export function listDeployPlaces(
+  config: DeployConfig,
+  configPath: string
+): DeployPlace[] {
+  return Object.keys(config.targets).flatMap((targetName) => {
+    const places = resolveDeployTargetPlaces(config, targetName);
+    return places.map((place) => ({
+      selector:
+        places.length > 1 && place.name
+          ? formatTargetSelector({ targetName, placeName: place.name })
+          : targetName,
+      place,
+      configPath,
+    }));
+  });
+}
+
+export interface FolderInstance {
+  instanceId: string;
+  deployPlace: DeployPlace;
+}
+
+/**
+ * The one connected Studio that has a place of the nearest config open, when
+ * several Studios are connected and exactly one does. Undefined otherwise,
+ * including when the config can't be read.
+ */
+export async function tryFindFolderInstanceAsync(
+  connection: BridgeConnection,
+  cwd: string
+): Promise<FolderInstance | undefined> {
+  const instances = connection.listInstances();
+  if (instances.length < 2) {
+    return undefined;
+  }
+
+  const configPath = await findDeployConfigPathAsync(cwd);
+  if (!configPath) {
+    return undefined;
+  }
+  let places: DeployPlace[];
+  try {
+    places = listDeployPlaces(
+      await loadDeployConfigAsync(configPath),
+      configPath
+    );
+  } catch {
+    return undefined;
+  }
+
+  const placeIds = await readInstancePlaceIdsAsync(connection);
+  const matches = placeIds.flatMap(({ instanceId, placeId }) => {
+    const deployPlace = places.find((p) => p.place.placeId === placeId);
+    return deployPlace ? [{ instanceId, deployPlace }] : [];
+  });
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
+/** The connected Studios whose open place is `placeId`. */
+export async function findInstancesShowingPlaceAsync(
+  connection: BridgeConnection,
+  placeId: number
+): Promise<string[]> {
+  const placeIds = await readInstancePlaceIdsAsync(connection);
+  return placeIds
+    .filter((instance) => instance.placeId === placeId)
+    .map((instance) => instance.instanceId);
+}
+
+async function readInstancePlaceIdsAsync(
+  connection: BridgeConnection
+): Promise<Array<{ instanceId: string; placeId: number | undefined }>> {
+  return Promise.all(
+    connection.listInstances().map(async (instance) => ({
+      instanceId: instance.instanceId,
+      placeId: await tryGetPlaceIdAsync(connection, instance),
+    }))
+  );
+}
+
+/** A cloud place loads after the plugin registers, so a registered 0 is read again live. */
+async function tryGetPlaceIdAsync(
+  connection: BridgeConnection,
+  instance: InstanceInfo
+): Promise<number | undefined> {
+  if (instance.placeId) {
+    return instance.placeId;
+  }
+
+  const editSession = connection
+    .listSessions()
+    .find((s) => s.instanceId === instance.instanceId && s.context === 'edit');
+  const session = editSession && connection.getSession(editSession.sessionId);
+  if (!session) {
+    return undefined;
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const state = await Promise.race([
+      session.queryStateAsync(),
+      new Promise<undefined>((resolve) => {
+        timer = setTimeout(() => resolve(undefined), PLACE_ID_QUERY_TIMEOUT_MS);
+      }),
+    ]);
+    return state?.placeId;
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/index.ts

@@ -107,11 +107,16 @@ export {
   queryLogsHandlerAsync,
   captureScreenshotHandlerAsync,
   queryDataModelHandlerAsync,
+  exportInstancesHandlerAsync,
+  importInstancesHandlerAsync,
   execHandlerAsync,
   runHandlerAsync,
   launchHandlerAsync,
   connectHandlerAsync,
   disconnectHandler,
+  playtestStartHandlerAsync,
+  playtestStopHandlerAsync,
+  playtestRunHandlerAsync,
 } from './commands/index.js';
 
 export type {
@@ -130,6 +135,12 @@ export type {
   ConnectOptions,
   ConnectResult,
   DisconnectResult,
+  PlaytestStartOptions,
+  PlaytestStartResult,
+  PlaytestStopOptions,
+  PlaytestStopResult,
+  PlaytestRunOptions,
+  PlaytestRunResult,
 } from './commands/index.js';
 
 // Command option/result types that conflict with bridge types are aliased

package/src/plugin/persistent-plugin-installer.test.ts

@@ -43,6 +43,10 @@ vi.mock('../process/studio-process-manager.js', () => ({
   findPluginsFolder: vi.fn(() => '/mock/plugins/folder'),
 }));
 
+vi.mock('./plugin-build-version.js', () => ({
+  getPluginBuildVersionAsync: vi.fn().mockResolvedValue('abc123'),
+}));
+
 vi.mock('./plugin-discovery.js', () => ({
   getPersistentPluginPath: mockGetPersistentPluginPath,
 }));

package/src/plugin/persistent-plugin-installer.ts

@@ -12,6 +12,7 @@ import {
 } from '@quenty/nevermore-template-helpers';
 import { findPluginsFolder } from '../process/studio-process-manager.js';
 import { getPersistentPluginPath } from './plugin-discovery.js';
+import { getPluginBuildVersionAsync } from './plugin-build-version.js';
 
 const templateDir = resolveTemplatePath(
   import.meta.url,
@@ -39,7 +40,7 @@ export async function installPersistentPluginAsync(): Promise<string> {
     await TemplateHelper.createDirectoryContentsAsync(
       templateDir,
       buildContext.buildDir,
-      {},
+      { PLUGIN_VERSION: await getPluginBuildVersionAsync() },
       false
     );
 

package/src/plugin/plugin-build-version.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { hashTemplateDirAsync } from './plugin-build-version.js';
+
+describe('hashTemplateDirAsync', () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    for (const dir of dirs) {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+    dirs.length = 0;
+  });
+
+  async function makeTemplateAsync(
+    files: Record<string, string>
+  ): Promise<string> {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'sb-template-'));
+    dirs.push(dir);
+    for (const [name, contents] of Object.entries(files)) {
+      await fs.mkdir(path.dirname(path.join(dir, name)), { recursive: true });
+      await fs.writeFile(path.join(dir, name), contents);
+    }
+    return dir;
+  }
+
+  it('changes when plugin source changes', async () => {
+    const before = await makeTemplateAsync({ 'src/Plugin.lua': 'print(1)' });
+    const after = await makeTemplateAsync({ 'src/Plugin.lua': 'print(2)' });
+
+    expect(await hashTemplateDirAsync(before)).not.toBe(
+      await hashTemplateDirAsync(after)
+    );
+  });
+
+  it('ignores specs and line endings', async () => {
+    const plain = await makeTemplateAsync({ 'src/Plugin.lua': 'a\nb\n' });
+    const withSpec = await makeTemplateAsync({
+      'src/Plugin.lua': 'a\r\nb\r\n',
+      'src/Plugin.spec.lua': 'test',
+    });
+
+    expect(await hashTemplateDirAsync(plain)).toBe(
+      await hashTemplateDirAsync(withSpec)
+    );
+  });
+
+  it('is a short hex string', async () => {
+    const dir = await makeTemplateAsync({ 'src/Plugin.lua': 'print(1)' });
+
+    expect(await hashTemplateDirAsync(dir)).toMatch(/^[0-9a-f]{12}$/);
+  });
+});

package/src/plugin/plugin-build-version.ts

@@ -0,0 +1,53 @@
+/**
+ * The plugin reports a hash of the template it was built from as its
+ * `pluginVersion`, so the CLI can tell when the installed plugin is stale.
+ */
+
+import { createHash } from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { resolveTemplatePath } from '@quenty/nevermore-template-helpers';
+
+const templateDir = resolveTemplatePath(
+  import.meta.url,
+  'studio-bridge-plugin'
+);
+
+let cachedVersion: Promise<string> | undefined;
+
+export function getPluginBuildVersionAsync(): Promise<string> {
+  cachedVersion ??= hashTemplateDirAsync(templateDir);
+  return cachedVersion;
+}
+
+export async function hashTemplateDirAsync(dir: string): Promise<string> {
+  const files = await listTemplateFilesAsync(dir, dir);
+  files.sort();
+
+  const hash = createHash('sha256');
+  for (const relativePath of files) {
+    const contents = await fs.readFile(path.join(dir, relativePath), 'utf-8');
+    hash.update(relativePath.replace(/\\/g, '/'));
+    hash.update('\0');
+    hash.update(contents.replace(/\r\n/g, '\n'));
+    hash.update('\0');
+  }
+  return hash.digest('hex').slice(0, 12);
+}
+
+async function listTemplateFilesAsync(
+  baseDir: string,
+  currentDir: string
+): Promise<string[]> {
+  const entries = await fs.readdir(currentDir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await listTemplateFilesAsync(baseDir, fullPath)));
+    } else if (!entry.name.endsWith('.spec.lua')) {
+      files.push(path.relative(baseDir, fullPath));
+    }
+  }
+  return files;
+}

package/src/plugin/plugin-injector.ts

@@ -9,6 +9,7 @@ import {
   resolveTemplatePath,
 } from '@quenty/nevermore-template-helpers';
 import { findPluginsFolder } from '../process/studio-process-manager.js';
+import { getPluginBuildVersionAsync } from './plugin-build-version.js';
 
 const templateDir = resolveTemplatePath(
   import.meta.url,
@@ -43,7 +44,12 @@ export async function injectPluginAsync(
     await TemplateHelper.createDirectoryContentsAsync(
       templateDir,
       buildContext.buildDir,
-      { PORT: String(port), SESSION_ID: sessionId, EPHEMERAL: 'true' },
+      {
+        PORT: String(port),
+        SESSION_ID: sessionId,
+        EPHEMERAL: 'true',
+        PLUGIN_VERSION: await getPluginBuildVersionAsync(),
+      },
       false
     );
 

package/src/process/studio-process-closer.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest';
+import {
+  matchStudioProcesses,
+  parseMacProcessList,
+  parseWindowsProcessList,
+} from './studio-process-closer.js';
+
+describe('parseWindowsProcessList', () => {
+  it('parses a single process object', () => {
+    expect(
+      parseWindowsProcessList(
+        '{"Id":9792,"MainWindowTitle":"C:\\\\places\\\\test-place.rbxl - Roblox Studio"}'
+      )
+    ).toEqual([
+      { pid: 9792, windowTitle: 'C:\\places\\test-place.rbxl - Roblox Studio' },
+    ]);
+  });
+
+  it('parses an array and treats a null title as empty', () => {
+    expect(
+      parseWindowsProcessList(
+        '[{"Id":1,"MainWindowTitle":"Map - Roblox Studio"},{"Id":2,"MainWindowTitle":null}]'
+      )
+    ).toEqual([
+      { pid: 1, windowTitle: 'Map - Roblox Studio' },
+      { pid: 2, windowTitle: '' },
+    ]);
+  });
+
+  it('returns nothing when no Studio is running', () => {
+    expect(parseWindowsProcessList('')).toEqual([]);
+  });
+});
+
+describe('parseMacProcessList', () => {
+  it('keeps only Studio processes', () => {
+    const stdout = [
+      '  101 /Applications/RobloxStudio.app/Contents/MacOS/RobloxStudio /Users/me/test-place.rbxl',
+      '  102 /usr/bin/zsh',
+    ].join('\n');
+
+    expect(parseMacProcessList(stdout)).toEqual([
+      {
+        pid: 101,
+        windowTitle:
+          '/Applications/RobloxStudio.app/Contents/MacOS/RobloxStudio /Users/me/test-place.rbxl',
+        commandLine:
+          '/Applications/RobloxStudio.app/Contents/MacOS/RobloxStudio /Users/me/test-place.rbxl',
+      },
+    ]);
+  });
+});
+
+describe('matchStudioProcesses', () => {
+  const processes = [
+    { pid: 1, windowTitle: 'C:\\places\\test-place.rbxl - Roblox Studio' },
+    { pid: 2, windowTitle: 'Map - Roblox Studio' },
+    { pid: 3, windowTitle: 'Other Map - Roblox Studio' },
+    { pid: 4, windowTitle: '' },
+  ];
+
+  it('matches a local file by its path', () => {
+    expect(matchStudioProcesses(processes, 'test-place.rbxl')).toEqual([
+      processes[0],
+    ]);
+  });
+
+  it('matches a cloud place by the place id it was launched with', () => {
+    const cloud = [
+      {
+        pid: 5,
+        windowTitle: 'My Game (abc123) - Roblox Studio',
+        commandLine:
+          'RobloxStudioBeta.exe roblox-studio:1+launchmode:edit+task:EditPlace+placeId:123+universeId:9',
+      },
+      {
+        pid: 6,
+        windowTitle: 'Other - Roblox Studio',
+        commandLine: 'RobloxStudioBeta.exe roblox-studio:1+placeId:1234',
+      },
+    ];
+
+    expect(matchStudioProcesses(cloud, 'Place1', 123)).toEqual([cloud[0]]);
+    expect(matchStudioProcesses(cloud, 'Place1')).toEqual([]);
+  });
+
+  it('prefers a title match over a launch place id', () => {
+    const cloud = [
+      {
+        pid: 5,
+        windowTitle: 'Other - Roblox Studio',
+        commandLine: 'RobloxStudioBeta.exe roblox-studio:1+placeId:123',
+      },
+      { pid: 6, windowTitle: 'Map - Roblox Studio' },
+    ];
+
+    expect(matchStudioProcesses(cloud, 'Map', 123)).toEqual([cloud[1]]);
+  });
+
+  it('matches a cloud place by its exact name', () => {
+    expect(matchStudioProcesses(processes, 'Map')).toEqual([processes[1]]);
+  });
+
+  it('matches nothing for an unknown place', () => {
+    expect(matchStudioProcesses(processes, 'Missing')).toEqual([]);
+  });
+});