wheels-sentry@1.0.0 is broken when installed via 'wheels packages add' — hardcoded plugins.sentry.SentryClient path doesn't resolve in vendor/wheels-sentry/

[bpamiri]

Severity: high — the flagship 4.0 first-party error-tracking package doesn't work via the documented install command.

Surfaced by: titan Phase 2.1 (Wheels 4.0 upgrade), 2026-05-15.

Repro

$ wheels packages add wheels-sentry        # installs to vendor/wheels-sentry/
$ wheels start

At boot, application.sentry initialization silently fails (caught by a try/catch in the surrounding code). No Sentry events are ever emitted. No error in the application log. The package appears installed but is non-functional.

Root cause

vendor/wheels-sentry/Sentry.cfc:79 hardcodes:

local.client = new plugins.sentry.SentryClient(...);

When wheels packages add places the package at vendor/wheels-sentry/, the dotted path plugins.sentry.SentryClient does not resolve. The wheels-sentry package's box.json declares legacy CommandBox install hints (directory: \"/plugins/\", packageDirectory: \"sentry\"), meaning the package was designed for plugins/sentry/ — but wheels packages add ignores those hints and installs to the lucli-canonical vendor/<name>/.

Workaround used in titan: move the package directory by hand after add, repointing .gitignore from !plugins/SentryForWheels/ to !plugins/sentry/.

Suggested fix

One of:

1. Patch wheels-sentry's Sentry.cfc to locate SentryClient.cfc by relative file path (getDirectoryFromPath(getCurrentTemplatePath()) & \"SentryClient.cfc\" + createObject(\"component\", path)).
2. Make wheels packages add honor the package's box.json directory / packageDirectory hints so legacy-shape packages install where they expect to be.
3. Auto-create a per-package Lucee mapping at install time (e.g. /wheels-sentry → vendor/wheels-sentry/) so packages can reference their own internal components by static dotted path. Note that hyphens in dirnames also break static CFC paths — this fix would address both.

Why this matters for v4.0.1

wheels-sentry is the canonical Sentry integration for 4.0. Anyone running the documented install path gets a silently-broken Sentry client.

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable broken behavior on the documented happy path: wheels packages add wheels-sentry followed by wheels start results in a silently-failing Sentry client. The reporter quotes the failing line (vendor/wheels-sentry/Sentry.cfc:79 — new plugins.sentry.SentryClient(...)) and traces it to the install directory mismatch between the package's legacy box.json hints (/plugins/sentry/) and wheels packages add's canonical install path (vendor/<name>/).

Suspected layer

cli — the package installer that drops the tarball into vendor/<name>/. Most plausible target: cli/lucli/services/packages/Installer.cfc (the file that decides the install destination and is the natural home for honoring legacy box.json directory / packageDirectory hints, or for emitting a per-package Lucee mapping at install time). The framework-side discovery code in vendor/wheels/PackageLoader.cfc is a secondary candidate if the chosen fix is to register mappings at boot rather than at install.

Note: fix option 1 from the report (patching wheels-sentry's own Sentry.cfc to use a relative file path) lives in the wheels-dev/wheels-sentry repo, not here. Options 2 and 3 both land in this repo.

Fix sketch

Three plausible shapes, in increasing scope:

1. Honor legacy box.json hints in Installer.cfc. Smallest change: when a package's manifest contains directory / packageDirectory, extract there instead of vendor/<name>/. Targets only the wheels-sentry-shaped case.
2. Auto-create a per-package CFML mapping at install time (e.g. /wheels-sentry → vendor/wheels-sentry/). Fixes the symptom for any package that references itself by static dotted path, and also addresses the related hyphen-in-dirname problem the reporter mentions. Probably needs to live in PackageLoader.cfc at boot (so reinstalls don't need to mutate engine config) rather than the CLI installer.
3. Patch wheels-sentry upstream to resolve SentryClient.cfc via getCurrentTemplatePath() + createObject(...). Out of scope for this repo, but worth coordinating with whichever fix lands here.

A judgment call between #1 (cheapest, only fixes this package) and #2 (broader, sets a convention for any first-party package referencing its own internals) belongs to propose-fix.

Confidence: medium

The bug and the reporter's analysis are clear, but the fix has real design trade-offs across three different scopes — including one that lives in a separate repo. Propose-fix needs to pick a path before writing a spec, so I'm not rating this high.

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

[wheels-bot]

Wheels Bot — Fix on hold for human review

The proposed fix touches a sensitive area (cross-engine CFML mapping registration) and the bot's safety net requires a human in the loop before any code is written.

Brief notes from investigation, for whoever picks this up:

• The fundamental options are all bounded:
  1. Register a CFML mapping at boot (e.g. /plugins/sentry → vendor/wheels-sentry/) derived from the package's legacy box.json directory + packageDirectory hints. Cleanest fix for wheels-sentry@1.0.0 as-shipped, but mapping registration via <cfapplication action="update" mappings="..."> has a Lucee-specific workaround (LDEV-2555 — sessionCluster / clientCluster / cgiReadOnly revert on each update) that the existing vendor/wheels/wheelstest/system/util/LuceeMappingHelper.cfc and BoxLangMappingHelper.cfc already split into per-engine files. So this path needs different code paths for Lucee vs Adobe vs BoxLang.
  2. Change the installer to honor box.json hints and install to plugins/sentry/. Breaks the PackageLoader.cfc discovery convention (it scans vendor/, not plugins/). Would require teaching the loader to also scan plugins/ or to register packages from explicit locations, which conflates the new packages system with the deprecated plugins/ directory.
  3. Patch wheels-sentry upstream to resolve SentryClient.cfc via getCurrentTemplatePath() + createObject(...). Lives in wheels-dev/wheels-sentry, not this repo. Even if option 1 or 2 ships here, it's worth coordinating with the upstream package author so the fix is durable.
• Whichever option lands, the discovery path in vendor/wheels/PackageLoader.cfc is the right home — cli/lucli/services/packages/Installer.cfc should remain "install to vendor/<name>/" only.
• A reasonable forward-looking shape: add a mappings field to package.json (and optionally derive a default from legacy box.json hints), then apply via <cfapplication action="update" mappings="..."> from Global.cfc::$loadPackages() with engine-aware handling.

A human needs to make the engine-handling call and verify the LDEV-2555 workaround against the local docker matrix (Lucee 6/7, Adobe 2023/2025, BoxLang) before this can land.