Razd (razd-cli/razd)

Razd

https://github.com/razd-cli/razd
Admin
Razd is a modern project setup tool that orchestrates mise and taskfile for one-command project...

Tokens:18,695
Snippets:148
Trust Score:2.7
Update:4 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Razd - Project Setup and Development Orchestration Tool

Razd is a modern CLI tool designed to streamline project initialization and development workflows. It orchestrates `mise` (a polyglot version/environment manager) and `taskfile` (a task runner) to provide one-command project setup. Written in Rust, it serves both as a command-line utility and a library for testing and integration purposes. The tool automates the entire project lifecycle from cloning repositories, installing development tools, setting up dependencies, to running development and build workflows.

The project addresses the common pain point of inconsistent development environment setup by providing a unified configuration format (Razdfile.yml) that combines tool management and task automation. It automatically synchronizes configuration between Razdfile.yml and mise.toml, ensuring consistency while supporting both simple and complex tool configurations. With built-in project type detection and template generation, Razd can quickly bootstrap new projects with sensible defaults for Node.js, Python, Rust, Go, and other ecosystems.

## CLI Commands

### razd up - Initialize and Setup Projects

Clone a repository and set it up, or initialize/setup a local project. Supports three modes: clone mode (with URL), local mode (no URL), and init mode (--init flag).

```bash
# Clone and setup a remote repository
razd up https://github.com/user/project.git

# Clone with custom directory name
razd up https://github.com/user/project.git --name my-project

# Setup existing local project
cd my-project
razd up

# Initialize new Razdfile.yml with project detection
razd up --init

# Example output:
# Setting up project from https://github.com/user/nodejs-app.git
# Cloning repository...
# Working in directory: /home/user/nodejs-app
# Installing development tools with mise
# Successfully installed development tools
# Running default workflow...
# ✓ Project setup completed successfully!
```

### razd install - Install Development Tools

Install all development tools defined in Razdfile.yml or mise.toml using mise.

```bash
# Install all tools from configuration
razd install

# Skip automatic sync between Razdfile.yml and mise.toml
razd install --no-sync

# Example with Razdfile.yml containing:
# mise:
#   tools:
#     node: "22"
#     python: "3.11"
#   plugins:
#     node: "https://github.com/asdf-vm/asdf-nodejs.git"

# Output:
# Installing development tools with mise
# Installing node@22...
# Installing python@3.11...
# Successfully installed development tools
```

### razd setup - Install Project Dependencies

Install project dependencies using taskfile. Executes the "setup" task defined in Razdfile.yml.

```bash
# Run project setup (npm install, pip install, cargo build, etc.)
razd setup

# Example for Node.js project:
# Running project setup...
# npm install
# added 247 packages in 5s
# ✓ Project dependencies installed successfully!

# Example for Python project:
# Running project setup...
# pip install -r requirements.txt
# Successfully installed 42 packages
# ✓ Project dependencies installed successfully!
```

### razd dev - Start Development Workflow

Start the development server or workflow. Executes the "dev" task with interactive output.

```bash
# Start development server
razd dev

# Example for Node.js project with this Razdfile.yml:
# tasks:
#   dev:
#     desc: Start development server
#     cmds:
#       - npm run dev

# Output (interactive):
# > app@1.0.0 dev
# > next dev
# ▲ Next.js 14.0.0
# - Local:        http://localhost:3000
# ✓ Ready in 2.3s
```

### razd build - Build Project

Build the project using the configured build workflow.

```bash
# Build project
razd build

# Example for Rust project:
# Building project...
# Compiling razd v0.4.2
# Finished release [optimized] target(s) in 45.23s
# ✓ Build completed successfully!

# Example for Node.js project:
# Building project...
# npm run build
# Creating optimized production build...
# ✓ Build completed successfully!
```

### razd run - Execute Custom Tasks

Execute any custom task defined in Razdfile.yml with optional arguments.

