aico-cli 2.1.7 → 2.1.23

package/templates/skills/vitest/references/features-snapshots.md

@@ -0,0 +1,207 @@
+---
+name: snapshot-testing
+description: Snapshot testing with file, inline, and file snapshots
+---
+
+# Snapshot Testing
+
+Snapshot tests capture output and compare against stored references.
+
+## Basic Snapshot
+
+```ts
+import { expect, test } from 'vitest'
+
+test('snapshot', () => {
+  const result = generateOutput()
+  expect(result).toMatchSnapshot()
+})
+```
+
+First run creates `.snap` file:
+
+```js
+// __snapshots__/test.spec.ts.snap
+exports['snapshot 1'] = `
+{
+  "id": 1,
+  "name": "test"
+}
+`
+```
+
+## Inline Snapshots
+
+Stored directly in test file:
+
+```ts
+test('inline snapshot', () => {
+  const data = { foo: 'bar' }
+  expect(data).toMatchInlineSnapshot()
+})
+```
+
+Vitest updates the test file:
+
+```ts
+test('inline snapshot', () => {
+  const data = { foo: 'bar' }
+  expect(data).toMatchInlineSnapshot(`
+    {
+      "foo": "bar",
+    }
+  `)
+})
+```
+
+## File Snapshots
+
+Compare against explicit file:
+
+```ts
+test('render html', async () => {
+  const html = renderComponent()
+  await expect(html).toMatchFileSnapshot('./expected/component.html')
+})
+```
+
+## Snapshot Hints
+
+Add descriptive hints:
+
+```ts
+test('multiple snapshots', () => {
+  expect(header).toMatchSnapshot('header')
+  expect(body).toMatchSnapshot('body content')
+  expect(footer).toMatchSnapshot('footer')
+})
+```
+
+## Object Shape Matching
+
+Match partial structure:
+
+```ts
+test('shape snapshot', () => {
+  const data = { 
+    id: Math.random(), 
+    created: new Date(),
+    name: 'test' 
+  }
+  
+  expect(data).toMatchSnapshot({
+    id: expect.any(Number),
+    created: expect.any(Date),
+  })
+})
+```
+
+## Error Snapshots
+
+```ts
+test('error message', () => {
+  expect(() => {
+    throw new Error('Something went wrong')
+  }).toThrowErrorMatchingSnapshot()
+})
+
+test('inline error', () => {
+  expect(() => {
+    throw new Error('Bad input')
+  }).toThrowErrorMatchingInlineSnapshot(`[Error: Bad input]`)
+})
+```
+
+## Updating Snapshots
+
+```bash
+# Update all snapshots
+vitest -u
+vitest --update
+
+# In watch mode, press 'u' to update failed snapshots
+```
+
+## Custom Serializers
+
+Add custom snapshot formatting:
+
+```ts
+expect.addSnapshotSerializer({
+  test(val) {
+    return val && typeof val.toJSON === 'function'
+  },
+  serialize(val, config, indentation, depth, refs, printer) {
+    return printer(val.toJSON(), config, indentation, depth, refs)
+  },
+})
+```
+
+Or via config:
+
+```ts
+// vitest.config.ts
+defineConfig({
+  test: {
+    snapshotSerializers: ['./my-serializer.ts'],
+  },
+})
+```
+
+## Snapshot Format Options
+
+```ts
+defineConfig({
+  test: {
+    snapshotFormat: {
+      printBasicPrototype: false, // Don't print Array/Object prototypes
+      escapeString: false,
+    },
+  },
+})
+```
+
+## Concurrent Test Snapshots
+
+Use context's expect:
+
+```ts
+test.concurrent('concurrent 1', async ({ expect }) => {
+  expect(await getData()).toMatchSnapshot()
+})
+
+test.concurrent('concurrent 2', async ({ expect }) => {
+  expect(await getOther()).toMatchSnapshot()
+})
+```
+
+## Snapshot File Location
+
+Default: `__snapshots__/<test-file>.snap`
+
+Customize:
+
+```ts
+defineConfig({
+  test: {
+    resolveSnapshotPath: (testPath, snapExtension) => {
+      return testPath.replace('__tests__', '__snapshots__') + snapExtension
+    },
+  },
+})
+```
+
+## Key Points
+
+- Commit snapshot files to version control
+- Review snapshot changes in code review
+- Use hints for multiple snapshots in one test
+- Use `toMatchFileSnapshot` for large outputs (HTML, JSON)
+- Inline snapshots auto-update in test file
+- Use context's `expect` for concurrent tests
+
+<!-- 
+Source references:
+- https://vitest.dev/guide/snapshot.html
+- https://vitest.dev/api/expect.html#tomatchsnapshot
+-->

