feat: add CLI progress tracker

[KHAEntertainment]

Resolves #3. Adds a simple file output tracking logger to the backup command since the sub-agent failed due to auth expiration.

Summary by CodeRabbit

• New Features

  • Added TTY-aware progress feedback during backup operations with live file counters.

• Improvements

  • Enhanced restore path validation to prevent directory escape attempts.
  • Refactored restore server URL generation for more explicit control.

• Chores

  • Updated dependency declaration format.
  • Removed redundant imports.

[coderabbitai]

Warning

Rate limit exceeded

@coderabbitai[bot] has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 23 minutes and 4 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a3046d60-8845-40c6-82c7-8657b5738f0e

📥 Commits

Reviewing files that changed from the base of the PR and between b332db9 and d68f321.

📒 Files selected for processing (2)

• src/ocbs/core.py
• src/ocbs/serve.py

Walkthrough

This PR implements backup progress tracking with TTY-aware output, hardens restore path validation using safer path resolution methods, refactors the restore server lifecycle from global to explicit management, adds a new URL generation utility function, and extends test coverage for path validation edge cases.

Changes

Cohort / File(s)	Summary
Dependency Management pyproject.toml	Changed clawhub dependency format from string ("clawhub>=0.1.0") to list format (["clawhub>=0.1.0"]).
Backup Progress & Path Hardening src/ocbs/core.py	Added TTY-aware progress output to _record_backup with live counter for interactive terminals or periodic updates for non-TTY streams. Replaced unsafe path validation in _resolve_restore_path with is_relative_to() check. Both backup flows now pre-collect files to compute total_files and pass it through the pipeline.
Restore Server & URL Generation src/ocbs/serve.py	Removed global server lifecycle management (_global_server) and start_restore_server() wrapper. Simplified format_restore_message() to return static text without server coordination. Added new generate_restore_url() function for deterministic URL construction.
Import Cleanup src/ocbs/skill.py	Removed redundant duplicate imports of OCBSCore, BackupScope, and RestorePageServer.
Path Validation Tests tests/test_core.py	Added comprehensive TestResolveRestorePath suite validating correct path resolution, \.openclaw/ prefix stripping, and rejection of unsafe inputs (absolute paths, traversal attempts, symlink escapes).

Sequence Diagram(s)

No sequence diagrams generated. While the changes introduce progress instrumentation to the backup flow, the underlying control flow and component interactions remain straightforward and self-evident.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

The PR spans multiple modules with heterogeneous change types: behavioral modifications to public APIs (serve.py), multi-flow logic updates (core.py), validation hardening, and expanded test coverage. The restore server lifecycle refactoring and backup progress threading require careful verification across affected code paths.

Possibly related PRs

• sync: S3 workspace dev head → master #4: Shares modifications to src/ocbs/serve.py restore-server functionality—both PRs alter how restore URLs and server lifecycle management are handled.

Poem

🔄 Files march forward with progress in sight,
Paths lock down tight with validation's might,
URLs generated, servers step back clean,
A lighter, leaner restore machine! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	Changes include additional improvements beyond the tracker: restore path validation hardening, dependency format change, import cleanup, and test coverage—none directly required by issue #3.	Consider separating the restore path validation hardening and dependency format changes into dedicated PRs to keep this focused solely on the progress tracker feature.

✅ 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 'feat: add CLI progress tracker' directly corresponds to the main change: adding TTY-aware progress output during backup recording in src/ocbs/core.py.
Linked Issues check	✅ Passed	The PR implements the core requirements from issue #3: TTY-aware progress display, files processed counter during backups, graceful fallback for non-TTY environments, and CLI-friendly approach.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-3-manual

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/ocbs/core.py`:
- Line 332: The non-interactive (non‑TTY) fallback branch that accepts
total_files: Optional[int] currently only logs progress every 100 files and
never includes the total count, causing silent runs for 1–99 files; update the
progress logic (the non‑TTY branch that checks total_files and the periodic log
that uses a 100-file interval) to (1) compute a dynamic interval like max(1,
total_files // 100) when total_files is provided so small runs still emit
progress, (2) include the total_files value in each progress message, and (3)
always emit a final completion log that includes the total_files (or total
processed when total_files is None); apply the same change to the other similar
fallback blocks referenced (the branches around the other occurrences you
noted).

In `@src/ocbs/serve.py`:
- Around line 844-856: The refactor broke the restore URL/port/path contract:
update format_restore_message(checkpoint_id, ...) and
generate_restore_url(checkpoint_id, ...) to produce the tokenized restore
endpoint that the server actually serves and that callers expect (i.e.,
/restore/<token>) and use the same default port as start_restore_server (3456)
and host parameter; ensure format_restore_message includes the generated URL so
callers in cli.py and skill.py show a usable link; keep function names
generate_restore_url and format_restore_message and accept host/port params so
callers need no other changes.

🪄 Autofix (Beta)

✅ Autofix completed

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 96903c5b-5028-4f91-8401-c178518e706f

📥 Commits

Reviewing files that changed from the base of the PR and between 34626a9 and b332db9.

📒 Files selected for processing (5)

• pyproject.toml
• src/ocbs/core.py
• src/ocbs/serve.py
• src/ocbs/skill.py
• tests/test_core.py

💤 Files with no reviewable changes (1)

• src/ocbs/skill.py

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Fixes Applied Successfully

Fixed 2 file(s) based on 2 unresolved review comments.

Files modified:

• src/ocbs/core.py
• src/ocbs/serve.py

Commit: d68f3213bc5efc7af833a0f352954570f31af343

The changes have been pushed to the fix/issue-3-manual branch.

Time taken: 4m 12s