@vc-shell/vc-app-skill 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [2.0.1](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0...v2.0.1) (2026-04-24)
+
+### Features
+
+- enhance migrate transforms, fix notification race condition, update migration docs (#221) ([3c2134d](https://github.com/VirtoCommerce/vc-shell/commit/3c2134d0fa1016a2e4e075a12bb9df9a31b3d381)), closes [#221](https://github.com/VirtoCommerce/vc-shell/issues/221)
+
+### Bug Fixes
+
+- **hooks:** update npm version retrieval in vc-app-check-update.js ([c8f0e68](https://github.com/VirtoCommerce/vc-shell/commit/c8f0e68ded994bdfb8d01dcf96e90184b9d278cd))
+
 # [2.0.0](https://github.com/VirtoCommerce/vc-shell/compare/v1.2.3...v2.0.0) (2026-04-22)
 
 ### Features

package/hooks/vc-app-check-update.js

@@ -35,7 +35,11 @@ if (!fs.existsSync(cacheDir)) {
   fs.mkdirSync(cacheDir, { recursive: true });
 }
 
-const child = spawn(process.execPath, ["-e", `
+const child = spawn(
+  process.execPath,
+  [
+    "-e",
+    `
   const fs = require("fs");
   const { execSync } = require("child_process");
 
@@ -54,7 +58,7 @@ const child = spawn(process.execPath, ["-e", `
 
   let latest = null;
   try {
-    latest = execSync("npm view @vc-shell/vc-app-skill@alpha version", { encoding: "utf8", timeout: 10000, windowsHide: true }).trim();
+    latest = execSync("npm view @vc-shell/vc-app-skill@latest version", { encoding: "utf8", timeout: 10000, windowsHide: true }).trim();
   } catch (e) {}
 
   const result = {
@@ -65,10 +69,13 @@ const child = spawn(process.execPath, ["-e", `
   };
 
   fs.writeFileSync(cacheFile, JSON.stringify(result));
-`], {
-  stdio: "ignore",
-  windowsHide: true,
-  detached: true
-});
+`,
+  ],
+  {
+    stdio: "ignore",
+    windowsHide: true,
+    detached: true,
+  },
+);
 
 child.unref();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.0.0
+2.0.1

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit be4d05add on 2026-04-22T12:54:33.589Z
+Synced from framework at commit 5f8005c08 on 2026-04-24T08:05:31.316Z

package/runtime/knowledge/docs/core/notifications/notifications.docs.md

@@ -17,7 +17,12 @@ The notification system receives `PushNotification` messages from the platform S
 ```
 PushNotification (SignalR)
         |
-        v
+  ┌─────┴─────┐
+  Send     SendSystemEvents
+  |            |
+  |     broadcastFilter?
+  |            |
+  v            v
   NotificationStore.ingest()
         |
         +---> history[]  (persistent, loaded from API)
@@ -47,7 +52,9 @@ Returns the shared `NotificationStore` singleton. Resolution order:
 | `unreadCount`                | `ComputedRef<number>`                        | Count of unread notifications in history                             |
 | `hasUnread`                  | `ComputedRef<boolean>`                       | Whether any unread notifications exist                               |
 | `registerType(type, config)` | `(string, NotificationTypeConfig) => void`   | Register a notification type with toast/template config              |
-| `ingest(message)`            | `(PushNotification) => void`                 | Process an incoming notification (upsert, toast, notify subscribers) |
+| `ingest(message, opts?)`     | `(PushNotification, {broadcast?}?) => void`  | Process an incoming notification; broadcast messages are filtered    |
+| `setBroadcastFilter(fn)`     | `((PushNotification) => boolean) => void`    | Set filter for broadcast messages (SendSystemEvents)                 |
+| `clearBroadcastFilter()`     | `() => void`                                 | Remove the broadcast filter                                          |
 | `markAsRead(message)`        | `(PushNotification) => void`                 | Mark a single notification as read                                   |
 | `markAllAsRead()`            | `() => Promise<void>`                        | Optimistic mark-all-as-read with server sync and rollback on failure |
 | `loadHistory(take?)`         | `(number?) => Promise<void>`                 | Load notification history from the API (default: 10)                 |
@@ -105,6 +112,35 @@ const notificationRef = useNotificationContext<IOrderNotification>();
 // notificationRef.value.orderId, notificationRef.value.title, etc.
 ```
 
+### `useBroadcastFilter()`
+
+Controls which broadcast push notifications (`SendSystemEvents`) are accepted by the store. Targeted notifications (`Send`) are always accepted regardless of filter.
+
+**File:** `composables/useBroadcastFilter.ts`
+
+#### Returns
+
+```typescript
+interface UseBroadcastFilterReturn {
+  setBroadcastFilter(fn: (msg: PushNotification) => boolean): void;
+  clearBroadcastFilter(): void;
+}
+```
+
+#### Example
+
+```typescript
+import { useBroadcastFilter } from "@vc-shell/framework";
+
+const { setBroadcastFilter, clearBroadcastFilter } = useBroadcastFilter();
+
+// Accept only notifications for the current seller
+setBroadcastFilter((msg) => msg.creator === currentSellerId);
+
+// Remove filter (accept all broadcast messages)
+clearBroadcastFilter();
+```
+
 ### Toast Controller
 
 Handles toast popup display based on `NotificationTypeConfig.toast` settings. Created internally by the store.

package/runtime/knowledge/migration-prompts/blade-form-migration.md

@@ -63,13 +63,14 @@ const { canSave, isModified, setBaseline, revert, setFieldError, errorBag } = us
   closeConfirmMessage: () => t("MY_MODULE.ALERTS.CLOSE_CONFIRMATION"),
 });
 
-watch(
-  item,
-  () => {
-    if (item.value) setBaseline();
-  },
-  { once: true },
-);
+// Call setBaseline() AFTER data is loaded in onMounted.
+// Do NOT use watch(item, ..., { once: true }) — it only detects ref
+// replacement (item.value = newData), not in-place mutations
+// (Object.assign(item.value, newData)).
+onMounted(async () => {
+  await load(param.value);
+  setBaseline();
+});
 
 async function handleSave() {
   await save(item.value);
@@ -77,6 +78,8 @@ async function handleSave() {
 }
 ```
 
+**IMPORTANT — `setBaseline()` placement:** Always call `setBaseline()` AFTER the async load completes, inside `onMounted` or after the load function returns. A `watch(data, ..., { once: true })` watcher fails when the composable mutates data in-place via `Object.assign(data.value, loadedData)` instead of replacing the ref — the watcher never fires because the `.value` reference doesn't change.
+
 ## RULE 2: Remove onBeforeClose Entirely
 
 `useBladeForm` handles the unsaved-changes guard automatically via `autoBeforeClose` (defaults to `true`).

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

@@ -90,7 +90,45 @@ 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
+## RULE 5: Remove `resolveBladeByName` — pass name directly to `openBlade`
+
+**BEFORE:**
+
+```typescript
+const { openBlade, resolveBladeByName } = useBlade();
+openBlade({ blade: resolveBladeByName("OrderDetails")!, param: orderId });
+```
+
+**AFTER:**
+
+```typescript
+const { openBlade } = useBlade();
+openBlade({ name: "OrderDetails", param: orderId });
+```
+
+Remove `resolveBladeByName` from the destructuring. The `blade` property in the openBlade argument is replaced by `name` (string).
+
+## RULE 6: Replace `onParentCall` with `callParent`
+
+**BEFORE:**
+
+```typescript
+const { onParentCall } = useBladeNavigation();
+onParentCall({ method: "reload" });
+onParentCall({ method: "updateItem", args: newItem });
+```
+
+**AFTER:**
+
+```typescript
+const { callParent } = useBlade();
+await callParent("reload");
+await callParent("updateItem", newItem);
+```
+
+Note: `callParent` is async and returns a Promise. Add `await` if the result matters.
+
+## RULE 7: Consolidate multiple `useBlade()` calls per file
 
 Use one `useBlade()` destructuring per component/composable unless there is a strong technical reason.
 
@@ -111,7 +149,7 @@ const { openBlade, closeSelf, callParent, param } = useBlade();
 
 After migration:
 
-1. Search and remove stale APIs: `useExternalWidgets`, `import moment`, `useFunctions(`, `closeBlade(`.
+1. Search and remove stale APIs: `useExternalWidgets`, `import moment`, `useFunctions(`, `closeBlade(`, `resolveBladeByName`, `onParentCall`.
 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

@@ -152,17 +152,28 @@ Toast options:
 
 ## RULE 4: Replace useNotifications in Blades
 
-Replace `useNotifications()` with `useBladeNotifications()`. Remove `setNotificationHandler`, `moduleNotifications` watch, and `notifyType` from `defineOptions`.
+Replace `useNotifications()` with `useBladeNotifications()`. Remove `setNotificationHandler`, the entire `watch(moduleNotifications, ...)` block, manual toast management, and `notifyType` from `defineOptions`.
+
+### What to DELETE (toast management is now automatic via module config):
+
+- The entire `watch(moduleNotifications/messages, ..., { deep: true })` block
+- All `notification()` / `notification.update()` calls related to notification messages
+- The `notificationId` ref used for toast tracking
+- `setNotificationHandler(...)` calls
+- `markAsRead()` calls inside toast `onClose` handlers
+- `notifyType` from `defineOptions`/`defineBlade`
+
+### What to EXTRACT into `onMessage`:
+
+- Only **data-reload logic** from the watch callback (e.g., `getTasks()`, `refreshData()`, `reload()`)
+- Add `filter` if the callback had blade-specific conditions (e.g., `message.profileId === param.value`)
+
+### Simple case: `setNotificationHandler`
 
 **BEFORE:**
 
 ```typescript
-defineOptions({
-  name: "MyBlade",
-  notifyType: "MyDomainEvent",
-});
-
-const { markAsRead, setNotificationHandler, moduleNotifications } = useNotifications("MyDomainEvent");
+const { markAsRead, setNotificationHandler } = useNotifications("MyDomainEvent");
 
 setNotificationHandler((message) => {
   if (message.title) {
@@ -173,12 +184,54 @@ setNotificationHandler((message) => {
     });
   }
 });
+```
+
+**AFTER:**
+
+```typescript
+useBladeNotifications({
+  types: ["MyDomainEvent"],
+});
+```
+
+### Complex case: `watch` with toast management + data reload
+
+**BEFORE:**
+
+```typescript
+const { moduleNotifications, markAsRead } = useNotifications("ImportPushNotification");
+const notificationId = ref();
 
-// or watch pattern:
 watch(
   moduleNotifications,
   (newVal) => {
-    // manual toast management
+    (newVal as ImportPushNotification[]).forEach((message) => {
+      const messageContent = message.profileName ? `${message.profileName}: ${message.title}` : message.title;
+
+      // DATA RELOAD — extract this into onMessage
+      if (!importStarted.value && message.profileId === param.value) {
+        getTasks({ profileId: message.profileId, importJobId: message.jobId });
+      }
+
+      // TOAST MANAGEMENT — delete all of this (handled by module config)
+      if (!message.finished) {
+        if (!notificationId.value && messageContent) {
+          notificationId.value = notification(messageContent, { timeout: false });
+        } else {
+          notification.update(notificationId.value, { content: messageContent });
+        }
+      } else {
+        notification.update(notificationId.value, {
+          timeout: 5000,
+          content: messageContent,
+          type: message.title === "Import failed" ? "error" : "success",
+          onClose() {
+            markAsRead(message);
+            notificationId.value = undefined;
+          },
+        });
+      }
+    });
   },
   { deep: true },
 );
@@ -187,28 +240,23 @@ watch(
 **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),
+  types: ["ImportPushNotification"],
+  filter: (msg) => (msg as ImportPushNotification).profileId === param.value,
+  onMessage: (msg) => {
+    if (!importStarted.value) {
+      getTasks({
+        profileId: (msg as ImportPushNotification).profileId,
+        importJobId: (msg as ImportPushNotification).jobId,
+      });
+    }
+  },
 });
+// DELETE: notificationId ref, watch block, notification()/notification.update() calls
 ```
 
+Toast appearance is configured in `defineAppModule({ notifications: { ImportPushNotification: { toast: { mode: "progress" } } } })`. The `markAsRead` is handled automatically.
+
 ## Verification
 
 After migration:

package/runtime/knowledge/migration-prompts/use-blade-migration.md

@@ -0,0 +1,153 @@
+---
+name: use-blade-migration
+description: AI transformation rules for useBladeNavigation → useBlade, resolveBladeByName removal, onParentCall → callParent.
+---
+
+# Blade Navigation Migration: useBladeNavigation → useBlade
+
+Replace `useBladeNavigation()`, `useBladeContext()`, `resolveBladeByName()`, and `onParentCall()` with the unified `useBlade()` composable.
+
+## RULE 1: Replace useBladeNavigation / useBladeContext with useBlade
+
+Rename the import and call site. Merge destructured properties from both into a single `useBlade()` call.
+
+**BEFORE:**
+
+```typescript
+import { useBladeNavigation } from "@vc-shell/framework";
+const { openBlade, resolveBladeByName, onBeforeClose } = useBladeNavigation();
+```
+
+**AFTER:**
+
+```typescript
+import { useBlade } from "@vc-shell/framework";
+const { openBlade, onBeforeClose } = useBlade();
+```
+
+If both `useBladeNavigation()` and `useBladeContext()` are used, merge into one `useBlade()`:
+
+**BEFORE:**
+
+```typescript
+const blade = useBlade();
+const { openBlade, onBeforeClose } = useBladeNavigation();
+registerWidget(myWidget, blade?.value.id ?? "");
+```
+
+**AFTER:**
+
+```typescript
+const { id: bladeId, openBlade, onBeforeClose } = useBlade();
+registerWidget(myWidget, bladeId.value);
+```
+
+## RULE 2: Remove resolveBladeByName
+
+`resolveBladeByName` is no longer needed — pass the blade name directly to `openBlade`.
+
+**BEFORE:**
+
+```typescript
+openBlade({ blade: resolveBladeByName("OrderDetails")!, param: orderId });
+```
+
+**AFTER:**
+
+```typescript
+openBlade({ name: "OrderDetails", param: orderId });
+```
+
+Also handle the pattern with options:
+
+**BEFORE:**
+
+```typescript
+openBlade({
+  blade: resolveBladeByName("ImportProcess")!,
+  param: profileId,
+  options: { title: profile.name, importJobId: jobId },
+});
+```
+
+**AFTER:**
+
+```typescript
+openBlade({
+  name: "ImportProcess",
+  param: profileId,
+  options: { title: profile.name, importJobId: jobId },
+});
+```
+
+Remove the `resolveBladeByName` destructure from `useBlade()` since it's no longer used.
+
+## RULE 3: Replace onParentCall with callParent
+
+**BEFORE:**
+
+```typescript
+const { onParentCall } = useBladeNavigation();
+onParentCall({ method: "reload" });
+onParentCall({ method: "updateItem", args: newItem });
+```
+
+**AFTER:**
+
+```typescript
+const { callParent } = useBlade();
+await callParent("reload");
+await callParent("updateItem", newItem);
+```
+
+Note: `callParent` is async and returns a Promise.
+
+## RULE 4: Invert onBeforeClose Boolean
+
+The guard semantics are **inverted** in the new API:
+
+| Legacy                         | New                           |
+| ------------------------------ | ----------------------------- |
+| `return false` → prevent close | `return true` → prevent close |
+| `return true` → allow close    | `return false` → allow close  |
+
+**BEFORE:**
+
+```typescript
+onBeforeClose(async () => {
+  if (isModified.value) {
+    return await showConfirmation(msg); // true = allow, false = prevent
+  }
+});
+```
+
+**AFTER:**
+
+```typescript
+onBeforeClose(async () => {
+  if (isModified.value) {
+    return !(await showConfirmation(msg)); // true = prevent, false = allow
+  }
+});
+```
+
+If `useBladeForm()` is used, `onBeforeClose` can be removed entirely — `useBladeForm` handles it automatically.
+
+## RULE 5: Clean Up Unused Imports
+
+After applying all rules, remove:
+
+- `useBladeNavigation` import
+- `useBladeContext` import
+- `resolveBladeByName` import (if it was imported separately)
+- Any unused destructured variables
+
+## Verification
+
+After migration:
+
+1. Run `npx vue-tsc --noEmit` to verify no TypeScript errors
+2. Confirm `openBlade` calls navigate correctly
+3. Confirm blade close confirmation dialogs still appear when data is modified
+4. Confirm no remaining imports of `useBladeNavigation`, `useBladeContext`, or `resolveBladeByName`
+5. Confirm no remaining `onParentCall` calls

package/runtime/vc-app.md

@@ -1600,19 +1600,19 @@ Parse the "Manual Migration Required" section. Extract each topic heading and th
 
 Map topic headings to migration prompt files and pattern files:
 
-| Report Heading contains (or equals transform name)                                           | Canonical topic name              | Migration Prompt                                                            | Pattern                                              |
-| -------------------------------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Widget / widgets-migration                                                                   | `widgets-migration`               | `{KNOWLEDGE_BASE}/migration-prompts/widgets-migration.md`                   | `{KNOWLEDGE_BASE}/patterns/blade-widget.md`          |
-| Form Management / useBladeForm / use-blade-form                                              | `use-blade-form`                  | `{KNOWLEDGE_BASE}/migration-prompts/blade-form-migration.md`                | `{KNOWLEDGE_BASE}/patterns/form-validation.md`       |
-| Injection Key / remove-deprecated-aliases                                                    | `remove-deprecated-aliases`       | `{KNOWLEDGE_BASE}/migration-prompts/blade-props-migration.md`               | `{KNOWLEDGE_BASE}/patterns/blade-navigation.md`      |
-| NSwag / DTO / Clone-then-mutate / nswag-class-to-interface                                   | `nswag-class-to-interface`        | `{KNOWLEDGE_BASE}/migration-prompts/nswag-migration.md`                     | —                                                    |
-| Reusable Blade Components / blade-props-simplification                                       | `blade-props-simplification`      | `{KNOWLEDGE_BASE}/migration-prompts/blade-props-migration.md`               | `{KNOWLEDGE_BASE}/patterns/child-blade-flow.md`      |
-| Notification / notification-migration                                                        | `notification-migration`          | `{KNOWLEDGE_BASE}/migration-prompts/notifications-migration.md`             | `{KNOWLEDGE_BASE}/patterns/signalr-notifications.md` |
-| VcTable / DataTable / vctable-audit                                                          | `vctable-audit`                   | `{KNOWLEDGE_BASE}/migration-prompts/datatable-migration.md`                 | `{KNOWLEDGE_BASE}/patterns/datatable-pattern.md`     |
-| Icon / material- / bi- / fa- / icon-audit                                                    | `icon-audit`                      | `{KNOWLEDGE_BASE}/migration-prompts/icon-migration.md`                      | —                                                    |
-| Assets API / useAssets / useAssetsManager / use-assets-migration                             | `use-assets-migration`            | `{KNOWLEDGE_BASE}/migration-prompts/use-assets-migration.md`                | `{KNOWLEDGE_BASE}/patterns/assets-management.md`     |
-| Manual Migration Audit / useExternalWidgets / moment / useFunctions / manual-migration-audit | `manual-migration-audit`          | `{KNOWLEDGE_BASE}/migration-prompts/manual-migration-audit.md`              | —                                                    |
-| Pagination / useDataTablePagination / use-data-table-pagination-audit                        | `use-data-table-pagination-audit` | `{KNOWLEDGE_BASE}/migration-prompts/use-data-table-pagination-migration.md` | —                                                    |
+| Report Heading contains (or equals transform name)                                                                               | Canonical topic name              | Migration Prompt                                                            | Pattern                                              |
+| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Widget / widgets-migration                                                                                                       | `widgets-migration`               | `{KNOWLEDGE_BASE}/migration-prompts/widgets-migration.md`                   | `{KNOWLEDGE_BASE}/patterns/blade-widget.md`          |
+| Form Management / useBladeForm / use-blade-form                                                                                  | `use-blade-form`                  | `{KNOWLEDGE_BASE}/migration-prompts/blade-form-migration.md`                | `{KNOWLEDGE_BASE}/patterns/form-validation.md`       |
+| Injection Key / remove-deprecated-aliases                                                                                        | `remove-deprecated-aliases`       | `{KNOWLEDGE_BASE}/migration-prompts/blade-props-migration.md`               | `{KNOWLEDGE_BASE}/patterns/blade-navigation.md`      |
+| NSwag / DTO / Clone-then-mutate / nswag-class-to-interface                                                                       | `nswag-class-to-interface`        | `{KNOWLEDGE_BASE}/migration-prompts/nswag-migration.md`                     | —                                                    |
+| Reusable Blade Components / blade-props-simplification                                                                           | `blade-props-simplification`      | `{KNOWLEDGE_BASE}/migration-prompts/blade-props-migration.md`               | `{KNOWLEDGE_BASE}/patterns/child-blade-flow.md`      |
+| Notification / notification-migration                                                                                            | `notification-migration`          | `{KNOWLEDGE_BASE}/migration-prompts/notifications-migration.md`             | `{KNOWLEDGE_BASE}/patterns/signalr-notifications.md` |
+| VcTable / DataTable / vctable-audit                                                                                              | `vctable-audit`                   | `{KNOWLEDGE_BASE}/migration-prompts/datatable-migration.md`                 | `{KNOWLEDGE_BASE}/patterns/datatable-pattern.md`     |
+| Icon / material- / bi- / fa- / icon-audit                                                                                        | `icon-audit`                      | `{KNOWLEDGE_BASE}/migration-prompts/icon-migration.md`                      | —                                                    |
+| Assets API / useAssets / useAssetsManager / use-assets-migration                                                                 | `use-assets-migration`            | `{KNOWLEDGE_BASE}/migration-prompts/use-assets-migration.md`                | `{KNOWLEDGE_BASE}/patterns/assets-management.md`     |
+| Manual Migration Audit / useExternalWidgets / moment / useFunctions / resolveBladeByName / onParentCall / manual-migration-audit | `manual-migration-audit`          | `{KNOWLEDGE_BASE}/migration-prompts/manual-migration-audit.md`              | —                                                    |
+| Pagination / useDataTablePagination / use-data-table-pagination-audit                                                            | `use-data-table-pagination-audit` | `{KNOWLEDGE_BASE}/migration-prompts/use-data-table-pagination-migration.md` | —                                                    |
 
 Build the `topics` array for the migration-agent using the canonical topic names above.