📖 Documentación completa y siempre actualizada: gitlab.wiedii.co/wildcat/wiedii-configs Esta nota es un resumen de referencia rápida. El README.md del repo es la fuente de verdad.

wiedii-configs — Hooks Compartidos

Repositorio centralizado de configuraciones de git hooks para todos los proyectos Wiedii. En lugar de copiar y mantener el mismo YAML de hooks en cada repo, los proyectos consumen este repo vía lefthook remotes.

Repo: wildcat/wiedii-configs
Rama activa: develop
Visibilidad: internal

Estructura

wiedii-configs/
├── lefthook/
│   ├── base.yaml        # todos los stacks — pre-commit + czg + commitlint + bun install
│   ├── js.yaml          # placeholder — hooks exclusivos JS/TS futuros
│   ├── python.yaml      # (próximamente) — Python
│   └── go.yaml          # (próximamente) — Go
├── taplo/
│   └── taplo.toml       # config canónica de taplo — copiar a cada nuevo repo
├── lefthook.yaml        # hooks internos del repo
├── commitlint.config.js # config de czg + commitlint (ESM)
├── package.json         # devDeps: czg, commitlint, cz-git
└── mise.toml            # herramientas: bun, lefthook, taplo

taplo no soporta extends ni config remota. La estrategia Wiedii es dual: las opciones de formato se pasan via --option en el hook de base.yaml (centralizado, se aplica siempre), y cada proyecto tiene su propio .taplo.toml para que taplo aplique las mismas opciones al correr manualmente, en VS Code o en CI. El archivo taplo/taplo.toml en este repo es la fuente canónica — copiar al crear un nuevo proyecto. Ver linters para el template completo.

Hooks disponibles

`lefthook/base.yaml` — todos los stacks

`pre-commit`

Comando	Glob	Qué hace
`toml`	`*.toml`	Formatea con `taplo fmt --option align_entries=true --option indent_entries=true --option reorder_arrays=true --option reorder_keys=true`, auto-stagea
`sort-package-json`	`package.json`	Ordena las claves del `package.json`, auto-stagea
`hadolint`	`Dockerfile`	Lint de Dockerfiles
`shfmt`	`*.sh`	Formatea scripts shell, auto-stagea
`shellcheck`	`*.sh`	Análisis estático de scripts shell
`lefthook-validate`	`lefthook*.yaml`	Valida la sintaxis de los configs de lefthook
`renovate-validate`	`renovate.json`, `.renovaterc*`	Valida la config de Renovate con `--strict`

Los jobs mise trust y mise install --yes corren antes de los comandos.

`prepare-commit-msg` y `commit-msg`

Hook	Qué hace
`prepare-commit-msg`	Abre el wizard de `czg` al hacer `git commit`, forzando el formato con emoji
`commit-msg`	Valida el mensaje con `commitlint` (Conventional Commits)

El hook prepare-commit-msg usa czg --hook {1} {2}: con TTY abre el selector interactivo; sin TTY (CI, -m, merge, rebase) se salta automáticamente.

`post-commit`

Comando	Qué hace
`graphify-update`	Actualiza el knowledge graph con `graphify . --update` si existe `graphify-out/`. Auto-detecta el backend LLM disponible. Solo procesa archivos cuyo SHA-256 cambió — típicamente < 5s en cambios incrementales. No-op en repos sin grafo inicializado.

El hook nunca bloquea el commit — si no hay backend disponible imprime un aviso y sale con 0; si graphify falla por cualquier otra razón, el || true garantiza que el commit continúe.

Detección de backend (en orden de prioridad):

Backend	Condición
`claude-cli`	`claude` CLI en PATH (Claude Code instalado)
`gemini`	`GEMINI_API_KEY` o `GOOGLE_API_KEY` en el entorno
`claude`	`ANTHROPIC_API_KEY` en el entorno
`openai`	`OPENAI_API_KEY` en el entorno
(skip)	Ninguno disponible — imprime aviso, no falla

Para actualizar el grafo manualmente: graphify . --update --backend <claude-cli|gemini|claude|openai>.

`post-merge`, `post-checkout`, `post-rewrite`

Hook	Qué hace
`post-merge`	Corre `bun install --frozen-lockfile` si cambiaron `package.json`, `bun.lock` o `bunfig.toml`
`post-checkout`	Ídem, al cambiar de rama
`post-rewrite`	Ídem, tras rebase o amend

Son idempotentes y glob-filtrados: solo corren si package.json, bun.lock o bunfig.toml cambiaron en el commit. Si el proyecto no tiene esos archivos, los hooks no se activan.

`lefthook/js.yaml` — JS / TS

Placeholder para hooks exclusivamente JS/TS que no tienen equivalente en otros stacks (ej. tsc --noEmit). Actualmente no contiene hooks activos — los hooks comunes (sort-package-json, bun install) ya están en base.yaml.

`lefthook/python.yaml` y `lefthook/go.yaml`

Reservados para futuros hooks de Python y Go.

Cómo consumir en un nuevo repo

Agregar el bloque remotes al lefthook.yaml del proyecto:

# lefthook.yaml
remotes:
  - git_url: git@gitlab.wiedii.co:wildcat/wiedii-configs.git
    configs:
      - lefthook/base.yaml   # obligatorio — todos los stacks

Luego instalar los hooks:

lefthook install   # descarga y cachea los configs en .lefthook/

.lefthook/ debe estar en .gitignore del repo consumidor — es un artefacto local generado.

Requisitos en el repo consumidor

Todas las herramientas de sistema deben instalarse vía mise — declaradas en el mise.toml del proyecto consumidor. Los hooks usan mise exec -- <herramienta> y fallará si la herramienta no está en el entorno mise del proyecto.

