# 🧵 Wefter
**Wefter** is a profile-driven automation runtime that lets you use Lua to define _cli_ command trees that perform structured, template-based code generation, embedding, or introspection.
In simple terms, **Wefter** helps you automate code scaffolding and project workflows:
* **Create custom CLI commands**: Define project-specific commands and subcommands using simple Lua scripts.
* **Generate files from templates**: Render new code files, components, or boilerplate using dynamic templates (powered by Tera/Jinja2).
* **Inject code into existing files**: Automatically insert imports, initialization code, or snippets into existing files at specified comment markers (`@wefter.embed`).
* **Prompt for user input**: Interactively ask for text input or menu selections right in the terminal.
* **Display rich Markdown in terminal**: Render formatted Markdown in the CLI for documentation, introspection, or command output.
## Quickstart 🚀
Get up and running with **Wefter** in a few steps by creating a project-local profile:
#### 1. Installation
Install Wefter directly from [crates.io](https://crates.io/crates/wefter):
```bash
cargo install wefter
```
Or install from source:
```bash
cargo install --path .
```
#### 2. Set up a project-local profile
Create a `.wefter` directory in the project root with a profile folder:
```bash
mkdir -p .wefter/my-profile/templates
```
#### 3. Add `auto.lua` & `init.lua`
Create `.wefter/my-profile/auto.lua` so Wefter automatically activates this profile when inside the project directory:
```lua
-- .wefter/my-profile/auto.lua
return true
```
Create `.wefter/my-profile/init.lua` to define custom commands:
```lua
-- .wefter/my-profile/init.lua
return {
component = {
description = "Component generation commands",
subcommand = {
create = {
description = "Create a new UI component",
exec = function()
local name = wefter.io.input("Component name (e.g., Button)")
wefter.template.create(
"src/components/" .. name .. ".js",
"component.js",
{ name = name }
)
end,
},
},
},
}
```
#### 4. Create a template
Create `.wefter/my-profile/templates/component.js`:
```javascript
// .wefter/my-profile/templates/component.js
export function {{ name }}() {
return <div>{{ name }} Component</div>;
}
```
#### 5. Run the command
Execute the CLI command:
```bash
wefter component create
```
Wefter will prompt for the component name, render the template, and create `src/components/Button.js`
### Examples
Check more advanced use cases in the `examples` directory, you can also check this repository's `.wefter` directory.
## Profiles 📑
A **profile** is a self-contained module written in Lua that defines a CLI command tree and provides the templates to use.
Profile directory structure:
```
my-profile/
init.lua
auto.lua (optional)
templates/
```
### `init.lua`
`init.lua` must return a Lua table describing the command hierarchy.
Example:
```lua
return {
-- Top level command
widget = {
description = "Widget utilities",
subcommand = {
-- Subcommand within widget command
create = {
description = "Create a widget",
exec = function()
local name = wefter.io.input("Widget name")
-- Create a new file from a template
wefter.template.create(
-- New file name (parent directories will be created)
"lib/widgets/" .. name .. ".dart",
-- Template path from profile (<profile>/templates/widget.dart)
"widget.dart",
-- Template parameters
{ name = name }
)
end,
},
},
},
}
```
This creates the following command:
```
wefter widget create
```
Each node may contain:
* `description` - String describing the command (for showing help on bad usage)
* `subcommand` - Table with key, value pairs for other commands
* `exec` - Function to execute when the command is called
A command can only have *subcommand* or *exec*
### `templates/`
This directory contains all user-defined templates (visit [Templates](#templates) on how templates work and how to create them).
Templates are resolved relative to the profile’s `templates/` directory.
i.e.
```
my-profile/
templates/
foo/
bar.md
baz.md
```
```lua
-- Create a file `hello.md` from template `my-profile/templates/foo/bar.md`
wefter.template.create("hello.md", "foo/bar.md", {})
-- Get rendered template as string from `my-profile/templates/baz.md`
local baz = wefter.template.get("baz.md", {})
-- Render template to cli (wefter has an embedded markdown CLI renderer)
-- You can use this feature to build introspection commands (i.e list classes,
-- show dependencies, etc) and presenting them with your own markdown template
wefter.io.markdown(baz);
```
### `auto.lua`
Helps `wefter` decide _which **profile** to use_ for the current project. If no `auto.lua` is specified, then the profile must be explicitly specified using `wefter -p my-profile`.
`auto.lua` is executed for every profile (when no profile is specified with `-p`). This file must return a boolean (`true` if the profile applies, `false` otherwise). Only one profile must be valid at a time; Wefter will request explicit profile selection on conflict.
In `auto.lua`, only `early-loading` API modules (such as `wefter.fs`) are available. It does not have access to other profile-specific modules or templates.
Here's a simple example of detecting a profile for a Rust application:
```lua
return wefter.fs.is_file("Cargo.toml")
```
For most project specific profiles ([.wefter directory](#profile-locations)) a simple `return true` statement is enough.
### Profile Locations
Profiles can be defined either system-wide or per project.
**System profiles** live in the configured data directory, `~/.local/share/wefter` by default, but location can be changed in the configuration file `~/.config/wefter/wefter.toml`:
```toml
data_dir = "/home/<user>/.local/share/wefter"
```
Paths vary by OS and are resolved using the Rust [directories](https://crates.io/crates/directories) crate.
**Project-local profiles** live inside a folder named `.wefter` in the project root directory.
```
my-project/
src/
.wefter/ (Project-local profiles)
my-profile/
```
Use the data directory for reusable profiles, and `.wefter/` for project-specific ones.
## Templates 📐
Wefter uses [Tera](https://keats.github.io/tera/docs/) as its template rendering engine. Tera is a powerful templating engine inspired by Jinja2 and Django templates.
### Overview
Templates live in your profile's `templates/` directory and support dynamic expression substitution (`{{ variable }}`), control flow constructs (`{% if %}`, `{% for %}`), filters, and formatting logic.
You can interact with templates using the Lua API:
- **`wefter.template.create(destination, template_path, params)`**: Renders a template and creates a new file at `destination`.
- **`wefter.template.embed(destination, insertion_point, template_path, params)`**: Renders a template and inserts its content into an existing file right before matching `@wefter.embed` or `@wefter.embed:<named>` insertion point comments.
- **`wefter.template.get(template_path, params)`**: Renders a template and returns the resulting content as a string.
You can also use _inline_ variant (create_inline, embed_inline) to use template strings instead of template paths.
For full details on template syntax, variables, filters, and control structures, check the official [Tera Documentation](https://keats.github.io/tera/docs/).
## Insertion Points 🪡
**Insertion points** allow Wefter to inject dynamically rendered code directly into existing files at specific locations marked by special comments.
### Comment Syntax
Place an insertion point comment anywhere in your target file using your language's standard comment syntax (`//`, `/* ... */`, `#`, `--`, `<!-- ... -->`):
- **Default Insertion Point**: `@wefter.embed` (matches when `ipoint` is `nil`)
- **Named Insertion Point**: `@wefter.embed:<name>` (e.g., `@wefter.embed:includes`, `@wefter.embed:routes`)
```c
// main.c
#include <stdio.h>
/* @wefter.embed:includes */
int main(void) {
/* @wefter.embed:init */
return 0;
}
```
### Embedding via Lua API
Use `wefter.template.embed` or `wefter.template.embed_inline` to insert content at an insertion point:
- **`wefter.template.embed(destination, ipoint, template_path, params)`**: Renders a template file and inserts it.
- **`wefter.template.embed_inline(destination, ipoint, template_str, params)`**: Renders an inline template string and inserts it.
#### Parameters:
* `destination` *(string)*: Target file path relative to project root.
* `ipoint` *(string | nil)*: Target insertion point name (e.g., `"includes"` matches `@wefter.embed:includes`). Pass `nil` to target generic `@wefter.embed` comments.
* `template` / `template_str` *(string)*: Template file path inside `templates/` or raw template string.
* `params` *(table)*: Parameters passed to the Tera rendering engine.
### Example
In your Lua profile script (`init.lua`):
```lua
-- Inject an include statement at `@wefter.embed:includes`
wefter.template.embed_inline("main.c", "includes", '#include "{{ header }}"', { header = "module.h" })
-- Inject initialization code at `@wefter.embed:init`
wefter.template.embed_inline("main.c", "init", 'init_module("{{ name }}");', { name = "my_module" })
```
#### Resulting `main.c`:
```c
#include <stdio.h>
#include "module.h"
/* @wefter.embed:includes */
int main(void) {
init_module("my_module");
/* @wefter.embed:init */
return 0;
}
```
### Key Behaviors
* **Automatic Indentation Matching**: Injected code automatically matches the indentation (leading spaces or tabs) of the insertion point comment line.
* **Marker Preservation**: The insertion point comment remains in place after injection, allowing subsequent commands to insert additional code at the same marker.
* **Multiple Markers**: If multiple matching insertion point comments exist in the target file, content is injected before each occurrence.
## Lua API ⚒️
Wefter exposes a global `wefter` namespace in the Lua runtime along with environment constants:
### Global Constants
* `WEFTER_VERSION`: Current Wefter version string.
* `WEFTER_PROJECT_ROOT`: Absolute path to the root directory of the current project.
### API Modules
* **`wefter.fs`**: Filesystem utilities (`is_dir`, `is_file`, `read_to_string`, `read_dir`). Available during early-loading (`auto.lua`).
* **`wefter.io`**: TUI and user interaction tools (`input`, `select`, `markdown`).
* **`wefter.template`**: Template rendering and code generation utilities (`create`, `embed`, `get`).
* **`wefter.txt`**: String casing transformation helpers (`to_snake_case`, `to_camel_case`, `to_pascal_case`, `to_upper_camel_case`, `to_kebab_case`).
For full type definitions, function signatures, and docstrings, see the definition file [`static/lua/wefter.d.lua`](static/lua/wefter.d.lua) (or generate it locally via `wefter --meta > .wefter.d.lua`).
## Lua LSP 🧰
Need help navigating the API? _wefter_ can create a [Lua Definition File](https://luals.github.io/wiki/definition-files/), this file will be used by your LSP to give you proper diagnostics and completion.
Create a **definition file** using the following command:
```
wefter --meta > .wefter.d.lua
```
Then, setup the LSP to use it.
**LuaLS** example, `.luarc.json`:
```json
{
"workspace.library": [".wefter.d.lua"],
"diagnostics.globals": ["wefter", "WEFTER_VERSION", "WEFTER_PROJECT_ROOT"]
}
```
## Acknowledgements ❤️
Wefter is built on top of amazing open-source libraries in the Rust ecosystem:
* [**mlua**](https://crates.io/crates/mlua) - Embedded Lua runtime bindings for Rust.
* [**tera**](https://crates.io/crates/tera) - Powerful Jinja2/Django-inspired templating engine.
* [**clap**](https://crates.io/crates/clap) - Command line argument parsing and help formatting.
* [**inquire**](https://crates.io/crates/inquire) - Interactive terminal prompts for user inputs and selections.
* [**termimad**](https://crates.io/crates/termimad) - In-terminal Markdown rendering engine.
* [**directories**](https://crates.io/crates/directories) - Cross-platform path resolution for system configuration and data folders.
* [**convert_case**](https://crates.io/crates/convert_case) - String case conversion helpers (_wefter.txt_ API).
## AI Notice 🤖
The core codebase of Wefter is mostly human-written (90%+). AI assistance was brealy used and was mainly focused on documentation and minor boilerplate