[PPSC-280] docs: add oss best practices and developer tooling

.editorconfig

@@ -0,0 +1,33 @@
+# EditorConfig helps maintain consistent coding styles across editors
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.go]
+indent_style = tab
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = false
+
+[*.json]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.sh]
+indent_style = space
+indent_size = 4

.github/CONTRIBUTING.md

@@ -1,6 +1,15 @@
 # Contributing
 
-Thanks for your interest in contributing!
+Thanks for your interest in contributing to the Armis CLI!
+
+## Table of Contents
+
+- [Scope](#scope)
+- [Development Setup](#development-setup)
+- [Code Style](#code-style)
+- [Testing](#testing)
+- [Contribution Process](#contribution-process)
+- [License](#license)
 
 ## Scope
 
@@ -15,12 +24,204 @@ the Armis cloud APIs. Contributions should focus on:
 Security detection logic, analysis engines, and backend services are
 intentionally out of scope.
 
+## Development Setup
+
+### Prerequisites
+
+- Go 1.24 or later
+- [golangci-lint](https://golangci-lint.run/welcome/install/) v2.0+
+- Make
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/ArmisSecurity/armis-cli.git
+cd armis-cli
+
+# Install dev tools (gotestsum for better test output)
+make tools
+
+# Build the binary
+make build
+
+# Run tests
+make test
+
+# Run linters
+make lint
+```
+
+### Available Make Targets
+
+| Target | Description |
+|--------|-------------|
+| `make build` | Build the binary to `bin/armis-cli` |
+| `make test` | Run tests with gotestsum (or go test as fallback) |
+| `make lint` | Run golangci-lint |
+| `make install` | Install binary to `/usr/local/bin` |
+| `make clean` | Remove build artifacts |
+| `make tools` | Install development tools |
+| `make scan` | Run security scan on this repository |
+
+## Code Style
+
+### Formatting
+
+- All code must be formatted with `gofmt`
+- Use tabs for indentation (Go standard)
+- Run `gofmt -w .` before committing or use editor integration
+
+### Linting
+
+We use [golangci-lint](https://golangci-lint.run/) with the following linters enabled:
+
+| Linter | Purpose |
+|--------|---------|
+| `errcheck` | Check for unchecked errors |
+| `govet` | Report suspicious constructs |
+| `ineffassign` | Detect ineffectual assignments |
+| `staticcheck` | Advanced static analysis |
+| `unused` | Find unused code |
+| `gosec` | Security-focused linting |
+| `goconst` | Find repeated strings that could be constants |
+| `misspell` | Catch common spelling mistakes |
+
+Run `make lint` to check your code before submitting.
+
+### Error Handling
+
+- Always wrap errors with context using `fmt.Errorf("context: %w", err)`
+- Provide actionable error messages for user-facing errors
+- Don't ignore errors; use `_ = fn()` explicitly if intentional
+
+```go
+// Good
+if err != nil {
+    return fmt.Errorf("failed to read config: %w", err)
+}
+
+// Bad
+if err != nil {
+    return err  // Missing context
+}
+```
+
+### Comments
+
+- Add package-level comments to all packages
+- Document exported functions and types
+- Focus on "why" rather than "what" in inline comments
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+make test
+
+# Run with verbose output
+go test -v ./...
+
+# Run specific package tests
+go test -v ./internal/api/...
+
+# Run with race detection
+go test -race ./...
+
+# Run with coverage
+go test -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out
+```
+
+### Writing Tests
+
+- Use table-driven tests for multiple test cases
+- Place tests in the same package as the code being tested
+- Use meaningful test names that describe the scenario
+
+```go
+func TestFormatBytes(t *testing.T) {
+    tests := []struct {
+        name     string
+        bytes    int64
+        expected string
+    }{
+        {"zero bytes", 0, "0B"},
+        {"kilobytes", 1024, "1.0KiB"},
+        {"megabytes", 1048576, "1.0MiB"},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := formatBytes(tt.bytes)
+            if result != tt.expected {
+                t.Errorf("got %s, want %s", result, tt.expected)
+            }
+        })
+    }
+}
+```
+
+### Test Utilities
+
+- HTTP test helpers are available in `internal/testutil/`
+- Sample test data is in `test/` directory
+
 ## Contribution Process
 
-1. Fork the repository
-2. Create a feature branch
-3. Add tests where applicable
-4. Submit a pull request with a clear description
+1. **Fork the repository** and clone it locally
+
+2. **Create a feature branch** from `main`:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make your changes**:
+   - Keep commits focused and atomic
+   - Write clear commit messages
+
+4. **Run quality checks**:
+
+   ```bash
+   make lint
+   make test
+   ```
+
+5. **Submit a pull request**:
+   - Fill out the PR template completely
+   - Link related issues
+   - Ensure CI passes
+
+### Commit Messages
+
+Follow conventional commit style:
+
+```text
+type: brief description
+
+Longer explanation if needed.
+
+Fixes #123
+```
+
+Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
+
+### Pull Request Guidelines
+
+- Keep PRs focused on a single change
+- Update documentation if behavior changes
+- Add tests for new functionality
+- Ensure all CI checks pass
+- Respond to review feedback promptly
+
+## Reporting Issues
+
+- **Bugs**: Use the [bug report template](https://github.com/ArmisSecurity/armis-cli/issues/new?template=bug_report.md)
+- **Features**: Use the [feature request template](https://github.com/ArmisSecurity/armis-cli/issues/new?template=feature_request.md)
+- **Security**: See [SECURITY.md](./SECURITY.md) for vulnerability reporting
 
 ## License
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,28 +7,34 @@ assignees: ''
 ---
 
 ## Description
+
 A clear and concise description of the bug.
 
 ## Steps to Reproduce
-1. 
-2. 
-3. 
+
+1.
+2.
+3.
 
 ## Expected Behavior
+
 What you expected to happen.
 
 ## Actual Behavior
+
 What actually happened.
 
 ## Environment
+
 - OS: [e.g., Ubuntu 22.04, macOS 13.0, Windows 11]
 - armis-cli version: [e.g., v1.0.0]
 - Go version (if building from source): [e.g., 1.21.0]
 - Installation method: [binary, go install, docker, etc.]
 
 ## Additional Context
+
 Add any other context, logs, or screenshots about the problem here.
 
-```
+```text
 # Paste relevant logs or command output here
 ```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,16 +7,21 @@ assignees: ''
 ---
 
 ## Problem Statement
+
 A clear description of the problem this feature would solve.
 
 ## Proposed Solution
+
 Describe your proposed solution or feature.
 
 ## Alternatives Considered
+
 Describe any alternative solutions or features you've considered.
 
 ## Use Case
+
 Describe how this feature would be used and who would benefit from it.
 
 ## Additional Context
+
 Add any other context, mockups, or examples about the feature request here.

.github/ISSUE_TEMPLATE/security_issue.md

@@ -13,6 +13,7 @@ assignees: ''
 Please report security vulnerabilities by following the process in our [SECURITY.md](../../SECURITY.md) file.
 
 For responsible disclosure:
+
 1. Email security contact listed in SECURITY.md
 2. Include detailed description and reproduction steps
 3. Allow time for patch before public disclosure

.github/SECURITY.md

@@ -20,9 +20,10 @@ We take security issues seriously and appreciate responsible disclosure.
 If you believe you have identified a security vulnerability in this CLI,
 please report it **privately by email**.
 
-**Email:** security@armis.com
+**Email:** <security@armis.com>
 
 When reporting, please include:
+
 - CLI version
 - Operating system and runtime environment
 - Clear steps to reproduce or a proof of concept
@@ -102,4 +103,4 @@ Our vulnerability disclosure approach aligns with widely accepted
 responsible disclosure practices, including those described in the
 Armis Vulnerability Disclosure Policy:
 
-https://www.armis.com/legal-compliance/vulnerability-disclosure-policy/
+<https://www.armis.com/legal-compliance/vulnerability-disclosure-policy/>