@webiny/mcp 6.1.0-beta.0 → 6.1.0-beta.2

package/skills/api/v5-to-v6-migration/SKILL.md

@@ -0,0 +1,416 @@
+---
+name: webiny-v5-to-v6-migration
+context: webiny-api
+description: >
+  Migration patterns for converting v5 Webiny code to v6 architecture. Use this skill when
+  migrating existing v5 plugins to v6 features, converting context plugins to DI services,
+  adapting v5 event subscriptions to v6 EventHandlers, or understanding how v5 patterns
+  translate to v6. Targeted at AI agents performing migrations.
+---
+
+# v5 → v6 Migration Patterns
+
+## Overview
+
+v6 replaces v5's plugin-based architecture with **feature-based DI**. The key shifts:
+
+| v5 Concept                       | v6 Equivalent                                          |
+| -------------------------------- | ------------------------------------------------------ |
+| `ContextPlugin`                  | `createAbstraction` + `createImplementation` (Service) |
+| Plugin array                     | `createFeature` + `container.register()`               |
+| `context.myService`              | DI injection via constructor                           |
+| `onEntryAfterCreate.subscribe()` | `EventHandler` feature                                 |
+| `new GraphQLSchemaPlugin()`      | `GraphQLSchemaFactory.createImplementation()`          |
+
+---
+
+## Pattern 1: Context Plugin → DI Service
+
+### v5
+
+```typescript
+new ContextPlugin(async context => {
+  context.lingotekService = {
+    translate: async (docId, locale) => {
+      /* ... */
+    },
+    getStatus: async docId => {
+      /* ... */
+    },
+    deleteProject: async projectId => {
+      /* ... */
+    }
+  };
+});
+```
+
+### v6
+
+```typescript
+// features/lingotekService/abstractions.ts
+import { createAbstraction } from "@webiny/feature/api";
+
+export interface ILingotekService {
+  translate(docId: string, locale: string): Promise<Result<void, Error>>;
+  getStatus(docId: string): Promise<Result<TranslationStatus, Error>>;
+  deleteProject(projectId: string): Promise<Result<void, Error>>;
+}
+
+export const LingotekService = createAbstraction<ILingotekService>("MyExt/LingotekService");
+
+export namespace LingotekService {
+  export type Interface = ILingotekService;
+}
+
+// features/lingotekService/LingotekService.ts
+class LingotekServiceImpl implements LingotekService.Interface {
+  constructor(private buildParams: BuildParams.Interface) {}
+
+  async translate(docId: string, locale: string) {
+    /* ... */
+  }
+  async getStatus(docId: string) {
+    /* ... */
+  }
+  async deleteProject(projectId: string) {
+    /* ... */
+  }
+}
+
+export default LingotekService.createImplementation({
+  implementation: LingotekServiceImpl,
+  dependencies: [BuildParams]
+});
+
+// features/lingotekService/feature.ts
+export const LingotekServiceFeature = createFeature({
+  name: "LingotekService",
+  register(container) {
+    container.register(LingotekServiceImpl).inSingletonScope();
+  }
+});
+```
+
+**Key difference:** v5 attaches to context object. v6 uses DI — consumers declare the service as a constructor dependency.
+
+---
+
+## Pattern 2: Event Subscription → EventHandler Feature
+
+### v5
+
+```typescript
+context.cms.onEntryAfterCreate.subscribe(async params => {
+  if (params.model.modelId !== "myModel") return;
+  await doSomething(params.entry);
+});
+```
+
+### v6
+
+```typescript
+// features/syncOnCreate/EntryAfterCreateHandler.ts
+import { EntryAfterCreateEventHandler } from "webiny/api/cms/entry";
+import { LingotekService } from "../lingotekService/abstractions.js";
+import { MY_MODEL_ID } from "~/shared/constants.js";
+
+class SyncOnCreateHandler implements EntryAfterCreateEventHandler.Interface {
+  constructor(private lingotekService: LingotekService.Interface) {}
+
+  async handle(event: EntryAfterCreateEventHandler.Event) {
+    const { entry, model } = event.payload;
+    if (model.modelId !== MY_MODEL_ID) return;
+    await this.lingotekService.translate(entry.entryId, "en");
+  }
+}
+
+export default EntryAfterCreateEventHandler.createImplementation({
+  implementation: SyncOnCreateHandler,
+  dependencies: [LingotekService]
+});
+
+// features/syncOnCreate/feature.ts
+export const SyncOnCreateFeature = createFeature({
+  name: "SyncOnCreate",
+  register(container) {
+    container.register(SyncOnCreateHandler);
+  }
+});
+```
+
+**Key differences:**
+
+- Feature directory is named by **business capability** (`syncOnCreate`), not by event name
+- Handler is a thin orchestrator — business logic lives in the injected service
+- Must filter by `model.modelId` — handler fires for ALL models
+
+---
+
+## Pattern 3: Plugin Array → Feature Registration
+
+### v5
+
+```typescript
+export default () => [
+    new GraphQLSchemaPlugin({ ... }),
+    new ContextPlugin(async ctx => { ... }),
+    myModelPlugin,
+    eventSubscriptionPlugin
+];
+```
+
+### v6
+
+```typescript
+// api/Extension.ts
+import { createFeature } from "webiny/api";
+
+export const Extension = createFeature({
+  name: "MyExtension",
+  register(container) {
+    container.register(MyModel);
+    container.register(MyGraphQLSchema);
+    SyncOnCreateFeature.register(container);
+    LingotekServiceFeature.register(container);
+  }
+});
+```
+
+---
+
+## Pattern 4: Async Service Bootstrap → ServiceProvider Pattern
+
+When a v5 service was initialized with async data (loading settings, fetching config), v6 uses the **ServiceProvider** pattern — a provider abstraction with `async getService()` that lazily creates and caches the service.
+
+See the **ServiceProvider Pattern** section in **webiny-api-architect** for the full pattern with abstractions, implementation, and consumer examples.
+
+---
+
+## Pattern 6: Permissions objects
+
+### v5
+
+```ts
+[
+  {
+    name: "content.i18n",
+    locales: ["en-US"]
+  },
+  {
+    name: "cms.endpoint.read"
+  },
+  {
+    name: "cms.endpoint.manage"
+  },
+  {
+    name: "cms.endpoint.preview"
+  },
+  {
+    name: "cms.contentModelGroup",
+    groups: {
+      "en-US": [LT_TRANSLATION_MODEL_GROUP_ID]
+    },
+    rwd: "rw",
+    own: false,
+    pw: ""
+  },
+  {
+    name: "cms.contentModel",
+    models: {
+      "en-US": [
+        LT_TRANSLATION_DOCUMENT_MODEL_ID,
+        LT_CONFIG_MODEL_ID,
+        LT_TRANSLATION_PROJECT_MODEL_ID
+      ]
+    },
+    rwd: "rwd",
+    own: false,
+    pw: ""
+  },
+  {
+    name: "cms.contentEntry",
+    rwd: "rwd",
+    own: false,
+    pw: ""
+  }
+];
+```
+
+### v6
+
+- `content.i18n` no longer exists
+- locale codes no longer exist
+- `models` is an array of `model.modelId` strings
+- `groups` is an array of `group.slug` strings
+
+```ts
+[
+  {
+    name: "cms.endpoint.read"
+  },
+  {
+    name: "cms.endpoint.manage"
+  },
+  {
+    name: "cms.endpoint.preview"
+  },
+  {
+    name: "cms.contentModelGroup",
+    groups: ["LT_TRANSLATION_MODEL_GROUP_ID"],
+    rwd: "rw",
+    own: false,
+    pw: ""
+  },
+  {
+    name: "cms.contentModel",
+    models: [
+      "LT_TRANSLATION_DOCUMENT_MODEL_ID",
+      "LT_CONFIG_MODEL_ID",
+      "LT_TRANSLATION_PROJECT_MODEL_ID"
+    ],
+    rwd: "rwd",
+    own: false,
+    pw: ""
+  },
+  {
+    name: "cms.contentEntry",
+    rwd: "rwd",
+    own: false,
+    pw: ""
+  }
+];
+```
+
+---
+
+## Type Resolution Guide
+
+When working with Webiny abstractions, always verify types from source before writing code.
+
+### Step 1: Find the catalog entry
+
+Use MCP skills or generated catalogs to look up the abstraction (e.g., `RoleFactory`).
+
+### Step 2: Get the source path
+
+The catalog entry includes a `Source` field pointing to the abstraction definition.
+
+### Step 3: Read the type definition
+
+```bash
+# Read the abstractions file
+cat node_modules/@webiny/api-core/features/security/roles/shared/abstractions.d.ts
+```
+
+### Common type patterns
+
+| Pattern       | What to expect                                     |
+| ------------- | -------------------------------------------------- |
+| Factories     | Return `Promise<Type[]>` or `Promise<Builder[]>`   |
+| UseCases      | Have `Input` type and return `Result<Data, Error>` |
+| EventHandlers | Have `Event` with `payload` property               |
+| Repositories  | Return `Result<T, Error>` — wrap CMS errors        |
+
+---
+
+## Migration Map: v5 → v6 Equivalents
+
+### Backend: Context Method Calls → Use Cases
+
+| v5 Pattern                                | v6 Equivalent                            |
+| ----------------------------------------- | ---------------------------------------- |
+| `context.cms.getModel()`                  | `GetModelUseCase`                        |
+| `context.cms.createModel()`               | `CreateModelUseCase`                     |
+| `context.cms.updateEntry()`               | `UpdateEntryUseCase`                     |
+| `context.cms.getSingletonEntryManager()`  | `GetSingletonEntryUseCase`               |
+| `context.tenancy.getCurrentTenant()`      | `TenantContext.getTenant()`              |
+| `context.security.withoutAuthorization()` | `IdentityContext.withoutAuthorization()` |
+| `context.aco.folder.delete()`             | `DeleteFolderUseCase`                    |
+| `context.aco.folder.get()`                | `GetFolderUseCase`                       |
+| `context.plugins.register()`              | DI container registration                |
+| `context.plugins.byType()`                | DI container injection                   |
+
+### Backend: Lifecycle Event Subscriptions → EventHandlers
+
+| v5 Pattern (`.subscribe()`)       | v6 EventHandler                    |
+| --------------------------------- | ---------------------------------- |
+| `cms.onEntryBeforeCreate`         | `EntryBeforeCreateEventHandler`    |
+| `cms.onEntryAfterCreate`          | `EntryAfterCreateEventHandler`     |
+| `cms.onEntryBeforeUpdate`         | `EntryBeforeUpdateEventHandler`    |
+| `cms.onEntryAfterUpdate`          | `EntryAfterUpdateEventHandler`     |
+| `cms.onEntryBeforeDelete`         | `EntryBeforeDeleteEventHandler`    |
+| `cms.onEntryAfterDelete`          | `EntryAfterDeleteEventHandler`     |
+| `cms.onEntryBeforeMove`           | `EntryBeforeMoveEventHandler`      |
+| `cms.onEntryBeforePublish`        | `EntryBeforePublishEventHandler`   |
+| `cms.onEntryBeforeUnpublish`      | `EntryBeforeUnpublishEventHandler` |
+| `aco.folder.onFolderBeforeUpdate` | `FolderBeforeUpdateEventHandler`   |
+| `aco.folder.onFolderAfterCreate`  | `FolderAfterCreateEventHandler`    |
+| `aco.folder.onFolderAfterUpdate`  | `FolderAfterUpdateEventHandler`    |
+
+### Backend: Plugin Classes → v6 Equivalents
+
+| v5 Plugin                                       | v6 Equivalent                 |
+| ----------------------------------------------- | ----------------------------- |
+| `ContextPlugin`                                 | DI-registered implementations |
+| `createContextPlugin`                           | DI-registered implementations |
+| `CmsModelPlugin`                                | `ModelFactory`                |
+| `GraphQLSchemaPlugin`                           | `GraphQLSchemaFactory`        |
+| `createGraphQLSchemaPlugin`                     | `GraphQLSchemaFactory`        |
+| `createTaskDefinition`                          | `TaskDefinition`              |
+| `CmsModelFieldToGraphQLPlugin`                  | TODO                          |
+| `createSecurityRolePlugin`                      | `RoleFactory`                 |
+| `createSecurityTeamPlugin`                      | `TeamFactory`                 |
+| `StorageTransformPlugin`                        | TODO                          |
+| `createApiGatewayRoute`                         | TODO (Adrian)                 |
+| `CmsModelFieldValidatorPlugin`                  | TODO                          |
+| `createCmsGraphQLSchemaSorterPlugin`            | TODO                          |
+| `createCmsEntryElasticsearchBodyModifierPlugin` | TODO                          |
+
+### Admin: React Plugins → AdminConfig API
+
+| v5 Pattern                         | v6 Equivalent                                            |
+| ---------------------------------- | -------------------------------------------------------- |
+| `createComponentPlugin`            | `Component.createDecorator`                              |
+| `RoutePlugin`                      | `<AdminConfig.Route/>`                                   |
+| `AddMenu` / menu components        | `<AdminConfig.Menu/>`                                    |
+| `HasPermission`                    | `HasPermission` or `createHasPermission` with new schema |
+| `GraphQLPlaygroundTabPlugin`       | TODO                                                     |
+| `CmsModelFieldTypePlugin`          | `<CmsModelFieldType/>`                                   |
+| `CmsModelFieldRendererPlugin`      | `<CmsModelFieldRenderer/>`                               |
+| `AdminAppPermissionRendererPlugin` | `createPermissionSchema` / `<Security.Permissions/>`     |
+| `webiny/app/config`                | `EnvConfig`                                              |
+
+---
+
+## Common Migration Mistakes
+
+### 1. Creating one abstraction per operation
+
+v5 habit: separate plugins per action. v6: group related operations into a **multi-method Service**.
+
+### 2. Naming features by technical event
+
+v5 habit: thinking in terms of hooks (`onEntryAfterCreate`). v6: features describe business capability (`syncToLingotek`). Files inside can be named technically (`EntryAfterCreateHandler.ts`).
+
+### 3. Assuming builder patterns
+
+v6 factories sometimes return plain objects, sometimes builder objects. Always read source types first, to understand what the factory in question returns.
+
+### 4. Putting event handlers in a handlers/ directory
+
+v5 habit: grouping by type. v6: handlers are features — they go in `features/`.
+
+### 5. Attaching to context
+
+v5: `context.myService = { ... }`. v6: create an abstraction and register it in the DI container via the parent feature, or a standalone feature (`createFeature`).
+
+### 6. Inline business logic in event handlers
+
+v5 habit: putting logic directly in the subscription callback. v6: handlers are thin orchestrators — extract logic into a Service or UseCase.
+
+## Related Skills
+
+- **webiny-api-architect** — Full v6 architecture, Services vs UseCases, anti-patterns
+- **webiny-use-case-pattern** — UseCase implementation details
+- **webiny-event-handler-pattern** — EventHandler and domain event patterns
+- **webiny-dependency-injection** — DI pattern and injectable services

package/skills/generated/admin/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/aco/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/build-params/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/cms/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/configs/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/env-config/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/form/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/graphql-client/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/lexical/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/local-storage/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/router/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/security/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/tenancy/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/ui/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/admin/website-builder/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/api/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 
 ## Abstractions

package/skills/generated/api/aco/SKILL.md

@@ -13,7 +13,7 @@ Folder event handlers and use cases.
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/build-params/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/cms/SKILL.md

@@ -13,7 +13,7 @@ Entry, model, and group event handlers and use cases.
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/event-publisher/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/file-manager/SKILL.md

@@ -13,7 +13,7 @@ File event handlers and use cases.
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/graphql/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/key-value-store/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/logger/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns
 

package/skills/generated/api/opensearch/SKILL.md

@@ -10,7 +10,7 @@ description: >
 ## How to Use
 
 1. Find the abstraction you need below
-2. Read the source file to get the exact interface and types
+2. You MUST read the source file to get the exact interface and types!
 3. Import: `import { Name } from "<importPath>";`
 4. See `webiny-use-case-pattern` or `webiny-event-handler-pattern` skills for implementation patterns