Templates - HoxCore Documentation

Overview

Templates in HoxCore are purely declarative and secure—no executable code, only YAML definitions. They provide a safe, predictable way to scaffold new projects with consistent structure and configuration.

✅ Safe by Design

HoxCore templates are interpreted by HoxCore itself, not executed as scripts. This ensures:

No arbitrary code execution
Predictable behavior
Easy to audit and understand
Safe to share and distribute

What Templates Can Do

📁

Directory Structure

Create folder hierarchies automatically

📄

File Generation

Generate files from templates with variable substitution

📋

File Copying

Copy static files from template directory

🔄

Git Initialization

Initialize Git repository with .gitignore

Template Philosophy

HoxCore's approach to templates is fundamentally different from traditional scaffolding tools:

Declarative vs. Imperative

Aspect	Traditional Tools	HoxCore
Execution	Run scripts (bash, Python, etc.)	Interpret YAML definitions
Security	Can execute arbitrary code	No code execution
Predictability	Depends on script logic	Always predictable
Auditability	Must read and understand code	Simple YAML inspection
Sharing	Security risk	Safe to share

Core Principles

🔒 Security First

No executable code means no security vulnerabilities from malicious templates.

📋 Declarative Only

Describe what you want, not how to do it. HoxCore handles the implementation.

🎯 Single Responsibility

Templates scaffold structure. Logic belongs in your project code, not templates.

🔍 Transparent

What you see in the YAML is exactly what you get. No hidden behavior.

⚠️ What Templates Cannot Do

By design, templates cannot:

Execute shell commands
Run scripts or programs
Make network requests
Access system resources beyond file creation
Perform complex logic or conditionals

This is a feature, not a limitation. It ensures templates remain safe and predictable.

Template Structure

A template consists of a YAML definition file and optional template files:

Template Directory Layout

templates/
└── my-template/
    ├── template.yml           # Template definition
    ├── files/                 # Template files
    │   ├── README.md.template
    │   ├── main.py.template
    │   └── config.yml.template
    └── static/                # Static files (copied as-is)
        ├── .gitignore
        └── LICENSE

Template Definition (template.yml)

# Template metadata
name: my-template
version: 1.0.0
description: "Description of what this template creates"
author: "Your Name"
category: software.dev/cli-tool

# Scaffolding instructions
scaffolding:
  # Directories to create
  directories:
    - src/
    - tests/
    - docs/
    - config/
  
  # Files to generate from templates
  files:
    - path: README.md
      source: files/README.md.template
      description: "Project README"
    
    - path: src/main.py
      source: files/main.py.template
      description: "Main entry point"
    
    - path: pyproject.toml
      content: |
        [project]
        name = "{{id}}"
        version = "0.1.0"
        description = "{{description}}"
  
  # Static files to copy
  static_files:
    - source: static/.gitignore
      destination: .gitignore
    
    - source: static/LICENSE
      destination: LICENSE

# Git configuration
git:
  initialize: true
  initial_commit: true
  commit_message: "Initial commit from template: {{template_name}}"
  gitignore:
    - __pycache__/
    - "*.pyc"
    - .venv/
    - dist/
    - build/

# Template variables (with defaults)
variables:
  python_version: "3.8"
  license: "MIT"
  author_email: "user@example.com"

# Requirements or dependencies
requirements:
  - git
  - python >= 3.8

# Post-creation instructions
instructions: |
  Your project has been created successfully!
  
  Next steps:
  1. cd into the project directory
  2. Create a virtual environment: python -m venv .venv
  3. Activate it: source .venv/bin/activate
  4. Install dependencies: pip install -e .
  
  Happy coding!

Template File Structure

Component	Required	Description
`template.yml`	Yes	Main template definition
`files/`	No	Template files with variable substitution
`static/`	No	Static files copied as-is
`README.md`	No	Template documentation

Scaffolding Definition

The scaffolding section defines what files and directories to create:

Directory Creation

scaffolding:
  directories:
    # Simple list
    - src/
    - tests/
    - docs/
    
    # Nested directories
    - src/core/
    - src/utils/
    - tests/unit/
    - tests/integration/
    
    # Deep nesting
    - config/environments/dev/
    - config/environments/prod/

File Generation

Generate files from templates with variable substitution:

scaffolding:
  files:
    # From template file
    - path: README.md
      source: files/README.md.template
      description: "Project README"
    
    # Inline content
    - path: .env.example
      content: |
        # Environment variables
        PROJECT_NAME={{title}}
        VERSION=0.1.0
        DEBUG=true
      description: "Environment template"
    
    # Conditional description
    - path: src/main.py
      source: files/main.py.template
      description: "Main application entry point"
      executable: false

Static File Copying

Copy files without variable substitution:

scaffolding:
  static_files:
    # Simple copy
    - source: static/.gitignore
      destination: .gitignore
    
    # Copy to different location
    - source: static/LICENSE
      destination: LICENSE
    
    # Copy with rename
    - source: static/config.example.yml
      destination: config/default.yml
    
    # Copy entire directory
    - source: static/assets/
      destination: public/assets/

File Operations Order

HoxCore processes scaffolding in this order:

Create directories - All directories are created first
Copy static files - Static files are copied as-is
Generate template files - Template files are processed with variable substitution
Initialize Git - If configured, Git repository is initialized

Template Variables

Variables enable dynamic content in template files using {{variable}} syntax:

Built-in Variables

These variables are automatically available in all templates:

Variable	Description	Example
`{{title}}`	Entity title	My Project
`{{description}}`	Entity description	A sample project
`{{uid}}`	Entity UID	proj_abc123def456
`{{id}}`	Entity ID (if set)	P-001
`{{category}}`	Entity category	software.dev/cli-tool
`{{type}}`	Entity type	project
`{{template_name}}`	Template name	cli-tool-python
`{{date}}`	Current date	2024-01-01
`{{year}}`	Current year	2024

Custom Variables

Define custom variables with defaults in your template:

variables:
  python_version: "3.8"
  license: "MIT"
  author_name: "Your Name"
  author_email: "user@example.com"
  github_username: "username"

Using Variables in Templates

Example template file (README.md.template):

# {{title}}

{{description}}

## Installation