test(ssh-commands): lock down update timing fix and clarify skill docs

[facundofarias]

Summary

The original ssh-commands update timing bug (PR #14, shipped in v0.16.4) was code-correct but untested, and the agent-facing skill reference still advertised a --name flag that doesn't exist while saying nothing about --timing. Mixpanel still shows 140 historical 422s from a single codex agent on v0.16.3 failing with timing is not included in the list — modern CLIs are immune, but the docs that drive agent input were still steering them wrong.

• pkg/sdk/ssh_commands_test.go (new) — asserts omitempty keeps empty Timing out of the PATCH body, plus a positive test that explicit values pass through. This is the actual regression guard for the original bug.
• internal/commands/ssh_commands_test.go (new) — unit test for validateSSHTiming covering empty (allowed on update), the three valid values, and the historically misleading before/after strings that the old help text suggested.
• skills/deployhq/references/configuration.md — removed the nonexistent --name flag, documented --command/--description/--timing with valid values, and added the missing update subcommand section.

Test plan

• go test ./... — all packages green
• golangci-lint run ./... — 0 issues
• New TestUpdateSSHCommand_OmitsEmptyTiming passes; reverting omitempty on SSHCommandCreateRequest.Timing makes it fail (verified the test actually guards the regression)

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated SSH commands docs: create examples now use --command (no --name), document optional --description and optional --timing (default: all), and update examples/flag table now clarify that update performs partial updates (only passed flags are sent).
• Tests
  • Added tests covering SSH timing validation (allowed/invalid values) and SSH command update requests (omits empty timing, sends explicit timing).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4a570cf1-2317-4cdc-a583-04b350d5e48c

📥 Commits

Reviewing files that changed from the base of the PR and between ed89189 and 981320f.

📒 Files selected for processing (1)

• skill-evals/deployhq/evals.json

---

Walkthrough

Adds tests for CLI timing validation and SDK request JSON serialization around the timing field, updates CLI documentation for dhq ssh-commands create/update to remove --name and document --timing, and updates an eval fixture to remove --name.

Changes

SSH Command Timing Tests & Documentation

Layer / File(s)	Summary
CLI timing validation tests internal/commands/ssh_commands_test.go	TestValidateSSHTiming verifies validateSSHTiming accepts empty string and all, first, after_first, and rejects invalid/case-variant values with an error containing Invalid --timing.
SDK request timing serialization tests pkg/sdk/ssh_commands_test.go	Two tests start an httptest server and assert UpdateSSHCommand omits command.timing when timing is not provided and includes it with the explicit value when set; includes readAllJSON helper to decode request JSON.
Command documentation and eval fixture updates skills/deployhq/references/configuration.md, skill-evals/deployhq/evals.json	Documentation for dhq ssh-commands create removes the --name flag and documents --command, optional --description, and optional --timing; update docs clarify partial-update behavior. Eval fixture removes --name from expected flags.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• deployhq/deployhq-cli#14: Implements validateSSHTiming logic and adjusts request/flag behavior around valid timing values (all, first, after_first), which this PR adds test coverage for.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly summarizes the main changes: adding regression tests for ssh-commands update timing and clarifying skill documentation.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ssh-commands-timing-tests-and-docs

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed89189d5b

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Update the SSH command eval expectation

Once this reference tells agents to create SSH commands without --name, the add-ssh-command skill eval is left inconsistent: skill-evals/deployhq/evals.json still requires the generated command to contain --name, and run-evals.sh reports MISSING_FLAG:--name whenever that expected flag is absent. In contexts where these skill evals are run against the updated reference, a correct agent response following this example will fail until that eval is updated to remove --name (and include the intended timing flag if needed).

Useful? React with 👍 / 👎.