Merge pull request #32 from bordeux/feature/ide-support

feat: add --ide-json flag for IDE integration

Author: bordeux

CLAUDE.md

@@ -59,6 +59,7 @@ It's designed for **DevOps/SRE workflows** like generating Kubernetes manifests,
 4. **Security by default** - Filesystem restricted to CWD; use `--trust` for full access
 5. **Output validation** - `--validate json/yaml/toml` ensures valid output format
 6. **Single binary** - No runtime dependencies, easy to deploy in containers
+7. **IDE integration** - `--ide-json` outputs all function metadata (83 functions) for editor autocomplete/docs
 
 ### CLI Quick Reference
 ```bash
@@ -70,6 +71,7 @@ echo '{{ now() }}' | tmpltool             # Pipe template from stdin
 # With options
 tmpltool --trust system.tmpl              # Allow filesystem access outside CWD
 tmpltool config.tmpl --validate json      # Validate output is valid JSON
+tmpltool --ide-json                       # Output function metadata as JSON (for IDE integration)
 
 # With environment variables
 DB_HOST=prod-db APP_ENV=production tmpltool config.tmpl
@@ -234,6 +236,7 @@ src/
 ├── renderer.rs       - Core template rendering logic (MiniJinja setup)
 ├── functions/        - Custom template functions (modular)
 │   ├── mod.rs        - Function registration with MiniJinja
+│   ├── metadata.rs   - FunctionMetadata types for IDE integration
 │   ├── environment.rs
 │   ├── hash.rs
 │   ├── filesystem.rs
@@ -288,26 +291,113 @@ main.rs → render_template() → read_template() → render() → write_output(
                               Template parsing + rendering with context
 ```
 
+**5. Trait-Based Metadata System**
+- All filter/is-functions implement traits with required `METADATA` constant
+- `FilterFunction` trait: dual function + filter syntax (e.g., `md5`)
+- `IsFunction` / `ContextIsFunction` traits: dual function + is-test syntax (e.g., `is_email`)
+- Metadata includes: name, category, description, arguments, return type, examples, syntax variants
+- `--ide-json` collects metadata from all traits via `get_all_metadata()` in lib.rs
+- Ensures documentation stays in sync with implementation (single source of truth)
+
 ### Adding New Functions
 
-When adding new template functions:
-
-1. **Create function file** in `src/functions/` (e.g., `network.rs`)
-2. **Implement function** using MiniJinja patterns:
-   ```rust
-   use minijinja::value::Kwargs;
-   use minijinja::{Error, Value};
-
-   pub fn my_function(kwargs: Kwargs) -> Result<Value, Error> {
-       let arg: String = kwargs.get("arg_name")?;
-       // Implementation
-       Ok(Value::from(result))
-   }
-   ```
-3. **Add module declaration** in `src/functions/mod.rs`: `pub mod network;`
-4. **Register function** in `register_all()`: `env.add_function("my_function", network::my_function);`
-5. **Write tests** in `tests/test_my_function.rs`. IMPORTANT: always in tests folder write tests. src folder should be clean from the tests.
-6. **Document** in README.md with examples
+Functions use a trait-based system with **required metadata** for IDE integration. When implementing traits (`FilterFunction`, `IsFunction`, `ContextIsFunction`), you MUST provide a `METADATA` constant.
+
+**For filter functions (dual function + filter syntax):**
+
+Add to `src/filter_functions/` and implement `FilterFunction` trait:
+```rust
+use crate::filter_functions::FilterFunction;
+use crate::functions::metadata::{ArgumentMetadata, FunctionMetadata, SyntaxVariants};
+use minijinja::value::Kwargs;
+use minijinja::{Error, Value};
+
+pub struct MyFilter;
+
+impl FilterFunction for MyFilter {
+    const NAME: &'static str = "my_filter";
+    const METADATA: FunctionMetadata = FunctionMetadata {
+        name: "my_filter",
+        category: "string",
+        description: "Description of what this does",
+        arguments: &[ArgumentMetadata {
+            name: "string",
+            arg_type: "string",
+            required: true,
+            default: None,
+            description: "Input string",
+        }],
+        return_type: "string",
+        examples: &[
+            "{{ my_filter(string=\"hello\") }}",
+            "{{ \"hello\" | my_filter }}",
+        ],
+        syntax: SyntaxVariants::FUNCTION_AND_FILTER,
+    };
+
+    fn call_as_function(kwargs: Kwargs) -> Result<Value, Error> {
+        let input: String = kwargs.get("string")?;
+        Ok(Value::from(input.to_uppercase()))
+    }
+
+    fn call_as_filter(value: &Value, _kwargs: Kwargs) -> Result<Value, Error> {
+        let input = value.as_str().unwrap_or_default();
+        Ok(Value::from(input.to_uppercase()))
+    }
+}
+```
+
+Then register in `src/filter_functions/mod.rs`:
+```rust
+MyFilter::register(env);
+```
+
+And add to `get_all_metadata()`:
+```rust
+&my_module::MyFilter::METADATA,
+```
+
+**For is-functions (dual function + is-test syntax):**
+
+Add to `src/is_functions/` and implement `IsFunction` or `ContextIsFunction` trait:
+```rust
+use crate::is_functions::IsFunction;
+use crate::functions::metadata::{ArgumentMetadata, FunctionMetadata, SyntaxVariants};
+
+pub struct MyCheck;
+
+impl IsFunction for MyCheck {
+    const FUNCTION_NAME: &'static str = "is_my_check";
+    const IS_NAME: &'static str = "my_check";
+    const METADATA: FunctionMetadata = FunctionMetadata {
+        name: "is_my_check",
+        category: "validation",
+        description: "Check if value passes my_check",
+        arguments: &[...],
+        return_type: "boolean",
+        examples: &[
+            "{{ is_my_check(string=\"test\") }}",
+            "{% if \"test\" is my_check %}...{% endif %}",
+        ],
+        syntax: SyntaxVariants::FUNCTION_AND_TEST,
+    };
+
+    fn call_as_function(kwargs: Kwargs) -> Result<Value, Error> { ... }
+    fn call_as_is(value: &Value) -> bool { ... }
+}
+```
+
+**For standalone functions in `src/functions/`:**
+
+These still use direct function registration:
+```rust
+pub fn my_function(kwargs: Kwargs) -> Result<Value, Error> {
+    let arg: String = kwargs.get("arg_name")?;
+    Ok(Value::from(result))
+}
+```
+
+Register in `register_all()`: `env.add_function("my_function", my_module::my_function);`
 
 **For context-aware functions (filesystem access):**
 ```rust
@@ -318,12 +408,13 @@ pub fn create_my_fn(context: Arc<TemplateContext>) -> impl Fn(Kwargs) -> Result<
     move |kwargs: Kwargs| {
         let path: String = kwargs.get("path")?;
         let resolved = context.validate_and_resolve_path(&path)?;
-        // Use resolved path
         Ok(Value::from(result))
     }
 }
 ```
 
