If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/coding-horror/basic-computer-games shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 19 active contributors
• Distributed ownership (top contributor 32% of recent commits)
• Unlicense licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live coding-horror/basic-computer-games repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/coding-horror/basic-computer-games.

What it runs against: a local clone of coding-horror/basic-computer-games — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in coding-horror/basic-computer-games | Confirms the artifact applies here, not a fork | | 2 | License is still Unlicense | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 114 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of coding-horror/basic-computer-games. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/coding-horror/basic-computer-games.git
#   cd basic-computer-games
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of coding-horror/basic-computer-games and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "coding-horror/basic-computer-games(\\.git)?\\b" \\
  && ok "origin remote is coding-horror/basic-computer-games" \\
  || miss "origin remote is not coding-horror/basic-computer-games (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Unlicense)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Unlicense\"" package.json 2>/dev/null) \\
  && ok "license is Unlicense" \\
  || miss "license drift — was Unlicense at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "00_Alternate_Languages/01_Acey_Ducey/README.md" \\
  && ok "00_Alternate_Languages/01_Acey_Ducey/README.md" \\
  || miss "missing critical file: 00_Alternate_Languages/01_Acey_Ducey/README.md"
test -f "00_Alternate_Languages/01_Acey_Ducey/aceyducey.bas" \\
  && ok "00_Alternate_Languages/01_Acey_Ducey/aceyducey.bas" \\
  || miss "missing critical file: 00_Alternate_Languages/01_Acey_Ducey/aceyducey.bas"
test -f "00_Alternate_Languages/01_Acey_Ducey/elm/src/Main.elm" \\
  && ok "00_Alternate_Languages/01_Acey_Ducey/elm/src/Main.elm" \\
  || miss "missing critical file: 00_Alternate_Languages/01_Acey_Ducey/elm/src/Main.elm"
test -f "00_Alternate_Languages/01_Acey_Ducey/go/main.go" \\
  && ok "00_Alternate_Languages/01_Acey_Ducey/go/main.go" \\
  || miss "missing critical file: 00_Alternate_Languages/01_Acey_Ducey/go/main.go"
