@quenty/studio-bridge 0.7.0 → 0.8.0

package/src/commands/linux/status/status.ts

@@ -0,0 +1,180 @@
+/**
+ * `linux status` — check the health of the Linux/Wine environment for
+ * running Studio.
+ */
+
+import * as fs from 'fs/promises';
+import { defineCommand } from '../../framework/define-command.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { checkLinuxEnvironmentAsync } from '../../../linux/linux-env-guard.js';
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+interface StatusArgs {}
+
+interface PrerequisiteStatus {
+  name: string;
+  available: boolean;
+  version?: string;
+  hint?: string;
+}
+
+interface StatusResult {
+  healthy: boolean;
+  prerequisites: PrerequisiteStatus[];
+  display: { xvfb: boolean; openbox: boolean };
+  studio: {
+    installed: boolean;
+    version?: string;
+    fflags: boolean;
+    shaders: boolean;
+  };
+  auth: { writeCredExe: boolean; credentialsInjected: boolean };
+}
+
+async function fileExistsAsync(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function statusHandlerAsync(
+  _args: StatusArgs
+): Promise<StatusResult> {
+  try {
+    const envError = await checkLinuxEnvironmentAsync();
+    if (envError) {
+      OutputHelper.error(envError);
+      process.exit(1);
+    }
+
+    const linux = await import('../../../linux/index.js');
+    const config = linux.resolveLinuxConfig();
+    let allOk = true;
+
+    // 1. Prerequisites
+    OutputHelper.info('System prerequisites:');
+    const prereqs = linux.checkPrerequisites();
+    for (const p of prereqs) {
+      const status = p.available
+        ? `  OK  ${p.name}${p.version ? ` (${p.version})` : ''}`
+        : `  MISSING  ${p.name} — ${p.hint}`;
+      if (p.available) {
+        OutputHelper.info(status);
+      } else {
+        OutputHelper.error(status);
+        allOk = false;
+      }
+    }
+
+    // 2. Display
+    const displayNum = config.display.replace(':', '');
+    const xvfbOk = linux.isXvfbRunning(displayNum);
+    const openboxOk = linux.isOpenboxRunning();
+    OutputHelper.info('');
+    OutputHelper.info('Display:');
+    OutputHelper.info(
+      `  Xvfb (${config.display}): ${xvfbOk ? 'running' : 'not running'}`
+    );
+    OutputHelper.info(`  openbox: ${openboxOk ? 'running' : 'not running'}`);
+    if (!xvfbOk || !openboxOk) allOk = false;
+
+    // 3. Studio installation
+    OutputHelper.info('');
+    OutputHelper.info('Studio installation:');
+    const studioExists = await fileExistsAsync(config.studioExe);
+    OutputHelper.info(
+      `  ${config.studioDir}: ${studioExists ? 'installed' : 'not found'}`
+    );
+    if (!studioExists) allOk = false;
+
+    const { readInstalledVersionAsync } = await import(
+      '../../../linux/linux-version-resolver.js'
+    );
+    const version = await readInstalledVersionAsync(config.studioDir);
+    if (version) {
+      OutputHelper.info(`  Version: ${version}`);
+    }
+
+    // 4. FFlags
+    const fflagsExist = await fileExistsAsync(config.clientSettingsPath);
+    OutputHelper.info(`  FFlags: ${fflagsExist ? 'configured' : 'not found'}`);
+
+    // 5. Shaders
+    const shadersExist = await fileExistsAsync(
+      `${config.shadersDir}/shaders_glsl3.pack`
+    );
+    OutputHelper.info(`  Shaders: ${shadersExist ? 'present' : 'not found'}`);
+
+    // 6. Credentials
+    OutputHelper.info('');
+    OutputHelper.info('Authentication:');
+    const writeCredExists = await fileExistsAsync(config.writeCredExe);
+    OutputHelper.info(
+      `  write-cred.exe: ${writeCredExists ? 'compiled' : 'not found'}`
+    );
+
+    // Check Wine registry for credential entries
+    let credentialsInjected = false;
+    const wineRegPath = `${config.winePrefix}/user.reg`;
+    const wineRegExists = await fileExistsAsync(wineRegPath);
+    if (wineRegExists) {
+      const regContent = await fs.readFile(wineRegPath, 'utf-8');
+      credentialsInjected = regContent.includes('RobloxStudioAuth');
+      OutputHelper.info(
+        `  Wine credentials: ${
+          credentialsInjected ? 'present' : 'not injected'
+        }`
+      );
+      if (!credentialsInjected) allOk = false;
+    } else {
+      OutputHelper.info('  Wine prefix: not initialized');
+      allOk = false;
+    }
+
+    // Summary
+    OutputHelper.info('');
+    if (allOk) {
+      OutputHelper.info('Environment is ready for Studio.');
+    } else {
+      OutputHelper.warn('Environment has issues. See above for details.');
+    }
+
+    return {
+      healthy: allOk,
+      prerequisites: prereqs,
+      display: { xvfb: xvfbOk, openbox: openboxOk },
+      studio: {
+        installed: studioExists,
+        version: version ?? undefined,
+        fflags: fflagsExist,
+        shaders: shadersExist,
+      },
+      auth: { writeCredExe: writeCredExists, credentialsInjected },
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    OutputHelper.error(message);
+    return {
+      healthy: false,
+      prerequisites: [],
+      display: { xvfb: false, openbox: false },
+      studio: { installed: false, fflags: false, shaders: false },
+      auth: { writeCredExe: false, credentialsInjected: false },
+    };
+  }
+}
+
+export const linuxStatusCommand = defineCommand<StatusArgs, StatusResult>({
+  group: 'linux',
+  name: 'status',
+  description:
+    'Check Linux/Wine environment health for Studio (within Docker image or Linux with Wine)',
+  category: 'infrastructure',
+  safety: 'none',
+  scope: 'standalone',
+  args: {},
+  handler: async (args) => statusHandlerAsync(args),
+});

package/src/commands/plugin/install/install.ts

@@ -0,0 +1,31 @@
+/**
+ * `plugin install` — install the persistent Studio Bridge plugin.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { installPersistentPluginAsync } from '../../../plugin/persistent-plugin-installer.js';
+
+export interface InstallPluginResult {
+  path: string;
+  summary: string;
+}
+
+export async function installPluginHandlerAsync(): Promise<InstallPluginResult> {
+  const installedPath = await installPersistentPluginAsync();
+
+  return {
+    path: installedPath,
+    summary: `Persistent plugin installed to ${installedPath}`,
+  };
+}
+
+export const installCommand = defineCommand({
+  group: 'plugin',
+  name: 'install',
+  description: 'Install the persistent Studio Bridge plugin',
+  category: 'infrastructure',
+  safety: 'none',
+  scope: 'standalone',
+  args: {},
+  handler: async () => installPluginHandlerAsync(),
+});

package/src/commands/plugin/uninstall/uninstall.ts

@@ -0,0 +1,54 @@
+/**
+ * `plugin uninstall` — remove the persistent Studio Bridge plugin.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import {
+  getPersistentPluginPath,
+  isPersistentPluginInstalled,
+} from '../../../plugin/plugin-discovery.js';
+import { uninstallPersistentPluginAsync } from '../../../plugin/persistent-plugin-installer.js';
+
+export interface UninstallPluginResult {
+  summary: string;
+}
+
+export async function uninstallPluginHandlerAsync(): Promise<UninstallPluginResult> {
+  const pluginPath = getPersistentPluginPath();
+
+  // Check first for a clean UX message, but rely on uninstallPersistentPluginAsync's
+  // ENOENT handling for the authoritative outcome (avoids TOCTOU between this
+  // check and the actual unlink).
+  if (!isPersistentPluginInstalled()) {
+    return {
+      summary: 'Persistent plugin is not installed. Nothing to remove.',
+    };
+  }
+
+  try {
+    await uninstallPersistentPluginAsync();
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      err.message.startsWith('Persistent plugin is not installed')
+    ) {
+      return { summary: err.message };
+    }
+    throw err;
+  }
+
+  return {
+    summary: `Persistent plugin removed from ${pluginPath}`,
+  };
+}
+
+export const uninstallCommand = defineCommand({
+  group: 'plugin',
+  name: 'uninstall',
+  description: 'Remove the persistent Studio Bridge plugin',
+  category: 'infrastructure',
+  safety: 'none',
+  scope: 'standalone',
+  args: {},
+  handler: async () => uninstallPluginHandlerAsync(),
+});

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

@@ -0,0 +1,52 @@
+/**
+ * `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.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+
+export interface ProcessCloseResult {
+  success: boolean;
+  sessionId: string;
+  summary: string;
+}
+
+interface ProcessCloseArgs {
+  force?: boolean;
+}
+
+export async function processCloseHandlerAsync(
+  session: BridgeSession
+): Promise<ProcessCloseResult> {
+  return {
+    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.`,
+  };
+}
+
+export const processCloseCommand = defineCommand<
+  ProcessCloseArgs,
+  ProcessCloseResult
+>({
+  group: 'process',
+  name: 'close',
+  description: 'Kill a Studio process (not yet implemented)',
+  category: 'infrastructure',
+  safety: 'mutate',
+  scope: 'session',
+  args: {
+    force: arg.flag({
+      description: 'Force shutdown without confirmation',
+      alias: 'f',
+    }),
+  },
+  handler: async (session) => processCloseHandlerAsync(session),
+});

package/src/commands/process/format-state.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared coloring helper for StudioState values, used by `process list`
+ * and `process info`.
+ */
+
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import type { StudioState } from '../../server/web-socket-protocol.js';
+
+export function colorizeState(state: StudioState): string {
+  switch (state) {
+    case 'Edit':
+      return OutputHelper.formatInfo(state);
+    case 'Play':
+    case 'Run':
+      return OutputHelper.formatSuccess(state);
+    case 'Paused':
+      return OutputHelper.formatWarning(state);
+    default:
+      return state;
+  }
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Unit tests for the info (state) command handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { queryStateHandlerAsync } from './info.js';
+
+function createMockSession(stateResult: {
+  state: string;
+  placeId: number;
+  placeName: string;
+  gameId: number;
+}) {
+  return {
+    queryStateAsync: vi.fn().mockResolvedValue(stateResult),
+  } as any;
+}
+
+describe('queryStateHandlerAsync', () => {
+  it('returns state result with summary', async () => {
+    const session = createMockSession({
+      state: 'Edit',
+      placeId: 12345,
+      placeName: 'TestPlace',
+      gameId: 67890,
+    });
+
+    const result = await queryStateHandlerAsync(session);
+
+    expect(result.state).toBe('Edit');
+    expect(result.placeId).toBe(12345);
+    expect(result.placeName).toBe('TestPlace');
+    expect(result.gameId).toBe(67890);
+    expect(result.summary).toContain('Edit');
+    expect(result.summary).toContain('TestPlace');
+    expect(result.summary).toContain('12345');
+  });
+
+  it('calls session.queryStateAsync', async () => {
+    const session = createMockSession({
+      state: 'Play',
+      placeId: 100,
+      placeName: 'GamePlace',
+      gameId: 200,
+    });
+
+    await queryStateHandlerAsync(session);
+
+    expect(session.queryStateAsync).toHaveBeenCalledOnce();
+  });
+
+  it('handles different state values correctly', async () => {
+    for (const state of ['Edit', 'Play', 'Paused', 'Run', 'Server', 'Client']) {
+      const session = createMockSession({
+        state,
+        placeId: 1,
+        placeName: 'Place',
+        gameId: 2,
+      });
+
+      const result = await queryStateHandlerAsync(session);
+      expect(result.state).toBe(state);
+      expect(result.summary).toContain(state);
+    }
+  });
+
+  it('propagates errors from session', async () => {
+    const session = {
+      queryStateAsync: vi.fn().mockRejectedValue(new Error('Connection lost')),
+    } as any;
+
+    await expect(queryStateHandlerAsync(session)).rejects.toThrow(
+      'Connection lost'
+    );
+  });
+});

package/src/commands/process/info/info.ts

@@ -0,0 +1,54 @@
+/**
+ * `process info` — query the current Studio state (mode, place info)
+ * from a connected session.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import type { BridgeSession } from '../../../bridge/index.js';
+import type { StudioState } from '../../../bridge/index.js';
+import { colorizeState } from '../format-state.js';
+
+export interface StateResult {
+  state: StudioState;
+  placeId: number;
+  placeName: string;
+  gameId: number;
+  summary: string;
+}
+
+export async function queryStateHandlerAsync(
+  session: BridgeSession
+): Promise<StateResult> {
+  const result = await session.queryStateAsync();
+
+  return {
+    state: result.state,
+    placeId: result.placeId,
+    placeName: result.placeName,
+    gameId: result.gameId,
+    summary: `Mode: ${result.state}, Place: ${result.placeName} (${result.placeId})`,
+  };
+}
+
+export function formatStateText(result: StateResult): string {
+  return [
+    `Mode:    ${colorizeState(result.state)}`,
+    `Place:   ${result.placeName}`,
+    `PlaceId: ${result.placeId}`,
+    `GameId:  ${result.gameId}`,
+  ].join('\n');
+}
+
+export const infoCommand = defineCommand({
+  group: 'process',
+  name: 'info',
+  description: 'Query the current Studio state (mode, place info)',
+  category: 'execution',
+  safety: 'read',
+  scope: 'session',
+  args: {},
+  cli: {
+    format: formatStateText,
+  },
+  handler: async (session) => queryStateHandlerAsync(session),
+});

package/src/commands/process/info/query-state.luau

@@ -0,0 +1,48 @@
+--[[
+	QueryState action handler for the studio-bridge plugin.
+
+	Returns the current Studio run mode, place name, place ID, and game ID.
+
+	Protocol:
+	  Request:  { type: "queryState", payload: {} }
+	  Response: { type: "stateResult", payload: { state, placeName, placeId, gameId } }
+]]
+
+local RunService = game:GetService("RunService")
+
+local QueryStateAction = {}
+
+-- ---------------------------------------------------------------------------
+-- State detection
+-- ---------------------------------------------------------------------------
+
+local function detectState(): string
+	if RunService:IsRunning() then
+		if RunService:IsClient() and not RunService:IsServer() then
+			return "Client"
+		elseif RunService:IsServer() and not RunService:IsClient() then
+			return "Server"
+		else
+			return "Play"
+		end
+	end
+	return "Edit"
+end
+
+-- ---------------------------------------------------------------------------
+-- Public API
+-- ---------------------------------------------------------------------------
+
+function QueryStateAction.register(router: any)
+	router:setResponseType("queryState", "stateResult")
+	router:register("queryState", function(_payload: { [string]: any }, _requestId: string, _sessionId: string)
+		return {
+			state = detectState(),
+			placeName = game.Name or "Unknown",
+			placeId = game.PlaceId,
+			gameId = game.GameId,
+		}
+	end)
+end
+
+return QueryStateAction

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

@@ -0,0 +1,65 @@
+/**
+ * Unit tests for the launch command handler.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+// Mock the process manager before importing the handler
+vi.mock('../../../process/studio-process-manager.js', () => ({
+  launchStudioAsync: vi.fn().mockResolvedValue({
+    process: {},
+    killAsync: vi.fn(),
+  }),
+}));
+
+import { launchHandlerAsync } from './launch.js';
+import { launchStudioAsync } from '../../../process/studio-process-manager.js';
+
+describe('launchHandlerAsync', () => {
+  it('calls launchStudioAsync and returns result', async () => {
+    const result = await launchHandlerAsync();
+
+    expect(launchStudioAsync).toHaveBeenCalled();
+    expect(result.launched).toBe(true);
+    expect(result.summary).toBe('Studio launched');
+  });
+
+  it('passes place path to launchStudioAsync', async () => {
+    const result = await launchHandlerAsync({
+      placePath: '/tmp/game.rbxl',
+    });
+
+    expect(launchStudioAsync).toHaveBeenCalledWith('/tmp/game.rbxl');
+    expect(result.launched).toBe(true);
+    expect(result.summary).toBe('Studio launched with /tmp/game.rbxl');
+  });
+
+  it('passes empty string when no place path', async () => {
+    await launchHandlerAsync({});
+
+    expect(launchStudioAsync).toHaveBeenCalledWith('');
+  });
+
+  it('returns correct summary without place path', async () => {
+    const result = await launchHandlerAsync({});
+
+    expect(result.summary).toBe('Studio launched');
+  });
+
+  it('propagates errors from launchStudioAsync', async () => {
+    vi.mocked(launchStudioAsync).mockRejectedValueOnce(
+      new Error('Studio not found')
+    );
+
+    await expect(launchHandlerAsync()).rejects.toThrow('Studio not found');
+  });
+
+  it('result shape matches LaunchResult interface', async () => {
+    const result = await launchHandlerAsync();
+
+    expect(result).toHaveProperty('launched');
+    expect(result).toHaveProperty('summary');
+    expect(typeof result.launched).toBe('boolean');
+    expect(typeof result.summary).toBe('string');
+  });
+});

package/src/commands/process/launch/launch.ts

@@ -0,0 +1,45 @@
+/**
+ * `process launch` — launch Roblox Studio, optionally with a place file.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { launchStudioAsync } from '../../../process/studio-process-manager.js';
+
+export interface LaunchOptions {
+  placePath?: string;
+}
+
+export interface LaunchResult {
+  launched: boolean;
+  summary: string;
+}
+
+export async function launchHandlerAsync(
+  options: LaunchOptions = {}
+): Promise<LaunchResult> {
+  await launchStudioAsync(options.placePath ?? '');
+  return {
+    launched: true,
+    summary: `Studio launched${
+      options.placePath ? ` with ${options.placePath}` : ''
+    }`,
+  };
+}
+
+interface LaunchArgs {
+  place?: string;
+}
+
+export const launchCommand = defineCommand<LaunchArgs, LaunchResult>({
+  group: 'process',
+  name: 'launch',
+  description: 'Launch Roblox Studio',
+  category: 'infrastructure',
+  safety: 'none',
+  scope: 'standalone',
+  args: {
+    place: arg.option({ description: 'Path to a .rbxl place file' }),
+  },
+  handler: async (args) => launchHandlerAsync({ placePath: args.place }),
+});