diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0efb83b..8723714 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,173 +1,67 @@ -# Contributing to RA-H +# Contributing to RA-H Open Source -Thank you for your interest in contributing to RA-H! This guide explains how to work inside the private repo that powers the packaged Mac app. +This is the **open source mirror** of a private repository. Features are developed privately and synced here periodically. -> **Licensing note:** By contributing, you agree that your contributions are provided under the [PolyForm Noncommercial License 1.0.0](LICENSE). If you need a commercial exception, contact hello@ra-h.app before submitting changes. +## How to Contribute -## ๐ŸŽฏ Ways to Contribute +### Bug Reports & Feature Requests +Open an [issue](../../issues). Include: +- What you expected vs what happened +- Steps to reproduce (for bugs) +- Your environment (OS, Node version, browser) -- **๐Ÿ› Bug Reports**: Found a bug? Let us know! -- **๐Ÿ’ก Feature Requests**: Have ideas for new features? -- **๐Ÿ“ Documentation**: Help improve our docs -- **๐Ÿ”ง Code Contributions**: Fix bugs or implement features -- **๐Ÿงช Testing**: Help us test new features and find edge cases +### Code Contributions +We accept pull requests for: +- **Bug fixes** - especially ones you've encountered +- **Documentation improvements** - typos, clarifications, examples +- **Small enhancements** - that don't require architectural changes -## ๐Ÿš€ Getting Started +For **larger features**, open an issue first to discuss. Major features are typically implemented in the private repo and synced here. -### Development Setup -Begin with `docs/development/process/0_kickstart.md` for internal context. When touching the desktop build, read `docs/development/process/6_macpack.md` so you follow the packaging checklist. `docs/9_open-source.md` simply tracks the future BYO-key repo idea; there is no public OSS workflow today. +## Development Setup -### Development Workflow -**Important**: We use Claude Code for all development. Follow the 7-step workflow documented in `docs/development/process/1_workflow.md`: - -1. **Review** - Read handoff and workflow docs -2. **Branch** - Create feature branch (NEVER work on main) -3. **Plan** - Write PRD and get approval -4. **Implement** - Code with user testing -5. **Document** - Update handoff and CLAUDE.md -6. **Commit** - Save and merge to main -7. **Cleanup** - Delete branch, confirm clean state - -### Quick Commands ```bash -# Start new feature -git checkout main && git pull && git checkout -b feature/your-name - -# Basic development -npm run build && npm run type-check && npm run lint - -# Clean generated artefacts before committing -npm run clean:local +git clone https://github.com/bradwmorris/ra-h_os.git +cd ra-h_os +npm install +npm rebuild better-sqlite3 +scripts/dev/bootstrap-local.sh +npm run dev ``` -## ๐Ÿ“ Code Standards +Open http://localhost:3000 and add your API keys. -### TypeScript -- Use strict TypeScript - no `any` types unless absolutely necessary -- Provide proper type definitions for all functions and objects -- Use meaningful interface names +## Before Submitting a PR -### React/Next.js -- Use functional components with hooks -- Follow Next.js App Router patterns -- Use proper error boundaries +```bash +npm run build +npm run type-check +npm run lint +``` -### Database -- All database operations must use the service layer (`/src/services/database/`) -- No direct SQL in components - use service methods -- Include proper error handling +All three must pass. -### Styling -- Use Tailwind CSS utilities -- Follow the existing color scheme (dark theme) -- Ensure responsive design +## Code Style -## ๐Ÿ—๏ธ Project Architecture +- TypeScript with strict types (avoid `any`) +- Functional React components +- Tailwind CSS for styling +- Database operations through service layer (`/src/services/database/`) -See `docs/overview.md` for complete system architecture. +## What Happens to Your Contribution -### Key Patterns -- Use service layer for all database operations -- Components organized by feature area -- Helpers are JSON-configured AI assistants -- All development follows 7-step Claude Code workflow +1. We review and merge to this repo +2. If applicable, we port the fix to the private repo +3. Future syncs won't overwrite your contribution +## Code of Conduct -## ๐Ÿงช Testing -Manual testing is primary - use `npm run build && npm run type-check && npm run lint` to verify changes. +Be respectful. No harassment, trolling, or personal attacks. Focus on constructive feedback. -## ๐Ÿ“š Documentation +## License -### What to Document -- New features and their usage -- API endpoint changes -- Database schema modifications -- Breaking changes +By contributing, you agree your work is licensed under [MIT](LICENSE). -### Documentation Style -- Use clear, concise language -- Include code examples -- Add screenshots for UI changes -- Keep README.md updated +## Questions? -## ๐Ÿšจ Issue Reporting - -### Bug Reports -Include: -- Steps to reproduce -- Expected vs actual behavior -- Environment details (OS, Node version, etc.) -- Screenshots if applicable -- Error messages/logs - -### Feature Requests -Include: -- Clear problem description -- Proposed solution -- Use cases -- Alternatives considered - -## ๐Ÿ” Pull Request Process - -### Before Submitting -- [ ] Tests pass locally -- [ ] Code follows our style guide -- [ ] Documentation updated if needed -- [ ] Branch is up to date with main - -### PR Template -We'll provide a template, but include: -- **Description**: What does this PR do? -- **Type**: Bug fix, feature, docs, etc. -- **Testing**: How was this tested? -- **Screenshots**: For UI changes - -### Review Process -1. Automated checks must pass -2. At least one maintainer review required -3. Address feedback promptly -4. Squash commits before merge - -## ๐Ÿท๏ธ Labels and Tagging - -We use these labels: -- `bug` - Something isn't working -- `enhancement` - New feature or request -- `documentation` - Improvements to docs -- `good first issue` - Good for newcomers -- `help wanted` - Extra attention needed -- `priority: high/medium/low` - Priority levels - -## ๐Ÿ’ฌ Communication - -### Channels -- **Issues**: Bug reports and feature requests -- **Discussions**: General questions and ideas -- **Pull Requests**: Code review discussions - -### Code of Conduct -- Be respectful and inclusive -- Focus on constructive feedback -- Help others learn and grow -- Follow our [Code of Conduct](CODE_OF_CONDUCT.md) - -## ๐ŸŽ‰ Recognition - -Contributors will be: -- Listed in our README acknowledgments -- Mentioned in release notes -- Invited to join our contributors team - -## ๐Ÿ“ž Getting Help - -Stuck? Need help? -- Check existing issues and discussions -- Create a new discussion for questions -- Tag maintainers in issues if urgent -- Join our community discussions - ---- - -**Happy Contributing!** ๐Ÿš€ - -Your contributions help make RA-H better for everyone. Thank you for being part of our open-source community! +Open a [discussion](../../discussions) or check existing issues. diff --git a/docs/0_overview.md b/docs/0_overview.md index 1dac1ff..fb374a4 100644 --- a/docs/0_overview.md +++ b/docs/0_overview.md @@ -23,6 +23,6 @@ For more information, visit [ra-h.app](https://ra-h.app) ## Current Status -- **Version:** Beta (private distribution) -- **Platform:** Web-based (Next.js server) -- **Roadmap:** Native Mac application with user data migration +- **Version:** 0.1.0 (Open Source) +- **Platform:** Web-based (Next.js server, local-only) +- **License:** MIT diff --git a/docs/6_ui.md b/docs/6_ui.md index 67a16ab..0ce63e1 100644 --- a/docs/6_ui.md +++ b/docs/6_ui.md @@ -76,7 +76,7 @@ RA-H uses a fixed 3-panel desktop layout optimized for knowledge work. 3. **Workflows** - Available workflows (integrate) 4. **Logs** - Activity feed (last 100 entries) 5. **Analytics** - Token usage and cost breakdown -6. **API Keys** - Configure Anthropic/OpenAI/Tavily keys (beta ships with embedded keys) +6. **API Keys** - Configure your Anthropic/OpenAI/Tavily keys (required for operation) **Logs view:** - Table/action filtering diff --git a/docs/9_open-source.md b/docs/9_open-source.md index 9557206..cdad25e 100644 --- a/docs/9_open-source.md +++ b/docs/9_open-source.md @@ -1,9 +1,30 @@ -# RA-H BYO-Key Plan (Future Work) +# RA-H Open Source -The production repo remains private and powers the packaged Mac app. A separate, minimal open-source project will be created later for users who want to run RA-H with their own API keys. That future repo will include: +This is the open source, BYO-key (bring your own API keys) version of RA-H. -1. Basic three-panel UI -2. Local SQLite storage -3. Simple Settings โ†’ API Keys experience (no Supabase/subscription backend) +## What's Included -No active work is happening in this repo toward that goal right now. Track progress in `docs/development/prd-private-repo-reset.md`. +- Full three-panel UI (Nodes | Focus | Helpers) +- Local SQLite storage with vector search +- Complete agent system (ra-h, mini-rah, wise-rah) +- All tools and workflows +- Settings panel with API key management + +## What's Not Included + +- Mac app packaging (Tauri) +- Supabase authentication +- Subscription/payment system +- Auto-updates + +## Relationship to Private Repo + +This repo is a **mirror** of the private `ra-h` repository. Features are developed privately and synced here periodically. + +- **Contributions welcome** - See [CONTRIBUTING.md](../CONTRIBUTING.md) +- **Bug reports** - Open an issue on GitHub +- **Feature requests** - Open an issue; major features are typically built in the private repo first + +## Setup + +See the main [README.md](../README.md) for installation instructions. diff --git a/docs/os_docs/2025-12-09-open-source-porting-notes.md b/docs/os_docs/2025-12-09-open-source-porting-notes.md index 67716e5..109ca6c 100644 --- a/docs/os_docs/2025-12-09-open-source-porting-notes.md +++ b/docs/os_docs/2025-12-09-open-source-porting-notes.md @@ -1,5 +1,167 @@ # RA-H Open Source Porting Notes (2025-12-09) +--- + +## Pre-Public Release Audit & Recommendations (2025-12-15) + +This section documents the security audit findings and open-source best practice recommendations compiled before making the repository public. + +### Audit Summary + +| Category | Status | +|----------|--------| +| Credentials/API Keys | โœ… Clean - none found | +| Private repo references | โš ๏ธ 1 issue to fix | +| Supabase remnants | โœ… Clean - properly removed | +| Sensitive business data | โœ… Clean | +| Documentation completeness | โš ๏ธ Gaps to address | + +--- + +### ๐Ÿšจ BLOCKING ISSUES (Must Fix Before Public) + +#### 1. Stale Reference in `docs/9_open-source.md` +**Line 9** references a non-existent internal doc: +``` +Track progress in `docs/development/prd-private-repo-reset.md`. +``` +**Fix:** Remove this line or replace with a public tracking mechanism (GitHub Issues). + +#### 2. Stale Version in `docs/0_overview.md` +**Line 26** states: `**Version:** Beta (private distribution)` +**Fix:** Update to `**Version:** 0.1.0 (Open Source)` + +#### 3. Outdated Key Reference in `docs/6_ui.md` +**Line 79** mentions: `beta ships with embedded keys` +**Fix:** Clarify this refers to the original private beta, not the BYO-key open source version. + +--- + +### ๐Ÿ“‹ MISSING FILES (Industry Standard for Open Source) + +Based on [GitHub's Open Source Guides](https://opensource.guide/starting-a-project/) and [10up Best Practices](https://10up.github.io/Open-Source-Best-Practices/community/), these files are expected: + +| File | Purpose | Priority | +|------|---------|----------| +| `CONTRIBUTING.md` | How to contribute, PR process, code style | **High** | +| `CODE_OF_CONDUCT.md` | Community behavior standards ([Contributor Covenant](https://www.contributor-covenant.org/)) | **High** | +| `SECURITY.md` | How to report vulnerabilities privately | **High** | +| `.github/ISSUE_TEMPLATE/` | Bug report & feature request templates | Medium | +| `.github/PULL_REQUEST_TEMPLATE.md` | PR checklist and format | Medium | +| `CHANGELOG.md` | Version history and changes | Medium | +| `docs/TROUBLESHOOTING.md` | Common issues and solutions | Low | + +--- + +### ๐Ÿ” SECURITY CHECKLIST + +Per [binbash pre-launch checklist](https://medium.com/binbash-inc/open-source-github-repository-pre-launch-checklist-4a52dbbe4af1) and [OpenSSF guidelines](https://github.com/ossf/wg-best-practices-os-developers): + +- [ ] **Run secret scanner** - Use [Gitleaks](https://github.com/gitleaks/gitleaks), [TruffleHog](https://github.com/trufflesecurity/trufflehog), or GitHub's built-in secret scanning +- [ ] **Check git history** - Ensure no credentials in commit history (fresh repo helps) +- [ ] **Enable branch protection** - Require PR reviews for `main` branch +- [ ] **Add SECURITY.md** - Define vulnerability reporting process (e.g., security@yourdomain.com or GitHub Security Advisories) +- [ ] **Review dependencies** - Run `npm audit` and document known vulnerabilities +- [ ] **Add .gitignore review** - Ensure `.env*`, credentials, and local configs are excluded + +--- + +### ๐Ÿ“š DOCUMENTATION GAPS + +Current docs are technically solid but missing contributor-facing content: + +| Gap | Recommendation | +|-----|----------------| +| No contribution guide | Create `CONTRIBUTING.md` with: setup instructions, code style, PR process, testing requirements | +| No API reference | Consider auto-generating from code or adding `docs/api.md` | +| No troubleshooting | Add common issues (SQLite rebuild, key validation errors) | +| No architecture decision records | Optional but helpful for major decisions | +| Numbered doc files unclear | Add `docs/README.md` explaining what each numbered file covers | + +--- + +### ๐Ÿ—๏ธ RECOMMENDED FILE STRUCTURE + +``` +ra-h_os/ +โ”œโ”€โ”€ README.md โœ… exists +โ”œโ”€โ”€ LICENSE โœ… exists (MIT) +โ”œโ”€โ”€ CONTRIBUTING.md โŒ create +โ”œโ”€โ”€ CODE_OF_CONDUCT.md โŒ create +โ”œโ”€โ”€ SECURITY.md โŒ create +โ”œโ”€โ”€ CHANGELOG.md โŒ create +โ”œโ”€โ”€ .github/ +โ”‚ โ”œโ”€โ”€ ISSUE_TEMPLATE/ +โ”‚ โ”‚ โ”œโ”€โ”€ bug_report.md +โ”‚ โ”‚ โ””โ”€โ”€ feature_request.md +โ”‚ โ””โ”€โ”€ PULL_REQUEST_TEMPLATE.md +โ”œโ”€โ”€ docs/ +โ”‚ โ”œโ”€โ”€ README.md โŒ create (index of docs) +โ”‚ โ””โ”€โ”€ ...existing docs... +โ””โ”€โ”€ ... +``` + +--- + +### ๐Ÿ”„ PRIVATE-TO-PUBLIC SYNC BEST PRACTICES + +Based on [Microsoft ISE's approach](https://devblogs.microsoft.com/ise/synchronizing-multiple-remote-git-repositories/) and [GitLab mirroring docs](https://docs.gitlab.com/user/project/repository/mirror/): + +**Current approach (manual sync) is correct for security.** Recommendations: + +1. **Document the sync process publicly** - The current reference to private repo workflow docs won't help public contributors understand when features land +2. **Consider a ROADMAP.md** - Let the community know what's coming from the private repo +3. **Tag releases** - Use semantic versioning (v0.1.0, v0.2.0) so users know when syncs happen +4. **Divergence handling** - Document what happens if someone contributes to OS version (does it get merged upstream? Is OS version append-only from private?) + +--- + +### ๐Ÿ‘ฅ GOVERNANCE MODEL + +For a project of this size with a private upstream, a **BDFL (Benevolent Dictator for Life)** model is appropriate per [Red Hat's governance guide](https://www.redhat.com/en/blog/understanding-open-source-governance-models): + +- You maintain final decision authority +- Contributions are welcome but reviewed against private repo direction +- Clear in CONTRIBUTING.md that this is a mirror, not a community-driven fork + +--- + +### ๐ŸŽฏ PRIORITY ACTION ITEMS + +**Before going public (blocking):** +1. Fix the 3 stale references listed above +2. Run a secret scanner on the repo +3. Create `SECURITY.md` with vulnerability reporting instructions +4. Create basic `CONTRIBUTING.md` +5. Add `CODE_OF_CONDUCT.md` (use Contributor Covenant template) + +**First week after public:** +6. Enable GitHub branch protection on `main` +7. Add issue templates +8. Create `CHANGELOG.md` starting from v0.1.0 +9. Add `docs/README.md` explaining the docs structure + +**Ongoing:** +10. Document sync cadence with private repo +11. Consider adding CI (linting, type-check) via GitHub Actions +12. Monitor for community contributions and establish response SLA + +--- + +### ๐Ÿ“– REFERENCE SOURCES + +- [Starting an Open Source Project - GitHub Guides](https://opensource.guide/starting-a-project/) +- [Open Source Pre-Launch Checklist - binbash](https://medium.com/binbash-inc/open-source-github-repository-pre-launch-checklist-4a52dbbe4af1) +- [README Best Practices - jehna](https://github.com/jehna/readme-best-practices) +- [Building Welcoming Communities - GitHub Guides](https://opensource.guide/building-community/) +- [Leadership and Governance - GitHub Guides](https://opensource.guide/leadership-and-governance/) +- [Understanding Open Source Governance - Red Hat](https://www.redhat.com/en/blog/understanding-open-source-governance-models) +- [Synchronizing Multiple Git Repositories - Microsoft ISE](https://devblogs.microsoft.com/ise/synchronizing-multiple-remote-git-repositories/) +- [OSS Security Checklist - Onboardbase](https://onboardbase.com/blog/oss-security/) +- [CFPB Open Source Template](https://github.com/cfpb/open-source-project-template) + +--- + ## Agent Handover **What is this repo?** This is `ra-h_os`, the open source mirror of the private `ra-h` application. It's a BYO-key (bring your own API keys) version without Mac packaging, Supabase auth, or subscription features.