vstruct-cli

CLI que genera proyectos Vue 3 con estructura 100% predecible. Cada archivo tiene UN lugar fijo. Cero ambigüedad. Listo para IA.

Que hace

vstruct-cli crea proyectos Vue 3 con una estructura canonica que elimina decisiones arbitrarias. Cuando abris un proyecto hecho con vstruct, sabes exactamente donde esta cada cosa sin preguntar.

Incluye de fábrica:

• Vue 3 + Vite + TypeScript + Pinia + Vue Router
• Tailwind CSS v4 (configurado y funcionando)
• CLAUDE.md — instrucciones para Claude Code
• AGENTS.md — instrucciones para OpenCode / Cursor
• AIREF.md — referencia rapida para cualquier IA
• vstruct.json — reglas estructurales del proyecto

Instalacion

No se instala. Se usa directo:

npx vstruct-cli new mi-proyecto
cd mi-proyecto
npm install
npm run dev

Estructura generada

mi-proyecto/
├── CLAUDE.md          ← Claude Code lee esto automaticamente
├── AGENTS.md          ← OpenCode / Cursor leen esto
├── AIREF.md           ← Referencia rapida para IAs
├── vstruct.json       ← Reglas estructurales (naming, capas, limites)
├── package.json       ← Tailwind v4 + Vue 3 + TS + Pinia + Router
├── vite.config.ts     ← Tailwind plugin + alias @/
├── tsconfig.json      ← strict + isolatedModules + noEmit
├── index.html
└── src/
    ├── main.ts
    ├── App.vue
    ├── styles/main.css        ← @import tailwindcss + @layer base
    ├── router/index.ts        ← Vue Router configurado
    ├── layouts/DefaultLayout.vue
    ├── pages/index.vue
    ├── components/
    │   ├── ui/                ← Botones, inputs, cards base
    │   └── features/          ← Componentes de negocio
    ├── stores/                ← Estado (Pinia setup syntax)
    ├── services/              ← Llamadas API (fetch puro)
    ├── composables/           ← Logica reutilizable (useXxx)
    └── types/index.ts         ← Tipos TypeScript compartidos

Tabla canonica — donde va cada cosa

| Tipo | Ubicacion | Naming | Ejemplo | |------|-----------|--------|---------| | Componente UI | src/components/ui/ | PascalCase.vue | Button.vue | | Componente Feature | src/components/features/ | PascalCase.vue | UserCard.vue | | Pagina | 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 | — |

Generar archivos

npx vstruct-cli g c UserCard          # componente feature
npx vstruct-cli g p user-profile      # pagina
nux vstruct-cli g s cart              # store
npx vstruct-cli g sv Product          # service
npx vstruct-cli g co useFetch         # composable
npx vstruct-cli g l Admin             # layout

Validar estructura

npx vstruct-cli analyze

Detecta:

• Naming incorrecto (PascalCase donde va kebab-case, etc.)
• Archivos fuera de ubicacion canonica
• fetch() directo en componentes (debe ir en services/)
• <a href> en vez de <router-link>
• <script> sin lang="ts"
• <style> sin scoped
• Stores que importan router (dependencia circular)
• Services que importan stores (flujo invertido)

Reglas inmutables

Estas reglas se aplican en TODOS los proyectos vstruct. No son sugerencias.

| # | Regla | Por que | |---|-------|---------| | 1 | Componentes en components/, NUNCA en pages/ ni layouts/ | Separacion de concerns | | 2 | NUNCA fetch() directo en componentes → crear services/X.service.ts | Testabilidad, caching | | 3 | NUNCA <a href> para rutas → <router-link> o router.push() | Recarga la SPA | | 4 | NUNCA <script> sin lang="ts" | TypeScript obligatorio | | 5 | NUNCA <style> sin scoped en componentes | Contamina otros componentes | | 6 | Store NO importa router | Dependencia circular | | 7 | Service NO importa stores | Services son puros HTTP | | 8 | Tipos en types/index.ts, no duplicados | Fuente unica de verdad |

Flujo de datos correcto

Pages → Stores → Services → fetch()

• Pages importan stores y componentes
• Stores importan services y tipos
• Services solo importan tipos
• Componentes solo reciben props y emiten eventos

Anti-patrones que analyze detecta

❌ fetch() en .vue            → crear X.service.ts
❌ <a href="/ruta">           → <router-link to="/ruta">
❌ import { useRouter } en store → componente hace router.push()
❌ interface User en 3 archivos  → types/index.ts
❌ <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

AI-ready

Los proyectos generados incluyen archivos que las IAs leen automaticamente:

• CLAUDE.md — Claude Code lo lee al abrir el proyecto
• AGENTS.md — OpenCode, Cursor, Windsurf lo usan
• AIREF.md — Referencia compacta para inyeccion de contexto
• vstruct.json — Reglas estructurales programaticas

Esto significa que cualquier IA que trabaje en el proyecto sabe exactamente donde va cada archivo sin que se lo expliques.

Stack incluido

| Tecnologia | Version | Rol | |------------|---------|-----| | Vue | ^3.4 | Framework UI | | Vite | ^5.4 | Bundler | | TypeScript | ^5.4 | Tipos | | Pinia | ^2.1 | Estado global | | Vue Router | ^4.3 | Navegacion SPA | | Tailwind CSS | ^4.1 | Estilos utility-first |

Comandos completos

npx vstruct-cli new <nombre>              # Crear proyecto
npx vstruct-cli g c <PascalCase>          # Componente feature
npx vstruct-cli g p <kebab-case>          # Pagina
npx vstruct-cli g s <camelCase>           # Store Pinia
npx vstruct-cli g sv <PascalCase>         # Service API
npx vstruct-cli g co <useXxx>            # Composable
npx vstruct-cli g l <PascalCase>          # Layout
npx vstruct-cli analyze                   # Validar estructura
npx vstruct-cli init [--force]            # Crear vstruct.json
npx vstruct-cli manifest                  # Mostrar vstruct.json

Licencia

MIT