redscript-mc 1.0.0

package/src/mc-test/client.ts

@@ -0,0 +1,259 @@
+/**
+ * RedScript MC Test Client
+ *
+ * Connects to a Paper server running TestHarnessPlugin and provides
+ * a fluent API for integration testing compiled datapacks.
+ *
+ * Usage:
+ *   const mc = new MCTestClient('localhost', 25561)
+ *   await mc.command('/function arena:start')
+ *   await mc.ticks(100)
+ *   const score = await mc.scoreboard('Alice', 'kills')
+ *   expect(score).toBe(3)
+ */
+
+export interface ScoreResult {
+  player: string
+  obj: string
+  value: number
+}
+
+export interface BlockResult {
+  x: number
+  y: number
+  z: number
+  world: string
+  type: string
+  blockData: string
+}
+
+export interface EntityResult {
+  uuid: string
+  name: string
+  type: string
+  x: number
+  y: number
+  z: number
+  world: string
+  tags: string[]
+}
+
+export interface ChatMessage {
+  tick: number
+  type: string
+  sender?: string
+  message: string
+}
+
+export interface GameEvent {
+  tick: number
+  type: string
+  player?: string
+  advancement?: string
+  cause?: string
+}
+
+export interface ServerStatus {
+  online: boolean
+  tps_1m: number
+  tps_5m: number
+  tps_15m: number
+  players: number
+  playerNames: string[]
+  worlds: string[]
+  version: string
+}
+
+export class MCTestClient {
+  private baseUrl: string
+
+  constructor(host = 'localhost', port = 25561) {
+    this.baseUrl = `http://${host}:${port}`
+  }
+
+  private async get<T>(path: string, params: Record<string, string | number> = {}): Promise<T> {
+    const qs = Object.entries(params)
+      .map(([k, v]) => `${k}=${encodeURIComponent(String(v))}`)
+      .join('&')
+    const url = `${this.baseUrl}${path}${qs ? '?' + qs : ''}`
+    const res = await fetch(url)
+    if (!res.ok) {
+      const body = await res.text()
+      throw new Error(`GET ${path} failed ${res.status}: ${body}`)
+    }
+    return res.json() as Promise<T>
+  }
+
+  private async post<T>(path: string, body: Record<string, unknown> = {}): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    })
+    if (!res.ok) {
+      const text = await res.text()
+      throw new Error(`POST ${path} failed ${res.status}: ${text}`)
+    }
+    return res.json() as Promise<T>
+  }
+
+  /** Check if server is reachable */
+  async isOnline(): Promise<boolean> {
+    try {
+      const status = await this.get<ServerStatus>('/status')
+      return status.online
+    } catch {
+      return false
+    }
+  }
+
+  /** Get server status */
+  async status(): Promise<ServerStatus> {
+    return this.get('/status')
+  }
+
+  /** Run a command on the server (as console sender) */
+  async command(cmd: string): Promise<{ ok: boolean; cmd: string }> {
+    return this.post('/command', { cmd })
+  }
+
+  /** Wait for N server ticks (50ms each) */
+  async ticks(count: number): Promise<void> {
+    await this.post('/tick', { count })
+  }
+
+  /** Wait for 1 second = 20 ticks */
+  async seconds(s: number): Promise<void> {
+    await this.ticks(s * 20)
+  }
+
+  /** Get a scoreboard value */
+  async scoreboard(player: string, obj: string): Promise<number> {
+    const result = await this.get<ScoreResult>('/scoreboard', { player, obj })
+    return result.value
+  }
+
+  /** Get all scoreboard values for a selector */
+  async scoreboardAll(selector: string, obj: string): Promise<ScoreResult[]> {
+    return this.get('/scoreboard', { player: selector, obj })
+  }
+
+  /** Get block at position */
+  async block(x: number, y: number, z: number, world = 'world'): Promise<BlockResult> {
+    return this.get('/block', { x, y, z, world })
+  }
+
+  /** Get entities matching selector */
+  async entities(selector = '@e'): Promise<EntityResult[]> {
+    return this.get('/entity', { sel: selector })
+  }
+
+  /** Get chat log since a tick */
+  async chat(since = 0): Promise<ChatMessage[]> {
+    return this.get('/chat', { since })
+  }
+
+  /** Get last N chat messages */
+  async chatLast(n: number): Promise<ChatMessage[]> {
+    return this.get('/chat', { last: n })
+  }
+
+  /** Get events since a tick, optionally filtered by type */
+  async events(since = 0, type?: string): Promise<GameEvent[]> {
+    const params: Record<string, string | number> = { since }
+    if (type) params.type = type
+    return this.get('/events', params)
+  }
+
+  /** Clear chat and event logs */
+  async reset(): Promise<void> {
+    await this.post('/reset')
+  }
+
+  /**
+   * Full test reset: clear logs + fill test area with air + kill entities + reset scoreboards.
+   * Call this at the start of each integration test.
+   */
+  async fullReset(options?: {
+    x1?: number; y1?: number; z1?: number
+    x2?: number; y2?: number; z2?: number
+    clearArea?: boolean
+    killEntities?: boolean
+    resetScoreboards?: boolean
+  }): Promise<void> {
+    await this.post('/reset', {
+      clearArea: options?.clearArea ?? true,
+      killEntities: options?.killEntities ?? true,
+      resetScoreboards: options?.resetScoreboards ?? true,
+      x1: options?.x1 ?? -50, y1: options?.y1 ?? 0, z1: options?.z1 ?? -50,
+      x2: options?.x2 ?? 50,  y2: options?.y2 ?? 100, z2: options?.z2 ?? 50,
+    })
+  }
+
+  /** Reload datapacks */
+  async reload(): Promise<void> {
+    await this.post('/reload')
+    await this.ticks(40) // wait 2s for reload
+  }
+
+  /**
+   * Assert a scoreboard value equals expected.
+   * Throws with a descriptive error if it doesn't match.
+   */
+  async assertScore(player: string, obj: string, expected: number, msg?: string): Promise<void> {
+    const actual = await this.scoreboard(player, obj)
+    if (actual !== expected) {
+      throw new Error(
+        msg ?? `assertScore failed: ${player}/${obj} expected ${expected}, got ${actual}`
+      )
+    }
+  }
+
+  /**
+   * Assert a block type at position.
+   */
+  async assertBlock(x: number, y: number, z: number, expectedType: string, world = 'world'): Promise<void> {
+    const block = await this.block(x, y, z, world)
+    if (block.type !== expectedType) {
+      throw new Error(
+        `assertBlock failed: (${x},${y},${z}) expected ${expectedType}, got ${block.type}`
+      )
+    }
+  }
+
+  /**
+   * Assert chat log contains a message matching substring.
+   */
+  async assertChatContains(substring: string, since = 0): Promise<void> {
+    const msgs = await this.chat(since)
+    const found = msgs.some(m => m.message.includes(substring))
+    if (!found) {
+      const recent = msgs.map(m => m.message).slice(-5).join(', ')
+      throw new Error(
+        `assertChatContains: "${substring}" not found in chat. Recent: [${recent}]`
+      )
+    }
+  }
+
+  /**
+   * Wait until a scoreboard value equals expected, up to timeout ms.
+   */
+  async waitForScore(
+    player: string,
+    obj: string,
+    expected: number,
+    timeoutMs = 5000,
+    pollMs = 100
+  ): Promise<void> {
+    const start = Date.now()
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const val = await this.scoreboard(player, obj)
+        if (val === expected) return
+      } catch { /* ignore transient errors */ }
+      await new Promise(r => setTimeout(r, pollMs))
+    }
+    const final = await this.scoreboard(player, obj)
+    throw new Error(`waitForScore: ${player}/${obj} never reached ${expected} (last: ${final})`)
+  }
+}

