bldrx 0.1.1

CLI-first scaffold & template injector

Bldrx — Project Scaffolding & Template Injector

Bldrx is a CLI-first tool to quickly scaffold new projects and inject reusable templates into existing repositories.

This README contains quick installation and usage instructions. For the project prototyping notes and full outline see PROJECT_OUTLINE.md.

---

Quickstart

Install in a virtual environment:

python -m venv .venv
source .venv/bin/activate  # or .\.venv\Scripts\Activate.ps1 on Windows
pip install --upgrade pip
pip install -r requirements.txt

Run tests:

python -m pytest -q

Build and install locally:

python -m build
pip install dist/*.whl

Examples

List available templates:

bldrx list-templates

Install a user template and list templates:

bldrx install-template ~/my-templates/cool-template --name cool
bldrx list-templates

Preview a template file or its rendered output:

bldrx list-templates --details
bldrx preview-template python-cli --file README.md.j2
bldrx preview-template python-cli --file README.md.j2 --render --meta project_name=demo

For full usage and prototyping notes, see PROJECT_OUTLINE.md, BUILD_INSTRUCTIONS.md, and the advanced guide at 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.
• For support, open an issue on the repository or contact the project maintainer listed in pyproject.toml.

Project metadata

• Owner: VoxDroid
• GitHub: https://github.com/VoxDroid
• Repository: https://github.com/VoxDroid/bldrx
• Contact: [e-mail]

---

A. CLI Commands

Command	Purpose	Details
bldrx new <project_name>	Scaffold a new project	Choose project type (Python CLI / library / Node API / React app) and optional templates
bldrx add-templates <existing_project>	Inject templates into existing project	Add GitHub meta files, CI/CD workflows, README, contributing docs, etc.
bldrx list-templates	Show available templates	JSON or human-readable table
bldrx remove-template <name>	Remove a template from a project	Safety flag to prevent accidental deletes (requires --force or --yes)

---

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 "[e-mail]"

---

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

Layer	Tech / Library	Reason
CLI	Python	Cross-platform, easy file handling
CLI Lib	click or argparse	Clean command definitions and options
Template Engine	jinja2	Placeholder replacement in templates
File Handling	pathlib, shutil	File copy, merge, create directories
Optional	watchdog	Detect changes for real-time template updates
Optional GUI	PySide6 or Tkinter	Interactive template selection

---

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).

Planned: Add a workflow that builds distribution artifacts on tags (sdist/wheel) and stores them as GitHub Actions artifacts — optionally publish to PyPI on release tags.

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)

---

Resume Bullet Points

1. Primary bullet:

Developed Bldrx, a CLI tool for scaffolding new projects and injecting customizable templates into existing repositories, supporting GitHub meta files (CODEOWNERS, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, funding.yml, issue templates), CI/CD workflows, and project structure setup.

2. Customization bullet:

Templates are fully configurable with placeholders for project name, author, email, GitHub username, and year, allowing automated metadata injection across multiple projects.

3. Impact bullet:

Standardized project setup and reduced manual boilerplate tasks by ~80%, enabling fast, consistent project initialization for personal and client repositories.

---