@jaypie/mcp 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",
@@ -45,6 +45,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "gitHead": "14683b303359f95dc63e58998959fddae3c90e97"
+  }
 }

package/prompts/Jaypie_Fabricator.md

@@ -1,6 +1,7 @@
 ---
 description: coding style resource, helpful when stuck on lint errors
 globs: packages/fabricator/**
+version: 0.3.0
 ---
 # Brief Guide to @jaypie/fabricator
 
@@ -17,6 +18,8 @@ The `Fabricator` class wraps faker.js and provides:
 - **Direct faker access**: All faker modules are proxied for convenience
 - **Enhanced random number generation**: Built-in `random()` function with advanced options
 - **Custom generators**: Specialized methods like `words()` and `generate.person()`
+- **Unique identifiers**: Each fabricator has an `id` (UUID) and `name` property
+- **Nested fabricators**: Support for hierarchical data generation with child fabricators
 
 ```typescript
 import { fabricator } from "@jaypie/fabricator";
@@ -27,6 +30,20 @@ const fab = fabricator();
 // Create seeded (deterministic) fabricator
 const seededFab = fabricator("my-seed");
 const uuidFab = fabricator("550e8400-e29b-41d4-a716-446655440000");
+
+// Access built-in properties
+console.log(fab.id);    // UUID
+console.log(fab.name);  // Generated name like "Happy Mountain"
+```
+
+**Options**:
+```typescript
+const fab = fabricator("my-seed", {
+  name: "Custom Name",  // String or function
+  generator: {
+    name: ({ fabricator }) => fabricator.faker.person.firstName()
+  }
+});
 ```
 
 ### 2. Deterministic Seeding
@@ -43,30 +60,54 @@ fab2.faker.person.firstName(); // "Jordan" (same!)
 
 **UUID Seeding**: UUIDs are converted to numeric arrays using `uuidToBytes` for efficient seeding.
 
+**Environment Variable**: Set `PROJECT_SEED` environment variable to provide a default seed for all unseeded fabricators:
+```typescript
+process.env.PROJECT_SEED = "my-project-seed";
+const fab = fabricator(); // Uses PROJECT_SEED
+```
+
 ### 3. Random Number Generation
 
 The `random()` function provides advanced randomness with multiple distribution types:
 
 **Basic Usage:**
 ```typescript
-fab.random();                          // 0-1 float
-fab.random({ min: 1, max: 10 });      // 1-10 float
-fab.random({ min: 1, max: 10, integer: true }); // 1-10 integer
+fab.random();                                     // 0-1 float
+fab.random({ min: 1, max: 10 });                 // 1-10 float
+fab.random({ min: 1, max: 10, integer: true });  // 1-10 integer
 ```
 
-**Advanced Options:**
-- `min/max`: Bounds (defaults: 0-1)
-- `integer`: Return integers (default: false)
-- `mean/stddev`: Normal distribution
-- `precision`: Decimal places
-- `currency`: Shorthand for precision: 2
-- `start`: Add offset to result
-- `seed`: Override the fabricator's seed for this call only
+**All Options:**
+```typescript
+fab.random({
+  min: 1,           // Minimum value (default: 0)
+  max: 10,          // Maximum value (default: 1)
+  integer: true,    // Return integer instead of float (default: false)
+  mean: 5,          // For normal distribution
+  stddev: 2,        // For normal distribution
+  precision: 2,     // Decimal places
+  currency: true,   // Shorthand for precision: 2
+  start: 100,       // Add offset to result
+  seed: "override"  // Override fabricator's seed for this call only
+});
+```
 
 **Smart Defaults:**
 - If only `min` is set, `max` defaults to `min * 2`
 - Normal distribution with `mean/stddev` can optionally be clamped by `min/max`
 
+**Common Patterns:**
+```typescript
+// Currency values
+fab.random({ min: 10, max: 1000, currency: true });  // e.g., 542.73
+
+// Percentages
+fab.random({ min: 0, max: 100, integer: true });     // e.g., 42
+
+// Weighted random with normal distribution
+fab.random({ mean: 50, stddev: 15, min: 0, max: 100 }); // Clusters around 50
+```
+
 ### 4. Faker Integration
 
 All faker modules are directly accessible through getters:
@@ -81,14 +122,14 @@ fab.company.name();
 
 ### 5. Custom Methods
 
-#### `words()`: Two-Word Combinations
+#### `generate.words()`: Two-Word Combinations
 Generates one of three patterns randomly:
 - adjective + noun
 - adjective + verb
 - noun + verb
 
 ```typescript
-fab.words(); // "happy dog" or "quick run" or "mountain climb"
+fab.generate.words(); // "happy dog" or "quick run" or "mountain climb"
 ```
 
 #### `generate.person(id?)`: Complex Person Generator
@@ -135,6 +176,47 @@ export const CHANCE = {
 
 Use these for consistent probability calculations across your test data.
 
+### 7. Nested Fabricators
+
+Create hierarchical data structures with `Fabricator.new()` and nested configurations:
+
+```typescript
+import { Fabricator } from "@jaypie/fabricator";
+
+// Define a nested structure
+const world = Fabricator.new({
+  seed: "my-world",
+  name: ({ fabricator }) => fabricator.location.city(),
+  fabricators: {
+    cities: {
+      name: ({ fabricator }) => fabricator.location.city(),
+      fabricators: {
+        streets: {
+          name: ({ fabricator }) => fabricator.location.street()
+        }
+      }
+    },
+    exports: {
+      name: ({ fabricator }) => fabricator.commerce.product()
+    }
+  }
+});
+
+// Access nested fabricators
+const cities = world.cities(5);  // Array of 5 city fabricators
+const cityGen = world.cities();  // Generator for infinite cities
+
+// Access nested child fabricators
+const city = cities[0];
+const streets = city.streets(10);  // 10 streets for this city
+```
+
+**Deterministic Child Seeding**: Child fabricators are seeded deterministically based on their parent's ID and their index, ensuring reproducible hierarchies.
+
+**Generator vs Array**:
+- `world.cities()` - Returns a generator for unlimited fabricators
+- `world.cities(n)` - Returns an array of exactly n fabricators
+
 ## Architecture
 
 ### Internal Utilities
@@ -143,6 +225,131 @@ Use these for consistent probability calculations across your test data.
 - **`uuidToBytes()`**: Converts UUIDs to byte arrays for seeding
 - **`uuidToNumber()`**: Converts UUIDs to single numbers (fallback)
 - **`numericSeedArray()`**: Smart converter that detects UUIDs and uses appropriate conversion
+- **`uuidFrom()`**: Generates deterministic UUID v5 from string or number using `JAYPIE_FABRICATOR_UUID` as namespace
+- **`isUuid()`**: Validates if a string is a properly formatted UUID
+
+## Best Practices & Patterns
+
+### Seeding Strategy
+
+Always tie seeds to fabricator instance ID for determinism with variety:
+
+```typescript
+// In parent fabricator method
+for (let i = 0; i < count; i++) {
+  const seed = `${this.id}-tenant-${i}`;
+  tenants.push(new TenantFabricator({ seed, name }));
+}
+
+// In child fabricator method
+for (let i = 0; i < count; i++) {
+  const seed = `${this.id}-merchant-${i}`;
+  merchants.push(new MerchantFabricator({ seed, name }));
+}
+```
+
+**Result:**
+- Same fabricator instance → same data (deterministic)
+- Different fabricator instance → different data (variety)
+- Each entity gets unique seed: `parentId-entityType-index`
+
+### Name Handling Pattern
+
+When passing name functions to child fabricators, pass the function itself (don't call it):
+
+```typescript
+// ✅ Correct - parent will invoke function
+const name = config?.name ? () => config.name : undefined;
+new TenantFabricator({ name, seed });
+
+// ❌ Wrong - calling function too early
+const name = config?.name ? config.name : generateName({ fabricator: this });
+new TenantFabricator({ name: () => name, seed });
+```
+
+The parent Fabricator class invokes name functions lazily when `get name()` is accessed and caches the result.
+
+### Generator Functions
+
+Export generator functions separately for reusability and testability:
+
+```typescript
+// Export the generator function
+export const generateTenantName = ({ fabricator }: FabricatorNameParams) => {
+  const city = fabricator.faker.location.city();
+  const suffixes = ["Financial", "Payments", "Commerce"];
+  const suffixIndex = Math.floor(fabricator.random() * suffixes.length);
+  return `${city} ${suffixes[suffixIndex]}`;
+};
+
+// Use in fabricator via generator option
+const fab = new Fabricator({
+  seed: "my-seed",
+  generator: {
+    name: generateTenantName
+  }
+});
+```
+
+### Extending Fabricator
+
+Create domain-specific fabricators by extending the base class:
+
+```typescript
+import { Fabricator as JaypieFabricator } from "@jaypie/fabricator";
+
+export class TenantFabricator extends JaypieFabricator {
+  constructor({
+    name,
+    seed,
+  }: {
+    name?: string | ((params: FabricatorNameParams) => string);
+    seed?: string | number;
+  } = {}) {
+    super({
+      name,
+      seed,
+      generator: {
+        name: generateTenantName,
+      },
+    });
+  }
+
+  // Add domain-specific methods
+  merchants(count: number): MerchantFabricator[] {
+    const merchants: MerchantFabricator[] = [];
+    for (let i = 0; i < count; i++) {
+      merchants.push(new MerchantFabricator({
+        seed: `${this.id}-merchant-${i}`
+      }));
+    }
+    return merchants;
+  }
+}
+```
+
+### Common Anti-Patterns
+
+**❌ Don't manage name storage yourself**
+```typescript
+// Wrong - parent already handles this
+private readonly _name: string;
+get name(): string {
+  return this._name;
+}
+```
+**✅ Right:** Use parent's `get name()` accessor via `generator` option.
+
+**❌ Don't pass index parameters**
+```typescript
+// Wrong - couples fabricator to sequence position
+class TenantFabricator {
+  constructor({ index, seed }) {
+    this._name = this.generateName(index);
+  }
+}
+```
+**✅ Right:** Use constructor config or generator functions.
 
 ## Key Design Patterns
 
@@ -150,15 +357,5 @@ Use these for consistent probability calculations across your test data.
 2. **Probabilistic Variations**: Use float rolls with CHANCE constants for realistic data variety
 3. **Proxy Access**: All faker modules exposed through getters for ergonomic API
 4. **Seed Flexibility**: Accepts strings, numbers, or UUIDs as seeds
-
-## Usage in @entpayco/fabricator
-
-Your wrapper package should:
-- Extend or compose `Fabricator` from `@jaypie/fabricator`
-- Add domain-specific generators (payments, accounts, transactions, etc.)
-- Follow the same patterns: seeding, probabilistic variations, subfaker for complex objects
-- Maintain the same function signature standards (single param, config object, or optional config)
-
----
-
-Ready to build domain-specific test data generators on this foundation!
+5. **Hierarchical Generation**: Nested fabricators enable deterministic tree structures for complex data models
+6. **Identity & Naming**: Every fabricator has a unique ID and name for tracking and debugging

package/LICENSE.txt

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Finlayson Studio, LLC
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.