justfile-expert

What this skill does

# Justfile Expert

Expert knowledge for Just command runner, recipe development, and task automation with focus on cross-platform compatibility and project standardization.

## When to Use This Skill

| Use this skill when... | Use alternative when... |
|------------------------|------------------------|
| Creating/editing justfiles for task automation | Need build system with incremental compilation → Make |
| Writing cross-platform project commands | Need tool version management bundled → mise tasks |
| Adding shebang recipes (Python, Node, Ruby, etc.) | Already using mise for all project tooling |
| Configuring dotenv loading and settings | Simple one-off shell scripts → Bash directly |
| Setting up CI/CD with just recipes | Project already has extensive Makefile |
| Standardizing recipes across projects | Need Docker-specific workflows → docker-compose |

## Core Expertise

**Command Runner Mastery**
- Justfile syntax and recipe structure
- Cross-platform task automation (Linux, macOS, Windows)
- Parameter handling and argument forwarding
- Module organization for large projects

**Recipe Development Excellence**
- Recipe patterns for common operations
- Dependency management between recipes
- Shebang recipes for complex logic
- Environment variable integration

**Project Standardization**
- Golden template with standard naming and section structure
- Self-documenting project operations
- Portable patterns across projects
- Integration with CI/CD pipelines

## Recipe Naming Conventions

| Rule | Pattern | Examples |
|------|---------|---------|
| Hyphen-separated | `word-word` | `test-unit`, `format-check` |
| Verb-first (actions) | `verb-object` | `lint`, `build`, `clean` |
| Noun-first (categories) | `noun-verb` | `db-migrate`, `docs-serve` |
| Private prefix | `_name` | `_generate-secrets`, `_setup` |
| `-check` suffix | Read-only verification | `format-check` |
| `-fix` suffix | Auto-correction | `lint-fix`, `check-fix` |
| `-watch` suffix | Watch mode | `test-watch`, `docs-watch` |
| Modifiers after base | `base-modifier` | `build-release` (not `release-build`) |

## Semantic Workflow Recipes

Standard composite recipes with defined meanings:

| Recipe | Composition | Purpose |
|--------|-------------|---------|
| `check` | `format-check` + `lint` + `typecheck` | Code quality only, no tests |
| `pre-commit` | `format-check` + `lint` + `typecheck` + `test-unit` | Fast, non-mutating validation |
| `ci` | `check` + `test-coverage` + `build` | Full CI simulation |
| `clean` | Remove build artifacts | Partial cleanup |
| `clean-all` | `clean` + remove deps/caches | Full cleanup |

```just
# Composite: code quality only (no tests)
check: format-check lint typecheck

# Pre-commit checks (fast, non-mutating)
pre-commit: format-check lint typecheck test-unit
    @echo "Pre-commit checks passed"

# Full CI simulation
ci: check test-coverage build
    @echo "CI simulation passed"

# Clean build artifacts
clean:
    rm -rf dist build .next

# Clean everything including deps
clean-all: clean
    rm -rf node_modules .venv __pycache__
```

## Key Capabilities

**Recipe Parameters**
- **Required parameters**: `recipe param:` - must be provided
- **Default values**: `recipe param="default":` - optional with fallback
- **Variadic `+`**: `recipe +FILES:` - one or more arguments
- **Variadic `*`**: `recipe *FLAGS:` - zero or more arguments
- **Environment export**: `recipe $VAR:` - parameter as env var

**Settings Configuration**
- **`set dotenv-load`**: Load `.env` file automatically
- **`set positional-arguments`**: Enable `$1`, `$2` syntax
- **`set export`**: Export all variables as env vars
- **`set shell`**: Custom shell interpreter
- **`set quiet`**: Suppress command echoing

