Wheels 4.0.3 released — rebuilt CLI argument parsing, honest exit codes, wrong-server guardrails

[bpamiri]

Wheels 4.0.3 is out, two weeks after 4.0.2. It's a patch release (no breaking API changes), and its center of gravity is the wheels CLI — making it behave the way scripts, CI pipelines, and MCP-driven agents need it to behave.

The argument-parsing rebuild. LuCLI hands each command a structured argument map, but the command layer flattened it back to argv and re-parsed it with per-command token loops. The round trip dropped every false value (so --no-sqlite / --no-routes / --no-test-db never worked) and dropped named-only invocations entirely (wheels seed --environment=production quietly seeded development). All 24 commands now parse through one typed ArgSpec, and the lossy shim is deleted. One deliberate change: space-separated option values (--filter models) give way to --key=value (--filter=models).

Failures exit non-zero. Several error paths printed a red message and exited 0 — a failed wheels migrate latest looked green to CI. Now: non-zero exits with the same friendly diagnostics first, and proper tool errors over MCP. If a script of yours relied on the old exit-0 behavior, that's the one scripting behavior change to check.

Wrong-server guardrails. With no port configured, the CLI used to probe common ports and attach to whatever answered — including a different project's server, meaning wheels migrate latest in app_b could run against app_a's database. Write-side commands (migrate, seed, reload, generate admin) now require a project-bound port from lucee.json / .env and refuse otherwise with a clear diagnostic. Read-only commands keep the convenience fallback.

Adapter fixes. The PostgreSQL adapter was missing addForeignKeyOptions, so every inline-FK migration (anything --belongsTo generates) crashed — fixed, with CockroachDB inheriting it. Oracle 19c/21c DROP TABLE / DROP VIEW work again (IF EXISTS is 23c-only; the migrator now uses the version-agnostic PL/SQL idiom).

Security fix. Framework helpers mixed into controllers (env(), model(), …) could be invoked as actions from a URL — the dispatch allow-list meant to prevent it was initialized empty. It's now populated from the framework's mixin surface automatically, and helper names 404 like any other missing action. If you have a controller action literally named after a framework helper, rename it; the standard REST action names are unaffected.

Also in 4.0.3: auto-derived model properties preserve database column casing again (check case-sensitive JSON consumers before upgrading), wheels new keeps generated secrets in .env instead of committed config, the packaged module's services load correctly again, fresh Windows/Scoop installs work, and the CLI test suite had 13 masked failures unmasked and repaired.

Upgrade:

brew upgrade wheels          # macOS
scoop update wheels          # Windows
sudo apt upgrade wheels      # Debian / Ubuntu
sudo dnf upgrade wheels      # Fedora / RHEL / Rocky

Full write-up: https://blog.wheels.dev/posts/wheels-4-0-3-released
Release notes: https://github.com/wheels-dev/wheels/releases/tag/v4.0.3