wietoo — CLI nativa de Wiedii: commits, releases y publicación de paquetes (sin Node)

⚠️ Verificar versiones antes de usar — la versión de wietoo pinneada en los ejemplos de esta nota puede estar desactualizada. Ver la sección Qué versión usar y politicas-core.

🎯 Para quién es esta guía. Cualquier persona del equipo que necesite hacer un commit en un repositorio Wiedii — no necesitas experiencia previa con la terminal, cada comando de esta guía trae la explicación de qué hace y qué vas a ver en pantalla. Si es tu primera semana y todavía no tienes el equipo configurado, primero completa guia-nuevo-dev; esta guía asume que ya tienes mise y un repo clonado.

Qué es wietoo, en una frase

wietoo es un programa — una CLI (command-line interface: una herramienta que se usa escribiendo comandos en la terminal en vez de hacer clic en botones) — que hace dos cosas en todos los repositorios de Wiedii:

Revisa automáticamente que cada commit y cada rama cumplan las reglas de la empresa (nombre de rama, formato del mensaje, longitud, emoji, etc.). Si algo no cumple, no te deja continuar y te dice exactamente qué corregir.
Te ayuda a escribir el mensaje del commit con un asistente de preguntas y respuestas (wietoo commit) — no necesitas memorizar el formato de memoria.
Corta releases y publica — binarios a GitLab (y a S3 para quien lo necesite) y paquetes npm — con wietoo release y wietoo publish packages, sin Node ni scripts sueltos por fuera del binario.

wietoo reemplaza a dos herramientas antiguas que usaba Wiedii: czg (el asistente de commits) y commitlint (el validador). Ver la nota de czg para lo que hacía antes.

La diferencia clave frente a esas dos: wietoo es un solo archivo ejecutable, sin Node.js. No necesita npm install, no crea una carpeta node_modules, no depende de package.json. Funciona exactamente igual en un repo de Go, de Python, de Terraform o en un repositorio que solo tiene documentación — antes, esos repos tenían que arrastrar todo el tooling de Node solo para poder validar sus commits.

ℹ️ "wietoo" no es un nombre nuevo — este binario es la reescritura completa del wietoo original. Antes de esta CLI en Go existía un proyecto homónimo, wiedii-registry/wietoo (un monorepo Nx/Bun en GitLab), cuyo paquete npm @wiedii-registry/wietoo-scripts hacía en JavaScript/Node lo mismo que hoy hace wietoo-cli: validar branches y commits. wietoo-cli ya superó esa paridad — replicó también su comando de publicación de paquetes (wietoo publish packages, ver más abajo) y agregó capacidades que el original en JS nunca tuvo, como la distribución de binarios de release vía S3 (ver Publicar binarios de release en S3 más abajo). Si ves documentación o código que asuma que "wietoo" todavía depende de Node/Bun para funcionar, está desactualizada — verifícalo contra este repo (wiedii-registry/wietoo-cli).

Antes de empezar — glosario de dos minutos

Si nunca usaste una terminal, estos son los únicos conceptos que necesitas para seguir esta guía:

Término	Qué significa
Terminal	Una ventana donde escribes comandos de texto en vez de hacer clic. En Wiedii se usa Warp por defecto (ver guia-nuevo-dev).
Comando	Una línea de texto que escribes y ejecutas presionando Enter. En esta guía, cada bloque de código gris es algo que puedes copiar y pegar tal cual.
Repositorio (repo)	La carpeta de un proyecto controlada por Git — el sistema que guarda el historial de cambios del código.
Commit	Un "guardado" del código con un mensaje que explica qué cambió y por qué.
Rama (branch)	Una línea de trabajo independiente dentro del repo (p. ej. `feature/0001-mi-cambio`).
Hook	Un script que se ejecuta automáticamente en un momento concreto de Git (p. ej. justo antes de crear un commit). No lo ejecutas tú — se dispara solo.
Wizard / asistente	Un modo interactivo donde el programa te hace preguntas una por una en vez de esperar que escribas todo de una vez. `wietoo commit` es un wizard.
CLI	Command-line interface — cualquier programa que se usa desde la terminal, como `wietoo`, `git` o `mise`.
mise	El gestor de herramientas de Wiedii: instala automáticamente la versión correcta de cada programa (incluido `wietoo`) al entrar a la carpeta del proyecto. Ver mise.
Binario nativo	Un programa ya compilado para tu sistema (macOS/Linux) que arranca directo, sin necesitar instalar aparte el lenguaje en el que fue escrito.
Runtime	El programa que debe estar instalado para poder ejecutar el código de un lenguaje (p. ej. Node.js ejecuta JavaScript). Un binario nativo no necesita esto.
Footer (del commit)	Una línea extra al final del mensaje de un commit, después del texto principal — en Wiedii se usa para anotar la tarea relacionada (`closed #123`).
SOC (SOC I/II)	Un tipo de auditoría de seguridad que revisa la gestión de cambios: cada cambio en producción debe poder rastrearse a una tarea autorizada. Por eso cada commit conecta con una tarea de Squadlinx.

