@macroforge/mcp-server 0.1.42 → 0.1.50

package/docs/integration/cli.md

@@ -1,76 +1,156 @@
 # Command Line Interface
-  *This binary provides command-line utilities for working with Macroforge TypeScript macros. It is designed for development workflows, enabling macro expansion and type checking without requiring Node.js integration.*
- ## Installation
- The CLI is a Rust binary. You can install it using Cargo:
- ```
-cargo install macroforge_ts
-``` Or build from source:
- ```
-git clone https://github.com/rymskip/macroforge-ts.git
-cd macroforge-ts/crates
-cargo build --release --bin macroforge
-
-# The binary is at target/release/macroforge
-``` ## Commands
- ### macroforge expand
- Expands macros in a TypeScript file and outputs the transformed code.
- ```
-macroforge expand <input> [options]
-``` #### Arguments
- | Argument | Description |
-| --- | --- |
-| <input> | Path to the TypeScript or TSX file to expand |
- #### Options
- | Option | Description |
-| --- | --- |
-| --out <path> | Write the expanded JavaScript/TypeScript to a file |
-| --types-out <path> | Write the generated .d.ts declarations to a file |
-| --print | Print output to stdout even when --out is specified |
-| --builtin-only | Use only built-in Rust macros (faster, but no external macro support) |
- #### Examples
- Expand a file and print to stdout:
- ```
-macroforge&nbsp;expand&nbsp;src/user.ts
-``` Expand and write to a file:
- ```
-macroforge&nbsp;expand&nbsp;src/user.ts&nbsp;--out&nbsp;dist/user.js
-``` Expand with both runtime output and type declarations:
- ```
-macroforge&nbsp;expand&nbsp;src/user.ts&nbsp;--out&nbsp;dist/user.js&nbsp;--types-out&nbsp;dist/user.d.ts
-``` Use fast built-in macros only (no external macro support):
- ```
-macroforge&nbsp;expand&nbsp;src/user.ts&nbsp;--builtin-only
-``` > **Note:** By default, the CLI uses Node.js for full macro support (including external macros). It must be run from your project's root directory where macroforge and any external macro packages are installed in node_modules. ### macroforge tsc
- Runs TypeScript type checking with macro expansion. This wraps <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">tsc <span style="--shiki-dark:#F97583;--shiki-light:#D73A49">--<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">noEmit</code> and expands macros before type checking, so your generated methods are properly type-checked.
- ```
-macroforge&nbsp;tsc&nbsp;[options]
-``` #### Options
- | Option | Description |
-| --- | --- |
-| -p, --project <path> | Path to tsconfig.json (defaults to tsconfig.json in current directory) |
- #### Examples
- Type check with default tsconfig.json:
- ```
-macroforge&nbsp;tsc
-``` Type check with a specific config:
- ```
-macroforge&nbsp;tsc&nbsp;-p&nbsp;tsconfig.build.json
-``` ## Output Format
- ### Expanded Code
- When expanding a file like this:
- ```
-/**&nbsp;@derive(Debug)&nbsp;*/
-class&nbsp;User&nbsp;&#123;
-&nbsp;&nbsp;name:&nbsp;string;
-&nbsp;&nbsp;age:&nbsp;number;
-
-&nbsp;&nbsp;constructor(name:&nbsp;string,&nbsp;age:&nbsp;number)&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;this.name&nbsp;=&nbsp;name;
-&nbsp;&nbsp;&nbsp;&nbsp;this.age&nbsp;=&nbsp;age;
-&nbsp;&nbsp;&#125;
-&#125;
-``` The CLI outputs the expanded code with the generated methods:
- ```
+
+macroforge v0.1.48
+
+This binary provides command-line utilities for working with Macroforge TypeScript macros. It is designed for development workflows, enabling macro expansion and type checking without requiring Node.js integration.
+
+## Installation
+
+The CLI is a Rust binary. You can install it using Cargo:
+
+Bash
+
+```
+cargo install macroforge_ts
+```
+
+Or build from source:
+
+Bash
+
+```
+git clone https://github.com/rymskip/macroforge-ts.git
+cd macroforge-ts/crates
+cargo build --release --bin macroforge
+
+# The binary is at target/release/macroforge
+```
+
+## Commands
+
+### macroforge expand
+
+Expands macros in a TypeScript file and outputs the transformed code.
+
+Bash
+
+```
+macroforge expand <input> [options]
+```
+
+#### Arguments
+
+| Argument  | Description                                  |
+| --------- | -------------------------------------------- |
+| `<input>` | Path to the TypeScript or TSX file to expand |
+
+#### Options
+
+| Option               | Description                                                           |
+| -------------------- | --------------------------------------------------------------------- |
+| `--out <path>`       | Write the expanded JavaScript/TypeScript to a file                    |
+| `--types-out <path>` | Write the generated `.d.ts` declarations to a file                    |
+| `--print`            | Print output to stdout even when `--out` is specified                 |
+| `--builtin-only`     | Use only built-in Rust macros (faster, but no external macro support) |
+
+#### Examples
+
+Expand a file and print to stdout:
+
+Bash
+
+```
+macroforge expand src/user.ts
+```
+
+Expand and write to a file:
+
+Bash
+
+```
+macroforge expand src/user.ts --out dist/user.js
+```
+
+Expand with both runtime output and type declarations:
+
+Bash
+
+```
+macroforge expand src/user.ts --out dist/user.js --types-out dist/user.d.ts
+```
+
+Use fast built-in macros only (no external macro support):
+
+Bash
+
+```
+macroforge expand src/user.ts --builtin-only
+```
+
+Note
+
+By default, the CLI uses Node.js for full macro support (including external macros). It must be run from your project's root directory where `macroforge` and any external macro packages are installed in `node_modules`.
+
+### macroforge tsc
+
+Runs TypeScript type checking with macro expansion. This wraps `tsc --noEmit` and expands macros before type checking, so your generated methods are properly type-checked.
+
+Bash
+
+```
+macroforge tsc [options]
+```
+
+#### Options
+
+| Option                 | Description                                                                |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `-p, --project <path>` | Path to `tsconfig.json` (defaults to `tsconfig.json` in current directory) |
+
+#### Examples
+
+Type check with default tsconfig.json:
+
+Bash
+
+```
+macroforge tsc
+```
+
+Type check with a specific config:
+
+Bash
+
+```
+macroforge tsc -p tsconfig.build.json
+```
+
+## Output Format
+
+### Expanded Code
+
+When expanding a file like this:
+
+TypeScript
+
+```
+/** @derive(Debug) */
+class User {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+```
+
+The CLI outputs the expanded code with the generated methods:
+
+TypeScript
+
+```
 class User {
   name: string;
   age: number;
@@ -84,38 +164,67 @@ class User {
     return `User { name: ${this.name}, age: ${this.age} }`;
   }
 }
-``` ### Diagnostics
- Errors and warnings are printed to stderr in a readable format:
- ```
-[macroforge]&nbsp;error&nbsp;at&nbsp;src/user.ts:5:1:&nbsp;Unknown&nbsp;derive&nbsp;macro:&nbsp;InvalidMacro
-[macroforge]&nbsp;warning&nbsp;at&nbsp;src/user.ts:10:3:&nbsp;Field&nbsp;'unused'&nbsp;is&nbsp;never&nbsp;used
-``` ## Use Cases
- ### CI/CD Type Checking
- Use <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">macroforge<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62"> tsc</code> in your CI pipeline to type-check with macro expansion:
- ```
-#&nbsp;package.json
-&#123;
-&nbsp;&nbsp;"scripts":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;"typecheck":&nbsp;"macroforge&nbsp;tsc"
-&nbsp;&nbsp;&#125;
-&#125;
-``` ### Debugging Macro Output
- Use <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#B392F0;--shiki-light:#6F42C1">macroforge<span style="--shiki-dark:#9ECBFF;--shiki-light:#032F62"> expand</code> to inspect what code your macros generate:
- ```
-macroforge&nbsp;expand&nbsp;src/models/user.ts&nbsp;|&nbsp;less
-``` ### Build Pipeline
- Generate expanded files as part of a custom build:
- ```
+```
+
+### Diagnostics
+
+Errors and warnings are printed to stderr in a readable format:
+
+Text
+
+```
+[macroforge] error at src/user.ts:5:1: Unknown derive macro: InvalidMacro
+[macroforge] warning at src/user.ts:10:3: Field 'unused' is never used
+```
+
+## Use Cases
+
+### CI/CD Type Checking
+
+Use `macroforge tsc` in your CI pipeline to type-check with macro expansion:
+
+JSON
+
+```
+# package.json
+{
+  "scripts": {
+    "typecheck": "macroforge tsc"
+  }
+}
+```
+
+### Debugging Macro Output
+
+Use `macroforge expand` to inspect what code your macros generate:
+
+Bash
+
+```
+macroforge expand src/models/user.ts | less
+```
+
+### Build Pipeline
+
+Generate expanded files as part of a custom build:
+
+Bash
+
+```
 #!/bin/bash
-for&nbsp;file&nbsp;in&nbsp;src/**/*.ts;&nbsp;do
-&nbsp;&nbsp;outfile="dist/$(basename&nbsp;"$file"&nbsp;.ts).js"
-&nbsp;&nbsp;macroforge&nbsp;expand&nbsp;"$file"&nbsp;--out&nbsp;"$outfile"
+for file in src/**/*.ts; do
+  outfile="dist/$(basename "$file" .ts).js"
+  macroforge expand "$file" --out "$outfile"
 done
-``` ## Built-in vs Full Mode
- By default, the CLI uses Node.js for full macro support including external macros. Use <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#F97583;--shiki-light:#D73A49">--<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">builtin<span style="--shiki-dark:#F97583;--shiki-light:#D73A49">-<span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">only</code> for faster expansion when you only need built-in macros:
- | Feature | Default (Node.js) | --builtin-only (Rust) |
-| --- | --- | --- |
-| Built-in macros | Yes | Yes |
-| External macros | Yes | No |
-| Performance | Standard | Faster |
-| Dependencies | Requires macroforge in node_modules | None |
+```
+
+## Built-in vs Full Mode
+
+By default, the CLI uses Node.js for full macro support including external macros. Use `--builtin-only` for faster expansion when you only need built-in macros:
+
+| Feature         | Default (Node.js)                      | `--builtin-only` (Rust) |
+| --------------- | -------------------------------------- | ----------------------- |
+| Built-in macros | Yes                                    | Yes                     |
+| External macros | Yes                                    | No                      |
+| Performance     | Standard                               | Faster                  |
+| Dependencies    | Requires `macroforge` in node\_modules | None                    |

package/docs/integration/configuration.md

@@ -1,73 +1,116 @@
 # Configuration
- *Macroforge can be configured with a <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">macroforge.json</code> file in your project root.*
- ## Configuration File
- Create a <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">macroforge.json</code> file:
- ```
-&#123;
-&nbsp;&nbsp;"allowNativeMacros":&nbsp;true,
-&nbsp;&nbsp;"macroPackages":&nbsp;[],
-&nbsp;&nbsp;"keepDecorators":&nbsp;false,
-&nbsp;&nbsp;"limits":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;"maxExecutionTimeMs":&nbsp;5000,
-&nbsp;&nbsp;&nbsp;&nbsp;"maxMemoryBytes":&nbsp;104857600,
-&nbsp;&nbsp;&nbsp;&nbsp;"maxOutputSize":&nbsp;10485760,
-&nbsp;&nbsp;&nbsp;&nbsp;"maxDiagnostics":&nbsp;100
-&nbsp;&nbsp;&#125;
-&#125;
-``` ## Options Reference
- ### allowNativeMacros
- | Type | boolean |
-| Default | true |
- Enable or disable native (Rust) macro packages. Set to <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#79B8FF;--shiki-light:#005CC5">false</code> to only allow built-in macros.
- ### macroPackages
- | Type | string[] |
-| Default | [] |
- List of npm packages that provide macros. Macroforge will look for macros in these packages.
- ```
-&#123;
-&nbsp;&nbsp;"macroPackages":&nbsp;[
-&nbsp;&nbsp;&nbsp;&nbsp;"@my-org/custom-macros",
-&nbsp;&nbsp;&nbsp;&nbsp;"community-macros"
-&nbsp;&nbsp;]
-&#125;
-``` ### keepDecorators
- | Type | boolean |
-| Default | false |
- Keep <code class="shiki-inline"><span class="line"><span style="--shiki-dark:#E1E4E8;--shiki-light:#24292E">@derive</code> decorators in the output. Useful for debugging.
- ### limits
- Configure resource limits for macro expansion:
- ```
-&#123;
-&nbsp;&nbsp;"limits":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;Maximum&nbsp;time&nbsp;for&nbsp;a&nbsp;single&nbsp;macro&nbsp;expansion&nbsp;(ms)
-&nbsp;&nbsp;&nbsp;&nbsp;"maxExecutionTimeMs":&nbsp;5000,
-
-&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;Maximum&nbsp;memory&nbsp;usage&nbsp;(bytes)
-&nbsp;&nbsp;&nbsp;&nbsp;"maxMemoryBytes":&nbsp;104857600,&nbsp;&nbsp;//&nbsp;100MB
-
-&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;Maximum&nbsp;size&nbsp;of&nbsp;generated&nbsp;code&nbsp;(bytes)
-&nbsp;&nbsp;&nbsp;&nbsp;"maxOutputSize":&nbsp;10485760,&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;10MB
-
-&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;Maximum&nbsp;number&nbsp;of&nbsp;diagnostics&nbsp;per&nbsp;file
-&nbsp;&nbsp;&nbsp;&nbsp;"maxDiagnostics":&nbsp;100
-&nbsp;&nbsp;&#125;
-&#125;
-``` ## Macro Runtime Overrides
- Override settings for specific macros:
- ```
-&#123;
-&nbsp;&nbsp;"macroRuntimeOverrides":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;"@my-org/macros":&nbsp;&#123;
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"maxExecutionTimeMs":&nbsp;10000
-&nbsp;&nbsp;&nbsp;&nbsp;&#125;
-&nbsp;&nbsp;&#125;
-&#125;
-```  **Warning Be careful when increasing limits, as this could allow malicious macros to consume excessive resources. ## Environment Variables
- Some settings can be overridden with environment variables:
- | Variable | Description |
-| --- | --- |
-| MACROFORGE_DEBUG | Enable debug logging |
-| MACROFORGE_LOG_FILE | Write logs to a file |
- ```
-MACROFORGE_DEBUG=1&nbsp;npm&nbsp;run&nbsp;dev
-```**
+
+Macroforge can be configured with a `macroforge.json` file in your project root.
+
+## Configuration File
+
+Create a `macroforge.json` file:
+
+macroforge.json 
+
+```
+{
+  "allowNativeMacros": true,
+  "macroPackages": [],
+  "keepDecorators": false,
+  "limits": {
+    "maxExecutionTimeMs": 5000,
+    "maxMemoryBytes": 104857600,
+    "maxOutputSize": 10485760,
+    "maxDiagnostics": 100
+  }
+}
+```
+
+## Options Reference
+
+### allowNativeMacros
+
+| Type    | `boolean` |
+| Default | `true`    |
+
+Enable or disable native (Rust) macro packages. Set to `false` to only allow built-in macros.
+
+### macroPackages
+
+| Type    | `string[]` |
+| Default | `[]`       |
+
+List of npm packages that provide macros. Macroforge will look for macros in these packages.
+
+JSON
+
+```
+{
+  "macroPackages": [
+    "@my-org/custom-macros",
+    "community-macros"
+  ]
+}
+```
+
+### keepDecorators
+
+| Type    | `boolean` |
+| Default | `false`   |
+
+Keep `@derive` decorators in the output. Useful for debugging.
+
+### limits
+
+Configure resource limits for macro expansion:
+
+JSON
+
+```
+{
+  "limits": {
+    // Maximum time for a single macro expansion (ms)
+    "maxExecutionTimeMs": 5000,
+
+    // Maximum memory usage (bytes)
+    "maxMemoryBytes": 104857600,  // 100MB
+
+    // Maximum size of generated code (bytes)
+    "maxOutputSize": 10485760,    // 10MB
+
+    // Maximum number of diagnostics per file
+    "maxDiagnostics": 100
+  }
+}
+```
+
+## Macro Runtime Overrides
+
+Override settings for specific macros:
+
+JSON
+
+```
+{
+  "macroRuntimeOverrides": {
+    "@my-org/macros": {
+      "maxExecutionTimeMs": 10000
+    }
+  }
+}
+```
+
+Warning
+
+Be careful when increasing limits, as this could allow malicious macros to consume excessive resources.
+
+## Environment Variables
+
+Some settings can be overridden with environment variables:
+
+| Variable              | Description          |
+| --------------------- | -------------------- |
+| `MACROFORGE_DEBUG`    | Enable debug logging |
+| `MACROFORGE_LOG_FILE` | Write logs to a file |
+
+Bash
+
+```
+MACROFORGE_DEBUG=1 npm run dev
+```

package/docs/integration/integration-overview.md

@@ -1,19 +1,56 @@
 # Integration
- *Macroforge integrates with your development workflow through IDE plugins and build tool integration.*
- ## Overview
- | Integration | Purpose | Package |
-| --- | --- | --- |
-| TypeScript Plugin | IDE support (errors, completions) | @macroforge/typescript-plugin |
-| Vite Plugin | Build-time macro expansion | @macroforge/vite-plugin |
- ## Recommended Setup
- For the best development experience, use both integrations:
- 1. **TypeScript Plugin**: Provides real-time feedback in your IDE
- 2. **Vite Plugin**: Expands macros during development and production builds
- ```
-# Install both plugins
-npm install -D @macroforge/typescript-plugin @macroforge/vite-plugin
-``` ## How They Work Together
- <div class="flex justify-center"><div class="border-2 border-primary bg-primary/10 rounded-lg px-6 py-3 text-center"><div class="font-semibold text-primary">Your Code TypeScript with @derive decorators  <div class="absolute top-0 h-px bg-border" style="width: 50%; left: 25%;"> <div class="flex flex-col items-center">  <div class="border border-border bg-card rounded-lg px-4 py-3 text-center w-full mt-1"><div class="font-medium text-foreground">TypeScript Plugin Language service integration   <div class="border border-success/30 bg-success/10 rounded-md px-3 py-2 text-center"><div class="text-sm font-medium text-success-foreground">IDE Feedback Errors & completions  <div class="border border-border bg-card rounded-lg px-4 py-3 text-center w-full mt-1"><div class="font-medium text-foreground">Vite Plugin Build-time transformation   <div class="border border-success/30 bg-success/10 rounded-md px-3 py-2 text-center"><div class="text-sm font-medium text-success-foreground">Dev Server Hot reload<div class="text-sm font-medium text-success-foreground">Production Build Optimized output ## Detailed Guides
- - [TypeScript Plugin setup](../docs/integration/typescript-plugin)
- - [Vite Plugin configuration](../docs/integration/vite-plugin)
- - [Configuration options](../docs/integration/configuration)
+
+Macroforge integrates with your development workflow through IDE plugins and build tool integration.
+
+## Overview
+
+| Integration       | Purpose                           | Package                         |
+| ----------------- | --------------------------------- | ------------------------------- |
+| TypeScript Plugin | IDE support (errors, completions) | `@macroforge/typescript-plugin` |
+| Vite Plugin       | Build-time macro expansion        | `@macroforge/vite-plugin`       |
+
+## Recommended Setup
+
+For the best development experience, use both integrations:
+
+1.  **TypeScript Plugin**: Provides real-time feedback in your IDE
+2.  **Vite Plugin**: Expands macros during development and production builds
+
+Bash
+
+```
+# Install both plugins
+npm install -D @macroforge/typescript-plugin @macroforge/vite-plugin
+```
+
+## How They Work Together
+
+Your Code
+
+TypeScript with @derive decorators
+
+TypeScript Plugin
+
+Language service integration
+
+IDE Feedback
+
+Errors & completions
+
+Vite Plugin
+
+Build-time transformation
+
+Dev Server
+
+Hot reload
+
+Production Build
+
+Optimized output
+
+## Detailed Guides
+
+*   [TypeScript Plugin setup](../docs/integration/typescript-plugin)
+*   [Vite Plugin configuration](../docs/integration/vite-plugin)
+*   [Configuration options](../docs/integration/configuration)