{"_rev":"4-72df55c758ece10e3c5736e13003ce51","time":{"created":"2025-10-15T11:25:41.945Z","modified":"2025-10-15T11:25:42.542Z","1.0.1":"2025-10-15T10:12:22.548Z","1.0.0":"2025-10-15T11:25:42.250Z"},"_id":"@astillero-digital/astillero-api","name":"@astillero-digital/astillero-api","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@astillero-digital/astillero-api","version":"1.0.0","description":"Plantilla para API RESTful del Astillero Digital (Submarino Modular)","bin":{"astillero-api":"cli.js"},"main":"src/server.ts","scripts":{"dev":"tsx watch src/server.ts","start":"tsx src/server.ts","db:generate":"drizzle-kit generate","db:push":"drizzle-kit push","db:seed:make":"tsx src/scripts/create-seed.ts","db:seed:make-all":"tsx src/scripts/create-seeds-all.ts","db:seed":"tsx src/scripts/run-seed.ts","crud:forge":"tsx src/scripts/forja-crud.ts","crud:forge:all":"tsx src/scripts/forja-crud-all.ts","swagger:update":"tsx src/scripts/update-swagger.ts","setup:scaffold":"tsx src/scripts/setup-scaffold.ts","reset:scaffold":"tsx src/scripts/reset-scaffold.ts","test":"vitest run","test:watch":"vitest","lint":"pnpm run lint:eslint && pnpm run lint:drizzle","lint:eslint":"eslint . --ext .ts","lint:drizzle":"drizzle-kit check","lint:fix":"eslint . --ext .ts --fix","format":"prettier --write .","format:check":"prettier --check ."},"keywords":["api","template","express","drizzle","astillero-digital"],"author":{"name":"Astillero Digital"},"license":"ISC","dependencies":{"cors":"^2.8.5","dotenv":"^16.4.5","drizzle-orm":"^0.44.6","drizzle-zod":"^0.8.3","express":"^4.19.2","express-rate-limit":"^8.1.0","helmet":"^8.1.0","pg":"^8.11.5","swagger-jsdoc":"^6.2.8","swagger-ui-express":"^5.0.0","zod":"^3.23.8"},"devDependencies":{"@eslint/js":"^9.37.0","@types/supertest":"^6.0.3","@typescript-eslint/eslint-plugin":"^8.46.0","@typescript-eslint/parser":"^8.46.0","drizzle-kit":"^0.31.5","eslint":"^9.37.0","eslint-config-prettier":"^10.1.8","globals":"^16.4.0","nodemon":"^3.1.0","prettier":"^3.6.2","supertest":"^7.1.4","tsx":"^4.16.0","typescript-eslint":"^8.46.0","vitest":"^3.2.4"},"_id":"@astillero-digital/astillero-api@1.0.0","gitHead":"1ba23fd07d0b8457629ebc3a6381a36f3fdd5c5e","_nodeVersion":"20.12.2","_npmVersion":"10.9.3","dist":{"integrity":"sha512-FMGI3oWw+Mm9WxEaXMUTvdqktC1wQySGa28yt9AQPBimM8uG54ruEojOjq2Zn7ouMWIwAEiIyrR3+NbPs/3/bg==","shasum":"70d049dae26e6fc1db3912bcaf092f4ee1eb7748","tarball":"https://registry.npmjs.org/@astillero-digital/astillero-api/-/astillero-api-1.0.0.tgz","fileCount":46,"unpackedSize":179620,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDC4zZiuCpVN+XYuN5L33EeY8FA9pPlI8ewaTUGy/fNWwIhAJuGW1NWRhT7zx2/T9UdIOxm+lM1qgsNqv0S4WeR/Qa8"}]},"_npmUser":{"name":"ccisnerosad_work","email":"carloscisnerosad@gmail.com"},"directories":{},"maintainers":[{"name":"ccisnerosad","email":"carlosalerta1992@gmail.com"},{"name":"ccisnerosad_work","email":"carloscisnerosad@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/astillero-api_1.0.0_1760527542033_0.1776229017299198"},"_hasShrinkwrap":false}},"maintainers":[{"name":"ccisnerosad","email":"carlosalerta1992@gmail.com"},{"name":"ccisnerosad_work","email":"carloscisnerosad@gmail.com"}],"description":"Plantilla para API RESTful del Astillero Digital (Submarino Modular)","keywords":["api","template","express","drizzle","astillero-digital"],"author":{"name":"Astillero Digital"},"license":"ISC","readme":"# 🌊 Plantilla API REST — Submarino Modular\r\n\r\nPlantilla oficial del Astillero Digital para creación acelerada de servicios API RESTful. El repositorio ofrece una base modular, tipada y documentada lista para construir microservicios sobre PostgreSQL.\r\n\r\n## Tabla de contenidos\r\n\r\n- [🌊 Plantilla API REST — Submarino Modular](#-plantilla-api-rest--submarino-modular)\r\n  - [Tabla de contenidos](#tabla-de-contenidos)\r\n  - [Visión general](#visión-general)\r\n  - [Características principales](#características-principales)\r\n  - [Arquitectura y estructura](#arquitectura-y-estructura)\r\n  - [Puesta en marcha (zarpar)](#puesta-en-marcha-zarpar)\r\n  - [Variables de entorno](#variables-de-entorno)\r\n  - [Scripts disponibles](#scripts-disponibles)\r\n  - [Manejo de base de datos y seeds](#manejo-de-base-de-datos-y-seeds)\r\n    - [Generar seeds](#generar-seeds)\r\n    - [Ejecutar seeds](#ejecutar-seeds)\r\n  - [Forja de CRUDs](#forja-de-cruds)\r\n    - [Modo puntual (interactivo)](#modo-puntual-interactivo)\r\n    - [Modo masivo (batch)](#modo-masivo-batch)\r\n  - [Guía paso a paso](#guía-paso-a-paso)\r\n  - [Rutas expuestas](#rutas-expuestas)\r\n  - [Calidad y aseguramiento](#calidad-y-aseguramiento)\r\n  - [Documentación complementaria](#documentación-complementaria)\r\n  - [Hoja de ruta](#hoja-de-ruta)\r\n\r\n## Visión general\r\n\r\n- Propósito: reducir el tiempo de arranque y estandarizar la arquitectura backend del Astillero Digital.\r\n- Enfoque: Express + Drizzle + Zod + Swagger sobre Node.js 20, con utilidades CLI para seeds y generación de CRUDs.\r\n- Estado: plantilla base estable con salud, validaciones, middlewares de seguridad y tooling para schema-first.\r\n\r\n## Características principales\r\n\r\n- ✅ **Configuración centralizada**: validación de variables con Zod (`src/config/environment.ts`).\r\n- 🛡️ **Seguridad por defecto**: CORS configurable, Helmet y Rate Limiting (`src/middlewares/security.ts`).\r\n- 🔎 **Validación declarativa**: helper `withValidation` para esquemas Zod (`src/middlewares/validation.ts`).\r\n- 🧭 **Arquitectura modular**: rutas versionadas en `src/api/v1`, controladores thin, services listos para integrarse.\r\n- 🗄️ **ORM moderno**: Drizzle ORM con schemas versionados en `src/db/schemas/**`.\r\n- ⚙️ **Tooling CLI**: scripts para generar seeds (`create-seed`, `create-seeds-all`) y CRUDs (`forja-crud`, `forja-crud-all`).\r\n- 📚 **Documentación integrada**: referencia de API con Swagger y manuales en `docs/`.\r\n\r\n## Arquitectura y estructura\r\n\r\n```text\r\nsrc/\r\n  api/\r\n    v1/\r\n      controllers/       # Controladores REST por recurso\r\n      routes/            # Routers Express versionados\r\n      validators/        # Esquemas Zod generados por la forja\r\n  config/                # Environment, swagger y otros settings globales\r\n  db/\r\n    client.ts            # Cliente Drizzle\r\n    schema.ts            # Re-export del schema activo\r\n    schemas/             # Schemas versionados por alias\r\n  middlewares/           # Seguridad, validación, manejo de errores\r\n  scripts/\r\n    shared/              # Utilidades comunes (schema parsing, forja, artefactos)\r\n    seeds/               # Núcleo del tooling de seeds\r\nserver.ts                 # Bootstrap Express\r\n```\r\n\r\nLos detalles arquitectónicos, convenciones y diagramas se documentan en el [Boceto Técnico](./docs/Boceto_tecnico.md).\r\n\r\n## Puesta en marcha (zarpar)\r\n\r\nPrerrequisitos:\r\n\r\n- Node.js 20 o superior\r\n- pnpm\r\n- PostgreSQL accesible (local o remoto)\r\n\r\nPasos iniciales (PowerShell):\r\n\r\n1. Copia el archivo de entorno y ajústalo:\r\n\r\n   ```powershell\r\n   Copy-Item .env.example .env\r\n   notepad .env\r\n   ```\r\n\r\n2. Instala dependencias:\r\n\r\n   ```powershell\r\n   pnpm install\r\n   ```\r\n\r\n3. Aplica el schema a la base seleccionada:\r\n\r\n   ```powershell\r\n   pnpm db:push\r\n   ```\r\n\r\n4. Arranca en modo desarrollo (watch):\r\n\r\n   ```powershell\r\n   pnpm dev\r\n   ```\r\n\r\n5. (Recomendado) Protege los archivos de andamiaje del tooling:\r\n\r\n  ```powershell\r\n  pnpm setup:scaffold\r\n  ```\r\n\r\n  Esto aplica `git update-index --skip-worktree` sobre `docs/swagger.json`, `src/api/v1/routes/index.ts` y `src/db/schema.ts`. Si necesitas revertirlo en algún momento, ejecuta `pnpm reset:scaffold`.\r\n\r\nServidor disponible en `http://localhost:3000`.\r\n\r\n## Variables de entorno\r\n\r\nLa validación ocurre al boot via `src/config/environment.ts`. Campos clave:\r\n\r\n| Variable | Descripción | Valor por defecto |\r\n| --- | --- | --- |\r\n| `PORT` | Puerto HTTP del servidor | `3000` |\r\n| `NODE_ENV` | Entorno (development, production, test) | `development` |\r\n| `DATABASE_URL` | Cadena completa para PostgreSQL | — |\r\n| `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME` | Alternativa granular a `DATABASE_URL` | — |\r\n| `CORS_ORIGINS` | Lista separada por comas | `*` en desarrollo |\r\n| `RATE_LIMIT_WINDOW_MS`, `RATE_LIMIT_MAX` | Configuración de rate limiting | `60000`, `100` |\r\n\r\nConsulta `.env.example` para el listado completo.\r\n\r\n## Scripts disponibles\r\n\r\n| Comando | Descripción |\r\n| --- | --- |\r\n| `pnpm dev` | Ejecuta el servidor con recarga (`tsx watch`). |\r\n| `pnpm start` | Levanta el servidor una sola vez (`tsx`). |\r\n| `pnpm lint` | Ejecuta ESLint y valida el schema con Drizzle Kit. |\r\n| `pnpm lint:eslint` / `pnpm lint:fix` | Revisión de estilo con ESLint (y autofix con `lint:fix`). |\r\n| `pnpm lint:drizzle` | Carga el schema con `drizzle-kit check` para detectar errores de ejecución. |\r\n| `pnpm test` / `pnpm test:watch` | Suite de Vitest + Supertest. |\r\n| `pnpm format` / `pnpm format:check` | Formateo con Prettier. |\r\n| `pnpm db:generate` | Genera migraciones Drizzle desde el schema. |\r\n| `pnpm db:push` | Sincroniza el schema actual con la base. |\r\n| `pnpm db:seed:make` | Crea un seed puntual basado en una tabla. |\r\n| `pnpm db:seed:make-all` | Genera seeds para todas las tablas detectadas. |\r\n| `pnpm db:seed` | Ejecuta seeds (individual o colección). |\r\n| `pnpm crud:forge` | Inicia la forja de CRUD para una tabla (modo CLI interactivo). |\r\n| `pnpm crud:forge:all` | Genera CRUDs para múltiples tablas (modo batch con filtros). |\r\n| `pnpm swagger:update` | Regenera el JSON de Swagger en `docs/swagger.json`. |\r\n| `pnpm setup:scaffold` | Marca archivos de andamiaje con `git update-index --skip-worktree`. |\r\n| `pnpm reset:scaffold` | Revierte los flags `skip-worktree` del andamiaje. |\r\n\r\n## Manejo de base de datos y seeds\r\n\r\n### Generar seeds\r\n\r\n- **Seed puntual**: `pnpm db:seed:make -- --table users` → crea `src/db/seeds/<alias>/users-seed.ts`.\r\n- **Semilla masiva**: `pnpm db:seed:make-all -- --yes` → recorre el schema activo y produce un seed por tabla.\r\n- Parámetros frecuentes:\r\n  - `--database <alias>` para alternar entre schemas definidos en `src/db/schemas`.\r\n  - `--filter users orders` para restringir la generación.\r\n  - `--output <ruta>` para personalizar la ubicación.\r\n\r\n### Ejecutar seeds\r\n\r\n- `pnpm db:seed -- users` → ejecuta un seed puntual.\r\n- `pnpm db:seed -- --all` → ejecuta todos los seeds detectados.\r\n- Opcionales: `--database`, `--dir` para ajustar origen o destino.\r\n\r\nGuía completa en [`docs/Seeds_tooling.md`](./docs/Seeds_tooling.md).\r\n\r\n## Forja de CRUDs\r\n\r\nLa herramienta de forja genera validadores, controladores y rutas a partir del schema Drizzle.\r\n\r\n### Modo puntual (interactivo)\r\n\r\n```powershell\r\npnpm crud:forge\r\n```\r\n\r\n- Muestra las tablas disponibles con badges:\r\n  - `[forjado]`: CRUD completo ya existe.\r\n  - `[parcial - faltan ...]`: hay archivos faltantes.\r\n  - `[nuevo]`: no se han generado artefactos.\r\n- Selecciona por número, por nombre o provee `--table usuarios` directamente.\r\n- Flags disponibles:\r\n  - `--id-column uuid` para utilizar otra columna primaria.\r\n  - `--force` para sobrescribir archivos existentes.\r\n  - `--schema <ruta>` y `--database <alias>` para seleccionar schema.\r\n\r\n### Modo masivo (batch)\r\n\r\n```powershell\r\npnpm crud:forge:all -- --filter usuario --filter orden --include-existing --force\r\n```\r\n\r\n- Recorre el schema y genera CRUDs para múltiples tablas.\r\n- `--filter` permite especificar tokens a incluir (puedes usar varios).\r\n- `--include-existing` vuelve a generar recursos aunque ya existan.\r\n- `--dry-run` imprime la lista de tablas afectadas sin tocar archivos.\r\n- `--id-column` y `--force` se comportan igual que en el modo puntual.\r\n- Al finalizar, la CLI ofrece actualizar automáticamente la especificación Swagger (`docs/swagger.json`).\r\n- Tras la ejecución puedes optar por refrescar la documentación Swagger directamente desde la forja.\r\n\r\nTodos los artefactos se ubican en:\r\n\r\n- Validadores: `src/api/v1/validators/<slug>.validator.ts`\r\n- Controladores: `src/api/v1/controllers/<slug>.controller.ts`\r\n- Rutas: `src/api/v1/routes/<slug>.route.ts`\r\n- Registro automático en `src/api/v1/routes/index.ts`\r\n\r\n## Guía paso a paso\r\n\r\n- **Arranque**: clona el repo, configura `.env` y ejecuta `pnpm install` seguido de `pnpm db:push` para validar la conexión.\r\n- **Modelado**: define tablas en `src/db/schemas/<alias>/schema.ts` y re-exporta desde `src/db/schema.ts`.\r\n- **Generación**: usa `pnpm crud:forge` o `pnpm crud:forge:all` para crear validadores, controladores y rutas.\r\n- **Datos**: genera seeds con `pnpm db:seed:make` o `pnpm db:seed:make-all` y ejecútalos con `pnpm db:seed`.\r\n- **Calidad**: escribe pruebas en `tests/`, documenta en Swagger y corre `pnpm test`, `pnpm lint` y `pnpm format:check`.\r\n\r\nConsulta la guía detallada en [`docs/Guia_construccion_api.md`](./docs/Guia_construccion_api.md) para seguir el flujo con consejos adicionales y enlaces rápidos.\r\n\r\n## Rutas expuestas\r\n\r\n- API base: `http://localhost:3000/api/v1`\r\n- Salud: `GET /api/v1/health` → responde `{ status: \"ok\", timestamp: ... }` y confirma conexión a la base.\r\n- Swagger UI: `http://localhost:3000/api-docs`\r\n\r\nLa documentación OpenAPI se define en `src/config/swagger.ts` y puede enriquecerse conforme se agreguen routers.\r\n\r\n## Calidad y aseguramiento\r\n\r\n- `pnpm test` ejecuta pruebas unitarias/integración (Vitest + Supertest).\r\n- `pnpm lint` valida estilo y errores comunes de TypeScript.\r\n- `pnpm format:check` verifica formato estándar con Prettier.\r\n- Se recomienda complementar con pruebas propias al extender la plantilla.\r\n\r\n## Documentación complementaria\r\n\r\n- [Manifiesto del Proyecto](./docs/Manifiesto_del_Proyecto.md): objetivos, alcance y pactos de tripulación.\r\n- [Boceto Técnico](./docs/Boceto_tecnico.md): arquitectura detallada, diagramas y convenciones.\r\n- [Procedimiento de Desarrollo](./docs/Desarrollo_de_Software.md): fases, protocolos y checklist operativo.\r\n- [Bitácora de Navegación](./docs/Bitacora_de_navegacion.md): registro histórico de decisiones y hitos.\r\n- [Seeds tooling](./docs/Seeds_tooling.md): referencia extendida del generador de seeds.\r\n- [Forja tooling](./docs/Forja_tooling.md): guía completa del generador de CRUDs.\r\n- [Guía paso a paso](./docs/Guia_construccion_api.md): bitácora para construir módulos API desde cero.\r\n\r\n## Hoja de ruta\r\n\r\n- Integrar módulos opcionales (autenticación JWT, logging avanzado, auditoría).\r\n- Extender soporte de bases de datos (SQLite, PlanetScale/MySQL).\r\n  \r\n---\r\n\r\n¡Que tengas una excelente travesía! ⚓\r\n","readmeFilename":"README.md"}