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

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

@@ -308,6 +308,193 @@ export const DashboardFeature = createFeature({
 
 > **Prefer the typical pattern.** Only use the one-off pattern when the business logic is truly presentation-specific and will never be reused by other features.
 
+## Observable Service Implementation
+
+For long-lived services that hold observable state (e.g., project config, feature flags):
+
+```ts
+import { makeAutoObservable, runInAction } from "mobx";
+import { WcpService as ServiceAbstraction, WcpGateway } from "./abstractions.js";
+
+class WcpServiceImpl implements ServiceAbstraction.Interface {
+    private project: ILicense | null = null;
+
+    constructor(private gateway: WcpGateway.Interface) {
+        makeAutoObservable(this);
+    }
+
+    getProject(): ILicense {
+        return this.project;
+    }
+
+    async loadProject(): Promise<void> {
+        const data = await this.gateway.fetchProject();
+        runInAction(() => {
+            this.project = data;
+        });
+    }
+}
+
+export const WcpService = ServiceAbstraction.createImplementation({
+    implementation: WcpServiceImpl,
+    dependencies: [WcpGateway]
+});
+```
+
+- Registered in **singleton scope** — long-lived, holds state
+- Use `makeAutoObservable(this)` in the constructor
+- Wrap async state mutations in `runInAction`
+
+## Repository Implementation
+
+Repositories own domain data and cache. They use MobX for reactivity:
+
+```ts
+import { makeAutoObservable, runInAction } from "mobx";
+import {
+    NextjsConfigRepository as RepositoryAbstraction,
+    NextjsConfigGateway,
+    NextjsConfig
+} from "./abstractions.js";
+
+class NextjsConfigRepositoryImpl implements RepositoryAbstraction.Interface {
+    private config: NextjsConfig | undefined = undefined;
+
+    constructor(private gateway: NextjsConfigGateway.Interface) {
+        makeAutoObservable(this);
+    }
+
+    getConfig(): NextjsConfig | undefined {
+        return this.config;
+    }
+
+    async loadConfig(): Promise<void> {
+        if (this.config) {
+            return; // Already loaded — cache hit
+        }
+
+        const config = await this.gateway.getConfig();
+        runInAction(() => {
+            this.config = config;
+        });
+    }
+}
+
+export const NextjsConfigRepository = RepositoryAbstraction.createImplementation({
+    implementation: NextjsConfigRepositoryImpl,
+    dependencies: [NextjsConfigGateway]
+});
+```
+
+## Gateway Implementation (GraphQL)
+
+Gateways handle external I/O. Use `GraphQLClient` for GraphQL calls:
+
+```ts
+import { NextjsConfigGateway as GatewayAbstraction } from "./abstractions.js";
+import { GraphQLClient } from "@webiny/app/features/graphqlClient";
+
+const GET_NEXTJS_CONFIG = /* GraphQL */ `
+    query GetNextjsConfig {
+        websiteBuilder {
+            getNextjsConfig {
+                data
+                error { code message data }
+            }
+        }
+    }
+`;
+
+type GetNextjsConfigResponse = {
+    websiteBuilder: {
+        getNextjsConfig:
+            | { data: string; error: null }
+            | { data: null; error: { code: string; message: string; data: any } };
+    };
+};
+
+class NextjsGraphQLGateway implements GatewayAbstraction.Interface {
+    constructor(private client: GraphQLClient.Interface) {}
+
+    async getConfig(): Promise<string> {
+        const response = await this.client.execute<GetNextjsConfigResponse>({
+            query: GET_NEXTJS_CONFIG
+        });
+
+        const envelope = response.websiteBuilder.getNextjsConfig;
+        if (envelope.error) {
+            throw new Error(envelope.error.message);
+        }
+
+        return envelope.data;
+    }
+}
+
+export const NextjsConfigGateway = GatewayAbstraction.createImplementation({
+    implementation: NextjsGraphQLGateway,
+    dependencies: [GraphQLClient]
+});
+```
+
+**Key points:**
+- Define the GraphQL query as a string constant with `/* GraphQL */` comment for syntax highlighting
+- Type the response shape explicitly
+- Handle the `data`/`error` envelope pattern
+- Inject `GraphQLClient` from `@webiny/app/features/graphqlClient`
+
+## Composite Features (Aggregating Child Features)
+
+When grouping related features, create a composite with no `resolve`:
+
+```ts
+import { createFeature } from "webiny/admin";
+
+export const FoldersFeature = createFeature({
+    name: "Folders",
+    register(container) {
+        CreateFolderFeature.register(container);
+        UpdateFolderFeature.register(container);
+        DeleteFolderFeature.register(container);
+    }
+});
+```
+
+## Extending Features (Decorators)
+
+Decorators add cross-cutting concerns without modifying the core implementation:
+
+```ts
+class ListFoldersUseCaseWithLoading implements UseCaseAbstraction.Interface {
+    constructor(
+        private loadingRepository: FoldersLoadingRepository.Interface,
+        private decoratee: UseCaseAbstraction.Interface  // decoratee is LAST
+    ) {}
+
+    async execute() {
+        await this.loadingRepository.runCallBack(
+            this.decoratee.execute(),
+            LoadingActionsEnum.list
+        );
+    }
+}
+```
+
+Register with `container.registerDecorator()`:
+
+```ts
+export const MyExtensionFeature = createFeature({
+    name: "MyExtension",
+    register(container) {
+        container.registerDecorator(MyPresenterDecorator);
+    }
+});
+```
+
+**Rules:**
+- Implements the same interface as the decorated abstraction
+- Constructor: extra dependencies first, `decoratee` **last**
+- The `dependencies` array does NOT include the decoratee
+
 ## Reading Admin BuildParams
 
 There are two ways to read build parameters on the Admin side:
@@ -384,6 +571,7 @@ Creates a feature definition for the admin runtime.
 
 ## Related Skills
 
+- **webiny-admin-permissions** — Admin permission UI registration (Security.Permissions schema, custom UIs)
 - **webiny-full-stack-architect** — Top-level component, shared domain layer, BuildParam declarations
 - **webiny-dependency-injection** — The `createImplementation` DI pattern and injectable services
 - **webiny-admin-ui-extensions** — Admin UI customization, decorators, theming, forms, and config

package/skills/admin/admin-permissions/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: webiny-admin-permissions
+context: webiny-extensions
+description: >
+  Admin-side permission UI registration using Security.Permissions. Use this skill when
+  adding permission controls to the admin UI — schema-based auto-generated forms, custom
+  permission UIs with usePermissionValue/usePermissionForm, entity dependencies, and
+  the Security.Permissions component props. Covers both simple apps and complex
+  multi-entity permission schemas.
+---
+
+# Admin Permissions UI
+
+## Overview
+
+Register permissions via `AdminConfig` + `Security.Permissions`. The framework auto-generates the UI from a schema and handles serialization. No form code needed for most apps.
+
+## Schema-Based (Auto-Generated UI)
+
+```tsx
+import React from "react";
+import { AdminConfig } from "@webiny/app-admin";
+import { ReactComponent as Icon } from "@webiny/icons/shield.svg";
+
+const { Security } = AdminConfig;
+
+export const MyPermission = () => {
+  return (
+    <AdminConfig>
+      <Security.Permissions
+        name="store-manager"
+        title="Store Manager"
+        description="Manage Store Manager permissions."
+        icon={<Icon />}
+        schema={{
+          prefix: "sm",
+          fullAccess: { name: "sm.*" },
+          entities: [
+            {
+              id: "product",
+              title: "Products",
+              permission: "sm.product",
+              scopes: ["full", "own"],
+              actions: [
+                { name: "rwd" },
+                { name: "pw" },
+                { name: "import", label: "Import products" },
+                { name: "export", label: "Export products" }
+              ]
+            },
+            {
+              id: "category",
+              title: "Categories",
+              permission: "sm.category",
+              scopes: ["full"],
+              actions: [{ name: "rwd" }]
+            },
+            {
+              id: "settings",
+              title: "Settings",
+              permission: "sm.settings",
+              scopes: ["full"]
+            }
+          ]
+        }}
+      />
+    </AdminConfig>
+  );
+};
+```
+
+Render `<MyPermission />` anywhere in your app's extension component.
+
+## Schema Reference
+
+| Field        | Type                 | Required | Description                                                    |
+| ------------ | -------------------- | -------- | -------------------------------------------------------------- |
+| `prefix`     | `string`             | Yes      | Permission prefix (e.g., `"sm"`)                               |
+| `fullAccess` | `{ name: string }`   | Yes      | Permission emitted on "Full access" (e.g., `{ name: "sm.*" }`) |
+| `entities`   | `EntityDefinition[]` | No       | Entity definitions. Omit for binary full/no access.            |
+
+### Entity Definition
+
+| Field        | Type                                   | Required | Description                                    |
+| ------------ | -------------------------------------- | -------- | ---------------------------------------------- |
+| `id`         | `string`                               | Yes      | Unique identifier for form field naming        |
+| `title`      | `string`                               | No       | Display title. Falls back to `id`.             |
+| `permission` | `string`                               | Yes      | Permission name emitted (e.g., `"sm.product"`) |
+| `scopes`     | `("full" \| "own")[]`                  | Yes      | Available access scopes                        |
+| `actions`    | `ActionDefinition[]`                   | No       | Actions on this entity                         |
+| `dependsOn`  | `{ entity: string; requires: string }` | No       | Dependency on another entity                   |
+
+### Actions
+
+- `{ name: "rwd" }` — Read/Write/Delete select dropdown. Auto-set to `"rwd"` when scope is `"own"`.
+- `{ name: "pw" }` — Publish/Unpublish checkbox group.
+- `{ name: "custom", label: "Label" }` — Custom boolean flag.
+
+### Entity Dependencies
+
+Child entities can depend on a parent. If the parent lacks the required action, the child is pruned from output. `"own"` scope cascades to dependents.
+
+```ts
+{
+    id: "review",
+    permission: "sm.review",
+    scopes: ["full", "own"],
+    actions: [{ name: "rwd" }],
+    dependsOn: { entity: "product", requires: "r" }
+}
+```
+
+---
+
+## Simple Apps (No Entities)
+
+Omit `entities` for binary full/no access:
+
+```tsx
+<Security.Permissions
+  name="my-app"
+  title="My App"
+  description="Manage My App access permissions."
+  schema={{ prefix: "ma", fullAccess: { name: "ma.*" } }}
+/>
+```
+
+---
+
+## `Security.Permissions` Props
+
+| Prop          | Type               | Required                  | Description                                     |
+| ------------- | ------------------ | ------------------------- | ----------------------------------------------- |
+| `name`        | `string`           | Yes                       | Unique identifier for this permission renderer  |
+| `title`       | `string`           | Yes                       | Display title in the accordion header           |
+| `description` | `string`           | No                        | Description shown below the title               |
+| `icon`        | `ReactElement`     | No                        | Icon in the accordion header                    |
+| `schema`      | `PermissionSchema` | One of `schema`/`element` | Auto-generate UI from schema                    |
+| `element`     | `ReactElement`     | One of `schema`/`element` | Fully custom permission UI                      |
+| `system`      | `boolean`          | No                        | If `true`, renders before app-level permissions |
+
+---
+
+## Matching API-Side Permissions
+
+The admin schema and the API-side `createPermissions` schema should use the **same prefix, entity IDs, and action names**. This ensures the permissions emitted by the admin UI are correctly evaluated by the API.
+
+```
+Admin:  schema={{ prefix: "sm", entities: [{ id: "product", permission: "sm.product", ... }] }}
+API:    createPermissions({ prefix: "sm", entities: [{ id: "product", permission: "sm.product", ... }] })
+```
+
+See **webiny-api-permissions** for the API-side implementation.
+
+## Related Skills
+
+- **webiny-api-permissions** — API-side permission checking (canRead, canEdit, etc.)
+- **webiny-admin-architect** — Admin architecture, headless and presentation features
+- **webiny-admin-ui-extensions** — Admin UI customization, decorators, config