@jaypie/mcp 0.8.45 → 0.8.47

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.8.45#115144e4"
+const BUILD_VERSION_STRING = "@jaypie/mcp@0.8.47#d4678bbc"
     ;
 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.8.45",
+  "version": "0.8.47",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",

package/release-notes/mcp/0.8.46.md

@@ -0,0 +1,11 @@
+---
+version: 0.8.46
+date: 2026-04-19
+summary: Add repokit skill documenting the @jaypie/repokit tooling bundle
+---
+
+## Changes
+
+- Added `skill("repokit")` covering what ships in `@jaypie/repokit` (`dotenv`, `env-cmd`, `rimraf`, `sort-package-json`, `tsx`), when to reach for it, and usage patterns — including the `env-cmd -f .env -- <cmd>` `--` separator gotcha
+- Registered `repokit` under the development category in `skill("skills")` and `skill("agents")`
+- Cross-linked from `skill("monorepo")` (added to related, recommended as root devDependency) and `skill("variables")` (added "Loading from `.env` Files" section)

package/release-notes/mcp/0.8.47.md

@@ -0,0 +1,12 @@
+---
+version: 0.8.47
+date: 2026-04-22
+summary: Add web skill covering JaypieWebDeploymentBucket, JaypieStaticWebBucket, and related CloudFront/S3 web hosting patterns
+---
+
+## Changes
+
+- Added `skill("web")` covering static site hosting with `@jaypie/constructs`: `JaypieWebDeploymentBucket`, `JaypieStaticWebBucket`, and pointers to `JaypieDistribution` for dynamic origins
+- Documented the OIDC deploy role flow, CfnOutputs consumed by CI/CD (`DestinationBucketName`, `DestinationBucketDeployRoleArn`, `DistributionId`, `CertificateArn`), and production caching behavior
+- Registered `web` under the infrastructure category in `skill("skills")`, `skill("agents")`, and `skill("infrastructure")`
+- Cross-linked from `skill("cdk")` (added to See Also) and `skill("dns")` (added to related + See Also)

package/skills/agents.md

@@ -33,8 +33,8 @@ Complete stack styles, techniques, and traditions.
 `mcp__jaypie__skill(alias: String)`
 
 Contents: index, releasenotes
-Development: apikey, documentation, errors, llm, logs, mocks, monorepo, style, subpackages, tests, tools
-Infrastructure: apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, websockets
+Development: apikey, documentation, errors, llm, logs, mocks, monorepo, repokit, style, subpackages, tests, tools
+Infrastructure: apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, web, websockets
 Patterns: api, fabric, handlers, models, services, vocabulary
 Recipes: recipe-api-server
 Meta: issues, jaypie, mcp, skills

package/skills/cdk.md

@@ -1,6 +1,6 @@
 ---
 description: CDK constructs and deployment patterns
-related: apikey, aws, cicd, dynamodb, express, lambda, migrations, secrets, streaming, websockets
+related: apikey, aws, cicd, dynamodb, express, lambda, migrations, secrets, streaming, web, websockets
 ---
 
 # CDK Constructs
