vstruct-cli 0.1.0

package/AIREF.md

@@ -0,0 +1,479 @@
+# vstruct — AIREF (referencia para IAs y devs)
+
+Estructura Vue 3 predecible. Todo tiene UN lugar fijo. Cero ambigüedad.
+La IA y el dev saben exactamente dónde va cada cosa SIN PENSAR.
+
+---
+
+## STACK OBLIGATORIO
+
+| Dep | Versión | Por qué |
+|-----|---------|---------|
+| `vue` | `^3.4` | `<script setup>` + Composition API tipada |
+| `vite` | `^5.4` | Dev server + build |
+| `pinia` | `^2.1` | Stores con setup syntax (NO options API) |
+| `vue-router` | `^4.3` | Router con `createWebHistory` |
+| `typescript` | `^5.0` | `strict: true` obligatorio |
+
+---
+
+## TABLA CANÓNICA — dónde va cada cosa
+
+```
+TIPOS DE ARCHIVO:
+
+Componente UI       → src/components/ui/<PascalCase>.vue
+                      Ej: Button.vue, InputField.vue, DataTable.vue
+                      Son componentes genéricos, reusables, sin lógica de negocio.
+
+Componente Feature  → src/components/features/<PascalCase>.vue
+                      Ej: UserCard.vue, ProductForm.vue, OrderTimeline.vue
+                      Son componentes de dominio, acoplados a la lógica del negocio.
+
+Página              → src/pages/<kebab-case>.vue
+                      Ej: user-list.vue, product-detail.vue, order-create.vue
+                      Una página por ruta. Representan una vista completa.
+
+Layout              → src/layouts/<PascalCase>.vue
+                      Ej: DefaultLayout.vue, AdminLayout.vue, AuthLayout.vue
+                      Contienen <slot /> para el contenido de la página.
+
+Store (Pinia)       → src/stores/<camelCase>.store.ts
+                      Ej: auth.store.ts, cart.store.ts, toast.store.ts
+                      Estado global. Siempre setup syntax (() => { ... }).
+
+Service (API)       → src/services/<PascalCase>.service.ts
+                      Ej: ProductService.ts, AuthService.ts, OrderService.ts
+                      Solo llamadas HTTP. NUNCA estado global ni stores.
+
+Composable          → src/composables/use<Xxx>.ts
+                      Ej: useFetch.ts, usePagination.ts, useFormValidation.ts
+                      Lógica reutilizable. SIEMPRE empieza con "use".
+
+Tipos               → src/types/index.ts
+                      Interfaces, tipos y DTOs compartidos. NO duplicar en archivos.
+
+Router              → src/router/index.ts
+                      Configuración de rutas. Un solo archivo.
+
+Estilos             → src/styles/main.css
+                      Estilos globales. Componentes usan <style scoped>.
+```
+
+---
+
+## REGLAS INMUTABLES — la IA NO debe romperlas
+
+| # | Regla | Por qué |
+|---|-------|---------|
+| 1 | Componentes en `components/`, NO en `pages/` ni `layouts/` | Separación de concerns rota = código inmantenible |
+| 2 | Stores en `stores/`, NO en `components/` ni `services/` | Estado global mezclado con UI = bugs de reactividad |
+| 3 | NUNCA `fetch()` directo en componentes | Rompe testabilidad, caching, y separación de capas |
+| 4 | NUNCA `<a href="/ruta">` para navegación interna | Recarga la página. Usar `<router-link>` o `router.push()` |
+| 5 | NUNCA `<script>` sin `lang="ts"` | TypeScript es obligatorio. Sin `lang="ts"` no hay type safety |
+| 6 | NUNCA estilos sin `<style scoped>` en componentes | Contamina otros componentes. Si necesitás global → `main.css` |
+| 7 | Store NO llama a `router` | Circular dependency. El componente decide navegar, no el store |
+| 8 | Service NO importa stores | Los services son puros HTTP. El store orquesta service + estado |
+| 9 | Tipos compartidos en `types/index.ts` | Evita duplicación de interfaces entre archivos |
+| 10 | NUNCA `any` sin justificación | `any` desactiva TypeScript. Usar `unknown` + type guard |
+
+---
+
+## BUENAS vs MALAS PRÁCTICAS — ejemplos concretos
+
+### Componentes
+
+| ✅ BIEN | ❌ MAL (causa errores) |
+|---------|------------------------|
+| `<router-link to="/users">` | `<a href="/users">` — recarga la SPA |
+| `<script setup lang="ts">` | `<script>` sin lang="ts" — sin type checking |
+| `<style scoped>` | `<style>` sin scoped — contamina otros componentes |
+| `defineProps<{ name: string }>()` | `defineProps({ name: String })` — sin tipos TS |
+| `defineEmits<{ select: [id: string] }>()` | `emit('select', id)` sin declarar emits |
+| `const visible = ref(false)` | `let visible = false` — no reactivo |
+| `v-if="item"` | `v-if="item != null"` component |
+| `<slot />` en layout | hardcodear contenido en layout |
+
+### Stores (Pinia)
+
+| ✅ BIEN | ❌ MAL (causa errores) |
+|---------|------------------------|
+| `defineStore('auth', () => { ... })` setup syntax | `defineStore('auth', { state: ... })` options API |
+| `const user = ref<User \| null>(null)` | `const user = ref()` sin tipo |
+| Actions async con try/catch | Actions sin manejo de error |
+| Store importa Service | Store hace `fetch()` directo |
+| Store retorna `{ state, getters, actions }` | Store expone todo sin estructura |
+| `return { user, login, logout }` | Store no retorna lo que el componente necesita |
+
+### Services (API)
+
+| ✅ BIEN | ❌ MAL (causa errores) |
+|---------|------------------------|
+| `const BASE_URL = '/api/products'` constante | URL hardcodeada en cada método |
+| `if (!res.ok) throw new Error(...)` | `return res.json()` sin checkear errores |
+| `async getAll(): Promise<Product[]>` | `async getAll()` sin tipo de retorno |
+| Service exporta objeto con métodos | Service es una clase con `this` |
+| Service usa `fetch()` (único lugar permitido) | Service importa pinia o vue-router |
+
+### Composables
+
+| ✅ BIEN | ❌ MAL (causa errores) |
+|---------|------------------------|
+| `useFetch`, `useAuth`, `usePagination` | `fetchData`, `auth`, `paginate` — sin prefijo "use" |
+| Retorna `{ data, loading, error, execute }` | Retorna solo `data` sin estado de carga |
+| Tipado genérico: `useFetch<T>(...)` | `useFetch()` sin genérico — `data` es `any` |
+| Maneja loading + error + success | Solo maneja success |
+| `error.value = e.message` en catch | Error silencioso — no se asigna nunca |
+
+### Routing
+
+| ✅ BIEN | ❌ MAL (causa errores) |
+|---------|------------------------|
+| `router.push({ name: 'user', params: { id } })` | `router.push('/user/' + id)` — string concatenation |
+| `createWebHistory()` | `createWebHashHistory()` — URLs con # |
+| Rutas con `name` único | Rutas sin `name` |
+| `<router-link :to="{ name: 'home' }">` | `<a href="/">` — full page reload |
+| Lazy load: `() => import('@/pages/X.vue')` | Import directo — bundle enorme |
+
+### Estructura de archivos
+
+| ✅ BIEN | ❌ MAL (causa errores) |
+|---------|------------------------|
+| `stores/auth.store.ts` | `store/auth.ts` sin sufijo `.store` |
+| `services/Product.service.ts` | `services/product.ts` sin sufijo `.service` |
+| `composables/useFetch.ts` | `composables/fetch.ts` sin prefijo `use` |
+| `components/ui/Button.vue` | `components/ui/button.vue` — PascalCase para componentes |
+| `pages/user-list.vue` | `pages/UserList.vue` — kebab-case para páginas |
+| `types/index.ts` centralizado | Tipos duplicados en cada archivo |
+
+---
+
+## PATRONES CANÓNICOS — copy-paste
+
+### Componente Vue (.vue)
+
+```vue
+<template>
+  <div class="user-card">
+    <h3>{{ props.name }}</h3>
+    <p v-if="props.email">{{ props.email }}</p>
+    <button @click="emit('select', props.id)">Seleccionar</button>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  id: string
+  name: string
+  email?: string
+}
+
+interface Emits {
+  (e: 'select', id: string): void
+}
+
+const props = defineProps<Props>()
+const emit = defineEmits<Emits>()
+</script>
+
+<style scoped>
+.user-card {
+  padding: 1rem;
+  border: 1px solid #e5e5e5;
+  border-radius: 8px;
+}
+</style>
+```
+
+### Página con datos y loading
+
+```vue
+<template>
+  <div class="page-product-detail">
+    <div v-if="loading" class="loading">Cargando...</div>
+    <div v-else-if="error" class="error">{{ error }}</div>
+    <div v-else-if="product">
+      <h1>{{ product.name }}</h1>
+      <p>{{ product.description }}</p>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+import { useRoute } from 'vue-router'
+import { ProductService } from '@/services/Product.service'
+import type { Product } from '@/types'
+
+const route = useRoute()
+const product = ref<Product | null>(null)
+const loading = ref(false)
+const error = ref<string | null>(null)
+
+onMounted(async () => {
+  loading.value = true
+  error.value = null
+  try {
+    product.value = await ProductService.getById(route.params.id as string)
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Error al cargar'
+  } finally {
+    loading.value = false
+  }
+})
+</script>
+```
+
+### Store (Pinia) con setup syntax
+
+```typescript
+// src/stores/auth.store.ts
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import { AuthService } from '@/services/Auth.service'
+import type { User } from '@/types'
+
+export const useAuthStore = defineStore('auth', () => {
+  const user = ref<User | null>(null)
+  const token = ref<string | null>(null)
+  const loading = ref(false)
+
+  const isAuthenticated = computed(() => !!token.value)
+
+  async function login(email: string, password: string) {
+    loading.value = true
+    try {
+      const data = await AuthService.login({ email, password })
+      token.value = data.token
+      user.value = data.user
+    } finally {
+      loading.value = false
+    }
+  }
+
+  function logout() {
+    token.value = null
+    user.value = null
+  }
+
+  return { user, token, loading, isAuthenticated, login, logout }
+})
+```
+
+### Service (API) — único lugar donde se usa fetch()
+
+```typescript
+// src/services/Product.service.ts
+import type { Product, CreateProductDTO } from '@/types'
+
+const BASE_URL = '/api/products'
+
+export const ProductService = {
+  async getAll(): Promise<Product[]> {
+    const res = await fetch(BASE_URL)
+    if (!res.ok) throw new Error(`GET ${BASE_URL} failed: ${res.status}`)
+    return res.json()
+  },
+
+  async getById(id: string): Promise<Product> {
+    const res = await fetch(`${BASE_URL}/${id}`)
+    if (!res.ok) throw new Error(`Product ${id} not found`)
+    return res.json()
+  },
+
+  async create(data: CreateProductDTO): Promise<Product> {
+    const res = await fetch(BASE_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    })
+    if (!res.ok) throw new Error(`Create failed: ${res.status}`)
+    return res.json()
+  },
+
+  async update(id: string, data: Partial<CreateProductDTO>): Promise<Product> {
+    const res = await fetch(`${BASE_URL}/${id}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    })
+    if (!res.ok) throw new Error(`Update ${id} failed: ${res.status}`)
+    return res.json()
+  },
+
+  async delete(id: string): Promise<void> {
+    const res = await fetch(`${BASE_URL}/${id}`, { method: 'DELETE' })
+    if (!res.ok) throw new Error(`Delete ${id} failed: ${res.status}`)
+  },
+}
+```
+
+### Composable
+
+```typescript
+// src/composables/useFetch.ts
+import { ref, type Ref } from 'vue'
+
+interface UseFetchReturn<T> {
+  data: Ref<T | null>
+  loading: Ref<boolean>
+  error: Ref<string | null>
+  execute: () => Promise<void>
+}
+
+export function useFetch<T>(loader: () => Promise<T>): UseFetchReturn<T> {
+  const data = ref<T | null>(null) as Ref<T | null>
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+
+  async function execute() {
+    loading.value = true
+    error.value = null
+    try {
+      data.value = await loader()
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Error desconocido'
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { data, loading, error, execute }
+}
+```
+
+### Layout con slot
+
+```vue
+<template>
+  <div class="layout-admin">
+    <aside class="sidebar">
+      <nav>
+        <router-link to="/dashboard">Dashboard</router-link>
+        <router-link to="/users">Usuarios</router-link>
+      </nav>
+    </aside>
+    <main class="content">
+      <slot />
+    </main>
+  </div>
+</template>
+
+<script setup lang="ts">
+// AdminLayout — no necesita lógica, solo estructura
+</script>
+
+<style scoped>
+.layout-admin { display: flex; min-height: 100dvh; }
+.sidebar { width: 250px; border-right: 1px solid #e5e5e5; padding: 1rem; }
+.content { flex: 1; padding: 2rem; }
+</style>
+```
+
+---
+
+## ANTIPATRONES QUE CAUSAN BUGS — NUNCA hacer esto
+
+```
+❌ fetch('/api/users') dentro de <script setup> de un .vue
+   → Crear Product.service.ts y llamar ProductService.getAll()
+
+❌ import { useRouter } from 'vue-router' dentro de un store
+   → El componente hace router.push() DESPUÉS de llamar al store
+
+❌ <a href="/dashboard">Ir</a>
+   → <router-link to="/dashboard">Ir</router-link>
+
+❌ const state = reactive({ count: 0 })  sin tipo
+   → const count = ref<number>(0)
+
+❌ <style> sin scoped en un .vue que no es layout
+   → <style scoped> SIEMPRE
+
+❌ interface User { ... } definida en 3 archivos distintos
+   → Ponerla UNA vez en types/index.ts y exportarla
+
+❌ store.auth.store.ts  (PascalCase)
+   → auth.store.ts  (camelCase.store.ts)
+
+❌ services/product.ts  (sin sufijo .service)
+   → Product.service.ts
+
+❌ composables/fetchData.ts  (sin prefijo use)
+   → useFetchData.ts
+
+❌ pages/UserList.vue  (PascalCase para página)
+   → user-list.vue  (kebab-case para páginas)
+
+❌ router.push('/user/' + id)  (string concatenation)
+   → router.push({ name: 'user-detail', params: { id } })
+
+❌ <script> sin lang="ts"
+   → <script setup lang="ts">
+```
+
+---
+
+## WORKFLOW OBLIGATORIO
+
+```
+1. LEER vstruct.json        ← fuente única de verdad
+2. USAR la tabla canónica   ← cada tipo de archivo tiene UN solo lugar
+3. USAR `vstruct g`         ← genera archivos en ubicación correcta automáticamente
+4. VALIDAR con `vstruct analyze` ← 0 errores = listo
+```
+
+---
+
+## CLI
+
+```bash
+vstruct new <name>           # Crear proyecto nuevo
+vstruct g c <PascalCase>     # Generar componente feature
+vstruct g p <kebab-case>     # Generar página
+vstruct g s <camelCase>      # Generar store (Pinia)
+vstruct g sv <PascalCase>    # Generar service (API)
+vstruct g co <useXxx>       # Generar composable
+vstruct g l <PascalCase>     # Generar layout
+vstruct analyze              # Validar estructura (debe pasar con 0 errores)
+vstruct init [--force]       # Crear vstruct.json en proyecto existente
+vstruct manifest             # Mostrar vstruct.json actual
+```
+
+---
+
+## vstruct.json — el manifiesto
+
+```json
+{
+  "version": "1",
+  "project": { "name": "mi-app" },
+  "layers": {
+    "ui":         "src/components/ui/*.vue",
+    "features":   "src/components/features/*.vue",
+    "pages":      "src/pages/**/*.vue",
+    "layouts":    "src/layouts/*.vue",
+    "stores":     "src/stores/*.store.ts",
+    "services":   "src/services/*.service.ts",
+    "composables":"src/composables/*.ts"
+  },
+  "conventions": {
+    "naming": {
+      "components":  "PascalCase.vue",
+      "pages":       "kebab-case.vue",
+      "stores":      "camelCase.store.ts",
+      "services":    "PascalCase.service.ts",
+      "composables": "useXxx.ts",
+      "layouts":     "PascalCase.vue"
+    }
+  },
+  "forbidden": [],
+  "required": {
+    "scriptLangTs": true,
+    "styleScoped": true,
+    "errorHandling": true
+  }
+}
+```
+
+**LA IA DEBE leer `vstruct.json` ANTES de generar código. Las reglas ahí son obligatorias.**

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "vstruct-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI que genera proyectos Vue 3 con estructura 100% predecible — cada archivo tiene un lugar fijo, sin pensar.",
+  "keywords": [
+    "vue",
+    "cli",
+    "scaffold",
+    "predictable",
+    "structure",
+    "ai-friendly",
+    "frontend"
+  ],
+  "author": "phantom",
+  "license": "MIT",
+  "bin": {
+    "vstruct": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "AIREF.md",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node src/cli.js new test-app --dry-run"
+  }
+}

package/skills/SKILL.md

@@ -0,0 +1,69 @@
+# vstruct — Vue Predictable Structure
+
+Skill para Claude/OpenCode que garantiza que la IA NUNCA improvise ubicaciones.
+Cada tipo de archivo tiene UN solo lugar. Cero ambigüedad.
+
+## Cuándo cargar
+
+Cargar cuando el proyecto tiene `vstruct.json` en la raíz, o cuando se pide
+crear componentes, pages, stores, services o composables en un proyecto vstruct.
+
+## Tabla canónica
+
+| Tipo | Ubicación | Naming | Ejemplo |
+|------|-----------|--------|---------|
+| Componente UI | `src/components/ui/` | `PascalCase.vue` | `Button.vue` |
+| Componente Feature | `src/components/features/` | `PascalCase.vue` | `UserCard.vue` |
+| Página | `src/pages/` | `kebab-case.vue` | `user-list.vue` |
+| Layout | `src/layouts/` | `PascalCase.vue` | `AdminLayout.vue` |
+| Store (Pinia) | `src/stores/` | `camelCase.store.ts` | `cart.store.ts` |
+| Service (API) | `src/services/` | `PascalCase.service.ts` | `Product.service.ts` |
+| Composable | `src/composables/` | `useXxx.ts` | `useFetch.ts` |
+| Tipos | `src/types/` | `index.ts` | — |
+
+## Protocolo obligatorio
+
+1. LEER `vstruct.json` — fuente única de verdad
+2. UBICAR según la tabla — cada cosa tiene UN lugar
+3. RESPETAR naming — PascalCase para componentes, kebab-case para páginas, etc.
+4. USAR el CLI: `npx vstruct g <tipo> <nombre>` cuando sea posible
+5. VALIDAR: `npx vstruct analyze` debe dar 0 errores
+
+## Reglas inmutables
+
+1. NUNCA inventar ubicaciones — usar la tabla
+2. NUNCA `fetch()` directo en componentes → crear `services/X.service.ts`
+3. NUNCA `<a href>` para rutas → `<router-link>` o `router.push()`
+4. NUNCA `<script>` sin `lang="ts"`
+5. NUNCA `<style>` sin `scoped` en componentes
+6. Store NO importa `useRouter`
+7. Service NO importa stores
+
+## Anti-patrones
+
+```
+❌ fetch() en .vue           → services/X.service.ts
+❌ <a href="/ruta">         → <router-link to="/ruta">
+❌ useRouter en store        → componente hace router.push()
+❌ <style> sin scoped        → <style scoped>
+❌ store/auth.ts             → stores/auth.store.ts
+❌ services/product.ts       → services/Product.service.ts
+❌ pages/UserList.vue        → pages/user-list.vue
+❌ composables/fetch.ts      → composables/useFetch.ts
+```
+
+## CLI rápida
+
+```bash
+vstruct g c UserCard    # componente
+vstruct g p user-list   # página
+vstruct g s cart        # store
+vstruct g sv Product    # service
+vstruct g co useFetch   # composable
+vstruct g l Admin       # layout
+vstruct analyze         # validar
+```
+
+## Más detalle
+
+Leer `AIREF.md` en la raíz del proyecto para patrones canónicos completos.