(v1) Move log helpers to @repo/utils and finish console.* migration

[yamcodes]

Problem

ArkEnv still has scattered ad-hoc console.* calls and manually-prefixed log strings in several production packages. PR #1294 introduced shared log helpers in @arkenv/build/log.ts, but that placement creates an unnecessary dependency footprint (e.g. pulling chokidar into @arkenv/bun-plugin consumers) and splits formatting utilities away from @repo/utils where styleText, indent, and ArkEnvError already live.

Already done (do not redo)

• Unify error normalization and formatting #709 / PR (v1) Unify error normalization and formatting #1157 (v1): Normalized validation errors — EnvIssue, ArkEnvError, formatIssues, safeArkEnv, credential redaction in @repo/utils.
• PR refactor: introduce shared log helpers in @arkenv/build and standardize warning/error prefixes #1294 (v1): Introduced log helper functions and migrated @arkenv/nextjs, @arkenv/nuxt, and @arkenv/build watcher paths — to be relocated to @repo/utils in this issue.

Scope — Phase 1 (v1)

1. Relocate log helpers to @repo/utils

Move log helper functions from @arkenv/build/log.ts to @repo/utils (e.g. log-helpers.ts):

• BUILD_PREFIX, WATCHER_PREFIX
• formatBuildError, logBuildWarning, logBuildError, logWatcherError
• Extend with any helpers needed for remaining call sites (e.g. logging a secondary error detail line)

Delete @arkenv/build/log entirely — no re-exports. The ./log subpath was added in #1294 (@arkenv/build@0.0.1), has no external consumers, and is safe to remove pre-v1.0 release.

2. Per-package migration rules

Package	Approach
@arkenv/bun-plugin	Bundle log helpers from @repo/utils via alwaysBundle. Zero runtime deps — do not depend on @arkenv/build.
@arkenv/nextjs	Bundle log helpers from @repo/utils via alwaysBundle. Update imports currently using @arkenv/build or @arkenv/build/log.
@arkenv/nuxt	Bundle log helpers from @repo/utils via alwaysBundle. Update imports currently using @arkenv/build.
@arkenv/build	Import log helpers directly from @repo/utils internally. Remove log.ts entry point and ./log export from package.json.
arkenv CLI	LoggerPort only. Instantiate a barebones TextReporter/LoggerPort fallback for unhandled rejections in index.ts when no global logger exists. Never import from @arkenv/build.
Scaffold generated script	Leave console.error. Generated user-run scripts should stay vanilla Node.

3. Remaining call sites to migrate

Build / integration packages

• @arkenv/bun-plugin — schema load failure uses raw console.error
• @arkenv/nextjs — validation failure still prints error body via raw console.error after logBuildError header

CLI (arkenv package)

• injection.ts — dts append failure uses raw console.error
• index.ts — unhandled rejection/exception fallbacks when no global logger is set
• node-project-scanner.adapter.ts — git-not-installed message uses raw console.debug

Explicitly excluded

• scaffold/executor.ts — generated script console.error stays as-is

Constraints

• Do not change ArkEnvError throw formatting or the EnvIssue system.
• Do not introduce a new logging package — use existing @repo/utils.
• Do not add @arkenv/build as a runtime dependency to @arkenv/bun-plugin or arkenv CLI.

Implementation order

1. Add log helpers to @repo/utils (+ tests)
2. Switch @arkenv/build to utils, delete ./log export
3. Migrate nextjs, nuxt, bun-plugin call sites
4. CLI LoggerPort fallback + remaining paths

Out of scope — Phase 2

Tracked in #1300 (v1): injectable logger API, log levels, silent mode, unified abstraction across packages.

Acceptance criteria

