Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
188 lines (146 loc) · 6.37 KB

CONTRIBUTING.md

File metadata and controls

188 lines (146 loc) · 6.37 KB
Raw

Contributing to AgentSecrets

Thanks for your interest in contributing! AgentSecrets is built in the open, and we welcome contributions from everyone.

Quick Start

# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/agentsecrets
cd agentsecrets

# Install Go (1.21+)
# macOS: brew install go
# Linux: snap install go --classic
# Windows: Download from https://go.dev/dl/

# Download dependencies
go mod download

# Run the CLI
go run cmd/agentsecrets/main.go --help

# Run tests
go test ./...

# Build binary
go build -o agentsecrets cmd/agentsecrets/main.go
./agentsecrets --help

Development Workflow

  1. Create a feature branch: git checkout -b feature/your-feature
  2. Make changes: Edit code, add tests
  3. Test: Run go test ./...
  4. Format: Run go fmt ./...
  5. Commit: Use clear commit messages
  6. Push: git push origin feature/your-feature
  7. PR: Open a pull request on GitHub

Code Style

We follow standard Go conventions:

  • Format: Use go fmt (enforced in CI)
  • Linting: Use golangci-lint (coming soon)
  • Naming:
    • Exported functions: PascalCase
    • Unexported functions: camelCase
    • Constants: PascalCase or UPPER_CASE
  • Errors: Return errors, don't panic
  • Comments: Public functions must have doc comments

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests verbosely
go test -v ./...

# Test specific package
go test ./pkg/crypto/...
go test ./pkg/proxy/...
go test ./pkg/auth/...

Project Structure

agentsecrets/
├── cmd/agentsecrets/              # CLI entry point + commands
│   ├── main.go
│   └── commands/
│       ├── root.go                # Root command + auth middleware
│       ├── init.go                # Account creation + workflow template
│       ├── login.go / logout.go   # Session management
│       ├── status.go              # Current context
│       ├── workspace.go           # Workspace management
│       ├── allowlist.go           # Zero-trust domain allowlist
│       ├── project.go             # Project management
│       ├── secrets.go             # Secrets CRUD + sync
│       ├── proxy.go               # HTTP proxy + audit logs
│       ├── call.go                # One-shot authenticated calls
│       ├── env.go                 # Env var injection into child processes
│       ├── mcp.go                 # MCP server + install
│       └── exec.go                # OpenClaw exec provider
├── pkg/
│   ├── api/                       # HTTP API client
│   ├── auth/                      # Authentication + JWT refresh middleware
│   ├── config/                    # Global config + project config
│   ├── crypto/                    # X25519 + AES-256-GCM + Argon2id
│   ├── keychainauth/              # keychain-auth daemon integration
│   ├── keyring/                   # OS keychain integration
│   ├── mcp/                       # MCP server implementation
│   ├── projects/                  # Project API wrappers
│   ├── proxy/                     # Proxy engine, injector, audit logger
│   ├── secrets/                   # Secret management + dotenv
│   ├── telemetry/                 # Local usage tracking + background sync
│   ├── ui/                        # Terminal UI components
│   └── workspaces/                # Workspace + allowlist API wrappers
├── integrations/openclaw/         # OpenClaw skill (SKILL.md)
├── docs/                          # Documentation
│   ├── commands/                  # Per-command reference docs
│   └── learning/                  # Tutorials and guides
└── .agent/workflows/              # AI assistant workflow (generated by init)

What We Need Help With

High Priority

  • Test coverage (aiming for 80%+)
  • Error message improvements (agents read these — clarity matters)
  • LangChain + CrewAI first-party integrations
  • Documentation (examples, guides, tutorials)

Medium Priority

  • Secret rotation
  • Web dashboard (separate repo)
  • CI/CD pipeline improvements
  • JavaScript / Node.js SDK

Low Priority

  • SSO integration
  • Plugin system for custom auth styles
  • Performance benchmarking

Security Rules for Contributors

These are non-negotiable. PRs violating them will be rejected:

  1. Never log credential values — not stdout, not stderr, not files, not audit logs
  2. Never pass credential values as function arguments where avoidable — pass key names and resolve at the last possible moment via pkg/keyring
  3. Never write credential values to any file — keychain only for StorageMode 1
  4. The audit log struct must never gain a value field
  5. All new cloud sync operations must use pkg/crypto — no plaintext uploads
  6. Domain allowlist enforcement must not be bypassable — all outbound proxy calls go through allowlist check

Commit Message Format

We use conventional commits:

feat: add secrets rotation command
fix: handle network errors gracefully
docs: update installation instructions
test: add crypto package tests
refactor: simplify workspace switching logic
chore: update dependencies

Pull Request Guidelines

  1. Title: Clear, descriptive (e.g., "Add secrets rotation command")
  2. Description:
    • What does this PR do?
    • Why is it needed?
    • How was it tested?
  3. Tests: Add tests for new features
  4. Docs: Update docs if needed
  5. Size: Keep PRs focused and reasonably sized

Questions?

  • GitHub Issues: For bugs and feature requests
  • GitHub Discussions: For questions and ideas

Learning Go?

Great resources:

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thanks for contributing to making secrets management better for the AI era!