makefile

Overview

Creates a Makefile following pixl-crew conventions. The focus is on non-obvious patterns — self-documenting help targets, monorepo-aware workspace targets, and correct integration with uv/bun/Docker Compose.

Step 1: Discovery

1. Detect project language, build system, and package manager
2. Identify existing scripts in package.json, pyproject.toml, etc.
3. Check for Docker/Docker Compose, CI/CD, and deployment tools
4. Determine if this is a monorepo (multiple package.json/pyproject.toml files, workspace config)
5. Check for .env files that need loading

Step 2: Generate Makefile

Structure

Follow this ordering convention:

# 1. .PHONY declaration — ALL non-file targets, one line
.PHONY: setup install dev build test lint format typecheck clean deploy docker-build docker-up help

# 2. Environment loading
ifneq (,$(wildcard .env))
  include .env
  export
endif

# 3. Variables with ?= defaults (overridable from CLI)
PORT ?= 3000
ENV ?= development
BUMP ?= patch

# 4. Composite targets first (setup, ci)
# 5. Dev targets (dev, build, clean)
# 6. Quality targets (test, lint, format, typecheck)
# 7. Deploy targets (deploy, docker-*)
# 8. help target LAST

Self-Documenting Help Target

Every target MUST have a ## Comment suffix. The help target auto-generates docs from these:

setup: install  ## Full setup: install deps + configure
	@echo "Ready."

help:  ## Show available targets
	@grep -E '^[a-zA-Z_-]+:.*?## ' Makefile | awk 'BEGIN {FS=":.*?## "};{printf "  %-18s %s\n",$$1,$$2}'

Package Manager Targets

uv (Python):

PYTEST := uv run python -m pytest --import-mode=importlib

install:  ## Install workspace packages
	uv sync --all-extras

test:  ## Run all tests
	$(PYTEST)

lint:  ## Lint check
	uv run ruff check .

format:  ## Auto-format
	uv run ruff check --fix .
	uv run ruff format .

bun (TypeScript):

install:  ## Install dependencies
	bun install

dev:  ## Start dev server
	bun run dev

build:  ## Production build
	bun run build

test:  ## Run tests
	bun test