Stack Tecnológico de Wiedii

⚠️ Verificar versiones antes de usar — los números de versión de imágenes, runtimes y herramientas mencionados en esta nota pueden estar desactualizados. Siempre consultar la versión estable más reciente antes de usarlos en un proyecto. Ver politicas-core.

Esta nota define los lenguajes, runtimes y herramientas que Wiedii usa oficialmente. Cualquier tecnología fuera de esta lista requiere aprobación del Tech Lead antes de incorporarse a un proyecto. Ver gestion-herramientas-brew-mise para la política de instalación.

---

Lenguajes de programación

Lenguaje	Uso principal	Notas
Go	Servicios backend, CLIs, binarios compilados	Preferido para herramientas internas y servicios de alta performance
PHP	Aplicaciones web, APIs REST	Proyectos legacy y nuevos proyectos web cuando aplica
JavaScript / TypeScript	Frontend, SSR, APIs Node, CLIs JS	TypeScript siempre — nunca JS plano en código nuevo
Python	Scripts, automatización, data, ML	FastAPI para APIs Python

Lenguajes que NO usamos

Lenguaje	Motivo
Java	No forma parte del stack de Wiedii
Ruby	No forma parte del stack de Wiedii
Rust	No es lenguaje de desarrollo en Wiedii — solo se usan herramientas escritas en Rust (bat, eza, fd, ripgrep, starship)
C / C++	Sin proyectos activos

Herramientas escritas en Rust como bat, eza, fd, ripgrep, sd, gping y starship son parte del entorno de desarrollo estándar — pero como binarios de CLI, no como lenguaje de programación de los proyectos. Ver herramientas-rust.

---

Runtimes y entornos

Tecnología	Rol	Version manager	Notas
Bun	Package manager	mise	bun install, bun run, bun test — gestión de deps y scripts
Node.js	Runtime de ejecución	mise	El proceso que corre en producción y en Docker
Go	Runtime + compilador	mise	Versión por proyecto en mise.toml
PHP	Runtime + FPM	dev container (NO local)	PHP no se instala en el host — se trabaja en un VS Code Dev Container. Ver nota abajo
Python	Runtime	mise	Versión por proyecto en mise.toml

PHP no se instala localmente — se usa un VS Code Dev Container. A diferencia del resto del stack (Go/Node/Python por mise), PHP no va por mise en el host. Gestionar la versión de PHP por proyecto con mise en macOS implica recompilar PHP constantemente y arrastrar muchas dependencias del sistema (extensiones, libs) → alto costo de mantenimiento. En su lugar, cada proyecto PHP trae un .devcontainer/devcontainer.json y se desarrolla dentro del contenedor: PHP, Composer, las extensiones y el LSP corren ahí (el editor abre el repo dentro del dev container). La imagen base sigue la convención de docker (php:8.3-fpm-alpine). Por eso el LSP de PHP no se cablea en Claude Code (lo sirve el editor dentro del contenedor).

LSP de Go (gopls) y build tags — pasar los tags por .lsp.json. Claude Code arranca gopls para archivos .go. Por defecto corre sin los build tags del proyecto, así que en repos con archivos bajo //go:build <tag> (p. ej. //go:build e2e para tests de integración, o //go:build darwin por plataforma) gopls no resuelve el paquete y emite falsos No packages found for open file … (go list) en cada lectura/edición — aunque go vet -tags e2e y go test -tags e2e pasen limpio. Es ruido que puede inducir al agente a "arreglar" errores inexistentes. Solución: declarar los tags del repo en su .lsp.json (raíz), pasándolos a gopls por initializationOptions.build.buildFlags:

{
  "go": {
    "command": "gopls",
    "initializationOptions": { "build.buildFlags": ["-tags=e2e"] },
    "extensionToLanguage": { ".go": "go" }
  }
}

Ajustar -tags=… a los build tags reales del repo (varios: -tags=integration,e2e). El plugin wiedii-dev trae su propio .lsp.json baseline que, según la documentación de plugins de Claude Code, debería activarse solo con instalar el plugin — pero se observó empíricamente que no ocurre de forma confiable en repos consumidores (squadlinx-frontend: el LSP del plugin nunca arrancó; causa raíz sin confirmar). El .lsp.json a nivel de repo (scaffoldeado por repo-setup) sigue siendo el mecanismo confiable, y es en todo caso necesario aquí — un baseline genérico de plugin nunca puede saber los build tags de un repo puntual. El binario gopls debe estar en el PATH. Ver repo-setup para el scaffolding del repo.

