🤖 refactor: unify logging with configurable log levels

- Add log levels: error, warn, info, debug (hierarchical)
- Add log.warn() method and log.setLevel()/getLevel() for programmatic control
- CLI defaults to 'error' level (quiet), Desktop defaults to 'info'
- Add --verbose/-v flag to mux run to enable info-level logs
- Add --log-level flag for explicit level control
- Migrate all console.error/warn calls in src/node/ to log.*
- Migrate ORPC error handler to use log.error
- Fix circular dependency: log.ts no longer imports defaultConfig

Environment variable MUX_LOG_LEVEL=error|warn|info|debug overrides defaults.
MUX_DEBUG=1 enables debug level as before.

_Generated with mux_

Author: ammar-agent

src/cli/orpcServer.ts

@@ -17,6 +17,7 @@ import { router } from "@/node/orpc/router";
 import type { ORPCContext } from "@/node/orpc/context";
 import { extractWsHeaders } from "@/node/orpc/authMiddleware";
 import { VERSION } from "@/version";
+import { log } from "@/node/services/log";
 
 // --- Types ---
 
@@ -71,7 +72,7 @@ export async function createOrpcServer({
   context,
   serveStatic = false,
   staticDir = path.join(__dirname, ".."),
-  onOrpcError = (error) => console.error("ORPC Error:", error),
+  onOrpcError = (error) => log.error("ORPC Error:", error),
 }: OrpcServerOptions): Promise<OrpcServer> {
   // Express app setup
   const app = express();

src/cli/run.ts

@@ -38,6 +38,7 @@ import type { RuntimeConfig } from "@/common/types/runtime";
 import { parseRuntimeModeAndHost, RUNTIME_MODE } from "@/common/types/runtime";
 import assert from "@/common/utils/assert";
 import parseDuration from "parse-duration";
+import { log, type LogLevel } from "@/node/services/log";
 
 type CLIMode = "plan" | "exec";
 
@@ -163,6 +164,8 @@ program
   .option("--mode <mode>", "agent mode: plan or exec", "exec")
   .option("-t, --thinking <level>", "thinking level: off, low, medium, high", "medium")
   .option("--timeout <duration>", "timeout (e.g., 5m, 300s, 300000)")
+  .option("-v, --verbose", "show info-level logs (default: errors only)")
+  .option("--log-level <level>", "set log level: error, warn, info, debug")
   .option("--json", "output NDJSON for programmatic consumption")
   .option("-q, --quiet", "only output final result")
   .option("--workspace-id <id>", "explicit workspace ID (auto-generated if not provided)")
@@ -189,6 +192,8 @@ interface CLIOptions {
   mode: string;
   thinking: string;
   timeout?: string;
+  verbose?: boolean;
+  logLevel?: string;
   json?: boolean;
   quiet?: boolean;
   workspaceId?: string;
@@ -199,6 +204,20 @@ const opts = program.opts<CLIOptions>();
 const messageArg = program.args[0];
 
 async function main(): Promise<void> {
+  // Configure log level early (before any logging happens)
+  if (opts.logLevel) {
+    const level = opts.logLevel.toLowerCase();
+    if (level === "error" || level === "warn" || level === "info" || level === "debug") {
+      log.setLevel(level as LogLevel);
+    } else {
+      console.error(`Invalid log level "${opts.logLevel}". Expected: error, warn, info, debug`);
+      process.exit(1);
+    }
+  } else if (opts.verbose) {
+    log.setLevel("info");
+  }
+  // Default is already "warn" for CLI mode (set in log.ts)
+
   // Resolve directory
   const projectDir = path.resolve(opts.dir);
   await ensureDirectory(projectDir);
@@ -236,14 +255,13 @@ async function main(): Promise<void> {
     if (emitJson) process.stdout.write(`${JSON.stringify(payload)}\n`);
   };
 
-  if (!suppressHumanOutput) {
-    console.error(`[mux run] Directory: ${projectDir}`);
-    console.error(`[mux run] Model: ${model}`);
-    console.error(
-      `[mux run] Runtime: ${runtimeConfig.type}${runtimeConfig.type === "ssh" ? ` (${runtimeConfig.host})` : ""}`
-    );
-    console.error(`[mux run] Mode: ${initialMode}`);
-  }
+  // Log startup info (shown at info+ level, i.e., with --verbose)
+  log.info(`Directory: ${projectDir}`);
+  log.info(`Model: ${model}`);
+  log.info(
+    `Runtime: ${runtimeConfig.type}${runtimeConfig.type === "ssh" ? ` (${runtimeConfig.host})` : ""}`
+  );
+  log.info(`Mode: ${initialMode}`);
 
   // Initialize services
   const historyService = new HistoryService(config);

src/node/config.ts

@@ -3,6 +3,7 @@ import * as path from "path";
 import * as crypto from "crypto";
 import * as jsonc from "jsonc-parser";
 import writeFileAtomic from "write-file-atomic";
+import { log } from "@/node/services/log";
 import type { WorkspaceMetadata, FrontendWorkspaceMetadata } from "@/common/types/workspace";
 import type { Secret, SecretsConfig } from "@/common/types/secrets";
 import type { Workspace, ProjectConfig, ProjectsConfig } from "@/common/types/project";
@@ -64,7 +65,7 @@ export class Config {
         }
       }
     } catch (error) {
-      console.error("Error loading config:", error);
+      log.error("Error loading config:", error);
     }
 
     // Return default config
@@ -85,7 +86,7 @@ export class Config {
 
       await writeFileAtomic(this.configFile, JSON.stringify(data, null, 2), "utf-8");
     } catch (error) {
-      console.error("Error saving config:", error);
+      log.error("Error saving config:", error);
     }
   }
 
