Wheels migration script runs against wrong Lucee instance

[teleotic]

Describe the bug
As discovered in #2876, when working on multiple apps migration scripts may run against the wrong Lucee instance. This could result in writes going to the wrong database.

To Reproduce
Steps to reproduce the behavior:

1. wheels new test_app_a
2. wheels new test_app_b
3. cd test_app_a
4. wheels start
5. cd ../test_app_b
6. wheels generate scaffold Post title body:text publishedAt:datetime --belongsTo=author
7. wheels migrate latest
8. See that test_app_b has now run its migration against test_app_a's Lucee instance

Expected behavior
wheels migrate should refuse to run, and provide an appropriate error, if the project's associated server is not active. It should not run against another project's server.

Desktop

• OS: Ubuntu 26.04 LTS
• Version 4.0.2

Additional context
In my case, I was working on an app with a PostgreSQL backend. Without stopping that app's server, I created a second app to test some Wheels behavior. The second app was created with default settings, which created a SQLite database. Running a wheels migrate latest in the second app's directory without starting that app's server resulted in an error mentioning PostgreSQL.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see cli/CLAUDE.md for CLI patterns (no .ai/wheels/cli/ doc exists yet; cli/lucli/Module.cfc is the canonical reference for command implementations).

Fix sketch

The root cause is in cli/lucli/Module.cfc::detectServerPort() (around line 5636) and its caller $requireRunningServer(). After checking lucee.json and .env, the helper falls back to a list of common ports ([8080, 60000, 3000, 8500]) and accepts whichever one is open — with no verification that the server on that port belongs to the current project. When test_app_a is already running on a default port and test_app_b has no server, wheels migrate latest in test_app_b happily targets test_app_a's Lucee instance and runs the migration against the wrong database. The fix likely tightens server detection so write-side commands (at minimum migrate, probably also seed / reload / generate) refuse to act unless the detected port matches an explicit project-local config (lucee.json / .env PORT) AND the server identifies itself as belonging to this project root — either by dropping the common-port fallback for write commands, or by adding a lightweight project-identity probe (e.g. an endpoint that returns the running server's projectRoot and matching it against variables.projectRoot). The migrate action at Module.cfc:396 should fail closed with a clear "no server for this project is running" error rather than proceed against an unverified port.

Confidence: medium

Clear bug with crisp repro, but auto-downgraded from high because the migrator subsystem is involved and the fix has a real design trade-off (drop the fallback entirely vs. add a server-identity probe — the latter requires framework-side changes too).

<!-- wheels-bot:triage:2878 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2879

Spec: cli/lucli/tests/specs/services/ServerDetectionSpec.cfc — failing → passing
Implementation: cli/lucli/Module.cfc (detectServerPort() gains a requireProjectConfig knob; four write-side runners opt in)

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.