@dianzhong/create-harness-app 0.1.1 → 0.1.3

package/templates/harness/full/.agents/skills/vue-best-practices/references/render-functions.md

@@ -1,227 +0,0 @@
----
-title: Render Function Patterns and Performance
-impact: MEDIUM
-impactDescription: Render functions require explicit patterns for lists, events, v-model, and performance to stay correct and maintainable
-type: best-practice
-tags: [vue3, render-function, h, v-model, directives, performance, jsx]
----
-
-# Render Function Patterns and Performance
-
-**Impact: MEDIUM** - Render functions are powerful but opt out of template compiler optimizations. Use them intentionally and apply the key patterns below to keep output correct and performant.
-
-## Task List
-
-- Prefer templates; use render functions only when templates cannot express the logic
-- Always add stable keys when rendering lists with `h()`/JSX
-- Use `withModifiers` / `withKeys` for event modifiers
-- Implement `v-model` via `modelValue` + `onUpdate:modelValue`
-- Apply custom directives with `withDirectives`
-- Use functional components for stateless presentational UI
-
-## Prefer templates over render functions
-
-**BAD:**
-
-```vue
-<script setup>
-import { h, ref } from 'vue'
-
-const count = ref(0)
-const render = () => h('div', `Count: ${count.value}`)
-</script>
-```
-
-**GOOD:**
-
-```vue
-<script setup>
-import { ref } from 'vue'
-
-const count = ref(0)
-</script>
-
-<template>
-  <div>Count: {{ count }}</div>
-</template>
-```
-
-## Always add keys for list rendering
-
-**BAD:**
-
-```javascript
-import { h, ref } from 'vue'
-
-export default {
-  setup() {
-    const items = ref([{ id: 1, name: 'Apple' }])
-
-    return () =>
-      h(
-        'ul',
-        items.value.map((item) => h('li', item.name)),
-      )
-  },
-}
-```
-
-**GOOD:**
-
-```javascript
-import { h, ref } from 'vue'
-
-export default {
-  setup() {
-    const items = ref([{ id: 1, name: 'Apple' }])
-
-    return () =>
-      h(
-        'ul',
-        items.value.map((item) => h('li', { key: item.id }, item.name)),
-      )
-  },
-}
-```
-
-## Use `withModifiers` / `withKeys` for event modifiers
-
-**BAD:**
-
-```javascript
-import { h } from 'vue'
-
-export default {
-  setup() {
-    const handleClick = (e) => {
-      e.stopPropagation()
-      e.preventDefault()
-    }
-
-    return () => h('button', { onClick: handleClick }, 'Click')
-  },
-}
-```
-
-**GOOD:**
-
-```javascript
-import { h, withKeys, withModifiers } from 'vue'
-
-export default {
-  setup() {
-    const handleClick = () => {}
-    const handleEnter = () => {}
-
-    return () =>
-      h('div', [
-        h(
-          'button',
-          {
-            onClick: withModifiers(handleClick, ['stop', 'prevent']),
-          },
-          'Click',
-        ),
-        h('input', {
-          onKeyup: withKeys(handleEnter, ['enter']),
-        }),
-      ])
-  },
-}
-```
-
-## Implement `v-model` explicitly
-
-**BAD:**
-
-```javascript
-import { h, ref } from 'vue'
-
-import CustomInput from './CustomInput.vue'
-
-export default {
-  setup() {
-    const text = ref('')
-    return () => h(CustomInput, { modelValue: text.value })
-  },
-}
-```
-
-**GOOD:**
-
-```javascript
-import { h, ref } from 'vue'
-
-import CustomInput from './CustomInput.vue'
-
-export default {
-  setup() {
-    const text = ref('')
-    return () =>
-      h(CustomInput, {
-        modelValue: text.value,
-        'onUpdate:modelValue': (value) => {
-          text.value = value
-        },
-      })
-  },
-}
-```
-
-## Use `withDirectives` for custom directives
-
-**BAD:**
-
-```javascript
-import { h } from 'vue'
-
-const vFocus = { mounted: (el) => el.focus() }
-
-export default {
-  setup() {
-    return () => h('input', { 'v-focus': true })
-  },
-}
-```
-
-**GOOD:**
-
-```javascript
-import { h, withDirectives } from 'vue'
-
-const vFocus = { mounted: (el) => el.focus() }
-
-export default {
-  setup() {
-    return () => withDirectives(h('input'), [[vFocus]])
-  },
-}
-```
-
-## Prefer functional components for stateless UI
-
-**BAD:**
-
-```javascript
-import { h } from 'vue'
-
-export default {
-  setup() {
-    return () => h('span', { class: 'badge' }, 'New')
-  },
-}
-```
-
-**GOOD:**
-
-```javascript
-import { h } from 'vue'
-
-function Badge(props, { slots }) {
-  return h('span', { class: 'badge' }, slots.default?.())
-}
-
-Badge.props = ['variant']
-
-export default Badge
-```

