cli: wheels test ignores the subpath setting — add base-path support for subfolder deployments

[bpamiri]

Context

Companion to #3025; the small half of the subfolder phase-2 work from discussion #2887 / issue #2968. PR #2985 gave the framework a subpath setting (set(subpath="/myapp") / WHEELS_SUBPATH), so generated URLs and asset paths now work under a URL prefix — but the CLI test command still assumes the app is mounted at the server root.

Problem

• cli/lucli/Module.cfc:4741 — var testPath = coreTests ? "/wheels/core/tests" : "/wheels/app/tests"; builds the runner URL with no subfolder segment.
• cli/lucli/Module.cfc:6819 — second hardcoded http://localhost:#serverPort#/wheels/app/tests?... URL with the same assumption.

For an app mounted at /wheelsproject1 (the six-instance IIS/CommandBox setup in #2887), the CLI requests /wheels/app/tests, which the rewrite layer never routes to the app — wheels test is unusable in that topology.

Proposed direction

1. Accept an explicit --base-path=/wheelsproject1 flag on wheels test (and the wheels_test MCP tool input), prefixed onto both URL constructions.
2. When the flag is absent, auto-derive: read WHEELS_SUBPATH from the environment, else scan config/settings.cfm for set(subpath=...) (strip CFML comments first — see Anti-Pattern 14 and the existing stripCfmlComments() helpers). Explicit flag wins over derivation.
3. Normalize like the framework does (leading slash, no trailing slash — mirror $resolveFrameworkPaths() in vendor/wheels/Global.cfc:2447).

Note the CLI ArgSpec migration context (#2861): implement the new flag via ArgSpec, not the legacy argsFromCollection round-trip, so --base-path=... parses reliably.

Acceptance

• wheels test (and wheels test --core) passes against an app served under set(subpath="/myapp") with rewrite rules per the Running Wheels 4 in a subfolder - And figuring out tests (broken) #2887 recipe.
• Root-mounted apps are unaffected with no flag.
• CLI suite covers the URL construction for both flag and derived forms.

Refs #2887. Follow-up to #2985 (phase 1).

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see cli/lucli/Module.cfc (the wheels test command and the wheels_test MCP tool). No dedicated .ai/wheels/cli/ doc exists; ground the fix in the issue cited line references and the ArgSpec migration context (issue 2861).

Fix sketch

Two hardcoded runner URLs in cli/lucli/Module.cfc (around line 4741: var testPath = coreTests ? "/wheels/core/tests" : "/wheels/app/tests"; and around line 6819: the http://localhost:.../wheels/app/tests?... URL) build the test-runner URL assuming a root mount, so a subfolder-mounted app (set(subpath="/myapp")) is never routed and wheels test fails. Fix: introduce a --base-path flag (via ArgSpec, per issue 2861) on wheels test and the wheels_test MCP tool input, prefixing it onto both URL constructions. When absent, auto-derive from WHEELS_SUBPATH, else scan config/settings.cfm for the set(subpath=...) call — stripping CFML comments first using the existing stripCfmlComments() helper (Anti-Pattern 14). Normalize to a leading slash / no trailing slash, mirroring $resolveFrameworkPaths() in vendor/wheels/Global.cfc. Explicit flag wins over derivation; root-mounted apps stay unaffected when no flag/subpath is present.

Confidence: medium

The report is precise (exact files, lines, proposed direction, acceptance criteria), but the fix carries design trade-offs — flag-vs-derivation precedence, the ArgSpec migration path, comment-stripped settings scanning, and path normalization across two call sites plus new CLI test coverage — so it is not a mechanical one-file change.

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

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3028

Spec: cli/lucli/tests/specs/commands/TestCommandSpec.cfc — failing → passing (new $normalizeBasePath / $resolveTestBasePath / $buildTestRunnerPath / --base-path schema coverage)
Implementation: cli/lucli/Module.cfc — --base-path flag on the test ArgSpec (flows into the wheels_test MCP input), subpath derivation + normalization helpers, and both hardcoded runner URLs (runTests and browserTest) now prefixed.

Local CLI suite: 866 pass / 0 fail / 0 error.

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