feat(cli): add json schema to cli tool (#54523)

Merged via squash.

Prepared head SHA: 39c15ee70d
Co-authored-by: kvokka <15954013+kvokka@users.noreply.github.com>
Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com>
Reviewed-by: @altaywtf

src/logging/config.test.ts

@@ -0,0 +1,28 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const loadConfigMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../config/config.js", () => ({
+  loadConfig: () => loadConfigMock(),
+}));
+
+const originalArgv = process.argv;
+
+describe("readLoggingConfig", () => {
+  afterEach(() => {
+    process.argv = originalArgv;
+    loadConfigMock.mockReset();
+  });
+
+  it("skips mutating config loads for config schema", async () => {
+    process.argv = ["node", "openclaw", "config", "schema"];
+    loadConfigMock.mockImplementation(() => {
+      throw new Error("loadConfig should not be called");
+    });
+
+    const { readLoggingConfig } = await import("./config.js");
+
+    expect(readLoggingConfig()).toBeUndefined();
+    expect(loadConfigMock).not.toHaveBeenCalled();
+  });
+});

src/logging/config.ts

@@ -1,8 +1,17 @@
+import { getCommandPathWithRootOptions } from "../cli/argv.js";
 import { loadConfig, type OpenClawConfig } from "../config/config.js";
 
 type LoggingConfig = OpenClawConfig["logging"];
 
