@builder.io/dev-tools/types/common/logger.d.ts

Builder.io Visual CMS Devtools

/**
 * Structured logger for dev-tools.
 *
 * ## Enabling debug logs
 *
 * Debug output is **off by default**. Two ways to turn it on:
 *
 * ### 1. `DEBUG` environment variable
 *
 * Set to any truthy value to enable debug output for all loggers:
 *
 * ```sh
 * DEBUG=1 npx @builder.io/dev-tools ...
 * ```
 *
 * ### 2. `--debug` CLI flag
 *
 * Sets `process.env.DEBUG = "1"` early in the CLI entry point, enabling
 * debug output for all loggers (including module-level ones created at
 * import time, since `DEBUG` is checked lazily at call time).
 *
 * ```sh
 * npx @builder.io/dev-tools --debug ...
 * ```
 *
 * ### `LOG_LEVEL` environment variable
 *
 * Controls the minimum severity for `info`, `warn`, and `error` messages.
 * Accepted values: `debug`, `info` (default), `warn`, `error`.
 *
 * `LOG_LEVEL` does **not** affect `debug()` output — debug messages are
 * controlled exclusively by the `DEBUG` env var / `--debug` CLI flag.
 * This is intentional: debug is an explicit opt-in, and the default
 * `LOG_LEVEL=info` must not silently suppress explicitly requested output.
 *
 * ```sh
 * DEBUG=1 npx @builder.io/dev-tools ...                    # debug + info/warn/error
 * LOG_LEVEL=error npx @builder.io/dev-tools ...            # errors only (no debug)
 * LOG_LEVEL=warn DEBUG=1 npx @builder.io/dev-tools ...     # debug + warn/error
 * ```
 *
 * ### Per-call options (`loggerOptions`)
 *
 * Any log method accepts an optional trailing `{ loggerOptions: { ... } }`
 * argument with:
 *
 * - `debug: true`  — only emit this call when debug mode is enabled.
 *   Useful for error/warn/info calls that should only appear during
 *   debugging (e.g. stack traces, verbose diagnostics).
 * - `stderr: true` — force output to stderr even for methods that
 *   normally write to stdout (debug, info). Useful when stdout is
 *   reserved for a protocol (e.g. MCP stdio JSON-RPC).
 *
 * ```ts
 * logger.error("Stack trace:", err.stack, { loggerOptions: { debug: true } });
 * logger.info("Server running on stdio", { loggerOptions: { stderr: true } });
 * ```
 *
 * ### Cloud environments
 *
 * When `FUSION_ENVIRONMENT` is `cloud` or `cloud-v2`, all output is emitted
 * as newline-delimited JSON (GCP Cloud Logging compatible) with `severity`,
 * `message`, `timestamp`, and optional `context` fields. The `stderr` option
 * controls which stream is used but does not affect the `severity` field —
 * GCP reads severity from the JSON payload, not from the stream.
 */
type LogLevel = "debug" | "info" | "warn" | "error";
export interface LogCallOptions {
    /** Force output to stderr (useful when stdout is reserved, e.g. MCP stdio). */
    stderr?: boolean;
    /** Only emit this call when debug mode is enabled on the logger. */
    debug?: boolean;
}
interface LogCallOptionsWrapper {
    loggerOptions: LogCallOptions;
}
export interface Logger {
    debug(...args: [...any[], LogCallOptionsWrapper]): void;
    debug(...args: any[]): void;
    info(...args: [...any[], LogCallOptionsWrapper]): void;
    info(...args: any[]): void;
    warn(...args: [...any[], LogCallOptionsWrapper]): void;
    warn(...args: any[]): void;
    error(...args: [...any[], LogCallOptionsWrapper]): void;
    error(...args: any[]): void;
}
export interface CreateLoggerOptions {
    /**
     * Enable debug output. Accepts a static boolean or a lazy `() => boolean`
     * for runtime checks (e.g. checking multiple env vars). When omitted,
     * defaults to checking `process.env.DEBUG` lazily at call time.
     */
    debug?: boolean | (() => boolean);
    level?: LogLevel;
}
export declare function setDebuggingEnabled(enabled: boolean): void;
export declare function createLogger(context: string, options?: CreateLoggerOptions): Logger;
/**
 * In cloud environments, intercept process.stderr.write so that any plain-text
 * write is re-emitted as a structured JSON entry with severity "ERROR". Writes
 * that are already structured JSON (produced by the logger) are passed through
 * unchanged.
 *
 * No-op outside cloud environments.
 */
export declare function setupCloudStderrCapture(): void;
/**
 * Register process-level error handlers that route uncaught exceptions and
 * unhandled promise rejections through the structured logger so they appear in
 * Cloud Logging with severity ERROR and a proper stack trace.
 */
export declare function setupProcessErrorHandlers(context?: string, exitFn?: (code: number) => Promise<void> | void): void;
export {};