Contributing
Thanks for contributing. This document covers the local development loop; see README.md for project behavior and public APIs. Participation is governed by the TunaOS Code of Conduct.
Contribute compute — no code needed
Your machine runs one task at a time using your signed-in AI coding CLI. The relay alternates between eligible School (OS) and Reef (apps) hives after each task. If one hive has no work, the other can continue.
The guide covers prerequisites, verified just setup, credentials, provider
costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply.
Never post account credentials or API keys in issues or pull requests.
Set up
- Install Go 1.24 or newer (see
go.mod). - Clone the repository and download dependencies with
go mod download. - Install Docker only when changing the
Dockerfileor running thedockerCI job locally. - Install a C compiler such as
gccto run tests with-race; plaingo testdoes not require one.
Build the library and CLI:
go build ./...
Build and test
Run the same checks CI runs, in this order:
gofmt -l . # must print nothing
go vet ./...
go test -race -count=1 ./... # drop -race if no C compiler is available
CGO_ENABLED=0 go build -trimpath -o /dev/null ./cmd/ccleft
If gofmt -l . prints any file paths, run gofmt -w . before committing.
For Dockerfile changes, also run docker build -t ccleft:local ..
CI also runs govulncheck (.github/workflows/govulncheck.yml) on every pull
request, on pushes to main, and weekly. Run it locally with:
go install golang.org/x/vuln/cmd/govulncheck@v1.9.0
govulncheck ./...
Standard-library findings depend on the Go toolchain that runs the scan. CI
scans with the toolchain of the golang build image pinned in the
Dockerfile, so a local Go older than that pin can report findings CI does
not; the workflow file has the exact docker run command CI uses. A new Go
security release or advisory can fail this check on a pull request that
changed nothing related. The fix is then a Dockerfile digest or dependency
bump.
Provider behavior is tested with httptest servers and recorded payloads under
testdata/. Tests must not contact live provider APIs or
require credentials. live_test.go means its fixtures originated from
live verification; the tests still run offline. When live verification is
needed, use a read-only account, redact the response before adding it, and
record its provenance in testdata/README.md.
Add or change a provider
Keep provider-specific credential discovery and response parsing in its own file. Follow an existing implementation and complete each part:
- Add the provider name and public state/window vocabulary in
reading.go. - Implement and register an
implwith separateidentifyandfetchfunctions.identifyreads local credentials without network access;fetchperforms the bounded upstream request or CLI invocation. - Derive every credential path from
Source.Homeor an explicit source environment override. Never use the process's home implicitly. - Add the provider timeout to
DefaultTimeouts, and update detection or CLI configuration when automatic discovery applies. - Map the response to normalized
Windowvalues. SetKind,Unit,Binding, usage values, and reset time deliberately; usederiveStatewhere the standard window rules apply. - Add synthetic or redacted fixtures,
httptestcoverage for successful and failure responses, and update the provider tables inREADME.md.
Use existing error helpers and preserve upstream context:
auth_required: credentials are absent, expired, or rejected.rate_limited: the quota endpoint itself throttled the request.unsupported: the login or provider has no quota source to query.error: network, timeout, schema, or other measurement failure.
Do not turn an unrecognized response into an ok reading. Return a stable
machine-readable cause plus a useful wrapped error, without exposing secrets.
Security-sensitive changes
ccleft is read-only by design (see README's Security section). It must never
write, refresh, or change permissions on credential files, and it must never
shell out to a CLI that could mutate one (codex, claude). Call out changes
to credential discovery or the agy execution path in the PR description.
Fixtures must contain no real tokens, account identifiers, or personal data.
Submit a pull request
- Branch from
mainusing the organization prefixesfix/,feat/,chore/, orarch/. - Use Conventional Commit subjects, such as
fix: ...ordocs: .... - Sign off every commit for DCO compliance with
git commit -s. - Run the checks above and update docs or fixture provenance affected by the change.
- Open a focused PR that explains behavior, tests, and any credential or live verification work.
A TunaOS maintainer reviews and merges after required CI checks pass and review feedback is resolved. This repository is maintained directly rather than as a fork; no upstream synchronization step is required. Keep NOTICE accurate when importing or adapting external work.
License
By contributing, you agree that your contribution is licensed under Apache-2.0 (see LICENSE).