`box install wheels-starter-app` is broken: declared dependency `wheels-authenticateThis` does not exist on ForgeBox

[bpamiri]

Summary

The ForgeBox wheels-starter-app package (slug wheels-starter-app, 51 installs, latest 1.0.0) cannot be installed. Its box.json declares:

"dependencies": { "wheels-core": "^4.0.0", "wheels-authenticateThis": "^1" }

but wheels-authenticateThis is not published on ForgeBox.

Reproduction

box install wheels-starter-app
# ... installs wheels-core into vendor/wheels, then:
# ERROR: Error getting ForgeBox entry [wheels-authenticateThis]
#        The entry slug sent is invalid or does not exist

ForgeBox API probes (all MISSING): wheels-authenticateThis, authenticatethis, wheels-flashmessagesbootstrap, wheels-jsconfirm.

The install aborts after fetching wheels-core, leaving no plugins/ directory. The app code requires these plugins — app/models/User.cfc calls authenticateThis(), and app/views/layout.cfm + app/snippets/bootstrap/layout.cfm call flashMessages().

Secondary issues found while testing

1. Published zip omits plugins/. prepare-starterApp.sh does cp -r examples/starter-app/* build/, but examples/starter-app/.gitignore contains /plugins/**/, and the repo's bundled plugin zips (authenticateThis-1.0.1.zip, FlashMessagesBootstrap-1.0.4.zip, jsconfirm-1.0.5.zip) are present locally but excluded from the artifact. So even the bundled-plugin fallback is missing from what users download.
2. MySQL-only boot. Even ignoring plugins, the app won't boot without MySQL: with no .env it 500s on key [DB_CLASS] doesn't exist (config/app.cfm:14); with .env.example copied it builds an unconditional jdbc:mysql://... connectionString and 500s on key [general_sitename] (needs a migrated/seeded MySQL DB). config/app.cfm ignores the DB_TYPE switch the README documents — there's no SQLite/H2 fast path a fresh user would expect.

Suggested direction

Resolve the dependency story: publish wheels-authenticateThis (+ the other two plugins) to ForgeBox, OR drop the ForgeBox-dependency form and ship the bundled plugin zips inside the artifact (un-gitignore for the publish), OR retire the ForgeBox starter-app in favor of wheels new. Also consider a SQLite/H2 default so the starter boots out of the box. Given 51 installs total, low urgency, but as published it is non-functional.

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

<!-- wheels-bot:triage:3181 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

The ForgeBox wheels-starter-app package is non-functional: it declares ForgeBox dependencies (wheels-authenticateThis, wheels-flashMessagesBootstrap, wheels-jsConfirm) that were never published, its published zip gitignores the bundled-plugin fallback, and it hard-codes MySQL so a fresh user can't boot it. The bug is concrete, but the framework-design question underneath it is: how should Wheels distribute and bootstrap a "starter app" — what's the right model for default/bundled features (auth, flash, UI), how should optional feature sets be offered, and how do you guarantee a freshly-scaffolded app boots out of the box with no external fetch or service that can fail?

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails	rails new; bin/rails generate authentication; -m app-template DSL	Starter emitted from generators inside the rails gem; deps written as Gemfile lines; SQLite default; importmap (no Node)	Zero network fetch that can 404; only bundle install is remote, deferrable via --skip-bundle	Auth generator omits sign-up flow; --js=esbuild reintroduces Node fetch
Laravel	laravel new; official Starter Kits (React/Vue/Livewire); Fortify backend	Kit chosen at create time; UI/controllers copied as owned source, durable auth logic = real dep (Fortify); SQLite default	Modern kits dropped the old composer require breeze then breeze:install two-step; "you own it, no upgrade path"	WorkOS variant is the only one needing an external account (gated behind --workos)
Django	startproject / startapp; --template <path|url|zip>	Auth (contrib.auth) and flash (contrib.messages) in core; SQLite default; single whole-template swap seam	Batteries in core = no PyPI fetch, no version skew; no UI kit in core	--template from URL = trusting arbitrary input (documented security warning)
Phoenix	mix phx.new; mix phx.gen.auth; --no-* opt-outs	Auth generated into the app as editable source; flash in core; maximal-by-default, subtract via flags	Generated auth "not updated after generation" — manual back-port	Default DB is Postgres so a fresh app needs a running DB unless --database sqlite3 / --no-ecto
Spring Boot	Initializr (start.spring.io); spring-boot-starter-*; BOM	Curated, version-aligned dependency bundles; BOM pins every version so a generated project always compiles; H2 in-memory default	The framework owns the tested set + cadence; implicit classpath-driven wiring is opaque	Selector hides incompatible combos; auto-injects base starter if none chosen
Symfony Flex (+1)	symfony new --webapp; composable packs; Flex recipes; make:auth	composer require also wires the package — registers bundle, copies config, seeds .env — via a declarative, reversible recipe tracked in symfony.lock; flash in core	Inheritance-skeleton (website-skeleton) was deprecated for exactly this; composition (packs) won	Recipe "magic" mitigated by lockfile + reversible remove

