@macroforge/mcp-server 0.1.25 → 0.1.26

package/docs/custom-macros/ts-quote/pattern-matching-if-let.md

@@ -0,0 +1,33 @@
+## Pattern Matching: `{#if let}`
+
+Use `if let` for pattern matching on `Option`, `Result`, or other Rust enums:
+
+```rust
+let maybe_name: Option<&str> = Some("Alice");
+
+let code = ts_template! {
+    {#if let Some(name) = maybe_name}
+        console.log("Hello, @{name}!");
+    {:else}
+        console.log("Hello, anonymous!");
+    {/if}
+};
+```
+
+**Generates:**
+
+```typescript
+console.log("Hello, Alice!");
+```
+
+This is useful when working with optional values from your IR:
+
+```rust
+let code = ts_template! {
+    {#if let Some(default_val) = field.default_value}
+        this.@{field.name} = @{default_val};
+    {:else}
+        this.@{field.name} = undefined;
+    {/if}
+};
+```

package/docs/custom-macros/ts-quote/quick-reference.md

@@ -0,0 +1,83 @@
+## Quick Reference
+
+| `@{expr}` 
+| Interpolate a Rust expression (adds space after) 
+
+| `{| content |}` 
+| Ident block: concatenates without spaces (e.g., `{|get@{name}|}` → `getUser`) 
+
+| `&#123;> comment <&#125;` 
+| Block comment: outputs `/* comment */` 
+
+| `&#123;>> doc <<&#125;` 
+| Doc comment: outputs `/** doc */` (for JSDoc) 
+
+| `@@&#123;` 
+| Escape for literal `@&#123;` (e.g., `"@@&#123;foo&#125;"` → `@&#123;foo&#125;`) 
+
+| `"text @&#123;expr&#125;"` 
+| String interpolation (auto-detected) 
+
+| `"'^template $&#123;js&#125;^'"` 
+| JS backtick template literal (outputs ``template $&#123;js&#125;``) 
+
+| `&#123;#if cond&#125;...&#123;/if&#125;` 
+| Conditional block 
+
+| `&#123;#if cond&#125;...&#123;:else&#125;...&#123;/if&#125;` 
+| Conditional with else 
+
+| `&#123;#if a&#125;...&#123;:else if b&#125;...&#123;:else&#125;...&#123;/if&#125;` 
+| Full if/else-if/else chain 
+
+| `&#123;#if let pattern = expr&#125;...&#123;/if&#125;` 
+| Pattern matching if-let 
+
+| `&#123;#match expr&#125;&#123;:case pattern&#125;...&#123;/match&#125;` 
+| Match expression with case arms 
+
+| `&#123;#for item in list&#125;...&#123;/for&#125;` 
+| Iterate over a collection 
+
+| `&#123;#while cond&#125;...&#123;/while&#125;` 
+| While loop 
+
+| `&#123;#while let pattern = expr&#125;...&#123;/while&#125;` 
+| While-let pattern matching loop 
+
+| `&#123;$let name = expr&#125;` 
+| Define a local constant 
+
+| `&#123;$let mut name = expr&#125;` 
+| Define a mutable local variable 
+
+| `&#123;$do expr&#125;` 
+| Execute a side-effectful expression 
+
+| `&#123;$typescript stream&#125;` 
+| Inject a TsStream, preserving its source and runtime_patches (imports)
+
+**Note:** A single `@` not followed by `&#123;` passes through unchanged (e.g., `email@domain.com` works as expected).
+
+## Interpolation: `@&#123;expr&#125;`
+
+Insert Rust expressions into the generated TypeScript:
+
+```rust
+let class_name = "User";
+let method = "toString";
+
+let code = ts_template! {
+    @{class_name}.prototype.@{method} = function() {
+        return "User instance";
+    };
+};
+```
+
+**Generates:**
+
+```typescript
+User.prototype.toString = function () {
+  return "User instance";
+};
+```

package/docs/custom-macros/ts-quote/side-effects-do.md

@@ -0,0 +1,23 @@
+## Side Effects: `{$do}`
+
+Execute an expression for its side effects without producing output. This is commonly used with mutable variables:
+
+```rust
+let code = ts_template! {
+    {$let mut results: Vec<String> = Vec::new()}
+    {#for field in fields}
+        {$do results.push(format!("this.{}", field))}
+    {/for}
+    return [@{results.join(", ")}];
+};
+```
+
+Common uses for `&#123;$do&#125;`:
+
+- Incrementing counters: `&#123;$do i += 1&#125;`
+
+- Building collections: `&#123;$do vec.push(item)&#125;`
+
+- Setting flags: `&#123;$do found = true&#125;`
+
+- Any mutating operation

package/docs/custom-macros/ts-quote/string-interpolation-text-expr.md

@@ -0,0 +1,30 @@
+## String Interpolation: `"text @{expr}"`
+
+Interpolation works automatically inside string literals - no `format!()` needed:
+
+```rust
+let name = "World";
+let count = 42;
+
+let code = ts_template! {
+    console.log("Hello @{name}!");
+    console.log("Count: @{count}, doubled: @{count * 2}");
+};
+```
+
+**Generates:**
+
+```typescript
+console.log("Hello World!");
+console.log("Count: 42, doubled: 84");
+```
+
+This also works with method calls and complex expressions:
+
+```rust
+let field = "username";
+
+let code = ts_template! {
+    throw new Error("Invalid @{field.to_uppercase()}");
+};
+```

package/docs/custom-macros/ts-quote/tsstream-injection-typescript.md

@@ -0,0 +1,61 @@
+## TsStream Injection: `{$typescript}`
+
+Inject another TsStream into your template, preserving both its source code and runtime patches (like imports added via `add_import()`):
+
+```rust
+// Create a helper method with its own import
+let mut helper = body! {
+    validateEmail(email: string): boolean {
+        return Result.ok(true);
+    }
+};
+helper.add_import("Result", "macroforge/result");
+
+// Inject the helper into the main template
+let result = body! {
+    {$typescript helper}
+
+    process(data: Record<string, unknown>): void {
+        // ...
+    }
+};
+// result now includes helper's source AND its Result import
+```
+
+This is essential for composing multiple macro outputs while preserving imports and patches:
+
+```rust
+let extra_methods = if include_validation {
+    Some(body! {
+        validate(): boolean { return true; }
+    })
+} else {
+    None
+};
+
+body! {
+    mainMethod(): void {}
+
+    {#if let Some(methods) = extra_methods}
+        {$typescript methods}
+    {/if}
+}
+```
+
+## Escape Syntax
+
+If you need a literal `@&#123;` in your output (not interpolation), use `@@&#123;`:
+
+```rust
+ts_template! {
+    // This outputs a literal @{foo}
+    const example = "Use @@{foo} for templates";
+}
+```
+
+**Generates:**
+
+```typescript
+// This outputs a literal @{foo}
+const example = "Use @{foo} for templates";
+```

package/docs/custom-macros/ts-quote/while-loops-while.md

@@ -0,0 +1,81 @@
+## While Loops: `{#while}`
+
+Use `while` for loops that need to continue until a condition is false:
+
+```rust
+let items = get_items();
+let mut idx = 0;
+
+let code = ts_template! {
+    {$let mut i = 0}
+    {#while i < items.len()}
+        console.log("Item @{i}");
+        {$do i += 1}
+    {/while}
+};
+```
+
+### While-Let Pattern Matching
+
+Use `while let` for iterating with pattern matching, similar to `if let`:
+
+```rust
+let mut items = vec!["a", "b", "c"].into_iter();
+
+let code = ts_template! {
+    {#while let Some(item) = items.next()}
+        console.log("@{item}");
+    {/while}
+};
+```
+
+**Generates:**
+
+```typescript
+console.log("a");
+console.log("b");
+console.log("c");
+```
+
+This is especially useful when working with iterators or consuming optional values:
+
+```rust
+let code = ts_template! {
+    {#while let Some(next_field) = remaining_fields.pop()}
+        result.@{next_field.name} = this.@{next_field.name};
+    {/while}
+};
+```
+
+## Local Constants: `&#123;$let&#125;`
+
+Define local variables within the template scope:
+
+```rust
+let items = vec![("user", "User"), ("post", "Post")];
+
+let code = ts_template! {
+    {#for (key, class_name) in items}
+        {$let upper = class_name.to_uppercase()}
+        console.log("Processing @{upper}");
+        const @{key} = new @{class_name}();
+    {/for}
+};
+```
+
+This is useful for computing derived values inside loops without cluttering the Rust code.
+
+## Mutable Variables: `&#123;$let mut&#125;`
+
+When you need to modify a variable within the template (e.g., in a `while` loop), use `&#123;$let mut&#125;`:
+
+```rust
+let code = ts_template! {
+    {$let mut count = 0}
+    {#for item in items}
+        console.log("Item @{count}: @{item}");
+        {$do count += 1}
+    {/for}
+    console.log("Total: @{count}");
+};
+```

package/docs/sections.json

@@ -111,13 +111,106 @@
     "path": "builtin-macros/serialize.md",
     "use_cases": "toJSON, serialization, json, api, data transfer"
   },
