miravo 0.6.0 → 0.6.2

package/src/logger.ts

@@ -1,402 +0,0 @@
-import { MiravoError } from "@miravo/shared";
-import type { ConsolaInstance } from "consola";
-import { createConsola } from "consola";
-import { colors, stripAnsi } from "consola/utils";
-
-type LogFormat = "pretty" | "json";
-type LogLevel = "debug" | "info" | "warn" | "error";
-
-const LOG_LEVEL_MAP: Readonly<Record<LogLevel, number>> = {
-  debug: 4,
-  info: 3,
-  warn: 2,
-  error: 0,
-};
-
-/**
- * Color map for log tags. Used in pretty mode to prepend a colored label.
- */
-/**
- * Aligned with Miravo brand palette (packages/shared/src/brand.css):
- *   engine     → yellow       brand primary #e5a218 (amber)
- *   mqtt       → green        brand success #10b981 (emerald)
- *   opcua      → blue         brand chart-3 #3b82f6
- *   modbus     → cyan         brand info    #38bdf8 (sky blue)
- *   config     → gray         low-priority setup messages
- *   lifecycle  → magenta      brand chart-4 #8b5cf6 (violet)
- *   fault      → redBright    brand destructive #f43f5e (rose)
- *   control    → blueBright   lighter blue, distinct from opcua
- *   platform   → greenBright  LE apply/cleanup operations
- */
-const TAG_COLORS: Readonly<Record<string, (s: string) => string>> = {
-  engine: colors.yellow,
-  mqtt: colors.green,
-  opcua: colors.blue,
-  modbus: colors.cyan,
-  config: colors.gray,
-  lifecycle: colors.magenta,
-  fault: colors.redBright,
-  control: colors.blueBright,
-  platform: colors.greenBright,
-};
-
-/**
- * Display names for log tags. Tags are internal identifiers; these are
- * the user-facing labels shown at the start of each log line.
- */
-const TAG_DISPLAY_NAMES: Readonly<Record<string, string>> = {
-  engine: "Engine",
-  mqtt: "MQTT",
-  opcua: "OPC UA",
-  modbus: "Modbus",
-  config: "Config",
-  lifecycle: "Lifecycle",
-  fault: "Fault",
-  control: "Control",
-  platform: "Platform",
-};
-
-/**
- * Root consola logger for the Miravo CLI.
- * `fancy: true` enables icons and color when a TTY is available.
- * consola automatically disables styling in non-TTY environments.
- *
- * We wrap the default FancyReporter to:
- * - Prepend a space to the first arg (breathing room after Unicode icons)
- * - Color-code tags by domain (engine=cyan, mqtt=green, etc.)
- */
-export const logger: ConsolaInstance = createConsola({
-  ...({ fancy: true } as Record<string, unknown>),
-  formatOptions: { date: true },
-});
-
-interface ReporterLogObject {
-  date?: Date;
-  level: number;
-  type?: string;
-  tag?: string;
-  args: unknown[];
-}
-
-const fancyReporters = [...logger.options.reporters];
-const prettyReporter = {
-  log(logObj: ReporterLogObject, ctx: unknown) {
-    // Move tag from the right side to a colored prefix at the start of the message
-    if (logObj.tag) {
-      const rawTag = logObj.tag;
-      const displayName = TAG_DISPLAY_NAMES[rawTag] ?? rawTag;
-      const colorFn = TAG_COLORS[rawTag] ?? colors.gray;
-      const prefix = `${colorFn(displayName)}${colors.dim(":")}`;
-      if (logObj.args.length > 0 && typeof logObj.args[0] === "string") {
-        logObj.args[0] = ` ${prefix} ${logObj.args[0]}`;
-      } else {
-        logObj.args.unshift(` ${prefix}`);
-      }
-      // Clear the tag so consola doesn't also render it on the right
-      logObj.tag = "";
-    } else if (logObj.args.length > 0 && typeof logObj.args[0] === "string") {
-      logObj.args[0] = ` ${logObj.args[0]}`;
-    }
-    for (const reporter of fancyReporters) {
-      reporter.log(logObj as never, ctx as never);
-    }
-  },
-};
-
-function normalizeMessageArgs(args: readonly unknown[]): string {
-  return args
-    .map((arg) => {
-      if (arg instanceof Error) return arg.message;
-      if (typeof arg === "string") return stripAnsi(arg);
-      if (typeof arg === "object" && arg !== null) {
-        try {
-          return stripAnsi(JSON.stringify(arg));
-        } catch {
-          return stripAnsi(String(arg));
-        }
-      }
-      return stripAnsi(String(arg));
-    })
-    .join(" ")
-    .trim();
-}
-
-function levelToString(level: number): "trace" | "debug" | "info" | "warn" | "error" | "fatal" {
-  if (level >= 5) return "trace";
-  if (level === 4) return "debug";
-  if (level === 3) return "info";
-  if (level === 2) return "warn";
-  if (level === 1) return "warn";
-  if (level === 0) return "error";
-  return "fatal";
-}
-
-const jsonReporter = {
-  log(logObj: ReporterLogObject) {
-    const errorArg = logObj.args.find((arg) => arg instanceof Error);
-    const metadataArg = logObj.args.find(
-      (arg) => typeof arg === "object" && arg !== null && !(arg instanceof Error),
-    );
-    const level = typeof logObj.type === "string" ? logObj.type : levelToString(logObj.level);
-    const entry = {
-      ts: (logObj.date ?? new Date()).toISOString(),
-      level,
-      type: logObj.type ?? "log",
-      ...(logObj.tag ? { tag: stripAnsi(logObj.tag) } : {}),
-      ...(runtimeLogContext.simulationName
-        ? { simulationName: runtimeLogContext.simulationName }
-        : {}),
-      ...(runtimeLogContext.runId ? { runId: runtimeLogContext.runId } : {}),
-      message: normalizeMessageArgs(logObj.args),
-      ...(errorArg instanceof Error
-        ? {
-            error: {
-              name: errorArg.name,
-              message: errorArg.message,
-              stack: errorArg.stack,
-            },
-          }
-        : {}),
-      ...(metadataArg !== undefined ? { metadata: metadataArg } : {}),
-    };
-    try {
-      console.log(JSON.stringify(entry));
-    } catch {
-      const { metadata, ...safeEntry } = entry as Record<string, unknown>;
-      console.log(JSON.stringify({ ...safeEntry, metadata: "[unserializable]" }));
-    }
-  },
-};
-
-/** Engine lifecycle and tick events. */
-export const engineLog: ConsolaInstance = logger.withTag("engine");
-
-/** MQTT adapter connection, publish, and broker events. */
-export const mqttLog: ConsolaInstance = logger.withTag("mqtt");
-
-/** Config loading, parsing, and validation events. */
-export const configLog: ConsolaInstance = logger.withTag("config");
-
-/** Instance lifecycle stage transitions. */
-export const lifecycleLog: ConsolaInstance = logger.withTag("lifecycle");
-
-/** Fault trigger and clear events. */
-export const faultLog: ConsolaInstance = logger.withTag("fault");
-
-/** OPC UA adapter connection and server events. */
-export const opcuaLog: ConsolaInstance = logger.withTag("opcua");
-
-/** Modbus TCP adapter connection and server events. */
-export const modbusLog: ConsolaInstance = logger.withTag("modbus");
-
-/** Control plane status and command routing events. */
-export const controlLog: ConsolaInstance = logger.withTag("control");
-
-/** Litmus Edge platform apply/cleanup operation events. */
-export const platformLog: ConsolaInstance = logger.withTag("platform");
-
-/** Route an adapter name to its dedicated logger. Falls back to engineLog for unknown names. */
-export function adapterLogger(name: string): ConsolaInstance {
-  if (name === "mqtt") return mqttLog;
-  if (name === "opcua") return opcuaLog;
-  if (name === "modbus") return modbusLog;
-  return engineLog;
-}
-
-/** All tag loggers, for bulk level updates. */
-const allLoggers: ConsolaInstance[] = [
-  logger,
-  engineLog,
-  mqttLog,
-  opcuaLog,
-  modbusLog,
-  configLog,
-  lifecycleLog,
-  faultLog,
-  controlLog,
-  platformLog,
-];
-
-function applyLogReporter(format: LogFormat): void {
-  const reporter = format === "json" ? jsonReporter : prettyReporter;
-  for (const l of allLoggers) {
-    l.setReporters([reporter]);
-  }
-}
-
-/** Options for configuring log verbosity from CLI flags. */
-interface LoggerOptions {
-  readonly verbose?: boolean | undefined;
-  readonly quiet?: boolean | undefined;
-  readonly plain?: boolean | undefined;
-  readonly logFormat?: LogFormat | undefined;
-  readonly logLevel?: LogLevel | undefined;
-}
-
-let _outputSuppressed = false;
-let _plainOutput = false;
-let _locked = false;
-let _logFormat: LogFormat = "pretty";
-const runtimeLogContext: { simulationName: string | undefined; runId: string | undefined } = {
-  simulationName: undefined,
-  runId: undefined,
-};
-
-export function parseLogFormat(raw: string): LogFormat {
-  if (raw === "pretty" || raw === "json") return raw;
-  throw new MiravoError(
-    `Invalid log format "${raw}".`,
-    "Use --log-format pretty or --log-format json.",
-  );
-}
-
-export function parseLogLevel(raw: string): LogLevel {
-  if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error") return raw;
-  throw new MiravoError(
-    `Invalid log level "${raw}".`,
-    "Use --log-level debug | info | warn | error.",
-  );
-}
-
-export function setRuntimeLogContext(context: { simulationName?: string; runId?: string }): void {
-  runtimeLogContext.simulationName = context.simulationName;
-  runtimeLogContext.runId = context.runId;
-}
-
-export function clearRuntimeLogContext(): void {
-  runtimeLogContext.simulationName = undefined;
-  runtimeLogContext.runId = undefined;
-}
-
-/**
- * Set the global log level based on CLI flags.
- * Priority: --quiet > --log-level > --verbose > default (info).
- *
- * Consola levels: 0 = errors/fatals, 2 = warn, 3 = info, 4 = debug.
- */
-export function configureLogger(opts: LoggerOptions): void {
-  if (_locked) return;
-  _logFormat = opts.logFormat ?? "pretty";
-  applyLogReporter(_logFormat);
-  _plainOutput = opts.plain ?? false;
-
-  // NO_COLOR convention: disable colors when set to any non-empty value
-  if (!_plainOutput && Bun.env["NO_COLOR"] !== undefined && Bun.env["NO_COLOR"] !== "") {
-    _plainOutput = true;
-  }
-
-  let level: number;
-  if (opts.quiet) {
-    level = 0;
-    _outputSuppressed = true;
-  } else if (opts.logLevel) {
-    level = LOG_LEVEL_MAP[opts.logLevel];
-    _outputSuppressed = false;
-  } else if (opts.verbose) {
-    level = LOG_LEVEL_MAP.debug;
-    _outputSuppressed = false;
-  } else {
-    level = LOG_LEVEL_MAP.info;
-    _outputSuppressed = false;
-  }
-  for (const l of allLoggers) {
-    l.level = level;
-  }
-}
-
-/** Returns true when JSON log output is active. */
-export function isJsonLogFormat(): boolean {
-  return _logFormat === "json";
-}
-
-/**
- * Write informational output to stdout, respecting --quiet.
- * Use this for primary formatted output (tables, boxes, status renders).
- * Do NOT use for machine-readable output (--json, --raw) — those should
- * always go through `process.stdout.write()` or `console.log()` directly.
- */
-export function writeOutput(...args: unknown[]): void {
-  if (_outputSuppressed) return;
-
-  if (_plainOutput) {
-    if (args.length === 0) {
-      console.log();
-      return;
-    }
-
-    const normalized = args
-      .map((arg) => {
-        if (typeof arg === "string") {
-          return stripAnsi(arg);
-        }
-        return stripAnsi(String(arg));
-      })
-      .join(" ");
-
-    console.log(normalized);
-    return;
-  }
-
-  console.log(...args);
-}
-
-/** Returns true when --quiet is active. */
-export function isQuiet(): boolean {
-  return _outputSuppressed;
-}
-
-/**
- * Lock logger configuration so subsequent `configureLogger()` calls are no-ops.
- * Used by test setup to prevent Commander's preAction hook from resetting levels.
- */
-export function lockLogger(): void {
-  _locked = true;
-}
-
-/** Unlock logger configuration. */
-export function unlockLogger(): void {
-  _locked = false;
-}
-
-/** Returns true when --plain is active. */
-export function isPlain(): boolean {
-  return _plainOutput;
-}
-
-/**
- * Handle a caught error in a CLI command action. If it's a `MiravoError`,
- * log the message and fix string and set a non-zero exit code. Otherwise
- * re-throw so unexpected errors surface with a full stack trace.
- */
-export function handleCommandError(error: unknown, log: ConsolaInstance = configLog): void {
-  if (error instanceof MiravoError) {
-    log.error(error.message);
-    log.error(`Fix: ${error.fix}`);
-    process.exitCode = 1;
-  } else {
-    throw error;
-  }
-}
-
-interface CommandResultLike {
-  readonly success: boolean;
-  readonly message: string;
-  readonly error?: string | undefined;
-}
-
-/**
- * Handle the result of an admin command, respecting --json output.
- * Writes success messages to stdout and errors to the control log.
- * Sets process.exitCode = 1 on failure.
- */
-export function handleCommandResult(result: CommandResultLike, json?: boolean): void {
-  if (json) {
-    console.log(JSON.stringify(result, null, 2));
-  } else if (result.success) {
-    writeOutput(result.message);
-  } else {
-    controlLog.error(result.message);
-    if (result.error) controlLog.error(`Fix: ${result.error}`);
-  }
-  if (!result.success) process.exitCode = 1;
-}

