@quenty/studio-bridge 0.7.1 → 0.8.0

package/src/commands/formatters.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Unit tests for per-command CLI formatters.
+ * Tests the formatResult callbacks in isolation with mock data.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { execCommand } from './console/exec/exec.js';
+import { logsCommand, formatLogsText } from './console/logs/logs.js';
+import { listCommand, formatSessionsTable } from './process/list/list.js';
+import { infoCommand, formatStateText } from './process/info/info.js';
+import { queryCommand, formatQueryText } from './explorer/query/query.js';
+import { screenshotCommand } from './viewport/screenshot/screenshot.js';
+
+describe('exec formatter', () => {
+  const format = execCommand.cli!.format!;
+
+  it('joins output lines', () => {
+    const result = { success: true, output: ['Hello', 'World'], summary: 'ok' };
+    expect(format(result)).toBe('Hello\nWorld');
+  });
+
+  it('appends error when present', () => {
+    const result = {
+      success: false,
+      output: ['partial'],
+      error: 'boom',
+      summary: 'fail',
+    };
+    expect(format(result)).toBe('partial\nboom');
+  });
+
+  it('falls back to summary when no output lines', () => {
+    const result = {
+      success: true,
+      output: [],
+      summary: 'Script executed successfully',
+    };
+    expect(format(result)).toBe('Script executed successfully');
+  });
+
+  it('handles error with no output', () => {
+    const result = {
+      success: false,
+      output: [],
+      error: 'boom',
+      summary: 'fail',
+    };
+    expect(format(result)).toBe('boom');
+  });
+});
+
+describe('logs formatter', () => {
+  it('returns summary when no entries', () => {
+    const result = {
+      entries: [],
+      total: 0,
+      bufferCapacity: 100,
+      summary: '0 entries',
+    };
+    expect(formatLogsText(result)).toBe('0 entries');
+  });
+
+  it('formats timestamped log lines', () => {
+    const result = {
+      entries: [
+        { level: 'Print' as const, body: 'Hello', timestamp: 1000000 },
+        { level: 'Error' as const, body: 'Boom', timestamp: 1001000 },
+      ],
+      total: 2,
+      bufferCapacity: 100,
+      summary: '2 entries',
+    };
+
+    const text = formatLogsText(result);
+    expect(text).toContain('Hello');
+    expect(text).toContain('Boom');
+    expect(text).toContain('(2 of 2 entries)');
+  });
+
+  it('is wired into command definition', () => {
+    expect(logsCommand.cli!.format).toBe(formatLogsText);
+  });
+});
+
+describe('list formatter', () => {
+  it('returns summary when no sessions', () => {
+    const result = { sessions: [], summary: 'No active sessions.' };
+    expect(formatSessionsTable(result)).toBe('No active sessions.');
+  });
+
+  it('formats session table', () => {
+    const result = {
+      sessions: [
+        {
+          sessionId: 'abcdefgh-1234',
+          placeName: 'TestPlace',
+          state: 'Edit' as const,
+          context: 'edit' as const,
+          pluginVersion: '1.0.0',
+          capabilities: [],
+          connectedAt: new Date(),
+          origin: 'user' as const,
+          instanceId: 'inst-1',
+          placeId: 123,
+          gameId: 456,
+        },
+      ],
+      summary: '1 session(s) connected.',
+    };
+
+    const text = formatSessionsTable(result);
+    expect(text).toContain('Session');
+    expect(text).toContain('abcdefg'); // truncated session ID
+    expect(text).toContain('TestPlace');
+    expect(text).toContain('Edit');
+  });
+
+  it('is wired into command definition', () => {
+    expect(listCommand.cli!.format).toBe(formatSessionsTable);
+  });
+});
+
+describe('info formatter', () => {
+  it('formats key-value pairs', () => {
+    const result = {
+      state: 'Edit' as const,
+      placeName: 'MyPlace',
+      placeId: 123,
+      gameId: 456,
+      summary: 'Mode: Edit, Place: MyPlace (123)',
+    };
+
+    const text = formatStateText(result);
+    expect(text).toContain('Mode:');
+    expect(text).toContain('MyPlace');
+    expect(text).toContain('123');
+    expect(text).toContain('456');
+  });
+
+  it('is wired into command definition', () => {
+    expect(infoCommand.cli!.format).toBe(formatStateText);
+  });
+});
+
+describe('query formatter', () => {
+  it('formats a simple node', () => {
+    const result = {
+      node: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+      },
+      summary: 'Workspace (Workspace) at game.Workspace',
+    };
+
+    const text = formatQueryText(result);
+    expect(text).toContain('Workspace');
+  });
+
+  it('formats nested children with indentation', () => {
+    const result = {
+      node: {
+        name: 'Workspace',
+        className: 'Workspace',
+        path: 'game.Workspace',
+        children: [
+          {
+            name: 'Part',
+            className: 'Part',
+            path: 'game.Workspace.Part',
+          },
+        ],
+      },
+      summary: 'Workspace',
+    };
+
+    const text = formatQueryText(result);
+    const lines = text.split('\n');
+    // Root should not be indented
+    expect(lines[0]).toMatch(/^Workspace/);
+    // Child should be indented
+    expect(lines[1]).toMatch(/^ {2}Part/);
+  });
+
+  it('formats properties and attributes', () => {
+    const result = {
+      node: {
+        name: 'Part',
+        className: 'Part',
+        path: 'game.Workspace.Part',
+        properties: { Size: [4, 1, 2] },
+        attributes: { Health: 100 },
+      },
+      summary: 'Part',
+    };
+
+    const text = formatQueryText(result);
+    expect(text).toContain('Size:');
+    expect(text).toContain('@Health:');
+  });
+
+  it('is wired into command definition', () => {
+    expect(queryCommand.cli!.format).toBe(formatQueryText);
+  });
+});
+
+describe('screenshot formatter', () => {
+  it('format returns summary only', () => {
+    const format = screenshotCommand.cli!.format!;
+    const result = {
+      data: 'base64...',
+      width: 800,
+      height: 600,
+      summary: 'Screenshot captured (800x600)',
+    };
+    expect(format(result)).toBe('Screenshot captured (800x600)');
+  });
+
+  it('json override omits data field', () => {
+    const json = screenshotCommand.cli!.json!;
+    const result = {
+      data: 'base64...',
+      width: 800,
+      height: 600,
+      summary: 'Screenshot captured (800x600)',
+    };
+    const parsed = JSON.parse(json(result));
+    expect(parsed).not.toHaveProperty('data');
+    expect(parsed.width).toBe(800);
+    expect(parsed.height).toBe(600);
+    expect(parsed.summary).toBe('Screenshot captured (800x600)');
+  });
+
+  it('has binaryField set to data', () => {
+    expect(screenshotCommand.cli!.binaryField).toBe('data');
+  });
+});

