@quenty/studio-bridge 0.7.1 → 0.8.0

package/src/cli/adapters/cli-command-adapter-handler.test.ts

@@ -0,0 +1,318 @@
+/**
+ * Handler-level tests for the CLI command adapter — format flags,
+ * output file writing, and watch mode.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { buildYargsCommand } from './cli-command-adapter.js';
+import { defineCommand } from '../../commands/framework/define-command.js';
+import type { CliLifecycleProvider } from './cli-command-adapter.js';
+
+vi.mock('fs', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('fs')>();
+  return {
+    ...actual,
+    writeFileSync: vi.fn(),
+  };
+});
+
+import * as fs from 'fs';
+
+function createMockSession() {
+  return { sessionId: 'mock-session' };
+}
+
+function createMockConnection() {
+  const session = createMockSession();
+  return {
+    connection: {
+      resolveSessionAsync: vi.fn().mockResolvedValue(session),
+      disconnectAsync: vi.fn().mockResolvedValue(undefined),
+      listSessions: vi.fn().mockReturnValue([]),
+    } as any,
+    session,
+  };
+}
+
+function createMockLifecycle(): CliLifecycleProvider & {
+  mock: ReturnType<typeof createMockConnection>;
+} {
+  const mock = createMockConnection();
+  return {
+    mock,
+    connectAsync: vi.fn().mockResolvedValue(mock.connection),
+  };
+}
+
+/** Capture console.log output during handler execution. */
+async function captureOutput(fn: () => Promise<void>): Promise<string[]> {
+  const logs: string[] = [];
+  const origLog = console.log;
+  console.log = (...args: unknown[]) => {
+    logs.push(args.map(String).join(' '));
+  };
+  try {
+    await fn();
+  } finally {
+    console.log = origLog;
+  }
+  return logs;
+}
+
+function readCommand(
+  overrides: Partial<{
+    handler: (...args: any[]) => Promise<any>;
+    cli: any;
+    scope: 'session' | 'connection' | 'standalone';
+  }> = {}
+) {
+  return defineCommand({
+    group: 'test',
+    name: 'read',
+    description: 'Test read command',
+    category: 'execution',
+    safety: 'read',
+    scope: overrides.scope ?? 'session',
+    args: {},
+    handler:
+      overrides.handler ??
+      (async () => ({
+        items: ['a', 'b'],
+        summary: 'Found 2 items',
+      })),
+    cli: overrides.cli,
+  } as any);
+}
+
+let exitSpy: any;
+
+beforeEach(() => {
+  exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
+    throw new Error('process.exit called');
+  });
+  vi.mocked(fs.writeFileSync).mockReset();
+});
+
+afterEach(() => {
+  exitSpy.mockRestore();
+});
+
+describe('handler — format flags', () => {
+  it('outputs JSON when --format json is specified', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = readCommand();
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    const output = await captureOutput(async () => {
+      await (module.handler as any)({ format: 'json' });
+    });
+
+    expect(output.length).toBe(1);
+    const parsed = JSON.parse(output[0]);
+    expect(parsed.items).toEqual(['a', 'b']);
+    expect(parsed.summary).toBe('Found 2 items');
+  });
+
+  it('outputs summary text when --format text and no cli.formatResult', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = readCommand();
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    const output = await captureOutput(async () => {
+      await (module.handler as any)({ format: 'text' });
+    });
+
+    expect(output[0]).toBe('Found 2 items');
+  });
+
+  it('uses cli.format when --format text', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = readCommand({
+      cli: {
+        format: (result: any) => `Custom: ${result.items.join(', ')}`,
+      },
+    });
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    const output = await captureOutput(async () => {
+      await (module.handler as any)({ format: 'text' });
+    });
+
+    expect(output[0]).toBe('Custom: a, b');
+  });
+
+  it('falls back to JSON when --format text and no formatter or summary', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = readCommand({
+      handler: async () => ({ data: [1, 2, 3] }),
+    });
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    const output = await captureOutput(async () => {
+      await (module.handler as any)({ format: 'text' });
+    });
+
+    expect(JSON.parse(output[0])).toEqual({ data: [1, 2, 3] });
+  });
+
+  it('defaults to JSON when no format specified and no formatter (non-TTY)', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = readCommand();
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    // No --format specified, non-TTY resolves to 'text' mode which falls
+    // back to summary
+    const output = await captureOutput(async () => {
+      await (module.handler as any)({});
+    });
+
+    // Should output the summary (in non-TTY mode resolves to 'text')
+    expect(output.length).toBe(1);
+    expect(output[0]).toBe('Found 2 items');
+  });
+});
+
+describe('handler — output file writing', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('writes JSON to file when --output and --format json', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = readCommand();
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    const stderrSpy = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+
+    await captureOutput(async () => {
+      await (module.handler as any)({
+        format: 'json',
+        output: '/tmp/test.json',
+      });
+    });
+
+    expect(fs.writeFileSync).toHaveBeenCalledOnce();
+    const call = vi.mocked(fs.writeFileSync).mock.calls[0];
+    expect(call[0]).toBe('/tmp/test.json');
+    const written = call[1] as string;
+    expect(JSON.parse(written)).toEqual({
+      items: ['a', 'b'],
+      summary: 'Found 2 items',
+    });
+    expect(stderrSpy).toHaveBeenCalledWith('Wrote output to /tmp/test.json\n');
+
+    stderrSpy.mockRestore();
+  });
+
+  it('writes binary when --output and binaryField is set', async () => {
+    const lifecycle = createMockLifecycle();
+    const base64Data = Buffer.from('PNG-DATA').toString('base64');
+    const cmd = readCommand({
+      handler: async () => ({
+        data: base64Data,
+        summary: 'Screenshot taken',
+      }),
+      cli: {
+        binaryField: 'data',
+        format: (result: any) => result.summary,
+      },
+    });
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    const stderrSpy = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+
+    await captureOutput(async () => {
+      await (module.handler as any)({
+        output: '/tmp/test.png',
+        format: 'text',
+      });
+    });
+
+    expect(fs.writeFileSync).toHaveBeenCalledOnce();
+    const call = vi.mocked(fs.writeFileSync).mock.calls[0];
+    expect(call[0]).toBe('/tmp/test.png');
+    // Should be a Buffer (binary write)
+    expect(Buffer.isBuffer(call[1])).toBe(true);
+    expect((call[1] as Buffer).toString()).toBe('PNG-DATA');
+    expect(stderrSpy).toHaveBeenCalledWith(
+      'Wrote binary output to /tmp/test.png\n'
+    );
+
+    stderrSpy.mockRestore();
+  });
+
+  it('writes JSON (not binary) when --output --format json even with binaryField', async () => {
+    const lifecycle = createMockLifecycle();
+    const base64Data = Buffer.from('PNG-DATA').toString('base64');
+    const cmd = readCommand({
+      handler: async () => ({
+        data: base64Data,
+        summary: 'Screenshot taken',
+      }),
+      cli: {
+        binaryField: 'data',
+        json: (result: any) => JSON.stringify({ summary: result.summary }),
+      },
+    });
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+
+    await captureOutput(async () => {
+      await (module.handler as any)({
+        output: '/tmp/test.json',
+        format: 'json',
+      });
+    });
+
+    expect(fs.writeFileSync).toHaveBeenCalledOnce();
+    const call = vi.mocked(fs.writeFileSync).mock.calls[0];
+    const written = call[1] as string;
+    // Should be the JSON formatter output, not binary
+    expect(JSON.parse(written)).toEqual({ summary: 'Screenshot taken' });
+
+    vi.restoreAllMocks();
+  });
+});
+
+describe('handler — standalone scope', () => {
+  it('does not connect for standalone commands', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = defineCommand({
+      group: null,
+      name: 'standalone',
+      description: 'Standalone test',
+      category: 'infrastructure',
+      safety: 'none',
+      scope: 'standalone',
+      args: {},
+      handler: async () => ({ ok: true, summary: 'done' }),
+    });
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    const output = await captureOutput(async () => {
+      await (module.handler as any)({ format: 'text' });
+    });
+
+    expect(lifecycle.connectAsync).not.toHaveBeenCalled();
+    expect(output[0]).toBe('done');
+  });
+});
+
+describe('handler — connection lifecycle', () => {
+  it('disconnects after handler completes', async () => {
+    const lifecycle = createMockLifecycle();
+    const cmd = readCommand();
+    const module = buildYargsCommand(cmd, { lifecycle });
+
+    await captureOutput(async () => {
+      await (module.handler as any)({ format: 'json' });
+    });
+
+    expect(lifecycle.mock.connection.disconnectAsync).toHaveBeenCalledOnce();
+  });
+});

package/src/cli/adapters/cli-command-adapter.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Unit tests for the CLI command adapter.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { buildYargsCommand } from './cli-command-adapter.js';
+import {
+  defineCommand,
+  type CommandDefinition,
+} from '../../commands/framework/define-command.js';
+import { arg } from '../../commands/framework/arg-builder.js';
+
+function sessionCommand(
+  overrides: Partial<{ name: string; safety: 'read' | 'mutate' | 'none' }> = {}
+): CommandDefinition {
+  return defineCommand({
+    group: 'console',
+    name: overrides.name ?? 'exec',
+    description: 'Execute code',
+    category: 'execution',
+    safety: overrides.safety ?? 'mutate',
+    scope: 'session',
+    args: {
+      code: arg.positional({ description: 'Luau source code' }),
+      timeout: arg.option({
+        description: 'Timeout',
+        type: 'number',
+        alias: 'T',
+      }),
+    },
+    handler: async (_session, _args) => ({ success: true }),
+  });
+}
+
+function standaloneCommand(): CommandDefinition {
+  return defineCommand({
+    group: null,
+    name: 'serve',
+    description: 'Start the bridge server',
+    category: 'infrastructure',
+    safety: 'none',
+    scope: 'standalone',
+    args: {
+      port: arg.option({
+        description: 'Port number',
+        type: 'number',
+        default: 38741,
+      }),
+    },
+    handler: async () => ({ started: true }),
+  });
+}
+
+function connectionCommand(): CommandDefinition {
+  return defineCommand({
+    group: 'process',
+    name: 'list',
+    description: 'List sessions',
+    category: 'infrastructure',
+    safety: 'read',
+    scope: 'connection',
+    args: {},
+    handler: async () => ({ sessions: [] }),
+  });
+}
+
+/** Mock yargs Argv object that records calls. */
+function createMockYargs() {
+  const positionals: Record<string, any> = {};
+  const options: Record<string, any> = {};
+
+  const mock: any = {
+    positionals,
+    options,
+    positional: vi.fn((name: string, opts: any) => {
+      positionals[name] = opts;
+      return mock;
+    }),
+    option: vi.fn((name: string, opts: any) => {
+      options[name] = opts;
+      return mock;
+    }),
+    demandCommand: vi.fn(() => mock),
+  };
+
+  return mock;
+}
+
+describe('buildYargsCommand', () => {
+  describe('command string', () => {
+    it('includes positional args in command string', () => {
+      const module = buildYargsCommand(sessionCommand());
+      expect(module.command).toBe('exec <code>');
+    });
+
+    it('produces simple command string with no positionals', () => {
+      const module = buildYargsCommand(standaloneCommand());
+      expect(module.command).toBe('serve');
+    });
+
+    it('uses command description', () => {
+      const module = buildYargsCommand(sessionCommand());
+      expect(module.describe).toBe('Execute code');
+    });
+  });
+
+  describe('builder — arg registration', () => {
+    it('registers positional args', () => {
+      const module = buildYargsCommand(sessionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.positionals.code).toBeDefined();
+      expect(yargs.positionals.code.describe).toBe('Luau source code');
+      expect(yargs.positionals.code.type).toBe('string');
+      expect(yargs.positionals.code.demandOption).toBe(true);
+    });
+
+    it('registers command-specific options', () => {
+      const module = buildYargsCommand(sessionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.timeout).toBeDefined();
+      expect(yargs.options.timeout.describe).toBe('Timeout');
+      expect(yargs.options.timeout.type).toBe('number');
+      expect(yargs.options.timeout.alias).toBe('T');
+    });
+  });
+
+  describe('builder — universal args', () => {
+    it('injects --target and --context for session-scoped commands', () => {
+      const module = buildYargsCommand(sessionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.target).toBeDefined();
+      expect(yargs.options.target.alias).toBe('t');
+      expect(yargs.options.context).toBeDefined();
+    });
+
+    it('injects --target and --context for connection-scoped commands', () => {
+      const module = buildYargsCommand(connectionCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.target).toBeDefined();
+      expect(yargs.options.context).toBeDefined();
+    });
+
+    it('does not inject --target for standalone commands', () => {
+      const module = buildYargsCommand(standaloneCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.target).toBeUndefined();
+      expect(yargs.options.context).toBeUndefined();
+    });
+
+    it('always injects --format, --output, --open', () => {
+      const module = buildYargsCommand(standaloneCommand());
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.format).toBeDefined();
+      expect(yargs.options.output).toBeDefined();
+      expect(yargs.options.open).toBeDefined();
+    });
+
+    it('injects --watch and --interval for read-safety commands', () => {
+      const module = buildYargsCommand(connectionCommand()); // safety: 'read'
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.watch).toBeDefined();
+      expect(yargs.options.watch.alias).toBe('w');
+      expect(yargs.options.interval).toBeDefined();
+      expect(yargs.options.interval.default).toBe(1000);
+    });
+
+    it('does not inject --watch for mutate-safety commands', () => {
+      const module = buildYargsCommand(sessionCommand({ safety: 'mutate' }));
+      const yargs = createMockYargs();
+      (module.builder as any)(yargs);
+
+      expect(yargs.options.watch).toBeUndefined();
+      expect(yargs.options.interval).toBeUndefined();
+    });
+  });
+
+  describe('handler — standalone', () => {
+    it('calls standalone handler with extracted args', async () => {
+      const handler = vi.fn().mockResolvedValue({ started: true });
+      const cmd = defineCommand({
+        group: null,
+        name: 'serve',
+        description: 'Start server',
+        category: 'infrastructure',
+        safety: 'none',
+        scope: 'standalone',
+        args: {
+          port: arg.option({
+            description: 'Port',
+            type: 'number',
+            default: 38741,
+          }),
+        },
+        handler,
+      });
+
+      const module = buildYargsCommand(cmd);
+      await (module.handler as any)({
+        port: 9999,
+        verbose: false,
+        timeout: 120000,
+      });
+
+      expect(handler).toHaveBeenCalledWith({ port: 9999 });
+    });
+  });
+});