@quenty/studio-bridge 0.7.1 → 0.9.0

package/src/commands/framework/command-registry.ts

@@ -0,0 +1,51 @@
+/**
+ * Command registry — collects `CommandDefinition` objects and provides
+ * lookup by group, name, category, and scope.
+ */
+
+import type { CommandDefinition, CommandCategory } from './define-command.js';
+
+export class CommandRegistry {
+  private _commands: CommandDefinition[] = [];
+
+  /** Register a command definition. */
+  register(def: CommandDefinition): void {
+    this._commands.push(def);
+  }
+
+  /** Return all registered commands in insertion order. */
+  getAll(): readonly CommandDefinition[] {
+    return this._commands;
+  }
+
+  /** Return commands belonging to a specific group. */
+  getByGroup(group: string): readonly CommandDefinition[] {
+    return this._commands.filter((d) => d.group === group);
+  }
+
+  /** Return unique group names (excluding top-level commands). */
+  getGroups(): string[] {
+    const groups = new Set<string>();
+    for (const cmd of this._commands) {
+      if (cmd.group !== null) {
+        groups.add(cmd.group);
+      }
+    }
+    return [...groups];
+  }
+
+  /** Return top-level commands (group is `null`). */
+  getTopLevel(): readonly CommandDefinition[] {
+    return this._commands.filter((d) => d.group === null);
+  }
+
+  /** Return commands in a given category. */
+  getByCategory(category: CommandCategory): readonly CommandDefinition[] {
+    return this._commands.filter((d) => d.category === category);
+  }
+
+  /** Find a specific command by group and name. */
+  get(group: string | null, name: string): CommandDefinition | undefined {
+    return this._commands.find((d) => d.group === group && d.name === name);
+  }
+}

package/src/commands/framework/define-command.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Unit tests for the defineCommand factory and isCommandDefinition guard.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  COMMAND_BRAND,
+  defineCommand,
+  isCommandDefinition,
+} from './define-command.js';
+import { arg } from './arg-builder.js';
+
+function sessionCommand() {
+  return defineCommand({
+    group: 'console',
+    name: 'exec',
+    description: 'Execute inline Luau code',
+    category: 'execution',
+    safety: 'mutate',
+    scope: 'session',
+    args: {
+      code: arg.positional({ description: 'Luau source code' }),
+    },
+    handler: async (_session, _args) => ({ success: true }),
+  });
+}
+
+function connectionCommand() {
+  return defineCommand({
+    group: 'process',
+    name: 'list',
+    description: 'List connected sessions',
+    category: 'infrastructure',
+    safety: 'read',
+    scope: 'connection',
+    args: {},
+    handler: async (_connection) => ({ sessions: [] }),
+  });
+}
+
+function standaloneCommand() {
+  return defineCommand({
+    group: null,
+    name: 'serve',
+    description: 'Start the bridge server',
+    category: 'infrastructure',
+    safety: 'none',
+    scope: 'standalone',
+    args: {},
+    handler: async () => ({ port: 38741 }),
+  });
+}
+
+describe('defineCommand', () => {
+  it('stamps brand symbol on session command', () => {
+    const cmd = sessionCommand();
+    expect(cmd[COMMAND_BRAND]).toBe(true);
+  });
+
+  it('stamps brand symbol on connection command', () => {
+    const cmd = connectionCommand();
+    expect(cmd[COMMAND_BRAND]).toBe(true);
+  });
+
+  it('stamps brand symbol on standalone command', () => {
+    const cmd = standaloneCommand();
+    expect(cmd[COMMAND_BRAND]).toBe(true);
+  });
+
+  it('preserves group, name, and description', () => {
+    const cmd = sessionCommand();
+    expect(cmd.group).toBe('console');
+    expect(cmd.name).toBe('exec');
+    expect(cmd.description).toBe('Execute inline Luau code');
+  });
+
+  it('preserves category and safety', () => {
+    const cmd = sessionCommand();
+    expect(cmd.category).toBe('execution');
+    expect(cmd.safety).toBe('mutate');
+  });
+
+  it('preserves scope discriminant', () => {
+    expect(sessionCommand().scope).toBe('session');
+    expect(connectionCommand().scope).toBe('connection');
+    expect(standaloneCommand().scope).toBe('standalone');
+  });
+
+  it('preserves args record', () => {
+    const cmd = sessionCommand();
+    expect(cmd.args).toHaveProperty('code');
+    expect(cmd.args.code.kind).toBe('positional');
+  });
+
+  it('preserves handler function', () => {
+    const cmd = sessionCommand();
+    expect(typeof cmd.handler).toBe('function');
+  });
+
+  it('preserves optional cli config', () => {
+    const cmd = defineCommand({
+      group: 'console',
+      name: 'exec',
+      description: 'Execute code',
+      category: 'execution',
+      safety: 'mutate',
+      scope: 'session',
+      args: {},
+      handler: async () => ({ done: true }),
+      cli: {
+        format: () => 'formatted',
+      },
+    });
+
+    expect(cmd.cli).toBeDefined();
+    expect(cmd.cli!.format!({} as any)).toBe('formatted');
+  });
+
+  it('allows null group for top-level commands', () => {
+    const cmd = standaloneCommand();
+    expect(cmd.group).toBeNull();
+  });
+});
+
+describe('isCommandDefinition', () => {
+  it('returns true for branded definition', () => {
+    expect(isCommandDefinition(sessionCommand())).toBe(true);
+  });
+
+  it('returns true for all scope variants', () => {
+    expect(isCommandDefinition(connectionCommand())).toBe(true);
+    expect(isCommandDefinition(standaloneCommand())).toBe(true);
+  });
+
+  it('returns false for plain object', () => {
+    expect(isCommandDefinition({ group: 'console', name: 'exec' })).toBe(false);
+  });
+
+  it('returns false for object with wrong brand value', () => {
+    const fake = { [COMMAND_BRAND]: 'yes' };
+    expect(isCommandDefinition(fake)).toBe(false);
+  });
+
+  it('returns false for null', () => {
+    expect(isCommandDefinition(null)).toBe(false);
+  });
+
+  it('returns false for undefined', () => {
+    expect(isCommandDefinition(undefined)).toBe(false);
+  });
+
+  it('returns false for non-object types', () => {
+    expect(isCommandDefinition('string')).toBe(false);
+    expect(isCommandDefinition(42)).toBe(false);
+    expect(isCommandDefinition(true)).toBe(false);
+  });
+
+  it('returns false for function', () => {
+    expect(isCommandDefinition(() => {})).toBe(false);
+  });
+});

