@macroforge/mcp-server 0.1.17

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

@@ -0,0 +1,120 @@
+# 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.
+
+`user.ts`
+```typescript
+import { Debug, Clone, Eq } from "macroforge";
+
+/** @derive(Debug, Clone, Eq) */
+export class User {
+  name: string;
+  age: number;
+  email: string;
+
+  constructor(name: string, age: number, email: string) {
+    this.name = name;
+    this.age = age;
+    this.email = email;
+  }
+}
+```
+
+## What Gets Generated
+
+After macro expansion, your class will have these methods:
+
+`user.ts (expanded)`
+```typescript
+export class User {
+  name: string;
+  age: number;
+  email: string;
+
+  constructor(name: string, age: number, email: string) {
+    this.name = name;
+    this.age = age;
+    this.email = email;
+  }
+
+  // Generated by Debug
+  toString(): string {
+    return \`User { name: \${this.name}, age: \${this.age}, email: \${this.email} }\`;
+  }
+
+  // Generated by Clone
+  clone(): User {
+    return new User(this.name, this.age, this.email);
+  }
+
+  // Generated by Eq
+  equals(other: User): boolean {
+    return this.name === other.name
+      && this.age === other.age
+      && this.email === other.email;
+  }
+}
+```
+
+## Using the Generated Methods
+
+```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 }
+
+// Clone: clone()
+const copy = user.clone();
+console.log(copy.name); // "Alice"
+
+// Eq: equals()
+console.log(user.equals(copy)); // true
+
+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:
+
+```typescript
+/** @derive(Debug) */
+export class User {
+  /** @debug({ rename: "userId" }) */
+  id: number;
+
+  name: string;
+
+  /** @debug({ skip: true }) */
+  password: string;
+
+  constructor(id: number, name: string, password: string) {
+    this.id = id;
+    this.name = name;
+    this.password = password;
+  }
+}
+
+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 let you control exactly how each field is handled by the macro.
+
+## Next Steps
+
+- [Learn how macros work under the hood]({base}/docs/concepts)
+
+- [Explore all Debug options]({base}/docs/builtin-macros/debug)
+
+- [Create your own custom macros]({base}/docs/custom-macros)

package/docs/getting-started/installation.md

@@ -0,0 +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 18.0 or later
+
+- TypeScript 5.0 or later
+
+## Install the Package
+
+Install Macroforge using your preferred package manager:
+
+`npm`
+```bash
+npm install macroforge
+```
+
+`bun`
+```bash
+bun add macroforge
+```
+
+`pnpm`
+```bash
+pnpm add macroforge
+```
+
+> **Note:**
+> 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`
+```typescript
+import { Debug, Clone, Eq } from "macroforge";
+
+/** @derive(Debug, Clone, Eq) */
+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: User): boolean  (from Eq)
+```
+
+## IDE Integration
+
+For the best development experience, add the TypeScript plugin to your `tsconfig.json`:
+
+`tsconfig.json`
+```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`
+```typescript
+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]({base}/docs/getting-started/first-macro)
+
+- [Understand how macros work]({base}/docs/concepts)
+
+- [Explore built-in macros]({base}/docs/builtin-macros)

package/docs/integration/cli.md

@@ -0,0 +1,207 @@
+# Command Line Interface
+
+*The `macroforge` CLI provides commands for expanding macros and running type checks with macro support.*
+
+## 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
+
+| `<input>` 
+| Path to the TypeScript or TSX file to expand
+
+#### Options
+
+| `--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
+```
+
+>
+> 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
+
+| `-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;
+
+  constructor(name: string, age: number) {
+    this.name = name;
+    this.age = age;
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return \`User { name: \${this.name}, age: \${this.age} }\`;
+  }
+}
+```
+
+### 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"
+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:
+
+| Built-in macros 
+| Yes 
+| Yes 
+
+| External macros 
+| Yes 
+| No 
+
+| Performance 
+| Standard 
+| Faster 
+
+| Dependencies 
+| Requires `macroforge` in node_modules 
+| None

package/docs/integration/configuration.md

@@ -0,0 +1,116 @@
+# Configuration
+
+*Macroforge can be configured with a `macroforge.json` file in your project root.*
+
+## Configuration File
+
+Create a `macroforge.json` file:
+
+`macroforge.json`
+```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:
+
+| `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

@@ -0,0 +1,51 @@
+# Integration
+
+*Macroforge integrates with your development workflow through IDE plugins and build tool integration.*
+
+## Overview
+
+| 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
+
+```text
+┌────────────────────────────────────────────────────────┐
+│                   Development Flow                      │
+├────────────────────────────────────────────────────────┤
+│                                                         │
+│  Your Code ──► TypeScript Plugin ──► IDE Feedback       │
+│      │                                                  │
+│      │                                                  │
+│      └──────► Vite Plugin ────────► Dev Server          │
+│                     │                                   │
+│                     └─────────────► Production Build    │
+│                                                         │
+└────────────────────────────────────────────────────────┘
+```
+
+## Detailed Guides
+
+- [TypeScript Plugin setup]({base}/docs/integration/typescript-plugin)
+
+- [Vite Plugin configuration]({base}/docs/integration/vite-plugin)
+
+- [Configuration options]({base}/docs/integration/configuration)

package/docs/integration/typescript-plugin.md

@@ -0,0 +1,96 @@
+# TypeScript Plugin
+
+*The TypeScript plugin provides IDE integration for Macroforge, including error reporting, completions, and type checking for generated code.*
+
+## Installation
+
+```bash
+npm install -D @macroforge/typescript-plugin
+```
+
+## Configuration
+
+Add the plugin to your `tsconfig.json`:
+
+`tsconfig.json`
+```json
+{
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@macroforge/typescript-plugin"
+      }
+    ]
+  }
+}
+```
+
+## VS Code Setup
+
+VS Code uses its own TypeScript version by default. To use the workspace version (which includes plugins):
+
+1. Open the Command Palette (`Cmd/Ctrl + Shift + P`)
+
+2. Search for "TypeScript: Select TypeScript Version"
+
+3. Choose "Use Workspace Version"
+
+>
+> Add this setting to your `.vscode/settings.json` to make it permanent:
+
+`.vscode/settings.json`
+```json
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}
+```
+
+## Features
+
+### Error Reporting
+
+Errors in macro-generated code are reported at the `@derive` decorator position:
+
+```typescript
+/** @derive(Debug) */  // <- Errors appear here
+class User {
+  name: string;
+}
+```
+
+### Completions
+
+The plugin provides completions for generated methods:
+
+```typescript
+const user = new User("Alice");
+user.to  // Suggests: toString(), toJSON(), etc.
+```
+
+### Type Information
+
+Hover over generated methods to see their types:
+
+```typescript
+// Hover over 'clone' shows:
+// (method) User.clone(): User
+const copy = user.clone();
+```
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+1. Ensure you're using the workspace TypeScript version
+
+2. Restart the TypeScript server (Command Palette → "TypeScript: Restart TS Server")
+
+3. Check that the plugin is listed in `tsconfig.json`
+
+### Errors Not Showing
+
+If errors from macros aren't appearing:
+
+1. Make sure the Vite plugin is also installed (for source file watching)
+
+2. Check that your file is saved (plugins process on save)