refactor(cli): extract sandbox logs helpers

[cv]

Summary

Extract pure sandbox log option and argv helpers from the log streaming action module.

Stack Navigation

• Position: 50 of 60
• Previous PR: #2964 — refactor(cli): extract sandbox destroy helpers
• Next PR: #2966 — refactor(cli): extract policy channel helpers

Changes

• Added sandbox-logs-helpers.ts for option normalization, timeout parsing, probe descriptions, signal exit codes, and OpenShell argv builders.
• Updated sandbox-logs-action.ts to import the helper logic and focus on subprocess orchestration.
• Moved helper tests to target the extracted helper module directly.

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

Summary by CodeRabbit

• Refactor

  • Reorganized sandbox logging utilities into a shared helpers module for improved maintainability.
  • Updated the return type for sandbox gateway logging operations.
  • Consolidated log probe result handling and error description logic.

• Tests

  • Enhanced test coverage for sandbox logging helper functions, including signal-to-exit-code mapping.

[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

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 45cbcd84-62da-4901-bfa5-07022402a79b

📥 Commits

Reviewing files that changed from the base of the PR and between 6943547 and 940b70d.

📒 Files selected for processing (3)

• src/lib/sandbox-logs-action.ts
• src/lib/sandbox-logs-helpers.test.ts
• src/lib/sandbox-logs-helpers.ts

---

📝 Walkthrough

Walkthrough

Core sandbox logs utilities are extracted from sandbox-logs-action.ts into a new shared helpers module. The public return type of runOpenclawGatewayLogs changes from SpawnLikeResult to LogProbeResult. Helper functions, constants, and types migrate to the new module; the action file now orchestrates via imports.

Changes

Sandbox Logs Extraction & Refactoring

Layer / File(s)	Summary
Types & Constants src/lib/sandbox-logs-helpers.ts	New module exports LogProbeResult type with status, stdout, stderr, error, and signal fields. Constants DEFAULT_LOGS_PROBE_TIMEOUT_MS and LOGS_PROBE_TIMEOUT_ENV defined.
Utility Functions src/lib/sandbox-logs-helpers.ts	Functions extracted: getLogsProbeTimeoutMs() (parses timeout from env), describeLogProbeResult() (formats results), exitCodeFromSignal() (maps signals to exit codes), normalizeSandboxLogsOptions() (normalizes boolean/object options), and three CLI argument builders (buildEnableSandboxAuditLogsArgs, buildSandboxOpenclawGatewayLogsArgs, buildSandboxLogsArgs).
Action Wiring & Integration src/lib/sandbox-logs-action.ts	Imports all helpers from new module; runOpenclawGatewayLogs return type changed to LogProbeResult; signal handling refactored to use exitCodeFromSignal; local helper definitions removed; warnSandboxAuditLogsUnavailable now accepts LogProbeResult.
Tests src/lib/sandbox-logs-helpers.test.ts	Test suite refactored to import from sandbox-logs-helpers; getLogsProbeTimeoutMs tests updated to accept option objects; new tests for exitCodeFromSignal validate exit code mapping.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A rabbit refactors with care and delight,
Extracting the helpers to helpers so right!
From action to shared, the logic takes flight—
Cleaner, reusable, and tested just right! ✨

✨ 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/retry-sandbox-logs-helpers

---

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

[prekshivyas]

LGTM. Same extraction pattern as #2962/#2963/#2964 — 3 files / +116 / -105.

Six helpers moved verbatim into sandbox-logs-helpers.ts plus one new shared utility, exitCodeFromSignal, that de-duplicates the same signal-to-exit-code logic that was previously inlined in two places (exitWithSpawnResult + the streamSandboxFollowLogs::exitFromSignal lambda). sandbox-logs-action.ts shrinks -86/+15 by importing.

SpawnLikeResult → LogProbeResult (internal rename). getLogsProbeTimeoutMs now takes env as a parameter (default process.env) — testability improvement, production unchanged.

Test file renamed (73% similarity, not deleted). Restructure drops vi.mock boilerplate (no longer needed since helpers are pure) and switches the timeout test from vi.stubEnv to explicit env passing — cleaner, no global mutation. +1 new test for exitCodeFromSignal.

CI: pr.yaml mostly green (lint/dco/check-hash/legacy-path-guard/changes PASS); macos-e2e/checks + pr-self-hosted builds still in flight at review time. No failures.