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

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
+```

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

@@ -1,185 +0,0 @@
-# Framework Constants
-
-Default values and configuration constants exported from `@vc-shell/framework` via `core/constants/index.ts`.
-
-## Overview
-
-Magic numbers scattered across a codebase make maintenance difficult and create inconsistencies. The vc-shell framework centralizes all layout dimensions, timing values, breakpoints, z-index layers, and component default props into a single constants module.
-
-These constants are organized into three categories:
-- **Top-level exports** -- standalone constants like `FALLBACK_BLADE_ID`
-- **`UI_CONSTANTS`** -- layout, timing, and threshold values used by the framework's UI layer
-- **`COMPONENT_DEFAULTS`** -- default prop values for each component type, accessible via `getComponentDefaults()`
-- **`languageToCountryMap`** -- locale-to-country code mapping for flag resolution
-
-All constants are importable from `@vc-shell/framework`.
-
-## Top-Level Exports
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `FALLBACK_BLADE_ID` | `"fallback-blade-id"` | Default blade identifier when no ID is provided |
-
-## UI Constants (`UI_CONSTANTS`)
-
-Centralized magic numbers for layout, timing, and thresholds.
-
-| Key | Value | Description |
-|-----|-------|-------------|
-| `GRID_COLUMNS` | `12` | Dashboard grid column count |
-| `CELL_HEIGHT` | `80` | Dashboard cell height (px) |
-| `WIDGET_GAP` | `20` | Dashboard widget gap (px) |
-| `DEBOUNCE_DEFAULT_MS` | `500` | Default debounce delay |
-| `HOVER_DELAY_MS` | `200` | Hover intent delay |
-| `TOOLTIP_DELAY_MS` | `300` | Tooltip show delay |
-| `RESIZE_DEBOUNCE_MS` | `100` | Window resize debounce |
-| `ANIMATION_DURATION_MS` | `200` | Default animation duration |
-| `TRANSITION_DURATION_MS` | `150` | Default CSS transition duration |
-| `DRAG_THRESHOLD_PX` | `3` | Min px movement to start drag |
-| `MAX_COLLISION_ITERATIONS` | `50` | Grid collision resolution limit |
-| `MIN_COLUMN_WIDTH_PX` | `15` | Minimum table column width |
-| `OVERFLOW_THRESHOLD` | `100` | Overflow detection threshold (px) |
-| `PAGINATION_VISIBLE_PAGES` | `5` | Visible page buttons in paginator |
-| `PAGINATION_EDGE_PAGES` | `3` | Edge page buttons shown |
-| `TABLE_ROW_HEIGHT` | `48` | Table row height (px) |
-| `TABLE_HEADER_HEIGHT` | `56` | Table header height (px) |
-| `DEFAULT_MAXLENGTH` | `1024` | Default input maxlength |
-| `DEFAULT_TEXTAREA_ROWS` | `3` | Default textarea rows |
-| `MENU_COLLAPSED_WIDTH` | `76` | Sidebar collapsed width (px) |
-| `MENU_EXPANDED_WIDTH` | `246` | Sidebar expanded width (px) |
-| `MENU_ITEM_HEIGHT` | `38` | Menu item height (px) |
-| `Z_INDEX.DROPDOWN` | `100` | Dropdown z-index |
-| `Z_INDEX.TOOLTIP` | `9999` | Tooltip z-index |
-| `Z_INDEX.POPUP` | `10000` | Popup z-index |
-| `Z_INDEX.MODAL` | `10001` | Modal z-index |
-| `Z_INDEX.DRAG` | `1000` | Drag overlay z-index |
-| `Z_INDEX.SIDEBAR` | `50` | Sidebar z-index |
-| `Z_INDEX.HEADER` | `40` | Header z-index |
-| `BREAKPOINTS.XS` | `0` | Extra small breakpoint |
-| `BREAKPOINTS.SM` | `576` | Small breakpoint |
-| `BREAKPOINTS.MD` | `768` | Medium breakpoint |
-| `BREAKPOINTS.LG` | `992` | Large breakpoint |
-| `BREAKPOINTS.XL` | `1200` | Extra large breakpoint |
-| `BREAKPOINTS.XXL` | `1400` | Extra extra large breakpoint |
-
-## Component Defaults (`COMPONENT_DEFAULTS`)
-
-Default prop values per component type. Access via `getComponentDefaults(name)`.
-
-| Component | Property | Default | Description |
-|-----------|----------|---------|-------------|
-| `input` | `maxlength` | `1024` | Max input length |
-| `input` | `debounce` | `0` | Input debounce (ms) |
-| `input` | `type` | `"text"` | Input type attribute |
-| `input` | `autocomplete` | `"off"` | Autocomplete attribute |
-| `select` | `debounce` | `500` | Search debounce (ms) |
-| `select` | `pageSize` | `20` | Items per page |
-| `select` | `searchable` | `true` | Enable search |
-| `select` | `clearable` | `true` | Show clear button |
-| `table` | `pageSize` | `20` | Rows per page |
-| `table` | `pageSizes` | `[10, 20, 50, 100]` | Page size options |
-| `table` | `selectable` | `false` | Row selection |
-| `table` | `multiselect` | `false` | Multi-row selection |
-| `table` | `stickyHeader` | `true` | Sticky header |
-| `pagination` | `pageSize` | `20` | Default page size |
-| `pagination` | `visiblePages` | `5` | Visible page buttons |
-| `textarea` | `rows` | `3` | Default rows |
-| `textarea` | `maxlength` | `4096` | Max textarea length |
-| `editor` | `minHeight` | `200` | Editor min height (px) |
-| `editor` | `maxHeight` | `500` | Editor max height (px) |
-| `tooltip` | `delay` | `300` | Show delay (ms) |
-| `tooltip` | `placement` | `"top"` | Default placement |
-| `modal` | `closeOnEscape` | `true` | Close on Esc key |
-| `modal` | `closeOnOverlayClick` | `true` | Close on backdrop click |
-| `notification` | `duration` | `5000` | Auto-dismiss (ms) |
-| `notification` | `position` | `"top-right"` | Toast position |
-| `dashboard` | `columns` | `12` | Grid columns |
-| `dashboard` | `rowHeight` | `80` | Row height (px) |
-| `dashboard` | `gap` | `20` | Widget gap (px) |
-
-## Locale Constants (`languageToCountryMap`)
-
-A `Record<string, string>` mapping ISO 639-1 language codes to ISO 3166-1 alpha-2 country codes. Contains 57 entries (e.g. `"en" -> "us"`, `"de" -> "de"`, `"ja" -> "jp"`). Used for flag icon resolution and locale fallback.
-
-| Helper | Signature | Description |
-|--------|-----------|-------------|
-| `getComponentDefaults` | `<K extends keyof ComponentDefaults>(componentName: K) => ComponentDefaults[K]` | Type-safe accessor for component default values |
-
-## Usage Examples
-
-### Using UI constants in a composable
-
-```typescript
-import { UI_CONSTANTS } from "@vc-shell/framework";
-
-function useCustomDebounce() {
-  // Use the framework's standard debounce delay
-  const debouncedSearch = useDebounceFn(
-    (query: string) => performSearch(query),
-    UI_CONSTANTS.DEBOUNCE_DEFAULT_MS,
-  );
-  return { debouncedSearch };
-}
-```
-
-### Using component defaults
-
-```typescript
-import { getComponentDefaults } from "@vc-shell/framework";
-
-// Get all default props for a select component
-const selectDefaults = getComponentDefaults("select");
-console.log(selectDefaults.debounce);   // 500
-console.log(selectDefaults.pageSize);   // 20
-console.log(selectDefaults.searchable); // true
-```
-
-### Using z-index layers in custom components
-
-```typescript
-import { UI_CONSTANTS } from "@vc-shell/framework";
-
-// Ensure custom dropdowns sit at the right z-index layer
-const dropdownStyle = computed(() => ({
-  zIndex: UI_CONSTANTS.Z_INDEX.DROPDOWN,
-}));
-```
-
-### Using breakpoints for responsive logic
-
-```typescript
-import { UI_CONSTANTS } from "@vc-shell/framework";
-
-const isMobile = computed(() =>
-  windowWidth.value < UI_CONSTANTS.BREAKPOINTS.MD,
-);
-```
-
-### Using the language-to-country map
-
-```typescript
-import { languageToCountryMap } from "@vc-shell/framework";
-
-function getFlagUrl(locale: string): string {
-  const country = languageToCountryMap[locale] ?? "us";
-  return `https://flagcdn.com/w20/${country}.png`;
-}
-```
-
-## Tip: Override Defaults at the Component Level
-
-Component defaults serve as fallback values. Any prop explicitly set on a component instance takes precedence over `COMPONENT_DEFAULTS`. You do not need to modify the constants to change behavior for a single instance:
-
-```vue
-<!-- Uses default pageSize of 20 -->
-<VcDataTable :items="items" :columns="columns" />
-
-<!-- Overrides to 50 rows per page -->
-<VcDataTable :items="items" :columns="columns" :page-size="50" />
-```
-
-## Related
-
-- `framework/core/constants/ui.ts` -- UI_CONSTANTS definition
-- `framework/core/constants/defaults.ts` -- COMPONENT_DEFAULTS and getComponentDefaults
-- `framework/core/constants/locale.ts` -- languageToCountryMap