refactor(cli): validate logs flags with oclif

[cv]

Summary

Move the sandbox logs command's --tail, -n, --since, and --follow option shape into the oclif adapter so invalid flag values fail before any OpenShell calls. This also carries the log filter options through the logs action and updates help/registry metadata for the new flags.

Stack Navigation

• Position: 13 of 60
• Previous PR: #2902 — refactor(cli): add oclif examples for utility commands
• Next PR: #2906 — refactor(cli): improve sandbox diagnostic command metadata

Changes

• Added SandboxLogsOptions and wired sandbox:logs to pass structured log options instead of a bare follow boolean.
• Modeled --tail/-n with Flags.integer({ min: 1 }) and kept custom --since duration validation in the oclif command.
• Updated log source argument construction so tail counts flow to both OpenClaw and OpenShell logs, while --since avoids an unfiltered gateway tail.
• Expanded logs help metadata and root command registry flags.
• Added CLI and command-adapter coverage for tail, since, follow, help, malformed values, and unknown flags.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

Release Notes

• New Features
  • The sandbox:logs command now supports --tail/-n flag to display a specific number of log lines
  • Added --since flag to filter logs from a specified duration with validation and helpful error messages
  • Updated command documentation with usage examples

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2baf5665-a485-49e8-968a-8cdd09e39d95

📥 Commits

Reviewing files that changed from the base of the PR and between 9513028 and a0c5636.

📒 Files selected for processing (1)

• src/lib/sandbox-logs-cli-command.ts

---

📝 Walkthrough

Walkthrough

The sandbox:logs CLI command adds --tail/-n and --since flags to control output line count and time filtering. A normalizeSinceDuration helper validates the --since duration format. The runtime bridge now receives an options object with follow, lines, and since instead of just a boolean flag.

Changes

Log Filtering and Output Options

Layer / File(s)	Summary
CLI Metadata src/lib/sandbox-logs-cli-command.ts (lines 36–62)	static usage expanded to document --tail/-n and --since flags; static examples added with usage patterns; static flags extended with tail (integer, default from DEFAULT_SANDBOX_LOG_LINE_COUNT) and since (string) flag definitions.
Duration Validation src/lib/sandbox-logs-cli-command.ts (lines 63–69)	Added private normalizeSinceDuration(since) helper that trims input, validates against LOGS_SINCE_DURATION_RE regex, and returns normalized string or null; exits with code 2 on invalid duration.
Runtime Bridge Integration src/lib/sandbox-logs-cli-command.ts (lines 70–75)	Updated run() method to pass an options object { follow, lines, since } to the runtime bridge instead of a single follow boolean; lines stringified from flags.tail, since from normalizeSinceDuration(flags.since).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A fuzzy tail now counts the logs,
Since durations dance through CLI's bogs,
With validation swift and options bright,
The sandbox logs flow feels just right! ✨

🚥 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 'refactor(cli): validate logs flags with oclif' accurately captures the main objective of the PR—adding flag validation for the logs command using oclif's validation framework.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ 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 refactor/oclif-ux-logs-flags

---

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

[prekshivyas]

LGTM after rebase. Tiny additive change — 1 file / +6 / -0, just static examples = [...] on SandboxLogsCommand for richer --help output.

Note: the PR description describes substantive flag-validation work (Flags.integer({min:1}), --since regex, SandboxLogsOptions wiring, etc.) but all of that is already present in sandbox-logs-cli-command.ts on main — it landed via earlier PRs in the stack and got absorbed by the rebase. The actual remaining delta here is the examples block.

Public surface unchanged (examples only render in --help). CI: pr.yaml fully green including CodeRabbit; pr-self-hosted build-sandbox-images/arm64 still in flight at review time.

Nit (non-blocking): consider updating the PR description before merging so the squash-merge commit message accurately reflects what's actually being added (examples), not the substantive work that already landed.