wl-coder — Guía de referencia — White Label Engineering

¿Qué es wl-coder?

wl-coder es la CLI oficial de scaffolding para el ecosistema White Label. Resuelve tres problemas concretos:

Crear microservicios nuevos — genera un proyecto Go con estructura WL completa (proto, gRPC, Kubernetes, Docker) en menos de cinco minutos.
Instrumentar proyectos existentes — añade CLAUDE.md, arch/, specs/ y los comandos slash de Claude Code a cualquier repositorio.
Inspeccionar entornos de GitHub — lista y compara variables y secrets entre los environments de un repositorio.

Instalación

Prerequisitos:

Go 1.26.2 o superior
Acceso a red para descargar dependencias

go install github.com/Cencosud-Cencommerce/dc-wl-coder/cmd/coder@latest

Esto compila e instala el binario coder en $GOPATH/bin. Verificá que ese directorio esté en tu $PATH:

coder --help

Para los comandos env, también necesitás un token de GitHub con alcance repo:

export GITHUB_TOKEN=ghp_...

También podés colocarlo en un archivo .env en el directorio de trabajo; wl-coder lo carga automáticamente.

Comandos

`coder new` — Generar microservicio

Crea un microservicio WL desde el template embebido en el binario.

# Crear en un directorio nuevo
coder new orders-service

# Crear en el directorio actual (el nombre del servicio se infiere del dirname)
coder new .

El generador crea la estructura completa del proyecto y luego ejecuta los hooks de post-generación en orden:

Paso	Descripción
Instalar tools	Instala 7 herramientas protobuf/gRPC en paralelo
`buf dep update`	Actualiza dependencias de Protocol Buffers
`buf generate`	Genera código Go desde los `.proto`
`go mod tidy`	Sincroniza el módulo Go
`go get -u ./...`	Actualiza dependencias a versiones recientes
Format	`go fmt` y `buf format` en paralelo
`golangci-lint`	Verifica calidad del código

Al finalizar, imprime el árbol de archivos generados en la terminal.

Estructura generada:

<service-name>/
├── CLAUDE.md                    ← instrucciones para agentes de IA
├── foundation.md                ← contexto del proyecto
├── go.mod
├── Dockerfile
├── k8s/                         ← manifiestos de Kubernetes
├── proto/                       ← definiciones Protocol Buffers
├── internal/
│   ├── application/             ← handlers gRPC
│   ├── core/                    ← lógica de negocio
│   ├── domain/                  ← entidades de dominio
│   └── platform/                ← clientes externos
└── arch/
    ├── adrs/                    ← ADRs base de la plataforma WL
    └── agdrs/

`coder instrument` — Instrumentar proyecto existente

Añade el scaffolding de flujo de trabajo AGF a un repositorio que ya existe.

# Instrumentar el directorio actual
coder instrument .

# Instrumentar un path específico
coder instrument ./mi-servicio

Flags:

Flag	Valores	Default	Descripción
`--preset`	`wl`, `generic`	`wl`	Preset de instrumentación

Preset wl (default) — incluye los ADRs base de la plataforma (ADR-000 a ADR-004), un CLAUDE.md con convenciones WL, y los comandos slash completos.

Preset generic — estructura básica sin los ADRs ni las convenciones específicas de WL. Útil para proyectos fuera del ecosistema.

Archivos que genera:

<repo>/
├── CLAUDE.md
├── arch/
│   ├── adrs/
│   │   ├── README.md
│   │   └── ADR-00X-*.md         ← ADRs base (solo con preset wl)
│   ├── agdrs/
│   └── drafts/
├── specs/
│   └── README.md
└── .claude/
    ├── commands/                 ← comandos slash (spec:*, adr:*, agdr:*)
    └── skills/                   ← skills (architecture-context, agdr-awareness)

`coder env list` — Listar entornos

Lista todos los GitHub Environments de un repositorio en la organización Cencosud-Cencommerce.

coder env list dc-wl-groceries-backend

Muestra el nombre de cada environment con sus fechas de creación y última actualización.

`coder env show` — Inspeccionar y comparar entornos

Muestra las variables y secrets de uno o más environments. Cuando se pasan varios, genera automáticamente una sección de diff con las diferencias.

# Ver un environment
coder env show dc-wl-groceries-backend staging

# Comparar dos environments
coder env show dc-wl-groceries-backend staging production

# Comparar tres environments con valores completos
coder env show dc-wl-groceries-backend dev staging production --full

Flags:

Flag	Descripción
`--full`	Muestra valores completos de las variables (por defecto trunca a 40 caracteres)

Note

Los secrets de GitHub nunca exponen sus valores por la API. env show muestra los nombres de los secrets, no sus valores.

Configuración

Variable	Requerida	Descripción
`GITHUB_TOKEN`	Solo para `env`	Token de GitHub con alcance `repo`

El token puede estar como variable de entorno o en un archivo .env en el directorio de trabajo.

Flujo típico de trabajo

Escenario 1 — Servicio nuevo desde cero:

# 1. Crear el scaffold
coder new grocery-checkout-service

# 2. Entrar al directorio generado
cd grocery-checkout-service

# 3. El proyecto ya tiene CLAUDE.md, ADRs, y comandos slash listos
# Abrir Claude Code y comenzar con /spec:explore

Escenario 2 — Agregar AGF a un proyecto existente:

cd ~/proyectos/mi-servicio-existente

# Agregar instrumentación con preset WL
coder instrument .

# Verificar que se generaron los archivos
ls arch/adrs/
ls .claude/commands/

Escenario 3 — Revisar diferencias entre entornos antes de un deploy:

# Comparar staging vs producción para detectar variables faltantes
coder env show dc-wl-groceries-backend staging production

# Ver todos los valores completos
coder env show dc-wl-groceries-backend staging production --full

Desarrollo del propio wl-coder

Para contribuir al tool o ejecutarlo sin compilar:

# Ejecutar sin compilar (para desarrollo)
make run ARGS="new test-service"

# Verificar calidad de código
make lint

# Limpiar dependencias
make tidy

# Instalar herramientas de desarrollo (primera vez)
make tools

Los cambios al tool siguen el mismo proceso AGF que cualquier otro servicio WL: /spec:explore → /spec:propose → /spec:apply → /spec:approve. Las decisiones de arquitectura se documentan en arch/adrs/ antes de implementarse.

wl-coder — Guía de referencia