package/src/mc-test/runner.ts

@@ -0,0 +1,140 @@
+/**
+ * RedScript MC Integration Test Runner
+ *
+ * Compiles a .rs file, installs it to a running Paper server,
+ * runs test scenarios, and reports results.
+ *
+ * Usage:
+ *   npx ts-node src/mc-test/runner.ts src/examples/counter.rs
+ *
+ * Requires:
+ *   - Paper server running with TestHarnessPlugin
+ *   - MC_SERVER_DIR env var pointing to server directory
+ *   - MC_HOST and MC_PORT env vars (default: localhost:25561)
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { execSync } from 'child_process'
+import { MCTestClient } from './client'
+import { compile } from '../compile'
+
+const MC_HOST = process.env.MC_HOST ?? 'localhost'
+const MC_PORT = parseInt(process.env.MC_PORT ?? '25561')
+const MC_SERVER_DIR = process.env.MC_SERVER_DIR ?? path.join(process.env.HOME!, 'mc-test-server')
+
+export interface TestCase {
+  name: string
+  run: (mc: MCTestClient) => Promise<void>
+}
+
+export interface TestResult {
+  name: string
+  passed: boolean
+  error?: string
+  durationMs: number
+}
+
+export async function runMCTests(
+  sourceFile: string,
+  tests: TestCase[],
+  options: { skipInstall?: boolean } = {}
+): Promise<TestResult[]> {
+  const mc = new MCTestClient(MC_HOST, MC_PORT)
+
+  // Check server is online
+  console.log(`Connecting to MC server at ${MC_HOST}:${MC_PORT}...`)
+  const online = await mc.isOnline()
+  if (!online) {
+    throw new Error(`MC server not reachable at ${MC_HOST}:${MC_PORT}. Start Paper server first.`)
+  }
+  console.log('✓ Server online')
+
+  if (!options.skipInstall) {
+    // Compile and install datapack
+    const outDir = path.join(MC_SERVER_DIR, 'world', 'datapacks', 'redscript-test')
+    console.log(`Compiling ${sourceFile}...`)
+    const result = compile(fs.readFileSync(sourceFile, 'utf-8'))
+    if (!result.success || !result.files) {
+      throw result.error ?? new Error('Compilation failed')
+    }
+    // Write files
+    fs.mkdirSync(outDir, { recursive: true })
+    for (const file of result.files) {
+      const filePath = path.join(outDir, file.path)
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, file.content)
+    }
+    console.log(`✓ Datapack installed to ${outDir}`)
+
+    // Reload datapacks
+    await mc.command('/reload')
+    await mc.ticks(40) // wait 2s for reload
+    console.log('✓ Datapacks reloaded')
+  }
+
+  // Run tests
+  const results: TestResult[] = []
+  for (const test of tests) {
+    await mc.reset() // clear logs before each test
+    const start = Date.now()
+    try {
+      await test.run(mc)
+      results.push({ name: test.name, passed: true, durationMs: Date.now() - start })
+      console.log(`  ✓ ${test.name} (${Date.now() - start}ms)`)
+    } catch (err: any) {
+      results.push({
+        name: test.name,
+        passed: false,
+        error: err.message,
+        durationMs: Date.now() - start
+      })
+      console.log(`  ✗ ${test.name}: ${err.message}`)
+    }
+  }
+
+  // Summary
+  const passed = results.filter(r => r.passed).length
+  const failed = results.length - passed
+  console.log(`\nResults: ${passed}/${results.length} passed${failed > 0 ? ` (${failed} FAILED)` : ''}`)
+
+  return results
+}
+
+// CLI entry point
+if (require.main === module) {
+  const sourceFile = process.argv[2]
+  if (!sourceFile) {
+    console.error('Usage: ts-node runner.ts <source.rs>')
+    process.exit(1)
+  }
+
+  // Example test suite (replace with actual tests)
+  const exampleTests: TestCase[] = [
+    {
+      name: 'server is online',
+      run: async (mc) => {
+        const status = await mc.status()
+        if (!status.online) throw new Error('Server not online')
+      }
+    },
+    {
+      name: 'datapack loads without errors',
+      run: async (mc) => {
+        await mc.command('/reload')
+        await mc.ticks(20)
+        // If reload didn't crash, we're good
+      }
+    }
+  ]
+
+  runMCTests(sourceFile, exampleTests)
+    .then(results => {
+      const failed = results.filter(r => !r.passed)
+      process.exit(failed.length > 0 ? 1 : 0)
+    })
+    .catch(err => {
+      console.error(err.message)
+      process.exit(1)
+    })
+}

package/src/mc-test/setup.ts

@@ -0,0 +1,70 @@
+/**
+ * MC Test Setup Script
+ *
+ * Pre-compiles all RedScript test fixtures into the datapack directory.
+ * Run this ONCE before starting the Paper server, or before running tests
+ * with a fresh server.
+ *
+ * Usage:
+ *   MC_SERVER_DIR=~/mc-test-server npx ts-node src/mc-test/setup.ts
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import { compile } from '../compile'
+
+const MC_SERVER_DIR = process.env.MC_SERVER_DIR ?? path.join(process.env.HOME!, 'mc-test-server')
+const DATAPACK_DIR = path.join(MC_SERVER_DIR, 'world', 'datapacks', 'redscript-test')
+const EXAMPLES_DIR = path.join(__dirname, '../examples')
+
+function writeFixture(source: string, namespace: string): void {
+  const result = compile(source, { namespace })
+  let fileCount = 0
+  for (const file of result.files ?? []) {
+    const filePath = path.join(DATAPACK_DIR, file.path)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, file.content)
+    fileCount++
+  }
+  console.log(`  ✓ ${namespace} (${fileCount} files)`)
+}
+
+function main() {
+  console.log(`Setting up MC test fixtures in:\n  ${DATAPACK_DIR}\n`)
+  fs.mkdirSync(DATAPACK_DIR, { recursive: true })
+
+  // Example files
+  const exampleNamespaces = ['counter', 'world_manager']
+  for (const ns of exampleNamespaces) {
+    const file = path.join(EXAMPLES_DIR, `${ns}.rs`)
+    if (fs.existsSync(file)) {
+      writeFixture(fs.readFileSync(file, 'utf-8'), ns)
+    } else {
+      console.log(`  ⚠ ${ns}.rs not found, skipping`)
+    }
+  }
+
+  // Inline test fixtures
+  writeFixture(`
+    @tick
+    fn on_tick() {
+      scoreboard_set("#tick_counter", "ticks", scoreboard_get("#tick_counter", "ticks") + 1)
+    }
+  `, 'tick_test')
+
+  writeFixture(`
+    fn check_score() {
+      let x: int = scoreboard_get("#check_x", "test_score")
+      if (x > 5) {
+        scoreboard_set("#check_x", "result", 1)
+      } else {
+        scoreboard_set("#check_x", "result", 0)
+      }
+    }
+  `, 'inline_test')
+
+  console.log('\n✅ All fixtures written. Restart the MC server to load them.')
+  console.log('   Then run: MC_SERVER_DIR=... npx jest mc-integration --testTimeout=60000')
+}
+
+main()