so-called-expert 0.0.0-stage → 0.1.0

package/src/game.js

@@ -0,0 +1,376 @@
+// The authoritative game state machine. It knows nothing about sockets or
+// terminals: the server feeds it messages and broadcasts `viewFor(player)`.
+import { EventEmitter } from 'node:events';
+import { normalize, similar, clean } from './text.js';
+
+export const DEFAULTS = {
+  questionsPerSubject: 5,
+  pickMs: 90_000,
+  introMs: 12_000,
+  questionMs: 30_000,
+  revealMs: 12_000,
+  basePoints: 100, // points for the first (easiest) question
+  stepPoints: 50, // extra points per difficulty step
+  guestMultiplier: 1.5, // non-experts earn this multiple
+  fraudPenalty: 0.5, // experts lose this fraction when wrong on their own subject
+  maxPlayers: 12,
+  generateConcurrency: 4,
+};
+
+export function pointsFor(settings, questionIndex) {
+  return settings.basePoints + settings.stepPoints * questionIndex;
+}
+
+function shuffle(list) {
+  const a = [...list];
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}
+
+export class Game extends EventEmitter {
+  constructor({ ai, settings = {} }) {
+    super();
+    this.ai = ai;
+    this.settings = { ...DEFAULTS, ...settings };
+    this.players = new Map();
+    this.phase = 'lobby';
+    this.join = null;
+    this.notice = null;
+    this.epoch = 0;
+    this.timer = null;
+    this.onTimeout = null;
+    this.deadline = null;
+    this.subjects = [];
+    this.gen = [];
+    this.si = 0;
+    this.qi = 0;
+    this.answers = new Map();
+    this.reveal = null;
+  }
+
+  // ---- connections -------------------------------------------------------
+
+  connect(id, rawName, isHost) {
+    const existing = this.players.get(id);
+    if (existing) {
+      existing.online = true;
+      this.changed();
+      return {};
+    }
+    if (this.phase !== 'lobby') return { error: 'That game has already started.' };
+    if (this.players.size >= this.settings.maxPlayers) return { error: 'That game is full.' };
+    let name = clean(rawName, 20) || 'Player';
+    const taken = (n) => [...this.players.values()].some((p) => p.name.toLowerCase() === n.toLowerCase());
+    for (let i = 2; taken(name); i++) name = `${clean(rawName, 20) || 'Player'} ${i}`;
+    this.players.set(id, { id, name, isHost: !!isHost, online: true, score: 0, subject: null, own: [0, 0] });
+    this.changed();
+    return {};
+  }
+
+  disconnect(id) {
+    const p = this.players.get(id);
+    if (!p) return;
+    if (this.phase === 'lobby' && !p.isHost) this.players.delete(id);
+    else p.online = false;
+    this.checkProgress();
+    this.changed();
+  }
+
+  setJoinInfo(join) {
+    this.join = join;
+    this.changed();
+  }
+
+  // ---- incoming messages -------------------------------------------------
+
+  handle(id, msg) {
+    const p = this.players.get(id);
+    if (!p || !msg || typeof msg.t !== 'string') return {};
+    switch (msg.t) {
+      case 'start':
+        if (p.isHost && this.phase === 'lobby') this.startPick();
+        return {};
+      case 'pick': {
+        if (this.phase !== 'pick' || p.subject) return {};
+        const subject = clean(msg.subject, 80);
+        if (!subject) return {};
+        const key = normalize(subject);
+        if ([...this.players.values()].some((o) => o.subject && normalize(o.subject) === key)) {
+          return { error: 'Someone already claimed that subject. Go more niche.' };
+        }
+        p.subject = subject;
+        this.changed();
+        this.checkProgress();
+        return {};
+      }
+      case 'answer': {
+        if (this.phase !== 'question' || this.answers.has(id)) return {};
+        this.answers.set(id, clean(msg.text, 120));
+        this.changed();
+        this.checkProgress();
+        return {};
+      }
+      case 'skip':
+        if (p.isHost && (this.phase === 'intro' || this.phase === 'reveal') && this.onTimeout) this.onTimeout();
+        return {};
+      case 'again':
+        if (p.isHost && this.phase === 'final') this.toLobby(null);
+        return {};
+      default:
+        return {};
+    }
+  }
+
+  // ---- phases ------------------------------------------------------------
+
+  changed() {
+    this.emit('change');
+  }
+
+  setPhase(phase, ms, onTimeout) {
+    clearTimeout(this.timer);
+    this.epoch++;
+    this.phase = phase;
+    this.timer = null;
+    this.deadline = null;
+    this.onTimeout = null;
+    if (ms != null) {
+      const epoch = this.epoch;
+      this.onTimeout = () => {
+        if (epoch === this.epoch) onTimeout();
+      };
+      this.deadline = Date.now() + ms;
+      this.timer = setTimeout(this.onTimeout, ms);
+    }
+    this.changed();
+  }
+
+  online() {
+    return [...this.players.values()].filter((p) => p.online);
+  }
+
+  checkProgress() {
+    const online = this.online();
+    if (!online.length) return;
+    if (this.phase === 'pick' && online.every((p) => p.subject)) this.startGenerating();
+    else if (this.phase === 'question' && online.every((p) => this.answers.has(p.id))) this.closeQuestion();
+  }
+
+  toLobby(notice) {
+    for (const p of [...this.players.values()]) {
+      if (!p.online && !p.isHost) this.players.delete(p.id);
+      p.score = 0;
+      p.subject = null;
+      p.own = [0, 0];
+    }
+    this.subjects = [];
+    this.gen = [];
+    this.reveal = null;
+    this.notice = notice;
+    this.setPhase('lobby');
+  }
+
+  startPick() {
+    this.notice = null;
+    for (const p of this.players.values()) {
+      p.score = 0;
+      p.subject = null;
+      p.own = [0, 0];
+    }
+    this.setPhase('pick', this.settings.pickMs, () => this.startGenerating());
+  }
+
+  async startGenerating() {
+    const pickers = [...this.players.values()].filter((p) => p.subject);
+    if (!pickers.length) return this.toLobby('Nobody picked a subject, so the game was called off.');
+    this.gen = pickers.map((p) => ({ ownerId: p.id, status: 'working' }));
+    this.setPhase('generating');
+    const epoch = this.epoch;
+    const n = this.settings.questionsPerSubject;
+    let lastError = null;
+    const results = new Array(pickers.length).fill(null);
+    let next = 0;
+    const worker = async () => {
+      while (next < pickers.length) {
+        const i = next++;
+        const p = pickers[i];
+        for (let attempt = 0; attempt < 2 && !results[i]; attempt++) {
+          try {
+            results[i] = validateSubject(await this.ai.generateSubject(p.subject, n), p, n);
+          } catch (err) {
+            lastError = err;
+          }
+        }
+        if (epoch !== this.epoch) return;
+        this.gen[i].status = results[i] ? 'done' : 'failed';
+        this.changed();
+      }
+    };
+    await Promise.all(Array.from({ length: this.settings.generateConcurrency }, worker));
+    if (epoch !== this.epoch) return;
+    this.subjects = shuffle(results.filter(Boolean));
+    if (!this.subjects.length) {
+      return this.toLobby(`Claude could not write any questions (${lastError?.message ?? 'unknown error'}).`);
+    }
+    this.startIntro(0);
+  }
+
+  startIntro(si) {
+    this.si = si;
+    this.qi = 0;
+    this.reveal = null;
+    this.setPhase('intro', this.settings.introMs, () => this.startQuestion(0));
+  }
+
+  startQuestion(qi) {
+    this.qi = qi;
+    this.answers = new Map();
+    this.reveal = null;
+    this.setPhase('question', this.settings.questionMs, () => this.closeQuestion());
+  }
+
+  async closeQuestion() {
+    if (this.phase !== 'question') return;
+    this.setPhase('judging');
+    const epoch = this.epoch;
+    const subject = this.subjects[this.si];
+    const q = subject.questions[this.qi];
+    const players = [...this.players.values()];
+    const verdicts = await this.judge(subject, q, players.map((p) => this.answers.get(p.id) ?? ''));
+    if (epoch !== this.epoch) return;
+
+    const x = pointsFor(this.settings, this.qi);
+    const results = players.map((p, i) => {
+      const isExpert = p.id === subject.ownerId;
+      const correct = verdicts[i];
+      let delta = 0;
+      if (correct) delta = isExpert ? x : Math.round(x * this.settings.guestMultiplier);
+      else if (isExpert) delta = -Math.round(x * this.settings.fraudPenalty);
+      p.score += delta;
+      if (isExpert) {
+        p.own[1]++;
+        if (correct) p.own[0]++;
+      }
+      return { id: p.id, answer: this.answers.get(p.id) ?? '', correct, delta, isExpert };
+    });
+    this.reveal = { answer: q.answer, explanation: q.explanation, results };
+    this.setPhase('reveal', this.settings.revealMs, () => this.advance());
+  }
+
+  /** Returns one boolean per answer. Obvious cases are settled locally. */
+  async judge(subject, q, texts) {
+    const accepted = [q.answer, ...(q.accept ?? [])].map(normalize).filter(Boolean);
+    const verdictByKey = new Map();
+    const pending = [];
+    for (const text of texts) {
+      const key = normalize(text);
+      if (verdictByKey.has(key)) continue;
+      if (!key) verdictByKey.set(key, false);
+      else if (accepted.includes(key)) verdictByKey.set(key, true);
+      else {
+        verdictByKey.set(key, null);
+        pending.push({ key, text });
+      }
+    }
+    if (pending.length) {
+      let judged = null;
+      try {
+        judged = await this.ai.judge({ subject: subject.title, ...q }, pending.map((p) => p.text));
+      } catch {
+        // Fall back to typo-tolerant matching if the judge is unavailable.
+      }
+      pending.forEach((p, i) => {
+        const v = judged ? !!judged[i] : accepted.some((a) => similar(a, p.key));
+        verdictByKey.set(p.key, v);
+      });
+    }
+    return texts.map((t) => verdictByKey.get(normalize(t)));
+  }
+
+  advance() {
+    const subject = this.subjects[this.si];
+    if (this.qi + 1 < subject.questions.length) this.startQuestion(this.qi + 1);
+    else if (this.si + 1 < this.subjects.length) this.startIntro(this.si + 1);
+    else this.setPhase('final');
+  }
+
+  // ---- what a given player is allowed to see ------------------------------
+
+  viewFor(id) {
+    const s = this.settings;
+    const subject = this.subjects[this.si];
+    const inRound = ['intro', 'question', 'judging', 'reveal'].includes(this.phase) && subject;
+    const owner = inRound ? this.players.get(subject.ownerId) : null;
+    const view = {
+      phase: this.phase,
+      you: id,
+      remainingMs: this.deadline ? Math.max(0, this.deadline - Date.now()) : null,
+      totalMs: { pick: s.pickMs, intro: s.introMs, question: s.questionMs, reveal: s.revealMs }[this.phase] ?? null,
+      notice: this.notice,
+      rules: { guestMultiplier: s.guestMultiplier, fraudPenalty: s.fraudPenalty, questionsPerSubject: s.questionsPerSubject },
+      players: [...this.players.values()].map((p) => ({
+        id: p.id,
+        name: p.name,
+        isHost: p.isHost,
+        online: p.online,
+        score: p.score,
+        own: p.own,
+        done: this.phase === 'pick' ? !!p.subject : this.phase === 'question' ? this.answers.has(p.id) : false,
+      })),
+    };
+    if (this.phase === 'lobby') view.join = this.join;
+    if (this.phase === 'pick') view.yourPick = this.players.get(id)?.subject ?? null;
+    if (this.phase === 'generating') view.gen = this.gen;
+    if (inRound) {
+      view.subject = {
+        index: this.si,
+        total: this.subjects.length,
+        title: subject.title,
+        picked: subject.picked,
+        description: subject.description,
+        ownerId: subject.ownerId,
+        ownerName: owner?.name ?? 'Someone',
+        questionCount: subject.questions.length,
+        minPoints: pointsFor(s, 0),
+        maxPoints: pointsFor(s, subject.questions.length - 1),
+      };
+    }
+    if (inRound && this.phase !== 'intro') {
+      view.question = {
+        index: this.qi,
+        total: subject.questions.length,
+        text: subject.questions[this.qi].question,
+        points: pointsFor(s, this.qi),
+        yourAnswer: this.answers.has(id) ? this.answers.get(id) : null,
+      };
+    }
+    if (this.phase === 'reveal') view.reveal = this.reveal;
+    if (this.phase === 'final') {
+      view.subjects = this.subjects.map((sub) => ({ title: sub.title, ownerId: sub.ownerId }));
+    }
+    return view;
+  }
+}
+
+function validateSubject(raw, player, n) {
+  const questions = (Array.isArray(raw?.questions) ? raw.questions : [])
+    .filter((q) => q && typeof q.question === 'string' && typeof q.answer === 'string' && q.question.trim() && q.answer.trim())
+    .slice(0, n)
+    .map((q) => ({
+      question: clean(q.question, 400),
+      answer: clean(q.answer, 120),
+      accept: (Array.isArray(q.accept) ? q.accept : []).filter((a) => typeof a === 'string').map((a) => clean(a, 120)),
+      explanation: clean(q.explanation, 300),
+    }));
+  if (!questions.length) throw new Error('no usable questions were generated');
+  return {
+    ownerId: player.id,
+    picked: player.subject,
+    title: clean(raw.title, 80) || player.subject,
+    description: clean(raw.description, 400),
+    questions,
+  };
+}