```bash
# Run custom task
razd run test

# Run task with arguments
razd run deploy --args "--env=production"

# Example Razdfile.yml:
# tasks:
#   test:
#     desc: Run test suite
#     cmds:
#       - cargo test
#   deploy:
#     desc: Deploy application
#     cmds:
#       - ./scripts/deploy.sh {{.CLI_ARGS}}

# Output:
# Running custom task: test
# running 15 tests
# test result: ok. 15 passed; 0 failed
```

## Configuration Format

### Razdfile.yml Structure

Complete configuration file supporting mise tools, plugins, and taskfile tasks.

```yaml
# Razdfile.yml - Project configuration
version: '3'

# Mise configuration for tool management
mise:
  # Simple tool versions
  tools:
    node: "22"
    python: "3.11"
    task: "latest"

    # Complex tool configuration with options
    go:
      version: "1.21"
      postinstall: "go install golang.org/x/tools/cmd/goimports@latest"
      os: ["linux", "macos"]
      install_env:
        CGO_ENABLED: "1"
        GOARCH: "amd64"

  # Custom mise plugins
  plugins:
    node: "https://github.com/asdf-vm/asdf-nodejs.git"
    elixir: "https://github.com/my-org/mise-elixir.git#v1.0.0"

# Task definitions (Taskfile v3 format)
tasks:
  # Primary setup task (executed by "razd up")
  default:
    desc: Set up and start project
    cmds:
      - task: install
      - task: setup
      - task: dev

  # Install development tools
  install:
    desc: Install development tools via mise
    cmds:
      - mise install
      - echo "Tools installed successfully"

  # Setup project dependencies
  setup:
    desc: Install project dependencies
    cmds:
      - npm install
      - npm run build

  # Development workflow
  dev:
    desc: Start development server
    cmds:
      - npm run dev

  # Build workflow
  build:
    desc: Build project for production
    cmds:
      - npm run build
      - npm run test

  # Custom task with variables
  deploy:
    desc: Deploy to environment
    cmds:
      - task: build
        vars:
          ENV: production
          VERSION: "{{.VERSION | default \"v1.0.0\"}}"
      - ./scripts/deploy.sh {{.ENV}} {{.VERSION}}

  # Internal task (hidden from task list)
  cleanup:
    desc: Internal cleanup task
    internal: true
    cmds:
      - rm -rf dist/
      - rm -rf node_modules/
```

### Project Type Detection and Templates

Auto-generate Razdfile.yml based on detected project type with appropriate defaults.

```bash
# Detect and initialize for Node.js project
cd my-nodejs-app
razd up --init

# Detected project type: Node.js
# Creates this Razdfile.yml:

# mise:
#   tools:
#     node: "22"
#     task: "latest"
#   plugins:
#     node: "https://github.com/asdf-vm/asdf-nodejs.git"
#
# tasks:
#   default:
#     desc: Set up and start Node.js project
#     cmds:
#       - task: install
#       - task: dev
#   install:
#     desc: Install dependencies
#     cmds:
#       - mise install
#       - npm install
#   dev:
#     desc: Start development server
#     cmds:
#       - npm run dev
#   build:
#     desc: Build project
#     cmds:
#       - npm run build
#   test:
#     desc: Run tests
#     cmds:
#       - npm test

# Supported project types:
# - Node.js (detects: package.json)
# - Python (detects: requirements.txt, pyproject.toml, setup.py)
# - Rust (detects: Cargo.toml)
# - Go (detects: go.mod)
# - Docker (detects: Dockerfile)
# - Generic (fallback)
```

## Library API

### Load and Parse Configuration

Load Razdfile.yml from filesystem and access configuration programmatically.

