@macroforge/mcp-server 0.1.36 → 0.1.38

package/docs/builtin-macros/clone.md

@@ -8,18 +8,11 @@ independent copies of values.
 
 | Type | Generated Code | Description |
 |------|----------------|-------------|
-| Class | `clone(): ClassName` | Instance method creating a new instance with copied fields |
-| Enum | `cloneEnumName(value: EnumName): EnumName` | Standalone function (enums are primitives, returns value as-is) |
-| Interface | `cloneInterfaceName(value: InterfaceName): InterfaceName` | Standalone function creating a new object literal |
-| Type Alias | `cloneTypeName(value: TypeName): TypeName` | Standalone function with spread copy for objects |
+| Class | `classNameClone(value)` + `static clone(value)` | Standalone function + static wrapper method |
+| Enum | `enumNameClone(value: EnumName): EnumName` | Standalone function (enums are primitives, returns value as-is) |
+| Interface | `interfaceNameClone(value: InterfaceName): InterfaceName` | Standalone function creating a new object literal |
+| Type Alias | `typeNameClone(value: TypeName): TypeName` | Standalone function with spread copy for objects |
 
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"suffix"` (default): Suffixes with type name (e.g., `cloneMyType`)
-- `"prefix"`: Prefixes with type name (e.g., `myTypeClone`)
-- `"generic"`: Uses TypeScript generics (e.g., `clone<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
 
 ## Cloning Strategy
 
@@ -34,28 +27,55 @@ and the caller should clone them explicitly.
 
 ## Example
 
-```typescript
-@derive(Clone)
+```typescript before
+/** @derive(Clone) */
+class Point {
+    x: number;
+    y: number;
+}
+```
+
+```typescript after
 class Point {
     x: number;
     y: number;
+
+    static clone(value: Point): Point {
+        return pointClone(value);
+    }
+}
+
+export function pointClone(value: Point): Point {
+    const cloned = Object.create(Object.getPrototypeOf(value));
+    cloned.x = value.x;
+    cloned.y = value.y;
+    return cloned;
 }
+```
+
+Generated output:
+
+```typescript
+class Point {
+    x: number;
+    y: number;
 
-// Generated:
-// clone(): Point {
-//     const cloned = Object.create(Object.getPrototypeOf(this));
-//     cloned.x = this.x;
-//     cloned.y = this.y;
-//     return cloned;
-// }
+    static clone(value: Point): Point {
+        return pointClone(value);
+    }
+}
 
-const p1 = new Point();
-const p2 = p1.clone(); // Creates a new Point with same values
+export function pointClone(value: Point): Point {
+    const cloned = Object.create(Object.getPrototypeOf(value));
+    cloned.x = value.x;
+    cloned.y = value.y;
+    return cloned;
+}
 ```
 
 ## Implementation Notes
 
-- **Classes**: Uses `Object.create(Object.getPrototypeOf(this))` to preserve
+- **Classes**: Uses `Object.create(Object.getPrototypeOf(value))` to preserve
   the prototype chain, ensuring `instanceof` checks work correctly
 - **Enums**: Simply returns the value (enums are primitives in TypeScript)
 - **Interfaces/Type Aliases**: Creates new object literals with spread operator

package/docs/builtin-macros/debug.md

@@ -5,24 +5,17 @@ TypeScript classes, interfaces, enums, and type aliases.
 
 ## Generated Output
 
-**Classes**: Generates an instance method returning a string
-like `"ClassName { field1: value1, field2: value2 }"`.
+**Classes**: Generates a standalone function `classNameToString(value)` and a static wrapper
+method `static toString(value)` returning a string like `"ClassName { field1: value1, field2: value2 }"`.
 
-**Enums**: Generates a standalone function `toStringEnumName(value)` that performs
+**Enums**: Generates a standalone function `enumNameToString(value)` that performs
 reverse lookup on numeric enums.
 
-**Interfaces**: Generates a standalone function `toStringInterfaceName(value)`.
+**Interfaces**: Generates a standalone function `interfaceNameToString(value)`.
 
 **Type Aliases**: Generates a standalone function using JSON.stringify for
 complex types, or field enumeration for object types.
 
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"suffix"` (default): Suffixes with type name (e.g., `toStringMyType`)
-- `"prefix"`: Prefixes with type name (e.g., `myTypeToString`)
-- `"generic"`: Uses TypeScript generics (e.g., `toString<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
 
 ## Field-Level Options
 
@@ -33,20 +26,59 @@ The `@debug` decorator supports:
 
 ## Example
 
+```typescript before
+/** @derive(Debug) */
+class User {
+    /** @debug({ rename: "id" }) */
+    userId: number;
+
+    /** @debug({ skip: true }) */
+    password: string;
+
+    email: string;
+}
+```
+
+```typescript after
+class User {
+    userId: number;
+
+    password: string;
+
+    email: string;
+
+    static toString(value: User): string {
+        return userToString(value);
+    }
+}
+
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('id: ' + value.userId);
+    parts.push('email: ' + value.email);
+    return 'User { ' + parts.join(', ') + ' }';
+}
+```
+
+Generated output:
+
 ```typescript
-@derive(Debug)
 class User {
-    @debug(rename = "id")
     userId: number;
 
-    @debug(skip)
     password: string;
 
     email: string;
+
+    static toString(value: User): string {
+        return userToString(value);
+    }
 }
 
-// Generated:
-// toString(): string {
-//     return "User { id: " + this.userId + ", email: " + this.email + " }";
-// }
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('id: ' + value.userId);
+    parts.push('email: ' + value.email);
+    return 'User { ' + parts.join(', ') + ' }';
+}
 ```

package/docs/builtin-macros/default.md

@@ -13,13 +13,6 @@ a standard way to create "zero" or "empty" instances of types.
 | Interface | `defaultValueInterfaceName(): InterfaceName` | Standalone function returning object literal |
 | Type Alias | `defaultValueTypeName(): TypeName` | Standalone function with type-appropriate default |
 
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"suffix"` (default): Suffixes with type name (e.g., `defaultValueMyType`)
-- `"prefix"`: Prefixes with type name (e.g., `myTypeDefaultValue`)
-- `"generic"`: Uses TypeScript generics (e.g., `defaultValue<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
 
 ## Default Values by Type
 
@@ -50,47 +43,105 @@ The `@default` decorator allows specifying explicit default values:
 
 ## Example
 
-```typescript
-@derive(Default)
+```typescript before
+/** @derive(Default) */
 class UserSettings {
-    @default("light")
+    /** @default("light") */
     theme: string;
 
-    @default(10)
+    /** @default(10) */
     pageSize: number;
 
-    notifications: boolean;  // Uses type default: false
+    notifications: boolean; // Uses type default: false
 }
+```
+
+```typescript after
+class UserSettings {
+    theme: string;
 
-// Generated:
-// static defaultValue(): UserSettings {
-//     const instance = new UserSettings();
-//     instance.theme = "light";
-//     instance.pageSize = 10;
-//     instance.notifications = false;
-//     return instance;
-// }
+    pageSize: number;
+
+    notifications: boolean; // Uses type default: false
+
+    static defaultValue(): UserSettings {
+        const instance = new UserSettings();
+        instance.theme = 'light';
+        instance.pageSize = 10;
+        instance.notifications = false;
+        return instance;
+    }
+}
+```
+
+Generated output:
+
+```typescript
+class UserSettings {
+    theme: string;
+
+    pageSize: number;
+
+    notifications: boolean; // Uses type default: false
+
+    static defaultValue(): UserSettings {
+        const instance = new UserSettings();
+        instance.theme = 'light';
+        instance.pageSize = 10;
+        instance.notifications = false;
+        return instance;
+    }
+}
 ```
 
 ## Enum Defaults
 
 For enums, mark one variant with `@default`:
 
+```typescript before
+/** @derive(Default) */
+enum Status {
+    /** @default */
+    Pending,
+    Active,
+    Completed
+}
+```
+
+```typescript after
+enum Status {
+    /** @default */
+    Pending,
+    Active,
+    Completed
+}
+
+export function statusDefaultValue(): Status {
+    return Status.Pending;
+}
+
+export const Status = {
+    defaultValue: statusDefaultValue
+} as const;
+```
+
+Generated output:
+
 ```typescript
-@derive(Default)
 enum Status {
-    @default
+    /** @default */
     Pending,
     Active,
     Completed
 }
 
-// Generated:
-// export namespace Status {
-//     export function defaultValue(): Status {
-//         return Status.Pending;
-//     }
-// }
+export function statusDefaultValue(): Status {
+    return Status.Pending;
+}
+
+export const Status = {
+    defaultValue: statusDefaultValue
+} as const;
 ```
 
 ## Error Handling

package/docs/builtin-macros/deserialize/cycleforward-reference-support.md

@@ -0,0 +1,11 @@
+## Cycle/Forward-Reference Support
+
+Uses deferred patching to handle references:
+
+1. When encountering `{ "__ref": id }`, returns a `PendingRef` marker
+2. Continues deserializing other fields
+3. After all objects are created, `ctx.applyPatches()` resolves all pending references
+
+References only apply to object-shaped, serializable values. The generator avoids probing for
+`__ref` on primitive-like fields (including literal unions and `T | null` where `T` is primitive-like),
+and it parses `Date` / `Date | null` from ISO strings without treating them as references.