@axinom/mosaic-agent-skills 0.0.1

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

@@ -0,0 +1,283 @@
+---
+name: video-management-station
+input:
+  - EntityFeatures (with capabilities.videos)
+  - DiscoveredPaths
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}VideoManagement/'
+    description: 'Complete video management station (4 files)'
+---
+
+# Generate Video Management Station
+
+Creates station for managing entity videos (main video + trailers).
+
+`Conditional` - only generate if `EntityFeatures.capabilities.videos` exists.
+
+## Prerequisites
+
+**Verify capability exists:**
+
+```typescript
+if (!EntityFeatures.capabilities.videos) {
+  skip this step
+}
+```
+
+## Files to Generate
+
+1. `{Entity}VideoManagement.tsx` - Router wrapper
+2. `{Entity}VideoManagementForm.tsx` - Form component
+3. `{Entity}VideoManagement.graphql` - Query
+4. `{Entity}VideoManagementQuickEdit.tsx` - Quick edit wrapper
+
+## File 1: Router Wrapper
+
+**Path:** `{Entity}VideoManagement/{Entity}VideoManagement.tsx`
+
+```typescript
+import React from 'react';
+import { useParams } from 'react-router-dom';
+import { {Entity}VideoManagementForm } from './{Entity}VideoManagementForm';
+
+interface UrlParams {
+  {entityCamel}Id: string;
+}
+
+export const {Entity}VideoManagement: React.FC = () => {
+  const { {entityCamel}Id } = useParams<UrlParams>();
+
+  return <{Entity}VideoManagementForm {entityCamel}Id={Number({entityCamel}Id)} />;
+};
+```
+
+## File 2: GraphQL Query
+
+**Path:** `{Entity}VideoManagement/{Entity}VideoManagement.graphql`
+
+```graphql
+query {Entity}Videos($id: {features.idType}!) {
+  {features.camelCase}(id: $id) {
+    # If mainVideoField exists:
+    {features.capabilities.videos.mainVideoField}
+    # End if
+    # If trailersConnection exists:
+    {features.capabilities.videos.trailersConnection} {
+      nodes {
+        videoId
+      }
+    }
+    # End if
+  }
+}
+```
+
+## File 3: Form Component
+
+**Path:** `{Entity}VideoManagement/{Entity}VideoManagementForm.tsx`
+
+```typescript
+import { ID } from '@axinom/mosaic-managed-workflow-integration';
+import {
+  createUpdateGQLFragmentGenerator,
+  Details,
+  DetailsProps,
+  generateArrayMutations,
+} from '@axinom/mosaic-ui';
+import { Field } from 'formik';
+import gql from 'graphql-tag';
+import { ObjectSchemaDefinition } from 'ObjectSchemaDefinition';
+import React, { useCallback, useContext } from 'react';
+import * as Yup from 'yup';
+import { client } from '../../../apolloClient';
+import { ExtensionsContext } from '{discoveredPaths.extensionsContextPath}';
+import {
+  Mutation,
+  // If trailersConnection exists:
+  MutationCreate{features.capabilities.videos.trailersNodeType}Args,
+  MutationDelete{features.capabilities.videos.trailersNodeType}Args,
+  // End if
+  // If mainVideoField exists:
+  MutationUpdate{Entity}Args,
+  // End if
+  use{Entity}VideosQuery,
+} from '../../../generated/graphql';
+
+interface FormData {
+  // If mainVideoField exists:
+  mainVideo: ID[];
+  // End if
+  // If trailersConnection exists:
+  trailerVideos: ID[];
+  // End if
+}
+
+interface {Entity}VideoManagementFormProps {
+  {entityCamel}Id: number;
+}
+
+const {entityCamel}VideoManagementSchema = Yup.object().shape<
+  ObjectSchemaDefinition<FormData>
+>({
+  // If mainVideoField exists:
+  mainVideo: Yup.array().of(Yup.mixed()).max(1),
+  // End if
+  // If trailersConnection exists:
+  trailerVideos: Yup.array().of(Yup.mixed()),
+  // End if
+});
+
+export const {Entity}VideoManagementForm: React.FC<
+  {Entity}VideoManagementFormProps
+> = ({ {entityCamel}Id }) => {
+  const { VideoSelectField } = useContext(ExtensionsContext);
+
+  const { loading, data, error } = use{Entity}VideosQuery({
+    client,
+    variables: { id: {entityCamel}Id },
+    fetchPolicy: 'no-cache',
+  });
+
+  const onSubmit = useCallback(
+    async (
+      formData: FormData,
+      initialData: DetailsProps<FormData>['initialData'],
+    ): Promise<void> => {
+      const generateUpdateGQLFragment =
+        createUpdateGQLFragmentGenerator<Mutation>();
+
+      // If trailersConnection exists:
+      const trailerAssignmentMutations = generateArrayMutations({
+        current: formData.trailerVideos,
+        original: initialData.data?.trailerVideos,
+        generateCreateMutation: (videoId) =>
+          generateUpdateGQLFragment<MutationCreate{features.capabilities.videos.trailersNodeType}Args>(
+            'create{features.capabilities.videos.trailersNodeType}',
+            { input: { {camelTrailersNodeType}: { videoId, {entityCamel}Id } } },
+          ),
+        generateDeleteMutation: (videoId) =>
+          generateUpdateGQLFragment<MutationDelete{features.capabilities.videos.trailersNodeType}Args>(
+            'delete{features.capabilities.videos.trailersNodeType}',
+            { input: { {entityCamel}Id, videoId } },
+          ),
+        prefix: '{entityCamel}Trailers',
+      });
+      // End if
+
+      // If mainVideoField exists:
+      const mainVideoUpdateMutation =
+        initialData.data?.mainVideo[0] !== formData.mainVideo[0]
+          ? generateUpdateGQLFragment<MutationUpdate{Entity}Args>('update{Entity}', {
+              input: {
+                id: {entityCamel}Id,
+                patch: { {mainVideoField}: formData.mainVideo[0] ?? null },
+              },
+            })
+          : '';
+      // End if
+
+      const GqlMutationDocument = gql`mutation Update{Entity}Videos {
+            // If mainVideoField exists:
+            ${mainVideoUpdateMutation}
+            // End if
+            // If trailersConnection exists:
+            ${trailerAssignmentMutations}
+            // End if
+          }`;
+
+      await client.mutate({ mutation: GqlMutationDocument });
+    },
+    [{entityCamel}Id],
+  );
+
+  return (
+    <Details<FormData>
+      defaultTitle="Video Management"
+      validationSchema={{entityCamel}VideoManagementSchema}
+      initialData={{
+        data: {
+          // If mainVideoField exists:
+          mainVideo: data?.{entityCamel}?.{mainVideoField} ? [data?.{entityCamel}?.{mainVideoField}] : [],
+          // End if
+          // If trailersConnection exists:
+          trailerVideos:
+            data?.{entityCamel}?.{trailersConnection}.nodes.map(
+              (trailer) => trailer.videoId,
+            ) ?? [],
+          // End if
+        },
+        loading,
+        entityNotFound: data?.{entityCamel} === null,
+        error: error?.message,
+      }}
+      saveData={onSubmit}
+    >
+      <Form videoSelectField={VideoSelectField} />
+    </Details>
+  );
+};
+
+const Form: React.FC<{ videoSelectField: unknown }> = ({
+  videoSelectField,
+}) => {
+  return (
+    <>
+      // If mainVideoField exists:
+      <Field
+        name="mainVideo"
+        label="Main Video"
+        as={videoSelectField}
+        maxItems={1}
+        defaultFilterTag="MAIN"
+        title="Select Main Video"
+      />
+      // End if
+      // If trailersConnection exists:
+      <Field
+        name="trailerVideos"
+        label="Trailer Videos"
+        as={videoSelectField}
+        defaultFilterTag="TRAILER"
+        title="Select Trailer Video(s)"
+      />
+      // End if
+    </>
+  );
+};
+```
+
+## File 4: Quick Edit Wrapper
+
+**Path:** `{Entity}VideoManagement/{Entity}VideoManagementQuickEdit.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}VideoManagementForm } from './{Entity}VideoManagementForm';
+
+export const {Entity}VideoManagementQuickEdit: React.FC = () => {
+  const { selectedItem } =
+    useContext<QuickEditContextType<{Entity}Data>>(QuickEditContext);
+
+  return <{Entity}VideoManagementForm {entityCamel}Id={selectedItem.id} />;
+};
+```
+
+## Conditional Generation
+
+**Generate fields based on capability detection:**
+
+- If `features.capabilities.videos.mainVideoField` exists → include main video
+  field
+- If `features.capabilities.videos.trailersConnection` exists → include trailers
+  array field
+- Both, one, or neither may be present
+
+## Notes
+
+- Uses `VideoSelectField` from `ExtensionsContext`
+- Main video uses `maxItems={1}` (single selection)
+- Trailers allows multiple selections
+- Main video updates via `update{Entity}` mutation (patch field)
+- Trailers use array mutations (create/delete)

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

