feature: FileLogHandler docs + FileSystem auto-init + .rotating recovery

[xerial]

Bundles four related changes that all sit under "make rotated file logging usable in uni":

Summary

• Remove legacy LogRotationHandler (JVM-only, dead code) so cross-platform FileLogHandler is the single canonical handler. FileHandler users migrate to FileLogHandlerConfig(...).noRotation.
• Document FileLogHandler in docs/core/logging.md: defaults (daily + 100 MB rotation, gzip, 100-file retention), the withXxx builder, .noCompression / .noRotation escape hatches.
• Auto-init FileSystem / IOWatch on first touch so callers (FileLogHandler, IO.readAsString, app code) no longer need an explicit FileSystemInit.init(). Lazy first-touch in impl() rather than the object body, per Gemini's reentrancy concern. Drops the now-redundant call from IO.scala.
• .rotating temp-file recovery in FileLogHandler.init() so a crash mid-rotation no longer leaves dangling log data: if logPath is absent we restore the orphan as the active log, otherwise we archive it under {stem}-recovered-{ts}.log.

Test plan

• ./sbt scalafmtAll compile — clean across JVM / Scala.js / Scala Native
• ./sbt uniJVM/testOnly wvlet.uni.log.* wvlet.uni.io.* wvlet.uni.control.* — 237/237 pass, including the new IOReadAsStringJvmTest chain (proves auto-init works without explicit FileSystemInit.init() via IO) and the two new FileLogHandlerTest recovery cases
• ./sbt uniJS/testOnly ... + ./sbt uniNative/testOnly ... — focused runs green on JS and Native, incl. new FileSystemAutoInitTest and the two recovery tests
• pnpm docs:build — docs site builds cleanly

Review

• Addressed all four Gemini items (high-priority circular-init concern, noCompression doc wording, plan scope, .rotating durability gap) in commit de910a6.

🤖 Generated with Claude Code

[xerial]

/gemini review

[gemini-code-assist]

Code Review

This pull request removes the legacy JVM-only LogRotationHandler and its FileHandler wrapper, as they are redundant with the existing cross-platform FileLogHandler. A new plan document has been added to the plans/ directory to document the context, decision, and scope of this removal. I have no feedback to provide as there were no review comments to evaluate.

[gemini-code-assist]

Code Review

This pull request removes the legacy JVM-only LogRotationHandler and FileHandler, as they are redundant with the cross-platform FileLogHandler. Feedback indicates that this removal may cause a regression in log durability because the legacy implementation included logic to recover orphaned temporary files after a crash, a feature currently missing from the replacement handler.

[gemini-code-assist]

The assertion that FileLogHandler fully covers the use cases of the deleted LogRotationHandler overlooks the orphaned file recovery logic present in the legacy implementation (LogRotationHandler.recoverTempFiles, lines 259-274). In FileLogHandler.rotate, a .rotating temporary file is created during the compression phase. If the process crashes before this file is compressed and deleted, the log data remains in the .rotating file and is not automatically recovered or appended to upon restart. The legacy handler included a mechanism to scan for and restore these temporary files during initialization. To avoid a regression in log durability, a similar recovery mechanism should be implemented in FileLogHandler.

[xerial]

