ForgeBox wheels-base-template ships unsubstituted |placeholders| — `box server start` fails out of the box

[bpamiri]

Journey

Fresh CommandBox user follows the package's own README: empty dir → box install wheels-base-template → box server start.

Repro

mkdir myapp && cd myapp
box install wheels-base-template   # installs 4.0.3 + wheels-core 4.0.3 into vendor/wheels (good)
box server start

Expected

Server starts on a default engine; app boots to the welcome page.

Actual

Contacting ForgeBox to determine the latest & greatest version of [|cfmlEngine| stable]...
ERROR: Invalid slug detected. Slugs can only contain letters, numbers, underscores, and hyphens.

The shipped files contain literal legacy-CLI placeholders that nothing on this install path substitutes:

• server.json: "name":"|appName|", "cfengine":"|cfmlEngine|"
• config/settings.cfm: set(dataSourceName="|datasourceName|"), set(coreTestDataSourceName="|datasourceName|"), set(reloadPassword="|reloadPassword|")
• config/app.cfm: this.name = "|appName|"

The package README documents box install wheels-base-template in an empty directory as the canonical install and never mentions editing these. After hand-replacing all 5 placeholders (cfengine=lucee) the app boots fine on Lucee 7.0.4.34 and renders the 4.0 welcome page.

Root cause

tools/build/scripts/prepare-base.sh copies tools/build/base/{server.json,box.json,config/app.cfm,config/settings.cfm} verbatim into the package. The |x| tokens were only ever substituted by the retired CommandBox cfwheels-cli (wheels create app) flow; the direct-install path the README sells is left with raw tokens.

Suggested fix

Ship working defaults instead of placeholders: cfengine pinned to the supported default (e.g. lucee@7), app/datasource name defaulting to the folder-name convention the settings comment already describes (just leave those set() lines commented out), and reloadPassword from env like the LuCLI template (set(reloadPassword=env("WHEELS_RELOAD_PASSWORD",""))). Alternatively a postInstall script could prompt/substitute, but inert defaults are simpler and match wheels new behavior.

Ancillary: the box.json postInstall script references env.example, which is not in the package (.env ships pre-made instead) — dead reference worth cleaning while in here.

Evidence from audit journey j1-template-install (CommandBox 6.3.3 docker, wheels-base-template 4.0.3, 2026-06-12).

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report describes observable wrong behavior with a clear expected-vs-actual: a fresh box install wheels-base-template → box server start fails with ERROR: Invalid slug detected because the shipped server.json/config/app.cfm/config/settings.cfm contain literal |appName|, |cfmlEngine|, |datasourceName|, |reloadPassword| placeholders. Confirmed in-repo: tools/build/scripts/prepare-base.sh copies tools/build/base/{server.json,config/app.cfm,config/settings.cfm} verbatim (lines 62-64) and its only sed substitutions are @build.version@/@build.number@ (lines 72-90) — nothing substitutes the |x| tokens on the direct-install path the README documents.

Suspected layer

cli — see .ai/wheels/cli/ for canonical patterns. The defect lives in the base-template packaging under tools/build/base/, the same scaffolding/template territory the CLI owns.

Fix sketch

Replace the literal |x| placeholders in the three static base-template files with inert working defaults: pin tools/build/base/server.json cfengine to the supported default (e.g. lucee@7); leave the name/dataSourceName/coreTestDataSourceName set() lines commented (folder-name convention the settings comment already describes); source reloadPassword from env like the LuCLI template (set(reloadPassword=env("WHEELS_RELOAD_PASSWORD",""))). Ancillary cleanup: tools/build/base/box.json postInstall references a non-shipped env.example (.env ships instead) — dead reference worth removing while in here. No build-script logic change required; edits are to the static template files.

Confidence: high

The report pinpoints the exact files, lines, and root cause; the fix is mechanical edits to static template files with no design trade-offs or cross-engine behavior differences, so no auto-downgrade rule fires.

<!-- wheels-bot:triage:3173 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:high -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3190

Spec: vendor/wheels/tests/specs/baseTemplatePlaceholdersSpec.cfc — failing → passing (structural guard; fails if any |placeholder| token or the env.example reference reappears in the shipped base-template files)
Implementation: tools/build/base/server.json, tools/build/base/config/app.cfm, tools/build/base/config/settings.cfm, tools/build/base/box.json

Note: no CFML runtime is available in the bot sandbox, so the BDD runner could not start a server here. The spec's red → green transition was verified with the exact equivalent matcher (grep -E '\\|[A-Za-z][A-Za-z0-9_]*\\|') — 7 placeholder tokens + the env.example reference present before, zero after; both JSON files stay valid. The authoritative cross-engine run happens in CI.

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.

[bpamiri]

Fixed on develop by the keystone PR #3196 (merged): prepare-base.sh now substitutes the placeholders to working defaults at build time — verified, the published artifact has no |tokens|/{{tokens}} and box server start boots clean.