-
Notifications
You must be signed in to change notification settings - Fork 9
add comet-crud Agent skills #5323
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
manuelblum
wants to merge
12
commits into
main
Choose a base branch
from
com-2900/add-crud-skills
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
5391676
add comet-api-graphql skill
manuelblum 283fb88
add comet-admin-translatable-enum
manuelblum 896401b
add comet-admin-datagrid skill
manuelblum 3cd676a
add comet-admin-form-skill
manuelblum 1ec591a
add comet-admin-pages skill
manuelblum 53eba4a
add comet-crud skill
manuelblum fe72d84
Fix skill consistency issues
manuelblum 16873b0
docs: add docs for skills
manuelblum 2c01157
Fix RadioGroupField props type: use RadioGroupFieldProps instead of S…
Copilot d17078b
Fix CheckboxListField skill template: use CheckboxListFieldProps and …
Copilot 7d09517
Use RadioGroupFieldProps instead of SelectFieldProps in RadioGroupFie…
Copilot ab9885b
Fix `onSelectItem` handler in editable chip skill template (#5328)
Copilot File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
88 changes: 88 additions & 0 deletions
88
docs/docs/11-agent-skills/2-comet-crud/1-comet-api-graphql.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| --- | ||
| title: comet-api-graphql | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| The `comet-api-graphql` skill generates the NestJS/GraphQL API layer for a MikroORM entity. It follows the Comet convention of **thin resolvers** (GraphQL layer only) and **fat services** (all business logic). | ||
|
|
||
| ## What It Generates | ||
|
|
||
| - **Entity** — MikroORM entity with decorators, validation, and relations | ||
| - **Service** — CRUD operations, pagination, filtering, sorting | ||
| - **Resolver** — thin GraphQL resolver delegating to the service | ||
| - **DTOs** — input, filter, sort, and args classes | ||
| - **Paginated Response** — `ObjectType` for paginated list queries | ||
| - **Module Registration** — adds the entity, service, and resolver to the NestJS module | ||
|
|
||
| ## Key Features | ||
|
|
||
| - Pagination, filtering, and sorting via `@comet/cms-api` utilities | ||
| - Content scope support for multi-tenant setups | ||
| - Position ordering for sortable entities | ||
| - All relation types: `ManyToOne`, `OneToMany`, `ManyToMany`, `OneToOne` | ||
| - Slug-based queries with unique validation | ||
| - Permission decorators on all resolver methods | ||
|
|
||
| ## Examples | ||
|
|
||
| :::tip | ||
| Skills should trigger automatically based on your prompt. If a skill does not activate as expected, you can force it by prefixing your prompt with "Use the comet-api-graphql skill" (or `/comet-api-graphql`). | ||
| ::: | ||
|
|
||
| ### Minimal — just fields | ||
|
|
||
| > Create the API for a `BlogPost` entity with title, content, author (string), and publishedAt (date). | ||
|
|
||
| The skill will create a scoped entity with a service, resolver, DTOs, and module registration using sensible defaults. | ||
|
|
||
| ### Scoped entity with relations and slug validation | ||
|
|
||
| > Create the API for a `Product` entity scoped by domain + language. | ||
| > | ||
| > **Fields:** name (string, required), slug (string, required, unique per scope), | ||
| > description (string, optional), price (decimal, required), isPublished (boolean, default false), | ||
| > mainImage (DAM image, optional). | ||
| > | ||
| > **Enum** productStatus: Draft, InReview, Published, Archived. | ||
| > | ||
| > **Relations:** ManyToMany to ProductCategory (owner side). | ||
| > | ||
| > **Validation:** Slug uniqueness validated server-side — return field-level error `SLUG_ALREADY_EXISTS`. | ||
| > Price must be positive. | ||
|
|
||
| ### Entity with position ordering and self-reference | ||
|
|
||
| > Create the API for a `ProductCategory` entity scoped by domain + language. | ||
| > | ||
| > **Fields:** name (string, required), slug (string, required, unique per scope), | ||
| > position (number, for manual ordering). | ||
| > | ||
| > **Relations:** ManyToOne to ProductCategory (optional parent for nesting). | ||
|
|
||
| ### Sub-entity scoped via parent relation | ||
|
|
||
| > Create the API for a `ProductVariant` entity scoped via its parent Product relation | ||
| > (use `@ScopedEntity` deriving scope from the product). | ||
| > | ||
| > **Fields:** name (string, required), sku (string, required), price (decimal, required), | ||
| > stock (integer, required, default 0), isAvailable (boolean, default true). | ||
| > | ||
| > **Enum** variantStatus: Active, OutOfStock, Discontinued. | ||
| > | ||
| > **Relations:** ManyToOne to Product (required parent). | ||
| > | ||
| > **Validation:** SKU uniqueness within the parent product — return field-level error `SKU_ALREADY_EXISTS`. | ||
|
|
||
| ### Unscoped entity with relation | ||
|
|
||
| > Create the API for a `ProductReview` entity (not scoped, global). | ||
| > | ||
| > **Fields:** title (string, required), body (string, required), rating enum (One through Five), | ||
| > reviewerName (string, required), reviewedAt (datetime, required), isApproved (boolean, default false). | ||
| > | ||
| > **Relations:** ManyToOne to Product (required). | ||
|
|
||
| ### Add fields to an existing entity | ||
|
|
||
| > Add a `description` text field and a `ManyToOne` relation to `Department` on the `Employee` entity, | ||
| > and update the service, resolver, and DTOs. | ||
58 changes: 58 additions & 0 deletions
58
docs/docs/11-agent-skills/2-comet-crud/2-comet-admin-translatable-enum.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| --- | ||
| title: comet-admin-translatable-enum | ||
| sidebar_position: 2 | ||
| --- | ||
|
|
||
| The `comet-admin-translatable-enum` skill generates React components for displaying and editing GraphQL enums in the Comet admin. It covers translations, colored chips, inline-editable chips, and form field components. | ||
|
|
||
| ## What It Generates | ||
|
|
||
| - **Translation component** — maps enum values to translated labels using `react-intl` | ||
| - **Chip component** — colored `MuiChip` for displaying enum values (e.g., status badges) | ||
| - **Editable chip** — chip with a dropdown menu that triggers an Apollo mutation to change the value inline | ||
| - **Form field components** — `SelectField`, `AutocompleteField`, `RadioGroupField`, `CheckboxListField` | ||
|
|
||
| ## Key Features | ||
|
|
||
| - All components are fully typed against the generated GraphQL enum | ||
| - Chip colors are configurable per enum value | ||
| - Editable chips handle optimistic updates and error states | ||
| - Form fields integrate with Final Form and support validation | ||
|
|
||
| ## Examples | ||
|
|
||
| :::tip | ||
| Skills should trigger automatically based on your prompt. If a skill does not activate as expected, you can force it by prefixing your prompt with "Use the comet-admin-translatable-enum skill" (or `/comet-admin-translatable-enum`). | ||
| ::: | ||
|
|
||
| ### All components at once | ||
|
|
||
| > Create all enum components for `productStatus` | ||
|
|
||
| ### Translation component | ||
|
|
||
| > Create a translation component for `productStatus` | ||
|
|
||
| ### Chip | ||
|
|
||
| > Create a chip for `productStatus` | ||
|
|
||
| ### Editable chip | ||
|
|
||
| > Create an editable chip for `productStatus` on the `Product` entity | ||
|
|
||
| ### Select field | ||
|
|
||
| > Create a select field for `productStatus` | ||
|
|
||
| ### Autocomplete field | ||
|
|
||
| > Create an autocomplete field for `productStatus` | ||
|
|
||
| ### Radio group field | ||
|
|
||
| > Create a radio group field for `productStatus` | ||
|
|
||
| ### Checkbox list field | ||
|
|
||
| > Create a checkbox list field for `productStatus` |
88 changes: 88 additions & 0 deletions
88
docs/docs/11-agent-skills/2-comet-crud/3-comet-admin-datagrid.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| --- | ||
| title: comet-admin-datagrid | ||
| sidebar_position: 3 | ||
| --- | ||
|
|
||
| The `comet-admin-datagrid` skill generates server-side MUI DataGrid components for the Comet admin. All filtering, sorting, searching, and pagination are handled server-side using Apollo Client. | ||
|
|
||
| ## What It Generates | ||
|
|
||
| - DataGrid component with typed columns | ||
| - Server-side pagination, sorting, and filtering via `useDataGridRemote` and `usePaginationQuery` | ||
| - Toolbar with search, filter button, and actions (add, delete) | ||
| - Filter bar components for each filterable field | ||
|
|
||
| ## Key Features | ||
|
|
||
| - Column types: string, boolean, number, date/time, enum (with chips), relations, file uploads | ||
| - Multiple variants: standard paginated, non-paginated, row reordering, sub-entity grids | ||
| - Selection/checkbox mode for bulk actions | ||
| - Excel export support | ||
| - Responsive column visibility | ||
|
|
||
| ## Examples | ||
|
|
||
| :::tip | ||
| Skills should trigger automatically based on your prompt. If a skill does not activate as expected, you can force it by prefixing your prompt with "Use the comet-admin-datagrid skill" (or `/comet-admin-datagrid`). | ||
| ::: | ||
|
|
||
| ### Minimal — no column or filter details | ||
|
|
||
| > Create a datagrid for `BlogPost`. | ||
|
|
||
| The skill reads the entity's GraphQL schema and generates columns, search, and filters based on the available fields. | ||
|
|
||
| ### Paginated grid with editable chips, filters, and Excel export | ||
|
|
||
| > Create a datagrid for `Product`. | ||
| > | ||
| > **Columns:** mainImage (thumbnail, excluded from Excel export), name, sku, productType as editable chip, | ||
| > categories (comma-separated names), price, productStatus as editable chip, publishedAt, isPublished. | ||
| > | ||
| > **Search:** by name and sku. | ||
| > | ||
| > **Filters:** productStatus, productType. | ||
| > | ||
| > **Features:** Excel export enabled. | ||
|
|
||
| ### Partial specification — only columns, no filters | ||
|
|
||
| > Create a datagrid for `Employee` with columns: name, email, department (relation), hiredAt. | ||
|
|
||
| The skill generates the grid with the specified columns. Since no filters or search are mentioned, it will ask or infer reasonable defaults. | ||
|
|
||
| ### Non-paginated grid with row reordering | ||
|
|
||
| > Create a datagrid for `ProductCategory`. | ||
| > | ||
| > **Columns:** name, slug, parentCategory (show parent name). | ||
| > | ||
| > **Variant:** Non-paginated grid with drag-and-drop row reordering. | ||
| > No search or filters — the dataset is small enough to display in full. | ||
|
|
||
| ### Sub-entity grid filtered by parent | ||
|
|
||
| > Create a datagrid for `ProductVariant` as a sub-entity grid of Product. | ||
| > | ||
| > **Columns:** name, sku, price, stock, variantStatus as editable chip, isAvailable. | ||
| > | ||
| > **Search:** by name and sku. | ||
| > | ||
| > The grid is filtered by the parent product ID passed as a prop. | ||
|
|
||
| ### Grid with optional relation filter prop | ||
|
|
||
| > Create a datagrid for `ProductReview`. | ||
| > | ||
| > **Columns:** title, rating, reviewerName, product name, reviewedAt, isApproved. | ||
| > | ||
| > **Search:** by title and reviewerName. | ||
| > | ||
| > **Filters:** product (relation filter with autocomplete), isApproved. | ||
| > | ||
| > **Features:** Excel export. The component accepts an optional `productId` prop | ||
| > to filter reviews for a specific product (for reuse on the Product detail page). | ||
|
|
||
| ### Add a column to an existing grid | ||
|
|
||
| > Add a `variantCount` column to the `Product` datagrid showing the number of variants per product in a grey Chip. |
74 changes: 74 additions & 0 deletions
74
docs/docs/11-agent-skills/2-comet-crud/4-comet-admin-form.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| --- | ||
| title: comet-admin-form | ||
| sidebar_position: 4 | ||
| --- | ||
|
|
||
| The `comet-admin-form` skill generates Final Form components for the Comet admin. All forms support both create and edit modes, save conflict detection, and Apollo Client mutations. | ||
|
|
||
| ## What It Generates | ||
|
|
||
| - Form component using `FinalForm` with `editMode` support | ||
| - Apollo `useQuery` for loading existing data (edit mode) | ||
| - Apollo `useMutation` for create and update operations | ||
| - Field layout using `FieldSet` grouping | ||
| - Save conflict detection via `SaveConflictDialog` | ||
|
|
||
| ## Key Features | ||
|
|
||
| - All `@comet/admin` field components: text, textarea, number, checkbox, switch, select, async autocomplete, date/time pickers | ||
| - File upload fields (Dam image/file) | ||
| - Block fields (rich text, content blocks) | ||
| - Validation with field-level and form-level rules | ||
| - Automatic dirty-checking and unsaved changes warning | ||
|
|
||
| ## Examples | ||
|
|
||
| :::tip | ||
| Skills should trigger automatically based on your prompt. If a skill does not activate as expected, you can force it by prefixing your prompt with "Use the comet-admin-form skill" (or `/comet-admin-form`). | ||
| ::: | ||
|
|
||
| ### Minimal | ||
|
|
||
| > Create a form for `BlogPost`. | ||
|
|
||
| The skill reads the entity's GraphQL schema and generates a form with appropriate field types and a single FieldSet grouping all fields. | ||
|
|
||
| ### Form with FieldSets, DAM image, and client-side validation | ||
|
|
||
| > Create a form for `Product`. | ||
| > | ||
| > **FieldSets:** | ||
| > - "General": name (text), slug (text), description (textarea), categories (AsyncAutocompleteField, multiple) | ||
| > - "Details": sku (text), price (number), productType (SelectField) | ||
| > - "Publishing": productStatus (SelectField), publishedAt (date picker), isPublished (switch) | ||
| > - "Media": mainImage (DAM image) | ||
| > | ||
| > **Validation:** price must be positive (client-side). sku must match format `[A-Z]{2,4}-[0-9]{4,8}` (client-side). | ||
|
|
||
| ### Simple form with single FieldSet and relation | ||
|
|
||
| > Create a form for `ProductCategory`. | ||
| > | ||
| > **FieldSets:** | ||
| > - "General": name (text), slug (text), parentCategory (AsyncSelectField) | ||
|
|
||
| ### Sub-entity form (parent set implicitly) | ||
|
|
||
| > Create a form for `ProductVariant` (sub-entity of Product — the product field is set implicitly from the parent). | ||
| > | ||
| > **FieldSets:** | ||
| > - "General": name (text), sku (text), variantStatus (SelectField) | ||
| > - "Pricing & Stock": price (number), stock (number), isAvailable (switch) | ||
| > | ||
| > **Validation:** price must be positive, stock must be zero or positive integer (client-side). | ||
|
|
||
| ### Dialog-based form | ||
|
|
||
| > Create a form for `ProductReview` rendered inside an EditDialog (no separate page). | ||
| > | ||
| > **Fields:** product (AsyncAutocompleteField, placed at the top), title (text), body (textarea), | ||
| > rating (SelectField), reviewerName (text), reviewedAt (datetime picker), isApproved (checkbox). | ||
|
|
||
| ### Add a field to an existing form | ||
|
|
||
| > Add a `notes` textarea field to the `Product` form in the "General" FieldSet. |
73 changes: 73 additions & 0 deletions
73
docs/docs/11-agent-skills/2-comet-crud/5-comet-admin-pages.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| --- | ||
| title: comet-admin-pages | ||
| sidebar_position: 5 | ||
| --- | ||
|
|
||
| The `comet-admin-pages` skill generates the page structure, navigation, and layout for Comet admin CRUD views. It encodes best practices for Stack-based routing, toolbars, and page composition. | ||
|
|
||
| ## What It Generates | ||
|
|
||
| - Page component with `Stack`, `StackSwitch`, and `StackPage` navigation | ||
| - `StackToolbar` with entity title and actions | ||
| - `StackMainContent` for page body layout | ||
| - `SaveBoundary` placement for form pages | ||
| - `RouterTabs` for multi-tab edit views | ||
| - `EditDialog` for lightweight inline editing | ||
|
|
||
| ## Key Features | ||
|
|
||
| - Decision guide: simple page → grid + dialog → grid + page → edit with tabs → nested CRUD | ||
| - Entity Toolbar pattern with its own GraphQL query, loading/error states, and title display | ||
| - `StackLink` for navigation between list and detail views | ||
| - Breadcrumb-style navigation via Stack | ||
|
|
||
| ## Examples | ||
|
|
||
| :::tip | ||
| Skills should trigger automatically based on your prompt. If a skill does not activate as expected, you can force it by prefixing your prompt with "Use the comet-admin-pages skill" (or `/comet-admin-pages`). | ||
| ::: | ||
|
|
||
| ### Minimal — let the skill decide the layout | ||
|
|
||
| > Create admin pages for `BlogPost`. | ||
|
|
||
| The skill generates a standard grid + edit page layout with StackSwitch and an entity toolbar. | ||
|
|
||
| ### Grid with separate edit page and entity toolbar | ||
|
|
||
| > Create admin pages for `Product`. | ||
| > | ||
| > **Layout:** StackSwitch with grid page, add page, and edit page. | ||
| > | ||
| > **Grid toolbar:** "Add Product" button navigating to the add page. | ||
| > | ||
| > **Entity toolbar:** Shows the product name with the SKU as support text. | ||
| > Includes a delete button. | ||
|
|
||
| ### Edit page with RouterTabs and nested sub-entity | ||
|
|
||
| > Create admin pages for `Product` with an edit page containing RouterTabs: | ||
| > | ||
| > - Tab "Product": the Product form | ||
| > - Tab "Variants": a ProductVariant sub-entity grid with its own nested StackSwitch | ||
| > for add/edit variant pages | ||
| > - Tab "Reviews": a ProductReview grid filtered by the current product | ||
| > | ||
| > The variant edit page shows the variant name in the entity toolbar. | ||
|
|
||
| ### Grid with dialog-based edit (no separate page) | ||
|
|
||
| > Create admin pages for `ProductReview`. | ||
| > | ||
| > **Layout:** Single page with the grid and an EditDialog on the same page. | ||
| > No StackSwitch needed. The dialog opens for both adding and editing. | ||
| > | ||
| > Use `ContentScopeIndicator global` since the entity is unscoped. | ||
|
|
||
| ### Simple grid with edit page (non-paginated) | ||
|
|
||
| > Create admin pages for `ProductCategory`. | ||
| > | ||
| > **Layout:** StackSwitch with grid page and edit page. | ||
| > | ||
| > **Entity toolbar:** Shows the category name. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is something we'll have to discuss, as it isn't the Comet convention (yet): https://docs.comet-dxp.com/docs/coding-guidelines/api-nestjs#service-best-practices.