@mrciphersmith/keryx 0.2.164 → 0.3.1

package/src/gdskills/bundled/stacks/vue/skills/vue2-to-vue3-migration/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: vue2-to-vue3-migration
+description: "Use when migrating a Vue 2 (Options API) codebase or component to Vue 3 -- covers converting Options API to <script setup> Composition API, replacing the removed filters and $listeners/$children APIs, Vuex-to-Pinia store migration, v-model breaking changes (single default to multiple named bindings), global API changes (createApp vs new Vue), and Vue 2 lifecycle hook renames (beforeDestroy -> beforeUnmount). Not for a fresh Vue 3 component with no legacy code (use vue-implementation)."
+triggers:
+  - "migrate this vue 2 component to vue 3"
+  - "convert this options api component to composition api"
+  - "upgrade this app from vue 2 to vue 3"
+  - "migrate this vuex store to pinia"
+  - "fix this v-model breaking change after upgrading to vue 3"
+  - "replace this vue 2 filter with vue 3"
+metadata:
+  origin: authored
+  category: migrate
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Vue 2 -> Vue 3 migration
+
+Migrate a Vue 2 (Options API) component, store, or app to Vue 3. See
+`rules/coding-style.mdc` and `rules/patterns.mdc` for the Composition API
+conventions the migrated code should land in, not the Options API shape
+it started from.
+
+## Workflow
+
+### Step 1: Inventory what actually changed for this codebase
+
+Do not attempt a blind global rewrite. Identify which of these the
+project actually uses before touching anything:
+
+- Options API components (`data()`, `methods`, `computed`, `watch`,
+  lifecycle hooks as object keys) to convert to `<script setup>`.
+- Vue 2 filters (`{{ value | currency }}`) -- removed entirely in Vue 3;
+  replace with a computed property or a plain method call.
+- `this.$listeners` -- removed; Vue 3 merges listeners into `$attrs`
+  automatically (`v-bind="$attrs"` now forwards both).
+- `this.$children` -- removed; use a template ref or provide/inject
+  instead of reaching into child instances.
+- Global API: `new Vue({ ... })` / `Vue.use(plugin)` -> `createApp(App)`
+  / `app.use(plugin)`; a global mixin/directive registration moves from
+  `Vue.mixin`/`Vue.directive` to `app.mixin`/`app.directive`.
+- Vuex store usage -- migrate to Pinia (the current recommended store)
+  unless the project has an explicit reason to keep Vuex.
+
+### Step 2: Convert one component at a time
+
+- Move `data()` return values to individual `ref()`/`reactive()`
+  declarations at the top of `<script setup>`.
+- Move `computed` properties to `computed(() => ...)` calls.
+- Move `methods` to plain functions in `<script setup>` scope --
+  no `this` binding needed or available.
+- Move `watch` entries to `watch()`/`watchEffect()` calls; a Vue 2
+  `watch: { foo(newVal, oldVal) { ... } }` becomes `watch(() =>
+  someSource, (newVal, oldVal) => { ... })` with an explicit source.
+- Rename lifecycle hooks per the Vue 3 mapping: `beforeDestroy` ->
+  `beforeUnmount`, `destroyed` -> `unmounted`; `created`/`beforeCreate`
+  have no Composition API equivalent -- that code just runs inline in
+  `<script setup>`'s top level, since setup itself runs at that point in
+  the lifecycle.
+- Convert `props`/`$emit` declarations to `defineProps<T>()`/
+  `defineEmits<T>()` per `rules/coding-style.mdc`.
+
+### Step 3: Handle the `v-model` breaking change
+
+- Vue 2's single default `v-model` (`value` prop + `input` event) became
+  Vue 3's `modelValue` prop + `update:modelValue` event by default, and
+  Vue 3 supports multiple named `v-model:propName` bindings on one
+  component. A component using the old `model: { prop: 'value', event:
+  'input' }` option needs its prop/emit renamed (or an explicit
+  `v-model:value` at every call site) -- pick one and apply it
+  consistently, do not leave some call sites on the old contract.
+
+### Step 4: Migrate Vuex state to Pinia (when applicable)
+
+- A Vuex module's `state` becomes a Pinia store's `state` (or individual
+  `ref`s in a setup-style store); `getters` become Pinia `getters` (or
+  `computed`s); `mutations` + `actions` collapse into Pinia `actions`
+  (Pinia has no separate mutations layer -- an action can assign state
+  directly).
+- Replace `this.$store.state.x` / `mapState`/`mapGetters`/`mapActions`
+  usage in components with the equivalent Pinia store instance and,
+  where destructuring is needed, `storeToRefs()`.
+
+### Step 5: Verify
+
+```bash
+npx vue-tsc --noEmit
+npx eslint .
+npm test
+npx vite build
+```
+
+Migrate and verify one component/store at a time rather than converting
+the whole tree before running anything -- a broad simultaneous rewrite
+makes the first failure much harder to localize.
+
+## Rules
+
+- Follow `rules/coding-style.mdc` and `rules/patterns.mdc` for the
+  Composition API shape the migrated code lands in.
+- NEVER leave a component half-migrated with both Options API keys and
+  `<script setup>` code mixed in the same file -- Vue does not support
+  that combination cleanly and it is confusing to read.
+- NEVER silently drop a Vue 2 filter's behavior; convert it to a
+  computed or method call with the same transformation applied, not just
+  remove the filter usage.
+- NEVER migrate a Vuex module's state shape into Pinia without checking
+  every component that reads it through `mapState`/`mapGetters` --
+  those call sites need updating too, not just the store definition.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll rewrite the whole app's components in one pass, then run the build once at the end" | The first failure is now ambiguous across dozens of changed files; migrate and verify one component/store at a time instead |
+| "This filter isn't that important, I'll just drop it during the conversion" | Silently changes what the template renders; convert it to a computed/method with the same transformation, don't remove the behavior |
+| "I'll leave `mapState`/`mapGetters` calling into the old Vuex store and only migrate the store definition to Pinia" | The store and its call sites have to move together; a component still importing Vuex helpers against a Pinia-shaped store fails immediately |
+| "I'll mix Options API `methods` and `<script setup>` in the same file to save time on this one" | Vue does not support combining them cleanly in one SFC; finish the conversion instead of leaving it half done |
+
+## Verification
+
+Do not report a component/store migrated until all of the following hold:
+
+- `vue-tsc --noEmit`, `eslint .`, and the project's test suite all exit
+  0 for the migrated file(s).
+- No file mixes Options API keys with `<script setup>` syntax.
+- Every `v-model` call site for a migrated component uses the new
+  `modelValue`/`update:modelValue` (or explicitly named) contract
+  consistently.
+- Every removed Vue 2 filter has an equivalent computed/method in the
+  migrated component producing the same output.
+- `git status` shows changes confined to the component(s)/store(s)
+  actually being migrated in this pass.

