@axinom/mosaic-agent-skills 0.0.1

package/skills/_shared/discovery/extract-entity-features.md

@@ -0,0 +1,565 @@
+---
+name: extract-entity-features
+input:
+  - Entity name (PascalCase)
+  - schemaPath
+  - serviceName
+output:
+  - EntityFeatures object
+---
+
+# Extract Entity Features
+
+## EntityFeatures Structure
+
+```typescript
+/**
+ * Identity used for file/folder names, routes, registration labels, URLs
+ */
+interface IdentityFeatures {
+  /**
+   * PascalCase singular - entity name as-is
+   * @example "Movie", "TvShow"
+   */
+  name: string;
+
+  /**
+   * PascalCase plural - pluralize entity name
+   * @example "Movies", "TvShows"
+   */
+  namePlural: string;
+
+  /**
+   * camelCase singular - lowercase first character
+   * @example "movie", "tvShow"
+   */
+  camelCase: string;
+
+  /**
+   * camelCase plural - pluralize camelCase form
+   * @example "movies", "tvShows"
+   */
+  camelCasePlural: string;
+
+  /**
+   * kebab-case plural for routes - lowercase with hyphens
+   * @example "movies", "tv-shows"
+   */
+  kebabCasePlural: string;
+
+  /**
+   * Main display field - look for field named `title` or `name` in entity type
+   * @example "title" (Movie), "name" (Account), "label" (Tag)
+   */
+  titleField: string;
+
+  /**
+   * User-facing display text for the entity name
+   * @example "Movie" (Movie), "Tv Show" (TvShow), "Service Account" (ServiceAccount)
+   */
+  displayText: string;
+
+  /**
+   * ID field type - check `id` field type in entity type definition
+   * @example "Int" (most entities), "UUID" (some entities)
+   */
+  idType: 'Int' | 'UUID';
+}
+
+/**
+ * GraphQL type names extracted from the GQL Schema for the Entity
+ */
+interface SchemaNames {
+  /**
+   * Entity `type` name
+   * @example "Movie", "Episode", "Genre"
+   */
+  entity: string;
+
+  /**
+   * Filter `input` type - pattern: `{Entity}Filter`
+   * @example "MovieFilter", "EpisodeFilter"
+   */
+  filter: string;
+
+  /**
+   * OrderBy `enum` - pattern: `{Plural}OrderBy`
+   * @example "MoviesOrderBy", "EpisodesOrderBy"
+   */
+  orderBy: string;
+
+  /**
+   * Condition `input` type - pattern: `{Entity}Condition`
+   * @example "MovieCondition", "EpisodeCondition"
+   */
+  condition: string;
+
+  /**
+   * Connection `type` - pattern: `{Plural}Connection`
+   * @example "MoviesConnection", "EpisodesConnection"
+   */
+  connection: string;
+
+  /**
+   * Input type - pattern: `{Entity}Input` (if exists in schema)
+   * @example "MovieInput", "EpisodeInput"
+   */
+  input?: string;
+
+  /**
+   * Patch type - pattern: `{Entity}Patch` (if exists in schema)
+   * @example "MoviePatch", "EpisodePatch"
+   */
+  patch?: string;
+}
+
+/**
+ * GraphQL Query field names for the entity - check queries: `{camelPlural}` and `{camel}`
+ */
+interface QueryNames {
+  list?: {
+    /**
+     * Query field name - pattern: `{camelPlural}`
+     * @example "movies", "episodes", "collections"
+     */
+    field: string;
+
+    /**
+     * Return type extracted from query definition
+     * @example "MoviesConnection", "EpisodesConnection"
+     */
+    returnType: string;
+  };
+  single?: {
+    /**
+     * Query field name - pattern: `{camel}`
+     * @example "movie", "episode", "collection"
+     */
+    field: string;
+
+    /**
+     * Return type extracted from query definition
+     * @example "Movie", "Episode", "Collection"
+     */
+    returnType: string;
+  };
+}
+
+/**
+ * GraphQL Mutation field names for the entity
+ */
+interface MutationNames {
+  /**
+   * Single entity create mutation - pattern: `create{Entity}`
+   * @example "createMovie", "createEpisode"
+   */
+  create?: string;
+
+  /**
+   * Single entity update mutation - pattern: `update{Entity}`
+   * @example "updateMovie", "updateEpisode"
+   */
+  update?: string;
+
+  /**
+   * Single entity delete mutation - pattern: `delete{Entity}`
+   * @example "deleteMovie", "deleteEpisode"
+   */
+  delete?: string;
+
+  /**
+   * Bulk edit mutation - pattern: `bulkEdit{Plural}Async`
+   * @example "bulkEditMoviesAsync", "bulkEditEpisodesAsync"
+   */
+  bulkEdit?: string;
+
+  /**
+   * Bulk action mutations - search for `Mutation.{verb}{Plural}` pattern
+   * @example ["deleteMovies", "publishMovies", "unpublishMovies", "archiveMovies"]
+   */
+  bulkActions?: string[];
+}
+
+/**
+ * GraphQL Subscription for the entity - check subscription: `{camel}Mutated`
+ */
+interface SubscriptionNames {
+  mutated?: {
+    /**
+     * Subscription field name - pattern: `{camel}Mutated`
+     * @example "movieMutated", "episodeMutated"
+     */
+    field: string;
+
+    /**
+     * Payload type extracted from subscription definition
+     * @example "MovieSubscriptionPayload", "EpisodeSubscriptionPayload"
+     */
+    payloadType: string;
+
+    /**
+     * Event key enum - pattern: `{Entity}SubscriptionEventKey`
+     * @example "MovieSubscriptionEventKey", "EpisodeSubscriptionEventKey"
+     */
+    eventKeyEnum: string;
+  };
+}
+
+interface MutationFeatures {
+  /**
+   * True if `create{Entity}` mutation exists
+   */
+  create: boolean;
+
+  /**
+   * True if `update{Entity}` mutation exists
+   */
+  update: boolean;
+
+  /**
+   * True if `delete{Entity}` mutation exists
+   */
+  delete: boolean;
+
+  /**
+   * True if `bulkEdit{Plural}Async` mutation exists
+   */
+  bulkEdit: boolean;
+
+  /**
+   * True if any bulk action mutations found (pattern: `{verb}{Plural}`)
+   */
+  bulkActions: boolean;
+}
+
+interface QueryFeatures {
+  /**
+   * True if list query (`{camelPlural}`) exists
+   */
+  list: boolean;
+
+  /**
+   * True if single query (`{camel}`) exists
+   */
+  single: boolean;
+
+  /**
+   * True if subscription (`{camel}Mutated`) exists
+   */
+  subscription: boolean;
+}
+
+/**
+ * Image management capability for the entity - look for `{camel}Images` connection and `{Entity}ImageType` enum
+ */
+interface ImageFeatures {
+  /**
+   * Connection field name - pattern: `{camel}Images`
+   * @example "moviesImages", "episodesImages"
+   */
+  connectionField: string;
+
+  /**
+   * Node type - pattern: `{Plural}Image`
+   * @example "MoviesImage", "EpisodesImage"
+   */
+  nodeType: string;
+
+  /**
+   * Image type enum - pattern: `{Entity}ImageType`
+   * @example "MovieImageType", "EpisodeImageType"
+   */
+  imageTypeEnum: string;
+
+  /**
+   * Enum values extracted from type definition
+   * @example ["COVER", "TEASER"]
+   */
+  imageTypeValues: string[];
+
+  /**
+   * Entity scope for image management (camelCase)
+   * @example "movie", "episode"
+   */
+  scope: string;
+}
+
+/**
+ * Video management capability for the entity - look for `mainVideoId` field and `{camel}Trailers` connection
+ */
+interface VideoFeatures {
+  /**
+   * Main video field (check entity type for this field)
+   * @example "mainVideoId"
+   */
+  mainVideoField?: string;
+
+  /**
+   * Trailers connection field - pattern: `{camel}Trailers`
+   * @example "moviesTrailers", "episodesTrailers"
+   */
+  trailersConnection?: string;
+
+  /**
+   * Trailers node type - pattern: `{Plural}Trailer`
+   * @example "MoviesTrailer", "EpisodesTrailer"
+   */
+  trailersNodeType?: string;
+}
+
+interface CapabilityFeatures {
+  images?: ImageFeatures;
+  videos?: VideoFeatures;
+}
+
+interface ScalarFieldConfig {
+  /**
+   * Field name from entity type
+   * @example "title", "name", "id", "description"
+   */
+  name: string;
+
+  /**
+   * GraphQL scalar type
+   * @example "String", "Int", "Date", "Datetime", "Boolean", "UUID", "Enum"
+   */
+  type: string;
+
+  /**
+   * True if field is non-nullable (ends with `!`)
+   * @example true for "title: String!", false for "synopsis: String"
+   */
+  isRequired: boolean;
+
+  /**
+   * True if field exists in {Entity}Patch type (can be updated)
+   * Check if field appears in the Patch type definition
+   * @example true for "description", false for "publishStatus", "createdDate"
+   */
+  isUpdatable: boolean;
+
+  /**
+   * Validation constraints extracted from field description in Input/Patch types
+   */
+  constraints?: {
+    /**
+     * Minimum length for string fields - parse from @minLength directive
+     * @example 3 (from "@minLength(3)")
+     */
+    minLength?: number;
+
+    /**
+     * Maximum length for string fields - parse from @maxLength directive
+     * @example 100 (from "@maxLength(100)")
+     */
+    maxLength?: number;
+  };
+
+  /**
+   * Semantic hint detected from field name - used for custom renderers
+   * @example "duration" (for durationInSeconds), "fileSize" (for sizeInBytes)
+   */
+  semanticHint?: 'duration' | 'currency' | 'percentage' | 'fileSize';
+
+  /**
+   * Enum type name if field is enum
+   * @example "PublishStatus", "MovieImageType"
+   */
+  enumType?: string;
+
+  /**
+   * True for Enum fields that are NOT found in the Patch/Input types, meaning they're controlled via mutations
+   * @example true for "approvalStatus"
+   */
+  isMutationControlled?: boolean;
+}
+
+/**
+ * TagLike: connection where nodes have simple scalar display field
+ * Pattern: `{entity}{AssociationPlural}` → nodes have direct scalar field
+ * @example moviesTags { nodes { name } }, moviesCasts { nodes { name } }
+ */
+interface TagLikeAssociation {
+  /**
+   * Connection field name from entity type
+   * @example "moviesTags", "moviesCasts"
+   */
+  connectionField: string;
+
+  /**
+   * Node type extracted from connection
+   * @example "MoviesTag", "MoviesCast"
+   */
+  nodeType: string;
+
+  /**
+   * OrderBy type - pattern: `{PascalConnection}OrderBy`
+   * @example "MoviesTagsOrderBy", "MoviesCastsOrderBy"
+   */
+  orderByType: string;
+
+  /**
+   * Display field - look for `name` or `title` in node type
+   * @example "name"
+   */
+  displayField: string;
+
+  /**
+   * Humanized label for UI
+   * @example "Tags", "Casts", "Production Countries"
+   */
+  label: string;
+}
+
+/**
+ * ManyToMany: junction connection where nodes have nested relation
+ * Pattern: `{entity}{Junction}` → nodes have field pointing to related entity
+ * @example moviesMovieGenres { nodes { movieGenres { title } } }
+ */
+interface ManyToManyAssociation {
+  /**
+   * Connection field name from entity type
+   * @example "moviesMovieGenres"
+   */
+  connectionField: string;
+
+  /**
+   * Junction type extracted from connection
+   * @example "MoviesMovieGenre"
+   */
+  junctionType: string;
+
+  /**
+   * Junction OrderBy - pattern: `{PascalConnection}OrderBy`
+   * @example "MoviesMovieGenresOrderBy"
+   */
+  junctionOrderByType: string;
+
+  /**
+   * Related field in junction - find non-ID field pointing to related entity
+   * @example "movieGenres" (field in MoviesMovieGenre type)
+   */
+  relatedField: string;
+
+  /**
+   * Related entity type
+   * @example "MovieGenre"
+   */
+  relatedType: string;
+
+  /**
+   * Related query field - pluralized camelCase of related type
+   * @example "movieGenres" (Query field for fetching options)
+   */
+  relatedQueryField: string;
+
+  /**
+   * Related OrderBy - pattern: `{RelatedPlural}OrderBy` (NO entity prefix)
+   * @example "MovieGenresOrderBy" (not MoviesMovieGenresOrderBy)
+   */
+  relatedOrderByType: string;
+
+  /**
+   * Display field - look for `title` or `name` in related type
+   * @example "title"
+   */
+  displayField: string;
+
+  /**
+   * Humanized label for UI
+   * @example "Genres"
+   */
+  label: string;
+}
+
+interface FieldFeatures {
+  /**
+   * All the directly defined fields of the entity
+   * except the audit fields & association (TagLike, ManyToMany) fields
+   */
+  scalars: ScalarFieldConfig[];
+
+  associations: {
+    /**
+     * TagLike associations - `1:M` connections with simple scalar display field
+     * @example moviesTags, moviesCasts, moviesProductionCountries
+     */
+    tagLike: TagLikeAssociation[];
+
+    /**
+     * ManyToMany associations - `M:N` connections through junction tables
+     * @example moviesMovieGenres (Movie ←→ MovieGenre)
+     */
+    manyToMany: ManyToManyAssociation[];
+  };
+
+  /**
+   * Audit fields - check entity type for these timestamp/user fields
+   */
+  audit: {
+    /**
+     * True if entity has a `createdDate` or a `createdAt` field
+     */
+    createdDate: boolean;
+
+    /**
+     * True if entity has a `createdUser` or a `createdBy` field
+     */
+    createdUser: boolean;
+
+    /**
+     * True if entity has a `updatedDate` or a `updatedAt` field
+     */
+    updatedDate: boolean;
+
+    /**
+     * True if entity has a `updatedUser` or a `updatedBy` field
+     */
+    updatedUser: boolean;
+  };
+}
+
+/**
+ * Service metadata - extract from entity type description and service context
+ */
+interface ServiceFeatures {
+  /**
+   * Service ID - pattern: `{serviceName}-service`
+   * @example "media-service", "catalog-service", "channel-service"
+   */
+  serviceId: string;
+
+  /**
+   * Permissions - parse from `@permissions` directive in entity type description
+   * Format: `"""@permissions: PERM1,PERM2,PERM3"""`
+   * @example ["MOVIES_VIEW", "MOVIES_EDIT", "ADMIN"]
+   */
+  permissions: string[];
+}
+
+type EntityFeatures = IdentityFeatures & {
+  schema: SchemaNames;
+  queries: QueryFeatures & { names: QueryNames };
+  mutations: MutationFeatures & { names: MutationNames };
+  subscriptions: SubscriptionNames;
+  capabilities: CapabilityFeatures;
+  fields: FieldFeatures;
+  service: ServiceFeatures;
+};
+```
+
+## Extraction Process
+
+- Use below GQL parsing MCP schema tools to extract entity information from
+  GraphQL schema and build the `EntityFeatures` object following the structure
+  above.
+  - `search_schema`
+  - `get_type_definitions`
+  - `get_query_fields`
+  - `get_mutation_fields`
+  - `get_subscription_fields`
+
+# Present Features
+
+After you have extracted the completed entity features, you MUST print the final
+`EntityFeatures` object so the user is aware of the root of all decisions

package/skills/generate-create-station/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: generate-create-station
+description: |
+  Generates a Create station for a Mosaic entity from scratch using
+  components from the `@axinom/mosaic-ui` library and GraphQL schema
+  introspection.
+
+  This skill is SELF-CONTAINED with all conventions, naming patterns, code
+  structures, and templates defined in its `references`. The skill's templates
+  and conventions are the AUTHORITATIVE source - rely on them as the primary
+  guide for all generation decisions.
+
+  Use the `get_skill_references` to retrieve ALL reference
+  files mentioned in the steps below BEFORE starting any code generation.
+allowed-tools:
+  - search_schema
+  - get_type_definitions
+  - get_query_fields
+  - get_mutation_fields
+  - get_subscription_fields
+  - list_skills
+  - get_skill
+  - get_skill_references
+  - execute_skill
+---
+
+# Generate Create Station
+
+## Input
+
+**Entity name** (PascalCase): e.g., "Movie", "Product", "ServiceAccount"
+
+## Output
+
+Complete create station with:
+
+- Create form component with create mutation and navigation
+- GraphQL create mutation
+- Breadcrumb resolver
+- Route registration
+- Explorer integration (onCreateAction)
+
+## Steps
+
+### 1. Discover Project Paths → `../_shared/discovery/discover-paths.md`
+
+Discover: schema path, apollo client, generated types path, workflows path,
+service name
+
+### 2. Extract Entity Features → `../_shared/discovery/extract-entity-features.md`
+
+Extract `EntityFeatures` from schema using MCP tools (fields, mutations, schema
+types)
+
+**Key for Create:** `schema.input` type contains all input fields with
+`isRequired` property
+
+### 3. Generate GraphQL Operations → `refs/templates/graphql-operations.md`
+
+Generate `.graphql` file with create mutation returning `id` and `titleField`
+
+### 4. Run Codegen → `../_shared/actions/typescript-codegen.md`
+
+Generate TypeScript types from GraphQL operations
+
+### 5. Generate Create Form Station
+
+#### 5.1. Read Field Component Mapping → `../_shared/conventions/field-component-mapping.md`
+
+Reference for component selection rules (String → TextField, Int → TextField
+with type="number", etc.)
+
+#### 5.2. Read Field Validation Schema → `../_shared/conventions/field-validation-schema.md`
+
+Reference for Yup validation patterns (required, maxLength, integer, etc.)
+
+#### 5.3. Generate Create Component → `refs/templates/create-form-station.md`
+
+Generate `{Entity}Create.tsx` with Create component, validation, mutation,
+navigation, and breadcrumb
+
+### 6. Register Station → `refs/finalization/station-registration.md`
+
+Register create route and update explorer's `onCreateAction` (if explorer
+exists)
+
+### 7. Validate TypeScript → `../_shared/actions/typescript-validation.md`
+
+Run `tsc --noEmit` to verify all generated files compile successfully
+
+### 8. Print Summary → `../_shared/actions/execution-summary.md`
+
+Display execution summary with generated files, routes, fields, TODOs