migrate-page-gitlab

Page Migration Command (GitLab Source)

Migrate a page from GitLab repository (Angular 16) to new one-ui monorepo (Angular 20) following DDD architecture.

Arguments

$ARGUMENTS - Format: --page <page_name>
- --page: Page folder name in GitLab (e.g., time, account, ddns)

Target Path Convention

Target path is automatically derived as libs/mxsecurity/{page_name}-page Example: --page time → libs/mxsecurity/time-page

GitLab Source Base URL

https://gitlab.com/moxa/sw/f2e/networking/f2e-networking/-/tree/main/apps/mxsecurity-web/src/app/pages/{page_name}

GitLab Access Token

Set environment variable GITLAB_TOKEN or use private_token=${GITLAB_TOKEN} for authenticated access.

Security Note: Never hardcode tokens in skill files. Use environment variables instead.

Workflow

Phase 1: Fetch Source from GitLab & Analysis

GitLab URLs (with token):

Tree API: https://gitlab.com/api/v4/projects/moxa%2Fsw%2Ff2e%2Fnetworking%2Ff2e-networking/repository/tree?path=apps/mxsecurity-web/src/app/pages/{page_name}&ref=main&private_token=${GITLAB_TOKEN}
Raw file: https://gitlab.com/api/v4/projects/moxa%2Fsw%2Ff2e%2Fnetworking%2Ff2e-networking/repository/files/{url_encoded_path}/raw?ref=main&private_token=${GITLAB_TOKEN}

Use WebFetch to fetch source files (*.component.ts, *.component.html, *.component.scss, *.service.ts, *.model.ts).

Analyze the fetched source and create a migration analysis document in {target}/domain/src/lib/docs/MIGRATION-ANALYSIS.md:

File Structure Analysis
- List all files fetched from GitLab
- Categorize by type: components, services, models, templates, styles
Component Analysis
- Identify all components and their relationships
- Note parent/child relationships
- Identify dialog components
- Identify table/form components
Form Validation Analysis
- List all form controls and their validators
- Identify Validators.* usage that needs OneValidators.* replacement
- Document custom validators
API Calls Analysis
- List all HTTP calls (endpoints, methods, request/response types)
- Identify API services being used
- Document data flow
Dependencies Analysis
- Third-party libraries used
- Angular Material components used
- Shared services/utils used
Translation Keys Analysis (CRITICAL)
- DO NOT create new translation keys
- DO NOT modify existing translation keys
- List all translation keys used in source HTML templates
- Copy exact keys for use in migrated components
Form Layout Analysis (CRITICAL)
- DO NOT change form field row groupings
- Analyze fxLayout="row" patterns in source templates
- Document which fields appear on same row
- Use .form-row class in migrated components to preserve layout

Phase 2: DDD Structure Migration

Reference documents from one-ui-migration skill's rules/ directory:

Reference Docs (rules/reference/):

ddd-architecture.md - DDD layers, helper files
api-types.md - API types, def files
checklist.md - Full compliance checklist
pitfalls/ - Common migration mistakes

Tool Docs (rules/tools/):

forms/validators.md - OneValidators usage, pattern constants
forms/error-handling.md - Template errors, custom errors
ui/page-layout.md - Page layout, breadcrumb
ui/forms.md - Form layout, validation
ui/buttons.md - Button types, loading states
ui/components.md - File upload, form patterns
ui/dialogs.md - Dialog config, viewContainerRef
tables/basics.md - CommonTableComponent
tables/columns.md - Column API, custom templates
tables/advanced.md - Paginator config

Guides (rules/guides/):

create-page.md - Page creation guide
create-dialog.md - Dialog creation guide
create-table.md - Table creation guide

Generate libraries using the Nx plugin:

# Generate all library types at once
nx g @one-ui/one-plugin:library mxsecurity {page-name} all

# Or generate individually if needed
nx g @one-ui/one-plugin:library mxsecurity {page-name} domain
nx g @one-ui/one-plugin:library mxsecurity {page-name} features
nx g @one-ui/one-plugin:library mxsecurity {page-name} ui
nx g @one-ui/one-plugin:library mxsecurity {page-name} shell

Phase 3: Layer-by-Layer Migration