+  {
+    "id": "deserialize/overview",
+    "title": "Deserialize: Overview",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/overview.md",
+    "use_cases": "fromJSON, deserialization, deserialize, fromjson()",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/runtime-validation",
+    "title": "Deserialize: Runtime Validation",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/runtime-validation.md",
+    "use_cases": "fromJSON, deserialization",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/serde-options",
+    "title": "Deserialize: Serde Options",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/serde-options.md",
+    "use_cases": "fromJSON, deserialization, @serde",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/all-options",
+    "title": "Deserialize: All Options",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/all-options.md",
+    "use_cases": "fromJSON, deserialization, rename_all, string, deny_unknown_fields, boolean",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/interface-support",
+    "title": "Deserialize: Interface Support",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/interface-support.md",
+    "use_cases": "fromJSON, deserialization, fromjson",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/enum-support",
+    "title": "Deserialize: Enum Support",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/enum-support.md",
+    "use_cases": "fromJSON, deserialization, fromjson",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/type-alias-support",
+    "title": "Deserialize: Type Alias Support",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/type-alias-support.md",
+    "use_cases": "fromJSON, deserialization",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/combining-with-serialize",
+    "title": "Deserialize: Combining with Serialize",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/combining-with-serialize.md",
+    "use_cases": "fromJSON, deserialization",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/error-handling",
+    "title": "Deserialize: Error Handling",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/error-handling.md",
+    "use_cases": "fromJSON, deserialization",
+    "parent_id": "deserialize"
+  },
   {
     "id": "deserialize",
     "title": "Deserialize",
     "category": "builtin-macros",
     "category_title": "Built-in Macros",
     "path": "builtin-macros/deserialize.md",
-    "use_cases": "fromJSON, deserialization, parsing, validation, json"
+    "use_cases": "fromJSON, deserialization, parsing, validation, json",
+    "is_chunked": true,
+    "chunk_ids": [
+      "deserialize/overview",
+      "deserialize/runtime-validation",
+      "deserialize/serde-options",
+      "deserialize/all-options",
+      "deserialize/interface-support",
+      "deserialize/enum-support",
+      "deserialize/type-alias-support",
+      "deserialize/combining-with-serialize",
+      "deserialize/error-handling"
+    ]
   },
   {
     "id": "custom-overview",
@@ -135,13 +228,222 @@
     "path": "custom-macros/rust-setup.md",
     "use_cases": "rust, cargo, napi, compilation, building"
   },
