fix(projects): guide users to enable a platform

[Henry Zhang (caezium)]

Summary

• Preserve the intentional no-platform default when --platforms is omitted.
• Explain in human-readable output that the new project has no enabled platforms.
• Print the exact command needed to enable iMessage for the new project.
• Suppress the hint when a platform was explicitly selected.
• Keep --json output unchanged.
• Add contract coverage through the CLI, getApi(), Eden treaty, and mock HTTP server.

Product decision

New projects created without --platforms should start with no enabled platforms. Users explicitly enable the platform they want afterward; the CLI should guide them rather than silently choosing iMessage.

Testing before implementation

Before this PR, creating without --platforms already sent platforms: [] and created a project with no enabled platforms. The problem was that the success output did not explain this or tell the user how to enable one.

Also tested an abandoned implementation that omitted the field. Production then returned { "imessage": true }, confirming that omission invokes the server default. Based on the product decision, this PR preserves platforms: [] and only adds actionable guidance.

Testing after implementation

• bun test tests/contract/projects.contract.test.ts: 10 tests and 35 assertions passed.
• bun run check on Node 24.14.1: typecheck, 93 tests / 230 assertions, snapshot, and build passed.
• Contract coverage verifies:
  • Default creation sends platforms: [].
  • Human output contains the enable command.
  • Explicit platforms suppress the hint.
  • JSON output remains exactly { id, name, env }.

Checklist

• No API types were changed or hand-edited
• No new runtime dependencies
• All snapshot diffs explained above
• bun run check passes locally

---

Note

Low Risk
CLI messaging and test-only mock instrumentation only; create API behavior and JSON output contract stay the same.

Overview
When photon projects create succeeds with no platforms (the existing default when --platforms is omitted), human-readable output now adds dimmed guidance: that no platforms are enabled, where to see valid names (projects create --help), and a concrete photon spectrum platforms enable … --project '<id>' example. --json still returns only { id, name, env } with no extra fields or hints.

Contract tests cover default create (platforms: []), suppression of the hint when --platforms is set, and unchanged JSON. The mock server records POST /api/projects bodies via getMockProjectCreateRequests, with resetMockState clearing that list in beforeEach for the create tests.

^{Reviewed by Cursor Bugbot for commit 3203f7a. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by CodeRabbit

• New Features
  • Added an extra guidance hint after projects create when no platforms are enabled, including an example command to enable a platform.
  • Preserved existing --json output behavior, including when no platforms are selected.
• Tests
  • Improved contract coverage for default (no-platform) messaging, explicit --platforms behavior, and --json output content.
  • Updated the mock server test setup to reset recorded request state before each contract test.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

📝 Walkthrough

Walkthrough

The project creation command now prints guidance when no platforms are enabled. Contract tests verify default, explicit iMessage, and JSON scenarios, while the mock server records project creation request payloads.

Changes

Project creation guidance

Layer / File(s)	Summary
Project creation request capture tests/helpers/mock-server.ts	Mock server state records authorized project creation request bodies and clears them between tests.
Platform guidance and contract coverage src/commands/projects.ts, tests/contract/projects.contract.test.ts	Project creation prints an iMessage enablement hint when no platforms are selected; tests verify text output, submitted platforms, and unchanged JSON behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• photon-hq/cli#89: Both changes affect empty platform handling in project creation and mock request capture.

Suggested reviewers: copilot

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is detailed, but it does not follow the required template sections like Upstream version and Routes added/removed/changed.	Rewrite the description to match the repository template and add the missing sections, especially Upstream version, route changes, snapshot changes, and runtime deps.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly matches the main change: guiding users to enable a platform after project creation.

✨ 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 henry/eng-2058-add-platform-enable-hint-after-project-creation

---

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.