**Recipe Attributes**
- **`[private]`**: Hide from `--list` output
- **`[no-cd]`**: Don't change directory
- **`[no-exit-message]`**: Suppress exit messages
- **`[unix]`** / **`[windows]`** / **`[linux]`** / **`[macos]`**: Platform-specific recipes
- **`[positional-arguments]`**: Per-recipe positional args
- **`[confirm]`** / **`[confirm("message")]`**: Require confirmation before running
- **`[group: "name"]`**: Group recipes in `--list` output
- **`[working-directory: "path"]`**: Run in specific directory

**Module System**
- **`mod name`**: Declare submodule
- **`mod name 'path'`**: Custom module path
- **Invocation**: `just module::recipe` or `just module recipe`

## Essential Syntax

**Basic Recipe Structure**
```just
# Comment describes the recipe
recipe-name:
    command1
    command2
```

**Recipe with Parameters**
```just
build target:
    @echo "Building {{target}}..."
    cd {{target}} && make

test *args:
    uv run pytest {{args}}
```

**Recipe Dependencies**
```just
default: build test

build: _setup
    cargo build --release

_setup:
    @echo "Setting up..."
```

**Variables and Interpolation**
```just
version := "1.0.0"
project := env('PROJECT_NAME', 'default')

info:
    @echo "Project: {{project}} v{{version}}"
```

**Conditional Recipes**
```just
[unix]
open:
    xdg-open http://localhost:8080

[windows]
open:
    start http://localhost:8080
```

## Standard Recipes

Every project should provide these standard recipes, organized by section:

```just
# Justfile - Project task runner
# Run `just` or `just help` to see available recipes

set dotenv-load
set positional-arguments

# Default recipe - show help
default:
    @just --list

# Show available recipes with descriptions
help:
    @just --list --unsorted

####################
# Development
####################

# Start development environment
dev:
    # bun run dev / uv run uvicorn app:app --reload / skaffold dev

# Build for production
build:
    # bun run build / cargo build --release / docker build

# Clean build artifacts
clean:
    # rm -rf dist build .next

####################
# Code Quality
####################

# Run linter (read-only)
lint *args:
    # bun run lint / uv run ruff check {{args}}

# Auto-fix lint issues
lint-fix:
    # bun run lint:fix / uv run ruff check --fix .

# Format code (mutating)
format *args:
    # bun run format / uv run ruff format {{args}}

# Check formatting without modifying (non-mutating)
format-check *args:
    # bun run format:check / uv run ruff format --check {{args}}

# Type checking
typecheck:
    # bunx tsc --noEmit / uv run basedpyright

####################
# Testing
####################

# Run all tests
test *args:
    # bun test {{args}} / uv run pytest {{args}}

# Run unit tests only
test-unit *args:
    # bun test --grep unit {{args}} / uv run pytest -m unit {{args}}

####################
# Workflows
####################

# Composite: code quality (no tests)
check: format-check lint typecheck

# Pre-commit checks (fast, non-mutating)
pre-commit: format-check lint typecheck test-unit
    @echo "Pre-commit checks passed"

# Full CI simulation
ci: check test-coverage build
    @echo "CI simulation passed"
```

### Section Structure

Organize recipes into these standard sections:

| Section | Recipes | Purpose |
|---------|---------|---------|
| **Metadata** | `default`, `help` | Discovery and navigation |
| **Development** | `dev`, `build`, `clean`, `start`, `stop` | Core dev cycle |
| **Code Quality** | `lint`, `lint-fix`, `format`, `format-check`, `typecheck` | Code standards |
| **Testing** | `test`, `test-unit`, `test-integration`, `test-e2e`, `test-watch` | Test tiers |
| **Workflows** | `check`, `pre-commit`, `ci` | Composite operations |
| **Dependencies** | `install`, `update` | Package management |
| **Database** | `db-migrate`, `db-seed`, `db-reset` | Data operations |
| **Kubernetes** | `skaffold`, `dev-k8s` | Container orchestration |
| **Documentation** | `docs`, `docs-serve` | Project docs |

Use `####################` comment blocks as section dividers for readability.

## Common Patterns

**Setup/Bootstrap Recipe**
```just
# Initial project setup
setup:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "Installing dependencies..."
    uv s