@vc-shell/vc-app-skill 2.0.0-alpha.32 → 2.0.0-alpha.33-pr220.455e322

package/runtime/knowledge/migration-prompts/icon-migration.md

@@ -0,0 +1,97 @@
+---
+name: icon-migration
+description: AI transformation rules for migrating non-lucide icons to lucide equivalents.
+---
+
+# Icon Migration: material-/bi-/fa- → lucide-
+
+All icons in the v2 framework must use the `lucide-` prefix. Replace all `material-*`, `bi-*`, and `fa-*` icons with their lucide equivalents.
+
+## RULE 1: Replace Icon Strings
+
+Scan ALL `.vue` and `.ts` files in the affected module for icon strings. For each non-lucide icon, choose the closest semantic match from the lucide icon set (https://lucide.dev/icons).
+
+When choosing a replacement:
+
+- Match by **meaning**, not by visual similarity — e.g., `material-delete` → `lucide-trash-2` (both mean "delete")
+- Use the most specific icon available — e.g., `material-person_add` → `lucide-user-plus` (not just `lucide-user`)
+- When no perfect match exists, pick the closest conceptual equivalent and note it in the report
+
+**BEFORE:**
+
+```typescript
+const bladeToolbar = computed((): IBladeToolbar[] => [
+  {
+    id: "refresh",
+    icon: "material-refresh",
+    title: t("...REFRESH"),
+    clickHandler: reload,
+  },
+  {
+    id: "add",
+    icon: "material-add",
+    title: t("...ADD"),
+    clickHandler: addItem,
+  },
+  {
+    id: "delete",
+    icon: "material-delete",
+    title: t("...DELETE"),
+    clickHandler: deleteItems,
+  },
+]);
+```
+
+**AFTER:**
+
+```typescript
+const bladeToolbar = computed((): IBladeToolbar[] => [
+  {
+    id: "refresh",
+    icon: "lucide-refresh-cw",
+    title: t("...REFRESH"),
+    clickHandler: reload,
+  },
+  {
+    id: "add",
+    icon: "lucide-plus",
+    title: t("...ADD"),
+    clickHandler: addItem,
+  },
+  {
+    id: "delete",
+    icon: "lucide-trash-2",
+    title: t("...DELETE"),
+    clickHandler: deleteItems,
+  },
+]);
+```
+
+## RULE 2: Where Icons Appear
+
+Icons appear in these contexts — check ALL of them:
+
+1. **Toolbar items:** `icon: "material-*"` in `IBladeToolbar[]`
+2. **Menu items in defineBlade:** `icon: "material-*"` in `menuItem` config
+3. **VcIcon components:** `<VcIcon icon="material-*" />`
+4. **Widget declarations:** `icon: "material-*"` in `useBladeWidgets()` config
+5. **Action builders / row actions:** `icon: "material-*"` in action definitions
+6. **Empty state configs:** `icon: "material-*"` in `:empty-state` or `:not-found-state`
+7. **Any other string literal** containing `material-`, `bi-`, or `fa-` prefixes
+
+## RULE 3: Perform Replacements In-Place
+
+This is a **mechanical replacement** — do not restructure code. For each icon string found:
+
+1. Identify the icon name (e.g., `material-edit_square`)
+2. Determine the semantic meaning (e.g., "edit with square indicator")
+3. Find the best lucide match (e.g., `lucide-square-pen`)
+4. Replace the string in-place
+
+## Verification
+
+After migration:
+
+1. Search for remaining non-lucide icons: `grep -rn '"material-\|"bi-\|fa-' src/modules/`
+2. Verify no results (all icons should be `lucide-*`)
+3. Run the app and visually confirm icons render correctly

package/runtime/knowledge/migration-prompts/manual-migration-audit.md

@@ -0,0 +1,117 @@
+---
+name: manual-migration-audit
+description: AI transformation rules for findings emitted by manual-migration-audit transform.
+---
+
+# Manual Migration Audit Fixes
+
+Apply targeted refactors for diagnostics emitted by `manual-migration-audit`.
+
+## RULE 1: `useExternalWidgets` is removed
+
+Replace `useExternalWidgets(...)` with module-level widget composables based on `useBladeWidgets()`.
+
+**BEFORE:**
+
+```typescript
+import { useExternalWidgets } from "@vc-shell/framework";
+
+useExternalWidgets({ bladeId, item });
+```
+
+**AFTER:**
+
+```typescript
+import { useEntityWidgets } from "../widgets";
+
+useEntityWidgets({
+  item,
+  isVisible: computed(() => !!param.value),
+  disabled,
+});
+```
+
+If widget migration is not yet done, perform it first (`widgets-migration` topic).
+
+## RULE 2: Replace `moment` usage with framework date utilities
+
+**BEFORE:**
+
+```typescript
+import moment from "moment";
+
+const formatted = moment(item.value.createdDate).format("L LT");
+```
+
+**AFTER:**
+
+```typescript
+import { formatDateWithPattern } from "@vc-shell/framework";
+
+const formatted = formatDateWithPattern(item.value.createdDate, "L LT", currentLocale.value);
+```
+
+For relative dates, use `formatDateRelative` from `@vc-shell/framework`.
+
+## RULE 3: Replace `useFunctions().debounce` with `useDebounceFn`
+
+**BEFORE:**
+
+```typescript
+import { useFunctions } from "@vc-shell/framework";
+
+const { debounce } = useFunctions();
+const debouncedSearch = debounce(runSearch, 300);
+```
+
+**AFTER:**
+
+```typescript
+import { useDebounceFn } from "@vueuse/core";
+
+const debouncedSearch = useDebounceFn(runSearch, 300);
+```
+
+## RULE 4: Replace `closeBlade()` with `closeSelf()` from `useBlade()`
+
+**BEFORE:**
+
+```typescript
+const { closeBlade } = useBlade();
+await closeBlade();
+```
+
+**AFTER:**
+
+```typescript
+const { closeSelf } = useBlade();
+await closeSelf();
+```
+
+If `closeBlade(index)` was used to close by index, refactor to close current blade only (or use explicit navigation logic) — do not keep index-based close calls.
+
+## RULE 5: Consolidate multiple `useBlade()` calls per file
+
+Use one `useBlade()` destructuring per component/composable unless there is a strong technical reason.
+
+**BEFORE:**
+
+```typescript
+const { openBlade } = useBlade();
+const { closeSelf } = useBlade();
+```
+
+**AFTER:**
+
+```typescript
+const { openBlade, closeSelf, callParent, param } = useBlade();
+```
+
+## Verification
+
+After migration:
+
+1. Search and remove stale APIs: `useExternalWidgets`, `import moment`, `useFunctions(`, `closeBlade(`.
+2. Search for duplicate `useBlade()` calls in the same file and consolidate.
+3. Run `npx vue-tsc --noEmit`.
+4. Run `yarn build`.

package/runtime/knowledge/migration-prompts/notifications-migration.md

@@ -0,0 +1,223 @@
+---
+name: notifications-migration
+description: AI transformation rules for notification template migration to new defineAppModule config.
+---
+
+# Notifications Migration: useNotifications → useBladeNotifications
+
+Migrate from `createAppModule(pages, locales, notificationTemplates)` to `defineAppModule({ notifications })`, and from `useNotifications()` to `useBladeNotifications()`.
+
+## RULE 1: Move Notification Directory
+
+Move `components/notifications/` to `notifications/` at the module root. Remove the barrel `index.ts` that re-exports all templates.
+
+**BEFORE:**
+
+```
+my-module/
+  components/
+    notifications/
+      index.ts           ← barrel: export { default as MyEvent } from "./MyEvent.vue"
+      MyEvent.vue
+  pages/
+  index.ts
+```
+
+**AFTER:**
+
+```
+my-module/
+  notifications/
+    MyEvent.vue          ← no barrel index.ts needed
+  pages/
+  index.ts
+```
+
+## RULE 2: Update Notification Template
+
+Remove `defineProps`, remove `defineOptions({ inheritAttrs: false })`, and use `useNotificationContext()` composable instead of props.
+
+**BEFORE:**
+
+```vue
+<template>
+  <NotificationTemplate
+    :color="color"
+    :title="notification.title"
+    :icon="icon"
+    :notification="notification"
+    @click="onClick"
+  >
+    <VcHint>{{ notification.description }}</VcHint>
+  </NotificationTemplate>
+</template>
+
+<script lang="ts" setup>
+import { PushNotification, NotificationTemplate } from "@vc-shell/framework";
+
+export interface Props {
+  notification: PushNotification;
+}
+
+defineProps<Props>();
+defineOptions({ inheritAttrs: false });
+
+const color = computed(() => "var(--primary-500)");
+const icon = "lucide-bell";
+
+function onClick() {
+  // handle click
+}
+</script>
+```
+
+**AFTER:**
+
+```vue
+<template>
+  <NotificationTemplate
+    :color="color"
+    :title="notification.title"
+    :icon="icon"
+    :notification="notification"
+    @click="onClick"
+  >
+    <VcHint>{{ notification.description }}</VcHint>
+  </NotificationTemplate>
+</template>
+
+<script lang="ts" setup>
+import { PushNotification, useBlade, NotificationTemplate, useNotificationContext } from "@vc-shell/framework";
+import { computed } from "vue";
+
+interface IMyNotification extends PushNotification {
+  customField?: string;
+}
+
+const notificationRef = useNotificationContext<IMyNotification>();
+const notification = computed(() => notificationRef.value);
+
+const color = computed(() => "var(--primary-500)");
+const icon = "lucide-bell";
+
+function onClick() {
+  // handle click
+}
+</script>
+```
+
+## RULE 3: Update Module index.ts
+
+Replace `createAppModule(pages, locales, notificationTemplates)` with `defineAppModule({ notifications })`. Import each notification template individually instead of using a barrel `import *`.
+
+**BEFORE:**
+
+```typescript
+import * as pages from "./pages";
+import * as locales from "./locales";
+import * as notificationTemplates from "./components/notifications";
+
+export default createAppModule(pages, locales, notificationTemplates);
+```
+
+**AFTER:**
+
+```typescript
+import * as pages from "./pages";
+import * as locales from "./locales";
+import MyCreatedEvent from "./notifications/MyCreatedEvent.vue";
+import MyDeletedEvent from "./notifications/MyDeletedEvent.vue";
+import { defineAppModule } from "@vc-shell/framework";
+
+export default defineAppModule({
+  blades: pages,
+  locales,
+  notifications: {
+    MyCreatedDomainEvent: {
+      template: MyCreatedEvent,
+      toast: { mode: "auto" },
+    },
+    MyDeletedDomainEvent: {
+      template: MyDeletedEvent,
+      toast: { mode: "auto", severity: "warning" },
+    },
+  },
+});
+```
+
+Toast options:
+
+- `mode`: `"auto"` (show and auto-dismiss), `"progress"` (show with progress bar), `"silent"` (no toast)
+- `severity`: `"info"` (default), `"warning"`, `"error"`, `"critical"`
+
+## RULE 4: Replace useNotifications in Blades
+
+Replace `useNotifications()` with `useBladeNotifications()`. Remove `setNotificationHandler`, `moduleNotifications` watch, and `notifyType` from `defineOptions`.
+
+**BEFORE:**
+
+```typescript
+defineOptions({
+  name: "MyBlade",
+  notifyType: "MyDomainEvent",
+});
+
+const { markAsRead, setNotificationHandler, moduleNotifications } = useNotifications("MyDomainEvent");
+
+setNotificationHandler((message) => {
+  if (message.title) {
+    notification.success(message.title, {
+      onClose() {
+        markAsRead(message);
+      },
+    });
+  }
+});
+
+// or watch pattern:
+watch(
+  moduleNotifications,
+  (newVal) => {
+    // manual toast management
+  },
+  { deep: true },
+);
+```
+
+**AFTER:**
+
+```typescript
+defineOptions({
+  name: "MyBlade",
+  // notifyType removed
+});
+
+const { messages } = useBladeNotifications({
+  types: ["MyDomainEvent"],
+  onMessage: () => reloadData(),
+});
+```
+
+For progress notifications:
+
+```typescript
+// Module config: notifications: { MyProgressEvent: { toast: { mode: "progress" } } }
+useBladeNotifications({
+  types: ["MyProgressEvent"],
+  filter: (msg) => msg.entityId === param.value,
+  onMessage: (msg) => refreshData(msg),
+});
+```
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm notification templates render correctly in the notification panel
+3. Confirm toast notifications appear for configured event types
+4. Confirm `useBladeNotifications` triggers `onMessage` callback when events arrive
+5. Confirm `notifyType` is removed from all `defineOptions` calls
+6. Confirm `components/notifications/` directory is removed and `notifications/` exists at module root
+7. Confirm no remaining imports of `useNotifications`, `setNotificationHandler`, or `moduleNotifications`
+8. Confirm no remaining `defineProps` or `defineOptions({ inheritAttrs: false })` in notification templates

package/runtime/knowledge/migration-prompts/nswag-migration.md

@@ -0,0 +1,244 @@
+---
+name: nswag-migration
+description: AI transformation rules for NSwag class→interface DTO migration.
+---
+
+# NSwag API Client Migration: Class to Interface
+
+You are tasked with fixing TypeScript errors caused by migrating NSwag-generated API clients from class-based to interface-based data models.
+
+**Context:**
+
+- API Client CLASSES (e.g., `*Client` classes) remain unchanged — they still have constructors
+- DATA MODEL types (DTOs, Commands, Queries, etc.) are now INTERFACES instead of classes
+- Interfaces cannot be instantiated with `new` — use object literals with type assertions instead
+
+## RULE 1: Import Name Changes (Remove "I" Prefix)
+
+**Error:** `error TS2724: has no exported member named 'IXxx'. Did you mean 'Xxx'?`
+
+**Fix:** Remove the "I" prefix from all data model interface imports.
+
+```typescript
+// BEFORE
+import { IOffer, ISeller, ISearchQuery } from "@your-api-package";
+
+// AFTER
+import { Offer, Seller, SearchQuery } from "@your-api-package";
+```
+
+Also update all type annotations in the file:
+
+```typescript
+// BEFORE
+const item = ref<IOffer>(...);
+function process(data: IOffer): IOffer { ... }
+
+// AFTER
+const item = ref<Offer>(...);
+function process(data: Offer): Offer { ... }
+```
+
+## RULE 2: Class Instantiation → Object Literals
+
+**Error:** `error TS2693: 'Xxx' only refers to a type, but is being used as a value here`
+
+**Fix:** Replace `new TypeName({...})` with `{...} as TypeName` or typed variable declaration.
+
+**Pattern A — Command/Query objects:**
+
+```typescript
+// BEFORE
+const command = new CreateCommand({
+  id: "123",
+  name: "Test",
+  details: new Details({ value: 100 }),
+});
+
+// AFTER
+const command: CreateCommand = {
+  id: "123",
+  name: "Test",
+  details: { value: 100 } as Details,
+};
+```
+
+**Pattern B — Search/Query criteria:**
+
+```typescript
+// BEFORE
+const criteria = new SearchQuery({
+  take: 20,
+  skip: 0,
+  sort: "name:asc",
+});
+
+// AFTER
+const criteria: SearchQuery = {
+  take: 20,
+  skip: 0,
+  sort: "name:asc",
+};
+```
+
+**Pattern C — Empty/default objects:**
+
+```typescript
+// BEFORE
+const item = ref<IEntity>(new Entity());
+
+// AFTER
+const item = ref<Entity>({} as Entity);
+```
+
+**Pattern D — Nested objects:**
+
+```typescript
+// BEFORE
+const data = ref(new Parent({ child: new Child() }));
+
+// AFTER
+const data = ref<Parent>({
+  child: {} as Child,
+} as Parent);
+```
+
+**Pattern E — With Vue reactive():**
+
+```typescript
+// BEFORE
+const item = ref<Order>(reactive(new Order()));
+
+// AFTER
+const item = ref<Order>(reactive({} as Order));
+```
+
+## RULE 3: Factory Functions for Framework Callbacks
+
+**Error:** `error TS2693: 'PropertyValue' only refers to a type, but is being used as a value here`
+
+When a framework function expects a constructor function (callable with `new`), create factory functions:
+
+```typescript
+// BEFORE — Framework expects constructor
+const { loadItems } = useFrameworkHook<Type1, Type2>(fetchFunction, ItemClass, OtherClass);
+
+// AFTER — Create factory functions
+const createItem = (data?: Partial<ItemType>): ItemType => ({ ...data }) as ItemType;
+
+const createOther = (data?: Partial<OtherType>): OtherType => ({ ...data }) as OtherType;
+
+const { loadItems } = useFrameworkHook<Type1, Type2>(fetchFunction, createItem, createOther);
+```
+
+## RULE 4: Image Import Conflict with Global DOM Type
+
+**Error:** `error TS2866: Import 'Image' conflicts with global value used in this file`
+
+**Fix:** Use type-only import or rename:
+
+```typescript
+// BEFORE
+import { Image, Entity } from "@your-api-package";
+
+// AFTER — Option 1: Type-only import
+import { type Image, Entity } from "@your-api-package";
+
+// AFTER — Option 2: Rename import
+import { Image as ApiImage, Entity } from "@your-api-package";
+```
+
+## RULE 5: Implicit Any Types
+
+**Error:** `error TS7006: Parameter 'x' implicitly has an 'any' type`
+
+**Fix:** Add explicit type annotations to callback parameters:
+
+```typescript
+// BEFORE
+items.map((x) => x.id);
+items.filter((item) => item.active);
+data.forEach((d) => process(d));
+
+// AFTER
+items.map((x: ItemType) => x.id);
+items.filter((item: ItemType) => item.active);
+data.forEach((d: DataType) => process(d));
+```
+
+## RULE 6: Type Mismatch in Function Arguments
+
+**Error:** `error TS2345: Argument of type 'X' is not assignable to parameter of type 'Y'`
+
+Check if the function signature expects a different type (often an ID instead of a full object):
+
+```typescript
+// BEFORE
+someFunction(asset); // asset is full object
+
+// AFTER
+someFunction(asset.id); // pass the id property
+```
+
+## Important Notes
+
+1. **API Client Classes are NOT affected** — Do NOT modify client classes like `*Client`. They remain classes with constructors:
+
+   ```typescript
+   const { getApiClient } = useApiClient(MyApiClient); // No change needed
+   ```
+
+2. **Spread operators work with interfaces:**
+
+   ```typescript
+   const updated = { ...existingItem, name: "New Name" }; // Works fine
+   ```
+
+3. **Required properties must be provided** when using type assertions:
+
+   ```typescript
+   const details: ItemDetails = {
+     sku: item.sku || "",
+     ...otherProps,
+   };
+   ```
+
+4. **Generic type parameters need updating too:**
+
+   ```typescript
+   // BEFORE
+   const { action } = useAsync<ISearchQuery>(...)
+
+   // AFTER
+   const { action } = useAsync<SearchQuery>(...)
+   ```
+
+5. **Interfaces with all optional properties** can use empty object:
+
+   ```typescript
+   const query: SearchQuery = {}; // OK if all properties are optional
+   ```
+
+6. **Interfaces with required properties** need those properties:
+   ```typescript
+   const item: Item = { id: "default" }; // Must provide 'id'
+   ```
+
+## Quick Reference Table
+
+| Error Code | Pattern                      | Fix                                             |
+| ---------- | ---------------------------- | ----------------------------------------------- |
+| TS2724     | `IXxx` not found             | Remove "I" prefix from import                   |
+| TS2693     | Type used as value           | Replace `new Type({})` with `{} as Type`        |
+| TS2866     | Import conflicts with global | Use `type` import or rename                     |
+| TS7006     | Implicit any                 | Add explicit type annotation                    |
+| TS2345     | Type not assignable          | Check if property (like `.id`) should be passed |
+
+## Verification
+
+After making changes:
+
+1. Run TypeScript compiler: `npx tsc --noEmit` or `npx vue-tsc --noEmit`
+2. Verify no new errors were introduced
+3. Build the project to ensure everything compiles
+4. Test affected functionality if possible