Getting Started

Start using Tuulbelt tools in minutes.

Quick Start

Clone the Repository

git clone https://github.com/tuulbelt/tuulbelt.git
cd tuulbelt

Try Test Flakiness Detector

cd test-flakiness-detector
npm install  # Dev dependencies only
flaky --test "npm test" --runs 10

Try CLI Progress Reporting

cd cli-progress-reporting
npm install  # Dev dependencies only

# Initialize progress
flaky init --total 100 --message "Processing files"

# Update progress
flaky increment --amount 10

# Check status
flaky get

Try Cross-Platform Path Normalizer

cd cross-platform-path-normalizer
npm install  # Dev dependencies only

# Convert Windows path to Unix format
flaky --format unix "C:\Users\file.txt"
# Output: /c/Users/file.txt

# Auto-detect format
flaky "/home/user/file.txt"
# Output: /home/user/file.txt (unix)

Available Tools

Tool	Status	Description
Test Flakiness Detector	v0.1.0	Detect unreliable tests
CLI Progress Reporting	v0.1.0	Concurrent-safe progress tracking
Cross-Platform Path Normalizer	v0.1.0	Convert Windows/Unix paths
File-Based Semaphore	v0.1.0	Process synchronization (Rust)
Output Diffing Utility	v0.1.0	Semantic diff for test output
Structured Error Handler	v0.1.0	Error serialization with context
Configuration File Merger	v0.1.0	ENV + config + CLI merging
Snapshot Comparison	v0.1.0	Binary/structured data snapshots
File-Based Semaphore (TS)	v0.1.0	Process synchronization (TypeScript)
Port Resolver	v0.1.0	Concurrent port allocation for any application

Progress: 10 of 33 tools (30%)

Installation Models

1. Clone Individual Tools (Recommended)

Each tool can be used independently:

# Current: Clone meta repo and navigate to tool
git clone https://github.com/tuulbelt/tuulbelt.git
cd tuulbelt/test-flakiness-detector
npm install && npm test

# Future (after migration): Clone individual tool repo
# git clone https://github.com/tuulbelt/test-flakiness-detector.git
# cd test-flakiness-detector
# npm install && npm test

2. Clone Entire Collection (All Tools)

Get all tools at once:

# Current: Clone meta repo
git clone https://github.com/tuulbelt/tuulbelt.git
cd tuulbelt

# Future (after migration): Clone with submodules
# git clone --recurse-submodules https://github.com/tuulbelt/tuulbelt.git
# cd tuulbelt

3. Use Without Cloning

Many tools can be used directly via npx (once published to npm):

# Future: Direct usage
npx @tuulbelt/test-flakiness-detector --test "npm test" --runs 10

Zero Dependencies Philosophy

Tuulbelt tools have ZERO runtime dependencies.

When you run npm install in a tool directory, you're only installing:

• TypeScript compiler (devDependency)
• Test runner (devDependency)
• Type definitions (devDependency)

The tools themselves use only Node.js built-in modules or Rust standard library.

Development Workflow

1. Explore a Tool

cd test-flakiness-detector
cat README.md  # Read documentation
ls examples/   # Check example outputs

2. Run Tests

npm test  # TypeScript tools
cargo test  # Rust tools

3. Try Examples

# Run tool with example data
flaky --test "echo test" --runs 5

4. Integrate Into Your Project

// Import as library
import { detectFlakiness } from './path/to/tool/src/index.js';

// Or use via CLI
import { execSync } from 'child_process';
execSync('npx tsx ../test-flakiness-detector/src/index.ts --test "npm test"');

Next Steps

Learn the Philosophy

• Philosophy - Why Tuulbelt exists
• Principles - Design principles guiding every tool

Explore Tools

• Test Flakiness Detector - Comprehensive docs
• CLI Progress Reporting - Full API reference
• Cross-Platform Path Normalizer - Path conversion guide

Contribute

• Contributing Guide - How to build new tools
• Quality Checklist - Pre-commit checks
• Testing Standards - Test requirements

Common Questions

Do I need to install dependencies?

For development: Yes, dev dependencies (TypeScript, test runners) For production: No, zero runtime dependencies

Can I use these in production?

Yes! All production-ready tools are battle-tested with 80%+ test coverage and dogfooding validation.

Which programming languages are supported?

TypeScript tools work with Node.js 18+ Rust tools work with Rust 1.70+

All tools provide CLI interfaces that work from any language.

Can I contribute?

Absolutely! See the Contributing Guide for how to propose and build new tools.

Where are the tools hosted?

All tools live in the tuulbelt/tuulbelt monorepo. Each tool is independently documented and can be extracted to its own repository if needed.

Support

• Issues: GitHub Issues
• Documentation: This site
• Source: GitHub Repository