package/src/gdskills/bundled/stacks/vue/skills/vue2-to-vue3-migration/evals.json

@@ -0,0 +1,71 @@
+{
+  "triggers": {
+    "positive": [
+      "this component still has data(), methods, and a beforeDestroy hook from vue 2 -- how do I bring it onto vue 3's composition api",
+      "we're on vue 2 and moving the whole app to vue 3 -- what's going to break across filters, v-model, and our vuex store",
+      "we're replacing vuex in this app with pinia -- how do I carry this store's state, mutations, and actions over",
+      "this vue app's custom input broke v-model after the vue 3 upgrade -- how do I fix the binding",
+      "this vue 2 template formats a price with a global filter -- vue 3 removed filters entirely, so what replaces that syntax",
+      "migrate this app's global Vue.use plugin registration from Vue 2's new Vue() to Vue 3's createApp"
+    ],
+    "negative": [
+      "build a new vue 3 component with script setup",
+      "write a vitest test for this vue 3 component",
+      "review this vue 3 component diff for reactivity bugs",
+      "fix this vue-tsc build error in this component",
+      "upgrade this react app from react 18 to react 19",
+      "migrate this node.js package from commonjs to esm"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "vue2-filter-to-computed",
+      "prompt": "This Vue 2 template uses a filter: `{{ price | currency }}`, defined as a global filter that formats a number as `$X.XX`. I'm converting this component to Vue 3 <script setup>. What do I do about the filter?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that Vue 3 removed filters entirely, and replaces the filter with an equivalent computed property (or a plain function call in the template) that applies the same currency formatting, rather than dropping the formatting behavior.",
+          "pass_criteria": [
+            "States that filters were removed in Vue 3 and the pipe syntax (`{{ price | currency }}`) no longer works",
+            "Shows the concrete replacement as code: a `computed()` (or plain function) that applies the same currency formatting, used in the template in place of the filter (e.g. `{{ formattedPrice }}` backed by `const formattedPrice = computed(() => currency(price.value))`)"
+          ],
+          "fail_criteria": [
+            "Suggests just removing the filter from the template and rendering the raw `price` value, losing the currency formatting"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Vue 3 removed filters entirely, so `{{ price | currency }}` won't work anymore -- the pipe syntax isn't valid template syntax at all in Vue 3. Replace it with a computed property that applies the same formatting the filter used to:\n```ts\nconst formattedPrice = computed(() => currency(price.value))\n```\n```vue\n<template>{{ formattedPrice }}</template>\n```\nIf `currency` was a global filter function used across many components, keep it as a plain importable function (from a `utils/currency.ts` module) and wrap it in a local `computed()` wherever it's used in a template -- that reproduces the same formatting behavior without the removed filter syntax.",
+        "known_wrong": "Filters don't exist in Vue 3, so just drop the `| currency` part and render the raw value: `{{ price }}`. You can always add formatting back later if someone notices.",
+        "vague": "Filters aren't supported anymore in Vue 3, you'll need to replace it with something else that formats the value the same way.",
+        "subtle_wrong": "Since filters are gone, I'd move the formatting into the parent component before the data even reaches this one, so `price` is passed in already formatted as a string. That avoids needing any change inside this component's own template or script."
+      }
+    },
+    {
+      "id": "vmodel-single-to-multiple-bindings",
+      "prompt": "We just upgraded this Vue app's major version. A custom input component that used to work fine with `v-model` back on the Options API release now doesn't update the parent's data at all. The component still defines `props: ['value']` and `emit('input', newVal)`. What's wrong?",
+      "strictness": "high",
+      "expected_behavior": [
+        { "grader": "regex", "value": "modelValue" },
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that Vue 3 changed v-model's default contract from a `value` prop + `input` event to a `modelValue` prop + `update:modelValue` event, and fixes the component to use the new default names (or an explicit named v-model) instead of the old Vue 2 contract.",
+          "pass_criteria": [
+            "Explains that Vue 3's default v-model contract changed from `value`/`input` to `modelValue`/`update:modelValue`, which is why the old prop/emit names no longer sync",
+            "Shows the concrete fix: rename the prop to `modelValue` and the emitted event to `update:modelValue` (e.g. `defineProps<{ modelValue: string }>()` and `emit('update:modelValue', newVal)`)"
+          ],
+          "fail_criteria": [
+            "Attributes the breakage to something unrelated to the v-model prop/event contract change, such as a build cache or a missing import, without addressing the value/input vs modelValue/update:modelValue mismatch"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "This is the Vue 3 v-model breaking change: Vue 2's default `v-model` wired up a `value` prop and an `input` event, but Vue 3 changed the default contract to a `modelValue` prop and an `update:modelValue` event. The component is still declaring the old Vue 2 names (`props: ['value']`, `emit('input', newVal)`), so when the parent's `v-model` now emits/listens for `update:modelValue` under the hood, this component never receives or fires the events the parent actually expects. Fix it by renaming to the Vue 3 default contract:\n```ts\nconst props = defineProps<{ modelValue: string }>()\nconst emit = defineEmits<{ 'update:modelValue': [value: string] }>()\n\nfunction onInput(e: Event) {\n  emit('update:modelValue', (e.target as HTMLInputElement).value)\n}\n```\n```vue\n<template>\n  <input :value=\"modelValue\" @input=\"onInput\" />\n</template>\n```\nAlternatively, keep the old prop/event names but require every call site to use the explicit form `v-model:value=\"...\"` instead of bare `v-model` -- either works, but pick one consistently across the codebase.",
+        "known_wrong": "That's probably just a stale build cache after the dependency upgrade -- try clearing node_modules/.vite and restarting the dev server, that usually clears up weird binding issues right after a major version bump like this.",
+        "vague": "v-model works a bit differently in Vue 3 now, you'll probably need to update the prop and event names in this component.",
+        "subtle_wrong": "I'd keep the component's internal prop named `value` and event named `input` as-is to avoid touching its internals, and instead wrap every usage site with the explicit long form `:value=\"x\" @input=\"x = $event\"` instead of `v-model`, so it keeps working without needing to rename anything inside the component."
+      }
+    }
+  ]
+}