Por qué la empresa lo usa

Razón	Explicación
Un solo estándar para todos los stacks	El mismo comando (`wietoo commit`) y las mismas reglas aplican en un repo Go, PHP, JS/TS, Python o Terraform. Antes cada stack necesitaba su propia copia de czg + commitlint.
Repos más livianos	Un repo que no es JS/TS ya no necesita `package.json` / `node_modules` / `bun.lock` solo para poder hacer commits.
Hooks más rápidos	Un binario nativo arranca casi instantáneo; no hay que levantar un runtime de Node en cada commit.
Trazabilidad para auditoría (SOC)	El footer `closed #<id>` conecta cada commit con la tarea de Squadlinx que lo originó — ver trazabilidad-commits-soc.
Repos privados sin fricción	wietoo se distribuye vía `mise`, igual que el resto de herramientas del proyecto — no hay que instalar nada "a mano".

Cómo saber si tu proyecto ya lo tiene activo

La mayoría de los repos Wiedii ya lo tienen — es parte de la configuración compartida de hooks (ver wiedii-configs). Para comprobarlo:

cd la-carpeta-de-tu-proyecto
wietoo version self   # ✅ imprime algo como 0.4.0

Si ves command not found: wietoo, significa que mise todavía no instaló las herramientas del proyecto — sigue la sección Cómo se activa en un proyecto.

mise trust && mise run setup   # instala todas las herramientas del mise.toml, incluido wietoo
wietoo version self            # ahora sí debería funcionar

💡 No necesitas instalar wietoo "a mano". Al igual que bun o lefthook, mise lo descarga solo la primera vez que entras a un proyecto que lo declara en su mise.toml — ver mise.

El día a día — cómo hacer un commit con wietoo

Este es el único flujo que necesita el 95% del equipo. El resto de la guía (configuración, releases, migración) es para quien administra el repositorio.

git add .          # marca los archivos que quieres incluir en el commit
wietoo commit      # abre el asistente interactivo

El asistente te hace estas preguntas, en este orden:

Tipo de cambio — eliges de una lista con flechas ↑/↓ y Enter:

Tipo	Emoji	Cuándo elegirlo
`feat`	✨	Agregaste algo nuevo
`fix`	🐛	Corregiste un error
`docs`	📝	Solo cambiaste documentación
`style`	💄	Formato, sin cambiar lógica
`refactor`	♻️	Reordenaste código sin arreglar ni agregar nada
`perf`	⚡️	Mejoraste el rendimiento
`test`	✅	Agregaste o corregiste tests
`build`	📦	Sistema de build o dependencias externas
`ci`	🎡	Configuración de CI/CD
`chore`	🔨	Mantenimiento, sin tocar código ni tests
`revert`	⏪️	Reviertes un commit anterior

Scope (opcional) — el área del proyecto que tocaste (p. ej. deps, config, ci). También puedes elegir "✎ custom scope…" para escribir uno libre, o "∅ no scope" para omitirlo. La lista que aparece aquí depende de si el proyecto tiene un wietoo.toml con scopes propios — ver Scopes del proyecto.
Descripción corta — en imperativo, sin mayúscula inicial forzada, sin punto final. Verás un contador en vivo (header 42/100 chars · 58 left) para no pasarte del límite.
Cuerpo (opcional) — una descripción más larga, con el contexto del cambio.
Breaking change — solo aparece si elegiste feat o fix. Déjalo vacío si tu cambio no rompe compatibilidad.
Tareas relacionadas — escribe el número de la tarea de Squadlinx, p. ej. #441131 (o varias separadas por coma: #441131, #441132). Déjalo vacío si no aplica (ver excepciones).

Al final, wietoo te muestra una vista previa del mensaje completo dentro de un recuadro, y pregunta Create this commit? — respondes y/Enter para confirmar o n para cancelar sin perder lo que escribiste en el git add.

Ejemplo de principio a fin

$ git add .
$ wietoo commit

? Select the type of change you're committing: fix
? Scope of this change (optional): api
? Short, imperative description: validate the user id before the query
   header 45/100 chars · 55 left
