@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/vue-nuxt/references/migration-nuxt4.md

@@ -0,0 +1,79 @@
+# Migration: Nuxt 3 → Nuxt 4, and Vue 3.4 → 3.5
+
+Companion to the SKILL "detect version" table. Nuxt 4.0 shipped July 2025; the 4.x line is current
+stable. Nuxt 5 + Nitro 3 are in active development — treat any "Nuxt 5" claim as pre-release.
+
+## The `app/` srcDir move (headline change)
+
+Nuxt 4 moves application code under `app/` (`srcDir: 'app/'`). New default layout:
+
+```
+app/
+  components/   composables/   pages/   layouts/   stores/   utils/   middleware/
+  app.vue   error.vue   app.config.ts
+server/         # Nitro: api/, routes/, middleware/, plugins/, utils/
+shared/         # code shared between app and server (auto-imported in both)
+public/   modules/   layers/   nuxt.config.ts
+```
+
+Why: cleaner separation of client vs server code, faster file watching, and the `shared/` folder
+for genuinely isomorphic utilities. A Nuxt 3 repo with root `components/`/`pages/` still works, but
+new code should follow the `app/` layout.
+
+## Opting in / compatibility
+
+```ts
+// nuxt.config.ts — stay on legacy behavior while migrating
+export default defineNuxtConfig({
+  future: { compatibilityVersion: 4 },   // opt into v4 behavior on the v3→v4 bridge
+  // or pin srcDir explicitly while you move files:
+  // srcDir: 'app/',
+})
+```
+
+Run the upgrade with `npx nuxi upgrade` and use `npx codemod@latest nuxt/4/migration-recipe` (or
+the official migration guide) to move files and rewrite imports. Migrate folder-by-folder; the
+bridge lets old and new layouts coexist during the move.
+
+## Data-fetching deltas in Nuxt 4
+
+- **Shared keys**: `useFetch`/`useAsyncData` with the same `key` now share one `data`/`error`/
+  `status` ref across all callers, auto-cleaned when the last consumer unmounts. Audit code that
+  relied on per-call isolation.
+- **`data` is a `shallowRef`** by default — replace the whole value to trigger an update; deep
+  mutation no longer re-renders. If you genuinely need deep reactivity, opt out with
+  `{ deep: true }`.
+- **`getCachedData`** now receives a `{ cause }` context (`'initial' | 'refresh:manual' |
+  'refresh:hook' | 'watch'`) so you can vary caching by trigger.
+- Reactive keys (`ref`/`computed`/getter) refetch on change — previously you wired `watch` manually.
+- Nuxt 4.2 adds `AbortController` signal support for request cancellation.
+
+## Other notable changes
+
+- Singleton data layer and consistent `useAsyncData`/`useFetch` keys reduce duplicate fetches.
+- Deprecated/renamed APIs flagged by `nuxi upgrade`; check the warnings and the official migration
+  guide rather than guessing.
+- `@pinia/nuxt` auto-imports stores from `app/stores/` (was `stores/`).
+
+## Vue 3.4 → 3.5 deltas (what Nuxt 4 builds on)
+
+Vue 3.5 is stable and the version Nuxt 4 ships against. Adopt:
+
+- **Reactive Props Destructure stabilized** — `const { count = 0 } = defineProps<{count?: number}>()`
+  stays reactive; the compiler rewrites references to `props.count`. Clean default syntax, no
+  `withDefaults`.
+- **`useTemplateRef('name')`** — typed template DOM refs without a manually-named `ref`.
+- **`useId()`** — SSR-stable unique ids for label/input pairs (no hydration mismatch).
+- **`<Teleport defer>`** — teleport to a target that mounts later in the same render.
+- **`onWatcherCleanup()`** — register watcher teardown without the callback's cleanup arg.
+- **Reactivity refactor** — ~56% lower memory and faster large-array iteration; `shallowRef`/
+  `shallowReactive` remain the lever for very large structures.
+
+From 3.4: **`defineModel()`** is stable — use it instead of the `props` + `emit('update:x')` pair.
+
+## Looking ahead (do not adopt as default)
+
+Vue 3.6 (beta in 2026) previews **Vapor Mode** — a compile-time, virtual-DOM-free render strategy
+opted into per component via `<script setup vapor>`, targeting mid-2026 stable. It is opt-in and
+preview-grade; keep production components on the standard renderer until Vapor is stable and the
+ecosystem (libraries, dev tools) supports it.