Domain Layer (domain/) - see rules/reference/ddd-architecture.md
- API response types → use existing types from @one-ui/mxsecurity/shared/domain (e.g., SRV_USER_ACCOUNT)
- If API type missing → create in libs/mxsecurity/shared/domain/src/lib/models/api/
- Page-specific models (view models, form models) → *.model.ts
- Migrate API service → *.api.ts
- Create SignalStore → *.store.ts
- Migrate constants → *.def.ts
- Extract pure functions → *.helper.ts (data transformations, serialization)
- Keep MIGRATION-ANALYSIS.md in domain/src/lib/docs/ folder
UI Layer (ui/) - see rules/tools/tables/basics.md
- Migrate tables → use CommonTableComponent pattern
- Migrate forms → use input(), output() pattern
- Table toolbar → use mat-stroked-button with general.button.create/delete
- Keep components dumb (no store injection, no HTTP)
Features Layer (features/) - see rules/tools/ui/forms.md, buttons.md and dialogs.md
- Migrate page component → smart component pattern
- Migrate dialogs → use smallDialogConfig, mediumDialogConfig, largeDialogConfig
- Form tooltips → use mxLabelTooltip instead of mat-icon with matTooltip
- Inject store, pass data to UI via inputs
Shell Layer (shell/)
- Create routes with resolver pattern
- Provide store and services
App Routes Registration (see rules/tools/ui/page-layout.md)
- Add route to apps/mxsecurity/mxsecurity/src/app/app.routes.ts
- Register in appRoutes children array with breadcrumb resolver

Phase 4: Syntax Modernization

Apply Angular 20 syntax updates (see rules/reference/angular-20-syntax.md):

*ngIf → @if
*ngFor → @for (item of items; track item.id)
constructor(private service: Service) → inject()
@Input() → input()
@Output() → output()
BehaviorSubject → signal()

Form Validation (see rules/tools/forms/validators.md):

Validators.required → OneValidators.required (no parentheses)
Validators.email → OneValidators.email (no parentheses)
Validators.minLength(n) → OneValidators.minLength(n)
Import from @one-ui/mxsecurity/shared/domain

UI Patterns:

Buttons (see buttons.md):
- mat-raised-button → mat-flat-button
- Form tooltips: Use mxLabelTooltip instead of mat-icon with matTooltip
- Loading states: Use MxLoadingButtonDirective with [mxButtonIsLoading]="loading()"
Page Layout (see ui/page-layout.md):
- mat-card → <div class="content-wrapper">
Dialogs (see dialogs.md):
- Dialog sizing: Use smallDialogConfig, mediumDialogConfig, largeDialogConfig
- Dialog API calls: Call API inside dialog, close only on success via next callback
- Dialog viewContainerRef: Set viewContainerRef: this.#viewContainerRef when dialog uses store
Tables (see basics.md):
- Table toolbar buttons: Use mat-stroked-button with general.button.create/general.button.delete

Translation Keys (see rules/reference/pitfalls/translation-layout.md):

MUST use exact same translation keys as source
Read source HTML templates to find correct keys
DO NOT create new keys or modify existing ones
Example: {{ 'general.common.name' | translate }} → {{ t('general.common.name') }}

Number-Only Input Directive (see rules/reference/pitfalls/forms-services.md):

MUST replace appNumberOnly with oneUiNumberOnly
Import NumberOnlyDirective from @one-ui/mxsecurity/shared/domain

Phase 5: Verification

# Type check
npx tsc --noEmit --project libs/mxsecurity/{page-name}/domain/tsconfig.lib.json

# Lint
nx lint mxsecurity-{page-name}-domain
nx lint mxsecurity-{page-name}-features
nx lint mxsecurity-{page-name}-ui
nx lint mxsecurity-{page-name}-shell

# Build
nx build mxsecurity-web

Output Format

After completing migration analysis (Phase 1), save the analysis to: {target}/domain/src/lib/docs/MIGRATION-ANALYSIS.md

Example Usage

/migrate-page-gitlab --page time
/migrate-page-gitlab --page account
/migrate-page-gitlab --page ddns

These will automatically migrate to:

libs/mxsecurity/time-page
libs/mxsecurity/account-page
libs/mxsecurity/ddns-page

Reference Examples

MAF Account Settings: libs/maf/act-account/
Switch L3 Interface: libs/switch/l3-interface/
MXsecurity Login: libs/mxsecurity/login-page/