@@ -0,0 +1,121 @@
+---
+name: generate-explorer-station
+description: |
+  Generates an Explorer 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 Explorer Station
+
+## Input
+
+**Entity name** (PascalCase): e.g., "Movie", "Product", "ServiceAccount"
+
+## Output
+
+Complete explorer station with:
+
+- NavigationExplorer component with data provider, columns, filters
+- Common utility files (types, columns, dataProvider, filters, inlineActions,
+  bulkActions)
+- GraphQL operations (fragment, query, filter queries, subscription)
+- Optional bulk edit functionality
+- Station registration (routes, navigation, home tiles)
+
+## 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, associations,
+capabilities, mutations)
+
+### 3. Select Columns & Filters → `refs/select-columns-filters.md`
+
+AI recommends columns/filters → present to developer and proceeds with selection
+
+### 4. Generate GraphQL Operations → `refs/templates/graphql-operations.md`
+
+Generate `.graphql` file with fragment, main query, filter queries, and
+subscription
+
+### 5. Run Codegen → `../_shared/actions/typescript-codegen.md`
+
+Generate TypeScript types from GraphQL operations
+
+### 6. Generate Common Files
+
+Generate explorer utility files in order:
+
+#### 6.1. Generate Types → `refs/templates/common/types.md`
+
+Generate TypeScript type definitions and selection explorer props
+
+#### 6.2. Generate Columns → `refs/templates/common/columns.md`
+
+Generate column definitions with appropriate renderers (thumbnail, date, enum,
+connection)
+
+#### 6.3. Generate Data Provider → `refs/templates/common/data-provider.md`
+
+Generate data provider with loadData and optional subscription support
+
+#### 6.4. Generate Filters → `refs/templates/common/filters.md`
+
+Generate filter options and transformers for PostGraphile filters
+
+#### 6.5. Generate Inline Actions → `refs/templates/common/inline-actions.md`
+
+Generate inline action menu generator (with TODOs for delete/open details)
+
+#### 6.6. Generate Bulk Actions _(conditional)_ → `refs/templates/common/bulk-actions.md`
+
+Generate bulk action hooks and actions (only if
+`features.mutations.bulkActions === true`)
+
+### 7. Generate Explorer Station → `refs/templates/navigation-explorer-station.md`
+
+Generate main `{EntityPlural}.tsx` NavigationExplorer component with TODOs for
+missing features
+
+### 8. Generate Bulk Edit _(conditional)_ → `refs/templates/bulk-edit.md`
+
+Generate BulkEdit configuration and component (only if
+`features.mutations.bulkEdit === true`)
+
+### 9. Validate TypeScript → `../_shared/actions/typescript-validation.md`
+
+Run `tsc --noEmit` to verify all generated files compile successfully
+
+### 10. Register Station → `refs/finalization/station-registration.md`
+
+Create/update registrations.tsx with explorer routes, navigation items, and home
+tiles
+
+### 11. Print Summary → `../_shared/actions/execution-summary.md`
+
+Display execution summary with generated files, configuration, columns, filters,
+routes, TODOs

