Skip to content

refactor: send all logging to stderr through an injectable Logger - #66

Merged
IvanKiral merged 2 commits into
add_mapi_commandfrom
worktree-refactor_logging
Aug 17, 2026
Merged

refactor: send all logging to stderr through an injectable Logger#66
IvanKiral merged 2 commits into
add_mapi_commandfrom
worktree-refactor_logging

Conversation

@IvanKiral

@IvanKiral IvanKiral commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Motivation

logInfo wrote to console.log — stdout. Harmless while every command prints prose, but the mapi command this branch builds on writes a response body to stdout. At that point every progress line lands inside the payload: kontent mapi content-types > types.json puts log lines in the JSON, | jq dies on the first one. Fixing the boundary before mapi emits a payload means it lands correct instead of being retrofitted.

What changed

  • All logging goes to stderr, unconditionally. stdout is reserved for command payloads. This is the POSIX meaning of stderr — diagnostics, not just errors — and how curl, git and npm behave.
  • logInfo/logWarning/logError/isVerbose are replaced by a Logger closure. Handlers build it once with createLoggerFromArgs(args) and pass it down; core takes a Logger parameter or carries it in deps, so it no longer sees LogOptions and can be tested by injecting a sink instead of stubbing console.
  • Colour on stderr comes from chalkStderr. chalk derives its level from stdout, so a piped stdout would otherwise strip colour from a stderr that is still a terminal.
  • New src/lib/ui/prompts.ts binds @clack/prompts to stderr in one place rather than at every call site. Side effect: spinners keep animating when stdout is piped, because clack's TTY check reads the stream it is handed.
  • --logLevel is typed end to end. LogLevel derives from the choices tuple, so yargs infers the union; LogOptions stays the flat parser shape and is collapsed into a single level by createLoggerFromArgs.

No user-facing change — --logLevel, --ll, --verbose and KONTENT_LOG_LEVEL behave exactly as before.

Checklist

  • Code follows coding conventions held in this repo
  • Automated tests have been added — existing tests updated to the new signatures; no new behaviour to cover
  • Tests are passing
  • Docs have been updated (CLAUDE.md: output-channel rule and the Logger convention)
  • Temporary settings have been reverted to defaults

How to test

kontent telemetry status 2>/dev/null              # stdout is empty
kontent telemetry status --verbose 1>/dev/null    # every diagnostic still visible
kontent telemetry status --ll bogus               # rejected by yargs choices
kontent project sample bootstrap --envId <id>     # spinners, prompts, notes render
kontent project sample bootstrap --envId <id> 1>/dev/null   # still usable, now on stderr

@IvanKiral
IvanKiral requested a review from a team as a code owner August 13, 2026 09:25
Comment thread src/log.ts Outdated
@IvanKiral
IvanKiral merged commit 63728b0 into add_mapi_command Aug 17, 2026
1 check passed
@IvanKiral
IvanKiral deleted the worktree-refactor_logging branch August 17, 2026 06:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants