@jaypie/mcp 0.7.16 → 0.7.18

package/dist/suites/docs/index.js

@@ -9,7 +9,7 @@ import { gt } from 'semver';
 /**
  * Docs Suite - Documentation services (skill, version, release_notes)
  */
-const BUILD_VERSION_STRING = "@jaypie/mcp@0.7.16#d8b8c444"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.7.18#db5c9ff1"
     ;
 const __filename$1 = fileURLToPath(import.meta.url);
 const __dirname$1 = path.dirname(__filename$1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.7.16",
+  "version": "0.7.18",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/constructs/1.2.30.md

@@ -0,0 +1,15 @@
+---
+version: 1.2.30
+date: 2026-02-13
+summary: Default security headers for JaypieDistribution
+---
+
+# @jaypie/constructs 1.2.30
+
+## Features
+
+- **JaypieDistribution**: Ships with default security response headers via a `ResponseHeadersPolicy`, analogous to `helmet` for Express. Headers include HSTS, X-Content-Type-Options, X-Frame-Options (DENY), Referrer-Policy, Content-Security-Policy, Permissions-Policy, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy, and Server removal.
+- **JaypieDistribution**: New `securityHeaders` prop — `true` (default) applies sensible defaults, `false` disables, or pass a `SecurityHeadersOverrides` object to selectively override individual headers.
+- **JaypieDistribution**: New `responseHeadersPolicy` prop for full override with a custom `IResponseHeadersPolicy`.
+- **SecurityHeadersOverrides**: New exported interface for selective security header configuration.
+- **CDK.SECURITY_HEADERS**: New constants for default CSP, HSTS max-age, and Permissions-Policy values.

package/release-notes/mcp/0.7.18.md

@@ -0,0 +1,10 @@
+---
+version: 0.7.18
+date: 2026-02-14
+summary: Fix dynamodb skill documentation errors
+---
+
+## Changes
+
+- Fix non-existent `JaypieTable` reference to `JaypieDynamoDb` in dynamodb skill
+- Add minimal-index guidance: start with zero GSIs, add only when access patterns demand

package/skills/cdk.md

@@ -169,6 +169,40 @@ new JaypieNextJs(this, "App", {
 
 **Streaming Note:** When `streaming: true`, also create `open-next.config.ts` in your Next.js app with `wrapper: "aws-lambda-streaming"`. See `skill("streaming")` for details.
 
+## Security Headers
+
+`JaypieDistribution` ships with default security response headers via a `ResponseHeadersPolicy` (analogous to `helmet` for Express):
+
+- HSTS (2-year max-age, includeSubDomains, preload)
+- X-Content-Type-Options (nosniff)
+- X-Frame-Options (DENY)
+- Referrer-Policy (strict-origin-when-cross-origin)
+- Content-Security-Policy (conservative defaults)
+- Permissions-Policy (camera, microphone, geolocation, payment disabled)
+- Cross-Origin-Opener-Policy (same-origin)
+- Cross-Origin-Resource-Policy (same-origin)
+- Server header removed
+
+```typescript
+// Disable security headers
+new JaypieDistribution(this, "Dist", { handler, securityHeaders: false });
+
+// Override specific headers
+new JaypieDistribution(this, "Dist", {
+  handler,
+  securityHeaders: {
+    contentSecurityPolicy: "default-src 'self';",
+    frameOption: HeadersFrameOption.SAMEORIGIN,
+  },
+});
+
+// Full custom policy override
+new JaypieDistribution(this, "Dist", {
+  handler,
+  responseHeadersPolicy: myCustomPolicy,
+});
+```
+
 ## See Also
 
 - **`skill("streaming")`** - JaypieDistribution and JaypieNextJs streaming configuration

package/skills/dynamodb.md

@@ -65,7 +65,9 @@ const result = await client.send(new QueryCommand({
 
 ## GSI Patterns
 
-### By-Status Index
+Start with zero GSIs. Add indexes only when a real access pattern requires them — GSIs cost money and can always be added later.
+
+### By-Status Index (example)
 
 ```typescript
 // GSI for querying by status across all users
@@ -92,18 +94,18 @@ const result = await client.send(new QueryCommand({
 
 ## CDK Table Definition
 
+Start with a basic table and add indexes only when access patterns demand them.
+
 ```typescript
-import { JaypieTable } from "@jaypie/constructs";
-
-const table = new JaypieTable(this, "DataTable", {
-  partitionKey: { name: "pk", type: AttributeType.STRING },
-  sortKey: { name: "sk", type: AttributeType.STRING },
-  globalSecondaryIndexes: [
-    {
-      indexName: "gsi1",
-      partitionKey: { name: "gsi1pk", type: AttributeType.STRING },
-      sortKey: { name: "gsi1sk", type: AttributeType.STRING },
-    },
+import { JaypieDynamoDb } from "@jaypie/constructs";
+
+// Recommended: start with no indexes
+const table = new JaypieDynamoDb(this, "myApp");
+
+// Add indexes later when driven by real access patterns
+const table = new JaypieDynamoDb(this, "myApp", {
+  indexes: [
+    { pk: ["scope", "model"], sk: ["sequence"] },
   ],
 });
 ```

package/skills/fabricator.md

@@ -0,0 +1,200 @@
+---
+description: Seeded deterministic test data generation with @jaypie/fabricator
+related: tests, mocks, models
+---
+
+# Fabricator
+
+`@jaypie/fabricator` provides seeded, deterministic data generation built on `@faker-js/faker`.
+
+## Installation
+
+```bash
+npm install @jaypie/fabricator
+```
+
+## Core: Fabricator Class
+
+Wraps faker.js with deterministic seeding. Same seed = same data.
+
+```typescript
+import { Fabricator } from "@jaypie/fabricator";
+
+const fab = new Fabricator("my-seed");
+fab.internet.email();    // Always the same for "my-seed"
+fab.person.firstName();  // Proxies to faker.js
+fab.id;                  // UUID derived from seed
+fab.name;                // Auto-generated word pair
+```
+
+### Factory Function
+
+```typescript
+import { fabricator } from "@jaypie/fabricator";
+
+const fab = fabricator("my-seed");
+const fab = fabricator({ seed: "my-seed", name: "Custom Name" });
+```
+
+### Environment Seed
+
+```typescript
+process.env.PROJECT_SEED = "test-seed";
+const fab = new Fabricator(); // Falls back to PROJECT_SEED
+```
+
+## Random Number Generation
+
+```typescript
+const fab = new Fabricator("seed");
+
+fab.random();                                     // 0-1 float
+fab.random({ min: 1, max: 10, integer: true });   // 1-10 integer
+fab.random({ mean: 50, stddev: 10 });             // Normal distribution
+fab.random({ min: 10, max: 100, currency: true }); // 2 decimal places
+fab.random({ min: 0, max: 1, precision: 4 });     // 4 decimal places
+```
+
+Standalone:
+
+```typescript
+import { random } from "@jaypie/fabricator";
+
+const rng = random("my-seed");
+rng({ min: 1, max: 100, integer: true });
+```
+
+## Built-in Generators
+
+### Words
+
+```typescript
+fab.generate.words(); // "adjective noun", "adjective verb", or "noun verb"
+```
+
+### Person
+
+Generates realistic person objects with probabilistic variations using Jaypie golden numbers:
+
+```typescript
+fab.generate.person();
+// { id, firstName, middleName, lastName, fullName }
+```
+
+- **UNCOMMON (14.6%)**: middleName missing, fullName includes middle
+- **RARE (2.1%)**: firstName is a surname, lastName is hyphenated
+- **EPIC (0.307%)**: double middle names
+
+## CHANCE Constants
+
+```typescript
+import { CHANCE } from "@jaypie/fabricator/constants";
+
+CHANCE.UNCOMMON;   // 0.146  (14.6%)
+CHANCE.RARE;       // 0.021  (2.1%)
+CHANCE.EPIC;       // 0.00307 (0.307%)
+CHANCE.LEGENDARY;  // 0.000441 (0.0441%)
+```
+
+## Nested Fabricators
+
+Create hierarchical fabricators with `Fabricator.new`:
+
+```typescript
+const world = Fabricator.new({
+  seed: "earth",
+  name: ({ fabricator }) => fabricator.generate.words(),
+  fabricators: {
+    cities: { name: ({ fabricator }) => fabricator.location.city() },
+    exports: { name: ({ fabricator }) => fabricator.commerce.product() },
+  },
+});
+
+world.cities(5);         // Array of 5 city fabricators
+for (const c of world.cities()) break; // Infinite generator
+```
+
+## EventFabricator
+
+Abstract base for generating temporally-distributed events across a year.
+
+```typescript
+import { EventFabricator } from "@jaypie/fabricator";
+
+class OrderFabricator extends EventFabricator<Order> {
+  protected createEvent({ timestamp, seed, index }) {
+    return { id: seed, timestamp, amount: 100 };
+  }
+}
+
+const fab = new OrderFabricator({
+  seed: "orders-2025",
+  annualCount: 10000,
+  template: ["HOURS_BUSINESS", "DAYS_WEEKDAYS_ONLY", "BOOST_HOLIDAY_SEASON"],
+  timezone: "America/New_York",
+});
+
+const orders = fab.events({ year: 2025 });
+```
+
+### Temporal Templates
+
+Combine templates for realistic distribution patterns:
+
+| Category | Templates |
+|----------|-----------|
+| Hours | `HOURS_BUSINESS`, `HOURS_RETAIL`, `HOURS_EVENING`, `HOURS_OVERNIGHT`, `HOURS_24_7`, etc. |
+| Days | `DAYS_WEEKDAYS_ONLY`, `DAYS_NO_SUNDAY`, `DAYS_NO_MONDAY`, `DAYS_NO_SUNDAY_MONDAY` |
+| Dates | `DATES_15_AND_25` (billing cycles) |
+| Seasonal | `SEASON_SUMMER_ONLY`, `SEASON_WINTER_ONLY`, `SEASON_NO_SUMMER`, `SEASON_NO_WINTER` |
+| Curves | `CURVE_EVENING_PEAK`, `CURVE_ECOMMERCE`, `CURVE_MIDDAY_PEAK` |
+| Spikes | `SPIKE_MORNING`, `SPIKE_LUNCH`, `SPIKE_EVENING` |
+| Boosts | `BOOST_SUMMER`, `BOOST_WINTER`, `BOOST_WEEKENDS`, `BOOST_HOLIDAY_SEASON` |
+| Lulls | `LULL_SUMMER`, `LULL_WINTER`, `LULL_WEEKENDS`, `LULL_WEEKDAYS` |
+
+### Derived Events
+
+Generate cascading follow-up events from parent events:
+
+```typescript
+const fab = new TransactionFabricator({
+  seed: "txn",
+  annualCount: 500,
+  derived: {
+    maxDepth: 3,
+    rules: [
+      {
+        name: "refund",
+        probability: CHANCE.UNCOMMON,
+        timing: { mode: "range", delayMin: 1, delayMax: 30, unit: "days" },
+        createDerived: ({ parent, seed, timestamp }) => ({
+          id: seed,
+          type: "refund",
+          amount: -parent.amount,
+          timestamp,
+          parentId: parent.id,
+        }),
+      },
+    ],
+  },
+});
+```
+
+#### Timing Modes
+
+| Mode | Description |
+|------|-------------|
+| `fixed` | Exact delay from parent |
+| `range` | Random delay within min/max |
+| `recurring` | Repeated at interval with `maxRecurrences` or `until` |
+| `same-day` | Same day as parent event |
+
+## Utilities
+
+```typescript
+import { isUuid, numericSeed, uuidFrom } from "@jaypie/fabricator";
+
+isUuid("550e8400-e29b-41d4-a716-446655440000"); // true
+numericSeed("my-string");                        // Deterministic number
+uuidFrom("any-value");                           // UUID v5 from string
+```

package/skills/secrets.md

@@ -92,7 +92,7 @@ The construct auto-detects consumer mode for personal/ephemeral environments (`P
 
 ## Generated Secrets
 
-For secrets without a source value (e.g., database passwords):
+For secrets that don't come from an external source, use `generateSecretString`. CloudFormation generates the value on the **first deploy only** and preserves it across subsequent deploys. The value is never visible in templates, logs, or CI/CD output — it exists only inside AWS Secrets Manager and is retrievable at runtime.
 
 ```typescript
 new JaypieEnvSecret(this, "DB_PASSWORD", {
@@ -103,6 +103,93 @@ new JaypieEnvSecret(this, "DB_PASSWORD", {
 });
 ```
 
+This is the preferred pattern for any secret that can be randomly generated. No GitHub secret or workflow variable is needed — the CDK deploy creates and manages the value automatically.
+
+### Base62 Generated Secrets
+
+For secrets that must be base62-safe (`0-9A-Za-z` only), such as seeds and signing keys:
+
+```typescript
+new JaypieEnvSecret(this, "AdminSeed", {
+  envKey: "PROJECT_ADMIN_SEED",
+  generateSecretString: {
+    excludePunctuation: true,
+    includeSpace: false,
+    passwordLength: 64,
+  },
+});
+```
+
+With `excludePunctuation: true` and `includeSpace: false`, the generated value contains only base62 characters.
+
+## Seeds and API Keys in Workflows
+
+Seeds are secrets used to derive deterministic values (like API keys) at runtime. The generated-secret pattern is ideal for seeds because:
+
+1. **Set once**: CloudFormation generates the value on the first deploy. Subsequent deploys do not regenerate it.
+2. **Never known**: No human ever sees the seed value. It exists only in Secrets Manager.
+3. **Retrievable at runtime**: `loadEnvSecrets("PROJECT_ADMIN_SEED")` populates `process.env` for the handler to derive keys from.
+4. **Environment-isolated**: Each environment (sandbox, development, production) generates its own independent seed.
+
+### CDK Pattern
+
+Create the secret with `generateSecretString` and pass it to the Lambda:
+
+```typescript
+import { JaypieEnvSecret, JaypieExpressLambda } from "@jaypie/constructs";
+
+const adminSeed = new JaypieEnvSecret(this, "ProjectAdminSeed", {
+  envKey: "PROJECT_ADMIN_SEED",
+  generateSecretString: {
+    excludePunctuation: true,
+    includeSpace: false,
+    passwordLength: 64,
+  },
+});
+
+new JaypieExpressLambda(this, "ApiLambda", {
+  code: "dist",
+  handler: "index.handler",
+  secrets: [adminSeed],
+});
+```
+
+### Runtime Usage
+
+The handler loads the seed at startup and derives keys:
+
+```typescript
+import { expressHandler } from "jaypie";
+
+export default expressHandler(handler, {
+  secrets: ["PROJECT_ADMIN_SEED"],
+  setup: () => initClient(),
+});
+```
+
+At runtime, `process.env.PROJECT_ADMIN_SEED` contains the generated seed value. Application code uses it to derive API keys via HMAC, validate presented keys, and auto-provision on first use.
+
+### Workflow Integration
+
+No special workflow steps are needed for generated secrets. The CDK deploy step handles everything:
+
+```yaml
+- name: Deploy CDK Stacks
+  uses: ./.github/actions/cdk-deploy
+  with:
+    stack-name: JaypieGardenApi
+```
+
+On the first deploy, CloudFormation generates the seed. On subsequent deploys, the seed is preserved. The workflow never needs to generate, store, or pass the seed value.
+
+### Why Not GitHub Secrets?
+
+For externally-provided credentials (API keys from vendors, database URIs), GitHub environment secrets and env vars are the right approach. But for **internally-generated** secrets like seeds:
+
+- `generateSecretString` is simpler — no manual setup per environment
+- The value is never exposed to CI/CD logs or GitHub settings
+- CloudFormation guarantees idempotent creation — first deploy sets, updates preserve
+
 ## Tagging
 
 Apply standard tags for organization: