(v1) Injectable logger API across ArkEnv packages

[yamcodes]

Summary

Introduce a user-configurable logging abstraction for ArkEnv — log levels, silent mode, and custom logger injection — unifying the currently separate logging surfaces across build integrations, CLI, and runtime packages.

Follows: #1237 (Phase 1 — finish @arkenv/build/log migration on v1)

Problem

After Phase 1 (#1237) and PR #1294, ArkEnv will have consistent prefix formatting, but logging remains fragmented:

• @arkenv/build/log — static helpers that call console.* directly (logBuildWarning, logBuildError, etc.)
• @arkenv/build Logger type — minimal optional { error, info? } passed to watcher callbacks
• CLI LoggerPort — rich CLI-specific interface (spinners, JSON mode, --quiet, fatal, flush)
• ArkEnvError — thrown validation errors with styled formatting (separate from logging; done in (v1) Unify error normalization and formatting #1157)

There is no way for consumers to suppress warnings, redirect output, or provide a custom logger across integrations. Each surface was designed independently.

Desired behavior

A shared, injectable logger API that:

• Lets consumers provide a custom logger instance or configure log level / silent mode
• Works across Node, Bun, and browser-compatible packages (no Node-only assumptions in shared code)
• Keeps thrown validation errors (ArkEnvError) separate from logged warnings/errors
• Subsumes or bridges the existing @arkenv/build Logger type and @arkenv/build/log static helpers without breaking Phase 1 output format
• Does not require CLI-specific features (spinners, JSON reporters) in the shared interface — CLI LoggerPort may adapt the shared type

Open design questions

1. Package placement: New internal package (e.g. @arkenv/log or @repo/log), module inside @arkenv/internal/utils, or extension of @arkenv/build/log?
2. API surface: Which methods? (error, warn, info, debug?) Support silent mode, env-driven log levels (ARKENV_LOG_LEVEL?), user-provided instances?
3. Runtime constraints: How do browser-compatible packages avoid Node-only behavior (e.g. process.exit in Next.js config on validation failure)?
4. Relationship to CLI: Should LoggerPort implement/extend the shared interface, or remain a CLI-only adapter that wraps it?
5. Relationship to ArkEnvError: Keep formatting in the throw path, or allow the logger to control output style for validation failures?

Prerequisites

• Phase 1 ((v1) Move log helpers to @repo/utils and finish console.* migration #1237) merged on v1 — all ad-hoc console.* call sites migrated to @arkenv/build/log or LoggerPort

Acceptance criteria

• Shared logger interface defined and published (or internal-only, with clear export path)
• Build integrations (@arkenv/build, @arkenv/nextjs, @arkenv/nuxt, @arkenv/bun-plugin, @arkenv/vite-plugin) accept an optional logger and fall back to sensible defaults
• Silent / log-level configuration supported (env var and/or programmatic)
• CLI LoggerPort integrates with the shared interface without losing JSON/quiet/spinner behavior
• ArkEnvError throw behavior unchanged unless explicitly redesigned and documented
• Browser-compatible packages do not introduce Node-only APIs in the shared logger
• Tests cover custom logger injection, silent mode, and default fallback behavior
• Changesets for affected published packages
• Documentation updated with logger configuration examples

Out of scope

• Re-normalizing validation errors (EnvIssue, formatIssues, safeArkEnv) — done in (v1) Unify error normalization and formatting #1157
• Phase 1 prefix migration — tracked in (v1) Move log helpers to @repo/utils and finish console.* migration #1237
• Replacing third-party logging libraries in consumer apps
• v0 (dev) feature work — this ships with the v1 breaking release

Target branch

v1 — v1 is the upcoming breaking release; new cross-cutting APIs belong here, not on dev (v0 maintenance).

Related

• (v1) Move log helpers to @repo/utils and finish console.* migration #1237 — Phase 1 (v1): finish migrating warnings/errors to @arkenv/build/log
• Unify error normalization and formatting #709 / PR (v1) Unify error normalization and formatting #1157 — validation error normalization (done)
• PR refactor: introduce shared log helpers in @arkenv/build and standardize warning/error prefixes #1294 — shared build log helpers (done)

[pullfrog]

This run croaked 😵

The workflow encountered an error before any progress could be reported. Please check the link below for details.

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[yamcodes]

This was generated by AI during triage.

Ready for human

Category: enhancement
State: ready for human

Why this isn't AFK-ready yet

Phase 2 requires maintainer design decisions before an agent can implement safely: where the shared logger lives, how it relates to the existing CLI LoggerPort and @arkenv/build/log helpers, and whether browser-compatible packages need different fallbacks. These choices affect package boundaries and public API surface across the monorepo.

Context from triage

• Phase 1 ((v1) Move log helpers to @repo/utils and finish console.* migration #1237) handles the mechanical migration of remaining console.* call sites on v1 — must land first.
• PR refactor: introduce shared log helpers in @arkenv/build and standardize warning/error prefixes #1294 established static build log helpers in @arkenv/build/log.ts — Phase 2 should wrap or replace these, not ignore them.
• CLI LoggerPort already supports text/JSON/silent reporters — the shared interface should be a subset that LoggerPort can adapt, not a full replacement.
• ArkEnvError formatting is intentionally on the throw path ((v1) Unify error normalization and formatting #1157) — logging and thrown errors should remain separate unless explicitly redesigned.

Suggested next step

Resolve the five open design questions in the issue body, then rewrite as an agent brief with a concrete package layout, interface definition, and migration checklist.

[yamcodes]

Retargeted to v1: v1 is the upcoming breaking release where new cross-cutting APIs belong. dev (v0) is for immediate v0 maintenance only.

[yamcodes]

This was generated by AI during triage.

Expert recommendation

My recommendation on the five open design questions:

1. Package placement: new internal workspace package (e.g. packages/internal/log, published surface only if a real consumer need emerges). Extending @arkenv/build/log couples runtime packages to a build-tool package, and stuffing it into @arkenv/internal/utils makes tree-shaking and browser-safety harder to reason about. A dedicated internal package keeps the dependency direction clean: everything may depend on the logger; the logger depends on nothing.

2. API surface: keep it minimal — error, warn, info, debug + a level threshold. That's the entire shared interface. Silent mode is just level: "silent", not a separate flag. Support both ARKENV_LOG_LEVEL and a programmatic option, with programmatic winning. Resist adding trace, child loggers, or structured metadata until something needs them.

3. Runtime constraints: the shared logger must never call process.exit, and defaults must be console.*-only. Exit behavior is a policy of the caller (CLI, build plugin), not the logger. This is also the fix for the Next.js browser-compat concern — the logger stays pure, the integration decides what "fatal" means.

4. CLI relationship: LoggerPort should satisfy the shared type structurally, not extend it nominally. Spinners, JSON reporters, and flush remain CLI-only. The win is that anything accepting the shared logger can be handed the CLI's logger for free; no adapter class needed if the method names line up.

5. ArkEnvError: keep formatting on the throw path. Thrown errors and logged diagnostics are different channels; letting the logger restyle validation errors reopens (v1) Unify error normalization and formatting #1157 for little gain. Revisit only if a user actually asks for it.

Sequencing: land #1237 first as stated, then implement the interface + default logger in one PR, then thread the optional logger option through the build integrations in a second PR. Doing it all at once will make the review painful across 5+ packages.

The label is right — question 1 and 3 are genuine API-boundary calls that shouldn't be delegated. But once you bless (or amend) the answers above, this can be rewritten as an agent brief.

[yamcodes]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Introduce a unified, user-configurable, browser-safe logging abstraction for ArkEnv — building on Phase 1's consolidated @repo/utils log helpers and existing optional-logger injection patterns.

Current behavior (post–Phase 1, #1237 / PR #1301 — merged on v1):

Phase 1 unified ad-hoc console.* call sites but did not add injectable log levels or a shared logger interface. The current state is:

• @repo/utils log helpers — the canonical logging surface. Static functions with standardized prefixes and symbols:
  • Build channel: BUILD_PREFIX ([ArkEnv]), logBuildWarning (⚠️), logBuildError (❌), logBuildErrorDetail, logBuildErrorBlankLine, logBuildErrorWithCause
  • Watcher channel: WATCHER_PREFIX ([ArkEnv Watcher]), logWatcherError, logWatcherErrorWithCause
  • Bridge helper: logErrorWithCauseVia(log, header, cause) — routes header + stack through a single-message (message: string) => void callback
  • Formatting utilities: formatBuildError, formatErrorCause
• @arkenv/build/log — a re-export shim of the above from @repo/utils (Phase 1 intended to delete this subpath; it remains as a thin compatibility layer and should be removed in Phase 2)
• @arkenv/build Logger type — minimal { error, info? } already passed to watchSchema / closeWatcher. When present, watcher errors use logErrorWithCauseVia(logger.error.bind(logger), …); otherwise they fall back to static logWatcherErrorWithCause
• Integration bundling — @arkenv/nextjs, @arkenv/nuxt, and @arkenv/bun-plugin bundle log helpers from @repo/utils via alwaysBundle (zero runtime deps; no @arkenv/build dependency for logging). @arkenv/vite-plugin was not migrated in Phase 1 and still has no log-helper wiring
• CLI LoggerPort — all CLI paths route through LoggerPort (including a fallback TextReporter for unhandled rejections). safeAppend accepts optional Pick<LoggerPort, "error"> and uses logErrorWithCauseVia when a logger is present, else logBuildErrorWithCause
• Fatal exit policy stays in integrations — e.g. @arkenv/nextjs calls process.exit(1) after logging validation failure; @arkenv/nuxt throws instead. The logger does not decide exit behavior
• ArkEnvError — thrown validation errors with styled formatting on the throw path ((v1) Unify error normalization and formatting #1157); separate from the logging channel
• Scaffold generated scripts — intentionally still use raw console.error (Phase 1 excluded these)

Consumers still cannot configure log levels, suppress warnings globally, or inject a custom logger consistently across all integrations.

Desired behavior:

A shared, injectable logger API that extends Phase 1's work rather than replacing it:

• Preserves existing prefix/symbol output format from @repo/utils log helpers
• Lets consumers provide a custom logger instance or configure log level / silent mode
• Works across Node, Bun, and browser-compatible packages (no Node-only assumptions in shared code)
• Keeps thrown validation errors (ArkEnvError) separate from logged warnings/errors
• Subsumes the existing @arkenv/build Logger type and static @repo/utils log helpers via delegation (not a parallel formatting system)
• Does not require CLI-specific features in the shared interface — CLI LoggerPort structurally satisfies the shared type for overlapping methods
• Removes the @arkenv/build/log re-export shim once integrations consume the injectable logger

---

Context & Prerequisites

• Target branch: v1
• Prerequisite (met): Phase 1 ((v1) Move log helpers to @repo/utils and finish console.* migration #1237, PR fix: (v1) Move log helpers to @repo/utils and finish console.* migration #1301) merged — log helpers live in @repo/utils, integration call sites migrated, CLI paths use LoggerPort, @arkenv/bun-plugin/nextjs/nuxt bundle helpers via alwaysBundle
• Scope: Add injectable logger abstraction; wire through build integrations and remaining gaps (@arkenv/vite-plugin); remove @arkenv/build/log shim
• Out of scope: Refactoring ArkEnvError formatting ((v1) Unify error normalization and formatting #1157), re-doing Phase 1 migration, scaffold generated script logging, replacing third-party logging libraries in consumer apps, or changing dev (v0) packages

---

Architecture & Design Decisions

1. Package placement

Create a new internal workspace package (e.g. @repo/log under packages/internal/log).

• Why now (supersedes Phase 1's "no new logging package" constraint): Phase 1 consolidated formatting into @repo/utils as static helpers. Phase 2 adds stateful concerns (level thresholds, silent mode, injectable instances) that do not belong alongside stateless utilities like indent and styleText
• Relationship to @repo/utils: The existing log helpers and their prefix/symbol formatting should delegate to (or be reimplemented atop) the new default logger instance — not duplicated. @repo/utils may re-export the default logger or thin wrapper functions for backward compatibility during migration
• Visibility: Private workspace package unless a clear public export path is needed for custom logger injection types
• Bundler constraint (from Phase 1): Browser-compatible integrations (nextjs, nuxt, bun-plugin, and newly vite-plugin) must bundle the log package via alwaysBundle — no new runtime dependencies on @arkenv/build

2. Interface definition

Keep the API surface minimal. Do not implement child loggers, tracing, or file transports.

• Methods: error, warn, info, debug
• Signatures: (message: string, ...optionalParams: unknown[]) => void
• Log levels: Threshold configuration (debug → info → warn → error → silent). Silent mode via level: "silent"
• Formatted output helpers: Preserve Phase 1's build/watcher prefix conventions. The injectable logger (or companion helpers) must produce the same visual output as today's logBuildWarning, logBuildError, logWatcherError, etc. — including the logErrorWithCauseVia routing pattern for header + stack output

3. Runtime constraints & environment

• No process.exit: The logger never terminates the process. Integrations retain their existing exit/throw policies (Next.js exits, Nuxt throws, etc.)
• Default fallback: Wrap console.*
• Environment variables: Support ARKENV_LOG_LEVEL; programmatic config takes precedence
• Color support: Respect NO_COLOR / FORCE_COLOR where applicable; degrade gracefully in browser environments

4. Integration with CLI & ArkEnvError

• CLI LoggerPort: Structurally satisfies the shared logger interface for overlapping methods (error, warn, info). No shared base class. Spinners, JSON reporters, flush, fatal, success, step, etc. remain CLI-only
• Existing injection points to extend: @arkenv/build watcher Logger param, CLI safeAppend optional logger, CLI NodeProjectScannerAdapter / NodeWorkspace optional logger picks — these should accept (or adapt from) the shared logger rather than inventing parallel types
• ArkEnvError: Leave entirely alone

---

Key interfaces

• Logger (new shared type) — error, warn, info, debug with level-threshold filtering
• LoggerConfig — optional level; programmatic config overrides ARKENV_LOG_LEVEL
• @arkenv/build Logger — existing minimal watcher callback type; should widen to or accept the shared logger
• logErrorWithCauseVia — existing bridge from Phase 1; should work with shared logger's error method (preserve behavior)
• LoggerPort — CLI port; structurally satisfies shared logger for overlapping methods
• Phase 1 static helpers (logBuildWarning, logBuildErrorWithCause, etc.) — become thin wrappers around default/injected logger instance, not parallel code paths
• @arkenv/build/log — re-export shim to delete once call sites migrate

---

Acceptance criteria

PR 1 — Core package & interface

• Scaffold @repo/log internal package
• Define shared Logger interface and default console implementation with level filtering (error, warn, info, debug, silent)
• Implement ARKENV_LOG_LEVEL parsing and NO_COLOR / FORCE_COLOR handling
• Default logger reproduces Phase 1 prefix/symbol formatting (build vs watcher channels)
• logErrorWithCauseVia-style cause routing works through shared logger
• Unit tests cover level thresholds, silent mode, formatted output parity with Phase 1 helpers, and browser-safe execution

PR 2 — Wiring & integrations

• Refactor @repo/utils log helpers to delegate to injectable/default logger (preserve exports and output shape)
• @arkenv/build, @arkenv/nextjs, @arkenv/nuxt, @arkenv/bun-plugin, @arkenv/vite-plugin accept optional logger config with sensible default
• @arkenv/vite-plugin bundles log helpers via alwaysBundle (Phase 1 gap)
• Watcher and CLI injection points (watchSchema, safeAppend, etc.) accept shared logger type
• Delete @arkenv/build/log re-export shim (entry point, tsdown config, package.json export)
• CLI LoggerPort type-checks against shared Logger interface
• ArkEnvError throw behavior unchanged; scaffold generated scripts unchanged
• Changesets for affected published packages
• Documentation updated with log level configuration and custom logger injection examples

---

Out of scope

• Re-normalizing validation errors — (v1) Unify error normalization and formatting #1157
• Re-doing Phase 1 console.* migration — (v1) Move log helpers to @repo/utils and finish console.* migration #1237 (done)
• Scaffold generated script logging (console.error in user-run scripts)
• Replacing third-party logging libraries in consumer apps
• v0 (dev) feature work
• Child loggers, tracing, structured metadata, or file transports
• Letting the logger restyle or control ArkEnvError output

---

Related

• (v1) Move log helpers to @repo/utils and finish console.* migration #1237 / PR fix: (v1) Move log helpers to @repo/utils and finish console.* migration #1301 — Phase 1 (merged): log helpers in @repo/utils, CLI LoggerPort routing, integration bundling
• Unify error normalization and formatting #709 / PR (v1) Unify error normalization and formatting #1157 — validation error normalization (done)
• PR refactor: introduce shared log helpers in @arkenv/build and standardize warning/error prefixes #1294 — original build log helpers (relocated to @repo/utils in Phase 1)