fix(cli): stop claiming logs --follow implies JSONL

[lidge-jun]

Summary

Carried from #3322 by @luvs01 onto current dev, with the author's Co-authored-by trailer on the commit.

ocx logs --follow documented and errored as though it implied JSONL output, which is not what the code does: bare --follow selects human formatting unless --jsonl is given. The error message, the capability metadata, and the generated skill reference all now say the same thing the output branch actually does — --follow cannot be combined with --json; use --jsonl for streaming JSONL.

The PR still shows CHANGES_REQUESTED, but that review is stale: its exact requested message and its requested tests are both present at the head this carries. Re-review rather than another code change is what it was waiting on.

Closes #3322

Verification

bun test tests/cli-usage-report.test.ts tests/cli-capabilities.test.ts   36 pass, 0 fail
bun run typecheck                                                       exit 0

Both assertions are RED against current dev: the error text at src/cli/observe.ts and the capability declaration at src/cli/capabilities.ts. A third test independently locks the bare---follow human output so the contract cannot drift back.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. (skills/ocx/references/01_management_surface.md regenerates from the capability registry and is included.)
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Co-authored-by: luvs01 27862058+luvs01@users.noreply.github.com

Summary by CodeRabbit

• Bug Fixes

  • Clarified that ocx logs --follow polls for new rows and displays human-readable output by default.
  • JSONL streaming now requires explicitly adding --jsonl; incompatible --follow --json usage provides clearer guidance.

• Documentation

  • Updated the logs command help text to accurately describe follow mode and JSONL output.

• Tests

  • Added coverage for follow-mode output and validation of JSONL streaming options.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-03T17:12:30.876859Z	35a3294	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: efcb3b87-493d-425f-89ce-75b1126eaaa9

📥 Commits

Reviewing files that changed from the base of the PR and between 664d80c and 35a3294.

📒 Files selected for processing (5)

• skills/ocx/references/01_management_surface.md
• src/cli/capabilities.ts
• src/cli/observe.ts
• tests/cli-capabilities.test.ts
• tests/cli-usage-report.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The change corrects ocx logs --follow documentation and validation text. Follow mode now communicates polling behavior, keeps human-readable output by default, and requires --jsonl for JSONL output. Tests cover the capability text and output contracts.

Changes

Logs follow-mode contract

Layer / File(s)	Summary
Update follow-mode contract src/cli/capabilities.ts, skills/ocx/references/01_management_surface.md, src/cli/observe.ts	The --follow descriptions now state that the command polls for new rows. JSONL output requires --jsonl. The --follow --json validation message directs streaming output to --jsonl.
Add follow-mode regression coverage tests/cli-capabilities.test.ts, tests/cli-usage-report.test.ts	Tests verify the capability summary, reject --follow --json with the updated guidance, and confirm that bare --follow renders human-readable rows.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 35a32

This change aligns logs follow-mode messaging, validation, and reference material with the existing human-readable default while preserving explicit JSONL selection. Regression coverage addresses the invalid JSON combination and bare follow output, with no current merge-blocking risk identified.

Suggested reviewers: luvs01

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files. (1 skipped: 1 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the primary change: correcting the claim that ocx logs --follow implies JSONL output.
Linked Issues check	✅ Passed	The changes satisfy issue #3322. They update the capability metadata and management-surface reference, correct the --follow --json error, and add regression tests for explicit JSONL streaming and hu…
Out of Scope Changes check	✅ Passed	The changes remain within issue #3322. They are limited to CLI descriptions, the generated reference, validation messaging, and focused regression tests. No unrelated code or behavior changes are pres…

Full details: Linked Issues check

Explanation

The changes satisfy issue #3322. They update the capability metadata and management-surface reference, correct the --follow --json error, and add regression tests for explicit JSONL streaming and human-readable bare --follow output. No changes alter log streaming or authentication behavior.

Full details: Out of Scope Changes check

Explanation

The changes remain within issue #3322. They are limited to CLI descriptions, the generated reference, validation messaging, and focused regression tests. No unrelated code or behavior changes are present.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/carry-3322

---

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.}

[lidge-jun]

리뷰 · 우선순위 71 / 80

