miki-template 1.2.0

package/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+# CI/CD Workflow
+
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types: [ created ]
+
+jobs:
+  lint:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Lint code
+        run: npx eslint src/**/*.js
+
+  test:
+    runs-on: windows-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Run test suite
+        run: npm test
+
+  publish:
+    runs-on: windows-latest
+    needs: test
+    if: github.event_name == 'release' && github.event.action == 'created'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - name: Publish package to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/AGENT.md

@@ -0,0 +1,71 @@
+# AGENT.md - Agent Instructions, Guardrails, & Architecture Rules
+
+This repository implements a Django-Style Template Engine for Node.js/Express. To ensure high code quality, consistent architecture, and full feature parity with Django without guesswork, all AI agents and developers must strictly follow these instructions and guardrails.
+
+---
+
+## 🎯 Core Objectives
+1. **Full Feature Parity**: Match Django's template engine rules for rendering variables, dotted lookups, built-in tags, filters, and template inheritance.
+2. **Deterministic & Secure**: Escape output by default using a safe-string mechanism.
+3. **No Spaghetti Code**: Maintain a strict separation of Lexer, Parser, Renderer, Context, and Tag/Filter registries.
+
+---
+
+## ⚠️ Strict Guardrails & Anti-Hallucination Rules
+
+> [!IMPORTANT]
+> **No Guesswork / Assumptions**
+> - If a tag or filter's behavior is not clearly defined in [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) or Django documentation, **DO NOT guess**. 
+> - If you notice ambiguities (e.g., how to handle circular extends or nested cycles), raise a question to the user immediately or throw a descriptive compilation error.
+
+> [!WARNING]
+> **No Regex-Based Global Search & Replace**
+> - You **must not** implement tags or filters using global regex replacements on the final string. All templates must go through:
+>   `Lexer (String -> Tokens) -> Parser (Tokens -> AST) -> Renderer (AST + Context -> HTML)`.
+> - Direct regex replacement on HTML bypasses nesting, escaping, and blocks, which introduces severe bugs.
+
+> [!CAUTION]
+> **Security Guardrails**
+> - All variable output must be HTML-escaped by default.
+> - A variable is only safe from escaping if it is marked as a `SafeString` (e.g., using the `safe` filter or internally flagged).
+> - Dynamic expression evaluation (such as in `if` tags) **must not** use direct JS `eval()`. Use a safe AST evaluator or sandboxed parser to prevent remote code execution.
+
+---
+
+## 🧩 Architectural Guidelines
+
+### 1. Lexing (`src/lexer.js`)
+*   Tokens must be generated for three primary types:
+    - `TEXT`: Plain HTML/text.
+    - `VAR`: Variables wrapped in `{{ ... }}`.
+    - `BLOCK`: Structural tags wrapped in `{% ... %}`.
+*   The Lexer must correctly handle verbatim blocks `{% verbatim %}` and comments `{% comment %}` by suppressing token output or passing raw text tokens.
+
+### 2. Parsing (`src/parser.js`)
+*   The Parser takes a stream of tokens and constructs an AST of nodes.
+*   Every node must implement a `.render(context)` method (async or sync).
+*   For tags that have closing tags (e.g., `{% if %}`...`{% endif %}`), the parser must parse nested tokens recursively until the matching close tag is encountered.
+
+### 3. Context & Scope Isolation (`src/context.js`)
+*   Context must support a stack-like structure: `.push()` to create a new scope, and `.pop()` to revert.
+*   **Variable Lookups**: Support dotted lookups:
+    - Example: `{{ user.profile.name }}` should search `user` in context, then resolve property `profile`, then property `name`.
+    - If a resolved value is a function, call it (without arguments, just like Django).
+    - If a lookup fails, return an empty string `""` by default, unless configured otherwise.
+
+### 4. Template Inheritance (`src/tags/inheritance.js`)
+*   Inheritance works by having a child template load a parent template via `{% extends "parent.html" %}`.
+*   The child overrides blocks defined as `{% block block_name %}`.
+*   During render, the parent's AST is evaluated, but block nodes are replaced by the child's corresponding block nodes.
+*   Support block nesting and the `{{ block.super }}` variable to render parent block content.
+
+---
+
+## 🛠️ Step-by-Step Task Execution Protocol
+
+When executing tasks:
+1. **Analyze Requirements**: Check [prd.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/prd.md) and [component.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/context/component.md).
+2. **Check Existing Tests**: Run current test suite using `npm test` or `node --test` to ensure a green state.
+3. **Write Tests First**: For any new filter, tag, or parser logic, write a corresponding unit test in `tests/` showing the expected template string and its expected output.
+4. **Implement Modular Code**: Put tag handlers in `src/tags/`, filters in `src/filters.js`, and maintain registry isolation.
+5. **Verify**: Ensure the test suite passes, check for escaping vulnerabilities, and check that no scope leaks occur.

