Contributing to git-grass

Core Principles for Contributors

• Zero Cost Mandate: git-grass must remain free to run. Never introduce mandatory paid services, paid APIs, or required subscriptions.
• Zero Code Uploads: Never transmit user source code, file contents, diffs, or Git histories over the network.
• Non-Destructive Git Hooks: All hook modifications must strictly preserve existing user hooks and clean up completely on uninstall.
• Safe Process Execution: Never concatenate user input into shell commands. Always use child_process.execFile with argument arrays.

Local Development Setup

# 1. Clone your fork
git clone https://github.com/YOUR_USERNAME/git-grass.git
cd git-grass

# 2. Install dependencies
npm install

# 3. Run the test suite
npm test

# 4. Verify TypeScript compilation
npm run lint
npm run build

Adding New Challenges

You can contribute new domain challenges to challenges/fallback-challenges.json. Ensure every challenge adheres to:

• durationMinutes >= 10 (10-minute minimum)
• phoneFree: true (strictly physical and screen-free)
• Observational, safe, respectful of nature, and non-intrusive

Submitting a Pull Request

1. Create a feature branch: git checkout -b feat/my-new-feature.
2. Follow Conventional Commits (e.g. feat: ..., fix: ..., docs: ...).
3. Ensure all tests pass: npm test.
4. Ensure the TypeScript build passes: npm run build.
5. Submit your Pull Request on GitHub with a clear description of your changes.