? Longer body (optional): Evita un panic cuando el id llega vacío desde el handler.
? Issues closed by this change, e.g. #123, #124 (empty to skip): #441131

╭──────────────────────────────────────────────────────────╮
│ fix(api): 🐛 validate the user id before the query        │
│                                                            │
│ Evita un panic cuando el id llega vacío desde el handler. │
│                                                            │
│ closed #441131                                            │
╰──────────────────────────────────────────────────────────╯
Create this commit? (y/n)

El mensaje resultante es exactamente el que se guarda en el historial de Git — con el emoji, el formato y el footer ya correctos, sin que tengas que recordar nada de eso.

⚠️ wietoo commit necesita archivos "staged". Si no corriste git add antes, wietoo te avisa: nothing staged to commit — stage changes with 'git add' or run 'wietoo commit --all'. La opción -a/--all hace el git add de los archivos ya rastreados por ti (equivalente a git commit -a), pero no agrega archivos nuevos que nunca se hayan commiteado — para esos siempre hace falta git add explícito.

Qué pasa si el commit no cumple las reglas

No necesitas ejecutar nada para esto — ocurre automáticamente cada vez que se crea un commit (tanto si usas wietoo commit como si haces git commit -m "..." directamente). Un script (commit-msg hook) valida el mensaje y, si algo está mal, el commit no se crea y ves el motivo exacto:

$ git commit -m "add new thing"

✗ commit.subject     commit subject must match type(scope)?: description (allowed types: feat, fix, docs, ...)
✗ commit.emoji       commit subject must contain ': ' after the type

Corriges el mensaje (o vuelves a correr wietoo commit para que te guíe) y listo. No hay forma de saltarse esta validación con --no-verify — está prohibido en Wiedii y además wietoo seguiría bloqueando el push si el pipeline de CI vuelve a chequear el rango de commits.

La tarea de Squadlinx (`closed #<N>`) es una advertencia, no un bloqueo

Si olvidas el footer closed #<número>, wietoo te avisa pero sí deja crear el commit:

⚠ commit.footer.task   commit message should include a 'closed #<N>' footer

Esto es intencional: no todos los commits tienen una tarea asociada (ver la lista de excepciones más abajo), así que el chequeo queda como recordatorio visible, nunca como bloqueo duro.

El nombre de la rama también se valida

Además del mensaje del commit, wietoo check valida que el nombre de la rama actual cumpla la convención de Wiedii — se dispara en el hook pre-push y en CI, no en cada commit.

Tipo de rama	Formato	Ejemplo
Feature (incluye fixes)	`feature/<número de tarea>-<máx. 3 palabras>`	`feature/441131-fix-null-id`
Release	`release/X.Y.Z`	`release/1.2.0`
Hotfix	`hotfix/X.Y.Z`	`hotfix/1.2.1`
Ramas protegidas	`main`, `master`, `develop`	—
Renovate	`renovate/*`	`renovate/update-deps`

