@quenty/studio-bridge 0.21.1 → 0.22.0

package/src/commands/process/close/close.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('../../../process/studio-process-closer.js', async (importOriginal) => {
+  const actual = await importOriginal<
+    typeof import('../../../process/studio-process-closer.js')
+  >();
+  return {
+    ...actual,
+    listStudioProcessesAsync: vi.fn(),
+    closeStudioProcessAsync: vi.fn(),
+  };
+});
+
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { closeDeployTargetAsync, processCloseHandlerAsync } from './close.js';
+import {
+  closeStudioProcessAsync,
+  listStudioProcessesAsync,
+} from '../../../process/studio-process-closer.js';
+
+const queryStateAsync = async () => ({ placeId: 0 });
+
+const session = {
+  info: { sessionId: 'test-place-edit', placeName: 'test-place.rbxl' },
+  queryStateAsync,
+} as any;
+
+describe('processCloseHandlerAsync', () => {
+  beforeEach(() => {
+    vi.mocked(listStudioProcessesAsync).mockResolvedValue([
+      { pid: 10, windowTitle: 'C:\\places\\test-place.rbxl - Roblox Studio' },
+      { pid: 20, windowTitle: 'Other - Roblox Studio' },
+    ]);
+    vi.mocked(closeStudioProcessAsync).mockReset().mockResolvedValue(true);
+  });
+
+  it('closes the Studio window showing the session place', async () => {
+    const result = await processCloseHandlerAsync(session);
+
+    expect(closeStudioProcessAsync).toHaveBeenCalledWith(10, {
+      force: undefined,
+    });
+    expect(result).toMatchObject({ success: true, pid: 10 });
+  });
+
+  it('closes the Studio a single-process playtest runs in', async () => {
+    const server = {
+      info: {
+        sessionId: 'test-place-server',
+        instanceId: 'test-place',
+        context: 'server',
+        placeName: 'Game',
+      },
+      queryStateAsync,
+    } as any;
+    const connection = {
+      listSessions: () => [
+        {
+          sessionId: 'test-place-server',
+          instanceId: 'test-place',
+          context: 'server',
+          placeName: 'test-place.rbxl',
+        },
+      ],
+    } as any;
+
+    const result = await processCloseHandlerAsync(server, {}, connection);
+
+    expect(result).toMatchObject({ success: true, pid: 10 });
+  });
+
+  it('refuses a multiplayer test process without --pid', async () => {
+    const client = {
+      info: {
+        sessionId: 'test-place-client-player1',
+        instanceId: 'test-place',
+        context: 'client',
+        placeName: 'Game',
+      },
+      queryStateAsync,
+    } as any;
+    const connection = {
+      listSessions: () =>
+        ['player1', 'player2'].map((player) => ({
+          sessionId: `test-place-client-${player}`,
+          instanceId: 'test-place',
+          context: 'client',
+          placeName: 'test-place.rbxl',
+          playerName: player,
+        })),
+    } as any;
+
+    const result = await processCloseHandlerAsync(client, {}, connection);
+
+    expect(result.success).toBe(false);
+    expect(result.summary).toContain("'studio-bridge playtest stop'");
+    expect(closeStudioProcessAsync).not.toHaveBeenCalled();
+  });
+
+  it('finds a cloud place by the place id Studio was launched with', async () => {
+    vi.mocked(listStudioProcessesAsync).mockResolvedValue([
+      {
+        pid: 30,
+        windowTitle: 'My Game (abc123) - Roblox Studio',
+        commandLine:
+          'RobloxStudioBeta.exe roblox-studio:1+placeId:555+universeId:9',
+      },
+    ]);
+    const cloudSession = {
+      info: { sessionId: 'place1-edit', placeName: 'Place1', placeId: 0 },
+      queryStateAsync: async () => ({ placeId: 555 }),
+    } as any;
+
+    const result = await processCloseHandlerAsync(cloudSession);
+
+    expect(result).toMatchObject({ success: true, pid: 30 });
+  });
+
+  it('passes --force through', async () => {
+    await processCloseHandlerAsync(session, { force: true });
+
+    expect(closeStudioProcessAsync).toHaveBeenCalledWith(10, { force: true });
+  });
+
+  it('suggests --force when Studio stays open', async () => {
+    vi.mocked(closeStudioProcessAsync).mockResolvedValue(false);
+
+    const result = await processCloseHandlerAsync(session);
+
+    expect(result.success).toBe(false);
+    expect(result.summary).toContain('--force');
+  });
+
+  it('fails without closing when no window shows the place', async () => {
+    vi.mocked(listStudioProcessesAsync).mockResolvedValue([
+      { pid: 20, windowTitle: 'Other - Roblox Studio' },
+    ]);
+
+    const result = await processCloseHandlerAsync(session);
+
+    expect(result.success).toBe(false);
+    expect(closeStudioProcessAsync).not.toHaveBeenCalled();
+  });
+
+  it('asks for --pid when several windows show the place', async () => {
+    vi.mocked(listStudioProcessesAsync).mockResolvedValue([
+      { pid: 10, windowTitle: 'C:\\a\\test-place.rbxl - Roblox Studio' },
+      { pid: 11, windowTitle: 'C:\\b\\test-place.rbxl - Roblox Studio' },
+    ]);
+
+    const result = await processCloseHandlerAsync(session);
+
+    expect(result.success).toBe(false);
+    expect(result.summary).toContain('--pid');
+    expect(closeStudioProcessAsync).not.toHaveBeenCalled();
+  });
+
+  it('closes the process picked with --pid', async () => {
+    const result = await processCloseHandlerAsync(session, { pid: 20 });
+
+    expect(closeStudioProcessAsync).toHaveBeenCalledWith(20, {
+      force: undefined,
+    });
+    expect(result.success).toBe(true);
+  });
+});
+
+describe('closeDeployTargetAsync', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'close-test-'));
+    await fs.writeFile(
+      path.join(tempDir, 'deploy.nevermore.json'),
+      JSON.stringify({
+        targets: {
+          test: { universeId: 9, placeId: 555, project: 'test.project.json' },
+        },
+      })
+    );
+    vi.mocked(closeStudioProcessAsync).mockReset().mockResolvedValue(true);
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('closes a Studio launched with the target place, connected or not', async () => {
+    vi.mocked(listStudioProcessesAsync).mockResolvedValue([
+      {
+        pid: 40,
+        windowTitle: 'My Game (abc123) - Roblox Studio',
+        commandLine: 'RobloxStudioBeta.exe roblox-studio:1+placeId:555',
+      },
+      { pid: 41, windowTitle: 'Other - Roblox Studio' },
+    ]);
+    const connection = { listInstances: () => [], listSessions: () => [] };
+
+    const result = await closeDeployTargetAsync(
+      connection as any,
+      'test',
+      {},
+      tempDir
+    );
+
+    expect(closeStudioProcessAsync).toHaveBeenCalledWith(40, {
+      force: undefined,
+    });
+    expect(result).toMatchObject({
+      success: true,
+      deployTarget: 'test',
+      pid: 40,
+    });
+  });
+
+  it('closes the connected Studio showing the target place', async () => {
+    vi.mocked(listStudioProcessesAsync).mockResolvedValue([
+      { pid: 50, windowTitle: 'My Game (abc123) - Roblox Studio' },
+    ]);
+    const editSession = {
+      info: {
+        sessionId: 'place1-1a2b-edit',
+        instanceId: 'place1-1a2b',
+        context: 'edit',
+        placeName: 'My Game (abc123)',
+      },
+      queryStateAsync: async () => ({ placeId: 555 }),
+    };
+    const connection = {
+      listInstances: () => [{ instanceId: 'place1-1a2b', placeId: 555 }],
+      listSessions: () => [editSession.info],
+      resolveSessionAsync: vi.fn().mockResolvedValue(editSession),
+    };
+
+    const result = await closeDeployTargetAsync(
+      connection as any,
+      'test',
+      {},
+      tempDir
+    );
+
+    expect(connection.resolveSessionAsync).toHaveBeenCalledWith(
+      'place1-1a2b',
+      'edit'
+    );
+    expect(result).toMatchObject({ success: true, pid: 50 });
+  });
+});

