fix(cli): short-circuit workspace-list when --workspace is set

[khaliqgant]

Summary

agentworkforce login --workspace <id> was failing with workspace list failed: 403 Forbidden because listWorkspacesForLogin ran unconditionally before --workspace was checked. This PR makes --workspace actually skip the list, which was the original intent.

Repro (pre-fix)

$ agentworkforce login --workspace 50587328-441d-4acb-b8f3-dbe1b3c5de99
agentworkforce login failed: workspace list failed: 403 {"error":"Forbidden"}

The 403 itself is a separate concern — the user's access token from PKCE lacks the scope GET /api/v1/workspaces requires. That needs a relay-side scope fix (@agent-relay/cloud's ensureAuthenticated requesting workspaces:read) OR a cloud-side route relaxation (return empty list for auth'd-but-no-workspaces users). This PR is the CLI-side mitigation so users with a known workspace id can still log in today.

Changes

• runLogin short-circuits listWorkspacesForLogin when --workspace is set
• 403 from the workspaces-list route now surfaces a clear "pass --workspace" hint
• Empty workspaces list (when the user is auth'd but has zero workspace memberships) surfaces a clear "create one at agentrelay.cloud or pass --workspace" message
• LOGIN_USAGE help text mentions the workaround
• 3 new test cases

Verification

• corepack pnpm -F @agentworkforce/cli typecheck — clean
• corepack pnpm -F @agentworkforce/cli test — 192 pass / 0 fail (was 189 on main)

Test plan

• runLogin with --workspace skips the workspace list call and uses the provided workspace
• runLogin without --workspace surfaces a --workspace hint when the workspaces list returns 403
• runLogin without --workspace surfaces a no-workspaces message when the list comes back empty
• Existing 189 cli tests still pass

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5fb9a073-59dd-4a0c-bd03-566a7f0e0777

📥 Commits

Reviewing files that changed from the base of the PR and between 25945b7 and 7c7d23d.

📒 Files selected for processing (2)

• packages/cli/src/deploy-command.test.ts
• packages/cli/src/deploy-command.ts

---

📝 Walkthrough

Walkthrough

The PR adds workspace selection optimization to the login flow. When --workspace is provided, workspace listing is skipped entirely and the token is issued directly. The API 403 and empty-list error cases now emit targeted guidance instructing users to use the --workspace flag. Three test cases cover all three paths.

Changes

Workspace Selection Optimization

Layer / File(s)	Summary
Workspace selection branching and 403 error handling packages/cli/src/deploy-command.ts	runLogin conditionally skips workspace listing when --workspace is provided, assigning the chosen workspace directly. listWorkspacesForLogin adds explicit HTTP 403 detection and throws a targeted error message guiding users to provide --workspace <id-or-slug>. LOGIN_USAGE is updated to document this behavior.
Test coverage for workspace selection scenarios packages/cli/src/deploy-command.test.ts	Three test cases verify: --workspace bypasses listing and issues token directly with exit code 0; 403 error returns exit code 1 with access-denied guidance; empty workspace list returns exit code 1 with no-workspaces guidance and --workspace usage hint.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A rabbit hops with flags in hand,
No listing needed, workspace grand!
When 403 bars the door,
"Use --workspace!" we now implore,
Skip the list, fast and fleet,
Workspace login, oh how sweet! ✨

🚥 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
Title check	✅ Passed	The title clearly and concisely summarizes the main change: skipping workspace list when --workspace is provided, which directly addresses the PR's core objective.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, including problem statement, reproduction steps, specific changes made, and verification results.
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 fix/cli-login-workspace-shortcircuit

---

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

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional findings.