⚠️ No existe fix/*, chore/*, docs/*, refactor/*, test/*, build/* ni ci/* como prefijo de rama. Esos son tipos de commit Conventional Commits, no tipos de rama de Git Flow — un fix también va en feature/* (ver git-flow).

Si la rama no cumple, ves el motivo exacto:

$ wietoo check

✗ branch.naming   branch "feature/tk123-too-many-words-here" must match
  ^(feature/[0-9]+-[a-z0-9]+(-[a-z0-9]+){0,2}|(release|hotfix)/[a-z0-9][a-z0-9._-]*)$
  (e.g. feature/123-foo-bar), be a protected branch (main, master, develop), or
  start with renovate/

Renombra la rama con git branch -m <nuevo-nombre> (o git flow rename <nuevo-nombre> si usas git-flow-next) y vuelve a intentarlo.

Comandos que no necesitas usar directamente

Estos corren solos, disparados por los hooks de Git — nunca los escribes a mano en tu día a día:

Comando	Quién lo ejecuta	Para qué
`wietoo check`	El hook `pre-push` / el pipeline de CI	Valida la rama, el autor y el commit actual contra las políticas de Wiedii.
`wietoo check-commit-msg <archivo>`	El hook `commit-msg` de Git	Valida el mensaje que acabas de escribir, antes de que el commit se cree de verdad.

Si quieres ver con tus propios ojos qué es lo que corre en cada commit, puedes ejecutarlo manualmente sin hacer ningún cambio:

wietoo check   # revisa el estado actual del repo sin crear nada

Salida 0 (sin mensajes de error en pantalla) = todo en regla. Si algo falla, wietoo termina con código de salida 1 y te dice cuál regla no se cumplió.

Personalizar los scopes del proyecto (`wietoo.toml`)

Por defecto, el asistente sugiere una lista genérica de scopes (deps, config, ci, hooks, tooling, release — los mismos que usaba czg). Si tu proyecto necesita además sus propios scopes (por ejemplo los módulos reales de tu app: auth, billing, api), un mantenedor del repo puede definirlos en un archivo wietoo.toml, en la raíz del repositorio:

# wietoo.toml
[commit]
  scopes = ["auth", "billing", "api"]
  # replace_defaults = true   # opcional — ver el aviso de abajo

Con esto activo pasan dos cosas:

El asistente wietoo commit sugiere tu lista más los scopes transversales por defecto (deps, config, ci, hooks, tooling, release) — no hace falta re-listarlos, y sigue permitiendo "custom scope…" para un caso puntual.
La validación automática (wietoo check / el hook commit-msg) rechaza cualquier commit cuyo scope no esté en esa lista combinada — igual que hacía scope-enum en commitlint:

$ git commit -m "chore(random): 🔨 update libs"

✗ commit.scope   scope "random" is not in the allowed list: deps, config, ci, hooks, tooling, release, auth, billing, api

⚠️ scopes extiende los defaults, no los reemplaza. Es a propósito: deps (los commits chore(deps) de Renovate) y release (los chore(release) de wietoo release) deben seguir aceptándose aunque el proyecto nunca los declare — si no, CI empezaría a rechazar la automatización compartida. Si de verdad necesitas una lista cerrada (sin los defaults), agrega replace_defaults = true; en ese caso eres responsable de volver a listar deps/release si tu repo los usa.

Un commit sin scope (chore: 🔨 update libs) siempre pasa — la agrupación type(scope) sigue siendo opcional.

ℹ️ Si el proyecto no tiene wietoo.toml, o no define [commit].scopes, no hay restricción: cualquier scope (o ninguno) es válido. Este chequeo es opt-in — no rompe repos existentes que todavía no lo configuraron.

Crear el archivo de configuración — `wietoo init`

No hace falta escribir el TOML a mano. Desde la raíz del repo:

wietoo init
# ✓ wrote wietoo.toml

Esto crea un wietoo.toml con una sección [commit] ya funcional y un ejemplo comentado de [release] (ver más abajo) — sirve como referencia de todo lo que wietoo puede hacer en un proyecto, no solo los scopes. Si el archivo ya existe, wietoo init se niega a pisarlo salvo que agregues --force.

Comandos para quien administra el repositorio

Estos los usa normalmente el TL o quien mantiene el repo — no hacen falta para el trabajo diario de escribir commits.

`wietoo version` — leer y escribir la versión del proyecto

wietoo version self       # versión del propio binario de wietoo instalado
wietoo version current    # primer manifiesto de versión encontrado (VERSION, package.json, etc.)
wietoo version list       # todos los manifiestos de versión que encuentre en el repo
wietoo version set 1.4.0  # escribe 1.4.0 en todos los manifiestos encontrados
wietoo version bump       # calcula (sin escribir) la próxima versión recomendada

`wietoo changelog generate <version>`

Genera la entrada del CHANGELOG.md para una versión, a partir de los Conventional Commits desde el último tag.

`wietoo release` — cortar una release de punta a punta

wietoo release --dry-run   # solo muestra el plan: versión actual → próxima, sin cambiar nada
wietoo release              # auto-decide el bump (feat → minor, fix/otro → patch, breaking → major) y lo ejecuta
wietoo release --patch      # fuerza un bump de patch (o --minor / --major / --version 1.4.0)

Detecta solo si el repo usa Git Flow (main+develop, crea rama release//hotfix/) o GitHub Flow (rama única main, tag directo) — ver git-flow. Necesita un GITLAB_TOKEN (Project Access Token, nunca el token de glab) para crear la página de release en GitLab — ver versioning y gestion-secretos-sops-age.

Subcomandos para el flujo Git Flow paso a paso (útil si quieres una ventana de estabilización en la rama release/* antes de cerrarla):

wietoo release create --specifier minor   # abre la rama release/hotfix y bumpea versión
wietoo release finish                     # changelog + git-flow finish + push + release de GitLab
wietoo release assets <tag> --create      # sube/repara los binarios de una release existente

Publicar binarios de release en S3 (para Homebrew)

Además de subir los binarios a la página de Release de GitLab, wietoo release (y wietoo release assets <tag>) los publica también en el bucket S3 compartido wiedii-releases (us-west-2, lectura anónima pública) cuando el proyecto lo activa — necesario para que Homebrew pueda instalar el binario aunque el repo fuente sea privado en GitLab (una descarga anónima a una release de GitLab da 401; S3 no).

Se activa agregando name a la sección [release] de wietoo.toml — el prefijo S3 de ese proyecto (p. ej. wdev, squadlinx-mcp):

[release]
  name = "wdev"   # activa la publicación a s3://wiedii-releases/wdev/<version>/...

Vacío (el default, p. ej. el propio wietoo-cli) significa que el proyecto no publica a S3 — sigue subiendo solo a GitLab, como siempre. Las credenciales AWS son por proyecto, nunca las genéricas del entorno: se leen de RELEASES_UPLOADER_<TOOL>_ACCESS_KEY_ID / _SECRET_ACCESS_KEY (p. ej. RELEASES_UPLOADER_WDEV_ACCESS_KEY_ID), cifradas con SOPS en el secrets.sops.yaml de cada proyecto — nunca AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, para que una sesión AWS ambiental de la máquina o del runner de CI no se cuele por accidente en la release de un proyecto que no activó S3.

Esta convención (bucket, región, credenciales por-tool) es nueva de wietoo-cli — el wietoo JS original nunca tuvo esta capacidad.

`wietoo tap-update` — actualizar una fórmula de Homebrew

Solo aplica a proyectos que se distribuyen como fórmula de Homebrew (un "tap"). Actualiza la versión y el sha256 de la fórmula y abre un MR — ver wietoo tap-update --help.

Cuando el proyecto tiene release.name configurado (ver arriba), tap-update lee el sha256 desde S3 en vez de pedirlo a la página de Release de GitLab — un solo campo controla ambos comportamientos, así nunca pueden desincronizarse.

`wietoo publish packages` — publicar paquetes npm

Publica cada packages/<nombre>/ que tenga una carpeta dist/ a un registry compatible con npm. Exige que el package.json de la raíz del repo declare un campo workspaces no vacío — si no lo declara, wietoo se niega a correr (evita publicar accidentalmente en un repo que no es un monorepo de paquetes).

wietoo publish packages                                        # registry desde $CI_PUBLISH_CONFIG, tag desde $CI_COMMIT_REF_NAME (o "latest")
wietoo publish packages -r https://registry.example -t next     # registry y tag explícitos
wietoo publish packages --dry-run                               # simula, sin subir nada
wietoo publish packages --only pkg-a,pkg-b                      # publica solo paquetes puntuales

Puerto 1:1 del comando publish del wietoo JS original (packages/scripts/src/commands/publish): mismo comportamiento, ahora sin necesitar Node/Bun para ejecutarse (el repo publicado sí puede seguir siendo JS/TS — eso no cambia).

Cómo se activa wietoo en un proyecto nuevo

Esta sección es la referencia técnica completa — la necesitas si vas a agregar wietoo a un repo que todavía no lo tiene, o si estás migrando un proyecto desde czg/commitlint (ver Migrar un proyecto existente más abajo). Si tu repo ya lo tiene activo, no necesitas hacer nada de esto.

wietoo llega a un proyecto por dos archivos: mise.toml (para que la herramienta esté instalada) y lefthook.yaml (para que se dispare en cada commit). Ambos ya son parte del setup estándar de cualquier repo Wiedii — ver repo-setup.

1. `mise.toml` — declarar la herramienta

# mise.toml
[env]
  GOPRIVATE = "gitlab.wiedii.co/*"   # wiedii-registry es un grupo interno, no público

[tools]
  "go:gitlab.wiedii.co/wiedii-registry/wietoo-cli/cmd/wietoo" = "vX.Y.Z"   # ← ver "Qué versión usar"
  bun                          = "1.x.x"
  "aqua:evilmartians/lefthook" = "x.x.x"
  "aqua:tamasfe/taplo"         = "x.x.x"
  "pipx:checkov"               = "x.x.x"

[settings]
  experimental = true   # requerido para poder usar [hooks] más abajo
  lockfile     = true

[hooks]
  postinstall = "[ -z \"$CI\" ] && lefthook install || true"

💡 GOPRIVATE va en [env] del propio mise.toml, no en un comando manual (go env -w). Así, con solo clonar el repo y correr mise trust && mise run setup, la variable ya queda activa para ese directorio — sin ningún paso extra por fuera del setup estándar, coherente con la filosofía de mise: "sin pasos manuales, sin scripts de setup" (ver mise).

Tabla completa de qué necesita el hook compartido (ver wiedii-configs para el detalle de cada uno):

Herramienta en `mise.toml`	¿Cuándo hace falta?	Para qué hook
`go:.../wietoo-cli/cmd/wietoo`	Siempre, todos los stacks	`commit-msg` (valida) + `wietoo commit` (wizard)
`bun`	Siempre, todos los stacks	El `bunx` efímero de `renovate-validate` — no implica que el repo tenga `package.json`
`aqua:evilmartians/lefthook`	Siempre	Ejecuta todos los hooks; `lefthook-validate`
`aqua:tamasfe/taplo`	Siempre	Formatea archivos `*.toml` en cada commit
`pipx:checkov`	Siempre	Escaneo de secretos (`checkov-secrets`) sobre los archivos del commit
`aqua:hadolint/hadolint`	Solo si el repo tiene `Dockerfile`	Lint de Dockerfiles
`aqua:mvdan/sh` (shfmt)	Solo si el repo tiene scripts `.sh`	Formato de shell
`aqua:koalaman/shellcheck`	Solo si el repo tiene scripts `.sh`	Lint de shell

⚠️ bun sigue siendo obligatorio incluso en repos que no son JS/TS. No es un descuido: el hook renovate-validate de wiedii-configs usa bunx para validar renovate.json en cualquier stack. Lo que sí puedes quitar en un repo no-JS es package.json / node_modules / bun.lock — ver Migrar un proyecto existente.

Qué versión usar

Los ejemplos de arriba usan vX.Y.Z a propósito — la versión real cambia seguido. Antes de fijarla:

Consulta con tu TL o revisa el mise.toml de un repo que ya lo tenga activo (p. ej. el propio wietoo-cli, o cualquier repo reciente).
El tag debe llevar el prefijo v (v0.4.0, no 0.4.0) — es la única excepción autorizada al estándar de versionado de Wiedii, porque el sistema de módulos de Go ignora los tags sin v. Ver [[versioning#Excepción — paquetes Go (go install / backend go: de mise)]].

wietoo vive en un repositorio privado — un paso de Git, una sola vez por máquina

gitlab.wiedii.co/wiedii-registry es un grupo con visibilidad interna. El GOPRIVATE de arriba ya le dice a go/mise que se salte el proxy público, pero Git todavía necesita saber cómo autenticarse — reescribiendo la URL para que use tu llave SSH en vez de HTTPS anónimo. Esto sí es una configuración de máquina, no de proyecto, una sola vez:

git config --global url."git@gitlab.wiedii.co:".insteadOf "https://gitlab.wiedii.co/"

Si mise trust && mise run setup falla intentando descargar wietoo con un error de red o de autenticación al repo de GitLab (y el mise.toml del proyecto ya tiene GOPRIVATE como arriba), es casi siempre porque falta este paso — ver modulos-go para el detalle completo (incluye la configuración equivalente en CI).

2. `lefthook.yaml` — activar el hook compartido

# lefthook.yaml
remotes:
  - git_url: git@gitlab.wiedii.co:wildcat/wiedii-configs.git
    ref: 0.2.0             # última release de wiedii-configs — no `main` (ver [[wiedii-configs]])
    configs:
      - lefthook/base.yaml   # obligatorio, todos los stacks — activa wietoo
      # - lefthook/js.yaml   # agregar SOLO si el repo es JS/TS real (gestión de paquetes Node)

Después de guardar, instala los hooks (o simplemente corre el setup del proyecto, que ya lo hace):

mise trust && mise run setup
# — o, si ya confiaste en el proyecto antes —
lefthook install

Ver wiedii-configs para el detalle de cada hook compartido y lefthook para la guía general de lefthook.

Diferencias con el flujo antiguo (czg + commitlint)

	Antes (czg + commitlint)	Ahora (wietoo)
Asistente de commits	`bun commit` (czg)	`wietoo commit`
Validación del mensaje	`commitlint` vía `bun commitlint`	`wietoo check-commit-msg` (nativo)
Requiere Node/`package.json`	Sí, en todos los stacks	No, en ningún stack
Archivo de configuración	`commitlint.config.js`/`.mjs`	`wietoo.toml` (opcional)
Scopes personalizados	`scope-enum` en `commitlint.config`	`[commit].scopes` en `wietoo.toml`
Scaffolding inicial	Copiar `commitlint.config.js` de otro repo a mano	`wietoo init`
Funciona sin TTY (agentes/CI)	`prepare-commit-msg` de czg se saltaba silenciosamente	`wietoo commit` requiere TTY igual (es interactivo); agentes usan `git commit -m`/`-F`, que el hook valida igual

Si tu proyecto todavía tiene czg/commitlint/cz-git instalados, revisa la sección Migrar un proyecto existente.

Migrar un proyecto existente

Para pasar un repo de czg/commitlint a wietoo:

Activa wietoo: añádelo al mise.toml y suma el remote de wiedii-configs al lefthook.yaml (ver Cómo se activa wietoo en un proyecto nuevo).
Elimina el tooling viejo: las devDependencies @commitlint/*, cz-git, czg, el script "commit" de package.json, y los archivos commitlint.config.{js,cjs,mjs} y changelog.config.js.
En repos que NO son JS/TS: evalúa quitar por completo package.json / node_modules / bun.lock si solo existían para sostener czg/commitlint (criterios en repo-setup Regla 5). ⚠️ No quites bun del mise.toml — el hook renovate-validate usa bunx en cualquier stack.
Verifica: mise trust && mise run setup → wietoo commit → el hook commit-msg valida igual.

Preguntas frecuentes

¿Puedo seguir usando git commit -m "..." en vez del asistente? Sí. El asistente (wietoo commit) es la forma recomendada porque te evita errores de formato, pero un git commit -m manual se valida exactamente igual por el hook. Solo tienes que escribir el emoji y el formato correctos tú mismo.

¿Qué significa closed #441131 al final del mensaje? Es la referencia a la tarea de Squadlinx que originó el cambio — permite rastrear qué trabajo planificado generó cada commit. Ver trazabilidad-commits-soc.

Me equivoqué al escribir el commit dentro del asistente, ¿puedo corregir? Sí — usa las flechas para volver a un campo dentro del mismo grupo de preguntas, o responde n en la confirmación final para cancelar sin perder el git add ya hecho, y vuelve a correr wietoo commit.

¿wietoo commit funciona en Windows/Linux, o solo macOS? Es un binario multiplataforma (darwin/linux, arm64/amd64); mise instala automáticamente la versión correcta para tu sistema.

¿Qué pasa si mi commit no tiene ninguna tarea de Squadlinx asociada? Salvo las excepciones de abajo, siempre debería llevar una. Si genuinamente no aplica, el commit se crea igual — el chequeo del footer es una advertencia, no un bloqueo (ver más arriba).

¿Necesito permisos especiales para instalar wietoo? No — se instala solo, vía mise, igual que cualquier otra herramienta del proyecto. El único paso manual de una sola vez por máquina es el insteadOf de Git (ver arriba) — GOPRIVATE ya viene declarado en el mise.toml del proyecto, así que no requiere ningún paso adicional de tu parte.

Referencia obligatoria a tarea Squadlinx

Todo commit de desarrollo debe llevar closed #<número> en el footer. Están exentos:

chore: initial commit — primer commit de un repo nuevo
Commits de Renovate — se generan automáticamente con su propio MR
Commits de release — chore(release): 🔨 bump version to 1.2.0

Ver la política completa en commits.

Troubleshooting

command not found: wietoo:

mise trust && mise run setup
wietoo version self   # ✅

wietoo commit dice "nothing staged to commit":

git add .              # o los archivos específicos que quieras incluir
wietoo commit
# alternativa: wietoo commit --all (solo agrega archivos ya rastreados, no archivos nuevos)

El commit se rechaza con commit.emoji o commit.subject: Vuelve a intentarlo con el asistente en vez de escribir el mensaje a mano — te evita todo el formato:

wietoo commit

mise run setup falla intentando descargar wietoo (error de red/auth al repo de GitLab): Si el mise.toml del proyecto ya declara GOPRIVATE en [env] (ver arriba), casi siempre falta el paso de Git, una sola vez por máquina:

git config --global url."git@gitlab.wiedii.co:".insteadOf "https://gitlab.wiedii.co/"
mise run setup

wietoo release falla pidiendo un token:

# Necesitas un Project Access Token (scope api) — nunca el token de glab
export GITLAB_TOKEN=glpat-...
# o, si el proyecto lo tiene cifrado con sops (recomendado):
mise run release

Ver versioning.

Mi commit falla con commit.scope aunque el scope me parece razonable: El proyecto restringió los scopes válidos en su wietoo.toml. Corre wietoo commit y elige uno de la lista sugerida, o pide al TL que agregue el scope que necesitas a [commit].scopes.

Tabla rápida por síntoma

Problema	Causa probable	Solución
`command not found: wietoo`	`mise` no instaló las herramientas del proyecto	`mise trust && mise run setup`
`nothing staged to commit`	No corriste `git add` antes de `wietoo commit`	`git add .` o `wietoo commit --all`
`commit.subject` / `commit.emoji` FAIL	Mensaje escrito a mano sin el formato correcto	Usar `wietoo commit` en vez de `git commit -m` a mano
`commit.footer.task` WARN	Falta `closed #<N>`	Agregarlo si aplica (ver excepciones); si no aplica, se puede ignorar
`commit.scope` FAIL	El proyecto restringió los scopes en `wietoo.toml`	Elegir un scope de la lista sugerida o pedir al TL que lo agregue
Falla la descarga de wietoo en `mise install`	Falta el `insteadOf` de Git en la máquina (`GOPRIVATE` ya debería venir del `mise.toml` del proyecto)	Ver el comando de Git en la sección de arriba
`wietoo release` pide token	Falta `GITLAB_TOKEN` o el token es el de `glab`	Usar un Project Access Token propio, vía `sops` si el repo lo tiene configurado

Referencia rápida — todos los comandos

Comando	Quién lo usa	Qué hace
`wietoo commit [-a]`	Todo el equipo	Asistente interactivo para crear un commit
`wietoo check [--json] [--allow-overrides] [--commits <rango>]`	Automático (hook/CI); manual para depurar	Valida rama, autor y commit(s) actuales
`wietoo check-commit-msg <archivo>`	Automático (hook `commit-msg`)	Valida un mensaje de commit antes de crearlo
`wietoo init [--force]`	TL / quien configura el repo	Crea `wietoo.toml` con `[commit].scopes` + ejemplo de `[release]`
`wietoo version {self\|current\|list\|set\|bump}`	TL	Leer, escribir o calcular la versión del proyecto
`wietoo changelog generate <version>`	TL	Genera la entrada de `CHANGELOG.md`
`wietoo release [--patch\|--minor\|--major\|--version\|--dry-run]`	TL	Corta una release completa (versión, changelog, tag, GitLab release)
`wietoo release create\|finish\|assets`	TL	Pasos granulares de una release Git Flow
`wietoo publish packages [-r/-t/--dry-run/--only]`	TL / CI	Publica cada `packages/<n>/dist` a un registry npm-compatible
`wietoo tap-update --tap-repo <ns/proj> --version <v>`	TL (proyectos con fórmula Homebrew)	Actualiza la fórmula del tap y abre un MR (lee checksums de S3 si `release.name` está configurado)

Referencias

czg — la herramienta que wietoo reemplaza para el asistente/validación de commits
wiedii-configs — los hooks compartidos de lefthook que disparan wietoo en cada commit
lefthook — guía general de lefthook
mise — cómo mise instala y activa wietoo por proyecto
commits — política completa de mensajes de commit
modulos-go — configuración de GOPRIVATE/insteadOf para módulos Go privados
versioning — excepción de tag v para paquetes Go, y token de release vía SOPS
trazabilidad-commits-soc — por qué el footer closed #<id> importa para auditoría
wiedii-registry/wietoo-cli — repositorio del proyecto

Qué es wietoo, en una frase​

Antes de empezar — glosario de dos minutos​

Por qué la empresa lo usa​

Cómo saber si tu proyecto ya lo tiene activo​

El día a día — cómo hacer un commit con wietoo​

Ejemplo de principio a fin​

Qué pasa si el commit no cumple las reglas​

La tarea de Squadlinx (closed #<N>) es una advertencia, no un bloqueo​

El nombre de la rama también se valida​

Comandos que no necesitas usar directamente​

Personalizar los scopes del proyecto (wietoo.toml)​

Crear el archivo de configuración — wietoo init​

Comandos para quien administra el repositorio​

wietoo version — leer y escribir la versión del proyecto​

wietoo changelog generate <version>​

wietoo release — cortar una release de punta a punta​

Publicar binarios de release en S3 (para Homebrew)​

wietoo tap-update — actualizar una fórmula de Homebrew​

wietoo publish packages — publicar paquetes npm​

Cómo se activa wietoo en un proyecto nuevo​

1. mise.toml — declarar la herramienta​

Qué versión usar​

wietoo vive en un repositorio privado — un paso de Git, una sola vez por máquina​

2. lefthook.yaml — activar el hook compartido​

Diferencias con el flujo antiguo (czg + commitlint)​

Migrar un proyecto existente​

Preguntas frecuentes​

Referencia obligatoria a tarea Squadlinx​

Troubleshooting​

Tabla rápida por síntoma​

Referencia rápida — todos los comandos​

Referencias​