cmd-makefile

What this skill does

# Makefile Helper

Create Makefiles that are simple, discoverable, and maintainable.

## Core Principles

1. **Default to rich help** - Use categorized help with emoji headers unless user requests minimal
2. **Default Chrome extensions to modular** - Use the modular `makefiles/*.mk` layout with shared colors/help for Chrome extension projects unless the repo is truly tiny
3. **Ask about structure upfront** - For new Makefiles, ask: "Flat or modular? Rich help or minimal?"
4. **Follow existing conventions** - Match the project's style if Makefile already exists
5. **Don't over-engineer** - Solve the immediate need, not hypothetical futures
6. **Use `uv run`** - Always run Python commands via `uv run` for venv context
7. **Explain decisions** - If choosing flat/minimal, explain why before generating

## When to Use This Skill

- Creating a new Makefile for a project
- Adding specific targets to an existing Makefile
- Improving/refactoring an existing Makefile
- Setting up CI/CD make targets
- Distributing pre-built binaries via GitHub Releases

## Quick Start

For new projects, use the appropriate template:

| Project Type | Template | Complexity | Asks upfront |
|-------------|----------|------------|------|
| Any project | `templates/base.mk` | Minimal | — |
| Python with uv | `templates/python-uv.mk` | Standard | — |
| Python FastAPI | `templates/python-fastapi.mk` | Full-featured | test split? prod target? `HEALTH_PATH`? |
| PostgreSQL + Alembic | `templates/postgres.mk` | Standard | `PG_PORT` (5433 default)? soft vs HARD reset? |
| Node.js | `templates/nodejs.mk` | Standard | — |
| Go | `templates/go.mk` | Standard | — |
| Chrome Extension | `templates/chrome-extension.mk` | Modular | — |
| Flutter App | `templates/flutter.mk` | Modular | — |
| Electron App | `templates/electron.mk` | Modular | — |
| Static Site (HTML/CSS/JS) | `templates/static-site.mk` | Standard | `DEPLOY_MODE` (rsync/gh-pages/netlify/vercel/none)? |

For templates in the "Asks upfront" column, run the Phase 2 interactive questions in §"Interaction Pattern" before scaffolding. Companion files:

- `templates/python-fastapi-env/.template.env` → project's `.template.env`
- `templates/python-fastapi-scripts/export_openapi_spec.py` → `scripts/export_openapi_spec.py`
- `templates/postgres-env/.template.env` → merge into project's `.template.env` (don't ship two)

### Chrome Extension Structure

The chrome extension template uses a modular structure:

```
Makefile                              # Main file with help + includes
makefiles/
  colors.mk                           # ANSI colors & print helpers
  common.mk                           # Shell flags, VERBOSE mode, guards
  build.mk                            # Build zip, version bump, releases
  dev.mk                              # Lint, clean, install
  test.mk                             # Unit tests, E2E tests, coverage
  env.mk                              # Environment setup, dependency checks
```

Copy from `templates/chrome-extension-modules/` to your project's `makefiles/` directory.

**Key features:**
- Use `makefiles/colors.mk` for ANSI color output and header helpers.
- Use `makefiles/common.mk` for shell flags, guard rails, and shared variables.
- Use `makefiles/env.mk` for environment checks and dependency sanity.
- Use `makefiles/build.mk` for build/package/release targets.
- Use `makefiles/dev.mk` for install, watch, clean, and other local workflows.
- Use `makefiles/test.mk` for typecheck, unit, and E2E targets when present.
- `build-release` - Version bump menu (major/minor/patch) + zip for Chrome Web Store
- `build-beta` - (Optional) GitHub releases with `gh` CLI
- `test-unit` / `test-e2e` - Vitest + Playwright testing
- `test-unit-<module>` / `test-e2e-<module>` - Per-module test targets
- `VERBOSE=1 make <target>` - Show commands for debugging

### Flutter App Structure