```rust
use razd::config::RazdfileConfig;
use razd::core::Result;
use std::path::Path;

// Load from current directory
let config = RazdfileConfig::load()?;
if let Some(razdfile) = config {
    println!("Version: {}", razdfile.version);

    // Access mise configuration
    if let Some(mise) = razdfile.mise {
        if let Some(tools) = mise.tools {
            for (name, tool_config) in tools.iter() {
                println!("Tool: {}", name);
            }
        }
    }

    // Check for tasks
    if razdfile.has_task("dev") {
        println!("Dev task exists");
    }

    // Get primary task for "razd up"
    if let Some(primary) = razdfile.get_primary_task() {
        println!("Primary task: {}", primary);
    }
}

// Load from specific path
let config = RazdfileConfig::load_from_path("/path/to/Razdfile.yml")?;

// Example usage with error handling
match RazdfileConfig::load() {
    Ok(Some(config)) => {
        // Process configuration
        for (task_name, task_config) in config.tasks.iter() {
            if let Some(desc) = &task_config.desc {
                println!("{}: {}", task_name, desc);
            }
        }
    },
    Ok(None) => println!("No Razdfile.yml found"),
    Err(e) => eprintln!("Failed to load config: {}", e),
}
```

### Tool Installation via Mise Integration

Install development tools programmatically using mise integration.

```rust
use razd::integrations::mise;
use std::path::Path;

#[tokio::main]
async fn main() -> razd::Result<()> {
    let project_dir = Path::new(".");

    // Install all tools from mise configuration
    mise::install_tools(project_dir).await?;

    // Install specific tool with version
    mise::install_specific_tool("node", "22", project_dir).await?;

    // Check if mise configuration exists
    if mise::has_mise_config(project_dir) {
        println!("Mise configuration found");
    }

    // Fast-path: ensure tool is available (skips if already installed)
    mise::ensure_tool_available("node", "22", project_dir).await?;

    Ok(())
}

// Example: Install tools and handle errors
async fn setup_environment(dir: &Path) -> razd::Result<()> {
    use razd::core::output;

    match mise::install_tools(dir).await {
        Ok(_) => {
            output::success("All tools installed successfully");
            Ok(())
        }
        Err(e) => {
            output::error(&format!("Failed to install tools: {}", e));
            Err(e)
        }
    }
}
```

### Execute Commands and Workflows

Execute system commands and taskfile workflows programmatically.

```rust
use razd::integrations::process;
use razd::integrations::taskfile;
use std::path::Path;

#[tokio::main]
async fn main() -> razd::Result<()> {
    let working_dir = Path::new(".");

    // Execute command and capture output
    let output = process::execute_command(
        "npm",
        &["install"],
        Some(working_dir)
    ).await?;

    println!("npm install output: {}", output);

    // Execute command with interactive output (real-time)
    process::execute_command_interactive(
        "npm",
        &["run", "dev"],
        Some(working_dir)
    ).await?;

    // Check if command is available
    if process::check_command_available("mise").await {
        println!("mise is installed");
    }

    // Execute taskfile workflow
    let workflow_content = r#"
version: '3'
tasks:
  build:
    cmds:
      - cargo build --release
      - echo "Build complete"
"#;

    taskfile::execute_workflow_task(
        "build",
        workflow_content,
        working_dir
    ).await?;

    // Execute workflow interactively
    taskfile::execute_workflow_task_interactive(
        "dev",
        workflow_content,
        working_dir
    ).await?;

    // Check for Taskfile configuration
    if taskfile::has_taskfile_config(working_dir) {
        println!("Taskfile found in project");
    }

    Ok(())
}
```

### Configuration Synchronization

Sync configuration between Razdfile.yml and mise.toml automatically.

