bldrx — Project scaffolding & template injector

bldrx is a small, CLI-first tool to scaffold new projects and inject reusable templates (CI, GitHub meta files, README/license, lint configs) into repos.

This README contains quick installation and usage instructions. For design details and the full project outline see PROJECT_OUTLINE.md or docs/TEMPLATES.md.

Table of Contents

• Quickstart
• Getting Started
• Examples
• Configuration
• Contributing & Support
• Templates

---

Quickstart

Get up and running quickly:

Install from PyPI (recommended for most users):

pip install -U bldrx
# verify installation
bldrx --version
# optional: install globally in an isolated environment using pipx
# (requires pipx to be installed)
pipx install bldrx

Developer / editable install (recommended for development):

python -m venv .venv
# activate (macOS/Linux)
source .venv/bin/activate
# activate (Windows PowerShell)
# .\.venv\Scripts\Activate.ps1

pip install -U pip
pip install -e .

Run the test suite:

python -m pytest -q

Need help? Use:

bldrx --help
bldrx <command> --help

Examples

1. Scaffold a new project (basic):

# scaffold a new python-cli project with author metadata (dry-run first)
bldrx new mytool --type python-cli --author "Your Name" --email you@example.com --dry-run

2. Scaffold and include specific templates (only some files):

# apply the 'python-cli' template but only include README.md and LICENSE
bldrx new mytool --type python-cli --templates python-cli --only README.md,LICENSE

# exclude a file from the template
bldrx new mytool --type python-cli --templates python-cli --except docs/EXAMPLE.md

2.a) Include a license using the convenience --license flag:

# include the MIT license when scaffolding a new project (dry-run first)
bldrx new mytool --type python-cli --license MIT --meta author_name="VoxDroid" --meta year=2026 --dry-run

# add a license to an existing project
bldrx add-templates ./existing-repo --license Apache-2.0 --meta author_name="VoxDroid" --meta year=2026 --dry-run

3. Inject templates into an existing project (preview, dry-run and diff):

# preview what would change when adding 'contributing' and 'ci' templates
bldrx add-templates ./existing-repo --templates contributing,ci --dry-run --json

# show rendered diffs against the current project (respect filters)
bldrx preview-template contributing --render --diff --meta project_name=demo --only CONTRIBUTING.md

4. Inspect and render template files:

# list files in template
bldrx preview-template python-cli

# render a single file with metadata
bldrx preview-template python-cli --file README.md.j2 --render --meta project_name=demo

# list available license templates
bldrx preview-template licenses

# render a specific license (MIT)
bldrx preview-template licenses/MIT --file LICENSE.j2 --render --meta author_name="VoxDroid" --meta year=2026

5. Manage user templates:

# install a local template into your user templates dir
bldrx install-template /path/to/local-template --name cool --wrap

# uninstall it
bldrx uninstall-template cool --yes

6. Manifests & verification (provenance):

# create a manifest for a template and sign it (requires BLDRX_MANIFEST_KEY)
bldrx manifest create cool --sign

# when applying, ensure verification (fail if mismatches/signature invalid)
bldrx add-templates ./repo --templates cool --verify

7. Publish & discover via local catalog:

# publish a template entry into your local catalog (json metadata)
bldrx catalog publish ./my-template --name cool --version 1.0.0 --description "Cool template" --tags "ci,github"

# search and inspect
bldrx catalog search ci
bldrx catalog info cool

For full usage and prototyping notes, see PROJECT_OUTLINE.md, BUILD_INSTRUCTIONS.md, and docs/ADVANCED_SCENARIOS.md.

Configuration

Environment variables and overrides:

• BLDRX_TEMPLATES_DIR — override the default user templates directory for the current session or environment.
• --templates-dir <path> — use a custom templates root for a single CLI invocation.

Config file (planned): support a .bldrx TOML/YAML file to store default metadata and templates selections per project.

Contributing & Support

• Contributions are welcome: open issues or PRs. See CONTRIBUTING.md template for guidance.
• Before opening a PR, run pre-commit and the test suite locally to catch issues early.
• For support, open an issue on the repository or contact the project maintainer listed in pyproject.toml.

Developer tooling (quick start):

• We use pre-commit to enforce code style and linting (Black, isort, ruff). To install and enable hooks locally:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Please run pre-commit before opening a PR to keep the codebase consistent.

Project metadata

• Owner: VoxDroid
• GitHub: https://github.com/VoxDroid
• Repository: https://github.com/VoxDroid/bldrx
• PyPI: https://pypi.org/project/bldrx
• Contact: izeno.contact@gmail.com

---

Highlights

Key implemented features include Jinja2 template rendering with strict undefined checks, preview/diff support, manifest generation and verification, transactional/atomic applies with backups, template filters (--only/--except), and an extensible plugin system. See PROJECT_OUTLINE.md for the full feature list and roadmap.