+export function shouldSkipMutatingLoggingConfigRead(argv: string[] = process.argv): boolean {
+  const [primary, secondary] = getCommandPathWithRootOptions(argv, 2);
+  return primary === "config" && (secondary === "schema" || secondary === "validate");
+}
+
 export function readLoggingConfig(): LoggingConfig | undefined {
+  if (shouldSkipMutatingLoggingConfigRead()) {
+    return undefined;
+  }
   try {
     const parsed = loadConfig();
     const logging = parsed?.logging;

src/logging/console-settings.test.ts

@@ -1,8 +1,11 @@
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { captureConsoleSnapshot, type ConsoleSnapshot } from "./test-helpers/console-snapshot.js";
 
+const shouldSkipMutatingLoggingConfigReadMock = vi.hoisted(() => vi.fn(() => false));
+
 vi.mock("./config.js", () => ({
   readLoggingConfig: () => undefined,
+  shouldSkipMutatingLoggingConfigRead: () => shouldSkipMutatingLoggingConfigReadMock(),
 }));
 
 vi.mock("./logger.js", () => ({
@@ -30,6 +33,8 @@ beforeAll(async () => {
 
 beforeEach(() => {
   loadConfigCalls = 0;
+  shouldSkipMutatingLoggingConfigReadMock.mockReset();
+  shouldSkipMutatingLoggingConfigReadMock.mockReturnValue(false);
   snapshot = captureConsoleSnapshot();
   originalIsTty = process.stdout.isTTY;
   originalOpenClawTestConsole = process.env.OPENCLAW_TEST_CONSOLE;

src/logging/console.ts

@@ -2,7 +2,7 @@ import util from "node:util";
 import type { OpenClawConfig } from "../config/types.js";
 import { isVerbose } from "../global-state.js";
 import { stripAnsi } from "../terminal/ansi.js";
-import { readLoggingConfig } from "./config.js";
+import { readLoggingConfig, shouldSkipMutatingLoggingConfigRead } from "./config.js";
 import { resolveEnvLogLevelOverride } from "./env-log-level.js";
 import { type LogLevel, normalizeLogLevel } from "./levels.js";
 import { getLogger, type LoggerSettings } from "./logger.js";
@@ -73,7 +73,7 @@ function resolveConsoleSettings(): ConsoleSettings {
 
   let cfg: OpenClawConfig["logging"] | undefined =
     (loggingState.overrideSettings as LoggerSettings | null) ?? readLoggingConfig();
-  if (!cfg) {
+  if (!cfg && !shouldSkipMutatingLoggingConfigRead()) {
     if (loggingState.resolvingConsoleSettings) {
       cfg = undefined;
     } else {

src/logging/logger-settings.test.ts

@@ -1,14 +1,17 @@
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
-const { fallbackRequireMock, readLoggingConfigMock } = vi.hoisted(() => ({
-  readLoggingConfigMock: vi.fn(() => undefined),
-  fallbackRequireMock: vi.fn(() => {
-    throw new Error("config fallback should not be used in this test");
-  }),
-}));
+const { fallbackRequireMock, readLoggingConfigMock, shouldSkipMutatingLoggingConfigReadMock } =
+  vi.hoisted(() => ({
+    readLoggingConfigMock: vi.fn(() => undefined),
+    shouldSkipMutatingLoggingConfigReadMock: vi.fn(() => false),
+    fallbackRequireMock: vi.fn(() => {
+      throw new Error("config fallback should not be used in this test");
+    }),
+  }));
 
 vi.mock("./config.js", () => ({
   readLoggingConfig: readLoggingConfigMock,
+  shouldSkipMutatingLoggingConfigRead: shouldSkipMutatingLoggingConfigReadMock,
 }));
 
 vi.mock("./node-require.js", () => ({
@@ -29,6 +32,8 @@ beforeEach(() => {
   delete process.env.OPENCLAW_TEST_FILE_LOG;
   delete process.env.OPENCLAW_LOG_LEVEL;
   readLoggingConfigMock.mockClear();
+  shouldSkipMutatingLoggingConfigReadMock.mockReset();
+  shouldSkipMutatingLoggingConfigReadMock.mockReturnValue(false);
   fallbackRequireMock.mockClear();
   logging.resetLogger();
   logging.setLoggerOverride(null);
@@ -63,4 +68,14 @@ describe("getResolvedLoggerSettings", () => {
     const settings = logging.getResolvedLoggerSettings();
     expect(settings.level).toBe("info");
   });
+
+  it("skips fallback config loads for config schema", () => {
+    process.env.OPENCLAW_TEST_FILE_LOG = "1";
+    shouldSkipMutatingLoggingConfigReadMock.mockReturnValue(true);
+
+    const settings = logging.getResolvedLoggerSettings();
+
+    expect(settings.level).toBe("info");
+    expect(fallbackRequireMock).not.toHaveBeenCalled();
+  });
 });

src/logging/logger.settings.test.ts

@@ -1,16 +1,19 @@
 import { describe, expect, it } from "vitest";
 import { __test__ } from "./logger.js";
 
-describe("shouldSkipLoadConfigFallback", () => {
-  it("matches config validate invocations", () => {
-    expect(__test__.shouldSkipLoadConfigFallback(["node", "openclaw", "config", "validate"])).toBe(
-      true,
-    );
+describe("shouldSkipMutatingLoggingConfigRead", () => {
+  it("matches config schema and validate invocations", () => {
+    expect(
+      __test__.shouldSkipMutatingLoggingConfigRead(["node", "openclaw", "config", "schema"]),
+    ).toBe(true);
+    expect(
+      __test__.shouldSkipMutatingLoggingConfigRead(["node", "openclaw", "config", "validate"]),
+    ).toBe(true);
   });
 
   it("handles root flags before config validate", () => {
     expect(
-      __test__.shouldSkipLoadConfigFallback([
+      __test__.shouldSkipMutatingLoggingConfigRead([
         "node",
         "openclaw",
         "--profile",
@@ -25,8 +28,10 @@ describe("shouldSkipLoadConfigFallback", () => {
 
   it("does not match other commands", () => {
     expect(
-      __test__.shouldSkipLoadConfigFallback(["node", "openclaw", "config", "get", "foo"]),
+      __test__.shouldSkipMutatingLoggingConfigRead(["node", "openclaw", "config", "get", "foo"]),
     ).toBe(false);
-    expect(__test__.shouldSkipLoadConfigFallback(["node", "openclaw", "status"])).toBe(false);
+    expect(__test__.shouldSkipMutatingLoggingConfigRead(["node", "openclaw", "status"])).toBe(
+      false,
+    );
   });
 });

src/logging/logger.ts

@@ -1,13 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Logger as TsLogger } from "tslog";
-import { getCommandPathWithRootOptions } from "../cli/argv.js";
 import type { OpenClawConfig } from "../config/types.js";
 import {
   POSIX_OPENCLAW_TMP_DIR,
   resolvePreferredOpenClawTmpDir,
 } from "../infra/tmp-openclaw-dir.js";
-import { readLoggingConfig } from "./config.js";
+import { readLoggingConfig, shouldSkipMutatingLoggingConfigRead } from "./config.js";
 import type { ConsoleStyle } from "./console.js";
 import { resolveEnvLogLevelOverride } from "./env-log-level.js";
 import { type LogLevel, levelToMinLevel, normalizeLogLevel } from "./levels.js";
@@ -72,11 +71,6 @@ export type LogTransport = (logObj: LogTransportRecord) => void;
 
 const externalTransports = new Set<LogTransport>();
 
-function shouldSkipLoadConfigFallback(argv: string[] = process.argv): boolean {
-  const [primary, secondary] = getCommandPathWithRootOptions(argv, 2);
-  return primary === "config" && secondary === "validate";
-}
-
 function attachExternalTransport(logger: TsLogger<LogObj>, transport: LogTransport): void {
   logger.attachTransport((logObj: LogObj) => {
     if (!externalTransports.has(transport)) {
@@ -121,7 +115,7 @@ function resolveSettings(): ResolvedSettings {
 
   let cfg: OpenClawConfig["logging"] | undefined =
     (loggingState.overrideSettings as LoggerSettings | null) ?? readLoggingConfig();
-  if (!cfg && !shouldSkipLoadConfigFallback()) {
+  if (!cfg && !shouldSkipMutatingLoggingConfigRead()) {
     try {
       const loaded = requireConfig?.("../config/config.js") as
         | {
@@ -333,7 +327,7 @@ export function registerLogTransport(transport: LogTransport): () => void {
 }
 
 export const __test__ = {
-  shouldSkipLoadConfigFallback,
+  shouldSkipMutatingLoggingConfigRead,
 };
 
 function formatLocalDate(date: Date): string {