@macroforge/mcp-server 0.1.40 → 0.1.49

package/docs/getting-started/first-macro.md

@@ -1,8 +1,13 @@
 # Your First Macro
- *Let's create a class that uses Macroforge's derive macros to automatically generate useful methods.*
- ## Creating a Class with Derive Macros
- Start by creating a simple `User` class. We'll use the `@derive` decorator to automatically generate methods.
- **Before:**
+
+Let's create a class that uses Macroforge's derive macros to automatically generate useful methods.
+
+## Creating a Class with Derive Macros
+
+Start by creating a simple `User` class. We'll use the `@derive` decorator to automatically generate methods.
+
+Before (Your Code)
+
 ```
 /** @derive(Debug, Clone, PartialEq) */
 export class User {
@@ -16,8 +21,10 @@ export class User {
         this.email = email;
     }
 }
-```  
-**After:**
+```
+
+After (Generated)
+
 ```
 export class User {
     name: string;
@@ -63,26 +70,36 @@ export function userEquals(a: User, b: User): boolean {
     if (a === b) return true;
     return a.name === b.name && a.age === b.age && a.email === b.email;
 }
-``` ## Using the Generated Methods
- ```
-const user = new User("Alice", 30, "alice@example.com");
+```
+
+## Using the Generated Methods
 
-// Debug: toString()
+TypeScript
+
+```
+const user = new User("Alice", 30, "alice@example.com");
+
+// Debug: toString()
 console.log(user.toString());
-// Output: User { name: Alice, age: 30, email: alice@example.com }
+// Output: User { name: Alice, age: 30, email: alice@example.com }
+
+// Clone: clone()
+const copy = user.clone();
+console.log(copy.name); // "Alice"
+
+// Eq: equals()
+console.log(user.equals(copy)); // true
 
-// Clone: clone()
-const copy = user.clone();
-console.log(copy.name); // "Alice"
+const different = new User("Bob", 25, "bob@example.com");
+console.log(user.equals(different)); // false
+```
+
+## Customizing Behavior
 
-// Eq: equals()
-console.log(user.equals(copy)); // true
+You can customize how macros work using field-level decorators. For example, with the Debug macro:
+
+Before (Your Code)
 
-const different = new User("Bob", 25, "bob@example.com");
-console.log(user.equals(different)); // false
-``` ## Customizing Behavior
- You can customize how macros work using field-level decorators. For example, with the Debug macro:
- **Before:**
 ```
 /** @derive(Debug) */
 export class User {
@@ -100,8 +117,10 @@ export class User {
         this.password = password;
     }
 }
-```  
-**After:**
+```
+
+After (Generated)
+
 ```
 export class User {
     id: number;
@@ -127,13 +146,23 @@ export function userToString(value: User): string {
     parts.push('name: ' + value.name);
     return 'User { ' + parts.join(', ') + ' }';
 }
-``` ```
-const user = new User(42, "Alice", "secret123");
+```
+
+TypeScript
+
+```
+const user = new User(42, "Alice", "secret123");
 console.log(user.toString());
-// Output: User { userId: 42, name: Alice }
-// Note: 'id' is renamed to 'userId', 'password' is skipped
-```  **Field-level decorators Field-level decorators let you control exactly how each field is handled by the macro. ## Next Steps
- - [Learn how macros work under the hood](../../docs/concepts)
- - [Explore all Debug options](../../docs/builtin-macros/debug)
- - [Create your own custom macros](../../docs/custom-macros)
-**
+// Output: User { userId: 42, name: Alice }
+// Note: 'id' is renamed to 'userId', 'password' is skipped
+```
+
+Field-level decorators
+
+Field-level decorators let you control exactly how each field is handled by the macro.
+
+## Next Steps
+
+*   [Learn how macros work under the hood](../../docs/concepts)
+*   [Explore all Debug options](../../docs/builtin-macros/debug)
+*   [Create your own custom macros](../../docs/custom-macros)

package/docs/getting-started/installation.md

@@ -1,67 +1,110 @@
 # Installation
- *Get started with Macroforge in just a few minutes. Install the package and configure your project to start using TypeScript macros.*
- ## Requirements
- - Node.js 24.0 or later
- - TypeScript 5.9 or later
- ## Install the Package
- Install Macroforge using your preferred package manager:
- ```
-npm install macroforge
-``` ```
-bun add macroforge
-``` ```
-pnpm add macroforge
-```  **Info Macroforge includes pre-built native binaries for macOS (x64, arm64), Linux (x64, arm64), and Windows (x64, arm64). ## Basic Usage
- The simplest way to use Macroforge is with the built-in derive macros. Add a `@derive` comment decorator to your class:
- ```
-/** @derive(Debug, Clone, PartialEq) */
-class User {
-  name: string;
-  age: number;
-
-  constructor(name: string, age: number) {
-    this.name = name;
-    this.age = age;
-  }
-}
-
-// After macro expansion, User has:
-// - toString(): string              (from Debug)
-// - clone(): User                   (from Clone)
-// - equals(other: unknown): boolean (from PartialEq)
-``` ## IDE Integration
- For the best development experience, add the TypeScript plugin to your `tsconfig.json`:
- ```
-{
-  "compilerOptions": {
-    "plugins": [
-      {
-        "name": "@macroforge/typescript-plugin"
-      }
-    ]
-  }
-}
-``` This enables features like:
- - Accurate error positions in your source code
- - Autocompletion for generated methods
- - Type checking for expanded code
- ## Build Integration (Vite)
- If you're using Vite, add the plugin to your config for automatic macro expansion during build:
- ```
-import macroforge from "@macroforge/vite-plugin";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  plugins: [
-    macroforge({
-      generateTypes: true,
-      typesOutputDir: ".macroforge/types"
-    })
-  ]
-});
-``` ## Next Steps
- Now that you have Macroforge installed, learn how to use it:
- - [Create your first macro](../docs/getting-started/first-macro)
- - [Understand how macros work](../docs/concepts)
- - [Explore built-in macros](../docs/builtin-macros)
-**
+
+Get started with Macroforge in just a few minutes. Install the package and configure your project to start using TypeScript macros.
+
+## Requirements
+
+*   Node.js 24.0 or later
+*   TypeScript 5.9 or later
+
+## Install the Package
+
+Install Macroforge using your preferred package manager:
+
+npm 
+
+```
+npm install macroforge
+```
+
+bun 
+
+```
+bun add macroforge
+```
+
+pnpm 
+
+```
+pnpm add macroforge
+```
+
+Info
+
+Macroforge includes pre-built native binaries for macOS (x64, arm64), Linux (x64, arm64), and Windows (x64, arm64).
+
+## Basic Usage
+
+The simplest way to use Macroforge is with the built-in derive macros. Add a `@derive` comment decorator to your class:
+
+user.ts 
+
+```
+/** @derive(Debug, Clone, PartialEq) */
+class User {
+  name: string;
+  age: number;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+}
+
+// After macro expansion, User has:
+// - toString(): string              (from Debug)
+// - clone(): User                   (from Clone)
+// - equals(other: unknown): boolean (from PartialEq)
+```
+
+## IDE Integration
+
+For the best development experience, add the TypeScript plugin to your `tsconfig.json`:
+
+tsconfig.json 
+
+```
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@macroforge/typescript-plugin"
+      }
+    ]
+  }
+}
+```
+
+This enables features like:
+
+*   Accurate error positions in your source code
+*   Autocompletion for generated methods
+*   Type checking for expanded code
+
+## Build Integration (Vite)
+
+If you're using Vite, add the plugin to your config for automatic macro expansion during build:
+
+vite.config.ts 
+
+```
+import macroforge from "@macroforge/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    macroforge({
+      generateTypes: true,
+      typesOutputDir: ".macroforge/types"
+    })
+  ]
+});
+```
+
+## Next Steps
+
+Now that you have Macroforge installed, learn how to use it:
+
+*   [Create your first macro](../docs/getting-started/first-macro)
+*   [Understand how macros work](../docs/concepts)
+*   [Explore built-in macros](../docs/builtin-macros)

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 |
-| --- | --- |
+
+macroforge v0.1.43
+
+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:
- ```
-macroforge expand src/user.ts
-``` Expand and write to a file:
- ```
-macroforge expand src/user.ts --out dist/user.js
-``` Expand with both runtime output and type declarations:
- ```
-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):
- ```
-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.
- ```
-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:
- ```
-macroforge tsc
-``` Type check with a specific config:
- ```
-macroforge tsc -p tsconfig.build.json
-``` ## Output Format
- ### Expanded Code
- When expanding a file like this:
- ```
-/** @derive(Debug) */
-class User &#123;
-  name: string;
-  age: number;
 
-  constructor(name: string, age: number) &#123;
-    this.name = name;
-    this.age = age;
-  &#125;
-&#125;
-``` The CLI outputs the expanded code with the generated methods:
- ```
+#### 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] 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:
- ```
-# package.json
-&#123;
-  "scripts": &#123;
-    "typecheck": "macroforge tsc"
-  &#125;
-&#125;
-``` ### Debugging Macro Output
- Use `macroforge expand` to inspect what code your macros generate:
- ```
-macroforge expand src/models/user.ts | 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 file in src/**/*.ts; do
-  outfile="dist/$(basename "$file" .ts).js"
-  macroforge expand "$file" --out "$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 `--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 |
+```
+
+## 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                    |