---

CLI reference — commands & options

Below is a comprehensive table with each command, key options, a short description, and a basic example. Use bldrx <command> --help for full option lists and platform-specific notes.

Tip: pass repeated --meta key=val flags to provide multiple metadata values (e.g., --meta project_name=MyProj --meta funding_url=https://...).

---

B. Templates (Expanded)

Core idea: Each template is self-contained and customizable. Placeholders can be automatically replaced, and users can provide custom names, emails, project name, year, and other metadata.

Categories of templates:

1. Project structure templates

• src/, tests/, README.md, LICENSE
• Placeholders: {{project_name}}, {{author_name}}, {{email}}, {{year}}

2. GitHub meta templates

• .github/CODEOWNERS
• .github/CONTRIBUTING.md
• .github/CODE_OF_CONDUCT.md
• .github/SUPPORT.md
• .github/funding.yml
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• Users can provide custom names, emails, GitHub usernames, funding links, and project names

3. CI/CD workflows

• .github/workflows/ci.yml
• .github/workflows/deploy.yml

4. Lint/Formatter configs

• .eslintrc.js, .prettierrc, pyproject.toml

---

C. Customization & Placeholders

All templates allow placeholders to be replaced automatically:

{{project_name}} → user-defined or CLI argument
{{author_name}} → user-defined
{{email}} → user-defined
{{year}} → auto-detect current year
{{github_username}} → user-defined (via `--github-username` or `--meta github_username=...`) 

• Optional CLI flags or JSON/YAML config to provide default values (config file support planned).

User templates & overrides:

• Install reusable templates for the current user with bldrx install-template <path> [--name NAME] [--force].
• Remove user templates with bldrx uninstall-template <name> [--yes].
• Override or add a templates root for a single command using --templates-dir <path> or configure BLDRX_TEMPLATES_DIR env var to point to your user templates directory.

New: list & preview enhancements

• bldrx list-templates --details shows the subfiles contained in each template (including .github subfolders).
• bldrx preview-template <template> --file <path> shows raw template content; add --render and --meta key=val to render it with provided metadata.

Security & integrity

• Templates may include a bldrx-manifest.json describing per-file SHA256 checksums in a files mapping and an optional HMAC signature in the hmac field.
• Use the --verify flag when applying templates (bldrx new ... --verify or bldrx add-templates ... --verify) to require manifest verification before files are applied.
• For HMAC-protected manifests, set BLDRX_MANIFEST_KEY (shared secret) in the environment to validate signatures. Asymmetric signatures (public-key) are planned for a future release.
• You can generate manifests (and optional HMAC signatures) locally using the new CLI helper:

# create and write a manifest for a user template named `cool` (writes to template root)
bldrx manifest create cool --sign

# generate a manifest and write it to a specific file
bldrx manifest create cool --output /tmp/cool-manifest.json

Catalog (local)

• Publish a template metadata entry into your local catalog/registry:

# publish a local template directory as `cool` version 1.0.0
bldrx catalog publish ./my-template --name cool --version 1.0.0 --description "Cool template" --tags "ci,github"

# search the local catalog
bldrx catalog search ci

# show info for a specific template
bldrx catalog info cool

# remove an entry
bldrx catalog remove cool --yes

Telemetry (opt-in)

• Telemetry is strictly opt-in. You can enable it via environment or CLI:

# enable in current session
export BLDRX_ENABLE_TELEMETRY=1
# or CLI
bldrx telemetry enable

# check status
bldrx telemetry status

• By default telemetry writes newline-delimited JSON events to ~/.bldrx/telemetry.log. You can override the endpoint for external collection with BLDRX_TELEMETRY_ENDPOINT (not enabled by default). All telemetry is best-effort and non-blocking; failures are ignored and events are local first.

Remote fetching (local archives, HTTP, Git)

• Engine.fetch_remote_template(url, name, force=True) supports local file:// archives (.tar.gz, .tgz, .zip) and directories, HTTP(S) downloads, and git+ or Git remote URLs (shallow git clone).
• Archives are extracted into a secure sandbox and checked for path traversal before installation. HTTP downloads are saved to a temporary file and then extracted; Git remotes are cloned and the repo root is used as the template source. Verification with --verify is applied after extraction/cloning when requested.
• CLI helpers for bldrx fetch and advanced remote registry are planned (for now use bldrx manifest create and Engine.fetch_remote_template).

Example (bash/macOS/Linux):

# install a template directory into the user templates dir
bldrx install-template ~/my-templates/cool-template --name cool

# list templates including user templates marker
bldrx list-templates
# or point a single command at a custom templates root
bldrx list-templates --templates-dir ~/other-templates

# Use BLDRX_TEMPLATES_DIR to override the default user templates dir
export BLDRX_TEMPLATES_DIR="$HOME/.config/my-bldrx/templates"
bldrx list-templates

Example (Windows PowerShell):

# set env var for current session
$env:BLDRX_TEMPLATES_DIR = "$env:APPDATA\bldrx\templates"
# install using interactive prompt or explicit name
bldrx install-template C:\path\to\template --name cool

---

D. CLI Options (Example)

# Scaffold new project with selected templates (dry-run)
bldrx new python-cli my_tool --templates security,ci --dry-run

# Inject templates into existing repo (dry-run)
bldrx add-templates ./existing-project --templates contributing,support --dry-run

# List all available templates (human-readable)
bldrx list-templates

# List templates as a JSON array
bldrx list-templates --json

# Remove templates from a project (requires --yes to confirm or --force)
bldrx remove-template ./existing-project contributing --yes

# Provide metadata overrides
bldrx new my_tool --author "Andrei" --email "andrei@example.com"

---

E. Template Injection & Safe Merging

• Templates can be applied to existing projects

• Engine automatically:

  • Merges files safely
  • Replaces placeholders
  • Adds missing folders
  • Avoids overwriting existing files unless --force is used

---

Workflow

A. New Project Flow

1. User runs bldrx new <project_name>

2. CLI prompts for:

   • Project type (Python CLI, Python library, Node API, React app)
   • Optional templates (security.md, PR template, CI/CD, CONTRIBUTING.md, LICENSE, funding.yml, etc.)
   • Optional metadata: author name, email, GitHub username

3. Engine copies folder structure + applies templates + replaces placeholders

4. Output: fully scaffolded project ready to go

---

B. Existing Project Flow

1. User runs bldrx add-templates ./existing-project
2. CLI lists available templates
3. User selects templates + metadata
4. Engine safely merges templates into project, replacing placeholders

---

Tech Stack

---

CI / Continuous Integration

A GitHub Actions workflow is included at .github/workflows/ci.yml which runs the test suite on push and pull requests (matrix: Python 3.9, 3.10, 3.11).

This repository includes a publish.yml workflow (in .github/workflows) that will publish to PyPI when the latest commit subject equals v<version> from pyproject.toml (e.g., commit subject v0.1.1 when package version is 0.1.1).

• Set PYPI_API_TOKEN (PyPI API token) in GitHub Secrets to enable uploads.
• Optionally set RELEASE_GITHUB_TOKEN (a personal access token) to have the GitHub Release authored by your user rather than the Actions bot.

Prefer testing against TestPyPI before publishing to the real PyPI; the workflow can be adapted to publish to TestPyPI first.

Folder / File Structure

bldrx/
├── bldrx/
│   ├── cli.py
│   ├── engine.py
│   ├── renderer.py
│   ├── templates/
│   │   ├── python-cli/ (implemented)
│   │   │   ├── src/main.py.j2
│   │   │   ├── README.md.j2
│   │   │   └── LICENSE.j2
│   │   ├── github/
│   │   │   ├── CODEOWNERS.j2
│   │   │   ├── CONTRIBUTING.md.j2
│   │   │   ├── CODE_OF_CONDUCT.md.j2
│   │   │   ├── SUPPORT.md.j2
│   │   │   ├── .github/
│   │   │   │   ├── funding.yml.j2
│   │   │   │   └── ISSUE_TEMPLATE/
│   │   │   │       ├── bug_report.md.j2
│   │   │   │       └── feature_request.md.j2
│   │   ├── node-api/
│   │   │   ├── package.json.j2
│   │   │   ├── src/index.js.j2
│   │   │   └── README.md.j2
│   │   ├── react-app/
│   │   │   ├── package.json.j2
│   │   │   ├── src/App.js.j2
│   │   │   └── README.md.j2
│   │   ├── ci/
│   │   │   ├── ci.yml.j2
│   │   │   └── deploy.yml.j2
│   │   ├── docker/
│   │   │   ├── Dockerfile.j2
│   │   │   └── .dockerignore.j2
│   │   └── lint/
│   │       ├── .eslintrc.js.j2
│   │       ├── .prettierrc.j2
│   │       └── pyproject.toml.j2
│   └── gui.py  # Optional GUI
├── tests/
├── README.md
└── setup.py

---

Optional / Future Features

• Add plugin system: users can drop in custom templates (planned)
• Dry-run mode: preview changes before applying (implemented)
• Auto-fetch templates from GitHub repo (planned)
• Multi-language support (Python, Node, React) (partial support via --type, templates needed)
• Interactive metadata prompts for faster scaffolding (partial — prompts for project type implemented)

---