Opt-in backwards compatibility for Grails 7 command plugins on Grails 8

[jamesfredley]

Summary

PR #15948 split CLI command code off the application runtime classpath. The command contract moved from grails.dev.commands.* to org.apache.grails.core.cli.*, and registration moved from META-INF/grails.factories to META-INF/grails-cli.factories. That split is preserved.

The side effect is that an unchanged, already-published Grails 7 application-command plugin would otherwise lose those commands on Grails 8: the old types no longer link, and the old factory entries are never read.

This PR restores that path with a deprecated, execution-only compatibility layer so existing Grails 7 application commands can keep working when opted in, without a plugin re-release and without putting the deprecated contract on the compile ABI of grails-core-cli.

Final behavior

Compatibility layer

• New artifact: org.apache.grails:grails-core-cli-legacy
  • Restores the deprecated grails.dev.commands.* command contract
  • Provides LegacyApplicationCommandAdapter / provider wiring
• Neutral SPI in grails-core-cli:
  • ApplicationCommandProvider
  • ApplicationCommandRegistrar
  • ApplicationCommandTargetAware
• ApplicationContextCommandRegistry discovers providers from META-INF/grails-cli.factories
  • dual-classloader
  • class-identity deduplicated
  • failure-isolated
  • modern command wins name clashes
  • one-time deprecation warning only when a legacy command is actually installed
• grails-core-cli has zero compile/runtime dependency on grails.dev.commands.*
• Runner unwrap uses ApplicationCommandTargetAware.getTarget() so Spring autowiring and skipBootstrap hit the real legacy command

Auto-provisioning flags

Flag	Default	Controls
cliAutoProvision	true	Modern CLI tier: grails-core-cli, grails-console, and discovered companion -cli artifacts
legacyCommandSupport	false	Only the Grails 7 application-command bridge: grails-core-cli-legacy

Rules:

• Modern CLI auto-provisioning runs when cliAutoProvision = true
• Legacy bridge auto-provisioning runs only when both cliAutoProvision = true and legacyCommandSupport = true
• legacyCommandSupport = false (the default) turns off only the Grails 7 bridge; modern companions still auto-provision
• cliAutoProvision = false turns off the whole auto-provisioned CLI tier, including the legacy bridge

Examples:

// default: modern CLI on, legacy bridge off
// no grails {} block required

// keep modern CLI companions, enable only Grails 7 bridge
grails {
    legacyCommandSupport = true
}

// disable all CLI auto-provisioning; declare deps yourself
grails {
    cliAutoProvision = false
}
dependencies {
    grailsCli 'org.apache.grails:grails-core-cli'
    grailsCli 'org.apache.grails:grails-console'
    grailsCli 'org.apache.grails:grails-data-hibernate7-dbmigration-cli'
    grailsCliLegacy 'org.apache.grails:grails-core-cli-legacy'
}

Project-property equivalents:

• grailsCliAutoProvision=false
• grailsLegacyCommandSupport=true (opt in; default is off)

Classpath shape

• grailsCliLegacy is execution-only
• It feeds grailsCliClasspath and test runtime classpaths
• It never extends application/plugin compile classpaths
• Auto-provisioned CLI coordinates are version-pinned to the current Grails version so consumers without a BOM-managed -cli coordinate still resolve

How legacy commands run

• Legacy Grails 7 application commands do not get named Gradle tasks
• Configuration-time runtimeClasspath scans for META-INF/grails.factories were removed (nondeterministic in multi-project builds)
• Run them through the generic runCommand task, or the shell (which routes legacy adapters there):

./gradlew runCommand "-Pargs=generate-controller example.Book"

• Named per-command Gradle tasks remain available only for migrated commands published in a companion -cli artifact

Command mechanisms

