feat: rename rails/ to tools/ and add service tool suites (#4)

Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
2026-02-22 17:52:23 +00:00
parent 248db8935c
commit a8e580e1a3
158 changed files with 2481 additions and 213 deletions
--- a/tools/quality/README.md
+++ b/tools/quality/README.md
@@ -0,0 +1,166 @@
+# Quality Rails
+
+Portable quality enforcement for TypeScript, Python, and Node.js projects.
+
+## 🎯 What This Prevents
+
+Based on real-world validation of 50 issues in a production codebase:
+- ❌ Hardcoded passwords
+- ❌ SQL injection vulnerabilities
+- ❌ Type safety violations (`any` types)
+- ❌ Missing test coverage
+- ❌ Build failures
+- ❌ Dependency vulnerabilities
+
+**70% of these issues are prevented mechanically with quality-rails.**
+
+## ⚡ Quick Start (Mosaic)
+
+### New Project
+```bash
+# Apply template from Mosaic
+~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/project
+
+# Install dependencies
+cd /path/to/project
+npm install
+
+# Initialize git hooks
+npx husky install
+
+# Verify enforcement is working
+~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/project
+```
+
+### Existing Project
+```bash
+# Same as above - works for new or existing projects
+~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/existing-project
+```
+
+## 🛡️ What You Get
+
+✅ **TypeScript strict mode** - All type checks enabled
+✅ **ESLint blocking `any` types** - no-explicit-any: error
+✅ **Pre-commit hooks** - Type check + lint + format before commit
+✅ **Secret scanning** - Block hardcoded passwords/API keys
+✅ **CI/CD templates** - Woodpecker, GitHub Actions, GitLab
+✅ **Test coverage enforcement** - 80% threshold
+✅ **Security scanning** - npm audit, OWASP checks
+
+## 📦 Available Templates
+
+| Template | Language | Framework | Status |
+|----------|----------|-----------|--------|
+| `typescript-node` | TypeScript | Node.js | ✅ Ready |
+| `typescript-nextjs` | TypeScript | Next.js | ✅ Ready |
+| `monorepo` | TypeScript | TurboRepo + pnpm | ✅ Ready |
+| `python` | Python | - | 🚧 Coming Soon |
+
+### Monorepo Template
+
+Perfect for projects combining **Next.js frontend** + **NestJS backend** in one repository.
+
+Features:
+- 🎯 **Multi-package aware** - lint-staged only checks changed packages
+- ⚡ **TurboRepo caching** - Faster builds and tests
+- 🔀 **Parallel dev servers** - Run web + API simultaneously
+- 📦 **pnpm workspaces** - Efficient dependency management
+- 🛡️ **Package-specific rules** - Next.js and NestJS get appropriate ESLint configs
+
+Example structure:
+```
+monorepo/
+├── apps/
+│   ├── web/    # Next.js frontend
+│   └── api/    # NestJS backend
+└── packages/
+    ├── shared-types/
+    ├── ui/
+    └── config/
+```
+
+## 🧪 How It Works
+
+### Pre-Commit (Local Enforcement)
+```bash
+# You try to commit code with a type error
+git commit -m "Add feature"
+
+# Quality rails blocks it:
+❌ Type error: Type 'number' is not assignable to type 'string'
+❌ ESLint: Unexpected any. Specify a different type.
+✋ Commit blocked - fix errors and try again
+```
+
+### CI/CD (Remote Enforcement)
+```yaml
+# Woodpecker pipeline runs:
+✓ npm audit (dependency security)
+✓ eslint (code quality)
+✓ tsc --noEmit (type checking)
+✓ jest --coverage (tests + coverage)
+✓ npm run build (compilation)
+
+# If any step fails, merge is blocked
+```
+
+## 🎓 Philosophy
+
+**Process compliance doesn't work.**
+
+Instructing AI agents to "do code review" or "run tests" fails. They claim to follow processes but output quality doesn't match claims.
+
+**Mechanical enforcement works.**
+
+Quality rails don't ask agents to follow processes. They **block commits** that don't pass automated checks.
+
+- Type errors? → **Commit blocked**
+- Hardcoded secrets? → **Commit blocked**
+- Test failures? → **Commit blocked**
+- Missing coverage? → **Commit blocked**
+
+This works for **any agent runtime** (Codex, Claude, OpenCode, Gemini, etc.) because enforcement is mechanical, not instructional.
+
+[Read more: PHILOSOPHY.md](./PHILOSOPHY.md)
+
+## 📖 Documentation
+
+- [TypeScript Setup Guide](./docs/TYPESCRIPT-SETUP.md)
+- [CI/CD Configuration](./docs/CI-SETUP.md)
+
+## 🔧 Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/install.sh` | Install template to project (Linux/Mac) |
+| `scripts/install.ps1` | Install template to project (Windows) |
+| `scripts/verify.sh` | Verify enforcement is working (Linux/Mac) |
+| `scripts/verify.ps1` | Verify enforcement is working (Windows) |
+
+## 🚀 Roadmap
+
+- [x] TypeScript/Node template
+- [x] Pre-commit enforcement (husky + lint-staged)
+- [x] CI/CD templates (Woodpecker, GitHub Actions)
+- [x] Installation scripts
+- [x] Verification testing
+- [x] Next.js template
+- [x] Monorepo template
+- [ ] Python template
+- [ ] Coverage visualization
+- [ ] IDE integration (VSCode extension)
+
+## 🤝 Contributing
+
+Quality Rails is based on lessons learned from real production codebases. Contributions welcome!
+
+## 📝 License
+
+MIT License - See LICENSE file for details
+
+## 🙏 Credits
+
+Built to solve real problems discovered in AI-assisted development workflows.
+
+Based on validation findings from a production patch milestone.