aico-cli 2.1.7 → 2.1.23

package/templates/skills/vue-best-practices/rules/deep-watch-numeric.md

@@ -0,0 +1,97 @@
+---
+title: Vue 3.5+ Deep Watch Numeric Depth
+impact: MEDIUM
+impactDescription: enables efficient array mutation watching with numeric deep option
+type: capability
+tags: watch, deep, vue-3.5, array, mutation, performance
+---
+
+# Vue 3.5+ Deep Watch Numeric Depth
+
+**Impact: MEDIUM** - enables efficient array mutation watching with numeric deep option
+
+Vue 3.5 introduced `deep: number` for watch depth control. This allows watching array mutations without the performance cost of deep traversal.
+
+## Symptoms
+
+- Array mutations not triggering watch callback
+- Deep watch causing performance issues on large nested objects
+- Unaware of new Vue 3.5 feature
+
+> **Note:** TypeScript error "Type 'number' is not assignable to type 'boolean'" no longer occurs with Vue 3.5+ and current TypeScript versions. The types now correctly support numeric `deep` values.
+
+## The Feature
+
+```typescript
+// Vue 3.5+ only
+watch(items, (newVal) => {
+  // Triggered on array mutations (push, pop, splice, etc.)
+}, { deep: 1 })
+```
+
+| deep value | Behavior |
+|------------|----------|
+| `true` | Full recursive traversal (original behavior) |
+| `false` | Only reference changes |
+| `1` | One level deep - array mutations, not nested objects |
+| `2` | Two levels deep |
+| `n` | N levels deep |
+
+## Fix
+
+**Step 1: Ensure Vue 3.5+**
+```bash
+npm install vue@^3.5.0
+```
+
+**Step 2: Use numeric depth**
+```typescript
+import { watch, ref } from 'vue'
+
+const items = ref([{ id: 1, data: { nested: 'value' } }])
+
+// Watch array mutations only (push, pop, etc.)
+watch(items, (newItems) => {
+  console.log('Array mutated')
+}, { deep: 1 })
+
+// Won't trigger on: items.value[0].data.nested = 'new'
+// Will trigger on: items.value.push(newItem)
+```
+
+## Performance Comparison
+
+```typescript
+const largeNestedData = ref({ /* deeply nested structure */ })
+
+// SLOW - traverses entire structure
+watch(largeNestedData, handler, { deep: true })
+
+// FAST - only watches top-level changes
+watch(largeNestedData, handler, { deep: 1 })
+
+// FASTEST - only reference changes
+watch(largeNestedData, handler, { deep: false })
+```
+
+## Alternative: watchEffect for Selective Tracking
+
+```typescript
+// Only tracks properties actually accessed
+watchEffect(() => {
+  // Only re-runs when items.value.length or first item changes
+  console.log(items.value.length, items.value[0]?.id)
+})
+```
+
+## TypeScript Note
+
+If TypeScript complains about numeric deep, ensure:
+1. Vue version is 3.5+
+2. TypeScript version is current (types are included with `vue` package)
+3. tsconfig targets correct node_modules types
+
+## Reference
+
+- [Vue Watchers Docs](https://vuejs.org/guide/essentials/watchers.html)
+- [Vue 3.5 Release Notes](https://blog.vuejs.org/posts/vue-3-5)

package/templates/skills/vue-best-practices/rules/define-model-update-event.md

@@ -0,0 +1,79 @@
+---
+title: defineModel Fires Update Event with Undefined
+impact: MEDIUM
+impactDescription: fixes runtime errors from unexpected undefined in model updates
+type: capability
+tags: defineModel, v-model, update-event, undefined, vue-3.5
+---
+
+# defineModel Fires Update Event with Undefined
+
+**Impact: MEDIUM** - fixes runtime errors from unexpected undefined in model updates
+
+> **Version Note:** This issue may be resolved in Vue 3.5+. Testing with Vue 3.5.26 could not reproduce the double emission with `undefined`. If you're on Vue 3.5+, verify the issue exists in your specific scenario before applying workarounds.
+
+Components using `defineModel` may fire the `@update:model-value` event with `undefined` in certain edge cases. TypeScript types don't always reflect this behavior, potentially causing runtime errors when the parent expects a non-nullable value.
+
+## Symptoms
+
+- Parent component receives `undefined` unexpectedly
+- Runtime error: "Cannot read property of undefined"
+- Type mismatch between expected `T` and received `T | undefined`
+- Issue appears when clearing/resetting the model value
+
+## Root Cause
+
+`defineModel` returns `Ref<T | undefined>` by default, even when `T` is non-nullable. The update event can fire with `undefined` when:
+- Component unmounts
+- Model is explicitly cleared
+- Internal state resets
+
+## Fix
+
+**Option 1: Use required option (Vue 3.5+)**
+```typescript
+// Returns Ref<Item> instead of Ref<Item | undefined>
+const model = defineModel<Item>({ required: true })
+```
+
+**Option 2: Type parent handler to accept undefined**
+```vue
+<template>
+  <MyComponent
+    v-model="item"
+    @update:model-value="handleUpdate"
+  />
+</template>
+
+<script setup lang="ts">
+// Handle both value and undefined
+const handleUpdate = (value: Item | undefined) => {
+  if (value !== undefined) {
+    item.value = value
+  }
+}
+</script>
+```
+
+**Option 3: Use default value in defineModel**
+```typescript
+const model = defineModel<string>({ default: '' })
+```
+
+## Type Declaration Pattern
+
+```typescript
+// In child component
+interface Props {
+  modelValue: Item
+}
+const model = defineModel<Item>({ required: true })
+
+// Emits will be typed as (value: Item) not (value: Item | undefined)
+```
+
+## Reference
+
+- [vuejs/core#12817](https://github.com/vuejs/core/issues/12817)
+- [vuejs/core#10103](https://github.com/vuejs/core/issues/10103)
+- [defineModel docs](https://vuejs.org/api/sfc-script-setup.html#definemodel)

package/templates/skills/vue-best-practices/rules/duplicate-plugin-detection.md

@@ -0,0 +1,102 @@
+---
+title: Duplicate Vue Plugin Detection
+impact: MEDIUM
+impactDescription: fixes cryptic build errors from Vue plugin registered twice
+type: capability
+tags: vite, plugin, vue, duplicate, config, inline
+---
+
+# Duplicate Vue Plugin Detection
+
+**Impact: MEDIUM** - fixes cryptic build errors from Vue plugin registered twice
+
+When using Vite's JavaScript API, if the Vue plugin is loaded in `vite.config.js` and specified again in `inlineConfig`, it gets registered twice, causing cryptic build errors.
+
+## Symptoms
+
+- Build produces unexpected output or fails silently
+- "Cannot read property of undefined" during build
+- Different build behavior between CLI and JavaScript API
+- Vue components render incorrectly after build
+
+## Root Cause
+
+Vite doesn't deduplicate plugins by name when merging configs. The Vue plugin's internal state gets corrupted when registered twice.
+
+## Fix
+
+**Option 1: Use configFile: false with inline plugins**
+```typescript
+import { build } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+await build({
+  configFile: false,  // Don't load vite.config.js
+  plugins: [vue()],
+  // ... rest of config
+})
+```
+
+**Option 2: Don't specify plugins in inlineConfig**
+```typescript
+// vite.config.js already has vue plugin
+import { build } from 'vite'
+
+await build({
+  // Don't add vue plugin here - it's in vite.config.js
+  root: './src',
+  build: { outDir: '../dist' }
+})
+```
+
+**Option 3: Filter out Vue plugin before merging**
+```typescript
+import { build, loadConfigFromFile } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+const { config } = await loadConfigFromFile({ command: 'build', mode: 'production' })
+
+// Remove existing Vue plugin
+const filteredPlugins = config.plugins?.filter(
+  p => !p || (Array.isArray(p) ? false : p.name !== 'vite:vue')
+) || []
+
+await build({
+  ...config,
+  plugins: [...filteredPlugins, vue({ /* your options */ })]
+})
+```
+
+## Detection Script
+
+Add this to debug plugin registration:
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    vue(),
+    {
+      name: 'debug-plugins',
+      configResolved(config) {
+        const vuePlugins = config.plugins.filter(p => p.name?.includes('vue'))
+        if (vuePlugins.length > 1) {
+          console.warn('WARNING: Multiple Vue plugins detected:', vuePlugins.map(p => p.name))
+        }
+      }
+    }
+  ]
+})
+```
+
+## Common Scenarios
+
+| Scenario | Solution |
+|----------|----------|
+| Using `vite.createServer()` | Use `configFile: false` |
+| Build script with custom config | Don't duplicate plugins |
+| Monorepo with shared config | Check for plugin inheritance |
+
+## Reference
+
+- [Vite Issue #5335](https://github.com/vitejs/vite/issues/5335)
+- [Vite JavaScript API](https://vite.dev/guide/api-javascript.html)

package/templates/skills/vue-best-practices/rules/extract-component-props.md

@@ -0,0 +1,57 @@
+---
+title: Extract Component Props
+impact: HIGH
+impactDescription: extract props, emits, slots types from .vue components
+type: capability
+tags: typescript, props, emits, slots, vue-component-type-helpers, wrapper, ComponentProps
+---
+
+# Extract Component Props
+
+**Impact: HIGH** - extract props, emits, slots types from .vue components
+
+Use `vue-component-type-helpers` to extract types from `.vue` components:
+
+```bash
+npm install -D vue-component-type-helpers
+```
+
+```typescript
+import type { ComponentProps, ComponentEmit, ComponentSlots, ComponentExposed } from 'vue-component-type-helpers'
+import MyButton from './MyButton.vue'
+
+type Props = ComponentProps<typeof MyButton>
+type Emits = ComponentEmit<typeof MyButton>
+type Slots = ComponentSlots<typeof MyButton>
+type Exposed = ComponentExposed<typeof MyButton>
+```
+
+## Wrapper Component Pattern
+
+```typescript
+import type { ComponentProps } from 'vue-component-type-helpers'
+import BaseButton from './BaseButton.vue'
+
+type BaseProps = ComponentProps<typeof BaseButton>
+
+interface Props extends BaseProps {
+  size: 'sm' | 'md' | 'lg'
+}
+
+defineProps<Props>()
+```
+
+## Do NOT Use
+
+```typescript
+// ❌ Includes Vue internal properties (onUpdate:*, class, style, etc.)
+type Props = InstanceType<typeof MyButton>['$props']
+```
+
+## Note
+
+Vue's built-in `ExtractPropTypes` is for runtime props objects (`props: { foo: String }`), not for `.vue` components.
+
+## Reference
+
+- [vue-component-type-helpers](https://github.com/vuejs/language-tools/tree/master/packages/component-type-helpers)

package/templates/skills/vue-best-practices/rules/fallthrough-attributes.md

@@ -0,0 +1,63 @@
+---
+title: Enable Fallthrough Attributes Type Checking
+impact: MEDIUM
+impactDescription: enables IDE autocomplete for fallthrough attributes in wrapper components
+type: capability
+tags: fallthroughAttributes, vueCompilerOptions, component-library, wrapper-components
+---
+
+# Enable Fallthrough Attributes Type Checking
+
+**Impact: MEDIUM** - enables type-aware attribute forwarding in component libraries
+
+When building component libraries with wrapper components, enable `fallthroughAttributes` to get IDE autocomplete for attributes that will be forwarded to child elements.
+
+## What It Does
+
+Wrapper components that pass attributes to child elements can benefit from type-aware completion:
+
+```vue
+<!-- MyButton.vue - wrapper around native button -->
+<template>
+  <button v-bind="$attrs"><slot /></button>
+</template>
+```
+
+## Solution
+
+Enable `fallthroughAttributes` in your tsconfig:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "fallthroughAttributes": true
+  }
+}
+```
+
+## How It Works
+
+When `fallthroughAttributes: true`:
+- Vue Language Server analyzes which element receives `$attrs`
+- IDE autocomplete suggests valid attributes for the target element
+- Helps developers discover available attributes
+
+> **Note:** This primarily enables IDE autocomplete for valid fallthrough attributes. It does NOT reject invalid attributes as type errors - arbitrary attributes are still allowed.
+
+## Related Options
+
+Combine with `strictTemplates` for comprehensive checking:
+
+```json
+{
+  "vueCompilerOptions": {
+    "strictTemplates": true,
+    "fallthroughAttributes": true
+  }
+}
+```
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

package/templates/skills/vue-best-practices/rules/hmr-vue-ssr.md

@@ -0,0 +1,124 @@
+---
+title: HMR Debugging for Vue SSR
+impact: MEDIUM
+impactDescription: fixes Hot Module Replacement breaking in Vue SSR applications
+type: efficiency
+tags: vite, hmr, ssr, vue, hot-reload, server-side-rendering
+---
+
+# HMR Debugging for Vue SSR
+
+**Impact: MEDIUM** - fixes Hot Module Replacement breaking in Vue SSR applications
+
+Hot Module Replacement breaks when modifying Vue component `<script setup>` sections in SSR applications. Changes cause errors instead of smooth updates, requiring full page reloads.
+
+## Symptoms
+
+- HMR works for `<template>` changes but breaks for `<script setup>`
+- "Cannot read property of undefined" after saving
+- Full page reload required after script changes
+- HMR works in dev:client but not dev:ssr
+
+## Root Cause
+
+SSR mode has a different transformation pipeline. The Vue plugin's HMR boundary detection doesn't handle SSR modules the same way as client modules.
+
+## Fix
+
+**Step 1: Ensure correct SSR plugin configuration**
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  ssr: {
+    // Don't externalize these for HMR to work
+    noExternal: ['vue', '@vue/runtime-core', '@vue/runtime-dom']
+  }
+})
+```
+
+**Step 2: Configure dev server for SSR HMR**
+```typescript
+// server.ts
+import { createServer } from 'vite'
+
+const vite = await createServer({
+  server: { middlewareMode: true },
+  appType: 'custom'
+})
+
+// Use vite.ssrLoadModule for server-side imports
+const { render } = await vite.ssrLoadModule('/src/entry-server.ts')
+
+// Handle HMR
+vite.watcher.on('change', async (file) => {
+  if (file.endsWith('.vue')) {
+    // Invalidate the module
+    const mod = vite.moduleGraph.getModuleById(file)
+    if (mod) {
+      vite.moduleGraph.invalidateModule(mod)
+    }
+  }
+})
+```
+
+**Step 3: Add HMR acceptance in entry-server**
+```typescript
+// entry-server.ts
+import { createApp } from './main'
+
+export async function render(url: string) {
+  const app = createApp()
+  // ... render logic
+}
+
+// Accept HMR updates
+if (import.meta.hot) {
+  import.meta.hot.accept()
+}
+```
+
+## Framework-Specific Solutions
+
+### Nuxt 3
+HMR should work out of the box. If not:
+```bash
+rm -rf .nuxt node_modules/.vite
+npm install
+npm run dev
+```
+
+### Vite SSR Template
+Ensure you're using the latest `@vitejs/plugin-vue`:
+```bash
+npm install @vitejs/plugin-vue@latest
+```
+
+## Debugging
+
+Enable verbose HMR logging:
+```typescript
+// vite.config.ts
+export default defineConfig({
+  server: {
+    hmr: {
+      overlay: true
+    }
+  },
+  logLevel: 'info'  // Shows HMR updates
+})
+```
+
+## Known Limitations
+
+- HMR for `<script>` (not `<script setup>`) may require full reload
+- SSR components with external dependencies may not hot-reload
+- State is not preserved for SSR components (expected behavior)
+
+## Reference
+
+- [vite-plugin-vue#525](https://github.com/vitejs/vite-plugin-vue/issues/525)
+- [Vite SSR Guide](https://vite.dev/guide/ssr.html)

package/templates/skills/vue-best-practices/rules/module-resolution-bundler.md

@@ -0,0 +1,81 @@
+---
+title: moduleResolution Bundler Migration Issues
+impact: HIGH
+impactDescription: fixes "Cannot find module" errors after @vue/tsconfig upgrade
+type: capability
+tags: moduleResolution, bundler, tsconfig, vue-tsconfig, node, esm
+---
+
+# moduleResolution Bundler Migration Issues
+
+**Impact: HIGH** - fixes "Cannot find module" errors after @vue/tsconfig upgrade
+
+Recent versions of `@vue/tsconfig` changed `moduleResolution` from `"node"` to `"bundler"`. This can break existing projects with errors like "Cannot find module 'vue'" or issues with `resolveJsonModule`.
+
+## Symptoms
+
+- `Cannot find module 'vue'` or other packages
+- `Option '--resolveJsonModule' cannot be specified without 'node' module resolution`
+- Errors appear after updating `@vue/tsconfig`
+- Some third-party packages no longer resolve
+
+## Root Cause
+
+`moduleResolution: "bundler"` requires:
+1. TypeScript 5.0+
+2. Packages to have proper `exports` field in package.json
+3. Different resolution rules than Node.js classic resolution
+
+## Fix
+
+**Option 1: Ensure TypeScript 5.0+ everywhere**
+```bash
+npm install -D typescript@^5.0.0
+```
+
+In monorepos, ALL packages must use TypeScript 5.0+.
+
+**Option 2: Add compatibility workaround**
+```json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolvePackageJsonExports": false
+  }
+}
+```
+
+Setting `resolvePackageJsonExports: false` restores compatibility with packages that don't have proper exports.
+
+**Option 3: Revert to Node resolution**
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Which Packages Break?
+
+Packages break if they:
+- Lack `exports` field in package.json
+- Have incorrect `exports` configuration
+- Rely on Node.js-specific resolution behavior
+
+## Diagnosis
+
+```bash
+# Check which resolution is being used
+cat tsconfig.json | grep moduleResolution
+
+# Test if a specific module resolves
+npx tsc --traceResolution 2>&1 | grep "module-name"
+```
+
+## Reference
+
+- [vuejs/tsconfig#8](https://github.com/vuejs/tsconfig/issues/8)
+- [TypeScript moduleResolution docs](https://www.typescriptlang.org/tsconfig#moduleResolution)
+- [Vite discussion#14001](https://github.com/vitejs/vite/discussions/14001)