bonescript-compiler 0.9.0 → 0.11.0

package/dist/emit_colyseus.js

@@ -0,0 +1,812 @@
+"use strict";
+/**
+ * BoneScript Colyseus Target Emitter
+ *
+ * Generates a Colyseus.io game server (v0.17) from `channel` declarations.
+ * One `Room` subclass per channel; authoritative state lives in a `Schema`
+ * class derived from the channel.
+ *
+ * Output:
+ *   src/index.ts            Colyseus Server bootstrap, registerRoom for each
+ *   src/rooms/<name>.ts     Room subclass per channel
+ *   src/state/<name>.ts     Schema class per channel
+ *   src/auth.ts             JWT verification helper (mirrors emit_runtime auth)
+ *   package.json, tsconfig.json, README.md
+ *
+ * Why a separate target rather than a flag on the Express target:
+ *   Colyseus rooms are authoritative process-locally. They speak msgpack-
+ *   encoded schema deltas over WebSocket. Mixing into the Express target
+ *   would mean co-hosting both servers, which is supported but adds
+ *   operational complexity for users who don't need realtime games.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColyseusEmitter = void 0;
+function toSnakeCase(s) {
+    return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+function toPascalCase(s) {
+    return s.replace(/(^|[-_\s])(\w)/g, (_, __, c) => c.toUpperCase());
+}
+// ─── Type mapping for Colyseus @type decorators ────────────────────────────────
+const COLYSEUS_TYPE_MAP = {
+    string: '"string"',
+    uint: '"number"',
+    int: '"number"',
+    float: '"number"',
+    bool: '"boolean"',
+    timestamp: '"string"',
+    uuid: '"string"',
+    bytes: '"string"',
+    json: '"string"', // serialized JSON (Colyseus schemas don't have a JSON primitive)
+};
+function toColyseusType(irType) {
+    return COLYSEUS_TYPE_MAP[irType] || '"string"';
+}
+function toTsTypeForSchema(irType) {
+    switch (irType) {
+        case "string":
+        case "timestamp":
+        case "uuid":
+        case "bytes":
+        case "json":
+            return "string";
+        case "uint":
+        case "int":
+        case "float":
+            return "number";
+        case "bool":
+            return "boolean";
+        default:
+            return "string";
+    }
+}
+function defaultValueForType(irType) {
+    switch (irType) {
+        case "string":
+        case "timestamp":
+        case "uuid":
+        case "bytes":
+        case "json":
+            return '""';
+        case "uint":
+        case "int":
+        case "float":
+            return "0";
+        case "bool":
+            return "false";
+        default:
+            return '""';
+    }
+}
+// ─── Per-channel state schema ─────────────────────────────────────────────────
+function emitStateSchema(channel, system) {
+    void system;
+    const lines = [];
+    const channelName = toPascalCase(channel.name);
+    const stateName = `${channelName}State`;
+    const playerName = `${channelName}Player`;
+    // Auto-derived player fields from the channel's participant entity. The
+    // lowering serialised these as a JSON string in config.participant_fields.
+    // We fall back to a minimal {userId, sessionId, joinedAt} default if the
+    // channel doesn't reference an entity.
+    let participantFields = [];
+    const raw = channel.config["participant_fields"];
+    if (typeof raw === "string" && raw.length > 0) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                participantFields = parsed;
+        }
+        catch { /* ignore */ }
+    }
+    lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+    lines.push(`// Colyseus schema for channel: ${channel.name}`);
+    if (channel.config["participant_entity"]) {
+        lines.push(`// Player schema derived from entity: ${channel.config["participant_entity"]}`);
+    }
+    lines.push(``);
+    lines.push(`import { Schema, type, MapSchema } from "@colyseus/schema";`);
+    lines.push(``);
+    lines.push(`export class ${playerName} extends Schema {`);
+    // Always-present identity fields
+    lines.push(`  @type("string") userId: string = "";`);
+    lines.push(`  @type("string") sessionId: string = "";`);
+    lines.push(`  @type("number") joinedAt: number = 0;`);
+    // Auto-derived fields from the entity
+    for (const f of participantFields) {
+        if (["userId", "sessionId", "joinedAt", "id", "created_at", "updated_at"].includes(f.name))
+            continue;
+        const tsType = toTsTypeForSchema(f.type);
+        const dv = defaultValueForType(f.type);
+        lines.push(`  @type(${toColyseusType(f.type)}) ${f.name}: ${tsType} = ${dv};`);
+    }
+    lines.push(`}`);
+    lines.push(``);
+    lines.push(`export class ${stateName} extends Schema {`);
+    lines.push(`  @type({ map: ${playerName} }) players = new MapSchema<${playerName}>();`);
+    lines.push(`  @type("number") tick: number = 0;`);
+    lines.push(`  // Add channel-wide state fields here.`);
+    lines.push(`}`);
+    lines.push(``);
+    return {
+        path: `src/state/${toSnakeCase(channel.name)}.ts`,
+        content: lines.join("\n"),
+        language: "typescript",
+        source_module: channel.id,
+    };
+}
+// ─── Per-channel Room class ───────────────────────────────────────────────────
+function emitRoom(channel, _system) {
+    const lines = [];
+    const channelName = toPascalCase(channel.name);
+    const roomName = `${channelName}Room`;
+    const stateName = `${channelName}State`;
+    const playerName = `${channelName}Player`;
+    const stateModule = toSnakeCase(channel.name);
+    const maxClients = channel.config["max_size"] || 16;
+    const ordering = channel.config["ordering"] || "fifo";
+    const persistence = channel.config["persistence"] || "none";
+    // Persistence: "last_N" → keep last N messages in room.history
+    // "database" → snapshot to disk on dispose, reload on create
+    const historyLimit = (() => {
+        const m = persistence.match(/^last_(\d+)$/);
+        if (m)
+            return parseInt(m[1], 10);
+        if (persistence === "none")
+            return 0;
+        if (persistence === "database")
+            return 0; // db handles durability separately
+        return 100;
+    })();
+    const usesDatabase = persistence === "database";
+    // Capabilities to expose as typed onMessage handlers (everything past the
+    // 3 base methods: connect, subscribe, publish).
+    const allMethods = channel.interfaces[0]?.methods ?? [];
+    const baseMethodNames = new Set(["connect", "subscribe", "publish"]);
+    const capabilities = allMethods.filter(m => !baseMethodNames.has(m.name));
+    // Participant entity name (for typed param hints in capability signatures).
+    const participantEntity = channel.config["participant_entity"];
+    lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+    lines.push(`// Colyseus room for channel: ${channel.name}`);
+    lines.push(`// transport: ${channel.config["transport"] || "websocket"}`);
+    lines.push(`// ordering:  ${ordering}`);
+    lines.push(`// persistence: ${persistence}`);
+    if (capabilities.length > 0) {
+        lines.push(`// capabilities: ${capabilities.map(c => c.name).join(", ")}`);
+    }
+    lines.push(``);
+    lines.push(`import { Room, Client, ServerError, AuthContext } from "colyseus";`);
+    lines.push(`import { ${stateName}, ${playerName} } from "../state/${stateModule}";`);
+    lines.push(`import { verifyToken } from "../auth";`);
+    if (usesDatabase) {
+        lines.push(`import { loadSnapshot, saveSnapshot } from "../persistence";`);
+    }
+    lines.push(``);
+    lines.push(`interface AuthData {`);
+    lines.push(`  userId: string;`);
+    lines.push(`}`);
+    lines.push(``);
+    // Per-capability message payload interfaces. Lets handlers be type-safe.
+    for (const cap of capabilities) {
+        const inputs = cap.input.filter(i => {
+            if (!participantEntity)
+                return true;
+            // Drop the participant entity param itself — that's "the calling client",
+            // resolved from sessionId rather than wire payload.
+            return i.type !== participantEntity;
+        });
+        if (inputs.length === 0) {
+            lines.push(`type ${toPascalCase(cap.name)}Payload = Record<string, never>;`);
+        }
+        else {
+            lines.push(`interface ${toPascalCase(cap.name)}Payload {`);
+            for (const inp of inputs) {
+                lines.push(`  ${inp.name}: ${toTsTypeForSchema(inp.type)};`);
+            }
+            lines.push(`}`);
+        }
+    }
+    if (capabilities.length > 0)
+        lines.push(``);
+    lines.push(`/**`);
+    lines.push(` * Channel: ${channel.name}`);
+    lines.push(` *`);
+    lines.push(` * Client connection example:`);
+    lines.push(` *`);
+    lines.push(` *   import { Client } from "@colyseus/sdk";`);
+    lines.push(` *   const client = new Client("ws://host:2567");`);
+    lines.push(` *   client.auth.token = "<jwt>";`);
+    lines.push(` *   const room = await client.joinOrCreate("${channel.name}");`);
+    lines.push(` *   room.state.players.onAdd((player, key) => { ... });`);
+    if (capabilities.length > 0) {
+        lines.push(` *   room.send("${capabilities[0].name}", { ... });  // → triggers capability`);
+    }
+    lines.push(` */`);
+    lines.push(`export class ${roomName} extends Room<{ state: ${stateName} }> {`);
+    lines.push(`  maxClients = ${maxClients};`);
+    lines.push(``);
+    lines.push(`  // Ring buffer of recent messages, replayed to new joiners when persistence != "none".`);
+    lines.push(`  private history: { type: string; payload: unknown; from: string; ts: number }[] = [];`);
+    lines.push(`  private readonly historyLimit = ${historyLimit};`);
+    if (usesDatabase) {
+        lines.push(``);
+        lines.push(`  // Save a snapshot every ${SNAPSHOT_INTERVAL_MS}ms while the room is active.`);
+        lines.push(`  private snapshotTimer: NodeJS.Timeout | null = null;`);
+    }
+    lines.push(``);
+    lines.push(`  /**`);
+    lines.push(`   * JWT-based auth. Token comes from the Authorization header set by the`);
+    lines.push(`   * client SDK via \`client.auth.token = "..."\`.`);
+    lines.push(`   *`);
+    lines.push(`   * Returns the user data (userId) on success. Throws ServerError on bad`);
+    lines.push(`   * tokens so the matchmaking call fails on the client.`);
+    lines.push(`   */`);
+    lines.push(`  static async onAuth(token: string, _options: Record<string, unknown>, _context: AuthContext): Promise<AuthData> {`);
+    lines.push(`    if (!token) throw new ServerError(401, "Missing auth token");`);
+    lines.push(`    const claims = verifyToken(token);`);
+    lines.push(`    if (!claims) throw new ServerError(401, "Invalid auth token");`);
+    lines.push(`    return { userId: claims.sub };`);
+    lines.push(`  }`);
+    lines.push(``);
+    lines.push(`  async onCreate(_options: Record<string, unknown>) {`);
+    lines.push(`    this.setState(new ${stateName}());`);
+    if (usesDatabase) {
+        lines.push(``);
+        lines.push(`    // Try to restore snapshot from durable storage on room creation.`);
+        lines.push(`    try {`);
+        lines.push(`      const snapshot = await loadSnapshot("${channel.name}", this.roomId);`);
+        lines.push(`      if (snapshot && typeof snapshot === "object") {`);
+        lines.push(`        const s = this.state as unknown as Record<string, unknown>;`);
+        lines.push(`        for (const [k, v] of Object.entries(snapshot)) {`);
+        lines.push(`          if (k === "players") continue; // sessions are not portable`);
+        lines.push(`          if (k in s) (s as any)[k] = v;`);
+        lines.push(`        }`);
+        lines.push(`        console.log(\`[${channel.name}] restored snapshot for room \${this.roomId}\`);`);
+        lines.push(`      }`);
+        lines.push(`    } catch (e: any) {`);
+        lines.push(`      console.warn(\`[${channel.name}] snapshot load failed: \${e.message}\`);`);
+        lines.push(`    }`);
+        lines.push(``);
+        lines.push(`    // Periodically save state to durable storage so a crash doesn't lose work.`);
+        lines.push(`    this.snapshotTimer = setInterval(() => {`);
+        lines.push(`      void saveSnapshot("${channel.name}", this.roomId, this.serializeStateForSnapshot()).catch(() => {});`);
+        lines.push(`    }, ${SNAPSHOT_INTERVAL_MS});`);
+    }
+    // Register typed handlers for each capability
+    for (const cap of capabilities) {
+        lines.push(``);
+        lines.push(`    // ${cap.name} — capability dispatch`);
+        lines.push(`    this.onMessage("${cap.name}", (client, payload: ${toPascalCase(cap.name)}Payload) => {`);
+        lines.push(`      this.handle${toPascalCase(cap.name)}(client, payload);`);
+        lines.push(`    });`);
+    }
+    lines.push(``);
+    lines.push(`    // Default fallback: rebroadcast unknown messages with sender attribution.`);
+    lines.push(`    // Handlers for known message types above take precedence (Colyseus 0.17`);
+    lines.push(`    // routes "*" only when no specific handler matches).`);
+    lines.push(`    this.onMessage("*", (client, type, payload) => {`);
+    lines.push(`      const userId = (client.userData as { userId?: string } | undefined)?.userId ?? client.sessionId;`);
+    lines.push(`      const msg = { type: String(type), payload, from: userId, ts: Date.now() };`);
+    lines.push(`      this.recordHistory(msg);`);
+    lines.push(`      this.broadcast(String(type), msg, { except: client });`);
+    lines.push(`    });`);
+    lines.push(`  }`);
+    // Per-capability handler implementations. Each applies effects to the
+    // calling client's player record (or the room state) and broadcasts.
+    for (const cap of capabilities) {
+        lines.push(``);
+        lines.push(emitCapabilityHandler(cap, participantEntity, channel.name));
+    }
+    lines.push(``);
+    lines.push(`  onJoin(client: Client, _options: Record<string, unknown>, auth: AuthData) {`);
+    lines.push(`    client.userData = { userId: auth.userId };`);
+    lines.push(``);
+    lines.push(`    const player = new ${playerName}();`);
+    lines.push(`    player.userId = auth.userId;`);
+    lines.push(`    player.sessionId = client.sessionId;`);
+    lines.push(`    player.joinedAt = Date.now();`);
+    lines.push(`    this.state.players.set(client.sessionId, player);`);
+    lines.push(``);
+    lines.push(`    console.log(\`[${channel.name}] \${auth.userId} joined (\${this.clients.length} clients, sessionId=\${client.sessionId})\`);`);
+    lines.push(``);
+    lines.push(`    // Replay history if configured`);
+    lines.push(`    if (this.historyLimit > 0 && this.history.length > 0) {`);
+    lines.push(`      client.send("__history__", { events: this.history });`);
+    lines.push(`    }`);
+    lines.push(`  }`);
+    lines.push(``);
+    lines.push(`  onLeave(client: Client, _code: number) {`);
+    lines.push(`    this.state.players.delete(client.sessionId);`);
+    lines.push(`    const userId = (client.userData as { userId?: string } | undefined)?.userId ?? client.sessionId;`);
+    lines.push(`    console.log(\`[${channel.name}] \${userId} left (\${this.clients.length} clients)\`);`);
+    lines.push(`  }`);
+    lines.push(``);
+    lines.push(`  async onDispose() {`);
+    if (usesDatabase) {
+        lines.push(`    if (this.snapshotTimer) { clearInterval(this.snapshotTimer); this.snapshotTimer = null; }`);
+        lines.push(`    try {`);
+        lines.push(`      await saveSnapshot("${channel.name}", this.roomId, this.serializeStateForSnapshot());`);
+        lines.push(`      console.log(\`[${channel.name}] saved final snapshot for room \${this.roomId}\`);`);
+        lines.push(`    } catch (e: any) {`);
+        lines.push(`      console.warn(\`[${channel.name}] snapshot save failed: \${e.message}\`);`);
+        lines.push(`    }`);
+    }
+    lines.push(`    console.log(\`[${channel.name}] room disposed\`);`);
+    lines.push(`  }`);
+    lines.push(``);
+    lines.push(`  private recordHistory(msg: { type: string; payload: unknown; from: string; ts: number }) {`);
+    lines.push(`    if (this.historyLimit <= 0) return;`);
+    lines.push(`    this.history.push(msg);`);
+    lines.push(`    while (this.history.length > this.historyLimit) this.history.shift();`);
+    lines.push(`  }`);
+    if (usesDatabase) {
+        lines.push(``);
+        lines.push(`  /**`);
+        lines.push(`   * Snapshot the channel-wide state. We exclude the players map because`);
+        lines.push(`   * sessions don't persist across processes; players reconnect with new`);
+        lines.push(`   * sessionIds when the room is restored.`);
+        lines.push(`   */`);
+        lines.push(`  private serializeStateForSnapshot(): Record<string, unknown> {`);
+        lines.push(`    const out: Record<string, unknown> = {};`);
+        lines.push(`    for (const [k, v] of Object.entries(this.state as unknown as Record<string, unknown>)) {`);
+        lines.push(`      if (k === "players") continue;`);
+        lines.push(`      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {`);
+        lines.push(`        out[k] = v;`);
+        lines.push(`      }`);
+        lines.push(`    }`);
+        lines.push(`    return out;`);
+        lines.push(`  }`);
+    }
+    lines.push(`}`);
+    lines.push(``);
+    return {
+        path: `src/rooms/${stateModule}.ts`,
+        content: lines.join("\n"),
+        language: "typescript",
+        source_module: channel.id,
+    };
+}
+const SNAPSHOT_INTERVAL_MS = 5000;
+/**
+ * Emit a capability handler.
+ *
+ * Translates IR effects to TypeScript that mutates the calling client's
+ * player record (or the room state) and broadcasts the result. Effects
+ * targeting `<participantParam>.<field>` map to the player; everything
+ * else maps to room state.
+ *
+ * Only `assign` op is fully supported in Phase 2. `add` / `remove` on
+ * scalars work for numbers; `add` on collections falls back to broadcasting
+ * a hint without mutating state (left as TODO with a comment).
+ */
+function emitCapabilityHandler(method, participantEntity, channelName) {
+    const lines = [];
+    const handlerName = `handle${toPascalCase(method.name)}`;
+    const payloadType = `${toPascalCase(method.name)}Payload`;
+    // Find the participant param name (used to discriminate state vs player effects).
+    const partParam = method.input.find(i => i.type === participantEntity);
+    const partParamName = partParam?.name ?? null;
+    lines.push(`  /**`);
+    lines.push(`   * Handle "${method.name}" capability message.`);
+    if (method.preconditions.length > 0) {
+        lines.push(`   *`);
+        lines.push(`   * Preconditions:`);
+        for (const pre of method.preconditions)
+            lines.push(`   *   - ${pre.expression}`);
+    }
+    if (method.effects.length > 0) {
+        lines.push(`   *`);
+        lines.push(`   * Effects:`);
+        for (const eff of method.effects) {
+            const opSym = eff.op === "assign" ? "=" : eff.op === "add" ? "+=" : "-=";
+            lines.push(`   *   - ${eff.target} ${opSym} ${eff.value}`);
+        }
+    }
+    lines.push(`   */`);
+    lines.push(`  private ${handlerName}(client: Client, payload: ${payloadType}): void {`);
+    lines.push(`    const player = this.state.players.get(client.sessionId);`);
+    lines.push(`    if (!player) return;`);
+    // Compile preconditions to runtime checks. Best-effort: we only check
+    // simple expressions referring to the participant or payload params.
+    if (method.preconditions.length > 0) {
+        lines.push(`    // Preconditions`);
+        for (const pre of method.preconditions) {
+            const expr = compileExprForRoom(pre.expression, partParamName, method.input);
+            if (expr) {
+                lines.push(`    if (!(${expr})) {`);
+                lines.push(`      client.send("${method.name}_failed", { reason: "precondition: ${escapeStringLiteral(pre.description)}" });`);
+                lines.push(`      return;`);
+                lines.push(`    }`);
+            }
+        }
+    }
+    // Compile effects
+    for (const eff of method.effects) {
+        const compiled = compileEffectForRoom(eff, partParamName, method.input);
+        if (compiled) {
+            lines.push(`    ${compiled}`);
+        }
+        else {
+            lines.push(`    // TODO: effect "${eff.target} ${eff.op} ${eff.value}" — not auto-translated`);
+        }
+    }
+    // Broadcast the resulting change to all clients (including sender so they
+    // see authoritative state). Colyseus's @type system already syncs state
+    // diffs, so this broadcast is just for clients listening to the explicit
+    // "<capability>_applied" event for animation cues etc.
+    lines.push(`    this.broadcast("${method.name}_applied", { from: player.userId, payload });`);
+    lines.push(`  }`);
+    void channelName;
+    return lines.join("\n");
+}
+/**
+ * Compile an effect expression to a TS statement that mutates state or player.
+ *
+ * Supported targets:
+ *   <partParam>.<field>           → player.<field>  (calling client's player)
+ *   <field>                        → this.state.<field>  (room-wide state)
+ *   <some-other-entity>.<field>    → not auto-translated; returns null
+ *
+ * Supported values:
+ *   identifier matching a payload param name → payload.<name>
+ *   number / string / bool literal           → as-is
+ *   simple binary expr referencing scalars   → translated by compileExprForRoom
+ */
+function compileEffectForRoom(eff, partParamName, inputs) {
+    const path = eff.target.split(".");
+    let lhs;
+    if (path.length === 2 && partParamName && path[0] === partParamName) {
+        lhs = `player.${path[1]}`;
+    }
+    else if (path.length === 1) {
+        lhs = `(this.state as any).${path[0]}`;
+    }
+    else {
+        return null; // can't safely translate cross-entity effects
+    }
+    const rhs = compileExprForRoom(eff.value, partParamName, inputs) ?? `(payload as any).${eff.value}`;
+    switch (eff.op) {
+        case "assign": return `${lhs} = ${rhs};`;
+        case "add": return `${lhs} = (${lhs} as number) + (${rhs} as number);`;
+        case "remove": return `${lhs} = (${lhs} as number) - (${rhs} as number);`;
+    }
+}
+/**
+ * Compile an IR expression string to a TS expression usable inside a room
+ * handler. Best-effort — we recognise:
+ *   - the participant param name → `player`
+ *   - any payload input name → `payload.<name>`
+ *   - bare identifiers we can't resolve → null (caller falls back)
+ *   - simple binary expressions like "x > 0", "qty <= player.capacity"
+ *
+ * For complex expressions involving function calls, returns the original
+ * expression unchanged. If that fails to compile, the user gets a tsc
+ * error pointing at the generated code; better than silent wrong behaviour.
+ */
+function compileExprForRoom(expr, partParamName, inputs) {
+    const trimmed = expr.trim();
+    // Number literal
+    if (/^-?\d+(\.\d+)?$/.test(trimmed))
+        return trimmed;
+    // String literal
+    if (/^"[^"]*"$/.test(trimmed))
+        return trimmed;
+    // Boolean
+    if (trimmed === "true" || trimmed === "false")
+        return trimmed;
+    // Replace identifiers with their compiled form.
+    // We do a simple word-boundary substitution which is safe for the
+    // expressions we generate (no shadowing, no string contents to worry about).
+    const inputNames = new Set(inputs.map(i => i.name));
+    const partOk = partParamName && partParamName.length > 0;
+    let out = trimmed;
+    // <partParam>.<field> → player.<field>
+    if (partOk) {
+        const re = new RegExp(`\\b${partParamName}\\.(\\w+)`, "g");
+        out = out.replace(re, "player.$1");
+    }
+    // <payloadParam>.<x> or <payloadParam> → payload.<...>
+    for (const inp of inputs) {
+        if (partOk && inp.name === partParamName)
+            continue;
+        const re = new RegExp(`\\b${inp.name}\\b`, "g");
+        out = out.replace(re, `(payload as any).${inp.name}`);
+    }
+    // If after substitution we still have bare identifiers we don't recognise,
+    // we leave them in — tsc will flag them at compile time so the user can
+    // fix the .bone source.
+    void inputNames;
+    return out;
+}
+function escapeStringLiteral(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+// ─── Auth helper (JWT verification) ───────────────────────────────────────────
+function emitColyseusAuth() {
+    return [
+        `// Generated by BoneScript compiler. DO NOT EDIT.`,
+        `// JWT verification helper. Mirrors the Express target's auth.ts: HS256-only,`,
+        `// 1h max-age cap, sub must be a non-empty string.`,
+        ``,
+        `import jwt from "jsonwebtoken";`,
+        ``,
+        `const JWT_SECRET = (() => {`,
+        `  const secret = process.env.JWT_SECRET;`,
+        `  if (!secret) {`,
+        `    if (process.env.NODE_ENV === "production") {`,
+        `      console.error("[FATAL] JWT_SECRET is not set. Refusing to start in production.");`,
+        `      process.exit(1);`,
+        `    }`,
+        `    console.warn("[WARN] JWT_SECRET is not set. Using insecure default — do not use in production.");`,
+        `    return "bonescript-dev-secret-do-not-use-in-production";`,
+        `  }`,
+        `  if (secret.length < 32) {`,
+        `    console.warn("[WARN] JWT_SECRET is shorter than 32 characters.");`,
+        `  }`,
+        `  return secret;`,
+        `})();`,
+        ``,
+        `export interface JwtClaims {`,
+        `  sub: string;`,
+        `}`,
+        ``,
+        `export function verifyToken(token: string): JwtClaims | null {`,
+        `  try {`,
+        `    const decoded = jwt.verify(token, JWT_SECRET, {`,
+        `      algorithms: ["HS256"],`,
+        `      maxAge: process.env.JWT_MAX_AGE || "1h",`,
+        `    }) as { sub?: unknown };`,
+        `    if (typeof decoded.sub !== "string" || decoded.sub.length === 0) return null;`,
+        `    return { sub: decoded.sub };`,
+        `  } catch {`,
+        `    return null;`,
+        `  }`,
+        `}`,
+        ``,
+    ].join("\n");
+}
+function emitColyseusPersistence() {
+    // Filesystem-based snapshot store. Default location: ./snapshots/<channel>/<roomId>.json.
+    // Override SNAPSHOT_DIR env var. To swap in a real DB (Postgres, Redis,
+    // etc.), replace the body of loadSnapshot/saveSnapshot — the interface
+    // is intentionally minimal.
+    return [
+        `// Generated by BoneScript compiler. DO NOT EDIT.`,
+        `// Snapshot persistence for rooms with \`persistence: database\`.`,
+        `//`,
+        `// Default implementation: JSON files under SNAPSHOT_DIR (./snapshots).`,
+        `// Replace with your DB / Redis / object store as needed — the only`,
+        `// contract is loadSnapshot/saveSnapshot returning Promise<unknown | null>.`,
+        ``,
+        `import * as fs from "fs/promises";`,
+        `import * as path from "path";`,
+        ``,
+        `const ROOT = path.resolve(process.env.SNAPSHOT_DIR || "./snapshots");`,
+        ``,
+        `function snapshotPath(channel: string, roomId: string): string {`,
+        `  // Filenames are limited to a safe character set so a malicious roomId`,
+        `  // can't escape the snapshot dir. Colyseus roomIds are alphanumeric so`,
+        `  // this is belt-and-braces.`,
+        `  const safeChannel = channel.replace(/[^a-zA-Z0-9_-]/g, "_");`,
+        `  const safeRoom = roomId.replace(/[^a-zA-Z0-9_-]/g, "_");`,
+        `  return path.join(ROOT, safeChannel, safeRoom + ".json");`,
+        `}`,
+        ``,
+        `export async function loadSnapshot(channel: string, roomId: string): Promise<unknown | null> {`,
+        `  const file = snapshotPath(channel, roomId);`,
+        `  try {`,
+        `    const data = await fs.readFile(file, "utf-8");`,
+        `    return JSON.parse(data);`,
+        `  } catch (e: any) {`,
+        `    if (e.code === "ENOENT") return null;`,
+        `    throw e;`,
+        `  }`,
+        `}`,
+        ``,
+        `export async function saveSnapshot(channel: string, roomId: string, state: unknown): Promise<void> {`,
+        `  const file = snapshotPath(channel, roomId);`,
+        `  await fs.mkdir(path.dirname(file), { recursive: true });`,
+        `  // Write to a temp file then rename — atomic on POSIX, near-atomic on Windows.`,
+        `  const tmp = file + ".tmp";`,
+        `  await fs.writeFile(tmp, JSON.stringify(state, null, 2), "utf-8");`,
+        `  await fs.rename(tmp, file);`,
+        `}`,
+        ``,
+        `export async function deleteSnapshot(channel: string, roomId: string): Promise<void> {`,
+        `  const file = snapshotPath(channel, roomId);`,
+        `  try { await fs.unlink(file); } catch { /* swallow */ }`,
+        `}`,
+        ``,
+    ].join("\n");
+}
+// ─── Server entry point ───────────────────────────────────────────────────────
+function emitColyseusIndex(system) {
+    const channels = system.modules.filter(m => m.kind === "realtime_service");
+    const lines = [];
+    lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+    lines.push(`// Colyseus server entry point.`);
+    lines.push(``);
+    lines.push(`require("dotenv").config();`);
+    lines.push(`import { Server } from "colyseus";`);
+    lines.push(`import { WebSocketTransport } from "@colyseus/ws-transport";`);
+    lines.push(`import { createServer } from "http";`);
+    for (const ch of channels) {
+        const stateModule = toSnakeCase(ch.name);
+        const roomName = `${toPascalCase(ch.name)}Room`;
+        lines.push(`import { ${roomName} } from "./rooms/${stateModule}";`);
+    }
+    lines.push(``);
+    lines.push(`const PORT = parseInt(process.env.PORT || "2567", 10);`);
+    lines.push(``);
+    lines.push(`const httpServer = createServer();`);
+    lines.push(`const gameServer = new Server({`);
+    lines.push(`  transport: new WebSocketTransport({ server: httpServer }),`);
+    lines.push(`});`);
+    lines.push(``);
+    for (const ch of channels) {
+        const roomName = `${toPascalCase(ch.name)}Room`;
+        lines.push(`gameServer.define("${ch.name}", ${roomName});`);
+    }
+    lines.push(``);
+    lines.push(`gameServer.listen(PORT).then(() => {`);
+    lines.push(`  console.log(\`[${system.name}] Colyseus listening on ws://localhost:\${PORT}\`);`);
+    for (const ch of channels) {
+        lines.push(`  console.log(\`  - room: ${ch.name}\`);`);
+    }
+    lines.push(`});`);
+    lines.push(``);
+    lines.push(`process.on("SIGTERM", () => { gameServer.gracefullyShutdown().then(() => process.exit(0)); });`);
+    lines.push(`process.on("SIGINT", () => { gameServer.gracefullyShutdown().then(() => process.exit(0)); });`);
+    lines.push(``);
+    return lines.join("\n");
+}
+// ─── Package config ──────────────────────────────────────────────────────────
+function emitColyseusPackageJson(system) {
+    return JSON.stringify({
+        name: toSnakeCase(system.name),
+        version: system.version,
+        private: true,
+        scripts: {
+            build: "tsc",
+            start: "node dist/index.js",
+            dev: "ts-node src/index.ts",
+        },
+        dependencies: {
+            // Pinned to known-working 0.17.x minor versions. These are the line
+            // Colyseus moved to in 2026; @colyseus/schema is now 4.x. Bump together.
+            colyseus: "^0.17.10",
+            "@colyseus/schema": "^4.0.25",
+            "@colyseus/ws-transport": "^0.17.13",
+            jsonwebtoken: "9.0.2",
+            dotenv: "16.4.7",
+        },
+        devDependencies: {
+            "@types/node": "20.14.0",
+            "@types/jsonwebtoken": "9.0.7",
+            typescript: "5.6.3",
+            "ts-node": "10.9.2",
+            // Tests / clients use the new SDK package name.
+            "@colyseus/sdk": "^0.17.42",
+        },
+    }, null, 2);
+}
+function emitColyseusTsConfig() {
+    // Colyseus schemas use class decorators; experimentalDecorators is required
+    // for @type to register at runtime.
+    return JSON.stringify({
+        compilerOptions: {
+            target: "ES2020",
+            module: "commonjs",
+            lib: ["ES2020"],
+            outDir: "./dist",
+            rootDir: "./src",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            experimentalDecorators: true,
+            emitDecoratorMetadata: true,
+            forceConsistentCasingInFileNames: true,
+            declaration: true,
+            sourceMap: true,
+        },
+        include: ["src/**/*"],
+        exclude: ["node_modules", "dist"],
+    }, null, 2);
+}
+function emitColyseusReadme(system) {
+    const channels = system.modules.filter(m => m.kind === "realtime_service");
+    const channelDocs = channels.length === 0
+        ? "_No channels declared._"
+        : channels.map(c => `- \`${c.name}\` (max ${c.config["max_size"] ?? 16} clients, ${c.config["persistence"] ?? "none"})`).join("\n");
+    return `# ${system.name} (Colyseus target)
+
+Generated by BoneScript compiler. Source hash: ${system.source_hash}
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+The server listens on \`ws://localhost:2567\` by default. Set \`PORT\` to change.
+Set \`JWT_SECRET\` to your token-signing secret; \`onAuth\` enforces HS256 + 1h max-age.
+
+## Rooms
+
+${channelDocs}
+
+## Client example
+
+\`\`\`typescript
+import { Client } from "@colyseus/sdk";
+
+const client = new Client("ws://localhost:2567");
+client.auth.token = "<jwt>"; // signed with JWT_SECRET, alg HS256, sub = user id
+const room = await client.joinOrCreate("${channels[0]?.name ?? "lobby"}");
+
+room.state.players.onAdd((player, key) => {
+  console.log("player joined:", player.userId);
+});
+
+room.send("chat", { text: "hello" });
+\`\`\`
+
+## What this target generates
+
+- One \`Room\` subclass per channel (\`src/rooms/\`)
+- One \`Schema\` state class per channel (\`src/state/\`)
+- JWT auth helper (\`src/auth.ts\`) — same algorithm pinning as the Express target
+- A Colyseus \`Server\` bootstrap (\`src/index.ts\`) that registers all rooms
+
+## What this target does NOT generate
+
+- HTTP REST routes — use the default Express target alongside this
+- Persistence to a database — the room state lives in memory; bridge to your
+  own DB or compile the Express target separately for CRUD
+- Lobby matchmaking beyond \`joinOrCreate\` — see the
+  [Colyseus matchmaking guide](https://docs.colyseus.io/matchmaker)
+  for advanced patterns
+`;
+}
+// ─── Top-level emitter ────────────────────────────────────────────────────────
+class ColyseusEmitter {
+    emit(system) {
+        const files = [];
+        const channels = system.modules.filter(m => m.kind === "realtime_service");
+        files.push({ path: "package.json", content: emitColyseusPackageJson(system), language: "json", source_module: "root" });
+        files.push({ path: "tsconfig.json", content: emitColyseusTsConfig(), language: "json", source_module: "root" });
+        files.push({ path: "README.md", content: emitColyseusReadme(system), language: "yaml", source_module: "root" });
+        files.push({ path: ".env.example", content: this.emitEnvExample(), language: "yaml", source_module: "root" });
+        files.push({ path: "src/auth.ts", content: emitColyseusAuth(), language: "typescript", source_module: "infra" });
+        files.push({ path: "src/index.ts", content: emitColyseusIndex(system), language: "typescript", source_module: "root" });
+        // Emit the persistence bridge only when at least one channel needs it.
+        const needsPersistence = channels.some(c => c.config["persistence"] === "database");
+        if (needsPersistence) {
+            files.push({
+                path: "src/persistence.ts",
+                content: emitColyseusPersistence(),
+                language: "typescript",
+                source_module: "infra",
+            });
+        }
+        for (const ch of channels) {
+            files.push(emitStateSchema(ch, system));
+            files.push(emitRoom(ch, system));
+        }
+        return files;
+    }
+    emitEnvExample() {
+        return `# JWT verification secret. Required in production.
+# Generate with: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+JWT_SECRET=
+
+# Colyseus server port (default 2567).
+PORT=2567
+
+NODE_ENV=development
+`;
+    }
+}
+exports.ColyseusEmitter = ColyseusEmitter;
+//# sourceMappingURL=emit_colyseus.js.map