이 PR은 ocx logs --follow가 JSONL을 강제한다고 적혀 있던 문서·에러·능력 표를, 실제 코드 동작과 같게 고칩니다. 지금 dev HEAD(664d80c76)의 src/cli/observe.ts를 보면 --follow는 1초마다 /api/logs를 다시 읽고, --jsonl이 있을 때만 JSON 한 줄씩 찍고, 없으면 formatLog로 사람 읽기 쉬운 줄을 찍습니다. 그런데 같은 파일의 에러 문구는 --follow uses --jsonl, not --json처럼 “follow가 jsonl을 쓴다”는 뉘앙스이고, src/cli/capabilities.ts의 --follow 요약은 Stream new rows as JSONL; implies --jsonl.이라고 거짓말합니다. 스킬 참고 문서 skills/ocx/references/01_management_surface.md도 능력 표에서 생성되므로 같은 거짓말을 그대로 따라갑니다. 운영자가 --follow만 켰는데 JSONL이 안 나오면, 문서 탓에 버그로 오해하기 쉽습니다.

고치는 내용은 세 군데를 한 계약으로 맞추는 것입니다. (1) observe.ts에서 --follow와 --json이 같이 오면 --follow cannot be combined with --json; use --jsonl for streaming JSONL이라고 말합니다. follow가 jsonl을 “켠다”가 아니라, json과 같이 쓸 수 없고 jsonl을 쓰라는 안내입니다. (2) capabilities.ts 요약을 Poll for new rows; add --jsonl to emit JSONL.로 바꿉니다. (3) 생성된 참고 문서 한 줄도 같이 바뀝니다. 테스트는 능력 표 문구를 잠그고, --follow --json이 새 에러 문구를 내는지, --follow만 주면 human 한 줄이 나오는지(t0 200 xai/grok-4.6 ...)까지 잠급니다. Bun.sleep을 한 번 막아서 follow 루프가 무한히 돌지 않게 한 점도 실무적입니다.

원본은 @luvs01 의 #3322입니다. 이 PR은 그 수정을 현재 dev 위에 올린 carry이고 Co-authored-by: luvs01이 들어 있습니다. 본문이 말한 대로, 원본에 남아 있는 CHANGES_REQUESTED는 이미 반영된 요청이 헤드에 들어온 상태라서, 코드를 더 고치기보다 재리뷰·머지가 맞습니다. types/config 분할과는 무관하고, 범위도 CLI 관찰 표면과 테스트·생성 문서뿐입니다. #3367 Logs GUI 비용 칸 작업과도 겹치지 않습니다. CLI 쪽 로그 계약만 고칩니다.

한 가지 알아 둘 점: 에러 문구에 “streaming JSONL”이라는 말이 남아 있습니다. 실제 follow는 WebSocket 스트림이 아니라 1초 폴링입니다. capabilities 요약은 “Poll”로 고쳤는데, 에러 문구의 streaming은 출력 형식(JSONL)을 가리키는 말로 읽을 수 있어 큰 거짓말은 아닙니다. 다만 나중에 문장을 더 다듬을 여지는 있습니다. --follow --jsonl 조합의 성공 경로를 잠그는 테스트는 없습니다. 이번 버그의 핵심은 “follow가 jsonl을 암시한다”는 거짓 문서와 --follow --json 안내이므로, 지금 범위로도 충분합니다.

src/cli/observe.ts 75행 근처 (현재 dev) - 에러가 --follow uses --jsonl, not --json이라 follow가 jsonl을 쓰는 것처럼 들립니다. 이 PR이 조합 금지 + jsonl 안내로 바꿉니다.

src/cli/capabilities.ts --follow summary - implies --jsonl 주장이 코드와 다릅니다. 이 PR이 Poll + 명시적 --jsonl 안내로 고칩니다.

skills/ocx/references/01_management_surface.md - 능력 표에서 생성되는 문서라 같이 고쳐야 문서·코드가 다시 어긋나지 않습니다. 이 PR에 포함돼 있습니다.

tests/cli-usage-report.test.ts (새 describe) - --follow --json 문구와 --follow human 출력을 잠급니다. 현재 dev 기준으로 RED인 계약 테스트입니다.

원본 #3322 - 머지 후 자동 close 또는 Landed via #3372 + landed-via-maintainer로 정리해야 합니다.

메인테이너의 판단이 필요한 지점

• 에러 문구의 “streaming JSONL”을 “emit JSONL”처럼 폴링 표현과 더 맞출지, 이번엔 그대로 둘지.
• 원본 #3322의 stale CHANGES_REQUESTED를 무시하고 이 carry만 머지할지(권장).

너의 추천
문서·에러·능력 표·테스트를 한 계약으로 맞춘 작은 CLI 수정입니다. 머지하세요. 머지 후 #3322가 열려 있으면 landed-via로 닫으세요. 추가 코드 변경은 필요 없습니다.

이 댓글은 grok-bot이 작성했습니다