# Devrail 🛤️

**Security & Quality Guardrails** — Adoption-first developer discipline

Stop fighting your team about guidelines. **Devrail blocks mistakes automatically** and lets you adopt security incrementally with baseline + diff-only mode.

```yaml
devrail:
  preset: "node-api"  # Auto-detected!
  level: "standard"
  baseline: ".devrail/baseline.json"  # Accept existing, block new
```

## Quick Start (3 minutes)

```bash
# Install
npm install -g devrail

# Initialize - auto-detects your stack!
npx devrail init

# See what's wrong
npx devrail check

# Fix safe issues automatically
npx devrail fix

# Accept existing issues, block only NEW ones
npx devrail baseline
```

## Why Devrail?

**The problem**: Vibecoding is fun until you ship secrets to GitHub, forget input validation, or deploy with 47 critical vulnerabilities.

**The solution**: Opinionated guardrails that:
- ✅ Block secrets in code (gitleaks)
- ✅ Block vulnerable dependencies (osv-scanner)
- ✅ Block dangerous patterns (semgrep)
- ✅ Enforce tests & coverage
- ✅ Generate CI pipelines automatically

## Presets

| Preset | Description |
|--------|-------------|
| `node-api` | Express, Fastify, Koa backends |
| `nextjs-app` | Next.js full-stack apps |
| `python-api` | FastAPI, Flask, Django (coming soon) |
| `cli-tool` | CLI applications |
| `library` | npm/PyPI packages |
| `monorepo` | Multi-package repositories |

## Levels

| Level | Description |
|-------|-------------|
| `basic` | Low friction, maximum adoption. Only critical issues. |
| `standard` | Recommended default. Balanced security + quality. |
| `strict` | Hard blocking. For mature teams. |

## CLI Commands

```bash
devrail init              # Auto-detect stack, bootstrap config
devrail check             # Fast local check
devrail check --changed   # Only check changed files (PR mode)
devrail ci                # Full CI check (blocking)
devrail fix               # Apply safe automatic fixes
devrail fix --all         # Include fixes that need review
devrail baseline          # Accept existing issues
devrail baseline --update # Update baseline with current state
devrail explain <rule>    # Explain a rule + how to fix
devrail rules             # List all rules
```

## Rules (30 MVP)

### Secrets
- `secrets.no-plaintext` — Detect hardcoded secrets
- `secrets.no-env-commit` — Block .env files in git
- `secrets.gitignore-required` — Ensure proper .gitignore

### Dependencies
- `deps.lockfile.required` — Require lockfile
- `deps.no-unpinned` — Warn about ^, ~, * versions
- `deps.no-git-deps` — Block git:// dependencies
- `deps.no-vulnerable` — Scan for CVEs
- `deps.no-typosquatting` — Detect malicious packages
- `deps.license-check` — Check license compatibility

### Security
- `security.headers.required` — Require security headers
- `security.cors.safe-default` — Block `origin: *`
- `security.no-eval` — Block eval/Function
- `security.no-unsafe-regex` — Detect ReDoS patterns
- `security.no-prototype-pollution` — Block prototype pollution

### Auth
- `auth.no-weak-jwt` — Block weak JWT configs
- `auth.no-hardcoded-credentials` — Block hardcoded creds
- `auth.session-secure` — Require secure cookies

### API
- `api.validation.required` — Require input validation
- `api.rate-limiting` — Require rate limiting
- `api.no-sensitive-logging` — Block PII in logs

### SQL
- `sql.no-string-concat` — Block SQL injection patterns
- `sql.no-raw-queries` — Prefer ORM

### Tests
- `tests.unit.required` — Require test files
- `tests.coverage.min-50` — 50% coverage minimum
- `tests.coverage.min-80` — 80% coverage (strict)
- `tests.no-skipped` — Block .skip()/.only()

### Logging
- `logging.no-pii` — Block PII in logs
- `logging.no-console` — Use proper logger

### Code Quality
- `code.no-any` — Block TypeScript any
- `code.strict-mode` — Require TS strict
- `code.no-unused-vars` — Remove dead code

### Config
- `config.node-version` — Specify Node version
- `config.editor-config` — Require .editorconfig

## Configuration

### Full Config Example

```yaml
devrail:
  preset: "node-api"
  level: "standard"
  
  # Baseline: accept existing, block new
  baseline: ".devrail/baseline.json"

  # Override specific rules
  rules:
    secrets.no-plaintext:
      enabled: true
      severity: error
    deps.no-unpinned:
      enabled: false  # Disable this rule
    tests.coverage.min-80:
      enabled: true
      blocking: false  # Warn but don't fail

  # CI settings
  ci:
    failOn: error  # error | warn | info
    reportFormat: console  # console | json | sarif

  # Tool toggles
  tools:
    eslint: true
    semgrep: true
    gitleaks: true
    osvScanner: true

  # File patterns
  include:
    - "src/**/*"
  exclude:
    - "**/*.test.ts"
    - "dist/**"
```

### Config File Locations

Devrail looks for config in:
- `devrail.config.yaml`
- `devrail.config.yml`
- `devrail.config.json`
- `devrail.config.js`
- `.devrailrc`
- `package.json` (under `devrail` key)

## CI Integration

### GitHub Actions

```yaml
# .github/workflows/devrail.yml
name: Devrail Security
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm install -g devrail
      - run: devrail ci --format sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
```

### GitLab CI

```yaml
devrail:
  image: node:20
  script:
    - npm ci
    - npm install -g devrail
    - devrail ci --fail-on error
```

## Tool Requirements

Devrail wraps existing best-in-class tools:

| Tool | Purpose | Install |
|------|---------|---------|
| [gitleaks](https://github.com/gitleaks/gitleaks) | Secret scanning | `brew install gitleaks` |
| [osv-scanner](https://github.com/google/osv-scanner) | Dependency vulnerabilities | `brew install osv-scanner` |
| [semgrep](https://semgrep.dev) | SAST | `pip install semgrep` |

Devrail gracefully skips tools that aren't installed.

## Philosophy

1. **Opinionated** — We make decisions so you don't have to
2. **Composable** — Mix presets and rules like Tailwind classes
3. **Frictionless** — 10-minute setup, not 10-day integration
4. **Blocking** — Fail fast, fix early
5. **Wrapper-based** — We don't reinvent scanners, we orchestrate them

## Key Innovation: Adoption-First

Unlike other tools that dump 400 errors on day one, Devrail:

1. **Baseline** - Accept existing issues, only block NEW ones
2. **Diff-only** - By default, only scan changed files in PRs
3. **Auto-fix** - Safe fixes applied automatically
4. **Levels** - Start with `basic`, graduate to `strict`

## Roadmap

- [x] Baseline system (accept existing, block new)
- [x] Auto stack detection
- [x] Diff-only mode
- [ ] ESLint integration with security rules
- [ ] Python preset (pytest, bandit, safety)
- [ ] Watch mode (`devrail guard --watch`)
- [ ] VS Code extension
- [ ] Custom rule definitions

## Contributing

```bash
git clone https://github.com/your-org/devrail
cd devrail
npm install
npm run dev
```

## License

MIT