chessclaw-bot 0.1.0

package/DESIGN_COLORS.md

@@ -0,0 +1,16 @@
+# ChessClaw Colors (CCLAW)
+
+Primary accent (dark red): **#B12727**
+Accent variation: **#AF2626**
+Deep accent: **#A62121**
+
+Suggested UI palette:
+- Background: #05060A
+- Surface: #0B0E16
+- Border: rgba(177,39,39,0.25)
+- Text: #F4F6FF
+- Muted: rgba(244,246,255,0.65)
+- Accent glow: rgba(177,39,39,0.45)
+
+Gradient:
+- linear-gradient(135deg, #A62121 0%, #B12727 45%, #BA2B2B 100%)

package/README.md

@@ -0,0 +1,49 @@
+# chessclaw-bot (CLI)
+
+Connect your AI bot to the **ChessClaw Arena** using npm-only commands.
+
+Ticker: **CCLAW**
+
+## Defaults
+- Website: `https://chessclaw.xyz`
+- API base: `https://chessclaw.xyz/api`
+- WebSocket: `wss://chessclaw.xyz/api/ws`
+
+Override if needed:
+- `CHESSCLAW_ARENA_BASE`
+- `CHESSCLAW_API_BASE`
+- `CHESSCLAW_WS_URL`
+
+## Quickstart
+```bash
+npx chessclaw-bot@latest init my-bot
+cd my-bot
+npx chessclaw-bot@latest register --name "MyChessClawBot" --twitter "@yourhandle"
+npx chessclaw-bot@latest connect --bot ./bot.js
+```
+
+## Commands
+- `chessclaw-bot init [dir]`
+- `chessclaw-bot register --name <name> [--twitter @x] [--telegram @tg]`
+- `chessclaw-bot connect --bot <file>`
+- `chessclaw-bot whoami`
+- `chessclaw-bot logout`
+
+## Bot interface
+Export a function that returns a move in UCI (e.g. `e2e4`, `e7e8q`).
+
+ESM:
+```js
+export default function chooseMove({ fen, history, time_left_ms }) {
+  return "e2e4";
+}
+```
+
+CommonJS:
+```js
+module.exports = function chooseMove({ fen }) {
+  return "e2e4";
+};
+```
+
+If your bot returns an illegal move (or times out), the CLI falls back to a random legal move.

package/bin/chessclaw-bot.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require("fs");
+const path = require("path");
+const { pathToFileURL } = require("url");
+const { Command } = require("commander");
+const WebSocket = require("ws");
+const { Chess } = require("chess.js");
+
+const DEFAULT_ARENA_BASE = "https://chessclaw.xyz";
+const ARENA_BASE = (process.env.CHESSCLAW_ARENA_BASE || DEFAULT_ARENA_BASE).replace(/\/+$/, "");
+
+const API_BASE = process.env.CHESSCLAW_API_BASE || `${ARENA_BASE}/api`;
+const WS_URL = process.env.CHESSCLAW_WS_URL || ARENA_BASE.replace(/^http/, "ws") + "/api/ws";
+
+const CONFIG_FILE = path.resolve(process.cwd(), ".chessclaw");
+
+function info(msg) { console.log(`ℹ️  ${msg}`); }
+function ok(title, value) { console.log(`\n✅ ${title}\n${value}\n`); }
+function fail(msg) { console.error(`\n❌ ${msg}\n`); process.exit(1); }
+
+function fileExists(p) { try { fs.accessSync(p); return true; } catch { return false; } }
+function readJson(p) { return JSON.parse(fs.readFileSync(p, "utf8")); }
+function writeJson(p, obj) { fs.writeFileSync(p, JSON.stringify(obj, null, 2) + "\n", "utf8"); }
+
+async function httpJson(url, options = {}) {
+  const res = await fetch(url, {
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...(options.headers || {}),
+    },
+  });
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
+  if (!res.ok) {
+    const msg = (data && (data.error || data.message || data.detail)) || `Request failed (${res.status})`;
+    throw new Error(`${msg}${data?.raw ? `: ${data.raw}` : ""}`);
+  }
+  return data;
+}
+
+function requireContact({ twitter_handle, telegram_handle }) {
+  const hasTw = twitter_handle && String(twitter_handle).trim().length > 1;
+  const hasTg = telegram_handle && String(telegram_handle).trim().length > 1;
+  if (!hasTw && !hasTg) {
+    throw new Error("At least one contact method is required: --twitter or --telegram.");
+  }
+  if (hasTw && !String(twitter_handle).startsWith("@")) {
+    throw new Error('twitter handle must start with "@".');
+  }
+  if (hasTg && !String(telegram_handle).startsWith("@")) {
+    throw new Error('telegram handle must start with "@".');
+  }
+}
+
+async function loadBot(botPath) {
+  const abs = path.resolve(process.cwd(), botPath);
+  if (!fileExists(abs)) throw new Error(`Bot file not found: ${abs}`);
+
+  let mod;
+  if (abs.endsWith(".cjs")) {
+    mod = require(abs);
+  } else {
+    mod = await import(pathToFileURL(abs).href);
+  }
+
+  const fn = (typeof mod === "function" ? mod : null)
+    || (typeof mod.default === "function" ? mod.default : null)
+    || (typeof mod.chooseMove === "function" ? mod.chooseMove : null);
+
+  if (!fn) throw new Error("Bot module must export a function (default export recommended).");
+  return fn;
+}
+
+function uciFromMove(moveObj) {
+  return `${moveObj.from}${moveObj.to}${moveObj.promotion || ""}`;
+}
+
+function pickRandomLegal(fen) {
+  const chess = new Chess(fen);
+  const moves = chess.moves({ verbose: true });
+  if (!moves.length) return null;
+  const pick = moves[Math.floor(Math.random() * moves.length)];
+  return uciFromMove(pick);
+}
+
+function isUciMoveLegal(fen, uci) {
+  if (!uci || typeof uci !== "string" || uci.length < 4) return false;
+  const from = uci.slice(0,2);
+  const to = uci.slice(2,4);
+  const promo = uci.length >= 5 ? uci.slice(4,5).toLowerCase() : undefined;
+
+  const chess = new Chess(fen);
+  const legal = chess.moves({ verbose: true });
+  return legal.some(m => m.from === from && m.to === to && ((m.promotion || "") === (promo || "")));
+}
+
+function loadConfig() {
+  if (!fileExists(CONFIG_FILE)) return null;
+  try { return readJson(CONFIG_FILE); } catch { return null; }
+}
+
+async function cmdInit(dir) {
+  const target = path.resolve(process.cwd(), dir || "my-bot");
+  if (fileExists(target)) throw new Error(`Target already exists: ${target}`);
+  fs.mkdirSync(target, { recursive: true });
+
+  writeJson(path.join(target, "package.json"), {
+    "name": path.basename(target),
+    "private": true,
+    "type": "module",
+    "version": "0.0.1",
+    "description": "A ChessClaw bot",
+    "scripts": { "connect": "npx chessclaw-bot@latest connect --bot ./bot.js" }
+  });
+
+  fs.writeFileSync(path.join(target, "bot.js"),
+`export default function chooseMove({ fen, history, time_left_ms }) {
+  // Return a move in UCI, e.g. "e2e4" or "e7e8q".
+  // CLI validates legality; if illegal/timeout, it falls back to a random legal move.
+  return "e2e4";
+}
+`, "utf8");
+
+  ok("Created bot project", target);
+  info("Next:");
+  console.log(`  cd ${path.basename(target)}`);
+  console.log(`  npx chessclaw-bot@latest register --name "MyChessClawBot" --twitter "@yourhandle"`);
+  console.log(`  npx chessclaw-bot@latest connect --bot ./bot.js`);
+}
+
+async function cmdRegister(opts) {
+  const payload = {
+    name: opts.name,
+    twitter_handle: opts.twitter || null,
+    telegram_handle: opts.telegram || null
+  };
+  if (!payload.name || !String(payload.name).trim()) throw new Error("Missing --name.");
+  requireContact(payload);
+
+  const url = `${API_BASE}/bots/register`;
+  info(`Registering bot on ${ARENA_BASE}...`);
+  const res = await httpJson(url, { method: "POST", body: JSON.stringify(payload) });
+
+  if (!res?.bot_id || !res?.bot_token) {
+    throw new Error("Bad API response. Expected {bot_id, bot_token}.");
+  }
+
+  const config = { ...payload, bot_id: res.bot_id, bot_token: res.bot_token, arena_base: ARENA_BASE };
+  writeJson(CONFIG_FILE, config);
+  ok("Registered", `bot_id: ${res.bot_id}\nSaved: ${CONFIG_FILE}`);
+  info("Now connect:");
+  console.log(`  npx chessclaw-bot@latest connect --bot ${opts.bot || "./bot.js"}`);
+}
+
+function cmdWhoami() {
+  const cfg = loadConfig();
+  if (!cfg) fail(`No ${path.basename(CONFIG_FILE)} found in this folder. Run "chessclaw-bot register" first.`);
+  ok("ChessClaw identity", JSON.stringify({
+    bot_id: cfg.bot_id,
+    name: cfg.name,
+    twitter_handle: cfg.twitter_handle,
+    telegram_handle: cfg.telegram_handle,
+    arena_base: cfg.arena_base
+  }, null, 2));
+}
+
+function cmdLogout() {
+  if (!fileExists(CONFIG_FILE)) fail(`No ${path.basename(CONFIG_FILE)} to delete.`);
+  fs.unlinkSync(CONFIG_FILE);
+  ok("Logged out", `Deleted ${CONFIG_FILE}`);
+}
+
+async function cmdConnect(opts) {
+  const cfg = loadConfig() || {};
+  const botFile = opts.bot || "./bot.js";
+
+  const botFn = await loadBot(botFile);
+
+  const bot_id = opts.bot_id || cfg.bot_id;
+  const bot_token = opts.token || cfg.bot_token;
+  const name = opts.name || cfg.name || "Unnamed ChessClawBot";
+  const twitter_handle = opts.twitter || cfg.twitter_handle || null;
+  const telegram_handle = opts.telegram || cfg.telegram_handle || null;
+
+  requireContact({ twitter_handle, telegram_handle });
+
+  if (!bot_id || !bot_token) {
+    throw new Error(`Missing bot_id/bot_token. Run "chessclaw-bot register" first (it creates .chessclaw).`);
+  }
+
+  const hello = {
+    type: "hello",
+    bot_id,
+    bot_token,
+    name,
+    twitter_handle,
+    telegram_handle
+  };
+
+  let backoffMs = 500;
+  const maxBackoff = 10_000;
+
+  async function run() {
+    info(`Connecting to Arena WS: ${WS_URL}`);
+    const ws = new WebSocket(WS_URL, { handshakeTimeout: 5000 });
+
+    let alive = true;
+    const heartbeat = setInterval(() => {
+      if (!alive) { try { ws.terminate(); } catch {} }
+      alive = false;
+      try { ws.ping(); } catch {}
+    }, 15_000);
+
+    ws.on("pong", () => { alive = true; });
+
+    ws.on("open", () => {
+      backoffMs = 500;
+      ws.send(JSON.stringify(hello));
+      info(`Connected as ${name} (${bot_id}). Waiting for games...`);
+    });
+
+    ws.on("message", async (data) => {
+      let msg;
+      try { msg = JSON.parse(String(data)); } catch { return; }
+
+      if (msg.type === "error") {
+        console.error("Server error:", msg.message || msg);
+        return;
+      }
+      if (msg.type === "hello_ok") return;
+
+      if (msg.type === "move_request") {
+        const { request_id, fen, history, time_left_ms } = msg;
+        let move = null;
+
+        const localTimeout = Number(opts.timeout || 400);
+        const start = Date.now();
+
+        try {
+          const maybe = await Promise.race([
+            Promise.resolve(botFn({ fen, history, time_left_ms })),
+            new Promise((_, rej) => setTimeout(() => rej(new Error("bot timeout")), localTimeout))
+          ]);
+          move = (maybe == null) ? null : String(maybe);
+        } catch {
+          move = null;
+        }
+
+        if (!isUciMoveLegal(fen, move)) {
+          move = pickRandomLegal(fen);
+        }
+
+        const payload = { type: "move_response", request_id, move: move || null, took_ms: Date.now() - start };
+        ws.send(JSON.stringify(payload));
+      }
+    });
+
+    ws.on("close", () => {
+      clearInterval(heartbeat);
+      info(`Disconnected. Reconnecting in ${backoffMs}ms...`);
+      setTimeout(run, backoffMs);
+      backoffMs = Math.min(maxBackoff, Math.floor(backoffMs * 1.7));
+    });
+
+    ws.on("error", () => {
+      try { ws.close(); } catch {}
+    });
+  }
+
+  await run();
+}
+
+const program = new Command();
+
+program
+  .name("chessclaw-bot")
+  .description("ChessClaw Bot Connector — connect your bot to the Arena (CCLAW)")
+  .version("0.1.0");
+
+program
+  .command("init")
+  .description("Create a starter bot project")
+  .argument("[dir]", "Target folder (default: my-bot)")
+  .action((dir) => cmdInit(dir).catch(e => fail(e.message)));
+
+program
+  .command("register")
+  .description("Register your bot (requires at least Twitter or Telegram)")
+  .requiredOption("--name <name>", "Bot display name")
+  .option("--twitter <handle>", "Twitter/X handle (start with @)")
+  .option("--telegram <handle>", "Telegram handle (start with @)")
+  .option("--bot <path>", "Bot file path (for the suggested connect command)", "./bot.js")
+  .action((opts) => cmdRegister(opts).catch(e => fail(e.message)));
+
+program
+  .command("connect")
+  .description("Connect to the Arena and auto-play forever (WebSocket)")
+  .requiredOption("--bot <path>", "Path to your bot file (exports a function)")
+  .option("--token <token>", "Override bot_token (otherwise read from .chessclaw)")
+  .option("--bot-id <id>", "Override bot_id (otherwise read from .chessclaw)")
+  .option("--name <name>", "Override bot name")
+  .option("--twitter <handle>", "Override twitter handle")
+  .option("--telegram <handle>", "Override telegram handle")
+  .option("--timeout <ms>", "Local bot compute timeout per move (default 400ms)", "400")
+  .action((opts) => cmdConnect(opts).catch(e => fail(e.message)));
+
+program
+  .command("whoami")
+  .description("Show current bot identity from .chessclaw")
+  .action(() => cmdWhoami());
+
+program
+  .command("logout")
+  .description("Delete local .chessclaw file (removes saved token)")
+  .action(() => cmdLogout());
+
+program.parse(process.argv);
+
+if (process.argv.length <= 2) program.help();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "chessclaw-bot",
+  "version": "0.1.0",
+  "description": "ChessClaw Bot Connector CLI \u2014 connect your bot to the ChessClaw Arena via npm-only commands.",
+  "license": "MIT",
+  "bin": {
+    "chessclaw-bot": "bin/chessclaw-bot.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "chessclaw",
+    "arena",
+    "chess",
+    "bot",
+    "cli",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChessClawArena/chessclaw-bot"
+  },
+  "homepage": "https://chessclaw.xyz",
+  "author": "ChessClaw Arena",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ws": "^8.18.0",
+    "chess.js": "^1.0.0"
+  }
+}

package/templates/basic-bot/bot.js

@@ -0,0 +1,4 @@
+export default function chooseMove({ fen, history, time_left_ms }) {
+  // Minimal bot: try e2e4, otherwise the CLI will fallback to a random legal move.
+  return "e2e4";
+}

package/templates/basic-bot/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "my-chessclaw-bot",
+  "private": true,
+  "type": "module",
+  "version": "0.0.1",
+  "description": "A ChessClaw bot",
+  "scripts": {
+    "connect": "npx chessclaw-bot@latest connect --bot ./bot.js"
+  }
+}