```rust
use razd::config::mise_sync::{MiseSyncManager, SyncConfig, SyncResult};
use std::path::PathBuf;

// Create sync manager with default config
let project_root = PathBuf::from(".");
let config = SyncConfig::default();
let sync_manager = MiseSyncManager::new(project_root, config);

// Check and sync if needed
match sync_manager.check_and_sync_if_needed()? {
    SyncResult::NoChangesNeeded => {
        println!("Configuration already in sync");
    }
    SyncResult::RazdfileToMise => {
        println!("Synced Razdfile.yml to mise.toml");
    }
    SyncResult::MiseToRazdfile => {
        println!("Synced mise.toml to Razdfile.yml");
    }
    SyncResult::Skipped => {
        println!("Sync skipped (--no-sync flag)");
    }
    SyncResult::Conflict => {
        println!("Conflict detected - manual resolution needed");
    }
}

// Custom sync configuration
let custom_config = SyncConfig {
    no_sync: false,
    auto_approve: true,  // Skip confirmation prompts
    create_backups: true, // Create .bak files before overwriting
};

let sync_manager = MiseSyncManager::new(project_root, custom_config);
let result = sync_manager.check_and_sync_if_needed()?;

// Example: Helper function for sync
use razd::config::mise_sync::check_and_sync_mise;

async fn ensure_synced(project_dir: &Path) -> razd::Result<()> {
    // Simple sync check using helper function
    check_and_sync_mise(project_dir)?;
    Ok(())
}
```

### Git Repository Operations

Clone repositories and extract repository information.

```rust
use razd::integrations::git;

#[tokio::main]
async fn main() -> razd::Result<()> {
    // Clone repository to default directory (repo name)
    let repo_path = git::clone_repository(
        "https://github.com/user/project.git",
        None
    ).await?;
    println!("Cloned to: {}", repo_path);

    // Clone to custom directory
    let custom_path = git::clone_repository(
        "https://github.com/user/project.git",
        Some("my-custom-name")
    ).await?;
    println!("Cloned to: {}", custom_path);

    // Extract repository name from URL
    let repo_name = git::extract_repo_name(
        "https://github.com/user/awesome-project.git"
    )?;
    assert_eq!(repo_name, "awesome-project");

    // Works with different URL formats
    let name1 = git::extract_repo_name("git@github.com:user/repo.git")?;
    let name2 = git::extract_repo_name("https://gitlab.com/user/repo")?;

    Ok(())
}

// Example: Clone and setup workflow
async fn clone_and_setup(url: &str, dir_name: Option<&str>) -> razd::Result<()> {
    use std::env;
    use razd::config::get_workflow_config;
    use razd::integrations::taskfile;

    // Clone repository
    let repo_path = git::clone_repository(url, dir_name).await?;

    // Change to repository directory
    let absolute_path = env::current_dir()?.join(&repo_path);
    env::set_current_dir(&absolute_path)?;

    // Get and execute workflow
    if let Some(workflow) = get_workflow_config("default")? {
        taskfile::execute_workflow_task_interactive(
            "default",
            &workflow,
            &absolute_path
        ).await?;
    }

    Ok(())
}
```

### Error Handling

Comprehensive error types for all operations with helpful context.

```rust
use razd::core::{RazdError, Result};

// Error variants and usage
fn example_error_handling() -> Result<()> {
    // Git errors
    Err(RazdError::git("Failed to clone repository"))?;

    // Mise errors
    Err(RazdError::mise("Tool installation failed"))?;

    // Task errors
    Err(RazdError::task("Workflow execution failed"))?;

    // Configuration errors
    Err(RazdError::config("Invalid Razdfile.yml format"))?;

    // Missing tool with help URL
    Err(RazdError::missing_tool(
        "mise",
        "https://mise.jdx.dev/getting-started.html"
    ))?;

    // No project configuration found
    Err(RazdError::no_project_config(
        "Run 'razd up --init' to create a Razdfile.yml"
    ))?;

    // No default task
    Err(RazdError::no_default_task())?;

    // Invalid URL
    Err(RazdError::invalid_url("Not a valid git URL"))?;

    Ok(())
}

// Pattern matching on errors
async fn handle_operation() {
    match perform_setup().await {
        Ok(_) => println!("Setup successful"),
        Err(RazdError::MissingTool { tool, help }) => {
            eprintln!("Missing tool: {}", tool);
            eprintln!("Install from: {}", help);
        }
        Err(RazdError::NoProjectConfig { suggestion }) => {
            eprintln!("No configuration found");
            eprintln!("Suggestion: {}", suggestion);
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

async fn perform_setup() -> Result<()> {
    // Implementation
    Ok(())
}

// Example with multiple error points
use razd::integrations::{mise, taskfile};
use std::path::Path;

async fn full_setup_with_errors(dir: &Path) -> Result<()> {
    // Check mise availability
    if !razd::integrations::process::check_command_available("mise").await {
        return Err(RazdError::missing_tool(
            "mise",
            "https://mise.jdx.dev"
        ));
    }

    // Install tools (may fail)
    mise::install_tools(dir).await
        .map_err(|e| RazdError::mise(format!("Setup failed: {}", e)))?;

    // Setup project (may fail)
    taskfile::setup_project(dir).await
        .map_err(|e| RazdError::task(format!("Dependency install failed: {}", e)))?;

    Ok(())
}
```