Herramientas en `mise.toml`

Herramienta	Cuándo es necesaria
`bun`	Siempre — czg, commitlint, sort-package-json y bun install
`lefthook`	Siempre — hook `lefthook-validate`
`taplo`	Siempre — hook `toml` (formato de archivos `.toml`)
`hadolint`	Si el repo tiene `Dockerfile`
`shfmt`	Si el repo tiene scripts `.sh`
`shellcheck`	Si el repo tiene scripts `.sh`

Ejemplo mínimo de mise.toml en el repo consumidor:

[tools]
bun        = "1.x.x"
"aqua:evilmartians/lefthook" = "x.x.x"
"aqua:tamasfe/taplo"         = "x.x.x"
# hadolint, shfmt, shellcheck — agregar si el repo los necesita

Dependencias en `package.json`

Paquete	Versión	Detalle
`@commitlint/cli`	`21.0.1`	Validación del mensaje de commit
`@commitlint/config-conventional`	`21.0.1`	Reglas Conventional Commits
`cz-git`	`1.13.1`	Adaptador de czg para commitlint
`czg`	`1.13.1`	Wizard interactivo de commits
`sort-package-json`	`3.6.1`	El hook lo busca en `node_modules/.bin/`; avisa y sigue si no está

Además, el proyecto debe tener:

commitlint.config.js / .cjs / .mjs en la raíz — el hook detecta automáticamente el formato (ESM o CJS)

Los hooks de sort-package-json y bun install solo se activan si los archivos correspondientes (package.json, bun.lock, bunfig.toml) existen y están staged. No son requisito para consumir base.yaml.

⚠️ PKG_DIR — detección de package.json: los hooks detectan dinámicamente la ubicación del package.json con find . -maxdepth 2 y toman el resultado más superficial. Si un proyecto tiene dos package.json (por ejemplo en raíz y en src/), se usará siempre el de raíz. Asegúrate de que las devDependencies (czg, commitlint, sort-package-json) estén en el package.json raíz; de lo contrario, los hooks de czg, commitlint y sort-package-json no encontrarán los binarios.

ℹ️ czg wizard (prepare-commit-msg): solo funciona cuando existe una TTY real, es decir, al ejecutar git commit (sin -m) desde una terminal interactiva. Desde Claude Code, CI, o al usar git commit -m, el hook se salta automáticamente. El flujo recomendado es bun commit (invoca czg directamente).

`lefthook.yaml` mínimo para un repo JS/TS

Los hooks centralizados cubren: sort-package-json, formateo TOML, Dockerfile lint, shell lint/format, lefthook validate, renovate validate, czg wizard, commitlint y bun install. El lefthook.yaml local solo necesita los linters específicos del proyecto:

remotes:
  - git_url: git@gitlab.wiedii.co:wildcat/wiedii-configs.git
    configs:
      - lefthook/base.yaml

pre-commit:
  parallel: true
  jobs:
    - run: mise trust
    - run: mise install --yes
  commands:
    prettier:
      priority: 1
      glob: '*.{js,cjs,mjs,ts,json,md,yaml}'
      run: mise exec -- bun prettier --write --cache {staged_files}
      stage_fixed: true
    eslint:
      priority: 2
      glob: '*.{js,cjs,mjs,ts,json}'
      run: mise exec -- bun eslint --config eslint.config.mjs --cache --fix {staged_files}
      stage_fixed: true

Los hooks commit-msg, prepare-commit-msg, post-merge/post-checkout/post-rewrite, sort-package-json y los validadores universales ya vienen de base.yaml — no se duplican.

Cómo contribuir / actualizar

git flow feature start hooks/nombre-del-cambio
# hacer cambios en lefthook/*.yaml
mise exec -- lefthook validate  # verificar sintaxis
lefthook run pre-commit        # probar hooks localmente
bun commit                     # wizard czg
git flow publish -o merge_request.create -o merge_request.target=develop \
  -o "merge_request.title=feat(hooks): descripción"

Nunca hacer push directo a main ni develop. Ver git-flow.

Probar en un repo consumidor antes de mergear

# lefthook.yaml — apuntar temporalmente al feature branch
remotes:
  - git_url: git@gitlab.wiedii.co:wildcat/wiedii-configs.git
    ref: feature/hooks/nombre-del-cambio
    configs:
      - lefthook/base.yaml

Revertir a develop (o quitar ref:) una vez mergeado.

Actualización automática en repos consumidores

lefthook install siempre descarga la versión más reciente de develop. Ocurre automáticamente en:

mise run setup (via [hooks].postinstall en mise.toml)
Al hacer post-merge / post-checkout si el repo lo incluye en hooks locales

No se requiere ninguna acción manual para adoptar nuevos hooks.

Referencias

lefthook — guía completa de lefthook: instalación, integración con mise, troubleshooting
commits — política de mensajes de commit que valida el hook commit-msg
repo-setup — checklist para configurar un nuevo repositorio (incluye bloque remotes)
cross-platform — .gitattributes y .gitignore estándar para repos Wiedii

Estructura​

Hooks disponibles​

lefthook/base.yaml — todos los stacks​

pre-commit​

prepare-commit-msg y commit-msg​

post-commit​

post-merge, post-checkout, post-rewrite​

lefthook/js.yaml — JS / TS​

lefthook/python.yaml y lefthook/go.yaml​

Cómo consumir en un nuevo repo​

Requisitos en el repo consumidor​

Herramientas en mise.toml​

Dependencias en package.json​

lefthook.yaml mínimo para un repo JS/TS​

Cómo contribuir / actualizar​

Probar en un repo consumidor antes de mergear​

Actualización automática en repos consumidores​

Referencias​