From b0461f6b926a9abd7306cc4698b50066b7f90386 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 5 Nov 2025 19:32:07 +0000 Subject: [PATCH] Add Spanish documentation and translations Co-authored-by: kevin --- README.es.md | 360 ++++++++++++++++++++++++++++++++ README.md | 2 + docs/es/constructa/hosting.md | 200 ++++++++++++++++++ docs/es/constructa/local-dev.md | 65 ++++++ docs/es/constructa/mastra.md | 253 ++++++++++++++++++++++ 5 files changed, 880 insertions(+) create mode 100644 README.es.md create mode 100644 docs/es/constructa/hosting.md create mode 100644 docs/es/constructa/local-dev.md create mode 100644 docs/es/constructa/mastra.md diff --git a/README.es.md b/README.es.md new file mode 100644 index 0000000..c0815b0 --- /dev/null +++ b/README.es.md @@ -0,0 +1,360 @@ +# Constructa Starter + +
+ Banner de Constructa Starter +
+ +
+

Kit de Inicio SAAS con IA

+

Optimizado para codificar con asistentes de IA • Impulsado por instructa.ai

+
+ +> 🌍 **También disponible en inglés** - [English README](README.md) | [English Documentation](docs/) + +> ⚠️ **Trabajo en Progreso** - Este kit de inicio está actualmente en desarrollo activo. Las características y la documentación pueden cambiar con frecuencia. + + +## ✨ Características + +- 🔐 **Autenticación** - Inicio de sesión/registro con email, GitHub y Google OAuth, recuperación de contraseña +- 📊 **Plantillas de Panel** - Chat de IA, Flujos de Trabajo, Documentos, Chat de Imágenes, Gráficos (`/dashboard`) +- 🤖 **Chat de Asistente IA** - Asistente de IA consciente del repositorio impulsado por Mastra con acceso a archivos respaldado por MinIO (`/dashboard/chat`) +- 💳 **Facturación y Pagos** - Sistema completo de suscripciones con integración de Polar.sh, gestión de créditos y portal de facturación (`/dashboard/billing`) +- 🎨 **Páginas de Marketing** - Página de inicio moderna con diseño responsivo y modo claro/oscuro +- 💾 **Base de Datos** - PostgreSQL local con Docker, listo para Supabase, Drizzle ORM +- 🚀 **Despliegue** - Despliegue en la nube de Hetzner con Docker, Dokku y CI/CD automatizado +- 🤖 **Optimizado para IA** - Reglas de Cursor, reglas de agentes auto-generadas con .ruler, formato AGENTS.md para Claude Code/Codex/Cursor, patrones consistentes, TypeScript para mejor codificación con IA +- 🛠️ **Herramientas de Desarrollo** - Recarga en caliente, alias de rutas, Oxlint, Vitest, CLI personalizado +- 🐛 **Registro de Errores Frontend** - Integración de Browser-Echo para captura automática de errores y registro estructurado + + +## 🚀 Inicio Rápido + +### Prerequisitos +- Descargar e Instalar **[Node.js](https://nodejs.org/en)** 22.12+ (requerido para TanStack Start RC1) +- Descargar e Instalar **[Docker](https://www.docker.com/)** Desktop +- **pnpm** (gestor de paquetes recomendado) + +### Instalación + +```bash +# Clonar el repositorio +npx gitpick git@github.com:instructa/constructa-starter.git my-app +cd my-app + +# Instalar dependencias +pnpm install + +# Iniciar servidor de desarrollo +pnpm dev +``` + +### Configuración + +``` +# Crear archivo env +cp .env.example .env + +# Usar CLI para iniciar tu proyecto +pnpm ex0 init +``` + +## ¿Por Qué? + +¿Por qué comenzar con una plantilla cuando la IA puede generar casi toda una aplicación? Porque una base sólida sigue siendo la parte más importante de construir aplicaciones web full-stack. Incluso los generadores de código como v0 o bolt.new se basan en un proyecto inicial. Proporciona consistencia y un punto de partida confiable. + +Además de eso, podemos agregar herramientas útiles como reglas de IA (Cursor Rules, Agents.md y más) y configuraciones que facilitan que Cursor, Claude y herramientas similares construyan tu aplicación. Esa es toda la idea detrás de este proyecto. Todavía está en una etapa temprana y no está listo para producción, pero ya es lo suficientemente maduro para crear algunas cosas interesantes. + + +## Stack Tecnológico + +- **[shadcn/ui](https://ui.shadcn.com/)** - Biblioteca de componentes hermosa y accesible +- **[Tailwind CSS v4](https://tailwindcss.com/)** - Framework CSS moderno basado en utilidades +- **[TypeScript](https://typescriptlang.org/)** - Seguridad de tipos completa +- **[TanStack Router](https://tanstack.com/router)** - Enrutamiento type-safe basado en archivos (v1.132.x) +- **[TanStack Start](https://tanstack.com/start)** - Framework React full-stack moderno (RC1) +- **[Better Auth](https://better-auth.com/)** - Biblioteca de autenticación moderna +- **[Better Auth UI](https://github.com/daveyplate/better-auth-ui)** - Componentes React pre-construidos para Better Auth +- **[Polar.sh](https://polar.sh)** - Gestión moderna de facturación y suscripciones +- **[Mastra](https://mastra.ai)** - Framework de agentes de IA con integración de herramientas +- **[Assistant UI](https://assistant-ui.com)** - Componentes React para interfaces de chat de IA +- **[OpenAI SDK](https://github.com/vercel/ai)** - SDK de IA para integración de LLM +- **[Drizzle ORM](https://orm.drizzle.team/)** - ORM TypeScript para PostgreSQL +- **[Oxlint](https://oxc.rs/docs/guide/usage/linter.html)** - Linter rápido para JavaScript/TypeScript +- **[Vitest](https://vitest.dev/)** - Framework de pruebas unitarias ultra rápido +- **Cursor Rules** - Reglas pre-configuradas de asistente de codificación con IA para experiencia de desarrollo óptima +- **.ruler** - Auto-genera reglas de agentes para desarrollo asistido por IA consistente +- **AGENTS.md** - Formato de reglas de agentes estandarizado compatible con Claude Code, Codex, Cursor y otros asistentes de codificación con IA + + +### CLI del Proyecto (`pnpm ex0`) + +Este proyecto incluye una herramienta CLI personalizada para tareas comunes. Ejecútala usando `pnpm ex0 `. + + +| Comando | Descripción | Argumentos | +| :--------- | :------------------------------------------------------------------------- | :------------------- | +| `init` | Inicializar el proyecto (dependencias, configuración de BD, Docker) | | +| `stop` | Detener contenedores Docker en ejecución | | +| `reload` | Recargar contenedores Docker con configuración actualizada | | +| `recreate` | Recrear contenedores Docker y volumen (¡ADVERTENCIA: elimina todos los datos!) | | +| `recreate` | Recrear contenedores Docker (usar --wipeVolume para también eliminar el volumen de datos) | `--wipeVolume` | +| `testdata` | Crear o eliminar datos de prueba en la base de datos | `--create`, `--delete` | +| `deploy` | Desplegar vía `git push dokku main` (ver docs/es/constructa/hosting.md) | Ejecutar según sea necesario | + +## 🔧 Configuración + +### Variables de Entorno + +Crea un archivo `.env` en el directorio raíz basado en `.env.example`: + +```bash +# Base de Datos +DATABASE_URL="postgresql://username:password@localhost:5432/constructa" + +# URL Base del Cliente (opcional - por defecto usa el origen actual en producción) +VITE_BASE_URL="http://localhost:3000" + +# Configuración de IA +OPENAI_API_KEY="sk-..." + +# Configuración de Facturación / Polar +POLAR_SERVER="sandbox" +POLAR_ACCESS_TOKEN="" +POLAR_WEBHOOK_SECRET="" +POLAR_ORGANIZATION_ID="" +POLAR_PRODUCT_PRO_MONTHLY="prod_..." +POLAR_PRODUCT_BUSINESS_MONTHLY="prod_..." +POLAR_PRODUCT_CREDITS_50="prod_..." +POLAR_PRODUCT_CREDITS_100="prod_..." +PUBLIC_URL="http://localhost:3000" +CHECKOUT_SUCCESS_URL="http://localhost:3000/dashboard/billing/success" +CHECKOUT_CANCEL_URL="http://localhost:3000/dashboard/billing" +VITE_ENTERPRISE_DEMO_URL="https://calendly.com/your-team/demo" +VITE_POLAR_PRODUCT_CREDITS_50="prod_..." +VITE_POLAR_PRODUCT_CREDITS_100="prod_..." +VITE_POLAR_PRODUCT_PRO_MONTHLY="prod_..." +VITE_POLAR_PRODUCT_BUSINESS_MONTHLY="prod_..." + +# Better Auth +BETTER_AUTH_SECRET="your-secret-key-here" +BETTER_AUTH_URL="http://localhost:3000" + +# Verificación de Email (deshabilitada por defecto) +# Control de verificación de email del lado del servidor +ENABLE_EMAIL_VERIFICATION="false" +# Control de verificación de email del lado del cliente (para decisiones de UI) +VITE_ENABLE_EMAIL_VERIFICATION="false" + +# Configuración del Servicio de Email (Resend es el proveedor por defecto) +EMAIL_FROM="noreply@yourdomain.com" +RESEND_API_KEY="your-resend-api-key" + +# Proveedores OAuth (opcional) +# Configuración OAuth del lado del servidor +GITHUB_CLIENT_ID="your-github-client-id" +GITHUB_CLIENT_SECRET="your-github-client-secret" +GOOGLE_CLIENT_ID="your-google-client-id" +GOOGLE_CLIENT_SECRET="your-google-client-secret" + +# Configuración OAuth del lado del cliente (para botones de UI) +VITE_GITHUB_CLIENT_ID="your-github-client-id" +VITE_GOOGLE_CLIENT_ID="your-google-client-id" +``` + +- `VITE_BASE_URL` es opcional - en producción, usará automáticamente el dominio actual +- Para desarrollo local, por defecto es `http://localhost:3000` + +### Configuración del Servicio de Email + +La aplicación soporta **múltiples proveedores de email** para máxima flexibilidad. Puedes elegir entre registro en consola, Mailhog (para desarrollo local), SMTP o Resend según tus necesidades. + +#### Opciones de Proveedores de Email + +1. **Proveedor de Consola** (Por defecto para desarrollo) + - Registra emails en la consola + - Sin dependencias externas + - Perfecto para desarrollo inicial + + ```bash + EMAIL_PROVIDER="console" + ``` + +2. **Mailhog** (Recomendado para desarrollo local) + - Captura todos los emails localmente + - Interfaz web para ver emails en http://localhost:8025 + - Ya incluido en Docker Compose + + ```bash + EMAIL_PROVIDER="mailhog" + # No requiere configuración adicional + ``` + + Iniciar Mailhog con Docker: + ```bash + docker-compose up -d mailhog + ``` + +3. **Proveedor SMTP** (Para producción o servidores de email personalizados) + ```bash + EMAIL_PROVIDER="smtp" + SMTP_HOST="smtp.gmail.com" + SMTP_PORT="587" + SMTP_SECURE="false" + SMTP_USER="your-email@gmail.com" + SMTP_PASS="your-app-password" + ``` + +4. **Resend** (API de email moderna) + ```bash + EMAIL_PROVIDER="resend" + RESEND_API_KEY="re_xxxxxxxxxxxx" + ``` + + - Regístrate en [resend.com](https://resend.com) + - Crea una clave API en tu panel + - Agrega y verifica tu dominio (para producción) + +#### Configuración Común de Email + +```bash +# Establecer la dirección "from" por defecto +EMAIL_FROM="noreply@yourdomain.com" + +# Habilitar verificación de email (opcional) +ENABLE_EMAIL_VERIFICATION="true" +VITE_ENABLE_EMAIL_VERIFICATION="true" +``` + +#### Agregar Proveedores de Email Personalizados + +El sistema de email está diseñado para ser extensible. Para agregar un nuevo proveedor: + +1. **Crear una nueva clase de proveedor** en `src/server/email/providers.ts`: + ```typescript + export class MyCustomProvider implements EmailProvider { + async sendEmail({ from, to, subject, html }) { + // Tu implementación aquí + } + } + ``` + +2. **Agregar el proveedor a la fábrica** en `src/server/email/index.ts`: + ```typescript + case "custom": + emailProvider = new MyCustomProvider(); + break; + ``` + +3. **Actualizar tus variables de entorno**: + ```bash + EMAIL_PROVIDER="custom" + # Agregar cualquier configuración personalizada necesaria + ``` + +#### Comportamiento de la Verificación de Email + +**Cuando está deshabilitada** (por defecto): +- Los usuarios inician sesión automáticamente después del registro +- No se envía email de verificación +- Los usuarios son redirigidos directamente al panel + +**Cuando está habilitada**: +- Los usuarios deben verificar su email antes de iniciar sesión +- Se envía un email de verificación tras el registro +- Los usuarios son redirigidos a una página de "verifica tu email" +- Los usuarios no pueden iniciar sesión hasta que su email sea verificado + +### Configuración de Proveedores OAuth + +La aplicación soporta autenticación OAuth con GitHub y Google. Aquí está cómo configurarlos: + +#### Configuración de OAuth de GitHub + +1. **Crear una App OAuth de GitHub:** + - Ir a [Configuración de Desarrollador de GitHub](https://github.com/settings/developers) + - Clic en "New OAuth App" + - Completar los detalles de la aplicación: + - **Nombre de la aplicación**: Nombre de tu app + - **URL de la página principal**: `http://localhost:3000` (para desarrollo) + - **URL de callback de autorización**: `http://localhost:3000/api/auth/callback/github` + +2. **Obtener tus credenciales:** + - Después de crear la app, copiar el **Client ID** + - Generar un nuevo **Client Secret** + +3. **Agregar a las variables de entorno:** + ```bash + # Configuración del lado del servidor + GITHUB_CLIENT_ID="your-github-client-id" + GITHUB_CLIENT_SECRET="your-github-client-secret" + + # Configuración del lado del cliente (para botones de UI) + VITE_GITHUB_CLIENT_ID="your-github-client-id" + ``` + +4. **Para despliegue en producción:** + - Actualizar la **URL de la página principal** a tu dominio de producción + - Actualizar la **URL de callback de autorización** a `https://yourdomain.com/api/auth/callback/github` + +#### Configuración de OAuth de Google + +1. **Crear una App OAuth de Google:** + - Ir a [Google Cloud Console](https://console.cloud.google.com/) + - Crear un nuevo proyecto o seleccionar uno existente + - Habilitar la API de Google+ + - Ir a "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs" + +2. **Configurar la pantalla de consentimiento OAuth:** + - Completar la información requerida de la aplicación + - Agregar tu dominio a los dominios autorizados + +3. **Crear ID de Cliente OAuth 2.0:** + - Tipo de aplicación: **Aplicación web** + - **Orígenes JavaScript autorizados**: `http://localhost:3000` (para desarrollo) + - **URIs de redireccionamiento autorizados**: `http://localhost:3000/api/auth/callback/google` + +4. **Obtener tus credenciales:** + - Copiar el **Client ID** y **Client Secret** + +5. **Agregar a las variables de entorno:** + ```bash + # Configuración del lado del servidor + GOOGLE_CLIENT_ID="your-google-client-id" + GOOGLE_CLIENT_SECRET="your-google-client-secret" + + # Configuración del lado del cliente (para botones de UI) + VITE_GOOGLE_CLIENT_ID="your-google-client-id" + ``` + +6. **Para despliegue en producción:** + - Actualizar orígenes autorizados a tu dominio de producción + - Actualizar URI de redirección a `https://yourdomain.com/api/auth/callback/google` + +#### Probar la Integración OAuth + +Una vez configurado, los usuarios verán opciones de inicio de sesión con GitHub y Google en las páginas de autenticación. Los proveedores OAuth se habilitan condicionalmente basados en la presencia de sus respectivas variables de entorno. + + +## 📄 Licencia + +Este proyecto está bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para más detalles. + +## Contribuir + +¡Damos la bienvenida a contribuciones! Por favor ver [CONTRIBUTING.md](CONTRIBUTING.md) para más detalles. + +## Enlaces + +- X/Twitter: [@kregenrek](https://x.com/kregenrek) +- Bluesky: [@kevinkern.dev](https://bsky.app/profile/kevinkern.dev) + +## Academia de IA y Cursos +- Aprende Cursor AI: [Curso Definitivo de Cursor](https://www.instructa.ai/en/cursor-ai) +- Aprende a construir software con IA: [instructa.ai](https://www.instructa.ai) + +## Ve mis otros proyectos: + +* [AI Prompts](https://github.com/instructa/ai-prompts/blob/main/README.md) - Prompts de IA curados para Cursor AI, Cline, Windsurf y Github Copilot +* [codefetch](https://github.com/regenrek/codefetch) - Convierte código en Markdown para LLMs con un simple comando de terminal +* [aidex](https://github.com/regenrek/aidex) - Herramienta CLI que proporciona información detallada sobre modelos de lenguaje de IA, ayudando a desarrolladores a elegir el modelo correcto para sus necesidades diff --git a/README.md b/README.md index f3859b6..7c6d610 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@

