fernando/clusterlogs

Fork 0

Files

T

fernando 1ecfb022b1 bootstrap: iniciar bitácora operativa

2026-08-13 00:43:15 -06:00

9.1 KiB

Raw Blame History

Referencia de `clusterlog`

1. Forma general

clusterlog [opciones globales] <comando> [opciones del comando]

Las opciones globales deben colocarse antes del comando.

Opción	Efecto
`--root DIR`	raíz del repositorio; si se omite, la CLI busca el proyecto desde el directorio actual
`--json`	salida estructurada y estable para agentes
`--ssh-key PATH`	llave pública o ruta base usada para resolver identidad y firma
`--commit`	crea un commit Git SSH firmado con sólo los archivos de la operación
`--dry-run`	valida y calcula el resultado sin escribir

También puede definirse CLUSTERLOG_SSH_KEY.

2. Contrato JSON

Éxito:

{
  "ok": true,
  "command": "memory.create",
  "data": {},
  "warnings": []
}

Error:

{
  "ok": false,
  "error": {
    "kind": "identity_not_found",
    "message": "ninguna llave SSH local coincide con un administrador activo",
    "details": {}
  }
}

Un agente debe usar el código del proceso como decisión primaria y error.kind para tratamiento específico. No debe inferir éxito por texto parcial.

3. Códigos de salida

Código	Significado
`0`	éxito
`2`	uso, flags o entrada inválida
`3`	identidad no encontrada o no autorizada
`4`	validación, firma o contenido inválido
`5`	conflicto de estado
`6`	operación Git fallida
`10`	error interno no clasificado

4. Identidad

clusterlog --root . --json --ssh-key ~/.ssh/id_ed25519.pub identity

La respuesta incluye el administrador, la huella, la ruta pública y la ruta que Git intentará usar para firmar. No prueba posesión hasta que exista una firma válida.

5. Administradores

Agregar

clusterlog --root . --ssh-key ~/.ssh/id_ed25519.pub admin add \
  --id ana \
  --name "Ana Torres" \
  --email ana@example.org \
  --key ~/.ssh/id_ed25519.pub \
  --roles owner,admin

Reglas:

El primer administrador obtiene owner aunque no se incluya explícitamente.
Después del primero, sólo un owner puede agregar administradores.
No se aceptan IDs, correos o huellas duplicados.
data/admins.json y config/allowed_signers se actualizan juntos.

Listar

clusterlog --root . --json admin list
clusterlog --root . --json admin list --active

6. Memorias

Consultar esquema

clusterlog --json schema memory

Crear por JSON

cat examples/memory.json | clusterlog \
  --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  memory create --from-json -

Crear por flags

clusterlog --root . --commit --ssh-key ~/.ssh/id_ed25519.pub memory create \
  --title "Rotar certificado del API" \
  --description "Renovación programada y comprobación de clientes" \
  --tags tls,certificados \
  --systems kube-apiserver \
  --risk medium \
  --ticket CHG-1042 \
  --duration 45m \
  --agent claude-code \
  --body-file memoria.md

Opciones específicas:

--title
--description
--tags
--systems
--risk low|medium|high|critical
--ticket
--review (por defecto true)
--review-policy all-active|all-active-except-author
--duration en minutos, 90m o 2h
--agent
--body-file ARCHIVO|-
--from-json ARCHIVO|-

Cuando se combinan JSON y flags, los flags que se proporcionen explícitamente tienen precedencia.

7. Revisión

Listar pendientes

clusterlog --root . --json review list
clusterlog --root . --json --ssh-key ~/.ssh/id_ed25519.pub review list --mine

--mine requiere identidad y devuelve sólo memorias cuyo conjunto pendiente contiene al administrador actual.

Marcar la versión actual

clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  review mark MEM-20260812-... --note "Revisado; sin objeciones"

El evento guarda el SHA-256 del contenido actual. Repetir el comando sobre el mismo hash es idempotente; editar la memoria hace que el evento anterior deje de contar.

8. Tareas

Crear

cat examples/task.json | clusterlog \
  --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  task create --from-json -

Flags disponibles:

--title, --description
--project PRJ-...
--priority low|medium|high|urgent
--assignees ana,luis
--estimate 120m
--due YYYY-MM-DD
--tags, --systems
--objective
--acceptance separado por comas
--notes
--body-file ARCHIVO|-
--from-json ARCHIVO|-

Iniciar y detener tiempo

clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  task start TSK-... --note "Diagnóstico inicial"

clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  task stop TSK-... --note "Prueba completada"

Un administrador sólo puede mantener un temporizador activo. Los eventos se ordenan por fecha y tipo para producir un total reproducible.