package/src/commands/framework/define-command.ts

@@ -0,0 +1,114 @@
+/**
+ * Core types and `defineCommand()` factory for the declarative command system.
+ *
+ * A single `CommandDefinition` drives CLI registration. The `scope`
+ * discriminant determines the handler signature:
+ *
+ *   - `session`    — `(session: BridgeSession, args) => Promise<TResult>`
+ *   - `connection` — `(connection: BridgeConnection, args) => Promise<TResult>`
+ *   - `standalone` — `(args) => Promise<TResult>`
+ */
+
+import type { BridgeSession, BridgeConnection } from '../../bridge/index.js';
+import type { ArgDefinition } from './arg-builder.js';
+
+/**
+ * Brand symbol used by the registry to identify command definitions when
+ * scanning module exports via dynamic `import()`.
+ */
+export const COMMAND_BRAND = Symbol.for('studio-bridge:command');
+
+/** Safety classification — drives targeting behavior in adapters. */
+export type CommandSafety = 'read' | 'mutate' | 'none';
+
+export type CommandScope = 'session' | 'connection' | 'standalone';
+
+export type CommandCategory = 'execution' | 'infrastructure';
+
+export interface CliConfig<TResult> {
+  /**
+   * Render the result for human (terminal) output. Used as the default and
+   * for `--format=text`. Falls back to `result.summary` then JSON if not set.
+   */
+  format?: (result: TResult) => string;
+  /**
+   * Override the default JSON output (which is `formatJson(result)`). Use
+   * this when the result has fields that don't belong in machine output —
+   * e.g. dropping a base64 binary field.
+   */
+  json?: (result: TResult) => string;
+  /** Field name containing base64 binary data for raw file writes via --output. */
+  binaryField?: string;
+}
+
+interface BaseFields<TArgs, TResult> {
+  /** `null` for top-level commands. */
+  group: string | null;
+  name: string;
+  description: string;
+  category: CommandCategory;
+  safety: CommandSafety;
+  args: Record<string, ArgDefinition>;
+  cli?: CliConfig<TResult>;
+}
+
+export interface SessionCommandInput<TArgs, TResult>
+  extends BaseFields<TArgs, TResult> {
+  scope: 'session';
+  handler: (session: BridgeSession, args: TArgs) => Promise<TResult>;
+}
+
+export interface ConnectionCommandInput<TArgs, TResult>
+  extends BaseFields<TArgs, TResult> {
+  scope: 'connection';
+  handler: (connection: BridgeConnection, args: TArgs) => Promise<TResult>;
+}
+
+export interface StandaloneCommandInput<TArgs, TResult>
+  extends BaseFields<TArgs, TResult> {
+  scope: 'standalone';
+  handler: (args: TArgs) => Promise<TResult>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CommandInput<TArgs = any, TResult = any> =
+  | SessionCommandInput<TArgs, TResult>
+  | ConnectionCommandInput<TArgs, TResult>
+  | StandaloneCommandInput<TArgs, TResult>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CommandDefinition<TArgs = any, TResult = any> = CommandInput<
+  TArgs,
+  TResult
+> & { readonly [COMMAND_BRAND]: true };
+
+/**
+ * Define a new command. Stamps the brand symbol so the registry can
+ * identify it when scanning module exports.
+ */
+export function defineCommand<TArgs, TResult>(
+  input: SessionCommandInput<TArgs, TResult>
+): CommandDefinition<TArgs, TResult>;
+export function defineCommand<TArgs, TResult>(
+  input: ConnectionCommandInput<TArgs, TResult>
+): CommandDefinition<TArgs, TResult>;
+export function defineCommand<TArgs, TResult>(
+  input: StandaloneCommandInput<TArgs, TResult>
+): CommandDefinition<TArgs, TResult>;
+export function defineCommand(input: CommandInput): CommandDefinition {
+  return { ...input, [COMMAND_BRAND]: true as const };
+}
+
+/**
+ * Check whether a value is a branded `CommandDefinition`. Used by the
+ * registry when scanning module exports via dynamic `import()`.
+ */
+export function isCommandDefinition(
+  value: unknown
+): value is CommandDefinition {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as any)[COMMAND_BRAND] === true
+  );
+}

