navi-bootstrap

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

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:

nboot new applies scaffold + base. All other packs are elective and can be layered on afterward with nboot apply.

CLI reference

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

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 — architecture, pack reference, spec schema, CLI reference, custom pack authoring.

License

MIT -- Copyright (c) 2026 Project Navi