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

``bash


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

$3

`bash


Create a new problem

algo new

Start practicing a problem

algo practice

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
`

$3

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

#### Phase 1: Problem Registration (algo new)
- Interactive wizard to set up problem structure
- Creates problems// 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 )
- Creates isolated sandbox in sandbox//
- 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//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

$3

- 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
│ └── /
│ ├── prompt.md # Problem description
│ ├── meta.json # Metadata and attempt history
│ ├── tests.ts # Test cases
│ └── solutions/ # Archived solutions
├── sandbox/ # Active practice area (gitignored)
│ ├── /
│ │ ├── solution.ts # Your current work
│ │ └── tests.ts # Copied test file
│ └── _active.json # Tracks active sandboxes
└── src/ # CLI source code
`

Development Commands

`bash


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

`bash


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