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

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

@@ -0,0 +1,248 @@
+---
+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

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

@@ -0,0 +1,157 @@
+---
+name: widgets-migration
+description: AI transformation rules for useWidgets→useBladeWidgets migration.
+---
+
+# Widget Migration: useWidgets → useBladeWidgets
+
+Migrate blade widgets from the imperative `useWidgets()` + `registerWidget()` API to the declarative `useBladeWidgets()` composable. The new API eliminates manual registration/cleanup and removes the need for per-widget `.vue` components when they only render a standard sidebar item.
+
+## RULE 1: Create Widget Composable
+
+For each blade that calls `registerWidget()`, create a `widgets/useXxxWidgets.ts` composable.
+
+**BEFORE:**
+
+```typescript
+// In XxxDetails.vue <script setup>
+import { useWidgets, useBlade } from "@vc-shell/framework";
+import type { BladeInstance } from "@vc-shell/framework";
+import { onMounted, onUnmounted } from "vue";
+import OffersWidget from "../widgets/OffersWidget.vue";
+
+const { registerWidget, clearBladeWidgets } = useWidgets();
+const { openBlade } = useBlade();
+
+onMounted(() => {
+  registerWidget(
+    {
+      id: "OffersWidget",
+      component: OffersWidget,
+      props: {
+        count: offersCount,
+        onClick: () => openBlade({ name: "OffersList", options: { productId: entity.value.id } }),
+      },
+    },
+    bladeContext.id,
+  );
+});
+
+onUnmounted(() => {
+  clearBladeWidgets(bladeContext.id);
+});
+```
+
+**AFTER:**
+
+```typescript
+// widgets/useProductWidgets.ts
+import { useBladeWidgets, useBlade } from "@vc-shell/framework";
+import type { UseBladeWidgetsReturn } from "@vc-shell/framework";
+import { computed, type Ref } from "vue";
+
+interface UseProductWidgetsOptions {
+  item: Ref<Product | undefined>;
+  isVisible: Ref<boolean> | boolean;
+  offersCount: Ref<number>;
+}
+
+export function useProductWidgets(options: UseProductWidgetsOptions): UseBladeWidgetsReturn {
+  const { item, isVisible, offersCount } = options;
+  const { openBlade } = useBlade();
+
+  return useBladeWidgets([
+    {
+      id: "OffersWidget",
+      icon: "lucide-tag",
+      title: "PRODUCTS.WIDGETS.OFFERS.TITLE",
+      badge: computed(() => offersCount.value),
+      isVisible,
+      onClick: () =>
+        openBlade({
+          name: "OffersList",
+          options: { productId: item.value?.id },
+        }),
+      onRefresh: async () => {
+        // load offers count logic here
+      },
+    },
+  ]);
+}
+```
+
+## RULE 2: Replace Usage in Blade Page
+
+Import the new composable and destructure `{ refreshAll }`.
+
+**BEFORE:**
+
+```typescript
+// XxxDetails.vue <script setup>
+import { useWidgets } from "@vc-shell/framework";
+import OffersWidget from "../widgets/OffersWidget.vue";
+import AssociationsWidget from "../widgets/AssociationsWidget.vue";
+
+const { registerWidget, clearBladeWidgets } = useWidgets();
+
+onMounted(() => {
+  registerWidget({ id: "OffersWidget", component: OffersWidget, props: { ... } }, bladeId);
+  registerWidget({ id: "AssociationsWidget", component: AssociationsWidget, props: { ... } }, bladeId);
+});
+
+onUnmounted(() => {
+  clearBladeWidgets(bladeId);
+});
+```
+
+**AFTER:**
+
+```typescript
+// XxxDetails.vue <script setup>
+import { useProductWidgets } from "../widgets/useProductWidgets";
+
+const isExisting = computed(() => !!param.value);
+
+const { refreshAll } = useProductWidgets({
+  item: entity,
+  isVisible: isExisting,
+  offersCount,
+});
+```
+
+## RULE 3: Remove Widget .vue Components
+
+Delete widget `.vue` files that only render a standard sidebar item (icon + title + badge + click handler). These are replaced by the declarative config in `useBladeWidgets()`.
+
+**Keep** the `.vue` component only if it has custom rendering beyond the standard widget layout.
+
+**Delete:**
+- `widgets/OffersWidget.vue` (if it only shows icon, title, badge, click)
+- `widgets/AssociationsWidget.vue` (same)
+
+**Keep:**
+- `widgets/CustomChartWidget.vue` (has custom chart rendering)
+
+## RULE 4: Remove Old Imports
+
+Remove these imports that are no longer needed:
+
+```typescript
+// REMOVE all of these:
+import { useWidgets } from "@vc-shell/framework";
+import type { BladeInstance } from "@vc-shell/framework"; // if only used for widgets
+import { registerWidget, unregisterWidget, clearBladeWidgets } from "...";
+import { onUnmounted } from "vue"; // if only used for widget cleanup
+import OffersWidget from "../widgets/OffersWidget.vue"; // deleted component
+```
+
+## Verification
+
+After migration:
+
+1. Run `npx tsc --noEmit` to verify no TypeScript errors
+2. Confirm widgets appear in the blade sidebar
+3. Confirm badge counts update reactively
+4. Confirm clicking a widget opens the correct child blade
+5. Confirm widgets are hidden when `isVisible` is false (e.g., on "create new" blades)
+6. Confirm no console errors about widget registration/cleanup on blade close

package/runtime/vc-app.md

@@ -53,6 +53,7 @@ Parse `$ARGUMENTS` to determine the subcommand:
 | `generate ...` | Section: `/vc-app generate` |
 | `promote <moduleName>` | Section: `/vc-app promote` |
 | `design ...`              | Section: `/vc-app design` |
