feat(agents): add pr and commit commands (4/8)

[VaibhavAcharya]

Summary

Linear: https://linear.app/netlify/issue/EX-2195

Part 4 of the agents CLI revamp split. Adds two commands that push a run's work out through git.

• agents:pr opens a pull request for the run's branch. Refuses on projects without a git remote.
• agents:commit commits the run's changes, defaulting to runner.branch (or runner.pr_branch when a PR is already open). Git-backed projects only.

$ netlify agents:pr <id>
✓ Pull request created!
  URL: https://github.com/x/y/pull/1
  Branch: agent-readme-comment-f5a2
  State: Open

$ netlify agents:commit <id>
Default: agent-branch-x (committing to this agent run's branch)
✓ Committed to agent-branch-x
  SHA: abc1234

Stacked on the diff/open PR.

---

For us to review and ship your PR efficiently, please perform the following steps:

• Open a bug/issue before writing your code 🧑‍💻. This ensures we can discuss the changes and get feedback from everyone that should be involved. If youre fixing a typo or something thats on fire 🔥 (e.g. incident related), you can skip this step.
• Read the contribution guidelines 📖. This ensures your code follows our style guide and
  passes our tests.
• Update or add tests (if any source code was changed or added) 🧪
• Update or add documentation (if features were changed or added) 📝
• Make sure the status checks below are successful ✅

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds two new CLI subcommands to the Netlify agents command: agents:pr and agents:commit. The agents:pr command creates a pull request from an agent run, validating the run ID, authenticating the user, and calling the Agents API to generate a PR with optional branch and state metadata. The agents:commit command commits an agent run to a target branch, supporting explicit branch selection via --branch or interactive prompting, with fallback branch selection based on open PR state or runner metadata. Both commands include registration in the agents.ts CLI structure, comprehensive integration test coverage, and documentation updates.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• serhalp

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding two new agent commands (pr and commit) as part of a larger multi-part effort.
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.
Description check	✅ Passed	The pull request description clearly relates to the changeset, detailing two new CLI commands (agents:pr and agents:commit) with usage examples and implementation details that match the file changes.

_{✏️ 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 agent/cli/pr8237-cmd-pr-commit

---

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

[VaibhavAcharya]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/commands/agents/agents-commit.ts`:
- Around line 85-93: The current success messaging in agents-commit.ts assumes a
completed commit whenever runner.merge_commit_error is falsy; update the logic
to first check runner.merge_commit_is_being_created and, if true, print an “in
progress” message instead of the success line (and avoid showing the SHA), only
printing the green "Committed to <branch>" and the SHA when
merge_commit_is_being_created is false and merge_commit_sha exists; similarly
ensure any caller/display logic that relies on
merge_commit_sha/merge_commit_error (e.g., agents-show.ts) treats
merge_commit_is_being_created as a separate in-progress state.

In `@src/commands/agents/agents-pr.ts`:
- Around line 33-43: The current success branch misreports a created PR when
AgentRunner indicates an in-progress creation; update the post-PR-handling in
agents-pr.ts to check runner.pr_is_being_created (and absence of
runner.pr_url/runner.pr_error) before logging “Pull request created!” — if
pr_is_being_created is true, log a clear in-progress message (e.g., “Pull
request is being created…”) and return runner early; otherwise continue to log
the created PR info (URL/Branch/State). Ensure you reference the
AgentRunner/runner object fields (runner.pr_is_being_created, runner.pr_url,
runner.pr_error, runner.pr_branch, runner.pr_state) so the conditional handles
async responses from agentRunnerPullRequest correctly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 68054664-b781-4687-b6f5-77c71c5fe39d

📥 Commits

Reviewing files that changed from the base of the PR and between 3220465 and 7d3ac26.

📒 Files selected for processing (7)

• docs/commands/agents.md
• docs/index.md
• src/commands/agents/agents-commit.ts
• src/commands/agents/agents-pr.ts
• src/commands/agents/agents.ts
• tests/integration/commands/agents/agents-commit.test.ts
• tests/integration/commands/agents/agents-pr.test.ts

[VaibhavAcharya]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

tests/integration/commands/agents/agents-pr.test.ts (1)

148-159: ⚡ Quick win

Consider covering the git-repo guard and 404 branches.

The suite exercises the API-success/error paths well, but two implementation branches in agents-pr.ts remain untested:

• The !siteInfo.build_settings?.repo_url guard that refuses non-git-backed projects (an explicit PR objective: "Refuses on projects without a git remote").
• The error.status === 404 → Agent run not found: ${id} mapping.

Adding cases for these would lock in the documented behavior and prevent regressions in the error-mapping logic.

Want me to draft these two additional test cases?

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/integration/commands/agents/agents-pr.test.ts` around lines 148 - 159,
Add two tests in tests/integration/commands/agents/agents-pr.test.ts: (1) a test
that builds a site whose siteInfo lacks build_settings?.repo_url and calls
callCli(['agents:pr', '<id>'], ...) expecting the CLI to reject with the guard
message (referring to the non-git-backed project path in agents-pr.ts that
checks siteInfo.build_settings?.repo_url); (2) a test that uses withMockApi to
mock the agent run endpoint to return a 404 and then calls callCli(['agents:pr',
id], ...) asserting the thrown error message equals "Agent run not found: <id>"
(this covers the error.status === 404 mapping in agents-pr.ts). Ensure you use
the same helpers present in the file (withSiteBuilder, withMockApi,
getCLIOptions, callCli) and match the exact error strings produced by
agents-pr.ts.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/integration/commands/agents/agents-pr.test.ts`:
- Around line 148-159: Add two tests in
tests/integration/commands/agents/agents-pr.test.ts: (1) a test that builds a
site whose siteInfo lacks build_settings?.repo_url and calls
callCli(['agents:pr', '<id>'], ...) expecting the CLI to reject with the guard
message (referring to the non-git-backed project path in agents-pr.ts that
checks siteInfo.build_settings?.repo_url); (2) a test that uses withMockApi to
mock the agent run endpoint to return a 404 and then calls callCli(['agents:pr',
id], ...) asserting the thrown error message equals "Agent run not found: <id>"
(this covers the error.status === 404 mapping in agents-pr.ts). Ensure you use
the same helpers present in the file (withSiteBuilder, withMockApi,
getCLIOptions, callCli) and match the exact error strings produced by
agents-pr.ts.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a3f64c8b-20b5-48f7-8099-15803285ad67

📥 Commits

Reviewing files that changed from the base of the PR and between 7d3ac26 and e4e146c.

📒 Files selected for processing (7)

• docs/commands/agents.md
• docs/index.md
• src/commands/agents/agents-commit.ts
• src/commands/agents/agents-pr.ts
• src/commands/agents/agents.ts
• tests/integration/commands/agents/agents-commit.test.ts
• tests/integration/commands/agents/agents-pr.test.ts

✅ Files skipped from review due to trivial changes (1)

• docs/index.md

🚧 Files skipped from review as they are similar to previous changes (3)

• src/commands/agents/agents.ts
• tests/integration/commands/agents/agents-commit.test.ts
• src/commands/agents/agents-pr.ts

[VaibhavAcharya]

Link EX-2195