• Log helpers live in @repo/utils and are exported from its index
• @arkenv/build/log subpath deleted — no re-exports, log.ts entry removed from tsdown config and package.json exports
• @arkenv/build watcher paths import log helpers from @repo/utils
• @arkenv/bun-plugin, @arkenv/nextjs, @arkenv/nuxt bundle log helpers from @repo/utils — no @arkenv/build dependency added for logging
• No raw [ArkEnv] or [ArkEnv Watcher] string literals outside @repo/utils log helpers
• @arkenv/nextjs validation failure output uses log helpers end-to-end (no raw console.error for the error body)
• CLI paths (injection.ts, index.ts, node-project-scanner.adapter.ts) route through LoggerPort — no ad-hoc console.*
• Scaffold generated script unchanged (console.error preserved)
• Existing tests pass; add/update tests if helper signatures change
• Changesets for affected published packages

Agent brief

See the single consolidated agent brief comment on this issue for the authoritative implementation spec.

Target branch

v1

[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]

related to #1294

[yamcodes]

Phase 2 (injectable logger API) tracked in #1300

[yamcodes]

This was generated by AI during triage.

Agent Brief

Category: enhancement
State: ready for agent
Summary: Move log helpers from @arkenv/build/log to @repo/utils, delete the build log subpath, and finish migrating remaining ad-hoc console.* call sites.

Current behavior

Validation errors are normalized via EnvIssue / ArkEnvError (#1157). PR #1294 added log helpers in @arkenv/build/log.ts with a public ./log export; @arkenv/nextjs, @arkenv/nuxt, and @arkenv/build watcher use them. Several production packages still emit warnings and errors via raw console.*. Placing helpers in @arkenv/build would force packages like @arkenv/bun-plugin to depend on a package that pulls chokidar.

Desired behavior

Log helpers become the source of truth in @repo/utils (alongside styleText, indent, ArkEnvError). @arkenv/build/log is deleted with no re-exports. Integration packages bundle helpers from @repo/utils. CLI uses LoggerPort exclusively, with a barebones fallback for pre-logger fatal paths. Generated scaffold scripts keep vanilla console.error.

Key interfaces

• @repo/utils log helpers — BUILD_PREFIX, WATCHER_PREFIX, formatBuildError, logBuildWarning, logBuildError, logWatcherError. Add helpers only if existing ones cannot cover a call site.
• @arkenv/build optional Logger type — watcher callbacks accept { error(msg) }; fallbacks delegate to logWatcherError from @repo/utils.
• LoggerPort (CLI) — use for all CLI output paths. For unhandled rejections before global logger exists, instantiate a barebones TextReporter-backed fallback that handles non-Error throws (strings, plain objects).
• ArkEnvError / EnvIssue — no changes.

Per-package rules

Package	Approach
@arkenv/bun-plugin	Bundle from @repo/utils via alwaysBundle. Zero runtime deps. No @arkenv/build.
@arkenv/nextjs, @arkenv/nuxt	Bundle from @repo/utils via alwaysBundle. Update imports away from @arkenv/build/log.
@arkenv/build	Import from @repo/utils internally. Delete log.ts entry and ./log export.
arkenv CLI	LoggerPort only. Never @arkenv/build.
Scaffold generated script	Leave console.error.

Implementation order

1. Add log helpers to @repo/utils (+ tests)
2. Switch @arkenv/build to utils, delete ./log export
3. Migrate nextjs, nuxt, bun-plugin call sites
4. CLI LoggerPort fallback + remaining paths

Acceptance criteria

• Log helpers exported from @repo/utils
• @arkenv/build/log subpath deleted — no re-exports
• @arkenv/bun-plugin bundles log helpers, maintains zero runtime deps
• @arkenv/nextjs validation failure fully routed through log helpers
• CLI production paths use LoggerPort — no ad-hoc console.*
• No raw [ArkEnv] / [ArkEnv Watcher] literals outside @repo/utils
• @repo/utils in devDependencies (not dependencies) for packages using alwaysBundle
• Changeset bumps @arkenv/build minor (breaking ./log removal in 0.x)
• All tests pass

Out of scope

• Injectable logger API ((v1) Injectable logger API across ArkEnv packages #1300)
• ArkEnvError / EnvIssue changes
• Scaffold generated script migration
• fumadocs-ui, test fixtures, changelog examples

Target branch: v1