@mrciphersmith/keryx 0.3.0 → 0.3.2

package/src/gdskills/bundled/stacks/vue/skills/vue-code-review/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: vue-code-review
+description: "Use when reviewing changed Vue 3 Single File Component or composable code (.vue) for reactivity bugs -- lost reactivity from destructuring reactive()/props, missing watch cleanup, prop mutation instead of emit, v-for key misuse, v-html injection risk, and Pinia store boundary violations. Read-only, no repository convention-doc lookup and no MobX/React store review. Not for authoring or fixing the component (use vue-implementation or vue-build-fix)."
+triggers:
+  - "review this vue component diff for reactivity bugs"
+  - "check this vue pull request for prop mutation"
+  - "does this vue composable leak a watcher"
+  - "review this pinia store change"
+  - "check for v-html injection in this vue template"
+  - "review this vue component's v-for keys"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Vue code review
+
+Review changed Vue 3 Single File Component or composable code for
+reactivity and structural bugs. Read-only: report findings, do not edit
+the code under review. See `rules/patterns.mdc` for the reactivity/
+composable rules a diff should follow and `rules/security.mdc` for
+`v-html`/routing risks.
+
+## Scope
+
+- Reviews `.vue` files and the composables/Pinia stores a changed
+  component pulls in.
+- Not for the `<script>`-only TypeScript/Node.js parts of a project with
+  no Vue rendering surface (use `nodejs-code-review`), and not for a
+  React or MobX store diff.
+- Does not read the repository's own convention docs -- flags what the
+  diff itself shows against the rules below, not against local style
+  guides.
+
+## Workflow
+
+### Step 1: Read the diff for reactivity boundary breaks
+
+- Any place a `reactive()` object, a Pinia store's state, or (on
+  pre-3.5 Vue) `defineProps()`'s return value is destructured into a
+  loose local variable and later expected to stay live.
+- Any `watch`/`watchEffect` created outside `setup`/`<script setup>`
+  scope (inside a manually managed subscription, an event listener
+  registered once at module scope) with no stored stop handle to clean
+  it up.
+- A `watch` whose source is broader than what actually changed (a whole
+  reactive object with `{ deep: true }` when only one field matters).
+
+### Step 2: Check prop/emit and component boundaries
+
+- A prop mutated in place inside the component that receives it
+  (`props.foo = ...`, `props.items.push(...)`) instead of emitting an
+  event for the parent to act on.
+- `defineProps`/`defineEmits` using the untyped runtime-object/string-
+  array form where the surrounding file is otherwise TypeScript, losing
+  compile-time checking on the component's own public contract.
+- A `v-for` list with no `:key`, or `:key` bound to the array index on a
+  list whose order or membership can change (reordering, filtering,
+  insertion in the middle) -- index keys silently misattribute component
+  state across re-orders.
+
+### Step 3: Check security-relevant sinks
+
+- `v-html` bound to anything that can carry user-controlled content with
+  no sanitization step immediately before the binding.
+- A dynamic `:href`/`:src` bound to user-controlled input with no
+  scheme allowlist.
+- A route param (`route.params.*`) used directly in a redirect target,
+  query, or `v-html` value with no validation.
+
+### Step 4: Check Pinia store boundaries
+
+- An action in one store mutating another store's state directly
+  instead of calling that store's own exported action.
+- Store state read or mutated from outside any component/setup
+  reactivity scope (e.g. a plain module-level side effect) in a way that
+  will not trigger the expected reactive updates.
+
+### Step 5: Report findings
+
+For each finding: file:line, what the diff does, why it is a bug (which
+rule it violates), and the concrete fix -- as a suggestion, not an edit
+you apply yourself.
+
+## Rules
+
+- Follow `rules/patterns.mdc` for reactivity/composable/store boundary
+  rules and `rules/security.mdc` for `v-html`/routing/store-persistence
+  risks.
+- Read-only: report findings and suggested fixes; do not edit the
+  reviewed files.
+- Do not flag a destructured `defineProps()` on a confirmed Vue 3.5+
+  project as broken reactivity -- it is reactive there by design; check
+  the `vue` dependency version before flagging this pattern.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "The `v-for` has a `:key`, so the missing-key rule doesn't apply, even though it's `:key=\"index\"`" | An index key on a reorderable/filterable list still causes Vue to misattribute component state across items after a reorder; the rule is about a *stable* key, not merely the presence of one |
+| "This destructured `const { count } = store` looks fine, JS objects are always live" | A plain destructure of Pinia/reactive state captures a snapshot value, not a live binding -- flag it unless `storeToRefs`/`toRefs` wraps it first |
+| "The prop mutation is inside a `watch`, so it's not really 'the component' mutating it" | A `watch` handler runs as part of the component's own reactive scope; mutating `props.x` there is the same violation as doing it in a click handler |
+| "`v-html` is bound to a value from our own API, so it's safe" | Content originating from an API is only as trustworthy as whatever produced it upstream (e.g. user-submitted text stored and echoed back); flag it unless a sanitize step sits immediately before the binding |
+
+## Verification
+
+Before finishing the review, confirm:
+
+- Every reactivity-boundary finding names the exact line and the
+  specific pattern violated (not a vague "check reactivity here").
+- Every `v-for`/`v-html`/prop-mutation finding includes the concrete
+  fix (the corrected `:key` expression, the sanitize call, or the emit
+  to add), not just "this looks wrong".
+- No suggested fix was applied to the files under review -- the skill
+  only reports.
+- The report distinguishes a genuine Vue 3.5+ destructured-props usage
+  (fine) from a pre-3.5 or reactive()/store destructure (a real bug).

