@webiny/mcp 6.0.0-rc.5 → 6.0.0-rc.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webiny/mcp",
-	"version": "6.0.0-rc.5",
+	"version": "6.0.0-rc.6",
 	"type": "module",
 	"main": "./index.js",
 	"repository": {
@@ -16,7 +16,7 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "1.27.1",
-		"@webiny/cli-core": "6.0.0-rc.5",
+		"@webiny/cli-core": "6.0.0-rc.6",
 		"front-matter": "4.0.2",
 		"react": "18.2.0",
 		"zod": "3.25.76"
@@ -24,7 +24,7 @@
 	"devDependencies": {
 		"@types/lodash": "4.17.24",
 		"@types/ncp": "2.0.8",
-		"@webiny/build-tools": "6.0.0-rc.5",
+		"@webiny/build-tools": "6.0.0-rc.6",
 		"typescript": "5.9.3"
 	},
 	"scripts": {
@@ -45,5 +45,5 @@
 			]
 		}
 	},
-	"gitHead": "8f9b60f1193682a21e037e6f771b19f1dfd65045"
+	"gitHead": "a2a076532809feabf674a6873464f09071d86c72"
 }

package/skills/api-custom-feature/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: webiny-api-custom-feature
+context: webiny-extensions
+description: >
+  Creating custom API features with createFeature and createAbstraction.
+  Use this skill when the developer wants to define a new backend service,
+  register an abstraction in the DI container, create a reusable API module,
+  or wire up custom business logic as a Webiny feature. Covers the full pattern:
+  define an interface, create an abstraction token, implement and register
+  via createFeature, and register the extension in webiny.config.tsx.
+---
+
+# Custom API Features
+
+## TL;DR
+
+Use `createFeature` and `createAbstraction` from `"webiny/api"` to define reusable backend services. An abstraction is a DI token typed to an interface. A feature registers concrete implementations into the DI container. Other extensions (GraphQL schemas, lifecycle hooks, etc.) can then declare the abstraction as a dependency and receive the implementation automatically.
+
+## Pattern
+
+```typescript
+// extensions/myFeature/MyFeature.ts
+import { createFeature, createAbstraction } from "webiny/api";
+
+// 1. Define the interface
+export interface IMyService {
+    doSomething(): string;
+}
+
+// 2. Create the abstraction (DI token)
+export const MyService = createAbstraction<IMyService>("MyService");
+
+// 3. Export the interface via namespace (convention for consumers)
+export namespace MyService {
+    export type Interface = IMyService;
+}
+
+// 4. Register the feature (default export)
+export default createFeature({
+    name: "MyApp/MyFeature",
+    register(container) {
+        // Register a plain object instance
+        container.registerInstance(MyService, {
+            doSomething() {
+                return "Hello!";
+            }
+        });
+    }
+});
+```
+
+## Core APIs
+
+### `createAbstraction<T>(name: string)`
+
+Creates a typed DI token (an `Abstraction<T>` instance). The generic `T` is the interface that implementations must satisfy. The `name` string is used for debugging and error messages.
+
+| Import | `import { createAbstraction } from "webiny/api"` |
+|---|---|
+| Returns | `Abstraction<T>` |
+| Usage | Pass to `container.registerInstance()`, `container.register()`, or as a dependency in other extensions |
+
+### `createFeature(def)`
+
+Creates a feature definition that the framework loads as an API extension. Must be the **default export** of the file.
+
+| Import | `import { createFeature } from "webiny/api"` |
+|---|---|
+| `def.name` | Unique feature name (convention: `"AppName/FeatureName"`) |
+| `def.register(container)` | Called at startup with the DI `Container` instance |
+
+### Container Registration Methods
+
+| Method | When to Use |
+|---|---|
+| `container.registerInstance(abstraction, instance)` | Register a plain object that satisfies the interface |
+| `container.register(Implementation)` | Register a class (created via `Abstraction.createImplementation`) |
+| `container.registerFactory(abstraction, () => instance)` | Register a lazy factory |
+
+## Extension Registration
+
+Register the feature file using `<Api.Extension>` in your extension's React entry point:
+
+```tsx
+// extensions/myFeature/Extension.tsx
+import React from "react";
+import { Api } from "webiny/extensions";
+
+export const MyFeature = () => {
+    return <Api.Extension src={"@/extensions/myFeature/MyFeature.ts"} />;
+};
+```
+
+Then mount it in `webiny.config.tsx` or your app's extension composition.
+
+## Examples
+
+### Simple Service with Instance Registration
+
+```typescript
+// extensions/pricing/PricingFeature.ts
+import { createFeature, createAbstraction } from "webiny/api";
+
+export interface IPricingService {
+    calculatePrice(basePrice: number, quantity: number): number;
+    getDiscount(customerId: string): Promise<number>;
+}
+
+export const PricingService = createAbstraction<IPricingService>("PricingService");
+
+export namespace PricingService {
+    export type Interface = IPricingService;
+}
+
+export default createFeature({
+    name: "MyApp/Pricing",
+    register(container) {
+        container.registerInstance(PricingService, {
+            calculatePrice(basePrice, quantity) {
+                return basePrice * quantity;
+            },
+            async getDiscount(_customerId) {
+                return 0.1; // 10% default discount
+            }
+        });
+    }
+});
+```
+
+### Service with Class Registration and Dependencies
+
+When your service itself needs dependencies, use `createImplementation` on the abstraction and `container.register()`:
+
+```typescript
+// extensions/notifications/NotificationFeature.ts
+import { createFeature, createAbstraction } from "webiny/api";
+import { Logger } from "webiny/api/logger";
+
+export interface INotificationService {
+    notify(userId: string, message: string): Promise<void>;
+}
+
+export const NotificationService = createAbstraction<INotificationService>("NotificationService");
+
+export namespace NotificationService {
+    export type Interface = INotificationService;
+}
+
+// Class implementation with injected dependencies
+class NotificationServiceImpl implements INotificationService {
+    constructor(private logger: Logger.Interface) {}
+
+    async notify(userId: string, message: string) {
+        this.logger.info(`Notifying ${userId}: ${message}`);
+    }
+}
+
+// Attach DI metadata to the class
+const NotificationServiceRegistration = NotificationService.createImplementation({
+    implementation: NotificationServiceImpl,
+    dependencies: [Logger]
+});
+
+export default createFeature({
+    name: "MyApp/Notifications",
+    register(container) {
+        container.register(NotificationServiceRegistration);
+    }
+});
+```
+
+## Key Rules
+
+1. **Default export** -- `createFeature()` result must be the default export of the file.
+2. **One feature per file** -- each `.ts` file loaded via `<Api.Extension>` should export one feature.
+3. **Namespace convention** -- export `namespace MyService { export type Interface = IMyService; }` so consumers can type dependencies as `MyService.Interface`.
+4. **Name uniqueness** -- feature names must be globally unique; use `"AppName/FeatureName"` convention.
+5. **Constructor param order** -- when using class registration, the `dependencies` array must match constructor parameter order exactly.
+
+## Quick Reference
+
+| What | How |
+|---|---|
+| Import | `import { createFeature, createAbstraction } from "webiny/api"` |
+| Create token | `const MyService = createAbstraction<IMyService>("MyService")` |
+| Register instance | `container.registerInstance(MyService, { ... })` |
+| Register class | `container.register(MyService.createImplementation({ implementation, dependencies }))` |
+| Extension entry | `<Api.Extension src={"@/extensions/myFeature/MyFeature.ts"} />` |
+| Deploy | `yarn webiny deploy api --env=dev` |
+
+## Related Skills
+
+- **webiny-dependency-injection** -- Full DI pattern details, all injectable services, decorator and composite patterns
+- **webiny-custom-graphql-api** -- How to consume your custom feature's abstraction in a GraphQL schema
+- **webiny-project-structure** -- Extension file layout and `webiny.config.tsx` registration

