Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Headless simulation / CLI

Open
  • Is something wrong?
#122 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
node.js, typescript
Domain
backend, cli

Research direction

Start with server/src/api/mcp.ts to understand runMatchToDecision and buildMatchSummary, then read server/src/api/arena.ts and server/src/api/token.ts for the existing arena endpoints and bearer token flow. The issue describes either a Node CLI using those REST endpoints or a CLI calling MCP tools; compare both paths and existing tests in server/test/mcp.test.ts and server/test/api.test.ts. Done means bot matches can be run headlessly with a reproducible seed and pass/fail plus leaderboard output.

Written by the indexing model from the issue text.

Description

enhancement priority: medium

A command (or thin client over the existing /arenas API) to run a match between bots without the UI — enables scripting, local iteration, and CI for your bot. The multi-arena API was built for exactly this kind of tooling.

Effort: M

Migrated from ENHANCEMENTS.md (§4 Developer experience).

Implementation notes

Priority: medium — Valuable for bot-author workflow/CI iteration, but the core capability (run_match/run_tournament) already ships via MCP; this is packaging, not core-path stability or security.

Purpose

Bot authors want to iterate and run CI checks without opening the UI: a scriptable way to run a match to a decision and get pass/fail + leaderboard output. This is mostly a packaging problem — runMatchToDecision and buildMatchSummary already implement the exact semantics needed; the gap is a client that doesn't require an MCP-capable agent.

Implementation approach
  • Reuse server/src/api/mcp.ts's runMatchToDecision (seed → restart → resume → poll buildMatchSummary → pause → restore speed) as the reference algorithm; either extract it to a shared util/matchRunner.ts used by both the MCP tools (run_match, run_tournament) and a new CLI, or have the CLI call it indirectly.
  • Two viable shapes, both "thin client over /arenas": (a) a Node bin/ script in server/ using an API token (server/src/api/token.ts) to call the existing REST endpoints — POST .../arenas/:arenaId/seed, /restart, /resume, GET .../arenas/:arenaId/summary (server/src/api/arena.ts, util/matchSummary.ts) — polling like runMatchToDecision does; or (b) a CLI that speaks MCP directly to POST /api/mcp and invokes run_match/run_tournament (auth already bearer-token based, per CLAUDE.md's MCP section).
  • No compiler.ts or bot-facing sandbox API changes — this only orchestrates existing arena control endpoints.
  • No UI changes required; SSE/reducer (arenaReducer.ts) untouched since this is a headless poll loop, not a stream consumer.
Key details to plan
  • No DB schema changes (services/*Service.ts untouched); note the no-migrations caveat from #142 doesn't apply here.
  • Auth: needs a bearer API token flow (api/token.ts) rather than the browser cookie session — document token creation as a prerequisite.
  • Determinism: expose seed (mirrors set_arena_seed/setSeed) so CI runs are reproducible, consistent with util/random.ts's mulberry32 PRNG.
  • Testing: extend server/test/mcp.test.ts and server/test/api.test.ts patterns (both already exercise restart/resume/seed/summary flows) rather than inventing new fixtures; if extracting runMatchToDecision, add unit coverage alongside simulation.test.ts's mock-tank style.
  • Depends on nothing blocking; complements #122's sibling MCP tools already shipped (run_match, run_tournament, match_status). Low technical risk — mostly plumbing/packaging (CLI entry point, token bootstrap, output formatting), effort M as labeled.
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
11h 21m
Merged PRs (30d)
21

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from LeeAdcock/robocodeJs.com

All issues in LeeAdcock/robocodeJs.com

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.