vstruct-cli 0.1.0

package/src/commands/new.js

@@ -0,0 +1,188 @@
+// ---------------------------------------------------------------------------
+// vstruct new — scaffold completo de proyecto Vue 3 predecible
+// ---------------------------------------------------------------------------
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import {
+  VSTRUCT_MANIFEST,
+  PACKAGE_JSON,
+  VITE_CONFIG,
+  TSCONFIG,
+  INDEX_HTML,
+  MAIN_TS,
+  APP_VUE,
+  MAIN_CSS,
+  ROUTER_INDEX,
+  GITIGNORE,
+  AGENTS_MD,
+  CLAUDE_MD,
+  README_MD,
+  AIREF_MD,
+} from '../templates/index.js'
+
+export function newProject(projectName, options = {}) {
+  const cwd = options.cwd ?? process.cwd()
+  const projectDir = path.join(cwd, projectName)
+  const dryRun = options.dryRun ?? false
+
+  const files = [
+    // Root config files
+    { rel: 'vstruct.json',        content: VSTRUCT_MANIFEST(projectName) },
+    { rel: 'env.d.ts',             content: `/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, any>
+  export default component
+}
+` },
+    { rel: 'package.json',         content: PACKAGE_JSON(projectName) },
+    { rel: 'vite.config.ts',       content: VITE_CONFIG },
+    { rel: 'tsconfig.json',       content: TSCONFIG },
+    { rel: 'index.html',           content: INDEX_HTML(projectName) },
+    { rel: '.gitignore',           content: GITIGNORE },
+    { rel: 'AGENTS.md',            content: AGENTS_MD(projectName) },
+    { rel: 'CLAUDE.md',            content: CLAUDE_MD(projectName) },
+    { rel: 'AIREF.md',             content: AIREF_MD(projectName) },
+    { rel: 'README.md',            content: README_MD(projectName) },
+
+    // src/
+    { rel: 'src/main.ts',          content: MAIN_TS },
+    { rel: 'src/App.vue',          content: APP_VUE },
+
+    // styles
+    { rel: 'src/styles/main.css',  content: MAIN_CSS },
+
+    // router
+    { rel: 'src/router/index.ts',  content: ROUTER_INDEX },
+
+    // pages — starter pages
+    { rel: 'src/pages/index.vue',  content: `<template>
+  <div class="page-home">
+    <h1>Bienvenido a ${projectName}</h1>
+    <p>Editá <code>src/pages/index.vue</code> para empezar.</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+// Home page
+</script>
+` },
+
+    // layouts — default layout
+    { rel: 'src/layouts/DefaultLayout.vue', content: `<template>
+  <div class="layout-default">
+    <header class="layout-header">
+      <nav>
+        <router-link to="/">${projectName}</router-link>
+      </nav>
+    </header>
+    <main class="layout-main">
+      <slot />
+    </main>
+  </div>
+</template>
+
+<script setup lang="ts">
+// DefaultLayout
+</script>
+
+<style scoped>
+.layout-default {
+  min-height: 100dvh;
+  display: flex;
+  flex-direction: column;
+}
+.layout-header {
+  padding: 1rem 2rem;
+  border-bottom: 1px solid #e5e5e5;
+}
+.layout-header a {
+  text-decoration: none;
+  font-weight: 600;
+  color: #1a1a1a;
+}
+.layout-main {
+  flex: 1;
+  padding: 2rem;
+}
+</style>
+` },
+
+    // components — starter
+    { rel: 'src/components/features/.gitkeep',  content: '' },
+    { rel: 'src/components/ui/.gitkeep',         content: '' },
+
+    // stores — starter
+    { rel: 'src/stores/app.store.ts', content: `import { defineStore } from 'pinia'
+import { ref } from 'vue'
+
+export const useAppStore = defineStore('app', () => {
+  const ready = ref(false)
+
+  function init() {
+    ready.value = true
+  }
+
+  return { ready, init }
+})
+` },
+
+    // services — starter
+    { rel: 'src/services/.gitkeep', content: '' },
+
+    // composables — starter
+    { rel: 'src/composables/.gitkeep', content: '' },
+
+    // types
+    { rel: 'src/types/index.ts', content: `// Tipos compartidos del proyecto
+
+export interface User {
+  id: string
+  email: string
+  nombre: string
+  rol?: string
+}
+
+export interface ApiEnvelope<T> {
+  success: boolean
+  data: T
+  message?: string
+}
+` },
+
+    // shared
+    { rel: 'src/shared/.gitkeep', content: '' },
+
+    // public
+    { rel: 'public/.gitkeep', content: '' },
+  ]
+
+  if (!dryRun) {
+    if (fs.existsSync(projectDir)) {
+      throw new NewProjectError(`El directorio "${projectDir}" ya existe.`)
+    }
+
+    for (const f of files) {
+      const fullPath = path.join(projectDir, f.rel)
+      const dir = path.dirname(fullPath)
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true })
+      }
+      fs.writeFileSync(fullPath, f.content, 'utf-8')
+    }
+  }
+
+  return {
+    projectDir,
+    files: files.map((f) => ({ path: path.join(projectDir, f.rel), content: f.content })),
+  }
+}
+
+export class NewProjectError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'NewProjectError'
+  }
+}

