Skip to content

CLAUDE.md

Latest commit

 

History

History
60 lines (45 loc) · 3.4 KB

CLAUDE.md

File metadata and controls

60 lines (45 loc) · 3.4 KB
Raw

bitbucket-cli

This is the master agent instruction file for this repository. Keep repository policy here. AGENTS.md exists only as a Codex compatibility shim and should contain only Codex-specific notes.

Project Structure & Module Organization

  • cmd/bkt/ contains the CLI entry point; the binary executes internal/bktcmd.
  • internal/ hosts non-exported wiring, including configuration (internal/config) and build metadata.
  • pkg/ holds reusable packages consumed by Cobra commands such as pkg/cmd/repo and pkg/bbdc.
  • Tests live alongside Go packages; add _test.go files next to the implementation.

Build, Test, and Development Commands

  • make build compiles the CLI with go build ./cmd/bkt.
  • make test or go test ./... runs the full unit test suite.
  • make fmt formats the codebase with go fmt ./....
  • make tidy syncs module dependencies with go mod tidy.
  • go run ./cmd/bkt --help is the quick local smoke test.
  • Windows-native development is supported: the same Make targets run under GNU Make with cmd.exe-pinned recipes, and the build-windows CI job is the source of truth for what works on Windows.

Coding Style & Naming Conventions

  • Follow standard Go conventions: tabs for indentation, PascalCase for exported identifiers, camelCase for private helpers.
  • Keep package names short and lowercase; command packages live under pkg/cmd/<topic>.
  • Prefer contextual errors such as fmt.Errorf("action: %w", err).
  • Run go fmt before committing; add comments only when the logic is not obvious.

Testing Guidelines

  • Prefer table-driven tests in _test.go files named Test<Subject>.
  • Use golden files under testdata/ when CLI output snapshots add value.
  • Cover flag parsing, API adapters, and error paths; mock HTTP interactions where needed.
  • Use go test ./pkg/... for faster package-focused iteration.

Release Contract

  • Release from master only through ./scripts/release.sh X.Y.Z and the resulting release PR; do not create manual tags or GitHub releases.
  • A push to master updates the AvivSinai marketplace immediately for the bkt skill.
  • Keep CHANGELOG.md and skill/plugin metadata on one version in the release commit; after the release PR merges, CI validates the merged commit, creates the tag, publishes GitHub/Homebrew artifacts, and uses the committed changelog entry as the GitHub release notes.
  • Official release binaries must keep Bitbucket Cloud browser OAuth (bkt auth login --kind cloud --web) zero-config by embedding bkt's OAuth consumer credentials through GoReleaser ldflags. Source and Nix builds may rely on BKT_OAUTH_CLIENT_ID / BKT_OAUTH_CLIENT_SECRET, but removing release-binary embedding is a breaking user-facing auth change and must not be done as generic security hardening. Keep scripts/check-oauth-release-contract.sh in CI/release verification.
  • See docs/RELEASE.md for the full release handbook.

Commit & Pull Request Guidelines

  • Use conventional commits such as feat:, fix:, docs:, ci:, or chore:.
  • Keep commits focused and descriptive; reference issues in the body when useful.
  • Pull requests should include a short summary plus testing notes such as go test ./....

Security & Configuration Tips

  • Never commit real credentials; the CLI reads tokens from $XDG_CONFIG_HOME/bkt/config.yml.
  • Use environment overrides such as BKT_CONFIG_DIR for sandbox testing without touching primary config.