package/src/server.js

@@ -0,0 +1,110 @@
+// WebSocket server the host runs. Guests (and the host's own UI) connect here.
+import http from 'node:http';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import { WebSocketServer } from 'ws';
+
+export async function startServer({ game, port = 4242, hostKey }) {
+  const server = http.createServer((req, res) => {
+    res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('This is a So-Called Expert game server.\nJoin from a terminal with: npx so-called-expert join <code>\n');
+  });
+  const wss = new WebSocketServer({ server, maxPayload: 16 * 1024 });
+  const sockets = new Map(); // player id -> ws
+  const idByToken = new Map(); // secret client token -> public player id
+
+  const send = (ws, msg) => {
+    if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(msg));
+  };
+
+  game.on('change', () => {
+    for (const [id, ws] of sockets) send(ws, { t: 'state', view: game.viewFor(id) });
+  });
+
+  wss.on('connection', (ws) => {
+    let id = null;
+    ws.isAlive = true;
+    ws.on('pong', () => (ws.isAlive = true));
+    ws.on('error', () => {});
+    ws.on('message', (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw.toString());
+      } catch {
+        return;
+      }
+      if (!msg || typeof msg !== 'object') return;
+      if (msg.t === 'hello') {
+        if (id || typeof msg.token !== 'string' || msg.token.length < 16 || msg.token.length > 64) return;
+        const pid = idByToken.get(msg.token) ?? crypto.randomBytes(4).toString('hex');
+        const result = game.connect(pid, msg.name, !!hostKey && msg.hostKey === hostKey);
+        if (result.error) {
+          send(ws, { t: 'error', message: result.error, fatal: true });
+          return ws.close();
+        }
+        idByToken.set(msg.token, pid);
+        const old = sockets.get(pid);
+        id = pid;
+        sockets.set(pid, ws);
+        if (old && old !== ws) old.close();
+        send(ws, { t: 'state', view: game.viewFor(pid) });
+      } else if (id) {
+        const result = game.handle(id, msg);
+        if (result?.error) send(ws, { t: 'error', message: result.error });
+      }
+    });
+    ws.on('close', () => {
+      if (id && sockets.get(id) === ws) {
+        sockets.delete(id);
+        game.disconnect(id);
+      }
+    });
+  });
+
+  // Keeps tunnel connections warm and notices players whose connection died.
+  const heartbeat = setInterval(() => {
+    for (const ws of wss.clients) {
+      if (!ws.isAlive) {
+        ws.terminate();
+        continue;
+      }
+      ws.isAlive = false;
+      ws.ping();
+    }
+  }, 15_000);
+  heartbeat.unref();
+
+  const listen = (p) =>
+    new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(p, () => {
+        server.removeListener('error', reject);
+        resolve();
+      });
+    });
+  try {
+    await listen(port);
+  } catch (err) {
+    if (err.code !== 'EADDRINUSE') throw err;
+    await listen(0); // preferred port is busy: let the OS choose one
+  }
+
+  return {
+    port: server.address().port,
+    close() {
+      clearInterval(heartbeat);
+      for (const ws of wss.clients) ws.terminate();
+      server.close();
+    },
+  };
+}
+
+/** First non-internal IPv4 address, for same-network joins. */
+export function lanAddress() {
+  for (const list of Object.values(os.networkInterfaces())) {
+    for (const addr of list ?? []) {
+      if (addr.family === 'IPv4' && !addr.internal) return addr.address;
+    }
+  }
+  return null;
+}

package/src/text.js

@@ -0,0 +1,83 @@
+// Small text helpers shared by the game engine and the terminal UI.
+
+/** Lowercase, strip accents/punctuation/leading articles, collapse whitespace. */
+export function normalize(s) {
+  return String(s ?? '')
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/^(the|a|an) /, '');
+}
+
+export function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+/** Typo-tolerant comparison of two already-normalized strings. */
+export function similar(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  const longest = Math.max(a.length, b.length);
+  if (longest < 5) return false;
+  return levenshtein(a, b) / longest <= 0.2;
+}
+
+/** Word-wrap plain text (no ANSI codes) to the given width. */
+export function wrap(text, width) {
+  const out = [];
+  for (const para of String(text ?? '').split('\n')) {
+    let line = '';
+    for (let word of para.split(/\s+/).filter(Boolean)) {
+      while (word.length > width) {
+        if (line) { out.push(line); line = ''; }
+        out.push(word.slice(0, width));
+        word = word.slice(width);
+      }
+      if (!line) line = word;
+      else if (line.length + 1 + word.length <= width) line += ' ' + word;
+      else { out.push(line); line = word; }
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+/** Remove control characters and trim to a maximum length. */
+export function clean(s, max) {
+  return String(s ?? '').replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+const TUNNEL_DOMAIN = 'trycloudflare.com';
+
+/** Turn a join code, host:port, or URL into a WebSocket URL. */
+export function joinTargetToUrl(target) {
+  const t = String(target).trim();
+  if (/^wss?:\/\//i.test(t)) return t;
+  if (/^https?:\/\//i.test(t)) return t.replace(/^http/i, 'ws');
+  if (/^[a-z0-9-]+$/i.test(t) && /[a-z]/i.test(t) && t.toLowerCase() !== 'localhost') {
+    return `wss://${t.toLowerCase()}.${TUNNEL_DOMAIN}`;
+  }
+  if (t.endsWith('.' + TUNNEL_DOMAIN)) return `wss://${t}`;
+  return `ws://${t}`;
+}
+
+/** Extract the short join code from a quick-tunnel URL. */
+export function urlToJoinCode(url) {
+  const m = /^https:\/\/([a-z0-9-]+)\.trycloudflare\.com/i.exec(url);
+  return m ? m[1] : url;
+}

package/src/tunnel.js

@@ -0,0 +1,50 @@
+// Opens a free Cloudflare "quick tunnel" so guests can reach the host's
+// machine over the internet without any port forwarding or account.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+
+const URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+
+/**
+ * @returns {Promise<{ url: string, stop: () => void }>}
+ */
+export async function startTunnel(port, { timeoutMs = 30_000 } = {}) {
+  const { bin, install } = await import('cloudflared');
+  if (!fs.existsSync(bin)) await install(bin);
+
+  const child = spawn(bin, ['tunnel', '--url', `http://127.0.0.1:${port}`, '--no-autoupdate'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const stop = () => {
+    if (!child.killed) child.kill();
+  };
+
+  const url = await new Promise((resolve, reject) => {
+    let log = '';
+    const timer = setTimeout(() => reject(new Error('timed out waiting for the tunnel')), timeoutMs);
+    const onData = (chunk) => {
+      log = (log + chunk.toString()).slice(-8000);
+      const match = URL_PATTERN.exec(log);
+      // Only hand out the link once cloudflared reports the tunnel is actually connected.
+      if (match && /Registered tunnel connection/i.test(log)) {
+        clearTimeout(timer);
+        resolve(match[0]);
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    child.once('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.once('exit', (code) => {
+      clearTimeout(timer);
+      reject(new Error(`cloudflared exited with code ${code}`));
+    });
+  }).catch((err) => {
+    stop();
+    throw err;
+  });
+
+  return { url, stop };
+}