package/src/commands/process/close/close.ts

@@ -1,34 +1,178 @@
 /**
- * `process close` -- kill a Studio process (not yet implemented).
- *
- * Closing a Studio process requires matching a bridge session to an OS
- * process, which is non-trivial: the Roblox plugin API doesn't expose
- * the process ID, so the bridge would need to scan and heuristically
- * match OS processes. This command is stubbed until that infrastructure
- * exists.
+ * `process close` — close the Studio process a session belongs to, or the
+ * Studio showing a `deploy.nevermore.json` target's place.
  */
 
 import { defineCommand } from '../../framework/define-command.js';
 import { arg } from '../../framework/arg-builder.js';
-import type { BridgeSession } from '../../../bridge/index.js';
+import type { BridgeConnection, BridgeSession } from '../../../bridge/index.js';
+import {
+  closeStudioProcessAsync,
+  listStudioProcessesAsync,
+  matchStudioProcesses,
+  matchStudioProcessesByPlaceId,
+  type RunningStudioProcess,
+} from '../../../process/studio-process-closer.js';
+import {
+  findInstancesShowingPlaceAsync,
+  resolveDeployPlaceAsync,
+} from '../../../deploy/deploy-places.js';
+import { explainMissingPlaytestContextAsync } from '../../playtest/playtest-sessions.js';
+import { describePlaytest } from '../info/info.js';
 
 export interface ProcessCloseResult {
   success: boolean;
-  sessionId: string;
+  sessionId?: string;
+  /** The `deploy.nevermore.json` target whose Studio was closed, if one was named. */
+  deployTarget?: string;
+  pid?: number;
   summary: string;
 }
 
