algo-practice

A CLI-first algorithm practice tool for TypeScript/Node.js that provides spoiler-free practice environments and tracks attempt history across Windows, Linux, and macOS.

Installation

# Install globally from npm
npm install -g algo-practice

# Or install locally in your project
npm install algo-practice

# Or build from source
git clone https://github.com/chris-amaya/algo.git
cd algo
pnpm install
pnpm build
npm install -g .

Usage

Basic Commands

# Create a new problem
algo new

# Start practicing a problem
algo practice <slug>

# Run tests for current problem
algo test

# Run tests in watch mode
algo watch [slug]

# Submit your solution
algo submit [-n "note"]

# Resume active sandbox
algo resume

# View past attempts
algo reveal [slug]

# Get help
algo --help

Development Workflow

The CLI follows a two-phase spoiler-free design:

Phase 1: Problem Registration (algo new)

• Interactive wizard to set up problem structure
• Creates problems/<slug>/ with:
  • prompt.md - Problem description
  • tests.ts - Test cases (no solutions visible)
  • meta.json - Metadata and attempt history
  • solutions/ - Directory for archived attempts
• Note: No solution.ts is created here to keep it spoiler-free

Phase 2: Practice Session (algo practice <slug>)

• Creates isolated sandbox in sandbox/<slug>/
• Copies test file without revealing solutions
• Creates solution.ts with intelligent stub based on test analysis
• Workspace is completely separate from problem definition

Development Loop

3. Run tests: algo test or algo watch

   • Uses Vitest to run tests against your solution
   • Watch mode automatically reruns on file changes

4. Submit solution: algo submit

   • Archives your solution with timestamp to problems/<slug>/solutions/
   • Records attempt metadata (passed/failed, notes)
   • Keeps solution history for later review

5. Review attempts: algo reveal

   • View all past attempts without spoilers
   • Compare different approaches over time

Why This Design?

• Spoiler-Free: Problem definitions never contain solutions
• Multiple Attempts: Each practice session is isolated
• Clean Separation: Problem registry vs. active workspaces
• History Tracking: All attempts are preserved chronologically

Directory Structure

algo/
├── problems/                 # Your problem collection
│   └── <slug>/
│       ├── prompt.md        # Problem description
│       ├── meta.json        # Metadata and attempt history
│       ├── tests.ts         # Test cases
│       └── solutions/       # Archived solutions
├── sandbox/                 # Active practice area (gitignored)
│   ├── <slug>/
│   │   ├── solution.ts      # Your current work
│   │   └── tests.ts         # Copied test file
│   └── _active.json         # Tracks active sandboxes
└── src/                     # CLI source code

Development Commands

# Run in development mode
pnpm dev

# Run tests
pnpm test
pnpm test:coverage

# Type checking
pnpm typecheck

# Linting
pnpm lint

# Build for production
pnpm build

Features

• Spoiler-Free Practice: Sandbox completely isolated from solutions
• Cross-Platform: Works on Windows, Linux, and macOS
• Test-Driven: Integrated Vitest workflow encourages TDD
• Attempt History: Track your progress over time
• TypeScript First: Full TypeScript support with type checking

Examples

# Create a new two-sum problem
algo new
# Enter: two-sum, Two Sum, easy

# Start practicing
algo practice two-sum

# Run tests in watch mode
algo watch

# Submit when ready
algo submit -n "O(n) hash table solution"

# View all attempts later
algo reveal two-sum

License

ISC