cargo-setupx 0.1.0

# 📘 cargo-setupx

> **Automate Rust project setup with modular configuration packs**

A Rust-based CLI and library that automates the initial setup of new Rust projects. Provides modular configuration packs that can be selectively applied to standardize development environments.

[![Crates.io](https://img.shields.io/crates/v/cargo-setupx.svg)](https://crates.io/crates/cargo-setupx)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🎯 Features

- **Quality Pack** - Code quality configuration files
  - `rustfmt.toml` - Code formatting rules
  - `clippy.toml` - Linting configuration
  - `_typos.toml` - Spell checking setup
  - `Makefile` - Common development commands

- **Hooks Pack** - Git hooks for automated quality checks
  - `.githooks/pre-push` - Pre-push quality gate
  - `.githooks/setup.sh` - Hooks installation script
  - Configures `core.hooksPath` automatically

- **Architecture Pack** - Project structure scaffolding
  - Clean Architecture (domain, application, infrastructure, presentation)
  - Additional patterns planned (hexagonal, onion - see Roadmap)

## 📦 Installation

```bash
cargo install cargo-setupx
```

Or install from source:

```bash
git clone https://github.com/ricardoferreirades/cargo-setupx.git
cd cargo-setupx
cargo install --path .
```

## 🚀 Quick Start

### Apply All Packs

```bash
# In your Rust project directory
cargo setupx --all
```

### Apply Specific Packs

```bash
# Quality pack only
cargo setupx --quality

# Hooks pack only
cargo setupx --hooks

# Architecture pack (clean)
cargo setupx --arch=clean

# Quality + Hooks
cargo setupx --quality --hooks
```

### Force Overwrite

```bash
# Overwrite existing files
cargo setupx --all --force

# Skip confirmation prompt
cargo setupx --all --yes
```

## 📖 Usage

### As a Cargo Subcommand

```bash
# Show help
cargo setupx --help

# Apply to current directory
cargo setupx --quality --hooks

# Apply to specific directory
cargo setupx --all /path/to/project

# Force overwrite with no prompts
cargo setupx --all --force --yes
```

### As a Library

```rust
use cargo_setupx::{Config, apply_packs};
use std::path::Path;

let config = Config {
    quality: true,
    hooks: true,
    arch: Some("clean".to_string()),
    force: false,
    yes: false,
};

apply_packs(&config, Path::new(".")).expect("Failed to apply packs");
```

## 📋 What Gets Created

### Quality Pack (`--quality`)

Creates the following files in your project root:

```
clippy.toml       # Clippy linter configuration
rustfmt.toml      # Rustfmt formatter settings
_typos.toml       # Typos spell checker config
Makefile          # Development commands
```

**Makefile commands:**
- `make fmt` - Format code (cargo fmt + taplo)
- `make lint` - Run clippy linter
- `make lint-fix` - Auto-fix linting issues
- `make check` - Type check without building
- `make spell` - Check spelling
- `make spell-fix` - Auto-fix spelling errors
- `make quality` - Run all quality checks
- `make test` - Run tests
- `make run` - Run the application

### Hooks Pack (`--hooks`)

Creates Git hooks for automated quality checks:

```
.githooks/
├── pre-push       # Pre-push quality gate (executable)
├── setup.sh       # Hook installation script (executable)
└── README.md      # Hooks documentation
```

The pre-push hook runs:
1. ✅ Code formatting check (`cargo fmt --check`)
2. ✅ TOML formatting check (`taplo format --check`)
3. ✅ Linting (`cargo clippy -- -D warnings`)
4. ✅ Spell check (`typos`)
5. ✅ Type check (`cargo check`)
6. ✅ Tests (`cargo test`)

**Push is blocked if any check fails!**

### Architecture Pack (`--arch=clean`)

**Note:** Currently only Clean Architecture is supported. Other patterns (hexagonal, onion) are planned.

Creates Clean Architecture folder structure:

```
src/
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── services/
├── application/
│   ├── dto/
│   └── use_cases/
├── infrastructure/
│   ├── database/
│   ├── config/
│   └── http/
└── presentation/
    └── handlers/
```

Each directory includes:
- `mod.rs` with documentation
- Stub files for quick start

## 🔧 Prerequisites

For full functionality, install these tools:

```bash
# Taplo (TOML formatter)
cargo install taplo-cli

# Typos (spell checker)
cargo install typos-cli
```

## 🛠️ Development Workflow

After running `cargo setupx --all`, use these commands:

```bash
# Initial setup
make setup-hooks    # Configure git hooks

# Daily development
make quality        # Run all checks
make fmt           # Format code
make lint-fix      # Fix linting issues
make spell-fix     # Fix spelling

# Testing
make test          # Run tests
make check         # Quick type check

# Building
make build         # Build release
make clean         # Clean artifacts
```

## ⚙️ Configuration

### Idempotent Setup

Running `cargo setupx` multiple times is safe. It will:
- Skip existing files (unless `--force` is used)
- Show clear status messages (Created, Skipped, Overwrote)
- Never corrupt existing files

### Force Overwrite

Use `--force` to overwrite existing files:

```bash
cargo setupx --all --force
```

### Skip Confirmation

Use `--yes` to skip confirmation prompts:

```bash
cargo setupx --all --yes
```

## 🎨 Examples

### New Project Setup

```bash
# Create new Rust project
cargo new my-awesome-project
cd my-awesome-project

# Apply all packs
cargo setupx --all

# Setup git hooks
make setup-hooks

# Verify everything works
make quality
```

### Existing Project Setup

```bash
# In your existing project
cd my-existing-project

# Apply quality + hooks (no architecture changes)
cargo setupx --quality --hooks --yes

# Setup hooks
make setup-hooks
```

### Library Project

```bash
# Create library
cargo new --lib my-library
cd my-library

# Apply quality pack + clean architecture
cargo setupx --quality --arch=clean

# Verify
make quality
```

## 🧪 Testing

Run the test suite:

```bash
cargo test
```

Run specific tests:

```bash
cargo test quality
cargo test hooks
cargo test architecture
```

## 📚 Documentation

Generate and open documentation:

```bash
cargo doc --open
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feat/amazing-feature`)
3. Make your changes
4. Run quality checks (`make quality`)
5. Commit your changes (`git commit -m 'feat: add amazing feature'`)
6. Push to the branch (`git push origin feat/amazing-feature`)
7. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by the need for consistent Rust project setups
- Built with [Clap](https://github.com/clap-rs/clap) for CLI parsing
- Quality tools: [Clippy](https://github.com/rust-lang/rust-clippy), [Rustfmt](https://github.com/rust-lang/rustfmt), [Typos](https://github.com/crate-ci/typos)

## 🔗 Links

- [Repository](https://github.com/ricardoferreirades/cargo-setupx)
- [Issue Tracker](https://github.com/ricardoferreirades/cargo-setupx/issues)
- [Documentation](https://docs.rs/cargo-setupx)

## 🚧 Roadmap

- [ ] Support for hexagonal architecture
- [ ] Support for onion architecture
- [ ] Custom pack definitions via `.setupx.toml`
- [ ] CI/CD configuration packs (GitHub Actions, GitLab CI)
- [ ] Docker configuration pack
- [ ] Plugin system for community packs
- [ ] Interactive mode for pack selection

---

**Made with ❤️ by Ricardo Ferreira**