package/src/commands/framework/action-loader.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Tests for action-loader: scanning .luau files and computing content hashes.
+ */
+
+import { createHash } from 'crypto';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadActionSourcesAsync } from './action-loader.js';
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'action-loader-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+function sha256(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+describe('loadActionSourcesAsync', () => {
+  it('loads .luau files from a flat directory', async () => {
+    const source = 'local M = {} return M';
+    await fs.writeFile(path.join(tmpDir, 'hello.luau'), source);
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('hello');
+    expect(results[0].source).toBe(source);
+    expect(results[0].relativePath).toBe('hello.luau');
+  });
+
+  it('computes SHA-256 hash of source content', async () => {
+    const source = 'return function() end';
+    await fs.writeFile(path.join(tmpDir, 'test.luau'), source);
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].hash).toBe(sha256(source));
+  });
+
+  it('different content produces different hashes', async () => {
+    await fs.writeFile(path.join(tmpDir, 'a.luau'), 'version 1');
+    await fs.writeFile(path.join(tmpDir, 'b.luau'), 'version 2');
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results).toHaveLength(2);
+    const hashA = results.find((r) => r.name === 'a')!.hash;
+    const hashB = results.find((r) => r.name === 'b')!.hash;
+    expect(hashA).not.toBe(hashB);
+  });
+
+  it('identical content produces identical hashes', async () => {
+    const source = 'local x = 42';
+    const subDir = path.join(tmpDir, 'sub');
+    await fs.mkdir(subDir);
+    await fs.writeFile(path.join(tmpDir, 'a.luau'), source);
+    await fs.writeFile(path.join(subDir, 'b.luau'), source);
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results).toHaveLength(2);
+    const hashA = results.find((r) => r.name === 'a')!.hash;
+    const hashB = results.find((r) => r.name === 'b')!.hash;
+    expect(hashA).toBe(hashB);
+  });
+
+  it('recursively scans subdirectories', async () => {
+    const subDir = path.join(tmpDir, 'nested', 'deep');
+    await fs.mkdir(subDir, { recursive: true });
+    await fs.writeFile(path.join(subDir, 'deep.luau'), 'return nil');
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('deep');
+    expect(results[0].relativePath).toBe(
+      path.join('nested', 'deep', 'deep.luau')
+    );
+  });
+
+  it('ignores non-.luau files', async () => {
+    await fs.writeFile(path.join(tmpDir, 'script.lua'), 'not included');
+    await fs.writeFile(path.join(tmpDir, 'module.ts'), 'not included');
+    await fs.writeFile(path.join(tmpDir, 'action.luau'), 'included');
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe('action');
+  });
+
+  it('returns empty array for empty directory', async () => {
+    const results = await loadActionSourcesAsync(tmpDir);
+    expect(results).toHaveLength(0);
+  });
+
+  it('returns empty array for non-existent directory', async () => {
+    const results = await loadActionSourcesAsync(path.join(tmpDir, 'nope'));
+    expect(results).toHaveLength(0);
+  });
+
+  it('hash is a 64-character hex string (SHA-256)', async () => {
+    await fs.writeFile(path.join(tmpDir, 'check.luau'), 'content');
+
+    const results = await loadActionSourcesAsync(tmpDir);
+
+    expect(results[0].hash).toMatch(/^[0-9a-f]{64}$/);
+  });
+});

package/src/commands/framework/action-loader.ts

@@ -0,0 +1,65 @@
+/**
+ * Scans co-located `.luau` action files from the command directory tree
+ * and returns their source contents for pushing to plugin sessions.
+ *
+ * Each command directory may contain a `.luau` file with the same stem
+ * as its `.ts` file (e.g. `exec.luau` next to `exec.ts`). These files
+ * are Luau modules that register action handlers in the plugin's
+ * ActionRouter at runtime.
+ */
+
+import { createHash } from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { resolvePackagePath } from '@quenty/nevermore-template-helpers';
+
+export interface ActionSource {
+  /** Action module name (derived from the filename, e.g. "exec"). */
+  name: string;
+  /** Full Luau source code of the action module. */
+  source: string;
+  /** Relative path within the commands directory (for diagnostics). */
+  relativePath: string;
+  /** SHA-256 hex digest of the source content. */
+  hash: string;
+}
+
+/**
+ * Recursively scan `baseDir` for `.luau` files and return their contents
+ * as `ActionSource` entries. Only files that end in `.luau` are included.
+ */
+export async function loadActionSourcesAsync(
+  baseDir?: string
+): Promise<ActionSource[]> {
+  const dir = baseDir ?? resolvePackagePath(import.meta.url, 'src', 'commands');
+
+  const actions: ActionSource[] = [];
+  await scanDirAsync(dir, dir, actions);
+  return actions;
+}
+
+async function scanDirAsync(
+  baseDir: string,
+  currentDir: string,
+  results: ActionSource[]
+): Promise<void> {
+  let entries;
+  try {
+    entries = await fs.readdir(currentDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      await scanDirAsync(baseDir, fullPath, results);
+    } else if (entry.name.endsWith('.luau')) {
+      const source = await fs.readFile(fullPath, 'utf-8');
+      const name = path.basename(entry.name, '.luau');
+      const relativePath = path.relative(baseDir, fullPath);
+      const hash = createHash('sha256').update(source).digest('hex');
+      results.push({ name, source, relativePath, hash });
+    }
+  }
+}