@axinom/mosaic-agent-skills 0.0.1

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

@@ -0,0 +1,163 @@
+---
+name: station-registration
+input:
+  - EntityFeatures
+  - Generated create component
+  - DiscoveredPaths
+output:
+  - Updated registrations.tsx with create route
+  - Updated explorer with onCreateAction (if explorer exists)
+---
+
+# Register Create Station
+
+Register create route and optionally integrate with explorer.
+
+## File Path
+
+`{workflowsPath}/src/Stations/{EntityPlural}/registrations.tsx`
+
+## Add Import
+
+```typescript
+import { {Entity}Create } from './{Entity}Create/{Entity}Create';
+```
+
+## Add Route Registration
+
+Add inside the `register()` function:
+
+```typescript
+app.registerPage('/{kebabCasePlural}/create', {Entity}Create, {
+  breadcrumb: () => 'New {Entity}',
+  permissions: { '{features.service.serviceId}': {features.service.permissions} },
+});
+```
+
+## Update Explorer Component (if exists)
+
+**Search for:**
+`{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/{EntityPlural}.tsx`
+
+**If file exists:**
+
+1. Check if `onCreateAction` prop already exists in `NavigationExplorer`
+2. If prop has TODO comment, replace with actual path
+3. If prop missing, add it
+
+```typescript
+<NavigationExplorer<{Entity}Data>
+  title="{EntityPlural}"
+  stationKey="{EntityPlural}Explorer"
+  calculateNavigateUrl={(item) => `/{kebabCasePlural}/${item.id}`}
+  onCreateAction="/{kebabCasePlural}/create"  // <-- Add or update this line
+  columns={{entityCamel}Columns}
+  // ... rest of props
+/>
+```
+
+**If file does not exist:** Skip this step (explorer not yet generated)
+
+## Example
+
+```typescript
+// In registrations.tsx
+import { PiletApi } from '@axinom/mosaic-portal';
+import React from 'react';
+import {
+  Extensions,
+  ExtensionsContext,
+} from '{discoveredPaths.extensionsContextPath}';
+import { MediaIconName, MediaIcons } from '../../MediaIcons';
+import { Movies } from './MoviesExplorer/Movies';
+import { MovieDetails } from './MovieDetails/MovieDetails';
+import { MovieDetailsCrumb } from './MovieDetails/MovieDetailsCrumb';
+import { MovieCreate } from './MovieCreate/MovieCreate';
+
+export function register(app: PiletApi, extensions: Extensions): void {
+  const moviesNav = {
+    name: 'movies',
+    path: '/movies',
+    label: 'Movies',
+    icon: <MediaIcons icon={MediaIconName.Movie} />,
+  };
+
+  app.registerTile({ ...moviesNav, kind: 'home', type: 'large' }, false);
+  app.registerNavigationItem({ ...moviesNav, categoryName: 'Content' });
+
+  // Explorer route
+  app.registerPage(
+    '/movies',
+    () => (
+      <ExtensionsContext.Provider value={extensions}>
+        <Movies />
+      </ExtensionsContext.Provider>
+    ),
+    {
+      breadcrumb: () => 'Movies',
+      permissions: { 'media-service': ['ADMIN', 'MOVIES_EDIT', 'MOVIES_VIEW'] },
+    },
+  );
+
+  // Create route
+  app.registerPage('/movies/create', MovieCreate, {
+    breadcrumb: () => 'New Movie',
+    permissions: { 'media-service': ['ADMIN', 'MOVIES_EDIT'] },
+  });
+
+  // Details route
+  app.registerPage(
+    '/movies/:movieId',
+    () => (
+      <ExtensionsContext.Provider value={extensions}>
+        <MovieDetails />
+      </ExtensionsContext.Provider>
+    ),
+    {
+      breadcrumb: MovieDetailsCrumb,
+      permissions: { 'media-service': ['ADMIN', 'MOVIES_EDIT', 'MOVIES_VIEW'] },
+    },
+  );
+}
+```
+
+```typescript
+// In MoviesExplorer/Movies.tsx
+import { NavigationExplorer } from '@axinom/mosaic-ui';
+import React from 'react';
+import { useMoviesBulkActions } from './common/Movies.bulkActions';
+import { moviesColumns } from './common/Movies.columns';
+import { createMoviesDataProvider } from './common/Movies.dataProvider';
+import { useMoviesFilters } from './common/Movies.filters';
+import { useMoviesInlineActions } from './common/Movies.inlineActions';
+import { MovieData } from './common/Movies.types';
+
+export const Movies: React.FC = () => {
+  const { transformFilters, filterOptions } = useMoviesFilters();
+  const { bulkActions } = useMoviesBulkActions();
+  const { generateInlineMenuActions } = useMoviesInlineActions();
+  const dataProvider = createMoviesDataProvider(transformFilters);
+
+  return (
+    <NavigationExplorer<MovieData>
+      title="Movies"
+      stationKey="MoviesExplorer"
+      calculateNavigateUrl={(item) => `/movies/${item.id}`}
+      onCreateAction="/movies/create" // <-- Integrated
+      columns={moviesColumns}
+      dataProvider={dataProvider}
+      filterOptions={filterOptions}
+      defaultSortOrder={{ column: 'updatedDate', direction: 'desc' }}
+      inlineMenuActions={generateInlineMenuActions}
+      bulkActions={bulkActions}
+      quickEditRegistrations={[]}
+    />
+  );
+};
+```
+
+## Notes
+
+- Create route uses same permissions as explorer (with `EDIT` capabilities)
+- Route path: `/{kebabCasePlural}/create`
+- Breadcrumb: Simple function returning `'New {Entity}'`

