Support sandbox branch targeting by name

[theunreal]

Note

Description

Adds branch targeting to the CLI so agents working outside Builder can read and edit files on a specific app branch. A new global --branch <name> flag resolves an exact branch name to its internal branch ID and forwards it to the sandbox bridge, while base44 branches list exposes the names available for that app. Commands that cannot honor branch scope reject the flag explicitly instead of silently operating on main.

Related Issue

None (pairs with base44-dev/apper#23840; supersedes #616)

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• New core/resources/branch/api.ts with listBranches() (Zod-validated GET branches, filtered to active) and resolveBranchName(), which maps main to undefined and fails on missing or ambiguous names.
• New base44 branches list command that prints main plus active branch names, emitting { "branches": [...] } under --json.
• Global --branch <name> option registered on the program; Base44Command gains a supportsBranch option, validates the flag before auth (rejecting unsupported commands and empty/whitespace values via InvalidInputError), resolves the name, and passes branchId through CLIContext.
• All seven sandbox commands (ls, read, write, edit, grep, run, checkpoint) opt in with supportsBranch: true and forward branch_id in their payloads.
• Sandbox param types extend a shared SandboxScopeParams interface carrying the optional branch_id.
• Docs: new "Branch targeting" section in docs/commands.md (including how to opt a command in) and two CHANGELOG.md entries.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

Branch IDs stay internal — names are the only public selector, and no checkout state is persisted, so every invocation is explicit. Omitting the flag (or passing --branch main) preserves existing behavior and skips the branch lookup entirely. New tests cover name resolution, not-found/ambiguous/invalid-schema rejection, pre-auth validation, per-command branch_id forwarding, and branches list JSON output including the access-denied failure case. Validated with build, typecheck, lint, Knip, and mocked-HTTP CLI tests; no live E2E run.

---

_{🤖 Generated by Claude | 2026-09-14 07:35 UTC | a1a2672}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.14-pr.622.a1a2672

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.1.14-pr.622.a1a2672"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.14-pr.622.a1a2672"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.14-pr.622.a1a2672
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}