+export interface ProcessCloseOptions {
+  force?: boolean;
+  pid?: number;
+}
+
 interface ProcessCloseArgs {
+  deployTarget?: string;
   force?: boolean;
+  pid?: number;
 }
 
 export async function processCloseHandlerAsync(
-  session: BridgeSession
+  session: BridgeSession,
+  options: ProcessCloseOptions = {},
+  connection?: BridgeConnection
 ): Promise<ProcessCloseResult> {
-  return {
+  const { sessionId, instanceId, context } = session.info;
+  const sessions = connection?.listSessions() ?? [];
+  // Listed sessions carry the edit session's place name for a playtest
+  const placeName =
+    sessions.find((s) => s.sessionId === sessionId)?.placeName ||
+    session.info.placeName;
+
+  const isMultiplayerProcess =
+    context !== 'edit' &&
+    describePlaytest(sessions, instanceId)?.playerCount !== undefined;
+  if (isMultiplayerProcess && options.pid === undefined) {
+    return {
+      success: false,
+      sessionId,
+      summary: `'${sessionId}' runs in its own process of a multiplayer test. End the test with 'studio-bridge playtest stop', remove a player with 'studio-bridge playtest player remove', or pass --pid.`,
+    };
+  }
+
+  const processes = await listStudioProcessesAsync();
+  let candidates =
+    options.pid !== undefined
+      ? processes.filter((proc) => proc.pid === options.pid)
+      : matchStudioProcesses(processes, placeName);
+  if (candidates.length === 0 && options.pid === undefined) {
+    // A cloud place loads after the plugin registers, so its registered id can be 0
+    const placeId = (await session.queryStateAsync().catch(() => undefined))
+      ?.placeId;
+    candidates = matchStudioProcesses(processes, placeName, placeId);
+  }
+
+  return closeCandidateAsync(candidates, `'${placeName}'`, options, {
+    sessionId,
+  });
+}
+
+/**
+ * Close the Studio showing a target's place from the nearest
+ * `deploy.nevermore.json`: a connected one, or else one launched with it.
+ */
+export async function closeDeployTargetAsync(
+  connection: BridgeConnection,
+  deployTarget: string,
+  options: ProcessCloseOptions = {},
+  cwd = process.cwd()
+): Promise<ProcessCloseResult> {
+  const deployPlace = await resolveDeployPlaceAsync(cwd, deployTarget);
+  if (!deployPlace) {
+    throw new Error(`Target '${deployTarget}' not found`);
+  }
+  const { placeId } = deployPlace.place;
+  const showing = `'${deployPlace.selector}' (place ${placeId})`;
+  const base = { deployTarget: deployPlace.selector };
+
+  const instanceIds = await findInstancesShowingPlaceAsync(connection, placeId);
+  if (instanceIds.length > 1) {
+    return {
+      ...base,
+      success: false,
+      summary: `${
+        instanceIds.length
+      } Studios have ${showing} open (${instanceIds.join(
+        ', '
+      )}). Pick one with --target.`,
+    };
+  }
+  if (instanceIds.length === 1) {
+    const session = await connection.resolveSessionAsync(
+      instanceIds[0],
+      'edit'
+    );
+    return {
+      ...(await processCloseHandlerAsync(session, options, connection)),
+      ...base,
+    };
+  }
+
+  const processes = await listStudioProcessesAsync();
+  const candidates =
+    options.pid !== undefined
+      ? processes.filter((proc) => proc.pid === options.pid)
+      : matchStudioProcessesByPlaceId(processes, placeId);
+  return closeCandidateAsync(candidates, showing, options, base);
+}
+
+async function closeCandidateAsync(
+  candidates: RunningStudioProcess[],
+  showing: string,
+  options: ProcessCloseOptions,
+  base: Pick<ProcessCloseResult, 'sessionId' | 'deployTarget'>
+): Promise<ProcessCloseResult> {
+  const fail = (summary: string, pid?: number): ProcessCloseResult => ({
+    ...base,
     success: false,
-    sessionId: session.info.sessionId,
-    summary: `process close is not yet implemented. Closing a Studio process requires OS process scanning which has not been built yet.`,
+    pid,
+    summary,
+  });
+
+  if (candidates.length === 0) {
+    return fail(
+      options.pid !== undefined
+        ? `No Studio process with pid ${options.pid}`
+        : `No Studio window is showing ${showing}`
+    );
+  }
+
+  if (candidates.length > 1) {
+    const pids = candidates.map((proc) => proc.pid).join(', ');
+    return fail(
+      `${candidates.length} Studio windows are showing ${showing} (pids ${pids}). Pick one with --pid.`
+    );
+  }
+
+  const { pid } = candidates[0];
+  const exited = await closeStudioProcessAsync(pid, { force: options.force });
+  if (!exited) {
+    return fail(
+      options.force
+        ? `Studio (pid ${pid}) did not exit`
+        : `Studio (pid ${pid}) is still open, likely asking to save. Use --force to close without saving.`,
+      pid
+    );
+  }
+
+  return {
+    ...base,
+    success: true,
+    pid,
+    summary: `Closed Studio (pid ${pid}) showing ${showing}`,
   };
 }
 
@@ -38,15 +182,37 @@ export const processCloseCommand = defineCommand<
 >({
   group: 'process',
   name: 'close',
-  description: 'Kill a Studio process (not yet implemented)',
+  description:
+    "Close a Studio: the one a session belongs to, or the one showing a deploy.nevermore.json target's place",
   category: 'infrastructure',
   safety: 'mutate',
-  scope: 'session',
+  scope: 'connection',
   args: {
+    deployTarget: arg.positional({
+      description:
+        'deploy.nevermore.json target whose Studio to close, e.g. test or integration.places.hub',
+      required: false,
+    }),
     force: arg.flag({
-      description: 'Force shutdown without confirmation',
+      description: 'Kill Studio without letting it prompt to save',
       alias: 'f',
     }),
+    pid: arg.option({
+      description: 'Studio process id, when several windows show the place',
+      type: 'number',
+    }),
+  },
+  handler: async (connection, args, targeting) => {
+    const options = { force: args.force, pid: args.pid };
+    if (args.deployTarget !== undefined) {
+      return closeDeployTargetAsync(connection, args.deployTarget, options);
+    }
+
+    const session = await connection
+      .resolveSessionAsync(targeting.target, targeting.context)
+      .catch(async (err: unknown) => {
+        throw await explainMissingPlaytestContextAsync(connection, err);
+      });
+    return processCloseHandlerAsync(session, options, connection);
   },
-  handler: async (session) => processCloseHandlerAsync(session),
 });