Add reusable CLI debug logging utility

[nerrad]

How AI was used in this PR

I used Codex to scaffold the utility module, then reviewed the API shape and verified the branch with lint, typecheck, a CLI build, and targeted CLI tests.

Proposed Changes

• add a small JSONL debug logger factory at apps/cli/lib/debug-log.ts
• support env-gated enablement and optional log-file overrides
• add direct unit tests for the debug logger behavior
• fix an unrelated lint warning on the branch in provider-constants-slice.ts

Redundancy Check

• checked the existing CLI Logger in apps/cli/logger.ts; it is a user-facing progress/error channel for spinners, IPC status, and loader text, not a persisted debug trace sink
• checked the studio ai command path; progress is wired into the TUI loader, so using the existing logger for raw debug payloads would mix internal tracing into the chat UI
• checked the desktop app logging in apps/studio/src/logging.ts; that is Electron-side rotating console/file logging and is not a reusable standalone CLI debug facility
• checked existing site debug.log support; that captures PHP/WordPress runtime issues, not CLI or agent-tool execution traces
• conclusion: this utility adds value for the AI CLI context because it provides opt-in, file-backed, structured JSONL tracing without interfering with the interactive terminal UI

Potential Follow-ups

• if we want a single logging abstraction later, move this JSONL debug sink behind apps/cli/logger.ts instead of keeping a separate helper
• if adopted more broadly, define a clearer split between user-facing progress logging and internal structured debug logging in the CLI layer
• if we expect wider use, consider standardizing log locations and naming instead of per-feature env vars

Testing Instructions

• Run npx eslint --fix apps/cli/lib/debug-log.ts apps/cli/lib/tests/debug-log.test.ts apps/studio/src/stores/provider-constants-slice.ts
• Run npm test -- apps/cli/lib/tests
• Run npm run typecheck
• Run npm run cli:build
• Example usage:
  • const debugLog = createDebugLogger( { enabledEnvVar: "STUDIO_AI_DEBUG", defaultFilename: "studio-ai-debug.log", scope: "todo-rendering" } );
  • debugLog.log( "todo_tool_use_received", { input } );
• To enable logging at runtime:
  • STUDIO_AI_DEBUG=1
• To override the output path:
  • STUDIO_AI_DEBUG_FILE=/tmp/studio-ai-debug.log

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing 69d0f06 vs trunk

site-editor

Metric	trunk	69d0f06	Diff	Change
load	1744.00 ms	1762.00 ms	+18.00 ms	⚪ 0.0%

site-startup

Metric	trunk	69d0f06	Diff	Change
siteCreation	7141.00 ms	7142.00 ms	+1.00 ms	⚪ 0.0%
siteStartup	3932.00 ms	3922.00 ms	-10.00 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[youknowriad]

I'm hesintant about this PR. How does this relate to the sessions work in #2767 Is it just one part of it?

[nerrad]

How does this relate to the sessions work in #2767 Is it just one part of it?

I wasn't aware of that PR. I was using a variation of this when working on #2772 to help debug calls within the CLI rendering (agents could use it as a fast feedback loop). However given the PR you shared I don't think this is necessary because agents could read the session data to get necessary feedback.