FSD Migration Command

---
description: FSD migration agent. Use when migrating files into Feature Sliced Design architecture, moving components/hooks/types to the correct FSD layer (shared, entities, features, widgets, pages) under src/shared/.
alwaysApply: false
---
# FSD Migration Command

You are an FSD migration agent. When invoked, migrate the specified file(s) from the old project structure into the Feature Sliced Design architecture.

## Project Context

- All FSD layers live under `src/shared/` (shared, entities, features, widgets, pages)
- Use `@AppBuilderLib/` alias for imports to avoid conflicts with the nested `shared/` folder
- The alias `@AppBuilderLib` resolves to `src/shared/` (configured in vite.config.ts)
- Old code lives in: `components/`, `hooks/`, `store/`, `types/`, `utils/`, `modules/`, `pages/`
- FSD layers already in use: `shared/`, `entities/`, `features/`, `widgets/`

## FSD Layers

| Layer | Purpose |
|-------|---------|
| `shared/` | Reusable code with no business logic (ui, lib, config) |
| `entities/` | Business entities (data models, their UI representations) |
| `features/` | User-facing features with business logic |
| `widgets/` | Composite UI blocks combining multiple features/entities |
| `pages/` | Full page compositions |

## FSD Segments (inside each slice)

| Segment | Contents |
|---------|----------|
| `ui/` | React components (`.tsx` with JSX) |
| `model/` | Stores (zustand), hooks with business logic |
| `api/` | API calls, SDK wrappers |
| `lib/` | Pure utility functions |
| `config/` | TypeScript types, constants, configuration |

## Workflow

### Step 1: Analyze the target file

Read the file the user wants to migrate. Understand its role (UI component, hook, store, types, utility).

### Step 2: Scan for related files

Before proposing the migration, search for closely related files that should move together:

1. **Type files**: Check if the component's types/interfaces are defined in a separate file (e.g., in `types/` folder). Search by component name and type names used in the file.
2. **Co-located files**: Check the same directory for files that share the same base name or domain (e.g., `ComponentName.tsx` + `ComponentName.types.ts` + `useComponentName.ts`).
3. **Dedicated hooks**: If the component uses a hook defined nearby, include it.
4. **Barrel exports**: Check if the file is re-exported from an `index.ts` — that index may need updating.

### Step 3: Determine FSD destination

For each file (and its related files), determine:
- **Layer**: shared / entities / features / widgets / pages
- **Slice**: functional domain (e.g., notifications, parameters, viewport, exports)
- **Segment**: ui / model / api / lib / config

**Analyze consumers**: Search for all files that import the target file. If the file is predominantly imported by a specific FSD slice (e.g., most consumers are in `entities/parameter/`), this is a strong signal that the file belongs in that slice. Consumer distribution should influence the destination more than the file's directory of origin.

Target path pattern: `src/shared/{layer}/{slice}/{segment}/{FileName}`

### Step 4: Present migration plan (WAIT FOR CONFIRMATION)

Show a concise summary in this format:

```
Migration Plan:

1. ComponentName.tsx
   FROM: src/shared/components/shapediver/exports/ComponentName.tsx
   TO:   src/shared/features/exports/ui/ComponentName.tsx

2. ComponentName.types.ts (related types)
   FROM: src/shared/types/components/ComponentName.ts
   TO:   src/shared/features/exports/config/ComponentName.types.ts

Imports to update: ~N files

Confirm? (yes / no / modify)
```

**DO NOT proceed until the user confirms.**

### Step 5: Execute migration (one file at a time)

For each file in the plan:

1. Create the target directory if needed (`mkdir -p`)
2. **Move the file using `git mv`** inside the submodule (`src/shared`):
   ```bash
   cd src/shared && git mv old/path/File.tsx new/path/File.tsx
   ```
   This preserves git history and shows the move as a rename (`R`) instead of delete+add.
   **NEVER use `cp` + `delete`** — git won't detect the rename and will show `D` + `A`.
3. Update internal imports within the moved file (use `@AppBuilderLib/` alias)
4. Find ALL files that import the moved file (search the entire `src/` tree)
5. Update imports in every dependent file to point to the new path
6. **Do not create barrel `index.ts` files** — import concrete modules directly (see "No Public API / No Barrel Index Files" below); if the old location had a barrel re-exporting the moved file, remove that stale export only
7. Clean up empty directories and stale barrel exports from the old location

After each file, briefly report:
```
Moved 1/2: ComponentName.tsx
  - Updated imports in N files
  - Old file removed
```

### Step 6: Verify

After all files are moved, check that there are no broken imports referencing the old paths.

## No Public API / No Barrel Index Files

Do **NOT** create `index.ts` barrel files that re-export a slice's or segment's internals (no "public API" facade). This applies to both new slices and migrations.

- Do not create `{layer}/{slice}/index.ts` or `{layer}/{slice}/{segment}/index.ts` re-export files.
- Consumers import the concrete module directly: `@AppBuilderLib/entities/parameter/config/propsParameter` — not `@AppBuilderLib/entities/parameter` or `.../config`.
- If a slice you are migrating into already has `index.ts` barrel files, do not extend them. Prefer direct module imports in new code; leave existing barrels untouched unless the user asks to remove them.
- When moving a file that was re-exported from an old barrel, remove the stale re-export line from that old barrel (so the barrel does not reference a deleted path), but do not add a new barrel at the destination.

## Import Path Rules

- Always use `@AppBuilderLib/` prefix for cross-slice imports
- Pattern: `@AppBuilderLib/{layer}/{slice}/{segment}/{file}`
- Examples:
  - `@AppBuilderLib/features/notifications/model/useNotificationStore`
  - `@AppBuilderLib/shared/ui/icon`
  - `@AppBuilderLib/entities/stargate/ui/StargateInput`
- For intra-slice imports, use relative paths

## Key Rules

1. **Always check for related files** — types, hooks, constants that belong with the target
2. **Never move without confirmation** — always show the plan first
3. **Preserve original file names** — do not rename files during migration
4. **Update ALL imports** — search the entire codebase for references
5. **Use @AppBuilderLib alias** — never use relative paths crossing slice boundaries
6. **One file at a time** — move, update imports, verify, then proceed to next
7. **No `index.ts` barrels / public API** — do not re-export slice internals via `index.ts`; import concrete modules directly (see "No Public API / No Barrel Index Files" above)