package/skills/generate-create-station/refs/templates/create-form-station.md

@@ -0,0 +1,206 @@
+---
+name: create-form-station
+input:
+  - EntityFeatures
+  - DiscoveredPaths
+  - Reference: field-component-mapping
+  - Reference: field-validation-schema
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Create/{Entity}Create.tsx'
+    description:
+      'Create component with form, validation, mutation, navigation, breadcrumb'
+---
+
+# Generate Create Form Station
+
+Create station with `@axinom/mosaic-ui` Create component, mutation, and
+navigation.
+
+## Template
+
+```typescript
+import { BreadcrumbResolver } from '@axinom/mosaic-portal';
+import {
+  ActionHandler,
+  Create,
+  Nullable,
+  // Import components based on field types (see field-component-mapping)
+  SingleLineTextField,
+  DateTimeTextField,
+  SelectField,
+  CheckboxField,
+  // ... other components as needed
+} from '@axinom/mosaic-ui';
+import { Field } from 'formik';
+import { ObjectSchemaDefinition } from 'ObjectSchemaDefinition';
+import React, { useCallback } from 'react';
+import { useHistory } from 'react-router-dom';
+import * as Yup from 'yup';
+import { client } from '{discoveredPath}/apolloClient';
+import {
+  Create{Entity}Mutation,
+  Create{Entity}MutationVariables,
+  useCreate{Entity}Mutation,
+} from '../../../generated/graphql';
+
+type FormData = Create{Entity}MutationVariables['input']['{entityCamel}'];
+
+type SubmitResponse = Nullable<Create{Entity}Mutation['create{Entity}']>;
+
+const {entityCamel}CreateSchema = Yup.object<ObjectSchemaDefinition<FormData>>({
+  // Generate validation for REQUIRED fields only from features.schema.input
+  // Use field-validation-schema patterns based on field.type
+
+  {titleField}: Yup.string().required('{TitleLabel} is a required field').max({maxLength}),
+  // ... other required fields only
+});
+
+export const {Entity}Create: React.FC = () => {
+  const [create{Entity}] = useCreate{Entity}Mutation({
+    client: client,
+    fetchPolicy: 'no-cache',
+  });
+
+  const saveData = useCallback(
+    async (formData: FormData): Promise<SubmitResponse> => {
+      return (
+        await create{Entity}({
+          variables: {
+            input: {
+              {entityCamel}: {
+                // Map REQUIRED fields from formData to mutation input
+                // Use field-component-mapping for type conversions (Number() for Int/Float)
+                {titleField}: formData.{titleField},
+                // ... other required fields
+              },
+            },
+          },
+        })
+      ).data?.create{Entity};
+    },
+    [create{Entity}],
+  );
+
+  const history = useHistory();
+  const onProceed = useCallback<ActionHandler<FormData, SubmitResponse>>(
+    ({ submitResponse }) => {
+      if (submitResponse?.{entityCamel}) {
+        // If Details station exists:
+        history.push(`/{kebabCasePlural}/${submitResponse?.{entityCamel}.id}`);
+        // If Details station does not exist:
+        // TODO: Update navigation once Details station is created
+        // history.push('/{kebabCasePlural}');
+      } else {
+        // The schema has the response.data properties marked as optional, since theoretically a user could have
+        // permissions to mutate but not to read. In practice this can not happen on that service, so we just throw
+        // an error in case we get there.
+        throw new Error('Not expected');
+      }
+    },
+    [history],
+  );
+
+  return (
+    <Create<FormData, SubmitResponse>
+      title="New {Entity}"
+      subtitle="Add new {entityCamel} metadata"
+      validationSchema={{entityCamel}CreateSchema}
+      saveData={saveData}
+      onProceed={onProceed}
+      cancelNavigationUrl="/{kebabCasePlural}"  // Navigate to explorer (if explorer doesn't exist, add TODO)
+      initialData={{
+        loading: false,
+      }}
+    >
+      {/* Generate Field for each REQUIRED field in features.schema.input where field.isRequired === true */}
+      {/* Use field-component-mapping to select component based on field.type */}
+      <Field name="{titleField}" label="{TitleLabel}" as={SingleLineTextField} />
+      {/* ... other required fields */}
+    </Create>
+  );
+};
+
+export const {Entity}CreateCrumb: BreadcrumbResolver = () => 'Create';
+```
+
+## Example
+
+```typescript
+import { BreadcrumbResolver } from '@axinom/mosaic-portal';
+import { ActionHandler, Create, SingleLineTextField } from '@axinom/mosaic-ui';
+import { Field } from 'formik';
+import { ObjectSchemaDefinition } from 'ObjectSchemaDefinition';
+import React, { useCallback } from 'react';
+import { useHistory } from 'react-router-dom';
+import * as Yup from 'yup';
+import { client } from '../../../apolloClient';
+import {
+  CreateMovieMutation,
+  CreateMovieMutationVariables,
+  useCreateMovieMutation,
+} from '../../../generated/graphql';
+
+type FormData = CreateMovieMutationVariables['input']['movie'];
+type SubmitResponse = CreateMovieMutation['createMovie'];
+
+const movieCreateSchema = Yup.object().shape<ObjectSchemaDefinition<FormData>>({
+  title: Yup.string().required('Title is a required field').max(100),
+});
+
+export const MovieCreate: React.FC = () => {
+  const [movieCreate] = useCreateMovieMutation({
+    client: client,
+    fetchPolicy: 'no-cache',
+  });
+
+  const saveData = useCallback(
+    async (formData: FormData): Promise<SubmitResponse> => {
+      return (
+        await movieCreate({
+          variables: { input: { movie: { title: formData.title } } },
+        })
+      ).data?.createMovie;
+    },
+    [movieCreate],
+  );
+
+  const history = useHistory();
+  const onProceed = useCallback<ActionHandler<FormData, SubmitResponse>>(
+    ({ submitResponse }) => {
+      if (submitResponse?.movie) {
+        history.push(`/movies/${submitResponse.movie.id}`);
+      } else {
+        throw new Error('Not expected');
+      }
+    },
+    [history],
+  );
+
+  return (
+    <Create<FormData, SubmitResponse>
+      title="New Movie"
+      subtitle="Add new movie metadata"
+      validationSchema={movieCreateSchema}
+      saveData={saveData}
+      onProceed={onProceed}
+      cancelNavigationUrl="/movies"
+      initialData={{ loading: false }}
+    >
+      <Field name="title" label="Title" as={SingleLineTextField} />
+    </Create>
+  );
+};
+
+export const MovieCreateCrumb: BreadcrumbResolver = () => 'Create';
+```
+
+## Notes
+
+- **Navigation after success (`onProceed`):**
+  - If Details station exists: Navigate to `/{kebabCasePlural}/${id}`
+  - If Details station does not exist: Keep commented fallback with TODO,
+    navigate to `/{kebabCasePlural}/${id}` (will be updated when Details is built)
+- **Cancel navigation (`cancelNavigationUrl`):**
+  - If Explorer station exists: Navigate to `/{kebabCasePlural}`
+  - If Explorer station does not exist: ADD TODO comment above the prop
+- **Only required fields** - no optional fields in create station

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