+1 justification: Symfony Flex is the most directly relevant comparison — its "recipe" model is the canonical answer to "how does installing a starter dependency also wire its config so the app boots." It's the precise capability the broken box.json dependency-fetch lacks.

Dominant pattern

Near-total convergence on three points. (1) Generate locally, don't fetch a starter-app package. Every framework emits the starter from generators/templates shipped inside the framework or its installer — none depend on a separately-published "starter app" artifact whose dependency graph can 404 (which is exactly the failure mode in this issue). (2) Default to a zero-config file/in-memory database (SQLite for Rails/Laravel/Django, H2 for Spring) so a fresh scaffold boots with no external service. (3) Auth and flash are core or generated source, never an opaque plugin dependency — flash is always in core (Rails, Django, Phoenix, Symfony); auth is core (Django) or one-shot generated owned code (Rails 8, Phoenix phx.gen.auth, Symfony make:auth, Laravel kits over Fortify). Where they diverge is only how optional feature sets are added: create-time flags/kits (Rails/Laravel/Phoenix) vs. add-anytime composable packs+recipes (Symfony) vs. a dependency selector + version-pinning BOM (Spring). Symfony's lesson is explicit and on-point: the inheritance-style fat skeleton was deprecated in favor of composition.

Recommended path for Wheels

Wheels already embodies the consensus — wheels new generates locally and defaults to zero-config SQLite (cli/lucli/Module.cfc::new(), --setup-h2 / --no-sqlite / --datasource options). The broken wheels-starter-app is a legacy parallel distribution path that violates all three consensus points at once (external dependency fetch, MySQL-only, opaque plugins). The framework-design answer is therefore consolidate on wheels new and retire the ForgeBox starter-app, then close the two real gaps the broken package was trying to fill — auth and flash — by following the rest of the field: flash into core, auth as a generator. Note plugins/ is already deprecated in Wheels (CLAUDE.md), so the bundled-plugin model the starter relied on is a dead end regardless.

// 1. Optional starter presets on the EXISTING local generator (Rails/Laravel/Phoenix model).
//    No external fetch — preset templates ship inside the CLI, like every other framework.
//    Lives in: cli/lucli/Module.cfc::new()  (+ cli/lucli/templates/app/**)
wheels new myapp                          // already: SQLite, boots immediately
wheels new myapp --preset=auth            // scaffolds owned User/Sessions code + migration
wheels new myapp --preset=auth,bootstrap  // + a Bootstrap layout & flash partials

// 2. Flash into CORE as a controller mixin (every researched framework keeps flash in core).
//    Lives in: vendor/wheels/controller/Flash.cfc  (public $-prefixed helpers — Invariant #7)
//    Wheels already HAS flash plumbing; expose a view helper so no plugin is needed:
flashMessages();                                       // renders all queued flashes
flashMessages(class="alert", keys="success,error");    // all-named args (Anti-Pattern #1)

