Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
SecretForge AI provides a structured framework for contributors to ensure code quality, security, and consistency across its AI-powered secret management platform. The guidelines establish a zero-trust development environment where automated checks handle linting, type safety, and security scanning.
The scope of these guidelines covers the entire monorepo, including the Cloudflare Workers API, the Next.js web dashboard, the CLI tool, and the MCP server integration. Contributors are expected to follow the Conventional Commits standard and utilize the provided Husky hooks to maintain the integrity of the codebase.
Sources: CONTRIBUTING.md:1-5, README.md:100-117, WARP.md:46-52
Getting Started
To begin contributing, developers must set up a local environment that mirrors the production edge-native stack. This involves cloning the repository, installing dependencies via pnpm, and configuring environment variables.
Initial Setup Sequence
The setup process ensures all local services, including Ollama and Docker-based databases, are operational before development begins.
Sources: WARP.md:15-43, CONTRIBUTING.md:10-25
Development Workflow
SecretForge AI follows a feature-branch workflow. All changes must be made in dedicated branches and submitted via Pull Requests.
Commit Standards
The project strictly enforces Conventional Commits to automate versioning and changelog generation.
| Type | Description |
|---|---|
feat: | A new feature |
fix: | A bug fix |
docs: | Documentation only changes |
test: | Adding missing tests or correcting existing tests |
refactor: | A code change that neither fixes a bug nor adds a feature |
chore: | Changes to the build process or auxiliary tools |
perf: | A code change that improves performance |
style: | Changes that do not affect the meaning of the code |
| Sources: CONTRIBUTING.md:43-56, AUTOMATION_SUMMARY.md:41-44 |
Branching and PRs
- Create Feature Branch:
git checkout -b feature/your-feature-name - Implementation: Follow existing patterns and add tests.
- Verification: Run
pnpm test,pnpm lint, andpnpm build. - Submission: Open a PR using the provided template, which requires descriptions of "What", "Why", "How", and "Testing".
Sources: CONTRIBUTING.md:27-41, CONTRIBUTING.md:112-118
Automated Processes
The repository utilizes extensive automation to enforce standards without manual intervention.
Git Hooks (Husky)
Husky manages local hooks that run before code is committed or messages are finalized.
This flow prevents non-compliant code or poorly formatted commit messages from entering the history.
Sources: CONTRIBUTING.md:61-75, AUTOMATION_SUMMARY.md:46-52
CI/CD Pipeline
Every push and pull request triggers a comprehensive GitHub Actions workflow.
| Stage | Tool | Purpose |
|---|---|---|
| Linting | ESLint | Enforces TypeScript quality and import ordering |
| Type Checking | tsc | Validates strict TypeScript types |
| Security | TruffleHog | Scans for hardcoded secrets and credentials |
| Security | CodeQL | Scans for vulnerabilities and quality issues |
| Testing | Vitest/Codecov | Executes unit tests and tracks coverage (>80% target) |
| Dependency | pnpm audit | Checks for known vulnerabilities in packages |
| Sources: CONTRIBUTING.md:77-88, AUTOMATION_SUMMARY.md:10-31, SYSTEM_EVALUATION.md:65-90 |
Coding Standards
TypeScript
- Use strict mode.
- Prefer
constoverlet. - Explicitly define function parameters and return types.
- Avoid
anyat all costs.
Sources: CONTRIBUTING.md:95-101, SYSTEM_EVALUATION.md:200-210
Security-First Implementation
Contributors must adhere to the encryption standards established in Phase 1. Any new secret handling must use the CryptoProvider which implements AES-256-GCM with a random 12-byte IV per encryption.
Sources: SYSTEM_EVALUATION.md:100-115, PHASE1_IMPLEMENTATION.md:65-80
Project Structure
The monorepo is organized by package responsibility:
secretforge-ai/
├── packages/
│ ├── api/ # Cloudflare Workers (Hono API)
│ ├── cli/ # Commander.js CLI tool
│ ├── mcp-server/ # Model Context Protocol integration
│ ├── web/ # Next.js frontend dashboard
│ └── shared/ # Common utilities and security logic
Sources: CONTRIBUTING.md:90-93, README.md:139-160, WARP.md:55-63
Summary
Contributing to SecretForge AI requires a commitment to automated quality and security. By utilizing Husky hooks for local validation and adhering to the Conventional Commits standard, contributors help maintain a platform that is secure by default. All submissions must pass the CI/CD pipeline, which includes rigorous security scanning via CodeQL and TruffleHog to ensure no secrets are ever exposed during the development process.
Sources: AUTOMATION_SUMMARY.md:120-135, SYSTEM_EVALUATION.md:315-330