@axinom/mosaic-agent-skills 0.0.1

package/skills/generate-details-station/refs/templates/graphql-operations.md

@@ -0,0 +1,256 @@
+---
+name: graphql-operations
+input:
+  - EntityFeatures
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Details/{Entity}Details.graphql'
+    description:
+      'GraphQL query, mutations, and search queries for details station'
+---
+
+# Generate GraphQL File
+
+Single file with entity query, update/delete mutations, search queries for
+autocomplete.
+
+## Template
+
+```graphql
+# Main query - fetch complete entity data
+query {features.name}($id: {features.idType}!) {
+  {features.camelCase}(id: $id) {
+    # ID field
+    id
+
+    # Scalar fields from features.fields.scalars[]
+    # For each scalar in features.fields.scalars:
+    {scalar.name}
+
+    # TagLike associations from features.fields.associations.tagLike[]
+    # For each tagLike in features.fields.associations.tagLike:
+    {tagLike.connectionField} {
+      nodes {
+        {tagLike.displayField}
+      }
+    }
+
+    # ManyToMany associations from features.fields.associations.manyToMany[]
+    # For each manyToMany in features.fields.associations.manyToMany:
+    {manyToMany.connectionField} {
+      nodes {
+        {manyToMany.relatedField} {
+          {manyToMany.displayField}
+        }
+      }
+    }
+
+    # If features.capabilities.images exists:
+    {features.capabilities.images.connectionField} {
+      nodes {
+        imageType
+        imageId
+      }
+    }
+
+    # If features.capabilities.videos.mainVideoField exists:
+    {features.capabilities.videos.mainVideoField}
+
+    # If features.capabilities.videos.trailersConnection exists:
+    {features.capabilities.videos.trailersConnection} {
+      totalCount
+    }
+
+    # Audit fields
+    createdDate
+    createdUser
+    updatedDate
+    updatedUser
+  }
+
+  # If manyToMany associations exist, fetch global lookup data:
+  # For each manyToMany in features.fields.associations.manyToMany:
+  {manyToMany.relatedQueryField} {
+    nodes {
+      {manyToMany.displayField}
+      id
+    }
+  }
+}
+
+# Update mutation
+mutation Update{features.name}($input: Update{features.name}Input!) {
+  update{features.name}(input: $input) {
+    clientMutationId
+    {features.camelCase} {
+      id
+      {features.titleField}
+    }
+  }
+}
+
+# Delete mutation (if features.mutations.delete === true)
+mutation Delete{features.name}($input: Delete{features.name}Input!) {
+  delete{features.name}(input: $input) {
+    clientMutationId
+  }
+}
+
+# Breadcrumb query - minimal fields for breadcrumb display
+query {features.name}Title($id: {features.idType}!) {
+  {features.camelCase}(id: $id) {
+    id
+    {features.titleField}
+  }
+}
+
+# Search queries for autocomplete (TagLike associations only)
+# For each tagLike in features.fields.associations.tagLike:
+# Use pattern: get{PascalConnectionField}Values helper query
+query Search{features.name}{tagLike.label}($searchKey: String!, $limit: Int!) {
+  get{PascalCase(tagLike.connectionField)}Values(
+    filter: { startsWithInsensitive: $searchKey }
+    first: $limit
+  ) {
+    nodes
+  }
+}
+```
+
+## Field Selection Rules
+
+Include in main query:
+
+- All `features.fields.scalars[]` fields (user-editable scalars)
+- All `features.fields.associations.tagLike[]` connections
+- All `features.fields.associations.manyToMany[]` connections
+- Image/video capability fields if present
+- Audit fields (`createdDate`, `createdUser`, `updatedDate`, `updatedUser`)
+- Always: `id`, `titleField`, `nameField` (unique identifier fields)
+
+**Note:** `features.fields.scalars` already excludes mutation-controlled fields
+(marked with `scalar.isMutationControlled === true` during extraction)
+
+## Example
+
+```graphql
+query Movie($id: Int!) {
+  movie(id: $id) {
+    id
+    title
+    originalTitle
+    synopsis
+    description
+    externalId
+    released
+    studio
+
+    moviesTags {
+      nodes {
+        name
+      }
+    }
+
+    moviesMovieGenres {
+      nodes {
+        movieGenres {
+          title
+        }
+      }
+    }
+
+    moviesCasts {
+      nodes {
+        name
+      }
+    }
+
+    moviesProductionCountries {
+      nodes {
+        name
+      }
+    }
+
+    moviesImages {
+      nodes {
+        imageType
+        imageId
+      }
+    }
+
+    mainVideoId
+
+    moviesTrailers {
+      totalCount
+    }
+
+    createdDate
+    createdUser
+    updatedDate
+    updatedUser
+  }
+
+  movieGenres {
+    nodes {
+      title
+      id
+    }
+  }
+}
+
+mutation UpdateMovie($input: UpdateMovieInput!) {
+  updateMovie(input: $input) {
+    clientMutationId
+    movie {
+      id
+      title
+    }
+  }
+}
+
+mutation DeleteMovie($input: DeleteMovieInput!) {
+  deleteMovie(input: $input) {
+    clientMutationId
+  }
+}
+
+query MovieTitle($id: Int!) {
+  movie(id: $id) {
+    id
+    title
+  }
+}
+
+query SearchMovieTags($searchKey: String!, $limit: Int!) {
+  getMoviesTagsValues(
+    filter: { startsWithInsensitive: $searchKey }
+    first: $limit
+  ) {
+    nodes
+  }
+}
+
+query SearchMovieCasts($searchKey: String!, $limit: Int!) {
+  getMoviesCastsValues(
+    filter: { startsWithInsensitive: $searchKey }
+    first: $limit
+  ) {
+    nodes
+  }
+}
+
+query SearchMovieProductionCountries($searchKey: String!, $limit: Int!) {
+  getMoviesProductionCountriesValues(
+    filter: { startsWithInsensitive: $searchKey }
+    first: $limit
+  ) {
+    nodes
+  }
+}
+```
+
+## Notes
+
+- VS Code may briefly show "Syntax Error: Unexpected <EOF>" when creating the
+  GraphQL file. This is a false positive caused by a race condition between file
+  creation and the `Apollo` extension's validation. It auto-resolves within
+  seconds and is safe to ignore and proceed.