+| `migrate`                | Section: `/vc-app migrate` |
 | empty / `help` / `--help` | Section: Help |
 
 If no arguments match, show the help section.
@@ -73,6 +74,7 @@ Commands:
   /vc-app generate            Generate a full UI module from intent (list/details blades, composables, locales)
   /vc-app promote <name>      Transition a prototype module from mock data to real API client
   /vc-app design [prompt]    Generate a full application from a free-text description (multi-module)
+  /vc-app migrate             Migrate existing app to latest @vc-shell/framework (CLI + AI)
 
 Examples:
   /vc-app create
@@ -1415,3 +1417,127 @@ Additional context:
 ```
 
 The agent will read its own instruction file, load any required knowledge/pattern files, execute its generation rules, perform its self-check, and report back.
+
+---
+
+## /vc-app migrate
+
+Fully automatic migration to the latest @vc-shell/framework version. Runs the CLI migrator for mechanical transforms, installs updated dependencies, then uses AI to complete manual migrations.
+
+### Step 1: Pre-flight checks
+
+1. Verify `@vc-shell/framework` exists in package.json (dependencies or devDependencies). If not found, stop: "This doesn't appear to be a vc-shell project."
+2. Run `git status --porcelain` — if output is non-empty, warn: "You have uncommitted changes. Commit or stash before migrating." Ask user to confirm before proceeding.
+3. Read current framework version from package.json for display.
+
+### Step 2: Run CLI migrator
+
+Resolve the migrate CLI binary. Run this shell snippet and use the result:
+
+```bash
+if [ -n "$VC_SHELL_MIGRATE_CLI" ] && [ -f "$VC_SHELL_MIGRATE_CLI" ]; then
+  echo "node $VC_SHELL_MIGRATE_CLI"
+elif [ -f "./node_modules/@vc-shell/migrate/dist/cli.js" ]; then
+  echo "node ./node_modules/@vc-shell/migrate/dist/cli.js"
+else
+  echo "npx @vc-shell/migrate"
+fi
+```
+
+Priority:
+1. **Env override:** `VC_SHELL_MIGRATE_CLI` env var
+2. **Project node_modules:** `./node_modules/@vc-shell/migrate/dist/cli.js`
+3. **npx fallback:** `npx @vc-shell/migrate`
+
+Run:
+
+```bash
+{resolved_migrate_command} --update-deps
+```
+
+Display the output to the user. If the command fails, stop and show the error.
+
+### Step 3: Install dependencies
+
+Run:
+
+```bash
+yarn install
+```
+
+If yarn fails (version conflicts, missing packages), stop and show the error. Dependencies must resolve before AI migration can type-check.
+
+### Step 4: Parse migration report
+
+Read `MIGRATION_REPORT.md` from project root.
+
+Parse the "Manual Migration Required" section. Extract each topic heading and the affected files listed under it.
+
+Map topic headings to migration prompt files and pattern files:
+
+| Report Heading contains | Migration Prompt | Pattern |
+|---|---|---|
+| Widget | `{KNOWLEDGE_BASE}/migration-prompts/widgets-migration.md` | `{KNOWLEDGE_BASE}/patterns/blade-widget.md` |
+| Form Management / useBladeForm | `{KNOWLEDGE_BASE}/migration-prompts/blade-form-migration.md` | `{KNOWLEDGE_BASE}/patterns/form-validation.md` |
+| Injection Key | `{KNOWLEDGE_BASE}/migration-prompts/blade-props-migration.md` | `{KNOWLEDGE_BASE}/patterns/blade-navigation.md` |
+| NSwag / DTO / Clone-then-mutate | `{KNOWLEDGE_BASE}/migration-prompts/nswag-migration.md` | — |
+| Reusable Blade Components | `{KNOWLEDGE_BASE}/migration-prompts/blade-props-migration.md` | `{KNOWLEDGE_BASE}/patterns/child-blade-flow.md` |
+| Notification | `{KNOWLEDGE_BASE}/migration-prompts/notifications-migration.md` | `{KNOWLEDGE_BASE}/patterns/signalr-notifications.md` |
+
+Build the `topics` array for the migration-agent, including only topics that appear in the report.
+
+### Step 5: Dispatch migration-agent
+
+If there are topics to process, dispatch the migration-agent subagent:
+
+**Agent:** `{SKILL_DIR}/agents/migration-agent.md`
+
+**Input:**
+
+```json
+{
+  "cwd": "<project root>",
+  "reportPath": "<path to MIGRATION_REPORT.md>",
+  "topics": [
+    {
+      "name": "<topic name>",
+      "affectedFiles": ["src/path/to/file.vue"],
+      "migrationPromptPath": "<absolute path to migration prompt>",
+      "patternPath": "<absolute path to pattern file or null>"
+    }
+  ]
+}
+```
+
+### Step 6: Type-check verification
+
+After migration-agent completes, run:
+
+```bash
+npx vue-tsc --noEmit
+```
+
+If there are remaining TypeScript errors:
+1. Show the errors to the user
+2. Attempt to fix iteratively — read each error, fix the file, re-check (max 3 rounds)
+
+### Step 7: Update report and summarize
+
+Update `MIGRATION_REPORT.md`:
+- For each topic the agent successfully completed, add ✅ to the heading
+- Add a "Completed by AI" section listing what was done
+
+Print summary to user:
+
+```
+Migration complete!
+
+  Mechanical (CLI):  {N} files
+  AI-assisted:       {M} files across {T} topics
+  Remaining issues:  {R} (see MIGRATION_REPORT.md)
+
+Next steps:
+  1. Review the changes: git diff
+  2. Run: yarn build
+  3. Test the application
+```