crinit

Next-generation pluggable project scaffolding engine for Crystal. Engineered for arbitrary tree mirroring, macro-safe token replacement, and zero-dependency upstream compiler integration.

Project Metadata:

• Description: Next-generation pluggable project scaffolding engine for Crystal. Engineered for arbitrary tree mirroring, macro-safe token replacement, and zero-dependency upstream compiler integration.
• Topics/Tags: crystal, crystal-lang, scaffolding, generator, template-engine, compiler, cli, ameba, flaw, sphinx, crstlint

🎯 Intent & Upstream Vision

crinit was created with the explicit intention of being proposed and merged directly into the upstream Crystal compiler (crystal init).

The current implementation of crystal init (located in src/compiler/crystal/tools/init.cr) has remained frozen for years and exhibits several architectural limitations that hinder production engineering:

1. Hardcoded File Inventory: The compiler explicitly declares a static set of eight views: .gitignore, .editorconfig, LICENSE, README.md, shard.yml, src/<name>.cr, spec/spec_helper.cr, and spec/<name>_spec.cr.
2. Monolithic Flat Hierarchy: Modern production architectures require domain-segregated directory structures (config/, containers/, packaging/, scripts/, docs/). The current tool forces all projects into a single flat file under src/.
3. Mandatory License Lock-In: The embedded LICENSE and shard.yml templates strictly mandate the MIT license. Organizations or open-source authors wishing to release software under copyleft terms (GPLv3, AGPLv3, MPL-2.0) are forced to manually overwrite files after initialization.
4. Zero Community Extensibility: Framework authors (Kemal, Lucky, Athena, Blueprint) cannot provide canonical skeletons. Instead, they must either maintain bespoke generator shards or instruct developers to perform tedious manual setup.

crinit acts as the reference prototype, testbed, and dogfooding tool to prove the design before submitting the formal Crystal RFC and Pull Request to crystal-lang/crystal.

💡 Key Highlights & Architectural Principles

• Zero External Runtime Dependencies: Uses strictly Crystal's standard library (OptionParser, YAML, File, Dir, Process, Path). No heavy scripting interpreters.
• Offline-First & Network-Decoupled: Operates entirely on the local filesystem. Remote template fetching is intentionally decoupled to respect the compiler team's separation between crystal and shards.
• 100% Backward Compatible: Drops in as a replacement for crystal init app <name> and crystal init lib <name>, preserving existing behavior via embedded fallbacks unless overridden.
• Multi-Platform Native Support: First-class support across the entire official Crystal tier matrix (Linux, macOS, Windows).
• Arbitrary Tree Mirroring: Complete topological freedom over directories, nested namespaces (src/<name>/init.cr), assets, and licensing.
• Macro-Safe Token Substitution: Prevents syntax collisions with Crystal's native macro delimiters ({{ ... }}) while supporting explicit escaping (\{{ ... \}}).

🚀 Quickstart

Prerequisites

• Crystal: >= 1.21.0
• Shards: Bundled with Crystal
• GNU Make & Git
• cRSTLint (optional, for documentation linting)

Build and Install Locally

# 1. Clone repository
git clone https://gitlab.com/renich/crinit.git
cd crinit

# 2. Compile release binary
make build

# 3. Run full verification quality gates
make check

# 4. Install to ~/.local/bin (or sudo make install for /usr/local/bin)
install -m 0755 bin/crinit ~/.local/bin/crinit

Usage

# Using standard built-in skeletons (100% compatible with crystal init)
crinit app my_application
crinit lib my_library

# Using a custom template installed in your user/system template path
crinit service telemetry_agent

# Using an explicit filesystem template path
crinit --template ~/Projects/crystal/init/app telemetry_agent

# Forcing overwrite or skipping existing files
crinit service telemetry_agent --force
crinit service telemetry_agent --skip-existing

📂 Cross-Platform Template Resolution

crinit resolves templates across standard platform directories in the following order:

Priority 1: --template <path>                                (Explicit CLI flag)
Priority 2: CRYSTAL_TEMPLATE_PATH                           (Environment variable, split by Process::PATH_DELIMITER)
Priority 3: ./.crystal/templates/<TYPE>                     (Project/Workspace local)
Priority 4: User Data Directory                             (OS-native user path)
Priority 5: System Data Directory                           (OS-native system path or $ORIGIN-relative)
Priority 6: Built-in Defaults                               (Embedded app/lib fallback)

OS Directory Mappings

🛠️ Template Anatomy & Substitution Tokens

A custom template is simply a directory containing files, directories, and an optional manifest:

~/.local/share/crystal/templates/service/
├── template.yml                  # Optional metadata and variable prompts
├── .editorconfig
├── .gitlab-ci.yml
├── .ameba.yml
├── GNUmakefile
├── LICENSE                       # Use any license you want (GPLv3, Apache-2.0, etc.)
├── shard.yml
├── config/
│   └── database/
│       ├── connection.cr
│       └── migrations.cr
├── src/
│   ├── {{name}}.cr               # Entry point
│   └── {{name}}/
│       ├── init.cr               # Initialization logic
│       ├── cli.cr
│       └── app.cr
└── spec/
    ├── spec_helper.cr
    └── {{name}}_spec.cr

Standard Replacement Tokens

🏗️ Build System Targets

The repository includes a standard, FHS-compliant GNUmakefile:

📚 Documentation Suite

Full architectural blueprints, functional specifications, and operational playbooks are maintained under docs/:

🤝 Contributing & Code of Honor

All contributions must adhere to the Universal Code of Honor and Contributing Guidelines.

📄 License

• Software: MIT License (LICENSE).
• Documentation: GNU Free Documentation License v1.3 or later (LICENSE-DOCS).

Copyright © 2026 Rénich Bon Ćirić <renich@evalinux.com>.

💖 Support & Donations

If you find this project useful and wish to support its ongoing development, please consider donating: