refactor(cli): parse durations with oclif flags

[cv]

Summary

Move duration syntax validation into shared custom oclif flags so logs and shields adapters rely on oclif parsing instead of post-parse validation.

Stack Navigation

• Position: 36 of 60
• Previous PR: #2928 — refactor(cli): pass lifecycle typed options
• Next PR: #2930 — refactor(cli): project public help through oclif

Changes

• Added shared custom oclif duration flag parsers for logs --since and shields --timeout.
• Updated logs command parsing to receive an already-normalized --since value from oclif.
• Updated hidden shields down command metadata to use the shared timeout parser.
• Added unit coverage for accepted and rejected duration inputs.

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

• Improvements

  • Enhanced validation and whitespace normalization for duration inputs in CLI flags (--since and --timeout), with clearer error messages for invalid values.

• Tests

  • Added test coverage for duration flag parsing to ensure proper validation and error handling.

[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]

Caution

Review failed

Pull request was closed or merged during review

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: d40e0fd6-6d94-41ef-a487-c72ecad57108

📥 Commits

Reviewing files that changed from the base of the PR and between 400869e and 46b349d.

📒 Files selected for processing (4)

• src/lib/duration-flags.test.ts
• src/lib/duration-flags.ts
• src/lib/sandbox-logs-cli-command.ts
• src/lib/shields-cli-commands.ts

---

📝 Walkthrough

Walkthrough

A new shared module extracts duration parsing logic into reusable oclif flag adapters. parseLogsSinceDuration and parseShieldsTimeoutDuration validate and normalize duration inputs; corresponding flag adapters wire them into CLI commands, replacing local validation logic.

Changes

Duration Parsing Extraction

Layer / File(s)	Summary
Duration Parsers src/lib/duration-flags.ts	New parsers: parseLogsSinceDuration validates positive durations via regex; parseShieldsTimeoutDuration delegates to parseDuration and wraps errors as CLIError.
oclif Flag Adapters src/lib/duration-flags.ts	Export logsSinceDurationFlag and shieldsTimeoutDurationFlag as Flags.custom<string> with parse hooks.
CLI Command Integration src/lib/sandbox-logs-cli-command.ts, src/lib/shields-cli-commands.ts	Replace local LOGS_SINCE_DURATION_RE and Flags.string with imported flag adapters; remove normalizeSinceDuration method.
Tests src/lib/duration-flags.test.ts	Verify whitespace trimming, regex validation, positive-duration enforcement, error messages, and maximum timeout limit detection.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

---

🐰 A rabbit hops with glee,
As parsers now are shared and free,
No duplication in sight—
Duration flags, now clean and right! ✨

🚥 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%.	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 describes the primary change: extracting duration parsing logic into shared oclif flag parsers for both logs and shields commands.
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-first-duration-flags

---

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

[cjagwani]

Approved as part of stack from #2886 (auto-approve: CI green, no scope/behavior flags).