@@ -422,4 +422,5 @@ new JaypieOrganizationTrail(this, "OrgTrail", {
 - **`skill("secrets")`** - Secret management with JaypieEnvSecret
 - **`skill("streaming")`** - JaypieDistribution and JaypieNextJs streaming configuration
 - **`skill("variables")`** - Environment variables reference
+- **`skill("web")`** - JaypieWebDeploymentBucket and JaypieStaticWebBucket for static sites
 - **`skill("websockets")`** - JaypieWebSocket and JaypieWebSocketTable constructs

package/skills/dns.md

@@ -1,6 +1,6 @@
 ---
 description: DNS and domain configuration
-related: cdk, aws
+related: aws, cdk, web
 ---
 
 # DNS Configuration
@@ -135,4 +135,5 @@ openssl s_client -connect app.example.com:443 -servername app.example.com
 ## See Also
 
 - **`skill("cdk")`** - CDK constructs including JaypieDistribution and JaypieNextJs
+- **`skill("web")`** - Static site hosting with JaypieWebDeploymentBucket and JaypieStaticWebBucket
 

package/skills/infrastructure.md

@@ -1,6 +1,6 @@
 ---
 description: AWS, CDK, CI/CD, and observability
-related: aws, cdk, cicd, cicd-actions, cicd-deploy, cicd-environments, datadog, dns, dynamodb, secrets, variables, websockets
+related: aws, cdk, cicd, cicd-actions, cicd-deploy, cicd-environments, datadog, dns, dynamodb, secrets, variables, web, websockets
 ---
 
 # Infrastructure
@@ -23,4 +23,5 @@ Cloud infrastructure and deployment patterns.
 | `migrations` | DynamoDB migration custom resources |
 | `secrets` | AWS Secrets Manager |
 | `variables` | Environment variables reference |
+| `web` | Static site and web content hosting |
 | `websockets` | WebSocket API Gateway constructs |

package/skills/monorepo.md

@@ -1,6 +1,6 @@
 ---
 description: Initialize a Jaypie monorepo project
-related: subpackage, cicd, style, tests
+related: subpackage, cicd, repokit, style, tests
 ---
 
 # Jaypie Monorepo Setup
@@ -130,9 +130,11 @@ npm-debug.log*
 Install root dev dependencies:
 
 ```bash
-npm install --save-dev @jaypie/eslint @jaypie/testkit eslint rimraf sort-package-json tsx vite vite-plugin-dts vitest
+npm install --save-dev @jaypie/eslint @jaypie/repokit @jaypie/testkit eslint vite vite-plugin-dts vitest
 ```
 
+`@jaypie/repokit` bundles `dotenv`, `env-cmd`, `rimraf`, `sort-package-json`, and `tsx` at consistent versions. See `skill("repokit")`.
+
 ## Workspace Conventions
 
 | Directory | Purpose |

package/skills/repokit.md

@@ -0,0 +1,97 @@
+---
+description: Bundled development tooling for Jaypie repositories (dotenv, env-cmd, rimraf, sort-package-json, tsx)
+related: monorepo, subpackages, variables
+---
+
+# Repokit
+
+`@jaypie/repokit` is a convenience bundle that consolidates common development tooling used across Jaypie repositories into a single devDependency. Install once and get `dotenv`, `env-cmd`, `rimraf`, `sort-package-json`, and `tsx` at consistent versions.
+
+## What Ships
+
+| Tool | Purpose |
+|------|---------|
+| `dotenv` | Load environment variables from `.env` files (re-exported for programmatic use) |
+| `env-cmd` | Run commands with env file loaded (CLI; use in npm scripts) |
+| `rimraf` | Cross-platform `rm -rf` (re-exported and available as CLI) |
+| `sort-package-json` | Enforce consistent `package.json` key ordering (CLI) |
+| `tsx` | Run TypeScript files directly without precompilation (CLI) |
+
+## When to Reach for It
+
+- **Monorepo root devDependency** — single install so every package has access to the same tooling versions
+- **Subpackages** — add as a devDependency where build/clean/script tooling is needed
+- **Avoid** listing each of the five underlying packages individually — let `@jaypie/repokit` pin them
+
+## Install
+
+```bash
+npm install --save-dev @jaypie/repokit
+# Or in a monorepo root:
+npm install --save-dev @jaypie/repokit -w .
+```
+
+## Programmatic Exports
+
+```typescript
+import { config, rimraf } from "@jaypie/repokit";
+
+config();                 // dotenv — loads process.env from .env
+await rimraf("./dist");   // cross-platform directory removal
+```
+
+Re-exports:
+
+- Everything from `dotenv` (`config`, `parse`, `populate`, etc.)
+- `rimraf` from `rimraf`
+
+## CLI Usage in `package.json` Scripts
+
+```json
+{
+  "scripts": {
+    "clean": "rimraf ./dist",
+    "clean:all": "rimraf ./packages/*/dist",
+    "format:package": "sort-package-json ./package.json ./packages/*/package.json",
+    "script:setup": "tsx scripts/setup.ts",
+    "start:dev": "env-cmd -f .env.development -- node server.js"
+  }
+}
+```
+
+### `env-cmd` — the `--` separator is required
+
+`env-cmd -f <file> -- <command>` passes the env file to the process and runs the command with those variables loaded. **Omit the `--` and env-cmd treats the file as an rc/JSON config instead of a dotenv file, which silently does the wrong thing.**
+
+```bash
+# Correct — `.env.dev` is read as a dotenv file
+env-cmd -f .env.dev -- node server.js
+
+# Wrong — `.env.dev` is parsed as JSON/rc config; server.js still runs but without env vars
+env-cmd -f .env.dev node server.js
+```
+
+Use this pattern to load repo-level `.env` files into scripts without hard-coding variables in `package.json`.
+
+### `tsx` — for TypeScript scripts
+
+```bash
+tsx scripts/seed.ts
+env-cmd -f .env.local -- tsx scripts/seed.ts   # combine with env-cmd
+```
+
+### `sort-package-json` — for consistency
+
+Add a `format:package` script and run it before committing, or enforce it in a pre-commit hook.
+
+## Why Not the Five Packages Directly?
+
+- **One devDependency vs five** — fewer entries in `package.json` and `package-lock.json`
+- **Pinned versions** — every Jaypie repo using repokit gets the same `dotenv`/`rimraf`/etc. version
+- **Easier upgrades** — bump repokit once, all tooling updates together
+
+## See Also
+
+- `skill("monorepo")` — repokit is a recommended devDependency for the monorepo root
+- `skill("subpackages")` — use repokit as a devDependency in any package that needs build/clean/script tooling
+- `skill("variables")` — pair `env-cmd` with `.env` files to load project environment variables

package/skills/skills.md

@@ -16,8 +16,8 @@ Look up skills by alias: `mcp__jaypie__skill(alias)`
 | Category | Skills |
 |----------|--------|
 | contents | index, releasenotes |
-| development | apikey, documentation, errors, llm, logs, mocks, monorepo, style, subpackages, tests, tools |
-| infrastructure | apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, websockets |
+| development | apikey, documentation, errors, llm, logs, mocks, monorepo, repokit, style, subpackages, tests, tools |
+| infrastructure | apigateway, aws, cdk, cicd, datadog, dns, dynamodb, express, lambda, migrations, secrets, sqs, streaming, variables, web, websockets |
 | patterns | api, fabric, handlers, models, services, vocabulary |
 | recipes | recipe-api-server |
 | meta | issues, jaypie, mcp, skills |

package/skills/variables.md

@@ -1,6 +1,6 @@
 ---
 description: Environment variables reference
-related: apikey, cdk, datadog, secrets
+related: apikey, cdk, datadog, repokit, secrets
 ---
 
 # Environment Variables
@@ -49,6 +49,21 @@ LOG_LEVEL=trace npm run dev
 LOG_LEVEL=debug npm run dev
 ```
 
+### Loading from `.env` Files
+
+Use `env-cmd` (bundled with `@jaypie/repokit`) to load a dotenv file into a script. The `--` separator is required — without it, `env-cmd` treats the file as rc/JSON config and silently does the wrong thing:
+
+```json
+{
+  "scripts": {
+    "start:dev": "env-cmd -f .env.development -- node server.js",
+    "script:seed": "env-cmd -f .env.local -- tsx scripts/seed.ts"
+  }
+}
+```
+
+See `skill("repokit")` for the full tooling bundle.
+
 ## CDK Infrastructure Variables
 
 | Variable | Description |

package/skills/web.md

@@ -0,0 +1,205 @@
+---
+description: Static site and web content hosting with CloudFront, S3, and DNS
+related: cdk, cicd-deploy, dns, secrets, streaming
+---
+
+# Web Hosting
+
+Deploying static websites and web content through `@jaypie/constructs`. Pair an S3 origin with a CloudFront distribution, Route53 alias, ACM certificate, and (optionally) an OIDC deploy role for GitHub Actions — all wired up by one construct.
+
+## Constructs
+
+| Construct | Purpose |
+|-----------|---------|
+| `JaypieWebDeploymentBucket` | S3 + CloudFront + Route53 + OIDC deploy role for a static site |
+| `JaypieStaticWebBucket` | Pre-configured `JaypieWebDeploymentBucket` that defaults to the `static` subdomain |
+| `JaypieDistribution` | CloudFront in front of a dynamic handler (Lambda / Function URL / origin) |
+| `JaypieNextJs` | Server-rendered Next.js deployment (see `skill("cdk")`) |
+
+Use `JaypieWebDeploymentBucket` / `JaypieStaticWebBucket` for pre-built assets (SPA bundles, static docs). Use `JaypieDistribution` when CloudFront fronts an Express Lambda or streaming handler. Use `JaypieNextJs` for SSR Next.js.
+
+## JaypieWebDeploymentBucket
+
+Static site on S3 fronted by CloudFront, wired to Route53 and ACM. Setting `CDK_ENV_REPO` also provisions an OIDC deploy role with scoped S3 and CloudFront invalidation permissions for GitHub Actions.
+
+```typescript
+import { JaypieWebDeploymentBucket } from "@jaypie/constructs";
+
+new JaypieWebDeploymentBucket(this, "Web", {
+  host: "app.example.com",
+  zone: "example.com",
+});
+```
+
+### Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `host` | `string` | `mergeDomain(CDK_ENV_WEB_SUBDOMAIN, CDK_ENV_WEB_HOSTED_ZONE \|\| CDK_ENV_HOSTED_ZONE)` |
+| `zone` | `string \| IHostedZone \| JaypieHostedZone` | `CDK_ENV_WEB_HOSTED_ZONE \|\| CDK_ENV_HOSTED_ZONE` |
+| `certificate` | `boolean \| ICertificate` | `true` (creates via `resolveCertificate`) |
+| `name` | `string` | `constructEnvName("web")` |
+| `roleTag` | `string` | `CDK.ROLE.HOSTING` |
+
+Also accepts all `s3.BucketProps` — the bucket defaults to `autoDeleteObjects: true`, `publicReadAccess: true`, `websiteIndexDocument: "index.html"`, `websiteErrorDocument: "index.html"` (SPA-friendly).
+
+### CloudFront
+
+- Default behavior: S3 static website origin, `REDIRECT_TO_HTTPS`, `CACHING_DISABLED`.
+- In production (`isProductionEnv()`), a second behavior on `/*` enables `CACHING_OPTIMIZED` — `index.html` stays uncached so SPA deploys are visible immediately; hashed assets get edge cache.
+
+### DNS
+
+Creates an A record alias to the distribution. Tags the record with `CDK.ROLE.NETWORKING`.
+
+### Deploy Role (OIDC)
+
+When `CDK_ENV_REPO` is set (e.g., `finlaysonstudio/jaypie`), the construct creates an IAM role assumed via GitHub OIDC with:
+
+- `s3:PutObject`, `s3:DeleteObject`, `s3:GetObject`, `s3:ListObjectsV2` on the bucket
+- `s3:ListBucket` on the bucket
+- `cloudformation:DescribeStacks` on the owning stack (so workflows can read outputs)
+- `cloudfront:CreateInvalidation` on the distribution
+
+Exposed as `CfnOutput`s for workflow consumption:
+
+| Output | Contents |
+|--------|----------|
+| `DestinationBucketName` | Target bucket for `aws s3 sync` |
+| `DestinationBucketDeployRoleArn` | Role ARN for `aws-actions/configure-aws-credentials` |
+| `DistributionId` | CloudFront distribution for `aws cloudfront create-invalidation` |
+| `CertificateArn` | ACM certificate ARN (when a certificate is created) |
+
+See `skill("cicd-deploy")` for the workflow pattern that reads these outputs and deploys content.
+
+## JaypieStaticWebBucket
+
+`JaypieWebDeploymentBucket` with `static` as the default subdomain. Use for a "static.example.com" asset site sharing the project's hosted zone.
+
+```typescript
+import { JaypieStaticWebBucket } from "@jaypie/constructs";
+
+// Minimal — host defaults to `envHostname({ subdomain: "static" })`,
+// zone defaults to CDK_ENV_DOMAIN || CDK_ENV_HOSTED_ZONE
+new JaypieStaticWebBucket(this, "Static");
+
+// Override host/zone when needed
+new JaypieStaticWebBucket(this, "Docs", {
+  host: "docs.example.com",
+  zone: "example.com",
+});
+```
+
+The default `name` is `constructEnvName("static")` so the bucket is namespaced per environment.
+
+## Environment-Aware Hosts
+
+`envHostname()` resolves a hostname from `PROJECT_ENV`, producing apex for production and a prefixed subdomain otherwise.
+
+```typescript
+import { envHostname, JaypieStaticWebBucket } from "@jaypie/constructs";
+
+// production → "jaypie.net"
+// sandbox    → "sandbox.jaypie.net"
+// development → "development.jaypie.net"
+const host = envHostname({ domain: "jaypie.net" });
+
+new JaypieStaticWebBucket(this, "Bucket", { host, zone: "jaypie.net" });
+```
+
+See `skill("variables")` for the `PROJECT_ENV` / `CDK_ENV_*` variables involved.
+
+## JaypieDistribution (dynamic origins)
+
+For CloudFront in front of an Express Lambda, Function URL, or custom origin — not a static S3 site — reach for `JaypieDistribution`. It ships with ACM, Route53 alias, WAF, and security headers by default.
+
+```typescript
+import { JaypieDistribution, JaypieExpressLambda } from "@jaypie/constructs";
+
+const api = new JaypieExpressLambda(this, "Api", {
+  code: "../api/dist",
+  handler: "index.handler",
+});
+
+new JaypieDistribution(this, "Distribution", {
+  handler: api,
+  host: "api.example.com",
+  zone: "example.com",
+});
+```
+
+Security headers (`ResponseHeadersPolicy`) and WAFv2 WebACL are covered in `skill("cdk")`. Response streaming with `createLambdaStreamHandler` is covered in `skill("streaming")`.
+
+### Certificate Sharing
+
+`resolveCertificate` caches certificates at the stack level by domain, so swapping `JaypieDistribution` ↔ `JaypieApiGateway` on the same hostname does not tear down or recreate the certificate. For explicit control:
+
+```typescript
+import { JaypieCertificate, JaypieDistribution } from "@jaypie/constructs";
+
+const cert = new JaypieCertificate(this, "ApiCert", {
+  domainName: "api.example.com",
+  zone: "example.com",
+});
+
+new JaypieDistribution(this, "Dist", { handler: api, certificate: cert });
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `CDK_ENV_HOSTED_ZONE` | Default hosted zone for all web constructs |
+| `CDK_ENV_WEB_HOSTED_ZONE` | Override hosted zone for web buckets specifically |
+| `CDK_ENV_WEB_SUBDOMAIN` | Subdomain under the hosted zone |
+| `CDK_ENV_WEB_HOST` | Full host override (skips subdomain + zone composition) |
+| `CDK_ENV_REPO` | `owner/repo` — when set, provisions the OIDC deploy role |
+| `CDK_ENV_DOMAIN` | Default domain for `JaypieStaticWebBucket` zone resolution |
+
+See `skill("variables")` for the full environment variable reference.
+
+## Deployment Workflow
+
+A typical `feat/*` branch deploy:
+
+1. CDK deploys the bucket, distribution, and deploy role.
+2. Workflow reads `DestinationBucketName`, `DestinationBucketDeployRoleArn`, and `DistributionId` from stack outputs.
+3. Workflow assumes the deploy role, runs `aws s3 sync ./dist s3://$BUCKET`, then invalidates `/*` on the distribution.
+
+See `skill("cicd-deploy")` for the reusable action pattern.
+
+## Stack Example
+
+```typescript
+import { Construct } from "constructs";
+import {
+  envHostname,
+  JaypieAppStack,
+  JaypieStaticWebBucket,
+} from "@jaypie/constructs";
+
+export class DocumentationStack extends JaypieAppStack {
+  public readonly bucket: JaypieStaticWebBucket;
+
+  constructor(scope: Construct, id?: string) {
+    super(scope, id ?? "JaypieDocumentationStack", { key: "documentation" });
+
+    const zone = process.env.CDK_ENV_HOSTED_ZONE ?? "example.com";
+    const host = envHostname({ domain: zone });
+
+    this.bucket = new JaypieStaticWebBucket(this, "DocumentationBucket", {
+      host,
+      zone,
+    });
+  }
+}
+```
+
+## See Also
+
+- **`skill("cdk")`** — core constructs, `JaypieDistribution` WAF and security headers, `JaypieNextJs`
+- **`skill("cicd-deploy")`** — workflows that consume `DestinationBucketName` / `DeployRoleArn` / `DistributionId`
+- **`skill("dns")`** — hosted zones, ACM certificates, DNS debugging
+- **`skill("secrets")`** — `JaypieEnvSecret` provider/consumer pattern
+- **`skill("streaming")`** — `JaypieDistribution` streaming configuration
+- **`skill("variables")`** — environment variable reference