package/src/commands/framework/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Declarative command framework. `defineCommand()` creates a single
+ * definition that drives the CLI adapter.
+ */
+
+export {
+  COMMAND_BRAND,
+  defineCommand,
+  isCommandDefinition,
+  type CommandSafety,
+  type CommandScope,
+  type CommandCategory,
+  type CommandInput,
+  type CommandDefinition,
+  type SessionCommandInput,
+  type ConnectionCommandInput,
+  type StandaloneCommandInput,
+  type CliConfig,
+} from './define-command.js';
+
+export {
+  arg,
+  toYargsOptions,
+  toJsonSchema,
+  type ArgKind,
+  type ArgType,
+  type ArgDefinition,
+  type YargsPositional,
+  type YargsArgConfig,
+  type JsonSchemaOutput,
+} from './arg-builder.js';
+
+export { CommandRegistry } from './command-registry.js';

package/src/commands/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Command registry barrel export. Every new command handler adds an
+ * export line here. cli.ts imports from this barrel.
+ */
+
+export {
+  listSessionsHandlerAsync,
+  type SessionsResult,
+} from './process/list/list.js';
+export {
+  serveHandlerAsync,
+  type ServeOptions,
+  type ServeResult,
+} from './serve/serve.js';
+export {
+  installPluginHandlerAsync,
+  type InstallPluginResult,
+} from './plugin/install/install.js';
+export {
+  uninstallPluginHandlerAsync,
+  type UninstallPluginResult,
+} from './plugin/uninstall/uninstall.js';
+export {
+  queryStateHandlerAsync,
+  type StateResult,
+} from './process/info/info.js';
+export {
+  queryLogsHandlerAsync,
+  type LogsResult,
+  type LogsOptions,
+} from './console/logs/logs.js';
+export {
+  captureScreenshotHandlerAsync,
+  type ScreenshotResult,
+  type ScreenshotOptions,
+} from './viewport/screenshot/screenshot.js';
+export {
+  queryDataModelHandlerAsync,
+  type QueryResult,
+  type QueryOptions,
+  type DataModelNode,
+} from './explorer/query/query.js';
+export {
+  execHandlerAsync,
+  type ExecOptions,
+  type ExecResult,
+} from './console/exec/exec.js';
+export {
+  runHandlerAsync,
+  type RunOptions,
+  type RunResult,
+} from './console/exec/exec.js';
+export {
+  launchHandlerAsync,
+  type LaunchOptions,
+  type LaunchResult,
+} from './process/launch/launch.js';
+export {
+  connectHandlerAsync,
+  type ConnectOptions,
+  type ConnectResult,
+} from './connect.js';
+export { disconnectHandler, type DisconnectResult } from './disconnect.js';
+export {
+  processRunHandlerAsync,
+  type ProcessRunOptions,
+  type ProcessRunResult,
+} from './process/run/run.js';
+export {
+  processCloseHandlerAsync,
+  type ProcessCloseResult,
+} from './process/close/close.js';