+**Testing:** Write tests in `tests/test_my_function.rs` (never in src folder)
+
 ### Testing Philosophy
 
 - Unit tests in `tests/` directory
@@ -366,6 +457,8 @@ cargo make all
 
 Husky pre-commit hooks validate commit message format.
 
+**Important:** Do not include Claude model references (e.g., "Co-Authored-By: Claude") in commit messages. Keep commits clean and professional.
+
 ### Debugging Template Rendering
 
 When debugging template issues:

Cargo.toml

@@ -39,6 +39,8 @@ urlencoding = "2"
 
 [dev-dependencies]
 tempfile = "3.24.0"
+assert_cmd = "2"
+predicates = "3"
 
 [package.metadata.deb]
 maintainer = "Chris Bednarczyk <tmpltool@bordeux.net>"

README.md

@@ -38,6 +38,7 @@ A fast and simple command-line template rendering tool using [MiniJinja](https:/
   - [Web & URL Functions](#web--url-functions)
   - [Logic Functions](#logic-functions)
   - [Debugging & Development Functions](#debugging--development-functions)
+- [IDE Integration](#ide-integration)
 - [Advanced Examples](#advanced-examples)
 - [Error Handling](#error-handling)
 - [Development](#development)
@@ -50,18 +51,8 @@ A fast and simple command-line template rendering tool using [MiniJinja](https:/
 Get started in 30 seconds:
 
 ```bash
-# Download binary for your platform from releases
-# https://github.com/bordeux/tmpltool/releases
-
-# Or use Docker to copy the binary (recommended for CI/CD):
-# Create a Dockerfile to extract the binary
-cat > Dockerfile << 'EOF'
-FROM alpine:latest
-COPY --from=ghcr.io/bordeux/tmpltool:latest /tmpltool /usr/local/bin/tmpltool
-EOF
-
-docker build -t myapp .
-# Now tmpltool is available in your image at /usr/local/bin/tmpltool
+# Install tmpltool (works on macOS, Linux, and more)
+curl -fsSL https://raw.githubusercontent.com/bordeux/repo/master/install.sh | sh -s -- tmpltool
 
 # Create and render template
 echo 'Hello {{ get_env(name="USER", default="World") }}!' > greeting.tmpl
@@ -94,6 +85,61 @@ tmpltool greeting.tmpl
 
 ## Installation
 
+### Universal Installer (Recommended)
+
+The easiest way to install tmpltool on any supported platform:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bordeux/repo/master/install.sh | sh -s -- tmpltool
+```
+
+This script automatically detects your OS and installs using the appropriate package manager.
+
+### macOS (Homebrew)
+
+```bash
+brew tap bordeux/tap
+brew install tmpltool
+```
+
+### Debian/Ubuntu (APT)
+
+```bash
+# Add repository and install
+curl -fsSL https://raw.githubusercontent.com/bordeux/repo/master/install.sh | sh
+sudo apt update
+sudo apt install tmpltool
+```
+
+Or manually:
+
+```bash
+# Add GPG key
+curl -fsSL https://bordeux.github.io/apt-repo/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/bordeux-archive-keyring.gpg
+
+# Add repository
+echo "deb [signed-by=/usr/share/keyrings/bordeux-archive-keyring.gpg] https://bordeux.github.io/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/bordeux.list
+
+# Install
+sudo apt update
+sudo apt install tmpltool
+```
+
+### Fedora/RHEL/CentOS (RPM)
+
+```bash
+# Add repository and install
+curl -fsSL https://raw.githubusercontent.com/bordeux/repo/master/install.sh | sh
+sudo dnf install tmpltool  # or yum on older systems
+```
+
+Or manually:
+
+```bash
+sudo curl -fsSL https://bordeux.github.io/rpm-repo/bordeux.repo -o /etc/yum.repos.d/bordeux.repo
+sudo dnf install tmpltool
+```
+
 ### From GitHub Releases
 
 Download pre-built binaries for your platform from the [releases page](https://github.com/bordeux/tmpltool/releases):
@@ -179,6 +225,10 @@ cat template.txt | tmpltool [OPTIONS]
   - Validates the rendered output conforms to the specified format
   - Exits with error code 1 if validation fails
   - No output on success, error message only on validation failure
+- `--ide <FORMAT>` - Output function metadata for IDE integration (json, yaml, or toml)
+  - Prints all available functions with descriptions, arguments, return types, and examples
+  - Exits immediately after printing metadata (does not render templates)
+  - Useful for building IDE plugins, autocomplete, and documentation generators
 
 ### Input/Output Patterns
 
@@ -6159,6 +6209,85 @@ application:
 - ✅ **Graceful Degradation**: Use `warn()` for non-critical issues
 - ✅ **Fail Fast**: Use `abort()` for critical failures requiring immediate attention
 
+## IDE Integration
+
+The `--ide` flag outputs comprehensive metadata about all available functions, making it easy to build IDE plugins, autocomplete systems, and documentation generators.
+
+### Output Formats
+
+```bash
+# JSON output (array of function metadata)
+tmpltool --ide json > functions.json
+
+# YAML output (list of function metadata)
+tmpltool --ide yaml > functions.yaml
+
+# TOML output (wrapped in [[functions]] array)
+tmpltool --ide toml > functions.toml
+```
+
+### Metadata Structure
+
+Each function includes:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Function name (e.g., `get_env`, `md5`) |
+| `category` | Category grouping (e.g., `environment`, `hash`, `string`) |
+| `description` | What the function does |
+| `arguments` | Array of argument definitions with name, type, required flag, default value, and description |
+| `return_type` | Type of value returned |
+| `examples` | Usage examples showing both function and filter syntax where applicable |
+| `syntax.function` | Whether callable as `func(arg=value)` |
+| `syntax.filter` | Whether callable as `value \| filter` |
+| `syntax.is_test` | Whether usable in `{% if value is test %}` |
+
+### Example Output (JSON)
+
+```json
+[
+  {
+    "name": "get_env",
+    "category": "environment",
+    "description": "Get environment variable with optional default value",
+    "arguments": [
+      {
+        "name": "name",
+        "arg_type": "string",
+        "required": true,
+        "default": null,
+        "description": "Environment variable name"
+      },
+      {
+        "name": "default",
+        "arg_type": "string",
+        "required": false,
+        "default": null,
+        "description": "Default value if variable is not set"
+      }
+    ],
+    "return_type": "string",
+    "examples": [
+      "{{ get_env(name=\"HOME\") }}",
+      "{{ get_env(name=\"PORT\", default=\"8080\") }}"
+    ],
+    "syntax": {
+      "function": true,
+      "filter": false,
+      "is_test": false
+    }
+  }
+]
+```
+
+### Use Cases
+
+- **IDE Plugins**: Provide autocomplete suggestions with argument hints and documentation
+- **Language Servers**: Power hover documentation and signature help
+- **Documentation Generators**: Automatically generate function reference documentation
+- **Validation Tools**: Verify template function usage against available functions
+- **CI/CD Integration**: Generate function lists for pipeline documentation
+
 ## Advanced Examples
 
 ### Docker Compose Generator