arckode-ui 0.2.0 → 0.2.1

package/CLAUDE.md.example

@@ -0,0 +1,123 @@
+# CLAUDE.md — proyecto que usa Arckode UI
+
+> Copiá este archivo a la raíz de tu proyecto (renómbralo a `CLAUDE.md`).
+> Claude Code / OpenCode lo cargan automáticamente cuando trabajan en el proyecto.
+
+## Skill obligatoria — leer ANTES de escribir código
+
+Arckode UI distribuye un SKILL con PROTOCOLO de 4 pasos y 16 REGLAS INMUTABLES.
+**Antes de crear/modificar cualquier `.ark` file, leer:**
+
+```
+./node_modules/arckode-ui/skills/SKILL.md
+```
+
+Sub-skills específicos por área:
+
+| Contexto | Sub-skill |
+|----------|-----------|
+| Escribir un `.ark`, patrones de UI (modal, form, lista) | `./node_modules/arckode-ui/skills/components/SKILL.md` |
+| Signals, computed, watch, comunicación padre↔hijo | `./node_modules/arckode-ui/skills/runtime/SKILL.md` |
+| Agregar regla nueva al analyzer | `./node_modules/arckode-ui/skills/analyzer/SKILL.md` |
+| CLI `ark` y generators | `./node_modules/arckode-ui/skills/cli/SKILL.md` |
+| Tests con vitest + happy-dom | `./node_modules/arckode-ui/skills/testing/SKILL.md` |
+| Compiler interno (avanzado) | `./node_modules/arckode-ui/skills/compiler/SKILL.md` |
+
+## Las 16 REGLAS INMUTABLES — referencia rápida
+
+| # | Regla | Detecta |
+|---|-------|---------|
+| 1 | Toda prop DEBE tener `type` (clase nativa) | `PROP_MISSING_TYPE` |
+| 2 | `emits` siempre kebab-case | `EMIT_CAMELCASE` |
+| 3 | `setup()` retorna SOLO `state`, `computed`, `actions` | `SETUP_UNKNOWN_RETURN_KEY` |
+| 4 | Handlers SIEMPRE `actions.xxx` | `HANDLER_NOT_IN_ACTIONS` |
+| 5 | `v-for` colección siempre namespaced | `VFOR_NOT_NAMESPACED` |
+| 6 | `v-if` con acceso namespaced (con `.`) | `VIF_NOT_NAMESPACED` |
+| 7 | NO existe `v-model` — input controlado explícito | — |
+| 8 | NO existe `ref()` ni `reactive()` — solo `signal()` | `REF_REACTIVE_USAGE` |
+| 9 | NO existe `provide`/`inject` — usar `defineStore` | `PROVIDE_INJECT_USAGE` |
+| 10 | `fetch()` PROHIBIDO en componente — usar `createService` | `DIRECT_FETCH_IN_COMPONENT` |
+| 11 | NO lógica en directivas (`++`, ternarios) | `LOGIC_IN_TEMPLATE` |
+| 12 | Actions como `function`, no arrow | `ARROW_FUNCTION_ACTION` |
+| 13 | Componentes hijos PascalCase + import explícito | — |
+| 14 | `mount(component, selector)` toma string | — |
+| 15 | Imports SOLO de `'arckode-ui'` o `'arckode-ui/vite'` | — |
+| 16 | Orden recomendado del `setup()` | — (convención) |
+
+Detalle completo y ejemplos en `./node_modules/arckode-ui/skills/SKILL.md`.
+
+## PROTOCOLO antes de codear
+
+```
+PASO 1 — IDENTIFICAR ALCANCE
+  ¿1 componente nuevo? ¿modificar existente? ¿estado global? ¿servicio HTTP?
+
+PASO 2 — VERIFICAR REGLAS (las 16 de arriba)
+
+PASO 3 — GENERAR
+  Si es componente nuevo: copiar PLANTILLA CANÓNICA del SKILL §5
+
+PASO 4 — VERIFICAR (NO asumir que funciona)
+  npx ark analyze    → 0 errors
+  Probar en navegador
+```
+
+## Comandos del proyecto
+
+```bash
+# Generar archivos con plantillas válidas garantizadas
+npx ark generate component <PascalCase>
+npx ark generate page <name>
+npx ark generate store <camelCase>
+npx ark generate service <PascalCase>
+npx ark generate layout <name>
+
+# Análisis
+npx ark analyze              # 0 errors antes de declarar listo
+npx ark routes               # listar rutas del file-system router
+
+# Dev / build
+bun dev
+bun build
+```
+
+## Anti-patterns más comunes (cada uno viola una regla)
+
+```typescript
+// ❌ REGLA #4
+@click="handleClick"          → @click="actions.handleClick"
+
+// ❌ REGLA #5
+v-for="item in items"         → v-for="item in state.items.value"
+
+// ❌ REGLA #7
+<input v-model="state.name"/> → :value + @input explícito
+
+// ❌ REGLA #8
+const x = ref(0)              → signal(0)
+
+// ❌ REGLA #11
+@click="state.count.value++"  → @click="actions.increment"
+:class="x.value ? 'a' : 'b'"  → mover a computed
+```
+
+## Cuando el analyzer reporta un error
+
+Cada violation incluye campo `Fix:` con sugerencia concreta. **Leerlo y aplicarlo literal:**
+
+```
+[arckode-ui] UserCard.ark:5
+  HANDLER_NOT_IN_ACTIONS: El handler "handleClick" no está namespaced.
+  > 5 | <button @click="handleClick">
+  Fix: Reemplazar "handleClick" por "actions.handleClick" y asegurarse de
+       que la función esté declarada en setup() y exportada en el return.actions.
+```
+
+## Benchmark de predictabilidad
+
+Test ciego (10 prompts × 2 variantes con Claude Sonnet):
+- **Sin SKILL:** 30% outputs válidos
+- **Con SKILL:** 100% outputs válidos
+
+Por eso vale la pena cargar el SKILL antes de generar código.
+Detalle en https://gitlab.com/underworf/arckode-ui/-/blob/main/BENCHMARK.md