@@ -0,0 +1,56 @@
+---
+name: graphql-operations
+input:
+  - EntityFeatures
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Create/{Entity}Create.graphql'
+    description: 'Create mutation returning id and title'
+---
+
+# Generate GraphQL File
+
+Single file with create mutation.
+
+## Template
+
+```graphql
+mutation Create{features.name}($input: Create{features.name}Input!) {
+  create{features.name}(input: $input) {
+    {features.camelCase} {
+      id
+      {features.titleField}
+    }
+  }
+}
+```
+
+## Pattern
+
+- Mutation name: `Create{Entity}`
+- Input type: `Create{Entity}Input!` (standard PostGraphile pattern)
+- Return payload path: `create{Entity}.{entityCamel}`
+- Return fields: `id`
+
+## Example
+
+```graphql
+mutation CreateMovie($input: CreateMovieInput!) {
+  createMovie(input: $input) {
+    movie {
+      id
+      title
+    }
+  }
+}
+```
+
+```graphql
+mutation CreateCollection($input: CreateCollectionInput!) {
+  createCollection(input: $input) {
+    collection {
+      id
+      title
+    }
+  }
+}
+```

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

@@ -0,0 +1,125 @@
+---
+name: generate-details-station
+description: |
+  Generates a Details 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 Details Station
+
+## Input
+
+**Entity name** (PascalCase): e.g., "Movie", "Product", "ServiceAccount"
+
+## Output
+
+Complete details station with:
+
+- Details form with query, mutations, field rendering, info panel
+- URL parameter wrapper component
+- Actions hook (delete, navigate to child resources)
+- Breadcrumb resolver
+- Optional image management station (if entity has image capability)
+- Optional video management station (if entity has video capability)
+- Quick edit integration with explorer
+- Route registration
+
+## 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. Generate GraphQL Operations → `refs/templates/graphql-operations.md`
+
+Generate `.graphql` file with entity query, update/delete mutations, search
+queries for autocomplete
+
+### 4. Run Codegen → `../_shared/actions/typescript-codegen.md`
+
+Generate TypeScript types from GraphQL operations
+
+### 5. Generate Form Data Types → `refs/templates/form-data-types.md`
+
+Generate form data type extending GraphQL update patch with transformed
+association arrays
+
+### 6. Generate Actions Hook → `refs/templates/actions.md`
+
+Generate actions hook with delete mutation and navigation to child resources
+
+### 7. Generate Details Form
+
+#### 7.1. Read Field Component Mapping → `../_shared/conventions/field-component-mapping.md`
+
+Reference for component selection rules (String → TextField, Boolean → Checkbox,
+etc.)
+
+#### 7.2. Read Field Validation Schema → `../_shared/conventions/field-validation-schema.md`
+
+Reference for Yup validation patterns (required, length, format, etc.)
+
+#### 7.3. Generate Form Component → `refs/templates/details-form-station.md`
+
+Generate main `{Entity}DetailsForm.tsx` with query, mutations, field rendering,
+info panel
+
+### 8. Generate Details Wrapper → `refs/templates/details-wrapper.md`
+
+Generate `{Entity}Details.tsx` wrapper that extracts URL params and delegates to
+form
+
+### 9. Generate Breadcrumb → `refs/templates/breadcrumb.md`
+
+Generate async breadcrumb resolver for entity title
+
+### 10. Generate Image Management → `refs/templates/managed-integrations/image-management-station.md`
+
+Generate image management station
+
+### 11. Generate Video Management → `refs/templates/managed-integrations/video-management-station.md`
+
+Generate video management station
+
+### 12. Integrate with Explorer → `refs/finalization/explorer-integration.md`
+
+Integrate details station with explorer: quick edit components, inline actions,
+and navigation URLs
+
+### 13. Validate TypeScript → `../_shared/actions/typescript-validation.md`
+
+Run `tsc --noEmit` to verify all generated files compile successfully
+
+### 14. Register Station → `refs/finalization/station-registration.md`
+
+Register details routes, image/video routes, and breadcrumbs in
+registrations.tsx
+
+### 15. Print Summary → `../_shared/actions/execution-summary.md`
+
+Display execution summary with generated files, configuration, routes, TODOs