@gallopsystems/agent-skills 1.8.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/copier-template/skills/copier-template/SKILL.md

@@ -62,6 +62,20 @@ git ls-remote --tags --refs --sort=-v:refname <template-url> 'v*' | head -1
 
 If newer, it pushes a **static branch name** (e.g. `chore/template-update`) with an `--allow-empty` commit and opens a PR whose body contains the version delta, release-notes/compare links, and step-by-step instructions an agent can execute. Hard-won details to keep if reimplementing: an explicit `permissions: contents: write, pull-requests: write` block (default token can't open PRs), a static branch name (dated branches caused duplicate PRs), and comparing **tag versions, not commit SHAs**.
 
+## Branch Protection in Descendants
+
+A template **cannot** enable branch protection for the repos it generates — GitHub reads required status checks from repo config, never from committed workflow files. So every descendant starts with nothing gating merges until someone sets it once (after the first CI run, so the check is known). This template's CI exposes a **`ci-success`** summary job to be exactly that gate — require it on `main`:
+
+```bash
+echo '{"required_status_checks":{"strict":false,"contexts":["ci-success"]},"enforce_admins":false,"required_pull_request_reviews":null,"restrictions":null}' \
+  | gh api -X PUT repos/<owner>/<repo>/branches/main/protection --input -
+```
+
+- **Require the single `ci-success` context, not individual job names.** CI shards the test suite, so the per-leg check names embed the matrix size (`test (shard 1/4)`) and change as the project grows — protection pinned to them blocks every PR the moment the count shifts. `ci-success` is a summary job (`needs:` all gating jobs, `if: always()`, fails unless every `needs.*.result` is `success`); `needs.test.result` rolls the whole matrix into one value, so it stays correct at any shard count. If you add a template whose CI lacks such a job, create one rather than requiring the matrix legs directly.
+- **`coverage` is deliberately excluded** from `ci-success` so the report never blocks a merge — don't add it to the required contexts.
+- The PUT body must include `required_status_checks`, `enforce_admins`, `required_pull_request_reviews`, and `restrictions` (any may be `null`) or the call 422s. Needs admin on the repo.
+- A Conventional-Commits **PR-title check is only worth requiring on repos something actually reads the title** — i.e. a published package with release-please/changelog automation. A private app (no release tooling, `"private": true`, no version) gains nothing from it; don't gate on it there.
+
 ## Further Reading
 
 - **Template anatomy & testing changes**: [template-authoring.md](template-authoring.md)

package/plugins/nitro-testing/skills/nitro-testing/frontend-testing.md

@@ -482,6 +482,77 @@ for (const tz of timezones) {
 }
 ```
 
+### 7. Reading or driving a stubbed child needs an explicit stub
+
+`Stub: true` (auto-stub) renders the child but **does not expose its props** to
+`findComponent(Stub).props("x")`. To read or drive a child's `modelValue`, give it
+an explicit stub that declares the prop:
+
+```typescript
+const SelectStub = {
+  name: "Select",
+  props: ["modelValue"],
+  emits: ["update:modelValue"],
+  template: "<div />",
+};
+// findComponent(SelectStub).props("modelValue")  — now readable
+// findComponent(SelectStub).vm.$emit("update:modelValue", x)  — drives the v-model
+```
+
+For a deep tree (a dialog full of fields), `shallow: true` auto-stubs everything;
+add explicit stubs only for the parts you assert on — plus a dialog stub that
+renders its slot, since UI-lib dialogs gate content behind a `visible` prop:
+
+```typescript
+const DialogStub = { props: ["visible"], template: "<div v-if='visible'><slot /><slot name='footer' /></div>" };
+```
+
+### 8. Driving and asserting route/query state
+
+A global route middleware that redirects unauthenticated navigations (to a public
+`/login`) means `mountSuspended(Comp, { route: "/private?foo=1" })` lands on the
+public path and **drops the query** — so a `useRouteQuery`-bound ref reads empty.
+Two ways around it:
+
+- **Carry the params on the public route:** `route: "/login?foo=1"`. `useRouteQuery`
+  binds to `route.query` regardless of the path.
+- **Assert URL *writes* by spying on `router.replace`**, not by reading
+  `currentRoute` (the redirect strips what you'd read back):
+
+```typescript
+const replace = vi.spyOn((wrapper.vm as any).$router, "replace");
+input.vm.$emit("update:modelValue", "foo");
+await flushPromises();
+expect(replace.mock.calls.some((c) => (c[0] as any)?.query?.q === "foo")).toBe(true);
+```
+
+### 9. Testing a composable that needs a component scope
+
+For a composable using lifecycle hooks or `provide`/`inject`, mount a throwaway
+component whose `setup()` calls it and capture the return:
+
+```typescript
+let api: ReturnType<typeof useThing>;
+const Comp = defineComponent({ setup() { api = useThing(); return () => h("div"); } });
+await mountSuspended(Comp);
+```
+
+Control a VueUse dependency with `vi.mock("@vueuse/core", …)` to return refs you
+drive. And make sure the vitest `include` glob covers `app/composables/**` — a
+composables dir is easy to leave out of the frontend config.
+
+### 10. Reset the shared `useFetch` cache between mounts
+
+`useFetch`/`useAsyncData` cache by key, and the cache is **shared across
+`mountSuspended` calls in a file**. When several tests mount the same component
+(fixed URL) but `registerEndpoint` returns different data per test, the second
+test sees the first's response unless you clear it:
+
+```typescript
+import { clearNuxtData } from "#imports"; // not exported from @nuxt/test-utils/runtime
+beforeEach(() => clearNuxtData());
+```
+
 ## File Organization
 
 Co-locate tests with source files:

package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vue-nuxt
-description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-import rules, component authoring (props/emits/withDefaults/generics), v-model/defineModel, slots, composables, reactivity, when watch is a code smell, page structure, display formatting, and Vue-shaped template idioms.
+description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-import rules, component authoring (props/emits/withDefaults/generics), v-model/defineModel, slots, composables, reactivity, when watch is a code smell, reaching for VueUse over hand-rolled effects, page structure, display formatting, and Vue-shaped template idioms.
 ---
 
 # Vue-in-Nuxt component authoring
@@ -23,6 +23,7 @@ cross-links to those rather than restating them.
 - Formatting display values (currency/date/number) consistently
 - Anything reactivity-shaped: `computed` vs `watch`, prop→state sync, DOM measurement
 - You see `watch` and want to know if it should be something else
+- About to hand-roll a `watch` + lifecycle teardown for a browser API (storage, timers, DOM, listeners, URL) — VueUse likely wraps it
 
 ## Reference Files
 
@@ -33,6 +34,7 @@ cross-links to those rather than restating them.
 - [composables.md](./composables.md) — `MaybeRefOrGetter`/`toValue` argument contract, return refs not `reactive()`, thin pure-core shell, `onScopeDispose`/`effectScope` cleanup
 - [reactivity.md](./reactivity.md) — `ref` over `reactive`, `useTemplateRef`, pure computeds, mutate-don't-reassign, DOM-measure + `ResizeObserver`, `shallowRef`, watch-getter prop sync, `:key` remount, listener cleanup
 - [watch.md](./watch.md) — **`watch` is the escape hatch, not the default**: when it's right, and the four smell shapes (with refactors) found auditing 159 real watchers
+- [vueuse.md](./vueuse.md) — reach for a VueUse composable before hand-rolling a `watch` + lifecycle teardown for an external-world effect (DOM, timers, storage, URL, listeners); the `@vueuse/nuxt` setup, the watch-sugar functions, and what to keep on Nuxt's own APIs
 - [template-idioms.md](./template-idioms.md) — duplicate-`@keyup` TS error, `:deep()`/`:slotted()`/`:global()`, click-outside marker class, `NuxtLink`/thin `app.vue`, `useHead`, `v-bind` shorthand, `useId`, `<Teleport>`/`<KeepAlive>`, `v-memo`/`v-once`, file-input reset
 - [page-structure.md](./page-structure.md) — keep pages thin: route-param parsing + layout in the page, data/logic/forms in components
 - [formatters.md](./formatters.md) — never inline a currency/date/number formatter; centralize in `useFormatters`, prefer Intl/date-fns
@@ -42,7 +44,7 @@ cross-links to those rather than restating them.
 1. **Lean on auto-imports.** `app/components`, `app/composables`, `app/utils`, and the Vue/Nuxt APIs all auto-import. Add an explicit `import` only for third-party symbols and TS types. A nested component's tag carries its directory as a prefix (`components/customers/ProfileCard.vue` → `<CustomersProfileCard>`).
 2. **Type props/emits, default the booleans.** Use the type-only macros (`defineProps<{...}>()`, `defineEmits<{...}>()`). A bare `boolean` prop coerces to `false` when absent (not `undefined`), so any "defaults-on" flag MUST be defaulted — via reactive destructure (`{ flag = true } = defineProps<…>()`, the 3.5 default, no factory needed for arrays/objects) or `withDefaults` (factory required for non-primitives).
 3. **`computed` for derivation, `watch` for escaping the graph.** If a watcher body just assigns one reactive value from others, it's a `computed`. Need to write a value back? A `computed` can have a setter — reach for a writable `computed` or `defineModel` before a sync watcher. Keep computed getters pure (no fetch, no mutation, no DOM).
-4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive).
+4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive). Before hand-rolling that effect-plus-teardown, check whether a **VueUse** composable already wraps it (`vueuse.md`) — they bundle the cleanup.
 5. **Call composables at the top of `<script setup>`** — never inside a callback or a template expression (both lose Nuxt's request scope). Derive display state with `computed`, guarding for possibly-null data.
 6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. Volt components, `pt:` styling, color tokens, dark mode → `volt-primevue`. Don't duplicate them here.
 

package/plugins/vue-nuxt/skills/vue-nuxt/vueuse.md

@@ -0,0 +1,101 @@
+# VueUse — reach for a composable before hand-rolling an effect
+
+`watch.md` lists the cases where `watch` is legit: they're all effects that cross
+**out of** the reactive graph (DOM, timers, storage, URL, the network). For most
+of those, **VueUse already wraps the boundary** — and a VueUse composable bundles
+the *teardown* with the reactive effect, so it retires the manual-`onUnmounted`
+cleanup, not just the watch. Before you write a `watch` + `onMounted`/`onUnmounted`
+pair against a browser API, check whether a composable does it.
+
+> Not a replacement for the framework. Data fetching stays on
+> `useFetch`/`useAsyncData` (see `nuxt-nitro-api`); cookies use Nuxt's built-in
+> `useCookie`; derivation stays a `computed`. VueUse is for the *external-world*
+> effects — see the caveats at the bottom.
+
+## Setup in Nuxt
+
+Add the module; it auto-imports every `@vueuse/core` function, so they need no
+explicit `import` (same as Nuxt's own composables — see `auto-imports.md`):
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({ modules: ['@vueuse/nuxt'] })
+```
+
+The **`@vueuse/router`** and **`@vueuse/integrations`** add-ons are separate
+installs and are **not** auto-imported by the module — import them explicitly.
+
+## The boundary cases (mapped from `watch.md`)
+
+| You were about to `watch` for… | Reach for | Why it's better |
+|---|---|---|
+| `document.body.style.overflow` toggle | `useScrollLock(document.body)` | writable ref; restores the prior value on unmount |
+| `setInterval` polling | `useIntervalFn(fn, ms)` / `useTimeoutPoll` | **auto-clears on unmount** — no `clearInterval` to forget |
+| `setTimeout` | `useTimeoutFn(fn, ms)` | same auto-cleanup, with `start`/`stop` controls |
+| debounced auto-save | `useDebounceFn` / `refDebounced` | no manual timer ref + cleanup |
+| `localStorage`/`sessionStorage` write-back | `useLocalStorage(key, init)` / `useStorage` | a reactive ref mirrored to storage both ways — the write-back watch disappears |
+| `addEventListener` in `onMounted` | `useEventListener(target, evt, fn)` | auto-removes on unmount |
+| click-outside marker class | `onClickOutside(el, fn)` | replaces the hand-rolled document listener (cf. `template-idioms.md`) |
+| `ResizeObserver` re-measure | `useElementSize` / `useElementBounding` / `useResizeObserver` | reactive size, observer torn down for you (cf. `reactivity.md`) |
+| `matchMedia` listener | `useMediaQuery` / `usePreferredColorScheme` / `usePreferredDark` | reactive boolean, no listener bookkeeping |
+| clipboard write + "copied!" flag | `useClipboard()` → `{ copy, copied }` | `copied` auto-resets |
+
+URL sync (`router.replace({ query: { ...route.query, tab } })`) →
+`useRouteQuery('tab')` from `@vueuse/router` gives a ref bound two-way to the query
+param. Nuxt's own `useRoute()` is already reactive for *reads*; reach for
+`useRouteQuery` when you want a **writable** ref bound to a single param.
+
+### `useLocalStorage` reads at setup — guard SSR hydration
+
+`useLocalStorage`/`useStorage` is SSR-safe: on the server there's no `window`, so
+it returns the default and never touches storage (no `import.meta.client` guard
+needed — that guard was only for raw `localStorage.*` calls, which throw on the
+server). But on the client it reads storage **synchronously at setup**, so a value
+rendered *without a mount gate* differs between the server render (the default) and
+the hydrating client render (the stored value) → a hydration mismatch. Pass
+`{ initOnMounted: true }` to defer the read to `onMounted` so the first client
+render matches the server, or gate the rendering until mounted.
+
+```ts
+// shown straight away (no v-if gate) → defer the storage read to onMounted
+const view = useLocalStorage('view', 'list', { initOnMounted: true })
+```
+
+### `useRouteQuery` makes the URL the single source of truth
+
+Because the bound ref reads from and writes to the query param, the URL *is* the
+state — so it **can't represent a ref with two distinct "empty" states** (e.g. a
+filter that defaults to `"Open"` on load but clears to `null`; both would be "param
+absent"). When you need that distinction, keep a plain `ref` + a projecting `watch`
+(a sanctioned `watch.md` "URL sync" case). And **don't mix `useUrlSearchParams`
+(History API) with `useRouteQuery` (vue-router) in the same component** — they write
+the URL through different mechanisms and clobber each other's params; pick one.
+
+## VueUse's `watch` sugar — when a `watch` IS warranted
+
+When the effect genuinely belongs in a watcher, VueUse's Watch category removes the
+boilerplate `watch.md` warns about:
+
+- **`watchDebounced(src, cb, { debounce: 300 })`** / **`watchThrottled`** — the
+  debounced-auto-save case without a `setTimeout` inside the callback.
+- **`whenever(source, cb)`** — fires only when `source` becomes truthy; the
+  "re-seed on dialog open" pattern (`watch(visible, v => { if (v) … })`) as one line.
+- **`until(source).toBe(x)`** — await a reactive condition instead of polling.
+- **`watchOnce`** — auto-stops after the first fire; no manual `stop()` handle.
+- **`watchIgnorable` / `watchPausable`** — suppress or pause a watcher around a
+  programmatic write (a cleaner answer than guard flags for the "re-fires on
+  programmatic reseed" trap in `watch.md`).
+
+`onWatcherCleanup` and `flush: 'post'` (in `watch.md`) still apply — these are sugar
+over the same watcher, not a different mechanism.
+
+## Caveats — don't over-reach
+
+- **Cookies:** use Nuxt's built-in **`useCookie`** (SSR-aware), not VueUse's
+  `@vueuse/integrations` `useCookies` (a `universal-cookie` wrapper).
+- **Fetching:** `useFetch`/`useAsyncData`/`$fetch` own the data layer
+  (`nuxt-nitro-api`). Skip VueUse's `useFetch`/`useAsyncState` in a Nuxt app.
+- **Head/title:** prefer Nuxt's `useHead`/`useSeoMeta` over `useTitle`/`useFavicon`.
+- **Derivation is still a `computed`.** VueUse doesn't change the core rule: if the
+  body just assigns one reactive value from others, it's a `computed`, not a
+  composable and not a watch.

package/plugins/vue-nuxt/skills/vue-nuxt/watch.md

@@ -68,12 +68,35 @@ Only when the effect crosses **out of** the reactive graph:
   polling `setInterval` (clear it in `onUnmounted`).
 - **Persist** — a `localStorage`/`useCookie` write, debounced auto-save of a
   deep-watched form.
-- **URL sync** — `router.replace({ query: { ...route.query, tab } })`.
+- **URL sync** — `router.replace({ query: { ...route.query, tab } })`. For a single
+  ref ↔ one query param, prefer `useRouteQuery` (see below). A write-back watch is
+  the right tool only when the URL can't model the state: a ref with **two distinct
+  "empty" states** (e.g. a filter that defaults to `"Open"` on load but clears to
+  `null` — an absent param can map to only one of them), or a **composite object
+  fanning out to many params** (a PrimeVue filter object) that a one-ref-per-param
+  `useRouteQuery` can't express.
 - **Re-seed local state on dialog open** — `watch(visible, (v) => { if (v) initForm() })`.
-  The single most common legit pattern.
+  The single most common legit pattern. Its one-liner is `whenever(visible, initForm)`
+  (see `vueuse.md`); a compound guard keeps its inner half —
+  `watch(visible, (v) => { if (v && !props.x) reset() })` →
+  `whenever(visible, () => { if (!props.x) reset() })`.
 - **Clone a server prop into a locally-editable draft** —
   `watch(() => props.record, (r) => { if (r) form.value = structuredClone(toRaw(r)) }, { immediate: true })`.
 
+> **Before hand-rolling the external-world cases, check VueUse.** Most of the
+> bullets above (DOM, timers, persist, URL) are exactly what VueUse wraps — and a
+> VueUse composable bundles the *teardown* with the reactive effect, so it
+> retires the manual-`onUnmounted` footgun, not just the watch:
+>
+> - **DOM / body scroll** — `useScrollLock(document.body)` over a watch toggling `document.body.style.overflow`.
+> - **Timers** — `useIntervalFn` / `useTimeoutFn` / `useTimeoutPoll` auto-clear on unmount (no manual `clearInterval`); `useDebounceFn` / `refDebounced` for debounce.
+> - **Persist** — `useLocalStorage` / `useStorage`: a reactive ref mirrored to storage, no write-back watch.
+> - **URL sync** — `useRouteQuery` (from `@vueuse/router`) for a ref bound to a query param.
+>
+> Nuxt caveats: cookies use the built-in `useCookie`, **not** VueUse's
+> `@vueuse/integrations` `useCookies`; data fetching stays on
+> `useFetch`/`useAsyncData`. Auto-import the rest via the `@vueuse/nuxt` module.
+
 ### Cancel stale work with `onWatcherCleanup`
 
 A watcher that starts async work (a keyed `$fetch`, a timer) must cancel the
@@ -116,6 +139,22 @@ watch(activeId, () => scrollActiveIntoView(), { flush: 'post' })  // DOM already
 | **side-effect-in-handler** | watching a value that only changes via one control, to clear a dependent field | that control's `@update:model-value` handler |
 | **manual-refetch** | watching filter refs to call a function that calls `useFetch` | a `computed` `query` passed to `useFetch` |
 
+**An external source doesn't legitimize a deriving watch.** The
+watch-vs-`computed` decision turns on whether the *body* leaves the reactive
+graph — **not** on whether the *source* came from outside it. A watcher whose
+source is a composable/library ref (`useEventSource`'s `status`, a store getter,
+a `useWindowSize`) but whose body only assigns a derived value is still a
+`computed`. "The source is external state" is the most common excuse for keeping
+such a watch, and it's wrong — it's still derivation.
+
+```ts
+// ❌ a library ref as source tempts a watch, but the body only derives
+const isConnected = ref(false)
+watch(status, (s) => { isConnected.value = s === 'OPEN' })   // status from useEventSource
+// ✅ derivation is a computed, regardless of where status came from
+const isConnected = computed(() => status.value === 'OPEN')
+```
+
 The biggest real cluster was **side-effect-in-handler** — resetting dependent
 fields when a Select changed. In a watcher it hides cause/effect and re-fires on
 programmatic form reseeds; the colocated handler is direct and only fires on the