Bun como PM, Node.js como runtime — la distinción clave

Wiedii usa Bun exclusivamente como package manager (bun install, bun run, bun test, bun add) pero Node.js como runtime de ejecución en producción y en contenedores Docker.

Motivo principal: compatibilidad de librerías con bindings nativos — especialmente librerías de procesamiento de imágenes (sharp, canvas, etc.) que requieren el runtime de Node.js para funcionar correctamente.

Segundo motivo (entorno de CI): el motor JS de Bun usa instrucciones AVX que algunos runners con CPU antigua no soportan, y el build revienta con SIGILL / CPU lacks AVX support (el bun install sí corre; falla el build pesado). En ese caso se instala con Bun y se compila bajo Node con node --run. Ver docker → sección 16 "Caso especial — Bun no puede ejecutar el build".

# Desarrollo y CI: bun gestiona las deps y corre los scripts
bun install
bun run build
bun run dev

# Producción y Docker: Node.js ejecuta el artefacto compilado
node dist/index.js

Bun es el package manager estándar — nunca npm ni yarn como herramienta de desarrollo. La política completa está en politicas-core.

---

Infraestructura y plataformas

Área	Tecnología
Contenedores	Docker (BuildKit)
Entorno local	OrbStack — reemplaza Docker Desktop
CI/CD	GitLab CI/CD
Registro de imágenes	GitLab Container Registry
Gestión de repos	GitLab (gitlab.wiedii.co)
Monorepo JS/TS	NX

---

Testing por lenguaje

Lenguaje	Unit / Integration	Property-based	E2E
JS/TS (CLI)	bun:test	fast-check	—
JS/TS (web/API)	Vitest (en evaluación)	fast-check	Playwright
Go	testing + testify	—	—
Python	pytest	hypothesis	—
PHP	PHPUnit	—	—

Ver trofeo-testing para la metodología y distribución de esfuerzo. Ver bun-testing para el detalle de bun:test y sus patrones.

---

Linters y formatters

Lenguaje	Linter	Formatter
JS/TS	ESLint (flat config) + TypeScript strict	Prettier
Python	ruff (lint + format) + mypy	ruff format
Go	golangci-lint	gofmt / goimports
PHP	PHPStan	PHP CS Fixer
TOML	taplo	taplo fmt
Shell	shellcheck	shfmt
Docker	hadolint	—

Ver linters para configuraciones exactas y políticas por stack.

---

Convenciones de código

Convención	Referencia
Commits	Conventional Commits con emoji — commits
Versionado	SemVer — versioning
Nombres de repos	Title Case display / kebab-case path — gitlab-naming
Estructura de repos nuevos	repo-setup
Git workflow	Git Flow — git-flow
Política de branches	branch-protection

---

Imágenes Docker base por lenguaje

Para builds de producción, siempre usar imágenes Alpine o slim para reducir la superficie de ataque. Ver docker para patrones completos de multi-stage y cache.

Lenguaje	Imagen de build	Imagen de runtime	Nota
Go	golang:1.24-alpine	alpine:3.21 o scratch	—
JS/TS	node:22-alpine (con bun instalado)	node:22-alpine	Bun instala deps, Node ejecuta
Python	python:3.12-slim	python:3.12-slim	—
PHP	php:8.3-fpm-alpine	php:8.3-fpm-alpine	—

JS/TS: la imagen base es node:22-alpine. Bun se instala en el build stage para gestionar dependencias (bun install). El runtime stage ejecuta con node — no con bun. Esto garantiza compatibilidad con librerías que requieren el runtime de Node.js.

Usuario de runtime por imagen — verificado contra Dockerfiles oficiales:

Imagen	Usuario	UID	Pre-existe	Acción
golang:1.24-alpine + alpine:3.21	app	1001	No	Crear manualmente
node:22-alpine	node	1000	Si, pero inactivo	USER node
python:3.12-slim	app	1001	No	Crear manualmente
php:8.3-fpm-alpine	www-data	82	Si	USER www-data + config pool
scratch (Go estático)	—	65534	No aplica	USER 65534:65534

---

Referencias

• politicas-core — reglas de desarrollo aplicables a todos los proyectos
• herramientas-por-rol — qué instala cada rol del equipo
• linters — configuración detallada de linters por stack
• docker — buenas prácticas de build, multi-stage y multi-plataforma
• trofeo-testing — metodología de testing por tipo de proyecto