Mechanism	Packaged as	Result on Grails 8 with this PR
create-command / grails.dev.commands.ApplicationCommand	class + META-INF/grails.factories	Works via grails-core-cli-legacy when both flags are on (runCommand / shell)
create-script / META-INF/commands/*.groovy	script resources	Unaffected by the split; hyphenated script name regression fixed
YAML multi-step / META-INF/commands/*.yml	YAML resources	Unaffected
ServiceLoader / profile commands	profile / services	Unaffected

Codegen script fix

Hyphenated script filenames (for example audit-quickstart) now resolve under the filename-derived command name under Groovy 5.

Testing

• Provider / adapter / registry unit coverage, including failure isolation and linkage diagnostics
• Gradle TestKit:
  • modern companion auto-discovery
  • compile-visible / runtime-isolated CLI tier
  • cliAutoProvision = false disables the whole tier (including when legacy is explicitly opted in)
  • legacyCommandSupport defaults to false
  • explicit legacyCommandSupport = false / true property cases
  • legacy runtime commands do not invent named Gradle tasks; runCommand remains available
• The compatibility suite lives in the top-level end-to-end build, which is its own Gradle build. The root build never reaches it, so ./gradlew build at the repository root is unaffected, and it is run by its own .github/workflows/end-to-end.yml:
  • end-to-end/legacy-commands - the Grails 8 application under test; opts in with grails { legacyCommandSupport = true }
  • end-to-end/legacy-commands-plugin - a Grails 8 plugin whose legacy commands are recompiled under Groovy 5
  • It resolves Grails from the artifacts the core build publishes into build/local-maven (scoped with exclusiveContent) rather than by project substitution, so the tests consume grails-core through real poms and Gradle module metadata the way an application does - including the -cli companion artifacts, which composite substitution cannot express because grails-core-cli is a secondary capability of :grails-core rather than a project
• Real Grails 7 / Groovy 4 precompiled binary fixture: end-to-end/legacy-g7-command-plugin
  • A standalone build with its own settings.gradle, its own mavenCentral()-only repository, and its own JDK 17 declared in .sdkmanrc (no Gradle toolchain, so no surrounding build inherits a second JDK requirement)
  • Pinned with enforcedPlatform('org.apache.grails:grails-bom:7.0.14'), resolving Groovy 4.0.32
  • Consumed as a prebuilt jar, never includeBuild, so composite substitution cannot rewrite org.apache.grails:grails-core to this repository's Groovy 5 projects - which is exactly what the fixture exists to prevent
  • Manifest Grails-Compile-Version / Groovy-Compile-Version are derived from the resolved compile classpath, not hand-typed, and are asserted by the integration test
  • Three genuinely precompiled commands prove the trait ABI holds across the Groovy 4 -> Groovy 5 boundary:
    • plain ApplicationCommand (G7-RAN)
    • GrailsApplicationCommand exercising the @Delegate forwarders (file(...), mkdir, render(...)) and applicationContext (G7-CONTEXT-true)
    • one declaring neither getName() nor getDescription() - the shape create-command generated on Grails 7 - so the trait's default name derivation is proven, registering as hello-derived-name
• Upgrade / What's New docs updated for both flags and runCommand-only legacy execution

Migration

• Consumers of already-published Grails 7 application-command plugins: enable grails { legacyCommandSupport = true } (or -PgrailsLegacyCommandSupport=true), or declare grailsCliLegacy explicitly when cliAutoProvision is disabled
• Plugin authors should migrate to org.apache.grails.core.cli.* and publish a companion -cli artifact
• A plugin that still authors against the deprecated contract must depend on grails-core-cli-legacy explicitly for compile
• The compatibility layer is deprecated and may be removed in a future major release; no removal major has been announced

Related

• Builds on Split CLI dependencies from the runtime classpath #15948
• The end-to-end build relocation, the trait-derived-name fixture command, and the remaining review follow-ups land on this branch via Move legacy command compatibility tests into an end-to-end build #16059
• Follow-up for remaining src/main/scripts runtime packaging: Move src/main/scripts command resources out of runtime plugin artifacts #16035

[Copilot]

Pull request overview

This PR restores backwards compatibility for already-published Grails 7 command plugins when running on Grails 8, while preserving the CLI/runtime classpath split introduced in #15948. It reintroduces the deprecated grails.dev.commands.* contract inside the CLI tier, adds adapter/registry/runner support to load legacy commands from META-INF/grails.factories, and fixes a Groovy 5 regression where hyphenated script commands (e.g. audit-quickstart) could be discovered under the wrong name.

Changes:

• Add a deprecated Grails 7 command compatibility layer (legacy contract types + adapter + dual-load registry behavior + runner unwrap).
• Restore hyphen-preserving discovery for plugin-provided Groovy script commands.
• Add unit + functional test coverage and a new end-to-end test-example fixture for legacy command plugins; update Grails 8 upgrade documentation accordingly.

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
settings.gradle	Registers new legacy-commands test-example projects in the build.
grails-test-examples/legacy-commands/src/integration-test/groovy/legacycommands/LegacyCommandCompatibilityIntegrationSpec.groovy	End-to-end integration test exercising legacy command discovery/adaptation and legacy script packaging.
grails-test-examples/legacy-commands/grails-app/init/legacycommands/Application.groovy	Test-example application entry point.
grails-test-examples/legacy-commands/grails-app/controllers/legacycommands/UrlMappings.groovy	Test-example URL mappings (baseline web profile wiring).
grails-test-examples/legacy-commands/grails-app/conf/logback.xml	Test-example logging configuration.
grails-test-examples/legacy-commands/grails-app/conf/application.yml	Test-example app configuration for integration execution.
grails-test-examples/legacy-commands/build.gradle	Test-example app build with legacy-commands plugin dependency.
grails-test-examples/legacy-commands-plugin/src/main/scripts/hello-legacy-script.groovy	Legacy plugin script command fixture with a hyphenated command name.
grails-test-examples/legacy-commands-plugin/src/main/resources/META-INF/grails.factories	Legacy factories registration under grails.dev.commands.ApplicationCommand.
grails-test-examples/legacy-commands-plugin/src/main/groovy/legacy/commands/plugin/LegacyCommandsPluginGrailsPlugin.groovy	Plugin descriptor for the legacy command fixture plugin.
grails-test-examples/legacy-commands-plugin/src/main/groovy/legacy/commands/plugin/HelloLegacyGrailsCommand.groovy	Legacy GrailsApplicationCommand fixture.
grails-test-examples/legacy-commands-plugin/src/main/groovy/legacy/commands/plugin/HelloLegacyAppCommand.groovy	Legacy ApplicationCommand fixture.
grails-test-examples/legacy-commands-plugin/build.gradle	Fixture plugin build (compiles against grails-core-cli without publishing a -cli companion).
grails-shell-cli/src/test/groovy/org/grails/cli/profile/commands/factory/LegacyPluginScriptCompatSpec.groovy	Unit test ensuring Grails 7-style plugin scripts remain discoverable with hyphenated names.
grails-shell-cli/src/main/groovy/org/grails/cli/profile/commands/factory/GroovyScriptCommandFactory.groovy	Ensures compiled script commands use the filename-derived command name (hyphen-preserving).
grails-gradle/plugins/src/main/groovy/org/grails/gradle/plugin/commands/GrailsCliGradlePlugin.groovy	Adds legacy factories scanning on runtimeClasspath to keep per-command Gradle tasks for Grails 7 plugins.
grails-doc/src/en/guide/upgrading/upgrading80x.adoc	Documents the deprecated compatibility layer and the migration path for plugin authors.
grails-core/src/test/groovy/org/apache/grails/core/cli/LegacyCommandRegistryLoadingSpec.groovy	Unit tests for legacy factories loading, isolation on constructor failure, and collision preference rules.
grails-core/src/test/groovy/org/apache/grails/core/cli/compat/LegacyApplicationCommandAdapterSpec.groovy	Unit test verifying adapter forwarding into legacy execution context.
grails-core/src/cli/groovy/org/apache/grails/core/cli/LegacyApplicationCommandAware.groovy	Marker interface for adapters to allow runner autowire/inspection unwrap.
grails-core/src/cli/groovy/org/apache/grails/core/cli/compat/LegacyApplicationCommandAdapter.groovy	Adapter bridging legacy grails.dev.commands.ApplicationCommand into the Grails 8 CLI contract.
grails-core/src/cli/groovy/org/apache/grails/core/cli/ApplicationContextCommandRegistry.groovy	Registry now dual-loads legacy factories and wraps legacy commands via adapter with one-time warning.
grails-core/src/cli/groovy/grails/dev/commands/template/TemplateRendererImpl.groovy	Restored deprecated template renderer implementation for legacy command plugins.
grails-core/src/cli/groovy/grails/dev/commands/template/TemplateRenderer.groovy	Restored deprecated template renderer API for legacy command plugins.
grails-core/src/cli/groovy/grails/dev/commands/template/TemplateException.groovy	Restored deprecated template exception for legacy command plugins.
grails-core/src/cli/groovy/grails/dev/commands/io/FileSystemInteractionImpl.groovy	Restored deprecated filesystem interaction implementation for legacy command plugins.
grails-core/src/cli/groovy/grails/dev/commands/io/FileSystemInteraction.groovy	Restored deprecated filesystem interaction API for legacy command plugins.
grails-core/src/cli/groovy/grails/dev/commands/GrailsApplicationCommand.groovy	Restored deprecated legacy GrailsApplicationCommand trait for Grails 7 commands.
grails-core/src/cli/groovy/grails/dev/commands/ExecutionContext.groovy	Restored deprecated legacy execution context type.
grails-core/src/cli/groovy/grails/dev/commands/ApplicationCommand.groovy	Restored deprecated legacy application command contract trait.
grails-console/src/test/groovy/grails/ui/command/GrailsApplicationContextCommandRunnerSpec.groovy	Tests that runner unwraps legacy adapter for autowiring/inspection.
grails-console/src/main/groovy/grails/ui/command/GrailsApplicationContextCommandRunner.groovy	Runner unwraps legacy adapters for autowiring and skipBootstrap inspection.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jdaugherty]

@jamesfredley if you can let me know today, I'm happy to add the proposed compatibility layer. I'd like to proceed with the M4. Are you wanting this done before the M4?

[codecov]

Codecov Report

❌ Patch coverage is 32.66667% with 202 lines in your changes missing coverage. Please review.
✅ Project coverage is 51.5022%. Comparing base (c6ce3fe) to head (75ed393).

Files with missing lines	Patch %	Lines
.../dev/commands/template/TemplateRendererImpl.groovy	5.7971%	65 Missing ⚠️
...s/dev/commands/io/FileSystemInteractionImpl.groovy	10.6061%	59 Missing ⚠️
...radle/plugin/commands/GrailsCliGradlePlugin.groovy	0.0000%	33 Missing ⚠️
...cli/compat/LegacyApplicationCommandProvider.groovy	70.9091%	6 Missing and 10 partials ⚠️
...ds/factory/ApplicationContextCommandFactory.groovy	54.1667%	8 Missing and 3 partials ⚠️
...mmand/GrailsApplicationContextCommandRunner.groovy	40.0000%	6 Missing ⚠️
...rails/dev/commands/io/FileSystemInteraction.groovy	0.0000%	4 Missing ⚠️
...rails/core/io/support/GrailsFactoriesLoader.groovy	81.8182%	0 Missing and 4 partials ⚠️
...g/grails/gradle/plugin/core/GrailsExtension.groovy	33.3333%	2 Missing ⚠️
...oovy/org/grails/cli/profile/AbstractProfile.groovy	0.0000%	2 Missing ⚠️

Additional details and impacted files

@@                Coverage Diff                 @@
##                8.0.x     #16011        +/-   ##
==================================================
+ Coverage     51.4910%   51.5022%   +0.0112%     
- Complexity      17762      17836        +74     
==================================================
  Files            2039       2044         +5     
  Lines           95537      95823       +286     
  Branches        16571      16629        +58     
==================================================
+ Hits            49193      49351       +158     
- Misses          39037      39142       +105     
- Partials         7307       7330        +23     

Files with missing lines	Coverage Δ
.../cli/compat/LegacyApplicationCommandAdapter.groovy	100.0000% <100.0000%> (ø)
...commands/factory/GroovyScriptCommandFactory.groovy	90.0000% <100.0000%> (+28.8889%)	⬆️
...g/grails/gradle/plugin/core/GrailsExtension.groovy	54.3478% <33.3333%> (-1.4661%)	⬇️
...oovy/org/grails/cli/profile/AbstractProfile.groovy	38.8235% <0.0000%> (-0.1529%)	⬇️
...rails/dev/commands/io/FileSystemInteraction.groovy	0.0000% <0.0000%> (ø)
...rails/core/io/support/GrailsFactoriesLoader.groovy	59.6774% <81.8182%> (+12.1774%)	⬆️
...mmand/GrailsApplicationContextCommandRunner.groovy	11.9048% <40.0000%> (+9.1270%)	⬆️
...ds/factory/ApplicationContextCommandFactory.groovy	51.7241% <54.1667%> (+51.7241%)	⬆️
...cli/compat/LegacyApplicationCommandProvider.groovy	70.9091% <70.9091%> (ø)
...radle/plugin/commands/GrailsCliGradlePlugin.groovy	0.0000% <0.0000%> (ø)
... and 2 more

... and 12 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jdaugherty]

@jamesfredley I strongly disagree with the legacy compatibility by default. A single setting can be changed as part of the upgrade if people use legacy plugins - this matches previous decisions like indy, and many more. Making this a default incentivizes people to not adopt the new api and when we remove it, it will break outside of a major release lifecycle.

[jdaugherty]

@jamesfredley Please stop resolving comments when they're only half completed. It makes extremely hard to understand what's done and what isn't.

[jamesfredley]

@jdaugherty Update after the latest push (c798c93778):

There is now a dedicated legacyCommandSupport flag (default on), separate from cliAutoProvision.

• cliAutoProvision controls modern CLI companions only
• legacyCommandSupport controls only the Grails 7 bridge (grails-core-cli-legacy)
• Bridge provisions only when both are true
• legacyCommandSupport = false keeps modern companions and disables only the bridge

I kept the default on so already-published G7 command plugins keep working with zero user action after the #15948 split. The separate flag is the opt-out for people who want the modern CLI tier without the compatibility bridge.

If the project decision is still "default off + loud detect/warn when legacy factories are present", that is a policy call and I can flip the default. The wiring is already split so that change is one convention flip, not a redesign.

[jamesfredley]

@jdaugherty On M4 timing: yes, I want this compatibility path landed before M4 if we can.

Current pushed state:

• separate execution-only grails-core-cli-legacy artifact
• two flags (cliAutoProvision, legacyCommandSupport), both default on
• linkage failures isolated/loud
• docs updated

Still open for a stronger green light:

• real Grails 7 / Groovy 4 precompiled fixture via composite build
• whether legacyCommandSupport default should stay on or flip off
• remaining Forge CI failures from empty -cli versions should be helped by the version-pin work in c798c93778; watching the new CI run

[jamesfredley]

@jdaugherty Agreed. I will not resolve review threads unless the full ask is actually done and you are good with it.

For the current open items I am only replying with status, not marking resolved.

[jamesfredley]

On the Forge failures (Could not find org.apache.grails:grails-scaffolding-cli:. / grails-data-hibernate5-cli:. with empty versions):

That was auto-provision creating companion coordinates without a version. The latest push pins framework CLI artifacts (grails-core-cli, grails-console, grails-core-cli-legacy) to the current Grails version, and derives external companion versions from the producer module/jar instead of leaving them versionless.

Watching the post-c798c93778 CI run for Forge. If anything still fails there I will chase it separately from the default-on policy discussion.

[jamesfredley]

Latest push summary (1d8edac99e)

Addressed remaining review/proof gaps and the Code Style CI failure.

1. Removed legacy named-task scan

• Deleted loadLegacyCommandNamesFromRuntimeClasspath and the configuration-time runtimeClasspath scan for grails.dev.commands.ApplicationCommand
• Legacy application commands no longer invent flaky named Gradle tasks
• They stay available via runCommand / shell adapter once grails-core-cli-legacy is provisioned
• TestKit now asserts LEGACY_COMMAND_TASK_PRESENT=false and RUN_COMMAND_TASK_PRESENT=true
• Docs updated to show the runCommand path

2. Real Grails 7 / Groovy 4 precompiled fixture

• New standalone project: grails-test-examples/legacy-g7-command-plugin
• Compiles against published grails-core:7.0.10 / Groovy 4.0.30
• Manifest stamps: Grails-Compile-Version: 7.0.10, Groovy-Compile-Version: 4.0.30
• Built via GradleBuild (not monorepo includeBuild) so monorepo BOM/JVM substitution cannot rewrite the fixture
• Wired into grails-test-examples/legacy-commands
• Integration test proves:
  • Adapter targets legacy.g7.commands.HelloG7PrecompiledCommand
  • Class loads from the G7 fixture jar
  • Command executes and writes G7-RAN
• LegacyCommandCompatibilityIntegrationSpec: 5/5 green locally, including the new G7 feature

3. Dual flags (already on tip before this note)

Flag	Default	Scope
cliAutoProvision	on	modern CLI tier + companions
legacyCommandSupport	on	only grails-core-cli-legacy

Legacy provisions only when both are true.

4. Code style CI fix

• Single-quoted SLF4J templates
• Dropped unnecessary ?. on non-null loop variables
• Empty catch variable renamed to ignored (EmptyCatchBlock)
• Local: :grails-core-cli-legacy:codenarcMain + :grails-core:codenarcCli green with ignoreFailures=false

Still open for reviewer preference

• Default-on vs default-off + detect/warn policy for legacyCommandSupport (product call currently remains default-on; flip is one convention change if decided)
• Remaining script/YAML packaging pollution tracked in Move src/main/scripts command resources out of runtime plugin artifacts #16035

[jamesfredley]

Pushed 116b0efab3: flipped legacyCommandSupport default from true → false everywhere.

Code

• GrailsExtension.legacyCommandSupport convention is now Boolean.FALSE when grailsLegacyCommandSupport is unset
• Javadoc / plugin property docs describe opt-in (= true), not opt-out

Docs

• Upgrade guide §35 / §35.1 and What's New: default false, enable examples, consumer checklist

Tests / fixtures

• CliAutoDiscoverySpec: default-false, explicit false, explicit true, and cliAutoProvision=false still wins when legacy is opted in
• grails-test-examples/legacy-commands opts in with grails { legacyCommandSupport = true }

PR description updated to match (default-off bridge, opt-in migration note).

[jdaugherty]

Re-reviewed the whole branch against my earlier rounds and resolved all nine of my open threads at 75ed39351b — the ABI isolation, the LinkageError/VirtualMachineError split with jar-named, framework-blaming wording, the removal of the nondeterministic named-task scan, the component-metadata companion version resolution, the runtime-only legacy detection with hints on both unknown-command paths, and the precompiled Grails 7 / Groovy 4 fixture actually executing through the registry. The last of those (the fixture tightenings) I resolved on the strength of three of its four asks being done; the remaining one is carried by a comment below rather than left buried in a thread about the build file. The legacyCommandSupport default is false, which matches where the dev list landed; I have nothing further on that.

Everything still open below is already implemented and verified on a branch: test/8.0.x-legacy-command-e2e (one commit on top of 75ed39351b, opened as a draft against this branch in #16059). Take it, cherry-pick from it, or ignore it — it exists so none of this has to block the merge on working out the shape. Nothing below is a request for you to go and write code.

The two I'd want fixed before merge

1. The Grails 7 fixture's JDK 17 requirement is expressed as a Gradle toolchain that nothing in the repo provisions, and it sits in the core build's task graph — so ./gradlew build -PskipTests fails on the documented developer JDK and in the reproducible-build container. Reproduced. The version is right; the placement isn't.
2. loadFactoryDeclarations silently discards a malformed factories resource — and it now backs modern grails-cli.factories discovery, so one bad file loses a plugin's Grails 8 commands with no log line anywhere.

The other two

3. The last part of my fixture tightening #4: the trait's default getName()/getDescription() derivation is shadowed by every legacy command in the tree, so the "command declares no name" variant — the shape create-command generated, and therefore what most published Grails 7 commands rely on for their registration key — has zero coverage.
4. No test coverage for the skipBootstrap-from-target behaviour, which decides whether BootStrap runs during things like dbm-update.

What the branch does

The build half is the substantial part: the three legacy-command projects move to a new top-level end-to-end build, the toolchain block is gone, the Grails 7 fixture pins its own JDK and Gradle version (17 and 8.14.5, what Grails 7 uses) in its own .sdkmanrc with gradle-bootstrap generating that wrapper from it, and .github/workflows/end-to-end.yml provisions both JDKs by reading those files.

Rather than composing grails-core with includeBuild('..'), it resolves from the artifacts the core build publishes — the same build/local-maven grails-forge points its generated apps at. That is what makes them end-to-end, and it disposes of the CLI companion problem instead of working around it: grails-core-cli can't be reached by composite substitution (it's a capability of :grails-core, not a project) but is a first-class published module, so resolving from the repository just works.

The minor items — also done, except one

• ThreadDeath removed from all four fatal-error guards; VirtualMachineError handling and the wrapped-cause walk untouched, and the specs now prove rethrow across two VirtualMachineError subtypes instead.
• rethrowIfFatal() left duplicated, deliberately. grails-shell-cli cannot see grails-core at compile time (verified: its compileClasspath resolves grails-bootstrap, not grails-core — which is why the factory loads the registry by string name). The only type visible to all four sites is ExceptionUtils in grails-bootstrap, and putting a CLI error-triage rule there means new public API on a general-purpose published utility. Worse trade than 13 duplicated lines. The byte-identical instantiate()/instantiateCommand() pair inside the one class was collapsed.
• Commands are now deduplicated across the registry and context classloaders, matching the provider path. Nice bit of evidence: the existing assertion was constructorCalls == registryClassLoaderConstructions + 1, and that + 1 was the double construction — it now asserts exactly one.
• Legacy commands take part in ordering: the adapter projects the target's Ordered/@Order onto itself (plain OrderComparator reads only Ordered, never annotations) and the provider sorts before registering.
• The stale "composite-build / included by the monorepo root" comments and the duplicated 7.0.14 pin are fixed.
• ApplicationCommandProviderSpec's misnamed feature: the dead branch is measured-dead (instrumented the handler; exactly one openConnection) and removed, and the feature renamed to what it actually verifies. Making the branch live would have broken the test — the fixture throws AssertionError, which loadFactoryDeclarations does not catch, so the hint would come back null and fail the feature's own first assertion.
• AbstractProfile:488 now has a spec driving the public Profile.handleCommand, red-checked against the pre-PR line.

On my inheritance question

Your answer is right that my literal proposal (legacy trait extends the new trait) fails: the bridge method lands abstract on the interface and an unrecompiled Grails 7 binary gets AbstractMethodError rather than a clean failure, which is worse than today. Worth noting for the record that "inheritance does not adapt the argument type" isn't true in general — a Java interface carrying a real default handle(new ExecutionContext) that delegates to handle(legacy ExecutionContext) does work on an unrecompiled binary. But the adapter is still the better choice, and for a concrete reason worth writing down: with the bridge, adding any member to org.apache.grails.core.cli.ApplicationCommand breaks every precompiled Grails 7 binary with AbstractMethodError, whereas the adapter absorbs that evolution. No change requested.

Verification on the branch

:grails-core:test 487, :grails-core-cli-legacy:test 19, :grails-shell-cli:test 175, :grails-console:test 36 — zero failures; codenarc and checkstyle clean on all four; the end-to-end suite 6/6 green against freshly published artifacts, and green in CI on #16059 including the two-JDK setup and the fixture-provenance check.

[jdaugherty]

Commenting on this line, though the Java version itself isn't the issue — 17 is correct and should stay. It's the minimum JDK for a Grails 7 app (7.0.x pins java=17.0.18-librca in .sdkmanrc and javaVersion=17 in gradle.properties), and matching what a Grails 7 app would actually be built with is the entire point of this fixture; anything newer would weaken what it proves. The issue is where that requirement is expressed.

Right now it's a Gradle toolchain, and this is the only production build in the repo that pins one — every other JavaLanguageVersion is a TestKit resource substituted with __CURRENT_JDK__ or a gated java-compat test project. We've deliberately stayed off toolchain configuration, and I don't want this fixture to be what introduces it into the core build.

As written it also can't be satisfied. Nothing provisions a JDK 17: there's no foojay-resolver or toolchainManagement block in this build's settings.gradle (which is just rootProject.name) or in the root settings.gradle, and no org.gradle.java.installations.* property anywhere. The root .sdkmanrc pins java=21.0.7-librca and nothing else, and etc/bin/Dockerfile is FROM bellsoft/liberica-openjdk-debian:21.0.7 with only a secondary JDK 25 at /opt/liberica-jdk25.

And it isn't confined to running the integration test. The fixture jar is an implementation dependency (legacy-commands/build.gradle:45), so buildLegacyG7CommandFixture is in the task graph for plain compilation:

$ ./gradlew :grails-test-examples-legacy-commands:compileGroovy --dry-run -PskipTests
:grails-test-examples-legacy-commands:buildLegacyG7CommandFixture SKIPPED
:grails-test-examples-legacy-commands:compileGroovy SKIPPED

That's reached by etc/bin/test-reproducible-builds.sh:42 (./gradlew build --rerun-tasks -PskipTests ...). With JDK 17 hidden:

$ ./gradlew -p grails-test-examples/legacy-g7-command-plugin jar \
    -Dorg.gradle.java.installations.auto-detect=false
> Cannot find a Java installation on your machine matching:
  {languageVersion=17, vendor=any vendor, ...}. Toolchain auto-provisioning is not enabled.

So a contributor whose only JDK is the one we document can't build the repo. CI can't catch it — it's green only because the GitHub runner images happen to ship a JDK 17 that Gradle auto-detects.

The fix isn't a different Java version or a resolver plugin. It's to stop wiring a second JDK requirement into the core build at all, and instead use the composition model we already use for every other build in this repo that has its own needs: grails-forge, grails-gradle, build-logic. Those are independent builds with their own settings.gradle and their own gradlew, and the dependency runs one way — grails-forge/settings.gradle:75 does includeBuild('..'), so Forge composes grails-core and grails-core's own ./gradlew build never reaches Forge. CI runs each as its own job (working-directory: 'grails-forge', working-directory: 'grails-gradle').

I'd like a new top-level end-to-end build to serve as the base for this kind of test, with the Grails 7 fixture and the legacy-commands example that consumes it as its first occupants:

• drop the java { toolchain { ... } } block;
• move the fixture and its consuming example into end-to-end, out of the root build graph, so ./gradlew build -PskipTests never triggers buildLegacyG7CommandFixture and the core build never needs a JDK it doesn't have;
• declare the Java 17 requirement in a .sdkmanrc next to the Grails 7 half — same mechanism the root and 7.0.x already use, and it keeps 17 an explicit, greppable statement of intent rather than something Gradle has to go find;
• run it from its own CI workflow, the way Forge and the Gradle plugins are run.

That also gives us an obvious home for the next end-to-end compatibility test instead of finding a new corner for each one.

Two things worth planning for in that layout, both of which a dedicated workflow handles cleanly and the core build can't:

1. Two JDKs, explicitly. The Grails 7 fixture wants 17; the Grails 8 app consuming it needs 21+. In a dedicated workflow that's just two setup-java steps around two build invocations, which is more honest than asking one Gradle build to straddle both — and it's what removes the auto-detection dependency that's making CI pass by luck today.
2. Keep the Grails 7 half outside dependency substitution. If includeBuild('..') reaches it, org.apache.grails:grails-core:7.0.14 gets rewritten to the local Groovy 5 project and the proof evaporates — which is exactly why you chose GradleBuild over includeBuild originally, and I agreed with that reasoning. The Grails 8 consuming app can compose the root normally; the fixture can't.

I've put this together as a working branch rather than leave it as a sketch: test/8.0.x-legacy-command-e2e (single commit).

The three projects move to a top-level end-to-end build and the toolchain block is gone. Only the Grails 7 fixture carries a .sdkmanrc (17); the Grails 8 side tracks the repository's root .sdkmanrc rather than re-pinning 21, since it has to run on whatever the core build it consumes runs on. .github/workflows/end-to-end.yml reads both versions out of those two files, so it cannot drift from what sdk env gives a developer.

The part worth a look is how it resolves Grails. Rather than includeBuild('..'), it consumes the artifacts the core build publishes — the same build/local-maven that grails-forge points its generated applications at, populated by publishAllPublicationsToTestCaseMavenRepoRepository in the root and grails-gradle builds. That is what makes these end-to-end: they go through real poms and module metadata the way an application does. settings.gradle scopes the repository with exclusiveContent so a remote snapshot can't quietly satisfy an org.apache.grails request and leave the suite testing something other than the working tree.

It also disposes of the CLI companion problem instead of working around it. grails-core-cli is a secondary capability of :grails-core rather than a project, so composite substitution can't express it and dies on a capability self-conflict — but it's a first-class published module whose metadata CliPublishingSupport already rewrites for external consumers, so resolving from the repository just works. Verified byte-for-byte: the grails-core-cli jar the suite resolves is sha1-identical to the one the publish task had just written to build/local-maven.

Verified end to end: end-to-end/./gradlew check green with all six integration tests passing, the root ./gradlew configures with zero references to the moved projects, and the fixture builds under JDK 17 with -Dorg.gradle.java.installations.auto-detect=false. Take it as a proposal, not a demand.

[jdaugherty]

catch (IOException | IllegalArgumentException ignored) { continue } drops the entire resource with no log line at any level — the class has no logger.

That would be defensible if this only backed the legacy diagnostic, but it doesn't. loadFactoryDeclarations is now the reader for modern discovery too: ApplicationContextCommandRegistry:64 for commands and :159 for providers, both against CLI_FACTORIES_RESOURCE_LOCATION. So a single plugin shipping a META-INF/grails-cli.factories with a stray backslash — Properties.load throws IllegalArgumentException("Malformed \\uxxxx encoding") — loses every one of that plugin's Grails 8 commands and providers. The user sees commands that simply aren't there, with nothing to chase.

It's also a loudness regression against what it replaced. FactoriesLoaderSupport.loadFactoryNames (grails-gradle/model/.../FactoriesLoaderSupport.groovy:99-101) rethrows IOException as IllegalArgumentException and doesn't catch IllegalArgumentException at all, so a malformed factories file propagated instead of vanishing. ApplicationCommandProviderSpec:301 currently locks the new silence in — it asserts only missingCommandHint == null and noExceptionThrown().

This is the same failure mode you and I already agreed on for linkage errors: a command the user expects, silently absent, diagnosable by nobody. Give the class a logger and warn with the resource URL and the cause before continuing.

Implemented on test/8.0.x-legacy-command-e2e: the class gets @Slf4j and the catch warns with the resource URL and cause, keeping the per-resource continue. The existing malformed-resource test now asserts the warning instead of only noExceptionThrown(), and a new one proves a malformed grails-cli.factories in one plugin no longer costs a different plugin its modern commands. :grails-core:test --tests ApplicationCommandProviderSpec green (23 features).

[jdaugherty]

Overriding getName() here is a legitimate Grails 7 shape and this command should keep it. The gap is that it's the only shape covered.

The deprecated trait ships two behaviours. One is "the command declares its own name", which this fixture exercises. The other is "the command declares no name and the trait derives one" — ApplicationCommand.getName() at grails-core-cli-legacy/.../grails/dev/commands/ApplicationCommand.groovy:50-57, which runs GrailsNameUtils.getScriptName(getLogicalName(...)) and, from a Groovy 4 binary, reaches it through ApplicationCommand$Trait$Helper. That second path has no coverage anywhere in the tree: both fixture commands override the getters (here at :35/:39, HelloG7PrecompiledGrailsCommand at :29/:33), LegacyApplicationCommandAdapterSpec:54-55 overrides them, and so do all eight classes in LegacyCommandRegistryLoadingSpec (:332, :354, :373, :395, :415, :440, :460, :484).

It matters because class FooBarCommand implements ApplicationCommand with no getName() is the shape create-command generated, so a large share of the published Grails 7 commands this bridge exists to keep working never declare a name at all. For those the derivation is the registration key — if the Groovy 5 recompile of the trait changes how that default is woven or dispatched into Groovy-4-compiled implementors, they register under the wrong key or not at all. That's precisely the class of failure this fixture was built to catch, and it's the one variant it currently can't see.

So: keep this command as-is, and add a third precompiled one alongside it that declares neither getter, letting the trait derive the name. The spec then looks it up under whatever the derivation produces, which only passes if the default survives the version boundary.

A unit test over in grails-core-cli-legacy wouldn't substitute for this — that would be a Groovy 5 implementor against a Groovy 5 trait, which isn't the cross-version question. It has to be a Groovy 4 binary to mean anything, which is why it belongs in this fixture.

There's a working version of this on test/8.0.x-legacy-command-e2e: a third precompiled HelloDerivedNameCommand matching the create-command template exactly - implements GrailsApplicationCommand, declares neither getter - which reads its own name inside handle() so the derivation is exercised from the Groovy 4 bytecode rather than only from the recompiled trait. It registers as hello-derived-name (confirmed by running the trait against the precompiled class), and the integration spec asserts both the registration key and the rendered output. Green.

[jdaugherty]

Reading skipBootstrap off the unwrapped target is the right call — the adapter forwards handle, not arbitrary properties — but nothing tests it. grep -rn skipBootstrap across the repo returns only production code: this file, and the skipBootstrap = true declarations in the hibernate5/7 SchemaExportCommand and ApplicationContextDatabaseMigrationCommand, scaffolding, and spring-security. No spec mentions it.

That matters more than a coverage count, because the flag decides whether BootStrap.groovy runs. If a later change collapses this back to command.hasProperty('skipBootstrap'), a legacy command declaring Boolean skipBootstrap = true silently stops setting Settings.SETTING_SKIP_BOOTSTRAP and BootStrap executes during something like dbm-update against whatever datasource is configured — with the whole suite still green.

run() has the same hole: LegacyCommandCompatibilityIntegrationSpec performs the autowire unwrap by hand at :85-98 instead of driving the runner, so reverting line 79 back to command also leaves every test passing.

Small fix: extract the flag lookup into a static helper next to resolveAutowireTarget and cover adapter-target / plain-command / no-property in GrailsApplicationContextCommandRunnerSpec, which this commit already added.

Implemented on test/8.0.x-legacy-command-e2e: the lookup moves into static Boolean resolveSkipBootstrap(Object) beside resolveAutowireTarget, with run() behaviour unchanged (the System.getProperty guard stays put). Four features in GrailsApplicationContextCommandRunnerSpec cover plain command, no-property, adapter-target, and non-Boolean. Mutation-checked: pointing the helper back at command instead of the resolved target fails exactly the adapter-target case. :grails-console:test --tests GrailsApplicationContextCommandRunnerSpec green (34 features).

[jdaugherty]

I think AI double posted my responses, but #16059 fixes all of my issues with this branch. If we merge that into this, we should merge this change.

[borinquenkid]

The TestLens failures for GrailsUtilStackFiltererSpec > installed DefaultStackTraceFilterer emits Full Stack Trace by default and GrailsBootstrapRegistryInitializerSpec > defaults logFullStackTraceOnFilter to true on the promoted DefaultStackTraceFilterer are a pre-existing bug on 8.0.x, unrelated to this PR's changes -- reproducible on plain 8.0.x today. DefaultStackTraceFilterer.STACK_LOG routes through a jcl-over-slf4j commons-logging binding, so the tests' System.setErr() capture never observes the emitted message.

Fix: #16067 (replaces the System.err capture with a Logback appender attached directly to the logger). Once that merges, rebasing onto 8.0.x should clear this failure here.

[testlens-app]

✅ All tests passed ✅

🏷️ Commit: bdb98a6
▶️ Tests: 41416 executed
⚪️ Checks: 60/60 completed

---

Learn more about TestLens at testlens.app.