Filtros TOML

Dónde se cargan los filtros

Boost fusiona filtros de varias ubicaciones y aplica cada filtro seleccionado por el comando o la salida. Los archivos dentro de una carpeta se cargan en orden determinista.

1. Filtros integrados incluidos con Boost (make, terraform, shellcheck, …)
2. ~/.boost/filters/*.toml (carpeta global, un filtro por archivo)
3. .boost/filters/*.toml en el proyecto — desde el cwd, luego la raíz git, luego $GITHUB_WORKSPACE

Project discovery loads only .boost/filters/*.toml — it does not read, create, or require a repo-level .boost/config.toml. Filters committed at the repo root apply from subdirectories. If the same name appears in more than one project dir, cwd wins. Enable/disable still uses ~/.boost/config.toml.

Las fuentes se fusionan, no se sobrescriben. Un filtro de proyecto no reemplaza un integrado con el mismo nombre — ambos se cargan (nombre + origen), y se aplica cada filtro cuyo match_command o match_output_select coincida, en orden (builtin → global → project). Para reemplazar un integrado, desactívalo con boost filters disable y publica el tuyo.

Create a project filter

Ship team filters in .boost/filters/ at the repo root. Anyone who clones the repo — and runs Boost from a subdirectory or CI — gets the same compression automatically.

1. mkdir -p .boost/filters
2. Add one .toml file per filter. The name comes from [filters.<name>]. Use match_command plus a distinctive match_output_select so the filter selects on the agent pipe path.
3. Commit the file with the repo.
4. From a subdirectory, run boost filters show — the filter should appear with SOURCE=project.

schema_version = 1

[filters.acme-cli]
description = "Keep errors and warnings from the internal acme-cli"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:\S*/)?acme-cli\b'
match_output_select = [
  '(?m)^acme-cli v',
]
strip_ansi = true
keep_lines_matching = [
  '^acme-cli v',
  '^Error:',
  '^Warning:',
  '^✗',
]
on_empty = "acme-cli: ok"

Confirm it loaded

# From any subdirectory of the repo:
boost filters show | grep acme-cli
# → enabled   project     acme-cli   toml:project:acme-cli

After boost init, agent shell commands are piped through Boost automatically. No repo-level .boost/config.toml is required for project filters; enable/disable still uses ~/.boost/config.toml. For a fuller end-to-end example with before/after output, see the deploy script section below.

Disposición de carpetas (un filtro por archivo)

Los filtros personalizados viven en archivos de un solo filtro: cada uno tiene un bloque [filters.<name>] y ejemplos [[tests.<name>]]. Así puedes ajustar un filtro sin tocar los demás.

~/.boost/filters/                 # global (this machine)
  my-personal.toml

<repo>/.boost/filters/            # project (commit with the team)
  acme-cli.toml
  deploy.toml

Los filtros en ~/.boost/filters/ los recoge el siguiente proceso boost sin recompilar.

Selectores y campos comunes

Cada filtro necesita al menos un selector. Estos campos aparecen en casi todos los ejemplos; el glosario completo está al final de la página.

Sabor de regex

Todos los patrones usan el paquete regexp de Go (sintaxis RE2), no PCRE. Sin backreferences ni lookbehind. ^/$ multilínea requieren (?m) al coincidir contra la salida completa. Ver regexp/syntax.

Ejemplo: script de deploy personalizado

Tu equipo ejecuta ./scripts/deploy.sh a través de Boost. El hook solo envía la salida, así que hace falta match_output_select además de match_command.

schema_version = 1

[filters.deploy]
description = "Keep failures from deploy.sh"
version = "1"
match_command = '(?:^|[;&|]\s*)(?:bash\s+)?(?:\S*/)?deploy\.sh\b'
# The hook pipes output to boost, so select by a distinctive output signature.
# (?m) makes ^ and $ match each line, not only the full output boundaries.
match_output_select = [
  '(?m)^Starting deployment$\n^Environment: ',
]
strip_ansi = true
keep_lines_matching = [
  '^Starting deployment$',
  '^Environment: ',
  '^\[(WARN|ERROR)\]',
  '^ERROR DETAILS:$',
  'failed readiness probe',
  '^File:$',
  '^deploy/check_health\.go:\d+$',
  '^Reason:$',
  '^connection refused',
  '^Rollback started\.\.\.$',
  '^Deployment FAILED$',
]

[[tests.deploy]]
name = "keeps failures, drops info chatter"
input = """
Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""
expected = """
Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging
"""

Starting deployment
Environment: staging
[INFO] Waiting for rollout
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging

Starting deployment
Environment: staging
[WARN] High memory usage detected
[ERROR] Deployment validation failed
ERROR DETAILS:
service payment-service failed readiness probe
File:
deploy/check_health.go:142
Reason:
connection refused to database
Rollback started...
Deployment FAILED
Environment: staging

Tests inline

Cada bloque [[tests.<name>]] es un fixture de regresión: name, input y expected. expect_match_output opcional comprueba si match_output_select seleccionaría el filtro.

Cómo ejecutarlos

Aún no hay boost filters test. Comprueba filtros personalizados enviando salida de ejemplo por boost. Los fixtures integrados se ejecutan con go test:

# Spot-check a custom filter: pipe sample output through boost
printf '%s\n' 'Starting deployment' 'Environment: staging' '[INFO] noise' | boost

# Built-in [[tests.*]] fixtures run in the Boost repo / CI:
go test ./internal/tomlfilter/ -run TestInlineTestDefs

Ejemplo: recortar ruido de make

Los filtros integrados usan el mismo esquema. Esto refleja el filtro make incluido: elimina líneas de entrar/salir de directorio y filas en blanco.

schema_version = 1

[filters.make]
match_command = "^make\\b"
match_output_select = [
  "^make\\[\\d+\\]:",
  "^gcc ",
]
strip_lines_matching = [
  "^make\\[\\d+\\]:",
  "^\\s*$",
  "^Nothing to be done",
]
on_empty = "make: ok"

make[1]: Entering directory '/home/user/app'
gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

make[1]: Leaving directory '/home/user/app'

gcc -O2 -c src/main.c
gcc -O2 -o app src/main.o

Ejemplo: resumen en lint limpio

Usa match_output para devolver un resumen de una línea cuando la herramienta terminó en silencio.

schema_version = 1

[filters.eslint-quiet]
match_command = "^eslint\\b"
match_output_select = [
  "problems",
]
match_output = [
  { pattern = "0 problems", message = "eslint: ok" },
]

Desactivar un filtro

Prefiere la CLI:

boost filters show                 # inventory with enabled/disabled status
boost filters show --enabled       # enabled filters only
boost filters disable git-status   # bare name or toml:builtin:git-status
boost filters enable git-status

O edita ~/.boost/config.toml directamente — lista nombres bajo [filters] disabled. Tras retrieve_disable_threshold eventos retrieve (predeterminado 3), boost retrieve añade automáticamente los nombres revertidos. Usa 0 para desactivar el auto-disable.

[filters]
disabled = ["git-status", "make"]
retrieve_disable_threshold = 3

Campos del filtro

Pon schema_version = 1 al inicio de cada archivo. Etapas en orden: strip ANSI → replace → match_output → strip/keep → dedupe → collapse → head/tail → on_empty. Referencia completa en docs/TOML_FILTERS.md.