@@ -344,7 +345,7 @@ export class Config {
             workspaceMetadata.push(this.addPathsToMetadata(metadata, workspace.path, projectPath));
           }
         } catch (error) {
-          console.error(`Failed to load/migrate workspace metadata:`, error);
+          log.error(`Failed to load/migrate workspace metadata:`, error);
           // Fallback to basic metadata if migration fails
           const legacyId = this.generateLegacyId(projectPath, workspace.path);
           const metadata: WorkspaceMetadata = {
@@ -431,7 +432,7 @@ export class Config {
       }
 
       if (!workspaceFound) {
-        console.warn(`Workspace ${workspaceId} not found in config during removal`);
+        log.warn(`Workspace ${workspaceId} not found in config during removal`);
       }
 
       return config;
@@ -469,7 +470,7 @@ export class Config {
         return jsonc.parse(data) as ProvidersConfig;
       }
     } catch (error) {
-      console.error("Error loading providers config:", error);
+      log.error("Error loading providers config:", error);
     }
 
     return null;
@@ -510,7 +511,7 @@ ${jsonString}`;
 
       fs.writeFileSync(this.providersFile, contentWithComments);
     } catch (error) {
-      console.error("Error saving providers config:", error);
+      log.error("Error saving providers config:", error);
       throw error; // Re-throw to let caller handle
     }
   }
@@ -526,7 +527,7 @@ ${jsonString}`;
         return JSON.parse(data) as SecretsConfig;
       }
     } catch (error) {
-      console.error("Error loading secrets config:", error);
+      log.error("Error loading secrets config:", error);
     }
 
     return {};
@@ -544,7 +545,7 @@ ${jsonString}`;
 
       await writeFileAtomic(this.secretsFile, JSON.stringify(config, null, 2), "utf-8");
     } catch (error) {
-      console.error("Error saving secrets config:", error);
+      log.error("Error saving secrets config:", error);
       throw error;
     }
   }

src/node/services/ExtensionMetadataService.ts

@@ -8,6 +8,7 @@ import {
   getExtensionMetadataPath,
 } from "@/node/utils/extensionMetadata";
 import type { WorkspaceActivitySnapshot } from "@/common/types/workspace";
+import { log } from "@/node/services/log";
 
 /**
  * Stateless service for managing workspace metadata used by VS Code extension integration.
@@ -74,13 +75,13 @@ export class ExtensionMetadataService {
 
       // Validate structure
       if (typeof parsed !== "object" || parsed.version !== 1) {
-        console.error("[ExtensionMetadataService] Invalid metadata file, resetting");
+        log.error("Invalid metadata file, resetting");
         return { version: 1, workspaces: {} };
       }
 
       return parsed;
     } catch (error) {
-      console.error("[ExtensionMetadataService] Failed to load metadata:", error);
+      log.error("Failed to load metadata:", error);
       return { version: 1, workspaces: {} };
     }
   }
@@ -90,7 +91,7 @@ export class ExtensionMetadataService {
       const content = JSON.stringify(data, null, 2);
       await writeFileAtomic(this.filePath, content, "utf-8");
     } catch (error) {
-      console.error("[ExtensionMetadataService] Failed to save metadata:", error);
+      log.error("Failed to save metadata:", error);
     }
   }
 

src/node/services/compactionHandler.ts

@@ -8,6 +8,7 @@ import type { LanguageModelV2Usage } from "@ai-sdk/provider";
 import { collectUsageHistory } from "@/common/utils/tokens/displayUsage";
 import { sumUsageHistory } from "@/common/utils/tokens/usageAggregator";
 import { createMuxMessage, type MuxMessage } from "@/common/types/message";
+import { log } from "@/node/services/log";
 
 interface CompactionHandlerOptions {
   workspaceId: string;
@@ -71,7 +72,7 @@ export class CompactionHandler {
 
     const result = await this.performCompaction(summary, messages, event.metadata);
     if (!result.success) {
-      console.error("[CompactionHandler] Compaction failed:", result.error);
+      log.error("Compaction failed:", result.error);
       return false;
     }
 

src/node/services/historyService.ts

@@ -54,8 +54,8 @@ export class HistoryService {
           messages.push(normalizeLegacyMuxMetadata(message));
         } catch (parseError) {
           // Skip malformed lines but log error for debugging
-          console.error(
-            `[HistoryService] Skipping malformed JSON at line ${i + 1} in ${workspaceId}/chat.jsonl:`,
+          log.warn(
+            `Skipping malformed JSON at line ${i + 1} in ${workspaceId}/chat.jsonl:`,
             parseError instanceof Error ? parseError.message : String(parseError),
             "\nLine content:",
             lines[i].substring(0, 100) + (lines[i].length > 100 ? "..." : "")