test -f ".github/workflows/check-python.yml" \\
  && ok ".github/workflows/check-python.yml" \\
  || miss "missing critical file: .github/workflows/check-python.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 114 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~84d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/coding-horror/basic-computer-games"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A modernized, multi-language port of the 1978 'BASIC Computer Games' book, with implementations of ~100 classic games in 10 memory-safe scripting languages (C#, Java, JavaScript, Python, Rust, Kotlin, Lua, Perl, Ruby, VB.NET). It proves nostalgic algorithms remain teachable and runnable in contemporary ecosystems while maintaining the original BASIC logic. Monorepo with 100+ game folders (01_Acey_Ducey/, etc.), each containing language-specific subfolders (c#/, java/, python/, rust/). Core BASIC originals live at the root of each game. Alternate languages (non-memory-safe or non-general-purpose) go into 00_Alternate_Languages/GAMENAME/LANGUAGE/ (e.g., 00_Alternate_Languages/01_Acey_Ducey/c++/, d/, elm/, nim/). Each language port has its own README.md, source files, and optional build configuration.

Computer science educators, language learners comparing syntax across ecosystems, and developers exploring classic game algorithms—anyone wanting to understand how 1970s game logic translates to 2022+ type-safe languages without boilerplate or IDEs.

Actively developed and well-established: the repo has comprehensive CI/CD workflows (.github/workflows/ for Python, Rust, and file-size checks), numerous mature ports across 25+ languages including alternates, and clear governance documenting why Pascal was replaced with Rust (March 2022). The project is production-ready for educational use and has stable structure, though individual game implementations may vary in completeness.

Low risk for educational use. The monorepo structure isolates languages, so breaking changes in one language port don't cascade. However, there is no per-game test suite visible in the file list (no test/ directories at game level), making validation of gameplay correctness dependent on manual QA. The project explicitly bans IDE/build files (.pre-commit-config.yaml enforces this), reducing noise but requiring strict contributor discipline.

Active porting and completion: GitHub workflows validate Python and Rust submissions via .github/workflows/check-python.yml and .github/workflows/rust.yml; file-size checks (.github/workflows/file-size.yml) ensure ports remain lightweight. The project tracks coverage via .coveragerc. Recent work includes finalizing ports in the core 10 languages and accepting alternate-language submissions to 00_Alternate_Languages/ (visible MiniScript, C++, D, Elm, Go, Nim variants).

git clone https://github.com/coding-horror/basic-computer-games.git
cd basic-computer-games
# For JavaScript ports: npm install in the specific game folder (e.g., 01_Acey_Ducey/javascript/)
# For Python: python3 01_Acey_Ducey/python/aceyducey.py
# For Rust: cargo build --release in the rust/ subfolder

Daily commands: Language-dependent. Example for Elm (from 00_Alternate_Languages/01_Acey_Ducey/elm/package.json): npm run live starts dev server on localhost:3000; npm run build outputs to docs/app.js for GitHub Pages. For interpreted languages (Python, Ruby, Perl), run the .py/.rb/.pl file directly. For compiled (Rust, C#), build first then execute binary.

• 00_Alternate_Languages/01_Acey_Ducey/README.md — Primary entry point documenting the original BASIC game and its purpose; essential for understanding project scope and game logic.
• 00_Alternate_Languages/01_Acey_Ducey/aceyducey.bas — Original BASIC source code that serves as the reference implementation for all language ports; canonical game logic.
• 00_Alternate_Languages/01_Acey_Ducey/elm/src/Main.elm — Example modern implementation showing architectural patterns for porting classic games to functional languages; demonstrates best practices.
• 00_Alternate_Languages/01_Acey_Ducey/go/main.go — Go implementation reference; shows idiomatic patterns for this repository's multi-language approach.
• .github/workflows/check-python.yml — CI/CD pipeline definition; ensures code quality and build consistency across all game implementations.
• 00_Alternate_Languages/01_Acey_Ducey/elm/elm.json — Package manifest for Elm implementations; defines dependencies and build configuration for functional language ports.

Add a New Language Implementation to an Existing Game

1. Create a new language subdirectory under the game folder, e.g., 00_Alternate_Languages/01_Acey_Ducey/rust/ (00_Alternate_Languages/01_Acey_Ducey/)
2. Reference the original BASIC source code as the specification (00_Alternate_Languages/01_Acey_Ducey/aceyducey.bas)
3. Implement game logic following idiomatic patterns of the target language (compare against existing implementations like Go, Elm, Pascal) (00_Alternate_Languages/01_Acey_Ducey/go/main.go)
4. Create a README.md in the language folder explaining build/run instructions and any language-specific notes (00_Alternate_Languages/01_Acey_Ducey/MiniScript/README.md)
5. If adding a web UI, include HTML resources and update elm.json or equivalent package config (00_Alternate_Languages/01_Acey_Ducey/elm/elm.json)
6. Add build/test step to appropriate CI/CD workflow file (.github/workflows/check-python.yml)

Add a New Game from the Original BASIC Computer Games Book

1. Create a numbered game folder following naming convention, e.g., 06_Lunar_Lander/ (00_Alternate_Languages/)
2. Place the original BASIC source code and create a README.md describing the game (00_Alternate_Languages/01_Acey_Ducey/README.md)
3. Start with at least one reference implementation (Go, Elm, or another memory-safe language) (00_Alternate_Languages/01_Acey_Ducey/go/main.go)
4. For web-based games, create elm/ subdirectory with Main.elm and resources/index.html (00_Alternate_Languages/01_Acey_Ducey/elm/src/Main.elm)
5. Update GitHub workflows to validate new game implementations (.github/workflows/rust.yml)

Create a Web Frontend for a Game Implementation

1. Create elm/ subdirectory with elm.json and src/ folder structure (00_Alternate_Languages/01_Acey_Ducey/elm/elm.json)
2. Implement game logic in elm/src/Main.elm using Elm's functional reactive patterns (00_Alternate_Languages/01_Acey_Ducey/elm/src/Main.elm)
3. Create resources/index.html as the entry point for the Elm application (00_Alternate_Languages/01_Acey_Ducey/elm/resources/index.html)
4. Configure build scripts in elm.json to compile to docs/ folder for GitHub Pages deployment (00_Alternate_Languages/01_Acey_Ducey/elm/package.json)
5. Test locally using elm-live as configured in package.json scripts (00_Alternate_Languages/01_Acey_Ducey/elm/package.json)

• Elm — Functional language with strong type safety and built-in web support; ideal for interactive browser-based games with guaranteed runtime error elimination
• Go — Memory-safe, cross-platform compiled language with minimal dependencies; excellent for console games and server implementations
• Rust — Systems programming with memory safety guarantees; enables safe performance-critical game implementations
• Pascal/Object Pascal — Historical language alignment with educational game design; demonstrates both procedural and object-oriented paradigms
• GitHub Pages + Elm — Free static hosting for compiled Elm games; enables instant playable demos without server infrastructure
• GitHub Actions CI/CD — Automated validation across multiple language implementations; ensures code quality and compilation success before merge

• Multiple language implementations for same game logic

  • Why: Demonstrates how to port classic games to modern memory-safe languages; educational value for learning different paradigms
  • Consequence: Code duplication and maintenance burden; each language port must be kept in sync with game logic changes

• Elm for web frontends instead of JavaScript/TypeScript

  • Why: Guarantees runtime safety and eliminates entire classes of bugs (null references, type errors at runtime)
  • Consequence: Steeper learning curve for contributors unfamiliar with functional programming; smaller ecosystem vs. JavaScript

• Static GitHub Pages hosting instead of server-rendered games

  • Why: Zero infrastructure cost, instant global CDN distribution, no server maintenance
  • Consequence: Games cannot maintain server-side state or multiplayer lobbies; limited to single-player or client-side state

1. Strict file-type filtering: .pre-commit-config.yaml blocks all IDE/build outputs (e.g., .vs/, .idea/, *.exe, *.o). Contributors must use .gitignore locally and never commit environment-specific files. 2. Language scope is narrow by design: C++, D, C are only allowed in 00_Alternate_Languages/ because they're not memory-safe scripting languages per the TIOBE mandate—attempting to add them to the core structure will be rejected. 3. Case sensitivity in BASIC: Original games expect CAPS LOCK input (noted in README); ports should preserve this for fidelity. 4. No shared build system: Each language/game has independent setup (npm vs cargo vs python3); there's no root Makefile or build orchestrator—contributions must be self-contained.

• Memory-safe scripting language — This repo explicitly filters languages by memory-safety (Rust yes, C++ no); understanding what 'memory-safe' means (no buffer overflows, null dereferences, use-after-free) is essential to grasping the project's scope decision and why alternates exist.
• TIOBE Index — The project's language selection is anchored to TIOBE's 2022 rankings of memory-safe scripting languages; understanding what TIOBE measures (search frequency, job postings, tutorials) explains why Lua replaced Pascal and why Kotlin/Ruby are included.
• Monorepo structure with language isolation — The repo uses a language-per-subfolder strategy (no shared build system or dependency tree) to scale across 10+ languages without toolchain conflicts; this is a pragmatic alternative to polyrepo or monoworkspace patterns.
• Idiomatic translation vs. line-for-line porting — Each port must map BASIC logic 1:1 but use idioms of the target language (e.g., list comprehensions in Python vs. loops in Java); contributors must balance fidelity to original with modern best practices.
• GitHub Pages + Elm compilation to JavaScript — Some alternates (Elm) compile to JavaScript and deploy to GitHub Pages docs/ folder; understanding this workflow (elm make → docs/app.js) is key for web-based ports.
• CI/CD gating for multi-language validation — The .github/workflows/*.yml files (Python, Rust, file-size checks) enforce correctness per language without manual review; new contributors should understand how their PRs are auto-validated.

• troypress/js-basic — Original BASIC interpreter in JavaScript (linked in README): lets readers play the original games in browser; shows the upstream reference this project ports from.
• vintage-basic/vintage-basic — The BASIC dialect (circa 2009) used to normalize all original game code in this repo; critical for understanding the source material all ports must match.
• awesome-competitive-programming/awesome-competitive-programming — Overlaps in algorithm pedagogy: educators and competitive programmers reuse classic game implementations for algorithm teaching and multi-language comparison.
• exercism/exercism — Parallel educational goal (language learning via multi-language tracks); this repo serves similar audience wanting to compare idioms across 10+ languages.
• danistefanovic/build-your-own-x — Peer project: both are curated collections of 'build this classic thing' projects; together they anchor hands-on learning for new programmers.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow to validate all language implementations against common test cases

The repo has .github/workflows for Python and Rust but lacks comprehensive cross-language validation. With 50+ implementations of the same games across C++, Go, Nim, D, Elm, Pascal, etc., there's no automated way to verify that all versions produce consistent output. This would catch regressions and ensure quality parity across implementations.

• [ ] Create a new GitHub Actions workflow file (.github/workflows/validate-games.yml) that defines expected I/O for at least 3 games (01_Acey_Ducey, 02_Amazing, etc.)
• [ ] Add test input/output fixtures in a new tests/ directory at repo root with format like tests/01_Acey_Ducey/input.txt and tests/01_Acey_Ducey/expected_output.txt
• [ ] Implement shell scripts or Python runner that executes each language implementation with test inputs and validates output matches expected behavior
• [ ] Update the workflow to run this validation on all pushes and PRs, covering at minimum the languages with existing CI (Python, Rust) plus Go, Elm, and Pascal implementations

Remove committed build artifacts and add comprehensive .gitignore entries for compiled outputs

The repo currently commits compiled binaries (00_Alternate_Languages/01_Acey_Ducey/c++/build/x64/Debug/aceyducey.exe, .pdb files, etc.). This bloats the repository and violates best practices. The .gitignore exists but is incomplete for the build directories and language-specific artifacts like Elm's docs/app.js, Pascal's compiled outputs, and D's object files.

• [ ] Audit existing build directories: remove committed 00_Alternate_Languages//c++/build/, 00_Alternate_Languages//d/build/, 00_Alternate_Languages//pascal//bin/, 00_Alternate_Languages//elm/docs/app.js artifacts
• [ ] Update .gitignore with patterns: */build/**, *.exe, *.pdb, *.o, *.obj, *.dcu, **/docs/app.js (for Elm), **/docs/app.min.js, **/.dub/ (for D)
• [ ] Add language-specific entries: elm-stuff/, .nimble/, nim.cfg local overrides, Go vendor/ if applicable
• [ ] Document in CONTRIBUTING.md or README.md that contributors should not commit build artifacts and how to locally build each language

Create missing README.md files for language folders lacking documentation

Several language implementation folders (00_Alternate_Languages/01_Acey_Ducey/go, 00_Alternate_Languages/01_Acey_Ducey/nim, 00_Alternate_Languages/01_Acey_Ducey/pascal/simple) lack README.md files explaining how to build/run them. Contributors and users can't easily understand setup steps. The MiniScript and Elm folders show the pattern with their READMEs.

• [ ] Create 00_Alternate_Languages/01_Acey_Ducey/go/README.md with: Go version requirement, build command (go run main.go or go build), dependencies if any, and sample execution
• [ ] Create 00_Alternate_Languages/01_Acey_Ducey/nim/README.md with: Nim version requirement, build/run command (nim compile --run aceyducey.nim), required packages from nimble, and execution notes
• [ ] Create 00_Alternate_Languages/01_Acey_Ducey/pascal/simple/README.md and 00_Alternate_Languages/01_Acey_Ducey/pascal/object-pascal/README.md with: IDE/compiler setup (Lazarus, Free Pascal version), project loading instructions, and build steps
• [ ] Use consistent format matching existing READMEs (MiniScript, Elm) with sections:

• Port the remaining games to one under-represented core language (e.g., only 30 of 100 games have Kotlin/Lua ports yet). Start with 02_Bagels or 03_Black_Box (smaller logic surface area) to learn the pattern before tackling complex simulators.
• Add missing README.md files in language subfolders (many games have code but no explanation of how to run or what the game does). Pick a game like 10_Blackjack/rust/ and document the port, build steps, and any deviations from BASIC.
• Extend .github/workflows/ to validate JavaScript and Java ports (currently only Python and Rust have CI checks visible). Add jobs in .github/workflows/ to run npm test and mvn test against a subset of games to catch regressions early.

The codebase exhibits moderate security concerns primarily related to outdated and potentially vulnerable dependencies (uglify-js ^3.15.3 and elm-live ^4.0.2), lack of a visible package lock file for reproducible builds, and committed build artifacts with debug symbols. The Elm-based web application lacks explicit security header configuration. The project itself (being a collection of educational game implementations) has limited runtime security risks as it contains primarily educational code without database integration, complex authentication, or user-sensitive operations. Critical improvements needed: update all npm dependencies immediately, add comprehensive .gitignore entries for build artifacts, maintain a lock file, and configure security headers for web-based implementations.

• High · Outdated uglify-js Dependency — package.json - devDependencies. The package.json specifies uglify-js version ^3.15.3, which is significantly outdated. This version has known security vulnerabilities, including CVE-2021-36475 (side effects during variable renaming), and the package itself is no longer actively maintained. Current versions should be used or the package should be replaced with alternatives like esbuild or terser. Fix: Update uglify-js to the latest version (if still needed) or replace with a maintained alternative like 'terser' (^5.0.0 or higher). Run 'npm audit' to identify and fix all vulnerable dependencies.
• Medium · Outdated elm-live Dependency — package.json - devDependencies. The package.json specifies elm-live version ^4.0.2, released in 2020. This development tool may have unpatched security vulnerabilities or compatibility issues. The latest versions should be evaluated and used. Fix: Update elm-live to the latest stable version. Run 'npm outdated' to identify outdated packages and 'npm audit' to check for known vulnerabilities.
• Medium · Development/Build Artifacts in Repository — 00_Alternate_Languages/01_Acey_Ducey/c++/build/ directory contents. Compiled binaries and debug files are committed to the repository (e.g., aceyducey.exe, aceyducey.pdb in build/x64/Debug and build/x86/Debug directories). This increases repository size, can expose debug information, and violates clean repository practices. Fix: Add build output directories to .gitignore (build/, dist/, *.exe, *.pdb, *.o, etc.). Remove existing build artifacts from git history using 'git filter-branch' or 'BFG Repo-Cleaner'. Only source code should be version controlled.
• Low · Missing Security Headers Configuration — 00_Alternate_Languages/01_Acey_Ducey/elm/ - web application. The Elm web application (as seen in resources/index.html and elm build output) lacks explicit security headers configuration. No evidence of Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, or other security headers in web server configuration. Fix: Configure security headers in the web server or through meta tags. Include: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection: 1; mode=block, Referrer-Policy: strict-origin-when-cross-origin.
• Low · No Dependency Lock File Visible — Repository root - missing lock file. While package.json is present, there is no indication of a package-lock.json or yarn.lock file in the file structure. This could lead to non-reproducible builds and inconsistent dependency versions across environments. Fix: Ensure package-lock.json (for npm) or yarn.lock (for yarn) is committed to version control. This guarantees reproducible builds and exact dependency versions across all environments.
• Low · Proxy Configuration in Development — package.json - scripts.live. The elm-live script in package.json uses --proxy-host pointing to localhost:8080/api without authentication or encryption specification. While this is for local development, it could be a security concern if accidentally used in production. Fix: Ensure proxy scripts are clearly marked as development-only. Use environment-based configuration to prevent development settings from leaking into production builds. Document that these scripts should never be used in production.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.