# codereview-cli Development Guide

This is the repo-local guide for codereview-cli-specific facts. Shared Open CLI
Collective standards and automation remain canonical in their own repositories.

## Project Overview

codereview-cli is the Open CLI Collective code-review CLI and ships the `cr`
binary. It provides configuration and credential commands, trusted-agent
inspection, dry-run and live pull-request review orchestration, named LLM
session management, and local data lifecycle commands.

The current Go code is a Cobra command tree in `internal/cmd/*` with a thin
`cmd/cr` entrypoint, shared exit-code mapping in `internal/cmd/exitcode`, and
version plumbing in `internal/version`. Review orchestration is split across
`internal/pipeline`, `internal/reviewrun`, `internal/reviewplan`,
`internal/outbox`, `internal/gate`, and `internal/gateio`.

Within `internal/pipeline`, the public entry points are `DryRun`, `Live`, and
`SelectionOnly`. `DryRun` and `Live` execute the full review pipeline, while
`SelectionOnly` runs just the selection phase with caller-owned artifact paths
and no ledger or posting side effects so benchmark tooling can reuse the real
selector implementation.

## Quick Commands

```bash
make build   # compile the binary
make test    # go test ./...
make lint    # golangci-lint run
make tidy    # go mod tidy and verify go.mod is unchanged
make deps    # download and verify Go modules
make check   # tidy + fmt + lint + test + build
make clean   # remove build artifacts
```

`make snapshot` runs a local GoReleaser snapshot build without publishing.

## Repo-Local Shape

- Module: `github.com/open-cli-collective/codereview-cli`
- Intended binary: `cr`
- Main branch: `main`
- Local workflow files: `.github/workflows/ci.yml`,
  `.github/workflows/auto-release.yml`, and `.github/workflows/release.yml`
- Packaging identity: `packaging/identity.yml`
- Current distribution status: GitHub release archives plus standard package
  channels declared in `packaging/identity.yml`.
- Application package layering follows the active codereview implementation:
  command glue in `internal/cmd/*`, presentation in `internal/view`,
  state/config adapters in `internal/config`, `internal/ledger`, and
  `internal/statepaths`, provider/LLM adapters in their owning packages, and
  review posting/gating in `internal/outbox`, `internal/gate`, and
  `internal/gateio`.

## Interactive Init Notes

`cr init` interactive mode only collects non-secret configuration. When the
selected LLM auth mode is `api_key`, the wizard saves the non-secret profile
shape and prints a follow-up `cr set-credential` command instead of collecting
the API key inline.

Interactive `git.host` edits now route through the repository-route stage when
the target profile already participates in `repository_profiles` routing. The
wizard shows the affected routes, lets the user reconcile or remove them, and
rejects preserved routes whose host no longer matches the selected profile.

Default repo builds now compile 1Password keyring backend support in by keeping
`keyring_nopassage` but dropping `keyring_no1password` from shipped build tags.
CI still runs an explicit `keyring_no1password` opt-out test path plus a
`CGO_ENABLED=0` smoke test so unsupported build modes fail intentionally rather
than drifting unnoticed.

Use the `keyring_no1password` build tag for distributions that must exclude
1Password integration entirely, such as FIPS-constrained, air-gapped, or
otherwise compliance-scoped builds. In that mode the named secrets-management
workflow hides all 1Password backends and validation rejects 1Password-backed
config up front instead of failing later at runtime.

## Release Secrets

`auto-release.yml` passes `RELEASE_TAG_TOKEN` to the shared auto-release
workflow as its `tag-token`. That credential must be separate from
`GITHUB_TOKEN` so tag pushes retrigger `release.yml`, and separate from
package-channel credentials. The preferred long-term shape is the GitHub App
installation-token path described in the shared release standard; until that is
wired through, use a narrowly scoped `RELEASE_TAG_TOKEN`.

`TAP_GITHUB_TOKEN` is only for Homebrew tap pushes from the release workflow.
Do not reuse it for auto-release tag pushes.

Package-channel releases also use `CHOCOLATEY_API_KEY`,
`WINGET_GITHUB_TOKEN`, and `LINUX_PACKAGES_DISPATCH_TOKEN` according to the
shared distribution secret table.

## Package Channel Release Mechanics

`release.yml` delegates package publishing to the shared reusable release
workflow. Repo-local files declare package identity and native metadata; the
shared workflow owns publish mechanics.

- Homebrew: GoReleaser renders `dist/homebrew/Casks/codereview-cli.rb` with
  `skip_upload: true`; the shared Homebrew job pushes that generated cask to
  `open-cli-collective/homebrew-tap` with `TAP_GITHUB_TOKEN`.
- Chocolatey: the shared Chocolatey job rewrites
  `packaging/chocolatey/codereview-cli.nuspec` from version `0.0.0` to the release version
  and replaces `CHECKSUM_AMD64_PLACEHOLDER` /
  `CHECKSUM_ARM64_PLACEHOLDER` in `chocolateyInstall.ps1` before packing and
  pushing.
- winget: the shared winget job resolves the release asset URLs/checksums and
  submits `OpenCLICollective.codereview-cli` with `WINGET_GITHUB_TOKEN`;
  because this is a first-time package id, `packaging/identity.yml` keeps
  `packages.winget.bootstrap: true` until the package exists upstream.
- Linux packages: GoReleaser renders `.deb` and `.rpm` artifacts named `cr`;
  the shared workflow dispatches `package-release` to
  `open-cli-collective/linux-packages` with `LINUX_PACKAGES_DISPATCH_TOKEN`.

`make snapshot` runs a local GoReleaser snapshot and then
`scripts/verify-package-render.sh`, which asserts the rendered cask, deb/rpm
artifacts, native package templates, and release secret wiring match the
declared package IDs.

## Shared Standards

Use these sources for shared policy. Do not copy their mechanics into this file.

```md
Source of truth: https://github.com/open-cli-collective/cli-common/blob/main/docs/repo-layout.md
Local convenience copy, if present: `../cli-common/docs/repo-layout.md`

Source of truth: https://github.com/open-cli-collective/cli-common/blob/main/docs/ci.md
Local convenience copy, if present: `../cli-common/docs/ci.md`

Source of truth: https://github.com/open-cli-collective/cli-common/blob/main/docs/release.md
Local convenience copy, if present: `../cli-common/docs/release.md`

Source of truth: https://github.com/open-cli-collective/cli-common/blob/main/docs/distribution.md
Local convenience copy, if present: `../cli-common/docs/distribution.md`
```

## Shared Automation

Use `open-cli-collective/.github` for shared action and reusable workflow
implementations.

```md
Source of truth: https://github.com/open-cli-collective/.github
Local convenience copy, if present: `../.github`
```

## Repo Policy Summary

Keep `main` protected, require reviewed pull requests, keep the shared checks
green, use squash merge, and delete branches after merge. For the exact branch
protection and check contracts, use the shared standards above.