package/src/commands/linux/inject-credentials/inject-credentials.ts

@@ -0,0 +1,118 @@
+/**
+ * `linux inject-credentials` — inject .ROBLOSECURITY cookie into Wine's
+ * Credential Manager so Studio can authenticate.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { getRobloxCookieAsync } from '@quenty/nevermore-cli-helpers';
+import { checkLinuxEnvironmentAsync } from '../../../linux/linux-env-guard.js';
+
+interface AuthArgs {
+  cookie?: string;
+}
+
+interface AuthResult {
+  success: boolean;
+  summary: string;
+}
+
+function readStdinAsync(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+export async function injectCredentialsHandlerAsync(
+  args: AuthArgs
+): Promise<AuthResult> {
+  try {
+    const envError = await checkLinuxEnvironmentAsync();
+    if (envError) {
+      OutputHelper.error(envError);
+      process.exit(1);
+    }
+
+    const linux = await import('../../../linux/index.js');
+    const config = linux.resolveLinuxConfig();
+
+    // Resolve cookie from explicit arg, stdin, or shared auth
+    let cookie: string;
+    if (args.cookie === '-') {
+      // Read from stdin
+      cookie = await readStdinAsync();
+      if (!cookie.trim()) {
+        throw new Error('No cookie provided on stdin');
+      }
+      cookie = cookie.trim();
+    } else if (args.cookie) {
+      cookie = args.cookie;
+    } else {
+      cookie = await getRobloxCookieAsync();
+    }
+
+    // Validate cookie before attempting Wine injection
+    const { validateCookieAsync } = await import(
+      '@quenty/nevermore-cli-helpers'
+    );
+    const validation = await validateCookieAsync(cookie);
+    if (!validation.valid) {
+      if (validation.reason === 'network_error') {
+        OutputHelper.warn(
+          'Could not validate ROBLOSECURITY cookie (network error). Continuing anyway.'
+        );
+      } else {
+        throw new Error(
+          `ROBLOSECURITY cookie is invalid or expired (HTTP ${validation.status}). Update the cookie and try again.`
+        );
+      }
+    }
+
+    // Ensure display is running (Wine needs it for credential write)
+    await linux.ensureDisplayAsync(config);
+
+    // Inject credentials
+    await linux.injectCredentialsAsync({ cookie, config });
+
+    OutputHelper.info('Credentials injected.');
+    OutputHelper.hint(
+      'Next: run "studio-bridge process launch" to start Studio'
+    );
+
+    return {
+      success: true,
+      summary: 'Credentials injected into Wine Credential Manager',
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    OutputHelper.error(message);
+    return { success: false, summary: message };
+  }
+}
+
+export const linuxInjectCredentialsCommand = defineCommand<
+  AuthArgs,
+  AuthResult
+>({
+  group: 'linux',
+  name: 'inject-credentials',
+  description:
+    'Inject .ROBLOSECURITY cookie into Wine Credential Manager (within Docker image or Linux with Wine)',
+  category: 'infrastructure',
+  safety: 'none',
+  scope: 'standalone',
+  args: {
+    cookie: arg.option({
+      description:
+        'Cookie value (or "-" to read from stdin). Falls back to $ROBLOSECURITY env var or interactive prompt.',
+    }),
+  },
+  handler: async (args) => injectCredentialsHandlerAsync(args),
+});

package/src/commands/linux/setup/setup.ts

@@ -0,0 +1,145 @@
+/**
+ * `linux setup` — install Wine dependencies and Roblox Studio for headless
+ * Linux operation.
+ */
+
+import { defineCommand } from '../../framework/define-command.js';
+import { arg } from '../../framework/arg-builder.js';
+import { OutputHelper } from '@quenty/cli-output-helpers';
+import { checkLinuxEnvironmentAsync } from '../../../linux/linux-env-guard.js';
+
+interface SetupArgs {
+  'install-deps': boolean;
+  'studio-version'?: string;
+  'studio-dir'?: string;
+  'skip-shaders': boolean;
+  force: boolean;
+}
+
+interface SetupResult {
+  success: boolean;
+  summary: string;
+}
+
+export async function setupHandlerAsync(args: SetupArgs): Promise<SetupResult> {
+  try {
+    const envError = await checkLinuxEnvironmentAsync();
+    if (envError) {
+      OutputHelper.error(envError);
+      process.exit(1);
+    }
+
+    const linux = await import('../../../linux/index.js');
+    const config = linux.resolveLinuxConfig();
+
+    // Override studioDir if provided
+    if (args['studio-dir']) {
+      config.studioDir = args['studio-dir'];
+    }
+
+    // Step 1: Install system deps
+    if (args['install-deps']) {
+      OutputHelper.info('Installing system dependencies...');
+      await linux.installDependenciesAsync();
+    }
+
+    // Step 2: Check prerequisites
+    OutputHelper.info('Checking prerequisites...');
+    const results = linux.checkPrerequisites();
+    const missing = results.filter((r) => !r.available);
+    if (missing.length > 0) {
+      for (const m of missing) {
+        OutputHelper.error(`Missing: ${m.name} — ${m.hint}`);
+      }
+      if (!args['install-deps']) {
+        OutputHelper.hint(
+          'Run with --install-deps to install missing dependencies'
+        );
+      }
+      return {
+        success: false,
+        summary: `Missing prerequisites: ${missing
+          .map((m) => m.name)
+          .join(', ')}`,
+      };
+    }
+    OutputHelper.info('All prerequisites satisfied.');
+
+    // Step 3: Resolve version
+    const version = await linux.resolveStudioVersionAsync(
+      args['studio-version']
+    );
+    OutputHelper.info(`Studio version: ${version}`);
+
+    // Step 4: Check if already installed
+    const { readInstalledVersionAsync } = await import(
+      '../../../linux/linux-version-resolver.js'
+    );
+    const installed = await readInstalledVersionAsync(config.studioDir);
+    if (installed === version && !args.force) {
+      OutputHelper.info(
+        `Studio ${version} already installed. Use --force to reinstall.`
+      );
+    } else {
+      await linux.installStudioAsync(config, version);
+    }
+
+    // Step 5: Patch shaders
+    if (!args['skip-shaders']) {
+      await linux.patchShadersAsync(config);
+    }
+
+    // Step 6: Write FFlags
+    await linux.writeFflagsAsync(config);
+
+    // Step 7: Compile write-cred.exe
+    const { compileWriteCredAsync } = await import(
+      '../../../linux/linux-credential-writer.js'
+    );
+    await compileWriteCredAsync(config);
+
+    // Step 8: Start display
+    await linux.ensureDisplayAsync(config);
+    await linux.ensureWindowManagerAsync(config);
+
+    OutputHelper.info('Linux setup complete.');
+    OutputHelper.hint(
+      'Next: run "studio-bridge linux inject-credentials" to inject credentials'
+    );
+
+    return {
+      success: true,
+      summary: `Studio ${version} installed and configured`,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    OutputHelper.error(message);
+    return { success: false, summary: message };
+  }
+}
+
+export const linuxSetupCommand = defineCommand<SetupArgs, SetupResult>({
+  group: 'linux',
+  name: 'setup',
+  description:
+    'Install Wine + Roblox Studio for headless Linux operation (within Docker image or Linux with Wine)',
+  category: 'infrastructure',
+  safety: 'none',
+  scope: 'standalone',
+  args: {
+    'install-deps': arg.flag({
+      description: 'Install system dependencies via apt-get (requires sudo)',
+    }),
+    'studio-version': arg.option({
+      description: 'Studio version hash (default: latest from CDN)',
+    }),
+    'studio-dir': arg.option({
+      description: 'Override Studio installation directory',
+    }),
+    'skip-shaders': arg.flag({ description: 'Skip shader patching' }),
+    force: arg.flag({
+      description: 'Force reinstall even if already installed',
+    }),
+  },
+  handler: async (args) => setupHandlerAsync(args),
+});