package/skills/shared/vue-nuxt/references/nitro-and-rendering.md

@@ -0,0 +1,117 @@
+# Nitro server routes & rendering strategy
+
+Companion to the SKILL "Nitro server routes" and "Rendering strategy" sections. Nitro is Nuxt's
+server engine; everything under `server/` runs there.
+
+## Server route handlers
+
+| File | Maps to |
+|---|---|
+| `server/api/users.get.ts` | `GET /api/users` |
+| `server/api/users.post.ts` | `POST /api/users` |
+| `server/api/users/[id].get.ts` | `GET /api/users/:id` |
+| `server/routes/sitemap.xml.ts` | `GET /sitemap.xml` (non-`/api` route) |
+| `server/middleware/auth.ts` | runs on every request before handlers |
+
+```ts
+// server/api/users.post.ts
+export default defineEventHandler(async (event) => {
+  const body = await readBody<{ email: string }>(event)
+  if (!body?.email?.includes('@')) {
+    throw createError({ statusCode: 422, statusMessage: 'invalid email' })
+  }
+  const config = useRuntimeConfig(event)            // pass event for request-scoped config
+  const created = await db.insert(body, config.dbUrl)
+  setResponseStatus(event, 201)
+  return created
+})
+```
+
+Useful helpers: `getQuery(event)`, `getRouterParam(event, 'id')`, `readBody(event)`,
+`getHeader(event, 'x-...')`, `setResponseHeader`, `setResponseStatus`, `sendRedirect`,
+`getCookie`/`setCookie`, `createError`.
+
+## Server middleware
+
+```ts
+// server/middleware/log.ts
+export default defineEventHandler((event) => {
+  // runs on every request; do not return a body unless you mean to short-circuit
+  console.log(`${event.method} ${getRequestURL(event).pathname}`)
+})
+```
+
+## Runtime config (private vs public)
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  runtimeConfig: {
+    apiSecret: '',                 // server-only; override via NUXT_API_SECRET
+    dbUrl: '',                     // server-only; NUXT_DB_URL
+    public: {
+      apiBase: '/api',             // shipped to the browser; NUXT_PUBLIC_API_BASE
+    },
+  },
+})
+```
+
+Rule: anything under `public` (or any `NUXT_PUBLIC_*` env) is bundled into client JS and readable
+by every visitor. Keep secrets at the top level and read them only in `server/` code via
+`useRuntimeConfig(event)`. Empty-string defaults force the env var to be set in production.
+
+## Route-rule recipes
+
+`routeRules` in `nuxt.config.ts` sets per-route rendering and caching at the Nitro layer.
+
+```ts
+export default defineNuxtConfig({
+  routeRules: {
+    '/':              { prerender: true },                 // SSG at build time
+    '/docs/**':       { prerender: true },
+    '/blog/**':       { swr: 600 },                        // stale-while-revalidate, 10 min
+    '/products/**':   { isr: true },                       // ISR — cache until next deploy/revalidate
+    '/products/[id]': { isr: 3600 },                       // ISR with 1h TTL
+    '/dashboard/**':  { ssr: false },                      // client-only SPA island
+    '/legacy':        { redirect: '/new' },
+    '/feed.xml':      { headers: { 'content-type': 'application/xml' } },
+    '/api/**':        { cors: true, headers: { 'cache-control': 's-maxage=60' } },
+  },
+})
+```
+
+| Rule | Meaning |
+|---|---|
+| `prerender: true` | rendered at build, served as static HTML |
+| `swr: <s>` | cached server render, revalidated in the background after `<s>` seconds |
+| `isr: true \| <s>` | incremental static regeneration (needs a supporting preset, e.g. Vercel) |
+| `ssr: false` | no server render; ship an SPA shell for this route |
+| `redirect` / `headers` / `cors` | edge-level redirect, response headers, CORS |
+
+## Cached event handlers
+
+Cache expensive server work with `defineCachedEventHandler` (or `cachedFunction`):
+
+```ts
+export default defineCachedEventHandler(async (event) => {
+  return await expensiveAggregate()
+}, { maxAge: 60, swr: true, name: 'aggregate' })
+```
+
+Backed by Nitro storage; pick a KV/Redis storage driver for multi-instance deployments so the cache
+is shared.
+
+## Build & preset selection
+
+- `nuxt build` → SSR/hybrid server output in `.output/`.
+- `nuxt generate` → fully prerendered static site (every route must be prerenderable).
+- The **Nitro preset** picks the deploy target. Auto-detected on most platforms; set explicitly via
+  `nitro.preset` or the `NITRO_PRESET` env: `node-server`, `vercel`, `netlify`,
+  `cloudflare-pages`/`cloudflare-module`, `bun`, `static`, and more.
+
+```ts
+export default defineNuxtConfig({ nitro: { preset: 'node-server' } })
+```
+
+Choose the preset here, then defer platform specifics (env, edge config, adapters, domains) to
+`../deployment/SKILL.md`, `../vercel/SKILL.md`, `../netlify/SKILL.md`, `../cloudflare/SKILL.md`.

package/skills/shared/vue-nuxt/references/reactivity.md

@@ -0,0 +1,135 @@
+# Reactivity deep dive (Vue 3.5)
+
+Companion to the SKILL "Composition API & reactivity core" section. Read it when a binding stops
+updating, an async effect races, or you are extracting a non-trivial composable.
+
+## `ref` vs `reactive` — pick `ref`
+
+- `ref` boxes any value behind `.value`; survives destructuring (you carry the box), works for
+  primitives, and reads uniformly. Templates auto-unwrap top-level refs.
+- `reactive` returns a deep Proxy of an object. It cannot hold primitives, breaks on destructure,
+  and a whole-object reassignment (`state = {...}`) detaches every consumer.
+- Rule: default to `ref`; reach for `reactive` only for a grouped object you never destructure and
+  never reassign.
+
+## Reactivity caveats
+
+```ts
+import { reactive, toRefs, toRef, ref } from 'vue'
+
+const state = reactive({ a: 1, b: 2 })
+const { a } = state           // ✗ detached primitive
+const { a: aRef } = toRefs(state)  // ✓ aRef.value linked
+const bRef = toRef(state, 'b')     // ✓ single-key ref
+
+// Reassigning a reactive loses every existing reference:
+let s = reactive({ n: 1 })
+// s = reactive({ n: 2 })     // ✗ old consumers keep the stale proxy
+s.n = 2                        // ✓ mutate in place
+```
+
+A `ref` of an object is deeply reactive by default. For large structures use `shallowRef`
+(reactivity only on `.value` replacement) or `shallowReactive` (only top-level keys) and replace
+the whole value to trigger updates.
+
+## `watch` vs `watchEffect` + cleanup
+
+- `watch(src, cb)` — lazy, gives `(new, old)`, explicit source; pass `{ immediate: true }` to run
+  once eagerly, `{ deep: true }` to track nested mutations of a `ref<object>`, `{ flush: 'post' }`
+  to run after DOM update.
+- `watchEffect(fn)` — runs immediately, auto-tracks whatever it reads, re-runs on any change. No
+  old value.
+- Always cancel stale async work so an out-of-order response can't overwrite a newer one:
+
+```ts
+import { watch, onWatcherCleanup } from 'vue'
+
+watch(query, async (q) => {
+  const ctrl = new AbortController()
+  onWatcherCleanup(() => ctrl.abort())   // 3.5: works without the cb arg
+  const res = await fetch(`/api/search?q=${q}`, { signal: ctrl.signal })
+  results.value = await res.json()
+})
+```
+
+## Effect scope
+
+`effectScope()` groups computed/watch effects so you can dispose them together — useful inside a
+composable that must tear down on demand. Effects created in `setup`/`onMounted` are auto-scoped to
+the component; effects created in a detached context (a singleton, a timer callback) are NOT and
+will leak unless you own a scope.
+
+```ts
+import { effectScope } from 'vue'
+const scope = effectScope()
+scope.run(() => { watch(/* ... */) })
+// later:
+scope.stop()
+```
+
+## Composable patterns
+
+A composable is a function named `useX` that uses Composition API internals and returns refs.
+Rules:
+
+- Call composables synchronously at the top of `setup` (or inside another composable), never inside
+  conditionals/loops — the same lifecycle constraint as React hooks.
+- Return refs (or readonly refs), not unwrapped values, so callers keep reactivity.
+- Accept refs/getters as input and normalize with `toValue()` so the composable works whether the
+  caller passes a raw value, a `ref`, or a getter.
+- No top-level module side effects — that runs once per server process and leaks across requests.
+
+```ts
+// composables/useMouse.ts
+import { ref, onMounted, onUnmounted } from 'vue'
+export function useMouse() {
+  const x = ref(0), y = ref(0)
+  const update = (e: MouseEvent) => { x.value = e.pageX; y.value = e.pageY }
+  onMounted(() => window.addEventListener('mousemove', update))   // browser-only, safe in onMounted
+  onUnmounted(() => window.removeEventListener('mousemove', update))
+  return { x, y }
+}
+```
+
+Composable, not mixin: mixins merge option objects invisibly and collide on names; composables are
+explicit, typed, and tree-shakeable.
+
+## Typed provide / inject
+
+Use an `InjectionKey<T>` so both ends are typed and you avoid string drift.
+
+```ts
+// keys.ts
+import type { InjectionKey, Ref } from 'vue'
+export const ThemeKey: InjectionKey<Ref<'light' | 'dark'>> = Symbol('theme')
+
+// provider
+provide(ThemeKey, theme)
+// consumer
+const theme = inject(ThemeKey)              // Ref<'light'|'dark'> | undefined
+const theme2 = inject(ThemeKey, ref('light'))  // with default
+```
+
+Provide a readonly ref + a mutator function when consumers should not write directly.
+
+## `defineModel` advanced
+
+```vue
+<script setup lang="ts">
+const model = defineModel<string>()                       // v-model
+const count = defineModel<number>('count', { default: 0 })// named: v-model:count
+const [name, modifiers] = defineModel<string>('name', {   // access v-model modifiers
+  set: (v) => modifiers.capitalize ? v.toUpperCase() : v,
+})
+</script>
+```
+
+`defineModel` compiles to the prop + `update:` emit pair; reading/writing `.value` is the
+two-way binding. Multiple named models on one component are fine.
+
+## Render functions / JSX
+
+`<script setup>` covers nearly everything. Drop to `h()` render functions or JSX (`@vitejs/plugin-vue-jsx`)
+only for highly dynamic component shapes a template can't express cleanly — a table that builds
+columns from data, a recursive tree renderer. Prefer templates otherwise: they get better
+compiler optimization (static hoisting, patch flags) and, in 3.6, Vapor compilation.

package/skills/shared/vue-nuxt/scripts/verify.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# verify.sh — Vue 3 + Nuxt 4 project gate.
+#
+# Usage:
+#   bash scripts/verify.sh            # run from the Vue/Nuxt project root
+#
+# What it does (in order): typecheck -> package `lint` script -> Vitest -> build.
+#   - Nuxt repo  (nuxt.config.{ts,js,mjs} present): nuxi typecheck (fallback vue-tsc
+#     --noEmit), lint, vitest run, nuxi build.
+#   - Plain Vue repo (no Nuxt config):              vue-tsc --noEmit, lint, vitest run,
+#     vite build.
+# Each tool is detected; if it is not installed/resolvable, it is SKIPped with a yellow
+# warning (NOT a failure). Exits non-zero only on a real tool failure.
+#
+# Side effects: typecheck / lint / test are read-only. The final build WRITES output
+# (`.nuxt/` + `.output/` for Nuxt, `dist/` for plain Vue). It performs no installs and no
+# network mutations. Safe to re-run. Exits 0 on a clean/empty target (everything skipped).
+#
+# Portability: targets stock macOS bash 3.2. No `mapfile`, no empty-array expansion under
+# `set -u`, graceful degradation when a tool is missing. `set -e` is intentionally NOT used.
+
+set -u
+
+# --- colors (only when stdout is a TTY) -----------------------------------
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+skips=""
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s\n' "${YELLOW}SKIP: $1${RESET}"; skips="${skips}${skips:+ }$2"; return 0; }
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- resolve a package runner from the lockfile ----------------------------
+RUN=""
+if [ -f pnpm-lock.yaml ] && have pnpm; then
+  RUN="pnpm exec"
+elif [ -f yarn.lock ] && have yarn; then
+  RUN="yarn"
+elif [ -f package-lock.json ] && have npm; then
+  RUN="npm exec --"
+elif have npx; then
+  RUN="npx --no-install"
+fi
+
+run_bin() {
+  # run_bin <bin-name> <args...> : true if the bin is resolvable and runs
+  bin="$1"; shift
+  if have "$bin"; then "$bin" "$@"; return $?; fi
+  if [ -x "node_modules/.bin/$bin" ]; then "node_modules/.bin/$bin" "$@"; return $?; fi
+  if [ -n "$RUN" ]; then $RUN "$bin" "$@"; return $?; fi
+  return 127
+}
+
+bin_available() {
+  bin="$1"
+  have "$bin" && return 0
+  [ -x "node_modules/.bin/$bin" ] && return 0
+  return 1
+}
+
+# --- detect Nuxt vs plain Vue ----------------------------------------------
+IS_NUXT=false
+if [ -f nuxt.config.ts ] || [ -f nuxt.config.js ] || [ -f nuxt.config.mjs ]; then
+  IS_NUXT=true
+fi
+
+# Does package.json declare a "lint" script? (bash-3.2 safe, no jq/node)
+has_lint_script() {
+  [ -f package.json ] || return 1
+  grep -q '"lint"[[:space:]]*:' package.json 2>/dev/null
+}
+
+# --- 1. typecheck ----------------------------------------------------------
+if [ "$IS_NUXT" = true ] && bin_available nuxi; then
+  printf '%s\n' "Running nuxi typecheck..."
+  if run_bin nuxi typecheck; then ok "nuxi typecheck"; else fail "nuxi typecheck"; fi
+elif bin_available vue-tsc && [ -f tsconfig.json ]; then
+  printf '%s\n' "Running vue-tsc --noEmit..."
+  if run_bin vue-tsc --noEmit; then ok "vue-tsc --noEmit"; else fail "vue-tsc --noEmit"; fi
+else
+  warn "nuxi/vue-tsc (or tsconfig.json) not resolvable — skipping type check" "typecheck"
+fi
+
+# --- 2. lint (package script: ESLint / oxlint) -----------------------------
+if has_lint_script && [ -n "$RUN" ]; then
+  printf '%s\n' "Running package lint script..."
+  case "$RUN" in
+    "pnpm exec") LINT_CMD="pnpm run lint" ;;
+    "yarn")      LINT_CMD="yarn lint" ;;
+    "npm exec --") LINT_CMD="npm run lint" ;;
+    *)           LINT_CMD="npm run lint" ;;
+  esac
+  if $LINT_CMD; then ok "lint"; else fail "lint"; fi
+else
+  warn "no package lint script (or no package runner) — skipping lint" "lint"
+fi
+
+# --- 3. Vitest -------------------------------------------------------------
+# Treat as having unit tests when a vitest config exists OR *.test.* / *.spec.*
+# files exist (Vue/Nuxt commonly use either for unit tests).
+has_tests=false
+if ls vitest.config.* vitest.workspace.* >/dev/null 2>&1; then
+  has_tests=true
+elif find . \( -name node_modules -o -name .nuxt -o -name .output -o -name dist \) -prune -o \
+       \( -name '*.test.*' -o -name '*.spec.*' \) -print 2>/dev/null | grep -q .; then
+  has_tests=true
+fi
+if bin_available vitest && [ "$has_tests" = true ]; then
+  printf '%s\n' "Running vitest run..."
+  if run_bin vitest run; then ok "vitest"; else fail "vitest"; fi
+else
+  warn "vitest or tests (vitest.config.* / *.test.* / *.spec.*) not present — skipping unit tests" "vitest"
+fi
+
+# --- 4. build (slow; WRITES output; run last) ------------------------------
+if [ "$IS_NUXT" = true ]; then
+  if bin_available nuxi; then
+    printf '%s\n' "Running nuxi build... (writes .nuxt/ and .output/)"
+    if run_bin nuxi build; then ok "nuxi build"; else fail "nuxi build"; fi
+  else
+    warn "nuxi not resolvable — skipping build" "build"
+  fi
+else
+  if bin_available vite; then
+    printf '%s\n' "Running vite build... (writes dist/)"
+    if run_bin vite build; then ok "vite build"; else fail "vite build"; fi
+  else
+    warn "vite not resolvable — skipping build" "build"
+  fi
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\n'
+if [ -n "$skips" ]; then
+  printf '%s\n' "${YELLOW}skipped: ${skips}${RESET}"
+fi
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}verify.sh: $failures check(s) failed${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}verify.sh: all runnable checks passed${RESET}"
+exit 0