package/templates/skills/vue/GENERATION.md

@@ -0,0 +1,5 @@
+# Generation Info
+
+- **Source:** `sources/vue`
+- **Git SHA:** `dcf363038ab2f5b4571028669cf893d084b6b207`
+- **Generated:** 2026-01-28

package/templates/skills/vue/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: vue
+description: Vue.js progressive JavaScript framework. Use when building Vue components, working with reactivity (ref, reactive, computed, watch), or implementing Vue Composition API patterns.
+metadata:
+  author: Anthony Fu
+  version: "2026.1.28"
+  source: Generated from https://github.com/vuejs/docs, scripts located at https://github.com/antfu/skills
+---
+
+# Vue
+
+> The skill is based on Vue 3.5+, generated at 2026-01-28.
+
+Vue is a progressive JavaScript framework for building user interfaces. It builds on standard HTML, CSS, and JavaScript with intuitive API and world-class documentation. The Composition API with `<script setup>` and TypeScript is the recommended approach for building Vue applications.
+
+## Core References
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Reactivity System | ref, reactive, computed, watch, and watchEffect | [core-reactivity](references/core-reactivity.md) |
+
+## Components
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Props | Declare and validate component props with TypeScript | [components-props](references/components-props.md) |
+| Events (Emits) | Emit custom events from components | [components-emits](references/components-emits.md) |
+| Slots | Pass template content to child components | [components-slots](references/components-slots.md) |
+| v-model | Two-way binding on custom components | [components-v-model](references/components-v-model.md) |
+| Lifecycle Hooks | Run code at specific component lifecycle stages | [components-lifecycle](references/components-lifecycle.md) |
+
+## Features
+
+### Script Setup & TypeScript
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Script Setup | Composition API syntactic sugar for SFCs | [features-script-setup](references/features-script-setup.md) |
+| TypeScript | Type-safe Vue components with Composition API | [features-typescript](references/features-typescript.md) |
+
+### Reusability
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Composables | Encapsulate and reuse stateful logic | [features-composables](references/features-composables.md) |
+| Custom Directives | Low-level DOM manipulation directives | [features-directives](references/features-directives.md) |
+| Template Refs | Direct DOM and component instance access | [features-template-refs](references/features-template-refs.md) |
+
+## Advanced
+
+| Topic | Description | Reference |
+|-------|-------------|-----------|
+| Provide/Inject | Dependency injection across component tree | [advanced-provide-inject](references/advanced-provide-inject.md) |
+| Async & Suspense | Top-level await pitfalls, async components, Suspense | [advanced-async-suspense](references/advanced-async-suspense.md) |
+
+## Key Recommendations
+
+- **Use `<script setup lang="ts">`** for all components
+- **Prefer `ref()` over `reactive()`** for declaring state
+- **Use type-based prop declarations** with interfaces
+- **Use `defineModel()`** for v-model (3.4+)
+- **Destructure props reactively** (3.5+) for cleaner code
+- **Extract composables** for reusable stateful logic

package/templates/skills/vue/references/advanced-async-suspense.md