package/API_REFERENCE.md

@@ -0,0 +1,314 @@
+# API Reference - miki-template
+
+This document provides complete details for the public APIs exported by the **miki-template** engine — a Django-style template engine for Node.js and Express.
+
+---
+
+## Core Exports
+
+```javascript
+const {
+  compile,
+  render,
+  asyncRender,
+  __express,
+  clearCache,
+  registerTag,
+  registerFilter,
+  registerHelper,
+  registerContextProcessor,
+  SafeString,
+  markSafe,
+  isSafe,
+  escapeHtml
+} = require('miki-template');
+```
+
+---
+
+### `compile(templateStr, options)`
+
+Compiles a raw template string into a reusable compiled template object. The compiled template caches its AST internally.
+
+**Parameters**:
+- `templateStr` (string): The raw template string to compile.
+- `options` (object): Config parameters:
+  - `views` (string|string[]): Directories to search for templates when using `extends` or `include`.
+  - `staticUrl` (string): Prefix for the `{% static %}` tag. Defaults to `/static/`.
+  - `urlHelper` (function): Custom URL resolver for `{% url %}` tag.
+
+**Returns**: An object containing:
+- `render(context)` — Synchronously renders the template.
+- `asyncRender(context)` — Returns a Promise for async rendering.
+- `renderBlock(blockName, context)` — Renders a specific block by name.
+- `renderPartial(partialName, context)` — Renders a defined partial by name.
+
+**Example**:
+```javascript
+const { compile } = require('miki-template');
+
+const template = compile('Hello {{ name }}!');
+const output = template.render({ name: 'World' });
+console.log(output); // Hello World!
+```
+
+---
+
+### `render(templateStr, context, options)`
+
+One-step convenience function that compiles and renders a template.
+
+**Parameters**:
+- `templateStr` (string): Raw template string.
+- `context` (object): Variables available to the template.
+- `options` (object): Same as `compile()` options.
+
+**Returns**: Rendered HTML string.
+
+---
+
+### `asyncRender(templateStr, context, options)`
+
+Asynchronous rendering for templates with async helpers or async context processors.
+
+**Parameters**: Same as `render()`.
+
+**Returns**: `Promise<string>` — resolved rendered HTML.
+
+**Example**:
+```javascript
+const { asyncRender } = require('miki-template');
+const html = await asyncRender('Hello {{ name }}!', { name: 'Async' });
+```
+
+---
+
+### `__express(filePath, options, callback)`
+
+Express-compatible view engine adapter. Use with `app.engine()`.
+
+**Parameters**:
+- `filePath` (string): Absolute path to the template file.
+- `options` (object): Express `res.render()` context (view engine strips `_locals`, `settings`, and other Express internals).
+- `callback` (function): Node.js callback `(err, html)`.
+
+**Example**:
+```javascript
+const express = require('express');
+const { __express } = require('miki-template');
+
+const app = express();
+app.engine('html', __express);
+app.set('view engine', 'html');
+app.set('views', './views');
+
+app.get('/', (req, res) => {
+  res.render('home', { title: 'Home Page' });
+});
+```
+
+---
+
+### `registerTag(name, parserFn)`
+
+Registers a custom block tag parser. Must be called **before** compiling templates that use the tag.
+
+**Parameters**:
+- `name` (string): Tag identifier word (e.g. `mytag` for `{% mytag %}`).
+- `parserFn` (function): `(tagContent: string, parser: Parser) => ASTNode`. Receives the raw tag content and the parser instance.
+
+**Returns**: `undefined`.
+
+**Example**:
+```javascript
+const { registerTag } = require('miki-template');
+
+registerTag('greet', (tagContent, parser) => {
+  const name = tagContent.slice(5).trim(); // strip 'greet'
+  return {
+    render: (context) => `Hello ${context.get(name) || 'Guest'}!`
+  };
+});
+
+// In template: {% greet user.name %}
+```
+
+---
+
+### `registerFilter(name, filterFn)`
+
+Registers a custom filter function.
+
+**Parameters**:
+- `name` (string): Filter name used after the pipe `|`.
+- `filterFn` (function): `(value: any, arg?: any) => any`. Receives the filtered value and optional argument.
+
+**Returns**: `undefined`.
+
+**Example**:
+```javascript
+const { registerFilter } = require('miki-template');
+
+registerFilter('reverse', (val) => {
+  return String(val).split('').reverse().join('');
+});
+
+// In template: {{ name|reverse }}
+```
+
+---
+
+### `registerHelper(name, fn)`
+
+Registers a custom block helper tag. The helper receives the **rendered** inner content as a string.
+
+**Parameters**:
+- `name` (string): Tag name (e.g. `markdown` creates `{% markdown %}...{% endmarkdown %}`).
+- `fn` (function): `(innerContent: string, context: Context) => string | Promise<string>`.
+
+**Returns**: `undefined`.
+
+**Example**:
+```javascript
+const { registerHelper } = require('miki-template');
+const markdownIt = require('markdown-it')();
+registerHelper('markdown', (content) => markdownIt.render(content));
+
+// In template:
+// {% markdown %}
+// # Hello
+// {% endmarkdown %}
+```
+
+---
+
+### `registerContextProcessor(fn)`
+
+Adds a context processor function. Similar to Django's custom context processors.
+
+**Parameters**:
+- `fn` (function): `(context: object) => object | undefined`. Receives the render context and returns extra key-value pairs to merge in.
+
+**Returns**: `undefined`.
+
+**Example**:
+```javascript
+const { registerContextProcessor } = require('miki-template');
+
+registerContextProcessor((ctx) => ({
+  siteName: 'MySite',
+  currentYear: new Date().getFullYear()
+}));
+
+// Available in all templates as {{ siteName }} and {{ currentYear }}
+```
+
+---
+
+### `SafeString`
+
+Class for values that should **bypass HTML auto-escaping**. Construct directly or use `markSafe()`.
+
+**Example**:
+```javascript
+const { SafeString } = require('miki-template');
+
+const html = new SafeString('<b>Bold</b>');
+// {{ html }} renders as <b>Bold</b>, NOT &lt;b&gt;Bold&lt;/b&gt;
+```
+
+---
+
+### `markSafe(value)`
+
+Wraps any value in a `SafeString`, instructing the engine to skip HTML escaping for that value.
+
+**Parameters**:
+- `value` (any): Value to mark as safe.
+
+**Returns**: `SafeString`.
+
+**Example**:
+```javascript
+const { markSafe } = require('miki-template');
+
+const html = markSafe('<script>alert("xss")</script>');
+// {{ html }} outputs the script tag literally (use with caution)
+```
+
+---
+
+### `isSafe(value)`
+
+Checks whether a value is a `SafeString` instance.
+
+**Parameters**:
+- `value` (any): Value to check.
+
+**Returns**: `boolean`.
+
+---
+
+### `escapeHtml(str)`
+
+Programmatically escapes HTML special characters (`<`, `>`, `&`, `"`, `'`).
+
+**Parameters**:
+- `str` (string): String to escape.
+
+**Returns**: `string`.
+
+---
+
+### `clearCache()`
+
+Clears the in-memory AST cache. Useful for development or when templates change at runtime.
+
+**Example**:
+```javascript
+const { clearCache } = require('miki-template');
+
+app.on('restart', () => clearCache());
+```
+
+---
+
+## Compiled Template API
+
+`compile()` returns an object with these methods:
+
+### `compiled.render(context)`
+
+Synchronously renders the template with the given context.
+
+```javascript
+const compiled = compile('Hello {{ name }}!');
+compiled.render({ name: 'World' }); // "Hello World!"
+```
+
+### `compiled.asyncRender(context)`
+
+Renders asynchronously, awaiting any Promise-returning helpers.
+
+```javascript
+const html = await compiled.asyncRender({ name: 'Async' });
+```
+
+### `compiled.renderBlock(blockName, context)`
+
+Renders **only** the named block. Useful for HTMX or AJAX partial responses.
+
+```javascript
+// Template: {% extends "base.html" %}
+//          {% block content %}Main{% endblock %}
+compiled.renderBlock('content', {}); // "Main"
+```
+
+### `compiled.renderPartial(partialName, context)`
+
+Renders a `{% partialdef %}` block by name.
+
+```javascript
+// Template: {% partialdef header %}My Header{% endpartialdef %}
+compiled.renderPartial('header', {}); // "My Header"
+```

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+## [1.2.0] - 2026-09-01
+### Added
+- Full **ESM** support via `src/esm.mjs` wrapper and conditional `package.json` exports.
+- **TypeScript** type definitions (`src/types.d.ts`).
+- **Async Express 5+** adapter: `__expressAsync(filePath, options) → Promise<string>`.
+- **i18n**: `trans` tag/filter, `blocktrans`, `language`, plural rules, `registerTranslation`.
+- **Plugin/library system**: `registerLibrary`, `registerLibraryFromPath`, built-ins (`humanize`, `cache`, `lorem`).
+- **`load` tag** now activates registered libraries (no longer a stub).
+- **`widthratio`** tag for proportional width calculations.
+- **`debug`** tag for dumping template context during development.
+- **`regroup`** filter for grouping arrays by attribute.
+- **`strftime`** filter with full `date-fns` format support.
+- **Unclosed tag validation**: throws descriptive errors for missing `endif`/`endfor`/`endwith`.
+- **Filter chaining on string literals**: `{{ "Hello"|lower|capfirst }}` now works.
+- New exports: `getFilter`, `stripExpressContext`, `activateLibrary`.
+
+### Fixed
+- `for` loop now supports filter expressions in iterable path (e.g. `items|regroup:"category"`).
+- `Context.reset()` properly clears cycle state and blocks between renders.
+- `__express` strips Express framework keys (`_locals`, `settings`, `cache`) from context.
+- `renderPartial` renders only the named partial, not the full template.
+- `with` tag correctly handles multiple `key=value` assignments and quoted values.
+- `if` tag condition evaluation handles `not`, `and`, `or`, and operator precedence correctly.
+- `forloop.parentloop` correctly propagates for nested loops.
+- `floatformat` default behavior matches Django (1 decimal place).
+- `timesince`/`timeuntil` handle seconds, minutes, hours, days correctly.
+- `pluralize` correctly handles singular vs plural forms.
+- `default` filter treats empty string `''` as falsy like Django.
+- `striptags` correctly removes HTML tags and handles edge cases.
+- Spaceless tag preserves whitespace inside tag attributes correctly.
+
+### Changed
+- Condition evaluation rewritten to use shunting-yard algorithm for correct operator precedence.
+- Simplified `for` loop to use `[key, value]` tuples internally for cleaner unpacking.
+- Improved `partialdef` to support both quoted and unquoted partial names.
+- `floatformat` with `-1` argument now removes all decimals.
+
+## [1.1.0] - 2026-08-31
+### Added
+- Missing `comment`/`endcomment` tag support for block comments.
+- `firstof` tag to return the first non-falsy value from arguments.
+- `length_is` filter for comparing length to a value.
+- `urlencode`, `escapeuri`, `stringformat`, `cut`, `addslashes`, `removetags` filters for Django parity.
+- `Context.reset()` method for clearing state between renders.
+- `firstof` filter variant for inline first-truthy selection.
+
+### Fixed
+- Malformed code in `inheritance.js` with extra closing braces.
+- `__express` was not exported from the module.
+- `__express` now strips Express framework keys (`_locals`, `settings`, etc.) from context.
+- `renderPartial` now properly extracts and renders only the named partial definition.
+- `with` tag now correctly handles multiple `key=value` assignments and quoted values.
+- `if` tag condition evaluation now properly handles `not`, `and`, `or`, and operator precedence.
+- `for` loop now correctly unpacks `key, value` from objects and `item, index` from arrays.
+- `forloop.parentloop` now correctly chains for nested loops.
+- Cycle state (`cycleStates`) now resets per render via `Context.reset()`.
+- Async helpers now work correctly with `asyncRender`.
+- Partial definitions now collected at compile time for proper `renderPartial` support.
+- Path traversal protection added to `extends` tag (previously only on `include`).
+- `floatformat` default behavior now matches Django (1 decimal place).
+- `timesince`/`timeuntil` now handles seconds, minutes, hours, days correctly.
+- `pluralize` now correctly handles singular vs plural forms.
+- `default` filter now treats empty string `''` as falsy like Django.
+- `striptags` now correctly removes HTML tags and handles edge cases.
+- Spaceless tag now preserves whitespace inside tag attributes correctly.
+
+### Changed
+- Rewrote condition evaluation to use shunting-yard algorithm for correct operator precedence.
+- Simplified `for` loop to use `[key, value]` tuples internally for cleaner unpacking.
+- Improved `partialdef` to support both quoted and unquoted partial names.
+- `floatformat` with `-1` argument now removes all decimals.
+
+## [1.0.0] - 2026-08-29
+### Added
+- Full Django‑style template engine with variables, filters, tags, inheritance, partials, and context processors.
+- Security features: auto‑escaping, `markSafe`, `csrf_token` and `csp_nonce_attr` tags.
+- Extensible API: `registerTag`, `registerFilter`, `markSafe`.
+- Express integration via `__express` adapter.
+- Comprehensive test suite (40 passing tests) and benchmark suite.
+- Detailed documentation hierarchy (`docs/`): overview, installation, usage, tags, filters, partialdef, security, API reference, contribution guide.
+- CI workflow using GitHub Actions.
+- Project scaffolding, linting, and contribution guardrails (`AGENT.md`).
+
+### Fixed
+- Auto‑escaping now respects `SafeString` values.
+- Context processors correctly propagate returned context.
+- Fixed tag parsing edge cases in `IfNode` and `PartialDefNode`.
+
+### Changed
+- Updated README with npm version and CI badges.
+- Added `CHANGELOG.md` for release notes.
+
+[1.2.0]: https://github.com/your-repo/miki-template/releases/tag/v1.2.0
+[1.1.0]: https://github.com/your-repo/miki-template/releases/tag/v1.1.0
+[1.0.0]: https://github.com/your-repo/miki-template/releases/tag/v1.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, experience level, nationality, personal appearance, race, religion, or sexual orientation.
+
+## Our Standards
+Examples of behavior that contributes to creating a positive environment include:
+- Using welcoming and inclusive language.
+- Being respectful of differing viewpoints and experiences.
+- Gracefully accepting constructive criticism.
+- Focusing on what is best for the community.
+- Showing empathy towards other community members.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct.

package/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing to Django-Style Template Engine
+
+Thank you for your interest in contributing! Please follow these guidelines:
+
+---
+
+## 🛠️ Development Setup
+
+1. **Clone the Repository**
+2. **Install Dependencies**:
+   ```bash
+   npm install
+   ```
+3. **Run the Tests**:
+   ```bash
+   npm test
+   ```
+
+---
+
+## 🛑 Guardrails & Standards
+
+Before submitting a PR, make sure your code aligns with the strict requirements outlined in [AGENT.md](file:///c:/Users/Coder%20Miki/Desktop/miki-template/AGENT.md):
+- Ensure full parity with Django syntax behavior.
+- Do not use `eval()` for safety.
+- Write corresponding unit tests in `tests/` for all new features or bug fixes.
+- Verify that auto-escaping remains secure by default.