@webiny/mcp 6.0.0 → 6.1.0-beta.1

package/skills/api/api-architect/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: webiny-api-architect
+context: webiny-extensions
+description: >
+  API-side architecture patterns for Webiny extensions. Use this skill when building
+  backend features with createFeature, createAbstraction, UseCase/Repository layering,
+  container registration, and API BuildParams. Covers the api/ directory structure
+  and DI scoping rules for API extensions.
+---
+
+# API Architecture Patterns
+
+## TL;DR
+
+API extensions use `createFeature` from `webiny/api` to register domain models, GraphQL schemas, and features into the DI container. Each feature is self-contained in its own directory with abstractions, implementations, and a `feature.ts` registration file. The layering is **UseCase → Repository**, with use cases as transient and repositories as singletons.
+
+## API Directory Structure
+
+```
+api/
+├── Extension.ts          # API entry point (createFeature)
+├── domain/               # Domain models, errors, value objects
+├── features/             # One directory per use case
+│   └── CreateThing/
+│       ├── abstractions.ts
+│       ├── CreateThingUseCase.ts
+│       ├── CreateThingRepository.ts
+│       └── feature.ts
+└── graphql/              # GraphQL schema definitions
+    └── CreateThingSchema.ts
+```
+
+## API Extension Entry Point
+
+The API entry point uses `createFeature` to register all backend components into the DI container:
+
+```ts
+// src/api/Extension.ts
+import { createFeature } from "webiny/api";
+import MyModel from "./domain/MyModel.js";
+import CreateThingSchema from "./graphql/CreateThingSchema.js";
+import { CreateThingFeature } from "./features/CreateThing/feature.js";
+import { GetThingFeature } from "./features/GetThing/feature.js";
+
+export const Extension = createFeature({
+  name: "MyExtension",
+  register(container) {
+    // Domain models (CMS content models, etc.)
+    container.register(MyModel);
+
+    // GraphQL schemas
+    container.register(CreateThingSchema);
+
+    // Features (use cases + repositories)
+    CreateThingFeature.register(container);
+    GetThingFeature.register(container);
+  }
+});
+```
+
+## Abstractions
+
+Every piece of business logic starts with a typed abstraction token:
+
+```ts
+// src/api/features/CreateThing/abstractions.ts
+import { createAbstraction, Result } from "webiny/api";
+import type { MyEntity } from "~/shared/MyEntity.js";
+
+export interface ICreateThingInput {
+  name: string;
+}
+
+export interface ICreateThingUseCase {
+  execute(input: ICreateThingInput): Promise<Result<MyEntity, Error>>;
+}
+
+export const CreateThingUseCase = createAbstraction<ICreateThingUseCase>(
+  "MyExtension/CreateThingUseCase"
+);
+
+// Namespace re-exports all related types for convenient access
+export namespace CreateThingUseCase {
+  export type Interface = ICreateThingUseCase;
+  export type Input = ICreateThingInput;
+}
+
+export interface ICreateThingRepository {
+  execute(entity: MyEntity): Promise<Result<MyEntity, Error>>;
+}
+
+export const CreateThingRepository = createAbstraction<ICreateThingRepository>(
+  "MyExtension/CreateThingRepository"
+);
+
+export namespace CreateThingRepository {
+  export type Interface = ICreateThingRepository;
+}
+```
+
+## Feature Registration
+
+```ts
+// src/api/features/CreateThing/feature.ts
+import { createFeature } from "webiny/api";
+import CreateThingUseCase from "./CreateThingUseCase.js";
+import CreateThingRepository from "./CreateThingRepository.js";
+
+export const CreateThingFeature = createFeature({
+  name: "CreateThing",
+  register(container) {
+    container.register(CreateThingUseCase); // transient (default)
+    container.register(CreateThingRepository).inSingletonScope();
+  }
+});
+```
+
+## Container Registration Methods
+
+| Method                                                   | When to Use                                                       |
+| -------------------------------------------------------- | ----------------------------------------------------------------- |
+| `container.register(Implementation)`                     | Register a class (created via `Abstraction.createImplementation`) |
+| `container.registerInstance(abstraction, instance)`      | Register a plain object that satisfies the interface              |
+| `container.registerFactory(abstraction, () => instance)` | Register a lazy factory                                           |
+
+## Reading API BuildParams
+
+A deployed API must **NEVER** use `process.env` to read configuration. All configuration flows through `BuildParams` via DI:
+
+```ts
+// Inside an API service — use BuildParams, NEVER process.env
+import { BuildParams } from "webiny/api/build-params";
+
+class MyServiceImpl implements MyService.Interface {
+  constructor(private buildParams: BuildParams.Interface) {}
+
+  doSomething() {
+    // buildParams.get() returns T | null — always handle null
+    const endpoint = this.buildParams.get<string>("MY_API_ENDPOINT");
+    if (!endpoint) {
+      throw new Error("MY_API_ENDPOINT build param is not configured.");
+    }
+  }
+}
+
+export default MyService.createImplementation({
+  implementation: MyServiceImpl,
+  dependencies: [BuildParams]
+});
+```
+
+> **Note:** BuildParam _declarations_ (`<Api.BuildParam>`) live in the top-level extension component — see the **webiny-full-stack-architect** skill.
+
+## Core APIs
+
+### `createAbstraction<T>(name: string)`
+
+Creates a typed DI token. 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>`                                 |
+
+### `createFeature(def)`
+
+Creates a feature definition that the framework loads as an extension.
+
+| 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        |
+
+## Key Rules
+
+1. **Abstractions first** — any new business logic MUST be encapsulated in `createAbstraction` + `createFeature`. Never put logic directly in an EventHandler, GraphQL resolver, or CLI command.
+2. **Namespace convention** — every abstraction exports `namespace MyAbstraction { export type Interface = ...; }` so consumers can type dependencies as `MyAbstraction.Interface`.
+3. **Name uniqueness** — feature names must be globally unique; use `"AppName/FeatureName"` convention.
+4. **Constructor param order** — `dependencies` array must match constructor parameter order exactly.
+5. **No `process.env` at runtime** — deployed API services must NEVER read `process.env`. All configuration flows through `BuildParams`.
+6. **Scoping** — use cases = transient (default), repositories = singleton (`.inSingletonScope()`).
+7. **Import extensions** — always use `.js` extensions in import paths (ESM).
+
+## Related Skills
+
+- **webiny-full-stack-architect** — Top-level component, shared domain layer, BuildParam declarations
+- **webiny-dependency-injection** — The `createImplementation` DI pattern and injectable services
+- **webiny-custom-graphql-api** — GraphQL schema creation with `GraphQLSchemaFactory`
+- **webiny-use-case-pattern** — UseCase pattern with `Result` type
+- **webiny-event-handler-pattern** — EventHandler lifecycle hooks

package/skills/api/custom-field-type/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: webiny-api-cms-custom-field-type
+context: webiny-extensions
+description: >
+  How to implement a custom CMS field type that integrates with the model builder's
+  fluent API. Covers extending DataFieldBuilder, composing validator interfaces,
+  creating a FieldTypeFactory, registering via DI, and module augmentation for
+  TypeScript autocomplete on the fields() registry.
+---
+
+# Custom CMS Field Type
+
+## TL;DR
+
+A custom field type is a class that extends `DataFieldBuilder<"yourType">`, paired with a factory class implementing `FieldType.Factory`. Register the factory with `container.register(YourFieldType)`. Add a module augmentation on `"webiny/api/cms/model"` so the `fields` registry method gets TypeScript autocomplete.
+
+## When to Use This
+
+Use a custom field type when:
+
+- You need a field with a storage format or validation logic not covered by the built-in types (`text`, `number`, `boolean`, `datetime`, `file`, `ref`, `object`, `richText`, `longText`, `json`, `dynamicZone`)
+- You want to expose a fluent builder API (e.g., `fields.slug()`, `fields.color()`) in `ModelFactory` implementations
+
+## Field Type Structure
+
+A custom field type consists of three parts:
+
+1. **Builder interface** — extends `DataFieldBuilder<"type">` plus `FieldTypeValidator.*` types
+2. **Builder class** — implements the interface, calls `this.validation()` for each validator
+3. **Factory class** — implements `FieldType.Factory`, creates builder instances
+
+As a standalone extension (not part of a larger feature), the directory layout is:
+
+```
+extensions/
+└── SlugFieldType/
+    ├── SlugFieldType.ts     # builder interface, builder class, factory class
+    └── feature.ts           # createFeature — registers the factory into the DI container
+```
+
+`feature.ts`:
+
+```ts
+// extensions/SlugFieldType/feature.ts
+import { createFeature } from "webiny/api";
+import { SlugFieldType } from "./SlugFieldType.js";
+
+export const SlugFieldTypeFeature = createFeature({
+  name: "SlugFieldType",
+  register(container) {
+    container.register(SlugFieldType);
+  }
+});
+```
+
+Register in the API entry point:
+
+```ts
+// api/Extension.ts
+import { createFeature } from "webiny/api";
+import { SlugFieldTypeFeature } from "~/extensions/SlugFieldType/feature.js";
+
+export const Extension = createFeature({
+  name: "MyExtension",
+  register(container) {
+    SlugFieldTypeFeature.register(container);
+  }
+});
+```
+
+## Complete Example
+
+```ts
+// extensions/SlugFieldType/SlugFieldType.ts
+import { DataFieldBuilder, FieldType } from "webiny/api/cms/model";
+import type { FieldTypeValidator } from "webiny/api/cms/model";
+
+// 1. Builder interface — extends DataFieldBuilder + desired FieldTypeValidator types
+export interface ISlugFieldBuilder
+  extends
+    DataFieldBuilder<"slug">,
+    FieldTypeValidator.Required,
+    FieldTypeValidator.Pattern,
+    FieldTypeValidator.Unique {}
+
+// 2. Module augmentation — adds fields.slug() to the registry
+declare module "webiny/api/cms/model" {
+  interface IFieldBuilderRegistry {
+    slug(): ISlugFieldBuilder;
+  }
+
+  interface IFieldRendererRegistry {
+    myCustomRenderer: {
+      fieldType: "text" | "number";
+      settings: undefined;
+    };
+  }
+}
+
+// 3. Builder class — implements each validator method via this.validation()
+class SlugFieldBuilder extends DataFieldBuilder<"slug"> implements ISlugFieldBuilder {
+  constructor() {
+    super("slug");
+  }
+
+  required(message?: string): this {
+    return this.validation({
+      name: "required",
+      message: message || "Value is required.",
+      settings: {}
+    });
+  }
+
+  pattern(regex: string, flags = "", message?: string): this {
+    return this.validation({
+      name: "pattern",
+      message: message || "Invalid value.",
+      settings: { preset: "custom", regex, flags }
+    });
+  }
+
+  unique(message?: string): this {
+    return this.validation({
+      name: "unique",
+      message: message || "Value must be unique.",
+      settings: {}
+    });
+  }
+}
+
+// 4. Factory class — implements FieldType.Factory
+class SlugFieldTypeFactory implements FieldType.Factory {
+  readonly type = "slug";
+
+  create(): ISlugFieldBuilder {
+    return new SlugFieldBuilder();
+  }
+}
+
+// 5. Export as a FieldType implementation
+export const SlugFieldType = FieldType.createImplementation({
+  implementation: SlugFieldTypeFactory,
+  dependencies: []
+});
+```
+
+## Using the Custom Field in a Model
+
+After registration, `fields.slug()` is available in any `ModelFactory` implementation:
+
+```ts
+import { ModelFactory } from "webiny/api/cms/model";
+
+class ProductModelImpl implements ModelFactory.Interface {
+  async execute(builder: ModelFactory.Builder) {
+    return [
+      builder
+        .public({ modelId: "product", name: "Product", group: "ungrouped" })
+        .fields(fields => ({
+          name: fields.text().label("Name").required(),
+          slug: fields
+            .slug()
+            .label("Slug")
+            .required("Slug is required.")
+            .unique()
+            .pattern("^[a-z0-9-]+$", "", "Only lowercase letters, numbers, and hyphens.")
+        }))
+        .layout([["name", "slug"]])
+        .titleFieldId("name")
+        .singularApiName("Product")
+        .pluralApiName("Products")
+    ];
+  }
+}
+```
+
+## DataFieldBuilder API
+
+All methods return `this` for chaining.
+
+| Method                      | Description                                   |
+| --------------------------- | --------------------------------------------- |
+| `label(text)`               | Field label shown in the Admin editor         |
+| `help(text)`                | Help text shown below the field               |
+| `description(text)`         | Field description                             |
+| `fieldId(id)`               | Override the auto-derived field ID            |
+| `storageId(id)`             | Override the storage identifier               |
+| `placeholder(text)`         | Placeholder text for the input                |
+| `defaultValue(value)`       | Default value for new entries                 |
+| `list()`                    | Make the field accept multiple values (array) |
+| `listMinLength(n, msg?)`    | Minimum number of list items                  |
+| `listMaxLength(n, msg?)`    | Maximum number of list items                  |
+| `tags(tags)`                | Arbitrary tags for filtering/querying         |
+| `renderer(name, settings?)` | Set the Admin UI renderer                     |
+| `settings(settings)`        | Set arbitrary field settings                  |
+
+### Protected Methods (for use inside validator implementations only)
+
+| Method                      | Description                                                        |
+| --------------------------- | ------------------------------------------------------------------ |
+| `this.validation(rule)`     | Append a `CmsModelFieldValidation` to the field's validation array |
+| `this.listValidation(rule)` | Append a `CmsModelFieldValidation` to the list validation array    |
+
+A `CmsModelFieldValidation` has the shape:
+
+```ts
+{
+  name: string; // validator name (e.g., "required", "minLength", "pattern")
+  message: string; // error message shown to the user
+  settings: Record<string, any>; // validator-specific config
+}
+```
+
+## Available Validators
+
+Import via `import type { FieldTypeValidator } from "webiny/api/cms/model"` and extend your builder interface with them. Each type adds one method to your interface:
+
+| Type                                | Method signature                   |
+| ----------------------------------- | ---------------------------------- |
+| `FieldTypeValidator.Required`       | `required(message?)`               |
+| `FieldTypeValidator.Unique`         | `unique(message?)`                 |
+| `FieldTypeValidator.MinLength`      | `minLength(value, message?)`       |
+| `FieldTypeValidator.MaxLength`      | `maxLength(value, message?)`       |
+| `FieldTypeValidator.Pattern`        | `pattern(regex, flags?, message?)` |
+| `FieldTypeValidator.Email`          | `email(message?)`                  |
+| `FieldTypeValidator.Url`            | `url(message?)`                    |
+| `FieldTypeValidator.LowerCase`      | `lowerCase(message?)`              |
+| `FieldTypeValidator.UpperCase`      | `upperCase(message?)`              |
+| `FieldTypeValidator.LowerCaseSpace` | `lowerCaseSpace(message?)`         |
+| `FieldTypeValidator.UpperCaseSpace` | `upperCaseSpace(message?)`         |
+| `FieldTypeValidator.Gte`            | `gte(value, message?)`             |
+| `FieldTypeValidator.Lte`            | `lte(value, message?)`             |
+| `FieldTypeValidator.DateGte`        | `dateGte(value, message?)`         |
+| `FieldTypeValidator.DateLte`        | `dateLte(value, message?)`         |
+| `FieldTypeValidator.ListMinLength`  | `listMinLength(value, message?)`   |
+| `FieldTypeValidator.ListMaxLength`  | `listMaxLength(value, message?)`   |
+
+When implementing a validator method in the builder class, call `this.validation()` with the appropriate `name` and `settings`. For `ListMinLength`/`ListMaxLength`, call `this.listValidation()` instead. The `settings` shapes:
+
+| Validator                    | `name`                        | `settings`                                                                   |
+| ---------------------------- | ----------------------------- | ---------------------------------------------------------------------------- |
+| Required, Unique             | `"required"` / `"unique"`     | `{}`                                                                         |
+| MinLength, MaxLength         | `"minLength"` / `"maxLength"` | `{ value: String(n) }`                                                       |
+| Gte, Lte                     | `"gte"` / `"lte"`             | `{ value: String(n) }`                                                       |
+| DateGte, DateLte             | `"dateGte"` / `"dateLte"`     | `{ value }`                                                                  |
+| Pattern                      | `"pattern"`                   | `{ preset: "custom", regex, flags }`                                         |
+| Email                        | `"pattern"`                   | `{ preset: "email", regex: null, flags: null }`                              |
+| Url                          | `"pattern"`                   | `{ preset: "url", regex: null, flags: null }`                                |
+| LowerCase / UpperCase / etc. | `"pattern"`                   | `{ preset: "lowerCase"` / `"upperCase"` / etc., `regex: null, flags: null }` |
+
+## Key Rules
+
+1. **`type` string must be unique** — the factory's `readonly type` must not collide with any built-in type (`text`, `number`, `boolean`, `datetime`, `file`, `ref`, `object`, `richText`, `longText`, `json`, `dynamicZone`) or other custom types.
+2. **Module augmentation target** — augment `"webiny/api/cms/model"` using `namespace FieldBuilderRegistry { interface Interface { yourType(): IYourFieldBuilder; } }`.
+3. **`validation()` is protected** — never call it from outside the builder class. Expose validators as named methods on the interface (e.g., `required()`, `minLength()`).
+4. **`dependencies: []`** — field type factories have no DI dependencies; always pass an empty array.
+5. **Registration order** — register custom `FieldType` implementations before `FieldBuilderRegistry` is resolved (i.e., in the same `register()` call or before it runs). The registry collects all `FieldType` instances at construction time.
+
+## Related Skills
+
+- **webiny-api-cms-content-models** — Using the model builder's fluent API to define CMS models
+- **webiny-api-cms-catalog** — Full catalog of CMS abstractions including `ModelFactory`, `FieldType`, `DataFieldBuilder`
+- **webiny-dependency-injection** — The `createImplementation` pattern and DI scoping

package/skills/api/event-handler-pattern/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: webiny-event-handler-pattern
+context: webiny-api
+description: >
+  Generic EventHandler implementation pattern — handle method, event payloads, filtering, DI.
+  Use this skill to understand how to implement any Webiny EventHandler (before/after hooks).
+---
+
+# EventHandler Pattern
+
+## What It Is
+
+An **EventHandler** reacts to domain events in the Webiny lifecycle (e.g., `EntryBeforeCreateEventHandler`, `TenantAfterDeleteEventHandler`). Each handler is a DI abstraction with a single `handle` method.
+
+## Naming Convention
+
+- `{Entity}Before{Operation}EventHandler` — fires before persistence, can validate/transform/reject
+- `{Entity}After{Operation}EventHandler` — fires after persistence, for side effects
+
+## Interface Shape
+
+Every EventHandler follows this pattern:
+
+```ts
+interface SomeEventHandler.Interface {
+    handle(event: SomeEventHandler.Event): Promise<void>;
+}
+```
+
+The `Event` is a `DomainEvent<Payload>` where the payload contains the entity and input data.
+
+## Architecture Rule: Always Wrap Logic in a Reusable Abstraction (MANDATORY)
+
+**Never put business logic directly inside an EventHandler.** EventHandlers are thin orchestrators — they receive an event and delegate to an injected service (abstraction). The real logic lives in a dedicated service defined with `createAbstraction` and `createFeature`.
+
+**Why:** Inline handler logic cannot be reused by other handlers, GraphQL resolvers, or CLI commands. Wrapping it in an abstraction makes it injectable, testable, and replaceable.
+
+**Always follow this structure:**
+
+```
+features/
+├── myService/             ← the reusable abstraction
+│   ├── abstractions.ts
+│   ├── feature.ts
+│   └── MyService.ts
+└── myHandler/             ← thin handler that injects the service
+    ├── feature.ts
+    └── MyHandler.ts
+```
+
+The EventHandler feature and the service feature are **registered separately** in `Extension.tsx`.
+
+## How to Implement
+
+```ts
+import { SomeEventHandler } from "webiny/api/<category>";
+import { MyService } from "../myService/abstractions.js";
+
+// ✅ Handler is a thin orchestrator — no business logic here
+class MyHandler implements SomeEventHandler.Interface {
+  constructor(private myService: MyService.Interface) {}
+
+  async handle(event: SomeEventHandler.Event) {
+    const { entity } = event.payload;
+
+    // For CMS handlers: always filter by model
+    // if (entity.modelId !== "myModel") return;
+
+    await this.myService.doWork(entity);
+  }
+}
+
+export default SomeEventHandler.createImplementation({
+  implementation: MyHandler,
+  dependencies: [MyService]
+});
+```
+
+See **webiny-api-architect** for how to define `MyService` as a proper abstraction.
+
+## Injecting Dependencies
+
+EventHandlers can depend on UseCases, platform services, or your own custom abstractions:
+
+```ts
+import { SomeEventHandler } from "webiny/api/<category>";
+import { SomeUseCase } from "webiny/api/<category>";
+
+class MyHandler implements SomeEventHandler.Interface {
+  constructor(private someUseCase: SomeUseCase.Interface) {}
+
+  async handle(event: SomeEventHandler.Event) {
+    const result = await this.someUseCase.execute({
+      /* ... */
+    });
+  }
+}
+
+export default SomeEventHandler.createImplementation({
+  implementation: MyHandler,
+  dependencies: [SomeUseCase]
+});
+```
+
+## Registration
+
+```tsx
+<Api.Extension src={"@/extensions/my-handler.ts"} />
+```
+
+Deploy with: `yarn webiny deploy api --env=dev`
+
+## Resolving Types (MANDATORY)
+
+**Before writing any code that accesses event payload properties or domain types (CmsEntry, CmsModel, etc.), you MUST read the source file listed in the catalog's `Source` field to verify the exact property names and types. Do not assume or guess property names from memory.**
+
+To see the exact event payload types for a specific EventHandler:
+
+1. Read the `abstractions.ts` file from the catalog `Source` path — it contains the payload interface with all property names and types.
+2. Read the `events.ts` file (sibling to `abstractions.ts`) — it contains the `Interface` and `Event` type aliases.
+3. If the payload references domain types (e.g., `CmsEntry`, `CmsModel`), follow the import and read that type declaration too.
+
+Only use properties that are confirmed to exist in the source type declarations.
+
+## Key Rules
+
+- **Before handlers**: payload may be mutable — write to it to set computed fields. Throw to reject the operation.
+- **After handlers**: payload reflects persisted state — do not mutate. Use for side effects.
+- **Filter by entity**: handlers fire for ALL entities of that type. Always check `modelId`, `entity type`, etc.
+- DI constructor parameter order must match the `dependencies` array order exactly
+- Use `.js` extensions in import paths (ES modules)

package/skills/{custom-graphql-api → api/graphql-api}/SKILL.md

@@ -204,6 +204,6 @@ Deploy:       yarn webiny deploy api --env=dev
 
 ## Related Skills
 
-- `api-custom-feature` -- Define custom abstractions and services consumed by resolvers
-- `dependency-injection` -- Full DI reference for all injectable services
-- `project-structure` -- How to register extensions in `webiny.config.tsx`
+- `webiny-api-architect` -- Define custom abstractions, features, and services consumed by resolvers
+- `webiny-dependency-injection` -- Full DI reference for all injectable services
+- `webiny-project-structure` -- How to register extensions in `webiny.config.tsx`