package/templates/harness/full/.agents/skills/vue-best-practices/references/sfc.md

@@ -1,355 +0,0 @@
----
-title: Single-File Component Structure, Styling, and Template Patterns
-impact: MEDIUM
-impactDescription: Consistent SFC structure and styling choices improve maintainability, tooling support, and render performance
-type: best-practice
-tags:
-  [
-    vue3,
-    sfc,
-    scoped-css,
-    styles,
-    build-tools,
-    performance,
-    template,
-    v-html,
-    v-for,
-    computed,
-    v-if,
-    v-show,
-  ]
----
-
-# Single-File Component Structure, Styling, and Template Patterns
-
-**Impact: MEDIUM** - Using SFCs with consistent structure and performant styling keeps components easier to maintain and avoids unnecessary render overhead.
-
-## Task List
-
-- Use `.vue` SFCs instead of separate `.js`/`.ts` and `.css` files for components
-- Colocate template, script, and styles in the same SFC by default
-- Use PascalCase for component names in templates and filenames
-- Prefer component-scoped styles
-- Prefer class selectors (not element selectors) in scoped CSS for performance
-- Access DOM / component refs with `useTemplateRef()` in Vue 3.5+
-- Use camelCase keys in `:style` bindings for consistency and IDE support
-- Use `v-for` and `v-if` correctly
-- Never use `v-html` with untrusted/user-provided content
-- Choose `v-if` vs `v-show` based on toggle frequency and initial render cost
-
-## Colocate template, script, and styles
-
-**BAD:**
-
-```
-components/
-├── UserCard.vue
-├── UserCard.js
-└── UserCard.css
-```
-
-**GOOD:**
-
-```vue
-<!-- components/UserCard.vue -->
-<script setup>
-import { computed } from 'vue'
-
-const props = defineProps({
-  user: { type: Object, required: true },
-})
-
-const displayName = computed(() => `${props.user.firstName} ${props.user.lastName}`)
-</script>
-
-<template>
-  <div class="user-card">
-    <h3 class="name">
-      {{ displayName }}
-    </h3>
-  </div>
-</template>
-
-<style scoped>
-.user-card {
-  padding: 1rem;
-}
-
-.name {
-  margin: 0;
-}
-</style>
-```
-
-## Use PascalCase for component names
-
-**BAD:**
-
-```vue
-<script setup>
-import userProfile from './user-profile.vue'
-</script>
-
-<template>
-  <user-profile :user="currentUser" />
-</template>
-```
-
-**GOOD:**
-
-```vue
-<script setup>
-import UserProfile from './UserProfile.vue'
-</script>
-
-<template>
-  <UserProfile :user="currentUser" />
-</template>
-```
-
-## Best practices for `<style>` block in SFCs
-
-### Prefer component-scoped styles
-
-- Use `<style scoped>` for styles that belong to a component.
-- Keep **global CSS** in a dedicated file (e.g. `src/assets/main.css`) for resets, typography, tokens, etc.
-- Use `:deep()` sparingly (edge cases only).
-
-**BAD:**
-
-```vue
-<style>
-/* ❌ leaks everywhere */
-button {
-  border-radius: 999px;
-}
-</style>
-```
-
-**GOOD:**
-
-```vue
-<style scoped>
-.button {
-  border-radius: 999px;
-}
-</style>
-```
-
-**GOOD:**
-
-```css
-/* src/assets/main.css */
-/* ✅ resets, tokens, typography, app-wide rules */
-:root {
-  --radius: 999px;
-}
-```
-
-### Use class selectors in scoped CSS
-
-**BAD:**
-
-```vue
-<template>
-  <article>
-    <h1>{{ title }}</h1>
-    <p>{{ subtitle }}</p>
-  </article>
-</template>
-
-<style scoped>
-article {
-  max-width: 800px;
-}
-h1 {
-  font-size: 2rem;
-}
-p {
-  line-height: 1.6;
-}
-</style>
-```
-
-**GOOD:**
-
-```vue
-<template>
-  <article class="article">
-    <h1 class="article-title">
-      {{ title }}
-    </h1>
-    <p class="article-subtitle">
-      {{ subtitle }}
-    </p>
-  </article>
-</template>
-
-<style scoped>
-.article {
-  max-width: 800px;
-}
-.article-title {
-  font-size: 2rem;
-}
-.article-subtitle {
-  line-height: 1.6;
-}
-</style>
-```
-
-## Access DOM / component refs with `useTemplateRef()`
-
-For Vue 3.5+: use `useTemplateRef()` to access template refs.
-
-```vue
-<script setup lang="ts">
-import { onMounted, useTemplateRef } from 'vue'
-
-const inputRef = useTemplateRef<HTMLInputElement>('input')
-
-onMounted(() => {
-  inputRef.value?.focus()
-})
-</script>
-
-<template>
-  <input ref="input" />
-</template>
-```
-
-## Use camelCase in `:style` bindings
-
-**BAD:**
-
-```vue
-<template>
-  <div :style="{ 'font-size': `${fontSize}px`, 'background-color': bg }">Content</div>
-</template>
-```
-
-**GOOD:**
-
-```vue
-<template>
-  <div :style="{ fontSize: `${fontSize}px`, backgroundColor: bg }">Content</div>
-</template>
-```
-
-## Use `v-for` and `v-if` correctly
-
-### Always provide a stable `:key`
-
-- Prefer primitive keys (`string | number`).
-- Avoid using objects as keys.
-
-**GOOD:**
-
-```vue
-<li v-for="item in items" :key="item.id">
-  <input v-model="item.text" />
-</li>
-```
-
-### Avoid `v-if` and `v-for` on the same element
-
-It leads to unclear intent and unnecessary work.
-([Reference](https://vuejs.org/guide/essentials/list.html#v-for-with-v-if))
-
-**To filter items**
-**BAD:**
-
-```vue
-<li v-for="user in users" v-if="user.active" :key="user.id">
-  {{ user.name }}
-</li>
-```
-
-**GOOD:**
-
-```vue
-<script setup lang="ts">
-import { computed } from 'vue'
-
-const activeUsers = computed(() => users.value.filter((u) => u.active))
-</script>
-
-<template>
-  <li v-for="user in activeUsers" :key="user.id">
-    {{ user.name }}
-  </li>
-</template>
-```
-
-**To conditionally show/hide the entire list**
-**GOOD:**
-
-```vue
-<ul v-if="shouldShowUsers">
-  <li v-for="user in users" :key="user.id">
-    {{ user.name }}
-  </li>
-</ul>
-```
-
-## Never render untrusted HTML with `v-html`
-
-**BAD:**
-
-```vue
-<template>
-  <!-- DANGEROUS: untrusted input can inject scripts -->
-  <article v-html="userProvidedContent" />
-</template>
-```
-
-**GOOD:**
-
-```vue
-<script setup>
-import DOMPurify from 'dompurify'
-
-import { computed } from 'vue'
-
-const props = defineProps<{
-  trustedHtml?: string
-  plainText: string
-}>()
-
-const safeHtml = computed(() => DOMPurify.sanitize(props.trustedHtml ?? ''))
-</script>
-
-<template>
-  <!-- Preferred: escaped interpolation -->
-  <p>{{ props.plainText }}</p>
-
-  <!-- Only for trusted/sanitized HTML -->
-  <article v-html="safeHtml" />
-</template>
-```
-
-## Choose `v-if` vs `v-show` by toggle behavior
-
-**BAD:**
-
-```vue
-<template>
-  <!-- Frequent toggles with v-if cause repeated mount/unmount -->
-  <ComplexPanel v-if="isPanelOpen" />
-
-  <!-- Rarely shown content with v-show pays initial render cost -->
-  <AdminPanel v-show="isAdmin" />
-</template>
-```
-
-**GOOD:**
-
-```vue
-<template>
-  <!-- Frequent toggles: keep in DOM, toggle display -->
-  <ComplexPanel v-show="isPanelOpen" />
-
-  <!-- Rare condition: lazy render only when true -->
-  <AdminPanel v-if="isAdmin" />
-</template>
-```

package/templates/harness/full/.agents/skills/vue-best-practices/references/state-management.md

@@ -1,138 +0,0 @@
----
-title: State Management Strategy
-impact: HIGH
-impactDescription: Choosing the wrong store pattern can cause SSR request leaks, brittle mutation flows, and poor scaling
-type: best-practice
-tags: [vue3, state-management, pinia, composables, ssr, vueuse]
----
-
-# State Management Strategy
-
-**Impact: HIGH** - Use the lightest state solution that fits your app architecture. SPA-only apps can use lightweight global composables, while SSR/Nuxt apps should default to Pinia for request-safe isolation and predictable tooling.
-
-## Task List
-
-- Keep state local first, then promote to shared/global only when needed
-- Use singleton composables only in non-SSR applications
-- Expose global state as readonly and mutate through explicit actions
-- Prefer Pinia for SSR/Nuxt, large apps, and advanced debugging/plugin needs
-- Avoid exporting mutable module-level reactive state directly
-
-## Choose the Lightest Store Approach
-
-- **Feature composable:** Default for reusable logic with local/feature-level state.
-- **Singleton composable or VueUse `createGlobalState`:** Small non-SSR apps needing shared app state.
-- **Pinia:** SSR/Nuxt apps, medium-to-large apps, and cases requiring DevTools, plugins, or action tracing.
-
-## Avoid Exporting Mutable Module State
-
-**BAD:**
-
-```ts
-// store/cart.ts
-import { reactive } from 'vue'
-
-export const cart = reactive({
-  items: [] as Array<{ id: string; qty: number }>,
-})
-```
-
-**GOOD:**
-
-```ts
-// composables/useCartStore.ts
-import { reactive, readonly } from 'vue'
-
-let _store: ReturnType<typeof createCartStore> | null = null
-
-function createCartStore() {
-  const state = reactive({
-    items: [] as Array<{ id: string; qty: number }>,
-  })
-
-  function addItem(id: string, qty = 1) {
-    const existing = state.items.find((item) => item.id === id)
-    if (existing) {
-      existing.qty += qty
-      return
-    }
-    state.items.push({ id, qty })
-  }
-
-  return {
-    state: readonly(state),
-    addItem,
-  }
-}
-
-export function useCartStore() {
-  if (!_store) _store = createCartStore()
-  return _store
-}
-```
-
-## Do Not Use Runtime Singletons in SSR
-
-Module singletons live for the runtime lifetime. In SSR this can leak state between requests.
-
-**BAD:**
-
-```ts
-// shared singleton reused across requests
-const cartStore = useCartStore()
-
-export function useServerCart() {
-  return cartStore
-}
-```
-
-**GOOD:**
-
-> `pinia` dependency required.
-
-```ts
-// stores/cart.ts
-import { defineStore } from 'pinia'
-
-export const useCartStore = defineStore('cart', {
-  state: () => ({
-    items: [] as Array<{ id: string; qty: number }>,
-  }),
-  actions: {
-    addItem(id: string, qty = 1) {
-      const existing = this.items.find((item) => item.id === id)
-      if (existing) {
-        existing.qty += qty
-        return
-      }
-      this.items.push({ id, qty })
-    },
-  },
-})
-```
-
-## Use `createGlobalState` for Small SPA Global State
-
-> `@vueuse/core` dependency required.
-
-If the app is non-SSR and already uses VueUse, `createGlobalState` removes singleton boilerplate.
-
-```ts
-import { createGlobalState } from '@vueuse/core'
-import { computed, ref } from 'vue'
-
-export const useAuthState = createGlobalState(() => {
-  const token = ref<string | null>(null)
-  const isAuthenticated = computed(() => token.value !== null)
-
-  function setToken(next: string | null) {
-    token.value = next
-  }
-
-  return {
-    token,
-    isAuthenticated,
-    setToken,
-  }
-})
-```