Skip to content

Added codex-generated AGENTS.md #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+37 −0
Open

Added codex-generated AGENTS.md #16

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Repository Guidelines

## Project Structure & Module Organization
- Go module entrypoint `cmd/system-api/main.go`; runtime config in repo root (`systemapi-config.toml`, TLS fixtures).
- Core HTTP handlers, middleware, config loaders in `systemapi/`; shared logging/version helpers in `common/`; TLS primitives in `crypto/`.
- Tests live beside code (`systemapi/server_test.go`); docs and measurement fixtures under `docs/`; build artifacts land in `build/`.

## Build, Test, and Development Commands
- Use tabs instead of spaces for indentation.
- Always run `make fmt` and `make lint` (and `make test`) before committing.
- `make run` starts the API with the default config; pass `GOFLAGS` or `--config` for overrides.
- `make build` emits `build/system-api` with version metadata from `common.Version`.
- `make test`, `make test-race`, and `make cover` cover the unit suite, race detector, and coverage report respectively.
- `make fmt` then `make lint` ensure gofmt, gofumpt, gci, go vet, staticcheck, and golangci-lint all pass before review.

## Coding Style & Naming Conventions
- Code is gofmt/gofumpt formatted with tabs; prefer explicit names (`eventStore`, `tlsCertPath`) and singular file names.
- Document exported symbols with concise GoDoc comments and keep configuration passed through structs instead of globals.
- Secrets, ports, and paths should be injected via config or env; never hardcode sensitive values.
Copy link
Preview

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This guideline should specify that environment variables containing secrets should be clearly documented and mention potential risks of environment variable exposure in process lists.

Suggested change
- Secrets, ports, and paths should be injected via config or env; never hardcode sensitive values.
- Secrets, ports, and paths should be injected via config or environment variables; never hardcode sensitive values. Environment variables containing secrets must be clearly documented, and note that such secrets may be exposed in process lists or logs—consider using configuration files or secret managers where possible.

Copilot uses AI. Check for mistakes.


## Testing Guidelines
- Mirror the table-driven patterns in `systemapi/server_test.go` when adding cases; colocate new `*_test.go` files.
- Iterate with `go test ./systemapi -run <Name>` as needed, then finish with `make test-race` before pushing.
- Add coverage for authentication, TLS, and upload branches when touched; store ad hoc fixtures under `docs/` or temp dirs.
- Validate new config keys by asserting defaults, validation errors, and hot-reload behavior where relevant.

## Commit & Pull Request Guidelines
- Use imperative commit subjects similar to `git log` (`Add TLS reload hook`, optional `(#123)` suffix for PRs).
- PR descriptions should summarize behavior, list verification commands, and reference BuilderNet tickets or incidents.
- Attach screenshots or curl transcripts when API responses change; call out config updates in both the PR and `README.md`.
- Confirm `make fmt`, `make lint`, and `make test` in PR checklists; ensure reviewers can reproduce your steps quickly.

## Security & Configuration Tips
- Maintain `basic-auth-hash.txt` outside version control; rotate secrets through the `/api/v1/set-basic-auth` endpoint.
Copy link
Preview

Copilot AI Sep 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding guidance on proper file permissions for basic-auth-hash.txt (e.g., 600 or 640) to prevent unauthorized access to authentication credentials.

Suggested change
- Maintain `basic-auth-hash.txt` outside version control; rotate secrets through the `/api/v1/set-basic-auth` endpoint.
- Maintain `basic-auth-hash.txt` outside version control; set file permissions to `600` or `640` to prevent unauthorized access; rotate secrets through the `/api/v1/set-basic-auth` endpoint.

Copilot uses AI. Check for mistakes.

- Regenerate local certificates with the `cmd/tls-gen` helpers before shipping TLS changes.
- Keep `systemapi-config.toml` modifications minimal and documented so operators can diff with their deployments.
- Run `make clean` to clear generated binaries and temporary TLS assets before packaging artifacts.