https://github.com/project-navi/navi-bootstrap
A repo that bootstraps repos. Spec-driven Jinja2 engine + 7 template packs for production-grade CI, security, and release pipelines.
https://github.com/project-navi/navi-bootstrap
bootstrapping ci-cd code-review devops jinja2 python security template-engine
Last synced: 4 months ago
JSON representation
A repo that bootstraps repos. Spec-driven Jinja2 engine + 7 template packs for production-grade CI, security, and release pipelines.
- Host: GitHub
- URL: https://github.com/project-navi/navi-bootstrap
- Owner: Project-Navi
- License: mit
- Created: 2026-02-26T01:50:44.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-28T02:43:46.000Z (4 months ago)
- Last Synced: 2026-02-28T07:26:57.426Z (4 months ago)
- Topics: bootstrapping, ci-cd, code-review, devops, jinja2, python, security, template-engine
- Language: Python
- Size: 572 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# navi-bootstrap
[](https://github.com/Project-Navi/navi-bootstrap/actions/workflows/tests.yml)
[](https://github.com/Project-Navi/navi-bootstrap/actions/workflows/codeql.yml)
[](https://github.com/Project-Navi/navi-bootstrap/actions/workflows/fuzz.yml)
[](https://codecov.io/gh/Project-Navi/navi-bootstrap)
[](https://scorecard.dev/viewer/?uri=github.com/Project-Navi/navi-bootstrap)
[](https://pypi.org/project/navi-bootstrap/)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/ruff)
navi-bootstrap generates operational infrastructure for Python projects — CI, security scanning, code review, release pipelines, quality gates, and the project skeleton itself — from declarative template packs.
---
## Quick start
```bash
pip install navi-bootstrap
nboot new my-project
```
One command, complete project:
```
my-project/
├── pyproject.toml
├── src/my_project/__init__.py
├── src/my_project/py.typed
├── tests/conftest.py
├── tests/test_my_project.py
├── README.md
├── LICENSE
├── .gitignore
├── .github/workflows/tests.yml
├── .github/dependabot.yml
├── .pre-commit-config.yaml
├── AGENTS.md
├── DEBT.md
└── nboot-spec.json
```
## How it works
```
spec (what your project is) + pack (what to generate) → rendered output
```
The **spec** describes your project: name, owner, Python version, license. The **pack** is a set of Jinja2 templates with a manifest declaring conditions and loops. The **engine** connects them deterministically — same spec + same pack = same output, every time.
## Packs
Eight template packs, layered with explicit dependencies:
| Pack | What it generates |
|------|-------------------|
| **scaffold** | Project skeleton — pyproject.toml, src layout, tests, README, LICENSE, .gitignore |
| **base** | CI workflows, pre-commit config, dependabot, tool config, AGENTS.md, DEBT.md |
| **security-scanning** | CodeQL analysis, OpenSSF Scorecard |
| **github-templates** | Bug report, feature request, issue config, PR template |
| **review-system** | Code review and security review workflows |
| **quality-gates** | Quality metrics baseline, test parity map |
| **code-hygiene** | CONTRIBUTING.md |
| **release-pipeline** | SLSA L3 build workflow, release dispatcher, changelog config |
`nboot new` applies `scaffold` + `base`. All other packs are elective and can be layered on afterward with `nboot apply`.
## CLI reference
| Command | Description |
|---------|-------------|
| `nboot new ` | Create a new project with scaffold + base packs |
| `nboot render --spec --pack --out` | Render a single pack to a new directory |
| `nboot apply --spec --pack --target` | Apply a pack to an existing project |
| `nboot diff --spec --pack --target` | Preview changes without writing |
| `nboot init --target` | Generate spec by inspecting an existing project |
| `nboot validate --spec` | Validate spec and manifest |
| `nboot list-packs` | List available packs |
## Architecture
Six-stage pipeline. Stateless and deterministic through stage 3.
```
spec.json + pack/
-> [Stage 0: Resolve] action SHAs via gh api
-> [Stage 1: Validate] spec + manifest against schemas
-> [Stage 2: Plan] evaluate conditions, expand loops, build render list
-> [Stage 3: Render] Jinja2 render to memory
-> [Stage 4: Validate] run post-render checks
-> [Stage 5: Hooks] post-render shell commands
-> output/
```
Stages 0-3 are pure functions — spec and pack in, rendered files out, no side effects. All project-specific opinions live in the spec and the template pack, never in the engine.
```
src/navi_bootstrap/
├── cli.py # Click CLI: new, init, render, apply, diff, validate, list-packs
├── engine.py # Plan + Render (stages 2-3), sandboxed dest paths
├── manifest.py # Manifest loading + validation
├── spec.py # Spec loading + JSON Schema validation
├── resolve.py # Stage 0: action SHA resolution
├── validate.py # Stage 4: post-render validation
├── hooks.py # Stage 5: hook runner
├── sanitize.py # Input sanitization (homoglyphs, traversal, injection)
├── init.py # Project inspection -> spec generation
├── diff.py # Drift detection (render-to-memory + unified diff)
└── packs.py # Pack discovery, resolution, and ordering
```
## Development
```bash
uv sync # Install dependencies
uv run pytest tests/ -v # Run all tests
uv run ruff check src/navi_bootstrap/ tests/ # Lint
uv run ruff format src/navi_bootstrap/ tests/ # Format
uv run mypy src/navi_bootstrap/ # Type check
uv run bandit -r src/navi_bootstrap -ll # Security scan
pre-commit run --all-files # All hooks
```
Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `test:`, `refactor:`.
Full documentation: **[Wiki](https://github.com/Project-Navi/navi-bootstrap/wiki)** — architecture, pack reference, spec schema, CLI reference, custom pack authoring.
## License
[MIT](LICENSE) -- Copyright (c) 2026 Project Navi