gotenberg/.agents/DEVELOPER.md

# Developer Persona

You are implementing features, fixing bugs, or refactoring code in Gotenberg.

## Makefile — the Only Build Interface

All build and verification tasks go through the Makefile. Do not run `go` commands directly unless debugging a specific package.

| Command                 | Purpose                                                       | When to use                                                            |
| ----------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `make build`            | Build the Docker image                                        | Before integration tests, or to verify compilation                     |
| `make run`              | Run a Gotenberg container locally                             | Manual testing. Flags are configured via `.env` and Makefile variables |
| `make fmt`              | Format Go code (`go fix`, `golangci-lint fmt`, `go mod tidy`) | Before every commit                                                    |
| `make lint`             | Lint Go code (strict `.golangci.yml` config)                  | Before every commit. Zero errors permitted                             |
| `make lint-prettier`    | Lint non-Go files (Markdown, YAML, etc.) with Prettier        | Before every commit                                                    |
| `make prettify`         | Format non-Go files (Markdown, YAML, etc.) with Prettier      | Before every commit                                                    |
| `make test-unit`        | Run unit tests (`go test -race ./...`)                        | After code changes to `pkg/`                                           |
| `make test-integration` | Run integration tests (Gherkin/Godog, 40min timeout)          | After any feature or route change                                      |
| `make godoc`            | Serve GoDoc at `localhost:6060`                               | To verify documentation                                                |

## Module System

Gotenberg uses a self-registering module architecture inspired by CaddyServer. Each module:

- Lives in `pkg/modules/<name>/`
- Implements the `gotenberg.Module` interface (at minimum `Descriptor()`)
- May also implement `gotenberg.Provisioner`, `gotenberg.Validator`, or `gotenberg.Debuggable`
- Self-registers via `init()` and is wired through `pkg/standard/`

When adding a feature, first determine if it belongs in an existing module. Only create a new module if the feature represents a genuinely separate concern.

## Commit Convention

Commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:

```
<type>(<scope>): <description>
```

Common types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `ci`, `build`. The scope should match the module or area of the change (e.g., `chromium`, `pdfengines`, `api`).

## Adding PDF Engine Features

When adding a new PDF engine capability (e.g., bookmarks, watermark, stamp, embed), you must update the Makefile to include the corresponding engine list variable and flag. Every `--pdfengines-*-engines` flag registered in `pkg/modules/pdfengines/pdfengines.go` must have a matching entry in the Makefile:

1. **Add a variable** in the Makefile's variable block (around line 60-70):
   ```makefile
   PDFENGINES_<FEATURE>_ENGINES=<default engines>
   ```
2. **Add the flag** in the Makefile's command args block (around line 140-155):
   ```makefile
   --pdfengines-<feature>-engines=$(PDFENGINES_<FEATURE>_ENGINES) \
   ```

The default value should match what is defined in `pdfengines.go`'s `fs.StringSlice(...)` call for that flag.

## Coding Patterns

- **Error handling:** Always wrap errors with context using `fmt.Errorf("description: %w", err)`. Never swallow errors silently.
- **Import ordering:** Enforced by `gci` — standard library, then third-party, then `github.com/gotenberg/gotenberg/v8`. Three groups separated by blank lines.
- **Mocks:** Comprehensive mock implementations for all major interfaces live in `pkg/gotenberg/mocks.go`. Use these for unit tests.
- **No business logic in `cmd/`:** The `cmd/gotenberg/` package is strictly for wiring and startup.

## Documentation

- Do not modify `README.md` unless explicitly asked.
- Every exported function, type, constant, and variable must have a GoDoc comment starting with its name.
- New packages must include a `doc.go` file with package-level documentation.