package/skills/generate-explorer-station/refs/finalization/station-registration.md

@@ -0,0 +1,145 @@
+---
+name: station-registration
+input:
+  - EntityFeatures
+  - DiscoveredPaths
+  - Generated explorer files
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/registrations.tsx'
+    description: 'Station registration with routes and navigation'
+---
+
+# Register Explorer
+
+## 1. Create registrations.tsx
+
+**File:** `{workflowsPath}/src/Stations/{EntityPlural}/registrations.tsx`
+
+**Discovery:** Icon mapping
+
+- Look at entity name to pick best icon from `MediaIconName` enum
+- If no perfect match, pick the best match and add a `TODO`
+
+```typescript
+import { PiletApi } from '@axinom/mosaic-portal';
+import React from 'react';
+import { Extensions, ExtensionsContext } from '{discoveredPaths.extensionsContextPath}';
+import { MediaIconName, MediaIcons } from '../../MediaIcons';
+import { {EntityPlural} } from './{EntityPlural}Explorer/{EntityPlural}';
+
+export function register(app: PiletApi, extensions: Extensions): void {
+  const {entityCamelPlural}Nav = {
+    name: '{entityCamelPlural}',
+    path: '/{kebabCasePlural}',
+    label: '{EntityPlural}',
+    // TODO: Update icon to match entity type
+    icon: <MediaIcons icon={MediaIconName.Movie} />,
+  };
+
+  // Home tile
+  app.registerTile(
+    {
+      ...{entityCamelPlural}Nav,
+      kind: 'home',
+      type: 'large',
+    },
+    false,
+  );
+
+  // Navigation item
+  app.registerNavigationItem({
+    ...{entityCamelPlural}Nav,
+    categoryName: 'Content',
+  });
+
+  // Explorer route
+  app.registerPage(
+    '/{kebabCasePlural}',
+    () => (
+      <ExtensionsContext.Provider value={extensions}>
+        <{EntityPlural} />
+      </ExtensionsContext.Provider>
+    ),
+    {
+      breadcrumb: () => '{EntityPlural}',
+      permissions: { '{features.service.serviceId}': {features.service.permissions} },
+    },
+  );
+
+  // If features.mutations.create === true:
+  // TODO: Add create route once Create station exists
+  // app.registerPage('/{kebabCasePlural}/create', {Entity}Create, {
+  //   breadcrumb: () => 'New {Entity}',
+  //   permissions: { '{features.service.serviceId}': {features.service.permissions} },
+  // });
+  // End if
+
+  // TODO: Add details route once Details station exists
+  // app.registerPage('/{kebabCasePlural}/:{entityCamel}Id', {Entity}Details, {
+  //   breadcrumb: {Entity}DetailsCrumb,
+  //   permissions: { '{features.service.serviceId}': {features.service.permissions} },
+  // });
+}
+```
+
+## 2. Register in main index
+
+**File:** `{workflowsPath}/src/index.tsx`
+
+Add import:
+
+```typescript
+import { register as register{EntityPlural} } from './Stations/{EntityPlural}/registrations';
+```
+
+Add registration call in `setup()`:
+
+```typescript
+register{EntityPlural}(app, extensions);
+```
+
+## Example (Product)
+
+```typescript
+// registrations.tsx
+import { PiletApi } from '@axinom/mosaic-portal';
+import React from 'react';
+import {
+  Extensions,
+  ExtensionsContext,
+} from '{discoveredPaths.extensionsContextPath}';
+import { MediaIconName, MediaIcons } from '../../MediaIcons';
+import { Products } from './ProductsExplorer/Products';
+
+export function register(app: PiletApi, extensions: Extensions): void {
+  const productsNav = {
+    name: 'products',
+    path: '/products',
+    label: 'Products',
+    // TODO: Update icon to match entity type
+    icon: <MediaIcons icon={MediaIconName.Movie} />,
+  };
+
+  app.registerTile({ ...productsNav, kind: 'home', type: 'large' }, false);
+
+  app.registerNavigationItem({ ...productsNav, categoryName: 'Content' });
+
+  app.registerPage(
+    '/products',
+    () => (
+      <ExtensionsContext.Provider value={extensions}>
+        <Products />
+      </ExtensionsContext.Provider>
+    ),
+    {
+      breadcrumb: () => 'Products',
+      permissions: {
+        'product-service': ['ADMIN', 'PRODUCTS_EDIT', 'PRODUCTS_VIEW'],
+      },
+    },
+  );
+
+  // TODO: Add create route once Create station exists
+  // TODO: Add details route once Details station exists
+}
+```