package/src/templates/index.js

@@ -0,0 +1,521 @@
+// ---------------------------------------------------------------------------
+// vstruct Templates — archivos generados por `vstruct new` y `vstruct g`
+// ---------------------------------------------------------------------------
+
+// ===========================================================================
+// HELPERS
+// ===========================================================================
+
+function capitalize(str) {
+  if (!str) return str
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+function toPascalCase(str) {
+  return str.split(/[-_\s]+/).map(capitalize).join('')
+}
+
+function pascalToKebab(str) {
+  return str
+    .replace(/([A-Z])/g, (c, i) => (i === 0 ? c.toLowerCase() : '-' + c.toLowerCase()))
+    .replace(/^-/, '')
+}
+
+// ===========================================================================
+// GENERATE TEMPLATES
+// ===========================================================================
+
+export function componentTemplate(name) {
+  const cssClass = pascalToKebab(name)
+  return `<template>
+  <div class="${cssClass}">
+    {{ msg }}
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+interface Props {
+  // props here
+}
+
+const props = defineProps<Props>()
+const emit = defineEmits<{
+  // events here
+}>()
+
+const msg = ref('${name}')
+</script>
+
+<style scoped>
+.${cssClass} {
+  /* styles */
+}
+</style>
+`
+}
+
+export function pageTemplate(name) {
+  const componentName = toPascalCase(name) + 'Page'
+  return `<template>
+  <div class="page-${name}">
+    <h1>${componentName}</h1>
+  </div>
+</template>
+
+<script setup lang="ts">
+// ${componentName} — page component
+</script>
+`
+}
+
+export function storeTemplate(name) {
+  const storeName = 'use' + capitalize(name) + 'Store'
+  return `import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const ${storeName} = defineStore('${name}', () => {
+  // state
+  const loading = ref(false)
+
+  // getters
+  const isLoading = computed(() => loading.value)
+
+  // actions
+  function init() {
+    loading.value = true
+    // ...
+    loading.value = false
+  }
+
+  return { loading, isLoading, init }
+})
+`
+}
+
+export function serviceTemplate(name) {
+  const serviceName = capitalize(name) + 'Service'
+  const urlBase = pascalToKebab(name) + 's'
+  return `const BASE_URL = '/api/${urlBase}'
+
+export const ${serviceName} = {
+  async getAll() {
+    const res = await fetch(BASE_URL)
+    if (!res.ok) throw new Error('Failed to fetch')
+    return res.json()
+  },
+
+  async getById(id: string) {
+    const res = await fetch(\`\${BASE_URL}/\${id}\`)
+    if (!res.ok) throw new Error('Failed to fetch')
+    return res.json()
+  },
+
+  async create(data: unknown) {
+    const res = await fetch(BASE_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    })
+    if (!res.ok) throw new Error('Failed to create')
+    return res.json()
+  },
+}
+`
+}
+
+export function composableTemplate(name) {
+  const fnName = name.startsWith('use') ? name : 'use' + capitalize(name)
+  return `import { ref } from 'vue'
+
+export function ${fnName}() {
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+
+  function reset() {
+    loading.value = false
+    error.value = null
+  }
+
+  return { loading, error, reset }
+}
+`
+}
+
+export function layoutTemplate(name) {
+  const componentName = toPascalCase(name) + 'Layout'
+  return `<template>
+  <div class="layout-${name}">
+    <header class="layout-header">
+      <nav>
+        <router-link to="/">Home</router-link>
+      </nav>
+    </header>
+    <main class="layout-main">
+      <slot />
+    </main>
+    <footer class="layout-footer">
+      <p>&copy; {{ new Date().getFullYear() }}</p>
+    </footer>
+  </div>
+</template>
+
+<script setup lang="ts">
+// ${componentName}
+</script>
+`
+}
+
+// ===========================================================================
+// PROJECT SCAFFOLD TEMPLATES
+// ===========================================================================
+
+export const VSTRUCT_MANIFEST = (projectName) => `{
+  "version": "1",
+  "project": {
+    "name": "${projectName}",
+    "description": ""
+  },
+  "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"
+    },
+    "maxComponentLines": 300,
+    "maxProps": 12,
+    "maxNesting": 6
+  },
+  "forbidden": [],
+  "required": {
+    "asyncButtons": false,
+    "errorHandling": true,
+    "imgAlt": true
+  }
+}
+`
+
+export const PACKAGE_JSON = (name) => `{
+  "name": "${name}",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "pinia": "^2.1.0",
+    "vue": "^3.4.0",
+    "vue-router": "^4.3.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.4.0",
+    "vue-tsc": "^2.0.0"
+  }
+}
+`
+
+export const VITE_CONFIG = `import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { resolve } from 'path'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+})
+`
+
+export const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "lib": ["ESNext", "DOM"],
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "src/**/*.d.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+`
+
+export const INDEX_HTML = (name) => `<!DOCTYPE html>
+<html lang="es">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${name}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+`
+
+export const MAIN_TS = `import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import App from './App.vue'
+import router from './router'
+import './styles/main.css'
+
+const app = createApp(App)
+app.use(createPinia())
+app.use(router)
+app.mount('#app')
+`
+
+export const APP_VUE = `<template>
+  <router-view />
+</template>
+
+<script setup lang="ts">
+// App root component
+</script>
+`
+
+export const MAIN_CSS = `*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  font-family: system-ui, -apple-system, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+body {
+  min-height: 100dvh;
+  color: #1a1a1a;
+  background: #ffffff;
+}
+`
+
+export const ROUTER_INDEX = `import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes: [
+    {
+      path: '/',
+      name: 'home',
+      component: () => import('@/pages/index.vue'),
+    },
+  ],
+})
+
+export default router
+`
+
+export const GITIGNORE = `node_modules/
+dist/
+.env
+.env.local
+*.log
+`
+
+export const AGENTS_MD = (name) => `# ${name}
+
+Framework: **Vue 3** + **Vite** + **TypeScript** + **Pinia** + **Vue Router**.
+
+## ⚠️ LECTURA OBLIGATORIA — antes de generar código
+
+1. **Leer \`vstruct.json\`** — reglas exactas del proyecto (naming, layers, límites). OBLIGATORIO.
+2. **Leer \`AIREF.md\`** — tabla canónica, patrones, buenas/malas prácticas.
+
+## TABLA CANÓNICA — dónde va cada cosa
+
+| Tipo | Ubicación | Naming |
+|------|-----------|--------|
+| Componente UI | \`src/components/ui/\` | \`PascalCase.vue\` |
+| Componente Feature | \`src/components/features/\` | \`PascalCase.vue\` |
+| Página | \`src/pages/\` | \`kebab-case.vue\` |
+| Layout | \`src/layouts/\` | \`PascalCase.vue\` |
+| Store (Pinia) | \`src/stores/\` | \`camelCase.store.ts\` |
+| Service (API) | \`src/services/\` | \`PascalCase.service.ts\` |
+| Composable | \`src/composables/\` | \`useXxx.ts\` |
+| Tipos compartidos | \`src/types/index.ts\` | — |
+
+## REGLAS INMUTABLES
+
+| # | Regla | Por qué |
+|---|-------|---------|
+| 1 | Componentes en \`components/\`, NO en \`pages/\` ni \`layouts/\` | Separación de concerns |
+| 2 | NUNCA \`fetch()\` directo en componentes → \`services/\` | 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 llama a router | Dependencia circular |
+| 7 | Service NO importa stores | Services son puros HTTP |
+| 8 | Tipos en \`types/index.ts\`, NO duplicados | Fuente única de verdad |
+
+## ANTIPATRONES — NUNCA hacer
+
+\`\`\`
+❌ fetch() en <script setup> de .vue → Crear X.service.ts
+❌ <a href="/ruta"> → <router-link to="/ruta">
+❌ <style> sin scoped → <style scoped>
+❌ import { useRouter } en store → Componente hace router.push()
+❌ interface User en 3 archivos → types/index.ts
+❌ pages/UserList.vue → pages/user-list.vue (kebab-case)
+❌ services/product.ts → Product.service.ts
+❌ composables/fetch.ts → useFetch.ts
+\`\`\`
+
+## VALIDACIÓN
+
+\`\`\`bash
+vstruct analyze   # 0 errores = listo. NUNCA declarar "terminado" sin 0 errores.
+\`\`\`
+
+## CLI rápida
+
+\`\`\`bash
+vstruct g c UserCard    # componente
+vstruct g p user-list   # página
+vstruct g s auth        # store
+vstruct g sv Product    # service
+vstruct g co useFetch   # composable
+vstruct g l Admin       # layout
+\`\`\`
+`
+
+export const README_MD = (name) => `# ${name}
+
+Creado con [vstruct](https://www.npmjs.com/package/vstruct) — estructura Vue 3 predecible.
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+Abre [http://localhost:5173](http://localhost:5173).
+
+## Estructura
+
+\`\`\`
+src/
+  components/
+    ui/           ← componentes base (Button, Input, Card...)
+    features/     ← componentes de dominio
+  pages/          ← rutas (file-based por convención)
+  layouts/        ← layouts con <slot>
+  stores/         ← estado global (Pinia)
+  services/       ← llamadas API
+  composables/    ← lógica reutilizable (useXxx)
+  types/          ← tipos TypeScript compartidos
+  router/
+    index.ts      ← configuración de Vue Router
+  styles/
+    main.css      ← estilos globales
+  App.vue
+  main.ts
+\`\`\`
+
+## CLI
+
+| Comando | Descripción |
+|---------|-------------|
+| \`npx vstruct g c <Name>\` | Generar componente |
+| \`npx vstruct g p <name>\` | Generar página |
+| \`npx vstruct g s <name>\` | Generar store (Pinia) |
+| \`npx vstruct g sv <Name>\` | Generar service (API) |
+| \`npx vstruct g co <name>\` | Generar composable |
+| \`npx vstruct g l <name>\` | Generar layout |
+| \`npx vstruct analyze\` | Validar estructura del proyecto |
+`
+
+export const CLAUDE_MD = AGENTS_MD
+
+export const AIREF_MD = () => `# AIREF — Quick Reference
+
+Estructura Vue 3 predecible. Todo tiene UN lugar. Cero ambigüedad.
+
+## 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 | \`src/stores/\` | \`camelCase.store.ts\` | \`cart.store.ts\` |
+| Service | \`src/services/\` | \`PascalCase.service.ts\` | \`Product.service.ts\` |
+| Composable | \`src/composables/\` | \`useXxx.ts\` | \`useFetch.ts\` |
+| Tipos | \`src/types/\` | \`index.ts\` | — |
+
+## Reglas inmutables
+
+1. NUNCA inventar ubicaciones — usar la tabla
+2. NUNCA \`fetch()\` directo en componentes → \`services/\`
+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 llama a router
+7. Service NO importa stores
+
+## Buenas vs Malas
+
+| ✅ BIEN | ❌ MAL |
+|---------|--------|
+| \`<router-link to="/">\` | \`<a href="/">\` |
+| \`<script setup lang="ts">\` | \`<script>\` |
+| \`<style scoped>\` | \`<style>\` |
+| \`defineStore('x', () => {})\` | \`defineStore('x', { state })\` |
+| \`if (!res.ok) throw Error\` | \`return res.json()\` sin check |
+| \`types/index.ts\` centralizado | Tipos duplicados |
+| \`useFetch\` (con use) | \`fetchData\` (sin use) |
+| \`stores/auth.store.ts\` | \`store/auth.ts\` |
+| \`services/Product.service.ts\` | \`services/product.ts\` |
+| \`pages/user-list.vue\` | \`pages/UserList.vue\` |
+
+## Antipatrones que rompen la app
+
+\`\`\`
+❌ 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>
+\`\`\`
+
+## CLI
+
+\`\`\`bash
+vstruct g c UserCard    # src/components/features/UserCard.vue
+vstruct g p user-list   # src/pages/user-list.vue
+vstruct g s cart        # src/stores/cart.store.ts
+vstruct g sv Product    # src/services/Product.service.ts
+vstruct g co useFetch   # src/composables/useFetch.ts
+vstruct g l Admin       # src/layouts/Admin.vue
+vstruct analyze         # 0 errores = listo
+\`\`\`
+`