@@ -0,0 +1,246 @@
+---
+name: async-components-suspense
+description: Handle async operations, top-level await, and Suspense boundaries
+---
+
+# Async Components & Suspense
+
+Vue provides patterns for handling asynchronous operations in components.
+
+## Top-Level await in Script Setup
+
+`<script setup>` supports top-level `await`, making the component an async dependency:
+
+```vue
+<script setup lang="ts">
+const data = await fetch('/api/data').then(r => r.json())
+</script>
+
+<template>
+  <div>{{ data }}</div>
+</template>
+```
+
+**Important**: Components with top-level `await` **require a `<Suspense>` boundary** in a parent component, otherwise they won't render.
+
+## Suspense
+
+`<Suspense>` is a built-in component for handling async dependencies in the component tree.
+
+```vue
+<template>
+  <Suspense>
+    <!-- Component with async setup -->
+    <AsyncComponent />
+    
+    <!-- Fallback while loading -->
+    <template #fallback>
+      <div>Loading...</div>
+    </template>
+  </Suspense>
+</template>
+```
+
+### Suspense Slots
+
+- **default**: The async content to render
+- **fallback**: Content shown while async dependencies are resolving
+
+```vue
+<Suspense>
+  <template #default>
+    <Dashboard />
+  </template>
+  <template #fallback>
+    <LoadingSpinner />
+  </template>
+</Suspense>
+```
+
+## Async Components
+
+Define components that are loaded asynchronously:
+
+```ts
+import { defineAsyncComponent } from 'vue'
+
+const AsyncModal = defineAsyncComponent(() => 
+  import('./components/Modal.vue')
+)
+
+// With options
+const AsyncModalWithOptions = defineAsyncComponent({
+  loader: () => import('./components/Modal.vue'),
+  loadingComponent: LoadingSpinner,
+  errorComponent: ErrorDisplay,
+  delay: 200,        // Delay before showing loading (ms)
+  timeout: 3000      // Timeout before showing error (ms)
+})
+```
+
+## Common Async Pitfalls
+
+### Pitfall 1: Missing Suspense Boundary
+
+```vue
+<!-- ❌ Won't work - no Suspense boundary -->
+<template>
+  <AsyncComponent />
+</template>
+
+<!-- ✅ Works -->
+<template>
+  <Suspense>
+    <AsyncComponent />
+    <template #fallback>Loading...</template>
+  </Suspense>
+</template>
+```
+
+### Pitfall 2: Lifecycle Hooks After await
+
+Lifecycle hooks must be registered synchronously, before any `await`:
+
+```vue
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue'
+
+// ✅ Register hooks BEFORE await
+onMounted(() => console.log('mounted'))
+onUnmounted(() => console.log('unmounted'))
+
+// Now you can await
+const data = await fetchData()
+</script>
+```
+
+```vue
+<script setup lang="ts">
+// ❌ WRONG - hooks after await won't work
+const data = await fetchData()
+
+onMounted(() => {
+  // This may not be called!
+})
+</script>
+```
+
+### Pitfall 3: Composables After await
+
+Composables that use lifecycle hooks must be called before `await`:
+
+```vue
+<script setup lang="ts">
+import { useMouse } from '@/composables/useMouse'
+
+// ✅ Call composables BEFORE await
+const { x, y } = useMouse()
+
+const data = await fetchData()
+</script>
+```
+
+### Pitfall 4: Watchers Created in Async Callbacks
+
+Watchers in async callbacks aren't auto-disposed:
+
+```ts
+// ❌ Memory leak - watcher not auto-disposed
+setTimeout(() => {
+  watch(source, callback) // Must be stopped manually
+}, 1000)
+
+// ✅ Watchers in setup are auto-disposed
+watch(source, callback)
+```
+
+## Recommended Pattern: Avoid Top-Level await
+
+Often better to handle async in `onMounted` or with watchers:
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const data = ref<Data | null>(null)
+const isLoading = ref(true)
+const error = ref<Error | null>(null)
+
+onMounted(async () => {
+  try {
+    data.value = await fetchData()
+  } catch (e) {
+    error.value = e as Error
+  } finally {
+    isLoading.value = false
+  }
+})
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <div v-else>{{ data }}</div>
+</template>
+```
+
+This pattern:
+- Doesn't require Suspense
+- Gives you control over loading/error states
+- Works everywhere without special parent setup
+
+## When to Use Suspense
+
+Use Suspense when:
+- You have nested async components
+- You want coordinated loading states across multiple async children
+- You're doing SSR with async data requirements
+
+Avoid Suspense when:
+- Simple single-component async loading
+- You need fine-grained control over loading states
+- You want to avoid Suspense complexity
+
+## Suspense Events
+
+```vue
+<Suspense
+  @pending="onPending"
+  @resolve="onResolve"
+  @fallback="onFallback"
+>
+  <AsyncComponent />
+</Suspense>
+```
+
+## Error Handling with Suspense
+
+Use `onErrorCaptured` or `<ErrorBoundary>` pattern:
+
+```vue
+<script setup lang="ts">
+import { onErrorCaptured, ref } from 'vue'
+
+const error = ref<Error | null>(null)
+
+onErrorCaptured((e) => {
+  error.value = e
+  return false // Prevent propagation
+})
+</script>
+
+<template>
+  <div v-if="error">Error: {{ error.message }}</div>
+  <Suspense v-else>
+    <AsyncComponent />
+    <template #fallback>Loading...</template>
+  </Suspense>
+</template>
+```
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/built-ins/suspense.html
+- https://vuejs.org/guide/components/async.html
+- https://vuejs.org/api/sfc-script-setup.html#top-level-await
+-->

package/templates/skills/vue/references/advanced-provide-inject.md

@@ -0,0 +1,174 @@
+---
+name: provide-inject
+description: Pass data through component tree without prop drilling
+---
+
+# Provide / Inject
+
+Provide data from ancestor components to any descendant, avoiding prop drilling.
+
+## Basic Usage
+
+```vue
+<!-- Provider.vue -->
+<script setup lang="ts">
+import { provide, ref } from 'vue'
+
+const message = ref('hello')
+provide('message', message)
+</script>
+```
+
+```vue
+<!-- DeepChild.vue (any level deep) -->
+<script setup lang="ts">
+import { inject } from 'vue'
+
+const message = inject('message')
+</script>
+```
+
+## Typing with InjectionKey
+
+Use `InjectionKey` for type safety between provider and injector:
+
+```ts
+// keys.ts
+import type { InjectionKey, Ref } from 'vue'
+
+export const messageKey = Symbol() as InjectionKey<Ref<string>>
+export const countKey = Symbol() as InjectionKey<number>
+```
+
+```vue
+<!-- Provider.vue -->
+<script setup lang="ts">
+import { provide, ref } from 'vue'
+import { messageKey } from './keys'
+
+const message = ref('hello')
+provide(messageKey, message)
+</script>
+```
+
+```vue
+<!-- Injector.vue -->
+<script setup lang="ts">
+import { inject } from 'vue'
+import { messageKey } from './keys'
+
+const message = inject(messageKey) // Ref<string> | undefined
+</script>
+```
+
+## Default Values
+
+```ts
+// Simple default
+const value = inject('message', 'default value')
+
+// Factory function (for expensive defaults)
+const value = inject('key', () => new ExpensiveClass(), true)
+//                                                       ^ treat as factory
+```
+
+## App-Level Provide
+
+Available to all components:
+
+```ts
+// main.ts
+import { createApp } from 'vue'
+
+const app = createApp(App)
+app.provide('globalConfig', { theme: 'dark' })
+```
+
+## Reactive Provide/Inject
+
+Provide reactive values for automatic updates:
+
+```vue
+<!-- Provider.vue -->
+<script setup lang="ts">
+import { provide, ref } from 'vue'
+
+const count = ref(0)
+provide('count', count)
+</script>
+```
+
+The injected value maintains reactivity connection.
+
+## Mutations Best Practice
+
+Keep mutations in the provider, expose update functions:
+
+```vue
+<!-- Provider.vue -->
+<script setup lang="ts">
+import { provide, ref, readonly } from 'vue'
+
+const location = ref('North Pole')
+
+function updateLocation(newLocation: string) {
+  location.value = newLocation
+}
+
+provide('location', {
+  location: readonly(location), // Prevent direct mutation
+  updateLocation
+})
+</script>
+```
+
+```vue
+<!-- Injector.vue -->
+<script setup lang="ts">
+import { inject } from 'vue'
+
+const { location, updateLocation } = inject('location')!
+</script>
+
+<template>
+  <button @click="updateLocation('South Pole')">
+    {{ location }}
+  </button>
+</template>
+```
+
+## Using Symbol Keys
+
+Recommended for libraries and large apps to avoid collisions:
+
+```ts
+// keys.ts
+export const myKey = Symbol('myKey')
+
+// provider
+provide(myKey, value)
+
+// injector
+inject(myKey)
+```
+
+## Type Helpers
+
+```ts
+// String key with explicit type
+const foo = inject<string>('foo')
+//    ^? string | undefined
+
+// With default (removes undefined)
+const foo = inject<string>('foo', 'default')
+//    ^? string
+
+// Force non-undefined (use when certain it's provided)
+const foo = inject('foo') as string
+```
+
+<!-- 
+Source references:
+- https://vuejs.org/guide/components/provide-inject.html
+- https://vuejs.org/guide/typescript/composition-api.html#typing-provide-inject
+-->