Polyman

CLI tool for Codeforces problem setters to automate the complete workflow for creating, testing, and verifying competitive programming problems.

📚 Quick Links | Installation • Quick Start • Commands • Docs • License

Why Polyman?

Stop switching between environments. Create competitive programming problems entirely in your terminal:

✅ Problem Templates – Generate complete folder structures in one command
✅ Test Generation – Automate test case creation with C++ generators
✅ Validation – Validate inputs against problem constraints
✅ Multi-Solution Testing – Test correct, wrong, TLE, and RE solutions simultaneously
✅ Smart Checkers – Use standard checkers or write custom ones
✅ Complete Verification – Full workflow in a single verify command
✅ Polygon Sync – Pull problems, work locally, push changes back
✅ Multi-Language – C++, Java, and Python support

Polyman eliminates manual testing and syncing, letting you focus on problem design.

Installation

System Requirements

• Node.js ≥ 14
• C++ Compiler (g++ with C++17+)
• Python 3 (optional - for Python solutions)
• Java JDK (optional - for Java solutions)

Quick Install

npm install -g polyman-cli

Build from source:

git clone https://github.com/HamzaHassanain/polyman.git
cd polyman && npm install && npm run build && npm link

Verify: polyman --version

Quick Start

Create & Test a Problem

# Create new problem
polyman new my-problem
cd my-problem

# Download testlib (required for validators/generators)
polyman download-testlib

# Run complete verification
polyman verify

Work with Polygon

# Setup (one-time)
polyman remote register

# Pull problem
polyman remote pull 123456 ./my-problem

# Work locally, then push back
polyman remote push .
polyman remote commit . -m "Updated solutions"

Commands

Essential Commands

| Command | Purpose | | ------------------------------ | ------------------------------- | | polyman new <dir> | Create new problem template | | polyman download-testlib | Download testlib.h header | | polyman generate --all | Generate all test cases | | polyman validate --all | Validate test inputs | | polyman run <solution> --all | Run solution on all tests | | polyman test <component> | Test validator/checker/solution | | polyman verify | Complete verification workflow |

Polygon Commands

| Command | Purpose | | -------------------------------------- | -------------------- | | polyman remote register | Save API credentials | | polyman remote list | List your problems | | polyman remote pull <id> <dir> | Download problem | | polyman remote push <dir> | Upload changes | | polyman remote commit <dir> -m "msg" | Commit changes | | polyman remote package <dir> <type> | Build package |

For detailed usage, see GUIDE.md.

Solution Tags

Every solution needs a tag indicating its expected behavior:

| Tag | Meaning | Purpose | | ---- | ------------------ | -------------------------------------- | | MA | Main Correct | Required - Reference solution | | OK | Correct | Alternative correct approach | | WA | Wrong Answer | Should fail on some tests | | TL | Time Limit | Should timeout on some tests | | TO | Time/OK | May TLE but is algorithmically correct | | ML | Memory Limit | Should exceed memory | | RE | Runtime Error | Should crash | | PE | Presentation Error | Wrong format | | RJ | Rejected | Should fail for any reason |

For full details, see GUIDE.md - Solution Types.

Standard Checkers

Polyman includes testlib checkers for common output formats:

polyman list checkers

Common checkers:

• ncmp - Sequence of numbers (most problems)
• wcmp - Sequence of tokens/words
• dcmp / rcmp* - Floating-point numbers
• yesno - Yes/No answers
• lcmp - Exact line comparison

For details, see GUIDE.md - Standard Checkers.

Project Structure

After polyman new my-problem, you get:

my-problem/
├── Config.json              # Problem configuration
├── solutions/               # Solution files (main + WA/TL/etc)
├── generators/              # Test generators
├── validator/               # Input validator
├── checker/                 # Custom checker (if needed)
├── statements/              # Problem statements
└── tests/                   # Generated test files

See GUIDE.md - Directory Structure for full details.

Configuration

The Config.json file defines your problem:

{
  "name": "problem-name",
  "timeLimit": 2000,
  "memoryLimit": 256,
  "inputFile": "stdin",
  "outputFile": "stdout",
  "solutions": [
    {
      "name": "main",
      "source": "./solutions/main.cpp",
      "tag": "MA",
      "sourceType": "cpp.g++17"
    }
  ],
  "generators": [
    {
      "name": "gen",
      "source": "./generators/gen.cpp"
    }
  ],
  "checker": {
    "name": "ncmp",
    "isStandard": true
  },
  "validator": {
    "name": "validator",
    "source": "./validator/validator.cpp"
  },
  "testsets": [
    {
      "name": "tests",
      "generatorScript": {
        "commands": [
          {
            "type": "generator",
            "generator": "gen",
            "range": [1, 50]
          }
        ]
      }
    }
  ]
}

See GUIDE.md - Configuration Reference for complete documentation.

Documentation

Choose your learning path:

📖 For Beginners

Complete User Guide - Comprehensive reference with configuration examples, validators, generators, checkers, and best practices.

🎓 Step-by-Step

Step-by-Step Tutorial - Learn by creating a simple "Sum of Two Numbers" problem from scratch.

🔧 For Developers

Technical Documentation - Architecture overview, type system, API reference, and implementation details.

⚙️ Platform-Specific

Windows Notes - Important considerations for Windows users regarding line endings and process cleanup.

📚 API Reference

TypeDoc Documentation - Generated API documentation for developers.

Workflow Summary

1. Create → polyman new my-problem
2. Setup → polyman download-testlib + edit Config.json
3. Implement → Write solutions, validator, generator, checker
4. Generate → polyman generate --all
5. Verify → polyman verify
6. Sync → polyman remote push . + polyman remote commit . "msg"

Detailed walkthrough: GUIDE.md - Workflow

Common Issues

Q: My test times out. How do I debug?
See GUIDE.md - Troubleshooting for performance tips and debugging strategies.

Q: Do I need a custom checker?
For most problems, a standard checker like wcmp or ncmp is sufficient. See GUIDE.md - FAQ.

Q: Windows users: Process not killed on TLE?
Check NOTES.md for cleanup instructions.

Support

• Issues: GitHub Issues
• Documentation: https://hamzahassanain.github.io/polyman/
• Codeforces: https://codeforces.com/ • Polygon

Contributing

Contributions welcome! To contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make changes with clear commit messages
4. Push and open a Pull Request

Please ensure code follows the existing style and includes tests.

License

MIT License. See LICENSE for details.

Acknowledgments

• testlib by Mike Mirzayanov - Validators, generators, and checkers
• Codeforces - Platform and community
• Contributors - All who have helped improve Polyman