@macroforge/mcp-server 0.1.40 → 0.1.49

package/docs/integration/svelte-preprocessor.md

@@ -1,128 +1,185 @@
 # Svelte Preprocessor
- *The Svelte preprocessor expands Macroforge macros in `<script>` blocks before Svelte compilation, enabling seamless macro usage in Svelte components.*
- ## Installation
- ```
-npm install -D @macroforge/svelte-preprocessor
-``` ## Configuration
- Add the preprocessor to your `svelte.config.js`:
- ```
-import adapter from '@sveltejs/adapter-auto';
-import &#123; vitePreprocess &#125; from '@sveltejs/vite-plugin-svelte';
-import &#123; macroforgePreprocess &#125; from '@macroforge/svelte-preprocessor';
-
-/** @type &#123;import('@sveltejs/kit').Config&#125; */
-const config = &#123;
-  preprocess: [
-    macroforgePreprocess(),  // Expand macros FIRST
-    vitePreprocess()          // Then handle TypeScript/CSS
-  ],
-
-  kit: &#123;
-    adapter: adapter()
-  &#125;
-&#125;;
-
-export default config;
-```  **Warning Always place `macroforgePreprocess()` **before** other preprocessors like `vitePreprocess()`. This ensures macros are expanded before TypeScript compilation. ## Usage
- Use `@derive` decorators directly in your Svelte component scripts:
- ```
-&#x3C;script lang="ts">
-  /** @derive(Debug, Clone) */
-  class User &#123;
-    name: string;
-    email: string;
-
-    constructor(name: string, email: string) &#123;
-      this.name = name;
-      this.email = email;
-    &#125;
-  &#125;
-
-  let user = new User("Alice", "alice@example.com");
-  console.log(user.toString());  // Generated by Debug macro
-&#x3C;/script>
-
-&#x3C;p>User: &#123;user.name&#125;&#x3C;/p>
-``` ## Options
- ```
-macroforgePreprocess(&#123;
-  // Keep @derive decorators in output (for debugging)
-  keepDecorators: false,
-
-  // Process JavaScript files (not just TypeScript)
-  processJavaScript: false
-&#125;)
-``` ### Option Reference
- | Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `keepDecorators` | `boolean` | `false` | Keep decorators in output |
+
+The Svelte preprocessor expands Macroforge macros in `<script>` blocks before Svelte compilation, enabling seamless macro usage in Svelte components.
+
+## Installation
+
+Bash
+
+```
+npm install -D @macroforge/svelte-preprocessor
+```
+
+## Configuration
+
+Add the preprocessor to your `svelte.config.js`:
+
+svelte.config.js 
+
+```
+import adapter from '@sveltejs/adapter-auto';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+  preprocess: [
+    macroforgePreprocess(),  // Expand macros FIRST
+    vitePreprocess()          // Then handle TypeScript/CSS
+  ],
+
+  kit: {
+    adapter: adapter()
+  }
+};
+
+export default config;
+```
+
+Warning
+
+Always place `macroforgePreprocess()` **before** other preprocessors like `vitePreprocess()`. This ensures macros are expanded before TypeScript compilation.
+
+## Usage
+
+Use `@derive` decorators directly in your Svelte component scripts:
+
+UserCard.svelte 
+
+```
+<script lang="ts">
+  /** @derive(Debug, Clone) */
+  class User {
+    name: string;
+    email: string;
+
+    constructor(name: string, email: string) {
+      this.name = name;
+      this.email = email;
+    }
+  }
+
+  let user = new User("Alice", "alice@example.com");
+  console.log(user.toString());  // Generated by Debug macro
+</script>
+
+<p>User: {user.name}</p>
+```
+
+## Options
+
+TypeScript
+
+```
+macroforgePreprocess({
+  // Keep @derive decorators in output (for debugging)
+  keepDecorators: false,
+
+  // Process JavaScript files (not just TypeScript)
+  processJavaScript: false
+})
+```
+
+### Option Reference
+
+| Option              | Type      | Default | Description                                   |
+| ------------------- | --------- | ------- | --------------------------------------------- |
+| `keepDecorators`    | `boolean` | `false` | Keep decorators in output                     |
 | `processJavaScript` | `boolean` | `false` | Process `<script>` blocks without `lang="ts"` |
- ## How It Works
- The preprocessor:
- 1. Intercepts `<script lang="ts">` blocks in `.svelte` files
- 2. Checks for `@derive` decorators (skips files without them)
- 3. Expands macros using the native Macroforge binary
- 4. Returns the transformed code for Svelte compilation
-  ****Tip Files without `@derive` decorators are passed through unchanged with zero overhead. ## SvelteKit Integration
- For SvelteKit projects, you can use both the preprocessor (for `.svelte` files) and the Vite plugin (for standalone `.ts` files):
- ```
-// svelte.config.js
-import &#123; macroforgePreprocess &#125; from '@macroforge/svelte-preprocessor';
-import &#123; vitePreprocess &#125; from '@sveltejs/vite-plugin-svelte';
-
-export default &#123;
-  preprocess: [
-    macroforgePreprocess(),
-    vitePreprocess()
-  ]
-&#125;;
-``` ```
-// vite.config.ts
-import macroforge from '@macroforge/vite-plugin';
-import &#123; sveltekit &#125; from '@sveltejs/kit/vite';
-import &#123; defineConfig &#125; from 'vite';
-
-export default defineConfig(&#123;
-  plugins: [
-    macroforge(),  // For .ts files
-    sveltekit()
-  ]
-&#125;);
-``` ## Using with Vitest
- The preprocessor works seamlessly with Vitest for testing Svelte components:
- ```
-// vitest.config.ts
-import &#123; defineConfig &#125; from 'vitest/config';
-import &#123; sveltekit &#125; from '@sveltejs/kit/vite';
-import &#123; svelteTesting &#125; from '@testing-library/svelte/vite';
-import macroforge from '@macroforge/vite-plugin';
-
-export default defineConfig(&#123;
-  plugins: [
-    macroforge(),
-    sveltekit(),
-    svelteTesting()
-  ],
-  test: &#123;
-    environment: 'jsdom',
-    include: ['src/**/*.&#123;test,spec&#125;.&#123;js,ts&#125;']
-  &#125;
-&#125;);
-``` ## Svelte 5 Runes Compatibility
- The preprocessor is fully compatible with Svelte 5 runes (`$state`, `$derived`, `$props`, etc.). Files using runes but without `@derive` decorators are skipped entirely.
- ```
-&#x3C;script lang="ts">
-  // Runes work normally
-  let count = $state(0);
-  let doubled = $derived(count * 2);
-
-  // Macros expand correctly
-  /** @derive(Debug) */
-  class Counter &#123;
-    value: number;
-    constructor(value: number) &#123;
-      this.value = value;
-    &#125;
-  &#125;
-&#x3C;/script>
-```**
+
+## How It Works
+
+The preprocessor:
+
+1.  Intercepts `<script lang="ts">` blocks in `.svelte` files
+2.  Checks for `@derive` decorators (skips files without them)
+3.  Expands macros using the native Macroforge binary
+4.  Returns the transformed code for Svelte compilation
+
+Tip
+
+Files without `@derive` decorators are passed through unchanged with zero overhead.
+
+## SvelteKit Integration
+
+For SvelteKit projects, you can use both the preprocessor (for `.svelte` files) and the Vite plugin (for standalone `.ts` files):
+
+svelte.config.js 
+
+```
+// svelte.config.js
+import { macroforgePreprocess } from '@macroforge/svelte-preprocessor';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+export default {
+  preprocess: [
+    macroforgePreprocess(),
+    vitePreprocess()
+  ]
+};
+```
+
+vite.config.ts 
+
+```
+// vite.config.ts
+import macroforge from '@macroforge/vite-plugin';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    macroforge(),  // For .ts files
+    sveltekit()
+  ]
+});
+```
+
+## Using with Vitest
+
+The preprocessor works seamlessly with Vitest for testing Svelte components:
+
+vitest.config.ts 
+
+```
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { svelteTesting } from '@testing-library/svelte/vite';
+import macroforge from '@macroforge/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    macroforge(),
+    sveltekit(),
+    svelteTesting()
+  ],
+  test: {
+    environment: 'jsdom',
+    include: ['src/**/*.{test,spec}.{js,ts}']
+  }
+});
+```
+
+## Svelte 5 Runes Compatibility
+
+The preprocessor is fully compatible with Svelte 5 runes (`$state`, `$derived`, `$props`, etc.). Files using runes but without `@derive` decorators are skipped entirely.
+
+Svelte
+
+```
+<script lang="ts">
+  // Runes work normally
+  let count = $state(0);
+  let doubled = $derived(count * 2);
+
+  // Macros expand correctly
+  /** @derive(Debug) */
+  class Counter {
+    value: number;
+    constructor(value: number) {
+      this.value = value;
+    }
+  }
+</script>
+```

package/docs/integration/typescript-plugin.md

@@ -1,55 +1,102 @@
 # TypeScript Plugin
- *The TypeScript plugin provides IDE integration for Macroforge, including error reporting, completions, and type checking for generated code.*
- ## Installation
- ```
-npm install -D @macroforge/typescript-plugin
-``` ## Configuration
- Add the plugin to your `tsconfig.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"
-  **Tip Add this setting to your `.vscode/settings.json` to make it permanent: ```
-{
-  "typescript.tsdk": "node_modules/typescript/lib"
-}
-``` ## Features
- ### Error Reporting
- Errors in macro-generated code are reported at the `@derive` decorator position:
- ```
-/** @derive(Debug) */  // <- Errors appear here
-class User {
-  name: string;
-}
-``` ### Completions
- The plugin provides completions for generated methods:
- ```
-const user = new User("Alice");
-user.to  // Suggests: toString(), toJSON(), etc.
-``` ### Type Information
- Hover over generated methods to see their types:
- ```
-// 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)
-**
+
+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 
+
+```
+{
+  "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"
+
+Tip
+
+Add this setting to your `.vscode/settings.json` to make it permanent:
+
+.vscode/settings.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)

package/docs/integration/vite-plugin.md

@@ -1,77 +1,117 @@
 # Vite Plugin
- *The Vite plugin provides build-time macro expansion, transforming your code during development and production builds.*
- ## Installation
- ```
-npm install -D @macroforge/vite-plugin
-``` ## Configuration
- Add the plugin to your `vite.config.ts`:
- ```
-import macroforge from "@macroforge/vite-plugin";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  plugins: [
-    macroforge()
-  ]
-});
-``` ## Options
- ```
-macroforge({
-  // Generate .d.ts files for expanded code
-  generateTypes: true,
-
-  // Output directory for generated types
-  typesOutputDir: ".macroforge/types",
-
-  // Emit metadata files for debugging
-  emitMetadata: false,
-
-  // Keep @derive decorators in output (for debugging)
-  keepDecorators: false,
-
-  // File patterns to process
-  include: ["**/*.ts", "**/*.tsx"],
-  exclude: ["node_modules/**"]
-})
-``` ### Option Reference
- | Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `generateTypes` | `boolean` | `true` | Generate .d.ts files |
-| `typesOutputDir` | `string` | `.macroforge/types` | Where to write type files |
-| `emitMetadata` | `boolean` | `false` | Emit macro metadata files |
-| `keepDecorators` | `boolean` | `false` | Keep decorators in output |
- ## Framework Integration
- ### React (Vite)
- ```
-import macroforge from "@macroforge/vite-plugin";
-import react from "@vitejs/plugin-react";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  plugins: [
-    macroforge(),  // Before React plugin
-    react()
-  ]
-});
-``` ### SvelteKit
- ```
-import macroforge from "@macroforge/vite-plugin";
-import { sveltekit } from "@sveltejs/kit/vite";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  plugins: [
-    macroforge(),  // Before SvelteKit
-    sveltekit()
-  ]
-});
-``` > **Note:** Always place the Macroforge plugin before other framework plugins to ensure macros are expanded first. ## Development Server
- During development, the plugin:
- - Watches for file changes
- - Expands macros on save
- - Provides HMR support for expanded code
- ## Production Build
- During production builds, the plugin:
- - Expands all macros in the source files
- - Generates type declaration files
- - Strips `@derive` decorators from output
+
+The Vite plugin provides build-time macro expansion, transforming your code during development and production builds.
+
+## Installation
+
+Bash
+
+```
+npm install -D @macroforge/vite-plugin
+```
+
+## Configuration
+
+Add the plugin to your `vite.config.ts`:
+
+vite.config.ts 
+
+```
+import macroforge from "@macroforge/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    macroforge()
+  ]
+});
+```
+
+## Options
+
+TypeScript
+
+```
+macroforge({
+  // Generate .d.ts files for expanded code
+  generateTypes: true,
+
+  // Output directory for generated types
+  typesOutputDir: ".macroforge/types",
+
+  // Emit metadata files for debugging
+  emitMetadata: false,
+
+  // Keep @derive decorators in output (for debugging)
+  keepDecorators: false,
+
+  // File patterns to process
+  include: ["**/*.ts", "**/*.tsx"],
+  exclude: ["node_modules/**"]
+})
+```
+
+### Option Reference
+
+| Option           | Type      | Default             | Description               |
+| ---------------- | --------- | ------------------- | ------------------------- |
+| `generateTypes`  | `boolean` | `true`              | Generate .d.ts files      |
+| `typesOutputDir` | `string`  | `.macroforge/types` | Where to write type files |
+| `emitMetadata`   | `boolean` | `false`             | Emit macro metadata files |
+| `keepDecorators` | `boolean` | `false`             | Keep decorators in output |
+
+## Framework Integration
+
+### React (Vite)
+
+vite.config.ts 
+
+```
+import macroforge from "@macroforge/vite-plugin";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    macroforge(),  // Before React plugin
+    react()
+  ]
+});
+```
+
+### SvelteKit
+
+vite.config.ts 
+
+```
+import macroforge from "@macroforge/vite-plugin";
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    macroforge(),  // Before SvelteKit
+    sveltekit()
+  ]
+});
+```
+
+Note
+
+Always place the Macroforge plugin before other framework plugins to ensure macros are expanded first.
+
+## Development Server
+
+During development, the plugin:
+
+*   Watches for file changes
+*   Expands macros on save
+*   Provides HMR support for expanded code
+
+## Production Build
+
+During production builds, the plugin:
+
+*   Expands all macros in the source files
+*   Generates type declaration files
+*   Strips `@derive` decorators from output