## Advanced Usage Patterns

### Custom Tool Configuration with Environment Variables

Configure complex tool installations with platform-specific options.

```yaml
# Razdfile.yml with advanced tool configuration
mise:
  tools:
    # Simple version
    node: "22"

    # Complex configuration
    python:
      version: "3.11"
      postinstall: |
        pip install --upgrade pip setuptools wheel
        pip install poetry
      os: ["linux", "macos"]
      install_env:
        PYTHON_CONFIGURE_OPTS: "--enable-optimizations"

    ruby:
      version: "3.2.0"
      postinstall: "gem install bundler"
      install_env:
        RUBY_CONFIGURE_OPTS: "--with-openssl-dir=/usr/local/opt/openssl"

    go:
      version: "1.21"
      postinstall: |
        go install golang.org/x/tools/cmd/goimports@latest
        go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
      install_env:
        CGO_ENABLED: "1"
        GOARCH: "amd64"

tasks:
  default:
    cmds:
      - mise install
      - echo "Environment ready"
```

### Task Composition with Variables

Compose complex workflows from reusable tasks with variable passing.

```yaml
# Razdfile.yml with task composition
tasks:
  # Reusable tasks
  clean:
    desc: Clean build artifacts
    cmds:
      - rm -rf dist/ build/ *.egg-info/

  lint:
    desc: Run linters
    cmds:
      - npm run lint
      - npm run format:check

  test:
    desc: Run test suite
    cmds:
      - npm run test -- --coverage

  build:
    desc: Build for specific environment
    cmds:
      - echo "Building for {{.ENV | default \"development\"}}"
      - npm run build -- --mode={{.ENV}}

  # Composite workflows
  ci:
    desc: Full CI pipeline
    cmds:
      - task: clean
      - task: lint
      - task: test
      - task: build
        vars:
          ENV: production

  deploy:
    desc: Deploy to environment
    cmds:
      - task: build
        vars:
          ENV: "{{.TARGET_ENV}}"
      - ./scripts/deploy.sh {{.TARGET_ENV}} {{.VERSION}}

  # Interactive development
  dev:
    desc: Development with watch mode
    cmds:
      - npm run dev -- --host={{.HOST | default "localhost"}} --port={{.PORT | default "3000"}}
```

Razd provides a comprehensive solution for project initialization and development workflow orchestration. By combining mise for tool management and taskfile for task automation under a unified Razdfile.yml configuration, it eliminates environment setup inconsistencies and reduces onboarding friction. The tool's automatic synchronization between Razdfile.yml and mise.toml ensures configuration stays consistent while giving developers flexibility to use either format. With intelligent project type detection, Razd can bootstrap new projects with appropriate templates and tool configurations for popular ecosystems.

The library API enables integration into larger automation systems, custom CI/CD pipelines, or development environment managers. The comprehensive error handling with contextual messages helps developers quickly resolve issues, while the built-in workflow fallbacks ensure commands work even without a Razdfile.yml present. Whether used as a CLI tool for daily development or integrated as a library for custom tooling, Razd streamlines the entire project lifecycle from initial clone to production build.