package/skills/configure-auth0/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: webiny-configure-auth0
+description: >
+  Configuring Auth0 as an identity provider (IDP) for Webiny projects.
+  Use this skill when the developer asks about Auth0 authentication, Auth0 SSO,
+  replacing Cognito with Auth0, setting up external identity providers, configuring
+  OIDC authentication, mapping JWT claims to Webiny identities, or customizing
+  the Auth0 login flow. Also relevant when asking about AUTH0_ISSUER, AUTH0_CLIENT_ID
+  environment variables, Auth0IdpConfig, or the MyAuth0Extension pattern.
+---
+
+# Configure Auth0 Authentication
+
+## TL;DR
+
+Webiny supports Auth0 as an external identity provider (IDP) to replace the default Cognito authentication. You create two files: an API config class that maps Auth0 JWT claims to Webiny identity data (`Auth0IdpConfig`), and a React extension component (`<Auth0 />`) that wires issuer URL, client ID, and the API config path. Register the extension in `webiny.config.tsx`, set two environment variables (`AUTH0_ISSUER`, `AUTH0_CLIENT_ID`), and deploy.
+
+## Pattern / Core Concept
+
+Auth0 integration has two parts:
+
+1. **API Config** — A class implementing `Auth0IdpConfig.Interface` that maps JWT token claims to Webiny's identity structure. Registered via `Auth0IdpConfig.createImplementation()` (the universal DI pattern).
+2. **Extension Component** — A React component that renders `<Auth0 />` from `@webiny/auth0`, passing the issuer URL, client ID, and path to the API config file. The `<Auth0 />` component handles environment variable injection, API extension registration, and Admin login screen setup automatically.
+
+### How `<Auth0 />` Works Internally
+
+The `<Auth0 />` component (from `@webiny/auth0`) is a `defineExtension` that:
+
+- Sets Lambda env vars: `AUTH0_ISSUER`, `AUTH0_CLIENT_ID`
+- Sets Admin app env vars: `REACT_APP_IDP_TYPE=auth0`, `REACT_APP_AUTH0_ISSUER`, `REACT_APP_AUTH0_CLIENT_ID`
+- Registers the internal `Auth0IdpFeature` API extension (OIDC token verification)
+- Registers your custom API config extension (identity mapping)
+- Registers the Admin Auth0 login screen extension
+
+## Reference Tables
+
+### `Auth0IdpConfig.Interface`
+
+| Method              | Signature                                                        | Required | Description                                           |
+| ------------------- | ---------------------------------------------------------------- | -------- | ----------------------------------------------------- |
+| `getIdentity`       | `(token: JwtPayload) => Auth0Identity \| Promise<Auth0Identity>` | Yes      | Maps JWT claims to Webiny identity data               |
+| `verifyTokenClaims` | `(token: JwtPayload) => void \| Promise<void>`                   | No       | Custom claim verification (throw to reject the token) |
+
+### `Auth0Identity` (Return Type of `getIdentity`)
+
+| Field         | Type                             | Description                                      |
+| ------------- | -------------------------------- | ------------------------------------------------ |
+| `id`          | `string`                         | Unique user ID (typically `token["sub"]`)        |
+| `displayName` | `string`                         | User's display name                              |
+| `roles`       | `string[]`                       | Webiny security roles to assign                  |
+| `teams`       | `string[]`                       | Webiny teams (optional, filter out falsy values) |
+| `profile`     | `{ firstName, lastName, email }` | User profile fields                              |
+| `context`     | `object`                         | Runtime data (not stored in DB)                  |
+
+### `<Auth0 />` Component Props
+
+| Prop        | Type     | Description                                              |
+| ----------- | -------- | -------------------------------------------------------- |
+| `issuer`    | `string` | Auth0 issuer URL (e.g., `https://your-tenant.auth0.com`) |
+| `clientId`  | `string` | Auth0 application client ID                              |
+| `apiConfig` | `string` | Absolute path to the API config file                     |
+
+### Environment Variables
+
+| Variable          | Used By     | Description                 |
+| ----------------- | ----------- | --------------------------- |
+| `AUTH0_ISSUER`    | API + Admin | Auth0 issuer URL            |
+| `AUTH0_CLIENT_ID` | API + Admin | Auth0 application client ID |
+
+## Full Examples
+
+### Example 1: Basic Auth0 Configuration
+
+**Step 1: Create the API config**
+
+Create `extensions/auth0/MyAuth0Config.ts`:
+
+```typescript
+import { Auth0IdpConfig } from "@webiny/auth0";
+
+class MyIdpConfig implements Auth0IdpConfig.Interface {
+  getIdentity(token: Auth0IdpConfig.JwtPayload) {
+    return {
+      id: String(token["sub"]),
+      displayName: token["name"],
+      roles: ["full-access"],
+      profile: {
+        firstName: token["given_name"],
+        lastName: token["family_name"],
+        email: token["email"]
+      },
+      context: {
+        canAccessTenant: true,
+        defaultTenant: "root"
+      }
+    };
+  }
+}
+
+const MyAuth0Config = Auth0IdpConfig.createImplementation({
+  implementation: MyIdpConfig,
+  dependencies: []
+});
+
+export default MyAuth0Config;
+```
+
+**Step 2: Create the extension component**
+
+Create `extensions/auth0/MyAuth0Extension.tsx`:
+
+```tsx
+import React from "react";
+import { Auth0 } from "@webiny/auth0";
+
+export const MyAuth0Extension = () => {
+  return (
+    <Auth0
+      issuer={String(process.env.AUTH0_ISSUER)}
+      clientId={String(process.env.AUTH0_CLIENT_ID)}
+      apiConfig={import.meta.dirname + "/MyAuth0Config.ts"}
+    />
+  );
+};
+```
+
+**Step 3: Register in `webiny.config.tsx`**
+
+```tsx
+import React from "react";
+import { MyAuth0Extension } from "./extensions/auth0/MyAuth0Extension.js";
+
+export const Extensions = () => {
+  return (
+    <>
+      {/* Replace <Cognito /> with Auth0 */}
+      <MyAuth0Extension />
+
+      {/* ... other extensions ... */}
+    </>
+  );
+};
+```
+
+**Step 4: Set environment variables**
+
+Add to your `.env` file (or CI/CD environment):
+
+```
+AUTH0_ISSUER=https://your-tenant.auth0.com/
+AUTH0_CLIENT_ID=your-auth0-client-id
+```
+
+**Step 5: Deploy**
+
+```bash
+yarn webiny deploy
+```
+
+### Example 2: Custom Claim Verification
+
+If your Auth0 setup uses custom claims (e.g., via Auth0 Actions or Rules) that need validation:
+
+```typescript
+import { Auth0IdpConfig } from "@webiny/auth0";
+
+class MyIdpConfig implements Auth0IdpConfig.Interface {
+  getIdentity(token: Auth0IdpConfig.JwtPayload) {
+    return {
+      id: String(token["sub"]),
+      displayName: token["name"],
+      roles: [token["https://webiny.com/role"]],
+      profile: {
+        firstName: token["given_name"],
+        lastName: token["family_name"],
+        email: token["email"]
+      },
+      context: {
+        canAccessTenant: true,
+        defaultTenant: "root"
+      }
+    };
+  }
+
+  verifyTokenClaims(token: Auth0IdpConfig.JwtPayload) {
+    // Reject tokens without the required custom claim
+    if (!token["https://webiny.com/role"]) {
+      throw new Error("Token is missing the 'https://webiny.com/role' claim.");
+    }
+
+    // Reject tokens from unauthorized organizations
+    if (token["org_id"] && token["org_id"] !== "org_expected") {
+      throw new Error("User does not belong to the authorized organization.");
+    }
+  }
+}
+
+const MyAuth0Config = Auth0IdpConfig.createImplementation({
+  implementation: MyIdpConfig,
+  dependencies: []
+});
+
+export default MyAuth0Config;
+```
+
+### Example 3: Using DI Dependencies in Config
+
+If your config needs access to other Webiny services (e.g., to look up tenant-specific roles):
+
+```typescript
+import { Auth0IdpConfig } from "@webiny/auth0";
+import { TenantContext } from "webiny/api/tenancy";
+
+class MyIdpConfig implements Auth0IdpConfig.Interface {
+  constructor(private tenantContext: TenantContext.Interface) {}
+
+  getIdentity(token: Auth0IdpConfig.JwtPayload) {
+    const tenant = this.tenantContext.getTenant();
+
+    return {
+      id: String(token["sub"]),
+      displayName: token["name"],
+      roles: [token["https://webiny.com/role"]],
+      profile: {
+        firstName: token["given_name"],
+        lastName: token["family_name"],
+        email: token["email"]
+      },
+      context: {
+        canAccessTenant: true,
+        defaultTenant: tenant?.id ?? "root"
+      }
+    };
+  }
+}
+
+const MyAuth0Config = Auth0IdpConfig.createImplementation({
+  implementation: MyIdpConfig,
+  dependencies: [TenantContext]
+});
+
+export default MyAuth0Config;
+```
+
+## Quick Reference
+
+### Imports
+
+```typescript
+// API config
+import { Auth0IdpConfig } from "@webiny/auth0";
+
+// Extension component
+import { Auth0 } from "@webiny/auth0";
+```
+
+### Key Interfaces
+
+| Interface                     | Package         | Purpose                          |
+| ----------------------------- | --------------- | -------------------------------- |
+| `Auth0IdpConfig.Interface`    | `@webiny/auth0` | API-side JWT-to-identity mapping |
+| `Auth0IdpConfig.JwtPayload`   | `@webiny/auth0` | JWT token payload type           |
+| `Auth0IdpConfig.IdentityData` | `@webiny/auth0` | Identity return type             |
+
+### File Structure
+
+```
+extensions/auth0/
+├── MyAuth0Config.ts        # API config (JWT claim mapping)
+└── MyAuth0Extension.tsx    # Extension component (Auth0 setup)
+```
+
+### Registration
+
+In `webiny.config.tsx`, replace `<Cognito />` with `<MyAuth0Extension />`.
+
+### Deploy
+
+```bash
+yarn webiny deploy        # Deploy all (Core + API + Admin)
+```
+
+Both API and Admin need to be redeployed since Auth0 affects both the backend (token verification, identity mapping) and the frontend (login screen).
+
+## Related Skills
+
+- **configure-okta** — Alternative IDP: configuring Okta authentication
+- **dependency-injection** — The universal DI pattern used by `Auth0IdpConfig.createImplementation()`
+- **project-structure** — How `webiny.config.tsx` and extensions are organized
+- **local-development** — Deploying and testing your Auth0 configuration