test(deploy): characterize cloud subscription credential flow

[willwashburn]

Summary

Adds characterization tests for the cloud subscription credential flow — ensureCloudSubscriptionReady and validateCloudSubscriptionSupport in packages/deploy/src/modes/cloud/index.ts. The main harness credential flow is well covered (~28 tests in cloud.test.ts), but the subscription variant had zero test references despite being an exported API consumed by deploy.ts — and this area has regressed before (#196: oauth legs deployed without credentialSelections, stubbing ctx.llm on every fire).

No production code changes — one new test file, packages/deploy/src/modes/cloud-subscription.test.ts (9 tests, modeled on the structure of cloud.test.ts):

• Source resolution: --harness-source plan rejected with the useSubscription:true guidance (both via arg and WORKFORCE_DEPLOY_HARNESS_SOURCE); defaults to oauth, throwing the not-connected error under --no-prompt when /api/v1/cloud-agents has no connected row.
• BYOK leg: credential POST body + returned { provider, credentialSelections } shape; missing-key error under --no-prompt; WORKFORCE_DEPLOY_BYOK_KEY used without prompting (test fails if io.prompt is called).
• OAuth leg: already-connected anthropic row → selections stamped without calling connectProvider; connect-then-poll path (confirm → connectProvider → polls /cloud-agents until connected → selections); the deploy/cloud: oauth harness legs never stamp credentialSelections — ctx.llm stubs on every CLI oauth deploy #196-adjacent shape — non-anthropic persona with no anthropic fallback returns { provider } without a credentialSelections key.

These tests freeze the deploy-time contract around /api/v1/cloud-agents and also unblock the planned split of the 1,270-line cloud module (the subscription functions move in that refactor; they're now characterized before they move).

Verification

• pnpm --filter @agentworkforce/deploy test → 196 pass, 0 fail (187 baseline + 9 new)
• pnpm typecheck → clean
• Diff touches only the new test file

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a comprehensive Node.js test suite characterizing the cloud subscription credential flow contract for deploy-time logic. The suite covers subscription source validation, BYOK credential handling with environment variable precedence, and OAuth agent connection with polling and selection logic.

Changes

Cloud Subscription Credential Flow Test Suite

Layer / File(s)	Summary
Test helpers and infrastructure packages/deploy/src/modes/cloud-subscription.test.ts:1–117	Test module setup with utilities to fabricate PersonaSpec objects, produce JSON Response mocks, intercept and mock fetch calls, and run tests with controlled environment variables via withEnv.
Cloud subscription validation and OAuth error handling packages/deploy/src/modes/cloud-subscription.test.ts:123–188	validateCloudSubscriptionSupport rejects plan harness source with guidance for useSubscription:true and OAuth flow; ensureCloudSubscriptionReady throws "credentials are not connected" error under noPrompt when no cloud agents exist.
BYOK credential flow packages/deploy/src/modes/cloud-subscription.test.ts:193–285	Tests BYOK-leg behavior: POST to provider-credentials endpoint with expected fields, rejection when BYOK key is missing under noPrompt, and preferential use of WORKFORCE_DEPLOY_BYOK_KEY environment variable without prompting.
OAuth credential flow and agent connection packages/deploy/src/modes/cloud-subscription.test.ts:290–452	Tests OAuth-leg success paths: immediate return when anthropic agent is already connected, connectProvider call and poll-until-connected flow, and selection return for connected anthropic provider; non-anthropic behavior returns { provider } without credentialSelections when no anthropic fallback exists.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A test suite hops into view,
Cloud credentials validated true,
OAuth, BYOK paths explored,
Each flow and fallback assured,
Deploy time flows, through and through!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.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 specifically describes the main change: adding characterization tests for the cloud subscription credential flow, which is the sole focus of this PR.
Description check	✅ Passed	The description is well-detailed and directly related to the changeset, providing context about the tests added, what they cover, and their significance to the codebase.
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 advisor/002-subscription-credential-flow-tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[gemini-code-assist]

Code Review

This pull request introduces a new test suite in packages/deploy/src/modes/cloud-subscription.test.ts to characterize and freeze the deploy-time contract for the cloud subscription credential flow. It includes tests for validateCloudSubscriptionSupport and ensureCloudSubscriptionReady across both BYOK and OAuth flows, ensuring proper handling of prompts, environment variables, and API polling. There are no review comments, and I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[coderabbitai]

🧹 Nitpick comments (2)

packages/deploy/src/modes/cloud-subscription.test.ts (2)

249-284: 💤 Low value

Optional: Dead code after assert.fail.

Line 257 contains return originalPrompt(''); which is unreachable because assert.fail throws. The code is present for type consistency, but you could simplify by returning a value directly without the originalPrompt call.

♻️ Proposed cleanup

   io.prompt = async () => {
     assert.fail('io.prompt must not be called when WORKFORCE_DEPLOY_BYOK_KEY is set');
-    return originalPrompt('');
+    return '';
   };

🤖 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 `@packages/deploy/src/modes/cloud-subscription.test.ts` around lines 249 - 284,
The override of io.prompt in the test "ensureCloudSubscriptionReady byok leg
uses WORKFORCE_DEPLOY_BYOK_KEY without prompting" contains dead code: after
assert.fail() the subsequent return originalPrompt('') is unreachable; simplify
by removing the originalPrompt call and return a direct value (e.g., an empty
string or the expected prompt result) from the io.prompt stub, and drop the
originalPrompt binding if it’s no longer used to keep the test concise and
type-correct.

---

405-452: 💤 Low value

Optional: Redundant persona override.

Lines 436-437 override harness: 'codex', model: 'openai-codex/test', which exactly matches the defaults from the persona() helper (lines 45-46). The override can be omitted for brevity.

♻️ Proposed cleanup

       ensureCloudSubscriptionReady(subscriptionArgs(io, {
-        persona: persona({ harness: 'codex', model: 'openai-codex/test' }),
+        persona: persona(),
         harnessSource: 'oauth',
         noPrompt: true
       }))

🤖 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 `@packages/deploy/src/modes/cloud-subscription.test.ts` around lines 405 - 452,
The test 'ensureCloudSubscriptionReady oauth leg returns { provider } without
credentialSelections for non-anthropic when no anthropic fallback' contains a
redundant persona override: remove the explicit override object { harness:
'codex', model: 'openai-codex/test' } passed into persona() in the
subscriptionArgs call since persona() already defaults to those values; update
the call to subscriptionArgs(..., { persona: persona(), harnessSource: 'oauth',
noPrompt: true }) (or simply persona() inlined) so the test is shorter and
behavior unchanged, leaving ensureCloudSubscriptionReady and subscriptionArgs
usage intact.

🤖 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 `@packages/deploy/src/modes/cloud-subscription.test.ts`:
- Around line 249-284: The override of io.prompt in the test
"ensureCloudSubscriptionReady byok leg uses WORKFORCE_DEPLOY_BYOK_KEY without
prompting" contains dead code: after assert.fail() the subsequent return
originalPrompt('') is unreachable; simplify by removing the originalPrompt call
and return a direct value (e.g., an empty string or the expected prompt result)
from the io.prompt stub, and drop the originalPrompt binding if it’s no longer
used to keep the test concise and type-correct.
- Around line 405-452: The test 'ensureCloudSubscriptionReady oauth leg returns
{ provider } without credentialSelections for non-anthropic when no anthropic
fallback' contains a redundant persona override: remove the explicit override
object { harness: 'codex', model: 'openai-codex/test' } passed into persona() in
the subscriptionArgs call since persona() already defaults to those values;
update the call to subscriptionArgs(..., { persona: persona(), harnessSource:
'oauth', noPrompt: true }) (or simply persona() inlined) so the test is shorter
and behavior unchanged, leaving ensureCloudSubscriptionReady and
subscriptionArgs usage intact.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 83116803-ddf5-4264-9a88-f87a626bb424

📥 Commits

Reviewing files that changed from the base of the PR and between fa0f737 and 311765e.

📒 Files selected for processing (1)

• packages/deploy/src/modes/cloud-subscription.test.ts