Added a Writing Logs to a File section in docs/core/logging.md covering FileLogHandler / FileLogHandlerConfig defaults, the builder/escape-hatch surface, and the FileSystemInit.init() startup step on Scala.js and Scala Native. The cross-platform handler was already in the code (PR #393) but undocumented — this surfaces it. Verified with pnpm docs:build. Re-running review since the diff grew: /gemini review

[gemini-code-assist]

Code Review

This pull request removes the legacy JVM-only LogRotationHandler and FileHandler classes, consolidating logging functionality into the cross-platform FileLogHandler. It adds a design plan for this removal and updates the documentation to include usage examples and configuration details for FileLogHandler. Review feedback suggests clarifying that the noCompression option preserves the configured file extension rather than just the default .log extension. Additionally, the plan document should be updated to include documentation changes within its scope, as they were implemented in this PR.

[gemini-code-assist]

The description for noCompression states that rotated files keep their .log extension. However, if a custom extension is configured via withLogFileExt, the rotated files will use that extension instead. It would be more accurate to say they keep their configured extension.

Suggested change

	| `noCompression` | Disable gzip; rotated files keep their `.log` extension. |
	| noCompression | Disable gzip; rotated files keep their configured extension (default: .log). |

[gemini-code-assist]

This pull request includes documentation for FileLogHandler in docs/core/logging.md. This item should be moved to the Scope section to accurately reflect the work performed in this PR.

[xerial]

Bundled the FileSystem auto-init follow-up here per your request. Now: FileSystem and IOWatch shared objects each call FileSystemInit.init() in their own body, so any first touch (FileSystem.exists, FileLogHandler, IO.readAsString, IOWatch.watch) self-bootstraps the platform impl. The same pattern Logger ↔ LogEnv already uses. Verified by a new FileSystemAutoInitTest that deliberately omits FileSystemInit.init() and runs green on JVM, JS, and Native, plus the now-existing-as-regression IOReadAsStringJvmTest which previously relied on IO calling init() (call removed in this commit). Docs caveat in core/logging.md dropped accordingly.

/gemini review

[gemini-code-assist]

Code Review

This pull request replaces the legacy JVM-only LogRotationHandler with the cross-platform FileLogHandler, adds detailed documentation for its usage, and introduces automatic platform-specific initialization for FileSystem and IOWatch. Reviewers identified a potential circular dependency risk in the FileSystem static initializer and suggested using lazy initialization instead. Additionally, feedback recommended refining the documentation for noCompression to account for custom file extensions and updating the project plan to correctly reflect that documentation was included in this PR.

[gemini-code-assist]

Calling FileSystemInit.init() during the static initialization of the FileSystem object carries a risk of circular dependency or IllegalStateException. If the platform-specific implementation's constructor or static initializer attempts to use FileSystem methods (like exists or currentDirectory) before setImplementation is called, it will trigger the impl check and throw an exception. A more robust approach would be to perform this initialization lazily inside the impl method when _impl is first found to be null, ensuring that init() is only called when needed and after the object is partially initialized.

[gemini-code-assist]

The description for noCompression states that rotated files keep their .log extension. However, FileLogHandlerConfig allows customizing the extension via withLogFileExt. It would be more accurate to say they keep their original extension (e.g., .log or .txt).

Suggested change

	| `noCompression` | Disable gzip; rotated files keep their `.log` extension. |
	| `noCompression` | Disable gzip; rotated files keep their original extension. |

[gemini-code-assist]

This line states that documentation changes are out of scope and that the docs don't currently mention either handler. However, this PR actually adds comprehensive documentation for FileLogHandler in docs/core/logging.md. This section should be updated to reflect that documentation is included in the scope of this PR.

[xerial]

Addressed all four Gemini items in de910a6:

[HIGH] Circular dependency in FileSystem static init. Moved FileSystemInit.init() from the object body into a lazy first-touch inside impl() on both FileSystem and IOWatch. A platform impl that referenced FileSystem mid-bootstrap would no longer trip the null check — init runs only when actually needed.

[MED] .rotating durability gap. FileLogHandler.init() now scans for a .{logPath.fileName}.rotating orphan: if logPath is missing we restore the temp as the active log; otherwise we archive it under {stem}-recovered-{ts}.log. Two new tests (recover .rotating temp file when active log is missing and archive .rotating temp file when active log already exists) cover both paths and pass on JVM/JS/Native. Note: the legacy LogRotationHandler.recoverTempFiles looked for .tmp files that no codepath ever created, so this is actually an improvement over the dropped handler rather than a regression patch.

[MED] noCompression doc wording. Now reads "rotated files keep their configured extension (default .log)".

[MED] Plan scope. Docs, auto-init, and .rotating recovery moved into the Scope section.

/gemini review

[gemini-code-assist]

Code Review

This pull request replaces the legacy JVM-only LogRotationHandler with the cross-platform FileLogHandler, updates the logging documentation, and implements lazy self-bootstrapping for FileSystem and IOWatch. Additionally, it introduces a recovery mechanism for .rotating temporary files in FileLogHandler to ensure log data is preserved after a crash. Review feedback highlights that the lazy initialization of FileSystem and IOWatch is not thread-safe and recommends using synchronized blocks to prevent redundant initialization calls.

[gemini-code-assist]

The lazy initialization of _impl is not thread-safe. While _impl is volatile, multiple threads could simultaneously enter the else block and call FileSystemInit.init() if they all observe _impl as null at startup. Although FileSystemInit.init() might be idempotent, it is better to use a synchronized block to ensure initialization happens exactly once and to avoid redundant calls to the platform-specific bootstrap logic.

  private def impl: FileSystemBase =
    val current = _impl
    if current != null then
      current
    else
      this.synchronized {
        if _impl == null then
          // First touch: trigger the platform-specific FileSystemInit, which writes back via
          // setImplementation as part of its own static initializer. Lazy (rather than in the
          // object body) so a partly-initialized platform object can't observe FileSystem
          // mid-bootstrap.
          FileSystemInit.init()
      }
      val after = _impl
      if after == null then
        throw IllegalStateException(
          "FileSystem not initialized. Platform-specific initialization required."
        )
      after

[gemini-code-assist]

Similar to FileSystem.impl, this lazy initialization lacks synchronization. Multiple concurrent calls to IOWatch.watch on a fresh JVM could trigger multiple calls to FileSystemInit.init(). Adding a synchronized block ensures thread-safe initialization.

  private def impl: IOWatchBase =
    val current = _impl
    if current != null then
      current
    else
      this.synchronized {
        if _impl == null then
          // FileSystemInit also registers the platform IOWatch implementation, so triggering it
          // here lets IOWatch.watch self-bootstrap even when FileSystem hasn't been touched yet.
          FileSystemInit.init()
      }
      val after = _impl
      if after == null then
        throw IllegalStateException(
          "IOWatch not initialized. Platform-specific initialization required."
        )
      after