package/skills/generate-explorer-station/refs/select-columns-filters.md

@@ -0,0 +1,63 @@
+---
+name: select-columns-filters
+input:
+  - EntityFeatures
+output:
+  - selectedColumns array
+  - selectedFilters array
+---
+
+# Select Columns & Filters
+
+## Column Selection Logic
+
+### Always Include
+
+1. **Thumbnail** (if `features.capabilities.images !== undefined`) - first
+   column
+2. **Title/Name field** - primary human identifier
+3. **ID** - primary technical identifier
+
+### AI Judgment
+
+Analyze fields by priority:
+
+- **High:** title, name, ID, status fields, tag-like (i.e. `Tags` for easy
+  filtering)
+- **Medium:** description fields, M:N associations (i.e. `Category`, `Genre` for
+  easy filtering)
+- **Low:** other fields, audit fields
+
+### Target
+
+Enough columns to distinguish the important metadata of the entity
+
+### Order
+
+1. Thumbnail (if `features.capabilities.images !== undefined`)
+2. Title field
+3. Important fields
+4. Associations
+5. Date fields
+6. Updated date (last)
+
+## Filter Selection Logic
+
+### Always Include
+
+- **Title field** - text search
+- **ID** - numeric filter
+
+### AI Judgment
+
+- Identity fields
+- Text fields that users search by
+- Enum fields (status, type, etc.)
+- Date fields (released, created, updated)
+- Tag-Like fields (tags)
+- Associations (genres, categories)
+- Audit fields (createdDate, updatedDate)
+
+### Target
+
+Enough filters to search by important fields of the entity