+  {
+    "id": "ts-macro-derive/overview",
+    "title": "#[ts_macro_derive]: Overview",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/overview.md",
+    "use_cases": "attribute, proc macro, #[ts_macro_derive]",
+    "parent_id": "ts-macro-derive"
+  },
+  {
+    "id": "ts-macro-derive/attribute-options",
+    "title": "#[ts_macro_derive]: Attribute Options",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/attribute-options.md",
+    "use_cases": "attribute, proc macro, @derive()",
+    "parent_id": "ts-macro-derive"
+  },
+  {
+    "id": "ts-macro-derive/parsing-input",
+    "title": "#[ts_macro_derive]: Parsing Input",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/parsing-input.md",
+    "use_cases": "attribute, proc macro, parse_ts_macro_input!",
+    "parent_id": "ts-macro-derive"
+  },
+  {
+    "id": "ts-macro-derive/deriveinput-structure",
+    "title": "#[ts_macro_derive]: DeriveInput Structure",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/deriveinput-structure.md",
+    "use_cases": "attribute, proc macro",
+    "parent_id": "ts-macro-derive"
+  },
+  {
+    "id": "ts-macro-derive/accessing-field-data",
+    "title": "#[ts_macro_derive]: Accessing Field Data",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/accessing-field-data.md",
+    "use_cases": "attribute, proc macro",
+    "parent_id": "ts-macro-derive"
+  },
+  {
+    "id": "ts-macro-derive/adding-imports",
+    "title": "#[ts_macro_derive]: Adding Imports",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/adding-imports.md",
+    "use_cases": "attribute, proc macro, add_import, tsstream",
+    "parent_id": "ts-macro-derive"
+  },
+  {
+    "id": "ts-macro-derive/returning-errors",
+    "title": "#[ts_macro_derive]: Returning Errors",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/returning-errors.md",
+    "use_cases": "attribute, proc macro, macroforgeerror",
+    "parent_id": "ts-macro-derive"
+  },
+  {
+    "id": "ts-macro-derive/complete-example",
+    "title": "#[ts_macro_derive]: Complete Example",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-macro-derive/complete-example.md",
+    "use_cases": "attribute, proc macro",
+    "parent_id": "ts-macro-derive"
+  },
   {
     "id": "ts-macro-derive",
     "title": "#[ts_macro_derive]",
     "category": "custom-macros",
     "category_title": "Custom Macros",
     "path": "custom-macros/ts-macro-derive.md",
-    "use_cases": "attribute, proc macro, derive attribute, rust macro"
+    "use_cases": "attribute, proc macro, derive attribute, rust macro",
+    "is_chunked": true,
+    "chunk_ids": [
+      "ts-macro-derive/overview",
+      "ts-macro-derive/attribute-options",
+      "ts-macro-derive/parsing-input",
+      "ts-macro-derive/deriveinput-structure",
+      "ts-macro-derive/accessing-field-data",
+      "ts-macro-derive/adding-imports",
+      "ts-macro-derive/returning-errors",
+      "ts-macro-derive/complete-example"
+    ]
+  },
+  {
+    "id": "ts-quote/overview",
+    "title": "Template Syntax: Overview",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/overview.md",
+    "use_cases": "ts_quote, template, macroforge_ts_quote, ts_template!, body!",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/quick-reference",
+    "title": "Template Syntax: Quick Reference",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/quick-reference.md",
+    "use_cases": "ts_quote, template, @{expr}, getuser",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/identifier-concatenation-content",
+    "title": "Template Syntax: Identifier Concatenation: `{| content |}`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/identifier-concatenation-content.md",
+    "use_cases": "ts_quote, template, getuser, setname",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/comments-and",
+    "title": "Template Syntax: Comments: `&#123;> ... <&#125;` and `&#123;>> ... <<&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/comments-and.md",
+    "use_cases": "ts_quote, template, \n\n**generates:**\n\n",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/string-interpolation-text-expr",
+    "title": "Template Syntax: String Interpolation: `\"text @&#123;expr&#125;\"`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/string-interpolation-text-expr.md",
+    "use_cases": "ts_quote, template, format!(), \n\n**generates:**\n\n",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/backtick-template-literals",
+    "title": "Template Syntax: Backtick Template Literals: `\"'^...^'\"`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/backtick-template-literals.md",
+    "use_cases": "ts_quote, template, \"'^...^'\", '^...^', ${\"${}\"}",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/conditionals-ifif",
+    "title": "Template Syntax: Conditionals: `&#123;#if&#125;...&#123;/if&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/conditionals-ifif.md",
+    "use_cases": "ts_quote, template",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/pattern-matching-if-let",
+    "title": "Template Syntax: Pattern Matching: `&#123;#if let&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/pattern-matching-if-let.md",
+    "use_cases": "ts_quote, template, option, result",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/match-expressions-match",
+    "title": "Template Syntax: Match Expressions: `&#123;#match&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/match-expressions-match.md",
+    "use_cases": "ts_quote, template, &#123;#match&#125;, match, \n\n**generates:**\n\n",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/iteration-for",
+    "title": "Template Syntax: Iteration: `&#123;#for&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/iteration-for.md",
+    "use_cases": "ts_quote, template, &#123;#for&#125;, \n\n**generates:**\n\n",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/while-loops-while",
+    "title": "Template Syntax: While Loops: `&#123;#while&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/while-loops-while.md",
+    "use_cases": "ts_quote, template, &#123;#while&#125;, while",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/side-effects-do",
+    "title": "Template Syntax: Side Effects: `&#123;$do&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/side-effects-do.md",
+    "use_cases": "ts_quote, template, &#123;$do&#125;",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/tsstream-injection-typescript",
+    "title": "Template Syntax: TsStream Injection: `&#123;$typescript&#125;`",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/tsstream-injection-typescript.md",
+    "use_cases": "ts_quote, template, &#123;$typescript&#125;, add_import()",
+    "parent_id": "ts-quote"
+  },
+  {
+    "id": "ts-quote/complete-example-json-derive-macro",
+    "title": "Template Syntax: Complete Example: JSON Derive Macro",
+    "category": "custom-macros",
+    "category_title": "Custom Macros",
+    "path": "custom-macros/ts-quote/complete-example-json-derive-macro.md",
+    "use_cases": "ts_quote, template, ts_template!",
+    "parent_id": "ts-quote"
   },
   {
     "id": "ts-quote",
@@ -149,7 +451,24 @@
     "category": "custom-macros",
     "category_title": "Custom Macros",
     "path": "custom-macros/ts-quote.md",
-    "use_cases": "ts_quote, template, code generation, interpolation"
+    "use_cases": "ts_quote, template, code generation, interpolation",
+    "is_chunked": true,
+    "chunk_ids": [
+      "ts-quote/overview",
+      "ts-quote/quick-reference",
+      "ts-quote/identifier-concatenation-content",
+      "ts-quote/comments-and",
+      "ts-quote/string-interpolation-text-expr",
+      "ts-quote/backtick-template-literals",
+      "ts-quote/conditionals-ifif",
+      "ts-quote/pattern-matching-if-let",
+      "ts-quote/match-expressions-match",
+      "ts-quote/iteration-for",
+      "ts-quote/while-loops-while",
+      "ts-quote/side-effects-do",
+      "ts-quote/tsstream-injection-typescript",
+      "ts-quote/complete-example-json-derive-macro"
+    ]
   },
   {
     "id": "integration-overview",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macroforge/mcp-server",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "MCP server for Macroforge documentation and code analysis",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
     "typescript": "^5.7.0"
   },
   "peerDependencies": {
-    "macroforge": "^0.1.25"
+    "macroforge": "^0.1.26"
   },
   "peerDependenciesMeta": {
     "macroforge": {