package/src/output.test.ts

@@ -1,64 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { colors, stripAnsi } from "consola/utils";
-import { formatDuration, formatKeyValue, formatTable } from "./output.ts";
-
-describe("formatTable", () => {
-  test("aligns columns to widest value", () => {
-    const result = formatTable({ name: "Name", sensors: "Sensors" }, [
-      { name: "centrifugal-pump", sensors: "5" },
-      { name: "conveyor", sensors: "12" },
-    ]);
-    const lines = result.split("\n");
-    expect(lines).toHaveLength(3);
-    expect(lines[0]).toContain("Name");
-    expect(lines[0]).toContain("Sensors");
-    expect(lines[1]).toContain("centrifugal-pump");
-    expect(lines[2]).toContain("conveyor");
-  });
-
-  test("aligns columns correctly when cells contain ANSI color codes", () => {
-    const result = formatTable({ name: colors.dim("Name"), count: colors.dim("Count") }, [
-      { name: colors.cyan("short"), count: "1" },
-      { name: colors.cyan("much-longer-name"), count: "2" },
-    ]);
-    const lines = result.split("\n");
-    expect(lines).toHaveLength(3);
-    const [header, row1, row2] = lines.map((l) => stripAnsi(l));
-    const countCol0 = header?.indexOf("Count") ?? -1;
-    const countCol1 = row1?.indexOf("1") ?? -1;
-    const countCol2 = row2?.indexOf("2") ?? -1;
-    expect(countCol0).toBeGreaterThan(0);
-    expect(countCol0).toBe(countCol1);
-    expect(countCol0).toBe(countCol2);
-  });
-});
-
-describe("formatKeyValue", () => {
-  test("aligns values by padding keys", () => {
-    const result = formatKeyValue([
-      ["Template", "plant.miravo.yaml"],
-      ["Seed", "42"],
-    ]);
-    const lines = result.split("\n");
-    expect(lines).toHaveLength(2);
-    expect(lines[0]).toMatch(/^ {4}Template:/);
-    expect(lines[1]).toMatch(/^ {4}Seed:/);
-    expect(lines[0]).toContain("plant.miravo.yaml");
-    expect(lines[1]).toContain("42");
-  });
-});
-
-describe("formatDuration", () => {
-  test("formats sub-second as milliseconds", () => {
-    expect(formatDuration(500)).toBe("500ms");
-    expect(formatDuration(0)).toBe("0ms");
-  });
-
-  test("formats minutes and seconds", () => {
-    expect(formatDuration(323_000)).toBe("5m 23s");
-  });
-
-  test("formats exact hours with no trailing zeros", () => {
-    expect(formatDuration(3_600_000)).toBe("1h");
-  });
-});

package/src/output.ts

@@ -1,160 +0,0 @@
-/**
- * Shared output formatting for the Miravo CLI.
- * Uses consola/utils for ANSI-aware width calculation.
- */
-
-import type { AdapterHealthSnapshot, AdapterMetrics } from "@miravo/shared";
-import { colors, stripAnsi } from "consola/utils";
-
-/** A single row in a table, where each cell is a string value keyed by column key. */
-interface TableRow {
-  readonly [key: string]: string;
-}
-
-/** Dim separator used between values on a single summary line. */
-export const sep = colors.dim(" \u00B7 ");
-
-/**
- * Format a list of objects as a column-aligned table.
- * Column widths are auto-calculated from header labels and cell values.
- * Each line is indented with a consistent prefix for clean CLI output.
- *
- * @param headers - Column definitions: `{ key: "Display Label" }`.
- * @param rows - Data rows with string values keyed by header keys.
- * @returns Multi-line string ready for console output.
- */
-export function formatTable(
-  headers: Readonly<Record<string, string>>,
-  rows: readonly TableRow[],
-): string {
-  const keys = Object.keys(headers);
-  const gap = 3;
-  const indent = "    ";
-
-  const widths = new Map<string, number>();
-  for (const key of keys) {
-    const headerLabel = headers[key];
-    if (headerLabel === undefined) continue;
-    let maxWidth = stripAnsi(headerLabel).length;
-    for (const row of rows) {
-      const value = row[key];
-      if (value !== undefined) {
-        const visible = stripAnsi(value).length;
-        if (visible > maxWidth) {
-          maxWidth = visible;
-        }
-      }
-    }
-    widths.set(key, maxWidth);
-  }
-
-  const headerLine = keys
-    .map((key) => {
-      const label = headers[key] ?? key;
-      const target = widths.get(key) ?? stripAnsi(label).length;
-      return label + " ".repeat(Math.max(0, target - stripAnsi(label).length));
-    })
-    .join(" ".repeat(gap));
-
-  const dataLines = rows.map((row) =>
-    keys
-      .map((key) => {
-        const value = row[key] ?? "";
-        const target = widths.get(key) ?? stripAnsi(value).length;
-        return value + " ".repeat(Math.max(0, target - stripAnsi(value).length));
-      })
-      .join(" ".repeat(gap)),
-  );
-
-  return [headerLine, ...dataLines].map((line) => `${indent}${line}`).join("\n");
-}
-
-/**
- * Format key-value pairs as aligned output.
- * Keys are right-padded to the width of the longest key.
- *
- * @example
- * formatKeyValue([["Template", "plant.miravo.yaml"], ["Seed", "42"]])
- * // "  Template:  plant.miravo.yaml\n  Seed:       42"
- */
-export function formatKeyValue(entries: ReadonlyArray<readonly [string, string]>): string {
-  if (entries.length === 0) return "";
-
-  const maxKeyWidth = Math.max(...entries.map(([key]) => stripAnsi(key).length));
-
-  return entries
-    .map(([key, value]) => {
-      const keyWithColon = `${key}:`;
-      const visibleLen = stripAnsi(keyWithColon).length;
-      const padded = keyWithColon + " ".repeat(Math.max(0, maxKeyWidth + 2 - visibleLen));
-      return `    ${padded} ${value}`;
-    })
-    .join("\n");
-}
-
-/**
- * Format a number with locale-aware comma separators.
- * Used for tick counts, message counts, etc.
- */
-export function formatCount(value: number): string {
-  return value.toLocaleString("en-US");
-}
-
-/**
- * Format milliseconds as a human-readable duration string.
- * Examples: "0s", "1.2s", "5m 23s", "1h 2m 15s"
- */
-export function formatDuration(ms: number): string {
-  if (ms < 1_000) return `${ms.toFixed(0)}ms`;
-
-  const totalSeconds = Math.floor(ms / 1_000);
-  const hours = Math.floor(totalSeconds / 3_600);
-  const minutes = Math.floor((totalSeconds % 3_600) / 60);
-  const seconds = totalSeconds % 60;
-
-  const parts: string[] = [];
-  if (hours > 0) parts.push(`${hours}h`);
-  if (minutes > 0) parts.push(`${minutes}m`);
-  if (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`);
-
-  return parts.join(" ");
-}
-
-/**
- * Format the health suffix for an adapter line in pretty/plain CLI output.
- * Returns a string like: " · State: healthy" or " · Pending: 18,420 · State: saturated"
- */
-export function formatHealthSuffix(metrics: AdapterMetrics, sep: string): string {
-  const health = metrics.health;
-  if (!health) return "";
-
-  let suffix = "";
-
-  if (health.pendingWorkCount > 0) {
-    suffix += `${sep}Pending: ${colors.yellow(formatCount(health.pendingWorkCount))}`;
-  }
-
-  suffix += `${sep}State: ${healthStateColor(health.state)}`;
-
-  return suffix;
-}
-
-function healthStateColor(state: AdapterHealthSnapshot["state"]): string {
-  switch (state) {
-    case "healthy":
-      return colors.green(state);
-    case "busy":
-      return colors.yellow(state);
-    case "saturated":
-      return colors.red(state);
-  }
-}
-
-/**
- * Compute average throughput over the entire run.
- * Returns null when there's no meaningful data (zero uptime or zero messages).
- */
-export function computeAverageThroughput(totalMessages: number, uptimeMs: number): number | null {
-  if (uptimeMs <= 0 || totalMessages === 0) return null;
-  return Math.round(totalMessages / (uptimeMs / 1_000));
-}