fix(logs): use userspace polling for -f follow mode

[Rinse12]

Summary

• On Windows, bitsocial logs -f silently misses lines appended to the current log file. Root cause: fs.watchFile (libuv's uv_fs_poll_t) is not reliable for cross-process appends on Windows. This is a long-standing platform gap (see nodejs/node#36888).
• Replace fs.watchFile with a self-rescheduling setTimeout poll that calls fs.promises.stat() and reads new bytes when the size grows. This is the pattern production tail-f libraries (@logdna/tail-file, etc.) use precisely because OS file-watcher events are not cross-platform reliable.
• The existing test continues watching old file if no new file appears (test/cli/logs.test.ts:462) acts as the regression test. It was failing on Windows in CI (runs 26140177410, 25375977963).

CPU/IO profile is unchanged — we were already polling, just inside libuv. Now the polling lives in JS, which behaves consistently across platforms.

Closes #40

Test plan

• npm run build && npm run build:test — clean
• npx vitest run test/cli/logs.test.ts on Linux — all 29 logs tests pass, including the previously-Windows-flaky one
• CI Windows job — the real verification; this is what motivated the change
• CI Linux + macOS jobs — confirm no regression on previously-working platforms

Summary by CodeRabbit

• Chores

  • Updated @pkcprotocol/pkc-js dependency to the latest version

• Bug Fixes

  • Improved log tailing in follow mode with enhanced file monitoring that provides better detection of log file changes and rotations. Upgraded shutdown behavior ensures proper cleanup and graceful termination of log operations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0a4c5a5f-0b62-4eb7-8ec7-a89b449a5d30

📥 Commits

Reviewing files that changed from the base of the PR and between 6ab08d6 and b01faab.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (2)

• package.json
• src/cli/commands/logs.ts

---

📝 Walkthrough

Walkthrough

Replace fs.watchFile with a self-rescheduling polling loop in follow mode to fix Windows log tailing, centralize shutdown handling with signal listeners, and update log file switching to work with the new polling mechanism. Independently, bump @pkcprotocol/pkc-js from 0.0.34 to 0.0.35.

Changes

Follow Mode Polling Implementation

Layer / File(s)	Summary
Polling loop and lifecycle management src/cli/commands/logs.ts	Replace fs.watchFile-based detection with a polling flag and self-rescheduling pollLoop that calls readNewData on fixed intervals. Add unified shutdown handler to disable polling, clear timers, and exit cleanly; wire SIGINT and SIGTERM listeners to use this handler.
Log file switching in polling mode src/cli/commands/logs.ts	When a newer log file is detected during polling, update currentLogFile, clear pendingBuffer, emit "switched" status to stderr, and re-read the new file applying existing since, until, and stream filters; reset position from the new file's size.

Dependency Update

Layer / File(s)	Summary
pkc-js dependency version bump package.json	Update @pkcprotocol/pkc-js runtime dependency from 0.0.34 to 0.0.35.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• bitsocialnet/bitsocial-cli#22: Both PRs modify the @pkcprotocol/pkc-js dependency version in package.json.

Poem

🐰 On Windows a watcher did fail,
fs.watchFile told a false tale,
So polling stepped in,
A loop, again and again,
Now the logs follow—no more to bemoan!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: replacing fs.watchFile with userspace polling for follow mode, directly addressing the root cause of the Windows issue.
Linked Issues check	✅ Passed	All coding requirements from issue #40 are met: fs.watchFile replaced with userspace polling using fs.promises.stat(), isolated to logs.ts, and regression test included.
Out of Scope Changes check	✅ Passed	All changes are within scope: package.json dependency bump aligns with the polling implementation, and logs.ts changes directly address the Windows follow mode issue.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/logs-follow-windows-polling

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}