master-zapier-plan-draft/docs/developer/modules/debug.md

Module: debug

Path: verae-zapier-middleware/src/debug/
Phase: 1
Purpose: Runtime-toggleable failure tracing with secret redaction and correlation IDs.

Files

File	Role
config.js	Parse env into enable/namespaces/level
redact.js	Strip secrets from log metadata
logger.js	Namespaced createDebugger
trace-context.js	ALS store (no logger import)
trace.js	withTrace, Express middleware
index.js	Public barrel export

---

parseDebugVeraeEnv(raw)

For	Interpret DEBUG_VERAE env string
Input	raw: string | undefined
Output	{ enabled: boolean, namespaces: Set<string>|null }
Notes	1/* → all namespaces; "auth,nats" → allow-list

loadDebugConfig(env?)

For	Build full debug config from environment
Input	env?: NodeJS.ProcessEnv (default process.env)
Output	DebugConfig { enabled, namespaces, level, filePath }

shouldLog(config, namespace, messageLevel)

For	Decide if a line should emit
Input	config, namespace string, level
Output	boolean

redact(input)

For	Deep-redact secrets for safe logging
Input	any JSON-like value
Output	redacted clone

createDebugger(namespace)

For	Get { debug, info, warn, error } logger for a namespace
Input	namespace: string
Output	Debugger
Side effects	Writes to stderr (or test sink) when enabled

Debugger.debug|info|warn|error(message, meta?)

Input	message: string, meta?: Record<string, unknown>
Output	void

withTrace(options, fn)

For	Run work under a correlation id
Input	{ traceId?, span? }, fn: () => T|Promise<T>
Output	T|Promise<T>

getTraceId()

For	Read active correlation id
Output	string|null

traceMiddleware(req, res, next)

For	Per-request Express trace context
Input	Express (req, res, next)
Output	void
Sets	req.traceId, response header X-Trace-Id

setDebugTestSink(sink)

For	Capture log lines in unit tests
Input	((line: string) => void) | null
Output	void

Env reference

See ../debugging.md.