Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs: define structured logging standard
Alfredo Lopezf5107d2e9ce2
diff --git a/AGENTS.md b/AGENTS.mdindex b01ca1dd1..90072669c 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -93,3 +93,42 @@ Labs reference. Use repository-standard conventional prefixes instead:`ci/*`, `build/*`, `perf/*`, or `revert/*`, choosing the one that describesthe change. This rule applies to new branches; it does not retroactivelyrewrite branches that already exist outside the task's scope.++## Logging standard++Use structured service logging for production Node.js/runtime code. Pino is+the repository reference implementation: `control-api` already exposes a+redacting root Pino logger and `workspace-files-controller` uses Pino with+`pino-http`. The repository does not use Winston. Other services currently+have local structured adapters (for example, `mcp-host`, HCC, workflow+recipes, and the workflow approval reader); those adapters remain the local+boundary until a separately scoped service migration is approved.++The choice is about the logging contract, not a blanket dependency migration:+structured JSON, explicit levels, contextual fields/child loggers,+`LOG_LEVEL` filtering, and secret-safe redaction. Direct `console.*` calls in+production code bypass those guarantees; in `control-api` they also bypass+Pino's redaction list. Winston or a new ad-hoc logger must not be introduced+to solve a one-file cleanup.++When modifying an individual file:++- In production Node.js code, use the existing logger or structured adapter+ for that service. Do not bypass it with `console.log`, `console.info`,+ `console.warn`, `console.error`, `console.debug`, or `console.trace`.+- Map levels consistently: `log`/`info` → `info`, `warn` → `warn`,+ `error` → `error`, and `debug`/`trace` → the adapter's debug/trace level.+ Pass fields as structured data; pass errors as an error field (for Pino,+ `{ err }`) rather than interpolating them into a string.+- Preserve the service's redaction, correlation, and JSON-output behavior.+ Never log tokens, credentials, authorization headers, DSNs, private URLs,+ cookies, keys, or raw request/response bodies.+- Scope the cleanup to the file already being changed and the minimum import+ or adapter support it needs. Do not sweep neighboring files, start a+ repository-wide migration, or add a second logging convention as collateral+ work.+- Direct `console.*`/`process.stdout` is allowed only inside a logger adapter,+ an explicit CLI/bootstrap path that runs before a logger exists, tests,+ E2E/fixtures, or intentional development-only diagnostics. Do not import a+ server logger into browser/renderer bundles; use their existing client+ logging boundary.diff --git a/CLAUDE.md b/CLAUDE.mdindex e23a2c362..a7d52c1f4 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -11,3 +11,20 @@ Labs reference. Use the repository's conventional prefixes instead: `feat/*`,The local Minikube T0/T1/T2 contract is development-only. Follow thecanonical `make minikube-t2-preflight` and `make minikube-t2` entry points andthe ownership, secret-safety, and evidence rules in `AGENTS.md`.++## Logging standard++For production Node.js/runtime code, use structured logging. Pino is the+repository reference implementation because `control-api` uses a redacting+root logger and `workspace-files-controller` uses Pino/Pino HTTP; Winston is+not a repository dependency. Services with an existing structured wrapper+(`mcp-host`, HCC, workflow recipes, and the workflow approval reader) should+continue using that wrapper rather than bypassing it.++When editing a file, replace its direct `console.*` calls with the existing+service logger, preserve levels/context/redaction, and keep the change scoped+to that file plus minimal support. Do not start a repository-wide logging+migration or add a second logger convention. Direct console output is reserved+for logger adapters, explicit CLI/bootstrap output, tests, E2E/fixtures, and+intentional development diagnostics; never emit secrets, tokens, credentials,+DSNs, private URLs, or raw request/response bodies.