fix: drop unpublished wheels-authenticateThis ForgeBox dependency from starter app

[wheels-bot]

Summary

box install wheels-starter-app aborted with Error getting ForgeBox entry [wheels-authenticateThis] — The entry slug sent is invalid or does not exist. The starter app's box.json declared wheels-authenticateThis ("^1") as a ForgeBox dependency, but that slug was never published — so CommandBox fetched wheels-core, then aborted on the missing slug, leaving a broken install.

The authenticateThis plugin already ships bundled under examples/starter-app/plugins/authenticateThis/ (git-tracked, copied into the published artifact by prepare-starterApp.sh), and flashMessages() lives in core (vendor/wheels/view/miscellaneous.cfc). So nothing actually needs to be fetched from ForgeBox beyond wheels-core. This PR drops the unpublished dependency (and its now-stale installPaths entry) so the install completes and the bundled plugin is used instead — matching the research's option (b): "drop the ForgeBox-dependency form and ship the bundled plugin inside the artifact."

A structural spec (StarterAppBoxJsonSpec.cfc) pins the manifest contract — mirroring the buildArtifactLicenseSpec.cfc / ApplicationCfcInjectorAssignmentSpec.cfc regression-guard pattern — so a bundled-plugin slug can't be reintroduced as a ForgeBox dependency.

Related Issue

Refs #3181

This PR resolves the titled install-break (the unpublished declared dependency). It intentionally does not address the issue's two broader threads, which are deferred to follow-ups / a maintainer call:

• Secondary issue New master #2 (MySQL-only boot): the starter still hard-codes a MySQL connection in config/app.cfm with no SQLite/H2 fast path. Out of scope here.
• Strategic direction: the research recommends consolidating on wheels new and retiring the ForgeBox starter-app entirely — a product/distribution decision (the ForgeBox listing has 51 installs) that is not the bot's to make.

Recommended path from research: #3181 (comment)

Type of Change

• Bug fix

Feature Completeness Checklist

• DCO sign-off -- commit carries Signed-off-by: (git commit -s)
• Tests -- vendor/wheels/tests/specs/cli/StarterAppBoxJsonSpec.cfc, failing → passing
• Framework Docs -- handled separately by bot-update-docs.yml
• AI Reference Docs -- handled separately by bot-update-docs.yml
• CLAUDE.md -- handled separately by bot-update-docs.yml
• Changelog fragment -- changelog.d/3181-starter-app-forgebox-dependency.fixed.md
• Test runner passes -- bash tools/test-local.sh wheels.tests.specs.cli → ✓ 123 passed (was 120 passed, 3 failed before the fix)

Test Plan

1. bash tools/test-local.sh wheels.tests.specs.cli — the new StarterAppBoxJsonSpec asserts box.json declares only wheels-core, carries no wheels-authenticateThis dependency or installPaths entry, and that the authenticateThis plugin still ships bundled.
2. Before the fix: 3 failures (declared dependency present, dependency count 2, stale installPaths). After the fix: all green.
3. End-to-end (manual, requires ForgeBox network): box install wheels-starter-app now fetches only wheels-core and completes instead of aborting on the missing slug.

[wheels-bot]

Wheels Bot — No doc updates

Reviewed this PR's diff and found no docs that need updating (the fix removes an unpublished ForgeBox dependency from examples/starter-app/box.json — the box install wheels-starter-app installation path is not documented in any existing guide page, .ai/wheels/ reference, or CLAUDE.md section; the guides cover only the wheels new CLI path).

[wheels-bot]

Wheels Bot — Reviewer

TL;DR: This PR fixes the broken box install wheels-starter-app flow by dropping the unpublished wheels-authenticateThis ForgeBox dependency (and its stale installPaths entry) from examples/starter-app/box.json, and pins the manifest contract with a structural regression spec. I verified every claim in the PR body against the repo and found no blocking issues. Verdict: comment (clean first pass; an approve would be rejected as a self-review since the PR author is wheels-bot).

Verification performed (no findings)

Correctness

• The resulting examples/starter-app/box.json is valid JSON; wheels-core is now the sole dependencies/installPaths entry (lines 30–35), with no dangling comma or orphaned installPaths key.
• The plugin genuinely ships bundled: examples/starter-app/plugins/authenticateThis/authenticateThis.cfc exists in-tree, and tools/build/scripts/prepare-starterApp.sh copies examples/starter-app/* wholesale into the publish artifact (cp -r examples/starter-app/* "${BUILD_DIR}/" with an empty ignore list in the manifest), so the dropped ForgeBox fetch is fully covered by the bundle.
• examples/starter-app/app/models/User.cfc:34 calls authenticateThis(), so the bundled-plugin assertion in the spec guards a real runtime dependency.
• Remaining wheels-authenticateThis references in the repo are the plugin's own manifest slug (examples/starter-app/plugins/authenticateThis/box.json — its identity, not a fetch declaration) and a historical v3 docs page. Neither needs changing.

Tests

• vendor/wheels/tests/specs/cli/StarterAppBoxJsonSpec.cfc extends wheels.WheelsTest (BDD, not legacy RocketUnit), uses the same var repoRoot = expandPath("/wheels/../..") repo-root resolution as the cited prior art (ApplicationCfcInjectorAssignmentSpec.cfc:23), and correctly escapes # as ## inside string literals — the classic suite-wide compile hazard is avoided.
• All four assertions are evidence-backed: absent dependency, sole-dependency count, absent stale installPaths, and bundled plugin file presence. The structCount(deps) == 1 pin is intentionally strict per the spec's own comments — a future legitimate dependency will force a conscious update, which is the point of a contract spec.
• Only cross-engine-safe BIFs are used (deserializeJSON, fileRead, structKeyExists, structCount); no closures-as-constructor-args, no reserved-scope parameter names, no bracket-notation calls.

Commits

• fix: drop unpublished wheels-authenticateThis ForgeBox dependency from starter app — valid commitlint type, 84-char header, body explains the why, DCO Signed-off-by matches the committing identity.

Docs

• Changelog fragment changelog.d/3181-starter-app-forgebox-dependency.fixed.md uses the fragment system correctly (valid fixed type, complete bullet line, no direct CHANGELOG.md edit).
• The PR body honestly scopes out issue #3181's two broader threads (MySQL-only boot, ForgeBox-starter retirement) as follow-ups — appropriate for the titled break.

One non-blocking observation: the second and third it() blocks call fileRead(boxJsonPath) without re-asserting fileExists(), so a missing manifest would surface as a thrown error rather than a clean expectation failure in those blocks. The first block does assert existence, and spec blocks run in order, so this is cosmetic — no change requested.

[bpamiri]

Superseded by #3199 (merged): a propose-fix draft that raced the ForgeBox path-repair campaign for the same issue; the campaign PR landed first and closed the underlying issue. Closing the duplicate.