Uxlog Usage

uxLog Usage

uxLog writes to three sinks at once:

1. The terminal (via commandThis.ux.log or console.log).
2. The hardisLogFileStream file log.
3. The VS Code (LWC) UI over WebSocket - except when logType === "other", or the line contains the markers [command] or [NotifProvider].

The logType argument both labels the line in the UI (drives section grouping, icons, colors) and decides whether the line reaches the UI at all. Pick it deliberately.

Import

import { uxLog, uxLogTable } from "../../../common/utils/index.js";
import c from "chalk";
import { t } from "../../../common/utils/i18n.js";

Levels and colors (strict 1:1 pairing)

Always pair the level with its chalk color. Mixing them confuses the terminal output and breaks the convention used across ~2000 existing call sites.

Examples

// New phase - opens a UI section
uxLog("action", this, c.cyan(t("deployingMetadata", { metadata: name })));

// Detail under that action
uxLog("log", this, c.grey(t("foundFiles", { count: files.length })));
uxLog("log", this, c.grey(`- ${reportFile}`));

// Recoverable issue
uxLog("warning", this, c.yellow(t("missingOptionalConfig", { key: "slackWebhook" })));

// Failure
uxLog("error", this, c.red(t("deploymentFailed", { message: e.message })));

// Successful completion
uxLog("success", this, c.green(t("deploymentSucceeded", { org: targetOrg })));

// Debug payload that should NOT pollute the VS Code UI
uxLog("other", this, JSON.stringify(rawApiResponse, null, 2));

Pitfalls to avoid

• Do not use c.green with error, c.red with success, etc. The level and color must match.
• Do not use action for sub-details - that creates spurious sections in the UI. One action per phase, then log for everything underneath.
• Do not use log (which goes to the UI in grey) for noisy diagnostic output - prefer other.
• Do not omit chalk - every uxLog should be wrapped in the matching color so terminal output stays readable.

Options (4th argument)

The optional fourth argument is a UxLogOptions object: { sensitive?: boolean; alwaysVisible?: boolean }.

uxLog("log", this, c.grey(`Authenticating with token ${token}`), { sensitive: true });
uxLog("action", this, c.cyan("Installation summary:"), { alwaysVisible: true });

Backward compatibility: the 4th argument also still accepts a bare boolean (the legacy sensitive flag), because uxLog is called by external plugins. uxLog(..., true) is equivalent to uxLog(..., { sensitive: true }). For new code, always use the options object.

sensitive

Set { sensitive: true } when the line contains credentials, tokens, secrets, or any data that must not land in the file log or the VS Code UI. Use it for any line that interpolates an access token, refresh token, client secret, password, or third-party API key.

Behaviour:

• Terminal: shows the real text (so the user running the command can still see it locally).
• File log (hardisLogFileStream): writes the literal string OBFUSCATED LOG LINE.
• VS Code UI: sends OBFUSCATED LOG LINE. Exception: lines containing SFDX_CLIENT_ID_, SFDX_CLIENT_KEY_, or SFDX_CLIENT_CERT_ are sent as-is even when sensitive is set.

alwaysVisible

Set { alwaysVisible: true } to keep the enclosing VS Code UI section expanded by default, instead of auto-collapsing when a later section opens (and staying open in the UI's "simple" mode too). A manual collapse by the user still wins.

• On an action line: keeps the section that line starts expanded.
• On any other level (log, warning, error, ...): keeps the section that contains the line expanded.

Use it for a summary block the user should keep seeing while they act on the next prompt (e.g. an install summary shown just before a confirmation). No effect outside the VS Code LWC UI.

VS Code / LWC UI suppression

The VS Code extension only renders lines whose logType !== "other" AND whose text does not include the markers [command] or [NotifProvider].

Practical consequences:

• For raw payloads, JSON dumps, or noisy progress that would overwhelm the UI session log, use uxLog("other", ...). The terminal and file log still receive it.
• The [command] and [NotifProvider] prefixes are reserved for internal command-execution and notification-provider lines that the UI handles through dedicated events; do not introduce new uses of those markers in unrelated code.
• Other [Marker] prefixes (e.g. [DORA], [sfdx-hardis]) are fine and are forwarded to the UI.