TOML-Filter

Wo Filter geladen werden

Boost merged Filter aus mehreren Orten und wendet jeden Filter an, der durch Befehl oder Ausgabe ausgewählt wird. Dateien in einem Ordner laden in deterministischer Reihenfolge.

1. Eingebaute Filter mit Boost (make, terraform, shellcheck, …)
2. ~/.boost/filters/*.toml (globaler Ordner, ein Filter pro Datei)
3. .boost/filters/*.toml im Projekt — cwd, dann Git-Root, dann $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.

Quellen werden zusammengeführt, nicht überschrieben. Ein Projektfilter ersetzt keinen Builtin gleichen Namens — beide laden (Name + Quelle), und jeder Treffer von match_command oder match_output_select wird in Ladereihenfolge angewendet (builtin → global → project). Zum Ersetzen: boost filters disable und eigenen Filter liefern.

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.

Ordnerlayout (ein Filter pro Datei)

Eigene Filter leben in Ein-Filter-Dateien: jede enthält einen [filters.<name>]-Block und [[tests.<name>]]-Beispiele.

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

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

Filter in ~/.boost/filters/ werden vom nächsten boost-Prozess ohne Rebuild geladen.

Selektoren & häufige Felder

Jeder Filter braucht mindestens einen Selektor. Diese Felder erscheinen in fast jedem Beispiel; das vollständige Glossar steht unten.

Regex-Variante

Alle Muster nutzen Go's regexp-Paket (RE2-Syntax), nicht PCRE. Keine Backreferences oder Lookbehind. Mehrzeilige ^/$ brauchen (?m). Siehe regexp/syntax.

Beispiel: eigenes Deploy-Skript

Ihr Team führt ./scripts/deploy.sh über Boost aus. Der Hook sendet nur Ausgabe, daher ist match_output_select zusätzlich zu match_command nötig.

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

Inline-Tests

Jeder [[tests.<name>]]-Block ist ein Regression-Fixture: name, input und expected. Optionales expect_match_output prüft die Selektion über match_output_select.

So führen Sie sie aus

Es gibt noch kein boost filters test. Prüfen Sie eigene Filter, indem Sie Beispielausgabe durch boost pipen. Eingebaute Fixtures laufen mit 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

Beispiel: make-Lärm entfernen

Builtin-Filter nutzen dasselbe Schema. Dies spiegelt den mitgelieferten make-Filter: Verzeichnis-Ein-/Ausgangszeilen und Leerzeilen entfernen.

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

Beispiel: Kurzschluss bei sauberem Lint

Nutzen Sie match_output für eine Einzeilen-Zusammenfassung, wenn das Tool still erfolgreich war.

schema_version = 1

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

Filter deaktivieren

Bevorzugen Sie die 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

Oder bearbeiten Sie ~/.boost/config.toml direkt — Namen unter [filters] disabled listen. Nach retrieve_disable_threshold Retrieve-Ereignissen (Standard 3) hängt boost retrieve Rollback-Namen an. 0 schaltet Auto-Disable aus.

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

Filterfelder

Setzen Sie schema_version = 1 an den Dateianfang. Stufen: strip ANSI → replace → match_output → strip/keep → dedupe → collapse → head/tail → on_empty. Vollständige Referenz in docs/TOML_FILTERS.md.