openprompt-lang 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 openPrompt-Lang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,663 @@
+# OpenPrompt-Lang
+
+Framework de anotaciones para desarrollo asistido por IA. Sistema de anotaciones `@kind`, `@contract`, `@limit`, etc. para guiar a la IA en proyectos React + TypeScript.
+
+```bash
+openPrompt-Lang --version
+```
+
+---
+
+## Índice
+
+- [Instalación](#instalación)
+- [Anotaciones PromptLang (directorio completo)](#anotaciones-promptlang-directorio-completo)
+  - [Tags de definición](#tags-de-definición)
+  - [Tags de contrato](#tags-de-contrato)
+  - [Tags de restricción](#tags-de-restricción)
+  - [Tags de composición](#tags-de-composición)
+  - [Tags de plataforma](#tags-de-plataforma)
+  - [Tags de alcance](#tags-de-alcance)
+  - [Tags de testing](#tags-de-testing)
+  - [Tags de metadata](#tags-de-metadata)
+- [Comandos CLI](#comandos-cli)
+- [Tutorial: Empezar desde 0](#tutorial-empezar-desde-0)
+- [Tutorial: Refactorizar proyecto existente](#tutorial-refactorizar-proyecto-existente)
+- [Configuración (prompt-lang.json)](#configuración-prompt-langjson)
+- [Validación cruzada](#validación-cruzada)
+- [Scripts descriptivos](#scripts-descriptivos)
+- [Estructura del proyecto](#estructura-del-proyecto)
+- [Sistema de componentes](#sistema-de-componentes)
+- [VS Code Extension](#vs-code-extension)
+- [Versionado (SemVer)](#versionado-semver)
+- [Documentación](#documentación)
+- [Publicación en npm](#publicación-en-npm)
+
+---
+
+## Instalación
+
+### Linux / macOS
+
+```bash
+# Instalación global
+npm install -g openprompt-lang
+
+# Si no tienes permisos globales:
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"   # agrega a ~/.bashrc o ~/.zshrc
+npm install -g openprompt-lang
+
+# Verificar
+openPrompt-Lang --version
+```
+
+### Windows (PowerShell)
+
+```powershell
+# Instalación global
+npm install -g openprompt-lang
+
+# Si no tienes permisos globales (ejecutar como Administrador una vez):
+npm config set prefix "${env:APPDATA}\npm"
+# O crear carpeta local:
+mkdir "$env:USERPROFILE\.npm-global" -Force
+npm config set prefix "$env:USERPROFILE\.npm-global"
+# Agregar al PATH (PowerShell profile):
+[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.npm-global\bin;" + $env:Path, "User")
+# O desde cmd/símbolo del sistema:
+:: setx PATH "%USERPROFILE%\.npm-global\bin;%PATH%"
+
+# Verificar
+openPrompt-Lang --version
+```
+
+### Alternativa: npx (sin instalar)
+
+```bash
+npx openprompt-lang --help
+```
+
+> El paquete está publicado en npm: `npx openprompt-lang --help`
+
+---
+
+## Anotaciones PromptLang (directorio completo)
+
+Las anotaciones se escriben como comentarios en el código. La IA las interpreta para entender restricciones, contratos y contexto del archivo.
+
+### Sintaxis general
+
+```typescript
+// @nombre(args)
+// @nombre(key: value, key2: value2)
+
+/* Formato multilinea */
+/*
+ * @use(kind, contract, deps)
+ * @kind(service)
+ * @contract(in: DTO -> out: Result @error: ServiceError)
+ */
+```
+
+### @use — Declaración de tags (OBLIGATORIO)
+
+Primer tag de todo archivo. Declara qué tags se usan.
+
+| Sintaxis | Significado |
+|---|---|
+| `@use(*)` | Todos los tags disponibles |
+| `@use(kind, contract)` | Solo los tags listados |
+
+---
+
+### Tags de definición
+
+#### @kind — Tipo de elemento
+
+```
+@kind(tipo)
+```
+
+| Valor | Descripción | Tags requeridos | Tags prohibidos | Límite default |
+|---|---|---|---|---|
+| `hook` | Custom hook React | `@contract` | `@props` | 80 líneas |
+| `component` | Componente UI | `@props` (recomendado) | `@contract` | 120 líneas |
+| `page` | Página completa | `@compose` | — | 200 líneas |
+| `service` | Servicio / API | `@contract` | `@props`, `@state` | 150 líneas |
+| `store` | Estado global | `@deps(zustand)` | — | 100 líneas |
+| `util` | Función utilitaria | — | `@state` | 100 líneas |
+| `type` | Interfaz / tipo | — | `@limit`, `@state` | — |
+| `layout` | Componente de layout | — | — | 150 líneas |
+| `feature` | Módulo completo | `@compose` | — | — |
+
+#### @pattern — Patrón de diseño
+
+```
+@pattern(nombre)
+```
+
+Valores: `compound`, `composition`, `generic`, `render-prop`, `provider`, `singleton`
+
+---
+
+### Tags de contrato
+
+#### @contract — Interfaz de función (hooks / services)
+
+```
+@contract(in: tipos -> out: tipo @error: tipo)
+```
+
+```
+@contract(in: email, password -> out: User @error: AuthError)
+@contract(in: ProductDTO -> out: Product @error: ValidationError)
+```
+
+#### @props — Props de componente
+
+```
+@props({ "nombre": "tipo", "nombre2?": "tipo", "nombre3": "tipo" })
+```
+
+> **Importante:** `@props` acepta dos formatos:
+> ```typescript
+> // Formato JSON (estricto):
+> ✅ @props({ "name": "string", "age?": "number", "label": "string" })
+> 
+> // Formato TypeScript (recomendado, más legible):
+> ✅ @props({ name: string, age?: number, label: string })
+> 
+> // ❌ Mezclar ambos no funciona:
+> ❌ @props({ "name": string })
+> ```
+
+```
+@props({ "name": "string", "age?": "number", "label": "string" })
+```
+
+#### @state — Estados visuales
+
+```
+@state(loading, empty, error, success, idle, submitting)
+```
+
+---
+
+### Tags de restricción
+
+#### @limit — Límites del archivo
+
+```
+@limit(lines: 120, functions: 3, params: 2, complexity: 5, nesting: 3)
+```
+
+#### @forbidden — Prohibiciones explícitas
+
+```
+@forbidden(any, css-modules, class-components)
+```
+
+---
+
+### Tags de composición
+
+#### @compose — Dependencias internas
+
+```
+@compose(Header, DataTable, Sidebar)
+```
+
+Requerido en `@kind(page)`.
+
+#### @deps — Dependencias externas
+
+```
+@deps(@external: [supabase, zod], @internal: [utils], @forbidden: [axios])
+```
+
+| Sub-tag | Descripción |
+|---|---|
+| `@external` | Librerías npm/pip/cargo |
+| `@internal` | Módulos del mismo proyecto |
+| `@forbidden` | Librerías prohibidas |
+| `@peer` | Peer dependencies |
+
+---
+
+### Tags de plataforma
+
+#### @platform — Target de ejecución
+
+```
+@platform(web, mobile, desktop)
+```
+
+Compatibilidad:
+
+| Plataforma | @capacitor/* | @tauri-apps/* |
+|---|---|---|
+| `web` | ❌ Prohibido | ❌ Prohibido |
+| `mobile` | ✅ Permitido | ❌ Prohibido |
+| `desktop` | ❌ Prohibido | ✅ Permitido |
+
+---
+
+### Tags de alcance
+
+#### @scope — Impacto del módulo
+
+```
+@scope(module: auth, affects: [login, register], breaking: false)
+```
+
+---
+
+### Tags de testing
+
+#### @test — Requisitos de testing
+
+```
+@test(@unit, @integration, @mock: [servicio], @coverage: 80)
+```
+
+---
+
+### Tags de metadata
+
+#### @meta — Metadatos del archivo
+
+```
+@meta(@version: "1.0.0", @author: "dev", @tags: [auth, supabase])
+```
+
+---
+
+### Ejemplos completos
+
+```typescript
+// @use(kind, contract, limit, deps, platform, scope, meta)
+// @kind(hook)
+// @limit(lines: 75, params: 1)
+// @contract(in: email, password -> out: user, token @error: AuthError)
+// @deps(@external: [supabase], @forbidden: [axios])
+// @platform(web)
+// @scope(module: auth, affects: [login, register, session])
+// @meta(@version: "1.0.0", @tags: [auth, supabase])
+export function useAuth() { ... }
+```
+
+```typescript
+// @use(kind, props, state, limit, pattern)
+// @kind(component)
+// @props({ "variant": "string", "size": "string", "children": "ReactNode", "disabled?": "boolean" })
+// @state(idle, disabled, loading)
+// @limit(lines: 90, functions: 2)
+// @pattern(composition)
+export function Button(props: ButtonProps) { ... }
+```
+
+> 📖 **Especificación completa:** `docs/SYNTAX.md`
+
+---
+
+## Comandos CLI
+
+| Comando | Descripción |
+|---|---|
+| `openPrompt-Lang init --name miapp` | Crea proyecto desde 0 con scaffolding completo + scripts descriptivos |
+| `openPrompt-Lang init --existing` | Configura proyecto existente (solo archivos de config) |
+| `openPrompt-Lang context --output contexto.md` | Extrae todo el código + anotaciones para dar contexto a la IA |
+| `openPrompt-Lang validate` | Valida anotaciones y ejecuta pipeline de verificación |
+| `openPrompt-Lang figma` | Genera prompt para diseño Figma |
+| `openPrompt-Lang suggest "descripción"` | IA sugiere stack y estructura según descripción |
+| `openPrompt-Lang component init` | Inicializa biblioteca de componentes reutilizables |
+| `openPrompt-Lang component list` | Lista componentes disponibles (proyecto + biblioteca) |
+| `openPrompt-Lang component add <nombre>` | Agrega componente de la biblioteca al proyecto |
+| `openPrompt-Lang component manifest` | Muestra el manifiesto de la biblioteca |
+
+> 📖 **Comandos y opciones detallados:** `docs/COMMANDS.md`
+
+---
+
+## Tutorial: Empezar desde 0
+
+### Paso 1: Inicializar el proyecto
+
+```bash
+openPrompt-Lang init --name mi-app-web
+cd mi-app-web
+```
+
+Esto crea:
+```
+mi-app-web/
+├── src/                     # Scaffolding: components/, hooks/, features/, services/, store/, ...
+├── docs/                    # BACKLOG/, COMMITS/, LOGS/, PROMPTS/
+├── scripts/
+│   └── validate.sh          # Pipeline de validación pre-commit
+├── package.json             # Scripts descriptivos (dev:start, test:unit, validate:all...)
+├── prompt-lang.json         # Configuración del framework
+├── AGENTS.md                # Contexto para la IA
+└── .gitignore
+```
+
+### Paso 2: Inicializar Vite + React + TS
+
+```bash
+npm create vite@latest . -- --template react-ts
+npm install
+npm install tailwindcss @tailwindcss/vite
+```
+
+Luego copia los scripts descriptivos del `package.json` generado o usa `--existing` para mergearlos.
+
+### Paso 3: Anotar tu primer hook
+
+```typescript
+// src/hooks/useAuth.ts
+// @use(kind, contract, limit, deps)
+// @kind(hook)
+// @limit(lines: 60, params: 1)
+// @contract(in: email, password -> out: User | null @error: string)
+// @deps(@external: [supabase])
+export function useAuth() {
+  // ...
+}
+```
+
+### Paso 4: Validar
+
+```bash
+openPrompt-Lang validate
+npm run type:check
+npm run test:unit
+```
+
+### Paso 5: Extraer contexto para la IA
+
+```bash
+openPrompt-Lang context --output contexto.md
+```
+
+Pasa ese `contexto.md` a la IA junto con `docs/referencia-metodologia/` para que entienda el proyecto completo.
+
+---
+
+## Tutorial: Refactorizar proyecto existente
+
+### Paso 1: Configurar
+
+```bash
+cd mi-proyecto-ya-iniciado
+openPrompt-Lang init --existing
+```
+
+Esto detecta automáticamente el stack y crea solo:
+- `prompt-lang.json` (config con stack detectado)
+- `AGENTS.md` (contexto para IA con tecnologías reales)
+
+Te preguntará:
+- ¿Agregar scripts descriptivos al `package.json`? (merge sin romper)
+- ¿Crear `docs/BACKLOG`, `COMMITS`, `LOGS`?
+
+### Paso 2: Anotar los archivos a refactorizar
+
+Empieza por los archivos que vas a tocar:
+
+```typescript
+// @use(kind, contract, limit)
+// @kind(service)
+// @limit(lines: 100)
+// @contract(in: UserDTO -> out: User @error: ApiError)
+export async function createUser(data: UserDTO): Promise<User> { ... }
+```
+
+### Paso 3: Validar solo lo que cambiaste
+
+```bash
+openPrompt-Lang validate src/services/userService.ts
+```
+
+### Paso 4: Generar contexto para la IA
+
+```bash
+openPrompt-Lang context --output contexto.md --scope auth
+```
+
+Filtra por módulo (`@scope`) para no saturar a la IA con código no relevante.
+
+### Paso 5: Refactorizar
+
+Pasa el `contexto.md` a la IA con instrucciones específicas (qué refactorizar, qué patrones usar, límites).
+
+---
+
+## Configuración (prompt-lang.json)
+
+```json
+{
+  "name": "mi-app",
+  "version": "0.1.0",
+  "stack": {
+    "base": ["react", "typescript", "vite", "tailwind"],
+    "extensions": ["supabase", "ionic"]
+  },
+  "profile": "senior",
+  "annotations": { "enabled": true, "strict": false },
+  "docs": { "commits": true, "logs": true, "backlog": true },
+  "extractor": {
+    "ignore": [".env", "*.local", "dist", "node_modules"],
+    "output": "contexto.md"
+  }
+}
+```
+
+| Campo | Descripción |
+|---|---|
+| `stack.base` | Tecnologías base del proyecto |
+| `stack.extensions` | Extensiones opcionales (supabase, ionic, tauri) |
+| `profile` | Perfil del dev: senior, mid, junior |
+| `annotations.strict` | Si `true`, falla en warnings (no solo errores) |
+| `components.source` | Ruta de componentes del proyecto (`src/components/ui`) |
+| `components.library` | Ruta de la biblioteca de componentes reutilizables |
+| `extractor.ignore` | Patrones a ignorar al extraer contexto |
+
+---
+
+## Validación cruzada
+
+El CLI valida relaciones entre tags automáticamente:
+
+| @kind | @contract | @props | @state | @compose | @limit default |
+|---|---|---|---|---|---|
+| `hook` | REQUERIDO | PROHIBIDO | — | — | 80 |
+| `component` | PROHIBIDO | RECOMENDADO | RECOMENDADO | — | 120 |
+| `page` | — | — | — | REQUERIDO | 200 |
+| `service` | REQUERIDO | PROHIBIDO | PROHIBIDO | — | 150 |
+| `store` | — | — | — | — | 100 |
+| `type` | — | — | PROHIBIDO | — | N/A |
+
+Además:
+- `@platform(web)` + `@deps(@capacitor/*)` → **ERROR**
+- `@platform(mobile)` + `@deps(@tauri-apps/*)` → **ERROR**
+- `@scope(breaking: true)` → commit debe ser breaking change `!`
+- `@forbidden(any)` → warning si se detecta `any` en el código
+- `@state(error)` sin `@contract(@error)` → warning (solo en `hook`/`service`, no en `component`/`page`)
+
+---
+
+## Scripts descriptivos
+
+Generados automáticamente por `npm init` (o mergeables con `--existing`).
+
+| Script | Comando real | Propósito |
+|---|---|---|
+| `npm run dev:start` | `vite` | Servidor de desarrollo |
+| `npm run dev:preview` | `vite preview` | Vista previa del build |
+| `npm run build:prod` | `vite build` | Build producción |
+| `npm run build:analyze` | `vite build --analyze` | Build con análisis de bundle |
+| `npm run lint:check` | `eslint src --ext .ts,.tsx` | Verificar lint |
+| `npm run lint:fix` | `eslint src --ext .ts,.tsx --fix` | Auto-corregir lint |
+| `npm run type:check` | `tsc --noEmit` | Verificar tipos TypeScript |
+| `npm run quality:doctor` | `npx react-doctor check ./src` | Auditoría React |
+| `npm run test:unit` | `vitest run` | Tests unitarios |
+| `npm run test:watch` | `vitest` | Tests en modo watch |
+| `npm run test:coverage` | `vitest run --coverage` | Tests con cobertura |
+| `npm run validate:all` | lint + typecheck + doctor + test | Pipeline completo |
+
+---
+
+## Estructura del proyecto
+
+```
+openPrompt-Lang/
+├── bin/cli.js                  ← Entry point del CLI
+├── src/
+│   ├── commands/
+│   │   ├── init.js             ← init + --existing
+│   │   ├── context.js          ← Extractor de contexto
+│   │   ├── validate.js         ← Validador de anotaciones
+│   │   ├── figma.js            ← Generador de prompts Figma
+│   │   └── suggest.js          ← Sugerencia de stack vía IA
+│   └── utils/
+│       ├── annotations.js      ← Parser + validador de anotaciones
+│       ├── config.js           ← Loader de prompt-lang.json + detectStack
+│       └── ai.js               ← Módulo de IA (OpenAI / opencode)
+├── tests/
+│   ├── annotations.test.js     ← ~65 tests de parser y validador
+│   └── config.test.js          ← Tests de configuración
+├── docs/
+│   ├── COMMANDS.md             ← Documentación completa de comandos
+│   ├── SYNTAX.md               ← Especificación del lenguaje PromptLang
+│   ├── DEPENDENCIES.md         ← Dependencias y versiones
+│   ├── FRAMEWORK.md            ← Framework spec (acceso rápido)
+│   └── referencia-metodologia/ ← Metodología completa (17 archivos)
+│       ├── Indice General.md
+│       ├── Fase - 1.md a Fase - 8.md
+│       ├── docs/PROMPTS/       ← Biblioteca de prompts reutilizables
+│       └── ...
+├── vscode-extension/          ← Extensión VS Code (highlighting + snippets)
+├── schemas/
+│   └── prompt-lang.json        ← JSON Schema para la configuración
+├── package.json
+└── .gitignore
+```
+
+---
+
+## Documentación
+
+| Archivo | Contenido |
+|---|---|
+| `docs/SYNTAX.md` | Especificación completa del lenguaje de anotaciones PromptLang |
+| `docs/COMMANDS.md` | Todos los comandos, opciones y configuración del CLI |
+| `docs/DEPENDENCIES.md` | Dependencias del proyecto, versiones y notas técnicas |
+| `docs/FRAMEWORK.md` | Framework spec — catálogo de patrones y metodología |
+| `docs/VERSIONING.md` | Convención de versionado SemVer (MAJOR/MINOR/PATCH, pre-release) |
+| `docs/referencia-metodologia/` | Metodología completa: fases, patrones, templates de prompts |
+| `docs/referencia-metodologia/docs/CONVENCIONES_DB.md` | 18 prácticas de base de datos (RLS, índices, batch, etc.) |
+| `docs/referencia-metodologia/docs/CONVENCIONES_DOCUMENTACION.md` | Estándar de documentación (tablas DB, Mermaid, contratos RPC) |
+| `docs/referencia-metodologia/docs/PROMPTS/` | Biblioteca de prompts reutilizables (17 plantillas + 3 stacks) |
+| `vscode-extension/` | Extensión VS Code: syntax highlighting y snippets para anotaciones |
+| `schemas/prompt-lang.json` | JSON Schema para validar `prompt-lang.json` |
+
+---
+
+## Versionado (SemVer)
+
+openPrompt-Lang sigue [SemVer estricto](docs/VERSIONING.md):
+
+| Bump | Cuándo | Ejemplo |
+|---|---|---|
+| **MAJOR** | Breaking changes en API, CLI o anotaciones | `1.0.0` → `2.0.0` |
+| **MINOR** | Nuevas funcionalidades, comandos, tags | `0.2.0` → `0.3.0` |
+| **PATCH** | Fixes, docs, refactors sin cambio de API | `0.2.0` → `0.2.1` |
+
+Pre-release: `1.0.0-alpha.1`, `1.0.0-beta.1`, `1.0.0-rc.1`
+
+> 📖 **Especificación completa:** `docs/VERSIONING.md`
+
+---
+
+## Sistema de componentes
+
+openPrompt-Lang incluye un sistema de **biblioteca de componentes reutilizables**:
+
+- **`component init`** — Crea una biblioteca con ejemplos (Button, ConfirmModal, Input)
+- **`component list`** — Muestra componentes del proyecto y de la biblioteca
+- **`component add <nombre>`** — Copia un componente de la biblioteca al proyecto
+- Los componentes incluyen UX patterns: `ConfirmModal` para acciones destructivas, `Button` con variante `danger`, etc.
+- Configurable en `prompt-lang.json` → `components.library`
+
+---
+
+## VS Code Extension
+
+openPrompt-Lang incluye una extensión para VS Code en `vscode-extension/` con resaltado de sintaxis y snippets.
+
+### Instalación
+
+**Opción 1 — Desde el paquete npm (recomendada):**
+
+```bash
+# La extensión está dentro del paquete npm instalado
+code --install-extension ./node_modules/openprompt-lang/vscode-extension/
+```
+
+**Opción 2 — Desde el repositorio local:**
+
+```bash
+cd ruta/a/openPrompt-Lang/vscode-extension/
+code --install-extension .
+```
+
+**Opción 3 — Empaquetar como .vsix:**
+
+```bash
+cd ruta/a/openPrompt-Lang/vscode-extension/
+npx @vscode/vsce package
+code --install-extension openprompt-lang-*.vsix
+```
+
+### Funcionalidades
+
+- **Syntax highlighting**: todos los tags (`@kind`, `@props`, `@contract`, etc.) se resaltan en comentarios de TypeScript/JavaScript
+- **Snippets**: escribe `@kind-` y autocompleta:
+  - `@kind-hook` → hook con `@contract`
+  - `@kind-component` → componente con `@props`
+  - `@kind-service` → servicio con `@contract` + `@platform`
+  - `@kind-page` → página con `@compose`
+  - `@kind-store` → store Zustand
+  - `@use-header` → declaración `@use()`
+  - `@props-ts` → props con sintaxis TypeScript
+
+### Requisitos
+
+- VS Code >= 1.85.0
+- La extensión se activa automáticamente en archivos `.ts` y `.tsx`
+
+---
+
+## Publicación en npm
+
+```bash
+# 1. Build (si aplica)
+npm run build
+
+# 2. Test
+npm test
+
+# 3. Versionar (e.g. 0.3.0 → 0.4.0 para nuevas features)
+npm version minor -m "feat: %s"
+
+# 4. Publicar
+npm publish --access public
+
+# 5. Tag de release
+git push --follow-tags
+```
+
+> ⚠️ Requiere cuenta npm: `npm login` primero.
+>
+> Pre-release: `npm publish --tag next`