package/src/gdskills/bundled/stacks/vue/skills/vue-code-review/evals.json

@@ -0,0 +1,71 @@
+{
+  "triggers": {
+    "positive": [
+      "can you scan this vue component's diff before it merges for anything that could break reactivity",
+      "check this pinia store change for state mutation across stores",
+      "does this vue composable's watch() call ever get cleaned up before the component unmounts, or is it leaking",
+      "is there an XSS risk from how this vue template renders raw HTML into the DOM",
+      "in this pull request's diff, take a look at whether this vue component's list rendering picks safe keys",
+      "review this vue diff for prop mutation instead of emit"
+    ],
+    "negative": [
+      "review this react component diff for hook bugs",
+      "build a new vue component with a pinia store",
+      "fix this vue-tsc build error in this component",
+      "write a vitest test for this vue component",
+      "review this node.js service diff for floating promises",
+      "review this mobx store diff for action boundary violations"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "index-key-on-reorderable-list",
+      "prompt": "Review this part of a Vue component diff:\n```vue\n<li v-for=\"(task, index) in tasks\" :key=\"index\">{{ task.title }}</li>\n```\nThe list supports drag-to-reorder and delete-in-the-middle. Any issue?",
+      "strictness": "high",
+      "expected_behavior": [
+        { "grader": "regex", "value": ":key" },
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags that keying by array index on a list that can reorder or delete from the middle causes Vue to misattribute per-item state across re-renders, and recommends keying by a stable identifier from the task itself instead.",
+          "pass_criteria": [
+            "Identifies that `:key=\"index\"` is unsafe specifically because the list reorders/deletes in the middle, not merely that a key is present",
+            "Names the concrete fix: key by a stable identifier from the item, e.g. `:key=\"task.id\"`"
+          ],
+          "fail_criteria": [
+            "Concludes the key is fine because a `:key` binding exists at all, without addressing that an index key breaks under reorder/delete-in-the-middle"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Flag this: `:key=\"index\"` is a problem here specifically because the list supports drag-to-reorder and delete-in-the-middle. Vue uses the key to decide which existing DOM node/component instance to reuse across a re-render; when the key is the array index, reordering or removing a middle item shifts every subsequent item's index, so Vue reuses the wrong node for the wrong task -- component-local state (an open edit field, a checked checkbox, an input's value) can end up attached to the wrong row. Fix: key by a stable id that travels with the task, not its position:\n```vue\n<li v-for=\"task in tasks\" :key=\"task.id\">{{ task.title }}</li>\n```\n(dropped `index` from the loop var since it's unused now). If `task` genuinely has no stable id, that's the actual bug to fix upstream -- generate one when the task is created, don't fall back to index.",
+        "known_wrong": "This is fine -- there's already a `:key` bound on the `<li>`, which is exactly what Vue's v-for warning asks for. The list has a key, so this satisfies the requirement.",
+        "vague": "Using the index as a key can cause issues with dynamic lists, might be worth using something else.",
+        "subtle_wrong": "Worth a second look, but since `task.title` is already unique across the list in practice, I'd key on that instead of the index: `:key=\"task.title\"`. That avoids the index issue and doesn't require adding an id field to the data."
+      }
+    },
+    {
+      "id": "action-mutates-other-store-state-directly",
+      "prompt": "Review this Pinia action:\n```ts\n// in useCartStore\nfunction checkout() {\n  const userStore = useUserStore()\n  userStore.recentOrders.push(buildOrder(items.value))\n  items.value = []\n}\n```\nAny concerns?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review flags that the cart store's action reaches into another store (userStore) and mutates its state array directly instead of calling a dedicated action on that store, and recommends adding/calling a userStore action (e.g. addRecentOrder) instead of pushing into its state from outside.",
+          "pass_criteria": [
+            "Identifies that `userStore.recentOrders.push(...)` mutates another store's state directly from outside that store, bypassing its own action layer",
+            "Recommends the concrete fix: call (or add) a userStore action such as `userStore.addRecentOrder(order)` instead of pushing into its state array from the cart store"
+          ],
+          "fail_criteria": [
+            "Treats the direct cross-store state mutation as acceptable because both stores are part of the same app/Pinia instance"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Flag `userStore.recentOrders.push(buildOrder(items.value))`: this mutates `userStore`'s state array directly from inside `useCartStore`'s `checkout` action, bypassing `userStore`'s own action layer entirely. Now there are two places `recentOrders` can change -- through `userStore`'s own actions, and through any other store that happens to reach in like this -- which makes it impossible to reason about where a change to that state actually came from, and any validation/side effect `userStore` might want on adding an order gets skipped here. Fix: give `userStore` an action for this and call it instead:\n```ts\n// in useUserStore\nfunction addRecentOrder(order: Order) {\n  recentOrders.push(order)\n}\n\n// in useCartStore.checkout\nconst userStore = useUserStore()\nuserStore.addRecentOrder(buildOrder(items.value))\nitems.value = []\n```\nNow `userStore` owns every mutation to its own state through one discoverable entry point.",
+        "known_wrong": "No concern -- both stores are part of the same Pinia instance in this app, so one store reaching into another's reactive state and pushing to it is just normal cross-store communication; Pinia doesn't enforce store boundaries anyway.",
+        "vague": "Might be better for the cart store to not touch the user store's data directly, worth reconsidering that.",
+        "subtle_wrong": "I'd tighten this slightly by having the cart store read `userStore.recentOrders` through a computed instead of accessing it live, but the push itself from `checkout` is a reasonable enough way to record the order without adding a whole new action just for this."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/vue/skills/vue-implementation/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: vue-implementation
+description: "Use when building or changing a Vue 3 Single File Component, composable, or Pinia store -- covers <script setup> with type-based defineProps/defineEmits, choosing ref vs reactive, computed vs watch/watchEffect, composable extraction, and Pinia store/action design. Not for Options API legacy components (use vue2-to-vue3-migration) or Node.js service/CLI code with no .vue file (use nodejs-implementation)."
+triggers:
+  - "build a vue component"
+  - "add a composable to this vue app"
+  - "wire up a pinia store"
+  - "add props and emits to this vue component"
+  - "should this be ref or reactive"
+  - "implement this vue form with v-model"
+  - "extract this logic into a use composable"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Vue implementation (Composition API)
+
+Build or change a Vue 3 Single File Component, composable, or Pinia store
+using the Composition API. See `rules/coding-style.mdc` for `<script
+setup>` typing conventions, `rules/patterns.mdc` for reactivity and
+composable design, and `rules/security.mdc` for `v-html`/routing risks a
+new component must avoid.
+
+## Workflow
+
+### Step 1: Discover the project's own conventions
+
+Before writing anything, check:
+
+- Does the project use `<script setup lang="ts">` everywhere, or does it
+  still have Options API components? Match the file's neighbors in the
+  same directory, not a mix.
+- Is state management Pinia, Vuex, or ad hoc `provide`/`inject` +
+  composables? Check `package.json` and an existing store file.
+- Is the project on Vue 3.5+ (destructured `defineProps()` stays
+  reactive) or an earlier 3.x (destructuring breaks reactivity)? Check
+  `package.json`'s `vue` dependency version before choosing which prop
+  access style to write.
+- Is `eslint-plugin-vue` configured, and with which rule preset
+  (`recommended`, `strongly-recommended`)? Its rule set decides template
+  formatting details (self-closing tags, attribute order) worth matching.
+
+### Step 2: Design the component/composable boundary
+
+- A piece of state or behavior used by more than one component becomes a
+  composable (`useX()`), not copy-pasted `ref`/`watch` blocks.
+- State shared across unrelated branches of the component tree (not just
+  parent-to-child) is a Pinia store, not `provide`/`inject` bolted onto an
+  unrelated ancestor.
+- A component that only renders based on props and emits events, with no
+  store/composable dependency of its own, stays "dumb" -- push data
+  fetching and derived state up into a parent or a composable it calls.
+
+### Step 3: Declare props, emits, and reactive state
+
+- Type-only `defineProps<{ ... }>()` / `defineEmits<{ ... }>()`, not the
+  runtime-object form -- see `rules/coding-style.mdc`.
+- Choose `ref()` for a value reassigned wholesale, `reactive()` for a
+  fixed-shape object mutated in place -- see `rules/patterns.mdc`. Never
+  destructure a `reactive()` object or a pre-3.5 props object into loose
+  variables; that breaks the reactive link.
+- Choose `computed()` for a pure re-derivation, `watch`/`watchEffect`
+  only for an actual side effect (fetch, DOM measurement, external sync).
+
+### Step 4: Wire the store (when the feature needs one)
+
+- Define Pinia state, getters, and actions in `defineStore()`; keep
+  mutation inside the store's own actions -- a component calls an action,
+  it does not reach in and mutate `store.someField` directly from outside.
+- One store owns one another store's state through that store's own
+  actions, not by importing and mutating it directly.
+
+### Step 5: Verify
+
+Run the project's own scripts (they may wrap these with extra flags):
+
+```bash
+npx vue-tsc --noEmit
+npx eslint .
+npm test
+```
+
+Confirm the new component renders without a runtime prop-mutation warning
+and that events fire with the expected payload (check in a quick manual
+mount or the existing dev server) before calling the feature done.
+
+## Rules
+
+- Follow `rules/coding-style.mdc` for `<script setup>`/prop/emit typing.
+- Follow `rules/patterns.mdc` for `ref`/`reactive` choice, composable
+  extraction, and `provide`/`inject` vs. Pinia store decisions.
+- Follow `rules/security.mdc` before adding any `v-html` binding or a
+  dynamic `:href`/`:src` from user-controlled input.
+- NEVER mutate a prop in place inside the child; emit an event
+  (`emit('update:modelValue', v)`) and let the parent own the state.
+- NEVER destructure a `reactive()` object into loose variables expecting
+  them to stay reactive.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just mutate `props.items.push(...)` directly, it's simpler than emitting" | Vue warns at runtime; the parent's data silently drifts from what it thinks it owns, and the mutation is invisible to anyone reading the parent |
+| "I'll destructure `const { count } = state` from this `reactive()` object for convenience" | `count` is now a frozen copy at destructure time; later mutations to `state.count` never update it, producing a component that silently stops re-rendering |
+| "I'll skip the composable and just copy this fetch+loading+error block into the second component" | Two independent copies of the same stateful logic drift apart the next time either one is bugfixed |
+| "`watch(props, ...)` with `deep: true` is easier than picking the one field I actually need" | A whole-object deep watch fires on every unrelated field change and is expensive on any non-trivial object |
+
+## Verification
+
+Do not report the feature done until all of the following hold:
+
+- `vue-tsc --noEmit` (or the project's own type-check script) exits 0.
+- `eslint .` exits 0 with no new `eslint-disable` added.
+- No prop is mutated in place; every parent-visible change goes through
+  an emitted event or a store action.
+- Every `defineProps`/`defineEmits` is the type-only form, not the
+  runtime-object form, unless the surrounding file is still Options API.
+- `git status` shows changes confined to the files the feature required.

package/src/gdskills/bundled/stacks/vue/skills/vue-implementation/evals.json

@@ -0,0 +1,72 @@
+{
+  "triggers": {
+    "positive": [
+      "I need a new vue single file component that takes some typed props from its parent and emits an event back up when something happens",
+      "add a pinia store action to update the cart",
+      "for this piece of local state in a vue component, is ref() or reactive() the better call here",
+      "two of my vue components need the same piece of reactive logic -- how do I pull it out into a composable so they can both use it",
+      "I want typing into this vue form's input to update the parent component's data automatically through v-model -- how do I wire that up",
+      "implement this vue 3 script setup component"
+    ],
+    "negative": [
+      "write a react component with props and state",
+      "fix this vue-tsc type error blocking the build",
+      "review this vue component diff for reactivity bugs",
+      "write a vitest test for this vue component",
+      "migrate this vue 2 options api component to vue 3",
+      "implement this node.js CLI command"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "prop-mutation-vs-emit",
+      "prompt": "A Vue child component has an 'items' prop for a todo list. A button handler currently does `props.items.push(newItem)` to add an item. What should this do instead so the parent's data stays in sync?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that props are one-way and must not be mutated in the child (e.g. via `props.items.push(...)`), and instead emits an event so the parent owns the state change -- naming the defineEmits declaration and the emit() call with the new item as payload.",
+          "pass_criteria": [
+            "Explicitly says not to mutate the prop directly (e.g. `props.items.push(...)`) since props flow one-way from parent to child",
+            "Shows the fix as code: a defineEmits<{...}>() declaration for an event (e.g. 'add-item' or 'update:items') and the emit(...) call passing the new item, not just a description of emitting something"
+          ],
+          "fail_criteria": [
+            "Recommends keeping `props.items.push(newItem)` (or an equivalent direct mutation of the prop) as the actual fix. Naming `props.items.push` only to explain why it is wrong does not count as this failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Don't call `props.items.push(newItem)` -- props flow one-way from parent to child, and mutating the array in place changes the parent's underlying data through a reference the child was never supposed to write to, which Vue also warns about at runtime. Instead, declare a typed emit and let the parent decide how to update its own state:\n\n```ts\nconst emit = defineEmits<{\n  'add-item': [item: TodoItem]\n}>()\n\nfunction onAdd(newItem: TodoItem) {\n  emit('add-item', newItem)\n}\n```\n\nIn the parent, listen for `@add-item` and push into its own `items` ref/reactive array there. Now the child never touches the prop directly, and the parent has one clear place where the list actually changes.",
+        "known_wrong": "Easiest fix: just keep doing `props.items.push(newItem)` inside the click handler. Since `items` is an array, JavaScript objects are passed by reference, so pushing into it from the child updates the same array the parent has -- it already works, no need to add an emit for something this simple.",
+        "vague": "Don't mutate the prop directly, emit an event instead so the parent controls the data update.",
+        "subtle_wrong": "Instead of mutating the prop, I'd clone it into local state so the child owns its own copy: `const localItems = ref([...props.items]); function onAdd(newItem) { localItems.value.push(newItem) }`, then render from `localItems` in the template. This avoids touching the prop directly and keeps the child's list working, and the parent can re-sync later if it needs to."
+      },
+      "anti_patterns": ["props.items.push"]
+    },
+    {
+      "id": "reactive-destructure-breaks-tracking",
+      "prompt": "I destructured a Pinia store's reactive state like `const { count } = store` inside a component so I don't have to write `store.count` everywhere. The template stopped updating when count changes elsewhere. What's wrong and how do I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies that destructuring a Pinia store's reactive state directly captures a frozen snapshot value at that moment, breaking the reactive connection, and fixes it with storeToRefs(store) (or toRefs()/toRef() for a plain reactive object) before destructuring.",
+          "pass_criteria": [
+            "Identifies that destructuring the reactive state directly copies a snapshot value, breaking the reactive connection to the store",
+            "Names the concrete fix as code: `storeToRefs(store)` for a Pinia store (or `toRefs()`/`toRef()` for a plain reactive object) used before destructuring, e.g. `const { count } = storeToRefs(store)`"
+          ],
+          "fail_criteria": [
+            "Concludes that plain destructuring of the store's state should already work and looks for the bug elsewhere (e.g. a re-fetch or a missing watcher) instead of identifying the destructuring itself as the cause",
+            "Proposes a fix that does not use storeToRefs/toRefs/toRef at all, such as only wrapping the read in a manual watch-and-copy workaround"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The problem is the destructuring itself: `const { count } = store` reads `store.count`'s current value once and assigns it to a plain local variable -- it's a snapshot, not a live binding, so later changes to `store.count` never touch your local `count`. Pinia's reactive state only stays reactive through the store object itself (or through a ref/computed derived from it), not through a plain destructured value.\n\nFix it with `storeToRefs`, which converts the store's reactive properties into individual refs before you destructure them:\n\n```ts\nimport { storeToRefs } from 'pinia'\n\nconst store = useCounterStore()\nconst { count } = storeToRefs(store)\n```\n\nNow `count` is a `Ref<number>` that stays linked to `store.count`, so the template updates when it changes elsewhere. (Actions like `store.increment` stay destructured directly from `store`, not through `storeToRefs` -- functions don't need reactive wrapping.)",
+        "known_wrong": "That should already work -- JavaScript destructuring just reads the current property values, and since Pinia stores are reactive objects, `count` should update along with `store.count` automatically. If the template isn't updating, it's probably not related to the destructuring at all; check whether the action that changes `count` elsewhere is actually being called, or whether the component is even re-rendering.",
+        "vague": "The destructuring probably broke reactivity somewhere. Try to keep it wired to the store more directly instead of pulling it out as a plain variable.",
+        "subtle_wrong": "Rather than changing how you read `count`, keep a local ref synced manually with a watcher: `const count = ref(store.count); watch(() => store.count, (v) => { count.value = v })`. That way `count` stays a reactive ref in the component and updates whenever the store's value changes, without needing to change the original destructuring line."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/vue/skills/vue-testing/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: vue-testing
+description: "Use when a Vue 3 component or composable's test suite needs writing, extending, or fixing with Vue Test Utils and Vitest -- covers mount vs. shallowMount, querying by test id/role, awaiting trigger()/nextTick for async DOM updates, asserting wrapper.emitted() payloads, and Pinia test-store isolation with createTestingPinia. Not for plain Node.js/TypeScript unit tests with no .vue mount (use nodejs-testing) or React Testing Library tests (use react-testing)."
+triggers:
+  - "write a vitest test for this vue component"
+  - "test this vue composable"
+  - "fix this failing vue test utils test"
+  - "mock the api call in this vue component test"
+  - "assert the emitted event payload in this test"
+  - "test this pinia store"
+metadata:
+  origin: authored
+  category: test
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Vue testing (Vue Test Utils / Vitest)
+
+Write, extend, or fix a Vue 3 component or composable test using Vue Test
+Utils and Vitest. See `rules/testing.mdc` for the layout, querying, and
+mocking conventions a correct test follows.
+
+## Workflow
+
+### Step 1: Discover the project's own test setup
+
+- Read an existing `*.spec.ts`/`*.test.ts` next to a `.vue` file in the
+  same directory (or the project's shared `__tests__` folder) to match
+  its layout, its DOM environment (`happy-dom` vs `jsdom`), and whether it
+  uses raw Vue Test Utils assertions or `@testing-library/vue` on top.
+- Check whether the project uses Pinia and, if so, whether
+  `@pinia/testing`'s `createTestingPinia()` is already a dependency --
+  use it if present rather than hand-rolling store setup.
+- Check the project's network-mocking convention (MSW, a mocked
+  service/composable module, or `vi.mock()` on the fetch wrapper) and
+  mock at that same boundary.
+
+### Step 2: Choose mount depth and render the component
+
+- `mount()` when the test cares about the full render tree, including
+  child components' own output.
+- `shallowMount()` only when child components are irrelevant noise for
+  this test and stubbing them meaningfully clarifies the assertions.
+- Pass every prop the assertions actually depend on explicitly through
+  `mount(Component, { props: { ... } })` -- do not lean on a default
+  silently covering a value the test cares about.
+
+### Step 3: Interact and wait for reactivity to settle
+
+- Trigger interaction with `await wrapper.find(selector).trigger('click')`
+  (or `@testing-library/vue`'s `fireEvent`) -- always `await` it, since
+  Vue's DOM updates are asynchronous (`flush: 'pre'` by default).
+- After an async composable/store call the interaction kicks off, `await
+  flushPromises()` (or the project's existing helper) plus `await
+  nextTick()` before asserting on DOM that depends on it -- never an
+  arbitrary `setTimeout`.
+
+### Step 4: Assert behavior, not internals
+
+- Assert on rendered text/attributes and `wrapper.emitted('eventName')`
+  payloads, not on `wrapper.vm`'s internal reactive state -- `vm` access
+  couples the test to implementation details that can change without
+  changing behavior.
+- When asserting an emitted event, check the payload array
+  (`wrapper.emitted('update')![0]`), not just that the event key exists --
+  a wrong payload with the right event name is still a real bug.
+
+### Step 5: Verify
+
+```bash
+npx vitest run <path-to-spec>
+npx vitest run
+```
+
+Run the full suite once the target file passes, to confirm the change did
+not affect an unrelated test through shared Pinia/module state.
+
+## Rules
+
+- Follow `rules/testing.mdc` for layout, querying, Pinia isolation, and
+  mocking boundaries.
+- ALWAYS `await` a `trigger()`/`fireEvent` call and any subsequent DOM
+  assertion that depends on it.
+- ALWAYS give a component under test that reads a Pinia store a fresh
+  test store instance (`createTestingPinia()` or a fresh `createPinia()` +
+  `setActivePinia()`) -- never reuse one Pinia instance across tests.
+- NEVER delete or loosen a failing assertion to make the suite green;
+  fix the component if behavior regressed, or fix the assertion if it
+  was asserting stale behavior, and say which.
+- NEVER assert through `wrapper.vm.someInternalRef` when the same fact is
+  observable through rendered output or an emitted event.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll skip the `await` on `trigger()`, the click is synchronous anyway" | Vue batches DOM updates asynchronously by default; the assertion right after an un-awaited trigger reads stale DOM and the test can pass for the wrong reason |
+| "I'll just check `wrapper.emitted('update')` exists, not the payload" | A component that emits the right event with the wrong value still passes this assertion, hiding a real bug |
+| "This test keeps failing on Pinia state from the previous test, I'll just reset it inside this one test" | The root cause is a shared store instance across tests; reset the store per-test globally (`beforeEach`) or use `createTestingPinia()`, not a one-off patch in the test that happened to notice |
+| "I'll assert `wrapper.vm.count` directly, it's faster than finding the rendered text" | Couples the test to an internal variable name; a refactor that keeps behavior identical but renames the ref breaks the test for no real reason |
+
+## Verification
+
+Do not report the test done until all of the following hold:
+
+- `npx vitest run` for the target file (and the full suite) exits 0.
+- Every `trigger()`/`fireEvent` call is `await`ed, and no arbitrary
+  `setTimeout` was used to wait for a DOM update.
+- Every emitted-event assertion checks the payload, not just presence.
+- A component reading a Pinia store gets its own fresh store instance in
+  this test, not one shared with another test file.
+- `git status` shows changes confined to the test file(s) the fix or new
+  coverage required.

package/src/gdskills/bundled/stacks/vue/skills/vue-testing/evals.json

@@ -0,0 +1,72 @@
+{
+  "triggers": {
+    "positive": [
+      "write a vue test utils spec that clicks this component's button and asserts the result",
+      "I want a vitest spec that verifies the values this vue composable returns are correct",
+      "debug why this vue test utils test fails intermittently",
+      "assert what payload this vue component's update event actually carries in its vue test utils spec",
+      "this vue component's vue test utils wrapper still triggers a real fetch call during its vitest spec -- how do I mock that out",
+      "how do I set up a test for this component that depends on a pinia store without hitting the real store"
+    ],
+    "negative": [
+      "add React Testing Library coverage for this React component's onClick handler",
+      "write vitest tests for this node.js service function",
+      "review this vue component diff for bugs",
+      "implement this vue composable for fetching orders",
+      "fix this vue-tsc build error",
+      "migrate this vuex store to pinia"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "await-trigger-before-assert",
+      "prompt": "This Vue Test Utils test clicks a button and immediately asserts the counter text updated, but it fails intermittently:\n```ts\nwrapper.find('button').trigger('click')\nexpect(wrapper.find('span').text()).toBe('1')\n```\nWhat's wrong and how do I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        { "grader": "regex", "value": "await" },
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that trigger() is asynchronous because Vue batches DOM updates, so the assertion right after an un-awaited trigger() can read stale DOM, and fixes it by awaiting the trigger() call (and, where relevant, nextTick) before asserting.",
+          "pass_criteria": [
+            "Explains that Vue's reactive DOM updates are asynchronous/batched, so trigger() must be awaited before the DOM reflects the click",
+            "Shows the fix as code: `await wrapper.find('button').trigger('click')` before the assertion"
+          ],
+          "fail_criteria": [
+            "Attributes the flakiness to something other than the missing await (e.g. a slow CI machine, a random test order) and proposes retries or a fixed setTimeout delay instead of awaiting trigger()"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The test is flaky because `trigger('click')` is asynchronous -- Vue Test Utils' `trigger()` returns a promise that resolves after Vue has flushed the resulting reactive DOM update (by default on the 'pre' flush timing). Calling it without `await` fires the click, but the assertion right after can run before the DOM has actually updated, so it sometimes reads the old text and sometimes the new one depending on timing. The fix is to await it:\n\n```ts\nawait wrapper.find('button').trigger('click')\nexpect(wrapper.find('span').text()).toBe('1')\n```\n\nIf the counter update itself depends on an async composable or store call beyond the synchronous reactive update, also await `flushPromises()` before the assertion.",
+        "known_wrong": "Test flakiness like this is usually just CI being slow under load -- I'd add a short `await new Promise(r => setTimeout(r, 100))` after the trigger to give it time to settle, or mark the test as retry: 2 in the Vitest config so a transient failure doesn't block the run.",
+        "vague": "trigger() is async so you need to wait for it before checking the result.",
+        "subtle_wrong": "Since `trigger()` needs time to propagate, I'd wrap the assertion in `await vi.waitFor(() => expect(wrapper.find('span').text()).toBe('1'))` so it polls until the DOM catches up, without changing the `trigger('click')` call itself."
+      },
+      "anti_patterns": ["setTimeout"]
+    },
+    {
+      "id": "assert-emitted-payload-not-presence",
+      "prompt": "My component test checks that clicking save fires the 'submit' event: `expect(wrapper.emitted('submit')).toBeTruthy()`. The test passes, but a teammate says it wouldn't catch a bug where the wrong data is submitted. What should the assertion actually check?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that checking only that the event was emitted proves the event fired but not that it carried the right data, and fixes it by asserting the emitted event's actual payload array.",
+          "pass_criteria": [
+            "States that `toBeTruthy()` on `wrapper.emitted('submit')` only proves the event fired, not that its payload was correct",
+            "Shows the concrete fix: asserting the payload, e.g. `expect(wrapper.emitted('submit')![0]).toEqual([expectedData])`"
+          ],
+          "fail_criteria": [
+            "Recommends leaving the assertion as just `toBeTruthy()`/presence-only and relying on a different, unrelated test to cover the payload instead of fixing this assertion"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "`expect(wrapper.emitted('submit')).toBeTruthy()` only proves the event fired at least once -- it says nothing about what was passed with it. A component that emits `submit` with completely wrong or stale data still passes that check. `wrapper.emitted('eventName')` returns an array of argument arrays, one per emit call, so assert against the actual payload:\n\n```ts\nawait wrapper.find('form').trigger('submit')\nexpect(wrapper.emitted('submit')).toBeTruthy()\nexpect(wrapper.emitted('submit')![0]).toEqual([{ name: 'Ada', email: 'ada@example.com' }])\n```\nNow a bug that emits the right event with the wrong data actually fails the test.",
+        "known_wrong": "toBeTruthy() is fine here -- the point of this test is just to confirm the submit flow wires up the event at all. Checking the exact payload is really the job of a separate unit test on the form's own validation logic, not this component test.",
+        "vague": "You should check what data was actually emitted, not just that the event happened.",
+        "subtle_wrong": "I'd strengthen it by checking the emitted count instead: `expect(wrapper.emitted('submit')!.length).toBe(1)`, so at least we know it only fired once and isn't double-submitting."
+      }
+    }
+  ]
+}