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

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [2.0.0-alpha.33](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.32...v2.0.0-alpha.33) (2026-04-14)
+
+
+### Bug Fixes
+
+* **vc-app-skill:** add VC_SHELL_MIGRATE_CLI env override for local testing ([010d2f2](https://github.com/VirtoCommerce/vc-shell/commit/010d2f2ecb29d31d9134406bcd18e46e5883208b))
+* **vc-app-skill:** resolve migrate CLI from project node_modules before npx fallback ([82a8156](https://github.com/VirtoCommerce/vc-shell/commit/82a81563f7fdb94a94a7b8a80796ecffc671a39c))
+* **vc-app-skill:** resolve migrate CLI locally in dev mode, fallback to npx ([89888a0](https://github.com/VirtoCommerce/vc-shell/commit/89888a06cc0b4a1519f46f070ee06ebb0d82fd09))
+
+
+### Features
+
+* **vc-app-skill:** add /vc-app migrate command with full migration pipeline ([35a8b11](https://github.com/VirtoCommerce/vc-shell/commit/35a8b119457b14f6f4626caf133476222afd6663))
+* **vc-app-skill:** add migration prompt knowledge base (nswag, widgets, form, blade-props, notifications) ([a0b0eb2](https://github.com/VirtoCommerce/vc-shell/commit/a0b0eb2a96521916a72bdbf787961c1c96f96f6d))
+* **vc-app-skill:** add migration-agent subagent prompt ([29ac155](https://github.com/VirtoCommerce/vc-shell/commit/29ac1550c8e3c9b71d5dbc2ade7ea86b4d40213f))
+# [2.0.0-alpha.32](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.31...v2.0.0-alpha.32) (2026-04-02)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
 # [2.0.0-alpha.31](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.30...v2.0.0-alpha.31) (2026-04-01)
 
 **Note:** Version bump only for package @vc-shell/vc-app-skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0-alpha.31",
+  "version": "2.0.0-alpha.33",
   "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-alpha.31
+2.0.0-alpha.33

package/runtime/agents/migration-agent.md

@@ -0,0 +1,83 @@
+---
+name: migration-agent
+description: Performs AI-powered manual migrations on files identified by MIGRATION_REPORT.md, using transformation rules from migration prompts.
+---
+
+## Input Contract
+
+```json
+{
+  "required": {
+    "cwd": "string — absolute path to project root",
+    "reportPath": "string — path to MIGRATION_REPORT.md",
+    "topics": "array — migration topics to process, each with: { name, affectedFiles, migrationPromptPath, patternPath? }"
+  }
+}
+```
+
+## Knowledge Loading
+
+For each topic in `topics`:
+1. Read the migration prompt from `migrationPromptPath` — these contain specific transformation rules with BEFORE/AFTER examples
+2. If `patternPath` is provided, read the pattern file — this shows what correct target code looks like
+
+Do NOT read all prompts upfront. Load each topic's knowledge just before processing that topic.
+
+## Processing Strategy
+
+### Topic Order
+
+Process topics in this order (dependencies first):
+1. `notifications-migration` — may create new files and restructure directories
+2. `nswag-migration` — type-level changes that affect all other code
+3. `widgets-migration` — creates new composable files referenced by blades
+4. `blade-form-migration` — depends on correct types from nswag
+5. `blade-props-migration` — final cleanup of reusable components
+
+Skip topics not present in the `topics` input.
+
+### Per-File Strategy
+
+For each affected file in the current topic:
+
+1. **Read the file** completely
+2. **Apply transformation rules** from the loaded migration prompt — follow the BEFORE/AFTER patterns exactly
+3. **Create new files if required** by the prompt (e.g. `widgets/useXxxWidgets.ts` for widget migration)
+4. **Write the modified file**
+5. **Type-check:** Run `cd {cwd} && npx vue-tsc --noEmit 2>&1 | head -30` to check for errors
+6. **If errors in this file:** Read error messages, fix, re-check. Max 3 attempts.
+7. **If fixed or clean:** Commit: `fix(migrate): {topic name} — {filename}`
+8. **If still broken after 3 attempts:** Revert the file (`git checkout -- {filepath}`), report as "needs manual intervention", continue to next file
+
+### Important Rules
+
+1. **Only modify files listed in the topic's `affectedFiles`** — do not touch other files unless creating new files required by the migration prompt (e.g. widget composables)
+2. **Follow transformation rules exactly** — each migration prompt has specific BEFORE/AFTER patterns. Apply them mechanically.
+3. **Do not add features or refactor** — only transform existing code to the new API
+4. **Preserve all business logic** — the behavior must stay identical after migration
+5. **Commit after each successfully migrated file** — atomic commits for easy rollback
+6. **Do not modify `api_client/` directory** — generated code, not consumer code
+7. **Do not modify `node_modules/`**
+
+## Output
+
+When all topics are processed, report:
+
+```
+## Migration Agent Report
+
+### Completed
+- {topic}: {N} files migrated
+  - src/path/to/file.vue ✅
+  - src/path/to/other.ts ✅
+
+### Failed (needs manual intervention)
+- {topic}: {M} files failed
+  - src/path/to/problem.vue — {error description}
+
+### New Files Created
+- src/modules/xxx/widgets/useXxxWidgets.ts
+
+### Remaining TypeScript Errors
+{output of final vue-tsc --noEmit, if any}
+```

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 2f71da38b on 2026-04-01T16:03:16.012Z
+Synced from framework at commit b399787ff on 2026-04-14T15:15:27.844Z

package/runtime/knowledge/docs/core/composables/bladeContext/index.docs.md

@@ -0,0 +1,111 @@
+# useBladeContext (defineBladeContext / injectBladeContext)
+
+Exposes blade-level data to descendant widgets, extensions, and nested components via Vue's provide/inject mechanism. This pair of functions eliminates the need for prop drilling when child widgets or extension points need access to the parent blade's entity data, loading flags, or other shared state.
+
+The pattern follows a "define once, inject anywhere" approach: the blade component calls `defineBladeContext` during setup, and any descendant (no matter how deeply nested) can call `injectBladeContext` to read that data reactively.
+
+## When to Use
+
+- Share blade state (current entity, loading flags, disabled state) with child widgets without prop drilling
+- Access parent blade data from an extension or widget component
+- Expose selective fields to widgets (e.g., only the entity ID) via a computed getter
+- When NOT to use: for cross-blade communication between sibling blades (use `useBlade` / blade messaging instead)
+
+## Basic Usage
+
+```typescript
+// In a blade's <script setup>
+import { defineBladeContext, injectBladeContext } from '@vc-shell/framework';
+
+// Provide context — refs/computeds are auto-unwrapped for consumers
+defineBladeContext({ item, disabled, loading });
+
+// Or with a computed for selective exposure
+defineBladeContext(computed(() => ({ id: item.value?.id })));
+```
+
+```typescript
+// In a widget or nested component
+import { injectBladeContext } from '@vc-shell/framework';
+
+const ctx = injectBladeContext();
+// Refs are already unwrapped — access values directly, no .value needed
+const entityId = computed(() => ctx.value.id as string);
+const item = computed(() => ctx.value.item as { id: string; name: string });
+```
+
+## API
+
+### defineBladeContext
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `data` | `MaybeRefOrGetter<Record<string, unknown>>` | Yes | Plain object, ref, or getter to expose |
+
+Returns `void`. Must be called in the blade's `<script setup>`.
+
+### injectBladeContext
+
+Takes no parameters. Returns `ComputedRef<Record<string, unknown>>`.
+
+Throws `InjectionError` if no ancestor blade has called `defineBladeContext`.
+
+## Recipe: Widget Consuming Blade Context
+
+A typical pattern is a sidebar widget that needs to load related data based on the current blade entity. The widget does not receive any props from the blade -- it reads the entity ID from the blade context:
+
+```vue
+<script setup lang="ts">
+// widgets/RelatedOrdersWidget.vue
+import { computed, watch } from "vue";
+import { injectBladeContext } from "@vc-shell/framework";
+
+const ctx = injectBladeContext();
+const customerId = computed(() => ctx.value.id as string | undefined);
+
+// Reload orders whenever the customer changes
+watch(customerId, async (id) => {
+  if (id) {
+    await loadOrders(id);
+  }
+});
+</script>
+```
+
+```vue
+<script setup lang="ts">
+// blades/CustomerDetailBlade.vue
+import { ref, computed } from "vue";
+import { defineBladeContext } from "@vc-shell/framework";
+
+const customer = ref({ id: "cust-1", name: "Acme Corp" });
+const loading = ref(false);
+
+// Expose the customer data to all descendant widgets
+defineBladeContext(computed(() => ({
+  id: customer.value?.id,
+  name: customer.value?.name,
+  loading: loading.value,
+})));
+</script>
+```
+
+## Details
+
+- **Automatic ref unwrapping**: `defineBladeContext` shallow-unwraps all ref/computed values in the provided object. Consumers get plain values directly (`ctx.value.item` instead of `ctx.value.item.value`). This works reactively — when the source ref changes, the context updates automatically.
+- **Reactivity**: The provided context is always wrapped in a `computed`, so consumers receive a `ComputedRef` regardless of whether the provider passed a plain object, a ref, or a getter. Changes propagate automatically.
+- **Injection key**: Uses `BladeContextKey` from `framework/injection-keys.ts`. This is a framework-level Symbol, so there is no risk of key collision with application code.
+- **Error handling**: `injectBladeContext` throws an `InjectionError` with a descriptive message if called outside a blade component tree. This fails fast during development rather than silently returning `undefined`.
+- **Scope**: The context is scoped to the Vue component subtree. Each blade in the stack has its own context, so nested blades do not leak data upward or sideways.
+
+## Tips
+
+- Prefer exposing a computed getter rather than the full reactive object when only a subset of fields is needed. This minimizes unnecessary re-renders in consuming widgets.
+- The context value is untyped (`Record<string, unknown>`). Use type assertions or a typed wrapper in your module if you need type safety (e.g., `ctx.value.id as string`).
+- If a blade does not call `defineBladeContext`, any descendant calling `injectBladeContext` will throw. Make sure all blades that host widgets define their context.
+
+## Related
+
+- `BladeContextKey` in `framework/injection-keys.ts`
+- `useBladeWidgets` -- widgets that consume blade context
+- `useBladeStack` -- manages the blade navigation stack

package/runtime/knowledge/docs/core/composables/useBladeForm/useBladeForm.docs.md

@@ -0,0 +1,167 @@
+# useBladeForm
+
+Unified form state management for blades. Replaces manual combination of `useForm` + `useModificationTracker` + `useBeforeUnload` + `onBeforeClose` with a single composable.
+
+## Import
+
+```ts
+import { useBladeForm } from "@vc-shell/framework";
+```
+
+## Basic Usage
+
+```ts
+const { item, loadItem, saveItem } = useItemData();
+
+const form = useBladeForm({ data: item });
+
+onMounted(async () => {
+  await loadItem({ id: param.value });
+  form.setBaseline(); // snapshot current data as pristine
+});
+
+// Toolbar
+const toolbar = ref<IBladeToolbar[]>([
+  {
+    id: "save",
+    title: "Save",
+    icon: "lucide-save",
+    disabled: computed(() => !form.canSave.value),
+    async clickHandler() {
+      await saveItem(item.value);
+      form.setBaseline(); // snapshot after save
+      callParent("reload");
+    },
+  },
+]);
+```
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `data` | `Ref<T>` | required | Reactive data object for the form |
+| `canSaveOverride` | `ComputedRef<boolean>` | — | Additional condition for canSave |
+| `autoBeforeClose` | `boolean \| ComputedRef<boolean>` | `true` | Close guard behavior |
+| `autoBeforeUnload` | `boolean` | `true` | Browser tab close guard |
+| `closeConfirmMessage` | `MaybeRefOrGetter<string>` | — | Custom unsaved changes message |
+| `onRevert` | `() => void \| Promise<void>` | — | Custom revert handler |
+
+### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `setBaseline()` | `() => void` | Snapshot current data as pristine. Call after load and after save |
+| `markReady()` | `() => void` | Mark form ready without resetting pristine snapshot. Computes modification state from current data vs setup-time snapshot |
+| `revert()` | `() => void \| Promise<void>` | Revert data to pristine (or call onRevert) |
+| `canSave` | `ComputedRef<boolean>` | `isReady && valid && modified && canSaveOverride` |
+| `isModified` | `ComputedRef<boolean>` | Data differs from pristine (false until setBaseline) |
+| `isReady` | `ComputedRef<boolean>` | setBaseline() called at least once |
+| `formMeta` | vee-validate meta | Form validation state |
+| `setFieldError` | function | Set field error programmatically |
+| `errorBag` | Ref | All field errors |
+
+## Lifecycle
+
+### Standard (edit existing entity)
+```
+Mount → Load data → setBaseline() → User edits → Save → setBaseline()
+                                                  └→ Cancel → revert()
+```
+
+### Pre-filled (create from template)
+```
+Mount → Pre-fill data → markReady() → canSave = true immediately
+                                       └→ Save → setBaseline()
+```
+
+## VcBlade Integration
+
+`useBladeForm` auto-provides form state to `VcBlade` via inject. No need to pass `:modified` prop:
+
+```vue
+<!-- Before -->
+<VcBlade :modified="isModified" :toolbar-items="toolbar">
+
+<!-- After -->
+<VcBlade :toolbar-items="toolbar">
+```
+
+## Advanced: Readonly Blade
+
+```ts
+const disabled = computed(() => !!param.value && !item.value?.canBeModified);
+
+const form = useBladeForm({
+  data: item,
+  canSaveOverride: computed(() => !disabled.value),
+  autoBeforeClose: computed(() => !disabled.value), // no prompt when readonly
+});
+```
+
+## Advanced: Custom Revert
+
+```ts
+const form = useBladeForm({
+  data: item,
+  onRevert: () => loadItem({ id: param.value }), // reload from server
+});
+```
+
+## Advanced: Pre-filled Entity (markReady)
+
+When creating a new entity that is pre-populated from a parent (e.g. new offer from a product), the form should be immediately saveable. Use `markReady()` instead of `setBaseline()`:
+
+```ts
+const form = useBladeForm({ data: item });
+
+onMounted(async () => {
+  // Populate base fields
+  item.value.sku = generateSku();
+  await addEmptyInventory();
+
+  const hasTemplate = !param.value && !!options.value?.templateId;
+
+  if (hasTemplate) {
+    // Fill from template — data diverges from the setup-time snapshot
+    await fillFromTemplate(options.value.templateId);
+    // Mark ready: compares current data to setup-time snapshot → isModified = true
+    form.markReady();
+  } else {
+    // Standard load — current state becomes the pristine baseline
+    await loadItem({ id: param.value });
+    form.setBaseline();
+  }
+});
+```
+
+### setBaseline vs markReady
+
+| | `setBaseline()` | `markReady()` |
+|--|-----------------|---------------|
+| Sets `isReady` | yes | yes |
+| Updates pristine snapshot | yes (current data → pristine) | no (keeps setup-time snapshot) |
+| `trackerIsModified` after call | `false` | computed: `data !== pristineSnapshot` |
+| Use case | Load / Save — "this is the clean state" | Pre-fill — "form is ready, changes are intentional" |
+
+### How it works
+
+At composable creation, `useBladeForm` takes a snapshot of `data` (the **setup-time snapshot**). When `markReady()` is called:
+
+1. `isReady` → `true` (gates `canSave` and the deep watcher)
+2. `trackerIsModified` = `!semanticEqual(data, setupTimeSnapshot)` — since data was mutated during `onMounted`, this evaluates to `true`
+3. Subsequent edits are tracked normally by the deep watcher
+
+After save, call `setBaseline()` as usual to capture the saved state as the new pristine snapshot.
+
+## Constraints
+
+- **Must be called from component `setup()`** (or `<script setup>`). Do NOT call from shared data-composables.
+- Validation rules stay in template (`<Field rules="...">`).
+- `setBaseline()` must be called after data is loaded — before that, `canSave` and `isModified` are `false`.
+
+## Migration
+
+See `MIGRATION_GUIDE.md` for step-by-step instructions on migrating existing modules.