Ajustar tiempo

clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  task adjust TSK-... --minutes 20 --note "Trabajo previo no registrado"

clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  task adjust TSK-... --minutes -10 --note "Corregir doble conteo"

El total efectivo nunca puede quedar negativo.

Cambiar estado

clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  task status TSK-... --status blocked --note "Esperando refacción"

Estados admitidos aquí: backlog, todo, in_progress, blocked, cancelled. Para finalizar use task done.

Completar

clusterlog --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  task done TSK-... --note "Criterios de aceptación verificados"

Si el administrador actual mantiene el temporizador, la CLI lo detiene. Rechaza completar si otra persona sigue registrando tiempo en la misma tarea.

Listar

clusterlog --root . --json task list
clusterlog --root . --json task list --status blocked
clusterlog --root . --json --ssh-key ~/.ssh/id_ed25519.pub task list --mine
clusterlog --root . --json task list --project PRJ-...

9. Proyectos

Crear

cat examples/project.json | clusterlog \
  --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  project create --from-json -

Flags:

--title, --description, --objective
--owners
--target-date YYYY-MM-DD
--status planned|active|blocked|done|cancelled|archived
--tags, --systems
--scope, --out-of-scope
--milestones, --success
--body-file ARCHIVO|-
--from-json ARCHIVO|-

Listar

clusterlog --root . --json project list
clusterlog --root . --json project list --status active

10. Documentación y manuales

cat examples/manual.json | clusterlog \
  --root . --json --commit --ssh-key ~/.ssh/id_ed25519.pub \
  content create --from-json -

También acepta:

clusterlog --root . --commit --ssh-key ~/.ssh/id_ed25519.pub content create \
  --section manuales \
  --title "Reemplazar nodo de cómputo" \
  --description "Procedimiento seguro y validaciones" \
  --tags runbook,hardware \
  --systems compute \
  --body-file reemplazo.md \
  --weight 20

section sólo puede ser documentacion o manuales.

11. Proyección

clusterlog --root . sync
clusterlog --root . sync --check

sync lee Markdown, administradores y eventos; genera data/generated/site_state.json. --check no escribe y falla cuando el archivo derivado no coincide con la fuente.

Los agentes no deben editar data/generated/site_state.json a mano.

12. Validación

clusterlog --root . --json validate
clusterlog --root . --json validate --skip-zola
clusterlog --root . --json validate --require-zola

Se comprueban, entre otros:

registro de administradores y allowed_signers;
IDs, autores, revisores, owners y assignees;
estados, fechas y referencias de proyectos;
eventos huérfanos o inconsistentes;
temporizadores concurrentes y totales negativos;
secretos probables;
vigencia de la proyección;
plantillas y enlaces con zola check, cuando está disponible.

13. Firmas

clusterlog --root . verify commit HEAD
clusterlog --root . verify commit abc1234

La verificación usa:

config/allowed_signers
namespace: git

En CI conviene verificar todos los commits nuevos, no sólo HEAD.

14. Esquemas para agentes

clusterlog --json schema
clusterlog --json schema memory
clusterlog --json schema task
clusterlog --json schema project
clusterlog --json schema content

Los esquemas siguen JSON Schema 2020-12 y rechazan propiedades adicionales. Esta restricción permite detectar errores ortográficos en nombres de campos.

15. Patrón recomendado para agentes

set -euo pipefail

SCHEMA="$(clusterlog --json schema memory)"
# Construir input.json con base en data del sobre.

clusterlog --root . --json --dry-run --ssh-key "$KEY" \
  memory create --from-json input.json

RESULT="$(clusterlog --root . --json --commit --ssh-key "$KEY" \
  memory create --from-json input.json)"

printf '%s\n' "$RESULT"
clusterlog --root . --json verify commit HEAD

El agente debe detenerse ante cualquier código distinto de cero y presentar el error al usuario sin ocultarlo.

9.1 KiB Raw Blame History

Referencia de clusterlog

1. Forma general

2. Contrato JSON

3. Códigos de salida

4. Identidad

5. Administradores

Agregar

Listar

6. Memorias

Consultar esquema

Crear por JSON

Crear por flags

7. Revisión

Listar pendientes

Marcar la versión actual

8. Tareas

Crear

Iniciar y detener tiempo

Ajustar tiempo

Cambiar estado

Completar

Listar

9. Proyectos

Crear

Listar

10. Documentación y manuales

11. Proyección

12. Validación

13. Firmas

14. Esquemas para agentes

15. Patrón recomendado para agentes

9.1 KiB

Raw Blame History

Referencia de `clusterlog`