// 3. Auth as a GENERATOR producing owned source (Rails 8 / Phoenix / Symfony model),
//    NOT a runtime plugin dependency.
//    Lives in: cli/lucli/services/Generate.cfc  + cli/lucli/templates/auth/**
wheels generate auth User                  // User model, Sessions controller, migration, views

Lives in: cli/lucli/Module.cfc + cli/lucli/templates/ (scaffolding), vendor/wheels/controller/Flash.cfc (core flash helper).
Composes with: the existing wheels new / wheels generate surface, migrations (timestamps()), and seedOnce() for default seed data — no new lifecycle hook or DI scope required.

Cross-engine notes

The bootstrap/scaffolding surface runs on the LuCLI runtime (single engine), so it carries no Lucee/Adobe/BoxLang concern. The only cross-engine touch-point is the core flash view helper: it must be public with a $-prefixed internal helper (Cross-Engine Invariant #7 — private mixins aren't integrated), use all-named args (Anti-Pattern #1), and avoid struct.map() / obj["key"]() in any closure. None of these are obstacles — they're the standard mixin rules. The generated app keeps SQLite-default, which is already the cross-engine-friendly choice.

Open questions

• Scope of this fix vs. the design. The immediate bug (issue body) can be closed three narrow ways: (a) publish the missing plugins, (b) un-gitignore the bundled zips in the publish artifact, or (c) retire the ForgeBox starter-app and point users at wheels new. The research strongly favors (c) as the strategic direction — but that's a maintainer/product call about the ForgeBox listing (51 installs), not purely a code decision.
• Flash-into-core vs. keep-as-package. Moving flash to core matches every framework but is a public-API addition; does the team want it in 4.x core or as a first-party vendor/wheels-flash package?
• Auth generator scope. Sessions + password reset only (Rails 8), or include a registration flow (which Rails deliberately omits)?
• Should wheels new --preset=... exist at all, or is the minimal-skeleton-plus-wheels generate path (Symfony's composition argument) preferable to create-time presets?

Confidence: medium

Downgraded from high per the auto-downgrade rule: the dominant pattern conflicts with the existing Wheels distribution convention (the ForgeBox wheels-starter-app + deprecated plugins/ model) and had to be adapted, and the recommended direction includes a product/distribution decision (retiring a published package) plus a flash-into-core API addition that warrant a maintainer call. It is not low — the six frameworks agree strongly, wheels new already implements the core pattern, and no genuinely new infrastructure is required.

Sources

• https://guides.rubyonrails.org/command_line.html · https://edgeguides.rubyonrails.org/rails_application_templates.html
• https://laravel.com/docs/12.x/starter-kits · https://github.com/laravel/laravel/blob/master/.env.example
• https://docs.djangoproject.com/en/6.0/ref/django-admin/ · https://docs.djangoproject.com/en/6.0/topics/auth/
• https://phoenix.hexdocs.pm/Mix.Tasks.Phx.New.html · https://phoenix.hexdocs.pm/mix_phx_gen_auth.html
• https://docs.spring.io/spring-boot/reference/using/build-systems.html · https://docs.spring.io/initializr/docs/current/reference/html/
• https://symfony.com/doc/current/setup.html · https://symfony.com/doc/3.x/setup/flex.html

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3193

Spec: vendor/wheels/tests/specs/cli/StarterAppBoxJsonSpec.cfc — failing → passing (120 passed, 3 failed → 123 passed)
Implementation: examples/starter-app/box.json (drops the unpublished wheels-authenticateThis ForgeBox dependency + its stale installPaths entry; the plugin already ships bundled under plugins/authenticateThis/, and flashMessages() is in core)

Scope note: this resolves the titled install-break only. The PR uses Refs #3181 (not Fixes) because two threads from the issue are deferred — the MySQL-only-boot secondary defect, and the research's strategic recommendation to retire the ForgeBox starter-app in favour of wheels new (a maintainer/product call given the 51-install listing).

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.