```
Makefile                    # Main file with help + includes
makefiles/
  colors.mk                # ANSI colors & print helpers
  common.mk                # Shell flags, VERBOSE mode, guards
  dev.mk                   # Setup, run simulator/device, devices, clean
  build.mk                 # iOS/Android builds (IPA, APK, AAB)
  deploy.mk                # TestFlight upload
  lint.mk                  # Dart analyze & format
```

Copy from `templates/flutter-modules/` to your project's `makefiles/` directory.

**Key features:**
- `flutter-run-ios` auto-boots simulator and waits for it
- `flutter-run-android` auto-launches emulator and waits for it
- `flutter-run-device` auto-detects or uses `FLUTTER_IOS_DEVICE` / `FLUTTER_ANDROID_DEVICE`
- `flutter-build-ipa` + `flutter-export-ipa` + `flutter-deploy-testflight` full iOS release workflow
- `flutter-export-ipa` re-exports IPA from existing archive without rebuilding
- `_check-asc-app` pre-flight App Store Connect validation (with ASC_API_KEY/ASC_API_ISSUER)
- `flutter-lint FIX=true` Dart formatting with FIX pattern
- `VERBOSE=1 make <target>` show commands for debugging

### Electron App Structure

```
Makefile                    # Main file with help + includes
makefiles/
  colors.mk                # ANSI colors & print helpers
  common.mk                # Shell flags, VERBOSE mode, guards
  dev.mk                   # Setup, dev server, debug, clean
  build.mk                 # Pack-check, dist (mac/win/linux), publish
  lint.mk                  # ESLint, Prettier, TypeScript, tests
```

Copy from `templates/electron-modules/` to your project's `makefiles/` directory.

**Key features:**
- `electron-dev` starts dev mode with hot-reload
- `electron-debug` launches with DevTools open
- `electron-clean` single target that removes artifacts, node_modules, and lock file
- `electron-pack-check` smoke-tests that the app loads without errors
- `electron-dist-mac` / `electron-dist-win` / `electron-dist-linux` cross-platform builds
- `electron-dist-all` builds for all platforms in one shot
- `electron-publish` publishes to GitHub Releases (requires `GH_TOKEN`)
- `electron-lint FIX=true` ESLint + Prettier with auto-fix pattern
- `electron-typecheck` TypeScript type checking
- `VERBOSE=1 make <target>` show commands for debugging

### Static Site (HTML/CSS/JS)

Plain static sites — landing pages, marketing pages, docs — with no bundler or SSR. Uses `npx --yes` for tooling so contributors don't need a local `package.json` or `node_modules`.

Copy `templates/static-site.mk` to your project root as `Makefile`.

Targets use `site-*` and `dev-*` prefixes (per §"Naming Conventions"). The template is deliberately slim — lint/link-check/image-optimization targets were cut because they're rarely run locally on a marketing page and collapse under the "too many granular `dev-*` quality targets" pitfall. Add them back only if a specific project needs them.

**Key features:**
- `site-serve` - local HTTP server via `python3 -m http.server` (falls back to `npx serve`). Override with `make site-serve PORT=9000 HOST=0.0.0.0`.
- `site-open` - open `$(ENTRY)` (default `index.html`) in the default browser (macOS `open` / Linux `xdg-open`).
- `site-status` - print site dir, entry, detected HTML pages, and tooling availability.
- `dev-format` - prettier `--write` across HTML/CSS/JS via `npx --yes`. No global install required, no `FIX=true` gate — always writes (formatting check-only is CI's job, not a local ergonomic).
- `dev-asset-report` - top 20 largest files (finds accidentally-committed hero images, uncompressed GIFs).
- `dev-build` - copies site into `$(BUILD_DIR)` (default `dist/`) via rsync with sensible excludes, then optionally minifies HTML/CSS/JS via `html-minifier-terser` (silently skipped if unavailable).
- `dev-deploy` - depends on `dev-build`; dispatches on `DEPLOY_MODE` (`rsync` | `gh-pages` | `netlify` | `vercel` | `none`). Fails fast with install hint if the selected tool is missing.
- `dev-clean` - removes `$(BUILD_DIR)/`.

**Config knobs (`?=` — override on command line):** `SITE_DIR`, `PORT`, `HOST`, `