feat: support fields with both hooks and variants API (#6)

* feat: support $dynamic fields with both hooks and variants API

Previously, $dynamic fields required values via the onBeforeCompile hook,
which caused errors when using the variants API to provide dynamic data.
This change allows $dynamic to work seamlessly with both approaches.

Changes:
- Moved $dynamic validation to occur after all data merging is complete
- Added _skipDynamicCheck flag for batch processor's first pass
- Validation now checks if originally-$dynamic fields have values after hook/variant data is merged
- Added comprehensive tests for variants with $dynamic fields

The system now validates that $dynamic fields are resolved regardless of
whether the data comes from onBeforeCompile hook or variants API, providing
a unified and flexible approach to dynamic content generation.

Fixes issue where variants API couldn't be used with $dynamic fields.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: make dynamic check skip truly internal

Changed _skipDynamicCheck from a public option to an internal implementation detail:
- Created private _processInternal() method with skipDynamicCheck parameter
- Added _processForBatch() method for batch processor use
- Removed _skipDynamicCheck from public ProcessOptions interface
- BatchProcessor now uses _processForBatch() instead of passing flag

This keeps the public API clean while maintaining the same functionality.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: document $dynamic support for variants API

Added comprehensive documentation showing that $dynamic fields work with:
- onBeforeCompile hook (existing)
- Variants API (new feature)
- Both combined

Changes:
- Added new subsection "Using $dynamic Fields with Variants" with examples
- Updated "Dynamic Variable Injection" section with cross-reference
- Updated features list to reflect unified $dynamic support

This makes it clear that $dynamic is a flexible keyword that works
with multiple data injection methods.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: PepijnSenders

README.md

@@ -80,7 +80,7 @@ docs/getting-started.md:
 - ✅ **File injection** - Include external files with `{{partials.xxx}}`
 - ✅ **Glob patterns** - `guides/*.md` expands to multiple files
 - ✅ **Security** - Path traversal protection, circular dependency detection
-- ✅ **Dynamic injection** - `onBeforeCompile` hook for runtime variable injection
+- ✅ **Dynamic fields** - `$dynamic` keyword works with hooks and variants API
 - ✅ **Multi-variant generation** - One template → many output files with different data
 - ✅ **Batch processing** - Process entire directories with one API call
 
@@ -695,7 +695,7 @@ const processor = new BatchProcessor({
 });
 ```
 
-Mark fields as `$dynamic` in frontmatter to require hook injection:
+Mark fields as `$dynamic` in frontmatter to require dynamic data:
 
 ```markdown
 ---
@@ -708,6 +708,11 @@ Built at {{buildTime}}
 Version: {{version}}
 ```
 
+**Note:** The `$dynamic` keyword works with both:
+- The `onBeforeCompile` hook (as shown above)
+- The variants API (see [Multi-Variant Template Generation](#multi-variant-template-generation))
+- Both combined (hook + variant data)
+
 ## Multi-Variant Template Generation
 
 Generate multiple output files from a single template with different data for each variant. Perfect for creating product pages, documentation in multiple languages, or any scenario where you need many similar files with different values.
@@ -757,6 +762,63 @@ SKU: {{sku}}
 - Works with `onBeforeCompile` for additional dynamic data
 - File-specific variants via `id` field in frontmatter
 
+### Using `$dynamic` Fields with Variants
+
+The `$dynamic` keyword works seamlessly with the variants API. Mark fields as `$dynamic` in your template, and provide values via the variant data:
+
+**Template file** (`templates/command.md`):
+```markdown
+---
+id: command-template
+name: $dynamic
+command: $dynamic
+description: $dynamic
+---
+
+# {{name}}
+
+Command: `{{command}}`
+
+{{description}}
+```
+
+**Variant configuration:**
+```typescript
+const processor = new BatchProcessor({
+  baseDir: './templates',
+  outDir: './dist',
+  variants: {
+    'command-template': {
+      data: [
+        {
+          name: 'Recipe Command',
+          command: '/recipe',
+          description: 'Generate cooking recipes'
+        },
+        {
+          name: 'Code Command',
+          command: '/code',
+          description: 'Generate code snippets'
+        }
+      ],
+      getOutputPath: (context, data, index) =>
+        `commands/${data.command.replace('/', '')}.md`
+    }
+  }
+});
+```
+
+**Generated output:**
+- `dist/commands/recipe.md` with recipe data
+- `dist/commands/code.md` with code data
+
+**Important:** If you mark fields as `$dynamic`, you must provide them via either:
+- The variants API (as shown above)
+- The `onBeforeCompile` hook
+- Both combined (hook values + variant data)
+
+If any `$dynamic` fields remain unresolved, you'll get a clear error message.
+
 ## Output Frontmatter Filtering
 
 Control which frontmatter fields appear in the final output:

packages/core/src/batch.ts

@@ -154,8 +154,9 @@ export class BatchProcessor {
       const content = readFileSync(file, "utf-8");
       const relativePath = relative(baseDir, file);
 
-      // First, do a quick parse to get the frontmatter and check for variants
-      const result = await this.mdi.process({
+      // First pass: extract frontmatter to detect if this file has variants configured
+      // Skip $dynamic validation on this pass - variants will provide the data on second pass
+      const result = await this.mdi._processForBatch({
         content,
         baseDir,
         currentFile: file,

packages/core/src/index.ts

@@ -83,9 +83,13 @@ export class MarkdownDI {
   }
 
   /**
-   * Process markdown content with dependency injection
+   * Internal process method with additional flags
+   * @internal - Used by batch processor
    */
-  async process(options: ProcessOptions): Promise<ProcessResult> {
+  private async _processInternal(
+    options: ProcessOptions,
+    skipDynamicCheck: boolean = false
+  ): Promise<ProcessResult> {
     const context: ProcessingContext = {
       baseDir: options.baseDir,
       mode: options.mode || "build",
@@ -129,24 +133,6 @@ export class MarkdownDI {
           dynamicFields,
         });
 
-        // Validate that all $dynamic fields are provided by hook
-        const missingFields: string[] = [];
-        for (const field of dynamicFields) {
-          if (!hookResult || !(field in hookResult)) {
-            missingFields.push(field);
-          }
-        }
-
-        if (missingFields.length > 0) {
-          allErrors.push({
-            type: "schema",
-            message: `Hook must provide these $dynamic fields: ${missingFields.join(
-              ", "
-            )}`,
-            location: "onBeforeCompile",
-          });
-        }
-
         // Remove $dynamic placeholders before merging
         for (const field of dynamicFields) {
           delete frontmatter[field];
@@ -163,15 +149,25 @@ export class MarkdownDI {
           location: "onBeforeCompile",
         });
       }
-    } else if (dynamicFields.length > 0) {
-      // $dynamic fields declared but no hook provided
-      allErrors.push({
-        type: "schema",
-        message: `Fields marked as $dynamic but no onBeforeCompile hook configured: ${dynamicFields.join(
-          ", "
-        )}`,
-        location: "frontmatter",
-      });
+    }
+
+    // After hook execution, validate that all $dynamic fields were provided
+    // Check that fields which were originally $dynamic now have values
+    if (!skipDynamicCheck) {
+      const missingDynamic: string[] = [];
+      for (const field of dynamicFields) {
+        if (!(field in frontmatter) || frontmatter[field] === undefined) {
+          missingDynamic.push(field);
+        }
+      }
+
+      if (missingDynamic.length > 0) {
+        allErrors.push({
+          type: "schema",
+          message: `These $dynamic fields were not provided: ${missingDynamic.join(", ")}. Provide values via onBeforeCompile hook or variants API`,
+          location: "frontmatter",
+        });
+      }
     }
 
     // Schema validation - supports both AJV (JSON Schema) and Zod (legacy)
@@ -265,6 +261,21 @@ export class MarkdownDI {
     };
   }
 
+  /**
+   * Process markdown content with dependency injection
+   */
+  async process(options: ProcessOptions): Promise<ProcessResult> {
+    return this._processInternal(options, false);
+  }
+
+  /**
+   * Internal method for batch processor to extract frontmatter without validating $dynamic fields
+   * @internal - Only for use by BatchProcessor
+   */
+  async _processForBatch(options: ProcessOptions): Promise<ProcessResult> {
+    return this._processInternal(options, true);
+  }
+
   /**
    * Validate markdown content without processing
    */

packages/core/test/batch-processor.test.ts

@@ -631,4 +631,102 @@ name: Check
     // No files should be written in check mode
     expect(existsSync(OUT_DIR)).toBe(false)
   })
+
+  test('variants work with $dynamic fields', async () => {
+    mkdirSync(join(TEST_DIR, 'templates'), { recursive: true })
+
+    writeFileSync(
+      join(TEST_DIR, 'templates', 'dynamic.md'),
+      `---
+id: dynamic-template
+name: $dynamic
+command: $dynamic
+description: $dynamic
+---
+# {{name}}
+
+Command: {{command}}
+
+{{description}}
+`
+    )
+
+    const processor = new BatchProcessor({
+      baseDir: join(TEST_DIR, 'templates'),
+      outDir: OUT_DIR,
+      variants: {
+        'dynamic-template': {
+          data: [
+            {
+              name: 'Recipe Command',
+              command: '/recipe',
+              description: 'Generate cooking recipes'
+            },
+            {
+              name: 'Code Command',
+              command: '/code',
+              description: 'Generate code snippets'
+            }
+          ],
+          getOutputPath: (_ctx, data, _idx) => {
+            const slug = (data.name as string).toLowerCase().replace(/\s+/g, '-')
+            return `${slug}.md`
+          }
+        }
+      }
+    })
+
+    const result = await processor.process()
+
+    expect(result.success).toBe(true)
+    expect(result.changedFiles).toBe(2)
+    expect(result.totalErrors).toBe(0)
+
+    // Verify first variant
+    const recipe = await Bun.file(join(OUT_DIR, 'recipe-command.md')).text()
+    expect(recipe).toContain('# Recipe Command')
+    expect(recipe).toContain('Command: /recipe')
+    expect(recipe).toContain('Generate cooking recipes')
+
+    // Verify second variant
+    const code = await Bun.file(join(OUT_DIR, 'code-command.md')).text()
+    expect(code).toContain('# Code Command')
+    expect(code).toContain('Command: /code')
+    expect(code).toContain('Generate code snippets')
+  })
+
+  test('variants with $dynamic fields fails when data not provided', async () => {
+    mkdirSync(join(TEST_DIR, 'templates'), { recursive: true })
+
+    writeFileSync(
+      join(TEST_DIR, 'templates', 'incomplete.md'),
+      `---
+id: incomplete-template
+name: $dynamic
+description: $dynamic
+---
+# {{name}}
+`
+    )
+
+    const processor = new BatchProcessor({
+      baseDir: join(TEST_DIR, 'templates'),
+      outDir: OUT_DIR,
+      variants: {
+        'incomplete-template': {
+          data: [
+            { name: 'Test' } // Missing 'description'
+          ],
+          getOutputPath: () => 'output.md'
+        }
+      }
+    })
+
+    const result = await processor.process()
+
+    expect(result.success).toBe(false)
+    expect(result.totalErrors).toBeGreaterThan(0)
+    expect(result.files[0].errors[0].message).toContain('$dynamic')
+    expect(result.files[0].errors[0].message).toContain('description')
+  })
 })