package/skills/generate-details-station/refs/templates/managed-integrations/image-management-station.md

@@ -0,0 +1,322 @@
+---
+name: image-management-station
+input:
+  - EntityFeatures (with capabilities.images)
+  - DiscoveredPaths
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}ImageManagement/'
+    description: 'Complete image management station (4 files)'
+---
+
+# Generate Image Management Station
+
+Creates station for managing entity images (COVER, TEASER, etc.).
+
+`Conditional` - only generate if `EntityFeatures.capabilities.images` exists.
+
+## Prerequisites
+
+**Verify capability exists:**
+
+```typescript
+if (!EntityFeatures.capabilities.images) {
+  skip this step
+}
+```
+
+## Files to Generate
+
+1. `{Entity}ImageManagement.tsx` - Router wrapper
+2. `{Entity}ImageManagementForm.tsx` - Form component
+3. `{Entity}ImageManagement.graphql` - Query
+4. `{Entity}ImageManagementQuickEdit.tsx` - Quick edit wrapper
+
+## File 1: Router Wrapper
+
+**Path:** `{Entity}ImageManagement/{Entity}ImageManagement.tsx`
+
+```typescript
+import React from 'react';
+import { useParams } from 'react-router-dom';
+import { {Entity}ImageManagementForm } from './{Entity}ImageManagementForm';
+
+interface UrlParams {
+  {entityCamel}Id: string;
+}
+
+export const {Entity}ImageManagement: React.FC = () => {
+  const { {entityCamel}Id } = useParams<UrlParams>();
+
+  return <{Entity}ImageManagementForm {entityCamel}Id={Number({entityCamel}Id)} />;
+};
+```
+
+## File 2: GraphQL Query
+
+**Path:** `{Entity}ImageManagement/{Entity}ImageManagement.graphql`
+
+```graphql
+query {Entity}Images($id: {features.idType}!) {
+  {features.camelCase}(id: $id) {
+    {features.capabilities.images.connectionField} {
+      nodes {
+        imageId
+        imageType
+      }
+    }
+  }
+}
+```
+
+## File 3: Form Component
+
+**Path:** `{Entity}ImageManagement/{Entity}ImageManagementForm.tsx`
+
+```typescript
+import {
+  createUpdateGQLFragmentGenerator,
+  Details,
+  DetailsProps,
+} from '@axinom/mosaic-ui';
+import { Field } from 'formik';
+import gql from 'graphql-tag';
+import React, { useCallback, useContext, useEffect, useState } from 'react';
+import { client } from '../../../apolloClient';
+import { ExtensionsContext } from '{discoveredPaths.extensionsContextPath}';
+import {
+  {features.capabilities.images.imageTypeEnum},
+  {features.capabilities.images.nodeType},
+  Mutation,
+  MutationCreate{features.capabilities.images.nodeType}Args,
+  MutationDelete{features.capabilities.images.nodeType}By{Entity}IdAndImageTypeArgs,
+  MutationUpdate{features.capabilities.images.nodeType}By{Entity}IdAndImageTypeArgs,
+  use{Entity}ImagesQuery,
+} from '../../../generated/graphql';
+
+interface {Entity}ImageManagementFormProps {
+  {entityCamel}Id: number;
+}
+
+type ImageNodes = Pick<{features.capabilities.images.nodeType}, 'imageId' | 'imageType'> & {
+  __typename: '{features.capabilities.images.nodeType}';
+};
+
+type FormData = Record<{features.capabilities.images.imageTypeEnum}, string[]>;
+
+const Form: React.FC<{ imageSelectField: unknown }> = ({
+  imageSelectField,
+}) => {
+  return (
+    <>
+      {Object.keys({features.capabilities.images.imageTypeEnum}).map((type) => {
+        const field = {features.capabilities.images.imageTypeEnum}[type];
+        return (
+          <Field
+            key={field}
+            name={field}
+            label={type}
+            as={imageSelectField}
+            maxItems={1}
+            title="Select Image"
+            imageScope="{features.capabilities.images.scope}"
+          />
+        );
+      })}
+    </>
+  );
+};
+
+export const {Entity}ImageManagementForm: React.FC<
+  {Entity}ImageManagementFormProps
+> = ({ {entityCamel}Id }) => {
+  const { loading, data, error } = use{Entity}ImagesQuery({
+    client,
+    variables: { id: {entityCamel}Id },
+    fetchPolicy: 'network-only',
+  });
+
+  const { initialImages } = useImageTypes(
+    data?.{entityCamel}?.{features.capabilities.images.connectionField}.nodes as ImageNodes[],
+  );
+
+  const onSubmit = useCallback(
+    async (
+      formData: FormData,
+      initialData: DetailsProps<FormData>['initialData'],
+    ): Promise<void> => {
+      const generateUpdateGQLFragment =
+        createUpdateGQLFragmentGenerator<Mutation>();
+
+      const mutations: string[] = [];
+
+      const generateCreateMutation = (
+        imageId: string,
+        imageType: {features.capabilities.images.imageTypeEnum},
+      ): string =>
+        generateUpdateGQLFragment<MutationCreate{features.capabilities.images.nodeType}Args>(
+          'create{features.capabilities.images.nodeType}',
+          {
+            input: {
+              {camelNodeType}: {
+                {entityCamel}Id,
+                imageId,
+                imageType: { type: 'enum', value: imageType },
+              },
+            },
+          },
+        );
+
+      const generateDeleteMutation = (imageType: {features.capabilities.images.imageTypeEnum}): string =>
+        generateUpdateGQLFragment<MutationDelete{features.capabilities.images.nodeType}By{Entity}IdAndImageTypeArgs>(
+          'delete{features.capabilities.images.nodeType}By{Entity}IdAndImageType',
+          {
+            input: { {entityCamel}Id, imageType: { type: 'enum', value: imageType } },
+          },
+        );
+
+      const generateUpdateMutation = (
+        imageId: string,
+        imageType: {features.capabilities.images.imageTypeEnum},
+      ): string =>
+        generateUpdateGQLFragment<MutationUpdate{features.capabilities.images.nodeType}By{Entity}IdAndImageTypeArgs>(
+          'update{features.capabilities.images.nodeType}By{Entity}IdAndImageType',
+          {
+            input: {
+              patch: { imageId },
+              {entityCamel}Id,
+              imageType: { type: 'enum', value: imageType },
+            },
+          },
+        );
+
+      Object.entries(formData ?? {}).forEach(([imageType, imageId], idx) => {
+        const [imgId] = imageId;
+        const [initialValue] = initialData?.data?.[imageType];
+        const [currentValue] = formData[imageType];
+
+        switch (true) {
+          case initialValue === undefined && currentValue !== undefined:
+            mutations.push(
+              `assign${idx}:${generateCreateMutation(
+                imgId,
+                imageType as {features.capabilities.images.imageTypeEnum},
+              )}`,
+            );
+            break;
+          case initialValue !== undefined && currentValue === undefined:
+            mutations.push(
+              `assign${idx}:${generateDeleteMutation(
+                imageType as {features.capabilities.images.imageTypeEnum},
+              )}`,
+            );
+            break;
+          case initialValue !== currentValue:
+            mutations.push(
+              `assign${idx}:${generateUpdateMutation(
+                currentValue,
+                imageType as {features.capabilities.images.imageTypeEnum},
+              )}`,
+            );
+            break;
+          default:
+            break;
+        }
+      });
+
+      const GqlDoc = gql`mutation ImageAssignments {
+          ${mutations}
+        }`;
+
+      await client.mutate({ mutation: GqlDoc });
+    },
+    [{entityCamel}Id],
+  );
+
+  const { ImageSelectField } = useContext(ExtensionsContext);
+
+  return (
+    <Details<FormData>
+      defaultTitle="Image Management"
+      initialData={{
+        data: initialImages ?? {},
+        loading,
+        entityNotFound: data?.{entityCamel} === null,
+        error: error?.message,
+      }}
+      saveData={onSubmit}
+    >
+      <Form imageSelectField={ImageSelectField} />
+    </Details>
+  );
+};
+
+/**
+ * Creates the initial image type values
+ * @param nodes - data nodes
+ */
+const useImageTypes = (
+  nodes: ImageNodes[] = [],
+): {
+  readonly initialImages: FormData;
+} => {
+  const [initialImages, setInitialImages] = useState<FormData>(getImageTypes());
+
+  // Set all currently assigned images on the server
+  useEffect(() => {
+    if (nodes.length > 0) {
+      let temp = {} as FormData;
+
+      for (const { imageType, imageId } of nodes) {
+        temp = { ...temp, [imageType]: [imageId] };
+      }
+
+      setInitialImages((prevState) => {
+        return { ...prevState, ...temp };
+      });
+    }
+  }, [nodes]);
+
+  return { initialImages } as const;
+};
+
+/**
+ * Returns an image type with empty array value using the `{ImageTypeEnum}` enum
+ */
+const getImageTypes = (): FormData => {
+  let types = {} as FormData;
+
+  Object.keys({features.capabilities.images.imageTypeEnum}).map((type) => {
+    const field = {features.capabilities.images.imageTypeEnum}[type];
+    types = { ...types, [field]: [] };
+  });
+
+  return types;
+};
+```
+
+## File 4: Quick Edit Wrapper
+
+**Path:** `{Entity}ImageManagement/{Entity}ImageManagementQuickEdit.tsx`
+
+```typescript
+import { QuickEditContext, QuickEditContextType } from '@axinom/mosaic-ui';
+import React, { useContext } from 'react';
+import { {Entity}Data } from '../{EntityPlural}Explorer/common/{EntityPlural}.types';
+import { {Entity}ImageManagementForm } from './{Entity}ImageManagementForm';
+
+export const {Entity}ImageManagementQuickEdit: React.FC = () => {
+  const { selectedItem } =
+    useContext<QuickEditContextType<{Entity}Data>>(QuickEditContext);
+
+  return <{Entity}ImageManagementForm {entityCamel}Id={selectedItem.id} />;
+};
+```
+
+## Notes
+
+- Image scope uses `features.capabilities.images.scope` (e.g., `"movie"`,
+  `"episode"`)
+- Form creates one field per image type from `imageTypeValues` enum
+- Uses `ImageSelectField` from `ExtensionsContext` (media management
+  integration)
+- Generates create/update/delete mutations dynamically based on form changes