package/README.md

@@ -1,10 +1,31 @@
 # Arckode UI
 
-Framework frontend con archivos `.ark` (Single File Components), reactividad por signals, compiler propio (Vite plugin), router file-system y analyzer estático.
+Framework frontend con archivos `.ark` (Single File Components), reactividad por signals, compiler propio (Vite plugin), router file-system y analyzer estático con sugerencias concretas de fix.
 
 > **Diseñado para máxima predictibilidad de output de IA.** Hay un solo camino correcto para cada problema. Para cada violation detectada, el analyzer sugiere el fix concreto.
 
-**Versión:** 0.1.0 — desarrollo activo
+**Predictabilidad medida (benchmark ciego con Claude Sonnet, 10 prompts):**
+**Sin SKILL: 30% outputs válidos · Con SKILL: 100%.** Ver [BENCHMARK.md](./BENCHMARK.md).
+
+**Versión:** 0.2.1 — desarrollo activo
+
+---
+
+## Activar el SKILL para tu IA (Claude/OpenCode)
+
+Después de instalar el paquete, copiá el `CLAUDE.md.example` a la raíz de tu proyecto:
+
+```bash
+cp node_modules/arckode-ui/CLAUDE.md.example ./CLAUDE.md
+```
+
+Eso hace que cualquier IA (Claude Code, OpenCode, Cursor) cargue automáticamente:
+- El PROTOCOLO de 4 pasos antes de codear
+- Las 16 reglas inmutables que el analyzer enforza
+- Las plantillas canónicas
+- Los 6 sub-skills temáticos (runtime, compiler, analyzer, cli, components, testing)
+
+Sin este archivo, la IA improvisa. Con este archivo, **9 de cada 10 outputs pasan el analyzer al primer intento**.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-ui",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Frontend framework con .ark SFCs, signals, file-system router y analyzer estático con sugerencias concretas de fix. Diseñado para máxima predictibilidad de output de IA.",
   "keywords": [
@@ -44,7 +44,8 @@
     "dist",
     "skills",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CLAUDE.md.example"
   ],
   "scripts": {
     "build": "vite build && chmod +x dist/cli.js",
@@ -58,6 +59,7 @@
     "vite": ">=5.0.0"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.98.0",
     "@types/bun": "latest",
     "happy-dom": "^20.9.0",
     "typescript": "^5.4.0",