Optimized for coding with AI assistants • Powered by instructa.ai

+> 🌍 **Documentación disponible en español** - [README en Español](README.es.md) | [Documentación en Español](docs/es/) + > ⚠️ **Work in Progress** - This starter kit is currently under active development. Features and documentation may change frequently. diff --git a/docs/es/constructa/hosting.md b/docs/es/constructa/hosting.md new file mode 100644 index 0000000..3c99b23 --- /dev/null +++ b/docs/es/constructa/hosting.md @@ -0,0 +1,200 @@ +# Hospedaje en Hetzner con Dokku + +Esta guía te proporciona un despliegue **limpio y reproducible**: + +- **Terraform** provisiona un VPS Debian 13 con Docker y Dokku +- **Compose (solo servidor)** ejecuta **Postgres, MinIO, Redis, Meilisearch, Worker** +- **Dokku** ejecuta la **aplicación web**; alcanza los servicios vía `host.docker.internal` +- **Let's Encrypt** manejado por Dokku + +--- + +## 1) Provisionar el servidor + +```bash +cd infra/hetzner +export TF_VAR_hcloud_token=YOUR_HETZNER_TOKEN +terraform init && terraform apply +```` + +Esto instala: + +* Docker Engine +* Dokku v0.36.7 +* Usuario `deploy` sin root con tu clave SSH +* Firewall UFW (SSH/HTTP/HTTPS) + +## 1.5) Bootstrap con Ansible (recomendado) + +La automatización vive en `infra/ansible/`. Sincroniza el bundle de compose, renderiza `/opt/constructa/.env`, inicia los servicios y configura Dokku para apuntar a ellos. + +```bash +# instalar colecciones galaxy de Ansible localmente +ansible-galaxy collection install -r infra/ansible/requirements.yml + +# copiar + editar secretos (mantenidos localmente) +cp infra/ansible/group_vars/constructa/vars.example.yml infra/ansible/group_vars/constructa/vars.yml +$EDITOR infra/ansible/group_vars/constructa/vars.yml + +# actualizar inventario con tu host/IP +$EDITOR infra/ansible/inventory/hosts.ini + +# ejecutar después de que terraform apply se complete +ansible-playbook -i infra/ansible/inventory/hosts.ini infra/ansible/site.yml +``` + +Lo que hace el playbook: + +* sincroniza `infra/deploy/` en `/opt/constructa` +* escribe `/opt/constructa/.env` desde tu archivo de variables +* inicia Postgres/MinIO/Redis/Meilisearch + worker vía compose +* ejecuta aprovisionamiento de buckets + `pnpm run db:migrate` +* asegura que la app Dokku existe y apunta a `host.docker.internal` +* provisiona un archivo swap (`constructa_swap_file` / `constructa_swap_size`) para que las compilaciones Docker tengan suficiente memoria +* instala el plugin **dokku-redirect** y agrega redirecciones 301 para cualquier `constructa_redirect_domains` +* instala el plugin **dokku-letsencrypt**, establece `DOKKU_LETSENCRYPT_EMAIL`, habilita certificados y programa renovaciones cuando se proporciona `constructa_letsencrypt_email` +* si estás usando Dokku-first, establece `HOST_BIND_ADDR=0.0.0.0` para que los + contenedores Dokku puedan alcanzar los servicios compose vía el gateway del host + +--- + +## Dokku-first (recomendado, sin registro) + +Usa esto si no quieres un registro en absoluto. + +**Primera ejecución:** + +1. Ejecuta el playbook una vez (la BD principal/almacenamiento de objetos/búsqueda se inician; el worker compose permanece inactivo hasta que lo apuntes a una imagen real). +2. **Despliega una vez** para que Dokku construya la imagen localmente: + + ```bash + pnpm run ex0 -- deploy --env dev --ref + # o --env prod + ``` + + Dokku produce `dokku/constructa:latest`. +3. Apunta Compose a esa imagen local y re-ejecuta Ansible: + + ```yml + # en vars.yml bajo constructa_compose_env + APP_IMAGE: "dokku/constructa" + APP_TAG: "latest" + ``` + + Deja `constructa_run_compose_migrate` en su valor por defecto `false`; Dokku ya ejecuta migraciones durante el despliegue. Re-ejecuta el playbook y (re)iniciará el worker usando la **imagen local de Dokku**—sin necesidad de push/pull del registro. El playbook también refrescará las redirecciones y certificados LetsEncrypt después de que la nueva configuración de dominio esté en su lugar. + +¿Necesitas omitir completamente el paso de compilación de Dokku? Construye y envía la imagen desde tu laptop en una línea: + +```bash +pnpm run ex0 -- deploy-image --env dev +``` + +Este comando ejecuta `docker build`, transmite la imagen por SSH y ejecuta `dokku git:from-image` bajo el capó (cambia `--env dev` por `--env prod` según sea necesario, y agrega `--tag my-tag` si quieres un tag diferente). + +--- + +## 2) DNS + +Apunta tu dominio de la app (ej. `app.example.com`) a la IP del servidor (un registro A proxied de Cloudflare está bien). Si quieres que `www.` redirija 301 al apex, listalo en `constructa_redirect_domains` y re-ejecuta el playbook. + +## 3) Iniciar servicios principales (Compose en el servidor) + +> Estos se ejecutan localmente en el VPS y se vinculan solo a **127.0.0.1**. + +> Si ejecutaste el playbook Ansible en el paso 1.5, los comandos a continuación ya fueron ejecutados. Mantenlos para referencia o cuando te recuperes manualmente. + +```bash +# Copiar el bundle de infra; o deja que la Acción de GH lo haga +scp -r infra/deploy/* deploy@your.server:/opt/constructa + +ssh deploy@your.server +cd /opt/constructa +cp .env.sample .env # completar valores +# Para Dokku-first, establece HOST_BIND_ADDR=0.0.0.0 para que la app Dokku alcance los servicios + +# Iniciar Postgres, MinIO (+provisionar bucket), Redis, Meilisearch +docker compose -f compose.yml up -d db minio redis meilisearch +docker compose -f compose.yml up provision-minio || true + +# Iniciar worker en segundo plano (las migraciones se ejecutan durante el despliegue Dokku) +docker compose -f compose.yml up -d worker +``` + +**¿Por qué este diseño?** Evita la variación de plugins para Postgres/MinIO en Dokku y te da una ruta estable para persistencia de datos a través de reinicios del servidor. + +> **Importante:** Este proyecto **no** usa los addons de Postgres/Redis de Dokku. La base de datos, caché, almacenamiento de objetos, etc. todos se ejecutan dentro del stack de compose arriba. Siempre mantén ese stack ejecutándose antes de desplegar; de lo contrario Dokku recurrirá a recursos provisionados por plugins que carecen de extensiones requeridas como `pgvector`. + +## 4) Crear la app Dokku + +> Si ejecutaste el playbook Ansible en el paso 1.5, Dokku ya ha sido configurado con la app, dominios, plugin de redirección, LetsEncrypt y opciones docker. Usa esta sección solo para bootstrap manual o recuperación ante desastres. + +```bash +# creación única de app +ssh root@your.server "dokku apps:create constructa" + +# dominio, enrutamiento http, y mapeo de host para alcanzar servicios compose +ssh root@your.server "dokku domains:set constructa app.example.com" +ssh root@your.server "dokku proxy:ports-set constructa http:80:5000" +ssh root@your.server \"dokku docker-options:add constructa deploy,run '--add-host=host.docker.internal:host-gateway'\" +``` + +Ahora establece la configuración requerida. El detalle clave: **apunta a tus servicios loopback** (si omites esto, Dokku intentará usar su base de datos addon, que no incluye `pgvector` y tus migraciones fallarán): + +```bash +ssh root@your.server "dokku config:set constructa \ + NODE_ENV=production PORT=5000 \ + DATABASE_URL='postgresql://user:password@host.docker.internal:5432/ex0' \ + S3_ENDPOINT='http://host.docker.internal:9000' S3_REGION='us-east-1' \ + S3_ACCESS_KEY_ID='minioadmin' S3_SECRET_ACCESS_KEY='minioadmin' \ + S3_BUCKET='constructa-files' S3_ENABLE_PATH_STYLE=1 S3_PREVIEW_URL_EXPIRE_IN=7200 \ + MEILI_HOST='http://host.docker.internal:7700' MEILI_API_KEY='changeme-master-key' \ + REDIS_URL='redis://host.docker.internal:6379'" +``` + +Habilitar HTTPS: + +```bash +ssh root@your.server "dokku letsencrypt:enable constructa" +``` + +(Con Ansible, establece `constructa_letsencrypt_email` en tu archivo vars y el playbook manejará la instalación del plugin, emisión del certificado y el trabajo cron de renovación.) + +## 5) Desplegar la app + +### Opción A – Simple: push desde tu laptop + +```bash +git remote add dokku-prod dokku@your.server:constructa +pnpm run ex0 -- deploy --env prod +``` + +### Opción B – CI/CD (GHCR): ver **docs/es/constructa/cicd.md** para login de registro y tags. + +--- + +## Operaciones Comunes + +```bash +# Logs +ssh root@your.server "dokku logs constructa -t" + +# Escalar (solo web, worker es manejado por compose) +ssh root@your.server "dokku ps:scale constructa web=1" + +# Reconstruir +ssh root@your.server "dokku ps:rebuild constructa" + +# Rotar certificados +ssh root@your.server "dokku letsencrypt:force-renew constructa" + +# Limpieza de disco (bajo demanda, seguro) +pnpm run ex0 -- gc --age 720h # podar imágenes/caché sin usar más antiguas que 30 días +``` + +### ¿Por qué `host.docker.internal`? + +Los contenedores Dokku viven en la red **dokku**, pero tus servicios viven en la red **compose**. Mapear `host.docker.internal` al gateway del host Linux permite que los contenedores de la app hablen con servicios publicados en loopback (`127.0.0.1:…`). Establecemos eso con: + +```bash +dokku docker-options:add constructa deploy,run "--add-host=host.docker.internal:host-gateway" +``` diff --git a/docs/es/constructa/local-dev.md b/docs/es/constructa/local-dev.md new file mode 100644 index 0000000..f4c5faf --- /dev/null +++ b/docs/es/constructa/local-dev.md @@ -0,0 +1,65 @@ +# Desarrollo Local + +## Una sola vez + +```bash +cp .env.example .env +pnpm install +pnpm run ex0 -- init # instala deps, inicia servicios principales, ejecuta migraciones +``` + +Esto inicia **PostgreSQL**, **MinIO**, **Redis**, **Meilisearch**, y **Mailhog** bajo el perfil `dev`. + +## Ejecutar la aplicación localmente + +```bash +pnpm dev +``` + +Tu aplicación está en [http://localhost:3000](http://localhost:3000). El **worker** en segundo plano se ejecuta como un proceso separado si lo deseas (opcional): + +```bash +pnpm worker +``` + +> El contenedor Docker `app` está reservado para auto-hospedaje/previews. En desarrollo, ejecuta el servidor Vite localmente para iteración más rápida. + +## Webhooks reales en desarrollo + +* **Ngrok**: `ngrok http 3000` — pega la URL de reenvío (ej. `https://xyz.ngrok-free.app/api/webhook/polar`) en el panel de Polar. +* **Cloudflare Tunnel (opcional)**: Coloca tu token de túnel en `.env` como `CLOUDFLARED_TUNNEL_TOKEN`, luego: + +```bash +docker compose --profile tunnel up -d cloudflared +``` + +> Los documentos de Polar recomiendan ngrok; Cloudflare Tunnel es una alternativa robusta con Zero Trust. Configura el que prefieras. + +## Emails + +Interfaz de Mailhog: [http://localhost:8025](http://localhost:8025) (SMTP en `mailhog:1025`). + +## Búsqueda + +* API de Meilisearch: `MEILI_HOST=http://localhost:7700` +* Sembrar o reconstruir el índice: + +```bash +pnpm run search:sync +``` + +## Trabajos en segundo plano + +* Cola: Redis (`REDIS_URL=redis://localhost:6379`) +* La recarga diaria de créditos está programada a las 03:00 UTC vía BullMQ. Llama a tu endpoint existente `routes/api/jobs/daily-credit-refill`. +* Puedes ejecutar el worker localmente: + +```bash +pnpm worker +``` + +### Worker ↔ Endpoint de la App en desarrollo + +# Por defecto `JOB_DAILY_CREDIT_REFILL_URL=http://localhost:3000/api/jobs/daily-credit-refill`. Cuando ejecutas el worker dentro de Docker, también puede alcanzar el host vía `http://host.docker.internal:3000`. + +``` diff --git a/docs/es/constructa/mastra.md b/docs/es/constructa/mastra.md new file mode 100644 index 0000000..6bae717 --- /dev/null +++ b/docs/es/constructa/mastra.md @@ -0,0 +1,253 @@ +# Integración de Mastra AI + +Este documento proporciona instrucciones completas de configuración y uso para la integración de Mastra AI en Constructa Starter. + +## Descripción General + +Constructa Starter incluye un asistente de IA consciente del repositorio impulsado por [Mastra](https://mastra.ai), un framework de agentes de IA que permite a los LLMs realizar acciones y acceder a herramientas externas. La integración presenta: + +- **Agente de Base de Código**: Un asistente de código senior que puede acceder a archivos almacenados en tu bucket MinIO/S3 +- **Integración de Herramientas**: Herramientas personalizadas para recuperar contenido de archivos desde almacenamiento de objetos +- **Interfaz de Chat**: Interfaz de chat moderna construida con componentes de [Assistant UI](https://assistant-ui.com) +- **Respuestas en Streaming**: Respuestas de IA en tiempo real con visualización de llamadas a herramientas + +## Arquitectura + +### Componentes + +1. **Agente Mastra** (`src/mastra/agents/codebase-agent.ts`) + - Impulsado por GPT-4.1-nano vía SDK de OpenAI + - Configurado con instrucciones para asistencia consciente del repositorio + - Integrado con herramientas personalizadas para acceso a archivos + +2. **Herramienta de Acceso a Archivos** (`src/mastra/tools/get-file-from-object-store.tool.ts`) + - Recupera contenido de texto UTF-8 desde buckets MinIO/S3 + - Límites de bytes configurables (por defecto: 500KB) + - Maneja truncamiento de archivos y metadatos + +3. **Capa de Almacenamiento** (`src/mastra/storage.ts`) + - Se integra con infraestructura existente de S3/MinIO + - Proporciona interfaz unificada para operaciones de archivos + +4. **Endpoint API** (`src/routes/api/chat.tsx`) + - Ruta del lado del servidor que maneja solicitudes de chat + - Transmite respuestas de IA con llamadas a herramientas + - Validación Zod para payloads de mensajes + +5. **Interfaz de Chat** (`src/routes/dashboard/chat/`) + - Interfaz de chat basada en React con autenticación + - Muestra archivos disponibles desde almacenamiento de documentos + - Transmisión de mensajes en tiempo real con visualización de llamadas a herramientas + +## Prerequisitos + +Antes de configurar Mastra, asegúrate de tener: + +- ✅ **Clave API de OpenAI** - Requerida para funcionalidad LLM +- ✅ **Configuración de MinIO/S3** - Para acceso a almacenamiento de archivos +- ✅ **Autenticación** - El usuario debe haber iniciado sesión para acceder al chat +- ✅ **Carga de Documentos** - Los archivos deben ser subidos vía página de Documentos para acceso de IA + +## Instrucciones de Configuración + +### 1. Configuración de Entorno + +Agrega tu clave API de OpenAI a tu archivo `.env`: + +```bash +# Configuración de IA +OPENAI_API_KEY="sk-your-openai-api-key-here" +``` + +### 2. Verificar Dependencias + +Los siguientes paquetes están incluidos automáticamente: + +```json +{ + "@mastra/core": "0.17.1", + "@ai-sdk/openai": "2.0.32", + "@assistant-ui/react": "^0.11.15", + "@assistant-ui/react-ai-sdk": "^1.1.0", + "@assistant-ui/react-data-stream": "^0.11.0", + "@assistant-ui/react-markdown": "^0.11.0", + "@assistant-ui/styles": "^0.2.1" +} +``` + +### 3. Acceder a la Interfaz de Chat + +1. Iniciar el servidor de desarrollo: + ```bash + pnpm dev + ``` + +2. Navegar a `/dashboard/chat` en tu navegador + +3. Iniciar sesión si se solicita + +4. Subir documentos vía `/dashboard/documents` para que la IA los referencie + +## Guía de Uso + +### Interacción Básica de Chat + +1. **Acceder al Chat**: Navegar a la sección "Chat" en la barra lateral +2. **Ver Archivos Disponibles**: La interfaz muestra archivos que has subido a tu bucket MinIO +3. **Hacer Preguntas**: Escribe preguntas sobre tu base de código o documentos subidos +4. **Referenciar Archivos**: Menciona rutas de archivos específicas (ej. `src/lib/api.ts`) para que la IA obtenga el contenido + +### Herramienta de Acceso a Archivos + +La IA puede recuperar automáticamente contenido de archivos cuando mencionas rutas de archivos. Por ejemplo: + +- "¿Qué hay en `src/components/Button.tsx`?" +- "Muéstrame el esquema de base de datos en `src/db/schema.ts`" +- "Explica la lógica de autenticación en `src/server/auth.server.ts`" + +### Visualización de Llamadas a Herramientas + +Cuando la IA usa herramientas, verás: +- **Indicadores de llamadas a herramientas** en los mensajes de chat +- **Estado de recuperación de archivos** con metadatos (bytes, estado de truncamiento) +- **Resultados de herramientas estructurados** para mejor legibilidad + +### Mejores Prácticas + +#### Referencias a Archivos +- Usar rutas de archivos exactas de la sección "Archivos disponibles" +- Incluir la ruta completa (ej. `src/routes/api/chat.tsx`) +- La IA automáticamente obtendrá y analizará el contenido de los archivos + +#### Tipos de Preguntas +- **Explicación de código**: "¿Qué hace esta función?" +- **Preguntas de arquitectura**: "¿Cómo está implementada la autenticación?" +- **Ayuda para depuración**: "¿Por qué no se está renderizando este componente?" +- **Documentación**: "Crea un README para esta característica" + +#### Gestión de Contexto +- Subir archivos relevantes antes de hacer preguntas +- Referenciar múltiples archivos en una sola conversación +- La IA mantiene el contexto a través de la conversación + +## Opciones de Configuración + +### Configuración del Agente + +El agente de base de código está configurado en `src/mastra/agents/codebase-agent.ts`: + +```typescript +export const codebaseAgent = new Agent({ + name: 'codebase-agent', + instructions: [ + 'You are a senior code assistant for this repository.', + 'When a prompt references files or code, use the get-file-from-object-store tool to retrieve the exact content before answering.', + 'Always mention the object key(s) you consulted, adapt verbosity to user directions, and escalate with follow-up questions when file context is ambiguous.', + ].join(' '), + model: openai('gpt-4.1-nano'), + tools: { + getFileFromObjectStore, + }, +}); +``` + +### Límites de Acceso a Archivos + +Configurar límites de recuperación de archivos en `src/mastra/tools/get-file-from-object-store.tool.ts`: + +```typescript +const DEFAULT_MAX_BYTES = 512_000; // límite por defecto de 500 KB +``` + +### Selección de Modelo + +Cambiar el modelo de IA modificando la configuración del agente: + +```typescript +model: openai('gpt-4'), // u otros modelos de OpenAI +``` + +## Solución de Problemas + +### Problemas Comunes + +#### "S3 bucket is not configured" +- Asegúrate de que tu configuración de MinIO/S3 sea correcta en `.env` +- Verifica que la variable de entorno `S3_BUCKET` esté establecida + +#### "No files synced yet" +- Sube documentos vía la página de Documentos primero +- Los archivos deben estar almacenados en tu bucket MinIO/S3 configurado + +#### "OpenAI API key missing" +- Agrega `OPENAI_API_KEY` a tu archivo `.env` +- Asegúrate de que la clave sea válida y tenga suficientes créditos + +#### Chat no se carga +- Verifica la consola del navegador para errores +- Verifica el estado de autenticación +- Asegúrate de que todas las variables de entorno requeridas estén establecidas + +### Modo de Depuración + +Habilita registro detallado estableciendo: + +```bash +DEBUG=mastra:* +``` + +### Consideraciones de Rendimiento + +- **Límites de Tamaño de Archivo**: Los archivos grandes se truncan automáticamente para prevenir desbordamiento de tokens +- **Limitación de Tasa**: Los límites de tasa de la API de OpenAI se aplican a todas las solicitudes +- **Caché**: Considera implementar caché de respuestas para archivos frecuentemente accedidos + +## Uso Avanzado + +### Herramientas Personalizadas + +Agregar nuevas herramientas creándolas en `src/mastra/tools/` y registrándolas en el agente: + +```typescript +// Ejemplo de herramienta personalizada +export const customTool = createTool({ + id: 'custom-tool', + description: 'Descripción de lo que hace esta herramienta', + inputSchema: z.object({ /* validación de entrada */ }), + execute: async ({ context }) => { + // Implementación de la herramienta + }, +}); +``` + +### Múltiples Agentes + +Crea agentes adicionales en `src/mastra/agents/` y regístralos en `src/mastra/index.ts`. + +### Backends de Almacenamiento Personalizados + +Extiende la capa de almacenamiento para soportar fuentes de archivos adicionales más allá de MinIO/S3. + +## Consideraciones de Seguridad + +- **Gestión de Claves API**: Nunca confirmes claves API en control de versiones +- **Acceso a Archivos**: La IA solo puede acceder a archivos en tu bucket MinIO/S3 configurado +- **Autenticación de Usuario**: La interfaz de chat requiere autenticación de usuario +- **Limitación de Tasa**: Considera implementar limitación de tasa para endpoints API + +## Contribuir + +Al extender la integración de Mastra: + +1. Seguir los patrones existentes en `src/mastra/` +2. Agregar tipos TypeScript apropiados +3. Incluir manejo de errores completo +4. Actualizar esta documentación +5. Probar con varios tipos y tamaños de archivos + +## Recursos + +- [Documentación de Mastra](https://mastra.ai/docs) +- [Documentación de Assistant UI](https://assistant-ui.com/docs) +- [Referencia de API de OpenAI](https://platform.openai.com/docs/api-reference) +- [Funciones del Servidor TanStack Start](https://tanstack.com/start/latest/docs/framework/server-functions)