CLAUDE.md

# CLAUDE.md

One `bitrise` binary, two halves: the local workflow runner (`bitrise local run`,
steps, tool provisioning, plugins) and the cloud commands (`app`, `build`, `stack`,
`auth`, `config`, `user`, `yml`, `api`, `rde`, `purr`). Cobra only - the `urfave/cli`
entry in `go.mod` is indirect and imported nowhere.

## Layering

```
cli/<group>/        cobra only: flags, arg validation, rendering
internal/<domain>/  service layer: stack, build, app, rde, yml, user, api
internal/bitriseapi, internal/rdeapi, internal/webclient   HTTP clients
```

An HTTP call or a business rule inside `cli/` is a review finding.

Detail lives in nested files, loaded when you touch those trees: `cli/CLAUDE.md`,
`internal/CLAUDE.md`, `cli/rde/CLAUDE.md`, `integrationtests/CLAUDE.md`.

## Commands

- `go build ./...`
- `go test ./...` (CI adds `-p 1`)
- `golangci-lint run` - CI installs v2.6.0; `.golangci.yml` adds `revive` and `unparam`
- `make docs` - regenerates `docs/cli/*.md` and the README command table.
  **IMPORTANT: run it after any change to a command, flag or help string.** CI runs
  `make docs-check`, which regenerates and fails if the result differs from what was
  committed.
- `go mod tidy` and `go mod vendor` move together

Integration tests are a separate module: see `integrationtests/CLAUDE.md`.

## Style

- Comment reasoning, external-system behavior, or a reference. Never restate the code.
- Helpers go after their callers, in production and test files alike.
- No single-use helper unless it encapsulates a coherent piece of logic.
- No lint suppression for a linter `.golangci.yml` does not enable.
- Don't build for a requirement that does not exist yet.

## Acting on review findings

Work not yet done (an old convention unapplied, a missing test) can be named and left.
Code that behaves or renders incorrectly today gets fixed now, and every other
occurrence of the same defect goes in the same pass. Scope discipline governs new
abstractions, not correctness.

## Gotchas

- `docs/cli/*.md` and the README table between the `commands-overview` markers are
  generated by `tools/gendocs`.
- Docs state the current state. Rewrite what is now wrong rather than appending a
  dated correction beside it.
- `log/models.go` and `log/corelog/` define a schema downstream systems consume.
  Renaming, retyping or removing a JSON field breaks them.
- `--format json`/`yml` output is a contract: additive changes only.
- `go test ./plugins/...` fails with a `stepman --version` error unless `bitrise setup`
  has run. `validatePlugin` probes all three tools whatever the plugin declares.

## Areas with their own conventions

Match the area you are editing. Do not normalize it, and do not carry its patterns out.

- `cli/local`, `cli/step`, `cli/plugin`, `bitrise/`, `toolprovider/`, `plugins/`,
  `stepruncmd/`, `configmerge/` follow older conventions.
- `cli/rde` differs for historical reasons. `cli/rde/CLAUDE.md` lists exactly how and
  is required reading before editing that tree.